@voluma/vlam 0.3.2 → 0.3.4

package/dist/streaming/lod-source.d.ts

@@ -32,12 +32,17 @@ export interface LodSource {
      */
     runsAtLevelFor?(from: number, to: number, level: number): LodRun[];
     /**
-     * Coarsest covering runs for finest cells currently in the camera frustum.
-     * Used by `.lcc2` startup `initialReveal: 'hold-coverage'` so the first
-     * painted frame has no empty cells. Optional: sources without a nested
-     * octree cover leave it undefined (the hold then stays disabled).
+     * Covering runs for finest cells currently in the camera frustum (or
+     * containing the camera). Used by `.lcc` / `.lcc2` startup
+     * `initialReveal: 'hold-coverage'` so the first painted frame has no empty
+     * cells. Classic LCC freezes nearby groups at finest+1 and farther in-view
+     * groups at coarsest; `.lcc2` still returns coarsest root-children.
+     * `cameraForward` (mesh-local) lets classic LCC ignore full-Z cells that
+     * sit entirely behind the camera plane — their AABBs otherwise hit the
+     * frustum from every indoor pose. Optional: sources without coverage groups
+     * or a nested octree cover leave it undefined (the hold then stays disabled).
      */
-    coverageRunsFor?(cameraLocal: THREE.Vector3, frustum: THREE.Frustum): LodRun[];
+    coverageRunsFor?(cameraLocal: THREE.Vector3, frustum: THREE.Frustum, cameraForward?: THREE.Vector3): LodRun[];
     /**
      * Notified when a chunk finishes decoding, so a source that discovers its
      * structure from chunk payloads (a `.rad` LOD tree lives in the chunks, not
@@ -75,10 +80,11 @@ export interface StreamedChunkOptions {
 }
 /**
  * A single always-resident environment/background tile a format ships outside
- * its LOD structure - the `.lcc2` `env.sog` sky, loaded once and toggled with
- * {@link StreamedSplatMesh.setEnvironmentEnabled} rather than scheduled by
- * camera distance. Its splat count is absent from the manifest and measured
- * when the tile decodes (see `docs/formats/lcc2-notes.md`).
+ * its LOD structure - classic `.lcc` `environment.bin` and `.lcc2` `env.sog`,
+ * loaded once and toggled with {@link StreamedSplatMesh.setEnvironmentEnabled}
+ * rather than scheduled by camera distance. `.lcc2` measures the splat count
+ * at decode (see `docs/formats/lcc2-notes.md`); classic `.lcc` sizes it from
+ * the file length.
  */
 export interface EnvironmentTile {
     /** Chunk-file index (into {@link StreamedScene.chunkUrls}) of the tile. */

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

@@ -23,7 +23,8 @@ export declare function estimateSceneDecodedBytes(scene: StreamedScene): number;
 /**
  * Read-only startup-hold progress for {@link StreamedSplatMeshOptions.initialReveal}.
  * Exported for hosts that gate visibility on the first useful coverage frame
- * (classic `.lcc` nearby L0, or `.lcc2` in-view coarsest cells).
+ * (classic `.lcc` nearby L1 / far coarsest, `.lcc2` in-view coarsest, or an
+ * explicit nearby-L0 hold).
  */
 export type InitialRevealState = {
     readonly status: 'disabled';
@@ -172,28 +173,35 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * - `'progressive'`: cells become visible as each swap group commits — can
      *   show sparse near-detail (classic `.lcc`) or empty octree squares
      *   (`.lcc2`) while siblings load.
-     * - `'hold-near-l0'` (the default for classic `.lcc` when unset): hide the
-     *   mesh until the camera's home coverage group is resident (L0 when it fits;
-     *   otherwise coarsen via the leaf ladder L1→L2). Neighbours are not part of
-     *   the hold - they compete via screenImportance and would steal the first
-     *   fetch slots. Home selection uses distance within `lodBaseDistance` and
-     *   does not require frustum intersection (HiRes tiles often fail `inView`
-     *   when the camera stands inside looking out). Coarser rungs come from
-     *   `LodSource.runsAtLevelFor`. Only home files are fetched during the hold.
-     *   A one-minute watchdog also degrades if the cut cannot finish.
-     * - `'hold-coverage'` (the default for `.lcc2` when unset): hide the mesh
-     *   until every in-view finest cell has a coarsest covering node resident
-     *   (any LOD), and until the always-resident environment tile is in the pool
-     *   when the scene ships one and it starts enabled. Does not wait for finest
-     *   tiles or the rest of the stream. An empty frustum falls back to the
-     *   nearest cell. Requires `LodSource.coverageRunsFor`; other formats treat
-     *   this as disabled.
+     * - `'hold-near-l0'` (opt-in): hide the mesh until the camera's home coverage
+     *   group is resident (L0 when it fits; otherwise coarsen via the leaf ladder
+     *   L1→L2). Neighbours are not part of the hold - they compete via
+     *   screenImportance and would steal the first fetch slots. Home selection
+     *   uses distance within `lodBaseDistance` and does not require frustum
+     *   intersection (HiRes tiles often fail `inView` when the camera stands
+     *   inside looking out). Coarser rungs come from `LodSource.runsAtLevelFor`.
+     *   Only home files are fetched during the hold. A one-minute watchdog also
+     *   degrades if the cut cannot finish. Classic `.lcc` uses the **resolved**
+     *   cut from the first schedule (after camera + format transform), not
+     *   distance ambition alone.
+     * - `'hold-coverage'` (the default for classic `.lcc` and `.lcc2` when
+     *   unset): hide the mesh until every in-view finest cell has covering
+     *   coverage resident, and until the always-resident environment tile is in
+     *   the pool when the scene ships one and it starts enabled. Classic `.lcc`
+     *   freezes nearby cells (within `lodBaseDistance · lodMultiplier`) at
+     *   finest+1 (L1, never L0) and farther in-view cells at coarsest. A cell
+     *   counts as in-view when the camera stands inside it, or when the unpadded
+     *   AABB hits the frustum and pokes in front of the camera plane (support
+     *   vertex — centres behind the look still count), **or** the cell is within
+     *   `lodBaseDistance` and pokes forward (30 m neighbours that fill the
+     *   frame while the look is off-axis). `.lcc2` still waits on
+     *   coarsest root-children. Does not wait for finest tiles or the rest of
+     *   the stream. An empty frustum falls back to the nearest cell. Requires
+     *   `LodSource.coverageRunsFor`; other formats treat this as disabled.
      *
      * A one-minute watchdog degrades to progressive if the frozen set cannot
-     * finish. Does not make detail downloads instantaneous. Classic `.lcc` uses
-     * the **resolved** cut from the first schedule (after camera + format
-     * transform), not distance ambition alone. Other streamed formats default
-     * to `'progressive'`.
+     * finish. Does not make detail downloads instantaneous. Other streamed
+     * formats default to `'progressive'`.
      */
     initialReveal?: 'progressive' | 'hold-near-l0' | 'hold-coverage';
     /** Receives lightweight LOD mutation events for performance attribution. */
@@ -927,11 +935,19 @@ export declare class StreamedSplatMesh extends SplatMesh {
     private publishInitialRevealProgress;
     private releaseInitialReveal;
     /**
-     * `.lcc2` coverage hold: freeze coarsest covering runs for in-view cells.
+     * Coverage hold: freeze covering runs for in-view cells (classic `.lcc`
+     * physical cells at L1 near / coarsest far, `.lcc2` octree root-children).
      * Missing `coverageRunsFor` (or an empty result after fallback) releases
      * immediately so the mesh does not stay hidden with nothing to fetch.
+     * If the mixed set overflows the pool, coarsen only the near (non-coarsest)
+     * groups one more rung before degrading to progressive.
      */
     private captureCoverageHold;
+    /**
+     * Bump each coverage run one coarser rung when the source has one. Already-
+     * coarsest (far) runs stay put so a tight pool only drops near L1 → L2.
+     */
+    private coarsenCoverageNearRuns;
     private captureOrContinueInitialReveal;
     /** After staging/commits, release the hold when every frozen run is resident. */
     private finishInitialRevealIfComplete;