@woosh/meep-engine 3.46.0 → 3.49.0

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

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;GAcG;AACH,mCAFU,SAAS,CAkChB;0BAlDuB,oCAAoC"}

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

@@ -12,14 +12,16 @@ import { chunk_bvh_delta } from "./chunk_bvh_delta.js";
  * 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.
  *
+ * Reads the sorted codes through {@link chunk_bvh_delta}, so from the module-scope array `keys`.
+ *
  * @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 {
+fn bvh_find_split(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));
+    let common_prefix = bvh_delta(n, first, i32(last));
 
     // Binary search for the highest index that still shares more than common_prefix bits with
     // the code at 'first'.
@@ -32,7 +34,7 @@ fn bvh_find_split(codes: ptr<storage, array<u32>>, n: u32, first: u32, last: u32
         let candidate = split + step;
 
         if (candidate < last) {
-            if (bvh_delta(codes, n, first, i32(candidate)) > common_prefix) {
+            if (bvh_delta(n, first, i32(candidate)) > common_prefix) {
                 split = candidate;
             }
         }

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

@@ -0,0 +1,21 @@
+/**
+ * The two children of Karras internal node `i` over `n` sorted codes, as node indices in the
+ * builder's layout: internal node `k` at node `k`, leaf `j` at node `(n-1)+j`.
+ *
+ * Its range comes from {@link bvh_determine_range} and its split from {@link bvh_find_split}. The
+ * subrange either side of the split is a leaf when it holds one code, and otherwise the internal
+ * node whose boundary sits at that code index.
+ *
+ * Shared by both builders, {@link shader_bvh_emit_hierarchy} and
+ * {@link shader_bvh_build_single_workgroup}. The two have to wire the same tree, and this is the
+ * part of the wiring that encodes the layout. Each builder does its own stores, because one writes
+ * the node buffer plainly and the other atomically.
+ *
+ * `i` must be an internal node, `i < n - 1`. The sorted codes are the module-scope array `keys`
+ * (see {@link chunk_bvh_delta}).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_internal_children: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bvh_internal_children.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bvh_internal_children.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/chunk_bvh_internal_children.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,0CAFU,SAAS,CAqBhB;0BAzCuB,oCAAoC"}

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

@@ -0,0 +1,42 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_bvh_determine_range } from "./chunk_bvh_determine_range.js";
+import { chunk_bvh_find_split } from "./chunk_bvh_find_split.js";
+
+/**
+ * The two children of Karras internal node `i` over `n` sorted codes, as node indices in the
+ * builder's layout: internal node `k` at node `k`, leaf `j` at node `(n-1)+j`.
+ *
+ * Its range comes from {@link bvh_determine_range} and its split from {@link bvh_find_split}. The
+ * subrange either side of the split is a leaf when it holds one code, and otherwise the internal
+ * node whose boundary sits at that code index.
+ *
+ * Shared by both builders, {@link shader_bvh_emit_hierarchy} and
+ * {@link shader_bvh_build_single_workgroup}. The two have to wire the same tree, and this is the
+ * part of the wiring that encodes the layout. Each builder does its own stores, because one writes
+ * the node buffer plainly and the other atomically.
+ *
+ * `i` must be an internal node, `i < n - 1`. The sorted codes are the module-scope array `keys`
+ * (see {@link chunk_bvh_delta}).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_internal_children = CodeChunk.from(
+    //language=WGSL
+    `
+fn bvh_internal_children(n: u32, i: u32) -> vec2<u32> {
+    let range = bvh_determine_range(n, i);
+
+    let first = range.x;
+    let last = range.y;
+
+    let split = bvh_find_split(n, first, last);
+
+    let child_1 = select(split, (n - 1u) + split, split == first);
+    let child_2 = select(split + 1u, (n - 1u) + split + 1u, split + 1u == last);
+
+    return vec2<u32>(child_1, child_2);
+}
+`, [
+    chunk_bvh_determine_range,
+    chunk_bvh_find_split,
+]);

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

@@ -0,0 +1,19 @@
+/**
+ * The Morton code a leaf box sorts by in the GPU LBVH build: its centroid, quantised to ten bits per
+ * axis inside the scene bounds and interleaved into a 30-bit code. It matches
+ * `v3_morton_encode_bounded` + `v3_morton_encode_normalized` on the CPU term for term
+ * (`round(1023 * t)`, zero-extent axes scaled by zero).
+ *
+ * One function, called by every builder that sorts leaves by it. The multi-pass build's
+ * {@link shader_bvh_morton} and the one-workgroup {@link shader_bvh_build_single_workgroup} must
+ * produce the same code for the same leaf, bit for bit, because the tree is a function of the
+ * sorted codes and the two paths have to build the same tree.
+ *
+ * A pure function of its arguments. That is what lets the emulator tier run it against the CPU
+ * encoder directly.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_morton_code: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_bvh_morton_code.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_bvh_morton_code.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/chunk_bvh_morton_code.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,oCAFU,SAAS,CA0BhB;0BA1CuB,oCAAoC"}

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

@@ -0,0 +1,44 @@
+import { chunk_v3_morton_encode } from "../../shader/chunk/bvh/morton/chunk_v3_morton_encode.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * The Morton code a leaf box sorts by in the GPU LBVH build: its centroid, quantised to ten bits per
+ * axis inside the scene bounds and interleaved into a 30-bit code. It matches
+ * `v3_morton_encode_bounded` + `v3_morton_encode_normalized` on the CPU term for term
+ * (`round(1023 * t)`, zero-extent axes scaled by zero).
+ *
+ * One function, called by every builder that sorts leaves by it. The multi-pass build's
+ * {@link shader_bvh_morton} and the one-workgroup {@link shader_bvh_build_single_workgroup} must
+ * produce the same code for the same leaf, bit for bit, because the tree is a function of the
+ * sorted codes and the two paths have to build the same tree.
+ *
+ * A pure function of its arguments. That is what lets the emulator tier run it against the CPU
+ * encoder directly.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_bvh_morton_code = CodeChunk.from(
+    //language=WGSL
+    `
+fn bvh_morton_code(low: vec3<f32>, high: vec3<f32>, scene_low: vec3<f32>, scene_high: vec3<f32>) -> u32 {
+    let centroid = (low + high) * 0.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));
+
+    return v3_morton_encode(quantised.x, quantised.y, quantised.z);
+}
+`, [
+    chunk_v3_morton_encode,
+]);

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

@@ -1,20 +1,37 @@
+/**
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ */
+/**
+ * Offer the pipelines {@link graph_bvh_build_lbvh} dispatches — see {@link PipelineEnquiry}.
+ *
+ * @param {PipelineEnquiry} enquiry
+ */
+export function enquire_bvh_build_lbvh_pipelines(enquiry: PipelineEnquiry): void;
 /**
  * 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.
  *
+ * 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.
+ * 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.
+ *
  * 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.
+ * `element_count` must be at least 1. A single leaf needs no special case on either path: there
+ * is nothing to sort, emission skips the internal node and writes leaf 0 at node 0 with
+ * `parents[0] = BVH_NULL_NODE`, and the refit's one climb 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".
@@ -50,4 +67,5 @@ export function graph_bvh_build_lbvh({ graph, leaf_bounds, leaf_payload, scene_b
     keys: number;
     values: number;
 };
+export type PipelineEnquiry = import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
 //# sourceMappingURL=graph_bvh_build_lbvh.d.ts.map

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":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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,CA8KzD"}
+{"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"}

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

@@ -2,29 +2,56 @@ 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 { 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 { 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";
 
+/**
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ */
+
+/**
+ * Offer the pipelines {@link graph_bvh_build_lbvh} dispatches — see {@link PipelineEnquiry}.
+ *
+ * @param {PipelineEnquiry} enquiry
+ */
+export function enquire_bvh_build_lbvh_pipelines(enquiry) {
+    enquiry.compute.push(shader_bvh_build_single_workgroup.pipeline);
+    enquiry.compute.push(shader_bvh_morton.pipeline);
+    enquire_radix_sort_pipelines(enquiry);
+    enquiry.compute.push(shader_bvh_emit_hierarchy.pipeline);
+    enquiry.compute.push(shader_bvh_refit.pipeline);
+}
+
 /**
  * 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.
  *
+ * 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.
+ * 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.
+ *
  * 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.
+ * `element_count` must be at least 1. A single leaf needs no special case on either path: there
+ * is nothing to sort, emission skips the internal node and writes leaf 0 at node 0 with
+ * `parents[0] = BVH_NULL_NODE`, and the refit's one climb 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".
@@ -69,30 +96,19 @@ export function graph_bvh_build_lbvh({
 
     const node_count = 2 * element_count - 1;
 
+    // the tree ends at its last node; where it starts is the caller's business
+    const end_byte = (node_word_offset + node_count * 8) * Uint32Array.BYTES_PER_ELEMENT;
+
     // 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 = {
@@ -103,6 +119,35 @@ export function graph_bvh_build_lbvh({
         leaf_nodes_offset: 0,
     };
 
+    if (element_count <= SORT_TILE_SIZE) {
+        return record_single_workgroup_build({
+            graph,
+            leaf_bounds,
+            leaf_payload,
+            scene_bounds,
+            nodes,
+            settings,
+            end_byte,
+            KEY_DESCRIPTOR,
+            // the shader zeroes its own counters, so a pooled buffer needs no clear
+            COUNTERS_DESCRIPTOR: BufferResourceDescriptor.from(counters_size, GPUBufferUsage.STORAGE),
+        });
+    }
+
+    const PARENTS_DESCRIPTOR = BufferResourceDescriptor.from(
+        round_up(node_count * Uint32Array.BYTES_PER_ELEMENT, 1024),
+        GPUBufferUsage.STORAGE
+    );
+
+    // 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
+    );
+
     /**
      * @param pass_data
      * @param {FramePassResources} resources
@@ -134,9 +179,6 @@ export function graph_bvh_build_lbvh({
 
         const output = resources.get(pass_data.nodes);
 
-        // the tree ends at its last node; where it starts is the caller's business
-        const end_byte = (node_word_offset + (2 * element_count - 1) * 8) * Uint32Array.BYTES_PER_ELEMENT;
-
         assert.greaterThanOrEqual(output.size, end_byte, 'node buffer underflow');
 
         shader_bvh_emit_hierarchy.dispatchThreads({
@@ -216,3 +258,77 @@ export function graph_bvh_build_lbvh({
         values: sorted.values,
     };
 }
+
+/**
+ * The build over at most one sort tile of leaves, as one pass: {@link shader_bvh_build_single_workgroup}
+ * dispatched as a single workgroup. It publishes what the multi-pass build publishes: the tree, and
+ * the sorted keys and leaf order in transients of the same size.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.leaf_bounds
+ * @param {number} options.leaf_payload
+ * @param {number} options.scene_bounds
+ * @param {number} options.nodes
+ * @param {Object} options.settings {@link BVH_BUILD_SETTINGS_STRUCT}
+ * @param {number} options.end_byte where the tree ends in `nodes`
+ * @param {BufferResourceDescriptor} options.KEY_DESCRIPTOR
+ * @param {BufferResourceDescriptor} options.COUNTERS_DESCRIPTOR
+ * @returns {{nodes: number, keys: number, values: number}}
+ */
+function record_single_workgroup_build({
+                                           graph,
+                                           leaf_bounds,
+                                           leaf_payload,
+                                           scene_bounds,
+                                           nodes,
+                                           settings,
+                                           end_byte,
+                                           KEY_DESCRIPTOR,
+                                           COUNTERS_DESCRIPTOR,
+                                       }) {
+
+    /**
+     * @param pass_data
+     * @param {FramePassResources} resources
+     * @param {GraphicsExecutionContext} context
+     */
+    function execute(pass_data, resources, context) {
+        const output = resources.get(pass_data.nodes);
+
+        assert.greaterThanOrEqual(output.size, end_byte, 'node buffer underflow');
+
+        shader_bvh_build_single_workgroup.dispatch({
+            encoder: context.encoder,
+            // one workgroup holds the whole build, so nothing in it waits on another
+            group_count_x: 1,
+            bindings: {
+                settings,
+                leaf_bounds: resources.get(pass_data.leaf_bounds),
+                leaf_payload: resources.get(pass_data.leaf_payload),
+                scene_bounds: resources.get(pass_data.scene_bounds),
+                sorted_keys: resources.get(pass_data.keys),
+                sorted_values: resources.get(pass_data.values),
+                nodes: output,
+                counters: resources.get(pass_data.counters),
+            }
+        });
+    }
+
+    const data = {};
+    const pass = graph.add("bvh build/single workgroup", data, execute);
+
+    data.leaf_bounds = pass.read(leaf_bounds);
+    data.leaf_payload = pass.read(leaf_payload);
+    data.scene_bounds = pass.read(scene_bounds);
+    data.nodes = pass.write(nodes);
+    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);
+
+    return {
+        nodes: data.nodes,
+        keys: data.keys,
+        values: data.values,
+    };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ *
+ * 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;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_bvh_build_single_workgroup.d.ts.map

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

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

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

@@ -0,0 +1,179 @@
+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 { 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";
+
+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);
+
+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);
+        }
+    }
+
+    // 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);
+
+                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);
+        }
+    }
+}
+`, [
+    BVH_NULL_NODE_DEFINITION,
+    BVH_NODE_LAYOUT_DEFINITION,
+    chunk_bvh_morton_code,
+    chunk_sort_bitonic_workgroup,
+    chunk_bvh_internal_children,
+    chunk_bvh_refit_climb,
+]);
+
+/**
+ * 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.
+ *
+ * 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,
+});