GSplat LOD format supports environment tag (#8110)

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

Author: mvaligursky

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

@@ -49,8 +49,7 @@ app.on('destroy', () => {
 // Skatepark configuration
 const config = {
     name: 'Skatepark',
-    url: 'https://code.playcanvas.com/examples_data/example_skatepark_01/lod-meta.json',
-    environment: 'https://code.playcanvas.com/examples_data/example_skatepark_01/environment.sog',
+    url: 'https://code.playcanvas.com/examples_data/example_skatepark_02/lod-meta.json',
     lodUpdateDistance: 1,
     lodUnderfillLimit: 10,
     cameraPosition: [32, 2, 2],
@@ -94,11 +93,6 @@ const assets = {
     )
 };
 
-// Add environment asset if specified in config
-if (config.environment) {
-    assets.environment = new pc.Asset('gsplat-environment', 'gsplat', { url: config.environment });
-}
-
 const assetListLoader = new pc.AssetListLoader(Object.values(assets), app.assets);
 assetListLoader.load(() => {
     app.start();
@@ -159,19 +153,6 @@ assetListLoader.load(() => {
     applyPreset();
     data.on('lodPreset:set', applyPreset);
 
-    // Add environment gsplat if specified
-    if (assets.environment) {
-        const envEntity = new pc.Entity('gsplat-environment');
-        envEntity.addComponent('gsplat', {
-            asset: assets.environment,
-            unified: true
-        });
-        envEntity.setLocalPosition(0, 0, 0);
-        envEntity.setLocalEulerAngles(rotX, rotY, rotZ);
-        envEntity.setLocalScale(1, 1, 1);
-        app.root.addChild(envEntity);
-    }
-
     // Create a camera with fly controls
     const camera = new pc.Entity('camera');
     camera.addComponent('camera', {

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

@@ -62,8 +62,7 @@ app.on('destroy', () => {
 // original dataset: https://www.youtube.com/watch?v=3RtY_cLK13k
 const config = {
     name: 'Roman-Parish',
-    url: 'https://code.playcanvas.com/examples_data/example_roman_parish_01/lod-meta.json',
-    environment: 'https://code.playcanvas.com/examples_data/example_roman_parish_01/environment.sog',
+    url: 'https://code.playcanvas.com/examples_data/example_roman_parish_02/lod-meta.json',
     lodUpdateDistance: 0.5,
     lodUnderfillLimit: 5,
     cameraPosition: [10.3, 2, -10],
@@ -107,11 +106,6 @@ const assets = {
     )
 };
 
-// Add environment asset if specified in config
-if (config.environment) {
-    assets.environment = new pc.Asset('gsplat-environment', 'gsplat', { url: config.environment });
-}
-
 const assetListLoader = new pc.AssetListLoader(Object.values(assets), app.assets);
 assetListLoader.load(() => {
     app.start();
@@ -172,19 +166,6 @@ assetListLoader.load(() => {
     applyPreset();
     data.on('lodPreset:set', applyPreset);
 
-    // Add environment gsplat if specified
-    if (assets.environment) {
-        const envEntity = new pc.Entity('gsplat-environment');
-        envEntity.addComponent('gsplat', {
-            asset: assets.environment,
-            unified: true
-        });
-        envEntity.setLocalPosition(0, 0, 0);
-        envEntity.setLocalEulerAngles(rotX, rotY, rotZ);
-        envEntity.setLocalScale(1, 1, 1);
-        app.root.addChild(envEntity);
-    }
-
     // Create a camera with fly controls
     const camera = new pc.Entity('camera');
     camera.addComponent('camera', {

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

@@ -112,6 +112,12 @@ class GSplatOctreeInstance {
      */
     pendingVisibleAdds = new Map();
 
+    /**
+     * Environment placement.
+     * @type {GSplatPlacement|null}
+     */
+    environmentPlacement = null;
+
     /**
      * @param {GSplatOctree} octree - The octree.
      * @param {GSplatPlacement} placement - The placement.
@@ -129,6 +135,12 @@ class GSplatOctreeInstance {
         // Initialize file placements array
         const numFiles = octree.files.length;
         this.filePlacements = new Array(numFiles).fill(null);
+
+        // Handle environment if configured
+        if (octree.environmentUrl) {
+            octree.incEnvironmentRefCount();
+            octree.ensureEnvironmentResource(assetLoader);
+        }
     }
 
     /**
@@ -138,6 +150,13 @@ class GSplatOctreeInstance {
         this.pending.clear();
         this.pendingDecrements.clear();
         this.filePlacements.length = 0;
+
+        // Clean up environment if present
+        if (this.environmentPlacement) {
+            this.activePlacements.delete(this.environmentPlacement);
+            this.octree.decEnvironmentRefCount(this.assetLoader);
+            this.environmentPlacement = null;
+        }
     }
 
     /**
@@ -599,6 +618,21 @@ class GSplatOctreeInstance {
         // watch prefetched loads for completion to allow promotion
         this.pollPrefetchCompletions();
 
+        // handle environment loading
+        if (this.octree.environmentUrl && !this.environmentPlacement) {
+            // poll for environment resource completion
+            this.octree.ensureEnvironmentResource(this.assetLoader);
+            const envResource = this.octree.environmentResource;
+
+            if (envResource) {
+                // create environment placement with the loaded resource
+                this.environmentPlacement = new GSplatPlacement(envResource, this.placement.node, 0);
+                this.environmentPlacement.aabb.copy(envResource.aabb);
+                this.activePlacements.add(this.environmentPlacement);
+                this.dirtyModifiedPlacements = true;
+            }
+        }
+
         // check if any placements need LOD update
         const dirty = this.dirtyModifiedPlacements;
         this.dirtyModifiedPlacements = false;

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

@@ -59,6 +59,27 @@ class GSplatOctree {
      */
     cooldowns = new Map();
 
+    /**
+     * Optional environment asset URL.
+     *
+     * @type {string|null}
+     */
+    environmentUrl = null;
+
+    /**
+     * Loaded environment resource.
+     *
+     * @type {GSplatResource|null}
+     */
+    environmentResource = null;
+
+    /**
+     * Reference count for environment usage.
+     *
+     * @type {number}
+     */
+    environmentRefCount = 0;
+
     /**
      * @param {string} assetFileUrl - The file URL of the container asset.
      * @param {Object} data - The parsed JSON data containing info, filenames and tree.
@@ -78,6 +99,13 @@ class GSplatOctree {
         // initialize per-file ref counts
         this.fileRefCounts = new Int32Array(this.files.length);
 
+        // parse optional environment field and resolve path
+        if (data.environment) {
+            this.environmentUrl = path.isRelativePath(data.environment) ?
+                path.join(baseDir, data.environment) :
+                data.environment;
+        }
+
         // Extract leaf nodes from hierarchical tree structure
         const leafNodes = [];
         this._extractLeafNodes(data.tree, leafNodes);
@@ -280,6 +308,73 @@ class GSplatOctree {
         // Start/continue loading (asset loader handles duplicates internally)
         assetLoader.load(fullUrl);
     }
+
+    /**
+     * Increments reference count for environment.
+     */
+    incEnvironmentRefCount() {
+        this.environmentRefCount++;
+    }
+
+    /**
+     * Decrements reference count for environment. When it reaches zero, immediately unload.
+     *
+     * @param {GSplatAssetLoaderBase} assetLoader - Asset loader used to unload the resource.
+     */
+    decEnvironmentRefCount(assetLoader) {
+        this.environmentRefCount--;
+        Debug.assert(this.environmentRefCount >= 0);
+
+        // unload immediately when reaching zero
+        if (this.environmentRefCount === 0) {
+            this.unloadEnvironmentResource(assetLoader);
+        }
+    }
+
+    /**
+     * Ensures environment resource is loaded and available.
+     *
+     * @param {GSplatAssetLoaderBase} assetLoader - The asset loader.
+     */
+    ensureEnvironmentResource(assetLoader) {
+        // no environment configured
+        if (!this.environmentUrl) {
+            return;
+        }
+
+        // resource already loaded
+        if (this.environmentResource) {
+            return;
+        }
+
+        // Check if the resource is now available from the asset loader
+        const res = assetLoader.getResource(this.environmentUrl);
+        if (res) {
+            this.environmentResource = res;
+
+            // if loaded but not needed, immediately unload
+            if (this.environmentRefCount === 0) {
+                this.unloadEnvironmentResource(assetLoader);
+            }
+
+            return;
+        }
+
+        // Start/continue loading (asset loader handles duplicates internally)
+        assetLoader.load(this.environmentUrl);
+    }
+
+    /**
+     * Unloads environment resource if currently loaded.
+     *
+     * @param {GSplatAssetLoaderBase} assetLoader - Asset loader used to unload the resource.
+     */
+    unloadEnvironmentResource(assetLoader) {
+        if (this.environmentResource && this.environmentUrl) {
+            assetLoader.unload(this.environmentUrl);
+            this.environmentResource = null;
+        }
+    }
 }
 
 export { GSplatOctree };