@woosh/meep-engine 3.3.0 → 3.4.0

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

@@ -0,0 +1,83 @@
+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";
+
+export const BVH_MORTON_WORKGROUP_SIZE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addUniform("settings", BVH_BUILD_SETTINGS_STRUCT)
+    // six floats per leaf: [min.xyz, max.xyz]
+    .addStorageBuffer("leaf_bounds", WebGPUArray.from(f32), false)
+    // the same six floats over the whole set, produced by the extraction pass
+    .addStorageBuffer("scene_bounds", WebGPUArray.from(f32), false)
+    .addStorageBuffer("keys", WebGPUArray.from(u32), true)
+    .addStorageBuffer("values", WebGPUArray.from(u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${BVH_MORTON_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let i = gid.x;
+
+    if (i >= settings.element_count) {
+        return;
+    }
+
+    let base = i * 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]);
+
+    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);
+
+    // the sort carries this along as the payload, so after it the leaves are in Morton order
+    values[i] = i;
+}
+`, [
+    chunk_v3_morton_encode,
+]);
+
+/**
+ * Morton code per leaf — pass 1 of {@link graph_bvh_build_lbvh}.
+ *
+ * The leaf's centroid is quantised to ten bits per axis inside the scene bounds and interleaved
+ * into a 30-bit code, matching `v3_morton_encode_bounded` + `v3_morton_encode_normalized` on the
+ * CPU term for term (`round(1023 * t)`, zero-extent axes scaled by zero). `values[i] = i` seeds the
+ * permutation the sort then carries.
+ *
+ * Pure per-invocation: no barriers, no atomics, no subgroups — which is what lets the emulator tier
+ * run it point-wise against the CPU encoder.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_morton = ComputeShader.from({
+    label: "BVHBuild/Morton",
+    resources,
+    body,
+    group_size: [BVH_MORTON_WORKGROUP_SIZE, 1, 1],
+});

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

@@ -0,0 +1,24 @@
+export const BVH_REFIT_WORKGROUP_SIZE: 64;
+/**
+ * Bottom-up AABB refit — pass 4 of {@link graph_bvh_build_lbvh}, and the last thing a build does.
+ *
+ * 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.
+ *
+ * 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 same pass serves refit-only updates (topology frozen, leaf bounds rewritten) — which is what
+ * per-frame skinned BLAS needs — so it exists as a standalone dispatch rather than fused into
+ * emission. Node indices are local to the tree and `settings.node_word_offset` says where node 0
+ * lands, so a BLAS living inside the shared geometry arena refits through this same kernel.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_refit: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_bvh_refit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_bvh_refit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/shader_bvh_refit.js"],"names":[],"mappings":"AAcA,0CAA2C;AAqG3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,+BAFU,aAAa,CAOpB;8BAxI2B,+BAA+B"}

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

@@ -0,0 +1,141 @@
+import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { BVH_NULL_NODE_DEFINITION } from "../../shader/chunk/bvh/BVH_NULL_NODE_DEFINITION.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    BVH_NODE_BOUNDS_WORD,
+    BVH_NODE_CHILD_1_WORD,
+    BVH_NODE_CHILD_2_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "./BVH_BUFFER_LAYOUT.js";
+import { BVH_BUILD_SETTINGS_STRUCT } from "./BVH_BUILD_SETTINGS_STRUCT.js";
+
+export const BVH_REFIT_WORKGROUP_SIZE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addUniform("settings", BVH_BUILD_SETTINGS_STRUCT)
+    .addStorageBuffer("parents", WebGPUArray.from(u32), false)
+    // node index of each leaf ordinal; the only thing this pass knows about the tree's layout
+    .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
+    // one arrival counter per internal node; must be zero at the start of every build
+    .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);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const NODE_STRIDE = ${BVH_NODE_STRIDE_WORDS}u;
+const NODE_BOUNDS = ${BVH_NODE_BOUNDS_WORD}u;
+const NODE_CHILD_1 = ${BVH_NODE_CHILD_1_WORD}u;
+const NODE_CHILD_2 = ${BVH_NODE_CHILD_2_WORD}u;
+
+fn bvh_node_word(node: u32) -> u32 {
+    return settings.node_word_offset + node * NODE_STRIDE;
+}
+
+fn bvh_parent(node: u32) -> u32 {
+    return parents[settings.parents_offset + node];
+}
+
+fn bvh_read_bounds_low(node_word: u32) -> vec3<f32> {
+    return vec3<f32>(
+        bitcast<f32>(atomicLoad(&nodes[node_word + NODE_BOUNDS])),
+        bitcast<f32>(atomicLoad(&nodes[node_word + NODE_BOUNDS + 1u])),
+        bitcast<f32>(atomicLoad(&nodes[node_word + NODE_BOUNDS + 2u])),
+    );
+}
+
+fn bvh_read_bounds_high(node_word: u32) -> vec3<f32> {
+    return vec3<f32>(
+        bitcast<f32>(atomicLoad(&nodes[node_word + NODE_BOUNDS + 3u])),
+        bitcast<f32>(atomicLoad(&nodes[node_word + NODE_BOUNDS + 4u])),
+        bitcast<f32>(atomicLoad(&nodes[node_word + NODE_BOUNDS + 5u])),
+    );
+}
+
+@compute @workgroup_size(${BVH_REFIT_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;
+    }
+
+    // Start above leaf i and climb. Which node that leaf is comes from the tree rather than from a
+    // layout this kernel assumes, so a tree that was built and a tree that was copied refit alike.
+    var node = bvh_parent(leaf_nodes[settings.leaf_nodes_offset + i]);
+
+    loop {
+        if (node == BVH_NULL_NODE) {
+            // climbed past the root
+            break;
+        }
+
+        // An internal node has exactly two children, so exactly two climbs pass through it. The
+        // first arrival exits — its sibling's subtree is still being fitted, and it has nothing to
+        // wait ON: no spin, no assumption about anyone else's forward progress. The second arrival
+        // finds both children written and owns the node from here up.
+        let arrivals = atomicAdd(&counters[node], 1u);
+
+        if (arrivals == 0u) {
+            break;
+        }
+
+        let node_word = bvh_node_word(node);
+
+        let child_1 = atomicLoad(&nodes[node_word + NODE_CHILD_1]);
+        let child_2 = atomicLoad(&nodes[node_word + NODE_CHILD_2]);
+
+        let word_1 = bvh_node_word(child_1);
+        let word_2 = bvh_node_word(child_2);
+
+        let low = min(bvh_read_bounds_low(word_1), bvh_read_bounds_low(word_2));
+        let high = max(bvh_read_bounds_high(word_1), bvh_read_bounds_high(word_2));
+
+        atomicStore(&nodes[node_word + NODE_BOUNDS], bitcast<u32>(low.x));
+        atomicStore(&nodes[node_word + NODE_BOUNDS + 1u], bitcast<u32>(low.y));
+        atomicStore(&nodes[node_word + NODE_BOUNDS + 2u], bitcast<u32>(low.z));
+        atomicStore(&nodes[node_word + NODE_BOUNDS + 3u], bitcast<u32>(high.x));
+        atomicStore(&nodes[node_word + NODE_BOUNDS + 4u], bitcast<u32>(high.y));
+        atomicStore(&nodes[node_word + NODE_BOUNDS + 5u], bitcast<u32>(high.z));
+
+        node = bvh_parent(node);
+    }
+}
+`, [
+    BVH_NULL_NODE_DEFINITION,
+]);
+
+/**
+ * Bottom-up AABB refit — pass 4 of {@link graph_bvh_build_lbvh}, and the last thing a build does.
+ *
+ * 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.
+ *
+ * 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 same pass serves refit-only updates (topology frozen, leaf bounds rewritten) — which is what
+ * per-frame skinned BLAS needs — so it exists as a standalone dispatch rather than fused into
+ * emission. Node indices are local to the tree and `settings.node_word_offset` says where node 0
+ * lands, so a BLAS living inside the shared geometry arena refits through this same kernel.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_refit = ComputeShader.from({
+    label: "BVHBuild/Refit",
+    resources,
+    body,
+    group_size: [BVH_REFIT_WORKGROUP_SIZE, 1, 1],
+});

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

@@ -0,0 +1,31 @@
+/**
+ * On-device verification of the GPU BVH build.
+ *
+ * Builds a tree for each of a set of leaf sets chosen for the shapes that break LBVH builders —
+ * coincident instances, tight clusters that quantise to one Morton code, degenerate zero-volume
+ * boxes, and counts either side of every tile and workgroup boundary — reads the result back, and
+ * checks on the CPU that:
+ *
+ *   - the root word is what the format says it is,
+ *   - every node is reachable exactly once (a shared node is the classic duplicate-key failure),
+ *   - every leaf carries its own payload and every payload appears once,
+ *   - every internal node's box contains both of its children's,
+ *   - the Morton order is an ascending permutation,
+ *   - the topology matches `ebvh_build_hierarchy_radix` node for node, fed the GPU's OWN sorted
+ *     order so the comparison tests emission rather than float rounding in the quantiser,
+ *   - the refit's internal bounds match the CPU's.
+ *
+ * And it reports what the risk register asks to be measured rather than assumed: the depth
+ * histogram against the shared traversal stack, and the SAH cost of the tree.
+ *
+ * Per-pass GPU timings go to the console for the largest case, through the debug-timers path —
+ * the `timer` argument `graph_compute_pass` forwards is silently dropped by
+ * `ComputeShader.dispatch`, so this is the path that actually reports anything.
+ *
+ * One graph and one submission per case: the transients then come and go with each build instead
+ * of all being alive at once, and each case gets a fresh set of timer query slots.
+ *
+ * @param {GraphicsContext} graphics
+ */
+export function verify_gpu_bvh_build(graphics: GraphicsContext): void;
+//# sourceMappingURL=verify_gpu_bvh_build.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify_gpu_bvh_build.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/bvh/verify_gpu_bvh_build.js"],"names":[],"mappings":"AAwQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,sEAKC"}