@viggle/splat-engine-three 0.0.0-stage → 0.1.1

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-mesh.d.ts

@@ -0,0 +1,71 @@
+import { Mesh } from 'three';
+import type { Camera } from 'three';
+import type { SplatEngine } from '../engine';
+import type { SplatBackend } from './backend';
+import type { Splat } from './splat';
+/**
+ * Make the WebGPU backend available to every {@link SplatMesh}. Called by the
+ * `@viggle/splat-engine-three/webgpu` entry point when it is imported; the
+ * default entry point leaves it out so WebGL applications never load
+ * `three/webgpu`.
+ *
+ * @internal
+ */
+export declare function registerWebGPUBackend(backend: SplatBackend): void;
+/**
+ * The object that draws one {@link Splat}: an ordinary `THREE.Mesh` in your
+ * scene graph, so `visible`, `renderOrder`, `layers` and parent transforms all
+ * work as they do for any mesh.
+ *
+ * It works with both `THREE.WebGLRenderer` and `WebGPURenderer`. Which one is
+ * not known until something renders it, so the renderer-specific geometry and
+ * material are attached the first time it is drawn; the mesh shows from the
+ * following frame.
+ *
+ * @group Splats
+ */
+export declare class SplatMesh extends Mesh {
+    /** Type flag, in the three.js manner. */
+    readonly isSplatMesh = true;
+    /** The splat this mesh draws: its data, tint, grade and render options. */
+    readonly splat: Splat;
+    private readonly _engine;
+    private readonly _asyncSort;
+    private _impl;
+    /**
+     * @param asyncSort - See {@link SplatBackend.createImpl}.
+     * @internal Construct a {@link Splat} instead; it creates its own mesh.
+     */
+    constructor(splat: Splat, engine: SplatEngine, asyncSort: boolean);
+    private _attach;
+    /** See {@link SplatRenderImpl.needsCpuCenters}. False until a renderer has drawn this mesh. */
+    get needsCpuCenters(): boolean;
+    /** True while the drawn order is stale or absent, including before the first draw. */
+    get sortPending(): boolean;
+    requestSort(): void;
+    syncDefines(): void;
+    syncBounds(): void;
+    syncBoneData(): void;
+    syncVariantGroups(): void;
+    onBeforeRender(renderer: unknown, _scene: unknown, camera: Camera): void;
+    /**
+     * A second mesh drawing the same splat data, at the same transform. The
+     * decoded data is shared; the GPU copy of it is not.
+     *
+     * Only for static splats. A mesh that belongs to a character is driven by
+     * that character's rig and cannot stand alone - clone the `SplatCharacter`.
+     */
+    clone(): this;
+    /**
+     * Splats are not pickable. The inherited implementation would test the ray
+     * against this mesh's own geometry, which is a single proxy quad at the
+     * local origin - every instance is positioned in the shader - and report
+     * hits that have nothing to do with where the splats are drawn.
+     */
+    raycast(): void;
+    /**
+     * Release every GPU resource behind this mesh - the splat's data textures as
+     * well as the renderer-specific buffers - and remove it from its parent.
+     */
+    dispose(): void;
+}

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

