@woosh/meep-engine 3.11.3 → 3.12.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;AA+G7C;;;;;;;;;;;;;;;;;GAiBG;AACH,iDAFU,aAAa,CAMpB;8BA1I2B,4BAA4B"}

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

@@ -141,5 +141,4 @@ export const shader_bvh_extract_instance_leaves = ComputeShader.from({
     label: "BVHBuild/ExtractInstanceLeaves",
     resources,
     body,
-    group_size: [BVH_EXTRACT_WORKGROUP_SIZE, 1, 1],
 });

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;
@@ -46,14 +48,33 @@ export class ComputeShader {
      */
     constructPass({ encoder, bindings }: ShadeGPUCommandContext): GPUComputePassEncoder;
     /**
+     * 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":"AASA;IA8FI;;;;;;;;;OASG;IACH,sDARW,MAAM,GAMJ,aAAa,CAuBzB;IA9DD;;;OAGG;IACH,wBAFW,gBAAgB,EA2B1B;IAhFD;;;OAGG;IACH,0CAEC;IAaD;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,mCAEC;IAkED;;;;;OAKG;IACH,oFAuBC;IAED;;;;;;;;;;;;;;;OAeG;IACH,sHA6BC;IAED;;;;;;;;;;;OAWG;IACH,mFAmBC;IAED;;;;;;;OAOG;IACH,4GAyCC;IAED;;;;;;OAMG;IACH,+FAsCC;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;;CANtC;0CAvVyC,gEAAgE;iCACzE,uBAAuB"}