@babylonjs/loaders 9.19.1 → 9.20.1

package/SPLAT/gaussianSplattingStream.d.ts

@@ -1,4 +1,5 @@
 import { GaussianSplattingMesh } from "@babylonjs/core/Meshes/GaussianSplatting/gaussianSplattingMesh.js";
+import { type GaussianSplattingPartProxyMesh } from "@babylonjs/core/Meshes/GaussianSplatting/gaussianSplattingPartProxyMesh.js";
 import { type Scene } from "@babylonjs/core/scene.js";
 import { type Nullable } from "@babylonjs/core/types.js";
 import { Camera } from "@babylonjs/core/Cameras/camera.js";
@@ -116,7 +117,8 @@ export interface IGaussianSplattingStreamOptions {
      * 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
-     * at ~84 bytes/splat. Combined with {@link maxResidentSplats} by taking the smaller of the two.
+     * 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.
      */
     memoryBudgetMb?: number;
     /**
@@ -130,6 +132,30 @@ export interface IGaussianSplattingStreamOptions {
      * return to it avoids a re-download. Only used when a budget enables eviction. PlayCanvas default `100`.
      */
     evictionCooldownFrames?: number;
+    /**
+     * When set, the stream does not render itself; instead it reserves a region of this compound mesh and
+     * decodes/sorts into it, so its splats are depth-sorted and drawn in ONE pass together with the compound's
+     * other (static) parts. Used by {@link AddGaussianSplattingStreamPart}. The stream mesh becomes a hidden
+     * controller; the SOG up-axis orientation is applied to the reserved part's proxy transform.
+     * @internal
+     */
+    hostCompound?: GaussianSplattingMesh;
+    /**
+     * 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).
+     */
+    decodeSh?: boolean;
+    /**
+     * When true, each splat's rotation matrix + scale are GPU-decoded into half-float rotation/scale textures so the
+     * streamed splats participate in voxel-based IBL shadowing (matching the non-stream path). Standalone: the work
+     * buffer owns the rotation textures. Hosted: the compound's rotation textures become a shared render-target atlas
+     * the stream decodes into. Defaults to `false`.
+     */
+    needsRotationScale?: boolean;
 }
 /**
  * Streams a PlayCanvas-style SOG LOD scene (`lod-meta.json`) into a single Gaussian Splatting mesh.
@@ -164,6 +190,10 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
     private readonly _frustumPlanes;
     private readonly _cullViewProj;
     private _workBuffer;
+    private _decodeSh;
+    private _streamShDegree;
+    private _shTextureCount;
+    private _needsRotationScale;
     private _useGpuPositionReadback;
     private _readbackCandidate;
     private _readbackProbed;
@@ -177,6 +207,8 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
     private readonly _cancelledDecodes;
     private _evictionEnabled;
     private _residentBudget;
+    private _maxResidentSplats;
+    private _memoryBudgetMb;
     private _evictionCooldownFrames;
     private _decodeGate;
     private readonly _relayoutOldOffsets;
@@ -198,6 +230,19 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
     private _debugColorData;
     private _debugSignature;
     private _disposed;
+    private readonly _hostCompound;
+    private _host;
+    private _positionBase;
+    private _unsubBeforeRebuild;
+    private _unsubAfterRebuild;
+    private _hostUnsubRemove;
+    private _hostUnsubDispose;
+    private _partReleasedByHost;
+    private _positionSnapshot;
+    private _partReadyPromise;
+    private _partReadyResolve;
+    private _partReadyReject;
+    private _partReadySettled;
     /**
      * Returns true when the parsed JSON looks like a PlayCanvas-style `lod-meta.json` payload.
      * @param data parsed JSON
@@ -214,6 +259,35 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
      */
     constructor(name: string, metadata: ISOGLODMetadata, rootUrl: string, scene: Scene, options?: IGaussianSplattingStreamOptions);
     getClassName(): string;
