@onerjs/core 8.54.4 → 8.54.5

package/Meshes/GaussianSplatting/gaussianSplattingMesh.pure.d.ts

@@ -4,7 +4,8 @@ import { type Scene } from "../../scene.pure.js";
 import { Matrix, Vector3 } from "../../Maths/math.vector.pure.js";
 import { type Vector2 } from "../../Maths/math.vector.js";
 import { type Effect } from "../../Materials/effect.pure.js";
-import { GaussianSplattingMeshBase } from "./gaussianSplattingMeshBase.pure.js";
+import { GaussianSplattingMeshBase, type IGaussianSplattingSplatRange } from "./gaussianSplattingMeshBase.pure.js";
+import { type MultiRenderTarget } from "../../Materials/Textures/multiRenderTarget.pure.js";
 import { GaussianSplattingPartProxyMesh } from "./gaussianSplattingPartProxyMesh.pure.js";
 import { BoundingInfo } from "../../Culling/boundingInfo.js";
 import { type BaseTexture } from "../../Materials/Textures/baseTexture.pure.js";
@@ -19,6 +20,105 @@ interface IGaussianSplattingPartSource {
     getWorldMatrix(): Matrix;
     getBoundingInfo(): BoundingInfo;
     dispose(): void;
+    /**
+     * When true this is a placeholder that reserves `_vertexCount` empty (invisible) splats in the
+     * atlas instead of copying real data. Used by {@link GaussianSplattingMesh.reserveStreamingPart}
+     * so a streaming engine can later GPU-decode into the reserved region. Sources flagged this way
+     * are allowed to have a null `_splatsData`; their atlas region is left zeroed (invisible padding).
+     */
+    _isReservedEmpty?: boolean;
+}
+/**
+ * Handle to a region of a compound Gaussian Splatting mesh reserved for dynamic (streamed) content by
+ * {@link GaussianSplattingMesh.reserveStreamingPart}. It lets a streaming engine populate the region's
+ * splats over time and drive which of them are sorted/rendered, while the compound keeps depth-sorting
+ * and drawing every part (static + streamed) together in one pass.
+ *
+ * Ranges/offsets passed to this handle are LOCAL to the part (0-based within `[0, capacity)`); the handle
+ * translates them to the compound's global atlas coordinates.
+ */
+export interface IGaussianSplattingStreamingPart {
+    /** The proxy mesh controlling this part's world transform and visibility. */
+    readonly proxy: GaussianSplattingPartProxyMesh;
+    /** The part index assigned to this streaming region in the compound. */
+    readonly partIndex: number;
+    /** First atlas splat index of the reserved region. */
+    readonly base: number;
+    /** Number of splats reserved for the region. */
+    readonly capacity: number;
+    /** The compound's shared centers texture (the region occupies `[base, base+capacity)` within it). */
+    readonly centersTexture: Nullable<BaseTexture>;
+    /** The compound's shared covariance A texture. */
+    readonly covariancesATexture: Nullable<BaseTexture>;
+    /** The compound's shared covariance B texture. */
+    readonly covariancesBTexture: Nullable<BaseTexture>;
+    /** The compound's shared colors texture. */
+    readonly colorsTexture: Nullable<BaseTexture>;
+    /** The compound's shared CPU centers buffer consumed by the sort worker. */
+    readonly splatPositions: Nullable<Float32Array>;
+    /** The compound's shared render-target atlas a streaming engine decodes into, or null on a non-GPU backend. */
+    readonly mrtAtlas: Nullable<MultiRenderTarget>;
+    /**
+     * The compound's shared higher-order SH render-target atlas (one single-attachment integer MRT per packed-u32
+     * SH texture) a streaming engine bakes SH into, or null when SH decode was not requested for this part.
+     */
+    readonly shMrtAtlas: Nullable<MultiRenderTarget[]>;
+    /**
+     * The compound's shared rotation/scale render-target atlas (one 3-attachment half-float MRT) a streaming engine
+     * decodes rotation/scale into for voxel-IBL shadows, or null when rotation decode was not requested for this part.
+     */
+    readonly rotMrtAtlas: Nullable<MultiRenderTarget>;
+    /** Width (in texels) of the atlas, used to address decode/readback over the wide layout. */
+    readonly atlasWidth: number;
+    /** Whether the compound's shared depth sort is settled (a streaming engine polls this to detect readiness). */
+    readonly isDepthSortSettled: boolean;
+    /**
+     * Restricts which of this part's splats are sorted/rendered, in LOCAL coordinates. `null` renders the
+     * whole reserved region. The compound merges this with every other part's ranges into the single sort.
+     * @param localRanges active local ranges, or `null` for the full region
+     */
+    setActiveRanges(localRanges: Nullable<readonly IGaussianSplattingSplatRange[]>): void;
+    /**
+     * CPU-decodes raw `.splat` bytes into the region at `localOffset`, uploading only those texels and
+     * patching the sort worker. Grows the part's bounding info to include the written centers. This is the
+     * CPU population path (used to seed the region or as a fallback when GPU decode is unavailable).
+     * @param localOffset first local splat index to write
+     * @param count number of splats to write
+     * @param splatsData raw `.splat` bytes for `count` splats (stride 32)
+     */
+    writeSplats(localOffset: number, count: number, splatsData: ArrayBuffer | ArrayBufferView): void;
+    /**
+     * Patches only `[localOffset, localOffset+count)` of the worker's position buffer (for the GPU path,
+     * where texel data is written directly to the atlas and only the CPU centers are pushed to the worker).
+     * @param localOffset first local splat index
+     * @param count number of splats
+     */
+    postPositionsRange(localOffset: number, count: number): void;
+    /**
+     * Grows the part's (and compound's) bounding info to include the given local-space centers extent.
+     * @param min minimum corner
+     * @param max maximum corner
+     */
+    expandBounds(min: Vector3, max: Vector3): void;
+    /**
+     * Re-posts the full merged position + part-index set to the compound's sort worker. Only needed after a
+     * relayout moved the region's data wholesale; per-decode updates use {@link postPositionsRange} instead.
+     */
+    notifyDataChanged(): void;
+    /**
+     * Subscribes to the "about to recreate the shared atlas to grow it" event (e.g. another part is being added).
+     * The callback receives the OLD atlas and should back up this region's GPU-only data before it is disposed.
+     * @param callback invoked with the old atlas MRT
+     * @returns an unsubscribe function (call it on dispose)
+     */
+    onBeforeAtlasRebuild(callback: (oldAtlas: MultiRenderTarget) => void): () => void;
+    /**
+     * Subscribes to the "shared atlas has been recreated" event. The callback receives the NEW atlas and should
+     * rebind to it and restore this region's backed-up data.
+     * @param callback invoked with the new atlas MRT
+     * @returns an unsubscribe function (call it on dispose)
+     */
+    onAfterAtlasRebuild(callback: (newAtlas: MultiRenderTarget) => void): () => void;
 }
 /**
  * Class used to render a Gaussian Splatting mesh. Supports both single-cloud and compound
@@ -44,6 +144,31 @@ export declare class GaussianSplattingMesh extends GaussianSplattingMeshBase {
      * Visibility values for each part (0.0 to 1.0), indexed by part index.
      */
     protected _partVisibility: number[];
