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

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

@@ -0,0 +1,186 @@
+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 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;
+    /** Re-upload the bone index/weight textures after editing their data arrays. */
+    markBoneTexturesDirty(): 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}.
+     */
+    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// 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_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,52 @@
+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;
+    /**
+     * @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;
+}

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

@@ -0,0 +1,25 @@
+import type { SplatEngine } from '../../engine';
+import type { Mesh } from 'three/webgpu';
+import type { SplatBackend, SplatRenderImpl } from '../backend';
+import type { Splat } from '../splat';
+/**
+ * Splat rendering for `WebGPURenderer` (`three/webgpu`), running on WebGPU.
+ *
+ * Skinning, projection and the depth sort all run in compute shaders, so the
+ * CPU does no per-splat work: adding an animated character costs a pose
+ * evaluation and a palette upload, not a pass over its splats.
+ *
+ * Importing `@viggle/splat-engine-three/webgpu` registers this backend, and
+ * splats then use it whenever a `WebGPURenderer` draws them; there is nothing
+ * to construct or pass.
+ *
+ * Requires the renderer's WebGPU backend. `WebGPURenderer`'s WebGL2 fallback
+ * (`forceWebGL`, or a browser without WebGPU) has no compute shaders; use
+ * `THREE.WebGLRenderer` there instead.
+ *
+ * @group Engine
+ */
+export declare class WebGPUSplatBackend implements SplatBackend {
+    private readonly _lighting;
+    createImpl(host: Mesh, splat: Splat, engine: SplatEngine): SplatRenderImpl;
+}

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

@@ -0,0 +1,34 @@
+import type { SplatEngine } from '../../engine';
+type Node = any;
+/** Point lights the WebGPU backend evaluates per splat. Extra lights are ignored. */
+export declare const MAX_POINT_LIGHTS = 16;
+/**
+ * The engine's lighting registry as TSL uniforms, shared by every WebGPU splat
+ * drawable of one engine.
+ *
+ * @internal
+ */
+export declare class WebGPULighting {
+    private readonly _engine;
+    private readonly _sunColor;
+    private readonly _sunIntensity;
+    private readonly _ambient;
+    private readonly _pointCount;
+    private readonly _pointPosRange;
+    private readonly _pointColor;
+    private readonly _pointPosRangeNode;
+    private readonly _pointColorNode;
+    private _version;
+    constructor(engine: SplatEngine);
+    /**
+     * Refresh the uniforms from the engine's lighting registry.
+     * @returns A number that changes whenever the lighting does.
+     */
+    sync(): number;
+    /**
+     * The multiplier applied to a splat's baked colour: ambient, plus sun, plus
+     * range-attenuated point lights. With no lights it is exactly 1.
+     */
+    litFactor(worldCenter: Node): Node;
+}
+export {};

package/dist/types/splat/webgpu/radix-sort.d.ts

