@onerjs/core 8.56.4 → 9.0.1

package/Meshes/GaussianSplatting/gaussianSplattingMesh.pure.js

@@ -7,8 +7,20 @@ import { RawTexture } from "../../Materials/Textures/rawTexture.js";
 
 import { DecodeBase64ToBinary, EncodeArrayBufferToBase64 } from "../../Misc/stringTools.js";
 import { Mesh } from "../mesh.pure.js";
+import { Logger } from "../../Misc/logger.js";
 import { GaussianSplattingPartProxyMesh } from "./gaussianSplattingPartProxyMesh.pure.js";
 import { BoundingInfo } from "../../Culling/boundingInfo.js";
+export { IsGaussianSplattingClassName } from "./gaussianSplatting.functions.js";
+let _PointSplattingControllerFactory = null;
+/**
+ * Installs the point-splatting controller factory. Called by the optional point-splatting module's
+ * registration; until then every point-splatting mode on {@link GaussianSplattingMesh} is a no-op.
+ * @param factory creates a controller for a given mesh
+ * @internal
+ */
+export function _SetGaussianPointSplattingControllerFactory(factory) {
+    _PointSplattingControllerFactory = factory;
+}
 const _GaussianSplattingBytesPerSplat = 32;
 const _GaussianSplattingBytesPerShTexel = 16;
 /**
@@ -62,6 +74,36 @@ function ParsePartIndices(compressed) {
  * addPart/addParts and removePart.
  */
 export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