@@ -0,0 +1,252 @@
+import { Box3, DataTexture, Vector2, Vector4 } from 'three';
+import type { Frustum } from 'three';
+import type { SplatEngine } from '../engine';
+import type { Mat4 } from '../math';
+import type { SplatWeights } from '../types';
+import type { PackedSplats } from './packed-splats';
+import { SplatMesh } from './splat-mesh';
+import { TransformPalette } from './transform-palette';
+/** What a {@link Splat} is built from: packed gaussians, plus skinning data for characters. */
+export interface SplatSource {
+    packed: PackedSplats;
+    /** Present for skinned splats. Any `K` influences per splat; the top four are used. */
+    splatWeights?: SplatWeights;
+    /** Bone count of the rig the weights index into, when it differs from the armature's. */
+    sourceBoneCount?: number;
+}
+/** @group Splats */
+export interface SplatOptions {
+    /**
+     * Depth-sort in a worker instead of synchronously. Default: `true` for
+     * unskinned splats, `false` for skinned ones (whose order must track the pose).
+     */
+    asyncSort?: boolean;
+}
+/**
+ * Gaussian splat renderer.
+ *
+ * Owns the splat data textures, the bone index/weight textures used for
+ * skeletal deformation, the transform palette written to by the linked
+ * {@link Armature}, and the three.js mesh that draws it all. Skinning runs on
+ * the GPU when the splat has weights; unskinned splats (environments) take the
+ * same path with the identity transform.
+ *
+ * {@link Character.load} and {@link Environment.load} construct this
+ * internally. Direct construction is only needed for custom loading pipelines.
+ *
+ * @group Splats
+ */
+export declare class Splat {
+    readonly numSplats: number;
+    /** The packed gaussian data backing the textures. */
+    readonly packed: PackedSplats;
+    /** The three.js object that draws this splat. Parent it; do not replace it. */
+    readonly object3D: SplatMesh;
+    readonly colorTexture: DataTexture;
+    readonly transformATexture: DataTexture;
+    readonly transformBTexture: DataTexture;
+    /** Per-splat palette slot indices, four per splat. Rewritten when an armature binds. */
+    boneIndicesData?: Float32Array;
+    boneWeightsData?: Float32Array;
+    boneIndicesTexture?: DataTexture;
+    boneWeightsTexture?: DataTexture;
+    groupIdsTexture?: DataTexture;
+    variantMaskTexture?: DataTexture;
+    variantMask?: Float32Array;
+    groupIds?: Uint8Array;
+    /** Bumped whenever the group ids or the variant mask change. */
+    variantMaskVersion: number;
+    transformPalette: TransformPalette;
+    /** rgb tint colour, w tint amount. Shared with the material by reference. */
+    readonly tint: Vector4;
+    /** x contrast, y saturation. Shared with the material by reference. */
+    readonly grade: Vector2;
+    linkedArmature: any;
+    /** Skinning influences normalised to exactly four slots per splat. */
+    splatWeights?: SplatWeights;
+    sourceBoneCount?: number;
+    /**
+     * Splat centres in local space: the rest pose until the first skinning
+     * update, the skinned pose after.
+     *
+     * Only kept current when the renderer sorts on the CPU (WebGL). Under WebGPU
+     * this lags the pose; call {@link Splat.ensureCenters} before reading it.
+     */
+    centers: Float32Array;
+    /** Bumped whenever {@link Splat.centers} changes. */
+    centersVersion: number;
+    /**
+     * Local-space bounds used for culling and visibility tests. With CPU
+     * centres these track the pose exactly; without, they are the rest bounds
+     * padded generously enough to contain any pose.
+     */
+    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;
+    private _flatBones;
+    private _variantMaskEnabled;
+    private _nonRigidCov;
+    private _antiAlias;
+    private _destroyed;
+    private readonly _worldBounds;
+    private readonly _worldSphere;
+    private readonly _groundHist;
+    constructor(engine: SplatEngine, source: SplatSource, opts?: SplatOptions);
+    /**
+     * A new, independent splat over the same packed data, carrying this one's
+     * render options. For unskinned splats only.
+     * @internal
+     */
+    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;
+    /**
+     * Toggle the non-rigid covariance shader path. When on, the palette's
+     * per-axis scale stretches each gaussian's covariance; the palette must then
+     * actually carry that scale (see `SplatSkinning.covStretch`). Off is the
+     * rigid path, where palette scale is treated as unit. Switching recompiles
+     * the shader, so toggle it rarely.
+     */
+    setNonRigidCovariance(on: boolean): void;
+    /**
+     * Compensate each splat's opacity for the screen-space dilation applied to
+     * keep sub-pixel splats visible. Off by default; turn on for assets trained
+     * with anti-aliasing (e.g. Mip-Splatting).
+     */
+    get antiAlias(): boolean;
+    set antiAlias(on: boolean);
+    /**
+     * Blend every splat's colour toward `color` by `intensity` (0..1).
+     * `intensity = 0` restores the authored colour.
+     */
+    setTint(intensity: number, color?: {
+        r: number;
+        g: number;
+        b: number;
+    }): void;
+    /** Per-splat colour grade. `(1, 1)` is a true no-op. */
+    setGrade(contrast: number, saturation: number): void;
+    /**
+     * 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. */
+    setVariantMask(mask: ArrayLike<number>): void;
+    /** Whether the splat's world-space bounding sphere touches `frustum`. */
+    isInFrustum(frustum: Frustum): boolean;
+    /** World-space bounds of the splat in its current pose. */
+    getWorldAabb(out?: Box3): Box3;
+    /** World-space Y of the lowest corner of the current bounds. */
+    getWorldMinY(): number;
+    /**
+     * World-space Y of the splat's ground contact: the height below which only
+     * `quantile` of the splats lie. More robust than the bounds minimum, which a
+     * single stray gaussian can drag down.
+     */
+    getGroundWorldY(quantile?: number): number;
+    /**
+     * Flatten rest centres and influences into one interleaved buffer for the
+     * per-frame CPU skinning pass: `[x, y, z, w0, b0, w1, b1, w2, b2, w3, b3]`.
+     */
+    private _bakeInfluences;
+    /**
+     * Tell the splat its bone matrices changed. When the renderer sorts on the
+     * CPU the centres are re-skinned immediately; otherwise the work is deferred
+     * until something asks for them ({@link Splat.ensureCenters}).
+     */
+    updatePositions(boneTransforms: Mat4[]): void;
+    /** Bring {@link Splat.centers} up to date with the latest bone matrices. */
+    ensureCenters(): void;
+    /**
+     * Skin the splat centres on the CPU with the same matrices the GPU uses.
+     * This is the dominant per-character CPU cost, which is why it only runs
+     * when something needs the result.
+     */
+    private _skinCenters;
+    /** Force a re-sort on the next render. */
+    requestSort(): void;
+    /** True while an asynchronous sort is outstanding, i.e. the drawn order is stale or absent. */
+    get sortPending(): boolean;
+    /** Show or hide the splat without disturbing its bindings. */
+    setRenderingEnabled(enabled: boolean): void;
+    get renderingEnabled(): boolean;
+    get destroyed(): boolean;
+    /** Remove from the scene graph and release every GPU resource. */
+    destroy(): void;
+    /** @internal */
+    static _liveInstances: Set<Splat>;
+}

