@woosh/meep-engine 3.12.0 → 3.13.0

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

@@ -1,383 +1,379 @@
-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_BUILD_SETTINGS_STRUCT } from "../gpu_primitive/bvh/BVH_BUILD_SETTINGS_STRUCT.js";
-import { bvh_buffer_size } from "../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.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";
-
-/**
- * `root = BVH_NULL_NODE` — an empty tree, in the four bytes every consumer already reads that way.
- * @type {Uint32Array}
- */
-const EMPTY_TREE = Uint32Array.from([0xffffffff]);
-
-/**
- * The scene-bounds cell before anything has been merged into it: +inf for the three minima, -inf
- * for the three maxima, so the first contribution wins on every axis.
- *
- * Written host-side as exact u32 bit patterns. A pool-cleared buffer holds zeroes, and zero is a
- * perfectly good coordinate — a scene entirely in the positive octant would end up with bounds
- * anchored at the origin and every Morton code crushed into a corner of the grid.
- *
- * @type {Uint32Array}
- */
-const SCENE_BOUNDS_SEED = Uint32Array.from([
-    0x7F800000, 0x7F800000, 0x7F800000,
-    0xFF800000, 0xFF800000, 0xFF800000,
-]);
-
-/**
- * Top-Level Acceleration Structure (TLAS)
- */
-export class GPUInstancesAccelerationStructure {
-
-    /**
-     * @type {GraphicsContext}
-     */
-    #graphics
-
-    /**
-     * @type {GPUDevice}
-     */
-    #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.#membership_version++;
-        this.#version++;
-    }
-
-    /**
-     * @type {GPUBuffer}
-     */
-    #buffer
-
-    /**
-     *
-     * @return {GPUBuffer}
-     */
-    get buffer() {
-        return this.#buffer;
-    }
-
-    #gpu_version = 0;
-    #version = 0;
-
-    /**
-     * Bumped when the set of live rows changes — an add or a remove — and not when one merely moves.
-     * The rows list is uploaded only when this moves, so a scene in continuous motion re-uploads
-     * nothing.
-     *
-     * @type {number}
-     */
-    #membership_version = 0;
-
-    /**
-     * Membership version the {@link #rows_buffer} currently holds.
-     * @type {number}
-     */
-    #rows_gpu_version = -1;
-
-    /**
-     * Compact mirror of the live `meshes` rows, in insertion order. Rebuilt from
-     * {@link #node_mapping} when membership churns.
-     *
-     * @type {Uint32Array}
-     */
-    #rows = new Uint32Array(0);
-
-    /**
-     * @type {GPUBuffer|undefined}
-     */
-    #rows_buffer
-
-    /**
-     *
-     * @param {GraphicsContext} graphics
-     */
-    constructor(graphics) {
-        assert.defined(graphics, 'graphics');
-        assert.equal(graphics.isGraphicsContext, true, 'graphics.isGraphicsContext !== true');
-
-        const device = graphics.device;
-
-        this.#graphics = graphics;
-        this.#device = device;
-
-        this.#buffer = device.createBuffer({
-            label: 'TLAS',
-            size: 1024,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
-        });
-    }
-
-    /**
-     *
-     * @type {Map<number, number>}
-     */
-    #node_mapping = new Map();
-
-    /**
-     *
-     * @param {number} index
-     * @param {Mesh} instance
-     */
-    instance_add(index, instance) {
-        assert.isNonNegativeInteger(index, 'index');
-        assert.defined(instance, 'instance');
-
-        const bvh = this.#bvh;
-
-        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.#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.
-     *
-     * @param {number} index
-     */
-    instance_remove(index) {
-        assert.isNonNegativeInteger(index, 'index');
-
-        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.#membership_version++;
-        this.#version++;
-    }
-
-    /**
-     *
-     * @param {number} index
-     * @param {Mesh} instance
-     */
-    instance_update(index, instance) {
-        assert.isNonNegativeInteger(index, 'index');
-        assert.defined(instance, 'instance');
-
-        const node = this.#node_mapping.get(index);
-
-        this.#bvh.node_move_aabb(node, instance.bounding_box);
-
-        this.#version++;
-    }
-
-    /**
-     * Bring {@link #rows_buffer} in line with the live row set, if and only if membership changed.
-     *
-     * @returns {number} number of live rows
-     */
-    #refresh_rows() {
-        const count = this.#node_mapping.size;
-
-        if (this.#rows_gpu_version === this.#membership_version && this.#rows.length >= count) {
-            return count;
-        }
-
-        if (this.#rows.length < count) {
-            this.#rows = new Uint32Array(count);
-        }
-
-        let i = 0;
-        for (const row of this.#node_mapping.keys()) {
-            this.#rows[i] = row;
-            i++;
-        }
-
-        const byte_size = Math.max(4, count * Uint32Array.BYTES_PER_ELEMENT);
-
-        if (this.#rows_buffer === undefined) {
-            this.#rows_buffer = this.#device.createBuffer({
-                label: 'TLAS/rows',
-                size: Math.max(1024, byte_size),
-                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
-            });
-        } else {
-            this.#rows_buffer = ensure_buffer_capacity(this.#device, this.#rows_buffer, byte_size);
-        }
-
-        // Queue writes land in submission order ahead of command buffers submitted after them, so
-        // the build encoded below sees these rows. Offset and size are in elements of the source,
-        // per `GPUQueue.writeBuffer` — `#rows` can be longer than the live set.
-        this.#device.queue.writeBuffer(this.#rows_buffer, 0, this.#rows, 0, count);
-
-        this.#rows_gpu_version = this.#membership_version;
-
-        return count;
-    }
-
-    /**
-     * Build the tree, from the world AABBs the scene database holds.
-     *
-     * @param {GPUBuffer} scene_database_buffer
-     */
-    #build(scene_database_buffer) {
-        assert.defined(scene_database_buffer, 'scene_database_buffer');
-
-        const device = this.#device;
-
-        const element_count = this.#node_mapping.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
-        // be reassigned before the graph imports it.
-        this.#buffer = ensure_buffer_capacity(
-            device,
-            this.#buffer,
-            bvh_buffer_size(Math.max(1, element_count)),
-            1024,
-            1024,
-            1.2
-        );
-
-        if (element_count === 0) {
-            device.queue.writeBuffer(this.#buffer, 0, EMPTY_TREE);
-
-            return;
-        }
-
-        this.#refresh_rows();
-
-        const graph = new FrameGraph('TLAS build');
-
-        const rows = graph.import_resource(
-            "tlas/rows",
-            BufferResourceDescriptor.fromBuffer(this.#rows_buffer),
-            this.#rows_buffer
-        );
-
-        const scene_database = graph.import_resource(
-            "scene database",
-            BufferResourceDescriptor.fromBuffer(scene_database_buffer),
-            scene_database_buffer
-        );
-
-        const nodes = graph.import_resource(
-            "tlas/nodes",
-            BufferResourceDescriptor.fromBuffer(this.#buffer),
-            this.#buffer
-        );
-
-        const extract_data = {};
-        const extract_pass = graph.add("tlas/extract instance leaves", extract_data, extract_execute);
-
-        extract_data.element_count = element_count;
-        extract_data.rows = extract_pass.read(rows);
-        extract_data.scene_database = extract_pass.read(scene_database);
-
-        extract_data.leaf_bounds = extract_pass.create("tlas/leaf bounds", BufferResourceDescriptor.from(
-            element_count * 6 * Float32Array.BYTES_PER_ELEMENT,
-            GPUBufferUsage.STORAGE
-        ));
-
-        extract_data.leaf_payload = extract_pass.create("tlas/leaf payload", BufferResourceDescriptor.from(
-            element_count * Uint32Array.BYTES_PER_ELEMENT,
-            GPUBufferUsage.STORAGE
-        ));
-
-        extract_data.scene_bounds = extract_pass.create("tlas/scene bounds", BufferResourceDescriptor.from(
-            SCENE_BOUNDS_SEED.byteLength,
-            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
-        ));
-
-        graph_bvh_build_lbvh({
-            graph,
-            leaf_bounds: extract_data.leaf_bounds,
-            leaf_payload: extract_data.leaf_payload,
-            scene_bounds: extract_data.scene_bounds,
-            element_count,
-            nodes,
-        });
-
-        const cmd = ShadeGPUCommandContext.create(this.#graphics, 'TLAS/build');
-
-        cmd.encodeGraph(graph);
-        cmd.finish();
-    }
-
-    /**
-     * @param {GPUBuffer} scene_database_buffer the table the world AABBs are read from
-     */
-    push_to_gpu(scene_database_buffer) {
-        this.#build(scene_database_buffer);
-
-        this.#gpu_version = this.#version;
-    }
-
-    /**
-     * @param {GPUBuffer} scene_database_buffer
-     */
-    update(scene_database_buffer) {
-        if (this.#gpu_version === this.#version) {
-            return;
-        }
-
-        this.push_to_gpu(scene_database_buffer);
-    }
-}
-
-/**
- * @param pass_data
- * @param {FramePassResources} resources
- * @param {GraphicsExecutionContext} context
- */
-function extract_execute(pass_data, resources, context) {
-    const encoder = context.encoder;
-
-    const scene_bounds = resources.get(pass_data.scene_bounds);
-
-    // Seeded rather than cleared: the merge is a min/max, and zero is not an identity for either.
-    encoder.writeBuffer(scene_bounds, 0, SCENE_BOUNDS_SEED.buffer, 0, SCENE_BOUNDS_SEED.byteLength);
-
-    shader_bvh_extract_instance_leaves.dispatchThreads({
-        encoder,
-        thread_count_x: pass_data.element_count,
-        bindings: {
-            settings: encoder.allocateTransientValueBuffer(
-                BVH_BUILD_SETTINGS_STRUCT,
-                { element_count: pass_data.element_count }
-            ),
-            rows: resources.get(pass_data.rows),
-            scene_database: resources.get(pass_data.scene_database),
-            leaf_bounds: resources.get(pass_data.leaf_bounds),
-            leaf_payload: resources.get(pass_data.leaf_payload),
-            scene_bounds,
-        }
-    });
-}
+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 { 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";
+
+/**
+ * `root = BVH_NULL_NODE` — an empty tree, in the four bytes every consumer already reads that way.
+ * @type {Uint32Array}
+ */
+const EMPTY_TREE = Uint32Array.from([0xffffffff]);
+
+/**
+ * The scene-bounds cell before anything has been merged into it: +inf for the three minima, -inf
+ * for the three maxima, so the first contribution wins on every axis.
+ *
+ * Written host-side as exact u32 bit patterns. A pool-cleared buffer holds zeroes, and zero is a
+ * perfectly good coordinate — a scene entirely in the positive octant would end up with bounds
+ * anchored at the origin and every Morton code crushed into a corner of the grid.
+ *
+ * @type {Uint32Array}
+ */
+const SCENE_BOUNDS_SEED = Uint32Array.from([
+    0x7F800000, 0x7F800000, 0x7F800000,
+    0xFF800000, 0xFF800000, 0xFF800000,
+]);
+
+/**
+ * Top-Level Acceleration Structure (TLAS)
+ */
+export class GPUInstancesAccelerationStructure {
+
+    /**
+     * @type {GraphicsContext}
+     */
+    #graphics
+
+    /**
+     * @type {GPUDevice}
+     */
+    #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.#membership_version++;
+        this.#version++;
+    }
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #buffer
+
+    /**
+     *
+     * @return {GPUBuffer}
+     */
+    get buffer() {
+        return this.#buffer;
+    }
+
+    #gpu_version = 0;
+    #version = 0;
+
+    /**
+     * Bumped when the set of live rows changes — an add or a remove — and not when one merely moves.
+     * The rows list is uploaded only when this moves, so a scene in continuous motion re-uploads
+     * nothing.
+     *
+     * @type {number}
+     */
+    #membership_version = 0;
+
+    /**
+     * Membership version the {@link #rows_buffer} currently holds.
+     * @type {number}
+     */
+    #rows_gpu_version = -1;
+
+    /**
+     * Compact mirror of the live `meshes` rows, in insertion order. Rebuilt from
+     * {@link #node_mapping} when membership churns.
+     *
+     * @type {Uint32Array}
+     */
+    #rows = new Uint32Array(0);
+
+    /**
+     * @type {GPUBuffer|undefined}
+     */
+    #rows_buffer
+
+    /**
+     *
+     * @param {GraphicsContext} graphics
+     */
+    constructor(graphics) {
+        assert.defined(graphics, 'graphics');
+        assert.equal(graphics.isGraphicsContext, true, 'graphics.isGraphicsContext !== true');
+
+        const device = graphics.device;
+
+        this.#graphics = graphics;
+        this.#device = device;
+
+        this.#buffer = device.createBuffer({
+            label: 'TLAS',
+            size: 1024,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
+        });
+    }
+
+    /**
+     *
+     * @type {Map<number, number>}
+     */
+    #node_mapping = new Map();
+
+    /**
+     *
+     * @param {number} index
+     * @param {Mesh} instance
+     */
+    instance_add(index, instance) {
+        assert.isNonNegativeInteger(index, 'index');
+        assert.defined(instance, 'instance');
+
+        const bvh = this.#bvh;
+
+        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.#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.
+     *
+     * @param {number} index
+     */
+    instance_remove(index) {
+        assert.isNonNegativeInteger(index, 'index');
+
+        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.#membership_version++;
+        this.#version++;
+    }
+
+    /**
+     *
+     * @param {number} index
+     * @param {Mesh} instance
+     */
+    instance_update(index, instance) {
+        assert.isNonNegativeInteger(index, 'index');
+        assert.defined(instance, 'instance');
+
+        const node = this.#node_mapping.get(index);
+
+        this.#bvh.node_move_aabb(node, instance.bounding_box);
+
+        this.#version++;
+    }
+
+    /**
+     * Bring {@link #rows_buffer} in line with the live row set, if and only if membership changed.
+     *
+     * @returns {number} number of live rows
+     */
+    #refresh_rows() {
+        const count = this.#node_mapping.size;
+
+        if (this.#rows_gpu_version === this.#membership_version && this.#rows.length >= count) {
+            return count;
+        }
+
+        if (this.#rows.length < count) {
+            this.#rows = new Uint32Array(count);
+        }
+
+        let i = 0;
+        for (const row of this.#node_mapping.keys()) {
+            this.#rows[i] = row;
+            i++;
+        }
+
+        const byte_size = Math.max(4, count * Uint32Array.BYTES_PER_ELEMENT);
+
+        if (this.#rows_buffer === undefined) {
+            this.#rows_buffer = this.#device.createBuffer({
+                label: 'TLAS/rows',
+                size: Math.max(1024, byte_size),
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC
+            });
+        } else {
+            this.#rows_buffer = ensure_buffer_capacity(this.#device, this.#rows_buffer, byte_size);
+        }
+
+        // Queue writes land in submission order ahead of command buffers submitted after them, so
+        // the build encoded below sees these rows. Offset and size are in elements of the source,
+        // per `GPUQueue.writeBuffer` — `#rows` can be longer than the live set.
+        this.#device.queue.writeBuffer(this.#rows_buffer, 0, this.#rows, 0, count);
+
+        this.#rows_gpu_version = this.#membership_version;
+
+        return count;
+    }
+
+    /**
+     * Build the tree, from the world AABBs the scene database holds.
+     *
+     * @param {GPUBuffer} scene_database_buffer
+     */
+    #build(scene_database_buffer) {
+        assert.defined(scene_database_buffer, 'scene_database_buffer');
+
+        const device = this.#device;
+
+        const element_count = this.#node_mapping.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
+        // be reassigned before the graph imports it.
+        this.#buffer = ensure_buffer_capacity(
+            device,
+            this.#buffer,
+            bvh_buffer_size(Math.max(1, element_count)),
+            1024,
+            1024,
+            1.2
+        );
+
+        if (element_count === 0) {
+            device.queue.writeBuffer(this.#buffer, 0, EMPTY_TREE);
+
+            return;
+        }
+
+        this.#refresh_rows();
+
+        const graph = new FrameGraph('TLAS build');
+
+        const rows = graph.import_resource(
+            "tlas/rows",
+            BufferResourceDescriptor.fromBuffer(this.#rows_buffer),
+            this.#rows_buffer
+        );
+
+        const scene_database = graph.import_resource(
+            "scene database",
+            BufferResourceDescriptor.fromBuffer(scene_database_buffer),
+            scene_database_buffer
+        );
+
+        const nodes = graph.import_resource(
+            "tlas/nodes",
+            BufferResourceDescriptor.fromBuffer(this.#buffer),
+            this.#buffer
+        );
+
+        const extract_data = {};
+        const extract_pass = graph.add("tlas/extract instance leaves", extract_data, extract_execute);
+
+        extract_data.element_count = element_count;
+        extract_data.rows = extract_pass.read(rows);
+        extract_data.scene_database = extract_pass.read(scene_database);
+
+        extract_data.leaf_bounds = extract_pass.create("tlas/leaf bounds", BufferResourceDescriptor.from(
+            element_count * 6 * Float32Array.BYTES_PER_ELEMENT,
+            GPUBufferUsage.STORAGE
+        ));
+
+        extract_data.leaf_payload = extract_pass.create("tlas/leaf payload", BufferResourceDescriptor.from(
+            element_count * Uint32Array.BYTES_PER_ELEMENT,
+            GPUBufferUsage.STORAGE
+        ));
+
+        extract_data.scene_bounds = extract_pass.create("tlas/scene bounds", BufferResourceDescriptor.from(
+            SCENE_BOUNDS_SEED.byteLength,
+            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+        ));
+
+        graph_bvh_build_lbvh({
+            graph,
+            leaf_bounds: extract_data.leaf_bounds,
+            leaf_payload: extract_data.leaf_payload,
+            scene_bounds: extract_data.scene_bounds,
+            element_count,
+            nodes,
+        });
+
+        const cmd = ShadeGPUCommandContext.create(this.#graphics, 'TLAS/build');
+
+        cmd.encodeGraph(graph);
+        cmd.finish();
+    }
+
+    /**
+     * @param {GPUBuffer} scene_database_buffer the table the world AABBs are read from
+     */
+    push_to_gpu(scene_database_buffer) {
+        this.#build(scene_database_buffer);
+
+        this.#gpu_version = this.#version;
+    }
+
+    /**
+     * @param {GPUBuffer} scene_database_buffer
+     */
+    update(scene_database_buffer) {
+        if (this.#gpu_version === this.#version) {
+            return;
+        }
+
+        this.push_to_gpu(scene_database_buffer);
+    }
+}
+
+/**
+ * @param pass_data
+ * @param {FramePassResources} resources
+ * @param {GraphicsExecutionContext} context
+ */
+function extract_execute(pass_data, resources, context) {
+    const encoder = context.encoder;
+
+    const scene_bounds = resources.get(pass_data.scene_bounds);
+
+    // Seeded rather than cleared: the merge is a min/max, and zero is not an identity for either.
+    encoder.writeBuffer(scene_bounds, 0, SCENE_BOUNDS_SEED.buffer, 0, SCENE_BOUNDS_SEED.byteLength);
+
+    shader_bvh_extract_instance_leaves.dispatchThreads({
+        encoder,
+        thread_count_x: pass_data.element_count,
+        bindings: {
+            settings: { element_count: pass_data.element_count },
+            rows: resources.get(pass_data.rows),
+            scene_database: resources.get(pass_data.scene_database),
+            leaf_bounds: resources.get(pass_data.leaf_bounds),
+            leaf_payload: resources.get(pass_data.leaf_payload),
+            scene_bounds,
+        }
+    });
+}