@woosh/meep-engine 3.47.0 → 3.50.0

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

@@ -0,0 +1,222 @@
+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 { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_sort_bitonic_workgroup } from "../sort/chunk_sort_bitonic_workgroup.js";
+import { SORT_KEYS_PER_THREAD, SORT_TILE_SIZE, SORT_WORKGROUP_SIZE } from "../sort/defs.js";
+import { BVH_BUILD_SETTINGS_STRUCT, BVH_NO_ROOT_WORD } from "./BVH_BUILD_SETTINGS_STRUCT.js";
+import { BVH_NODE_LAYOUT_DEFINITION } from "./BVH_NODE_LAYOUT_DEFINITION.js";
+import { BVH_REFIT_DEFERRED_DEFINITION } from "./BVH_REFIT_DEFERRED_DEFINITION.js";
+import { chunk_bvh_internal_children } from "./chunk_bvh_internal_children.js";
+import { chunk_bvh_morton_code } from "./chunk_bvh_morton_code.js";
+import { chunk_bvh_refit_climb } from "./chunk_bvh_refit_climb.js";
+import { chunk_bvh_refit_repair } from "./chunk_bvh_refit_repair.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+// see shader_bvh_morton — the same build settings, carried as immediate data
+resources.setImmediate("settings", BVH_BUILD_SETTINGS_STRUCT);
+
+resources.createGroup()
+    // six floats per leaf: [min.xyz, max.xyz]
+    .addStorageBuffer("leaf_bounds", WebGPUArray.from(f32), false)
+    .addStorageBuffer("leaf_payload", WebGPUArray.from(u32), false)
+    // the same six floats over the whole set, produced by the extraction pass
+    .addStorageBuffer("scene_bounds", WebGPUArray.from(f32), false)
+    // the Morton order the tree was built from, published as the multi-pass build publishes it
+    .addStorageBuffer("sorted_keys", WebGPUArray.from(u32), true)
+    .addStorageBuffer("sorted_values", WebGPUArray.from(u32), true)
+    // `{root: u32, nodes: array<BVH2_NODE_STRUCT>}`, bound flat and atomic, as the refit binds it
+    .addStorageBuffer("nodes", WebGPUArray.from(atomic_u32), true)
+    // one arrival counter per internal node; zeroed here, so they can arrive with anything in them
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
+    // the nodes the climb defers to the repair at the end; header zeroed here too
+    .addStorageBuffer("refit_deferred", WebGPUArray.from(atomic_u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WORKGROUP_SIZE = ${SORT_WORKGROUP_SIZE}u;
+const KEYS_PER_THREAD = ${SORT_KEYS_PER_THREAD}u;
+const NO_ROOT_WORD = ${BVH_NO_ROOT_WORD}u;
+
+// Each leaf's Morton code, and beside it the leaf it came from. The bitonic sort orders them in
+// place, and emission reads the sorted codes from here by name.
+var<workgroup> keys: array<u32, ${SORT_TILE_SIZE}>;
+var<workgroup> values: array<u32, ${SORT_TILE_SIZE}>;
+
+// Parent of every node, indexed as the node buffer is, 2N-1 of them. With the two arrays above that
+// is 16,380 bytes, inside the 16 KiB default limit. The climb reads it once per step, so it is
+// here rather than one more storage round trip.
+var<workgroup> parents: array<u32, ${2 * SORT_TILE_SIZE - 1}>;
+
+@compute @workgroup_size(WORKGROUP_SIZE, 1, 1)
+fn main(@builtin(local_invocation_index) thread_id: u32) {
+    let n = settings.element_count;
+
+    let scene_low = vec3<f32>(scene_bounds[0], scene_bounds[1], scene_bounds[2]);
+    let scene_high = vec3<f32>(scene_bounds[3], scene_bounds[4], scene_bounds[5]);
+
+    // Morton code per leaf, striped so neighbouring threads read neighbouring leaves, and a zero
+    // arrival count for each of the n - 1 internal nodes.
+    for (var k = 0u; k < KEYS_PER_THREAD; k += 1u) {
+        let leaf = k * WORKGROUP_SIZE + thread_id;
+
+        if (leaf < n) {
+            let base = leaf * 6u;
+
+            let low = vec3<f32>(leaf_bounds[base], leaf_bounds[base + 1u], leaf_bounds[base + 2u]);
+            let high = vec3<f32>(leaf_bounds[base + 3u], leaf_bounds[base + 4u], leaf_bounds[base + 5u]);
+
+            keys[leaf] = bvh_morton_code(low, high, scene_low, scene_high);
+            values[leaf] = leaf;
+        }
+
+        if (leaf + 1u < n) {
+            atomicStore(&counters[leaf], 0u);
+        }
+    }
+
+    if (thread_id == 0u) {
+        for (var w = 0u; w < BVH_REFIT_DEFERRED_ENTRIES; w += 1u) {
+            atomicStore(&refit_deferred[w], 0u);
+        }
+    }
+
+    // Ascending by (code, leaf), which is a stable sort by code: the order the multi-pass radix
+    // sort produces, so both paths build the same tree.
+    sort_bitonic_workgroup(thread_id, n);
+
+    // Emission, as shader_bvh_emit_hierarchy does it. Leaf j lives at node (n-1)+j, internal node
+    // k at node k, and the root is internal node 0. The node words are stored atomically because
+    // the refit below reads them atomically.
+    for (var k = 0u; k < KEYS_PER_THREAD; k += 1u) {
+        let i = k * WORKGROUP_SIZE + thread_id;
+
+        if (i < n) {
+            let leaf_source = values[i];
+
+            sorted_keys[i] = keys[i];
+            sorted_values[i] = leaf_source;
+
+            let leaf_word = settings.node_word_offset + ((n - 1u) + i) * BVH_NODE_STRIDE;
+            let bounds_source = leaf_source * 6u;
+
+            for (var w = 0u; w < 6u; w += 1u) {
+                atomicStore(&nodes[leaf_word + BVH_NODE_BOUNDS + w], bitcast<u32>(leaf_bounds[bounds_source + w]));
+            }
+
+            atomicStore(&nodes[leaf_word + BVH_NODE_CHILD_1], BVH_NULL_NODE);
+            atomicStore(&nodes[leaf_word + BVH_NODE_CHILD_2], leaf_payload[leaf_source]);
+
+            // n leaves, n-1 internal nodes — the last leaf has no internal node to go with it
+            if (i < n - 1u) {
+                let children = bvh_internal_children(n, i);
+
+                let node_word = settings.node_word_offset + i * BVH_NODE_STRIDE;
+
+                atomicStore(&nodes[node_word + BVH_NODE_CHILD_1], children.x);
+                atomicStore(&nodes[node_word + BVH_NODE_CHILD_2], children.y);
+
+                // seeded, as shader_bvh_emit_hierarchy seeds them, so the climb can see a box that
+                // has not reached it
+                for (var w = 0u; w < 6u; w += 1u) {
+                    atomicStore(&nodes[node_word + BVH_NODE_BOUNDS + w], BVH_UNFITTED);
+                }
+
+                parents[children.x] = i;
+                parents[children.y] = i;
+            }
+        }
+    }
+
+    if (thread_id == 0u) {
+        // see shader_bvh_emit_hierarchy: a BLAS has no root word and says so with NO_ROOT_WORD
+        if (settings.root_word_offset != NO_ROOT_WORD) {
+            atomicStore(&nodes[settings.root_word_offset], 0u);
+        }
+
+        // where the climb stops
+        parents[0] = BVH_NULL_NODE;
+    }
+
+    // Every word the climb reads was written above by some other thread of this workgroup: the
+    // parents in workgroup memory, and the counters and child words in storage.
+    workgroupBarrier();
+    storageBarrier();
+
+    // Refit, as shader_bvh_refit does it: one climb per leaf, and the second arrival at a node fits
+    // it. Nothing waits, so which thread climbs which leaf does not matter.
+    for (var k = 0u; k < KEYS_PER_THREAD; k += 1u) {
+        let i = k * WORKGROUP_SIZE + thread_id;
+
+        if (i < n) {
+            bvh_refit_climb(settings.node_word_offset, 0u, 0u, (n - 1u) + i);
+        }
+    }
+
+    // Every store of the climb, visible to the whole workgroup: what the multi-pass build gets from
+    // the dispatch boundary before its repair, one workgroup gets from a barrier.
+    workgroupBarrier();
+    storageBarrier();
+
+    // The repair, as shader_bvh_refit_repair does it, over whatever the climb deferred. A node is
+    // deferred at most once, so there are fewer entries than leaves.
+    let deferred = atomicLoad(&refit_deferred[BVH_REFIT_DEFERRED_COUNT]);
+
+    for (var k = 0u; k < KEYS_PER_THREAD; k += 1u) {
+        let e = k * WORKGROUP_SIZE + thread_id;
+
+        if (e < deferred) {
+            let entry = BVH_REFIT_DEFERRED_ENTRIES + e * BVH_REFIT_DEFERRED_ENTRY_WORDS;
+
+            bvh_refit_repair(
+                atomicLoad(&refit_deferred[entry]),
+                atomicLoad(&refit_deferred[entry + 1u]),
+                atomicLoad(&refit_deferred[entry + 2u])
+            );
+        }
+    }
+}
+`, [
+    BVH_NULL_NODE_DEFINITION,
+    BVH_NODE_LAYOUT_DEFINITION,
+    BVH_REFIT_DEFERRED_DEFINITION,
+    chunk_bvh_morton_code,
+    chunk_sort_bitonic_workgroup,
+    chunk_bvh_internal_children,
+    chunk_bvh_refit_climb,
+    chunk_bvh_refit_repair,
+]);
+
+/**
+ * The whole LBVH build over at most one sort tile of leaves ({@link SORT_TILE_SIZE}), in one
+ * workgroup and one dispatch: Morton codes, a bitonic sort in workgroup memory, Karras emission and
+ * the bottom-up refit. {@link graph_bvh_build_lbvh} records this in place of its 19 dispatches
+ * when the leaves fit, because over that few leaves every one of those dispatches is nearly empty
+ * and the build costs their fixed overhead.
+ *
+ * Its output is the multi-pass build's, word for word. It computes the same Morton code
+ * ({@link chunk_bvh_morton_code}) and sorts into the same order (by code, then leaf index, which
+ * is what the stable radix sort produces). It wires the same children
+ * ({@link chunk_bvh_internal_children}) and fits each node with the same climb
+ * ({@link chunk_bvh_refit_climb}). It publishes the same sorted keys and leaf order.
+ *
+ * Nothing in it waits on another workgroup, because there is no other workgroup. The phases are
+ * fenced by barriers, every per-thread loop is bounded by the tile constants, and the climb is the
+ * multi-pass refit's: counters and node words stay storage atomics, as there, internal bounds are
+ * seeded the way emission seeds them, and what the climb defers is repaired after one more barrier
+ * instead of in a dispatch of its own.
+ *
+ * Workgroup memory is 16,380 bytes: the keys, the values and the parents. That fits the default
+ * 16 KiB `maxComputeWorkgroupStorageSize` with four bytes to spare.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_build_single_workgroup = ComputeShader.from({
+    label: "BVHBuild/SingleWorkgroup",
+    resources,
+    body,
+});

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

@@ -9,13 +9,14 @@ export const BVH_EMIT_WORKGROUP_SIZE: 64;
  * 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.
+ * always writes leaf `(n-1)+i`, and threads below `n-1` additionally wire internal node `i`'s two
+ * children, which {@link chunk_bvh_internal_children} derives from its range and split.
  *
  * 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}.
+ * in-repo CPU oracle, duplicate-code runs and all. Internal-node bounds are fitted by
+ * {@link shader_bvh_refit}; this pass seeds them with {@link BVH_UNFITTED}, which is what lets the
+ * refit see which boxes have not reached it yet.
  *
  * @type {ComputeShader}
  */

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;AAwG1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wCAFU,aAAa,CAMpB;8BA5I2B,+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;AAwG1C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wCAFU,aAAa,CAMpB;8BA7I2B,+BAA+B"}

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

@@ -11,8 +11,8 @@ import {
     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";
+import { BVH_REFIT_DEFERRED_DEFINITION } from "./BVH_REFIT_DEFERRED_DEFINITION.js";
+import { chunk_bvh_internal_children } from "./chunk_bvh_internal_children.js";
 
 export const BVH_EMIT_WORKGROUP_SIZE = 64;
 
@@ -79,24 +79,24 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
 
     // 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 children = bvh_internal_children(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 child_1 = children.x;
+        let child_2 = children.y;
 
         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.
+        // Fitting the box is the refit's business, but the refit has to be able to tell a box it has
+        // not received from one it has: its climbs hand boxes over through relaxed atomics, and a
+        // store need not reach the reader before the dispatch ends. Seeded here, a dispatch earlier,
+        // a word the refit reads is its own store or this seed — never the previous build's box.
+        for (var k = 0u; k < 6u; k += 1u) {
+            nodes[node_word + NODE_BOUNDS + k] = BVH_UNFITTED;
+        }
+
         parents[child_1] = i;
         parents[child_2] = i;
     }
@@ -114,8 +114,8 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
 }
 `, [
     BVH_NULL_NODE_DEFINITION,
-    chunk_bvh_determine_range,
-    chunk_bvh_find_split,
+    BVH_REFIT_DEFERRED_DEFINITION,
+    chunk_bvh_internal_children,
 ]);
 
 /**
@@ -128,13 +128,14 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  * 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.
+ * always writes leaf `(n-1)+i`, and threads below `n-1` additionally wire internal node `i`'s two
+ * children, which {@link chunk_bvh_internal_children} derives from its range and split.
  *
  * 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}.
+ * in-repo CPU oracle, duplicate-code runs and all. Internal-node bounds are fitted by
+ * {@link shader_bvh_refit}; this pass seeds them with {@link BVH_UNFITTED}, which is what lets the
+ * refit see which boxes have not reached it yet.
  *
  * @type {ComputeShader}
  */

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

@@ -2,10 +2,9 @@ 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.
+ * The code itself is {@link chunk_bvh_morton_code}, shared with the one-workgroup build so both
+ * paths sort the same leaves by the same codes. `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.

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

@@ -1 +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;AA6D5C;;;;;;;;;;;;GAYG;AACH,gCAFU,aAAa,CAMpB;8BAlF2B,+BAA+B"}
+{"version":3,"file":"shader_bvh_morton.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_morton.js"],"names":[],"mappings":"AAQA,2CAA4C;AA6C5C;;;;;;;;;;;GAWG;AACH,gCAFU,aAAa,CAMpB;8BAlE2B,+BAA+B"}

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

@@ -1,10 +1,10 @@
 import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { chunk_v3_morton_encode } from "../../shader/chunk/bvh/morton/chunk_v3_morton_encode.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { BVH_BUILD_SETTINGS_STRUCT } from "./BVH_BUILD_SETTINGS_STRUCT.js";
+import { chunk_bvh_morton_code } from "./chunk_bvh_morton_code.js";
 
 export const BVH_MORTON_WORKGROUP_SIZE = 64;
 
@@ -39,41 +39,24 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
     let low = vec3<f32>(leaf_bounds[base], leaf_bounds[base + 1u], leaf_bounds[base + 2u]);
     let high = vec3<f32>(leaf_bounds[base + 3u], leaf_bounds[base + 4u], leaf_bounds[base + 5u]);
 
-    let centroid = (low + high) * 0.5;
-
     let scene_low = vec3<f32>(scene_bounds[0], scene_bounds[1], scene_bounds[2]);
     let scene_high = vec3<f32>(scene_bounds[3], scene_bounds[4], scene_bounds[5]);
 
-    let span = scene_high - scene_low;
-
-    // An axis of zero extent contributes nothing to the code, exactly as it does in
-    // v3_morton_encode_bounded — every centroid quantises to 0 along it rather than to a division
-    // by zero.
-    let scale = select(vec3<f32>(0.0), vec3<f32>(1.0) / span, span != vec3<f32>(0.0));
-
-    // The centroid of a leaf box is inside the union of every leaf box by construction, so the
-    // clamp never binds on well-formed input; it is here so that a rounding error at the extreme,
-    // or a NaN-free degenerate box, cannot produce an out-of-range quantised coordinate.
-    let normalized = clamp((centroid - scene_low) * scale, vec3<f32>(0.0), vec3<f32>(1.0));
-
-    let quantised = vec3<u32>(round(normalized * 1023.0));
-
-    keys[i] = v3_morton_encode(quantised.x, quantised.y, quantised.z);
+    keys[i] = bvh_morton_code(low, high, scene_low, scene_high);
 
     // the sort carries this along as the payload, so after it the leaves are in Morton order
     values[i] = i;
 }
 `, [
-    chunk_v3_morton_encode,
+    chunk_bvh_morton_code,
 ]);
 
 /**
  * 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.
+ * The code itself is {@link chunk_bvh_morton_code}, shared with the one-workgroup build so both
+ * paths sort the same leaves by the same codes. `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.

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

@@ -4,17 +4,17 @@ export const BVH_REFIT_WORKGROUP_SIZE: 64;
  *
  * One thread per leaf climbs the `parents` chain from the node `leaf_nodes` says that leaf occupies,
  * taking an arrival counter at each internal node on the way. Nothing waits: the thread that arrives
- * first at a node simply dies, and the one that arrives second is guaranteed both children are
- * complete, because the only way to arrive is to have finished a child. That is the whole
- * synchronisation, and it assumes atomic-word visibility rather than any scheduling fairness — which
- * is why it sits on the accepted side of the engine's line on cross-workgroup communication.
+ * first at a node simply dies, and the one that arrives second fits it. Arriving second does not
+ * mean the sibling's box has reached it — the counter and the box are different atomic words — so
+ * the climb reads the box against the {@link BVH_UNFITTED} seed emission left there, and defers a
+ * node whose box has not fully arrived to {@link shader_bvh_refit_repair}, the build's next pass.
  *
  * The climb itself is {@link chunk_bvh_refit_climb}, shared with the batched per-frame BLAS refit,
  * which runs the same climb over many trees from one dispatch. This kernel is the build's framing
  * of it: one thread per leaf, settings from immediate data, counters of its own.
  *
- * The counters must be zero when the pass starts; the graph declares them with a clear range so a
- * pool-reused buffer is cleared and a fresh one arrives zeroed already.
+ * The counters and the deferred list's header must be zero when the pass starts; the graph declares
+ * both with a clear range so a pool-reused buffer is cleared and a fresh one arrives zeroed already.
  *
  * Node indices are local to the tree and `settings.node_word_offset` says where node 0 lands, so a
  * tree living inside a shared arena refits through this same kernel.

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

@@ -1 +1 @@
-{"version":3,"file":"shader_bvh_refit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_refit.js"],"names":[],"mappings":"AAQA,0CAA2C;AA8C3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,+BAFU,aAAa,CAMpB;8BA7E2B,+BAA+B"}
+{"version":3,"file":"shader_bvh_refit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_refit.js"],"names":[],"mappings":"AAQA,0CAA2C;AAiD3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,+BAFU,aAAa,CAMpB;8BAhF2B,+BAA+B"}

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

@@ -21,8 +21,11 @@ resources.createGroup()
     .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
     // The same buffer the emission pass wrote as typed nodes, bound flat and atomic here. Every
     // word this pass touches is communicated between workgroups, so every access to it is an
-    // atomic one — the strictest formulation WGSL offers, and the discipline the plan's R1 rests on.
-    .addStorageBuffer("nodes", WebGPUArray.from(atomic_u32), true);
+    // atomic one.
+    .addStorageBuffer("nodes", WebGPUArray.from(atomic_u32), true)
+    // the nodes whose children had not all reached their second arrival, for the repair; header zero
+    // at the start of every build
+    .addStorageBuffer("refit_deferred", WebGPUArray.from(atomic_u32), true);
 
 const body = CodeChunk.from(
     //language=WGSL
@@ -57,17 +60,17 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  *
  * One thread per leaf climbs the `parents` chain from the node `leaf_nodes` says that leaf occupies,
  * taking an arrival counter at each internal node on the way. Nothing waits: the thread that arrives
- * first at a node simply dies, and the one that arrives second is guaranteed both children are
- * complete, because the only way to arrive is to have finished a child. That is the whole
- * synchronisation, and it assumes atomic-word visibility rather than any scheduling fairness — which
- * is why it sits on the accepted side of the engine's line on cross-workgroup communication.
+ * first at a node simply dies, and the one that arrives second fits it. Arriving second does not
+ * mean the sibling's box has reached it — the counter and the box are different atomic words — so
+ * the climb reads the box against the {@link BVH_UNFITTED} seed emission left there, and defers a
+ * node whose box has not fully arrived to {@link shader_bvh_refit_repair}, the build's next pass.
  *
  * The climb itself is {@link chunk_bvh_refit_climb}, shared with the batched per-frame BLAS refit,
  * which runs the same climb over many trees from one dispatch. This kernel is the build's framing
  * of it: one thread per leaf, settings from immediate data, counters of its own.
  *
- * The counters must be zero when the pass starts; the graph declares them with a clear range so a
- * pool-reused buffer is cleared and a fresh one arrives zeroed already.
+ * The counters and the deferred list's header must be zero when the pass starts; the graph declares
+ * both with a clear range so a pool-reused buffer is cleared and a fresh one arrives zeroed already.
  *
  * Node indices are local to the tree and `settings.node_word_offset` says where node 0 lands, so a
  * tree living inside a shared arena refits through this same kernel.

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

@@ -0,0 +1,24 @@
+export const BVH_REFIT_PREPARE_WORKGROUP_SIZE: 64;
+/**
+ * The first pass of a refit-only update ({@link graph_bvh_refit_lbvh}): one thread per leaf rewrites
+ * the leaf's box from `leaf_bounds` and lays out what {@link shader_bvh_refit}'s climb reads, from the
+ * tree itself.
+ *
+ * - Leaf position `i` is node `(n−1)+i`, as the build lays a tree out; its box is rewritten from
+ *   `leaf_bounds[payload]`, so this serves a tree whose **leaf payload is the leaf's index** into the
+ *   boxes it was built from (the GPU fluid's), and the stored tree is the Morton order.
+ * - `parents` of both children of internal node `i`, read off the node, and the root's
+ *   `BVH_NULL_NODE`: the same array the emission writes, rebuilt from the topology it left.
+ * - `leaf_nodes[i] = (n−1)+i`.
+ * - Internal node `i`'s bound words seeded with {@link BVH_UNFITTED}, as emission seeds a build's.
+ *   The refit fits them from every leaf, and its climb reads a child's box through relaxed atomics
+ *   that need not have carried the fitting store yet; the seed is what such a read returns instead
+ *   of the previous frame's box, so the climb defers the node to {@link shader_bvh_refit_repair}.
+ *
+ * Barrier-free and atomic-free, a pure function per thread.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_refit_prepare: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_bvh_refit_prepare.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_bvh_refit_prepare.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_refit_prepare.js"],"names":[],"mappings":"AAUA,kDAAmD;AAgEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,uCAFU,aAAa,CAMpB;8BAjG2B,+BAA+B"}

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

@@ -0,0 +1,99 @@
+import { BVH_NULL_NODE_DEFINITION } from "../../shader/chunk/bvh/BVH_NULL_NODE_DEFINITION.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { BVH_BUILD_SETTINGS_STRUCT } from "./BVH_BUILD_SETTINGS_STRUCT.js";
+import { BVH_NODE_LAYOUT_DEFINITION } from "./BVH_NODE_LAYOUT_DEFINITION.js";
+import { BVH_REFIT_DEFERRED_DEFINITION } from "./BVH_REFIT_DEFERRED_DEFINITION.js";
+
+export const BVH_REFIT_PREPARE_WORKGROUP_SIZE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+
+// the build's settings, as immediate data; the offsets of parents and leaf nodes are 0, transients of the refit
+resources.setImmediate("settings", BVH_BUILD_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addStorageBuffer("leaf_bounds", WebGPUArray.from(f32), false)
+    // `{root: u32, nodes: array<BVH2_NODE_STRUCT>}` as the build wrote it, flat
+    .addStorageBuffer("nodes", WebGPUArray.from(u32), true)
+    .addStorageBuffer("parents", WebGPUArray.from(u32), true)
+    .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${BVH_REFIT_PREPARE_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;
+    }
+
+    // the leaf the build put at sorted position i, and the box it holds now: its payload is its index
+    let leaf_node = (n - 1u) + i;
+    let leaf_word = settings.node_word_offset + leaf_node * BVH_NODE_STRIDE;
+    let source = nodes[leaf_word + BVH_NODE_CHILD_2] * 6u;
+
+    for (var k = 0u; k < 6u; k += 1u) {
+        nodes[leaf_word + BVH_NODE_BOUNDS + k] = bitcast<u32>(leaf_bounds[source + k]);
+    }
+
+    leaf_nodes[settings.leaf_nodes_offset + i] = leaf_node;
+
+    // the parents the climb follows, from the tree's own children
+    if (i < n - 1u) {
+        let node_word = settings.node_word_offset + i * BVH_NODE_STRIDE;
+
+        parents[settings.parents_offset + nodes[node_word + BVH_NODE_CHILD_1]] = i;
+        parents[settings.parents_offset + nodes[node_word + BVH_NODE_CHILD_2]] = i;
+
+        // Internal node i's box is the previous frame's until the climb fits it, and the climb's
+        // read of it may come before the fitting store lands. Seeded here, a dispatch earlier, as
+        // emission seeds a build's, that read returns the store or this seed: a box the climb can
+        // see has not arrived, never the previous frame's.
+        for (var k = 0u; k < 6u; k += 1u) {
+            nodes[node_word + BVH_NODE_BOUNDS + k] = BVH_UNFITTED;
+        }
+    }
+
+    if (i == 0u) {
+        // node 0 is the root, nobody's child: where the climb stops
+        parents[settings.parents_offset] = BVH_NULL_NODE;
+    }
+}
+`, [
+    BVH_NULL_NODE_DEFINITION,
+    BVH_NODE_LAYOUT_DEFINITION,
+    BVH_REFIT_DEFERRED_DEFINITION,
+]);
+
+/**
+ * The first pass of a refit-only update ({@link graph_bvh_refit_lbvh}): one thread per leaf rewrites
+ * the leaf's box from `leaf_bounds` and lays out what {@link shader_bvh_refit}'s climb reads, from the
+ * tree itself.
+ *
+ * - Leaf position `i` is node `(n−1)+i`, as the build lays a tree out; its box is rewritten from
+ *   `leaf_bounds[payload]`, so this serves a tree whose **leaf payload is the leaf's index** into the
+ *   boxes it was built from (the GPU fluid's), and the stored tree is the Morton order.
+ * - `parents` of both children of internal node `i`, read off the node, and the root's
+ *   `BVH_NULL_NODE`: the same array the emission writes, rebuilt from the topology it left.
+ * - `leaf_nodes[i] = (n−1)+i`.
+ * - Internal node `i`'s bound words seeded with {@link BVH_UNFITTED}, as emission seeds a build's.
+ *   The refit fits them from every leaf, and its climb reads a child's box through relaxed atomics
+ *   that need not have carried the fitting store yet; the seed is what such a read returns instead
+ *   of the previous frame's box, so the climb defers the node to {@link shader_bvh_refit_repair}.
+ *
+ * Barrier-free and atomic-free, a pure function per thread.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_refit_prepare = ComputeShader.from({
+    label: "BVHBuild/RefitPrepare",
+    resources,
+    body,
+});

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

@@ -0,0 +1,17 @@
+/**
+ * The refit's repair: one thread per node the climb ({@link chunk_bvh_refit_climb}) deferred,
+ * growing it and every node above it by the union of its children ({@link chunk_bvh_refit_repair}).
+ *
+ * Dispatched indirectly from the deferred list itself: its first three words are the command the
+ * climb wrote as it deferred, folded, so this flattens with {@link chunk_folded_workgroup_index}
+ * rather than asking for `num_workgroups` (see `renderer/gpu_primitive/indirect/NOTES.md`). On a
+ * refit where every box arrived in time the command is empty and nothing runs.
+ *
+ * The list's entries carry their tree's node and parents offsets, so the same dispatch serves a
+ * build's one tree and a batch of trees in an arena.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_refit_repair: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_bvh_refit_repair.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_bvh_refit_repair.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_refit_repair.js"],"names":[],"mappings":"AA4CA;;;;;;;;;;;;;GAaG;AACH,sCAFU,aAAa,CAMpB;8BA5D2B,+BAA+B"}