+    /**
+     * When `_hostCompound` is set (i.e. this stream was created via {@link AddGaussianSplattingStreamPart}
+     * to drive a reserved region of another compound mesh, rather than rendering itself), this instance is
+     * disabled and never drawn — so it never runs its own depth-sort worker and the base class's readiness
+     * check (which waits for one) would never pass. Report ready unconditionally in that case; the host
+     * compound is the one actually rendering, and its own `isReady()` already covers real sort completion.
+     * @param completeCheck defines if a complete check (including materials and lights) has to be done (false by default)
+     * @returns true when ready
+     */
+    isReady(completeCheck?: boolean): boolean;
+    /**
+     * Hosted mode only: the compound part proxy this stream drives (world transform + visibility of the
+     * reserved region), or null before the part has been reserved (or when running standalone).
+     */
+    get streamingPartProxy(): Nullable<GaussianSplattingPartProxyMesh>;
+    /**
+     * Hosted mode only: resolves once the reserved part exists and its base layer has decoded (so the proxy's
+     * bounds are real and the part is ready to be placed/framed), or rejects if streaming fails/disposes first.
+     * Resolves immediately for a standalone stream. Used by {@link AddGaussianSplattingStreamPartAsync}.
+     * @returns a promise that settles when the hosted part is ready to use
+     */
+    whenPartReadyAsync(): Promise<void>;
+    /** Resolves the part-ready deferred (hosted mode); no-op if already settled or standalone. */
+    private _resolvePartReady;
+    /**
+     * Rejects the part-ready deferred (hosted mode); no-op if already settled or standalone.
+     * @param message failure reason surfaced to the awaiter
+     */
+    private _rejectPartReady;
     /**
      * Resolves once the scene is fully streamed and displayed for the current camera: a LOD re-evaluation has
      * run for the current point of view, every reachable LOD file has finished downloading and decoding (no
@@ -269,6 +343,23 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
     get debugLodSource(): GaussianSplattingStreamDebugLodSource;
     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
+     * {@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:
+     * 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
+     * (producing wrong per-chunk LODs, i.e. holes, whenever the host applies a non-identity transform).
+     * @param force when true, forces a full world-matrix recompute (else uses the renderId/sync fast-path)
+     * @returns the effective world matrix for LOD/culling
+     */
+    private _getEffectiveWorldMatrix;
     /**
      * Re-evaluates the optimal LOD for every node based on the camera position. The result is stored in
      * each node's `optimalLod`. Rendering is unaffected; this currently drives only diagnostics and the
@@ -326,6 +417,22 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
      * base layer, then installs the per-frame loop that streams finer LODs on demand.
      */
     private _streamAllAsync;
+    /**
+     * Waits (up to a frame cap) until the work buffer's backup/restore copy shaders are compiled, so a later
+     * grow/compaction can preserve this hosted region (see {@link GaussianSplattingWorkBuffer.backupRegion}).
+     * Polls per rendered frame: shader readiness here depends on the render loop (and the shared atlas can be
+     * rebuilt concurrently), so this stays synchronized with the render-driven decode and always makes progress.
+     * On timeout it proceeds best-effort — a subsequent grow/compaction then warns rather than blocking decode.
+     * @param wb the hosted work buffer to wait on
+     */
+    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.
+     */
+    private _resolveResidentBudget;
     /**
      * Collects the unique set of source file indices referenced by any LOD of any leaf, sorted ascending.
      * @returns sorted unique file indices
@@ -356,6 +463,21 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
      * @param count number of splats in the range
      */
     private _applyPositions;
+    /**
+     * Sets the active source ranges (local to the stream's buffer) on the render sink.
+     * @param localRanges active ranges in the stream's local index space
+     */
+    private _sinkSetActiveRanges;
+    /**
+     * Patches a decoded position range (local offset) into the render sink's sort worker.
+     * @param base first splat index of the range, local to the stream's buffer
+     * @param count number of splats in the range
+     */
+    private _sinkPostPositionsRange;
+    /** Re-posts the full position/part set to the render sink's worker (after a relayout moved the region). */
+    private _sinkNotifyDataChanged;
+    /** Whether the render sink's depth sort is settled. */
+    private get _sinkIsDepthSortSettled();
     /**
      * One-time validation of GPU position readback: reads a sample of the just-decoded range back from the work
      * buffer and compares it to the CPU-decoded positions. Enables {@link _useGpuPositionReadback} only on an
@@ -496,6 +618,13 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
      * @returns the splat count
      */
     private static _GetSplatCount;
