@voluma/vlam 0.1.0 → 0.2.0

package/dist/splat-modifier-stack.d.ts

@@ -0,0 +1,38 @@
+/** Modifier-stack folding for the splat material graph. */
+import * as THREE from 'three/webgpu';
+import type { SplatModifier } from './splat-modifier';
+import type { Vec3Uniform } from './splat-mesh-material';
+/**
+ * Builds the per-splat {@link SplatContext}, folds the modifier stack
+ * over it in order, and returns the graph fragments the renderer applies.
+ * `null` fragments mean "untouched": with an empty stack every fragment
+ * is null and the caller emits exactly the unhooked graph.
+ *
+ * Modifiers are called once, here, at material build time - they are
+ * graph builders, not per-frame callbacks. Derived context fields
+ * (worldCenter, viewCenter, normal) are memoized lazily so only the
+ * modifiers that read them add their nodes to the graph.
+ */
+export declare function foldSplatModifierStack(modifierList: readonly SplatModifier[], localCameraPosition: Vec3Uniform, inputs: {
+    index: THREE.Node<'int'>;
+    localCenter: THREE.Node<'vec3'>;
+    /** Pre-placement pool position; defaults to {@link localCenter}. */
+    sourceCenter?: THREE.Node<'vec3'>;
+    /** Source-data-frame → mesh-local linear transform; defaults to identity. */
+    sourceToLocal?: THREE.Node<'mat3'>;
+    color: THREE.Node<'vec4'>;
+    makeNormal: () => THREE.Node<'vec3'>;
+    makeChannel: (name: string) => THREE.Node<'float'>;
+    /** Optional coordinate-space adapters for compute-time modifier folding. */
+    makeWorldCenter?: () => THREE.Node<'vec3'>;
+    makeViewCenter?: () => THREE.Node<'vec3'>;
+}): {
+    color: THREE.Node<'vec4'>;
+    offset: THREE.Node<'vec3'> | null;
+    scaleSquared: THREE.Node<'float'> | null;
+    rotation: THREE.Node<'mat3'> | null;
+    visible: THREE.Node<'bool'> | null;
+    isotropicCovarianceMix: THREE.Node<'float'> | null;
+    isotropicVarianceScale: THREE.Node<'float'> | null;
+    isotropicScreenRadiusPx: THREE.Node<'float'> | null;
+};

package/dist/splat-modifier.d.ts

