@woosh/meep-engine 3.23.0 → 3.24.0

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);
     }
 }
 

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

@@ -1,5 +1,12 @@
 /**
- * Abstraction on the context of a scene, there are no hierarchies, just a collection of meshes and a geometry context
+ * The GPU side of one {@link Scene}: its database — the `transforms` and `meshes` tables, one row
+ * per entity that is drawn or posed, at `entity + 1` — and what is built over that database each
+ * frame: the lights' records, the probe volume, the volumetrics, the animation, the TLAS.
+ *
+ * Nothing here holds a hierarchy of its own. An entity's row names its parent's row and the GPU
+ * composes the chain each frame, derives every mesh row's bounds under the composed matrix and
+ * builds the tree over them — see {@link tick}. What the CPU writes is what it owns: an entity's
+ * local TRS and the row of its parent, through {@link rows}.
  */
 export class GPUSceneContext {
     /**
@@ -46,22 +53,6 @@ export class GPUSceneContext {
      * @returns {GPUInstancesAccelerationStructure}
      */
     get tlas(): GPUInstancesAccelerationStructure;
-    /**
-     * Mesh → instance index. Rebuilt each frame in {@link build}. The
-     * Lookup from a node's stable JS-side {@link Node3D.id} to its row
-     * in the scene database's `transforms` table. Built during
-     * {@link build} as each node is allocated via
-     * {@link GPUTypedTable.add}; the table itself owns the row
-     * allocation, this map just bridges between Node3D handles and the
-     * GPU rows they live at.
-     *
-     * Public so external code can do partial updates: looking up a
-     * single node's row lets a system patch one `transforms_table`
-     * entry instead of re-uploading the whole scene.
-     *
-     * @type {Map<number, number>}
-     */
-    id_mapping: Map<number, number>;
     /**
      * @returns {GPUAnimationManager}
      */
@@ -79,10 +70,9 @@ export class GPUSceneContext {
      */
     get scene_database_buffer(): GPUBuffer;
     /**
-     * Per-scene skinning subsystem. Routes {@link SkinnedMesh}
-     * instances through per-instance geometry clones; later phases
-     * grow Skin-binding management and the per-frame skinning compute
-     * onto it.
+     * Per-scene skinning subsystem. Routes skinned rows through
+     * per-instance geometry clones; later phases grow Skin-binding
+     * management and the per-frame skinning compute onto it.
      *
      * Lazy because it depends on {@link geometries}, which is assigned
      * externally after this object's constructor returns
@@ -94,32 +84,37 @@ export class GPUSceneContext {
     get skinning(): GPUMeshSkinningContext;
     get gpu_memory_usage(): number;
     /**
-     * Which row of the `meshes` table a node occupies — **the value the visibility buffer writes
-     * for every pixel that node covers**, which is what makes it worth reading from outside.
+     * Entities as rows of the scene database, at `entity + 1` in both tables.
      *
-     * `id_mapping` is not this. That map goes from a node's id to its row in the `transforms`
-     * table, which is a different table with different rows; a caller that used it to index the
-     * visibility buffer would be reading somebody else's mesh.
+     * A system that places an entity acquires its row here and marks it on the dataset's change
+     * events; a scene with no systems places through `prefab_place` and `place_primitive`, which
+     * do the same by hand; and {@link build} flushes what was marked. The scene has to name its
+     * dataset ({@link Scene.dataset}) before this is first asked for, because the rows are written
+     * from that dataset's components.
      *
-     * @param {Node3D} node
-     * @returns {number} the row, or `-1` for a node that is not in this scene or carries no geometry
+     * @returns {GPUSceneRows}
      */
-    mesh_row_of(node: Node3D): number;
+    get rows(): GPUSceneRows;
     /**
-     * Bumped every time the `meshes` table gains or loses a row. **Rows are reused** — the table
-     * hands out the lowest free one — so a row read through {@link mesh_row_of} and kept is only
-     * valid while this number is unchanged. Anything holding one compares against its own copy and
-     * re-reads when they differ.
+     * An entity's world bounds as the GPU holds them, read back — what a consumer that wants the
+     * box that is drawn asks, a frame or two behind the device. Built on demand, over the rows.
      *
-     * @returns {number}
+     * @returns {GPUEntityBoundsReadback}
      */
-    get mesh_rows_version(): number;
+    get bounds(): GPUEntityBoundsReadback;
     /**
-     * Bring the GPU scene database in line with the scene, writing only the rows that changed.
+     * Every material something in the scene draws with, each once — the rows' own list, kept
+     * current as meshes attach and detach. What the rasterizers iterate to decide which buckets
+     * and pipelines a frame needs. The array is reused until the set changes; a scene with no
+     * rows draws with nothing.
      *
-     * Membership is reconciled when the batch says it moved; transforms are checked every frame,
-     * because a node moving does not touch the batch. Both walk the scene once and write nothing
-     * for a node that has not changed.
+     * @returns {ShadeMaterial[]}
+     */
+    get drawn_materials(): import("../material/ShadeMaterial.js").ShadeMaterial[];
+    /**
+     * Bring the GPU scene database in line with the scene, writing only the rows that changed:
+     * the scene root's, once; a light's, as it arrives; and every entity's row that a system
+     * marked since the last build. Nothing is walked — the rows keep what was marked.
      */
     build(): void;
     /**
@@ -128,15 +123,24 @@ export class GPUSceneContext {
      */
     update(ctx: GraphicsContext): void;
     /**
-     * Per-frame animation tick — drains pending registrations,
-     * advances `clip.time` on the GPU, runs apply → resolve →
-     * hierarchy propagate → skin-matrix prep → skinning. Thin
-     * passthrough to {@link GPUAnimationManager#tick}; lives here
-     * so the renderer can call it on every scene it renders without
-     * reaching past `GPUSceneContext` for an internal manager.
+     * Per-frame GPU-side scene update, once per scene per frame, after every view's {@link update}
+     * has flushed what the CPU changed:
+     *
+     * 1. the animation tick — pending registrations drained, `clip.time` advanced, apply → resolve
+     *    → hierarchy propagate → skin-matrix prep → skinning, through {@link GPUAnimationManager#tick};
+     * 2. render bounds — every mesh row's world box and sphere, derived from its geometry under
+     *    the `global` the hierarchy pass just composed, because the CPU does not hold that matrix
+     *    for a subtree the GPU drives;
+     * 3. light poses — every light record's position and direction, from its entity's row, for
+     *    the same reason;
+     * 4. the TLAS — rebuilt from those bounds when anything moved, on either side.
+     *
+     * All four into `cmd_ctx`, in that order, so the tree the frame's ray passes traverse is built
+     * over this frame's bounds rather than last frame's, and what lights the frame is where it is
+     * this frame.
      *
-     * `dt_seconds` is wall-clock seconds since the last call (the
-     * renderer's `time_delta_seconds` argument to `render()`).
+     * `dt_seconds` is wall-clock seconds since the last call (the renderer's `time_delta_seconds`
+     * argument to `render()`).
      *
      * @param {ShadeGPUCommandContext} cmd_ctx
      * @param {number} dt_seconds wall-clock seconds since last call
@@ -153,7 +157,8 @@ export class GPUSceneContext {
 export type GraphicsContext = import("../GraphicsContext.js").GraphicsContext;
 export type GPUGeometryManager = import("../geometry/GPUGeometryManager.js").GPUGeometryManager;
 export type GPUMaterialManager = import("../material/GPUMaterialManager.js").GPUMaterialManager;
-export type Node3D = import("./Node3D.js").Node3D;
+export type ShadeMaterial = import("../material/ShadeMaterial.js").ShadeMaterial;
+export type GPURecordWriter = import("../buffer/table/serde/generate_record_writer.js").GPURecordWriter;
 import { Brick4LightMap } from "../global_illumination/brick4/Brick4LightMap.js";
 import { Scene } from "./Scene.js";
 import { GPUSceneVolumetrics } from "../volumetrics/GPUSceneVolumetrics.js";
@@ -163,5 +168,7 @@ import { GPUInstancesAccelerationStructure } from "./GPUInstancesAccelerationStr
 import { GPUAnimationManager } from "../animation/GPUAnimationManager.js";
 import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
 import { GPUMeshSkinningContext } from "../animation/skinning/GPUMeshSkinningContext.js";
+import { GPUSceneRows } from "./rows/GPUSceneRows.js";
+import { GPUEntityBoundsReadback } from "./rows/GPUEntityBoundsReadback.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 //# sourceMappingURL=GPUSceneContext.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUSceneContext.js"],"names":[],"mappings":"AAmEA;;GAEG;AACH;IAkJI;;;;OAIG;IACH,sBAHW,eAAe,SACf,KAAK,EAiCf;IApLD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAGV;;OAEG;IACH,sBAFU,cAAc,CAEH;IASrB;;;OAGG;IACH,mBAEC;IAOD,uCAEC;IAQD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,8CAEC;IAOD;;;OAGG;IACH,8CAEC;IAmBD;;;;;;;;;;;;;;OAcG;IACH,YAFU,IAAI,MAAM,EAAE,MAAM,CAAC,CAEN;IAgEvB;;OAEG;IACH,6CAEC;IAeD;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,uCAEC;IAED;;;;;;;;;;;;OAYG;IACH,uCAUC;IAED,+BAUC;IAkKD;;;;;;;;;;OAUG;IACH,kBAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;;;OAOG;IACH,gCAEC;IAuRD;;;;;;OAMG;IACH,cA4DC;IAED;;;OAGG;IACH,YAFW,eAAe,QAyBzB;IAED;;;;;;;;;;;;;OAaG;IACH,cAHW,sBAAsB,cACtB,MAAM,QAIhB;IAED,gBAQC;IAIL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;8BAv4BY,OAAO,uBAAuB,EAAE,eAAe;iCAC/C,OAAO,mCAAmC,EAAE,kBAAkB;iCAC9D,OAAO,mCAAmC,EAAE,kBAAkB;qBAC9D,OAAO,aAAa,EAAE,MAAM;+BAhBV,iDAAiD;sBAI1D,YAAY;oCADE,uCAAuC;mCADxC,gCAAgC;oCAD/B,mDAAmD;kDAIrC,wCAAwC;oCAPtD,qCAAqC;4BAC7C,gCAAgC;uCAOrB,iDAAiD;uCATjD,wCAAwC"}
+{"version":3,"file":"GPUSceneContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUSceneContext.js"],"names":[],"mappings":"AA4DA;;;;;;;;;GASG;AACH;IA0II;;;;OAIG;IACH,sBAHW,eAAe,SACf,KAAK,EAiCf;IA5KD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAGV;;OAEG;IACH,sBAFU,cAAc,CAEH;IASrB;;;OAGG;IACH,mBAEC;IAOD,uCAEC;IAQD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,8CAEC;IAOD;;;OAGG;IACH,8CAEC;IA0FD;;OAEG;IACH,6CAEC;IAYD;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,uCAEC;IAED;;;;;;;;;;;OAWG;IACH,uCAUC;IAED,+BAUC;IAED;;;;;;;;;;OAUG;IACH,yBAEC;IAED;;;;;OAKG;IACH,sCAMC;IAOD;;;;;;;OAOG;IACH,8EAEC;IA0BD;;;;OAIG;IACH,cAqEC;IAED;;;OAGG;IACH,YAFW,eAAe,QA0BzB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAHW,sBAAsB,cACtB,MAAM,QAuBhB;IAoCD,gBAYC;IAIL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;8BArjBY,OAAO,uBAAuB,EAAE,eAAe;iCAC/C,OAAO,mCAAmC,EAAE,kBAAkB;iCAC9D,OAAO,mCAAmC,EAAE,kBAAkB;4BAC9D,OAAO,8BAA8B,EAAE,aAAa;8BACpD,OAAO,iDAAiD,EAAE,eAAe;+BAtBvD,iDAAiD;sBAI1D,YAAY;oCADE,uCAAuC;mCADxC,gCAAgC;oCAD/B,mDAAmD;kDAIrC,wCAAwC;oCAPtD,qCAAqC;4BAC7C,gCAAgC;uCAOrB,iDAAiD;6BAM3D,wBAAwB;wCADb,mCAAmC;uCAdpC,wCAAwC"}