@viggle/splat-engine-three 0.1.0 → 0.1.1

package/dist/index.js

@@ -13,6 +13,7 @@ import {
   SplatEngine,
   SplatMesh,
   SplatPLYLoader,
+  SplatQuality,
   SunLight,
   VSplatLoader,
   WebGLSplatBackend,
@@ -21,8 +22,9 @@ import {
   loadCharacterBundleFromBytes,
   makeRegionMask,
   packSplats,
-  parseGaussianPly
-} from "./chunks/chunk-MM6DJU6S.js";
+  parseGaussianPly,
+  pruneSplats
+} from "./chunks/chunk-WN5WBKM4.js";
 export {
   Animation,
   Armature,
@@ -39,6 +41,7 @@ export {
   SplatEngine,
   SplatMesh,
   SplatPLYLoader,
+  SplatQuality,
   SunLight,
   VSplatLoader,
   WebGLSplatBackend,
@@ -47,6 +50,7 @@ export {
   loadCharacterBundleFromBytes,
   makeRegionMask,
   packSplats,
-  parseGaussianPly
+  parseGaussianPly,
+  pruneSplats
 };
 //# sourceMappingURL=index.js.map

package/dist/types/character.d.ts

@@ -65,7 +65,9 @@ export interface LoadCharacterOptions {
      * Bundles carry translations only, never rotations, so `'bundled'` yields
      * per-character bone LENGTHS with canonical joint ORIENTATIONS - a hybrid.
      * Falls back to `'builtin'` when the bundle has no joints (older files) or
-     * the array length disagrees with the bone count.
+     * the array length disagrees with the bone count. A 119-bone expression
+     * bundle keeps its first 86 body rest translations when posed on Body86;
+     * its 33 facial influences are attached to the head separately.
      */
     restSource?: 'auto' | 'builtin' | 'bundled';
 }
@@ -87,6 +89,11 @@ export declare class Character {
      * vanishes when the active level swaps.
      */
     get splat(): Splat;
+    private _countLodEnabled;
+    private _countLodNearDist;
+    private _countLodFarDist;
+    private _countLodNearFraction;
+    private _countLodFarFraction;
     private _renderLodEnabled;
     private _renderLodNearDist;
     private _renderLodFarDist;
@@ -250,6 +257,41 @@ export declare class Character {
     /** Force a specific render-LOD level, bypassing distance bands. Useful
      *  for debugging / A-B comparisons in the profiling scene. */
     setRenderLevel(level: number): void;
+    /**
+     * Thin the character with distance by processing fewer of its splats, rather
+     * than by switching to a different file.
+     *
+     * At `nearDist` and closer, `nearFraction` of the splats are skinned, sorted
+     * and drawn; at `farDist` and beyond, `farFraction` of them; in between, the
+     * fraction is interpolated. Which splats those are is decided by importance
+     * inside each 4 cm cell (see {@link Splat.setCountLod}), so the character
+     * thins evenly instead of losing a region.
+     *
+     * The dynamic counterpart of {@link SplatQuality.pruneRatio}, and the one to
+     * reach for when the splats are still wanted close up. It composes with
+     * everything else: {@link Character.setRenderLod} switches between loaded
+     * files, {@link Armature.setAnimationLod} and {@link Armature.setSortLod}
+     * drop frames of pose and sort work, and this one changes how much of the
+     * character each of those frames covers.
+     *
+     * `WebGLRenderer` only - see {@link Splat.setCountLod} for why.
+     *
+     * ```ts
+     * character.setSplatCountLod({ nearDist: 4, farDist: 16, farFraction: 0.25 });
+     * ```
+     */
+    setSplatCountLod(opts: {
+        nearDist: number;
+        farDist: number;
+        /** Fraction kept at `nearDist` and closer. Default 1. */
+        nearFraction?: number;
+        /** Fraction kept at `farDist` and beyond. Default 0.3. */
+        farFraction?: number;
+    }): void;
+    /** Stop thinning: every splat is processed again, on every level. */
+    disableSplatCountLod(): void;
+    /** Pick this frame's splat fraction from camera distance and apply it. */
+    private _applyCountLod;
     /** Number of LOD levels loaded for this character (>=1). */
     get renderLodLevels(): number;
     /** Active render-LOD level (0 = highest fidelity). */

package/dist/types/index.d.ts

@@ -19,6 +19,9 @@ export type { SplatBackend } from './splat/backend';
 export type { SplatOptions, SplatSource } from './splat/splat';
 export { packSplats } from './splat/packed-splats';
 export type { PackedSplats } from './splat/packed-splats';
+export { SplatQuality } from './splat/quality';
+export { pruneSplats } from './splat/prune';
+export type { PruneOptions, PruneReport } from './splat/prune';
 export { SunLight } from './lighting/sun-light';
 export type { CreateSunLightOptions } from './lighting/sun-light';
 export { SkyLight } from './lighting/sky-light';

package/dist/types/splat/bone-binding.d.ts

@@ -35,4 +35,4 @@ export declare function initializeSplatBoneMapping(splat: Splat, numBones: numbe
  * Returns an empty `Int32Array` when the splat has no weights data - callers
  * treat that as "fall back to walking every bone."
  */
-export declare function buildSplatBoneIndexList(splat: Splat, numBones: number): Int32Array;
+export declare function buildSplatBoneIndexList(splat: Splat, numBones: number, firstPaletteIdx: number): Int32Array;

package/dist/types/splat/depth-sort.d.ts

@@ -19,7 +19,13 @@ export declare function projectBoundsOnDirection(min: ArrayLike<number>, max: Ar
 /** Synchronous sorter with its own scratch buffers. One per splat. */
 export declare class DepthSorter {
     private readonly _scratch;
-    sort(centers: Float32Array, count: number, dx: number, dy: number, dz: number, depthMin: number, depthMax: number, order: Uint32Array): void;
+    /**
+     * @param count - How many splats take part. With `subset`, the length of
+     * the prefix of it to use; without, the splats are `[0, count)`.
+     * @param subset - Splat indices to sort, for a count LOD. See
+     * {@link Splat.setCountLod}.
+     */
+    sort(centers: Float32Array, count: number, dx: number, dy: number, dz: number, depthMin: number, depthMax: number, order: Uint32Array, subset?: Uint32Array | null): void;
 }
 export interface SortRequest {
     dx: number;
@@ -27,6 +33,11 @@ export interface SortRequest {
     dz: number;
     depthMin: number;
     depthMax: number;
+    /**
+     * How many splats to order, for a count LOD. Defaults to all of them; with
+     * a subset set, the length of the prefix of it to use.
+     */
+    count?: number;
 }
 /**
  * Worker-backed sorter for static splats.
@@ -46,11 +57,18 @@ export declare class AsyncDepthSorter {
     private _order;
     /**
      * @param centers - Flat `[x,y,z] * count`. Copied into the worker once.
-     * @param onSorted - Called with each finished order. The array is only valid
-     * for the duration of the call - it goes back to the worker on the next
-     * request - so copy out of it before returning.
+     * @param onSorted - Called with each finished order and how many of its
+     * entries are current. The array is only valid for the duration of the call
+     * - it goes back to the worker on the next request - so copy out of it
+     * before returning.
+     */
+    constructor(centers: Float32Array, count: number, onSorted: (order: Uint32Array, count: number) => void);
+    /**
+     * Give the worker the importance ordering a count LOD selects from. Sent
+     * once and kept there, like the centres; after this a request carries only
+     * how many of its entries to use.
      */
-    constructor(centers: Float32Array, count: number, onSorted: (order: Uint32Array) => void);
+    setSubset(subset: Uint32Array): void;
     /** True while a sort is running in the worker. */
     get busy(): boolean;
     request(req: SortRequest): void;

package/dist/types/splat/importance.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Ranking splats by how much they contribute, and the spatial bucketing both
+ * users of that ranking share.
+ *
+ * Two features are built on it. {@link pruneSplats} throws the weakest splats
+ * away at load; the count LOD ({@link Splat.setCountLod}) keeps them all and
+ * processes a prefix of the ranking that shrinks with distance. The ranking
+ * has to be the same one in both cases, which is why it lives here rather than
+ * in either of them.
+ */
+import type { PackedSplats } from './packed-splats';
+/**
+ * Group indices by spatial cell without a comparison sort: hash the cells to
+ * dense ids, count, prefix-sum, scatter.
+ *
+ * O(n) with one map probe per splat, against the O(n log n) a sort over a
+ * composite key would cost - which measured 11-16 ms of a ~40 ms character
+ * load in the Unity build this is ported from.
+ */
+export declare function bucketByCell(cellKey: Float64Array, n: number): {
+    order: Uint32Array;
+    start: Uint32Array;
+    cells: number;
+};
+/**
+ * One splat's cell key on a `1 / voxelSize` grid whose origin is `min`.
+ *
+ * The one definition of the grid. Both users of it have to agree - a splat
+ * pruned by one rule and ranked by another would be thinned twice in the same
+ * place - and they walk different layouts, so what they share is this rather
+ * than a loop.
+ */
+export declare function cellKeyOf(x: number, y: number, z: number, minX: number, minY: number, minZ: number, invVoxel: number): number;
+/**
+ * Cell keys for `centers`, with the grid origin at the actual minimum of the
+ * positions rather than at any declared bounds, which can carry a margin the
+ * grid should not inherit.
+ */
+export declare function cellKeysFor(centers: Float32Array, count: number, voxelSize: number): Float64Array;
+/**
+ * Splat indices ordered so that any prefix of the result is a good-looking
+ * subset of the whole: the most important splat of every cell first, then the
+ * second of every cell, and so on.
+ *
+ * Importance within a cell is opacity times the two largest gaussian axes -
+ * the area the splat actually paints, which the Unity build measured as
+ * ranking 0.80 with the ink each splat deposits, at no cost to compute.
+ *
+ * The round-robin across cells is what makes this usable as a prefix, and it
+ * is the same decision the load-time prune makes for the same reason: ranked
+ * globally, a prefix would be every strong splat on the jacket and none of the
+ * many individually-faint ones that make up a face, so the face would be the
+ * first thing to go. Taken a rank at a time across cells, every region thins
+ * by the same proportion at every prefix length, so a character at 30% looks
+ * like a sparser version of itself rather than a damaged one.
+ *
+ * Costs one pass over the splats plus a small sort inside each cell, and is
+ * built once, the first time a count LOD asks for it.
+ */
+export declare function buildImportanceOrder(packed: PackedSplats, voxelSize: number): Uint32Array;

package/dist/types/splat/prune.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Load-time splat removal: the two passes that make a character cheaper by
+ * containing fewer splats, rather than by drawing each one faster.
+ *
+ * Both run on the decoded attribute columns, before {@link packSplats} turns
+ * them into texels, so a removed splat costs nothing anywhere afterwards -
+ * no texel, no CPU skinning slot, no sort slot, no quad. That is what
+ * separates these from {@link SplatQuality.quadAlphaCutoff}, which shrinks
+ * quads and saves rasterisation alone.
+ *
+ * Ported from the Unity build's `SplatCharacterBinData.CullByOpacity` and
+ * `PruneByImportance`, including the two decisions in them that are easy to
+ * get wrong: ranking inside spatial cells rather than globally, and selecting
+ * rather than sorting within a cell.
+ */
+import type { SplatAttributes } from '../loader/character/types';
+import type { SplatWeights } from '../types';
+/** What {@link pruneSplats} did, for a caller that wants to log or report it. */
+export interface PruneReport {
+    /** Splats the decode handed in. */
+    numSplatsIn: number;
+    /** Splats left after both passes. This is what every consumer should read. */
+    numSplatsOut: number;
+    /** Removed by the opacity floor. */
+    droppedByOpacity: number;
+    /** Removed by the per-voxel importance quota, on top of the opacity floor. */
+    droppedByImportance: number;
+    /**
+     * The skinning influences, re-viewed onto the compacted prefix when anything
+     * was removed, or the caller's own object when nothing was. `undefined` for
+     * a splat with no skinning.
+     *
+     * Handed back rather than mutated in place because the arrays' *length* is
+     * what says how many influences each splat has: `Splat` divides it by the
+     * splat count to recover `K`, and leaving a pruned set at its original
+     * length would make that division report a `K` several times too large.
+     */
+    weights?: SplatWeights;
+}
+export interface PruneOptions {
+    /** Defaults to {@link SplatQuality.minOpacity}. */
+    minOpacity?: number;
+    /** Defaults to {@link SplatQuality.pruneRatio}. */
+    pruneRatio?: number;
+    /** Defaults to {@link SplatQuality.pruneVoxelSize}. */
+    voxelSize?: number;
+}
+/**
+ * Remove splats the current quality settings say are not worth carrying,
+ * compacting every column in place.
+ *
+ * `attributes` and `weights` are mutated: their arrays keep their allocated
+ * length and the returned count is what every consumer should read, which is
+ * exactly how {@link packSplats} already uses `numSplats`. Order is preserved,
+ * so whatever spatial coherence the file had survives.
+ *
+ * Returns the input count unchanged, having touched nothing, when both knobs
+ * are off - the default - so this sits on the load path for free.
+ */
+export declare function pruneSplats(numSplats: number, attributes: SplatAttributes, weights?: SplatWeights, opts?: PruneOptions): PruneReport;

package/dist/types/splat/quality.d.ts

@@ -0,0 +1,175 @@
+export declare const SplatQuality: {
+    /**
+     * Alpha at which a splat's quad is allowed to end, so each one is sized to
+     * the radius its own opacity actually reaches instead of to the worst case.
+     * **The first knob to reach for on a weak GPU.**
+     *
+     * The fragment stage multiplies a gaussian falloff by the splat's opacity
+     * and discards anything below 1/255, so a quad drawn out to where that
+     * product is already below the cutoff spends fragments on a ring that
+     * cannot put ink on the screen. Raising the cutoff shrinks every quad. What
+     * it costs is a harder edge on each splat, which shows first on soft things
+     * - hair, fabric, anything semi-transparent.
+     *
+     * Takes effect on the next frame; nothing is reloaded and nothing is lost,
+     * so it is safe to drive from a frame-rate governor.
+     *
+     * | Value | What it is for |
+     * |---|---|
+     * | `1 / 255` | Exactly the behaviour before this knob existed. Changes nothing at all: below it a fragment is discarded anyway, so the quad it trims was drawing nothing. |
+     * | `8 / 255` | What the Unity build ships. The conservative end. |
+     * | `12 / 255` | **The default here.** |
+     * | `16 / 255` | **Low-end phones, and the floor.** Still 43.7 dB overall and 34.8 dB on the face, which the Unity build calls invisible at arm's length. |
+     * | above `16 / 255` | Not on this project. The Unity build measures a further -7% at 24/255, but the edges are visibly harder by then; a device that needs more should spend it on {@link SplatQuality.pruneRatio}, the renderer's pixel ratio, or a distance LOD, none of which harden every silhouette in the frame. |
+     *
+     * Measured on a Mali-G57 with three characters, against 8/255: 12/255 -7%,
+     * 16/255 -12%, 24/255 -19%. Measured here on an Apple GPU where fragments
+     * are the bottleneck, against 1/255: 8/255 -29%, 16/255 -42%, 24/255 -50%.
+     * Where the main thread is the bottleneck instead - the WebGL backend with
+     * animated characters - it is free but buys nothing; see the README's
+     * Tuning section for which case a scene is in.
+     */
+    quadAlphaCutoff: number;
+    /**
+     * Drop splats whose projected size falls below this radius in pixels, for
+     * every splat at once. `0` (the default) draws everything.
+     *
+     * The same test as the per-splat {@link Splat.minPixelSize}; the larger of
+     * the two wins, so a global floor cannot un-cull a splat an application
+     * already asked to cull. Removes distant crowd splats that cannot contribute
+     * more than a fraction of a pixel.
+     */
+    screenSizeCull: number;
+    /**
+     * Peak opacity a splat must reach to be kept when a character or scene is
+     * loaded. `0` keeps everything.
+     *
+     * A splat's alpha at its centre IS its opacity - the gaussian only falls
+     * off from there - so the faintest splats in a bundle are ones that paint
+     * almost nothing from any camera while still costing memory, a skinning
+     * pass, a sort slot and a quad. This removes them outright, which is what
+     * separates it from {@link SplatQuality.quadAlphaCutoff}: the cutoff
+     * shrinks a splat's quad and saves rasterisation alone, this saves
+     * everything, but it cannot half-remove one.
+     *
+     * **Applied during the decode of a CHARACTER bundle**, so it only affects
+     * what is loaded afterwards - set it before the first `load()`, and changing
+     * it later does nothing to characters already in the scene. It does not
+     * touch `.ply` scenes, matching the Unity build, which applies it in the
+     * skinned renderer and nowhere else: a scene's opacity distribution is a
+     * different thing, and 0.05 measured as 8.7% of a character against 41.8%
+     * of a 1M-splat room. {@link pruneSplats} is exported for an application
+     * that wants to make the trade on a scene of its own. It also changes
+     * {@link Splat.numSplats}, so an application that hands back a per-splat
+     * array ({@link Splat.setSplatGroups}) must size that array from
+     * `numSplats` after loading rather than from the file.
+     *
+     * | Value | What it is for |
+     * |---|---|
+     * | `0` | Keep every splat. The behaviour before this knob existed. |
+     * | `1 / 255` | Free in the strict sense: provably pixel-identical, because a splat under the fragment shader's own discard cannot produce a pixel. Worth about 2% of a character. |
+     * | `0.05` | **The default here, and what the Unity build ships.** Removes ~13% of a typical character for a difference of at most 11/255 on 1.3% of it - 58-62 dB, which does not read as a quality loss. |
+     * | above `0.05` | Untested. Prefer {@link SplatQuality.pruneRatio} to go further: it is measured, and it thins every region by the same share instead of taking the faintest splats wherever they happen to be - which is disproportionately the face. |
+     */
+    minOpacity: number;
+    /**
+     * Fraction of splats removed at load by voxel-local importance, on top of
+     * {@link SplatQuality.minOpacity}. `0` (the default) keeps everything, `0.5`
+     * drops the least-important half of every cell.
+     *
+     * Importance is opacity times a splat's two largest axes - the area it
+     * actually paints - ranked separately inside each spatial cell so a dense
+     * region loses the same share as a sparse one rather than being deleted
+     * wholesale. That per-cell quota is what keeps the face: a global ranking
+     * puts the many faint facial splats at the bottom and smears it. Measured on
+     * the Unity build's reference character at 0.5: 25,826 of 50,267 splats
+     * remain, the frame falls 24.5% on a Mali-G57, and the face holds 43.5 dB
+     * where a global rank gives 37.6.
+     *
+     * Applied during the decode of a character bundle, like
+     * {@link SplatQuality.minOpacity}, with the same scope and the same reason
+     * for being off by default.
+     */
+    pruneRatio: number;
+    /**
+     * Cell size, in metres, for {@link SplatQuality.pruneRatio}'s per-voxel
+     * quota.
+     *
+     * 4 cm gives ~19 splats per occupied cell on the Unity build's reference
+     * character - small enough that the face and the jacket are ranked apart,
+     * large enough that a cell has a population to rank. A tuning constant
+     * rather than a per-title knob, exposed because a character authored at a
+     * different scale needs a different one.
+     */
+    pruneVoxelSize: number;
+    /**
+     * Test each splat against the depth buffer, so opaque geometry hides the
+     * splats behind it. On by default.
+     *
+     * Unlike the Unity build, where turning this off was the single largest
+     * mobile saving, this is a correctness switch here and not a performance
+     * one: that build renders splats into an offscreen target and pays for the
+     * test by sampling a depth texture per fragment, where this package draws
+     * straight into the camera's target and gets the hardware depth test for
+     * free. Turning it off makes characters draw through walls and saves
+     * nothing. It is here because the behaviour is occasionally what an
+     * application wants - a character deliberately drawn over the scene.
+     */
+    depthOcclusion: boolean;
+    /**
+     * Collect {@link SplatQuality.timings}. Off by default.
+     *
+     * The CPU stages are timed with `performance.now()`, which is cheap but not
+     * free at a few calls per splat per frame, and a shipping application that
+     * never reads the numbers should not pay for them.
+     */
+    passTimings: boolean;
+    /**
+     * Per-stage cost of the last frame in which {@link SplatQuality.passTimings}
+     * was on, in milliseconds, summed over every splat that ran that stage.
+     *
+     * These are main-thread times, which is the measurement that matters for
+     * this package: under `WebGLRenderer` the per-character CPU cost - skinning
+     * every centre to feed the sort, then the sort - is what limits how many
+     * characters a scene can carry, and neither stage exists on the GPU
+     * timeline. `skin` and `sort` are zero under `WebGPURenderer`, where both
+     * happen in compute; `splatsDrawn` and `splatsTotal` are meaningful on both,
+     * and differ when {@link SplatQuality.screenSizeCull} or a count LOD is
+     * reducing what is submitted.
+     *
+     * These describe the most recent pass in which any splat drew, so read them
+     * after your render call. A pass that drew no splats leaves the previous
+     * numbers in place rather than zeroing them - a zero and "nothing happened"
+     * would otherwise read the same, which is the mistake the Unity build's
+     * equivalent made and spent a long time chasing.
+     */
+    timings: {
+        /** CPU skinning of splat centres, i.e. `Splat.ensureCenters`. */
+        skin: number;
+        /** The depth sort, where it runs on the main thread. */
+        sort: number;
+        /** Uniform and buffer updates in `beforeRender`, excluding skin and sort. */
+        prepare: number;
+        /** Splat instances submitted to the GPU this frame. */
+        splatsDrawn: number;
+        /** Splat instances those draws could have covered at full detail. */
+        splatsTotal: number;
+    };
+    /** Restore every knob to its default. Call when tearing the engine down. */
+    resetStatics(): void;
+};
+/** The effective sub-pixel cull for one splat: its own floor or the global one. */
+export declare function effectiveMinPixelSize(splatMinPixelSize: number): number;
+/**
+ * Add a CPU skinning measurement for the frame now being prepared.
+ * @internal
+ */
+export declare function addSkinTime(ms: number): void;
+/**
+ * Open this pass's timing accumulation, clearing it when `source` - the splat
+ * reporting - has already contributed, which means a new pass has begun.
+ * Called by every backend before it adds to {@link SplatQuality.timings}.
+ *
+ * @internal
+ */
+export declare function beginFrameTimings(source: object): void;

package/dist/types/splat/splat.d.ts

@@ -83,6 +83,10 @@ export declare class Splat {
     readonly localBounds: Box3;
     /** Discard splats smaller than this many pixels on screen. `0` draws everything. */
     minPixelSize: number;
+    private _activeSplatCount;
+    private _importanceOrder;
+    /** `_importanceOrder` inverted: each splat's place in it. @internal */
+    private _importanceRank;
     private readonly _mesh;
     private _cpuInfluences;
     private _pendingBoneTransforms;
@@ -103,8 +107,65 @@ export declare class Splat {
     cloneStatic(engine: SplatEngine, asyncSort: boolean): Splat;
     /** Top-4 influences per splat, zero-padded. The shader and the CPU path both assume four. */
     private _normalizeWeights;
+    /**
+     * How many splats are skinned, sorted and drawn this frame: the whole set,
+     * or the first `n` of {@link Splat.importanceOrder} after
+     * {@link Splat.setCountLod}.
+     */
+    get activeSplatCount(): number;
+    /** Whether a count LOD is currently reducing this splat. */
+    get countLodActive(): boolean;
+    /**
+     * Process only the `n` most important splats this frame, or the whole set
+     * with `null`.
+     *
+     * The dynamic counterpart of {@link SplatQuality.pruneRatio}: the prune
+     * decides once, at load, that some splats are not worth carrying at all,
+     * while this decides per frame how many of them are worth the work right
+     * now - which is the trade a character makes as it walks away from the
+     * camera. Nothing is freed, so it reverses the moment `n` goes back up.
+     *
+     * Which splats the first `n` are is {@link Splat.importanceOrder}'s answer:
+     * the strongest splat of every 4 cm cell, then the second of every cell, and
+     * so on, so the character thins evenly rather than losing a region.
+     *
+     * `WebGLRenderer` only, where it is worth the most: that backend skins every
+     * splat centre on the CPU each frame to feed its sort, and this cuts that
+     * pass, the sort and the draw together. Under `WebGPURenderer` all of that
+     * already happens in compute, and the call is accepted and ignored rather
+     * than silently changing which splats a GPU sort can see.
+     *
+     * {@link Character.setSplatCountLod} drives this from camera distance; call
+     * it directly for a policy of your own.
+     */
+    setCountLod(n: number | null): void;
+    /**
+     * Build {@link Splat.importanceOrder} now, if it does not exist yet.
+     *
+     * One pass over the splats plus a small sort inside each 4 cm cell - single
+     * digit milliseconds for a character, but milliseconds that would otherwise
+     * land on the frame where the LOD first engages, which is a frame where the
+     * camera is already moving. {@link Character.setSplatCountLod} calls this
+     * when the LOD is configured, so the cost lands there instead.
+     */
+    prepareCountLod(): void;
+    /**
+     * Each splat's place in {@link Splat.importanceOrder}, which is how the
+     * per-frame passes test membership of the active prefix. `null` until
+     * {@link Splat.prepareCountLod}.
+     * @internal
+     */
+    get importanceRank(): Uint32Array | null;
+    /**
+     * Splat indices ordered by importance for {@link Splat.setCountLod}. `null`
+     * until {@link Splat.prepareCountLod} or a count LOD has asked for one.
+     */
+    get importanceOrder(): Uint32Array | null;
     /** Re-upload the bone index/weight textures after editing their data arrays. */
     markBoneTexturesDirty(): void;
+    /** Keep CPU-skinned centres (sorting and ground probes) on the same bone
+     * mapping as the GPU shader. Called once when an armature binds this splat. */
+    syncMappedCpuInfluences(firstPaletteIdx: number): void;
     get variantMaskEnabled(): boolean;
     get nonRigidCovariance(): boolean;
     /**
@@ -136,6 +197,11 @@ export declare class Splat {
     /**
      * Assign each splat to a group and enable per-group visibility. All groups
      * start visible; toggle them with {@link Splat.setVariantMask}.
+     *
+     * `groupIds` is indexed by splat, so it has to be built against
+     * {@link Splat.numSplats} as loaded - which {@link SplatQuality.minOpacity}
+     * makes smaller than the count in the file. An array authored offline
+     * against the file cannot simply be shortened: see the error this throws.
      */
     setSplatGroups(groupIds: Uint8Array, numGroups: number): void;
     /** Per-group visibility, one entry per group: `>= 0.5` shows the group. */

package/dist/types/splat/webgl/shaders.d.ts

@@ -1,2 +1,2 @@
-export declare const SPLAT_VERTEX_GLSL = "\nprecision highp float;\nprecision highp int;\nprecision highp usampler2D;\n\n// Quad corner in [-1, 1].\nin vec3 position;\n// Index of the splat this instance draws; instances arrive back-to-front.\nin uint splatOrder;\n\nuniform mat4 modelMatrix;\nuniform mat4 viewMatrix;\nuniform mat4 projectionMatrix;\n\nuniform highp usampler2D tTransformA;\nuniform highp sampler2D tTransformB;\nuniform highp sampler2D tColor;\nuniform int uTexWidth;\n\n// Drawing-buffer size in pixels.\nuniform vec2 uViewport;\nuniform float uMinPixelSize;\n// World rotation (xyzw) and scale of the splat object.\nuniform vec4 uModelRotation;\nuniform vec3 uModelScale;\n// rgb tint colour, a tint amount.\nuniform vec4 uTint;\n// x contrast, y saturation.\nuniform vec2 uGrade;\n// 1 when the render target expects linear colour, 0 when it is display-referred.\nuniform float uOutputLinear;\n\nout mediump vec2 gaussianUV;\nout mediump vec4 gaussianColor;\n\n\nuniform vec3 uSunColor;\nuniform float uSunIntensity;\nuniform vec3 uAmbientColor;\nuniform int uPointLightCount;\nuniform highp sampler2D uPointLightTex;\n\n// Baked splat colour is multiplied by this. With no lights it is exactly 1.\nvec3 computeLitFactor(vec3 worldCenter) {\n    vec3 lit = uAmbientColor + uSunColor * uSunIntensity;\n    for (int i = 0; i < uPointLightCount; i++) {\n        vec4 posRange = texelFetch(uPointLightTex, ivec2(i, 0), 0);\n        vec4 colorInt = texelFetch(uPointLightTex, ivec2(i, 1), 0);\n        vec3 toLight = posRange.xyz - worldCenter;\n        float dist = length(toLight);\n        float range = posRange.w;\n        if (dist >= range) continue;\n        float t = dist / range;\n        float atten = 1.0 - t * t;\n        atten = atten * atten;\n        lit += colorInt.rgb * colorInt.w * atten;\n    }\n    return lit;\n}\n\n\nuniform highp sampler2D transformPalette;\n\n#ifdef USE_BONE_BLENDING\nuniform highp sampler2D boneIndices;\nuniform highp sampler2D boneWeights;\n#endif\n\n#ifdef USE_VARIANT_MASK\nuniform highp sampler2D splatGroupIds;\nuniform highp sampler2D splatVariantMask;\n\nbool isSplatHiddenByVariantMask(ivec2 splatUV) {\n    float gidF = texelFetch(splatGroupIds, splatUV, 0).r;\n    int gid = int(gidF + 0.5);\n    float bit = texelFetch(splatVariantMask, ivec2(gid, 0), 0).r;\n    return bit < 0.5;\n}\n#endif\n\nbool isReasonablePaletteTransform(mat4 t) {\n    mat3 lin = mat3(t);\n    vec3 s = vec3(length(lin[0]), length(lin[1]), length(lin[2]));\n    // Reject only when EVERY column is near-zero (a truly empty palette slot).\n    // Linear-blend skinning of two very different bone rotations produces a\n    // candy-wrapper matrix with one short column; that is still a valid\n    // mid-rotation transform. Requiring all columns to pass would collapse\n    // joint-spanning splats (notably the neck) back to the bind pose.\n    return any(greaterThan(s, vec3(1e-4)));\n}\n\nmat4 readTransformFromPalette(uint paletteIndex) {\n    if (paletteIndex == 0u) {\n        return mat4(1.0);\n    }\n\n    int u = int(paletteIndex % 512u) * 3;\n    int v = int(paletteIndex / 512u);\n\n    mat4 t;\n    t[0] = texelFetch(transformPalette, ivec2(u, v), 0);\n    t[1] = texelFetch(transformPalette, ivec2(u + 1, v), 0);\n    t[2] = texelFetch(transformPalette, ivec2(u + 2, v), 0);\n    t[3] = vec4(0.0, 0.0, 0.0, 1.0);\n\n    mat4 result = transpose(t);\n    if (!isReasonablePaletteTransform(result)) {\n        return mat4(1.0);\n    }\n    return result;\n}\n\nmat4 getSplatPaletteTransform(ivec2 splatUV) {\n    #ifdef USE_BONE_BLENDING\n    vec4 boneIdxVec = texelFetch(boneIndices, splatUV, 0);\n    vec4 boneWeightVec = texelFetch(boneWeights, splatUV, 0);\n    float totalWeight = dot(boneWeightVec, vec4(1.0));\n    if (totalWeight > 0.001) {\n        mat4 blended = mat4(0.0);\n        for (int i = 0; i < 4; i++) {\n            float w = boneWeightVec[i];\n            if (w > 0.001) {\n                uint idx = uint(boneIdxVec[i] + 0.5);\n                blended += readTransformFromPalette(idx) * w;\n            }\n        }\n        mat4 result = blended / totalWeight;\n        if (isReasonablePaletteTransform(result)) {\n            return result;\n        }\n    }\n    #endif\n\n    return mat4(1.0);\n}\n\nvec4 mat3ToQuatXYZW(mat3 R) {\n    vec4 q;\n    float trace = R[0][0] + R[1][1] + R[2][2];\n    if (trace > 0.0) {\n        float s = sqrt(trace + 1.0) * 2.0;\n        q.w = 0.25 * s;\n        q.x = (R[1][2] - R[2][1]) / s;\n        q.y = (R[2][0] - R[0][2]) / s;\n        q.z = (R[0][1] - R[1][0]) / s;\n    } else if (R[0][0] > R[1][1] && R[0][0] > R[2][2]) {\n        float s = sqrt(1.0 + R[0][0] - R[1][1] - R[2][2]) * 2.0;\n        q.w = (R[1][2] - R[2][1]) / s;\n        q.x = 0.25 * s;\n        q.y = (R[1][0] + R[0][1]) / s;\n        q.z = (R[2][0] + R[0][2]) / s;\n    } else if (R[1][1] > R[2][2]) {\n        float s = sqrt(1.0 + R[1][1] - R[0][0] - R[2][2]) * 2.0;\n        q.w = (R[2][0] - R[0][2]) / s;\n        q.x = (R[1][0] + R[0][1]) / s;\n        q.y = 0.25 * s;\n        q.z = (R[2][1] + R[1][2]) / s;\n    } else {\n        float s = sqrt(1.0 + R[2][2] - R[0][0] - R[1][1]) * 2.0;\n        q.w = (R[0][1] - R[1][0]) / s;\n        q.x = (R[2][0] + R[0][2]) / s;\n        q.y = (R[2][1] + R[1][2]) / s;\n        q.z = 0.25 * s;\n    }\n    return q;\n}\n\n\nconst vec4 discardVec = vec4(0.0, 0.0, 2.0, 1.0);\n\nmat3 quatToMat3(vec4 R) {\n    vec4 R2 = R + R;\n    float X = R2.x * R.w;\n    vec4 Y = R2.y * R;\n    vec4 Z = R2.z * R;\n    float W = R2.w * R.w;\n    return mat3(\n        1.0 - Z.z - W, Y.z + X, Y.w - Z.x,\n        Y.z - X, 1.0 - Y.y - W, Z.w + Y.x,\n        Y.w + Z.x, Z.w - Y.x, 1.0 - Y.y - Z.z\n    );\n}\n\nvec4 quatMul(vec4 a, vec4 b) {\n    return vec4(\n        a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,\n        a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,\n        a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,\n        a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z\n    );\n}\n\nvoid computeCovariance(vec4 rotation, vec3 scale, out vec3 covA, out vec3 covB) {\n    mat3 rot = quatToMat3(rotation);\n    mat3 M = transpose(mat3(\n        scale.x * rot[0],\n        scale.y * rot[1],\n        scale.z * rot[2]\n    ));\n    covA = vec3(dot(M[0], M[0]), dot(M[0], M[1]), dot(M[0], M[2]));\n    covB = vec3(dot(M[1], M[1]), dot(M[1], M[2]), dot(M[2], M[2]));\n}\n\nvec3 sRGBToLinear(vec3 c) {\n    return mix(\n        pow(c * 0.9478672986 + vec3(0.0521327014), vec3(2.4)),\n        c * 0.0773993808,\n        vec3(lessThanEqual(c, vec3(0.04045)))\n    );\n}\n\nvoid main(void) {\n    ivec2 splatUV = ivec2(int(splatOrder % uint(uTexWidth)), int(splatOrder / uint(uTexWidth)));\n    uvec4 tA = texelFetch(tTransformA, splatUV, 0);\n    vec4 tB = texelFetch(tTransformB, splatUV, 0);\n\n    vec3 modelCenter = uintBitsToFloat(tA.xyz);\n    vec3 packedRot = vec3(unpackHalf2x16(tA.w), tB.w);\n    // xyzw, with w recovered: quaternions are stored on the w >= 0 hemisphere.\n    vec4 srcRotation = vec4(packedRot, sqrt(max(0.0, 1.0 - dot(packedRot, packedRot))));\n    vec3 srcScale = tB.xyz;\n\n    // ---- Skin, then lift to world space --------------------------------\n    mat4 palette = getSplatPaletteTransform(splatUV);\n    vec3 modelDeformed = (palette * vec4(modelCenter, 1.0)).xyz;\n    vec3 worldCenter = (modelMatrix * vec4(modelDeformed, 1.0)).xyz;\n\n    vec4 worldRotation = quatMul(uModelRotation, srcRotation);\n    if (worldRotation.w < 0.0) worldRotation = -worldRotation;\n    vec3 worldScale = uModelScale * srcScale;\n\n    #ifdef USE_BONE_BLENDING\n    {\n        // The full world-space skinning rotation comes from modelMatrix * palette;\n        // the palette's own scale is deliberately dropped (rigid skinning).\n        mat3 lin = mat3(modelMatrix * palette);\n        vec3 s = vec3(length(lin[0]), length(lin[1]), length(lin[2]));\n        if (s.x > 1e-5 && s.y > 1e-5 && s.z > 1e-5) {\n            mat3 rot = mat3(lin[0] / s.x, lin[1] / s.y, lin[2] / s.z);\n            vec4 composed = normalize(quatMul(mat3ToQuatXYZW(rot), srcRotation));\n            if (composed.w < 0.0) composed = -composed;\n            worldRotation = composed;\n        }\n        #ifdef USE_NONRIGID_COV\n        // Bone-length scaling: the palette keeps its per-axis scale and the\n        // gaussian stretches with the bone.\n        worldScale *= s;\n        #endif\n    }\n    #endif\n\n    #ifdef USE_VARIANT_MASK\n    if (isSplatHiddenByVariantMask(splatUV)) {\n        gl_Position = discardVec;\n        return;\n    }\n    #endif\n\n    // ---- Project the centre --------------------------------------------\n    bool ortho = projectionMatrix[3][3] == 1.0;\n    vec4 centerView = viewMatrix * vec4(worldCenter, 1.0);\n    if (!ortho && centerView.z > 0.0) {\n        gl_Position = discardVec;\n        return;\n    }\n    vec4 centerProj = projectionMatrix * centerView;\n    centerProj.z = clamp(centerProj.z, -abs(centerProj.w), abs(centerProj.w));\n\n    // ---- Project the covariance to a screen-space ellipse ----------------\n    vec3 covA, covB;\n    computeCovariance(worldRotation.wxyz, worldScale, covA, covB);\n    mat3 Vrk = mat3(\n        covA.x, covA.y, covA.z,\n        covA.y, covB.x, covB.y,\n        covA.z, covB.y, covB.z\n    );\n\n    float focal = uViewport.x * projectionMatrix[0][0];\n    vec3 v = centerView.xyz;\n    vec3 vp = ortho ? vec3(0.0, 0.0, 1.0) : v;\n    float J1 = focal / vp.z;\n    vec2 J2 = -J1 / vp.z * vp.xy;\n    mat3 J = mat3(\n        J1, 0.0, J2.x,\n        0.0, J1, J2.y,\n        0.0, 0.0, 0.0\n    );\n    mat3 W = transpose(mat3(viewMatrix));\n    mat3 T = W * J;\n    mat3 cov = transpose(T) * Vrk * T;\n\n    #ifdef USE_ANTIALIAS\n    float detOrig = cov[0][0] * cov[1][1] - cov[0][1] * cov[0][1];\n    float detBlur = (cov[0][0] + 0.3) * (cov[1][1] + 0.3) - cov[0][1] * cov[0][1];\n    float aaFactor = sqrt(max(detOrig / detBlur, 0.0));\n    #endif\n\n    float diagonal1 = cov[0][0] + 0.3;\n    float offDiagonal = cov[0][1];\n    float diagonal2 = cov[1][1] + 0.3;\n    float mid = 0.5 * (diagonal1 + diagonal2);\n    float radius = length(vec2((diagonal1 - diagonal2) / 2.0, offDiagonal));\n    float lambda1 = mid + radius;\n    float lambda2 = max(mid - radius, 0.1);\n\n    float vmin = min(1024.0, min(uViewport.x, uViewport.y));\n    float l1 = 2.0 * min(sqrt(2.0 * lambda1), vmin);\n    float l2 = 2.0 * min(sqrt(2.0 * lambda2), vmin);\n    if (max(l1, l2) < uMinPixelSize) {\n        gl_Position = discardVec;\n        return;\n    }\n\n    // Cull splats whose ellipse lies wholly off-screen.\n    vec2 c = centerProj.ww / uViewport;\n    if (any(greaterThan(abs(centerProj.xy) - vec2(max(l1, l2)) * c, centerProj.ww))) {\n        gl_Position = discardVec;\n        return;\n    }\n\n    vec2 diagonalVector = normalize(vec2(offDiagonal, lambda1 - diagonal1));\n    vec2 v1 = l1 * diagonalVector;\n    vec2 v2 = l2 * vec2(diagonalVector.y, -diagonalVector.x);\n    vec2 cornerUV = position.xy;\n    vec2 offset = (cornerUV.x * v1 + cornerUV.y * v2) * c;\n\n    // ---- Colour -----------------------------------------------------------\n    vec4 clr = texelFetch(tColor, splatUV, 0);\n    #ifdef USE_ANTIALIAS\n    clr.a *= aaFactor;\n    #endif\n\n    clr.rgb *= computeLitFactor(worldCenter);\n    clr.rgb = mix(clr.rgb, uTint.rgb, clamp(uTint.a, 0.0, 1.0));\n    // Identity grade is a true no-op: skipping it keeps HDR splat colours unclamped.\n    if (uGrade.x != 1.0 || uGrade.y != 1.0) {\n        clr.rgb = (clr.rgb - 0.5) * uGrade.x + 0.5;\n        float luma = dot(clr.rgb, vec3(0.2126, 0.7152, 0.0722));\n        clr.rgb = mix(vec3(luma), clr.rgb, uGrade.y);\n        clr.rgb = clamp(clr.rgb, 0.0, 1.0);\n    }\n\n    if (255.0 * clr.a <= 1.0) {\n        gl_Position = discardVec;\n        return;\n    }\n\n    // Shrink the quad to where the gaussian is still above 1/255: fewer\n    // fragments, identical pixels.\n    float clip = min(1.0, sqrt(log(255.0 * clr.a)) * 0.5);\n    offset *= clip;\n\n    gl_Position = centerProj + vec4(offset, 0.0, 0.0);\n    gaussianUV = cornerUV * clip;\n\n    vec3 rgb = max(clr.rgb, 0.0);\n    if (uOutputLinear > 0.5) rgb = sRGBToLinear(rgb);\n    gaussianColor = vec4(rgb, clr.a);\n}\n";
+export declare const SPLAT_VERTEX_GLSL = "\nprecision highp float;\nprecision highp int;\nprecision highp usampler2D;\n\n// Quad corner in [-1, 1].\nin vec3 position;\n// Index of the splat this instance draws; instances arrive back-to-front.\nin uint splatOrder;\n\nuniform mat4 modelMatrix;\nuniform mat4 viewMatrix;\nuniform mat4 projectionMatrix;\n\nuniform highp usampler2D tTransformA;\nuniform highp sampler2D tTransformB;\nuniform highp sampler2D tColor;\nuniform int uTexWidth;\n\n// Drawing-buffer size in pixels.\nuniform vec2 uViewport;\nuniform float uMinPixelSize;\n// 1 / the alpha a splat's quad is allowed to end at. Carried as the reciprocal\n// so the historic 1/255 cutoff arrives as exactly 255.0 and the two\n// expressions below reduce, bit for bit, to what they were before the cutoff\n// was a setting at all. See SplatQuality.quadAlphaCutoff.\nuniform float uAlphaCutoffScale;\n// World rotation (xyzw) and scale of the splat object.\nuniform vec4 uModelRotation;\nuniform vec3 uModelScale;\n// rgb tint colour, a tint amount.\nuniform vec4 uTint;\n// x contrast, y saturation.\nuniform vec2 uGrade;\n// 1 when the render target expects linear colour, 0 when it is display-referred.\nuniform float uOutputLinear;\n\nout mediump vec2 gaussianUV;\nout mediump vec4 gaussianColor;\n\n\nuniform vec3 uSunColor;\nuniform float uSunIntensity;\nuniform vec3 uAmbientColor;\nuniform int uPointLightCount;\nuniform highp sampler2D uPointLightTex;\n\n// Baked splat colour is multiplied by this. With no lights it is exactly 1.\nvec3 computeLitFactor(vec3 worldCenter) {\n    vec3 lit = uAmbientColor + uSunColor * uSunIntensity;\n    for (int i = 0; i < uPointLightCount; i++) {\n        vec4 posRange = texelFetch(uPointLightTex, ivec2(i, 0), 0);\n        vec4 colorInt = texelFetch(uPointLightTex, ivec2(i, 1), 0);\n        vec3 toLight = posRange.xyz - worldCenter;\n        float dist = length(toLight);\n        float range = posRange.w;\n        if (dist >= range) continue;\n        float t = dist / range;\n        float atten = 1.0 - t * t;\n        atten = atten * atten;\n        lit += colorInt.rgb * colorInt.w * atten;\n    }\n    return lit;\n}\n\n\nuniform highp sampler2D transformPalette;\n\n#ifdef USE_BONE_BLENDING\nuniform highp sampler2D boneIndices;\nuniform highp sampler2D boneWeights;\n#endif\n\n#ifdef USE_VARIANT_MASK\nuniform highp sampler2D splatGroupIds;\nuniform highp sampler2D splatVariantMask;\n\nbool isSplatHiddenByVariantMask(ivec2 splatUV) {\n    float gidF = texelFetch(splatGroupIds, splatUV, 0).r;\n    int gid = int(gidF + 0.5);\n    float bit = texelFetch(splatVariantMask, ivec2(gid, 0), 0).r;\n    return bit < 0.5;\n}\n#endif\n\nbool isReasonablePaletteTransform(mat4 t) {\n    mat3 lin = mat3(t);\n    vec3 s = vec3(length(lin[0]), length(lin[1]), length(lin[2]));\n    // Reject only when EVERY column is near-zero (a truly empty palette slot).\n    // Linear-blend skinning of two very different bone rotations produces a\n    // candy-wrapper matrix with one short column; that is still a valid\n    // mid-rotation transform. Requiring all columns to pass would collapse\n    // joint-spanning splats (notably the neck) back to the bind pose.\n    return any(greaterThan(s, vec3(1e-4)));\n}\n\nmat4 readTransformFromPalette(uint paletteIndex) {\n    if (paletteIndex == 0u) {\n        return mat4(1.0);\n    }\n\n    int u = int(paletteIndex % 512u) * 3;\n    int v = int(paletteIndex / 512u);\n\n    mat4 t;\n    t[0] = texelFetch(transformPalette, ivec2(u, v), 0);\n    t[1] = texelFetch(transformPalette, ivec2(u + 1, v), 0);\n    t[2] = texelFetch(transformPalette, ivec2(u + 2, v), 0);\n    t[3] = vec4(0.0, 0.0, 0.0, 1.0);\n\n    mat4 result = transpose(t);\n    if (!isReasonablePaletteTransform(result)) {\n        return mat4(1.0);\n    }\n    return result;\n}\n\nmat4 getSplatPaletteTransform(ivec2 splatUV) {\n    #ifdef USE_BONE_BLENDING\n    vec4 boneIdxVec = texelFetch(boneIndices, splatUV, 0);\n    vec4 boneWeightVec = texelFetch(boneWeights, splatUV, 0);\n    float totalWeight = dot(boneWeightVec, vec4(1.0));\n    if (totalWeight > 0.001) {\n        mat4 blended = mat4(0.0);\n        for (int i = 0; i < 4; i++) {\n            float w = boneWeightVec[i];\n            if (w > 0.001) {\n                uint idx = uint(boneIdxVec[i] + 0.5);\n                blended += readTransformFromPalette(idx) * w;\n            }\n        }\n        mat4 result = blended / totalWeight;\n        if (isReasonablePaletteTransform(result)) {\n            return result;\n        }\n    }\n    #endif\n\n    return mat4(1.0);\n}\n\nvec4 mat3ToQuatXYZW(mat3 R) {\n    vec4 q;\n    float trace = R[0][0] + R[1][1] + R[2][2];\n    if (trace > 0.0) {\n        float s = sqrt(trace + 1.0) * 2.0;\n        q.w = 0.25 * s;\n        q.x = (R[1][2] - R[2][1]) / s;\n        q.y = (R[2][0] - R[0][2]) / s;\n        q.z = (R[0][1] - R[1][0]) / s;\n    } else if (R[0][0] > R[1][1] && R[0][0] > R[2][2]) {\n        float s = sqrt(1.0 + R[0][0] - R[1][1] - R[2][2]) * 2.0;\n        q.w = (R[1][2] - R[2][1]) / s;\n        q.x = 0.25 * s;\n        q.y = (R[1][0] + R[0][1]) / s;\n        q.z = (R[2][0] + R[0][2]) / s;\n    } else if (R[1][1] > R[2][2]) {\n        float s = sqrt(1.0 + R[1][1] - R[0][0] - R[2][2]) * 2.0;\n        q.w = (R[2][0] - R[0][2]) / s;\n        q.x = (R[1][0] + R[0][1]) / s;\n        q.y = 0.25 * s;\n        q.z = (R[2][1] + R[1][2]) / s;\n    } else {\n        float s = sqrt(1.0 + R[2][2] - R[0][0] - R[1][1]) * 2.0;\n        q.w = (R[0][1] - R[1][0]) / s;\n        q.x = (R[2][0] + R[0][2]) / s;\n        q.y = (R[2][1] + R[1][2]) / s;\n        q.z = 0.25 * s;\n    }\n    return q;\n}\n\n\nconst vec4 discardVec = vec4(0.0, 0.0, 2.0, 1.0);\n\nmat3 quatToMat3(vec4 R) {\n    vec4 R2 = R + R;\n    float X = R2.x * R.w;\n    vec4 Y = R2.y * R;\n    vec4 Z = R2.z * R;\n    float W = R2.w * R.w;\n    return mat3(\n        1.0 - Z.z - W, Y.z + X, Y.w - Z.x,\n        Y.z - X, 1.0 - Y.y - W, Z.w + Y.x,\n        Y.w + Z.x, Z.w - Y.x, 1.0 - Y.y - Z.z\n    );\n}\n\nvec4 quatMul(vec4 a, vec4 b) {\n    return vec4(\n        a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,\n        a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,\n        a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,\n        a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z\n    );\n}\n\nvoid computeCovariance(vec4 rotation, vec3 scale, out vec3 covA, out vec3 covB) {\n    mat3 rot = quatToMat3(rotation);\n    mat3 M = transpose(mat3(\n        scale.x * rot[0],\n        scale.y * rot[1],\n        scale.z * rot[2]\n    ));\n    covA = vec3(dot(M[0], M[0]), dot(M[0], M[1]), dot(M[0], M[2]));\n    covB = vec3(dot(M[1], M[1]), dot(M[1], M[2]), dot(M[2], M[2]));\n}\n\nvec3 sRGBToLinear(vec3 c) {\n    return mix(\n        pow(c * 0.9478672986 + vec3(0.0521327014), vec3(2.4)),\n        c * 0.0773993808,\n        vec3(lessThanEqual(c, vec3(0.04045)))\n    );\n}\n\nvoid main(void) {\n    ivec2 splatUV = ivec2(int(splatOrder % uint(uTexWidth)), int(splatOrder / uint(uTexWidth)));\n    uvec4 tA = texelFetch(tTransformA, splatUV, 0);\n    vec4 tB = texelFetch(tTransformB, splatUV, 0);\n\n    vec3 modelCenter = uintBitsToFloat(tA.xyz);\n    vec3 packedRot = vec3(unpackHalf2x16(tA.w), tB.w);\n    // xyzw, with w recovered: quaternions are stored on the w >= 0 hemisphere.\n    vec4 srcRotation = vec4(packedRot, sqrt(max(0.0, 1.0 - dot(packedRot, packedRot))));\n    vec3 srcScale = tB.xyz;\n\n    // ---- Skin, then lift to world space --------------------------------\n    mat4 palette = getSplatPaletteTransform(splatUV);\n    vec3 modelDeformed = (palette * vec4(modelCenter, 1.0)).xyz;\n    vec3 worldCenter = (modelMatrix * vec4(modelDeformed, 1.0)).xyz;\n\n    vec4 worldRotation = quatMul(uModelRotation, srcRotation);\n    if (worldRotation.w < 0.0) worldRotation = -worldRotation;\n    vec3 worldScale = uModelScale * srcScale;\n\n    #ifdef USE_BONE_BLENDING\n    {\n        // The full world-space skinning rotation comes from modelMatrix * palette;\n        // the palette's own scale is deliberately dropped (rigid skinning).\n        mat3 lin = mat3(modelMatrix * palette);\n        vec3 s = vec3(length(lin[0]), length(lin[1]), length(lin[2]));\n        if (s.x > 1e-5 && s.y > 1e-5 && s.z > 1e-5) {\n            mat3 rot = mat3(lin[0] / s.x, lin[1] / s.y, lin[2] / s.z);\n            vec4 composed = normalize(quatMul(mat3ToQuatXYZW(rot), srcRotation));\n            if (composed.w < 0.0) composed = -composed;\n            worldRotation = composed;\n        }\n        #ifdef USE_NONRIGID_COV\n        // Bone-length scaling: the palette keeps its per-axis scale and the\n        // gaussian stretches with the bone.\n        worldScale *= s;\n        #endif\n    }\n    #endif\n\n    #ifdef USE_VARIANT_MASK\n    if (isSplatHiddenByVariantMask(splatUV)) {\n        gl_Position = discardVec;\n        return;\n    }\n    #endif\n\n    // ---- Project the centre --------------------------------------------\n    bool ortho = projectionMatrix[3][3] == 1.0;\n    vec4 centerView = viewMatrix * vec4(worldCenter, 1.0);\n    if (!ortho && centerView.z > 0.0) {\n        gl_Position = discardVec;\n        return;\n    }\n    vec4 centerProj = projectionMatrix * centerView;\n    centerProj.z = clamp(centerProj.z, -abs(centerProj.w), abs(centerProj.w));\n\n    // ---- Project the covariance to a screen-space ellipse ----------------\n    vec3 covA, covB;\n    computeCovariance(worldRotation.wxyz, worldScale, covA, covB);\n    mat3 Vrk = mat3(\n        covA.x, covA.y, covA.z,\n        covA.y, covB.x, covB.y,\n        covA.z, covB.y, covB.z\n    );\n\n    float focal = uViewport.x * projectionMatrix[0][0];\n    vec3 v = centerView.xyz;\n    vec3 vp = ortho ? vec3(0.0, 0.0, 1.0) : v;\n    float J1 = focal / vp.z;\n    vec2 J2 = -J1 / vp.z * vp.xy;\n    mat3 J = mat3(\n        J1, 0.0, J2.x,\n        0.0, J1, J2.y,\n        0.0, 0.0, 0.0\n    );\n    mat3 W = transpose(mat3(viewMatrix));\n    mat3 T = W * J;\n    mat3 cov = transpose(T) * Vrk * T;\n\n    #ifdef USE_ANTIALIAS\n    float detOrig = cov[0][0] * cov[1][1] - cov[0][1] * cov[0][1];\n    float detBlur = (cov[0][0] + 0.3) * (cov[1][1] + 0.3) - cov[0][1] * cov[0][1];\n    float aaFactor = sqrt(max(detOrig / detBlur, 0.0));\n    #endif\n\n    float diagonal1 = cov[0][0] + 0.3;\n    float offDiagonal = cov[0][1];\n    float diagonal2 = cov[1][1] + 0.3;\n    float mid = 0.5 * (diagonal1 + diagonal2);\n    float radius = length(vec2((diagonal1 - diagonal2) / 2.0, offDiagonal));\n    float lambda1 = mid + radius;\n    float lambda2 = max(mid - radius, 0.1);\n\n    float vmin = min(1024.0, min(uViewport.x, uViewport.y));\n    float l1 = 2.0 * min(sqrt(2.0 * lambda1), vmin);\n    float l2 = 2.0 * min(sqrt(2.0 * lambda2), vmin);\n    if (max(l1, l2) < uMinPixelSize) {\n        gl_Position = discardVec;\n        return;\n    }\n\n    // Cull splats whose ellipse lies wholly off-screen.\n    vec2 c = centerProj.ww / uViewport;\n    if (any(greaterThan(abs(centerProj.xy) - vec2(max(l1, l2)) * c, centerProj.ww))) {\n        gl_Position = discardVec;\n        return;\n    }\n\n    vec2 diagonalVector = normalize(vec2(offDiagonal, lambda1 - diagonal1));\n    vec2 v1 = l1 * diagonalVector;\n    vec2 v2 = l2 * vec2(diagonalVector.y, -diagonalVector.x);\n    vec2 cornerUV = position.xy;\n    vec2 offset = (cornerUV.x * v1 + cornerUV.y * v2) * c;\n\n    // ---- Colour -----------------------------------------------------------\n    vec4 clr = texelFetch(tColor, splatUV, 0);\n    #ifdef USE_ANTIALIAS\n    clr.a *= aaFactor;\n    #endif\n\n    clr.rgb *= computeLitFactor(worldCenter);\n    clr.rgb = mix(clr.rgb, uTint.rgb, clamp(uTint.a, 0.0, 1.0));\n    // Identity grade is a true no-op: skipping it keeps HDR splat colours unclamped.\n    if (uGrade.x != 1.0 || uGrade.y != 1.0) {\n        clr.rgb = (clr.rgb - 0.5) * uGrade.x + 0.5;\n        float luma = dot(clr.rgb, vec3(0.2126, 0.7152, 0.0722));\n        clr.rgb = mix(vec3(luma), clr.rgb, uGrade.y);\n        clr.rgb = clamp(clr.rgb, 0.0, 1.0);\n    }\n\n    // A splat whose peak alpha is already under the cutoff cannot put a\n    // fragment on screen: its own quad would be empty.\n    float alphaOverCutoff = clr.a * uAlphaCutoffScale;\n    if (alphaOverCutoff <= 1.0) {\n        gl_Position = discardVec;\n        return;\n    }\n\n    // Shrink the quad to where the gaussian is still above the cutoff: fewer\n    // fragments. At a cutoff of 1/255 the pixels are identical, since below\n    // that frag() discards anyway; above it, this is the trade the setting\n    // exists to make.\n    float clip = min(1.0, sqrt(log(alphaOverCutoff)) * 0.5);\n    offset *= clip;\n\n    gl_Position = centerProj + vec4(offset, 0.0, 0.0);\n    gaussianUV = cornerUV * clip;\n\n    vec3 rgb = max(clr.rgb, 0.0);\n    if (uOutputLinear > 0.5) rgb = sRGBToLinear(rgb);\n    gaussianColor = vec4(rgb, clr.a);\n}\n";
 export declare const SPLAT_FRAGMENT_GLSL = "\nprecision highp float;\n\nin mediump vec2 gaussianUV;\nin mediump vec4 gaussianColor;\n\nlayout(location = 0) out highp vec4 fragColor;\n\nconst float EXP4 = exp(-4.0);\nconst float INV_EXP4 = 1.0 / (1.0 - EXP4);\n\n// exp(-4x) rescaled to hit exactly 0 at the quad edge (x = 1).\nfloat normExp(float x) {\n    return (exp(x * -4.0) - EXP4) * INV_EXP4;\n}\n\nvoid main(void) {\n    mediump float A = dot(gaussianUV, gaussianUV);\n    if (A > 1.0) {\n        discard;\n    }\n    mediump float alpha = normExp(A) * gaussianColor.a;\n    if (alpha < 1.0 / 255.0) {\n        discard;\n    }\n    // Premultiplied.\n    fragColor = vec4(gaussianColor.rgb * alpha, alpha);\n}\n";

package/dist/types/splat/webgl/splat-mesh.d.ts

@@ -28,6 +28,8 @@ export declare class WebGLSplatImpl implements SplatRenderImpl {
     private _lastDx;
     private _lastDy;
     private _lastDz;
+    /** The importance ordering the worker already holds, if any. */
+    private _sentSubset;
     /**
      * @param asyncSort - Sort in a worker and keep drawing the previous order
      * meanwhile. Right for large static splats; wrong for skinned ones, whose

package/dist/types/splat/webgpu/splat-mesh.d.ts

@@ -67,5 +67,7 @@ export declare class WebGPUSplatImpl implements SplatRenderImpl {
      */
     private _build;
     beforeRender(renderer: any, camera: Camera): void;
+    /** Refresh this splat's uniforms and run whatever compute this frame needs. */
+    private _prepare;
     dispose(): void;
 }