@voluma/vlam 0.2.3 → 0.3.0

package/dist/static-lod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-lod.js","sources":["../src/lib/static-lod-splat-mesh.ts"],"sourcesContent":["/** @role Bridge - Camera-aware rendering for worker-built static splat hierarchies. */\nimport * as THREE from 'three/webgpu';\nimport { loadSplatData, type SplatDataLoadOptions } from './load-splat-data';\nimport type { SplatData } from './splat-data';\nimport { SplatMesh, type SplatMeshOptions, type SplatUpdateOptions } from './splat-mesh';\nimport type { StaticLodBuildProgress } from './static-lod';\nimport type { StaticLodWorkerRequest, StaticLodWorkerResponse } from './static-lod-worker-protocol';\n\nconst BUDGET_GRANULARITY = 4096;\nconst CAMERA_RESCHEDULE_INTERVAL_MS = 250;\n\nexport interface StaticLodSplatMeshOptions extends SplatMeshOptions {\n  /** Initial selected-frontier budget. Defaults to the build ceiling. */\n  budget?: number;\n  /** Finest frontier retained by the hierarchy and immutable pool ceiling. */\n  maxBudget: number;\n  /** Reports the spatial ordering and hierarchy-build phase. */\n  onLodProgress?: (progress: StaticLodBuildProgress) => void;\n  /** Phase-aware progress spanning download, decode completion and LOD build. */\n  onAutoLodProgress?: (progress: StaticLodLoadProgress) => void;\n}\n\nexport interface StaticLodLoadProgress {\n  readonly phase: 'download' | 'decode' | 'lod-build';\n  readonly completed: number;\n  readonly total: number;\n}\n\nexport interface StaticLodSplatMeshLoadOptions\n  extends StaticLodSplatMeshOptions, SplatDataLoadOptions {}\n\nconst transferablesFor = (data: SplatData): Transferable[] => {\n  const transferables: Transferable[] = [\n    data.positions.buffer as ArrayBuffer,\n    data.colors.buffer as ArrayBuffer,\n    data.covariances.buffer as ArrayBuffer,\n  ];\n  if (data.sh) transferables.push(data.sh.labels.buffer as ArrayBuffer);\n  if (data.shPacked) transferables.push(data.shPacked.packed.buffer as ArrayBuffer);\n  return transferables;\n};\n\nconst normalizeBudget = (value: number, ceiling: number): number => {\n  if (!Number.isFinite(value) || value <= 0) {\n    throw new RangeError('StaticLodSplatMesh budget must be a positive finite number.');\n  }\n  const clamped = Math.min(ceiling, Math.floor(value));\n  if (clamped === ceiling || clamped < BUDGET_GRANULARITY) return Math.max(1, clamped);\n  return Math.max(\n    BUDGET_GRANULARITY,\n    Math.floor(clamped / BUDGET_GRANULARITY) * BUDGET_GRANULARITY,\n  );\n};\n\nconst buildInWorker = async (\n  source: SplatData,\n  options: StaticLodSplatMeshOptions,\n  signal: AbortSignal | undefined,\n): Promise<{\n  data: SplatData;\n  contentSplatCount: number;\n  finestSplatCount: number;\n  worker: Worker;\n}> => {\n  const module = await import('./static-lod-worker?worker&inline');\n  const WorkerClass = module.default;\n  const worker = new WorkerClass();\n  return await new Promise((resolve, reject) => {\n    const abort = (): void => {\n      worker.terminate();\n      reject(new DOMException('Static LOD build aborted.', 'AbortError'));\n    };\n    if (signal?.aborted) {\n      abort();\n      return;\n    }\n    signal?.addEventListener('abort', abort, { once: true });\n    worker.onerror = (event): void => {\n      signal?.removeEventListener('abort', abort);\n      worker.terminate();\n      reject(new Error(event.message));\n    };\n    worker.onmessage = (event: MessageEvent<StaticLodWorkerResponse>): void => {\n      const response = event.data;\n      if (response.type === 'progress') {\n        options.onLodProgress?.(response.progress);\n        options.onAutoLodProgress?.({ phase: 'lod-build', ...response.progress });\n        return;\n      }\n      if (response.type === 'error') {\n        signal?.removeEventListener('abort', abort);\n        worker.terminate();\n        reject(new Error(response.message));\n        return;\n      }\n      if (response.type !== 'built') return;\n      signal?.removeEventListener('abort', abort);\n      resolve({\n        data: response.data,\n        contentSplatCount: response.contentSplatCount,\n        finestSplatCount: response.finestSplatCount,\n        worker,\n      });\n    };\n    const request: StaticLodWorkerRequest = {\n      type: 'build',\n      source,\n      maxBudget: options.maxBudget,\n    };\n    worker.postMessage(request, transferablesFor(source));\n  });\n};\n\n/**\n * Static splat mesh backed by a merged hierarchy and camera-aware frontier.\n * The full hierarchy is uploaded once; camera/budget cuts only remap the\n * active pool indices and never rewrite resident splat attributes.\n */\nexport class StaticLodSplatMesh extends SplatMesh {\n  private readonly worker: Worker;\n  private readonly ceilingValue: number;\n  private readonly contentCountValue: number;\n  private budgetValue: number;\n  private sequence = 0;\n  private lastScheduleAt = -Infinity;\n  private selectionPending = false;\n  private readonly cameraLocal = new THREE.Vector3();\n  private readonly cameraForward = new THREE.Vector3(0, 0, -1);\n  private readonly inverseWorld = new THREE.Matrix4();\n\n  private constructor(\n    data: SplatData,\n    contentSplatCount: number,\n    finestSplatCount: number,\n    worker: Worker,\n    options: StaticLodSplatMeshOptions,\n  ) {\n    super(data, options);\n    this.worker = worker;\n    this.ceilingValue = finestSplatCount;\n    this.contentCountValue = contentSplatCount;\n    this.budgetValue = normalizeBudget(options.budget ?? this.ceilingValue, this.ceilingValue);\n    // Hierarchy layout: finest level occupies pool indices `[0, finest)`.\n    this.replaceActivePrefix(this.ceilingValue);\n    this.worker.onmessage = (event: MessageEvent<StaticLodWorkerResponse>): void => {\n      const response = event.data;\n      if (response.type === 'error') {\n        this.selectionPending = false;\n        return;\n      }\n      if (response.type !== 'selection' || response.sequence !== this.sequence) return;\n      this.selectionPending = false;\n      this.replaceActiveIndices(response.indices);\n    };\n    if (this.budgetValue < this.ceilingValue) this.scheduleSelection(true);\n  }\n\n  /** Loads, decodes and builds a merged static hierarchy without blocking UI. */\n  static async load(\n    input: string | URL,\n    options: StaticLodSplatMeshLoadOptions,\n  ): Promise<StaticLodSplatMesh> {\n    let decodeReported = false;\n    const source = await loadSplatData(input, {\n      ...options,\n      onProgress: (completed, total) => {\n        options.onProgress?.(completed, total);\n        options.onAutoLodProgress?.({ phase: 'download', completed, total });\n        if (!decodeReported && total > 0 && completed >= total) {\n          decodeReported = true;\n          options.onAutoLodProgress?.({ phase: 'decode', completed: 0, total: 1 });\n        }\n      },\n    });\n    if (!decodeReported) {\n      options.onAutoLodProgress?.({ phase: 'decode', completed: 0, total: 1 });\n    }\n    options.onAutoLodProgress?.({ phase: 'decode', completed: 1, total: 1 });\n    const result = await buildInWorker(source, options, options.signal);\n    return new StaticLodSplatMesh(\n      result.data,\n      result.contentSplatCount,\n      result.finestSplatCount,\n      result.worker,\n      options,\n    );\n  }\n\n  get budget(): number {\n    return this.budgetValue;\n  }\n\n  get budgetCeiling(): number {\n    return this.ceilingValue;\n  }\n\n  get maxBudget(): number {\n    return this.ceilingValue;\n  }\n\n  get contentSplatCount(): number {\n    return this.contentCountValue;\n  }\n\n  /** Changes the selected frontier budget within the immutable build ceiling. */\n  setBudget(value: number): number {\n    const next = normalizeBudget(value, this.ceilingValue);\n    if (next === this.budgetValue) return next;\n    this.budgetValue = next;\n    this.selectionPending = false;\n    this.scheduleSelection(true);\n    return next;\n  }\n\n  override update(\n    camera: THREE.PerspectiveCamera,\n    renderer: THREE.WebGPURenderer,\n    options: SplatUpdateOptions = {},\n  ): void {\n    super.update(camera, renderer, options);\n    this.updateLod(camera);\n  }\n\n  /** Schedules a camera-aware cut when a unified renderer owns drawing/sorting. */\n  updateLod(camera: THREE.PerspectiveCamera): void {\n    camera.updateMatrixWorld();\n    this.updateWorldMatrix(true, false);\n    this.inverseWorld.copy(this.matrixWorld).invert();\n    this.cameraLocal.setFromMatrixPosition(camera.matrixWorld).applyMatrix4(this.inverseWorld);\n    camera.getWorldDirection(this.cameraForward).transformDirection(this.inverseWorld);\n    this.scheduleSelection(false);\n  }\n\n  override dispose(): void {\n    if (this.disposed) return;\n    this.worker.terminate();\n    super.dispose();\n  }\n\n  private scheduleSelection(immediate: boolean): void {\n    if (this.disposed || this.selectionPending) return;\n    const now = performance.now();\n    if (!immediate && now - this.lastScheduleAt < CAMERA_RESCHEDULE_INTERVAL_MS) return;\n    this.lastScheduleAt = now;\n    this.selectionPending = true;\n    const request: StaticLodWorkerRequest = {\n      type: 'select',\n      sequence: ++this.sequence,\n      budget: this.budgetValue,\n      cameraLocal: this.cameraLocal.toArray(),\n      cameraForward: this.cameraForward.toArray(),\n    };\n    this.worker.postMessage(request);\n  }\n}\n"],"names":["BUDGET_GRANULARITY","CAMERA_RESCHEDULE_INTERVAL_MS","transferablesFor","data","transferables","normalizeBudget","value","ceiling","clamped","buildInWorker","source","options","signal","WorkerClass","worker","resolve","reject","abort","event","response","_a","_b","request","StaticLodSplatMesh","SplatMesh","contentSplatCount","finestSplatCount","__publicField","THREE","input","decodeReported","loadSplatData","completed","total","_c","result","next","camera","renderer","immediate","now"],"mappings":"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"}

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

@@ -1,7 +1,6 @@
 export * from './streamed-splat-mesh-utils';
 import * as THREE from 'three/webgpu';
 import { SplatMesh, type SplatChannelOptions, type SplatMeshOptions, type SplatUpdateOptions } from './splat-mesh';
-import type { StaticLodSplatMesh, StaticLodSplatMeshLoadOptions } from './static-lod-splat-mesh';
 import { type StreamedScene } from './lod-source';
 import type { CollisionMeshTile } from './formats/lcc/collision-mesh';
 import { type SplatRequestOptions, type StreamedSplatFormat } from './loading';
@@ -87,13 +86,13 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * should be able to *grow* this mesh's share: the pool is allocated once at
      * construction and never grows, so without headroom reserved here a governed
      * mesh can only ever be shrunk below the budget it was built with. That is
-     * the whole reason a hand-split `pool / N` marker stays coarse near the
-     * camera - every marker's ceiling was fixed at a quarter of the pool.
+     * the whole reason a hand-split `pool / N` mesh stays coarse near the
+     * camera - every mesh's ceiling was fixed at a quarter of the pool.
      *
      * It is not free: the pool costs its *ceiling* in memory whether or not the
      * budget ever reaches it (~64 B of GPU pool plus ~56 B of CPU backing per
      * splat, 1.5× for capacity slack). Price it with `estimateSplatPoolBytes`
-     * before choosing - for several markers the
+     * before choosing - for several additional meshes the
      * sum of the ceilings is what has to fit, not the shared budget. A ceiling
      * around 1.5–2× a member's fair share is usually the right trade.
      *
@@ -106,7 +105,7 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * `> 1` refines further (finer cut, more splats drawn), `< 1` coarsens.
      * Default `1`.
      *
-     * **`.rad` `foveationMode: 'pagetable'` only** - it scales the frontier cut
+     * **`.rad` `foveationMode: 'page-table'` only** - it scales the frontier cut
      * the page-table traversal is given (`pixel_scale × lodScale ≤ limit`, exactly
      * Spark's formula). It does nothing on a mesh with no per-splat cut to scale:
      * a moderate `.rad` read as a chunk prefix, or a Streamed SOG / LCC scene. For
@@ -128,7 +127,7 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * later streaming is stopped by {@link SplatMesh.dispose}.
      */
     signal?: AbortSignal;
-    /** Base URL a relative manifest URL resolves against (like {@link loadScene}). */
+    /** Base URL a relative manifest URL resolves against (like {@link loadSplatData}). */
     baseUrl?: string | URL;
     /** World-unit distance inside which the finest LOD is used. Default 10. */
     lodBaseDistance?: number;
@@ -186,7 +185,7 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * to `'progressive'`.
      */
     initialReveal?: 'progressive' | 'hold-near-l0' | 'hold-coverage';
-    /** Receives lightweight LOD swap markers for performance attribution. */
+    /** Receives lightweight LOD mutation events for performance attribution. */
     onPerformanceEvent?: (event: StreamedSplatPerformanceEvent) => void;
     /**
      * View-dependent color (higher-order SH). This is the streaming counterpart
@@ -234,7 +233,7 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * or suspended, and has one effect on its own: the background sweep that
      * pre-warms the whole capture into the page-table cache stops. That sweep is
      * pure speculation about a camera move that has not happened, and on a
-     * multi-marker scene it is most of the traffic competing with the marker the
+     * multi-mesh scene it is most of the traffic competing with the mesh the
      * viewer is actually looking at.
      *
      * Unset (the default) leaves fetching exactly as it was: every mesh sweeps.
@@ -244,8 +243,8 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
     /**
      * Scene-wide fetch arbitration, shared by every streamed mesh the way a
      * {@link SplatMeshOptions.pool} is - see {@link ChunkFetchScheduler}. Without
-     * one, each mesh fetches toward its own in-flight cap and a near marker's
-     * detail queues behind a dozen far markers' background traffic.
+     * one, each mesh fetches toward its own in-flight cap and a near mesh's
+     * detail queues behind a dozen far meshes' background traffic.
      *
      * The scheduler is *not* owned by the mesh: dispose unregisters this mesh and
      * leaves the scheduler running for its siblings. Weights come from
@@ -261,7 +260,7 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * Without one, each `.rad` page-table mesh caps its own cache at
      * `max(cpuCacheBytes, min(2 GiB, this capture's decoded size))`: the right
      * number for a lone streamed scene, and no bound at all across a scene of
-     * markers, because every mesh gets its own and each is sized to its own
+     * additional meshes, because every mesh gets its own and each is sized to its own
      * capture. With one, that figure becomes this mesh's *ceiling* and the budget
      * splits a scene total across every registered mesh by camera weight.
      *
@@ -328,11 +327,6 @@ export interface PersistentChannelOptions extends SplatChannelOptions {
  * `docs/formats/streamed-shn-notes.md`).
  */
 export declare class StreamedSplatMesh extends SplatMesh {
-    /**
-     * Loads a non-streamed splat file into a worker-built merged hierarchy.
-     * The returned static mesh shares this class's runtime budget contract.
-     */
-    static loadAutoLod(input: string | URL, options: StaticLodSplatMeshLoadOptions): Promise<StaticLodSplatMesh>;
     private readonly scene;
     private readonly loader;
     /**
@@ -399,7 +393,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
     private lodLevelScratch;
     /** Desired-but-not-resident files this tick; protected from cache eviction. */
     private readonly neededFiles;
-    /** Non-null in `foveationMode: 'pagetable'`: the worker that owns the chunk
+    /** Non-null in `foveationMode: 'page-table'`: the worker that owns the chunk
      * cache + traversal + pager off the main thread, and the always-active slab it
      * pages the returned frontier into. */
     private readonly frontierWorker;
@@ -454,7 +448,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * governed budget outgrows it, rather than the library's own default. */
     private pageTableDrawTargetExplicit;
     /** Last frontier's drawn (non-degenerate) splat count - the true on-screen size
-     * in `pagetable` mode, where the slab is fully "active" but mostly degenerate. */
+     * in `page-table` mode, where the slab is fully "active" but mostly degenerate. */
     private pageTableDrawn;
     /** Monotonic reschedule id; a stale plan (superseded by a newer request) is
      * dropped. `pageTableInFlight` coalesces to one outstanding traversal. */
@@ -563,8 +557,8 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * tells the worker's pager the new slot count.
      *
      * This is the mechanism that makes a shared pool worth having: storage follows
-     * the governed budget, so approaching a marker grows its pages while the ones
-     * behind you hand theirs back, instead of every marker holding its ceiling for
+     * the governed budget, so approaching a mesh grows its pages while the ones
+     * behind you hand theirs back, instead of every mesh holding its ceiling for
      * the whole session. Growth stops at the construction ceiling and at whatever
      * the pool can actually spare - a mesh that cannot grow simply stays coarse
      * rather than throwing.
@@ -684,7 +678,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * The drawn-splat target currently driving the `.rad` page-table frontier -
      * the governed budget, capped by
      * {@link SplatMeshOptions.foveationDrawBudget}. `0` on a mesh that is not in
-     * `foveationMode: 'pagetable'`, which has no frontier to target.
+     * `foveationMode: 'page-table'`, which has no frontier to target.
      *
      * This is the number that decides how deep the traversal descends, so it is
      * what to watch when checking that a near mesh really did receive more
@@ -700,7 +694,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
      */
     get lodScale(): number;
     set lodScale(value: number);
-    /** In `pagetable` mode the slab is fully active but mostly degenerate, so the
+    /** In `page-table` mode the slab is fully active but mostly degenerate, so the
      * base `activeSplatCount` (slab size) is not the on-screen count - report the
      * frontier's drawn size instead. */
     get activeSplatCount(): number;
@@ -736,7 +730,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
     /** Chunk fetches currently in flight. */
     get pendingChunkCount(): number;
     /**
-     * Main-thread cost of applying paging plans in `foveationMode: 'pagetable'`.
+     * Main-thread cost of applying paging plans in `foveationMode: 'page-table'`.
      *
      * A plan is applied whole, off the render loop's own timing, so its cost does
      * not appear in {@link getUpdateTimings} - but it lands on the same thread and
@@ -906,7 +900,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * and it starts enabled. Failed / unfit / disabled tiles do not block reveal.
      */
     private environmentPendingForReveal;
-    /** Creates a marker for a changed streamed-LOD tick, if any. */
+    /** Creates a performance event for a changed streamed-LOD tick, if any. */
     private createPerformanceEvent;
     /** Returns whether all new rows can coexist with the currently visible region. */
     private canStageGroup;
@@ -963,7 +957,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
     /** Ranks the env tile ahead of every LOD want in {@link flushClassicFetches}. */
     private enqueueEnvironmentFetch;
     /**
-     * Page-table reschedule (`foveationMode: 'pagetable'`): posts the camera to the
+     * Page-table reschedule (`foveationMode: 'page-table'`): posts the camera to the
      * worker, which owns the cache + traversal + pager and replies asynchronously
      * with a paging plan. Coalesced to one outstanding request so the main thread
      * never blocks. Also drives chunk fetching, in priority order.
@@ -979,8 +973,8 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * worker's cache/traversal/gather can use it. */
     private forwardChunkToWorker;
     /** Parallel chunk fetches. HTTP/2 multiplexes them; on HTTP/1.1 the browser's
-     * per-host cap simply queues. Same cap for classic and pagetable so near
-     * detail is not structurally starved on the non-pagetable path. */
+     * per-host cap simply queues. Same cap for classic and page-table so near
+     * detail is not structurally starved on the non-page-table path. */
     private get maxInflight();
     /**
      * Whether this mesh may run its speculative background sweep. A mesh with no

package/dist/streaming.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@voluma/vlam/streaming` - budgeted LOD streaming for scenes larger than
+ * GPU memory.
+ *
+ * {@link StreamedSplatMesh.load} opens Streamed SOG, LCC / `.lcc2`, and Spark
+ * `.rad`. Shared loading errors and request types are re-exported so a host
+ * that only imports this entry can still name them.
+ *
+ * Static auto-LOD lives on `@voluma/vlam/static-lod`.
+ *
+ * @module streaming
+ */
+export { StreamedSplatMesh, type StreamedSplatMeshOptions, type InitialRevealState, type PersistentChannelOptions, type StreamedSplatPerformanceEvent, } from './streamed-splat-mesh';
+export { BudgetGovernor, type BudgetGovernorOptions, type BudgetGovernedMember, } from './budget-governor';
+export { CameraBudgetGovernor, type CameraBudgetGovernorOptions, type CameraBudgetMember, type CameraBudgetMemberOptions, } from './camera-budget-governor';
+export { ChunkFetchScheduler, type ChunkFetchSchedulerOptions, type ChunkFetchClient, type ChunkFetchHandle, type ChunkFetchKind, } from './chunk-fetch-scheduler';
+export { ChunkCacheBudget, type ChunkCacheBudgetOptions, type ChunkCacheClient, type ChunkCacheHandle, } from './chunk-cache-budget';
+export { httpDatasetSource, createLocalDataset } from './dataset-source';
+export type { SplatDatasetSource, LocalDataset } from './dataset-source';
+export type { CollisionMeshTile } from './formats/lcc/collision-mesh';
+export type { SplatCollisionData, CollisionMeshDescriptor, EnvironmentTile } from './lod-source';
+export { resolveCpuCacheBytes } from './splat-budget';
+export { SplatLoadError, isAbortError, type SplatProgressCallback, type StreamedSplatFormat, type SplatRequestOptions, type SplatLoadPhase, type SplatInputOptions, } from './loading';