@voluma/vlam 0.1.0 → 0.2.0

package/dist/splat-mesh-material.d.ts

@@ -0,0 +1,255 @@
+/**
+ * The TSL material graph behind `SplatMesh`.
+ *
+ * One graph serves both of the mesh's materials: `display` writes premultiplied
+ * color, `pick` encodes linear view depth. They must stay one builder - a pick
+ * that disagreed with the display about projection, covariance or visibility
+ * would return hits for splats the viewer cannot see.
+ *
+ * Everything here runs once, at material build time, and reads only what the
+ * mesh hands it, so these are free functions rather than methods. Note the two
+ * inputs that must be passed live rather than copied: the uniform *node
+ * instances* (display and pick share them, so a frame updates both at once) and
+ * the channels map (a rebuild after `defineChannel` has to see the new entry).
+ *
+ * Internal. Nothing here is exported from `index.ts`.
+ */
+import * as THREE from 'three/webgpu';
+import { uniformArray } from 'three/tsl';
+import type { SplatModifier } from './splat-modifier';
+import { foldSplatModifierStack } from './splat-modifier-stack';
+import type { SplatPerformanceProfile } from './splat-mesh';
+/** Default variance scale for isotropic point mode: (0.35 × min-axis)². */
+export declare const DEFAULT_ISOTROPIC_VARIANCE_SCALE: number;
+/** Default isotropic screen-space sigma radius (px); only used when a modifier opts in. */
+export declare const DEFAULT_ISOTROPIC_SCREEN_RADIUS_PX = 1;
+/**
+ * Blends `Σ` toward σ²·I where σ² = λ_min(Σ) · varianceScale. Spark point
+ * mode sets every scale axis to min(scale)·0.35; since λ_min(Σ) = min(scale)²,
+ * that is exactly σ² = (min·0.35)².
+ *
+ * λ_min is estimated without `Σ⁻¹` (near-singular on flat Gaussians, which
+ * made n·Σ·n blow up into large blobs): take the min of the three axis
+ * Rayleigh quotients and the Rayleigh along the longest row-cross of Σ (a
+ * stable thin-axis hint when Σ is rank-deficient). The `normal` argument is
+ * kept for call-site compatibility and ignored.
+ */
+export declare function applyIsotropicCovarianceOverride(covariance: THREE.Node<'mat3'>, _normal: THREE.Node<'vec3'>, mixFactor: THREE.Node<'float'>, varianceScale: THREE.Node<'float'>): THREE.Node<'mat3'>;
+/** Sets both screen-space eigenvalues to min(λ1, λ2) for a circular footprint. */
+export declare function equalizeProjectedEigenvalues(lambda1: THREE.Node<'float'>, lambda2: THREE.Node<'float'>, mixFactor: THREE.Node<'float'>): {
+    lambda1: THREE.Node<'float'>;
+    lambda2: THREE.Node<'float'>;
+};
+/**
+ * Caps isotropic λ to a screen-space sigma radius while blending by mix.
+ * `screenRadiusPx ≤ 0` is a no-op (opt-in only; 0 must not shrink λ toward zero).
+ */
+export declare function capProjectedEigenvaluesToScreenRadius(lambda1: THREE.Node<'float'>, lambda2: THREE.Node<'float'>, mixFactor: THREE.Node<'float'>, screenRadiusPx: THREE.Node<'float'>, maxStdDev: THREE.Node<'float'>): {
+    lambda1: THREE.Node<'float'>;
+    lambda2: THREE.Node<'float'>;
+};
+/** The pool data textures a graph samples per splat. */
+export interface SplatMaterialTextures {
+    centersTexture: THREE.DataTexture;
+    colorsTexture: THREE.DataTexture;
+    covarianceATexture: THREE.DataTexture;
+    covarianceBTexture: THREE.DataTexture;
+}
+/** Narrow a TSL expression to the typed {@link THREE.Node} our hook contract
+ * expects. Identity at runtime - satisfies TypeScript only. */
+export declare function asNode<T extends string>(node: unknown): THREE.Node<T>;
+/** A `vec3` uniform, named so its type can be referred to in field decls. */
+export declare function vec3Uniform(): THREE.UniformNode<"vec3", THREE.Vector3>;
+export type Vec3Uniform = ReturnType<typeof vec3Uniform>;
+declare function vec2Uniform(): THREE.UniformNode<"vec2", THREE.Vector2>;
+/** A `vec2` uniform (focal, viewport). */
+export type Vec2Uniform = ReturnType<typeof vec2Uniform>;
+declare function floatUniform(): THREE.UniformNode<"float", number>;
+/** A scalar uniform (pick thresholds and planes). */
+export type FloatUniform = ReturnType<typeof floatUniform>;
+/**
+ * How the material reads a splat's higher-order SH coefficients. The two
+ * sources differ only in where a coefficient comes from - the band
+ * accumulation and view-direction math are shared:
+ *
+ *  - `palette`: SOG/`.lcc2` shN. Coefficients live in a per-file codebook and
+ *    each splat stores a label; only a static mesh can use it, because two
+ *    files' palettes cannot be merged into one pool.
+ *  - `packed`: LCC `Quality`, `.rad`, etc. Each splat carries its own coefficients as packed
+ *    words in pool-shaped textures, so appended ranges keep their SH.
+ */
+export type SplatShInputs = {
+    mode: 'palette';
+    bands: number;
+    paletteTexture: THREE.DataTexture;
+} | {
+    mode: 'packed';
+    bands: 1 | 2 | 3;
+    textures: readonly THREE.DataTexture[];
+    range: {
+        min: Vec3Uniform;
+        max: Vec3Uniform;
+    };
+};
+/**
+ * Per-source placement inputs for a unified pool ({@link SplatScene}): the
+ * splat's source id plus the shared array of source matrices. Drives two things
+ * at once - the splat's mesh-local position (`M · poolCenter`, applied before
+ * the modifier stack) and the frame view-dependent SH is evaluated in.
+ */
+export interface SplatSourcePlacement {
+    /** Pool-aligned source id channel. */
+    sourceIdTexture: THREE.DataTexture;
+    /** Four column vectors per source world matrix. */
+    columns: ReturnType<typeof uniformArray>;
+}
+/**
+ * The `mat4 · (poolCenter, 1)` placed center for source id `s`, plus the linear
+ * 3×3 part as a `mat3`, read from the shared column array (three.js
+ * `Matrix4.elements` are column-major, so a column maps to
+ * `elements[k*4 .. k*4+3]`).
+ *
+ * Lives here rather than in `source-transform.ts` because the material graph and
+ * the sorter must place a splat identically. Keeping it on the material side
+ * also avoids a runtime dependency from `source-transform.ts` back into the
+ * material graph.
+ */
+export declare function sourceWorldTransform(columns: ReturnType<typeof uniformArray>, sourceId: THREE.Node<'int'>, localCenter: THREE.Node<'vec3'>): {
+    worldCenter: THREE.Node<'vec3'>;
+    linear: THREE.Node<'mat3'>;
+};
+/** Coefficients per channel for a band count (0 → none, 3 → 3rd order). */
+export declare function shCoefficientCount(bands: number): number;
+/**
+ * Builds the per-coefficient accessor for whichever SH source the mesh has -
+ * the only part of the SH graph that differs between them.
+ *
+ * `palette` indirects through the splat's codebook label; `packed` reads the
+ * splat's own words straight out of the pool-shaped integer textures and
+ * unpacks them (R: bits 0-10, G: 11-20, B: 21-31, each a unit fraction of its
+ * field, dequantized across the scene's range). The packed texel loads are
+ * hoisted into variables so all 15 coefficients cost at most four fetches.
+ */
+export declare function shCoefficientReader(sh: SplatShInputs, textures: {
+    covarianceBTexture: THREE.DataTexture;
+}, splatTexel: THREE.Node<'ivec2'>): (c: number) => THREE.Node<'vec3'>;
+/** Evaluates a source's higher-order SH contribution for a local view direction. */
+export declare function evaluateSplatSh(sh: SplatShInputs, textures: {
+    covarianceBTexture: THREE.DataTexture;
+}, splatTexel: THREE.Node<'ivec2'>, direction: THREE.Node<'vec3'>): THREE.Node<'vec3'>;
+/** Everything the material graph reads, gathered by the mesh. */
+export interface SplatMaterialBuildInputs {
+    textures: SplatMaterialTextures;
+    sh: SplatShInputs | null;
+    /**
+     * Per-source placement for a unified pool, or `null` for a plain mesh. When
+     * present, a splat's mesh-local center is `M · poolCenter` and SH is
+     * evaluated in the source's own frame.
+     */
+    sourcePlacement: SplatSourcePlacement | null;
+    /**
+     * The mesh's uniform *node instances*, not their values: display and pick
+     * share them, so a per-frame write reaches both graphs.
+     */
+    uniforms: {
+        focal: Vec2Uniform;
+        viewport: Vec2Uniform;
+        localCameraPosition: Vec3Uniform;
+        /** Frontier-cut limit on `own_size / distance` (`foveationMode: 'frontier'`). */
+        pixelScaleLimit: FloatUniform;
+        /**
+         * Core projected-2D DoF focus plane (world/view units). Live uniform -
+         * racking focus does not rebuild the material. See `depth-of-field.ts`.
+         */
+        dofFocusDistance: FloatUniform;
+        /** Core DoF aperture; `0` disables. Live uniform. */
+        dofAperture: FloatUniform;
+        /**
+         * Screen-radius band bounds in px, live so a foveated mesh can follow its
+         * own LOD cut. Whether the band exists at all is still decided at build
+         * time from `settings.minScreenRadiusPx` / `maxScreenRadiusPx`; only the
+         * bounds move.
+         *
+         * They have to move: the band spans one LOD level, so a mesh that refines
+         * its cut to spend spare budget would have exactly that new detail culled
+         * for being smaller than a bound chosen for the coarser cut.
+         */
+        screenBandMin: FloatUniform;
+        screenBandMax: FloatUniform;
+        /**
+         * Proxy-mesh relight map (RGB = lit, A = coverage). Live texture binding -
+         * swap via the TextureNode / rebuild when the mesh updates `setRelighting`.
+         * Display fragment only; pick ignores this.
+         */
+        relightMap: THREE.Texture;
+        /** `0` = baked color only; `1` = full modulate. Live uniform. */
+        relightBlend: FloatUniform;
+        /** Scales lit RGB (PlayCanvas default ~2 for 0.5 gray proxy). Live. */
+        relightBrightness: FloatUniform;
+        /** Multiplier where coverage alpha is 0 (sky). Live. */
+        relightBackground: FloatUniform;
+        /**
+         * Coverage soft edge in screen pixels. Live; `0` = hard mask.
+         * See {@link RelightingSettings.softness}.
+         */
+        relightSoftness: FloatUniform;
+    };
+    /** Pick-only uniforms. Required when building in `'pick'` mode. */
+    pick: {
+        alphaThreshold: FloatUniform;
+        near: FloatUniform;
+        far: FloatUniform;
+    } | null;
+    /** Baked at build time; changing any of these needs a rebuild. */
+    settings: {
+        maxStdDev: number;
+        /** Screen-space floor on each quad axis, px (0/undefined = off). */
+        minSplatSizePx?: number;
+        antialias: boolean;
+        /** Classic LCC uses XGRIDS' smaller, always-compensated low-pass. */
+        projectedFilterProfile: 'default' | 'lcc';
+        srgbOutput: boolean;
+        performanceProfile: SplatPerformanceProfile;
+        /** Cull splats whose projected radius exceeds this many px (0 = off). */
+        maxScreenRadiusPx?: number;
+        /** Foveation band lower bound: cull splats *below* this many px (0 = off). */
+        minScreenRadiusPx?: number;
+        /**
+         * `.rad` foveation cut. `'band'` (default/undefined) uses the screen-radius
+         * band above; `'frontier'` uses Spark's exact per-splat tree cut driven by
+         * `own_size` (from the covariance) and the `parent_size` packed in
+         * `covarianceB.w`. See `docs/formats/rad-notes.md` M14.6.
+         */
+        foveationMode?: 'band' | 'frontier' | 'pagetable';
+        /**
+         * Cap on a rendered splat's major/minor axis ratio (0/undefined = off). Tames
+         * far-field needle/spike artifacts from very anisotropic Gaussians and
+         * expansion-enlarged coarse LOD nodes. Baked into the material graph.
+         */
+        maxAspect?: number;
+        /**
+         * Spark's LOD alpha encoding (`.rad`): the stored opacity byte is `alpha/2`,
+         * so the shader multiplies by 2 to recover `alpha ∈ [0,2]`; `alpha > 1` marks
+         * a merged node whose σ-cutoff grows (`+0.7·(remap−1)`) and whose falloff
+         * becomes a super-Gaussian, covering its subtree without scaling covariance.
+         */
+        lodAlpha?: boolean;
+    };
+    /**
+     * The mesh's live channel map, not a copy: `defineChannel` adds to it and
+     * then rebuilds, and the graph must resolve names against the new entry.
+     */
+    channels: ReadonlyMap<string, {
+        texture: THREE.DataTexture;
+    }>;
+    modifiers: readonly SplatModifier[];
+}
+/**
+ * Shared TSL graph for display and pick materials: projection, covariance,
+ * modifiers, visibility, and Gaussian falloff. Display writes premultiplied
+ * color; pick encodes linear view depth into RGB with alpha as the hit flag.
+ *
+ * @param inputs.pick - Required when `mode` is `'pick'`.
+ */
+export declare function applySplatMaterialGraph(material: THREE.NodeMaterial, mode: 'display' | 'pick', inputs: SplatMaterialBuildInputs): void;
+export { foldSplatModifierStack };