@@ -0,0 +1,156 @@
+import type { Node } from 'three/webgpu';
+/**
+ * Per-splat context a {@link SplatModifier} reads, evaluated in the vertex
+ * stage. All fields are TSL nodes; see `docs/guide/effects-and-modifiers.md`.
+ */
+export interface SplatContext {
+    /** Pool splat index (stable identity for per-splat channels). */
+    readonly index: Node<'int'>;
+    /**
+     * Splat center in mesh-local space (pre-displacement).
+     *
+     * Inside a `SplatScene` this is the splat's **placed** position
+     * (`sourceMatrix · poolCenter`) - the placement is applied before the stack
+     * runs, so effects stay anchored to the scene rather than travelling with a
+     * moved source. Use {@link sourceCenter} for the pre-placement position.
+     */
+    readonly localCenter: Node<'vec3'>;
+    /**
+     * The splat's position in its own source's data frame. Identical to
+     * {@link localCenter} on a plain mesh; inside a `SplatScene` it is the
+     * **pre-placement** position, for effects that should travel *with* a moved
+     * source instead of staying put in the scene.
+     */
+    readonly sourceCenter: Node<'vec3'>;
+    /**
+     * Linear transform from the source data frame to mesh-local space. This is
+     * identity on a plain mesh; inside a {@link SplatScene} it is the linear part
+     * of the source placement. Apply it to source-frame displacement vectors.
+     * To express a source-frame rotation `R` as a mesh-local `rotation` output,
+     * conjugate it: `sourceToLocal · R · sourceToLocal.inverse()`.
+     */
+    readonly sourceToLocal: Node<'mat3'>;
+    /** `modelMatrix · localCenter` (world space). */
+    readonly worldCenter: Node<'vec3'>;
+    /** `modelViewMatrix · localCenter` (view space). */
+    readonly viewCenter: Node<'vec3'>;
+    /** Camera position in mesh-local space. */
+    readonly cameraLocal: Node<'vec3'>;
+    /** Color + opacity after SH - the stack's input color. */
+    readonly baseColor: Node<'vec4'>;
+    /** Approximate surface normal (least-variance axis of the splat's
+     * covariance), mesh-local, oriented toward the camera. Built lazily -
+     * only modifiers that read it pay for the eigen approximation. */
+    readonly normal: Node<'vec3'>;
+    /**
+     * Reads a per-splat channel by name (see `SplatMesh.defineChannel` /
+     * `writeChannel`). Float channels return their stored value; byte channels
+     * return the value normalized to `[0, 1]`. Reading an undefined channel is
+     * a build-time error (a missing mask is a bug, not a silent zero). The read
+     * is memoized per name, so referencing the same channel twice costs one
+     * texture fetch.
+     */
+    channel(name: string): Node<'float'>;
+    /** rgb + opacity. */
+    readonly color: Node<'vec4'>;
+    /** Local-space center displacement. */
+    readonly offset: Node<'vec3'>;
+    /** Uniform scale multiplier. */
+    readonly scale: Node<'float'>;
+    /** Rigid rotation. */
+    readonly rotation: Node<'mat3'>;
+    /** Visibility. */
+    readonly visible: Node<'bool'>;
+}
+/** The transform fields a modifier changes; omitted fields pass through. */
+export interface SplatOutputs {
+    color?: Node<'vec4'>;
+    offset?: Node<'vec3'>;
+    scale?: Node<'float'>;
+    rotation?: Node<'mat3'>;
+    visible?: Node<'bool'>;
+    /** Blend `Σ` toward σ²·I (0 = keep, 1 = full collapse). Screen λ equalized when > 0. */
+    isotropicCovarianceMix?: Node<'float'>;
+    /** Multiplier on max(n·Σ·n, ε); defaults to 0.35² when omitted. */
+    isotropicVarianceScale?: Node<'float'>;
+    /**
+     * Optional isotropic screen-space σ radius in pixels. When set (> 0), caps
+     * projected λ for zoom-stable dots. Omit for Spark-style world-space points
+     * (size grows mildly on zoom-in).
+     */
+    isotropicScreenRadiusPx?: Node<'float'>;
+}
+/**
+ * A splat effect hook. Reads the per-splat {@link SplatContext} and returns
+ * the transform fields it wants to change. Pure TSL, so it compiles to WGSL
+ * and GLSL and runs on both backends. Modifiers compose by folding over
+ * `SplatMesh.modifiers` in order - each sees the running result of the ones
+ * before it. Adding/removing/reordering modifiers recompiles the material;
+ * changing a modifier's own uniforms or storage buffers never does.
+ *
+ * Constraints (see `docs/guide/effects-and-modifiers.md`): covariance is pre-baked,
+ * so `scale` is uniform-only and `rotation` rigid-only; displaced splats
+ * keep their pre-displacement depth-sort order.
+ */
+export type SplatModifier = (context: SplatContext) => SplatOutputs;
+/** Anything with a `modifiers` list - {@link ModifierSlots.apply} target. */
+export interface ModifierStackTarget {
+    modifiers: readonly SplatModifier[];
+}
+/**
+ * Named, ordered modifier slots for hosts that stack several effects (reveal,
+ * SDF, lighting, fog, opacity, …) on one mesh. The slot **order is fixed at
+ * construction** - it defines the fold order of the compiled stack - while
+ * each slot's occupant can change at runtime.
+ *
+ * The rebuild vs uniform-update contract (see
+ * `docs/guide/effects-and-modifiers.md`, "Multi-slot stacks"):
+ *
+ *  - An **empty slot costs nothing**: it is omitted from the compacted list
+ *    entirely, never compiled as a passthrough. All slots empty ⇒ the mesh
+ *    gets an empty list ⇒ the unhooked graph (and the unified renderer's
+ *    zero-modifier gather fast path stays eligible - except for a `SplatScene`,
+ *    which `UnifiedSplatRenderer` does not accept as a source at all).
+ *  - {@link apply} hands the mesh a **compacted array whose reference is
+ *    stable** while the occupancy is unchanged, so re-applying after
+ *    uniform-only changes is a guaranteed no-op on the mesh's identity diff -
+ *    no material rebuild, no `graphRevision` bump.
+ *  - Filling, clearing, or replacing a slot with a *different* function is a
+ *    structural change: the next {@link apply} rebuilds the material once.
+ *    Setting a slot to the function it already holds is a no-op.
+ */
+export declare class ModifierSlots {
+    private readonly order;
+    private readonly occupants;
+    /** Compacted stack in slot order; rebuilt only on structural change so the
+     * array reference itself is stable across uniform-only frames. */
+    private compacted;
+    /** @param order Slot names, in fold order. Must be non-empty and unique. */
+    constructor(order: readonly string[]);
+    /** The declared slot names, in fold order. */
+    get slotNames(): readonly string[];
+    /**
+     * Fills or clears a slot (`null` clears). Returns `true` when the change is
+     * structural - i.e. the next {@link apply} will trigger a material rebuild -
+     * and `false` when it was a no-op (same function, or clearing an already
+     * empty slot). Unknown slot names throw: a typo must not silently drop an
+     * effect.
+     */
+    set(name: string, modifier: SplatModifier | null): boolean;
+    /** The slot's current occupant, or `null` when empty. */
+    get(name: string): SplatModifier | null;
+    /** Sugar for `set(name, null)`; returns whether the slot was occupied. */
+    clear(name: string): boolean;
+    /**
+     * The compacted stack: occupied slots only, in slot order. The reference is
+     * stable while occupancy is unchanged, so it is safe to assign every frame.
+     */
+    get modifiers(): readonly SplatModifier[];
+    /**
+     * Assigns the compacted stack to `target.modifiers` (a `SplatMesh` or
+     * anything with the same setter). The mesh's identity diff makes this free
+     * when nothing structural changed, so calling it after every `set` - or
+     * even every frame - is fine.
+     */
+    apply(target: ModifierStackTarget): void;
+}

