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

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,73 @@
+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;
+    /** Refresh this splat's uniforms and run whatever compute this frame needs. */
+    private _prepare;
+    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 {};

package/dist/types/three/splat-character.d.ts

@@ -0,0 +1,220 @@
+import { Matrix4, Object3D, Vector3 } from 'three';
+import type { ColorRepresentation, Object3DEventMap } from 'three';
+import type { Animation } from '../animation';
+import type { Armature } from '../armature';
+import { Character } from '../character';
+import type { SplatEngine } from '../engine';
+import type { CharacterBundle } from '../loader/character/load';
+import type { BodyRegion, BoneMask } from '../skeletal/bone-mask';
+import type { Splat } from '../splat/splat';
+/**
+ * What a clip's horizontal travel does to the character.
+ *
+ * - `'off'` - the clip plays in place.
+ * - `'apply'` - the character's body moves with the clip, beneath
+ *   {@link SplatCharacter.position}, which stays where you put it.
+ * - `'extract'` - the clip plays in place and its travel is handed to you by
+ *   {@link SplatCharacter.consumeRootMotion}, to feed a controller or physics.
+ *
+ * @group Characters & Animation
+ */
+export type SplatRootMotion = 'off' | 'apply' | 'extract';
+/** @group Characters & Animation */
+export interface SplatPlayOptions {
+    /** Repeat when the clip ends. Default `true`. */
+    loop?: boolean;
+}
+/** @group Characters & Animation */
+export interface SplatCrossFadeOptions extends SplatPlayOptions {
+    /** Start the new clip at the same fraction of its length the old one had reached. Default `false`. */
+    preserveTime?: boolean;
+}
+/** @group Characters & Animation */
+export interface SplatLayerOptions {
+    /** The bones the layer drives, as a named region. Give this or `mask`. */
+    region?: BodyRegion;
+    /** The bones the layer drives, as an explicit mask. Give this or `region`. */
+    mask?: BoneMask;
+    /** Repeat when the clip ends. Default `true`. */
+    loop?: boolean;
+    /** Seconds to blend the layer in. Default `0`. */
+    fadeDuration?: number;
+    /** How strongly the layer overrides the base pose, 0..1. Default `1`. */
+    weight?: number;
+}
+/**
+ * Events a {@link SplatCharacter} dispatches, alongside the usual `Object3D` ones.
+ * @group Characters & Animation
+ */
+export interface SplatCharacterEventMap extends Object3DEventMap {
+    /** A non-looping clip reached its last frame. */
+    finished: {
+        clip: Animation;
+    };
+    /** A looping clip wrapped around to its start. */
+    loop: {
+        clip: Animation;
+    };
+    /** An event authored into the clip was crossed. */
+    clipevent: {
+        clip: Animation | null;
+        name: string;
+        frame: number;
+        payload?: unknown;
+    };
+}
+/**
+ * A gaussian-splat character, as a three.js object.
+ *
+ * Add it to a scene, move it with `position` / `rotation` / `scale`, and call
+ * {@link SplatCharacter.update} once per frame - the role `AnimationMixer.update`
+ * plays for a skinned mesh. Create one with {@link VSplatLoader}.
+ *
+ * ```ts
+ * const character = await new VSplatLoader().loadAsync('/assets/hero.vsplat');
+ * scene.add(character);
+ * character.position.set(1, 0, 0);
+ *
+ * const run = await new SplatClipLoader().loadAsync('/assets/run.glb');
+ * character.play(run);
+ *
+ * renderer.setAnimationLoop(() => {
+ *   character.update(clock.getDelta());
+ *   renderer.render(scene, camera);
+ * });
+ * ```
+ *
+ * `position` is the model origin. A character in its rest pose stands on it;
+ * how closely a clip keeps the feet on it depends on the clip.
+ *
+ * Animation is driven by this class rather than by `AnimationMixer`: a splat
+ * character has no `Bone` hierarchy for a mixer to write to. Clips are
+ * {@link Animation} objects from {@link SplatClipLoader}.
+ *
+ * @group Characters & Animation
+ */
+export declare class SplatCharacter extends Object3D<SplatCharacterEventMap> {
+    /** Type flag, in the three.js manner. */
+    readonly isSplatCharacter = true;
+    readonly type: string;
+    /**
+     * The engine-level character this object wraps. Everything not surfaced
+     * here - multi-level LOD, variant splats, animation LOD - is reachable
+     * through it.
+     */
+    readonly character: Character;
+    private readonly _engine;
+    private readonly _bundles;
+    private _clip;
+    private _loop;
+    private _finishedSent;
+    private _rootMotion;
+    /** Optional world-space floor height. When set, the lowest visible splats
+     * are aligned to it after each pose. Useful for dances with no airborne
+     * phase; leave null for clips with intentional jumps or flight. */
+    groundLockY: number | null;
+    private _disposed;
+    /**
+     * @param bundles - Decoded character bundles, finest level of detail first.
+     * They are read, never modified, so clones share them.
+     * @internal Use {@link VSplatLoader}.
+     */
+    constructor(engine: SplatEngine, bundles: CharacterBundle[], name?: string);
+    /** The rig: bone names, bone matrices, bone-length scaling. */
+    get armature(): Armature;
+    /** The splats that draw this character, one per level of detail. */
+    get splats(): readonly Splat[];
+    /**
+     * Advance the animation by `delta` seconds and pose the splats. Call once
+     * per frame, before rendering.
+     */
+    update(delta: number): void;
+    /** Start `clip` from its first frame, cutting from whatever was playing. */
+    play(clip: Animation, options?: SplatPlayOptions): this;
+    /** Blend from the current pose into `clip` over `duration` seconds. */
+    crossFadeTo(clip: Animation, duration?: number, options?: SplatCrossFadeOptions): this;
+    /** Stop playback and return to the rest pose, blending over `fadeDuration` seconds. */
+    stop(fadeDuration?: number): this;
+    /**
+     * Play `clip` on a named layer that overrides part of the body - an upper
+     * body wave over a full-body run, say. Calling it again with the same layer
+     * name replaces what that layer plays.
+     */
+    playLayer(layer: string, clip: Animation, options: SplatLayerOptions): this;
+    setLayerWeight(layer: string, weight: number): this;
+    stopLayer(layer: string, fadeDuration?: number): this;
+    /** The clip the base track is playing, or `null`. */
+    get clip(): Animation | null;
+    get isPlaying(): boolean;
+    get paused(): boolean;
+    set paused(value: boolean);
+    /** Playback speed multiplier. `1` is the authored speed. */
+    get timeScale(): number;
+    set timeScale(value: number);
+    /** Position in the current clip, in seconds. */
+    get time(): number;
+    set time(seconds: number);
+    /** Length of the current clip in seconds, or `0` when nothing is playing. */
+    get duration(): number;
+    /** See {@link SplatRootMotion}. Applies to the current clip and every later one. */
+    get rootMotion(): SplatRootMotion;
+    set rootMotion(mode: SplatRootMotion);
+    /**
+     * The clip's horizontal travel since the last call, in this object's local
+     * space. Non-zero only in `'extract'` mode. `y` is always `0`.
+     */
+    consumeRootMotion(target?: Vector3): Vector3;
+    /**
+     * Blend the character's colour toward `color` by `amount` (0..1) - a hit
+     * flash, a selection highlight. `amount = 0` restores the authored colour.
+     */
+    setTint(color: ColorRepresentation, amount?: number): this;
+    /** Contrast and saturation multipliers for the character's colour. `(1, 1)` is unchanged. */
+    setGrade(contrast: number, saturation: number): this;
+    /**
+     * Draw fewer of this character's splats as it gets further away.
+     *
+     * `nearFraction` of them at `nearDist` and closer, `farFraction` at
+     * `farDist` and beyond, interpolated in between. Which splats those are is
+     * decided by importance within each 4 cm cell, so the character thins evenly
+     * rather than losing a region of itself. See {@link Character.setSplatCountLod}.
+     *
+     * Needs a camera on the engine to measure distance from - the same one the
+     * other distance throttles use:
+     *
+     * ```ts
+     * SplatEngine.shared.camera = camera;
+     * character.setSplatCountLod({ nearDist: 4, farDist: 16, farFraction: 0.25 });
+     * ```
+     */
+    setSplatCountLod(opts: {
+        nearDist: number;
+        farDist: number;
+        nearFraction?: number;
+        farFraction?: number;
+    }): this;
+    /** Stop thinning: every splat is drawn again, at any distance. */
+    disableSplatCountLod(): this;
+    /** Bone names, in rig order. */
+    get boneNames(): readonly string[];
+    /**
+     * World matrix of a bone as of the last {@link SplatCharacter.update} - for
+     * attaching a prop to a hand, or aiming a camera at a head.
+     *
+     * @returns `target`, or `null` when the rig has no bone of that name.
+     */
+    getBoneWorldMatrix(name: string, target?: Matrix4): Matrix4 | null;
+    /**
+     * A second character from the same decoded data, at the same transform. The
+     * copy starts in the rest pose with nothing playing; it does not share this
+     * one's animation state.
+     */
+    clone(): this;
+    /**
+     * Release every GPU resource the character holds. The object stays in the
+     * scene graph, empty; remove it yourself if you no longer want it there.
+     */
+    dispose(): void;
+    private _keyFor;
+    private _started;
+}

