@voluma/vlam 0.2.4 → 0.3.2

package/dist/unified/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@voluma/vlam/unified` - one WebGPU draw over several splat sources.
+ *
+ * {@link UnifiedSplatMesh} concatenates static and streamed meshes into a
+ * shared work buffer so overlapping clouds inter-sort. WebGL2 is unsupported;
+ * {@link supportsUnifiedSplatMesh} reports that after renderer init.
+ *
+ * @module unified
+ */
+export { UnifiedSplatMesh, supportsUnifiedSplatMesh, type UnifiedSplatPickResult, type UnifiedSplatMeshOptions, type UnifiedSplatSourceOptions, } from './unified-splat-mesh';
+export { estimateLargestStorageBufferBytes, estimateUnifiedWorkBufferBytes, estimateUnifiedWorkBufferPeakBytes, WORK_BUFFER_CENTERS_BYTES_PER_SPLAT, WORK_BUFFER_BYTES_PER_SLOT, } from './unified-work-buffer';

package/dist/{unified-splat-renderer.d.ts → unified/unified-splat-mesh.d.ts}

@@ -1,18 +1,19 @@
 import * as THREE from 'three/webgpu';
-import { type DepthOfFieldSettings } from './depth-of-field';
-import { type RelightingSettings, type RelightingUniforms } from './relighting';
-import { SplatMesh } from './splat-mesh';
-import type { SplatPickOptions, SplatPickResult } from './splat-mesh';
-/** Registration settings for one source in a {@link UnifiedSplatRenderer}. */
+import { type DepthOfFieldSettings } from '../core/depth-of-field';
+import { type RelightingSettings, type RelightingUniforms } from '../core/relighting';
+import { SplatMesh } from '../core/splat-mesh';
+import type { SplatPickOptions, SplatPickResult } from '../core/splat-mesh';
+/** Registration settings for one source in a {@link UnifiedSplatMesh}. */
 export interface UnifiedSplatSourceOptions {
-    /** Whole-source opacity applied after its modifier stack. Defaults to `1`. */
+    /** Whole-source display opacity applied after gather falloff. Defaults to `1`.
+     * Does not change RAD LOD classification or splat shape. */
     opacity?: number;
     /** Whether this source contributes to the unified draw. Defaults to `true`. */
     visible?: boolean;
     /** Higher values survive a fixed work-buffer overflow first. Defaults to `0`. */
     priority?: number;
     /**
-     * Cache a modifier-bearing source until {@link UnifiedSplatRenderer.invalidateSource}
+     * Cache a modifier-bearing source until {@link UnifiedSplatMesh.invalidateSource}
      * is called. Defaults to `false`, which safely re-gathers live modifier
      * uniforms every frame.
      *
@@ -23,7 +24,7 @@ export interface UnifiedSplatSourceOptions {
     cacheModifiers?: boolean;
 }
 /**
- * Result of a successful {@link UnifiedSplatRenderer.pick}: the frontmost hit
+ * Result of a successful {@link UnifiedSplatMesh.pick}: the frontmost hit
  * across every visible registered source, tagged with the source it landed on.
  */
 export interface UnifiedSplatPickResult extends SplatPickResult {
@@ -35,7 +36,7 @@ export interface UnifiedSplatPickResult extends SplatPickResult {
  *
  * @experimental May change in a minor release.
  */
-export interface UnifiedSplatRendererOptions {
+export interface UnifiedSplatMeshOptions {
     /** Composite source colors in display (sRGB) space. Defaults to `false`. */
     srgbOutput?: boolean;
     /**
@@ -49,11 +50,11 @@ export interface UnifiedSplatRendererOptions {
     sortStrategy?: 'counting' | 'exact';
 }
 /**
- * Returns true when `renderer` can drive {@link UnifiedSplatRenderer}.
+ * Returns true when `renderer` can drive {@link UnifiedSplatMesh}.
  * Heterogeneous gather/sort/draw is WebGPU-only; WebGL2 hosts keep standalone
- * `SplatMesh` draws or static {@link SplatScene}.
+ * `SplatMesh` draws or static {@link MergedSplatMesh}.
  */
-export declare function supportsUnifiedSplatRenderer(renderer: object): boolean;
+export declare function supportsUnifiedSplatMesh(renderer: object): boolean;
 /**
  * One gather → global-sort → draw path for static and streamed splat sources.
  * Sources retain their own residency and update lifecycle; this mesh gathers
@@ -63,11 +64,11 @@ export declare function supportsUnifiedSplatRenderer(renderer: object): boolean;
  * registered source mesh instead - sorter bounds and the draw material both
  * consume world-space centers written by gather.
  *
- * WebGPU only. Prefer {@link supportsUnifiedSplatRenderer} before construction.
+ * WebGPU only. Prefer {@link supportsUnifiedSplatMesh} before construction.
  *
  * @experimental May change in a minor release.
  */
-export declare class UnifiedSplatRenderer extends THREE.Mesh {
+export declare class UnifiedSplatMesh extends THREE.Mesh {
     private readonly workBuffer;
     private readonly workSourceIndex;
     /** The sorted draw-order buffer; lives outside the geometry, freed on dispose. */
@@ -131,7 +132,7 @@ export declare class UnifiedSplatRenderer extends THREE.Mesh {
     private overflowedSourceCount;
     private overflowedSplatCount;
     private disposed;
-    constructor(renderer: THREE.WebGPURenderer, capacity: number, options?: UnifiedSplatRendererOptions);
+    constructor(renderer: THREE.WebGPURenderer, capacity: number, options?: UnifiedSplatMeshOptions);
     /** Fixed work-buffer splat capacity chosen at construction. */
     get capacity(): number;
     /** Registers a source. The caller keeps ownership and may still query it. */
@@ -149,7 +150,13 @@ export declare class UnifiedSplatRenderer extends THREE.Mesh {
     get droppedSourceCount(): number;
     /** Number of active splats omitted in the most recent update due to capacity. */
     get droppedSplatCount(): number;
-    /** Updates a source's resolved opacity without rebuilding its gather pipeline. */
+    /**
+     * Sets whole-source display opacity without rebuilding the gather pipeline.
+     *
+     * This scales the completed fragment after RAD merged-vs-leaf classification
+     * and falloff. It must never alter LOD selection or splat shape; hosts such as
+     * marker crossfades rely on that. Values `<= 0` skip drawing the source.
+     */
     setSourceOpacity(source: SplatMesh, opacity: number): void;
     /** Shows or hides a source without changing its residency. */
     setSourceVisible(source: SplatMesh, visible: boolean): void;

package/dist/unified/unified-work-buffer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Byte costs of {@link UnifiedSplatMesh}'s GPU work buffer.
+ *
+ * Kept off the core entry so hosts that never composite sources do not pay
+ * for the accounting, and so the numbers cannot drift from the renderer
+ * that allocates those buffers.
+ */
+/** Bytes per splat in the largest unified work-buffer attribute (RGBA32F centers). */
+export declare const WORK_BUFFER_CENTERS_BYTES_PER_SPLAT = 16;
+/**
+ * Bytes per work-buffer slot across *all* of its attributes: centers, colors,
+ * covarianceA and covarianceB at RGBA32F (16 each), plus the isotropic mix and
+ * screen-radius scalars (4 each).
+ */
+export declare const WORK_BUFFER_BYTES_PER_SLOT: number;
+/**
+ * Byte size of the largest single storage-buffer bind VLAM allocates for a
+ * given splat capacity (unified work-buffer centers: `capacity × 16`).
+ *
+ * Use with adapter/device limits to decide whether to raise `requiredLimits`
+ * or lower the budget before constructing {@link UnifiedSplatMesh}.
+ */
+export declare function estimateLargestStorageBufferBytes(capacity: number): number;
+/**
+ * Estimates what a {@link UnifiedSplatMesh}'s work buffer costs, in bytes,
+ * once the scene has rendered a frame.
+ *
+ * This used to be double the figure below, and the doubling was not a detail.
+ * Every `THREE.StorageBufferAttribute` is constructed around a JS typed array,
+ * and three's WebGPU backend never releases it: the
+ * `attribute.onUploadCallback()` call that would is missing from the backend's
+ * buffer upload path. So a work buffer of N slots cost
+ * N × {@link WORK_BUFFER_BYTES_PER_SLOT} on the GPU *and* the same again on the
+ * JS heap, permanently, even though nothing ever reads the CPU copy back - the
+ * gather pass writes these buffers entirely on the GPU.
+ *
+ * `WorkBuffer.releaseCpuMirrors` now drops those mirrors after the first
+ * dispatch that uploads them (see `storage-attribute-mirror`), so steady state
+ * is the GPU side alone. The *peak* is still double - the array has to exist
+ * for the upload copy - which is what
+ * {@link estimateUnifiedWorkBufferPeakBytes} reports.
+ *
+ * Either figure is invisible to `estimateSplatPoolBytes`, which prices the
+ * splat *pool* and knows nothing about the unified renderer's scratch space. A
+ * host sizing a scene for a memory-constrained device wants both.
+ *
+ * @param capacity - Work-buffer capacity in splats.
+ * @returns Estimated steady-state bytes.
+ * @throws {RangeError} if `capacity` is not a non-negative finite number.
+ */
+export declare function estimateUnifiedWorkBufferBytes(capacity: number): number;
+/**
+ * Peak bytes a {@link UnifiedSplatMesh}'s work buffer occupies: the window
+ * between construction and the first dispatch, while the GPU buffer and the JS
+ * array three copied it from are both alive.
+ *
+ * Ask this one when the question is "will allocating this scene succeed" - an
+ * out-of-memory failure happens against the peak. Ask
+ * {@link estimateUnifiedWorkBufferBytes} when the question is "what will this
+ * scene hold once it is up".
+ *
+ * @param capacity - Work-buffer capacity in splats.
+ * @returns Estimated bytes, GPU plus the not-yet-released CPU mirror.
+ * @throws {RangeError} if `capacity` is not a non-negative finite number.
+ */
+export declare function estimateUnifiedWorkBufferPeakBytes(capacity: number): number;

package/dist/{work-buffer-gather.d.ts → unified/work-buffer-gather.d.ts}

@@ -1,6 +1,6 @@
 import * as THREE from 'three/webgpu';
-import { type SplatShInputs, type Vec3Uniform } from './splat-mesh-material';
-import type { SplatModifier } from './splat-modifier';
+import { type SplatShInputs, type Vec3Uniform } from '../core/splat-mesh-material';
+import type { SplatModifier } from '../core/splat-modifier';
 /**
  * GPU gather pass for Phase 0 of the unified renderer. It resolves a source
  * pool's active local centers into a shared world-space storage buffer. The
@@ -12,7 +12,7 @@ import type { SplatModifier } from './splat-modifier';
 /** Shared GPU storage for every gathered source in one unified frame. */
 export declare class WorkBuffer {
     readonly capacity: number;
-    /** World-space center xyz; w is the drawable flag (1 draw, 0 modifier-hidden). */
+    /** World-space center xyz; w is display opacity (`visibility × source opacity ×` RAD modifier ratio). */
     readonly centers: THREE.StorageBufferAttribute;
     /** Resolved color and opacity per work slot. */
     readonly colors: THREE.StorageBufferAttribute;
@@ -86,8 +86,8 @@ export declare class WorkBufferGather {
         srgbOutput?: boolean;
         /**
          * Source stores Spark LOD alpha (`alpha ÷ 2`, `.rad`). Recover the full
-         * `alpha ∈ [0,2]` here so the shared draw material sees one convention;
-         * `alpha > 1` then marks a merged node (see `createWorkBufferMaterial`).
+         * `alpha ∈ [0,2]` into `colors.a` from the *original* texture channel so the
+         * shared draw material can classify merged vs leaf without seeing fades.
          */
         lodAlpha?: boolean;
         /** Reuse one target across all source gather passes. */
@@ -99,7 +99,7 @@ export declare class WorkBufferGather {
      * Compiles this gather's compute pipeline without gathering anything.
      *
      * WebGPU compiles a compute pipeline lazily, at its first dispatch - not when
-     * the node graph is built. Measured on a 13-marker scene, a source's *first*
+     * the node graph is built. Measured on a 13-mesh scene, a source's *first*
      * `gather` took up to 2.0s while every later dispatch of the same pipeline
      * took under 0.4ms, and because `gather` runs inside `update` that compile
      * landed whole in one render frame. Running it through the async path here

package/dist/{work-buffer-material.d.ts → unified/work-buffer-material.d.ts}

@@ -1,5 +1,5 @@
 import * as THREE from 'three/webgpu';
-import type { FloatUniform, Vec2Uniform } from './splat-mesh-material';
+import type { FloatUniform, Vec2Uniform } from '../core/splat-mesh-material';
 /**
  * Creates the unified EWA draw material for gathered world-space splats.
  *