package/dist/splat-mesh-picking.d.ts

@@ -0,0 +1,87 @@
+/**
+ * GPU screen-space picking for `SplatMesh`.
+ *
+ * Picking renders the splats once more into a 1×1 target, with a
+ * material that writes linear view depth instead of color; the depth comes back
+ * through an async readback and unprojects to a world point. That needs a whole
+ * subsystem of its own - a render target, a proxy mesh, a private scene, saved
+ * renderer state - none of which the mesh itself ever touches, so it lives here
+ * rather than as ten more fields on an already large class.
+ *
+ * The picker reaches back into the mesh through {@link SplatPickHost} rather
+ * than holding the mesh itself: the four things it needs are otherwise private,
+ * and widening them for the picker would put them in the published .d.ts.
+ *
+ * Internal. Nothing here is exported from `index.ts`.
+ */
+import * as THREE from 'three/webgpu';
+import type { SplatPickOptions, SplatPickResult } from './splat-mesh';
+import type { FloatUniform } from './splat-mesh-material';
+/** What the picker needs from the mesh it picks. */
+export interface SplatPickHost {
+    /** The mesh, for the transform/visibility the proxy mirrors and its geometry. */
+    readonly mesh: THREE.Mesh;
+    isDisposed(): boolean;
+    getActiveCount(): number;
+    /** The mesh's live viewport uniform value, in drawing-buffer pixels. */
+    getViewportSize(): THREE.Vector2;
+    /** Visibility as resolved by an owning unified renderer, when any. */
+    getPickVisible(): boolean;
+    /** Whether a sorter exists. A pick never creates one - see {@link prepare}. */
+    hasSorter(): boolean;
+    updateWorldMatrix(): void;
+    /**
+     * Brings the GPU to the state `update()` would leave it in: flush pending
+     * uploads, refresh the projection uniforms, and refresh an existing sorter's
+     * draw list. Ordering matters, so the mesh owns it.
+     */
+    prepare(camera: THREE.Camera, renderer: THREE.WebGPURenderer): void;
+    /**
+     * Writes focal / viewport / local-camera uniforms for a camera drawing into
+     * a viewport of `width`×`height` pixels. The pick pass crops the frustum to
+     * one source pixel and renders into a 1×1 target, so it must rewrite these
+     * after the crop and restore the canvas-sized values before returning.
+     */
+    setView(camera: THREE.Camera, width: number, height: number): void;
+    /** Builds the pick-mode TSL graph onto a freshly created material. */
+    applyPickGraph(material: THREE.NodeMaterial): void;
+}
+/**
+ * Owns the pick pass and everything it allocates. Resources are created on the
+ * first pick, so a mesh that is never picked pays nothing.
+ */
+export declare class SplatPicker {
+    private readonly host;
+    /** Alpha below which a splat is transparent enough to pick through. */
+    private readonly alphaThreshold;
+    /** Camera planes for the pick material's depth encoding. */
+    private readonly near;
+    private readonly far;
+    private material;
+    private proxy;
+    private target;
+    /** Reused sub-frustum camera; preserves the caller's concrete camera type. */
+    private pickCamera;
+    private readonly scene;
+    /** Serializes picks: they share one render target and one renderer. */
+    private queue;
+    private readonly point;
+    private readonly savedClearColor;
+    constructor(host: SplatPickHost);
+    /** The pick uniforms the material graph binds. */
+    get uniforms(): {
+        alphaThreshold: FloatUniform;
+        near: FloatUniform;
+        far: FloatUniform;
+    };
+    pick(ndc: THREE.Vector2, camera: THREE.Camera, renderer: THREE.WebGPURenderer, options?: SplatPickOptions): Promise<SplatPickResult | null>;
+    /** Rebuilds the pick graph after a settings change. No-op before the first pick. */
+    rebuildMaterial(): void;
+    /** Flags the pick graph for recompile (e.g. the modifier list changed). */
+    markNeedsUpdate(): void;
+    dispose(): void;
+    private run;
+    private ensureResources;
+    /** Maps one original framebuffer pixel onto the complete 1×1 pick target. */
+    private cropCameraToPixel;
+}

