@woosh/meep-engine 3.49.0 → 3.51.0

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

@@ -0,0 +1,80 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { BVH_NULL_NODE_DEFINITION } from "../../shader/chunk/bvh/BVH_NULL_NODE_DEFINITION.js";
+import { chunk_atomic_max_f32_storage } from "../../shader/chunk/atomic/chunk_atomic_max_f32_storage.js";
+import { chunk_atomic_min_f32_storage } from "../../shader/chunk/atomic/chunk_atomic_min_f32_storage.js";
+import { BVH_NODE_LAYOUT_DEFINITION } from "./BVH_NODE_LAYOUT_DEFINITION.js";
+
+/**
+ * Repair of one node the refit climb ({@link chunk_bvh_refit_climb}) deferred: the union of its
+ * children as they stand now, grown into the node and into every node above it.
+ *
+ * Call it where every store of the climb is visible — in a later dispatch, or in the same
+ * workgroup after a storage barrier. Every child has been fitted by then, if only from part of its
+ * own children, so no word reads as {@link BVH_UNFITTED}.
+ *
+ * Why growing is enough, and exact. Whatever the climb fitted holds no more than the true box,
+ * because a word that had not arrived read as the empty box's. The union grown here holds no more
+ * than the true box either, for the same reason. And a leaf's box is missing from a node only if,
+ * somewhere between the two, a node read the child on that path before it arrived — and that node
+ * was deferred, so its repair grows the whole path by a box that holds the leaf. Growth is a min
+ * and a max per word, which commute, so repairs that meet on the way up need no order between them.
+ *
+ * Assumes the module-scope bindings `parents` (`array<u32>`) and `nodes` (`array<atomic<u32>>`),
+ * as the climb does.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_refit_repair = CodeChunk.from(
+    //language=WGSL
+    `
+fn bvh_refit_repair_read_low(bounds_word: u32) -> vec3<f32> {
+    return vec3<f32>(
+        bitcast<f32>(atomicLoad(&nodes[bounds_word])),
+        bitcast<f32>(atomicLoad(&nodes[bounds_word + 1u])),
+        bitcast<f32>(atomicLoad(&nodes[bounds_word + 2u])),
+    );
+}
+
+fn bvh_refit_repair_read_high(bounds_word: u32) -> vec3<f32> {
+    return vec3<f32>(
+        bitcast<f32>(atomicLoad(&nodes[bounds_word + 3u])),
+        bitcast<f32>(atomicLoad(&nodes[bounds_word + 4u])),
+        bitcast<f32>(atomicLoad(&nodes[bounds_word + 5u])),
+    );
+}
+
+fn bvh_refit_repair(node_word_offset: u32, parents_offset: u32, node: u32) {
+    let node_word = node_word_offset + node * BVH_NODE_STRIDE;
+
+    let word_1 = node_word_offset + atomicLoad(&nodes[node_word + BVH_NODE_CHILD_1]) * BVH_NODE_STRIDE + BVH_NODE_BOUNDS;
+    let word_2 = node_word_offset + atomicLoad(&nodes[node_word + BVH_NODE_CHILD_2]) * BVH_NODE_STRIDE + BVH_NODE_BOUNDS;
+
+    let low = min(bvh_refit_repair_read_low(word_1), bvh_refit_repair_read_low(word_2));
+    let high = max(bvh_refit_repair_read_high(word_1), bvh_refit_repair_read_high(word_2));
+
+    var current = node;
+
+    loop {
+        if (current == BVH_NULL_NODE) {
+            // grown past the root
+            break;
+        }
+
+        let bounds_word = node_word_offset + current * BVH_NODE_STRIDE + BVH_NODE_BOUNDS;
+
+        atomic_min_f32_storage(&nodes[bounds_word], low.x);
+        atomic_min_f32_storage(&nodes[bounds_word + 1u], low.y);
+        atomic_min_f32_storage(&nodes[bounds_word + 2u], low.z);
+        atomic_max_f32_storage(&nodes[bounds_word + 3u], high.x);
+        atomic_max_f32_storage(&nodes[bounds_word + 4u], high.y);
+        atomic_max_f32_storage(&nodes[bounds_word + 5u], high.z);
+
+        current = parents[parents_offset + current];
+    }
+}
+`, [
+    BVH_NULL_NODE_DEFINITION,
+    BVH_NODE_LAYOUT_DEFINITION,
+    chunk_atomic_min_f32_storage,
+    chunk_atomic_max_f32_storage,
+]);

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

@@ -15,9 +15,11 @@ export function enquire_bvh_build_lbvh_pipelines(enquiry: PipelineEnquiry): void
  *
  * Two recordings, chosen by `element_count` and nothing else. Up to one sort tile of leaves
  * ({@link SORT_TILE_SIZE}), the whole build is one dispatch of one workgroup,
- * {@link shader_bvh_build_single_workgroup}. Above it the build is 19 dispatches: Morton, the four
- * digit passes of {@link graph_radix_sort}, emission and refit. Over a few leaves each of those 19 is
- * nearly empty and costs its fixed overhead, and a rebuild per spawn or despawn pays it every time.
+ * {@link shader_bvh_build_single_workgroup}. Above it the build is 20 dispatches: Morton, the four
+ * digit passes of {@link graph_radix_sort}, emission, refit, and the refit's repair
+ * ({@link shader_bvh_refit_repair}), which is indirect and empty unless a refit climb read a box
+ * before it arrived. Over a few leaves each of those is nearly empty and costs its fixed overhead,
+ * and a rebuild per spawn or despawn pays it every time.
  * Both write the same tree and the same Morton order, word for word. The single-workgroup path sorts
  * by code and then leaf index, which is the stable radix sort's order.
  *

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

@@ -1 +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":"AAYA;;GAEG;AAEH;;;;GAIG;AACH,0DAFW,eAAe,QAQzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IAhB+B,KAAK;IACT,WAAW,EAA3B,MAAM;IACU,YAAY,EAA5B,MAAM;IACU,YAAY,EAA5B,MAAM;IACU,aAAa,EAA7B,MAAM;IACU,KAAK,EAArB,MAAM;IACW,gBAAgB,GAAjC,MAAM;IAGW,gBAAgB,GAAjC,MAAM;IAEJ;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CA6LzD;8BAtPY,OAAO,6CAA6C,EAAE,eAAe"}
+{"version":3,"file":"graph_bvh_build_lbvh.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/graph_bvh_build_lbvh.js"],"names":[],"mappings":"AAcA;;GAEG;AAEH;;;;GAIG;AACH,0DAFW,eAAe,QASzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IAhB+B,KAAK;IACT,WAAW,EAA3B,MAAM;IACU,YAAY,EAA5B,MAAM;IACU,YAAY,EAA5B,MAAM;IACU,aAAa,EAA7B,MAAM;IACU,KAAK,EAArB,MAAM;IACW,gBAAgB,GAAjC,MAAM;IAGW,gBAAgB,GAAjC,MAAM;IAEJ;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAsOzD;8BAlSY,OAAO,6CAA6C,EAAE,eAAe"}

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

@@ -5,10 +5,12 @@ import { BVH_HEADER_WORDS, bvh_buffer_size } from "./BVH_BUFFER_LAYOUT.js";
 import { SORT_TILE_SIZE } from "../sort/defs.js";
 import { enquire_radix_sort_pipelines, graph_radix_sort } from "../sort/graph_radix_sort.js";
 import { BVH_NO_ROOT_WORD } from "./BVH_BUILD_SETTINGS_STRUCT.js";
+import { BVH_REFIT_DEFERRED_HEADER_BYTES, bvh_refit_deferred_byte_size } from "./BVH_REFIT_DEFERRED_LAYOUT.js";
 import { shader_bvh_build_single_workgroup } from "./shader_bvh_build_single_workgroup.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";
+import { shader_bvh_refit_repair } from "./shader_bvh_refit_repair.js";
 
 /**
  * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
@@ -25,6 +27,7 @@ export function enquire_bvh_build_lbvh_pipelines(enquiry) {
     enquire_radix_sort_pipelines(enquiry);
     enquiry.compute.push(shader_bvh_emit_hierarchy.pipeline);
     enquiry.compute.push(shader_bvh_refit.pipeline);
+    enquiry.compute.push(shader_bvh_refit_repair.pipeline);
 }
 
 /**
@@ -35,9 +38,11 @@ export function enquire_bvh_build_lbvh_pipelines(enquiry) {
  *
  * Two recordings, chosen by `element_count` and nothing else. Up to one sort tile of leaves
  * ({@link SORT_TILE_SIZE}), the whole build is one dispatch of one workgroup,
- * {@link shader_bvh_build_single_workgroup}. Above it the build is 19 dispatches: Morton, the four
- * digit passes of {@link graph_radix_sort}, emission and refit. Over a few leaves each of those 19 is
- * nearly empty and costs its fixed overhead, and a rebuild per spawn or despawn pays it every time.
+ * {@link shader_bvh_build_single_workgroup}. Above it the build is 20 dispatches: Morton, the four
+ * digit passes of {@link graph_radix_sort}, emission, refit, and the refit's repair
+ * ({@link shader_bvh_refit_repair}), which is indirect and empty unless a refit climb read a box
+ * before it arrived. Over a few leaves each of those is nearly empty and costs its fixed overhead,
+ * and a rebuild per spawn or despawn pays it every time.
  * Both write the same tree and the same Morton order, word for word. The single-workgroup path sorts
  * by code and then leaf index, which is the stable radix sort's order.
  *
@@ -109,6 +114,9 @@ export function graph_bvh_build_lbvh({
     // 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;
 
+    // Room for every internal node the refit climb might defer; the header alone for a single leaf.
+    const deferred_size = bvh_refit_deferred_byte_size(element_count - 1);
+
     // 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 = {
@@ -129,8 +137,9 @@ export function graph_bvh_build_lbvh({
             settings,
             end_byte,
             KEY_DESCRIPTOR,
-            // the shader zeroes its own counters, so a pooled buffer needs no clear
+            // the shader zeroes its own counters and deferred header, so a pooled buffer needs no clear
             COUNTERS_DESCRIPTOR: BufferResourceDescriptor.from(counters_size, GPUBufferUsage.STORAGE),
+            DEFERRED_DESCRIPTOR: BufferResourceDescriptor.from(deferred_size, GPUBufferUsage.STORAGE),
         });
     }
 
@@ -148,6 +157,15 @@ export function graph_bvh_build_lbvh({
         0, counters_size
     );
 
+    // The nodes the climb defers, and the repair's dispatch command in its first words. The header
+    // starts every build at zero for the reason the counters do; the entries are written before
+    // anything reads them.
+    const DEFERRED_DESCRIPTOR = BufferResourceDescriptor.from(
+        deferred_size,
+        GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
+        0, BVH_REFIT_DEFERRED_HEADER_BYTES
+    );
+
     /**
      * @param pass_data
      * @param {FramePassResources} resources
@@ -214,6 +232,26 @@ export function graph_bvh_build_lbvh({
                 leaf_nodes: resources.get(pass_data.leaf_nodes),
                 counters: resources.get(pass_data.counters),
                 nodes: resources.get(pass_data.nodes),
+                refit_deferred: resources.get(pass_data.deferred),
+            }
+        });
+    }
+
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_repair(pass_data, resources, context) {
+        const deferred = resources.get(pass_data.deferred);
+
+        shader_bvh_refit_repair.dispatchIndirect({
+            encoder: context.encoder,
+            command: deferred,
+            bindings: {
+                parents: resources.get(pass_data.parents),
+                refit_deferred: deferred,
+                nodes: resources.get(pass_data.nodes),
             }
         });
     }
@@ -250,10 +288,18 @@ export function graph_bvh_build_lbvh({
     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.deferred = refit_pass.create("bvh build/refit deferred", DEFERRED_DESCRIPTOR);
     refit_data.nodes = refit_pass.write(emit_data.nodes);
 
+    const repair_data = {};
+    const repair_pass = graph.add("bvh build/refit repair", repair_data, execute_repair);
+
+    repair_data.parents = repair_pass.read(emit_data.parents);
+    repair_data.deferred = repair_pass.read(refit_data.deferred);
+    repair_data.nodes = repair_pass.write(refit_data.nodes);
+
     return {
-        nodes: refit_data.nodes,
+        nodes: repair_data.nodes,
         keys: sorted.keys,
         values: sorted.values,
     };
@@ -274,6 +320,7 @@ export function graph_bvh_build_lbvh({
  * @param {number} options.end_byte where the tree ends in `nodes`
  * @param {BufferResourceDescriptor} options.KEY_DESCRIPTOR
  * @param {BufferResourceDescriptor} options.COUNTERS_DESCRIPTOR
+ * @param {BufferResourceDescriptor} options.DEFERRED_DESCRIPTOR
  * @returns {{nodes: number, keys: number, values: number}}
  */
 function record_single_workgroup_build({
@@ -286,6 +333,7 @@ function record_single_workgroup_build({
                                            end_byte,
                                            KEY_DESCRIPTOR,
                                            COUNTERS_DESCRIPTOR,
+                                           DEFERRED_DESCRIPTOR,
                                        }) {
 
     /**
@@ -311,6 +359,7 @@ function record_single_workgroup_build({
                 sorted_values: resources.get(pass_data.values),
                 nodes: output,
                 counters: resources.get(pass_data.counters),
+                refit_deferred: resources.get(pass_data.deferred),
             }
         });
     }
@@ -325,6 +374,7 @@ function record_single_workgroup_build({
     data.keys = pass.create("bvh build/morton keys", KEY_DESCRIPTOR);
     data.values = pass.create("bvh build/leaf order", KEY_DESCRIPTOR);
     data.counters = pass.create("bvh build/refit counters", COUNTERS_DESCRIPTOR);
+    data.deferred = pass.create("bvh build/refit deferred", DEFERRED_DESCRIPTOR);
 
     return {
         nodes: data.nodes,

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

@@ -0,0 +1,55 @@
+/**
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ */
+/**
+ * Offer the pipelines {@link graph_bvh_refit_lbvh} dispatches — see {@link PipelineEnquiry}.
+ *
+ * @param {PipelineEnquiry} enquiry
+ */
+export function enquire_bvh_refit_lbvh_pipelines(enquiry: PipelineEnquiry): void;
+/**
+ * Record a refit-only update of a tree {@link graph_bvh_build_lbvh} built: the same leaves, moved.
+ * Three dispatches where a rebuild is one ({@link SORT_TILE_SIZE} leaves or fewer) or twenty:
+ *
+ *     refit prepare    every leaf's box from leaf_bounds, through the stored tree; parents and leaf
+ *                      nodes from its topology; every internal node's box seeded with
+ *                      BVH_UNFITTED (shader_bvh_refit_prepare)
+ *     refit            the build's own bottom-up climb (shader_bvh_refit)
+ *     refit repair     the build's own repair, indirect, empty unless the climb deferred a node
+ *                      (shader_bvh_refit_repair)
+ *
+ * The last two are the build's refit contract (R1 in GPU_BVH_BUILD_PLAN.md). The climb's second
+ * arrival can read a sibling's box before the sibling's stores reach it; the seed makes that read
+ * visible instead of returning the previous frame's box, the climb defers the node, and the repair
+ * grows it once the dispatch boundary has made every store visible. The prepare is the dispatch
+ * ahead of the climb that the seed needs, so the seed costs no dispatch of its own.
+ *
+ * The topology, and so the Morton order, is the one the build left in `nodes`: what a refit keeps
+ * is exactly what makes it cheaper, and what it loses is the tree's fit to where the leaves are
+ * now. A caller rebuilds when that matters, on whatever it observes (a count, a membership, an
+ * age).
+ *
+ * **The contract:** `nodes` holds a tree the build wrote over exactly `element_count` leaves, at
+ * `node_word_offset`, and **each leaf's payload is its index** into `leaf_bounds`, which is what the
+ * prepare pass rewrites a leaf's box through. The root word is not touched.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.leaf_bounds buffer resource ID, `array<f32>`, six floats per leaf
+ * @param {number} options.element_count number of leaves the tree was built over, at least 1
+ * @param {number} options.nodes buffer resource ID of the tree
+ * @param {number} [options.node_word_offset] u32 word the tree's node 0 starts at, as the build was
+ *   given it
+ * @returns {{nodes: number}} the refitted tree
+ */
+export function graph_bvh_refit_lbvh({ graph, leaf_bounds, element_count, nodes, node_word_offset, }: {
+    graph: FrameGraph;
+    leaf_bounds: number;
+    element_count: number;
+    nodes: number;
+    node_word_offset?: number;
+}): {
+    nodes: number;
+};
+export type PipelineEnquiry = import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
+//# sourceMappingURL=graph_bvh_refit_lbvh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_bvh_refit_lbvh.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/graph_bvh_refit_lbvh.js"],"names":[],"mappings":"AAUA;;GAEG;AAEH;;;;GAIG;AACH,0DAFW,eAAe,QAMzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IAR+B,KAAK;IACT,WAAW,EAA3B,MAAM;IACU,aAAa,EAA7B,MAAM;IACU,KAAK,EAArB,MAAM;IACW,gBAAgB,GAAjC,MAAM;IAEJ;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CA0I3B;8BAzLY,OAAO,6CAA6C,EAAE,eAAe"}

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

@@ -0,0 +1,197 @@
+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 } from "./BVH_BUFFER_LAYOUT.js";
+import { BVH_NO_ROOT_WORD } from "./BVH_BUILD_SETTINGS_STRUCT.js";
+import { BVH_REFIT_DEFERRED_HEADER_BYTES, bvh_refit_deferred_byte_size } from "./BVH_REFIT_DEFERRED_LAYOUT.js";
+import { shader_bvh_refit } from "./shader_bvh_refit.js";
+import { shader_bvh_refit_prepare } from "./shader_bvh_refit_prepare.js";
+import { shader_bvh_refit_repair } from "./shader_bvh_refit_repair.js";
+
+/**
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ */
+
+/**
+ * Offer the pipelines {@link graph_bvh_refit_lbvh} dispatches — see {@link PipelineEnquiry}.
+ *
+ * @param {PipelineEnquiry} enquiry
+ */
+export function enquire_bvh_refit_lbvh_pipelines(enquiry) {
+    enquiry.compute.push(shader_bvh_refit_prepare.pipeline);
+    enquiry.compute.push(shader_bvh_refit.pipeline);
+    enquiry.compute.push(shader_bvh_refit_repair.pipeline);
+}
+
+/**
+ * Record a refit-only update of a tree {@link graph_bvh_build_lbvh} built: the same leaves, moved.
+ * Three dispatches where a rebuild is one ({@link SORT_TILE_SIZE} leaves or fewer) or twenty:
+ *
+ *     refit prepare    every leaf's box from leaf_bounds, through the stored tree; parents and leaf
+ *                      nodes from its topology; every internal node's box seeded with
+ *                      BVH_UNFITTED (shader_bvh_refit_prepare)
+ *     refit            the build's own bottom-up climb (shader_bvh_refit)
+ *     refit repair     the build's own repair, indirect, empty unless the climb deferred a node
+ *                      (shader_bvh_refit_repair)
+ *
+ * The last two are the build's refit contract (R1 in GPU_BVH_BUILD_PLAN.md). The climb's second
+ * arrival can read a sibling's box before the sibling's stores reach it; the seed makes that read
+ * visible instead of returning the previous frame's box, the climb defers the node, and the repair
+ * grows it once the dispatch boundary has made every store visible. The prepare is the dispatch
+ * ahead of the climb that the seed needs, so the seed costs no dispatch of its own.
+ *
+ * The topology, and so the Morton order, is the one the build left in `nodes`: what a refit keeps
+ * is exactly what makes it cheaper, and what it loses is the tree's fit to where the leaves are
+ * now. A caller rebuilds when that matters, on whatever it observes (a count, a membership, an
+ * age).
+ *
+ * **The contract:** `nodes` holds a tree the build wrote over exactly `element_count` leaves, at
+ * `node_word_offset`, and **each leaf's payload is its index** into `leaf_bounds`, which is what the
+ * prepare pass rewrites a leaf's box through. The root word is not touched.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.leaf_bounds buffer resource ID, `array<f32>`, six floats per leaf
+ * @param {number} options.element_count number of leaves the tree was built over, at least 1
+ * @param {number} options.nodes buffer resource ID of the tree
+ * @param {number} [options.node_word_offset] u32 word the tree's node 0 starts at, as the build was
+ *   given it
+ * @returns {{nodes: number}} the refitted tree
+ */
+export function graph_bvh_refit_lbvh({
+                                         graph,
+                                         leaf_bounds,
+                                         element_count,
+                                         nodes,
+                                         node_word_offset = BVH_HEADER_WORDS,
+                                     }) {
+    assert.defined(graph, 'graph');
+    assert.isNonNegativeInteger(leaf_bounds, 'leaf_bounds');
+    assert.isNonNegativeInteger(nodes, 'nodes');
+    assert.isNonNegativeInteger(element_count, 'element_count');
+    assert.greaterThanOrEqual(element_count, 1, 'element_count — an empty tree has nothing to refit');
+    assert.isNonNegativeInteger(node_word_offset, 'node_word_offset');
+
+    const node_count = 2 * element_count - 1;
+
+    const settings = {
+        element_count,
+        node_word_offset,
+        root_word_offset: BVH_NO_ROOT_WORD,
+        parents_offset: 0,
+        leaf_nodes_offset: 0,
+    };
+
+    const PARENTS_DESCRIPTOR = BufferResourceDescriptor.from(
+        round_up(node_count * Uint32Array.BYTES_PER_ELEMENT, 1024),
+        GPUBufferUsage.STORAGE
+    );
+
+    const LEAF_NODES_DESCRIPTOR = BufferResourceDescriptor.from(
+        round_up(element_count * Uint32Array.BYTES_PER_ELEMENT, 1024),
+        GPUBufferUsage.STORAGE
+    );
+
+    // zero at the start of every climb, as for the build's own refit; one cell for a tree of one leaf
+    const counters_size = Math.max(1, element_count - 1) * Uint32Array.BYTES_PER_ELEMENT;
+
+    const COUNTERS_DESCRIPTOR = BufferResourceDescriptor.from(
+        counters_size,
+        GPUBufferUsage.STORAGE,
+        0, counters_size
+    );
+
+    // the nodes the climb defers, the repair's command in its first words: the header cleared for
+    // the reason the counters are, room for every internal node
+    const DEFERRED_DESCRIPTOR = BufferResourceDescriptor.from(
+        bvh_refit_deferred_byte_size(element_count - 1),
+        GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
+        0, BVH_REFIT_DEFERRED_HEADER_BYTES
+    );
+
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_prepare(pass_data, resources, context) {
+        shader_bvh_refit_prepare.dispatchThreads({
+            encoder: context.encoder,
+            thread_count_x: element_count,
+            bindings: {
+                settings,
+                leaf_bounds: resources.get(pass_data.leaf_bounds),
+                nodes: resources.get(pass_data.nodes),
+                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) {
+        shader_bvh_refit.dispatchThreads({
+            encoder: context.encoder,
+            thread_count_x: element_count,
+            bindings: {
+                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),
+                refit_deferred: resources.get(pass_data.deferred),
+            }
+        });
+    }
+
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute_repair(pass_data, resources, context) {
+        const deferred = resources.get(pass_data.deferred);
+
+        shader_bvh_refit_repair.dispatchIndirect({
+            encoder: context.encoder,
+            command: deferred,
+            bindings: {
+                parents: resources.get(pass_data.parents),
+                refit_deferred: deferred,
+                nodes: resources.get(pass_data.nodes),
+            }
+        });
+    }
+
+    const prepare_data = {};
+    const prepare_pass = graph.add("bvh refit/prepare", prepare_data, execute_prepare);
+
+    prepare_data.leaf_bounds = prepare_pass.read(leaf_bounds);
+    prepare_data.nodes = prepare_pass.write(nodes);
+    prepare_data.parents = prepare_pass.create("bvh refit/parents", PARENTS_DESCRIPTOR);
+    prepare_data.leaf_nodes = prepare_pass.create("bvh refit/leaf nodes", LEAF_NODES_DESCRIPTOR);
+
+    const refit_data = {};
+    const refit_pass = graph.add("bvh refit/refit", refit_data, execute_refit);
+
+    refit_data.parents = refit_pass.read(prepare_data.parents);
+    refit_data.leaf_nodes = refit_pass.read(prepare_data.leaf_nodes);
+    refit_data.counters = refit_pass.create("bvh refit/counters", COUNTERS_DESCRIPTOR);
+    refit_data.deferred = refit_pass.create("bvh refit/deferred", DEFERRED_DESCRIPTOR);
+    refit_data.nodes = refit_pass.write(prepare_data.nodes);
+
+    const repair_data = {};
+    const repair_pass = graph.add("bvh refit/repair", repair_data, execute_repair);
+
+    repair_data.parents = repair_pass.read(prepare_data.parents);
+    repair_data.deferred = repair_pass.read(refit_data.deferred);
+    repair_data.nodes = repair_pass.write(refit_data.nodes);
+
+    return {
+        nodes: repair_data.nodes,
+    };
+}

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

@@ -13,7 +13,9 @@
  *
  * 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.
+ * 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.

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

@@ -1 +1 @@
-{"version":3,"file":"shader_bvh_build_single_workgroup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_build_single_workgroup.js"],"names":[],"mappings":"AAwJA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,gDAFU,aAAa,CAMpB;8BAhL2B,+BAA+B"}
+{"version":3,"file":"shader_bvh_build_single_workgroup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_build_single_workgroup.js"],"names":[],"mappings":"AAiMA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,gDAFU,aAAa,CAMpB;8BA3N2B,+BAA+B"}

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

@@ -8,9 +8,11 @@ import { chunk_sort_bitonic_workgroup } from "../sort/chunk_sort_bitonic_workgro
 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();
 
@@ -29,7 +31,9 @@ resources.createGroup()
     // `{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);
+    .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
@@ -75,6 +79,12 @@ fn main(@builtin(local_invocation_index) thread_id: u32) {
         }
     }
 
+    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);
@@ -110,6 +120,12 @@ fn main(@builtin(local_invocation_index) thread_id: u32) {
                 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;
             }
@@ -140,14 +156,39 @@ fn main(@builtin(local_invocation_index) thread_id: u32) {
             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,
 ]);
 
 /**
@@ -165,7 +206,9 @@ fn main(@builtin(local_invocation_index) thread_id: u32) {
  *
  * 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.
+ * 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.

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

@@ -14,8 +14,9 @@ export const BVH_EMIT_WORKGROUP_SIZE: 64;
  *
  * 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":"AAeA,yCAA0C;AAgG1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wCAFU,aAAa,CAMpB;8BAnI2B,+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"}