@woosh/meep-engine 3.11.3 → 3.13.0

package/src/shade/renderer/scene/hierarchy/shader_nodes_update_transform_hierarchy_naive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_nodes_update_transform_hierarchy_naive.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/hierarchy/shader_nodes_update_transform_hierarchy_naive.js"],"names":[],"mappings":"AA0GA,0EAKG;8BAtG2B,+BAA+B"}
+{"version":3,"file":"shader_nodes_update_transform_hierarchy_naive.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/hierarchy/shader_nodes_update_transform_hierarchy_naive.js"],"names":[],"mappings":"AA0GA,0EAIG;8BArG2B,+BAA+B"}

package/src/shade/renderer/scene/hierarchy/shader_nodes_update_transform_hierarchy_naive.js

@@ -1,112 +1,111 @@
-import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
-import { chunk_scene_database_access_rw } from "../chunk_scene_database_access.js";
-import { NODE3D_SCENE_ID } from "../NODE3D_STRUCT.js";
-import {
-    chunk_mat4_compose_transform
-} from "../../shader/chunk/geometry/mat4/chunk_mat4_compose_transform.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-
-/**
- * Maximum parent-chain depth a thread will walk before giving up.
- * Bounds runtime / shader complexity even on pathological data
- * (cycles, very deep skeletons). Same value the CSDLDF variant uses
- * for its fallback path.
- *
- * @type {number}
- */
-const MAX_PARENT_WALK = 64;
-
-const WORKGROUP_SIZE = 64;
-
-/**
- * Brute-force "Northlight-style" propagation pass for scene-graph node
- * transforms. Runs alongside {@link shader_nodes_update_transform_hierarchy}
- * (the CSDLDF lookback variant) as a comparison reference: when the
- * outputs of the two diverge, the bug is somewhere in the clever path.
- *
- * **Per-thread work**
- *
- * One thread per input position. Each thread:
- *  - Reads its own node, composes its local TRS into `acc`.
- *  - Walks `node.parent` repeatedly, composing each ancestor's local
- *    TRS into `acc` from the left, until the chain hits the scene root
- *    (`parent == NODE3D_SCENE_ID`) or `MAX_PARENT_WALK` steps.
- *  - Writes the final `acc` into `node.global` via the per-field
- *    `scene_write_node_global` helper — only the `global` field is
- *    touched, so a transient stale read can't poison `local_T/R/S`.
- *
- * Every thread re-walks the entire parent chain — there's no
- * cross-thread cooperation, no spine flag, no lookback. That makes
- * each thread's work `O(depth)` and the overall pass
- * `O(node_count × depth)`. For the scene depths the prototype targets
- * (≤32) the absolute cost is fine; the point of this implementation
- * isn't speed, it's giving us a known-correct baseline to validate
- * the CSDLDF variant against.
- *
- * @type {ComputeShader}
- */
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addStorageBuffer("input", COLLECTION_U32_STRUCT_READ)
-    .addStorageBuffer("scene_database", WebGPUArray.from(u32), true);
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-const NODE_SCENE: u32 = ${NODE3D_SCENE_ID}u;
-const MAX_PARENT_WALK: u32 = ${MAX_PARENT_WALK}u;
-
-@compute @workgroup_size(${WORKGROUP_SIZE})
-fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
-    let pos = gid.x;
-    if(pos >= input.count){
-        return;
-    }
-
-    let node_id = input.elements[pos];
-
-    let node = scene_read_node_rw(&scene_database, node_id);
-
-    // Capture this node's current \`global\` as last frame's value,
-    // before the new compose overwrites it. The full transforms row
-    // is already loaded; reading the field here is free, and writing
-    // prev_global ahead of the new global means there's never a
-    // window where prev and current disagree about which is which.
-    scene_write_node_prev_global(&scene_database, node_id, node.global);
-
-    var acc = mat4_compose_transform(node.local_translation, node.local_rotation, node.local_scale);
-    var parent_id = node.parent;
-
-    // Walk straight up. Each step reads the parent fresh and prepends
-    // its local matrix to acc. No reliance on previously-written
-    // \`global\` fields anywhere — every thread reconstructs the full
-    // world transform from local TRS data alone, so the order in
-    // which threads finish doesn't matter and there's nothing for a
-    // sibling thread's writes to corrupt mid-flight.
-    for(var step = 0u; step < MAX_PARENT_WALK; step = step + 1u){
-        if(parent_id == NODE_SCENE){
-            break;
-        }
-        let parent = scene_read_node_rw(&scene_database, parent_id);
-        let parent_local = mat4_compose_transform(parent.local_translation, parent.local_rotation, parent.local_scale);
-        acc = parent_local * acc;
-        parent_id = parent.parent;
-    }
-
-    scene_write_node_global(&scene_database, node_id, acc);
-}
-`, [
-        chunk_scene_database_access_rw,
-        chunk_mat4_compose_transform,
-    ]);
-
-export const shader_nodes_update_transform_hierarchy_naive = ComputeShader.from({
-    label: "SceneGraph/UpdateTransformHierarchy/Naive",
-    body,
-    resources,
-    group_size: [WORKGROUP_SIZE, 1, 1],
-});
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { chunk_scene_database_access_rw } from "../chunk_scene_database_access.js";
+import { NODE3D_SCENE_ID } from "../NODE3D_STRUCT.js";
+import {
+    chunk_mat4_compose_transform
+} from "../../shader/chunk/geometry/mat4/chunk_mat4_compose_transform.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+
+/**
+ * Maximum parent-chain depth a thread will walk before giving up.
+ * Bounds runtime / shader complexity even on pathological data
+ * (cycles, very deep skeletons). Same value the CSDLDF variant uses
+ * for its fallback path.
+ *
+ * @type {number}
+ */
+const MAX_PARENT_WALK = 64;
+
+const WORKGROUP_SIZE = 64;
+
+/**
+ * Brute-force "Northlight-style" propagation pass for scene-graph node
+ * transforms. Runs alongside {@link shader_nodes_update_transform_hierarchy}
+ * (the CSDLDF lookback variant) as a comparison reference: when the
+ * outputs of the two diverge, the bug is somewhere in the clever path.
+ *
+ * **Per-thread work**
+ *
+ * One thread per input position. Each thread:
+ *  - Reads its own node, composes its local TRS into `acc`.
+ *  - Walks `node.parent` repeatedly, composing each ancestor's local
+ *    TRS into `acc` from the left, until the chain hits the scene root
+ *    (`parent == NODE3D_SCENE_ID`) or `MAX_PARENT_WALK` steps.
+ *  - Writes the final `acc` into `node.global` via the per-field
+ *    `scene_write_node_global` helper — only the `global` field is
+ *    touched, so a transient stale read can't poison `local_T/R/S`.
+ *
+ * Every thread re-walks the entire parent chain — there's no
+ * cross-thread cooperation, no spine flag, no lookback. That makes
+ * each thread's work `O(depth)` and the overall pass
+ * `O(node_count × depth)`. For the scene depths the prototype targets
+ * (≤32) the absolute cost is fine; the point of this implementation
+ * isn't speed, it's giving us a known-correct baseline to validate
+ * the CSDLDF variant against.
+ *
+ * @type {ComputeShader}
+ */
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addStorageBuffer("input", COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const NODE_SCENE: u32 = ${NODE3D_SCENE_ID}u;
+const MAX_PARENT_WALK: u32 = ${MAX_PARENT_WALK}u;
+
+@compute @workgroup_size(${WORKGROUP_SIZE})
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+    let pos = gid.x;
+    if(pos >= input.count){
+        return;
+    }
+
+    let node_id = input.elements[pos];
+
+    let node = scene_read_node_rw(&scene_database, node_id);
+
+    // Capture this node's current \`global\` as last frame's value,
+    // before the new compose overwrites it. The full transforms row
+    // is already loaded; reading the field here is free, and writing
+    // prev_global ahead of the new global means there's never a
+    // window where prev and current disagree about which is which.
+    scene_write_node_prev_global(&scene_database, node_id, node.global);
+
+    var acc = mat4_compose_transform(node.local_translation, node.local_rotation, node.local_scale);
+    var parent_id = node.parent;
+
+    // Walk straight up. Each step reads the parent fresh and prepends
+    // its local matrix to acc. No reliance on previously-written
+    // \`global\` fields anywhere — every thread reconstructs the full
+    // world transform from local TRS data alone, so the order in
+    // which threads finish doesn't matter and there's nothing for a
+    // sibling thread's writes to corrupt mid-flight.
+    for(var step = 0u; step < MAX_PARENT_WALK; step = step + 1u){
+        if(parent_id == NODE_SCENE){
+            break;
+        }
+        let parent = scene_read_node_rw(&scene_database, parent_id);
+        let parent_local = mat4_compose_transform(parent.local_translation, parent.local_rotation, parent.local_scale);
+        acc = parent_local * acc;
+        parent_id = parent.parent;
+    }
+
+    scene_write_node_global(&scene_database, node_id, acc);
+}
+`, [
+        chunk_scene_database_access_rw,
+        chunk_mat4_compose_transform,
+    ]);
+
+export const shader_nodes_update_transform_hierarchy_naive = ComputeShader.from({
+    label: "SceneGraph/UpdateTransformHierarchy/Naive",
+    body,
+    resources,
+});