+    /**
+     * Reads a SOG file's higher-order SH degree and coefficient count from its metadata, mirroring
+     * {@link ParseSogDatas}'s `coeffs`/`shDegree` derivation. Returns zeros when the file carries no `shN`.
+     * @param data parsed SOG root metadata
+     * @returns the SH degree and higher-order coefficient count (excludes the DC/SH0 term)
+     */
+    private static _GetShInfo;
     /**
      * Disposes all GPU source textures of a SOG pack (they are only needed for the one decode pass).
      * @param pack the SOG texture pack
@@ -526,4 +655,44 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
      */
     private _unzipAsync;
 }
+/**
+ * Adds a PlayCanvas-style SOG LOD stream as a part of a compound Gaussian Splatting mesh, so the streamed
+ * splats are depth-sorted and rendered in ONE pass together with the compound's other (static) parts.
+ *
+ * The returned mesh is a hidden controller: it streams SOG LOD files, GPU-decodes them into a reserved region
+ * of the compound's shared atlas, and drives which of its splats are active (LOD) — the compound owns the sort
+ * and the single instanced draw. The SOG up-axis orientation is applied to the reserved part's proxy transform;
+ * move/hide the part via the proxy (`streamController` exposes it once streaming has started).
+ * @param compound the compound mesh to add the streamed part to
+ * @param name name for the streaming controller / part
+ * @param metadata parsed `lod-meta.json`
+ * @param rootUrl base URL the metadata's relative paths resolve against
+ * @param options streaming options
+ * @returns the streaming controller mesh (hidden; drives the reserved compound part)
+ * @experimental
+ */
+export declare function AddGaussianSplattingStreamPart(compound: GaussianSplattingMesh, name: string, metadata: ISOGLODMetadata, rootUrl: string, options?: IGaussianSplattingStreamOptions): GaussianSplattingStream;
+/**
+ * Adds a PlayCanvas-style SOG LOD stream as a part of a compound Gaussian Splatting mesh and resolves once the
+ * part is ready to use, returning its {@link GaussianSplattingPartProxyMesh} — the same handle
+ * `GaussianSplattingCompoundMesh.addPart` returns for a static part. This lets a host application treat a
+ * streamed splat exactly like any other compound part (place/frame/gizmo via the proxy, remove via
+ * `compound.removePart(proxy.partIndex)`); the streaming controller lives behind the proxy and is disposed
+ * automatically when the part is removed.
+ *
+ * Resolves after the reserved region exists and its base layer has decoded (so the proxy's bounds are real),
+ * and rejects if streaming fails before that (the partially-constructed stream is disposed on rejection).
+ *
+ * NOTE: the base-layer decode runs on the GPU inside the scene's render loop, so this promise only resolves once
+ * the scene is rendering. Do not `await` it before the render loop has started (it would never resolve) — start
+ * rendering (e.g. `engine.runRenderLoop`) first, or `await` it concurrently with the first frames.
+ * @param compound the compound mesh to add the streamed part to
+ * @param name name for the streaming controller / part
+ * @param metadata parsed `lod-meta.json`
+ * @param rootUrl base URL the metadata's relative paths resolve against
+ * @param options streaming options
+ * @returns the part proxy driving the streamed region, ready to place/frame
+ * @experimental
+ */
+export declare function AddGaussianSplattingStreamPartAsync(compound: GaussianSplattingMesh, name: string, metadata: ISOGLODMetadata, rootUrl: string, options?: IGaussianSplattingStreamOptions): Promise<GaussianSplattingPartProxyMesh>;
 export {};