@onerjs/core 9.0.0 → 9.0.1

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

@@ -339,7 +339,8 @@ export declare class GaussianSplattingMeshBase extends Mesh {
     private _splatSizeMin;
     private _splatSizeMax;
     private _sortIsDirty;
-    private _activeSplatRanges;
+    private _forcedSortPending;
+    protected _activeSplatRanges: Nullable<Uint32Array>;
     private _activeSplatRangeKey;
     private _activeSplatRenderCount;
     protected _cachedBoundingMin: Nullable<Vector3>;
@@ -350,6 +351,10 @@ export declare class GaussianSplattingMeshBase extends Mesh {
     private static _PlyConversionBatchSize;
     /** @internal */
     _shDegree: number;
+    /** Incremented whenever `_updateData` replaces the splat data, even when it reuses the same buffer. @internal */
+    _splatDataRevision: number;
+    /** True while `_updateData` is filling the atlas, so consumers keep the last complete data. @internal */
+    _splatDataPending: boolean;
     protected _maxShDegree: number;
     private static readonly _BatchSize;
     private _cameraViewInfos;
@@ -394,6 +399,7 @@ export declare class GaussianSplattingMeshBase extends Mesh {
     protected _disableDepthSort: boolean;
     /**
      * If true, disables depth sorting of the splats (default: false)
+     * Disabling sorting also discards deferred forced-sort requests.
      */
     get disableDepthSort(): boolean;
     set disableDepthSort(value: boolean);
@@ -430,7 +436,8 @@ export declare class GaussianSplattingMeshBase extends Mesh {
     private _setSplatIndexRanges;
     /**
      * Whether the depth sort is settled: a sort computed for the current active ranges and camera has been
-     * applied to the rendered index buffer, and no further sort is pending or in flight. For a static camera
+     * applied to the rendered index buffer, and no further sort is pending or in flight (including a forced sort
+     * deferred until a classic pass needs it). For a static camera
      * and a fixed active set this becomes true once the final sort completes. Used by streaming subclasses to
      * detect when rendering is fully up to date (e.g. for deterministic screenshots) and by IBL shadows to
      * avoid voxelizing against an index buffer the worker has not finished (re)building yet.
@@ -560,9 +567,9 @@ export declare class GaussianSplattingMeshBase extends Mesh {
     set minPixelSize(value: number);
     private _loadingPromise;
     /**
-     * set rendering material
+     * Sets the rendering material and updates camera views. Notifies material-change observers when the material changes.
      */
-    set material(value: Material);
+    set material(value: Nullable<Material>);
     /**
      * get rendering material
      */
@@ -611,6 +618,26 @@ export declare class GaussianSplattingMeshBase extends Mesh {
      * @returns the current mesh
      */
     render(subMesh: SubMesh, enableAlphaMode: boolean, effectiveMeshReplacement?: AbstractMesh): Mesh;
+    /**
+     * Draws the inner per-camera mesh for one render pass. Subclasses may replace selected passes.
+     * @param mesh inner per-camera mesh carrying the sorted splat geometry
+     * @param subMesh the submesh to draw
+     * @param enableAlphaMode whether alpha mode can be changed
+     * @param effectiveMeshReplacement optional mesh providing render info
+     * @returns the drawn mesh
+     */
+    protected _drawColorPass(mesh: Mesh, subMesh: SubMesh, enableAlphaMode: boolean, effectiveMeshReplacement?: AbstractMesh): Mesh;
+    /**
+     * Whether the current pass needs classic sorted splat geometry.
+     * @returns whether classic sorting is required
+     */
+    protected _isSortRequired(): boolean;
+    /**
+     * Handles a compute-owned pass before allocating or waiting for sorted geometry.
+     * @param _enableAlphaMode whether alpha mode can be changed
+     * @returns whether the pass was handled
+     */
+    protected _drawPointPass(_enableAlphaMode: boolean): boolean;
     private static _TypeNameToEnum;
     private static _ValueNameToEnum;
     /**
@@ -729,6 +756,7 @@ export declare class GaussianSplattingMeshBase extends Mesh {
      */
     get isCompound(): boolean;
     protected _setDelayedTextureUpdate(covA: Uint16Array, covB: Uint16Array, colorArray: Uint8Array, sh?: Uint8Array[]): void;
+    private _commitDelayedTextureUpdate;
     /**
      * Creates (or recreates) the MRT-backed data atlas at the given size and points the four core data
      * textures at its attachments. The attachments use the same decoded GS layout as {@link GaussianSplattingWorkBuffer}

package/Meshes/GaussianSplatting/gaussianSplattingMeshBase.pure.js

@@ -300,6 +300,7 @@ export class GaussianSplattingMeshBase extends Mesh {
     }
     /**
      * If true, disables depth sorting of the splats (default: false)
+     * Disabling sorting also discards deferred forced-sort requests.
      */
     get disableDepthSort() {
         return this._disableDepthSort;
@@ -309,6 +310,7 @@ export class GaussianSplattingMeshBase extends Mesh {
             this._worker?.terminate();
             this._worker = null;
             this._disableDepthSort = true;
+            this._forcedSortPending = false;
         }
         else if (this._disableDepthSort && !value) {
             this._disableDepthSort = false;
@@ -396,14 +398,15 @@ export class GaussianSplattingMeshBase extends Mesh {
     }
     /**
      * Whether the depth sort is settled: a sort computed for the current active ranges and camera has been
-     * applied to the rendered index buffer, and no further sort is pending or in flight. For a static camera
+     * applied to the rendered index buffer, and no further sort is pending or in flight (including a forced sort
+     * deferred until a classic pass needs it). For a static camera
      * and a fixed active set this becomes true once the final sort completes. Used by streaming subclasses to
      * detect when rendering is fully up to date (e.g. for deterministic screenshots) and by IBL shadows to
      * avoid voxelizing against an index buffer the worker has not finished (re)building yet.
      * @internal
      */
     get _isDepthSortSettled() {
-        return this._readyToDisplay && !this._sortIsDirty && this._canPostToWorker;
+        return this._readyToDisplay && !this._sortIsDirty && !this._forcedSortPending && this._canPostToWorker;
     }
     // (Re)allocates the worker depth buffer to the given padded size. A fresh array is allocated when the
     // size differs or the current buffer is detached (in-flight in the worker), so a queued sort can be
@@ -688,16 +691,22 @@ export class GaussianSplattingMeshBase extends Mesh {
         }
     }
     /**
-     * set rendering material
+     * Sets the rendering material and updates camera views. Notifies material-change observers when the material changes.
      */
     set material(value) {
+        const previous = this._material;
         this._material = value;
-        this._material.backFaceCulling = false;
-        this._material.cullBackFaces = false;
-        value.resetDrawCache();
+        if (value) {
+            value.backFaceCulling = false;
+            value.cullBackFaces = false;
+            value.resetDrawCache();
+        }
         this._cameraViewInfos?.forEach((cameraViewInfo) => {
             cameraViewInfo.mesh.material = value;
         });
+        if (previous !== value && this.onMaterialChangedObservable.hasObservers()) {
+            this.onMaterialChangedObservable.notifyObservers(this);
+        }
     }
     /**
      * get rendering material
@@ -803,6 +812,8 @@ export class GaussianSplattingMeshBase extends Mesh {
         this._splatSizeMin = Infinity;
         this._splatSizeMax = -Infinity;
         this._sortIsDirty = false;
+        // A forced sort requested while no classic pass needed sorting; runs on the next classic pass.
+        this._forcedSortPending = false;
         this._activeSplatRanges = null;
         this._activeSplatRangeKey = "";
         this._activeSplatRenderCount = 0;
@@ -811,6 +822,10 @@ export class GaussianSplattingMeshBase extends Mesh {
         this._cachedBoundingMax = null;
         /** @internal */
         this._shDegree = 0;
+        /** Incremented whenever `_updateData` replaces the splat data, even when it reuses the same buffer. @internal */
+        this._splatDataRevision = 0;
+        /** True while `_updateData` is filling the atlas, so consumers keep the last complete data. @internal */
+        this._splatDataPending = false;
         this._maxShDegree = 0;
         this._cameraViewInfos = new Map();
         /** Fired after parts are added or the mesh is rebuilt following a removal. Payload is the new part count. */
@@ -839,7 +854,13 @@ export class GaussianSplattingMeshBase extends Mesh {
         this._loadingPromise = null;
         this._updateTextureFromData = (texture, data, width, lineStart, lineCount) => {
             const engine = this._getTextureDataUpdateEngine();
-            engine.updateTextureData(texture.getInternalTexture(), data, 0, lineStart, width, lineCount, 0, 0, false);
+            const internalTexture = texture.getInternalTexture();
+            // NativeEngine and NullEngine support complete raw uploads, but not sub-texture uploads.
+            if (!engine._gl && !engine.isWebGPU && lineStart === 0 && lineCount === internalTexture.height) {
+                engine.updateRawTexture(internalTexture, data, internalTexture.format, internalTexture.invertY, null, internalTexture.type, internalTexture._useSRGBBuffer);
+                return;
+            }
+            engine.updateTextureData(internalTexture, data, 0, lineStart, width, lineCount, 0, 0, false);
         };
         this._updateTextureFromDataRect = (texture, data, xOffset, yOffset, width, height) => {
             const engine = this._getTextureDataUpdateEngine();
@@ -908,10 +929,14 @@ export class GaussianSplattingMeshBase extends Mesh {
      * @returns true when ready
      */
     isReady(completeCheck = false) {
-        if (!super.isReady(completeCheck, true)) {
+        const sortRequired = this._isSortRequired();
+        if (!super.isReady(sortRequired && completeCheck, true)) {
             return false;
         }
-        if (!this._readyToDisplay) {
+        if (!sortRequired && !this._geometry) {
+            this._postToWorker();
+        }
+        if (sortRequired && !this._readyToDisplay) {
             // mesh is ready when worker has done at least 1 sorting
             this._postToWorker(true);
             return false;
@@ -919,7 +944,7 @@ export class GaussianSplattingMeshBase extends Mesh {
         // Before the first successful render, require an applied index buffer. A pending refresh can
         // use the latest completed buffer, otherwise a transform changed every frame would starve the
         // first render. Once rendered, the render loop continuously re-sorts as the camera/world changes.
-        if (!this._hasRenderedOnce && !this._disableDepthSort) {
+        if (sortRequired && !this._hasRenderedOnce && !this._disableDepthSort) {
             const cameras = this._scene.activeCameras?.length ? this._scene.activeCameras : [this._scene.activeCamera];
             const canRenderWithPendingRefresh = this._scene._isInRenderingMeshEvaluation() && cameras.filter((camera) => camera !== null).length === 1;
             const worldMatrix = this.computeWorldMatrix(true);
@@ -1120,7 +1145,16 @@ export class GaussianSplattingMeshBase extends Mesh {
         // null before any splat data has been committed) or the native binding throws on the conversion.
         const hasNativeSort = !!Native?.sortSplats && !!this._splatPositions && !!this._splatIndex;
         // When depth sort is disabled, no sort function must run: fall through to the no-sort path below.
-        const hasSortFunction = !this._disableDepthSort && (this._worker || hasNativeSort);
+        const sortRequired = this._isSortRequired();
+        const hasSortFunction = sortRequired && !this._disableDepthSort && (this._worker || hasNativeSort);
+        // A forced sort (new data or parts) requested while no classic pass needs sorting (e.g. point
+        // splatting) is deferred to the next classic pass; the camera and world may be unchanged by then.
+        if (forced && !sortRequired && !this._disableDepthSort) {
+            this._forcedSortPending = true;
+        }
+        else if (hasSortFunction && this._forcedSortPending) {
+            forced = true;
+        }
         if ((forced || outdated) && hasSortFunction && (this._scene.activeCameras?.length || this._scene.activeCamera) && this._canPostToWorker) {
             const worldMatrix = this.computeWorldMatrix(true);
             // view infos sorted by least recent updated frame id
@@ -1136,6 +1170,7 @@ export class GaussianSplattingMeshBase extends Mesh {
                     cameraViewInfos.sortRequestId = ++this._sortRequestId;
                     cameraViewInfos.frameIdLastUpdate = frameId;
                     this._canPostToWorker = false;
+                    this._forcedSortPending = false;
                     if (this._worker) {
                         this._worker.postMessage({
                             command: GaussianSplattingSortWorkerCommand.SORT,
@@ -1173,7 +1208,17 @@ export class GaussianSplattingMeshBase extends Mesh {
                 }
             });
         }
-        else if (this._disableDepthSort) {
+        else if (this._disableDepthSort || !sortRequired) {
+            // ShadowGenerator bypasses render()/isReady(), so its atlas cannot wait for a deferred camera sort.
+            if (this._delayedTextureUpdate) {
+                this._updateSplatIndexBuffer(this._vertexCount);
+                this._cameraViewInfos.forEach((info) => {
+                    if (info.splatIndexBufferSet) {
+                        info.mesh.thinInstanceBufferUpdated("splatIndex");
+                    }
+                });
+                this._commitDelayedTextureUpdate();
+            }
             if (this._splatIndex) {
                 activeViewInfos.forEach((cameraViewInfos) => {
                     if (!cameraViewInfos.splatIndexBufferSet) {
@@ -1183,7 +1228,10 @@ export class GaussianSplattingMeshBase extends Mesh {
                 });
                 this._readyToDisplay = true;
             }
-            this._canPostToWorker = true;
+            // With a worker, the gate is owned by in-flight sorts and rebuilds; their completion unlocks it.
+            if (this._disableDepthSort || !this._worker) {
+                this._canPostToWorker = true;
+            }
         }
     }
     /**
@@ -1194,6 +1242,15 @@ export class GaussianSplattingMeshBase extends Mesh {
      * @returns the current mesh
      */
     render(subMesh, enableAlphaMode, effectiveMeshReplacement) {
+        let beforeNotified = false;
+        if (!this._isSortRequired()) {
+            this.onBeforeRenderObservable.notifyObservers(this);
+            beforeNotified = true;
+            if (this._drawPointPass(enableAlphaMode)) {
+                this.onAfterRenderObservable.notifyObservers(this);
+                return this;
+            }
+        }
         this._postToWorker();
         // geometry used for shadows, bind the first found in the camera view infos
         if (!this._geometry && this._cameraViewInfos.size) {
@@ -1202,9 +1259,12 @@ export class GaussianSplattingMeshBase extends Mesh {
         const cameraId = this._scene.activeCamera.uniqueId;
         const cameraViewInfos = this._cameraViewInfos.get(cameraId);
         if (!cameraViewInfos || !cameraViewInfos.splatIndexBufferSet) {
+            if (beforeNotified) {
+                this.onAfterRenderObservable.notifyObservers(this);
+            }
             return this;
         }
-        if (this.onBeforeRenderObservable) {
+        if (!beforeNotified && this.onBeforeRenderObservable) {
             this.onBeforeRenderObservable.notifyObservers(this);
         }
         const mesh = cameraViewInfos.mesh;
@@ -1218,7 +1278,7 @@ export class GaussianSplattingMeshBase extends Mesh {
         if (renderPassMaterial) {
             mesh.setMaterialForRenderPass(renderPassId, renderPassMaterial);
         }
-        const ret = mesh.render(subMesh, enableAlphaMode, effectiveMeshReplacement);
+        const ret = this._drawColorPass(mesh, subMesh, enableAlphaMode, effectiveMeshReplacement);
         this._hasRenderedOnce = true;
         // Clean up the temporary override to avoid affecting other render passes
         if (renderPassMaterial) {
@@ -1229,6 +1289,32 @@ export class GaussianSplattingMeshBase extends Mesh {
         }
         return ret;
     }
+    /**
+     * Draws the inner per-camera mesh for one render pass. Subclasses may replace selected passes.
+     * @param mesh inner per-camera mesh carrying the sorted splat geometry
+     * @param subMesh the submesh to draw
+     * @param enableAlphaMode whether alpha mode can be changed
+     * @param effectiveMeshReplacement optional mesh providing render info
+     * @returns the drawn mesh
+     */
+    _drawColorPass(mesh, subMesh, enableAlphaMode, effectiveMeshReplacement) {
+        return mesh.render(subMesh, enableAlphaMode, effectiveMeshReplacement);
+    }
+    /**
+     * Whether the current pass needs classic sorted splat geometry.
+     * @returns whether classic sorting is required
+     */
+    _isSortRequired() {
+        return true;
+    }
+    /**
+     * Handles a compute-owned pass before allocating or waiting for sorted geometry.
+     * @param _enableAlphaMode whether alpha mode can be changed
+     * @returns whether the pass was handled
+     */
+    _drawPointPass(_enableAlphaMode) {
+        return false;
+    }
     static _TypeNameToEnum(name) {
         switch (name) {
             case "float":
@@ -2221,6 +2307,15 @@ export class GaussianSplattingMeshBase extends Mesh {
     _setDelayedTextureUpdate(covA, covB, colorArray, sh) {
         this._delayedTextureUpdate = { covA, covB, colors: colorArray, centers: this._splatPositions, sh };
     }
+    _commitDelayedTextureUpdate() {
+        const update = this._delayedTextureUpdate;
+        if (!update) {
+            return;
+        }
+        const textureSize = this._getTextureSize(this._vertexCount);
+        this._updateSubTextures(update.centers, update.covA, update.covB, update.colors, 0, textureSize.y, update.sh);
+        this._delayedTextureUpdate = null;
+    }
     /**
      * Creates (or recreates) the MRT-backed data atlas at the given size and points the four core data
      * textures at its attachments. The attachments use the same decoded GS layout as {@link GaussianSplattingWorkBuffer}
@@ -2730,6 +2825,8 @@ export class GaussianSplattingMeshBase extends Mesh {
             this._readyToDisplay = false;
         }
         this._flipY = flipY;
+        this._splatDataRevision++;
+        this._splatDataPending = true;
         const uBuffer = new Uint8Array(data);
         const fBuffer = new Float32Array(uBuffer.buffer);
         // Optionally store the raw splat buffer as an ArrayBuffer. This is the source reference
@@ -2857,6 +2954,7 @@ export class GaussianSplattingMeshBase extends Mesh {
         // Cache bounding box for the next incremental addPart call
         this._cachedBoundingMin = minimum.clone();
         this._cachedBoundingMax = maximum.clone();
+        this._splatDataPending = false;
         this._postToWorker(true);
     }
     /**
@@ -3078,12 +3176,7 @@ export class GaussianSplattingMeshBase extends Mesh {
                 }
             }
             this.forcedInstanceCount = Math.max(renderedPadded >> 4, 1);
-            if (this._delayedTextureUpdate) {
-                const vertexCountPadded = (this._vertexCount + 15) & ~0xf;
-                const textureSize = this._getTextureSize(vertexCountPadded);
-                this._updateSubTextures(this._delayedTextureUpdate.centers, this._delayedTextureUpdate.covA, this._delayedTextureUpdate.covB, this._delayedTextureUpdate.colors, 0, textureSize.y, this._delayedTextureUpdate.sh);
-                this._delayedTextureUpdate = null;
-            }
+            this._commitDelayedTextureUpdate();
             // get mesh for camera and update its instance buffer
             const cameraViewInfos = this._cameraViewInfos.get(cameraId);
             if (cameraViewInfos) {