GSplat using streaming LOD supports unloading files no longer needed (#7955)

* Fixes to SOGS data unloading

* one more

* some more

* cleanup

* simplified

* inlined

* fix

* GSplat using streaming LOD supports unloading files no longer needed

---------

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

Author: mvaligursky

examples/src/examples/gaussian-splatting/lod.example.mjs

@@ -47,14 +47,15 @@ app.on('destroy', () => {
 });
 
 pc.Tracing.set(pc.TRACEID_SHADER_ALLOC, true);
+pc.Tracing.set(pc.TRACEID_OCTREE_RESOURCES, true);
 
 const assets = {
     // church: new pc.Asset('gsplat', 'gsplat', { url: `${rootPath}/static/assets/splats/morocco.ply` }),
     church: new pc.Asset('gsplat', 'gsplat', { url: `${rootPath}/static/assets/splats/morocco/lod-meta.json` }),
     // church: new pc.Asset('gsplat', 'gsplat', { url: `${rootPath}/static/assets/splats/garage/lod-meta.json` }),
     logo: new pc.Asset('gsplat', 'gsplat', { url: `${rootPath}/static/assets/splats/lod/lod-meta.json` }),
     guitar: new pc.Asset('gsplat', 'gsplat', { url: `${rootPath}/static/assets/splats/guitar.compressed.ply` }),
-    skull: new pc.Asset('gsplat', 'gsplat', { url: `${rootPath}/static/assets/splats/skull.ply` })
+    skull: new pc.Asset('gsplat', 'gsplat', { url: `${rootPath}/static/assets/splats/skull.sog` })
 };
 
 const assetListLoader = new pc.AssetListLoader(Object.values(assets), app.assets);
@@ -117,8 +118,10 @@ assetListLoader.load(() => {
     const cc = /** @type { CameraControls} */ (camera.script.create(CameraControls));
     Object.assign(cc, {
         sceneSize: 500,
-        moveSpeed: 0.005,
-        moveFastSpeed: 0.03,
+        moveSpeed: 0.05,
+        moveFastSpeed: 0.3,
+        // moveSpeed: 0.005,
+        // moveFastSpeed: 0.03,
         enableOrbit: false,
         enablePan: false
     });

src/core/constants.js

@@ -146,6 +146,13 @@ export const TRACEID_TEXTURES = 'Textures';
  */
 export const TRACEID_RENDER_QUEUE = 'RenderQueue';
 
+/**
+ * Logs the loaded GSplat resources for individual LOD levels of an octree.
+ *
+ * @category Debug
+ */
+export const TRACEID_OCTREE_RESOURCES = 'OctreeResources';
+
 /**
  * Logs the GPU timings.
  *

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

@@ -82,6 +82,7 @@ class GSplatAssetLoader extends GSplatAssetLoaderBase {
     unload(url) {
         const asset = this._urlToAsset.get(url);
         if (asset) {
+            this._registry.remove(asset);
             asset.unload();
             this._urlToAsset.delete(url);
         }

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

@@ -7,6 +7,11 @@ import { Debug } from '../../core/debug.js';
  * @category Asset
  */
 class GSplatAssetLoaderBase {
+    /**
+     * Number of ticks to wait before unloading a zero-ref file.
+     */
+    cooldownTicks = 100;
+
     /**
      * Initiates loading of a gsplat asset. This is a fire-and-forget operation that starts
      * the loading process.

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

@@ -1,13 +1,11 @@
 import { GSplatManager } from './gsplat-manager.js';
 
 /**
- * @import { GSplatOctree } from './gsplat-octree.js';
  * @import { LayerComposition } from '../composition/layer-composition.js'
  * @import { Camera } from '../camera.js'
  * @import { Layer } from '../layer.js'
  * @import { GraphicsDevice } from '../../platform/graphics/graphics-device.js'
  * @import { GraphNode } from '../graph-node.js'
- * @import { GSplatOctreeResource } from './gsplat-octree.resource.js'
  * @import { GSplatAssetLoaderBase } from './gsplat-asset-loader-base.js'
  * @import { Scene } from '../scene.js'
  */
@@ -90,13 +88,6 @@ class GSplatDirector {
      */
     camerasMap = new Map();
 
-    /**
-     * Global octrees, allowing sharing between its placements.
-     *
-     * @type {Map<GSplatOctreeResource, GSplatOctree>}
-     */
-    octrees = new Map();
-
     /**
      * @type {GSplatAssetLoaderBase}
      */
@@ -118,6 +109,13 @@ class GSplatDirector {
         this.scene = scene;
     }
 
+    destroy() {
+
+        // destroy all gsplat managers
+        this.camerasMap.forEach(cameraData => cameraData.destroy());
+        this.camerasMap.clear();
+    }
+
     getCameraData(camera) {
         let cameraData = this.camerasMap.get(camera);
         if (!cameraData) {

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

@@ -27,6 +27,7 @@ const invModelMat = new Mat4();
 const tempNonOctreePlacements = new Set();
 const tempOctreePlacements = new Set();
 const _updatedSplats = [];
+const tempOctreesTicked = new Set();
 
 /**
  * GSplatManager manages the rendering of splats using a work buffer, where all active splats are
@@ -41,6 +42,9 @@ class GSplatManager {
     /** @type {GraphNode} */
     node = new GraphNode('GSplatManager');
 
+    /** @type {number} */
+    cooldownTicks;
+
     /** @type {GSplatWorkBuffer} */
     workBuffer;
 
@@ -86,13 +90,22 @@ class GSplatManager {
     /** @type {Map<GSplatPlacement, GSplatOctreeInstance>} */
     octreeInstances = new Map();
 
+    /**
+     * Octree instances scheduled for destruction. We collect their releases and destroy them
+     * when creating the next world state
+     *
+     * @type {GSplatOctreeInstance[]}
+     */
+    octreeInstancesToDestroy = [];
+
     constructor(device, director, layer, cameraNode) {
         this.device = device;
         this.director = director;
         this.cameraNode = cameraNode;
         this.workBuffer = new GSplatWorkBuffer(device);
         this.renderer = new GSplatRenderer(device, this.node, this.cameraNode, layer, this.workBuffer);
         this.sorter = this.createSorter();
+        this.cooldownTicks = this.director.assetLoader.cooldownTicks;
     }
 
     destroy() {
@@ -133,11 +146,16 @@ class GSplatManager {
             }
         }
 
-        // destroy and remove octree instances that are no longer present
+        // remove octree instances that are no longer present and schedule them for destruction
         for (const [placement, inst] of this.octreeInstances) {
             if (!tempOctreePlacements.has(placement)) {
                 this.octreeInstances.delete(placement);
-                inst.destroy();
+
+                // mark world as dirty since octree set changed
+                this.layerPlacementsDirty = true;
+
+                // queue the instance to be processed during next world state creation
+                this.octreeInstancesToDestroy.push(inst);
             }
         }
 
@@ -196,6 +214,33 @@ class GSplatManager {
             });
 
             const newState = new GSplatWorldState(this.device, this.lastWorldStateVersion, splats);
+
+            // collect file-release requests from octree instances.
+            for (const [, inst] of this.octreeInstances) {
+                if (inst.removedCandidates && inst.removedCandidates.size) {
+                    for (const fileIndex of inst.removedCandidates) {
+                        // each entry represents a single decRef
+                        // pending releases will be applied on onSorted for this state
+                        newState.pendingReleases.push([inst.octree, fileIndex]);
+                    }
+                    inst.removedCandidates.clear();
+                }
+            }
+
+            // handle destruction of octree instances
+            if (this.octreeInstancesToDestroy.length) {
+                for (const inst of this.octreeInstancesToDestroy) {
+
+                    // collect file-release requests from octree instances
+                    const toRelease = inst.getFileDecrements();
+                    for (const fileIndex of toRelease) {
+                        newState.pendingReleases.push([inst.octree, fileIndex]);
+                    }
+                    inst.destroy();
+                }
+                this.octreeInstancesToDestroy.length = 0;
+            }
+
             this.worldStates.set(this.lastWorldStateVersion, newState);
 
             this.layerPlacementsDirty = false;
@@ -233,6 +278,16 @@ class GSplatManager {
 
                 // render all splats to work buffer
                 this.workBuffer.render(worldState.splats, this.cameraNode);
+
+                // apply pending file-release requests
+                if (worldState.pendingReleases && worldState.pendingReleases.length) {
+                    for (const [octree, fileIndex] of worldState.pendingReleases) {
+                        // decrement once for each staged release; refcount system guards against premature unload
+                        octree.decRefCount(fileIndex, this.cooldownTicks);
+                    }
+                    worldState.pendingReleases.length = 0;
+                }
+
             }
 
             // update order texture
@@ -313,6 +368,18 @@ class GSplatManager {
                 _updatedSplats.length = 0;
             }
         }
+
+        // tick cooldowns once per frame per unique octree
+        if (this.octreeInstances.size) {
+            for (const [, inst] of this.octreeInstances) {
+                const octree = inst.octree;
+                if (!tempOctreesTicked.has(octree)) {
+                    tempOctreesTicked.add(octree);
+                    octree.updateCooldownTick(this.director.assetLoader);
+                }
+            }
+            tempOctreesTicked.clear();
+        }
     }
 
     /**