+    /**
+     * Per-part active source-splat range overrides, indexed by part index, in GLOBAL source-splat
+     * coordinates (offsets into the merged atlas). A part with no entry (undefined) renders its full
+     * range; a part with an entry renders only those ranges. Used by streaming parts to render just
+     * their currently-active LOD splats while static parts render fully. No overrides at all means no
+     * filter (the base renders every splat, preserving the non-streaming fast path).
+     */
+    private _partSplatRanges;
+    /**
+     * True once a streaming part has been reserved. A streamed region's data lives only on the GPU (no retained CPU
+     * source), so atlas rebuilds and part add/remove take the streaming-aware paths that back up and restore each
+     * region rather than regenerating it from a CPU source.
+     * @internal
+     */
+    protected _hasStreamingPart: boolean;
+    /** Mutable bookkeeping for each reserved streaming region, so {@link compactAtlas} can relocate them. */
+    private _streamingStates;
+    /**
+     * Max SH degree contributed by the live (non-tombstoned) streaming parts. Recomputed by
+     * {@link _refreshStreamingShState} whenever parts change, so removing the last SH stream turns the shared SH
+     * atlas off instead of leaving SH_DEGREE high over texels nothing refills.
+     */
+    private _streamingShDegree;
+    /** Part indices tombstoned by {@link removePart} while streaming — excluded from render, reclaimed by {@link compactAtlas}. */
+    private _tombstonedPartIndices;
     private _partIndicesTexture;
     private _partIndices;
     /** Gets the part indices texture used for compound rendering */