@@ -0,0 +1,46 @@
+type Node = any;
+/** Sort keys are 16 bits, sorted as two 8-bit digits. */
+export declare const SORT_KEY_BITS = 16;
+/**
+ * A stable least-significant-digit radix sort over 16-bit keys, in compute.
+ *
+ * Stability is the point. The obvious GPU counting sort - histogram, prefix
+ * sum, then every element claiming its slot with an atomic add - leaves the
+ * order inside a bucket to whichever thread wins the race, and that changes
+ * from frame to frame. For splats sharing a depth bucket (a surface seen
+ * face-on is full of them) the result is visible shimmer on a perfectly still
+ * frame. Here ties always resolve in element-index order, exactly as a CPU
+ * counting sort does, so a still frame is bit-stable.
+ *
+ * Each digit takes three steps:
+ *
+ *   histogram  count digits per block of {@link BLOCK} consecutive elements
+ *              (atomic adds; counts do not depend on thread order).
+ *   prefix     for each digit, in parallel, walk the blocks turning counts
+ *              into starting offsets; then one thread turns the 256 digit
+ *              totals into digit bases.
+ *   scatter    one invocation per block walks its elements in order, placing
+ *              each at its digit's running offset.
+ *
+ * The first digit's histogram is folded into the caller's own per-element
+ * pass through {@link GpuRadixSort.countFirstDigit}, saving a dispatch.
+ */
+export declare class GpuRadixSort {
+    readonly count: number;
+    /** Write each element's key here (`uint`, low 16 bits significant) before {@link GpuRadixSort.sortNodes} run. */
+    readonly keysWrite: Node;
+    /** Element indices in ascending key order, valid after {@link GpuRadixSort.sortNodes} have run. */
+    readonly orderRead: Node;
+    /** Run before the pass that writes keys: clears both digit histograms. */
+    readonly resetNode: Node;
+    /** Run, in order, after the pass that writes keys. */
+    readonly sortNodes: Node[];
+    private readonly _firstHistogram;
+    constructor(count: number);
+    /**
+     * Count `key`'s low digit for the element at `index`. Call from inside the
+     * compute pass that writes the keys.
+     */
+    countFirstDigit(index: Node, key: Node): void;
+}
+export {};

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

@@ -0,0 +1,71 @@
+import { InstancedBufferGeometry, NodeMaterial } from 'three/webgpu';
+import type { Camera, Mesh } from 'three/webgpu';
+import type { SplatRenderImpl } from '../backend';
+import type { Splat } from '../splat';
+import type { WebGPULighting } from './lighting';
+/** Groups a variant mask can address. The mask travels as a uniform array of this size. */
+export declare const MAX_VARIANT_GROUPS = 64;
+/**
+ * How one {@link Splat} is drawn under `WebGPURenderer`.
+ *
+ * Everything per-splat happens in compute, once per splat per frame:
+ *
+ *   1. project  - skin, lift to world space, project the covariance to a
+ *                 screen-space ellipse, shade; write the result to a work
+ *                 buffer along with a 16-bit depth key.
+ *   2. sort     - a stable radix sort of the keys ({@link GpuRadixSort}),
+ *                 giving splat indices in back-to-front order.
+ *
+ * Buffers are interleaved so no stage binds more than seven storage buffers:
+ * WebGPU only guarantees eight per stage, and some browsers stop there.
+ *
+ * The vertex stage then only expands each work-buffer entry into a quad. No
+ * per-splat work happens on the CPU, which is what lets this backend carry
+ * many animated characters: the WebGL backend re-skins every centre on the
+ * main thread each frame just to feed its sort.
+ *
+ * @internal
+ */
+export declare class WebGPUSplatImpl implements SplatRenderImpl {
+    readonly geometry: InstancedBufferGeometry;
+    readonly material: NodeMaterial;
+    /** Skinning for the sort happens in compute; the CPU never touches a splat. */
+    readonly needsCpuCenters = false;
+    private readonly _host;
+    private readonly _splat;
+    private readonly _lighting;
+    private _paletteArray;
+    private _paletteAttribute;
+    private _paletteVersion;
+    private _boneAttribute;
+    private _groupAttribute;
+    private readonly _variantMask;
+    /** [sort reset, project] - everything that depends on the camera or the pose. */
+    private _projectNodes;
+    /** The sort proper - needed only when the depth ORDER may have changed. */
+    private _sortNodes;
+    private readonly _lastInputs;
+    private readonly _inputs;
+    private readonly _lastSortDirection;
+    private _buildId;
+    private _sortedBuildId;
+    private _allNodes;
+    private readonly _u;
+    constructor(host: Mesh, splat: Splat, lighting: WebGPULighting);
+    /** The sort runs in the same frame as the draw; the order is never stale. */
+    get sortPending(): boolean;
+    /** Force the next frame to re-project and re-sort even if nothing appears to have changed. */
+    requestSort(): void;
+    syncDefines(): void;
+    syncBounds(): void;
+    syncBoneData(): void;
+    syncVariantGroups(): void;
+    /**
+     * (Re)create the storage buffers, compute nodes and material nodes. Runs at
+     * construction, and again when a feature toggle changes the shader or the
+     * palette outgrows its buffer.
+     */
+    private _build;
+    beforeRender(renderer: any, camera: Camera): void;
+    dispose(): void;
+}

