Add frame:ready event to GSplatComponentSystem for video capture workflows (#8128)

Co-authored-by: Martin Valigursky <[email protected]>

Author: mvaligursky

src/framework/components/gsplat/gsplat-asset-loader.js

@@ -81,6 +81,10 @@ class GSplatAssetLoader extends GSplatAssetLoaderBase {
         this._registry = registry;
     }
 
+    get isLoading() {
+        return this._currentlyLoading.size > 0 || this._loadQueue.length > 0;
+    }
+
     /**
      * Initiates loading of a gsplat asset. This is a fire-and-forget operation that starts
      * the loading process. Use getResource() later to check if the asset has finished loading.

src/framework/components/gsplat/system.js

@@ -42,7 +42,8 @@ class GSplatComponentSystem extends ComponentSystem {
     /**
      * Fired when a GSplat material is created for a camera and layer combination. In unified
      * mode, materials are created during the first frame update when the GSplat is rendered.
-     * The handler is passed the {@link ShaderMaterial}, the {@link Camera}, and the {@link Layer}.
+     * The handler is passed the {@link ShaderMaterial}, the {@link CameraComponent}, and
+     * the {@link Layer}.
      *
      * This event is useful for setting up custom material chunks and parameters before the
      * first render.
@@ -57,6 +58,30 @@ class GSplatComponentSystem extends ComponentSystem {
      */
     static EVENT_MATERIALCREATED = 'material:created';
 
+    /**
+     * Fired every frame for each camera and layer combination rendering GSplats in unified mode.
+     * The handler is passed the {@link CameraComponent}, the {@link Layer}, a boolean indicating
+     * if the current frame has up-to-date sorting, and a boolean indicating if resources are loading.
+     *
+     * The `ready` parameter indicates whether the current frame reflects all recent changes (camera
+     * movement, splat transforms, lod updates, etc.) with the latest sorting applied. The `loading`
+     * parameter indicates if octree LOD resources are still being loaded.
+     *
+     * This event is useful for video capture or other workflows that need to wait for frames
+     * to be fully ready. Only capture frames and move camera to next position when both
+     * `ready === true` and `loading === false`.
+     *
+     * @event
+     * @example
+     * app.systems.gsplat.on('frame:ready', (camera, layer, ready, loading) => {
+     *     if (ready && !loading) {
+     *         console.log(`Frame ready to capture for camera ${camera.entity.name}`);
+     *         // Capture frame here
+     *     }
+     * });
+     */
+    static EVENT_FRAMEREADY = 'frame:ready';
+
     /**
      * Create a new GSplatComponentSystem.
      *

src/scene/gsplat-unified/gsplat-asset-loader-base.js

@@ -43,6 +43,17 @@ class GSplatAssetLoaderBase {
     getResource(url) {
         Debug.error('GSplatAssetLoaderBase#getResource: Not implemented');
     }
+
+    /**
+     * Returns true if any resources are currently loading or queued to load.
+     *
+     * @type {boolean}
+     * @abstract
+     */
+    get isLoading() {
+        Debug.error('GSplatAssetLoaderBase#isLoading: Not implemented');
+        return false;
+    }
 }
 
 export { GSplatAssetLoaderBase };

src/scene/gsplat-unified/gsplat-manager.js

@@ -500,6 +500,23 @@ class GSplatManager {
         return _cameraDeltas;
     }
 
+    /**
+     * Fires the frame:ready event with current sorting and loading state.
+     */
+    fireFrameReadyEvent() {
+        const ready = this.sortedVersion === this.lastWorldStateVersion;
+
+        // Check loader queue and octree instances' pending loads
+        let loading = this.director.assetLoader.isLoading;
+        if (!loading) {
+            for (const [, inst] of this.octreeInstances) {
+                loading ||= inst.hasPendingLoads;
+            }
+        }
+
+        this.director.eventHandler.fire('frame:ready', this.cameraNode.camera, this.renderer.layer, ready, loading);
+    }
+
     update() {
 
         // apply any pending sorted results
@@ -689,6 +706,9 @@ class GSplatManager {
             tempOctreesTicked.clear();
         }
 
+        // fire frame:ready event
+        this.fireFrameReadyEvent();
+
         // return the number of visible splats for stats
         const { textureSize } = this.workBuffer;
         return textureSize * textureSize;

src/scene/gsplat-unified/gsplat-octree-instance.js

@@ -112,6 +112,15 @@ class GSplatOctreeInstance {
      */
     pendingVisibleAdds = new Map();
 
+    /**
+     * Returns true if this instance has resources pending load or prefetch.
+     *
+     * @type {boolean}
+     */
+    get hasPendingLoads() {
+        return this.pending.size > 0 || this.prefetchPending.size > 0;
+    }
+
     /**
      * Environment placement.
      * @type {GSplatPlacement|null}

src/scene/gsplat-unified/gsplat-work-buffer.js

@@ -123,6 +123,10 @@ class GSplatWorkBuffer {
         // Detect compatible HDR format for color texture, fallback to RGBA16U if RGBA16F not supported
         this.colorTextureFormat = device.getRenderableHdrFormat([PIXELFORMAT_RGBA16F]) || PIXELFORMAT_RGBA16U;
 
+        // Work buffer textures format:
+        // - colorTexture (RGBA16F/RGBA16U): RGBA color with alpha
+        // - splatTexture0 (RGBA32U): modelCenter.xyz (3×32-bit floats as uint) + 2×16-bit covariance halfs (covA.z, covB.z)
+        // - splatTexture1 (RG32U): 4×16-bit covariance halfs packed as (covA.xy, covB.xy)
         this.colorTexture = this.createTexture('splatColor', this.colorTextureFormat, 1, 1);
         this.splatTexture0 = this.createTexture('splatTexture0', PIXELFORMAT_RGBA32U, 1, 1);
         this.splatTexture1 = this.createTexture('splatTexture1', PIXELFORMAT_RG32U, 1, 1);