@babylonjs/loaders 9.26.1 → 9.26.2

package/SPLAT/gaussianSplattingStream.d.ts

@@ -129,17 +129,20 @@ export interface IGaussianSplattingStreamOptions {
     /** Number of times a failed file download is retried before giving up. PlayCanvas default `2`. */
     maxDownloadRetries?: number;
     /**
-     * GPU memory budget (in megabytes) for resident splats. When set (and smaller than the full dataset),
-     * LOD files are streamed through a fixed-size work buffer and unreferenced files are evicted to stay
-     * within budget, allowing datasets larger than a single full-dataset buffer. Converted to a splat count
-     * using the per-splat cost (core data plus any baked SH and rotation/scale textures). Combined with
-     * {@link maxResidentSplats} by taking the smaller of the two.
+     * Initial GPU/CPU memory estimate (in megabytes) for resident splats. It is converted to a splat count
+     * using the per-splat cost (core data plus any baked SH and rotation/scale textures), combined with
+     * {@link maxResidentSplats} by taking the smaller limit, then raised when necessary to fit the complete
+     * coarse layer. The work buffer has a fixed lifetime capacity; construct a new stream to use another limit.
+     * Finite non-positive values leave this limit unset; non-finite values are rejected.
      */
     memoryBudgetMb?: number;
     /**
-     * Maximum number of splats kept resident in the work buffer. When set (and smaller than the full
-     * dataset), enables eviction-based streaming (see {@link memoryBudgetMb}). Default unset = size the work
-     * buffer for the whole dataset (no eviction).
+     * Initial maximum number of splats kept resident in the fixed-size work buffer. It is raised when necessary
+     * to fit the complete coarse layer. When unset and the complete source size is known, streams retain the complete
+     * source. Streams that defer finer metadata use a bounded device-tiered default with coarse-derived refinement
+     * headroom.
+     * Finite non-positive values leave this limit unset; non-finite or unsafe positive counts are rejected.
+     * Positive fractional counts are floored to at least one splat before applying the coarse minimum.
      */
     maxResidentSplats?: number;
     /**
@@ -169,10 +172,10 @@ export interface IGaussianSplattingStreamOptions {
     /**
      * When true, higher-order spherical-harmonics carried by the SOG files (`shN`) are GPU-decoded into baked
      * packed-u32 SH textures so the streamed splats render with view-dependent lighting (matching the non-stream
-     * `.spz`/`.sog` path) instead of flat DC-only color. The SH degree is the max `shN.bands` across the streamed
-     * files (lower-band files neutral-fill). No effect when the files carry no `shN`. Defaults to `true`, matching
-     * the non-stream path's always-decode-if-present behavior; set to `false` to force flat DC-only color even
-     * when the data carries `shN` (e.g. to save the decode cost/texture memory).
+     * `.spz`/`.sog` path) instead of flat DC-only color. Streams with complete initial metadata use the maximum
+     * source SH degree. Streams that defer finer metadata reserve the supported degree-4 layout before it is known,
+     * even if the files ultimately carry no `shN`; lower-degree files neutral-fill the unused bands.
+     * Defaults to `true`; set to `false` to force flat DC-only color and avoid the SH decode cost/texture memory.
      */
     decodeSh?: boolean;
     /**
@@ -217,6 +220,7 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
     private _hostBudgetAllocation;
     private _frustumCulling;
     private readonly _frustumPlanes;
+    private readonly _cullCameraViewProj;
     private readonly _cullViewProj;
     private readonly _frustumScratch;
     private _workBuffer;
@@ -230,6 +234,7 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
     private _residency;
     private readonly _fileCounts;
     private readonly _fileMeta;
+    private readonly _baseFileIds;
     private readonly _decodedFiles;
     private readonly _loadingFiles;
     private readonly _decodeQueue;
@@ -237,6 +242,7 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
     private readonly _cancelledDecodes;
     private _evictionEnabled;
     private _residentBudget;
+    private _minimumResidentSplats;
     private _maxResidentSplats;
     private _memoryBudgetMb;
     private _evictionCooldownFrames;
@@ -248,6 +254,7 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
     private _environmentFiles;
     private _lodObserver;
     private _baseLayerReady;
+    private _metadataReady;
     private _framesSinceLodUpdate;
     private readonly _lastLodCamPositions;
     private _lastLodSignature;
@@ -370,10 +377,19 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
     /**
      * 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.
+     * taking the smaller positive limit and raising it to {@link minimumResidentSplats}. With neither limit set,
+     * the complete source size is retained when known; otherwise a bounded device-tiered default is used.
+     * The fixed capacity is capped at the device texture limit. `0` means initial capacity has not been resolved.
      * @experimental
      */
     get residentSplatBudget(): number;
+    /**
+     * Minimum fixed work-buffer capacity required for the complete coarse representation: one invisible padding
+     * splat, the included environment, and every unique whole coarse source file. It is `0` until the required
+     * coarse metadata has resolved. Initial residency options below this value are raised to it.
+     * @experimental
+     */
+    get minimumResidentSplats(): 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.
@@ -448,14 +464,14 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
     set debugLodSource(value: GaussianSplattingStreamDebugLodSource);
     dispose(doNotRecurse?: boolean): void;
     /**
-     * Disposes this stream (which tombstones its region) and then compacts the host once to actually reclaim the
-     * reserved rows. Used on a definitive load failure / empty result — a discrete, one-off reclaim, versus a bare
+     * Disposes this stream and, when hosted, compacts the host once to reclaim its tombstoned region's reserved
+     * rows. Used on a definitive load failure / empty result — a discrete, one-off reclaim, versus a bare
      * {@link dispose} that only tombstones so tearing down several parts doesn't rebuild the atlas repeatedly.
      */
     private _disposeAndReclaim;
     /**
      * The world matrix that actually places this stream's splats, used to map the camera into the space the
-     * node bounds live in (for LOD distance) and to build per-node world AABBs (for frustum culling). Standalone:
+     * node bounds live in (for LOD distance) and to build camera-local frusta (for frustum culling). Standalone:
      * this controller mesh carries the transform. Hosted: this controller is a hidden, unplaced node — the splats
      * are placed by the reserved part's proxy (SOG up-axis basis composed with the host's placement), so LOD and
      * culling MUST use the proxy's world matrix or they compute distances/frustum tests in the wrong space
@@ -523,9 +539,9 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
      */
     private _collectLodEntries;
     /**
-     * Streams the scene: learns every source file's splat count, allocates one unified GPU work buffer
-     * sized for all LOD files, decodes the environment and the coarsest LOD of every node as a permanent
-     * base layer, then installs the per-frame loop that streams finer LODs on demand.
+     * Streams the scene. Large streams fetch only required coarse metadata before allocating and decoding the
+     * complete coarse layer; finer metadata starts afterwards so it cannot occupy the download queue ahead of
+     * visible geometry. Small streams and streams containing only coarse files retain an exact all-file capacity upper bound.
      */
     private _streamAllAsync;
     /**
@@ -538,26 +554,47 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
      */
     private _waitForCanBackupAsync;
     /**
-     * Resolves the resident-splat budget from the raw options, sizing a memory (MB) budget with the actual per-splat
-     * GPU+CPU cost — core data plus the baked SH textures and rotation/scale textures when enabled — so SH/rotation
-     * assets don't silently consume up to double the configured budget. Requires the SH degree (from the metadata
-     * pre-pass) to be known. The smaller of the splat-count and memory budgets wins.
+     * Resolves the fixed initial work-buffer capacity. Explicit count/MB limits are combined by taking the smaller
+     * and then raised to the complete coarse minimum. Without an explicit limit, a known complete source retains
+     * legacy full residency. When finer metadata is deferred and the complete size is unknown, the device-tiered
+     * memory estimate is given at least one largest-coarse-file of headroom so one replacement file can refine
+     * while all coarse fallback files remain pinned.
+     * @param fullCapacity exact complete source capacity, or null when unavailable
+     * @param largestBaseFileCount largest whole coarse source file, used as modest replacement headroom
+     * @returns the fixed initial work-buffer capacity
      */
     private _resolveResidentBudget;
+    /**
+     * Returns the estimated combined GPU/CPU bytes occupied by one resident splat.
+     * @returns estimated bytes per resident splat
+     */
+    private _bytesPerResidentSplat;
     /**
      * Collects the unique set of source file indices referenced by any LOD of any leaf, sorted ascending.
      * @returns sorted unique file indices
      */
     private _collectAllFileIds;
+    /**
+     * Collects unique whole source files required by the coarsest entry of every valid leaf.
+     * @returns sorted unique coarse file indices
+     */
+    private _collectBaseFileIds;
+    /**
+     * Resolves the immutable minimum initial capacity from padding, environment, and unique whole coarse files.
+     * @param baseFileIds unique coarse source file indices
+     * @param environmentCount included environment splat count
+     */
+    private _resolveMinimumResidentSplats;
     /**
      * 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.
+     * Fetches the environment bundle and the supplied referenced files' metadata to learn splat counts, caching
+     * each file's parsed metadata for the later on-demand decode. File metadata fetches run in parallel.
      * @param fileIds file indices to fetch metadata for
+     * @param includeEnvironment whether to fetch the optional environment bundle in this phase
      * @returns the environment splat count (0 when there is no environment)
      */
     private _gatherCountsAsync;
@@ -625,6 +662,7 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
      * Concurrent or repeat requests for the same file are ignored. If the file is cancelled mid-flight
      * (because every node that wanted it retargeted), the decode bails cooperatively at the next checkpoint.
      * @param fileId file index to decode
+     * @returns whether the file was decoded and published successfully
      */
     private _decodeFileAsync;
     /**
@@ -789,6 +827,22 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh imple
      * @returns whether any node's in-frustum state changed
      */
     private _updateNodeFrustum;
+    /**
+     * Normalizes an initial residency option, preserving finite non-positive values as an unset limit.
+     * @param value option value
+     * @param name option name used in errors
+     * @param integer whether the normalized value must be an integer splat count
+     * @returns normalized value
+     */
+    private static _NormalizeResidentLimit;
+    /**
+     * Adds trusted non-negative integer counts without allowing unsafe capacity arithmetic.
+     * @param left first count
+     * @param right second count
+     * @param label capacity name used in errors
+     * @returns the safe integer sum
+     */
+    private static _SafeAddCounts;
     /**
      * Reads the splat count from SOG metadata, coerced to a finite non-negative integer (metadata is untrusted, so
      * `count` / `shape[0]` may be a string or malformed — a non-numeric value must not leak into count arithmetic).