package/dist/types/splat/transform-palette.d.ts

@@ -0,0 +1,42 @@
+import { DataTexture } from 'three';
+import type { Mat4 } from '../math';
+/** Transforms per texture row. The shader's palette lookup hard-codes this. */
+export declare const PALETTE_ROW_SLOTS = 512;
+/**
+ * The per-splat table of skinning matrices, stored as a float texture: three
+ * RGBA texels per transform, {@link PALETTE_ROW_SLOTS} transforms per row.
+ *
+ * Slot 0 is reserved for identity and is what unmapped influences point at.
+ */
+declare class TransformPalette {
+    private _texture;
+    private _data;
+    private _dirty;
+    private _nextIdx;
+    private readonly _identity;
+    constructor(initialSize?: number);
+    /**
+     * The backing texture. Replaced when the palette grows, so read it each
+     * frame rather than holding on to it.
+     */
+    get texture(): DataTexture;
+    /**
+     * The backing array: twelve floats per slot, three row-major vec4 rows.
+     * Replaced when the palette grows, like {@link TransformPalette.texture}.
+     */
+    get data(): Float32Array;
+    /** Incremented every time {@link TransformPalette.upload} reports a change. */
+    version: number;
+    /** Slots the palette can hold before it has to grow. */
+    get capacity(): number;
+    private _realloc;
+    getTransform(index: number, transform: Mat4): void;
+    setTransform(index: number, transform: Mat4): void;
+    /** Flag the texture for re-upload if anything changed. Returns whether it did. */
+    upload(): boolean;
+    /** Reserve `num` consecutive slots and return the index of the first. */
+    alloc(num?: number): number;
+    free(num?: number): void;
+    dispose(): void;
+}
+export { TransformPalette };

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

@@ -0,0 +1,17 @@
+import type { Mesh } from 'three';
+import type { SplatEngine } from '../../engine';
+import type { SplatBackend, SplatRenderImpl } from '../backend';
+import type { Splat } from '../splat';
+/**
+ * Splat rendering for `THREE.WebGLRenderer`: GLSL ES 3.00, WebGL2.
+ *
+ * Splats are skinned and projected in the vertex stage. The depth sort runs on
+ * the CPU - synchronously for skinned characters, in a worker for static
+ * environments - which is what makes this backend's cost scale with the
+ * number of animated characters.
+ *
+ * @group Engine
+ */
+export declare class WebGLSplatBackend implements SplatBackend {
+    createImpl(host: Mesh, splat: Splat, engine: SplatEngine, asyncSort: boolean): SplatRenderImpl;
+}

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

@@ -0,0 +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// 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

@@ -0,0 +1,54 @@
+import { InstancedBufferGeometry, RawShaderMaterial } from 'three';
+import type { Camera, Mesh } from 'three';
+import type { SplatEngine } from '../../engine';
+import type { SplatRenderImpl } from '../backend';
+import type { Splat } from '../splat';
+/**
+ * How one {@link Splat} is drawn under `WebGLRenderer`: one instanced quad per
+ * gaussian, drawn back-to-front with premultiplied alpha.
+ *
+ * The instance attribute holds splat indices in draw order, so sorting only
+ * ever rewrites that one buffer; all splat data stays put in textures.
+ *
+ * @internal
+ */
+export declare class WebGLSplatImpl implements SplatRenderImpl {
+    readonly geometry: InstancedBufferGeometry;
+    readonly material: RawShaderMaterial;
+    /** The depth sort runs on the CPU, so it needs CPU-side centres. */
+    readonly needsCpuCenters = true;
+    private readonly _host;
+    private readonly _splat;
+    private readonly _engine;
+    private readonly _order;
+    private readonly _syncSorter;
+    private readonly _asyncSorter;
+    private _sortedVersion;
+    private _sortRequested;
+    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
+     * order would lag the pose.
+     */
+    constructor(host: Mesh, splat: Splat, engine: SplatEngine, asyncSort: boolean);
+    /** True while a worker sort is in flight (always false for synchronous sorting). */
+    get sortPending(): boolean;
+    /** Force a re-sort on the next render even if the view direction is unchanged. */
+    requestSort(): void;
+    /** Rebuild the shader variant after a feature toggle on the splat. */
+    syncDefines(): void;
+    /** The bone textures are the splat's own; flagging them is all there is to do. */
+    syncBoneData(): void;
+    /** Group ids live in the splat's own texture, which it flags itself. */
+    syncVariantGroups(): void;
+    /** Refresh the culling sphere from the splat's current local bounds. */
+    syncBounds(): void;
+    beforeRender(renderer: unknown, camera: Camera): void;
+    private _sortFor;
+    dispose(): void;
+}