package/dist/splat-partition.d.ts

@@ -0,0 +1,37 @@
+import type { SplatData } from './splat-data';
+import { type SelectionVolume } from './selection-volume';
+/**
+ * Splits a {@link SplatData} into the part inside a {@link SelectionVolume}
+ * and the rest, so the selected region can live as its own independently
+ * transformed (and therefore independently animated) object.
+ *
+ * Both halves keep the source's local frame - separation does not bake any
+ * transform. Register them as `SplatScene` or `UnifiedSplatRenderer` sources
+ * for one global sort while they are posed independently. Separate
+ * `SplatMesh` draw calls sort only within each mesh and can misblend where
+ * their Gaussian footprints overlap.
+ */
+export interface SplatPartition {
+    /** The splats whose centers passed the volume test. */
+    readonly inside: SplatData;
+    /** Everything else. */
+    readonly outside: SplatData;
+    /** Source indices of {@link inside}'s splats, ascending. */
+    readonly insideIndices: Uint32Array;
+}
+/**
+ * Partitions `data` by a selection.
+ *
+ * `selection` is either a volume (each splat center is tested) or an already
+ * computed ascending index list, e.g. from {@link selectInData} - passing the
+ * list avoids re-testing when a host previews a selection before separating.
+ *
+ * Per-splat arrays (positions, colors, covariances, SH) are gathered by index;
+ * a SOG SH palette is shared by reference between the halves (it is immutable
+ * and per-splat `labels` keep it valid for any subset). Streamed-only fields
+ * (`radTree`, `frontierParent`, `radShCodebook`) do not survive a partition -
+ * their index topology is meaningless on a subset - so they are dropped;
+ * partitioning is for fully resident data. An empty or all-inclusive selection
+ * is valid and yields a zero-count half.
+ */
+export declare function partitionSplatData(data: SplatData, selection: SelectionVolume | Uint32Array): SplatPartition;

