@onerjs/core 9.0.2 → 9.0.3

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

@@ -284,6 +284,35 @@ export declare class GaussianSplattingMeshBase extends Mesh {
      * Off by default; intended for performance investigation only.
      */
     static LogSortPerformance: boolean;
+    /**
+     * When true, meshes sort their splats on the GPU with a compute shader when the engine is WebGPU with compute shader support
+     * and the splat count is within the GPU sorter limit. The CPU worker is then not created. False by default: the asynchronous CPU
+     * worker is usually faster on low-end GPUs while the camera moves, because the GPU sort competes with rendering. Other engines
+     * (WebGL, Native) always use the CPU worker. Meshes of a scene using a custom render function (`scene.customRenderFunction`, other than
+     * the frame graph one) also keep the CPU worker, because the GPU sort is dispatched from `onBeforeRenderObservable`.
+     * A mesh leaves the GPU sort for the CPU worker, and does not come back to it, when depth sorting is disabled at runtime
+     * (see {@link GaussianSplattingMeshBase.disableDepthSort}), when point splatting is enabled, or when it starts streaming parts.
+     * After a WebGPU device restoration, the sorter and its buffers are recreated.
+     * Progressive loading sorts only the batches already uploaded, making them displayable before loading completes.
+     * Read when the mesh instantiates its sort, so set it before loading data.
+     * See also {@link GaussianSplattingMeshBase.useGpuSort} to override it on a single mesh.
+     * @experimental
+     */
+    static UseGpuSort: boolean;
+    /**
+     * Minimum number of frames between two GPU sorts of the same camera view when only the view changed (the camera moved or the mesh world
+     * transform changed). Sorts caused by data changes (new splat data, parts, ranges) and the first sort of a view bypass this throttle.
+     * After the first render, requests are coalesced at the next scene pre-render; initial readiness checks can sort synchronously.
+     * The default of 1 re-sorts whenever the view changed. On a slow GPU the sort competes with rendering; a value of 2 or
+     * more trades a slightly stale order during camera motion for a lower GPU cost, like the asynchronous CPU worker does.
+     * @experimental
+     */
+    static GpuSortMinFrameInterval: number;
+    /**
+     * Overrides {@link GaussianSplattingMeshBase.UseGpuSort} for this mesh when not null. Set it before loading data.
+     * @experimental
+     */
+    useGpuSort: Nullable<boolean>;
     /**
      * Safe-orbit camera limits parsed from the source file's metadata, or `null` when the file
      * carries none. The loader also auto-applies these to an active ArcRotateCamera at load time
@@ -340,6 +369,26 @@ export declare class GaussianSplattingMeshBase extends Mesh {
     private _splatSizeMax;
     private _sortIsDirty;
     private _forcedSortPending;
+    private _gpuMode;
+    private _gpuSorter;
+    private _gpuObserver;
+    private _gpuRestoreObserver;
+    private _gpuDataRevision;
+    private _gpuSourceDirty;
+    private _gpuIntervalsDirty;
+    private _gpuProgressiveCount;
+    private _gpuSortPending;
+    private _gpuPaddedCount;
+    private _gpuBoundsMin;
+    private _gpuBoundsMax;
+    private _gpuBoundsDirty;
+    private _gpuSortOptions;
+    private _gpuViewInfos;
+    private _gpuCollectFrameId;
+    private _gpuCameraPosition;
+    private _workerPending;
+    private _gpuPartMatricesDirty;
+    private _gpuSortForbidden;
     protected _activeSplatRanges: Nullable<Uint32Array>;
     private _activeSplatRangeKey;
     private _activeSplatRenderCount;
@@ -358,6 +407,7 @@ export declare class GaussianSplattingMeshBase extends Mesh {
     protected _maxShDegree: number;
     private static readonly _BatchSize;
     private _cameraViewInfos;
+    private _cameraRemovedObserver;
     protected static readonly _DefaultViewUpdateThreshold = 0.0001;
     /** Fired after parts are added or the mesh is rebuilt following a removal. Payload is the new part count. */
     readonly onPartCountChangedObservable: Observable<number>;
@@ -400,6 +450,8 @@ export declare class GaussianSplattingMeshBase extends Mesh {
     /**
      * If true, disables depth sorting of the splats (default: false)
      * Disabling sorting also discards deferred forced-sort requests.
+     * A mesh sorted on the GPU (see {@link GaussianSplattingMeshBase.UseGpuSort}) leaves the GPU sort when it is disabled at runtime
+     * and uses the identity index buffer of the CPU path. It does not return to the GPU sort when sorting is enabled again: the CPU worker is used instead.
      */
     get disableDepthSort(): boolean;
     set disableDepthSort(value: boolean);
@@ -496,31 +548,38 @@ export declare class GaussianSplattingMeshBase extends Mesh {
      */
     static ProgressiveUpdateAmount: number;
     /**
-     * Gets the covariancesA texture
+     * Gets the covariancesA texture.
+     * On WebGPU it is created as a sampled-data-only texture (no render attachment usage), so it cannot be used as a render target.
      */
     get covariancesATexture(): Nullable<BaseTexture>;
     /**
-     * Gets the covariancesB texture
+     * Gets the covariancesB texture.
+     * On WebGPU it is created as a sampled-data-only texture (no render attachment usage), so it cannot be used as a render target.
      */
     get covariancesBTexture(): Nullable<BaseTexture>;
     /**
-     * Gets the centers texture
+     * Gets the centers texture.
+     * On WebGPU it is created as a sampled-data-only texture (no render attachment usage), so it cannot be used as a render target.
      */
     get centersTexture(): Nullable<BaseTexture>;
     /**
-     * Gets the colors texture
+     * Gets the colors texture.
+     * On WebGPU it is created as a sampled-data-only texture (no render attachment usage), so it cannot be used as a render target.
      */
     get colorsTexture(): Nullable<BaseTexture>;
     /**
-     * Gets the rotation matrix A texture (rotation elements m[0],m[1],m[2],m[4])
+     * Gets the rotation matrix A texture (rotation elements m[0],m[1],m[2],m[4]).
+     * On WebGPU it is created as a sampled-data-only texture (no render attachment usage), so it cannot be used as a render target.
      */
     get rotationsATexture(): Nullable<BaseTexture>;
     /**
-     * Gets the rotation matrix B texture (rotation elements m[5],m[6],m[8],m[9])
+     * Gets the rotation matrix B texture (rotation elements m[5],m[6],m[8],m[9]).
+     * On WebGPU it is created as a sampled-data-only texture (no render attachment usage), so it cannot be used as a render target.
      */
     get rotationsBTexture(): Nullable<BaseTexture>;
     /**
-     * Gets the rotation scale texture (rotation element m[10] followed by scale diagonal sx,sy,sz)
+     * Gets the rotation scale texture (rotation element m[10] followed by scale diagonal sx,sy,sz).
+     * On WebGPU it is created as a sampled-data-only texture (no render attachment usage), so it cannot be used as a render target.
      */
     get rotationScaleTexture(): Nullable<BaseTexture>;
     /**
@@ -529,7 +588,8 @@ export declare class GaussianSplattingMeshBase extends Mesh {
     get needsRotationScaleTextures(): boolean;
     set needsRotationScaleTextures(value: boolean);
     /**
-     * Gets the SH textures
+     * Gets the SH textures.
+     * On WebGPU these are created as sampled-data-only textures (no render attachment usage), so they cannot be used as render targets.
      */
     get shTextures(): Nullable<BaseTexture[]>;
     /**
@@ -610,6 +670,50 @@ export declare class GaussianSplattingMeshBase extends Mesh {
     private _isSortStateDirty;
     /** @internal */
     _postToWorker(forced?: boolean): void;
+    private _collectActiveViewInfos;
+    private _collectCameraViewInfo;
+    /**
+     * Whether the sort of this mesh runs on the GPU (WebGPU compute) instead of the CPU worker.
+     * @internal
+     */
+    get _isGpuSortActive(): boolean;
+    /** @internal */
+    _markGpuSourceDirty(): void;
+    /** @internal */
+    _markGpuPartMatricesDirty(): void;
+    /**
+     * Texture holding the part index of each splat, for compound meshes. Null for a regular mesh.
+     * @returns the part indices texture
+     */
+    protected _getGpuSortPartIndicesTexture(): Nullable<BaseTexture>;
+    /**
+     * Transforms of the parts of a compound mesh. They replace the world matrix when sorting. Null for a regular mesh.
+     * @returns the part matrices
+     */
+    protected _getGpuSortPartMatrices(): Nullable<ReadonlyArray<Matrix>>;
+    /**
+     * Synchronizes compound part transforms before checking whether the GPU sort is up to date.
+     */
+    protected _syncPartProxyWorldMatrices(): void;
+    private _isGpuSortEligible;
+    private _enterGpuMode;
+    private _onGpuContextRestored;
+    private _resetGpuViews;
+    private _exitGpuMode;
+    /**
+     * Switches a mesh sorted on the GPU to the CPU worker (e.g. when it starts streaming, which needs a render-target atlas).
+     * @internal
+     */
+    _switchToWorkerSort(): void;
+    private _postToGpuSort;
+    private _gpuViewNeedsSort;
+    private _collectRecentViewInfo;
+    private _ensureGpuSorter;
+    private _updateGpuBounds;
+    private _applyGpuIntervals;
+    private _applyGpuSource;
+    private _bindGpuOutput;
+    private _runGpuSort;
     /**
      * Triggers the draw call for the mesh. Usually, you don't need to call this method by your own because the mesh rendering is handled by the scene rendering manager
      * @param subMesh defines the subMesh to render