@woosh/meep-engine 3.14.5 → 3.14.6

package/src/shade/renderer/particles/GPUParticleSystem.d.ts

@@ -12,11 +12,18 @@
  * 1. reset counters (snapshot the previous alive count as this frame's simulate input, zero the new
  *    alive count)
  * 2. emit — run SPAWN for each scheduled spawn request (pop dead -> init -> append alive)
- * 3. simulate — one dispatch runs every emitter's UPDATE over the previous alive list, compacting
- *    survivors into the new alive list and freed slots into the dead list
- * 4. build indirect — derive the render draw's instance count from the new alive count
- * 5. sort (optional) — histogram -> csdldf scan -> scatter to a back-to-front index list
- * 6. render — one instanced billboard draw over the sorted list
+ * 3. simulate — one dispatch runs every emitter's UPDATE over the coherence list built last frame,
+ *    compacting survivors into the new alive list and freed slots into the dead list
+ * 4. bucket — regroup the new alive list by VM program, padded to whole workgroups, into the list
+ *    NEXT frame's simulate consumes (`coherence/`)
+ * 5. build indirect — derive next frame's simulate dispatch from the padded list length and this
+ *    frame's render draw instance count from the alive count
+ * 6. sort (optional) — histogram -> csdldf scan -> scatter to a back-to-front index list
+ * 7. render — one instanced billboard draw over the sorted list
+ *
+ * Steps 4 and 6 are two different orderings of the same particles and share nothing: the
+ * simulation order is program-coherent and camera-independent, the render order is back-to-front
+ * and changes with the camera. Separate buffers, separate passes, separate counter slots.
  *
  * The alive lists ping-pong by frame parity, exactly like the ReSTIR reservoirs.
  *