package/dist/splat-query.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A lazily built uniform spatial grid over splat centers, for the CPU spatial
+ * queries `SplatMesh` exposes (M9). Pure array math - no THREE, no GPU - over
+ * the pool's CPU-side centers, so it is cheap to build and to test.
+ *
+ * The grid indexes a set of *pool indices* into a shared centers array (the
+ * pool's `backing.centers`, RGBA-strided: splat `p`'s center is
+ * `centers[p*4 + 0..2]`). Only the indices handed in are indexed, so a static
+ * mesh grids its whole scene and a streamed mesh grids exactly its resident
+ * splats. Everything is in the mesh's **local** space; the caller converts
+ * world queries in and results out.
+ */
+export declare class UniformGrid {
+    /** Populated-region minimum corner (local space). */
+    private readonly min;
+    /** Per-axis cell size (local units). */
+    private readonly cellSize;
+    /** Per-axis cell counts. */
+    private readonly dims;
+    /** CSR cell offsets: cell c owns `items[start[c] .. start[c+1])`. */
+    private readonly cellStart;
+    /** Pool indices, bucketed by cell. */
+    private readonly items;
+    /** Pool centers array this grid points into (RGBA stride 4). */
+    private readonly centers;
+    readonly count: number;
+    /**
+     * @param centers - The pool's CPU centers (stride 4: x,y,z,_ per splat).
+     * @param poolIndices - The pool indices to index (e.g. the active list).
+     * @param count - How many entries of `poolIndices` are valid.
+     */
+    constructor(centers: Float32Array, poolIndices: Uint32Array, count: number);
+    /** The cell index of pool splat `p`, clamped into range. */
+    private cellOf;
+    private axisCell;
+    /**
+     * Visits every indexed splat within `radius` (local units) of the local
+     * point, calling `visit(poolIndex, distanceSq)`. Cells are pruned by their
+     * axis span and each candidate is distance-filtered here, so the callback
+     * only ever sees splats truly within the radius.
+     */
+    forEachWithin(x: number, y: number, z: number, radius: number, visit: (poolIndex: number, distanceSq: number) => void): void;
+    /**
+     * The nearest indexed splat to the local point within `radius`, or null.
+     * Returns its pool index and squared local distance.
+     */
+    nearest(x: number, y: number, z: number, radius: number): {
+        poolIndex: number;
+        distSq: number;
+    } | null;
+}

package/dist/splat-scene.d.ts

