@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/rasterize/native/avboit/graph_rasterize_meshes_transparent_avboit.js

@@ -766,7 +766,7 @@ export function graph_rasterize_meshes_transparent_avboit({
      */
     const materials_double = [];
 
-    const scene_materials = scene_ctx.scene.instances.materials;
+    const scene_materials = scene_ctx.drawn_materials;
 
     // Front-sided and double-sided materials need different pipeline states, so every raster pass
     // below runs twice. `ShadeDrawSide.Back` is not drawn, the same as under MBOIT (plan §7).

package/src/shade/renderer/rasterize/native/graph_rasterize_meshes_alpha_tested.js

@@ -68,7 +68,7 @@ export function graph_rasterize_meshes_alpha_tested({
      * @type {ShadeMaterial[]}
      */
     const relevant_materials = [];
-    const scene_materials = scene_ctx.scene.instances.materials;
+    const scene_materials = scene_ctx.drawn_materials;
 
     const material_count = filter_materials_by_bucket(
         relevant_materials, 0,

package/src/shade/renderer/rasterize/native/oit/graph_rasterize_meshes_transparent_oit.js

@@ -481,7 +481,7 @@ export function graph_rasterize_meshes_transparent_oit({
      */
     const materials_double = [];
 
-    const scene_materials = scene_ctx.scene.instances.materials;
+    const scene_materials = scene_ctx.drawn_materials;
 
     // we need to draw with different pipeline states, so the code is a little convoluted
     // Essentially, we draw Double-side and Front-sided materials

package/src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_partial_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;GAeG;AACH,gMAFa;IAAC,eAAe,EAAC,MAAM,CAAC;IAAC,cAAc,EAAC,MAAM,CAAC;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CA8LjG"}
+{"version":3,"file":"graph_rasterize_partial_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;GAeG;AACH,gMAFa;IAAC,eAAe,EAAC,MAAM,CAAC;IAAC,cAAc,EAAC,MAAM,CAAC;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CAwMjG"}

package/src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js

@@ -17,6 +17,7 @@ import {
 import { rasterization_material_bucket } from "../expand/bucket/chunk_rasterization_material_bucket.js";
 import { graph_meshlets_rasterize } from "../expand/graph_meshlets_rasterize.js";
 import { graph_expand_meshes_to_meshlets } from "../expand/mesh/graph_expand_meshes_to_meshlets.js";
+import { graph_vgeo_expand_if_enabled } from "../../geometry/virtual/runtime/graph_vgeo_expand_if_enabled.js";
 import { MeshletFilter2WayPassData, pass_filter_meshlets_2way } from "../expand/pass1/pass_filter_meshlets_2way.js";
 import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
 import { construct_primitive_state, CullPolicy } from "../bucket/construct_primitive_state.js";
@@ -166,7 +167,7 @@ export function graph_rasterize_partial_opaque({
 
             gr_instances_maybe = pass_data_instances_0.instances_maybe = pass_instances_0.write(gr_instances_maybe);
 
-            const meshlet_expansion_0 = graph_expand_meshes_to_meshlets({
+            let meshlet_expansion_0 = graph_expand_meshes_to_meshlets({
                 graph,
                 input_meshes: pass_data_instances_0.instances_positive,
                 scene: scene_ctx,
@@ -174,6 +175,16 @@ export function graph_rasterize_partial_opaque({
                 limits,
             });
 
+            // the seam. The instance sets of the two HZB passes are disjoint, so cutting each of
+            // them costs one cut per view in total and no instance is ever cut twice
+            meshlet_expansion_0 = graph_vgeo_expand_if_enabled({
+                graph,
+                input_meshes: pass_data_instances_0.instances_positive,
+                output_meshlets: meshlet_expansion_0,
+                view,
+                limits,
+            });
+
 
             graph_record_stat(graph, limits.stats, RasterizationCollectionType.Meshlets, meshlet_expansion_0);
 

package/src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_remaining_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js"],"names":[],"mappings":"AAyFA;;;;;;;;;;;;;;;;;GAiBG;AACH,kOAFa;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CAmGlD"}
+{"version":3,"file":"graph_rasterize_remaining_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js"],"names":[],"mappings":"AA0FA;;;;;;;;;;;;;;;;;GAiBG;AACH,kOAFa;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CA4GlD"}

package/src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js

@@ -14,6 +14,7 @@ import { graph_mesh_filter_one_way } from "../expand/graph_mesh_filter_one_way.j
 import { graph_meshlets_filter_one_way } from "../expand/graph_meshlets_filter_one_way.js";
 import { graph_meshlets_rasterize } from "../expand/graph_meshlets_rasterize.js";
 import { graph_expand_meshes_to_meshlets } from "../expand/mesh/graph_expand_meshes_to_meshlets.js";
+import { graph_vgeo_expand_if_enabled } from "../../geometry/virtual/runtime/graph_vgeo_expand_if_enabled.js";
 import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
 import { construct_primitive_state, CullPolicy } from "../bucket/construct_primitive_state.js";
 
@@ -144,6 +145,15 @@ export function graph_rasterize_remaining_opaque({
         limits,
     });
 
+    // the seam, on the instances the first pass could not decide about
+    gr_live_meshlets = graph_vgeo_expand_if_enabled({
+        graph,
+        input_meshes: gr_live_instances,
+        output_meshlets: gr_live_meshlets,
+        view,
+        limits,
+    });
+
     graph_record_stat(graph, limits.stats, RasterizationCollectionType.Meshlets, gr_live_meshlets);
 
     // cull meshlets against new HZB

package/src/shade/renderer/rasterize/standard/graph_rasterize_scene.js

@@ -48,7 +48,7 @@ export function graph_rasterize_scene({
     const active_buckets = new Set();
 
     const scene_ctx = view_ctx.scene;
-    const cached_materials = scene_ctx.scene.instances.materials;
+    const cached_materials = scene_ctx.drawn_materials;
 
     for (const material of cached_materials) {
         const bucket_id = rasterization_material_bucket(material.transparency_mode, material.draw_mode, material.draw_side);

package/src/shade/renderer/scene/DynamicMesh.d.ts

@@ -9,19 +9,28 @@
  * frame to force such content down the static path is explicitly not the answer.
  *
  * So a `DynamicMesh` holds a plain {@link Geometry}: attribute arrays and an index, uploaded as
- * they are and drawn by a pass of their own. It is not part of the scene's instance batch and gets
- * no row in the scene database — the meshlet pipeline never sees it.
+ * they are and drawn by a pass of their own. It is not part of the scene's instance batch, gets
+ * no row in the scene database — the meshlet pipeline never sees it — and is a node of nothing:
+ * the world transform the draw applies is its own {@link transform}, with nothing above it.
  *
  * Its geometry says when it has changed through {@link Geometry.needsUpdate}; nothing watches the
  * arrays.
  */
-export class DynamicMesh extends Node3D {
+export class DynamicMesh {
     /**
      * @param {Geometry} geometry
      * @param {Float32Array|number[]} [color]
      * @returns {DynamicMesh}
      */
     static from(geometry: Geometry, color?: Float32Array | number[]): DynamicMesh;
+    /**
+     * World transform the draw applies to the vertices. Identity until moved — and the systems
+     * that write world-space vertices never move it. What the draw binds is its matrix, so a mover
+     * calls `updateMatrix()` after a rotation or scale change, as with any `Transform64`.
+     *
+     * @type {Transform64}
+     */
+    transform: Transform64;
     /**
      * Vertex data, drawn as it stands. Must carry a position attribute and an index.
      *
@@ -49,5 +58,5 @@ export class DynamicMesh extends Node3D {
      */
     readonly isDynamicMesh: boolean;
 }
-import { Node3D } from "./Node3D.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 //# sourceMappingURL=DynamicMesh.d.ts.map

package/src/shade/renderer/scene/DynamicMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DynamicMesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/DynamicMesh.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH;IAyBI;;;;OAIG;IACH,wCAHW,YAAY,GAAC,MAAM,EAAE,GACnB,WAAW,CAcvB;IAzCD;;;;OAIG;IACH,mBAAgB;IAEhB;;;;;OAKG;IACH,OAFU,YAAY,CAEiB;IAEvC;;;;;;OAMG;IACH,SAFU,OAAO,CAEF;IAsBnB;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;uBA9DsB,aAAa"}
+{"version":3,"file":"DynamicMesh.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/DynamicMesh.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAkCI;;;;OAIG;IACH,wCAHW,YAAY,GAAC,MAAM,EAAE,GACnB,WAAW,CAcvB;IAlDD;;;;;;OAMG;IACH,WAFU,WAAW,CAES;IAE9B;;;;OAIG;IACH,mBAAgB;IAEhB;;;;;OAKG;IACH,OAFU,YAAY,CAEiB;IAEvC;;;;;;OAMG;IACH,SAFU,OAAO,CAEF;IAsBnB;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;4BAxE2B,8CAA8C"}

package/src/shade/renderer/scene/DynamicMesh.js

@@ -1,5 +1,5 @@
 import { assert } from "../../../core/assert.js";
-import { Node3D } from "./Node3D.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 
 /**
  * A mesh whose vertices are expected to change, drawn straight from its attributes.
@@ -12,13 +12,23 @@ import { Node3D } from "./Node3D.js";
  * frame to force such content down the static path is explicitly not the answer.
  *
  * So a `DynamicMesh` holds a plain {@link Geometry}: attribute arrays and an index, uploaded as
- * they are and drawn by a pass of their own. It is not part of the scene's instance batch and gets
- * no row in the scene database — the meshlet pipeline never sees it.
+ * they are and drawn by a pass of their own. It is not part of the scene's instance batch, gets
+ * no row in the scene database — the meshlet pipeline never sees it — and is a node of nothing:
+ * the world transform the draw applies is its own {@link transform}, with nothing above it.
  *
  * Its geometry says when it has changed through {@link Geometry.needsUpdate}; nothing watches the
  * arrays.
  */
-export class DynamicMesh extends Node3D {
+export class DynamicMesh {
+    /**
+     * World transform the draw applies to the vertices. Identity until moved — and the systems
+     * that write world-space vertices never move it. What the draw binds is its matrix, so a mover
+     * calls `updateMatrix()` after a rotation or scale change, as with any `Transform64`.
+     *
+     * @type {Transform64}
+     */
+    transform = new Transform64();
+
     /**
      * Vertex data, drawn as it stands. Must carry a position attribute and an index.
      *

package/src/shade/renderer/scene/GPUInstancesAccelerationStructure.d.ts

@@ -7,13 +7,6 @@ export class GPUInstancesAccelerationStructure {
      * @param {GraphicsContext} graphics
      */
     constructor(graphics: GraphicsContext);
-    /**
-     * The CPU-side tree. Still maintained incrementally by the `instance_*` methods and still walked
-     * by CPU queries — {@link DirectionalLightShadowmap} runs `compute_tight_near_far_clipping_planes`
-     * against it per cascade per frame. What the GPU build retires is the per-frame treelet pass and
-     * the full flatten-and-upload, not the tree.
-     */
-    get bvh(): BVH;
     clear(): void;
     /**
      *
@@ -21,36 +14,63 @@ export class GPUInstancesAccelerationStructure {
      */
     get buffer(): GPUBuffer;
     /**
+     * A `meshes` row has come into the scene.
      *
      * @param {number} index
-     * @param {Mesh} instance
      */
-    instance_add(index: number, instance: Mesh): void;
+    instance_add(index: number): void;
     /**
-     * Drop an instance previously handed to {@link instance_add}. The leaf is unlinked and its node
-     * returned to the pool, so the tree stays proportional to what is in the scene rather than to
-     * everything that ever was.
+     * Drop a row previously handed to {@link instance_add}, so the tree stays proportional to what
+     * is in the scene rather than to everything that ever was.
      *
      * @param {number} index
      */
     instance_remove(index: number): void;
     /**
+     * A row's bounds moved: the next {@link update} rebuilds.
      *
      * @param {number} index
-     * @param {Mesh} instance
      */
-    instance_update(index: number, instance: Mesh): void;
+    instance_update(index: number): void;
+    /**
+     * Build the tree, from the world AABBs the scene database holds.
+     *
+     * @param {GPUBuffer} scene_database_buffer
+     */
+    /**
+     * Something moved on the GPU that this tree is built over — bounds the CPU never saw change.
+     * The next {@link update} rebuilds.
+     */
+    invalidate(): void;
+    /**
+     * The bounds of everything in the tree, read back from its root node: the box the GPU built
+     * the tree under, the union of every live row's bounds as the bounds pass derived them — the
+     * whole scene, whoever placed what. For a consumer that sizes work by the scene once, a probe
+     * placement or a bake; a frame-loop reader wants the scene database's readback service.
+     *
+     * Resolves once the copy has landed and been mapped, which is after the device has finished
+     * whatever build was submitted before this call — so build first, ask after. Resolves `false`
+     * for an empty tree, leaving `target` alone.
+     *
+     * @param {Float32Array|Float64Array|number[]} target six numbers, `x0,y0,z0,x1,y1,z1`
+     * @returns {Promise<boolean>}
+     */
+    read_scene_bounds(target: Float32Array | Float64Array | number[]): Promise<boolean>;
     /**
      * @param {GPUBuffer} scene_database_buffer the table the world AABBs are read from
+     * @param {ShadeGPUCommandContext} [cmd_ctx]
      */
-    push_to_gpu(scene_database_buffer: GPUBuffer): void;
+    push_to_gpu(scene_database_buffer: GPUBuffer, cmd_ctx?: ShadeGPUCommandContext): void;
     /**
+     * Rebuild if anything moved since the last build.
+     *
      * @param {GPUBuffer} scene_database_buffer
+     * @param {ShadeGPUCommandContext} [cmd_ctx] encode into this context rather than submitting
+     * on its own — what a frame does, so the build follows the bounds pass it reads
      */
-    update(scene_database_buffer: GPUBuffer): void;
+    update(scene_database_buffer: GPUBuffer, cmd_ctx?: ShadeGPUCommandContext): void;
     #private;
 }
 export type GraphicsContext = import("../GraphicsContext.js").GraphicsContext;
-export type Mesh = import("./Mesh.js").Mesh;
-import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 //# sourceMappingURL=GPUInstancesAccelerationStructure.d.ts.map

package/src/shade/renderer/scene/GPUInstancesAccelerationStructure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUInstancesAccelerationStructure.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUInstancesAccelerationStructure.js"],"names":[],"mappings":"AAoCA;;GAEG;AACH;IA2EI;;;OAGG;IACH,sBAFW,eAAe,EAgBzB;IA/ED;;;;;OAKG;IACH,eAEC;IAED,cAKC;IAOD;;;OAGG;IACH,wBAEC;IA2DD;;;;OAIG;IACH,oBAHW,MAAM,YACN,IAAI,QAkBd;IAED;;;;;;OAMG;IACH,uBAFW,MAAM,QAkBhB;IAED;;;;OAIG;IACH,uBAHW,MAAM,YACN,IAAI,QAWd;IAuID;;OAEG;IACH,oDAIC;IAED;;OAEG;IACH,+CAMC;;CACJ;8BAzVY,OAAO,uBAAuB,EAAE,eAAe;mBAC/C,OAAO,WAAW,EAAE,IAAI;oBAXjB,gCAAgC"}
+{"version":3,"file":"GPUInstancesAccelerationStructure.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUInstancesAccelerationStructure.js"],"names":[],"mappings":"AAmCA;;GAEG;AACH;IA8DI;;;OAGG;IACH,sBAFW,eAAe,EAqBzB;IAzED,cAIC;IAOD;;;OAGG;IACH,wBAEC;IAmED;;;;OAIG;IACH,oBAFW,MAAM,QAUhB;IAED;;;;;OAKG;IACH,uBAFW,MAAM,QAUhB;IAED;;;;OAIG;IACH,uBAFW,MAAM,QAOhB;IA8CD;;;;OAIG;IACH;;;OAGG;IACH,mBAEC;IAiGD;;;;;;;;;;;;OAYG;IACH,0BAHW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,GAChC,QAAQ,OAAO,CAAC,CA0C5B;IAED;;;OAGG;IACH,wDAFW,sBAAsB,QAMhC;IAED;;;;;;OAMG;IACH,mDAHW,sBAAsB,QAShC;;CACJ;8BA7YY,OAAO,uBAAuB,EAAE,eAAe;uCARrB,wCAAwC"}

package/src/shade/renderer/scene/GPUInstancesAccelerationStructure.js

@@ -1,16 +1,15 @@
 import { assert } from "../../../core/assert.js";
-import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
 import { FrameGraph } from "../../../engine/graphics/render/frame_graph/FrameGraph.js";
 import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 import { ensure_buffer_capacity } from "../geometry/make_temp_gpu_buffer.js";
-import { bvh_buffer_size } from "../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import { BVH_HEADER_WORDS, BVH_NODE_STRIDE_WORDS, bvh_buffer_size } from "../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import { BVH_NULL_NODE, bvh_tree_views, read_bvh_node } from "../gpu_primitive/bvh/check_bvh_structure.js";
 import { graph_bvh_build_lbvh } from "../gpu_primitive/bvh/graph_bvh_build_lbvh.js";
 import { shader_bvh_extract_instance_leaves } from "./shader_bvh_extract_instance_leaves.js";
 
 /**
  * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
- * @typedef {import("./Mesh.js").Mesh} Mesh
  */
 
 /**
@@ -49,21 +48,8 @@ export class GPUInstancesAccelerationStructure {
      */
     #device
 
-    #bvh = new BVH();
-
-    /**
-     * The CPU-side tree. Still maintained incrementally by the `instance_*` methods and still walked
-     * by CPU queries — {@link DirectionalLightShadowmap} runs `compute_tight_near_far_clipping_planes`
-     * against it per cascade per frame. What the GPU build retires is the per-frame treelet pass and
-     * the full flatten-and-upload, not the tree.
-     */
-    get bvh() {
-        return this.#bvh;
-    }
-
     clear() {
-        this.#bvh.release_all();
-        this.#node_mapping.clear();
+        this.#live.clear();
         this.#membership_version++;
         this.#version++;
     }
@@ -101,7 +87,7 @@ export class GPUInstancesAccelerationStructure {
 
     /**
      * Compact mirror of the live `meshes` rows, in insertion order. Rebuilt from
-     * {@link #node_mapping} when membership churns.
+     * {@link #live} when membership churns.
      *
      * @type {Uint32Array}
      */
@@ -130,74 +116,61 @@ export class GPUInstancesAccelerationStructure {
             size: 1024,
             usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
         });
+
+        // A fresh buffer holds zeroes, and zero is a root word naming node 0 — a tree that was never
+        // built would read as one with a root of zero bounds. Empty, until the first build says
+        // otherwise.
+        device.queue.writeBuffer(this.#buffer, 0, EMPTY_TREE);
     }
 
     /**
+     * The live `meshes` rows, in insertion order — what the build extracts leaves from. There is
+     * no tree on this side: the tree is the GPU's, built from the bounds the GPU holds, and every
+     * query walks it there.
      *
-     * @type {Map<number, number>}
+     * @type {Set<number>}
      */
-    #node_mapping = new Map();
+    #live = new Set();
 
     /**
+     * A `meshes` row has come into the scene.
      *
      * @param {number} index
-     * @param {Mesh} instance
      */
-    instance_add(index, instance) {
+    instance_add(index) {
         assert.isNonNegativeInteger(index, 'index');
-        assert.defined(instance, 'instance');
-
-        const bvh = this.#bvh;
+        assert.equal(this.#live.has(index), false, 'the row is already in the TLAS');
 
-        const node = bvh.allocate_node();
-        bvh.node_set_user_data(node, index);
-        bvh.node_set_aabb(node, instance.bounding_box);
-
-        bvh.insert_leaf(node);
-
-        this.#node_mapping.set(index, node);
+        this.#live.add(index);
 
         this.#membership_version++;
         this.#version++;
     }
 
     /**
-     * Drop an instance previously handed to {@link instance_add}. The leaf is unlinked and its node
-     * returned to the pool, so the tree stays proportional to what is in the scene rather than to
-     * everything that ever was.
+     * Drop a row previously handed to {@link instance_add}, so the tree stays proportional to what
+     * is in the scene rather than to everything that ever was.
      *
      * @param {number} index
      */
     instance_remove(index) {
         assert.isNonNegativeInteger(index, 'index');
+        assert.equal(this.#live.has(index), true, 'the row is not in the TLAS');
 
-        const node = this.#node_mapping.get(index);
-
-        assert.defined(node, 'node');
-
-        const bvh = this.#bvh;
-
-        bvh.remove_leaf(node);
-        bvh.release_node(node);
-
-        this.#node_mapping.delete(index);
+        this.#live.delete(index);
 
         this.#membership_version++;
         this.#version++;
     }
 
     /**
+     * A row's bounds moved: the next {@link update} rebuilds.
      *
      * @param {number} index
-     * @param {Mesh} instance
      */
-    instance_update(index, instance) {
+    instance_update(index) {
         assert.isNonNegativeInteger(index, 'index');
-        assert.defined(instance, 'instance');
-
-        const node = this.#node_mapping.get(index);
-
-        this.#bvh.node_move_aabb(node, instance.bounding_box);
+        assert.equal(this.#live.has(index), true, 'the row is not in the TLAS');
 
         this.#version++;
     }
@@ -208,7 +181,7 @@ export class GPUInstancesAccelerationStructure {
      * @returns {number} number of live rows
      */
     #refresh_rows() {
-        const count = this.#node_mapping.size;
+        const count = this.#live.size;
 
         if (this.#rows_gpu_version === this.#membership_version && this.#rows.length >= count) {
             return count;
@@ -219,7 +192,7 @@ export class GPUInstancesAccelerationStructure {
         }
 
         let i = 0;
-        for (const row of this.#node_mapping.keys()) {
+        for (const row of this.#live) {
             this.#rows[i] = row;
             i++;
         }
@@ -251,12 +224,25 @@ export class GPUInstancesAccelerationStructure {
      *
      * @param {GPUBuffer} scene_database_buffer
      */
-    #build(scene_database_buffer) {
+    /**
+     * Something moved on the GPU that this tree is built over — bounds the CPU never saw change.
+     * The next {@link update} rebuilds.
+     */
+    invalidate() {
+        this.#version++;
+    }
+
+    /**
+     * @param {GPUBuffer} scene_database_buffer
+     * @param {ShadeGPUCommandContext} [cmd_ctx] a context to encode the build into; when absent
+     * the build is submitted on its own, ahead of anything not yet submitted
+     */
+    #build(scene_database_buffer, cmd_ctx) {
         assert.defined(scene_database_buffer, 'scene_database_buffer');
 
         const device = this.#device;
 
-        const element_count = this.#node_mapping.size;
+        const element_count = this.#live.size;
 
         // `ensure_buffer_capacity` can hand back a NEW buffer and destroy the old one. Consumers are
         // safe because they read `tlas.buffer` per frame at pass-execute time — but the field has to
@@ -329,30 +315,96 @@ export class GPUInstancesAccelerationStructure {
             nodes,
         });
 
+        if (cmd_ctx !== undefined) {
+            cmd_ctx.encodeGraph(graph);
+
+            return;
+        }
+
         const cmd = ShadeGPUCommandContext.create(this.#graphics, 'TLAS/build');
 
         cmd.encodeGraph(graph);
         cmd.finish();
     }
 
+    /**
+     * The bounds of everything in the tree, read back from its root node: the box the GPU built
+     * the tree under, the union of every live row's bounds as the bounds pass derived them — the
+     * whole scene, whoever placed what. For a consumer that sizes work by the scene once, a probe
+     * placement or a bake; a frame-loop reader wants the scene database's readback service.
+     *
+     * Resolves once the copy has landed and been mapped, which is after the device has finished
+     * whatever build was submitted before this call — so build first, ask after. Resolves `false`
+     * for an empty tree, leaving `target` alone.
+     *
+     * @param {Float32Array|Float64Array|number[]} target six numbers, `x0,y0,z0,x1,y1,z1`
+     * @returns {Promise<boolean>}
+     */
+    async read_scene_bounds(target) {
+        assert.isArrayLike(target, 'target');
+        assert.greaterThanOrEqual(target.length, 6, 'target.length < 6');
+
+        // the root word and node 0 — the root by the builder's construction
+        const byte_size = (BVH_HEADER_WORDS + BVH_NODE_STRIDE_WORDS) * Uint32Array.BYTES_PER_ELEMENT;
+
+        const allocator = this.#graphics.buffer_allocator_readback;
+        const staging = allocator.get(byte_size);
+
+        const cmd = ShadeGPUCommandContext.create(this.#graphics, 'TLAS/read scene bounds');
+
+        cmd.copyBufferToBuffer(this.#buffer, 0, staging, 0, byte_size);
+        cmd.finish();
+
+        await staging.mapAsync(GPUMapMode.READ, 0, byte_size);
+
+        const { words, floats } = bvh_tree_views(new Uint32Array(staging.getMappedRange(0, byte_size)));
+        const root = words[0];
+
+        let found = false;
+
+        if (root !== BVH_NULL_NODE) {
+            assert.equal(root, 0, 'the tree\'s root is not node 0');
+
+            const node = read_bvh_node(words, floats, root);
+
+            target[0] = node.low[0];
+            target[1] = node.low[1];
+            target[2] = node.low[2];
+            target[3] = node.high[0];
+            target[4] = node.high[1];
+            target[5] = node.high[2];
+
+            found = true;
+        }
+
+        allocator.release(staging);
+
+        return found;
+    }
+
     /**
      * @param {GPUBuffer} scene_database_buffer the table the world AABBs are read from
+     * @param {ShadeGPUCommandContext} [cmd_ctx]
      */
-    push_to_gpu(scene_database_buffer) {
-        this.#build(scene_database_buffer);
+    push_to_gpu(scene_database_buffer, cmd_ctx) {
+        this.#build(scene_database_buffer, cmd_ctx);
 
         this.#gpu_version = this.#version;
     }
 
     /**
+     * Rebuild if anything moved since the last build.
+     *
      * @param {GPUBuffer} scene_database_buffer
+     * @param {ShadeGPUCommandContext} [cmd_ctx] encode into this context rather than submitting
+     * on its own — what a frame does, so the build follows the bounds pass it reads
      */
-    update(scene_database_buffer) {
+    update(scene_database_buffer, cmd_ctx) {
         if (this.#gpu_version === this.#version) {
             return;
         }
 
-        this.push_to_gpu(scene_database_buffer);
+        this.push_to_gpu(scene_database_buffer, cmd_ctx);
     }
 }