@onerjs/loaders 8.56.1 → 8.56.2

package/SPLAT/gaussianSplattingStream.d.ts

@@ -71,6 +71,18 @@ export interface ISOGLODMetadata {
  * Selects which LOD value drives the {@link GaussianSplattingStream} debug wireframe colors.
  */
 export type GaussianSplattingStreamDebugLodSource = "optimal" | "current";
+/**
+ * Immutable metadata-resolution state for a stream's total number of finest-LOD splats.
+ * @experimental
+ */
+export type GaussianSplattingStreamLod0SplatCount = Readonly<{
+    status: "pending";
+}> | Readonly<{
+    status: "available";
+    count: number;
+}> | Readonly<{
+    status: "unavailable";
+}>;
 /**
  * Options for {@link GaussianSplattingStream}.
  */
@@ -190,6 +202,7 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
     private readonly _rootUrl;
     private readonly _streamOptions;
     private readonly _leafNodes;
+    private _lod0SplatCount;
     private _lodBaseDistance;
     private _lodMultiplier;
     private _lodBehindPenalty;
@@ -354,6 +367,19 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
      * @experimental
      */
     get effectiveSplatBudget(): number;
+    /**
+     * The resolved maximum number of splats kept resident in the work buffer. This combines
+     * {@link IGaussianSplattingStreamOptions.maxResidentSplats} and {@link IGaussianSplattingStreamOptions.memoryBudgetMb},
+     * taking the smaller limit when both are configured. `0` means the resident budget is disabled.
+     * @experimental
+     */
+    get residentSplatBudget(): number;
+    /**
+     * The total number of splats represented by valid level-0 leaf entries. This remains pending while source
+     * metadata is loading and is unavailable when no applicable level-0 entries exist or required metadata fails.
+     * @experimental
+     */
+    get lod0SplatCount(): GaussianSplattingStreamLod0SplatCount;
     /**
      * Resolves the raw {@link splatBudget} option to a concrete cap: `undefined` ⇒ 0 (disabled), `"auto"` ⇒ a
      * device-tiered default, a positive number ⇒ itself (floored).
@@ -523,6 +549,11 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
      * @returns sorted unique file indices
      */
     private _collectAllFileIds;
+    /**
+     * Settles the level-0 diagnostic from normalized renderable leaf entries after their source metadata resolves.
+     * A file may back several leaf ranges, so its source count is deliberately not used in the total.
+     */
+    private _resolveLod0SplatCount;
     /**
      * Fetches the environment bundle and every referenced file's metadata to learn splat counts, caching
      * each file's parsed metadata for the later on-demand decode. Metadata fetches run in parallel.

package/SPLAT/gaussianSplattingStream.js

@@ -97,6 +97,7 @@ export class GaussianSplattingStream extends GaussianSplattingMesh {
         super(name, null, scene, false);
         // Flat list of leaf nodes that carry renderable LOD entries (used by the LOD heuristic and debug).
         this._leafNodes = [];
+        this._lod0SplatCount = Object.freeze({ status: "pending" });
         // LOD heuristic parameters (PlayCanvas-aligned defaults).
         this._lodBaseDistance = 5;
         this._lodMultiplier = 3;
@@ -344,6 +345,7 @@ export class GaussianSplattingStream extends GaussianSplattingMesh {
                 this._disposeAndReclaim();
             }
         }, (e) => {
+            this._lod0SplatCount = Object.freeze({ status: "unavailable" });
             Logger.Error("GaussianSplattingStream: streaming failed: " + (e?.message ?? e));
             this._rejectPartReady("GaussianSplattingStream: streaming failed: " + (e?.message ?? e));
             if (this._hostCompound && !this._disposed) {
@@ -533,6 +535,23 @@ export class GaussianSplattingStream extends GaussianSplattingMesh {
     get effectiveSplatBudget() {
         return this._effectiveSplatBudget();
     }
+    /**
+     * The resolved maximum number of splats kept resident in the work buffer. This combines
+     * {@link IGaussianSplattingStreamOptions.maxResidentSplats} and {@link IGaussianSplattingStreamOptions.memoryBudgetMb},
+     * taking the smaller limit when both are configured. `0` means the resident budget is disabled.
+     * @experimental
+     */
+    get residentSplatBudget() {
+        return this._residentBudget;
+    }
+    /**
+     * The total number of splats represented by valid level-0 leaf entries. This remains pending while source
+     * metadata is loading and is unavailable when no applicable level-0 entries exist or required metadata fails.
+     * @experimental
+     */
+    get lod0SplatCount() {
+        return this._lod0SplatCount;
+    }
     /**
      * Resolves the raw {@link splatBudget} option to a concrete cap: `undefined` ⇒ 0 (disabled), `"auto"` ⇒ a
      * device-tiered default, a positive number ⇒ itself (floored).
@@ -1113,6 +1132,7 @@ export class GaussianSplattingStream extends GaussianSplattingMesh {
         // resolves the max SH degree, so the resident-splat budget can now be sized with the SH/rotation byte cost.
         const fileIds = this._collectAllFileIds();
         const envCount = await this._gatherCountsAsync(fileIds);
+        this._resolveLod0SplatCount();
         if (this._disposed) {
             return;
         }
@@ -1335,6 +1355,35 @@ export class GaussianSplattingStream extends GaussianSplattingMesh {
         }
         return Array.from(ids).sort((a, b) => a - b);
     }
+    /**
+     * Settles the level-0 diagnostic from normalized renderable leaf entries after their source metadata resolves.
+     * A file may back several leaf ranges, so its source count is deliberately not used in the total.
+     */
+    _resolveLod0SplatCount() {
+        let total = 0;
+        let hasLod0Entry = false;
+        for (const node of this._leafNodes) {
+            if (node.availableLevels?.[0] !== 0) {
+                continue;
+            }
+            const entry = node.lods?.["0"];
+            if (!entry) {
+                this._lod0SplatCount = Object.freeze({ status: "unavailable" });
+                return;
+            }
+            hasLod0Entry = true;
+            if (!this._fileCounts.has(entry.file) || !this._fileMeta.has(entry.file)) {
+                this._lod0SplatCount = Object.freeze({ status: "unavailable" });
+                return;
+            }
+            total += entry.count;
+            if (!Number.isSafeInteger(total)) {
+                this._lod0SplatCount = Object.freeze({ status: "unavailable" });
+                return;
+            }
+        }
+        this._lod0SplatCount = hasLod0Entry ? Object.freeze({ status: "available", count: total }) : Object.freeze({ status: "unavailable" });
+    }
     /**
      * Fetches the environment bundle and every referenced file's metadata to learn splat counts, caching
      * each file's parsed metadata for the later on-demand decode. Metadata fetches run in parallel.