package/dist/splat-mesh-pool.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Texture-pool primitives behind `SplatMesh`.
+ *
+ * Splat attributes live in pool data textures, a fixed number of texels wide,
+ * and every range the mesh hands out is a whole number of rows in them. This
+ * module holds the parts of that scheme with no dependency on the mesh's own
+ * state: creating the textures, measuring the backend's limits, and the row-span
+ * bookkeeping the allocator runs on.
+ *
+ * {@link SplatPool} is public - a host builds one to let several meshes draw
+ * from a shared memory envelope. The rest is internal.
+ */
+import * as THREE from 'three/webgpu';
+/**
+ * Texels per row in every pool data texture.
+ *
+ * A range is row-aligned, so this also sets the allocation granularity: a
+ * 10-splat chunk still occupies a whole 2048-texel row. Wider rows waste more
+ * on small chunks; narrower rows need more rows than a backend may allow.
+ */
+export declare const SPLAT_DATA_TEXTURE_WIDTH = 2048;
+/** A free span of rows in the pool, as a row index and a row count. */
+export interface RowSpan {
+    start: number;
+    count: number;
+}
+/**
+ * Takes `rowCount` contiguous rows out of `spans`, best-fit.
+ *
+ * Best-fit rather than first-fit: a chunk pool churns ranges of very different
+ * sizes, and spending the smallest span that fits keeps the large ones intact
+ * for the large chunks that have nowhere else to go.
+ *
+ * Mutates `spans` in place. Throws when nothing contiguous is left, which is
+ * the caller's cue to compact.
+ *
+ * @param poolRows - Total rows in the pool; named in the failure only.
+ * @returns The starting row of the allocated span.
+ */
+export declare function allocateRowSpan(spans: RowSpan[], rowCount: number, poolRows: number): number;
+/**
+ * Returns a span to the free list, coalescing it with any neighbours.
+ *
+ * Merging on release is what keeps {@link allocateRowSpan} able to satisfy a
+ * large request after many small ranges have come and gone; without it the
+ * free list fragments into unusable slivers.
+ *
+ * @returns The new free list, sorted by start row.
+ */
+export declare function releaseRowSpan(spans: RowSpan[], start: number, count: number): RowSpan[];
+/** CPU-side mirror of the pool textures, kept for partial uploads. */
+export interface SplatPoolBacking {
+    centers: Float32Array;
+    colors: Uint8Array;
+    covarianceA: Float32Array;
+    covarianceB: Float32Array;
+    /** Per-splat packed SH; texture t holds coefficients 4t..4t+3. */
+    shPacked: Uint32Array[];
+}
+/** A tenant's allocation in the pool, as a row index and a row count. */
+export interface SplatPoolRange {
+    startRow: number;
+    rowCount: number;
+}
+/**
+ * A mesh that draws from a {@link SplatPool}.
+ *
+ * Only compaction needs this: packing the pool relocates rows belonging to
+ * every tenant, so each must be able to enumerate its ranges, follow them to
+ * their new rows, and rebuild whatever it keyed by pool index.
+ */
+export interface SplatPoolTenant {
+    /** The tenant's current allocations. */
+    poolRanges(): Iterable<SplatPoolRange>;
+    /**
+     * Adopts a new start row for one of this tenant's ranges. The pool has
+     * already moved the splat data; the tenant moves anything else keyed by pool
+     * row (per-splat channels) and records that those rows need re-uploading.
+     */
+    relocatePoolRange(range: SplatPoolRange, targetRow: number): void;
+    /** Called once after a compaction, so the tenant can rebuild draw state. */
+    onPoolCompacted(): void;
+}
+/** Options for {@link SplatPool}. */
+export interface SplatPoolOptions {
+    /** Splats the pool must hold; rounded up to whole rows. */
+    capacity: number;
+    /**
+     * Texture precision for centers and covarianceA. `'float16'` halves their
+     * VRAM; covarianceB stays float32 either way because it packs integer IDs
+     * (SOG palette label, `.rad` frontier parent) that halves cannot represent
+     * exactly above 2048.
+     */
+    floatTextures?: 'float32' | 'float16';
+    /** Bands of per-splat (non-palette) SH to allocate for; 0 disables. */
+    packedShBands?: 0 | 1 | 2 | 3;
+    /** Packed-SH coefficient count for `packedShBands`, supplied by the caller
+     * so this module stays free of the SH packing tables. */
+    packedShTextureCount?: number;
+    /**
+     * The device's `maxTextureDimension2D`, so a pool too tall for it fails here
+     * rather than at first draw. Pass {@link deviceMaxTextureSize}.
+     *
+     * `SplatMesh.update` also checks this, but only once and only if it is ever
+     * reached: a pool created past the limit and drawn through a path that
+     * swallows that first throw renders forever against invalid textures, which
+     * surfaces as an unreadable cascade of WebGPU "invalid due to a previous
+     * error" validation failures and a black canvas. Checking at construction is
+     * both earlier (before the allocation) and unskippable.
+     *
+     * Omitted or 0 skips the check, so a caller that cannot read the limit is not
+     * falsely rejected.
+     */
+    maxTextureSize?: number;
+}
+/**
+ * The splat storage a mesh draws from: the data textures, their CPU backing,
+ * and the row allocator that hands out space in them.
+ *
+ * Split out of `SplatMesh` because storage and drawing have different
+ * lifetimes and, ultimately, different owners. A mesh's *draw identity* is
+ * already independent of where its splats sit - `splatIndex` maps each
+ * instance to a pool index and the sorter rewrites it freely - so the pool
+ * behind those indices is a separate concern, and one pool can in principle
+ * back several meshes (each keeping its own active list of pool indices).
+ *
+ * Allocation is row-aligned and best-fit; see {@link allocateRowSpan}.
+ */
+export declare class SplatPool {
+    readonly width = 2048;
+    readonly rows: number;
+    readonly floatTextures: 'float32' | 'float16';
+    readonly packedShBands: 0 | 1 | 2 | 3;
+    readonly backing: SplatPoolBacking;
+    readonly centersTexture: THREE.DataTexture;
+    readonly colorsTexture: THREE.DataTexture;
+    readonly covarianceATexture: THREE.DataTexture;
+    readonly covarianceBTexture: THREE.DataTexture;
+    readonly shPackedTextures: readonly THREE.DataTexture[];
+    /** Free row spans, sorted by start row. Mutated in place by the allocator. */
+    freeRowSpans: RowSpan[];
+    private readonly tenants;
+    /**
+     * Pool index → its owner's packed active-list slot, valid only while that
+     * pool index is active.
+     *
+     * Pool-owned rather than per-mesh because it is keyed by *pool* index: a
+     * per-mesh copy would have to span the whole pool, so N meshes sharing one
+     * pool would each pay 4 B per pool splat (a 4 M-splat pool shared by 13
+     * meshes = ~200 MB of reverse maps). One array is safe because a row belongs
+     * to exactly one tenant at a time, so no two tenants ever write the same
+     * entry - the slot numbers in it are simply read back by whoever owns
+     * the row.
+     */
+    readonly activeSlotByPoolIndex: Uint32Array;
+    private poolIndexTemplate;
+    constructor(options: SplatPoolOptions);
+    /**
+     * A reusable `0, 1, 2, …` ramp over the pool, used to fill runs of pool
+     * indices and active-list slots without a per-element loop. Pool-owned so
+     * tenants sharing a pool share the one copy.
+     */
+    indexTemplate(): Uint32Array;
+    /** Splats the pool holds, always a whole number of rows. */
+    get capacity(): number;
+    /** Whether `texture` belongs to this pool (and so outlives any one tenant). */
+    isPoolTexture(texture: THREE.Texture): boolean;
+    /** The four core textures, in the order the upload path indexes them. */
+    get coreTextures(): readonly THREE.DataTexture[];
+    /** Rows still free, whether or not they are contiguous. */
+    get freeRows(): number;
+    /** Takes `rowCount` contiguous rows; throws when none are left (compact cue). */
+    allocateRows(rowCount: number): number;
+    /** Returns rows to the free list, coalescing neighbours. */
+    releaseRows(start: number, count: number): void;
+    /** Resets the free list to one span covering the whole pool. */
+    resetFreeRows(fromRow?: number): void;
+    /**
+     * Adds a mesh that draws from this pool. Registration exists for
+     * {@link compact}: packing the pool moves rows that belong to *every*
+     * tenant, so each has to be told where its ranges went.
+     */
+    register(tenant: SplatPoolTenant): void;
+    /**
+     * Drops a tenant. Release its ranges first: an unregistered tenant is
+     * invisible to {@link compact}, which would then treat rows it still holds
+     * as free and hand them to someone else. `compact` throws rather than let
+     * that happen silently.
+     */
+    unregister(tenant: SplatPoolTenant): void;
+    /** Number of meshes drawing from this pool. */
+    get tenantCount(): number;
+    /**
+     * Packs every tenant's ranges toward row 0, removing the gaps that add /
+     * remove churn leaves behind and restoring a single contiguous free span.
+     * Callers reach this when {@link allocateRows} throws despite enough total
+     * free rows - row-alignment fragmentation.
+     *
+     * The CPU backing arrays are authoritative, so nothing is re-fetched; moved
+     * rows are re-uploaded on the tenant's next update.
+     *
+     * Note this is a whole-pool stall: with several tenants, one mesh's
+     * fragmentation relocates the others' rows too, and every tenant rebuilds
+     * its draw state. (Spark sidesteps the equivalent by allocating fixed-size,
+     * interchangeable pages that never need packing; vlam's ranges are variable
+     * runs, so it packs instead.)
+     */
+    compact(): void;
+    dispose(): void;
+}
+export declare function createDataTexture(data: Float32Array | Uint8Array | Uint16Array, width: number, height: number, type: THREE.TextureDataType): THREE.DataTexture;
+/**
+ * An RGBA32UI data texture: four raw `uint32` per texel, delivered to the
+ * shader as a `uvec4` with no filtering or normalization. Packed SH words go
+ * through this rather than a float texture so they survive bit-exact.
+ */
+export declare function createIntegerDataTexture(data: Uint32Array, width: number, height: number): THREE.DataTexture;
+/**
+ * The renderer backend's maximum 2D texture dimension, or 0 when it can't be
+ * read (in which case callers skip any limit check rather than falsely reject).
+ * WebGPU exposes `device.limits.maxTextureDimension2D`; WebGL2 exposes
+ * `gl.MAX_TEXTURE_SIZE`.
+ */
+export declare function deviceMaxTextureSize(renderer: THREE.WebGPURenderer): number;
+/**
+ * Throws when a pool's data textures would be taller than the device allows.
+ *
+ * `maxTextureSize <= 0` means "limit unknown" and skips the check rather than
+ * risk a false rejection; see {@link deviceMaxTextureSize}.
+ *
+ * @param rows - Rows the pool needs.
+ * @param maxTextureSize - The device's `maxTextureDimension2D`.
+ * @param width - Texels per row, for the splat count in the message.
+ */
+export declare function assertPoolRowsFitDevice(rows: number, maxTextureSize: number, width?: number): void;
+/**
+ * Three's WebGPU backend submits one `queue.writeBuffer` per update range.
+ * Merge touching mutations here so a region-atomic commit does not turn a
+ * handful of contiguous backfills into several main-thread submissions.
+ */
+export declare function addMergedUpdateRange(attribute: THREE.BufferAttribute, start: number, count: number): void;