@woosh/meep-engine 3.2.0 → 3.4.0

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

@@ -0,0 +1,79 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_bvh_delta } from "./chunk_bvh_delta.js";
+
+/**
+ * The `[first, last]` code range internal node `idx` covers — a transliteration of `determineRange`
+ * inside {@link ebvh_build_hierarchy_radix}: pick the direction the node grows in by comparing the
+ * prefixes shared with either neighbour, find an upper bound on its length by doubling, then binary
+ * search inside that bound.
+ *
+ * Node 0 is short-circuited to the whole array, as on the CPU, so callers do not special-case the
+ * root.
+ *
+ * Returned as `vec2<u32>(first, last)`; both ends are always valid leaf indices.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_determine_range = CodeChunk.from(
+    //language=WGSL
+    `
+fn bvh_determine_range(codes: ptr<storage, array<u32>>, leaf_count: u32, idx: u32) -> vec2<u32> {
+    // For the root the range is unambiguously [0, leaf_count - 1].
+    if (idx == 0u) {
+        return vec2<u32>(0u, leaf_count - 1u);
+    }
+
+    let index = i32(idx);
+    let count = i32(leaf_count);
+
+    let prefix_right = bvh_delta(codes, leaf_count, idx, index + 1);
+    let prefix_left = bvh_delta(codes, leaf_count, idx, index - 1);
+
+    var direction = -1;
+    if (prefix_right - prefix_left > 0) {
+        direction = 1;
+    }
+
+    // Minimum prefix length required to stay in this range — anything sharing fewer bits than this
+    // is outside the node's subtree.
+    let min_prefix_range = bvh_delta(codes, leaf_count, idx, index - direction);
+
+    // Expand the maximum range with exponential growth, bounded by the array.
+    var lmax = 2;
+    var next_key = index + lmax * direction;
+
+    loop {
+        if (!(next_key >= 0 && next_key < count
+            && bvh_delta(codes, leaf_count, idx, next_key) > min_prefix_range)) {
+            break;
+        }
+
+        lmax = lmax * 2;
+        next_key = index + lmax * direction;
+    }
+
+    // Binary-search for the actual length within [0, lmax].
+    var length = 0;
+    loop {
+        lmax = (lmax + 1) >> 1u;
+
+        let candidate = index + (length + lmax) * direction;
+
+        if (candidate >= 0 && candidate < count) {
+            if (bvh_delta(codes, leaf_count, idx, candidate) > min_prefix_range) {
+                length = length + lmax;
+            }
+        }
+
+        if (lmax <= 1) {
+            break;
+        }
+    }
+
+    let other = index + length * direction;
+
+    return vec2<u32>(u32(min(index, other)), u32(max(index, other)));
+}
+`, [
+    chunk_bvh_delta,
+]);

package/src/shade/renderer/gpu_primitive/bvh/chunk_bvh_find_split.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The split point of the range `[first, last]` — the highest index still sharing more leading bits
+ * with `first` than `first` shares with `last`. Transliterated from `find_split` inside
+ * {@link ebvh_build_hierarchy_radix}, including the thing it does *not* do.
+ *
+ * There is deliberately **no midpoint special case for identical Morton codes**. `bvh_delta` breaks
+ * ties by index, so the binary search below lands on a split consistent with the ranges
+ * {@link bvh_determine_range} produces. A midpoint shortcut returns a different split, and a parent
+ * and its child then both claim the same leaf — a shared node, which is not a tree, and which only
+ * shows up when duplicate codes appear mid-range.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_find_split: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bvh_find_split.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bvh_find_split.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/chunk_bvh_find_split.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,mCAFU,SAAS,CAkChB;0BAhDuB,oCAAoC"}

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

@@ -0,0 +1,49 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_bvh_delta } from "./chunk_bvh_delta.js";
+
+/**
+ * The split point of the range `[first, last]` — the highest index still sharing more leading bits
+ * with `first` than `first` shares with `last`. Transliterated from `find_split` inside
+ * {@link ebvh_build_hierarchy_radix}, including the thing it does *not* do.
+ *
+ * There is deliberately **no midpoint special case for identical Morton codes**. `bvh_delta` breaks
+ * ties by index, so the binary search below lands on a split consistent with the ranges
+ * {@link bvh_determine_range} produces. A midpoint shortcut returns a different split, and a parent
+ * and its child then both claim the same leaf — a shared node, which is not a tree, and which only
+ * shows up when duplicate codes appear mid-range.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_find_split = CodeChunk.from(
+    //language=WGSL
+    `
+fn bvh_find_split(codes: ptr<storage, array<u32>>, n: u32, first: u32, last: u32) -> u32 {
+    // Number of highest bits that match between first and last (index-tiebroken).
+    let common_prefix = bvh_delta(codes, n, first, i32(last));
+
+    // Binary search for the highest index that still shares more than common_prefix bits with
+    // the code at 'first'.
+    var split = first;
+    var step = last - first;
+
+    loop {
+        step = (step + 1u) >> 1u;
+
+        let candidate = split + step;
+
+        if (candidate < last) {
+            if (bvh_delta(codes, n, first, i32(candidate)) > common_prefix) {
+                split = candidate;
+            }
+        }
+
+        if (step <= 1u) {
+            break;
+        }
+    }
+
+    return split;
+}
+`, [
+    chunk_bvh_delta,
+]);

package/src/shade/renderer/gpu_primitive/bvh/graph_bvh_build_lbvh.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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, root_word_offset, }: FrameGraph): {
+    nodes: number;
+    keys: number;
+    values: number;
+};
+//# sourceMappingURL=graph_bvh_build_lbvh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_bvh_build_lbvh.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/graph_bvh_build_lbvh.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,iKALa;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CA8KzD"}

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

@@ -0,0 +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,
+    };
+}

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

@@ -0,0 +1,24 @@
+export const BVH_EMIT_WORKGROUP_SIZE: 64;
+/**
+ * Karras hierarchy emission — pass 3 of {@link graph_bvh_build_lbvh}, and a transliteration of
+ * {@link ebvh_build_hierarchy_radix} with the DXR Fallback's index layout: internal node `k` at node
+ * `k` (root = 0), leaf `j` at node `(n-1)+j`, `2n-1` nodes in total.
+ *
+ * Node indices are local to the tree; where node 0 actually lands is `settings.node_word_offset`,
+ * so the same kernel writes a TLAS that owns its buffer and a BLAS that is a tenant in a shared
+ * arena. Root-at-node-0 is what both conventions want, which is why one kernel can serve them.
+ *
+ * One dispatch of `n` threads with a tail `if`, which is the canonical LBVH formulation: thread `i`
+ * always writes leaf `(n-1)+i`, and threads below `n-1` additionally derive internal node `i`'s
+ * range and split and wire its two children.
+ *
+ * Barrier-free, atomic-free, subgroup-free, and a pure function of the sorted keys — deliberately,
+ * because that is what lets the WGSL emulator execute this kernel point-wise in vitest against the
+ * in-repo CPU oracle, duplicate-code runs and all. Internal-node bounds are left to
+ * {@link shader_bvh_refit}.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_emit_hierarchy: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_bvh_emit_hierarchy.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,143 @@
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { BVH_NULL_NODE_DEFINITION } from "../../shader/chunk/bvh/BVH_NULL_NODE_DEFINITION.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    BVH_NODE_BOUNDS_WORD,
+    BVH_NODE_CHILD_1_WORD,
+    BVH_NODE_CHILD_2_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "./BVH_BUFFER_LAYOUT.js";
+import { BVH_BUILD_SETTINGS_STRUCT, BVH_NO_ROOT_WORD } from "./BVH_BUILD_SETTINGS_STRUCT.js";
+import { chunk_bvh_determine_range } from "./chunk_bvh_determine_range.js";
+import { chunk_bvh_find_split } from "./chunk_bvh_find_split.js";
+
+export const BVH_EMIT_WORKGROUP_SIZE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addUniform("settings", BVH_BUILD_SETTINGS_STRUCT)
+    // sorted Morton codes, and the leaf index each one came from
+    .addStorageBuffer("keys", WebGPUArray.from(u32), false)
+    .addStorageBuffer("values", WebGPUArray.from(u32), false)
+    .addStorageBuffer("leaf_bounds", WebGPUArray.from(f32), false)
+    .addStorageBuffer("leaf_payload", WebGPUArray.from(u32), false)
+    // `{root: u32, nodes: array<BVH2_NODE_STRUCT>}`, written flat
+    .addStorageBuffer("nodes", WebGPUArray.from(u32), true)
+    // parent of every node, indexed the same way the node buffer is
+    .addStorageBuffer("parents", WebGPUArray.from(u32), true)
+    // which node each leaf ordinal lives at — see the shader's note on why this is written out
+    .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const NODE_STRIDE = ${BVH_NODE_STRIDE_WORDS}u;
+const NODE_BOUNDS = ${BVH_NODE_BOUNDS_WORD}u;
+const NODE_CHILD_1 = ${BVH_NODE_CHILD_1_WORD}u;
+const NODE_CHILD_2 = ${BVH_NODE_CHILD_2_WORD}u;
+const NO_ROOT_WORD = ${BVH_NO_ROOT_WORD}u;
+
+fn bvh_node_word(node: u32) -> u32 {
+    return settings.node_word_offset + node * NODE_STRIDE;
+}
+
+@compute @workgroup_size(${BVH_EMIT_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let i = gid.x;
+    let n = settings.element_count;
+
+    if (i >= n) {
+        return;
+    }
+
+    // Leaf j lives at node (n-1)+j, internal node k at node k. Root is internal node 0 by Karras's
+    // construction — it is the node whose range is the whole array.
+    let leaf_source = values[i];
+    let leaf_node = (n - 1u) + i;
+
+    let bounds_source = leaf_source * 6u;
+    let leaf_word = bvh_node_word(leaf_node);
+
+    for (var k = 0u; k < 6u; k += 1u) {
+        nodes[leaf_word + NODE_BOUNDS + k] = bitcast<u32>(leaf_bounds[bounds_source + k]);
+    }
+
+    nodes[leaf_word + NODE_CHILD_1] = BVH_NULL_NODE;
+    nodes[leaf_word + NODE_CHILD_2] = leaf_payload[leaf_source];
+
+    // Where the leaves are is an output of construction, not a convention two kernels have to
+    // share. For this layout it is (n-1)+i and the refit could work it out — but a tree that was
+    // copied rather than built has its leaves wherever its builder put them, and the refit reads
+    // this the same way for both.
+    leaf_nodes[i] = leaf_node;
+
+    // n leaves, n-1 internal nodes — the tail thread has only a leaf to write.
+    if (i < n - 1u) {
+        let range = bvh_determine_range(&keys, n, i);
+
+        let first = range.x;
+        let last = range.y;
+
+        let split = bvh_find_split(&keys, n, first, last);
+
+        // A subrange of one element is a leaf; otherwise it is owned by the internal node whose
+        // left boundary sits at that code index.
+        let child_1 = select(split, (n - 1u) + split, split == first);
+        let child_2 = select(split + 1u, (n - 1u) + split + 1u, split + 1u == last);
+
+        let node_word = bvh_node_word(i);
+
+        nodes[node_word + NODE_CHILD_1] = child_1;
+        nodes[node_word + NODE_CHILD_2] = child_2;
+
+        // The refit climbs these; internal-node bounds are its business, not this pass's.
+        parents[child_1] = i;
+        parents[child_2] = i;
+    }
+
+    if (i == 0u) {
+        // Constant by construction, but a tree whose format has a root word has consumers that read
+        // it. A BLAS has none — its root is node 0 by convention — and says so with NO_ROOT_WORD.
+        if (settings.root_word_offset != NO_ROOT_WORD) {
+            nodes[settings.root_word_offset] = 0u;
+        }
+
+        // Where the refit's climb stops.
+        parents[0] = BVH_NULL_NODE;
+    }
+}
+`, [
+    BVH_NULL_NODE_DEFINITION,
+    chunk_bvh_determine_range,
+    chunk_bvh_find_split,
+]);
+
+/**
+ * Karras hierarchy emission — pass 3 of {@link graph_bvh_build_lbvh}, and a transliteration of
+ * {@link ebvh_build_hierarchy_radix} with the DXR Fallback's index layout: internal node `k` at node
+ * `k` (root = 0), leaf `j` at node `(n-1)+j`, `2n-1` nodes in total.
+ *
+ * Node indices are local to the tree; where node 0 actually lands is `settings.node_word_offset`,
+ * so the same kernel writes a TLAS that owns its buffer and a BLAS that is a tenant in a shared
+ * arena. Root-at-node-0 is what both conventions want, which is why one kernel can serve them.
+ *
+ * One dispatch of `n` threads with a tail `if`, which is the canonical LBVH formulation: thread `i`
+ * always writes leaf `(n-1)+i`, and threads below `n-1` additionally derive internal node `i`'s
+ * range and split and wire its two children.
+ *
+ * Barrier-free, atomic-free, subgroup-free, and a pure function of the sorted keys — deliberately,
+ * because that is what lets the WGSL emulator execute this kernel point-wise in vitest against the
+ * in-repo CPU oracle, duplicate-code runs and all. Internal-node bounds are left to
+ * {@link shader_bvh_refit}.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_emit_hierarchy = ComputeShader.from({
+    label: "BVHBuild/EmitHierarchy",
+    resources,
+    body,
+    group_size: [BVH_EMIT_WORKGROUP_SIZE, 1, 1],
+});

package/src/shade/renderer/gpu_primitive/bvh/shader_bvh_morton.d.ts

@@ -0,0 +1,17 @@
+export const BVH_MORTON_WORKGROUP_SIZE: 64;
+/**
+ * Morton code per leaf — pass 1 of {@link graph_bvh_build_lbvh}.
+ *
+ * The leaf's centroid is quantised to ten bits per axis inside the scene bounds and interleaved
+ * into a 30-bit code, matching `v3_morton_encode_bounded` + `v3_morton_encode_normalized` on the
+ * CPU term for term (`round(1023 * t)`, zero-extent axes scaled by zero). `values[i] = i` seeds the
+ * permutation the sort then carries.
+ *
+ * Pure per-invocation: no barriers, no atomics, no subgroups — which is what lets the emulator tier
+ * run it point-wise against the CPU encoder.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_morton: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_bvh_morton.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_bvh_morton.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_morton.js"],"names":[],"mappings":"AAQA,2CAA4C;AAwD5C;;;;;;;;;;;;GAYG;AACH,gCAFU,aAAa,CAOpB;8BA9E2B,+BAA+B"}