Merge branch 'main' into xr-navigation-arc-teleport

Author: willeastcott

src/framework/components/gsplat/component.js

@@ -923,7 +923,7 @@ class GSplatComponent extends Component {
     setParameter(name, data) {
         const scopeId = this.system.app.graphicsDevice.scope.resolve(name);
         this._parameters.set(name, { scopeId, data });
-        if (this._placement) this._placement.renderDirty = true;
+        if (this._placement) this._placement.markDirty();
     }
 
     /**
@@ -943,7 +943,7 @@ class GSplatComponent extends Component {
      */
     deleteParameter(name) {
         this._parameters.delete(name);
-        if (this._placement) this._placement.renderDirty = true;
+        if (this._placement) this._placement.markDirty();
     }
 
     /**

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

@@ -5,6 +5,7 @@ import { BoundingBox } from '../../core/shape/bounding-box.js';
 import { PIXELFORMAT_RGBA32U } from '../../platform/graphics/constants.js';
 import { Texture } from '../../platform/graphics/texture.js';
 import { TextureUtils } from '../../platform/graphics/texture-utils.js';
+import { WORKBUFFER_UPDATE_ALWAYS } from '../constants.js';
 
 /**
  * @import { GraphicsDevice } from "../../platform/graphics/graphics-device.js";
@@ -29,7 +30,10 @@ const _fullRangeInterval = [0, 0];
 /**
  * Represents a snapshot of gsplat state for rendering. This class captures all necessary data
  * at a point in time and should not hold references back to the source placement. All required
- * data should be copied or referenced, allowing placement to be modified without affecting the info.
+ * data should be copied or referenced, allowing placement to be modified without affecting the
+ * info. The only exception is shader configuration and dirty state, which are deliberately read
+ * live through narrow accessor closures (see the fields documented as 'retrieved live'), so that
+ * changes raised after the snapshot was taken are still observed.
  *
  * @ignore
  */
@@ -183,24 +187,45 @@ class GSplatInfo {
     getInstanceStreams = null;
 
     /**
-     * Callback to consume render dirty flag from the source placement.
+     * Function to get the placement that owns the dirty state - the parent placement for child
+     * placements (octree files, environment), the placement itself otherwise. Retrieved live (not
+     * snapshotted) so dirty requests raised after this info was created are still observed.
      *
-     * @type {Function|null}
+     * @type {(() => GSplatPlacement)|null}
      * @private
      */
-    _consumeRenderDirty = null;
+    _getDirtySource = null;
+
+    /**
+     * The last {@link GSplatPlacement#dirtyVersion} this consumer re-copied at. Tracked here (per
+     * camera) rather than on the shared placement, so a single dirty request re-copies every
+     * consumer of the placement exactly once.
+     *
+     * @type {number}
+     * @private
+     */
+    _lastDirtyVersion = -1;
+
+    /**
+     * The last resource format extra-streams version this consumer re-copied at.
+     *
+     * @type {number}
+     * @private
+     */
+    _lastFormatVersion = -1;
 
     /**
      * Create a new GSplatInfo.
      *
      * @param {GraphicsDevice} device - The graphics device.
      * @param {GSplatResourceBase} resource - The splat resource.
-     * @param {GSplatPlacement} placement - The placement of the splat.
-     * @param {Function|null} [consumeRenderDirty] - Callback to consume render dirty flag.
+     * @param {GSplatPlacement} placement - The placement of the splat. Do not store it - snapshot
+     * its data instead, as the placement is mutated for future world states while this info still
+     * renders. Only shader configuration and dirty state may be read live, via accessor closures.
      * @param {GSplatOctreeNode[]|null} [octreeNodes] - Octree nodes for bounds lookup.
      * @param {NodeInfo[]|null} [nodeInfos] - Per-node info array from octree instance.
      */
-    constructor(device, resource, placement, consumeRenderDirty = null, octreeNodes = null, nodeInfos = null) {
+    constructor(device, resource, placement, octreeNodes = null, nodeInfos = null) {
         Debug.assert(resource);
         Debug.assert(placement);
 
@@ -221,7 +246,7 @@ class GSplatInfo {
         this.parameters = placement.parameters;
         this.getWorkBufferModifier = () => placement.workBufferModifier;
         this.getInstanceStreams = () => placement.streams;
-        this._consumeRenderDirty = consumeRenderDirty;
+        this._getDirtySource = () => placement.parentPlacement ?? placement;
         this.octreeNodes = octreeNodes;
         this.nodeInfos = nodeInfos;
 
@@ -439,9 +464,29 @@ class GSplatInfo {
             this.previousWorldTransform.copy(worldMatrix);
         }
 
-        const renderDirty = this._consumeRenderDirty ? this._consumeRenderDirty() : false;
+        let dirty = worldMatrixChanged;
+
+        // One-shot re-copy requests (parameter or modifier changes, or an explicit update) and
+        // the continuous update mode come from the placement - or its parent for child placements
+        // (octree files, environment). The last-seen version is tracked here (per consumer), so a
+        // single request re-copies every consumer of a shared placement exactly once.
+        const source = this._getDirtySource();
+        if (this._lastDirtyVersion !== source.dirtyVersion) {
+            this._lastDirtyVersion = source.dirtyVersion;
+            dirty = true;
+        }
+        if (source.workBufferUpdate === WORKBUFFER_UPDATE_ALWAYS) {
+            dirty = true;
+        }
+
+        // Auto-detect resource format (extra streams) changes, also tracked per consumer.
+        const format = this.resource?.format;
+        if (format && this._lastFormatVersion !== format.extraStreamsVersion) {
+            this._lastFormatVersion = format.extraStreamsVersion;
+            dirty = true;
+        }
 
-        return worldMatrixChanged || renderDirty;
+        return dirty;
     }
 
     /**

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

@@ -1,6 +1,6 @@
 import { Debug } from '../../core/debug.js';
 import { GSplatStreams } from '../gsplat/gsplat-streams.js';
-import { WORKBUFFER_UPDATE_AUTO, WORKBUFFER_UPDATE_ALWAYS, WORKBUFFER_UPDATE_ONCE } from '../constants.js';
+import { WORKBUFFER_UPDATE_AUTO, WORKBUFFER_UPDATE_ONCE } from '../constants.js';
 import { GsplatAllocId } from './gsplat-alloc-id.js';
 
 /**
@@ -175,23 +175,25 @@ class GSplatPlacement {
     lodDirty = false;
 
     /**
-     * Flag indicating the splat needs to be re-rendered to work buffer.
-     */
-    renderDirty = false;
-
-    /**
-     * Work buffer update mode.
+     * Monotonically increasing counter, bumped whenever this placement's splats need to be
+     * re-copied to the work buffer (parameter or modifier changes, or an explicit one-shot update
+     * request). Each consumer (a per-camera {@link GSplatInfo}) remembers the value it last
+     * copied at, so a single request re-copies every consumer of a shared placement exactly once,
+     * and child placements (octree files, environment) fan out from their parent's counter.
      *
      * @type {number}
+     * @ignore
      */
-    workBufferUpdate = WORKBUFFER_UPDATE_AUTO;
+    dirtyVersion = 0;
 
     /**
-     * Last seen format version for auto-detecting format changes.
+     * Work buffer update mode (see WORKBUFFER_UPDATE_*). WORKBUFFER_UPDATE_ONCE is not stored as a
+     * mode - it is converted into a single {@link dirtyVersion} bump.
      *
+     * @type {number}
      * @private
      */
-    _lastFormatVersion = -1;
+    _workBufferUpdate = WORKBUFFER_UPDATE_AUTO;
 
     /**
      * Custom work buffer modifier code for this placement (object with code and pre-computed hash).
@@ -247,7 +249,7 @@ class GSplatPlacement {
      */
     set workBufferModifier(value) {
         this._workBufferModifier = value;
-        this.renderDirty = true;
+        this.dirtyVersion++;
     }
 
     /**
@@ -261,31 +263,35 @@ class GSplatPlacement {
     }
 
     /**
-     * Returns and clears the render dirty flag. Also checks for format version changes
-     * and handles render mode.
+     * Sets the work buffer update mode (see WORKBUFFER_UPDATE_*). WORKBUFFER_UPDATE_ONCE is turned
+     * into a single {@link dirtyVersion} bump so every consumer re-copies once, rather than being
+     * stored as a persistent mode.
      *
-     * @returns {boolean} True if the splat needed re-rendering.
-     */
-    consumeRenderDirty() {
-        // Auto-detect format version changes
-        // Cast to access format property (GSplatOctreeResource doesn't have format)
-        const format = /** @type {GSplatResourceBase} */ (this.resource)?.format;
-        if (format && this._lastFormatVersion !== format.extraStreamsVersion) {
-            this._lastFormatVersion = format.extraStreamsVersion;
-            this.renderDirty = true;
+     * @type {number}
+     */
+    set workBufferUpdate(value) {
+        if (value === WORKBUFFER_UPDATE_ONCE) {
+            this.dirtyVersion++;
+        } else {
+            this._workBufferUpdate = value;
         }
+    }
 
-        // Handle work buffer update mode
-        if (this.workBufferUpdate === WORKBUFFER_UPDATE_ALWAYS) {
-            this.renderDirty = true;
-        } else if (this.workBufferUpdate === WORKBUFFER_UPDATE_ONCE) {
-            this.renderDirty = true;
-            this.workBufferUpdate = WORKBUFFER_UPDATE_AUTO;  // Auto-reset
-        }
+    /**
+     * Gets the work buffer update mode.
+     *
+     * @type {number}
+     */
+    get workBufferUpdate() {
+        return this._workBufferUpdate;
+    }
 
-        const dirty = this.renderDirty;
-        this.renderDirty = false;
-        return dirty;
+    /**
+     * Marks the placement as needing a one-time re-copy to the work buffer by all of its
+     * consumers.
+     */
+    markDirty() {
+        this.dirtyVersion++;
     }
 
     /**

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

@@ -613,7 +613,7 @@ class GSplatWorld {
                 continue;
             }
             p.ensureInstanceStreams(this._device);
-            const splatInfo = new GSplatInfo(this._device, p.resource, p, p.consumeRenderDirty.bind(p));
+            const splatInfo = new GSplatInfo(this._device, p.resource, p);
             splats.push(splatInfo);
         }
 
@@ -629,7 +629,7 @@ class GSplatWorld {
                     p.ensureInstanceStreams(this._device);
                     const octreeNodes = p.intervals.size > 0 ? inst.octree.nodes : null;
                     const nodeInfos = octreeNodes ? inst.nodeInfos : null;
-                    const splatInfo = new GSplatInfo(this._device, p.resource, p, p.consumeRenderDirty.bind(p), octreeNodes, nodeInfos);
+                    const splatInfo = new GSplatInfo(this._device, p.resource, p, octreeNodes, nodeInfos);
                     splats.push(splatInfo);
                 }
             });

test/framework/components/gsplat/component.test.mjs

@@ -1,6 +1,7 @@
 import { expect } from 'chai';
 
 import { Entity } from '../../../../src/framework/entity.js';
+import { GSplatPlacement } from '../../../../src/scene/gsplat-unified/gsplat-placement.js';
 import { createApp } from '../../../app.mjs';
 import { jsdomSetup, jsdomTeardown } from '../../../jsdom.mjs';
 
@@ -70,6 +71,28 @@ describe('GSplatComponent', function () {
 
     });
 
+    describe('#parameters', function () {
+
+        it('marks the placement dirty on setParameter and deleteParameter', function () {
+            const e = new Entity();
+            e.addComponent('gsplat');
+
+            const placement = new GSplatPlacement(null, e);
+            e.gsplat._placement = placement;
+
+            const v0 = placement.dirtyVersion;
+            e.gsplat.setParameter('uTest', 1);
+            expect(e.gsplat.getParameter('uTest')).to.equal(1);
+            expect(placement.dirtyVersion).to.be.above(v0);
+
+            const v1 = placement.dirtyVersion;
+            e.gsplat.deleteParameter('uTest');
+            expect(e.gsplat.getParameter('uTest')).to.be.undefined;
+            expect(placement.dirtyVersion).to.be.above(v1);
+        });
+
+    });
+
     describe('#cloneComponent', function () {
 
         it('copies LOD properties to the clone', function () {

test/scene/gsplat-unified/gsplat-placement.test.mjs

@@ -0,0 +1,48 @@
+import { expect } from 'chai';
+
+import { WORKBUFFER_UPDATE_ALWAYS, WORKBUFFER_UPDATE_AUTO, WORKBUFFER_UPDATE_ONCE } from '../../../src/scene/constants.js';
+import { GraphNode } from '../../../src/scene/graph-node.js';
+import { GSplatPlacement } from '../../../src/scene/gsplat-unified/gsplat-placement.js';
+
+describe('GSplatPlacement', function () {
+
+    describe('dirty state', function () {
+
+        it('starts with dirtyVersion 0 and AUTO update mode', function () {
+            const placement = new GSplatPlacement(null, new GraphNode());
+            expect(placement.dirtyVersion).to.equal(0);
+            expect(placement.workBufferUpdate).to.equal(WORKBUFFER_UPDATE_AUTO);
+        });
+
+        it('markDirty increments dirtyVersion', function () {
+            const placement = new GSplatPlacement(null, new GraphNode());
+            placement.markDirty();
+            expect(placement.dirtyVersion).to.equal(1);
+            placement.markDirty();
+            expect(placement.dirtyVersion).to.equal(2);
+        });
+
+        it('WORKBUFFER_UPDATE_ONCE bumps dirtyVersion without changing the stored mode', function () {
+            const placement = new GSplatPlacement(null, new GraphNode());
+            placement.workBufferUpdate = WORKBUFFER_UPDATE_ONCE;
+            expect(placement.dirtyVersion).to.equal(1);
+            expect(placement.workBufferUpdate).to.equal(WORKBUFFER_UPDATE_AUTO);
+        });
+
+        it('WORKBUFFER_UPDATE_ALWAYS sets the mode without bumping dirtyVersion', function () {
+            const placement = new GSplatPlacement(null, new GraphNode());
+            placement.workBufferUpdate = WORKBUFFER_UPDATE_ALWAYS;
+            expect(placement.dirtyVersion).to.equal(0);
+            expect(placement.workBufferUpdate).to.equal(WORKBUFFER_UPDATE_ALWAYS);
+        });
+
+        it('setting workBufferModifier bumps dirtyVersion', function () {
+            const placement = new GSplatPlacement(null, new GraphNode());
+            placement.workBufferModifier = { code: 'void modifySplatCenter() {}', hash: 1 };
+            expect(placement.dirtyVersion).to.equal(1);
+            placement.workBufferModifier = null;
+            expect(placement.dirtyVersion).to.equal(2);
+        });
+
+    });
+});