package/src/shade/renderer/scene/shader_bvh_extract_instance_leaves.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_bvh_extract_instance_leaves.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/shader_bvh_extract_instance_leaves.js"],"names":[],"mappings":"AAUA,4CAA6C;AA+G7C;;;;;;;;;;;;;;;;;GAiBG;AACH,iDAFU,aAAa,CAOpB;8BA3I2B,4BAA4B"}
+{"version":3,"file":"shader_bvh_extract_instance_leaves.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/shader_bvh_extract_instance_leaves.js"],"names":[],"mappings":"AAUA,4CAA6C;AAkH7C;;;;;;;;;;;;;;;;;GAiBG;AACH,iDAFU,aAAa,CAMpB;8BA7I2B,4BAA4B"}

package/src/shade/renderer/scene/shader_bvh_extract_instance_leaves.js

@@ -1,145 +1,147 @@
-import { WebGPUExtensionType } from "../../descriptor/WebGPUExtensionType.js";
-import { atomic_u32, f32, u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../shader/type/WebGPUArray.js";
-import { chunk_aabb_atomic_f32 } from "../animation/skinning/bounds_refresh/chunk_aabb_atomic_f32.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 "../gpu_primitive/bvh/BVH_BUILD_SETTINGS_STRUCT.js";
-import { chunk_scene_database_access } from "./chunk_scene_database_access.js";
-
-export const BVH_EXTRACT_WORKGROUP_SIZE = 64;
-
-/**
- * Subgroup size is a runtime value of at least 4, so a workgroup splits into at most this many
- * subgroups. The array of per-subgroup partials is sized for the worst case.
- *
- * @type {number}
- */
-const MAX_SUBGROUPS = BVH_EXTRACT_WORKGROUP_SIZE / 4;
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addUniform("settings", BVH_BUILD_SETTINGS_STRUCT)
-    // occupied rows of the scene database's `meshes` table, compacted — dead and reused rows never
-    // reach the build
-    .addStorageBuffer("rows", WebGPUArray.from(u32), false)
-    .addStorageBuffer("scene_database", WebGPUArray.from(u32), false)
-    .addStorageBuffer("leaf_bounds", WebGPUArray.from(f32), true)
-    .addStorageBuffer("leaf_payload", WebGPUArray.from(u32), true)
-    // six words holding plain f32 bit patterns, seeded to +/-inf before this pass runs
-    .addStorageBuffer("scene_bounds", WebGPUArray.from(atomic_u32), true);
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-const WORKGROUP_SIZE = ${BVH_EXTRACT_WORKGROUP_SIZE}u;
-
-// The scatter sentinels in scene_bounds are true +/-inf, written host-side as u32 bit patterns.
-// Here they cannot be: WGSL will not const-fold bitcast<f32>(0x7F800000u), because the result is
-// not representable as a literal. The largest finite f32 is the identity element in practice —
-// no world-space bound comes within many orders of magnitude of it.
-const FLOAT_MAX = 3.4028234e38;
-
-var<workgroup> wg_low: array<vec3<f32>, ${MAX_SUBGROUPS}>;
-var<workgroup> wg_high: array<vec3<f32>, ${MAX_SUBGROUPS}>;
-
-@compute @workgroup_size(WORKGROUP_SIZE, 1, 1)
-fn main(
-    @builtin(global_invocation_id) gid: vec3<u32>,
-    @builtin(local_invocation_index) thread_id: u32,
-    @builtin(subgroup_invocation_id) lane_id: u32,
-    @builtin(subgroup_size) lane_count: u32,
-) {
-    let i = gid.x;
-
-    // Threads past the end contribute the identity element rather than returning: the reduction
-    // below is workgroup-wide and every lane has to reach it.
-    var low = vec3<f32>(FLOAT_MAX);
-    var high = vec3<f32>(-FLOAT_MAX);
-
-    if (i < settings.element_count) {
-        let row = rows[i];
-
-        let mesh = scene_read_mesh(&scene_database, row);
-
-        low = vec3<f32>(mesh.bounding_box[0], mesh.bounding_box[1], mesh.bounding_box[2]);
-        high = vec3<f32>(mesh.bounding_box[3], mesh.bounding_box[4], mesh.bounding_box[5]);
-
-        let destination = i * 6u;
-
-        leaf_bounds[destination] = low.x;
-        leaf_bounds[destination + 1u] = low.y;
-        leaf_bounds[destination + 2u] = low.z;
-        leaf_bounds[destination + 3u] = high.x;
-        leaf_bounds[destination + 4u] = high.y;
-        leaf_bounds[destination + 5u] = high.z;
-
-        // The leaf's payload IS the mesh row — what the traversal hands to scene_read_mesh on a hit.
-        leaf_payload[i] = row;
-    }
-
-    // Subgroups first, workgroup memory only across subgroup boundaries.
-    let subgroup_low = subgroupMin(low);
-    let subgroup_high = subgroupMax(high);
-
-    let subgroup_id = thread_id / lane_count;
-    let subgroup_count = WORKGROUP_SIZE / lane_count;
-
-    if (lane_id == 0u) {
-        wg_low[subgroup_id] = subgroup_low;
-        wg_high[subgroup_id] = subgroup_high;
-    }
-
-    workgroupBarrier();
-
-    // At most MAX_SUBGROUPS entries left; one thread walks them, so nothing here depends on the
-    // subgroup width and no barrier sits under a bound derived from it.
-    if (thread_id == 0u) {
-        var group_low = wg_low[0];
-        var group_high = wg_high[0];
-
-        for (var s = 1u; s < subgroup_count; s += 1u) {
-            group_low = min(group_low, wg_low[s]);
-            group_high = max(group_high, wg_high[s]);
-        }
-
-        aabb_atomic_min_f32(&scene_bounds[0], group_low.x);
-        aabb_atomic_min_f32(&scene_bounds[1], group_low.y);
-        aabb_atomic_min_f32(&scene_bounds[2], group_low.z);
-        aabb_atomic_max_f32(&scene_bounds[3], group_high.x);
-        aabb_atomic_max_f32(&scene_bounds[4], group_high.y);
-        aabb_atomic_max_f32(&scene_bounds[5], group_high.z);
-    }
-}
-`, [
-    chunk_scene_database_access,
-    chunk_aabb_atomic_f32,
-]);
-
-body.addExtension(WebGPUExtensionType.Subgroups);
-
-/**
- * Turn the TLAS's live instance rows into the flat leaf set {@link graph_bvh_build_lbvh} consumes,
- * and reduce their union into the scene-bounds cell the Morton pass quantises against.
- *
- * World AABBs come from the scene database's `meshes` table rather than from the CPU tree's leaves:
- * it is the single source of truth, it is refreshed GPU-side for GPU-authority rows (which the CPU
- * never learns about at all), and reading it removes the build's dependency on CPU-side bounds
- * bookkeeping.
- *
- * This is the only scene-aware pass in the build, which is why it lives here with the scene code
- * rather than in `gpu_primitive/bvh/` — everything downstream of it takes flat boxes and payloads
- * and serves geometry just as well as instances.
- *
- * `scene_bounds` must be seeded with +/-inf before this runs; a pool-cleared buffer is zeroed, and
- * zero is a perfectly good coordinate.
- *
- * @type {ComputeShader}
- */
-export const shader_bvh_extract_instance_leaves = ComputeShader.from({
-    label: "BVHBuild/ExtractInstanceLeaves",
-    resources,
-    body,
-    group_size: [BVH_EXTRACT_WORKGROUP_SIZE, 1, 1],
-});
+import { WebGPUExtensionType } from "../../descriptor/WebGPUExtensionType.js";
+import { atomic_u32, f32, u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { chunk_aabb_atomic_f32 } from "../animation/skinning/bounds_refresh/chunk_aabb_atomic_f32.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 "../gpu_primitive/bvh/BVH_BUILD_SETTINGS_STRUCT.js";
+import { chunk_scene_database_access } from "./chunk_scene_database_access.js";
+
+export const BVH_EXTRACT_WORKGROUP_SIZE = 64;
+
+/**
+ * Subgroup size is a runtime value of at least 4, so a workgroup splits into at most this many
+ * subgroups. The array of per-subgroup partials is sized for the worst case.
+ *
+ * @type {number}
+ */
+const MAX_SUBGROUPS = BVH_EXTRACT_WORKGROUP_SIZE / 4;
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, 20 bytes, read-only: immediate data rather than a uniform buffer
+resources.setImmediate("settings", BVH_BUILD_SETTINGS_STRUCT);
+
+resources.createGroup()
+    // occupied rows of the scene database's `meshes` table, compacted — dead and reused rows never
+    // reach the build
+    .addStorageBuffer("rows", WebGPUArray.from(u32), false)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32), false)
+    .addStorageBuffer("leaf_bounds", WebGPUArray.from(f32), true)
+    .addStorageBuffer("leaf_payload", WebGPUArray.from(u32), true)
+    // six words holding plain f32 bit patterns, seeded to +/-inf before this pass runs
+    .addStorageBuffer("scene_bounds", WebGPUArray.from(atomic_u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WORKGROUP_SIZE = ${BVH_EXTRACT_WORKGROUP_SIZE}u;
+
+// The scatter sentinels in scene_bounds are true +/-inf, written host-side as u32 bit patterns.
+// Here they cannot be: WGSL will not const-fold bitcast<f32>(0x7F800000u), because the result is
+// not representable as a literal. The largest finite f32 is the identity element in practice —
+// no world-space bound comes within many orders of magnitude of it.
+const FLOAT_MAX = 3.4028234e38;
+
+var<workgroup> wg_low: array<vec3<f32>, ${MAX_SUBGROUPS}>;
+var<workgroup> wg_high: array<vec3<f32>, ${MAX_SUBGROUPS}>;
+
+@compute @workgroup_size(WORKGROUP_SIZE, 1, 1)
+fn main(
+    @builtin(global_invocation_id) gid: vec3<u32>,
+    @builtin(local_invocation_index) thread_id: u32,
+    @builtin(subgroup_invocation_id) lane_id: u32,
+    @builtin(subgroup_size) lane_count: u32,
+) {
+    let i = gid.x;
+
+    // Threads past the end contribute the identity element rather than returning: the reduction
+    // below is workgroup-wide and every lane has to reach it.
+    var low = vec3<f32>(FLOAT_MAX);
+    var high = vec3<f32>(-FLOAT_MAX);
+
+    if (i < settings.element_count) {
+        let row = rows[i];
+
+        let mesh = scene_read_mesh(&scene_database, row);
+
+        low = vec3<f32>(mesh.bounding_box[0], mesh.bounding_box[1], mesh.bounding_box[2]);
+        high = vec3<f32>(mesh.bounding_box[3], mesh.bounding_box[4], mesh.bounding_box[5]);
+
+        let destination = i * 6u;
+
+        leaf_bounds[destination] = low.x;
+        leaf_bounds[destination + 1u] = low.y;
+        leaf_bounds[destination + 2u] = low.z;
+        leaf_bounds[destination + 3u] = high.x;
+        leaf_bounds[destination + 4u] = high.y;
+        leaf_bounds[destination + 5u] = high.z;
+
+        // The leaf's payload IS the mesh row — what the traversal hands to scene_read_mesh on a hit.
+        leaf_payload[i] = row;
+    }
+
+    // Subgroups first, workgroup memory only across subgroup boundaries.
+    let subgroup_low = subgroupMin(low);
+    let subgroup_high = subgroupMax(high);
+
+    let subgroup_id = thread_id / lane_count;
+    let subgroup_count = WORKGROUP_SIZE / lane_count;
+
+    if (lane_id == 0u) {
+        wg_low[subgroup_id] = subgroup_low;
+        wg_high[subgroup_id] = subgroup_high;
+    }
+
+    workgroupBarrier();
+
+    // At most MAX_SUBGROUPS entries left; one thread walks them, so nothing here depends on the
+    // subgroup width and no barrier sits under a bound derived from it.
+    if (thread_id == 0u) {
+        var group_low = wg_low[0];
+        var group_high = wg_high[0];
+
+        for (var s = 1u; s < subgroup_count; s += 1u) {
+            group_low = min(group_low, wg_low[s]);
+            group_high = max(group_high, wg_high[s]);
+        }
+
+        aabb_atomic_min_f32(&scene_bounds[0], group_low.x);
+        aabb_atomic_min_f32(&scene_bounds[1], group_low.y);
+        aabb_atomic_min_f32(&scene_bounds[2], group_low.z);
+        aabb_atomic_max_f32(&scene_bounds[3], group_high.x);
+        aabb_atomic_max_f32(&scene_bounds[4], group_high.y);
+        aabb_atomic_max_f32(&scene_bounds[5], group_high.z);
+    }
+}
+`, [
+    chunk_scene_database_access,
+    chunk_aabb_atomic_f32,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * Turn the TLAS's live instance rows into the flat leaf set {@link graph_bvh_build_lbvh} consumes,
+ * and reduce their union into the scene-bounds cell the Morton pass quantises against.
+ *
+ * World AABBs come from the scene database's `meshes` table rather than from the CPU tree's leaves:
+ * it is the single source of truth, it is refreshed GPU-side for GPU-authority rows (which the CPU
+ * never learns about at all), and reading it removes the build's dependency on CPU-side bounds
+ * bookkeeping.
+ *
+ * This is the only scene-aware pass in the build, which is why it lives here with the scene code
+ * rather than in `gpu_primitive/bvh/` — everything downstream of it takes flat boxes and payloads
+ * and serves geometry just as well as instances.
+ *
+ * `scene_bounds` must be seeded with +/-inf before this runs; a pool-cleared buffer is zeroed, and
+ * zero is a perfectly good coordinate.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_bvh_extract_instance_leaves = ComputeShader.from({
+    label: "BVHBuild/ExtractInstanceLeaves",
+    resources,
+    body,
+});

package/src/shade/renderer/shader/ComputeShader.d.ts

@@ -4,7 +4,9 @@ export class ComputeShader {
      * @param {string} [label]
      * @param {ShaderResourceSetDescriptor} resources
      * @param {CodeChunk} body
-     * @param {number[]} [group_size] Compute shader's group_size attribute, defaults to `[1,1,1]`, can be [x], [x,y] or [x,y,z].
+     * @param {number[]} [group_size] removed — see {@link group_size_x}. Still destructured only so
+     * that a call site left over from before the removal fails loudly instead of having its value
+     * silently ignored.
      * @returns {ComputeShader}
      */
     static from({ label, body, resources, group_size, }?: string): ComputeShader;
@@ -42,18 +44,37 @@ export class ComputeShader {
      *
      * @param {ShadeGPUCommandContext} encoder
      * @param {Object} bindings
-     * @return {GPUComputePassEncoder}
+     * @return {ShadeGPUComputePassEncoder}
      */
-    constructPass({ encoder, bindings }: ShadeGPUCommandContext): GPUComputePassEncoder;
+    constructPass({ encoder, bindings }: ShadeGPUCommandContext): ShadeGPUComputePassEncoder;
     /**
+     * Shortcut to {@link dispatch}, expressed in threads instead of workgroups.
+     *
+     * Each dimension's thread count is divided by the matching `group_size` component, rounding up.
+     *
+     * For example, if we have a workload with 1000 elements, and `@workgroup_size(256,1,1)`. We supply `thread_count_x=1000` and this utility will set `group_count_x` to `Math.ceil(1000 / 256) = 4`.
+     *
+     * NOTE: rounding up means the last group in each dimension is only partially useful, the shader is responsible for discarding threads beyond the requested counts.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {Object} bindings
+     * @param {number} [thread_count_x] number of useful threads to process along X. Must be a non-negative integer. Defaults to `1`.
+     * @param {number} [thread_count_y] number of useful threads to process along Y. Must be a non-negative integer. Defaults to `1`.
+     * @param {number} [thread_count_z] number of useful threads to process along Z. Must be a non-negative integer. Defaults to `1`.
+     * @see dispatch
+     */
+    dispatchThreads({ encoder, bindings, thread_count_x, thread_count_y, thread_count_z, }: ShadeGPUCommandContext): void;
+    /**
+     * @deprecated use {@link dispatchThreads} instead, passing `element_count` as `thread_count_x`.
+     *
      * Shortcut to {@link dispatch}, intended for iteration of linear workloads.
      *
-     * For example, if we have a workload with 1000 elements, and `@group_size(256,1,1)`. We supply `element_count=1000` and this utility will set group_count to `Math.ceil(1000 / 256) = 4`.
+     * For example, if we have a workload with 1000 elements, and `@workgroup_size(256,1,1)`. We supply `element_count=1000` and this utility will set group_count to `Math.ceil(1000 / 256) = 4`.
      *
      * @param {ShadeGPUCommandContext} encoder
      * @param {Object} bindings
      * @param {number} element_count number of useful threads to process. Must be a non-negative integer.
-     * @see dispatch
+     * @see dispatchThreads
      */
     dispatchLinear({ encoder, bindings, element_count }: ShadeGPUCommandContext): void;
     /**

package/src/shade/renderer/shader/ComputeShader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ComputeShader.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ComputeShader.js"],"names":[],"mappings":"AAMA;IA2EI;;;;;;;OAOG;IACH,sDANW,MAAM,GAIJ,aAAa,CAiCzB;IAvDD;;;OAGG;IACH,wBAFW,gBAAgB,EAY1B;IA7DD;;;OAGG;IACH,0CAEC;IASD;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,mCAEC;IA2DD;;;;;OAKG;IACH,oFAuBC;IAED;;;;;;;;;OASG;IACH,mFA4BC;IAED;;;;;;;OAOG;IACH,4GAyCC;IAED;;;;;;OAMG;IACH,+FAsCC;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;;CANtC;0CAjSyC,gEAAgE;iCACzE,uBAAuB"}
+{"version":3,"file":"ComputeShader.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/shader/ComputeShader.js"],"names":[],"mappings":"AAMA;IA8FI;;;;;;;;;OASG;IACH,sDARW,MAAM,GAMJ,aAAa,CAuBzB;IA3DD;;;OAGG;IACH,wBAFW,gBAAgB,EAwB1B;IAhFD;;;OAGG;IACH,0CAEC;IAgBD;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,mCAEC;IA+DD;;;;;OAKG;IACH,yFAuBC;IAED;;;;;;;;;;;;;;;OAeG;IACH,sHA6BC;IAED;;;;;;;;;;;OAWG;IACH,mFAmBC;IAED;;;;;;;OAOG;IACH,4GAyCC;IAED;;;;;;OAMG;IACH,+FAsCC;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;;CANtC;0CApVyC,gEAAgE;iCACzE,uBAAuB"}