@@ -49,6 +56,13 @@ export class GPUParticleSystem {
     /** CPU shadow of the packed emitter buffer (for in-place transform patching) */
     emitter_cpu: Uint32Array;
     emitters_dirty: boolean;
+    /**
+     * Distinct compiled programs across the emitter set — the number of buckets the coherence
+     * pass sorts into. Known only after {@link buildEmitterData}; until then the emitter count
+     * is a safe upper bound (programs can be shared, never invented).
+     * @type {number|undefined}
+     */
+    program_count: number | undefined;
     /**
      * Register an emitter.
      * @param {object} config see {@link EmitterRegistry#add}
@@ -82,6 +96,16 @@ export class GPUParticleSystem {
         program: Uint32Array;
         constants: Uint32Array;
     };
+    /**
+     * Number of simulation-order buckets — one per distinct compiled program.
+     *
+     * This is the coherence pass's only host-provided number, and it is static topology rather than
+     * per-frame state: it changes when the emitter set changes, not as particles are born and die.
+     * Everything the pass measures per frame stays on the GPU.
+     *
+     * @returns {number}
+     */
+    bucketCount(): number;
     /**
      * Sizes of the persistent buffers, in bytes. Exposed for tests and allocation.
      * @returns {object}

package/src/shade/renderer/particles/GPUParticleSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IACI;;;;OAIG;IACH,sBAJW,MAAM;QAEW,QAAQ,GAAzB,MAAM;OAuBhB;IAjBG,cAAwB;IACxB,iBAAwB;IAExB,0BAAqC;IACrC,kCAA6C;IAE7C,gEAAgE;IAChE,aADW,IAAI,MAAM,EAAE,MAAM,CAAC,CACF;IAE5B,qBAAqB;IACrB,OADW,MAAM,CACH;IAEd,mCAAmC;IACnC,aAAwB;IACxB,gFAAgF;IAChF,yBAA4B;IAC5B,wBAA0B;IAG9B;;;;OAIG;IACH,mBAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;OAKG;IACH,4BAHW,MAAM,QACN,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,WALW,MAAM;oCAES,MAAM,KAAK,OAAO;QAC/B,WAAW,CAiBvB;IAED;;;OAGG;IACH,oBAFa;QAAC,QAAQ,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,WAAW,CAAA;KAAC,CAOjF;IAED;;;OAGG;IACH,eAFa,MAAM,CAalB;IAED;;;OAGG;IACH;cAFoB,WAAW;kBAAY,WAAW;MAUrD;IAED;;;OAGG;IACH;cAFoB,MAAM;eAAS,MAAM;MAKxC;CACJ;gCA7J+B,8BAA8B;uCACvB,qCAAqC"}
+{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH;IACI;;;;OAIG;IACH,sBAJW,MAAM;QAEW,QAAQ,GAAzB,MAAM;OA8BhB;IAxBG,cAAwB;IACxB,iBAAwB;IAExB,0BAAqC;IACrC,kCAA6C;IAE7C,gEAAgE;IAChE,aADW,IAAI,MAAM,EAAE,MAAM,CAAC,CACF;IAE5B,qBAAqB;IACrB,OADW,MAAM,CACH;IAEd,mCAAmC;IACnC,aAAwB;IACxB,gFAAgF;IAChF,yBAA4B;IAC5B,wBAA0B;IAC1B;;;;;OAKG;IACH,eAFU,MAAM,GAAC,SAAS,CAEI;IAGlC;;;;OAIG;IACH,mBAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;OAKG;IACH,4BAHW,MAAM,QACN,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,WALW,MAAM;oCAES,MAAM,KAAK,OAAO;QAC/B,WAAW,CAiBvB;IAED;;;OAGG;IACH,oBAFa;QAAC,QAAQ,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,WAAW,CAAA;KAAC,CAQjF;IAED;;;;;;;;OAQG;IACH,eAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,eAFa,MAAM,CA+BlB;IAED;;;OAGG;IACH;cAFoB,WAAW;kBAAY,WAAW;MAUrD;IAED;;;OAGG;IACH;cAFoB,MAAM;eAAS,MAAM;MAKxC;CACJ;gCA3M+B,8BAA8B;uCACvB,qCAAqC"}

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

@@ -1,5 +1,6 @@
 import { assert } from "../../../core/assert.js";
-import { PARTICLE_RECORD_WORD_COUNT } from "./ParticleConstants.js";
+import { PARTICLE_RECORD_WORD_COUNT, PARTICLE_SIMULATE_WORKGROUP_SIZE } from "./ParticleConstants.js";
+import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
 import { EMITTER_STRIDE, write_emitter_transform } from "./data/PARTICLE_EMITTER_LAYOUT.js";
 import { PARTICLE_COUNTER, PARTICLE_COUNTER_COUNT } from "./data/PARTICLE_COUNTERS.js";
 import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
@@ -19,11 +20,18 @@ import { ParticleSpawnScheduler } from "./runtime/ParticleSpawnScheduler.js";
  * 1. reset counters (snapshot the previous alive count as this frame's simulate input, zero the new
  *    alive count)
  * 2. emit — run SPAWN for each scheduled spawn request (pop dead -> init -> append alive)
- * 3. simulate — one dispatch runs every emitter's UPDATE over the previous alive list, compacting
- *    survivors into the new alive list and freed slots into the dead list
- * 4. build indirect — derive the render draw's instance count from the new alive count
- * 5. sort (optional) — histogram -> csdldf scan -> scatter to a back-to-front index list
- * 6. render — one instanced billboard draw over the sorted list
+ * 3. simulate — one dispatch runs every emitter's UPDATE over the coherence list built last frame,
+ *    compacting survivors into the new alive list and freed slots into the dead list
+ * 4. bucket — regroup the new alive list by VM program, padded to whole workgroups, into the list
+ *    NEXT frame's simulate consumes (`coherence/`)
+ * 5. build indirect — derive next frame's simulate dispatch from the padded list length and this
+ *    frame's render draw instance count from the alive count
+ * 6. sort (optional) — histogram -> csdldf scan -> scatter to a back-to-front index list
+ * 7. render — one instanced billboard draw over the sorted list
+ *
+ * Steps 4 and 6 are two different orderings of the same particles and share nothing: the
+ * simulation order is program-coherent and camera-independent, the render order is back-to-front
+ * and changes with the camera. Separate buffers, separate passes, separate counter slots.
  *
  * The alive lists ping-pong by frame parity, exactly like the ReSTIR reservoirs.
  *
@@ -61,6 +69,13 @@ export class GPUParticleSystem {
         /** CPU shadow of the packed emitter buffer (for in-place transform patching) */
         this.emitter_cpu = undefined;
         this.emitters_dirty = true;
+        /**
+         * Distinct compiled programs across the emitter set — the number of buckets the coherence
+         * pass sorts into. Known only after {@link buildEmitterData}; until then the emitter count
+         * is a safe upper bound (programs can be shared, never invented).
+         * @type {number|undefined}
+         */
+        this.program_count = undefined;
     }
 
     /**
@@ -116,24 +131,56 @@ export class GPUParticleSystem {
     buildEmitterData() {
         const built = this.registry.build();
         this.emitter_cpu = built.emitters;
+        this.program_count = built.program_count;
         this.emitters_dirty = false;
         return built;
     }
 
+    /**
+     * Number of simulation-order buckets — one per distinct compiled program.
+     *
+     * This is the coherence pass's only host-provided number, and it is static topology rather than
+     * per-frame state: it changes when the emitter set changes, not as particles are born and die.
+     * Everything the pass measures per frame stays on the GPU.
+     *
+     * @returns {number}
+     */
+    bucketCount() {
+        return Math.max(1, this.program_count ?? this.registry.count);
+    }
+
     /**
      * Sizes of the persistent buffers, in bytes. Exposed for tests and allocation.
      * @returns {object}
      */
     bufferSizes() {
         const u32 = 4;
+        const buckets = this.bucketCount();
+
         return {
             pool: this.capacity * PARTICLE_RECORD_WORD_COUNT * u32,
             alive_list: this.capacity * u32,
             dead_list: this.capacity * u32,
             counters: PARTICLE_COUNTER_COUNT * u32,
+            // render order (sort/)
             sorted: this.capacity * u32,
             keys: this.capacity * u32,
             emitter_record: EMITTER_STRIDE * u32,
+
+            // simulation order (coherence/) — a separate set of buffers on purpose; sharing any of
+            // them with the render order would couple a camera-driven ordering to a program-driven
+            // one.
+            //
+            // Padding rounds each bucket up to a whole workgroup, so it can add at most
+            // `workgroup - 1` entries per bucket; one whole workgroup per bucket is the bound.
+            sim_list: (this.capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * u32,
+            sim_keys: this.capacity * u32,
+            // `{count, elements}` for the CSDLDF scan; the scan reads whole vec4s, so the bins are
+            // rounded up to a multiple of four.
+            sim_histogram: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(buckets)) * u32,
+            sim_bucket_counts: buckets * u32,
+            sim_cursor: buckets * u32,
+            sim_dispatch_args: 3 * u32,
         };
     }
 
