fix(Gsplat): Sort Worker Message Starvation in GaussianSplattingMesh (BabylonJS#18554)

When a scene contains a Gsplat alongside geometry with other expensive
rendering passes (e.g., IBL shadows), the splat's depth sorting can feel
sluggish, where splats appear in the wrong order for up to 2 seconds
after the camera moves or a transformation is applied, even though the
sort itself finishes almost immediately. Sometimes the sorting even
stops working for more than 10 secs.

### Reason

The sort worker posts its result back to the main thread as a
regular-priority browser task. The browser's scheduler deprioritizes
regular tasks whenever a higher-priority frame request is pending. When
rendering passes are heavy enough to consume most of the frame budget,
the render loop continuously reschedules the next frame, starving the
worker's message handler. Therefore, the sort result may sit in the task
queue undelivered for an arbitrarily long time.

### Fix

We now install a `customAnimationFrameRequester` in
`GaussianSplattingMeshBase` that inserts a `setTimeout(0)` before each
frame request. This yields control back to the browser's event loop,
giving the scheduler an opportunity to deliver pending tasks, including
the sort result, before the next frame begins.

The wrapper is ref-counted, so it only exists while at least one
`GaussianSplattingMesh` is alive in the scene; there is no overhead for
scenes that don't use Gaussian splatting.

Note: If something else has already claimed
`customAnimationFrameRequester` (such as an immersive WebXR session), we
skip installation. For example, WebXR is not affected by this issue,
where its frame provider already yields to the task queue between frames
by design (refer to
[`xr_frame_provider.cc`](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/modules/xr/xr_frame_provider.cc),
[crbug.com/701444](https://crbug.com/701444).). For other modules
claiming the `customAnimationFrameRequester` in the future, they should
be responsible for yielding to the task queue between frames.

---------

Co-authored-by: Raymond Fei <yfei@adobe.com>

Author: raymondyfei

packages/dev/core/src/Meshes/GaussianSplatting/gaussianSplattingMeshBase.pure.ts

@@ -24,6 +24,8 @@ import { EngineStore } from "core/Engines/engineStore";
 import { type Camera } from "core/Cameras/camera.pure";
 import { ImportMeshAsync } from "core/Loading/sceneLoader";
 import { type INative } from "core/Engines/Native/nativeInterfaces";
+import { type AbstractEngine } from "core/Engines/abstractEngine.pure";
+import { type ICustomAnimationFrameRequester } from "core/Misc/customAnimationFrameRequester";
 
 // eslint-disable-next-line @typescript-eslint/naming-convention
 declare const _native: INative;
@@ -381,6 +383,75 @@ export interface PLYHeader {
     shBuffer: ArrayBuffer | null;
 }
 
+// Inter-frame task-queue yield
+// Depth-sort results arrive via worker postMessage, which is a regular-priority
+// task. At high refresh rates the rAF loop can leave almost no time for the
+// regular task queue, starving sort results for hundreds of milliseconds.
+// Installing a customAnimationFrameRequester that inserts a setTimeout(0) before
+// each rAF forces the event loop to drain regular tasks between frames.
+// The wrapper is ref-counted so it is installed when the first GSplat mesh is
+// created and removed when the last one is disposed.
+
+interface IGsInterFrameYieldRequester extends ICustomAnimationFrameRequester {
+    _gsInterFrameYield: true;
+    _refCount: number;
+}
+
+function _AcquireGsInterFrameYield(engine: AbstractEngine): void {
+    // Browser-only optimization: wraps the global requestAnimationFrame, which
+    // doesn't exist on Babylon Native. Skip it there so the engine uses its
+    // default frame scheduling.
+    if (IsNative) {
+        return;
+    }
+    const existing = engine.customAnimationFrameRequester as IGsInterFrameYieldRequester | null;
+    if (existing?._gsInterFrameYield) {
+        existing._refCount++;
+        return;
+    }
+    if (existing) {
+        // Slot is owned by another requester. Don't interfere.
+        return;
+    }
+    let _timeoutId = 0;
+    let _innerRafId = 0;
+    const wrapper: IGsInterFrameYieldRequester = {
+        _gsInterFrameYield: true,
+        _refCount: 1,
+        requestAnimationFrame: (callback: Function): number => {
+            // Insert a setTimeout(0) to yield to the regular task queue (worker
+            // postMessage results, input events) before scheduling the next animation
+            // frame. Without this, a continuous rAF loop at high refresh rates leaves
+            // almost no time for regular tasks, starving worker messages for hundreds of ms.
+            _timeoutId = setTimeout(() => {
+                _innerRafId = requestAnimationFrame(callback as FrameRequestCallback);
+            }, 0) as unknown as number;
+            return _timeoutId;
+        },
+        cancelAnimationFrame: (_id: number) => {
+            clearTimeout(_timeoutId);
+            if (_innerRafId > 0) {
+                cancelAnimationFrame(_innerRafId);
+            }
+            _timeoutId = 0;
+            _innerRafId = 0;
+        },
+    };
+    engine.customAnimationFrameRequester = wrapper;
+}
+
+// Counterpart to _AcquireGsInterFrameYield. Call once per mesh on dispose.
+function _ReleaseGsInterFrameYield(engine: AbstractEngine): void {
+    const existing = engine.customAnimationFrameRequester as IGsInterFrameYieldRequester | null;
+    if (!existing?._gsInterFrameYield) {
+        return;
+    }
+    existing._refCount--;
+    if (existing._refCount === 0) {
+        engine.customAnimationFrameRequester = null;
+    }
+}
+
 /**
  * Base class for Gaussian Splatting meshes. Contains all single-cloud rendering logic.
  * @internal Use GaussianSplattingMesh instead; this class is an internal implementation detail.
@@ -843,6 +914,7 @@ export class GaussianSplattingMeshBase extends Mesh {
         this.setEnabled(false);
         // webGL2 and webGPU support for RG texture with float16 is fine. not webGL1
         this._useRGBACovariants = !this.getEngine().isWebGPU && this.getEngine().version === 1.0;
+        _AcquireGsInterFrameYield(this.getEngine());
 
         this._keepInRam = keepInRam;
         if (url) {
@@ -2017,6 +2089,7 @@ export class GaussianSplattingMeshBase extends Mesh {
         // They can still be used as runtime source buffers by a compound mesh that retained
         // this mesh's data before disposal.
 
+        _ReleaseGsInterFrameYield(this.getEngine());
         this._worker?.terminate();
         this._worker = null;