@@ -0,0 +1,127 @@
+/**
+ * A scene of several independently-posed Gaussian splat clouds that all sort
+ * and blend as one.
+ *
+ * The problem it solves: two separate {@link SplatMesh} instances are two
+ * transparent draw calls, each depth-sorted only within itself, so where the
+ * clouds overlap one is painted wholesale in front of the other ("pasted over")
+ * - the same artifact PlayCanvas's unified rendering and Spark's accumulator
+ * exist to fix. `SplatScene` concatenates every cloud into **one pool** and
+ * runs **one global depth sort**, so splats from different clouds interleave
+ * correctly, from any angle.
+ *
+ * Each cloud ("source") keeps its own world transform, applied in the shader
+ * (never baked into the pool): the sorter transforms each splat's center to
+ * world space before measuring depth, and the material places each splat's
+ * center and covariance by its source's matrix. So {@link setSourceTransform}
+ * is a handful of uniform writes - a source can be dragged or animated every
+ * frame at full rate, at any splat count, with no data re-upload.
+ *
+ * The placement runs **before** the modifier stack, so a host effect sees each
+ * splat where it visually is: an SDF light shape spanning two sources paints
+ * one continuous shape, and a reveal sweeps them together. A modifier that
+ * wants to travel *with* a moved source reads `ctx.sourceCenter` instead of
+ * `ctx.localCenter`. See `docs/guide/effects-and-modifiers.md`.
+ *
+ * On WebGPU the world-depth sort runs in a compute pass; on the WebGL2
+ * fallback the worker applies the same source matrices on the CPU before
+ * sorting. Both backends therefore inter-sort sources correctly.
+ *
+ * Limitations, all inherited from the dynamic pool: sources may not carry
+ * palette (SOG `shN`) view-dependent color - per-file palettes cannot be merged
+ * - but DC color and per-splat (LCC) SH are fine; all sources share one
+ * antialias setting (from the scene options).
+ *
+ * Sources are **static**: {@link addSource} takes a fully-resident
+ * {@link SplatData} and copies it once into the pool, so a streaming
+ * {@link StreamedSplatMesh} (which swaps its resident LOD cut every frame)
+ * cannot be a source yet - keep a streamed main splat separate and unify only
+ * the static sources. Streamed sources are ROADMAP M15.4.
+ */
+import * as THREE from 'three/webgpu';
+import { SplatMesh, type SplatMeshOptions } from './splat-mesh';
+import type { SplatData } from './splat-data';
+import { type SplatOrientation } from './orientation';
+/** Construction options for a {@link SplatScene}. */
+export interface SplatSceneOptions extends SplatMeshOptions {
+    /** Total pool size in splats - must cover the sum of every source added. */
+    capacity: number;
+    /** Maximum number of sources (default {@link MAX_SOURCES}). */
+    maxSources?: number;
+}
+/** Per-source placement options. */
+export interface AddSourceOptions {
+    /**
+     * Y-up normalization for this source's data frame, like {@link SplatMesh}'s
+     * `orientation`. `'y-up'` (default) applies the format's stand-up correction
+     * before the placement matrix; `'source'` places the raw data frame.
+     */
+    orientation?: SplatOrientation;
+}
+/**
+ * One pool, one global sort, many independently-posed splat sources - see the
+ * module overview above for the artifact this exists to remove.
+ *
+ * @experimental May change in a minor release.
+ */
+export declare class SplatScene extends SplatMesh {
+    private readonly matrices;
+    private readonly maxSources;
+    /** Indexed by source id; holes are left by {@link removeSource}. */
+    private readonly sources;
+    private nextId;
+    constructor(options: SplatSceneOptions);
+    /** Number of live sources. */
+    get sourceCount(): number;
+    /**
+     * Adds a cloud at a world placement and returns its id (for
+     * {@link setSourceTransform} / {@link removeSource}). The data is copied into
+     * the shared pool in its own local frame; the placement is applied live in
+     * the shader.
+     *
+     * @throws if the pool cannot fit the cloud, or the source limit is reached.
+     */
+    addSource(data: SplatData, placement?: THREE.Matrix4, options?: AddSourceOptions): number;
+    /**
+     * Re-places a source. Cheap by design: only the shared matrix uniform and the
+     * sort bound change, so it is safe to call every frame while dragging.
+     *
+     * Bad-id semantics across the triad: this method **throws** (a write to a
+     * dead source is a caller bug that would otherwise vanish silently),
+     * {@link getSourceTransform} returns `undefined` (querying is how you ask
+     * whether a source is live), and {@link removeSource} returns `false`
+     * (removal is idempotent).
+     *
+     * @throws if `id` is not a live source.
+     */
+    setSourceTransform(id: number, placement: THREE.Matrix4): void;
+    /**
+     * The current world matrix of a source (a copy), or `undefined` if `id` is
+     * not a live source - see {@link setSourceTransform} for the bad-id triad.
+     */
+    getSourceTransform(id: number): THREE.Matrix4 | undefined;
+    /**
+     * Removes a source and frees its pool range. The id is not reused (later ids
+     * keep their matrix slots), so long-lived churn should prefer reusing a scene
+     * over unbounded add/remove.
+     *
+     * @returns `true` when a live source was removed, `false` when `id` was not
+     * live (idempotent - see {@link setSourceTransform} for the bad-id triad).
+     */
+    removeSource(id: number): boolean;
+    /** Recomputes a source's world matrix (placement · correction) and republishes it. */
+    private applyPlacement;
+    /** Sort depth is quantized over the world span of every source, not the pool's local box. */
+    protected refreshSortBounds(): void;
+    /**
+     * Mesh-local bounds spanning every source at its **current placement** -
+     * the pool's own box would be the union of the sources' data frames, which
+     * is not where any of them is drawn. Each source's data-frame box is
+     * transformed by its matrix, so a rotated source contributes the (standard,
+     * conservative) axis-aligned box of its rotated bounds.
+     *
+     * Hosts use this to place effects, so it has to agree with what
+     * `ctx.localCenter` reports; it tracks {@link setSourceTransform}.
+     */
+    computeSplatBounds(): THREE.Box3;
+}

