@voluma/vlam 0.2.4 → 0.3.0

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

@@ -3,7 +3,7 @@ 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}. */
+/** Registration settings for one source in a {@link UnifiedSplatMesh}. */
 export interface UnifiedSplatSourceOptions {
     /** Whole-source opacity applied after its modifier stack. Defaults to `1`. */
     opacity?: number;
@@ -12,7 +12,7 @@ export interface UnifiedSplatSourceOptions {
     /** 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 +23,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 +35,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 +49,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 +63,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 +131,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. */

package/dist/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/unified.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';