babylonjs-loaders 9.12.1 → 9.13.0

package/babylonjs.loaders.d.ts

@@ -7418,9 +7418,13 @@ declare namespace BABYLON {
      * @param dataOrFiles Either the SOGRootData or a Map of filenames to Uint8Array file data (including meta.json)
      * @param rootUrl Base URL to load webp files from (if dataOrFiles is SOGRootData)
      * @param scene The Babylon.js scene
+     * @param computeCpuPositions When true (default), means_l/means_u are read back on the CPU and `pack.positions`
+     *   is decoded for the sort worker / bounding box. Pass false when the caller will instead read the decoded
+     *   centers back from the GPU work buffer — then every attribute (including means) uses the fast direct
+     *   ImageBitmap upload (no `getImageData` readback) and `pack.positions` is left empty.
      * @returns Parsed splat info with `sogTextures` populated.
      */
-    export function ParseSogMetaAsTextures(dataOrFiles: SOGRootData | Map<string, Uint8Array>, rootUrl: string, scene: Scene): Promise<IParsedSplat>;
+    export function ParseSogMetaAsTextures(dataOrFiles: SOGRootData | Map<string, Uint8Array>, rootUrl: string, scene: Scene, computeCpuPositions?: boolean): Promise<IParsedSplat>;
 
 
 
@@ -7470,6 +7474,13 @@ declare namespace BABYLON {
         private readonly _material;
         private readonly _quad;
         private _disposed;
+        private _readFbo;
+        /**
+         * True when the engine supports the non-blocking GPU readback used by {@link readCentersRangeAsync}:
+         * WebGL2 (PBO + fence) or WebGPU (copyTextureToBuffer + mapAsync). When false (e.g. WebGL1), callers must
+         * decode positions on the CPU instead.
+         */
+        get supportsAsyncCentersReadback(): boolean;
         /**
          * Square edge length (in pixels) of the work-buffer textures.
          */
@@ -7492,6 +7503,18 @@ declare namespace BABYLON {
          * @param offset first splat index (pixel offset) for this file in the work buffer
          */
         decodeAsync(pack: ISogTexturePack, offset: number): Promise<void>;
+        /**
+         * Asynchronously reads back the decoded splat centers (stride-4 xyzw, w=1) for a contiguous splat range
+         * from the work buffer's centers texture, using a non-blocking GPU readback (WebGL2 PBO + fence, or WebGPU
+         * copyTextureToBuffer + mapAsync) so it never stalls the frame the way a CPU image decode does. The centers
+         * texture already holds the GPU-decoded positions (identical to the CPU decode), so this replaces decoding
+         * positions on the CPU from the means images. Returns null when async readback is unsupported (caller should
+         * fall back to CPU decoding).
+         * @param splatOffset first splat index of the range
+         * @param splatCount number of splats in the range
+         * @returns a stride-4 Float32Array of length `splatCount * 4`, or null when unsupported/failed
+         */
+        readCentersRangeAsync(splatOffset: number, splatCount: number): Promise<Nullable<Float32Array>>;
         /**
          * Disposes the work buffer and its decode resources.
          */
@@ -7537,6 +7560,11 @@ declare namespace BABYLON {
         targetLevel?: number;
         /** Frames remaining before this node may switch LOD again (oscillation damping). */
         lodCooldown?: number;
+        /** True when the node's bounding box currently intersects the camera frustum. Drives the LOD bias that
+         * pushes off-screen nodes to the coarsest level (they stay rendered, not hidden). */
+        inFrustum?: boolean;
+        /** Cached local-space bounding info used for the per-node frustum test (created once per leaf). */
+        cullBounds?: BoundingInfo;
     }
     /**
      * Parsed contents of a PlayCanvas-style `lod-meta.json` file.
@@ -7590,6 +7618,12 @@ declare namespace BABYLON {
          * `1` caps detail at the next-coarser level, and so on. Higher values force a coarser maximum detail.
          */
         maxDetailLod?: number;
+        /**
+         * When true (default), LOD nodes outside the camera frustum are biased to their coarsest LOD rather than
+         * rendered at full detail. They stay in the sort/render set so they appear instantly (at low detail) when
+         * the camera turns toward them, then refine. Set to `false` to render every node at its distance LOD.
+         */
+        frustumCulling?: boolean;
     }
     /**
      * Streams a PlayCanvas-style SOG LOD scene (`lod-meta.json`) into a single Gaussian Splatting mesh.
@@ -7620,7 +7654,13 @@ declare namespace BABYLON {
         private _lodUpdateInterval;
         private _lodUpdateDistance;
         private _maxDetailLod;
+        private _frustumCulling;
+        private readonly _frustumPlanes;
+        private readonly _cullViewProj;
         private _workBuffer;
+        private _useGpuPositionReadback;
+        private _readbackCandidate;
+        private _readbackProbed;
         private readonly _fileBaseSplat;
         private readonly _fileCounts;
         private readonly _fileMeta;
@@ -7671,6 +7711,14 @@ declare namespace BABYLON {
          * for {@link maxDetailLod}.
          */
         get maxLodLevel(): number;
+        /**
+         * When true (default), nodes whose bounding box is outside the camera frustum are biased to the coarsest
+         * LOD instead of being hidden. They stay in the sort/render set (their off-screen splats are clipped), so
+         * turning the camera toward them shows low detail immediately with no invisible frames, then refines.
+         * Changes take effect in real time.
+         */
+        get frustumCulling(): boolean;
+        set frustumCulling(value: boolean);
         /**
          * When true, renders a wireframe box per LOD node, colored by the LOD level selected by {@link debugLodSource}.
          */
@@ -7762,6 +7810,35 @@ declare namespace BABYLON {
          * and promote any waiting nodes once they complete.
          */
         private _pumpDecodeQueue;
+        /**
+         * Writes a decoded splat range's positions into the shared buffer, expands the bounds, and incrementally
+         * patches the sort worker.
+         * @param positions stride-4 positions for the range
+         * @param base first splat index of the range in the work buffer
+         * @param count number of splats in the range
+         */
+        private _applyPositions;
+        /**
+         * 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
+         * exact (within float tolerance) match, so an unsupported or incorrect readback (e.g. a backend without the
+         * required texture usage, or an orientation mismatch) safely keeps the CPU decode path.
+         * @param base first splat index of the validated range
+         * @param count number of splats in the range
+         * @param cpuPositions the CPU-decoded stride-4 positions for the range (ground truth)
+         */
+        private _probeReadbackAsync;
+        /**
+         * Resolves the decoded positions for a splat range and applies them. Once GPU readback has been validated,
+         * positions are read back from the work buffer (non-blocking) and `pack.positions` is empty; otherwise the
+         * CPU-decoded `pack.positions` are used, and — on the first such decode — the GPU readback is validated
+         * against them so subsequent decodes can use the fast path.
+         * @param pack the parsed SOG pack (its `positions` is populated only on the CPU path)
+         * @param base first splat index of the range in the work buffer
+         * @param count number of splats in the range
+         * @returns whether positions were applied
+         */
+        private _applyDecodedPositionsAsync;
         /**
          * Decodes the always-on environment bundle into its work-buffer block and activates its range.
          */
@@ -7795,13 +7872,21 @@ declare namespace BABYLON {
          */
         private _applyDesiredLods;
         /**
-         * Per-frame LOD streaming loop. Ticks cooldowns and pumps the decode queue every frame, but throttles
-         * the expensive LOD re-evaluation (optimal-LOD computation, budget balancing, desired-LOD application
-         * and interval rebuild) to run at most every {@link _lodUpdateInterval} frames and only after the camera
-         * has moved far enough, so continuous camera motion no longer rebuilds the interval set every frame. A
-         * budget change forces a single immediate update regardless of the throttle.
+         * Per-frame LOD streaming loop. Ticks cooldowns and pumps the decode queue every frame, and runs the
+         * cheap per-node frustum test every frame so the off-screen LOD bias tracks camera rotation. The LOD
+         * re-evaluation is throttled to at most every {@link _lodUpdateInterval} frames once the camera has
+         * translated far enough, but also runs immediately whenever a node enters/leaves the frustum (so its
+         * detail upgrades/downgrades promptly) or a cap change forces it. Active ranges rebuild on any LOD change.
          */
         private _onLodFrame;
+        /**
+         * Updates each leaf node's {@link ISOGLODNode.inFrustum} flag from a per-node frustum test against the
+         * active camera. When {@link frustumCulling} is disabled (or there is no camera) every node is marked
+         * in-frustum. Bounds are static (from the LOD tree), so flags are valid for all nodes regardless of
+         * decode state. Returns true when any node's in-frustum state changed (so the LOD bias must be re-applied).
+         * @returns whether any node's in-frustum state changed
+         */
+        private _updateNodeFrustum;
         /**
          * Reads the splat count from SOG metadata.
          * @param data SOG metadata