@@ -160,3 +207,11 @@ export class GPUParticleSystem {
         return { read, write: 1 - read };
     }
 }
+
+/**
+ * @param {number} value
+ * @returns {number} `value` rounded up to a multiple of four
+ */
+function round_up_4(value) {
+    return (value + 3) & ~3;
+}

package/src/shade/renderer/particles/ParticleConstants.d.ts

@@ -42,4 +42,35 @@ export const PARTICLE_VM_INSTRUCTION_WORDS: number;
  * @type {number}
  */
 export const PARTICLE_VM_MAX_INSTRUCTIONS: number;
+/**
+ * Threads per workgroup in the simulate dispatch — and therefore the granularity the simulate input
+ * list is bucketed to (see `coherence/`).
+ *
+ * 64 is a multiple of both subgroup widths a WebGPU implementation plausibly reports (32 on NVIDIA
+ * and RDNA wave32, 64 on GCN wave64), so aligning a bucket to it aligns it to a wave without the
+ * shader ever having to query `subgroup_size`. It is also a power of two, which is what lets the
+ * round-up be a mask rather than a divide — the WGSL emulator's `/` is float division, so an
+ * integer-truncating round-up would read differently there than on a device.
+ *
+ * Lives here rather than in the simulate shader because the bucketing passes, the CPU reference and
+ * the indirect-args pass all have to agree on it; `shaders/shader_particle_simulate.js` re-exports
+ * it for callers that think of it as that pass's property.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SIMULATE_WORKGROUP_SIZE: number;
+/**
+ * Slot value carried by a padding entry in the simulate input list.
+ *
+ * Bucketing pads each program's run out to {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} so no wave ever
+ * spans two VM programs; the entries that padding adds name no particle. The simulate shader must
+ * recognise this and return BEFORE the compaction atomics, so a padding lane never appends to the
+ * alive list and never pushes a slot onto the dead (free) list.
+ *
+ * `0xffffffff` is not a reachable slot index: a slot index addresses `pool` at
+ * `slot * PARTICLE_RECORD_WORD_COUNT`, so a pool with 2^32-1 slots would need 512 GiB.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SIM_PAD_SLOT: number;
 //# sourceMappingURL=ParticleConstants.d.ts.map

package/src/shade/renderer/particles/ParticleConstants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;GAIG;AACH,2CAFU,MAAM,CAEgC"}
+{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;GAIG;AACH,2CAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC"}

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

@@ -48,3 +48,36 @@ export const PARTICLE_VM_INSTRUCTION_WORDS = 5;
  * @type {number}
  */
 export const PARTICLE_VM_MAX_INSTRUCTIONS = 256;