package/dist/types/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared data shapes used across the loader, skeletal and splat layers.
+ */
+/**
+ * Rig description handed to {@link Armature}.
+ *
+ * The `stdMale*` field names are inherited from the skeleton library and mean
+ * "the rest pose this armature binds to", whichever rig that is.
+ */
+export interface ArmatureData {
+    numBones: number;
+    /** Flat `[x,y,z] * numBones` rest translations carried by the character bundle. */
+    joints?: Float32Array;
+    /** Whether the bundle's geometric corrections are baked into its splats and joints. */
+    corrected?: boolean;
+    /** Whether `joints` is this character's own vetted rest pose. */
+    restIsPerCharacter?: boolean;
+    skeleton?: Int32Array;
+    stdMaleRestTranslations?: Float32Array;
+    stdMaleRestRotations?: Float32Array;
+    stdMaleParents?: Int32Array;
+}
+/** Per-splat skinning influences, `K` slots per splat. */
+export interface SplatWeights {
+    /** `numSplats * K` rig bone indices. */
+    indices: Uint16Array;
+    /** `numSplats * K` weights, matching `indices`. */
+    weights: Float32Array;
+}
+export type { SkeletonLibrary } from './loader/skeleton';

package/dist/types/webgpu.d.ts

@@ -0,0 +1,5 @@
+import { WebGPUSplatBackend } from './splat/webgpu/backend';
+export * from './index';
+export { WebGPUSplatBackend };
+export { MAX_POINT_LIGHTS } from './splat/webgpu/lighting';
+export { MAX_VARIANT_GROUPS } from './splat/webgpu/splat-mesh';