@@ -189,6 +314,34 @@ export declare class GaussianSplattingMesh extends GaussianSplattingMeshBase {
      * @param value the visibility value (0.0 to 1.0) to set
      */
     setPartVisibility(partIndex: number, value: number): void;
+    /**
+     * Restricts which source splats of a single part are sorted and rendered, in GLOBAL source-splat
+     * coordinates (offsets into the merged atlas). Static parts render fully by default; a streaming
+     * part uses this to render only its currently-active LOD splats. The compound recomputes the union
+     * of every part's active ranges and drives the single shared depth sort / draw with it, so all
+     * parts still sort together in one pass.
+     *
+     * Passing `null` clears the override for that part (it reverts to rendering its full range). When no
+     * part has an override, the compound clears the range filter entirely (renders every splat), which
+     * preserves the non-streaming fast path.
+     * @param partIndex index of the part to constrain
+     * @param ranges active global source-splat ranges for the part, or `null` to render the whole part
+     */
+    setPartSplatRanges(partIndex: number, ranges: Nullable<readonly IGaussianSplattingSplatRange[]>): void;
+    /**
+     * Recomputes the global active-range union across all parts and pushes it to the shared sort/draw
+     * via the base {@link setSplatIndexRanges}. When no part carries an override the filter is cleared
+     * (render everything). A part without an override contributes its full `[offset, count)` derived
+     * from its proxy; a part with an override contributes exactly those ranges.
+     */
+    private _refreshPartRangeUnion;
+    /**
+     * Sorts and merges adjacent/overlapping source-splat ranges so the interval list handed to the sort
+     * worker stays compact (parts occupy disjoint regions, so this mainly coalesces contiguous parts).
+     * @param ranges raw ranges
+     * @returns coalesced ranges sorted by offset
+     */
+    private static _CoalesceSplatRanges;
     protected _copyTextures(source: GaussianSplattingMeshBase): void;
     protected _onUpdateTextures(textureSize: Vector2): void;
     protected _updateSubTextures(splatPositions: Float32Array, covA: Uint16Array, covB: Uint16Array, colorArray: Uint8Array, lineStart: number, lineCount: number, sh?: Uint8Array[], partIndices?: Uint8Array): void;
@@ -224,15 +377,77 @@ export declare class GaussianSplattingMesh extends GaussianSplattingMeshBase {
      * @deprecated Use {@link GaussianSplattingCompoundMesh.addPart} instead.
      */
     addPart(other: GaussianSplattingMesh, disposeOther?: boolean): GaussianSplattingPartProxyMesh;
+    /**
+     * Recomputes the shared SH-atlas state ({@link _useShMrtAtlas}, {@link _shMrtAtlasTextureCount},
+     * {@link _streamingShDegree}) from the currently-live (non-tombstoned) streaming parts. Call before an atlas
+     * rebuild that follows a removal so a stale SH degree/count from a removed part can't keep the SH atlas active
+     * (and SH_DEGREE high) with nothing refilling the SH texels.
+     */
+    private _refreshStreamingShState;
+    /**
+     * Tombstones a part of a streaming compound: excludes it from the render union permanently and hides its
+     * proxy, leaving its atlas rows idle. Used instead of the compacting {@link removePart} rebuild whenever a
+     * streaming part is reserved — a streamed region has no retained CPU source and decodes at a FIXED base
+     * offset, so the rebuild can neither reconstruct it nor shift any part without desynchronizing the streaming
+     * engine. Every other part keeps its exact offset (no shift), so resident streams keep decoding at their base.
+     * The empty `[]` override survives future add-driven rebuilds, so the region stays invisible even though its
+     * texels get rebuilt; memory is only reclaimed by disposing/recreating the whole compound.
+     * @param index the part index to tombstone
+     */
+    private _tombstonePart;
+    /**
+     * Tears the compound down to an empty state so a subsequent {@link _addPartsInternal} recreates fresh GPU
+     * textures. Shared by {@link removePart} (compacting rebuild) and {@link compactAtlas}. Does NOT dispose the
+     * part proxies — callers dispose only the proxies being removed and reuse the survivors' proxy objects.
+     * @internal
+     */
+    protected _resetForRebuild(): void;
+    /**
+     * Reclaims the atlas rows of parts removed (tombstoned) while a streaming part was resident. `removePart`
+     * on a streaming compound only tombstones — it excludes the part from the render union and hides its proxy,
+     * but leaves its rows allocated, since compacting them would relocate the still-resident streaming regions.
+     * This method performs that compaction: it rebuilds the shared atlas from the LIVE parts at new, contiguous
+     * (row-aligned for streaming) offsets, physically relocating each surviving streaming region's GPU texels,
+     * CPU sort positions, and decode/render base offset, and drops the tombstoned rows — shrinking the atlas.
+     *
+     * Call it after removing one or more models to actually free the GPU/CPU memory (e.g. on idle, or once a
+     * batch of removals settles). No-op when nothing is tombstoned. Safe while streams are actively decoding:
+     * each surviving region is backed up before the old atlas is disposed and restored at its new base after.
+     */
+    compactAtlas(): void;
     /**
      * Remove a part from this compound mesh.
      * The remaining parts are rebuilt directly from the compound mesh's retained source buffers.
      * The current mesh is reset to a plain (single-part) state and then each remaining source is
      * re-added via addParts.
+     * When a streaming part is reserved the part is tombstoned instead of compacted (see {@link _tombstonePart}).
      * @param index - The index of the part to remove
      * @deprecated Use {@link GaussianSplattingCompoundMesh.removePart} instead.
      */
     removePart(index: number): void;
+    /**
+     * Reserves a contiguous region of `capacity` splats in the compound as a new part for dynamic (streamed)
+     * content. Unlike {@link addPart}, no source data is copied: the region is created as invisible padding
+     * (zeroed) for a streaming engine to populate over time via the returned handle. The reserved part
+     * participates in the compound's single shared depth sort and draw exactly like a static part — it has a
+     * `partIndex`, a per-part world matrix (via its proxy), and a per-part visibility — so streamed splats are
+     * sorted and rendered together in one pass with the static parts.
+     *
+     * Add the streaming part LAST (after all static parts). The returned handle drives which of the region's
+     * splats render (LOD) and writes their data.
+     * @param capacity number of splats to reserve
+     * @param worldMatrix initial world matrix for the region's proxy (e.g. carrying a source's up-axis
+     *   convention); defaults to identity
+     * @param name name for the region's proxy mesh
+     * @param shTextureCount number of packed-u32 higher-order SH textures to allocate as a shared render-target SH
+     *   atlas the streaming engine bakes into (`ceil(coeffs*3/16)` for the stream's max SH degree); 0 = no SH
+     * @param shDegree SH degree of the streamed content (drives the compound's `SH_DEGREE`); ignored when
+     *   `shTextureCount` is 0. The compound keeps the MAX SH degree across its parts.
+     * @param needsRotationScale when true, converts the compound's rotation/scale textures to a shared render-target
+     *   half-float atlas the streaming engine decodes into, so the streamed splats participate in voxel-IBL shadows.
+     * @returns a handle used to populate and control the reserved region
+     */
+    reserveStreamingPart(capacity: number, worldMatrix?: Matrix, name?: string, shTextureCount?: number, shDegree?: number, needsRotationScale?: boolean): IGaussianSplattingStreamingPart;
     /**
      * Serialize current GaussianSplattingMesh
      * @param serializationObject defines the object which will receive the serialization data