package/dist/splat-sort-bounds.d.ts

@@ -0,0 +1,11 @@
+import type * as THREE from 'three/webgpu';
+/**
+ * The greatest view-space depth displacement of a local bounding sphere.
+ *
+ * View depth is the dot product of the local point and row 2 of `modelView`.
+ * A sphere with radius `r` therefore spans exactly `r · ||row2.xyz||` either
+ * side of its transformed center. Unlike a maximum-axis-scale estimate, this
+ * remains correct when a non-uniformly scaled ancestor and a rotated child
+ * compose into a shear.
+ */
+export declare function viewDepthRadius(modelView: THREE.Matrix4, radius: number): number;

package/dist/static-lod-splat-mesh.d.ts

@@ -0,0 +1,53 @@
+/** @role Bridge - Camera-aware rendering for worker-built static splat hierarchies. */
+import * as THREE from 'three/webgpu';
+import { type SplatLoadOptions } from './load-scene';
+import { SplatMesh, type SplatMeshOptions, type SplatUpdateOptions } from './splat-mesh';
+import type { StaticLodBuildProgress } from './static-lod';
+export interface StaticLodSplatMeshOptions extends SplatMeshOptions {
+    /** Initial selected-frontier budget. Defaults to the build ceiling. */
+    budget?: number;
+    /** Finest frontier retained by the hierarchy and immutable pool ceiling. */
+    maxBudget: number;
+    /** Reports the spatial ordering and hierarchy-build phase. */
+    onLodProgress?: (progress: StaticLodBuildProgress) => void;
+    /** Phase-aware progress spanning download, decode completion and LOD build. */
+    onAutoLodProgress?: (progress: StaticLodLoadProgress) => void;
+}
+export interface StaticLodLoadProgress {
+    readonly phase: 'download' | 'decode' | 'lod-build';
+    readonly completed: number;
+    readonly total: number;
+}
+export interface StaticLodSplatMeshLoadOptions extends StaticLodSplatMeshOptions, SplatLoadOptions {
+}
+/**
+ * Static splat mesh backed by a merged hierarchy and camera-aware frontier.
+ * The full hierarchy is uploaded once; camera/budget cuts only remap the
+ * active pool indices and never rewrite resident splat attributes.
+ */
+export declare class StaticLodSplatMesh extends SplatMesh {
+    private readonly worker;
+    private readonly ceilingValue;
+    private readonly contentCountValue;
+    private budgetValue;
+    private sequence;
+    private lastScheduleAt;
+    private selectionPending;
+    private readonly cameraLocal;
+    private readonly cameraForward;
+    private readonly inverseWorld;
+    private constructor();
+    /** Loads, decodes and builds a merged static hierarchy without blocking UI. */
+    static load(input: string | URL, options: StaticLodSplatMeshLoadOptions): Promise<StaticLodSplatMesh>;
+    get budget(): number;
+    get budgetCeiling(): number;
+    get maxBudget(): number;
+    get contentSplatCount(): number;
+    /** Changes the selected frontier budget within the immutable build ceiling. */
+    setBudget(value: number): number;
+    update(camera: THREE.PerspectiveCamera, renderer: THREE.WebGPURenderer, options?: SplatUpdateOptions): void;
+    /** Schedules a camera-aware cut when a unified renderer owns drawing/sorting. */
+    updateLod(camera: THREE.PerspectiveCamera): void;
+    dispose(): void;
+    private scheduleSelection;
+}