package/dist/types/three/loaders.d.ts

@@ -0,0 +1,77 @@
+import { Loader } from 'three';
+import type { LoadingManager } from 'three';
+import { Animation } from '../animation';
+import { SplatEngine } from '../engine';
+import type { SplatMesh } from '../splat/splat-mesh';
+import { SplatCharacter } from './splat-character';
+/**
+ * Shared plumbing: fetch bytes the three.js way - through a `FileLoader`, so
+ * the `LoadingManager`, base path, request headers and credentials mode all
+ * apply - then hand them to an asynchronous `parseAsync`.
+ */
+declare abstract class SplatLoaderBase<T> extends Loader<T> {
+    /**
+     * The engine loaded objects belong to: the skeleton library, clip registry
+     * and lights they share. Leave unset to use {@link SplatEngine.shared}.
+     */
+    engine: SplatEngine | null;
+    constructor(manager?: LoadingManager);
+    setEngine(engine: SplatEngine | null): this;
+    /** Decode bytes already in memory. `name` labels the result; for a loaded file it is the file's base name. */
+    abstract parseAsync(data: ArrayBuffer, name?: string): Promise<T>;
+    load(url: string, onLoad: (result: T) => void, onProgress?: (event: ProgressEvent) => void, onError?: (error: unknown) => void): void;
+    protected get resolvedEngine(): SplatEngine;
+}
+/**
+ * Loads a `.vsplat` character bundle (or a legacy `.bin` one - the container
+ * is recognised from the file's own bytes) as a {@link SplatCharacter}.
+ *
+ * ```ts
+ * const character = await new VSplatLoader().loadAsync('/assets/hero.vsplat');
+ * scene.add(character);
+ * ```
+ *
+ * @group Loaders
+ */
+export declare class VSplatLoader extends SplatLoaderBase<SplatCharacter> {
+    parseAsync(data: ArrayBuffer, name?: string): Promise<SplatCharacter>;
+}
+/**
+ * Loads an animation clip for {@link SplatCharacter.play}: a MetaHuman-rig
+ * `.glb`, or an `.anim` file.
+ *
+ * ```ts
+ * const run = await new SplatClipLoader().loadAsync('/assets/run.glb');
+ * character.play(run);
+ * ```
+ *
+ * A clip is not tied to one character; play the same one on as many as you like.
+ *
+ * @group Loaders
+ */
+export declare class SplatClipLoader extends SplatLoaderBase<Animation> {
+    /** For a `.glb` holding several animations, the one to take. Default: the first. */
+    animationName: string | undefined;
+    parseAsync(data: ArrayBuffer, name?: string): Promise<Animation>;
+}
+/**
+ * Loads an uncompressed 3D Gaussian Splatting `.ply` as a static
+ * {@link SplatMesh} - an environment, a prop, a scanned object.
+ *
+ * ```ts
+ * const room = await new SplatPLYLoader().loadAsync('/assets/room.ply');
+ * room.rotation.x = Math.PI; // many captures are authored Y-down
+ * scene.add(room);
+ * ```
+ *
+ * The mesh is given `renderOrder = -1` so it draws before characters, which
+ * then always composite on top of it. Splats do not write depth, so without
+ * that a large environment whose origin happens to be nearer the camera would
+ * be drawn over a character standing in it.
+ *
+ * @group Loaders
+ */
+export declare class SplatPLYLoader extends SplatLoaderBase<SplatMesh> {
+    parseAsync(data: ArrayBuffer, name?: string): Promise<SplatMesh>;
+}
+export {};