+
+/**
+ * Threads per workgroup in the simulate dispatch — and therefore the granularity the simulate input
+ * list is bucketed to (see `coherence/`).
+ *
+ * 64 is a multiple of both subgroup widths a WebGPU implementation plausibly reports (32 on NVIDIA
+ * and RDNA wave32, 64 on GCN wave64), so aligning a bucket to it aligns it to a wave without the
+ * shader ever having to query `subgroup_size`. It is also a power of two, which is what lets the
+ * round-up be a mask rather than a divide — the WGSL emulator's `/` is float division, so an
+ * integer-truncating round-up would read differently there than on a device.
+ *
+ * Lives here rather than in the simulate shader because the bucketing passes, the CPU reference and
+ * the indirect-args pass all have to agree on it; `shaders/shader_particle_simulate.js` re-exports
+ * it for callers that think of it as that pass's property.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SIMULATE_WORKGROUP_SIZE = 64;
+
+/**
+ * Slot value carried by a padding entry in the simulate input list.
+ *
+ * Bucketing pads each program's run out to {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} so no wave ever
+ * spans two VM programs; the entries that padding adds name no particle. The simulate shader must
+ * recognise this and return BEFORE the compaction atomics, so a padding lane never appends to the
+ * alive list and never pushes a slot onto the dead (free) list.
+ *
+ * `0xffffffff` is not a reachable slot index: a slot index addresses `pool` at
+ * `slot * PARTICLE_RECORD_WORD_COUNT`, so a pool with 2^32-1 slots would need 512 GiB.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SIM_PAD_SLOT = 0xffffffff;

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

@@ -0,0 +1,61 @@
+/**
+ * Frame-graph wiring for the simulation-order bucketing: turns the frame's freshly compacted alive
+ * list into the program-coherent, workgroup-padded list NEXT frame's simulate consumes.
+ *
+ * Runs at the end of the frame, after emit and simulate have both finished appending to the alive
+ * list and before the build-indirect pass, which reads the padded length this produces
+ * ({@link PARTICLE_COUNTER.SIM_PADDED}) and turns it into next frame's dispatch args and bound.
+ *
+ * Six passes, the middle one being `graph_prefix_scan_csdldf` reused unchanged — the same scan the
+ * radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan in this
+ * codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so the pass
+ * makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here would be
+ * a second place to get that wrong.
+ *
+ * Nothing on this path reads back to the CPU. The only host-supplied number is `bucket_count`, and
+ * that is static topology — it changes when the emitter set does, never as particles are born and
+ * die. The per-frame quantities (the alive count, the bin sizes, the padded total) are produced and
+ * consumed entirely on the GPU, including the dispatch size of the two per-particle passes, which
+ * the reset pass writes into `sim_dispatch_args` from the GPU's own alive count.
+ *
+ * @param {object} params
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {object} params.gpu persistent buffers owned by the feature (GPUBuffer instances)
+ * @param {GPUBuffer} params.gpu.sim_list the padded, program-coherent index list this produces
+ * @param {GPUBuffer} params.gpu.sim_keys per-alive-entry program id
+ * @param {GPUBuffer} params.gpu.sim_histogram `{count, elements}` bins for the CSDLDF scan
+ * @param {GPUBuffer} params.gpu.sim_bucket_counts raw (unpadded) per-bucket counts
+ * @param {GPUBuffer} params.gpu.sim_cursor per-bucket scatter cursor
+ * @param {GPUBuffer} params.gpu.sim_dispatch_args indirect args for the two per-particle passes
+ * @param {number} params.emitters graph handle of the packed emitter records
+ * @param {number} params.pool graph handle of the particle pool
+ * @param {number} params.alive graph handle of this frame's compacted alive list
+ * @param {number} params.counters graph handle of the atomic counters
+ * @param {number} params.sim_list graph handle of the list this rewrites. Passed in rather than
+ *   imported here because the simulate pass reads it earlier in the same frame: importing the same
+ *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
+ *   and the write end up on separate dependency chains
+ * @param {number} params.bucket_count number of distinct compiled programs
+ * @returns {{counters: number, sim_list: number}} the threaded handles downstream passes must read
+ */
+export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, counters, sim_list, bucket_count }: {
+    graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    gpu: {
+        sim_list: GPUBuffer;
+        sim_keys: GPUBuffer;
+        sim_histogram: GPUBuffer;
+        sim_bucket_counts: GPUBuffer;
+        sim_cursor: GPUBuffer;
+        sim_dispatch_args: GPUBuffer;
+    };
+    emitters: number;
+    pool: number;
+    alive: number;
+    counters: number;
+    sim_list: number;
+    bucket_count: number;
+}): {
+    counters: number;
+    sim_list: number;
+};
+//# sourceMappingURL=graph_particle_bucket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/graph_particle_bucket.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;IAnBqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,GAAG;QACI,QAAQ;QACR,QAAQ;QACR,aAAa;QACb,iBAAiB;QACjB,UAAU;QACV,iBAAiB;;IACxB,QAAQ,EAAvB,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,QAAQ,EAAvB,MAAM;IAIS,YAAY,EAA3B,MAAM;IACJ;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAqGhD"}