+    /**
+     * Internal render-resolution scale for point splatting (1 = full). Lower values emit ~scale^2 fewer
+     * points; full resolution is reconstructed over frames. `"auto"` (default) targets a device-tiered point
+     * budget, with the upscale factor capped at 8. Setting it restarts accumulation.
+     */
+    get pointSplattingRenderScale() {
+        return this._pointRenderScale;
+    }
+    set pointSplattingRenderScale(value) {
+        if (value === this._pointRenderScale) {
+            return;
+        }
+        this._pointRenderScale = value;
+        if (this._pointController) {
+            this._pointController.renderScale = value;
+        }
+    }
+    /** Enables previous-frame Hi-Z culling in point mode. Off by default because translucent splats can be biased. */
+    get pointSplattingOcclusionCulling() {
+        return this._pointOcclusionCulling;
+    }
+    set pointSplattingOcclusionCulling(value) {
+        if (value === this._pointOcclusionCulling) {
+            return;
+        }
+        this._pointOcclusionCulling = value;
+        if (this._pointController) {
+            this._pointController.occlusionCulling = value;
+        }
+    }
     /** Gets the part indices texture used for compound rendering */
     get partIndicesTexture() {
         return this._partIndicesTexture;
@@ -93,6 +135,11 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
          * Visibility values for each part (0.0 to 1.0), indexed by part index.
          */
         this._partVisibility = [];
+        // Point-splatting settings, kept here so they can be set before the controller exists.
+        this._pointScale = 1;
+        this._pointRenderScale = "auto";
+        this._pointOcclusionCulling = false;
+        this._pointController = null;
         /**
          * 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
@@ -135,6 +182,8 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
         this._tombstonedPartIndices = new Set();
         this._partIndicesTexture = null;
         this._partIndices = null;
+        this._partWorldData = new Float32Array(0);
+        this._partVisibilityData = [];
         // Ensure _splatsData is retained once compound mode is entered — addPart/addParts need
         // the source data for full-texture rebuilds. Set after super() so it is visible to
         // _updateData when the async load completes.
@@ -285,6 +334,8 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
         this._partIndicesTexture = null;
         this._part0LocalMin = null;
         this._part0LocalMax = null;
+        this._pointController?.dispose();
+        this._pointController = null;
         super.dispose(doNotRecurse);
     }
     // ---------------------------------------------------------------------------
@@ -310,6 +361,144 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
         this._partIndices = new Uint8Array(textureLength);
         this._partIndices.set(partIndices);
     }
+    // Point-splatting properties are no-ops until the controller module is registered.
+    /**
+     * Lazily creates this mesh's point-splatting controller, or null when the optional module is absent.
+     * @returns the controller, or null when point splatting has not been registered
+     */
+    _ensurePointController() {
+        if (!this._pointController) {
+            if (!_PointSplattingControllerFactory) {
+                Logger.Warn('GaussianSplattingMesh: point splatting is not registered; import "@babylonjs/core/Meshes/GaussianSplatting/gaussianPointSplattingController" to enable it.');
+                return null;
+            }
+            this._pointController = _PointSplattingControllerFactory(this);
+            this._pointController.pointScale = this._pointScale;
+            this._pointController.renderScale = this._pointRenderScale;
+            this._pointController.occlusionCulling = this._pointOcclusionCulling;
+        }
+        return this._pointController;
+    }
+    /**
+     * Whether the main color pass is rendered with the WebGPU compute point-splatting path instead of the
+     * classic sorted quads. Off by default; other passes (shadows, picking, prepass) are unaffected. Falls
+     * back to the classic path for multiple or rig cameras, floating-origin scenes, clip planes, and streamed parts.
+     * Color rendering also falls back when the camera viewport does not cover the full target or projected-size visualization is enabled.
+     * Wireframe, point-cloud, and other non-triangle fill modes use classic color, including scene-wide and mesh overrides.
+     * Clipping and depth quantization use the supplied projection's planes, including frozen projections.
+     * Tilted and custom projections are supported by the point path. Compute runs immediately
+     * before compositing with the pass's actual view and target dimensions; matching color and depth passes share one result.
+     * While point shaders compile, the pass waits without drawing classic splats. The color pass uses the classic path
+     * while the GaussianSplattingSolidColorMaterialPlugin override is enabled or the source material's
+     * alpha mode is not ALPHA_COMBINE. Point color supports only the built-in GaussianSplattingMaterial;
+     * NodeMaterials, subclasses, and other source materials use classic color to preserve their shader behavior.
+     * Custom material plugins and built-in visualization or picking plugins use classic color unless their
+     * behavior is explicitly reproduced or they are known neutral while disabled. The built-in debug plugin is supported.
+     * The source must require alpha blending without alpha testing; opaque and alpha-test transparency modes use classic color.
+     * Material compatibility is reevaluated each draw, including after material replacement or plugin attachment. WebGPU only.
+     *
+     * Limitation: each pixel's accumulated color is depth-tested as a whole against its latest sample's depth. Where
+     * other geometry intersects the splats, occluded splats can bleed through or visible ones drop out, and the
+     * result can flicker as the latest sample changes. Non-intersecting geometry composites correctly, and mostly
+     * opaque splats show no visible artifacts.
+     *
+     * Requires `@babylonjs/core/Meshes/GaussianSplatting/gaussianPointSplattingController` (included in
+     * `@babylonjs/core`); without it, enabling this logs a warning and does nothing.
+     * @see https://playground.babylonjs.com/#F39YWU#1
+     */
+    get pointSplattingRenderMode() {
+        return this._pointController?.colorRenderMode ?? false;
+    }
+    set pointSplattingRenderMode(value) {
+        if (value === this.pointSplattingRenderMode) {
+            return;
+        }
+        const controller = value ? this._ensurePointController() : this._pointController;
+        if (controller) {
+            controller.colorRenderMode = value;
+        }
+    }
+    /**
+     * Whether the active camera's DepthRenderer depth for this mesh comes from the point-splatting compute
+     * (an opaque nearest-surface depth) instead of the classic path. Off by default and independent of
+     * {@link pointSplattingRenderMode}, with the same camera, floating-origin, clip-plane, data fallbacks and module requirement.
+     * Color-only material fallbacks do not disable point depth. Scene-wide wireframe or point-cloud overrides
+     * use classic depth. For partial camera viewports, point depth
+     * requires a depth map with ignoreCameraViewport enabled. When point color is supported, depth maps
+     * with different pixel dimensions use classic depth to preserve color accumulation.
+     * Depth passes whose view, material parameters, or part inputs differ from retained point-color history
+     * also use classic depth rather than resetting that history. WebGPU only.
+     */
+    get pointSplattingDepthRenderMode() {
+        return this._pointController?.depthRenderMode ?? false;
+    }
+    set pointSplattingDepthRenderMode(value) {
+        if (value === this.pointSplattingDepthRenderMode) {
+            return;
+        }
+        const controller = value ? this._ensurePointController() : this._pointController;
+        if (controller) {
+            controller.depthRenderMode = value;
+        }
+    }
+    /**
+     * Counters of the most recent point-splatting compute frame, or null when compute has no available result.
+     * Individual render passes may still use the classic path for unsupported configurations.
+     *
+     * Snapshot `renderedFrameCount` whenever `accumulationVersion` changes: after the first frame of a
+     * generation, each further `pixelCycleLength` frames add one sample to every output pixel.
+     * @returns the latest compute counters, or null when point splatting is not producing frames
+     */
+    get pointSplattingProgress() {
+        return this._pointController?.progress ?? null;
+    }
+    /** Density multiplier for point splatting (higher = denser and slower). */
+    get pointSplattingScale() {
+        return this._pointScale;
+    }
+    set pointSplattingScale(value) {
+        this._pointScale = value;
+        if (this._pointController) {
+            this._pointController.pointScale = value;
+        }
+    }
+    /**
+     * True when this mesh hosts a streamed (GPU-decoded) region, which is absent from the CPU `_splatsData`
+     * that point splatting decodes.
+     * @internal
+     */
+    get _pointStreamingUnsupported() {
+        return this._hasStreamingPart;
+    }
+    /**
+     * Force-computes every part proxy's world matrix (a non-forced call skips nodes already computed this frame).
+     * @internal
+     */
+    _syncPartProxyWorldMatrices() {
+        for (const proxy of this._partProxies) {
+            proxy?.computeWorldMatrix(true);
+        }
+    }
+    /**
+     * Protected state the point-splatting controller needs to decode {@link _splatsData}.
+     * @returns the decoded atlas positions, fallback flip-Y convention, part indices, and active splat-range pairs
+     * @internal
+     */
+    _getPointDecodeInputs() {
+        return { positions: this._splatPositions, flipY: this._flipY, partIndices: this._partIndices, activeRanges: this._activeSplatRanges };
+    }
+    _drawColorPass(mesh, subMesh, enableAlphaMode, effectiveMeshReplacement) {
+        if (this._pointController?.drawColorPass(enableAlphaMode)) {
+            return mesh;
+        }
+        return super._drawColorPass(mesh, subMesh, enableAlphaMode, effectiveMeshReplacement);
+    }
+    _isSortRequired() {
+        return !this._pointController?.handlesCurrentPass;
+    }
+    _drawPointPass(enableAlphaMode) {
+        return this._pointController?.drawColorPass(enableAlphaMode) ?? false;
+    }
     /**
      * Returns `true` when at least one part has been added to this compound mesh.
      * Returns `false` before any parts are added, so the mesh renders in normal
@@ -366,14 +555,19 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
             return;
         }
         effect.setTexture("partIndicesTexture", this._partIndicesTexture);
-        const partWorldData = new Float32Array(this.partCount * 16);
+        const partWorldDataLength = this.partCount * 16;
+        if (this._partWorldData.length !== partWorldDataLength) {
+            this._partWorldData = new Float32Array(partWorldDataLength);
+        }
+        const partWorldData = this._partWorldData;
         for (let i = 0; i < this.partCount; i++) {
             this._partMatrices[i].toArray(partWorldData, i * 16);
         }
         effect.setMatrices("partWorld", partWorldData);
-        const partVisibilityData = [];
+        const partVisibilityData = this._partVisibilityData;
+        partVisibilityData.length = this.partCount;
         for (let i = 0; i < this.partCount; i++) {
-            partVisibilityData.push(this._partVisibility[i] ?? 1.0);
+            partVisibilityData[i] = this._partVisibility[i] ?? 1.0;
         }
         effect.setArray("partVisibility", partVisibilityData);
     }
@@ -614,6 +808,17 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
         this._partSplatRanges[partIndex] = ranges ? ranges.map((r) => ({ offset: r.offset, count: r.count })) : null;
         this._refreshPartRangeUnion();
     }
+    /**
+     * Sets the active splat ranges and invalidates decoded point-splatting data when they change.
+     * @param ranges global source-splat ranges to render, or null to render all splats
+     */
+    setSplatIndexRanges(ranges) {
+        const previous = this._activeSplatRanges;
+        super.setSplatIndexRanges(ranges);
+        if (previous !== this._activeSplatRanges) {
+            this._pointController?.invalidateDecodedSplats();
+        }
+    }
     /**
      * 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
@@ -685,7 +890,7 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
     }
     _onUpdateTextures(textureSize) {
         const createTextureFromDataU8 = (data, width, height, format) => {
-            return new RawTexture(data, width, height, format, this._scene, false, false, 2, 0);
+            return new RawTexture(data, width, height, format, this._scene, false, false, 1, 0);
         };
         // Keep the part indices texture in sync with _partIndices whenever textures are rebuilt.
         // The old "only create if absent" logic left the texture stale after a second addPart/addParts
@@ -741,7 +946,7 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
             return;
         }
         const buffer = new Uint8Array(this._partIndices);
-        this._partIndicesTexture = new RawTexture(buffer, textureSize.x, textureSize.y, 6, this._scene, false, false, 2, 0);
+        this._partIndicesTexture = new RawTexture(buffer, textureSize.x, textureSize.y, 6, this._scene, false, false, 1, 0);
         this._partIndicesTexture.wrapU = 0;
         this._partIndicesTexture.wrapV = 0;
         if (this._worker) {
@@ -785,11 +990,14 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
             splatByteOffset += existingVertexCount * _GaussianSplattingBytesPerSplat;
         }
         for (const other of others) {
-            if (!other._splatsData) {
-                continue;
-            }
+            // A reserved-empty streaming source carries no CPU data but still owns its slot in the atlas (its
+            // GPU rows are decoded later). Advance past that slot regardless of data so a real source appended
+            // after it lands at the offset its proxy's _splatsDataOffset points to — matching the unconditional
+            // GPU dstOffset advance in _addPartsInternal (and the SH loop below).
             const splatByteLength = other._vertexCount * _GaussianSplattingBytesPerSplat;
-            mergedSplatsData.set(GaussianSplattingMeshBase._GetSplatDataBytes(other._splatsData).subarray(0, splatByteLength), splatByteOffset);
+            if (other._splatsData) {
+                mergedSplatsData.set(GaussianSplattingMeshBase._GetSplatDataBytes(other._splatsData).subarray(0, splatByteLength), splatByteOffset);
+            }
             splatByteOffset += splatByteLength;
         }
         this._splatsData = mergedSplatsData.buffer;
@@ -1909,6 +2117,11 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
         serializationObject.disableDepthSort = this._disableDepthSort;
         serializationObject.viewUpdateThreshold = this.viewUpdateThreshold;
         serializationObject._flipY = this._flipY;
+        serializationObject.pointSplattingScale = this._pointScale;
+        serializationObject.pointSplattingRenderScale = this._pointRenderScale;
+        serializationObject.pointSplattingOcclusionCulling = this._pointOcclusionCulling;
+        serializationObject.pointSplattingRenderMode = this.pointSplattingRenderMode;
+        serializationObject.pointSplattingDepthRenderMode = this.pointSplattingDepthRenderMode;
         if (this._splatsData) {
             serializationObject.splatsData = encoding === "base64" ? EncodeArrayBufferToBase64(this._splatsData) : this._splatsData;
         }
@@ -1968,6 +2181,23 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
             const flipY = parsedMesh._flipY ?? false;
             mesh.updateData(splatsData, parsedShData, { flipY }, parsedPartIndices, parsedMesh.shDegree);
         }
+        // After updateData, which rebuilds the point-splatting state from the restored splats.
+        if (parsedMesh.pointSplattingScale !== undefined) {
+            mesh.pointSplattingScale = parsedMesh.pointSplattingScale;
+        }
+        if (parsedMesh.pointSplattingRenderScale !== undefined) {
+            mesh.pointSplattingRenderScale = parsedMesh.pointSplattingRenderScale;
+        }
+        if (parsedMesh.pointSplattingOcclusionCulling !== undefined) {
+            mesh.pointSplattingOcclusionCulling = parsedMesh.pointSplattingOcclusionCulling;
+        }
+        // Only assign when enabled: the setters warn when the optional point-splatting module is absent.
+        if (parsedMesh.pointSplattingRenderMode) {
+            mesh.pointSplattingRenderMode = true;
+        }
+        if (parsedMesh.pointSplattingDepthRenderMode) {
+            mesh.pointSplattingDepthRenderMode = true;
+        }
         if (parsedMesh.partProxies) {
             for (const serializedPart of parsedMesh.partProxies) {
                 const part = Object.assign({}, serializedPart);
@@ -1991,21 +2221,6 @@ export class GaussianSplattingMesh extends GaussianSplattingMeshBase {
         return GaussianSplattingMesh._ParseInternal(parsedMesh, scene, GaussianSplattingMesh);
     }
 }
-/**
- * True when `className` (from `AbstractMesh.getClassName()`) identifies a Gaussian Splatting mesh whose
- * `position.z` vertex attribute encodes a splat index rather than world-space Z: `"GaussianSplattingMesh"`
- * (also returned by {@link GaussianSplattingCompoundMesh}, which deliberately does not override
- * `getClassName()`) and `"GaussianSplattingStream"` (which does override it, to remain distinguishable for
- * other purposes). Rendering-pipeline code that must treat any Gaussian Splatting mesh differently from an
- * ordinary mesh (geometry buffer, depth pre-pass, GPU picking, IBL voxelization, snapshot rendering, ...)
- * should use this instead of a literal string comparison, so a future splat mesh subclass only needs to be
- * added here once.
- * @param className the mesh class name to test, e.g. from `AbstractMesh.getClassName()`
- * @returns true if the class name identifies a Gaussian Splatting mesh
- */
-export function IsGaussianSplattingClassName(className) {
-    return className === "GaussianSplattingMesh" || className === "GaussianSplattingStream";
-}
 let _Registered = false;
 /**
  * Register side effects for gaussianSplattingMesh.