@woosh/meep-engine 3.24.0 → 3.25.0

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

@@ -1,594 +1,647 @@
-import { assert } from "../../../core/assert.js";
-import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
-import { GPUAnimationManager } from "../animation/GPUAnimationManager.js";
-import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
-import { Brick4LightMap } from "../global_illumination/brick4/Brick4LightMap.js";
-import { GPULightProbeVolume } from "../global_illumination/lpv/GPULightProbeVolume.js";
-import { GPULightCollection } from "../light/GPULightCollection.js";
-import { GPUSceneVolumetrics } from "../volumetrics/GPUSceneVolumetrics.js";
-import { Scene } from "./Scene.js";
-import { GPUInstancesAccelerationStructure } from "./GPUInstancesAccelerationStructure.js";
-import { GPUMeshSkinningContext } from "../animation/skinning/GPUMeshSkinningContext.js";
-import {
-    shader_refresh_all_mesh_bounds,
-    WORKGROUP_SIZE as REFRESH_ALL_MESH_BOUNDS_WORKGROUP_SIZE
-} from "../object_property/shader_refresh_all_mesh_bounds.js";
-import { GPUEntityBoundsReadback } from "./rows/GPUEntityBoundsReadback.js";
-import { GPUSceneRows } from "./rows/GPUSceneRows.js";
-import { generate_record_writer } from "../buffer/table/serde/generate_record_writer.js";
-import { NODE3D_SCENE_ID, NODE3D_STRUCT } from "./NODE3D_STRUCT.js";
-import { SCENE_DATABASE_SPEC } from "./SCENE_DATABASE_SPEC.js";
-
-/**
- * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
- * @typedef {import("../geometry/GPUGeometryManager.js").GPUGeometryManager} GPUGeometryManager
- * @typedef {import("../material/GPUMaterialManager.js").GPUMaterialManager} GPUMaterialManager
- * @typedef {import("../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
- * @typedef {import("../buffer/table/serde/generate_record_writer.js").GPURecordWriter} GPURecordWriter
- */
-
-
-let id_counter = 0;
-
-/**
- * Row 0 of the `transforms` table: the scene root. Identity, and its own parent — which is what the
- * hierarchy pass takes as "no further ancestor" — so an entity whose attachment names no entity
- * with a row is posed under it in world space, and the composition is exact. Written once, at the
- * first {@link GPUSceneContext.build}, so it goes up with the first rows rather than being left to
- * whatever the buffer held.
- */
-const ROOT_RECORD = {
-    local_translation: new Float32Array([0, 0, 0]),
-    local_rotation: new Float32Array([0, 0, 0, 1]),
-    local_scale: new Float32Array([1, 1, 1]),
-    global: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
-    prev_global: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
-    parent: NODE3D_SCENE_ID,
-};
-
-/**
- * @type {GPURecordWriter}
- */
-const ROOT_RECORD_WRITER = generate_record_writer(NODE3D_STRUCT);
-
-/**
- * What a scene with no rows draws with.
- *
- * @type {ShadeMaterial[]}
- */
-const NO_MATERIALS = Object.freeze([]);
-
-/**
- * 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 {
-
-    /**
-     * @readonly
-     * @type {number}
-     */
-    id = id_counter++;
-
-    /**
-     * @type {GPUGeometryManager}
-     */
-    geometries;
-
-    /**
-     * @type {GPUMaterialManager}
-     */
-    materials;
-
-
-    /**
-     * @type {Brick4LightMap}
-     */
-    volumetric_light_map;
-
-
-    /**
-     *
-     * @type {Scene}
-     */
-    #scene;
-
-    /**
-     *
-     * @return {Scene}
-     */
-    get scene() {
-        return this.#scene;
-    }
-
-    /**
-     * @type {GPUSceneVolumetrics}
-     */
-    #volumetrics;
-
-    get volumetrics() {
-        return this.#volumetrics;
-    }
-
-    /**
-     * @type {GPULightCollection}
-     */
-    #lights;
-
-
-    /**
-     *
-     * @returns {GPULightCollection}
-     */
-    get lights() {
-        return this.#lights;
-    }
-
-    /**
-     * @type {GPULightProbeVolume}
-     */
-    #light_probe_volume;
-
-    /**
-     *
-     * @returns {GPULightProbeVolume}
-     */
-    get light_probe_volume() {
-        return this.#light_probe_volume;
-    }
-
-    /**
-     * @type {GPUInstancesAccelerationStructure}
-     */
-    #tlas
-
-    /**
-     *
-     * @returns {GPUInstancesAccelerationStructure}
-     */
-    get tlas() {
-        return this.#tlas;
-    }
-
-    /**
-     * GPU-resident scene database — mesh metadata in the `meshes` table,
-     * transforms in the `transforms` table, one row per entity in each.
-     * Consumers bind `scene_database.buffer` as `array<u32>` and read
-     * records via `scene_read_mesh` / `scene_read_node` (see
-     * `chunk_scene_database_access`).
-     *
-     * @type {GPUDatabase}
-     */
-    #scene_database;
-
-    /**
-     * Entities as rows of {@link scene_database} — see {@link rows}. Built the first time it is
-     * asked for, which needs the scene to name its dataset by then.
-     *
-     * @type {GPUSceneRows|null}
-     */
-    #rows = null;
-
-    /**
-     * Whether {@link ROOT_RECORD} has been written to row 0 — once, at the first build.
-     *
-     * @type {boolean}
-     */
-    #root_written = false;
-
-    /**
-     * Per-scene skinning state — clone-index cache today, plus
-     * Skin-bindings and the per-frame skinning compute dispatch in
-     * later phases. Lazily constructed because it depends on
-     * {@link geometries}, which {@link SceneManager#create} assigns
-     * externally after this constructor runs. See {@link skinning} for
-     * access.
-     *
-     * @type {GPUMeshSkinningContext|null}
-     */
-    #skinning = null;
-
-    /**
-     * Per-scene animation system — clips, tracks, curves, skins, and
-     * the skin-matrix scratch buffer. Owned here (rather than passed
-     * in) so that consumers fetching `gpu_scene.animation_manager`
-     * always see the same instance, and so per-frame database flush
-     * can be wired into {@link update} alongside the rest of the
-     * scene's bookkeeping.
-     *
-     * @type {GPUAnimationManager}
-     */
-    #animation_manager;
-
-    /**
-     *
-     * @param {GraphicsContext} graphics
-     * @param {Scene} scene
-     */
-    constructor(graphics, scene) {
-        assert.defined(scene, 'scene');
-        assert.isObject(scene, 'scene');
-        assert.equal(scene.isScene, true, 'scene.isScene !== true');
-
-        const device = graphics.device;
-
-        this.#scene = scene;
-        this.#device = device;
-        this.#graphics = graphics;
-
-        this.#tlas = new GPUInstancesAccelerationStructure(graphics);
-
-        // Pass `this` so the light collection (and its child shadow context) can use
-        // this scene's GPUSceneContext when building its own ViewManager — avoids
-        // threading the renderer-level ViewManager / SceneManager through every layer.
-        this.#lights = new GPULightCollection(graphics, this);
-
-        this.#scene_database = new GPUDatabase({
-            device,
-            definition: SCENE_DATABASE_SPEC,
-            label: "GPUSceneContext/Database",
-        });
-
-        this.#light_probe_volume = new GPULightProbeVolume(device, scene.light_probe_volume);
-
-        this.volumetric_light_map = new Brick4LightMap(device);
-
-        this.#volumetrics = new GPUSceneVolumetrics(device, scene.volumetrics);
-
-        this.#animation_manager = new GPUAnimationManager(device, `GPUSceneContext[${this.id}]/Animation`, this);
-    }
-
-    /**
-     * @returns {GPUAnimationManager}
-     */
-    get animation_manager() {
-        return this.#animation_manager;
-    }
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-
-    /**
-     * @type {GraphicsContext}
-     */
-    #graphics;
-
-    /**
-     *
-     * @returns {GPUDatabase}
-     */
-    get scene_database() {
-        return this.#scene_database;
-    }
-
-    /**
-     * The underlying buffer that backs {@link scene_database} — bind this
-     * as `array<u32>` in shaders that read mesh / transform records.
-     *
-     * @returns {GPUBuffer}
-     */
-    get scene_database_buffer() {
-        return this.#scene_database.buffer;
-    }
-
-    /**
-     * 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
-     * (see {@link SceneManager}). The first access happens during
-     * {@link build}, which runs well after that assignment.
-     *
-     * @returns {GPUMeshSkinningContext}
-     */
-    get skinning() {
-        if (this.#skinning === null) {
-            this.#skinning = new GPUMeshSkinningContext({
-                geometries: this.geometries,
-                animation_manager: this.#animation_manager,
-                scene_context: this,
-                device: this.#device,
-            });
-        }
-        return this.#skinning;
-    }
-
-    get gpu_memory_usage(){
-        let r = 0;
-
-        r+= this.#scene_database.gpu_memory_usage;
-
-        r += this.#lights.gpu_memory_usage;
-        r += this.#light_probe_volume.gpu_memory_usage;
-        r += this.volumetric_light_map.gpu_memory_usage;
-
-        return r;
-    }
-
-    /**
-     * Entities as rows of the scene database, at `entity + 1` in both tables.
-     *
-     * 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.
-     *
-     * @returns {GPUSceneRows}
-     */
-    get rows() {
-        return this.#obtain_rows();
-    }
-
-    /**
-     * 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 {GPUEntityBoundsReadback}
-     */
-    get bounds() {
-        if (this.#bounds === null) {
-            this.#bounds = new GPUEntityBoundsReadback(this.#scene_database.readback, this.rows);
-        }
-
-        return this.#bounds;
-    }
-
-    /**
-     * @type {GPUEntityBoundsReadback|null}
-     */
-    #bounds = null;
-
-    /**
-     * 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.
-     *
-     * @returns {ShadeMaterial[]}
-     */
-    get drawn_materials() {
-        return this.#rows === null ? NO_MATERIALS : this.#rows.materials;
-    }
-
-    /**
-     * @returns {GPUSceneRows}
-     */
-    #obtain_rows() {
-        if (this.#rows === null) {
-            const dataset = this.#scene.dataset;
-
-            assert.notNull(dataset, 'the scene names no dataset — set Scene.dataset before asking for its rows');
-            assert.defined(dataset, 'the scene names no dataset — set Scene.dataset before asking for its rows');
-
-            this.#rows = new GPUSceneRows({
-                dataset,
-                transforms: this.#scene_database.get('transforms'),
-                meshes: this.#scene_database.get('meshes'),
-                geometries: this.geometries,
-                materials: this.materials,
-                tlas: this.#tlas,
-                skinning: () => this.skinning,
-            });
-        }
-
-        return this.#rows;
-    }
-
-    /**
-     * 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() {
-        let written = 0;
-
-        if (!this.#root_written) {
-            this.#scene_database.get('transforms').set_record(NODE3D_SCENE_ID, ROOT_RECORD, ROOT_RECORD_WRITER);
-
-            this.#root_written = true;
-            written++;
-        }
-
-        // Entities are rows — marked by the systems that place them, written here. Built on demand
-        // because the scene may name its dataset after this context was made.
-        if (this.#rows === null && this.#scene.dataset !== null && this.#scene.dataset !== undefined) {
-            this.rows;
-        }
-
-        if (this.#rows !== null) {
-            // A light is an entity's row, held here on the light collection's behalf — before the
-            // flush, so a light that arrived this frame is written this frame.
-            this.#lights.sync_rows(this.#rows);
-
-            written += this.#rows.flush();
-        } else {
-            assert.equal(this.#scene.lights.elements.length, 0, 'the scene has lights and names no dataset; a light is an entity of one');
-        }
-
-        if (written === 0) {
-            return;
-        }
-
-        // Flush the scene database — only the rows that changed carry an upload record.
-        const cmd = ShadeGPUCommandContext.create(this.#graphics, 'GPUSceneContext/database-build');
-
-        // Also flush the global geometry manager. The first time a scene
-        // sees a new mesh, the rows' flush calls `geometries.add(...)`,
-        // which registers the source MeshletGeometry and flips
-        // `geometries.__needs_update = true`. The next per-frame
-        // `graphics.update()` would normally rebuild
-        // `geometries.buffer_metadata` to reflect those new entries — but
-        // `graphics.update()` runs at the *head* of `Renderer.#begin_frame`,
-        // *before* this scene.build, so the buffer_metadata stays whatever
-        // it was at the start of the frame (often the zero-record placeholder
-        // from the renderer's startup build, when the scene's geometries
-        // hadn't been registered yet).
-        //
-        // Any pass reading `geometries[mesh.geometry]` later in the frame
-        // (rasterization meshlet expansion, `shader_refresh_all_mesh_bounds`,
-        // etc.) sees zeros — `meshlets_count = 0` produces no triangles and
-        // `bounding_box = (0,0,0)-(0,0,0)` collapses world bounds to a
-        // single point in `shader_refresh_all_mesh_bounds`, which then writes
-        // those collapsed bounds back into `meshes_table`. Subsequent frames
-        // get a correct `buffer_metadata` from the next `graphics.update()`,
-        // but the `meshes_table` bounds stay collapsed until refresh_all
-        // overwrites them again — and frustum cull on the collapsed bounds
-        // can drop meshes whose collapsed point sits outside the frustum.
-        //
-        // Symptom: stress test rendered ground (whose collapsed point at the
-        // origin survives the cull) but dropped most trees (whose collapsed
-        // points scattered across the grid trigger cull edge cases).
-        //
-        // Calling `geometries.update(cmd)` here ensures the new buffer is in
-        // place before any pass in the same frame reads it. Idempotent / no-op
-        // when nothing's queued, so the per-frame `graphics.update` head call
-        // and this build-time call together leave the buffer in the right
-        // state under both lifetimes.
-        this.geometries.update(cmd);
-
-        this.#scene_database.update(cmd);
-        cmd.finish();
-    }
-
-    /**
-     *
-     * @param {GraphicsContext} ctx
-     */
-    update(ctx) {
-        assert.defined(ctx, 'ctx');
-
-        // TODO add a fast update check, so that calling this multiple times per frame can be fast.
-
-        // The apply point of the scene database's readback: whatever the device has answered since
-        // — an entity's drawn bounds, asked for through {@link bounds} — is delivered before
-        // anything this frame reads it, and never mid-update.
-        this.#scene_database.readback.apply();
-
-        this.#light_probe_volume.update();
-        this.#lights.update(ctx);
-        this.#volumetrics.update(ctx, 0);
-
-        // Per-frame animation database flush — picks up any new clips,
-        // tracks, skins, or per-frame `set_time` writes queued since
-        // last frame. Idempotent / cheap when nothing's queued.
-        const animation_cmd = ShadeGPUCommandContext.create(this.#graphics, 'GPUSceneContext/animation-flush');
-        this.#animation_manager.update(animation_cmd);
-        animation_cmd.finish();
-
-        // TODO update SDF
-
-        this.build();
-    }
-
-    /**
-     * 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()`).
-     *
-     * @param {ShadeGPUCommandContext} cmd_ctx
-     * @param {number} dt_seconds wall-clock seconds since last call
-     */
-    tick(cmd_ctx, dt_seconds) {
-        const animated = this.#animation_manager.tick(cmd_ctx, dt_seconds);
-
-        this.#refresh_mesh_bounds(cmd_ctx);
-
-        this.#lights.refresh_poses(cmd_ctx, this.scene_database_buffer);
-
-        if (animated) {
-            // Rows moved on the GPU, where no version was bumped: a clip resolved into a TRS, a
-            // skinning pass moved a clone's vertices. The bounds pass just re-derived their boxes,
-            // and the tree is built over boxes.
-            this.#tlas.invalidate();
-        }
-
-        this.#tlas.update(this.scene_database_buffer, cmd_ctx);
-
-        // What was asked of the scene database this frame is copied out at the tail of the
-        // database's own update when rows were written this frame, and here — after the bounds
-        // pass — when none were; either way what lands, at the head of a later frame's update, is
-        // the box the GPU held when the copy ran.
-        this.#scene_database.readback.encode(cmd_ctx);
-    }
-
-    /**
-     * Recompute every mesh row's world bounds from its geometry under its composed `global`.
-     * Skipped when there is no mesh row; otherwise one thread per slot of the `meshes` table's
-     * pages, occupancy-masked.
-     *
-     * @param {ShadeGPUCommandContext} cmd_ctx
-     */
-    #refresh_mesh_bounds(cmd_ctx) {
-        const meshes_table = this.#scene_database.get('meshes');
-
-        const group_count = meshes_table.dispatch_group_count(REFRESH_ALL_MESH_BOUNDS_WORKGROUP_SIZE);
-
-        if (group_count === 0) {
-            return;
-        }
-
-        const geometries = this.geometries.buffer_metadata;
-
-        if (geometries === null) {
-            // a mesh row names a geometry, and a geometry is registered before its row is written
-            // — so this is a scene whose first frame has not flushed the geometry manager yet
-            return;
-        }
-
-        shader_refresh_all_mesh_bounds.dispatch({
-            encoder: cmd_ctx,
-            group_count_x: group_count,
-            bindings: {
-                scene_database: this.scene_database_buffer,
-                geometries,
-            },
-        });
-    }
-
-    destroy() {
-        if (this.#rows !== null) {
-            this.#rows.destroy();
-        }
-
-        this.#scene_database.destroy();
-        this.#lights.destroy();
-        this.#light_probe_volume.destroy();
-        this.#animation_manager.destroy();
-        if (this.#skinning !== null) {
-            this.#skinning.destroy();
-        }
-    }
-
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-GPUSceneContext.prototype.isGPUSceneContext = true;
+import { GPUVirtualGeometryPool } from "../geometry/virtual/runtime/GPUVirtualGeometryPool.js";
+import { GPUVirtualGeometryRuntime } from "../geometry/virtual/runtime/GPUVirtualGeometryRuntime.js";
+import { assert } from "../../../core/assert.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { GPUAnimationManager } from "../animation/GPUAnimationManager.js";
+import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
+import { Brick4LightMap } from "../global_illumination/brick4/Brick4LightMap.js";
+import { GPULightProbeVolume } from "../global_illumination/lpv/GPULightProbeVolume.js";
+import { GPULightCollection } from "../light/GPULightCollection.js";
+import { GPUSceneVolumetrics } from "../volumetrics/GPUSceneVolumetrics.js";
+import { Scene } from "./Scene.js";
+import { GPUInstancesAccelerationStructure } from "./GPUInstancesAccelerationStructure.js";
+import { GPUMeshSkinningContext } from "../animation/skinning/GPUMeshSkinningContext.js";
+import {
+    shader_refresh_all_mesh_bounds,
+    WORKGROUP_SIZE as REFRESH_ALL_MESH_BOUNDS_WORKGROUP_SIZE
+} from "../object_property/shader_refresh_all_mesh_bounds.js";
+import { GPUEntityBoundsReadback } from "./rows/GPUEntityBoundsReadback.js";
+import { GPUSceneRows } from "./rows/GPUSceneRows.js";
+import { generate_record_writer } from "../buffer/table/serde/generate_record_writer.js";
+import { NODE3D_SCENE_ID, NODE3D_STRUCT } from "./NODE3D_STRUCT.js";
+import { SCENE_DATABASE_SPEC } from "./SCENE_DATABASE_SPEC.js";
+
+/**
+ * @typedef {import("../GraphicsContext.js").GraphicsContext} GraphicsContext
+ * @typedef {import("../geometry/GPUGeometryManager.js").GPUGeometryManager} GPUGeometryManager
+ * @typedef {import("../material/GPUMaterialManager.js").GPUMaterialManager} GPUMaterialManager
+ * @typedef {import("../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ * @typedef {import("../buffer/table/serde/generate_record_writer.js").GPURecordWriter} GPURecordWriter
+ */
+
+
+let id_counter = 0;
+
+/**
+ * Row 0 of the `transforms` table: the scene root. Identity, and its own parent — which is what the
+ * hierarchy pass takes as "no further ancestor" — so an entity whose attachment names no entity
+ * with a row is posed under it in world space, and the composition is exact. Written once, at the
+ * first {@link GPUSceneContext.build}, so it goes up with the first rows rather than being left to
+ * whatever the buffer held.
+ */
+const ROOT_RECORD = {
+    local_translation: new Float32Array([0, 0, 0]),
+    local_rotation: new Float32Array([0, 0, 0, 1]),
+    local_scale: new Float32Array([1, 1, 1]),
+    global: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+    prev_global: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
+    parent: NODE3D_SCENE_ID,
+};
+
+/**
+ * @type {GPURecordWriter}
+ */
+const ROOT_RECORD_WRITER = generate_record_writer(NODE3D_STRUCT);
+
+/**
+ * What a scene with no rows draws with.
+ *
+ * @type {ShadeMaterial[]}
+ */
+const NO_MATERIALS = Object.freeze([]);
+
+/**
+ * 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 {
+
+    /**
+     * @readonly
+     * @type {number}
+     */
+    id = id_counter++;
+
+    /**
+     * @type {GPUGeometryManager}
+     */
+    geometries;
+
+    /**
+     * @type {GPUMaterialManager}
+     */
+    materials;
+
+
+    /**
+     * @type {Brick4LightMap}
+     */
+    volumetric_light_map;
+
+
+    /**
+     *
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     *
+     * @return {Scene}
+     */
+    get scene() {
+        return this.#scene;
+    }
+
+    /**
+     * @type {GPUSceneVolumetrics}
+     */
+    #volumetrics;
+
+    get volumetrics() {
+        return this.#volumetrics;
+    }
+
+    /**
+     * @type {GPULightCollection}
+     */
+    #lights;
+
+
+    /**
+     *
+     * @returns {GPULightCollection}
+     */
+    get lights() {
+        return this.#lights;
+    }
+
+    /**
+     * @type {GPULightProbeVolume}
+     */
+    #light_probe_volume;
+
+    /**
+     *
+     * @returns {GPULightProbeVolume}
+     */
+    get light_probe_volume() {
+        return this.#light_probe_volume;
+    }
+
+    /**
+     * @type {GPUInstancesAccelerationStructure}
+     */
+    #tlas
+
+    /**
+     *
+     * @returns {GPUInstancesAccelerationStructure}
+     */
+    get tlas() {
+        return this.#tlas;
+    }
+
+    /**
+     * GPU-resident scene database — mesh metadata in the `meshes` table,
+     * transforms in the `transforms` table, one row per entity in each.
+     * Consumers bind `scene_database.buffer` as `array<u32>` and read
+     * records via `scene_read_mesh` / `scene_read_node` (see
+     * `chunk_scene_database_access`).
+     *
+     * @type {GPUDatabase}
+     */
+    #scene_database;
+
+    /**
+     * Entities as rows of {@link scene_database} — see {@link rows}. Built the first time it is
+     * asked for, which needs the scene to name its dataset by then.
+     *
+     * @type {GPUSceneRows|null}
+     */
+    #rows = null;
+
+    /**
+     * Whether {@link ROOT_RECORD} has been written to row 0 — once, at the first build.
+     *
+     * @type {boolean}
+     */
+    #root_written = false;
+
+    /**
+     * Per-scene skinning state — clone-index cache today, plus
+     * Skin-bindings and the per-frame skinning compute dispatch in
+     * later phases. Lazily constructed because it depends on
+     * {@link geometries}, which {@link SceneManager#create} assigns
+     * externally after this constructor runs. See {@link skinning} for
+     * access.
+     *
+     * @type {GPUMeshSkinningContext|null}
+     */
+    #skinning = null;
+
+    /**
+     * Per-scene animation system — clips, tracks, curves, skins, and
+     * the skin-matrix scratch buffer. Owned here (rather than passed
+     * in) so that consumers fetching `gpu_scene.animation_manager`
+     * always see the same instance, and so per-frame database flush
+     * can be wired into {@link update} alongside the rest of the
+     * scene's bookkeeping.
+     *
+     * @type {GPUAnimationManager}
+     */
+    #animation_manager;
+
+    /**
+     *
+     * @param {GraphicsContext} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        assert.defined(scene, 'scene');
+        assert.isObject(scene, 'scene');
+        assert.equal(scene.isScene, true, 'scene.isScene !== true');
+
+        const device = graphics.device;
+
+        this.#scene = scene;
+        this.#device = device;
+        this.#graphics = graphics;
+
+        this.#tlas = new GPUInstancesAccelerationStructure(graphics);
+
+        // Pass `this` so the light collection (and its child shadow context) can use
+        // this scene's GPUSceneContext when building its own ViewManager — avoids
+        // threading the renderer-level ViewManager / SceneManager through every layer.
+        this.#lights = new GPULightCollection(graphics, this);
+
+        this.#scene_database = new GPUDatabase({
+            device,
+            definition: SCENE_DATABASE_SPEC,
+            label: "GPUSceneContext/Database",
+        });
+
+        this.#light_probe_volume = new GPULightProbeVolume(device, scene.light_probe_volume);
+
+        this.volumetric_light_map = new Brick4LightMap(device);
+
+        this.#volumetrics = new GPUSceneVolumetrics(device, scene.volumetrics);
+
+        this.#animation_manager = new GPUAnimationManager(device, `GPUSceneContext[${this.id}]/Animation`, this);
+    }
+
+    /**
+     * The virtual-geometry runtime, once something has asked for one.
+     *
+     * `undefined` until {@link enable_virtual_geometry}, and every rasterization path treats that
+     * as "there is no virtual geometry in this scene" and skips the cut entirely. Opt-in rather
+     * than always-on because the pool owns real buffers — a page arena, a page table, a per-asset
+     * lookup — and a scene of ordinary meshes should not pay for them.
+     *
+     * @type {GPUVirtualGeometryRuntime|undefined}
+     */
+    #virtual_geometry;
+
+    /**
+     * @returns {GPUVirtualGeometryRuntime|undefined}
+     */
+    get virtual_geometry() {
+        return this.#virtual_geometry;
+    }
+
+    /**
+     * Give this scene a virtual-geometry runtime, sharing the meshlet pool with everything else it
+     * draws.
+     *
+     * Sharing the pool is the whole seam on this side: a cut emits `MESHLET_DEFINITION_STRUCT`
+     * records naming rows of the same metadata buffer a static mesh's meshlets live in, so nothing
+     * downstream of the expansion has to know which kind of geometry it is looking at.
+     *
+     * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and
+     *     {@link GPUVirtualGeometryRuntime}
+     * @returns {GPUVirtualGeometryRuntime}
+     */
+    enable_virtual_geometry(options = {}) {
+        if (this.#virtual_geometry !== undefined) {
+            return this.#virtual_geometry;
+        }
+
+        const pool = new GPUVirtualGeometryPool({
+            device: this.#device,
+            meshlets: this.geometries.meshlets,
+            ...options,
+        });
+
+        this.#virtual_geometry = new GPUVirtualGeometryRuntime({
+            pool,
+            device: this.#device,
+            ...options,
+        });
+
+        return this.#virtual_geometry;
+    }
+
+    /**
+     * @returns {GPUAnimationManager}
+     */
+    get animation_manager() {
+        return this.#animation_manager;
+    }
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * @type {GraphicsContext}
+     */
+    #graphics;
+
+    /**
+     *
+     * @returns {GPUDatabase}
+     */
+    get scene_database() {
+        return this.#scene_database;
+    }
+
+    /**
+     * The underlying buffer that backs {@link scene_database} — bind this
+     * as `array<u32>` in shaders that read mesh / transform records.
+     *
+     * @returns {GPUBuffer}
+     */
+    get scene_database_buffer() {
+        return this.#scene_database.buffer;
+    }
+
+    /**
+     * 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
+     * (see {@link SceneManager}). The first access happens during
+     * {@link build}, which runs well after that assignment.
+     *
+     * @returns {GPUMeshSkinningContext}
+     */
+    get skinning() {
+        if (this.#skinning === null) {
+            this.#skinning = new GPUMeshSkinningContext({
+                geometries: this.geometries,
+                animation_manager: this.#animation_manager,
+                scene_context: this,
+                device: this.#device,
+            });
+        }
+        return this.#skinning;
+    }
+
+    get gpu_memory_usage(){
+        let r = 0;
+
+        r+= this.#scene_database.gpu_memory_usage;
+
+        r += this.#lights.gpu_memory_usage;
+        r += this.#light_probe_volume.gpu_memory_usage;
+        r += this.volumetric_light_map.gpu_memory_usage;
+
+        return r;
+    }
+
+    /**
+     * Entities as rows of the scene database, at `entity + 1` in both tables.
+     *
+     * 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.
+     *
+     * @returns {GPUSceneRows}
+     */
+    get rows() {
+        return this.#obtain_rows();
+    }
+
+    /**
+     * 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 {GPUEntityBoundsReadback}
+     */
+    get bounds() {
+        if (this.#bounds === null) {
+            this.#bounds = new GPUEntityBoundsReadback(this.#scene_database.readback, this.rows);
+        }
+
+        return this.#bounds;
+    }
+
+    /**
+     * @type {GPUEntityBoundsReadback|null}
+     */
+    #bounds = null;
+
+    /**
+     * 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.
+     *
+     * @returns {ShadeMaterial[]}
+     */
+    get drawn_materials() {
+        return this.#rows === null ? NO_MATERIALS : this.#rows.materials;
+    }
+
+    /**
+     * @returns {GPUSceneRows}
+     */
+    #obtain_rows() {
+        if (this.#rows === null) {
+            const dataset = this.#scene.dataset;
+
+            assert.notNull(dataset, 'the scene names no dataset — set Scene.dataset before asking for its rows');
+            assert.defined(dataset, 'the scene names no dataset — set Scene.dataset before asking for its rows');
+
+            this.#rows = new GPUSceneRows({
+                dataset,
+                transforms: this.#scene_database.get('transforms'),
+                meshes: this.#scene_database.get('meshes'),
+                geometries: this.geometries,
+                materials: this.materials,
+                tlas: this.#tlas,
+                skinning: () => this.skinning,
+            });
+        }
+
+        return this.#rows;
+    }
+
+    /**
+     * 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() {
+        let written = 0;
+
+        if (!this.#root_written) {
+            this.#scene_database.get('transforms').set_record(NODE3D_SCENE_ID, ROOT_RECORD, ROOT_RECORD_WRITER);
+
+            this.#root_written = true;
+            written++;
+        }
+
+        // Entities are rows — marked by the systems that place them, written here. Built on demand
+        // because the scene may name its dataset after this context was made.
+        if (this.#rows === null && this.#scene.dataset !== null && this.#scene.dataset !== undefined) {
+            this.rows;
+        }
+
+        if (this.#rows !== null) {
+            // A light is an entity's row, held here on the light collection's behalf — before the
+            // flush, so a light that arrived this frame is written this frame.
+            this.#lights.sync_rows(this.#rows);
+
+            written += this.#rows.flush();
+        } else {
+            assert.equal(this.#scene.lights.elements.length, 0, 'the scene has lights and names no dataset; a light is an entity of one');
+        }
+
+        if (written === 0) {
+            return;
+        }
+
+        // Flush the scene database — only the rows that changed carry an upload record.
+        const cmd = ShadeGPUCommandContext.create(this.#graphics, 'GPUSceneContext/database-build');
+
+        // Also flush the global geometry manager. The first time a scene
+        // sees a new mesh, the rows' flush calls `geometries.add(...)`,
+        // which registers the source MeshletGeometry and flips
+        // `geometries.__needs_update = true`. The next per-frame
+        // `graphics.update()` would normally rebuild
+        // `geometries.buffer_metadata` to reflect those new entries — but
+        // `graphics.update()` runs at the *head* of `Renderer.#begin_frame`,
+        // *before* this scene.build, so the buffer_metadata stays whatever
+        // it was at the start of the frame (often the zero-record placeholder
+        // from the renderer's startup build, when the scene's geometries
+        // hadn't been registered yet).
+        //
+        // Any pass reading `geometries[mesh.geometry]` later in the frame
+        // (rasterization meshlet expansion, `shader_refresh_all_mesh_bounds`,
+        // etc.) sees zeros — `meshlets_count = 0` produces no triangles and
+        // `bounding_box = (0,0,0)-(0,0,0)` collapses world bounds to a
+        // single point in `shader_refresh_all_mesh_bounds`, which then writes
+        // those collapsed bounds back into `meshes_table`. Subsequent frames
+        // get a correct `buffer_metadata` from the next `graphics.update()`,
+        // but the `meshes_table` bounds stay collapsed until refresh_all
+        // overwrites them again — and frustum cull on the collapsed bounds
+        // can drop meshes whose collapsed point sits outside the frustum.
+        //
+        // Symptom: stress test rendered ground (whose collapsed point at the
+        // origin survives the cull) but dropped most trees (whose collapsed
+        // points scattered across the grid trigger cull edge cases).
+        //
+        // Calling `geometries.update(cmd)` here ensures the new buffer is in
+        // place before any pass in the same frame reads it. Idempotent / no-op
+        // when nothing's queued, so the per-frame `graphics.update` head call
+        // and this build-time call together leave the buffer in the right
+        // state under both lifetimes.
+        this.geometries.update(cmd);
+
+        this.#scene_database.update(cmd);
+        cmd.finish();
+    }
+
+    /**
+     *
+     * @param {GraphicsContext} ctx
+     */
+    update(ctx) {
+        assert.defined(ctx, 'ctx');
+
+        // TODO add a fast update check, so that calling this multiple times per frame can be fast.
+
+        // The apply point of the scene database's readback: whatever the device has answered since
+        // — an entity's drawn bounds, asked for through {@link bounds} — is delivered before
+        // anything this frame reads it, and never mid-update.
+        this.#scene_database.readback.apply();
+
+        this.#light_probe_volume.update();
+        this.#lights.update(ctx);
+        this.#volumetrics.update(ctx, 0);
+
+        // Per-frame animation database flush — picks up any new clips,
+        // tracks, skins, or per-frame `set_time` writes queued since
+        // last frame. Idempotent / cheap when nothing's queued.
+        const animation_cmd = ShadeGPUCommandContext.create(this.#graphics, 'GPUSceneContext/animation-flush');
+        this.#animation_manager.update(animation_cmd);
+        animation_cmd.finish();
+
+        // TODO update SDF
+
+        this.build();
+    }
+
+    /**
+     * 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()`).
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     * @param {number} dt_seconds wall-clock seconds since last call
+     */
+    tick(cmd_ctx, dt_seconds) {
+        const animated = this.#animation_manager.tick(cmd_ctx, dt_seconds);
+
+        this.#refresh_mesh_bounds(cmd_ctx);
+
+        this.#lights.refresh_poses(cmd_ctx, this.scene_database_buffer);
+
+        if (animated) {
+            // Rows moved on the GPU, where no version was bumped: a clip resolved into a TRS, a
+            // skinning pass moved a clone's vertices. The bounds pass just re-derived their boxes,
+            // and the tree is built over boxes.
+            this.#tlas.invalidate();
+        }
+
+        this.#tlas.update(this.scene_database_buffer, cmd_ctx);
+
+        // What was asked of the scene database this frame is copied out at the tail of the
+        // database's own update when rows were written this frame, and here — after the bounds
+        // pass — when none were; either way what lands, at the head of a later frame's update, is
+        // the box the GPU held when the copy ran.
+        this.#scene_database.readback.encode(cmd_ctx);
+    }
+
+    /**
+     * Recompute every mesh row's world bounds from its geometry under its composed `global`.
+     * Skipped when there is no mesh row; otherwise one thread per slot of the `meshes` table's
+     * pages, occupancy-masked.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     */
+    #refresh_mesh_bounds(cmd_ctx) {
+        const meshes_table = this.#scene_database.get('meshes');
+
+        const group_count = meshes_table.dispatch_group_count(REFRESH_ALL_MESH_BOUNDS_WORKGROUP_SIZE);
+
+        if (group_count === 0) {
+            return;
+        }
+
+        const geometries = this.geometries.buffer_metadata;
+
+        if (geometries === null) {
+            // a mesh row names a geometry, and a geometry is registered before its row is written
+            // — so this is a scene whose first frame has not flushed the geometry manager yet
+            return;
+        }
+
+        shader_refresh_all_mesh_bounds.dispatch({
+            encoder: cmd_ctx,
+            group_count_x: group_count,
+            bindings: {
+                scene_database: this.scene_database_buffer,
+                geometries,
+            },
+        });
+    }
+
+    destroy() {
+        if (this.#rows !== null) {
+            this.#rows.destroy();
+        }
+
+        this.#scene_database.destroy();
+        this.#lights.destroy();
+        this.#light_probe_volume.destroy();
+        this.#animation_manager.destroy();
+        if (this.#skinning !== null) {
+            this.#skinning.destroy();
+        }
+    }
+
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+GPUSceneContext.prototype.isGPUSceneContext = true;