@woosh/meep-engine 3.43.0 → 3.44.0

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js

@@ -1,4 +1,7 @@
 import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import {
+    WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION
+} from "../../indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
 import { atomic_u32, u32, vec4u } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
@@ -32,9 +35,18 @@ const DATA_STRUCT = WebGPUStruct.from({
  */
 export const PREFIX_SCAN_CSDLDF_HEADER_WORDS = DATA_STRUCT.get("elements").offset / u32.size;
 
+/*
+ The input is bound read-only and the sums go to a buffer of their own, as in both references: a tile that does not see
+ its predecessor's flag within MAX_SPIN_COUNT re-reduces the predecessor's elements itself (the fallback), so those
+ elements must still be the inputs while any tile of the dispatch runs. Scanned in place, a predecessor that had already
+ written its sums handed the fallback a mix of inputs and sums, and the tiles after it carried the difference: on an
+ RTX 4090 one scan of 3,100 came back wrong (196,608 elements, tiles 5–12 all off by 33,721,938), and with
+ MAX_SPIN_COUNT at 1, 65 of 500.
+*/
 const resources = new ShaderResourceSetDescriptor();
 resources.createGroup()
-    .addStorageBuffer("scan_in", DATA_STRUCT, true)
+    .addStorageBuffer("scan_in", DATA_STRUCT)
+    .addStorageBuffer("scan_out", DATA_STRUCT, true)
     .addStorageBuffer("spine", WebGPUArray.from(WebGPUArray.from(atomic_u32, 2)), true)
 
 const body = CodeChunk.from(
@@ -93,7 +105,7 @@ fn main(
     @builtin(subgroup_invocation_id) lane_id: u32,
     @builtin(subgroup_size) lane_count: u32,
 ) {
-    
+
     let vec_size = divide_round_up_u32(scan_in.count, 4);
     let work_tiles = divide_round_up_u32(scan_in.count, ${PREFIX_SCAN_CSDLDF_PARTITION_SIZE});
 
@@ -306,7 +318,7 @@ fn main(
         let prev = wg_broadcast + select(0u, wg_partials[subgroup_id - 1u], subgroup_id != 0u); //wg_broadcast is 0 for tile_id 0
         if(tile_id < work_tiles - 1u){
             for(var k = 0u; k < VEC4_SPT; k += 1u){
-                scan_in.elements[i] = t_scan[k] + prev;
+                scan_out.elements[i] = t_scan[k] + prev;
                 i += lane_count;
             }
         }
@@ -314,7 +326,7 @@ fn main(
         if(tile_id == work_tiles - 1u){
             for(var k = 0u; k < VEC4_SPT; k += 1u){
                 if(i < vec_size){
-                    scan_in.elements[i] = t_scan[k] + prev;
+                    scan_out.elements[i] = t_scan[k] + prev;
                 }
                 i += lane_count;
             }
@@ -338,4 +350,34 @@ export const shader_prefix_scan_csdldf = ComputeShader.from({
     label: "Prefix Scan / CSDLDF",
     body,
     resources,
+});
+
+const prepare_resources = new ShaderResourceSetDescriptor();
+prepare_resources.createGroup()
+    .addStorageBuffer("scan_in", DATA_STRUCT)
+    .addStorageBuffer("scan_out", DATA_STRUCT, true)
+    .addStorageBuffer("command", WebGPUArray.u32, true);
+
+/**
+ * One thread ahead of {@link shader_prefix_scan_csdldf}: the scan's dispatch, a workgroup per partition of the input's
+ * count, and the output's count. The output gets its count here rather than from the scan's first tile because an input
+ * of no elements dispatches no tile at all.
+ * @type {ComputeShader}
+ */
+export const shader_prefix_scan_csdldf_prepare = ComputeShader.from({
+    label: "Prefix Scan / CSDLDF prepare",
+    resources: prepare_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(1)
+fn main() {
+    let count = scan_in.count;
+    scan_out.count = count;
+    // the scan reads its tile from workgroup_id.x alone; past one dimension's guaranteed width it is incomplete
+    command[0] = min(divide_round_up_u32(count, ${PREFIX_SCAN_CSDLDF_PARTITION_SIZE}u), ${WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION}u);
+    command[1] = 1u;
+    command[2] = 1u;
+}
+`, [chunk_divide_round_up_u32]),
 });

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/test_prefix_sum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test_prefix_sum.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/gpu_primitive/prefix_sum/v1/test_prefix_sum.js"],"names":[],"mappings":"AA2BA;;;GAGG;AACH,0EA8DC"}
+{"version":3,"file":"test_prefix_sum.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/gpu_primitive/prefix_sum/v1/test_prefix_sum.js"],"names":[],"mappings":"AA4BA;;;GAGG;AACH,0EA+DC"}

package/src/shade/renderer/gpu_primitive/prefix_sum/v1/test_prefix_sum.js

@@ -12,7 +12,8 @@ import { WGSLAttributes } from "../../../shader/type/WGSLAttributes.js";
 import { WGSLStructField } from "../../../shader/type/WGSLStructField.js";
 import { graph_inspect_gpu_buffer } from "../../../buffer/graph_inspect_gpu_buffer.js";
 import { graph_import_typed_buffer } from "../../../shader/graph/graph_import_typed_buffer.js";
-import { graph_prefix_scan_csdldf } from "./graph_prefix_scan_csdldf.js";
+import { graph_create_buffer } from "../../../shader/graph/graph_create_buffer.js";
+import { graph_prefix_scan_csdldf, prefix_scan_csdldf_output_descriptor } from "./graph_prefix_scan_csdldf.js";
 
 function cpu_prefix_sum(input) {
     const output = new Uint32Array(input.length);
@@ -57,7 +58,8 @@ export async function test_prefix_sum(graphics) {
 
     const prefix_sum = graph_prefix_scan_csdldf({
         graph,
-        data,
+        input: data,
+        output: graph_create_buffer(graph, "prefix sum", prefix_scan_csdldf_output_descriptor(input.length)),
         element_max_count: input.length,
     });
 

package/src/shade/renderer/gpu_primitive/sort/defs.d.ts

@@ -63,8 +63,8 @@ export const MAX_SUBGROUPS_PER_WORKGROUP: number;
  * Words of `{count: u32, elements: array<vec4u>}` header that sit in front of the spine's elements.
  *
  * {@link graph_prefix_scan_csdldf} reads its element count from word 0 and its `elements` member is
- * `@align(16)`, so the first count word lives at word 4. The histogram and scatter shaders bind the
- * same buffer flat and have to step over the header by hand.
+ * `@align(16)`, so the first count word lives at word 4. The histogram shader binds the spine flat and
+ * the scatter its scan, laid out the same, and both have to step over the header by hand.
  * @type {number}
  */
 export const SPINE_HEADER_WORDS: number;

package/src/shade/renderer/gpu_primitive/sort/defs.js

@@ -1,79 +1,79 @@
-/**
- * Shared configuration for the key-value radix sort.
- *
- * The sort is LSD reduce-then-scan: four 8-bit digit passes, each of them a per-tile histogram,
- * a spine scan through {@link graph_prefix_scan_csdldf}, and a rank-and-scatter. The numbers below
- * are what the three stages have to agree on, so they live in one place rather than in each
- * shader's template literal.
- */
-
-/**
- * Number of digit bins. 8-bit digits — one `u32` key is covered by {@link RADIX_PASSES} of them.
- * @type {number}
- */
-export const RADIX = 256;
-
-/**
- * `log2(RADIX)` — also the number of binary split rounds the scatter's in-tile sort runs.
- * @type {number}
- */
-export const RADIX_LOG = 8;
-
-/**
- * (key width) / RADIX_LOG. Four passes over a 32-bit key.
- *
- * Even, which is what puts the result back in the caller's buffers rather than in the ping-pong
- * scratch — see {@link graph_radix_sort}.
- * @type {number}
- */
-export const RADIX_PASSES = 4;
-
-/**
- * Threads per workgroup, in both the histogram and the scatter.
- *
- * 256 is `maxComputeInvocationsPerWorkgroup`'s default value, and it is also exactly {@link RADIX},
- * which is what lets the scatter run "one thread per bin" over its local histogram with no strided
- * loop.
- * @type {number}
- */
-export const SORT_WORKGROUP_SIZE = 256;
-
-/**
- * Keys each thread carries through a tile.
- * @type {number}
- */
-export const SORT_KEYS_PER_THREAD = 4;
-
-/**
- * Keys one workgroup processes. Also the granularity of the spine: the spine holds one 256-bin
- * histogram per tile.
- * @type {number}
- */
-export const SORT_TILE_SIZE = SORT_WORKGROUP_SIZE * SORT_KEYS_PER_THREAD;
-
-/**
- * The smallest subgroup size WebGPU permits, and therefore the largest number of subgroups a
- * workgroup can be split into: `SORT_WORKGROUP_SIZE / MIN_SUBGROUP_SIZE`.
- *
- * Subgroup size is a runtime value in [4, 128]; nothing here may bake a width in. What the bound
- * buys is a *compile-time* trip count for the loop that scans the per-subgroup partials — a loop
- * that contains barriers, and whose bound therefore has to be provably uniform. Iterations past
- * the real subgroup count do nothing.
- * @type {number}
- */
-export const MIN_SUBGROUP_SIZE = 4;
-
-/**
- * @type {number}
- */
-export const MAX_SUBGROUPS_PER_WORKGROUP = SORT_WORKGROUP_SIZE / MIN_SUBGROUP_SIZE;
-
-/**
- * Words of `{count: u32, elements: array<vec4u>}` header that sit in front of the spine's elements.
- *
- * {@link graph_prefix_scan_csdldf} reads its element count from word 0 and its `elements` member is
- * `@align(16)`, so the first count word lives at word 4. The histogram and scatter shaders bind the
- * same buffer flat and have to step over the header by hand.
- * @type {number}
- */
-export const SPINE_HEADER_WORDS = 4;
+/**
+ * Shared configuration for the key-value radix sort.
+ *
+ * The sort is LSD reduce-then-scan: four 8-bit digit passes, each of them a per-tile histogram,
+ * a spine scan through {@link graph_prefix_scan_csdldf}, and a rank-and-scatter. The numbers below
+ * are what the three stages have to agree on, so they live in one place rather than in each
+ * shader's template literal.
+ */
+
+/**
+ * Number of digit bins. 8-bit digits — one `u32` key is covered by {@link RADIX_PASSES} of them.
+ * @type {number}
+ */
+export const RADIX = 256;
+
+/**
+ * `log2(RADIX)` — also the number of binary split rounds the scatter's in-tile sort runs.
+ * @type {number}
+ */
+export const RADIX_LOG = 8;
+
+/**
+ * (key width) / RADIX_LOG. Four passes over a 32-bit key.
+ *
+ * Even, which is what puts the result back in the caller's buffers rather than in the ping-pong
+ * scratch — see {@link graph_radix_sort}.
+ * @type {number}
+ */
+export const RADIX_PASSES = 4;
+
+/**
+ * Threads per workgroup, in both the histogram and the scatter.
+ *
+ * 256 is `maxComputeInvocationsPerWorkgroup`'s default value, and it is also exactly {@link RADIX},
+ * which is what lets the scatter run "one thread per bin" over its local histogram with no strided
+ * loop.
+ * @type {number}
+ */
+export const SORT_WORKGROUP_SIZE = 256;
+
+/**
+ * Keys each thread carries through a tile.
+ * @type {number}
+ */
+export const SORT_KEYS_PER_THREAD = 4;
+
+/**
+ * Keys one workgroup processes. Also the granularity of the spine: the spine holds one 256-bin
+ * histogram per tile.
+ * @type {number}
+ */
+export const SORT_TILE_SIZE = SORT_WORKGROUP_SIZE * SORT_KEYS_PER_THREAD;
+
+/**
+ * The smallest subgroup size WebGPU permits, and therefore the largest number of subgroups a
+ * workgroup can be split into: `SORT_WORKGROUP_SIZE / MIN_SUBGROUP_SIZE`.
+ *
+ * Subgroup size is a runtime value in [4, 128]; nothing here may bake a width in. What the bound
+ * buys is a *compile-time* trip count for the loop that scans the per-subgroup partials — a loop
+ * that contains barriers, and whose bound therefore has to be provably uniform. Iterations past
+ * the real subgroup count do nothing.
+ * @type {number}
+ */
+export const MIN_SUBGROUP_SIZE = 4;
+
+/**
+ * @type {number}
+ */
+export const MAX_SUBGROUPS_PER_WORKGROUP = SORT_WORKGROUP_SIZE / MIN_SUBGROUP_SIZE;
+
+/**
+ * Words of `{count: u32, elements: array<vec4u>}` header that sit in front of the spine's elements.
+ *
+ * {@link graph_prefix_scan_csdldf} reads its element count from word 0 and its `elements` member is
+ * `@align(16)`, so the first count word lives at word 4. The histogram shader binds the spine flat and
+ * the scatter its scan, laid out the same, and both have to step over the header by hand.
+ * @type {number}
+ */
+export const SPINE_HEADER_WORDS = 4;

package/src/shade/renderer/gpu_primitive/sort/graph_radix_sort.d.ts

@@ -13,7 +13,7 @@
  *      bin-major;
  *   2. {@link graph_prefix_scan_csdldf}, reused as-is — one running scan over the whole spine
  *      therefore yields the global start of every digit and the per-tile offset within it together.
- *      That scan is inclusive-only and in-place, so the scatter recovers the exclusive value by
+ *      That scan is inclusive-only, so the scatter recovers the exclusive value by
  *      subtracting the tile's own count (which it has, having re-derived the tile histogram to rank
  *      its keys anyway);
  *   3. {@link shader_radix_sort_scatter} — rank within the tile, then scatter.

package/src/shade/renderer/gpu_primitive/sort/graph_radix_sort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_radix_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/graph_radix_sort.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAN+B,KAAK;IACT,IAAI,EAApB,MAAM;IACU,MAAM,EAAtB,MAAM;IACU,aAAa,EAA7B,MAAM;IACJ;IAAC,IAAI,EAAC,MAAM,CAAC;IAAC,MAAM,EAAC,MAAM,CAAA;CAAC,CA4JxC"}
+{"version":3,"file":"graph_radix_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/graph_radix_sort.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAN+B,KAAK;IACT,IAAI,EAApB,MAAM;IACU,MAAM,EAAtB,MAAM;IACU,aAAa,EAA7B,MAAM;IACJ;IAAC,IAAI,EAAC,MAAM,CAAC;IAAC,MAAM,EAAC,MAAM,CAAA;CAAC,CA+JxC"}

package/src/shade/renderer/gpu_primitive/sort/graph_radix_sort.js

@@ -2,7 +2,8 @@ import { assert } from "../../../../core/assert.js";
 import { round_up } from "../../../../core/math/round_up.js";
 import { warn_limited } from "../../../util/warn_limited.js";
 import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
-import { graph_prefix_scan_csdldf } from "../prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { graph_create_buffer } from "../../shader/graph/graph_create_buffer.js";
+import { graph_prefix_scan_csdldf, prefix_scan_csdldf_output_descriptor } from "../prefix_sum/v1/graph_prefix_scan_csdldf.js";
 import { RADIX, RADIX_LOG, RADIX_PASSES, SORT_TILE_SIZE, SPINE_HEADER_WORDS } from "./defs.js";
 import { shader_radix_sort_histogram } from "./shader_radix_sort_histogram.js";
 import { shader_radix_sort_scatter } from "./shader_radix_sort_scatter.js";
@@ -22,7 +23,7 @@ import { shader_radix_sort_scatter } from "./shader_radix_sort_scatter.js";
  *      bin-major;
  *   2. {@link graph_prefix_scan_csdldf}, reused as-is — one running scan over the whole spine
  *      therefore yields the global start of every digit and the per-tile offset within it together.
- *      That scan is inclusive-only and in-place, so the scatter recovers the exclusive value by
+ *      That scan is inclusive-only, so the scatter recovers the exclusive value by
  *      subtracting the tile's own count (which it has, having re-derived the tile histogram to rank
  *      its keys anyway);
  *   3. {@link shader_radix_sort_scatter} — rank within the tile, then scatter.
@@ -71,6 +72,8 @@ export function graph_radix_sort({
         0, spine_size
     );
 
+    const SCANNED_SPINE_DESCRIPTOR = prefix_scan_csdldf_output_descriptor(spine_element_count);
+
     // aligned on a 1k boundary to lower memory fragmentation, as the deleted port did
     const PING_PONG_DESCRIPTOR = BufferResourceDescriptor.from(
         round_up(element_count * Uint32Array.BYTES_PER_ELEMENT, 1024),
@@ -163,7 +166,8 @@ export function graph_radix_sort({
 
         const scanned_spine = graph_prefix_scan_csdldf({
             graph,
-            data: histogram_data.spine,
+            input: histogram_data.spine,
+            output: graph_create_buffer(graph, `radix sort/scanned spine ${pass_index}`, SCANNED_SPINE_DESCRIPTOR),
             element_max_count: spine_element_count,
         });
 

package/src/shade/renderer/particles/GPUParticleSystem.js

@@ -56,7 +56,7 @@ const STORAGE_GROWABLE = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUB
  */
 const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
 
-const DEFAULT_CAPACITY = 524288;
+const DEFAULT_CAPACITY = 131072;
 
 /**
  * What {@link GPUParticleSystem#read_stats} decodes: the counts the GPU keeps between frames, named.

package/src/shade/renderer/particles/coherence/graph_particle_bucket.d.ts

@@ -1,5 +1,5 @@
 /**
- * @typedef {{keys: number, histogram: number, cursor: number, bucket_counts: number, dispatch_args: number}} ParticleBucketScratch
+ * @typedef {{keys: number, histogram: number, scanned: number, cursor: number, bucket_counts: number, dispatch_args: number}} ParticleBucketScratch
  */
 /**
  * Frame-graph wiring for the simulation-order bucketing: turns the frame's freshly compacted alive
@@ -32,8 +32,8 @@
  *
  * None of them asks for a clear. The reset pass covers the histogram (header, padding and the bins
  * up to the whole `vec4` the last one lands in), the cursors and all three dispatch words; `keys`
- * is written by the same indirect dispatch that later reads it, and `bucket_counts` by the same
- * `bucket_count` threads.
+ * is written by the same indirect dispatch that later reads it, `bucket_counts` by the same
+ * `bucket_count` threads, and the scanned bins, header included, by the scan.
  *
  * @param {object} params
  * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
@@ -69,6 +69,7 @@ export function graph_particle_bucket({ graph, emitter_database, pool, alive, co
 export type ParticleBucketScratch = {
     keys: number;
     histogram: number;
+    scanned: number;
     cursor: number;
     bucket_counts: number;
     dispatch_args: number;

package/src/shade/renderer/particles/coherence/graph_particle_bucket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/graph_particle_bucket.js"],"names":[],"mappings":"AAoBA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;IAdqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,gBAAgB,EAA/B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,QAAQ,EAAvB,MAAM;IAIS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IACyB,OAAO,GAAtC,qBAAqB;IACnB;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAC,CA4GvG;oCA9JY;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAC"}
+{"version":3,"file":"graph_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/graph_particle_bucket.js"],"names":[],"mappings":"AAwBA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;IAdqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,gBAAgB,EAA/B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,QAAQ,EAAvB,MAAM;IAIS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IACyB,OAAO,GAAtC,qBAAqB;IACnB;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAC,CA8GvG;oCAhKY;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAC"}