@woosh/meep-engine 3.11.2 → 3.12.0

package/src/shade/renderer/gpu_primitive/bvh/graph_bvh_build_lbvh.js

@@ -1,217 +1,217 @@
-import { assert } from "../../../../core/assert.js";
-import { round_up } from "../../../../core/math/round_up.js";
-import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
-import { BVH_HEADER_WORDS, bvh_buffer_size } from "./BVH_BUFFER_LAYOUT.js";
-import { graph_radix_sort } from "../sort/graph_radix_sort.js";
-import { BVH_BUILD_SETTINGS_STRUCT, BVH_NO_ROOT_WORD } from "./BVH_BUILD_SETTINGS_STRUCT.js";
-import { shader_bvh_emit_hierarchy } from "./shader_bvh_emit_hierarchy.js";
-import { shader_bvh_morton } from "./shader_bvh_morton.js";
-import { shader_bvh_refit } from "./shader_bvh_refit.js";
-
-/**
- * Record a GPU LBVH build over a flat set of leaves: Morton code, sort, Karras emission, bottom-up
- * refit. Everything scene- or geometry-specific happens upstream, in whichever extraction pass
- * produced `leaf_bounds` / `leaf_payload` / `scene_bounds` — this recorder knows only that it has
- * `element_count` boxes with payloads and somewhere to put a tree.
- *
- * The output honours the format in {@link BVH_BUFFER_LAYOUT}: a `u32` root word, then `2N-1` nodes
- * with internal nodes at `[0, N-2]` (root = 0, by Karras's construction) and leaf `j` at `(N-1)+j`.
- * That ordering differs from the CPU path's slot-order-with-holes, which is legal because no
- * consumer reads node *order* — only the node format and the root word. It is also exactly the
- * BLAS convention (root at node 0), which is why the same recorder serves the geometry side later.
- *
- * `element_count` must be at least 1. A single leaf falls out of the same passes with no special
- * case anywhere: the sort has nothing to reorder and returns its input, emission's tail `if` skips
- * the internal node and writes leaf 0 at node 0 with `parents[0] = BVH_NULL_NODE`, and the refit's
- * one thread reads that terminator and stops. The only thing it needs is a counters buffer WebGPU
- * will accept, since a tree of one leaf has no internal node to count arrivals at.
- *
- * Zero leaves is refused. There is no tree to write and no dispatch to make — the caller writes
- * `root = BVH_NULL_NODE` host-side, which is the four bytes consumers already read as "empty".
- *
- * @param {FrameGraph} graph
- * @param {number} leaf_bounds buffer resource ID, `array<f32>`, six floats per leaf: `[min.xyz, max.xyz]`
- * @param {number} leaf_payload buffer resource ID, `array<u32>`, one per leaf — becomes the leaf's `child_2`
- * @param {number} scene_bounds buffer resource ID, `array<f32>`, six floats bounding every leaf centroid
- * @param {number} element_count number of leaves, at least 1
- * @param {number} nodes buffer resource ID to write the tree into, at least `bvh_buffer_size(element_count)` bytes
- * @param {number} [node_word_offset] u32 word the tree's node 0 starts at. Defaults to
- * {@link BVH_HEADER_WORDS} — straight after a root word, which is what a tree that owns its buffer
- * wants. A tree living inside a shared arena passes its address there instead.
- * @param {number} [root_word_offset] u32 word to write the root index into, or
- * {@link BVH_NO_ROOT_WORD} for a format that has no header. Defaults to word 0.
- * @returns {{nodes: number, keys: number, values: number}} the written tree, plus the Morton order
- * it was built from — `values[i]` is the leaf that sorted to position `i`. The permutation is what a
- * refit-only update would rewrite leaves through, and what the verify harness feeds the CPU oracle
- * so that a topology comparison tests emission rather than float rounding in the quantiser.
- */
-export function graph_bvh_build_lbvh({
-                                         graph,
-                                         leaf_bounds,
-                                         leaf_payload,
-                                         scene_bounds,
-                                         element_count,
-                                         nodes,
-                                         node_word_offset = BVH_HEADER_WORDS,
-                                         root_word_offset = 0,
-                                     }) {
-
-    assert.defined(graph, 'graph');
-    assert.isNonNegativeInteger(leaf_bounds, 'leaf_bounds');
-    assert.isNonNegativeInteger(leaf_payload, 'leaf_payload');
-    assert.isNonNegativeInteger(scene_bounds, 'scene_bounds');
-    assert.isNonNegativeInteger(nodes, 'nodes');
-    assert.isNonNegativeInteger(element_count, 'element_count');
-    assert.greaterThanOrEqual(element_count, 1, 'element_count — an empty tree is written host-side');
-    assert.isNonNegativeInteger(node_word_offset, 'node_word_offset');
-    assert.isNonNegativeInteger(root_word_offset, 'root_word_offset');
-
-    const node_count = 2 * element_count - 1;
-
-    // aligned on a 1k boundary to lower memory fragmentation, as the sort's own transients are
-    const KEY_DESCRIPTOR = BufferResourceDescriptor.from(
-        round_up(element_count * Uint32Array.BYTES_PER_ELEMENT, 1024),
-        GPUBufferUsage.STORAGE
-    );
-
-    const PARENTS_DESCRIPTOR = BufferResourceDescriptor.from(
-        round_up(node_count * Uint32Array.BYTES_PER_ELEMENT, 1024),
-        GPUBufferUsage.STORAGE
-    );
-
-    // One per internal node. A single-leaf tree has none, and a zero-sized buffer is not a thing
-    // WebGPU will hand out, so it gets one cell that nothing ever touches.
-    const counters_size = Math.max(1, element_count - 1) * Uint32Array.BYTES_PER_ELEMENT;
-
-    // Every build needs these at zero. A fresh buffer arrives zeroed; a pool-reused one carries
-    // the previous build's arrival counts, which would let a first arrival believe it was a second
-    // and fit a node from a sibling that has not been written yet.
-    const COUNTERS_DESCRIPTOR = BufferResourceDescriptor.from(
-        counters_size,
-        GPUBufferUsage.STORAGE,
-        0, counters_size
-    );
-
-    // The build owns its `parents` and `leaf_nodes` outright — they are transients of this graph,
-    // one tree to a buffer — so both start at word 0.
-    const settings = {
-        element_count,
-        node_word_offset,
-        root_word_offset,
-        parents_offset: 0,
-        leaf_nodes_offset: 0,
-    };
-
-    /**
-     * @param pass_data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     */
-    function execute_morton(pass_data, resources, context) {
-        const encoder = context.encoder;
-
-        shader_bvh_morton.dispatchLinear({
-            encoder,
-            element_count,
-            bindings: {
-                settings: encoder.allocateTransientValueBuffer(BVH_BUILD_SETTINGS_STRUCT, settings),
-                leaf_bounds: resources.get(pass_data.leaf_bounds),
-                scene_bounds: resources.get(pass_data.scene_bounds),
-                keys: resources.get(pass_data.keys),
-                values: resources.get(pass_data.values),
-            }
-        });
-    }
-
-    /**
-     * @param pass_data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     */
-    function execute_emit(pass_data, resources, context) {
-        const encoder = context.encoder;
-
-        const output = resources.get(pass_data.nodes);
-
-        // the tree ends at its last node; where it starts is the caller's business
-        const end_byte = (node_word_offset + (2 * element_count - 1) * 8) * Uint32Array.BYTES_PER_ELEMENT;
-
-        assert.greaterThanOrEqual(output.size, end_byte, 'node buffer underflow');
-
-        shader_bvh_emit_hierarchy.dispatchLinear({
-            encoder,
-            element_count,
-            bindings: {
-                settings: encoder.allocateTransientValueBuffer(BVH_BUILD_SETTINGS_STRUCT, settings),
-                keys: resources.get(pass_data.keys),
-                values: resources.get(pass_data.values),
-                leaf_bounds: resources.get(pass_data.leaf_bounds),
-                leaf_payload: resources.get(pass_data.leaf_payload),
-                nodes: output,
-                parents: resources.get(pass_data.parents),
-                leaf_nodes: resources.get(pass_data.leaf_nodes),
-            }
-        });
-    }
-
-    /**
-     * @param pass_data
-     * @param {FramePassResources} resources
-     * @param {GraphicsExecutionContext} context
-     */
-    function execute_refit(pass_data, resources, context) {
-        const encoder = context.encoder;
-
-        shader_bvh_refit.dispatchLinear({
-            encoder,
-            element_count,
-            bindings: {
-                settings: encoder.allocateTransientValueBuffer(BVH_BUILD_SETTINGS_STRUCT, settings),
-                parents: resources.get(pass_data.parents),
-                leaf_nodes: resources.get(pass_data.leaf_nodes),
-                counters: resources.get(pass_data.counters),
-                nodes: resources.get(pass_data.nodes),
-            }
-        });
-    }
-
-    const morton_data = {};
-    const morton_pass = graph.add("bvh build/morton", morton_data, execute_morton);
-
-    morton_data.leaf_bounds = morton_pass.read(leaf_bounds);
-    morton_data.scene_bounds = morton_pass.read(scene_bounds);
-    morton_data.keys = morton_pass.create("bvh build/morton keys", KEY_DESCRIPTOR);
-    morton_data.values = morton_pass.create("bvh build/leaf order", KEY_DESCRIPTOR);
-
-    const sorted = graph_radix_sort({
-        graph,
-        keys: morton_data.keys,
-        values: morton_data.values,
-        element_count,
-    });
-
-    const emit_data = {};
-    const emit_pass = graph.add("bvh build/emit hierarchy", emit_data, execute_emit);
-
-    emit_data.keys = emit_pass.read(sorted.keys);
-    emit_data.values = emit_pass.read(sorted.values);
-    emit_data.leaf_bounds = emit_pass.read(leaf_bounds);
-    emit_data.leaf_payload = emit_pass.read(leaf_payload);
-    emit_data.nodes = emit_pass.write(nodes);
-    emit_data.parents = emit_pass.create("bvh build/parents", PARENTS_DESCRIPTOR);
-    emit_data.leaf_nodes = emit_pass.create("bvh build/leaf nodes", KEY_DESCRIPTOR);
-
-    const refit_data = {};
-    const refit_pass = graph.add("bvh build/refit", refit_data, execute_refit);
-
-    refit_data.parents = refit_pass.read(emit_data.parents);
-    refit_data.leaf_nodes = refit_pass.read(emit_data.leaf_nodes);
-    refit_data.counters = refit_pass.create("bvh build/refit counters", COUNTERS_DESCRIPTOR);
-    refit_data.nodes = refit_pass.write(emit_data.nodes);
-
-    return {
-        nodes: refit_data.nodes,
-        keys: sorted.keys,
-        values: sorted.values,
-    };
-}
+import { assert } from "../../../../core/assert.js";
+import { round_up } from "../../../../core/math/round_up.js";
+import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
+import { BVH_HEADER_WORDS, bvh_buffer_size } from "./BVH_BUFFER_LAYOUT.js";
+import { graph_radix_sort } from "../sort/graph_radix_sort.js";
+import { BVH_BUILD_SETTINGS_STRUCT, BVH_NO_ROOT_WORD } from "./BVH_BUILD_SETTINGS_STRUCT.js";
+import { shader_bvh_emit_hierarchy } from "./shader_bvh_emit_hierarchy.js";
+import { shader_bvh_morton } from "./shader_bvh_morton.js";
+import { shader_bvh_refit } from "./shader_bvh_refit.js";
+
+/**
+ * Record a GPU LBVH build over a flat set of leaves: Morton code, sort, Karras emission, bottom-up
+ * refit. Everything scene- or geometry-specific happens upstream, in whichever extraction pass
+ * produced `leaf_bounds` / `leaf_payload` / `scene_bounds` — this recorder knows only that it has
+ * `element_count` boxes with payloads and somewhere to put a tree.
+ *
+ * The output honours the format in {@link BVH_BUFFER_LAYOUT}: a `u32` root word, then `2N-1` nodes
+ * with internal nodes at `[0, N-2]` (root = 0, by Karras's construction) and leaf `j` at `(N-1)+j`.
+ * That ordering differs from the CPU path's slot-order-with-holes, which is legal because no
+ * consumer reads node *order* — only the node format and the root word. It is also exactly the
+ * BLAS convention (root at node 0), which is why the same recorder serves the geometry side later.
+ *
+ * `element_count` must be at least 1. A single leaf falls out of the same passes with no special
+ * case anywhere: the sort has nothing to reorder and returns its input, emission's tail `if` skips
+ * the internal node and writes leaf 0 at node 0 with `parents[0] = BVH_NULL_NODE`, and the refit's
+ * one thread reads that terminator and stops. The only thing it needs is a counters buffer WebGPU
+ * will accept, since a tree of one leaf has no internal node to count arrivals at.
+ *
+ * Zero leaves is refused. There is no tree to write and no dispatch to make — the caller writes
+ * `root = BVH_NULL_NODE` host-side, which is the four bytes consumers already read as "empty".
+ *
+ * @param {FrameGraph} graph
+ * @param {number} leaf_bounds buffer resource ID, `array<f32>`, six floats per leaf: `[min.xyz, max.xyz]`
+ * @param {number} leaf_payload buffer resource ID, `array<u32>`, one per leaf — becomes the leaf's `child_2`
+ * @param {number} scene_bounds buffer resource ID, `array<f32>`, six floats bounding every leaf centroid
+ * @param {number} element_count number of leaves, at least 1
+ * @param {number} nodes buffer resource ID to write the tree into, at least `bvh_buffer_size(element_count)` bytes
+ * @param {number} [node_word_offset] u32 word the tree's node 0 starts at. Defaults to
+ * {@link BVH_HEADER_WORDS} — straight after a root word, which is what a tree that owns its buffer
+ * wants. A tree living inside a shared arena passes its address there instead.
+ * @param {number} [root_word_offset] u32 word to write the root index into, or
+ * {@link BVH_NO_ROOT_WORD} for a format that has no header. Defaults to word 0.
+ * @returns {{nodes: number, keys: number, values: number}} the written tree, plus the Morton order
+ * it was built from — `values[i]` is the leaf that sorted to position `i`. The permutation is what a
+ * refit-only update would rewrite leaves through, and what the verify harness feeds the CPU oracle
+ * so that a topology comparison tests emission rather than float rounding in the quantiser.
+ */
+export function graph_bvh_build_lbvh({
+                                         graph,
+                                         leaf_bounds,
+                                         leaf_payload,
+                                         scene_bounds,
+                                         element_count,
+                                         nodes,
+                                         node_word_offset = BVH_HEADER_WORDS,
+                                         root_word_offset = 0,
+                                     }) {
+
+    assert.defined(graph, 'graph');
+    assert.isNonNegativeInteger(leaf_bounds, 'leaf_bounds');
+    assert.isNonNegativeInteger(leaf_payload, 'leaf_payload');
+    assert.isNonNegativeInteger(scene_bounds, 'scene_bounds');
+    assert.isNonNegativeInteger(nodes, 'nodes');
+    assert.isNonNegativeInteger(element_count, 'element_count');
+    assert.greaterThanOrEqual(element_count, 1, 'element_count — an empty tree is written host-side');
+    assert.isNonNegativeInteger(node_word_offset, 'node_word_offset');
+    assert.isNonNegativeInteger(root_word_offset, 'root_word_offset');
+
+    const node_count = 2 * element_count - 1;
+
+    // aligned on a 1k boundary to lower memory fragmentation, as the sort's own transients are
+    const KEY_DESCRIPTOR = BufferResourceDescriptor.from(
+        round_up(element_count * Uint32Array.BYTES_PER_ELEMENT, 1024),
+        GPUBufferUsage.STORAGE
+    );
+
+    const PARENTS_DESCRIPTOR = BufferResourceDescriptor.from(
+        round_up(node_count * Uint32Array.BYTES_PER_ELEMENT, 1024),
+        GPUBufferUsage.STORAGE
+    );
+
+    // One per internal node. A single-leaf tree has none, and a zero-sized buffer is not a thing
+    // WebGPU will hand out, so it gets one cell that nothing ever touches.
+    const counters_size = Math.max(1, element_count - 1) * Uint32Array.BYTES_PER_ELEMENT;
+
+    // Every build needs these at zero. A fresh buffer arrives zeroed; a pool-reused one carries
+    // the previous build's arrival counts, which would let a first arrival believe it was a second
+    // and fit a node from a sibling that has not been written yet.
+    const COUNTERS_DESCRIPTOR = BufferResourceDescriptor.from(
+        counters_size,
+        GPUBufferUsage.STORAGE,
+        0, counters_size
+    );
+
+    // The build owns its `parents` and `leaf_nodes` outright — they are transients of this graph,
+    // one tree to a buffer — so both start at word 0.
+    const settings = {
+        element_count,
+        node_word_offset,
+        root_word_offset,
+        parents_offset: 0,
+        leaf_nodes_offset: 0,
+    };
+
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_morton(pass_data, resources, context) {
+        const encoder = context.encoder;
+
+        shader_bvh_morton.dispatchThreads({
+            encoder,
+            thread_count_x: element_count,
+            bindings: {
+                settings: encoder.allocateTransientValueBuffer(BVH_BUILD_SETTINGS_STRUCT, settings),
+                leaf_bounds: resources.get(pass_data.leaf_bounds),
+                scene_bounds: resources.get(pass_data.scene_bounds),
+                keys: resources.get(pass_data.keys),
+                values: resources.get(pass_data.values),
+            }
+        });
+    }
+
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_emit(pass_data, resources, context) {
+        const encoder = context.encoder;
+
+        const output = resources.get(pass_data.nodes);
+
+        // the tree ends at its last node; where it starts is the caller's business
+        const end_byte = (node_word_offset + (2 * element_count - 1) * 8) * Uint32Array.BYTES_PER_ELEMENT;
+
+        assert.greaterThanOrEqual(output.size, end_byte, 'node buffer underflow');
+
+        shader_bvh_emit_hierarchy.dispatchThreads({
+            encoder,
+            thread_count_x: element_count,
+            bindings: {
+                settings: encoder.allocateTransientValueBuffer(BVH_BUILD_SETTINGS_STRUCT, settings),
+                keys: resources.get(pass_data.keys),
+                values: resources.get(pass_data.values),
+                leaf_bounds: resources.get(pass_data.leaf_bounds),
+                leaf_payload: resources.get(pass_data.leaf_payload),
+                nodes: output,
+                parents: resources.get(pass_data.parents),
+                leaf_nodes: resources.get(pass_data.leaf_nodes),
+            }
+        });
+    }
+
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_refit(pass_data, resources, context) {
+        const encoder = context.encoder;
+
+        shader_bvh_refit.dispatchThreads({
+            encoder,
+            thread_count_x: element_count,
+            bindings: {
+                settings: encoder.allocateTransientValueBuffer(BVH_BUILD_SETTINGS_STRUCT, settings),
+                parents: resources.get(pass_data.parents),
+                leaf_nodes: resources.get(pass_data.leaf_nodes),
+                counters: resources.get(pass_data.counters),
+                nodes: resources.get(pass_data.nodes),
+            }
+        });
+    }
+
+    const morton_data = {};
+    const morton_pass = graph.add("bvh build/morton", morton_data, execute_morton);
+
+    morton_data.leaf_bounds = morton_pass.read(leaf_bounds);
+    morton_data.scene_bounds = morton_pass.read(scene_bounds);
+    morton_data.keys = morton_pass.create("bvh build/morton keys", KEY_DESCRIPTOR);
+    morton_data.values = morton_pass.create("bvh build/leaf order", KEY_DESCRIPTOR);
+
+    const sorted = graph_radix_sort({
+        graph,
+        keys: morton_data.keys,
+        values: morton_data.values,
+        element_count,
+    });
+
+    const emit_data = {};
+    const emit_pass = graph.add("bvh build/emit hierarchy", emit_data, execute_emit);
+
+    emit_data.keys = emit_pass.read(sorted.keys);
+    emit_data.values = emit_pass.read(sorted.values);
+    emit_data.leaf_bounds = emit_pass.read(leaf_bounds);
+    emit_data.leaf_payload = emit_pass.read(leaf_payload);
+    emit_data.nodes = emit_pass.write(nodes);
+    emit_data.parents = emit_pass.create("bvh build/parents", PARENTS_DESCRIPTOR);
+    emit_data.leaf_nodes = emit_pass.create("bvh build/leaf nodes", KEY_DESCRIPTOR);
+
+    const refit_data = {};
+    const refit_pass = graph.add("bvh build/refit", refit_data, execute_refit);
+
+    refit_data.parents = refit_pass.read(emit_data.parents);
+    refit_data.leaf_nodes = refit_pass.read(emit_data.leaf_nodes);
+    refit_data.counters = refit_pass.create("bvh build/refit counters", COUNTERS_DESCRIPTOR);
+    refit_data.nodes = refit_pass.write(emit_data.nodes);
+
+    return {
+        nodes: refit_data.nodes,
+        keys: sorted.keys,
+        values: sorted.values,
+    };
+}

package/src/shade/renderer/gpu_primitive/bvh/shader_bvh_emit_hierarchy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_bvh_emit_hierarchy.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_emit_hierarchy.js"],"names":[],"mappings":"AAgBA,yCAA0C;AAqG1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wCAFU,aAAa,CAOpB;8BA1I2B,+BAA+B"}
+{"version":3,"file":"shader_bvh_emit_hierarchy.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_emit_hierarchy.js"],"names":[],"mappings":"AAgBA,yCAA0C;AAqG1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wCAFU,aAAa,CAMpB;8BAzI2B,+BAA+B"}