package/src/shade/renderer/particles/coherence/graph_particle_bucket.js

@@ -0,0 +1,179 @@
+import { assert } from "../../../../core/assert.js";
+import { graph_compute_indirect_pass } from "../../shader/graph/compute/graph_compute_indirect_pass.js";
+import { graph_compute_pass } from "../../shader/graph/compute/graph_compute_pass.js";
+import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
+import {
+    PREFIX_SCAN_CSDLDF_HEADER_WORDS,
+} from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
+import { graph_prefix_scan_csdldf } from "../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "../ParticleConstants.js";
+import {
+    shader_particle_bucket_fill,
+    shader_particle_bucket_histogram,
+    shader_particle_bucket_pad,
+    shader_particle_bucket_reset,
+    shader_particle_bucket_scatter,
+} from "./shader_particle_bucket.js";
+
+/**
+ * Frame-graph wiring for the simulation-order bucketing: turns the frame's freshly compacted alive
+ * list into the program-coherent, workgroup-padded list NEXT frame's simulate consumes.
+ *
+ * Runs at the end of the frame, after emit and simulate have both finished appending to the alive
+ * list and before the build-indirect pass, which reads the padded length this produces
+ * ({@link PARTICLE_COUNTER.SIM_PADDED}) and turns it into next frame's dispatch args and bound.
+ *
+ * Six passes, the middle one being `graph_prefix_scan_csdldf` reused unchanged — the same scan the
+ * radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan in this
+ * codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so the pass
+ * makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here would be
+ * a second place to get that wrong.
+ *
+ * Nothing on this path reads back to the CPU. The only host-supplied number is `bucket_count`, and
+ * that is static topology — it changes when the emitter set does, never as particles are born and
+ * die. The per-frame quantities (the alive count, the bin sizes, the padded total) are produced and
+ * consumed entirely on the GPU, including the dispatch size of the two per-particle passes, which
+ * the reset pass writes into `sim_dispatch_args` from the GPU's own alive count.
+ *
+ * @param {object} params
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {object} params.gpu persistent buffers owned by the feature (GPUBuffer instances)
+ * @param {GPUBuffer} params.gpu.sim_list the padded, program-coherent index list this produces
+ * @param {GPUBuffer} params.gpu.sim_keys per-alive-entry program id
+ * @param {GPUBuffer} params.gpu.sim_histogram `{count, elements}` bins for the CSDLDF scan
+ * @param {GPUBuffer} params.gpu.sim_bucket_counts raw (unpadded) per-bucket counts
+ * @param {GPUBuffer} params.gpu.sim_cursor per-bucket scatter cursor
+ * @param {GPUBuffer} params.gpu.sim_dispatch_args indirect args for the two per-particle passes
+ * @param {number} params.emitters graph handle of the packed emitter records
+ * @param {number} params.pool graph handle of the particle pool
+ * @param {number} params.alive graph handle of this frame's compacted alive list
+ * @param {number} params.counters graph handle of the atomic counters
+ * @param {number} params.sim_list graph handle of the list this rewrites. Passed in rather than
+ *   imported here because the simulate pass reads it earlier in the same frame: importing the same
+ *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
+ *   and the write end up on separate dependency chains
+ * @param {number} params.bucket_count number of distinct compiled programs
+ * @returns {{counters: number, sim_list: number}} the threaded handles downstream passes must read
+ */
+export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, counters, sim_list, bucket_count }) {
+    assert.defined(graph, "graph");
+    assert.isPositiveInteger(bucket_count, "bucket_count");
+    assert.isNonNegativeInteger(sim_list, "sim_list");
+
+    // Sized from the bucket count, which only changes when the emitter set does — so a caller that
+    // added an emitter and did not reallocate gets told here rather than scattering out of bounds.
+    const bin_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count);
+    assert.greaterThanOrEqual(gpu.sim_histogram.size, bin_words * Uint32Array.BYTES_PER_ELEMENT, "sim_histogram is too small for the bucket count");
+    assert.greaterThanOrEqual(gpu.sim_cursor.size, bucket_count * Uint32Array.BYTES_PER_ELEMENT, "sim_cursor is too small for the bucket count");
+    assert.greaterThanOrEqual(gpu.sim_bucket_counts.size, bucket_count * Uint32Array.BYTES_PER_ELEMENT, "sim_bucket_counts is too small for the bucket count");
+
+    // Every buffer a pass WRITES must be THREADED: the write returns a renamed (versioned) handle
+    // and the next pass must read THAT one. Reading the original import instead leaves the ordering
+    // between the two passes unexpressed — the graph's own validator rejects it, because both
+    // versions name one piece of memory and the stale-looking read silently returns the new
+    // contents.
+    let keys = graph_import_buffer(graph, gpu.sim_keys, "particles/sim_keys");
+    let histogram = graph_import_buffer(graph, gpu.sim_histogram, "particles/sim_histogram");
+    let cursor = graph_import_buffer(graph, gpu.sim_cursor, "particles/sim_cursor");
+    let bucket_counts = graph_import_buffer(graph, gpu.sim_bucket_counts, "particles/sim_bucket_counts");
+    let dispatch_args = graph_import_buffer(graph, gpu.sim_dispatch_args, "particles/sim_dispatch_args");
+
+    // 0. Clear the bins and cursors, write the scan's {count} header, and size the two per-particle
+    //    passes below from the GPU's own alive count.
+    {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_particle_bucket_reset,
+            bindings: { counters, histogram, cursor, sim_dispatch_args: dispatch_args, u_bucket_count: bucket_count },
+            group_count: [reset_group_count(bucket_count), 1, 1],
+        });
+        counters = out.counters;
+        histogram = out.histogram;
+        cursor = out.cursor;
+        dispatch_args = out.sim_dispatch_args;
+    }
+
+    // 1. One bin per PROGRAM. Indirect, because the thread count is the alive count.
+    {
+        const out = graph_compute_indirect_pass({
+            graph,
+            shader: shader_particle_bucket_histogram,
+            bindings: { emitters, pool, alive, keys, histogram, counters },
+            command: dispatch_args,
+        });
+        keys = out.keys;
+        histogram = out.histogram;
+        counters = out.counters;
+    }
+
+    // 2. Round every bin up to a whole workgroup BEFORE the scan — that is what puts each bucket
+    //    boundary on a wave boundary rather than in the middle of one.
+    {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_particle_bucket_pad,
+            bindings: { histogram, bucket_counts, u_bucket_count: bucket_count },
+            group_count: [Math.ceil(bucket_count / PARTICLE_SIMULATE_WORKGROUP_SIZE), 1, 1],
+        });
+        histogram = out.histogram;
+        bucket_counts = out.bucket_counts;
+    }
+
+    // 3. Inclusive prefix sums of the padded bins, in place.
+    const scanned = graph_prefix_scan_csdldf({
+        graph,
+        data: histogram,
+        element_max_count: bucket_count,
+    });
+
+    // 4. Place each alive entry at its bucket's offset plus an atomic rank.
+    {
+        const out = graph_compute_indirect_pass({
+            graph,
+            shader: shader_particle_bucket_scatter,
+            bindings: { keys, alive, scanned, cursor, sim_list, counters },
+            command: dispatch_args,
+        });
+        cursor = out.cursor;
+        sim_list = out.sim_list;
+        counters = out.counters;
+    }
+
+    // 5. Stamp the padding sentinel into each bucket's tail and publish the padded total. One
+    //    workgroup per bucket: padding is at most a workgroup less one entry, and a bucket whose
+    //    particles all died has no scatter thread to ride along with.
+    {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_particle_bucket_fill,
+            bindings: { bucket_counts, scanned, sim_list, counters, u_bucket_count: bucket_count },
+            group_count: [bucket_count, 1, 1],
+        });
+        sim_list = out.sim_list;
+        counters = out.counters;
+    }
+
+    return { counters, sim_list };
+}
+
+/**
+ * Workgroups the reset pass needs to cover its widest loop — the scan header plus the bins, rounded
+ * up to the whole `vec4` the last bin lands in (the scan reads whole `vec4`s, so the tail has to be
+ * cleared too or garbage joins the sums).
+ *
+ * @param {number} bucket_count
+ * @returns {number}
+ */
+function reset_group_count(bucket_count) {
+    const words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count);
+
+    return Math.ceil(words / PARTICLE_SIMULATE_WORKGROUP_SIZE);
+}
+
+/**
+ * @param {number} value
+ * @returns {number} `value` rounded up to a multiple of four — the scan reads whole `vec4`s
+ */
+function round_up_4(value) {
+    return (value + 3) & ~3;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Round `value` up to a multiple of {@link PARTICLE_SIMULATE_WORKGROUP_SIZE}.
+ *
+ * Mirrors the WGSL, which does this with a mask rather than a divide — see
+ * {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} for why.
+ *
+ * @param {number} value
+ * @returns {number}
+ */
+export function particle_bucket_round_up(value: number): number;
+/**
+ * @typedef {object} ParticleProgramBucketLayout
+ * @property {number[]} counts particles per program, before padding
+ * @property {number[]} padded_counts each count rounded up to a whole workgroup
+ * @property {number[]} offsets first index of each program's run in the padded list
+ * @property {number} total length of the padded list — what sizes the simulate dispatch
+ */
+/**
+ * Bucket sizes and start offsets, exactly as the GPU derives them: an atomic histogram, a round-up
+ * of each bin to a whole workgroup, and an exclusive prefix sum of the *padded* bins (the GPU takes
+ * that sum from `graph_prefix_scan_csdldf`, the same scan the radix sort runs its spine through).
+ *
+ * A program with no particles contributes nothing: `round_up(0)` is 0, so empty buckets neither
+ * consume a workgroup nor shift the offsets of the buckets after them.
+ *
+ * @param {ArrayLike<number>} programs program id of each alive entry
+ * @param {number} program_count number of distinct programs (the bucket count)
+ * @returns {ParticleProgramBucketLayout}
+ */
+export function particle_program_bucket_layout(programs: ArrayLike<number>, program_count: number): ParticleProgramBucketLayout;
+/**
+ * The simulate pass's input list: pool slot indices grouped by program, each group padded out to a
+ * workgroup boundary with {@link PARTICLE_SIM_PAD_SLOT}.
+ *
+ * Order within a bucket is arrival order here and arbitrary on the GPU (the scatter takes its rank
+ * from an atomic), which is fine — nothing downstream depends on the order of particles running the
+ * same program.
+ *
+ * @param {ArrayLike<number>} slots pool slot index of each alive entry
+ * @param {ArrayLike<number>} programs program id of each alive entry, parallel to `slots`
+ * @param {number} program_count number of distinct programs (the bucket count)
+ * @returns {number[]} the padded, program-coherent indirection list
+ */
+export function particle_program_bucket_list(slots: ArrayLike<number>, programs: ArrayLike<number>, program_count: number): number[];
+export type ParticleProgramBucketLayout = {
+    /**
+     * particles per program, before padding
+     */
+    counts: number[];
+    /**
+     * each count rounded up to a whole workgroup
+     */
+    padded_counts: number[];
+    /**
+     * first index of each program's run in the padded list
+     */
+    offsets: number[];
+    /**
+     * length of the padded list — what sizes the simulate dispatch
+     */
+    total: number;
+};
+//# sourceMappingURL=particle_program_buckets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_program_buckets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/particle_program_buckets.js"],"names":[],"mappings":"AAwCA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,yDAJW,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,2BAA2B,CAkBvC;AAED;;;;;;;;;;;;GAYG;AACH,oDALW,UAAU,MAAM,CAAC,YACjB,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,MAAM,EAAE,CAapB;;;;;YA5Da,MAAM,EAAE;;;;mBACR,MAAM,EAAE;;;;aACR,MAAM,EAAE;;;;WACR,MAAM"}