@woosh/meep-engine 3.14.5 → 3.14.6

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

@@ -0,0 +1,116 @@
+import { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_SIM_PAD_SLOT } from "../ParticleConstants.js";
+
+/**
+ * CPU reference for the simulation-order bucketing — the readable statement of the answer the GPU
+ * passes in {@link ./shader_particle_bucket.js} have to produce, the same role
+ * {@link ../sort/particle_counting_sort.js} plays for the render-order depth sort.
+ *
+ * ## What it is for
+ *
+ * The simulate pass is one dispatch interpreting every emitter's compiled UPDATE bytecode over the
+ * whole alive list. The alive list comes out of compaction — survivors are appended with
+ * `atomicAdd(&counters[ALIVE])` — so its order says nothing about which emitter a particle belongs
+ * to, and a single wave routinely holds particles running different programs. That costs twice
+ * over: the interpreter's opcode `switch` diverges, so the wave serially executes the union of the
+ * opcodes its lanes want; and the VM register file is dynamically indexed, which on AMD compiles to
+ * a `v_movrels`/`v_movreld` waterfall whose trip count is the number of *distinct* register indices
+ * live in the wave.
+ *
+ * Grouping the list by program collapses both. Padding each group out to
+ * {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} is what makes the grouping actually hold at wave
+ * granularity: an unpadded boundary lands mid-wave and that wave spans two programs again.
+ *
+ * ## What it is NOT
+ *
+ * This is the *simulation* order: camera-independent, changing only when emitters and their
+ * programs change. It is a different ordering from the *render* order in `../sort/`, which is
+ * back-to-front by view depth and exists so premultiplied transparency composites correctly. The
+ * two must stay in separate buffers and separate passes — reordering the render list for coherence
+ * breaks transparency, and depth-sorting the simulation list destroys the coherence.
+ *
+ * ## Indirection only
+ *
+ * Everything here permutes *indices into the pool*. Particle records never move: a slot is
+ * referenced by the dead (free) list and by the alive list across frames, so relocating a record
+ * would leave both pointing at the wrong particle.
+ */
+
+/** @type {number} bucket granularity — one whole simulate workgroup, and so at least one whole wave */
+const WG = PARTICLE_SIMULATE_WORKGROUP_SIZE;
+
+/**
+ * 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) {
+    return (value + (WG - 1)) & ~(WG - 1);
+}
+
+/**
+ * @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, program_count) {
+    const counts = new Array(program_count).fill(0);
+    for (let i = 0; i < programs.length; i++) {
+        counts[programs[i]]++;
+    }
+
+    const padded_counts = counts.map(particle_bucket_round_up);
+
+    const offsets = new Array(program_count);
+    let total = 0;
+    for (let b = 0; b < program_count; b++) {
+        offsets[b] = total;
+        total += padded_counts[b];
+    }
+
+    return { counts, padded_counts, offsets, total };
+}
+
+/**
+ * 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, programs, program_count) {
+    const layout = particle_program_bucket_layout(programs, program_count);
+
+    const list = new Array(layout.total).fill(PARTICLE_SIM_PAD_SLOT);
+
+    const cursor = layout.offsets.slice();
+    for (let i = 0; i < slots.length; i++) {
+        list[cursor[programs[i]]++] = slots[i];
+    }
+
+    return list;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Per-frame reset, and the only place the bucketing decides how big it is.
+ *
+ * WebGPU zero-fills a buffer on CREATION only, so without this the scan would consume last frame's
+ * bins and the scatter would compound last frame's ranks.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_reset: ComputeShader;
+/**
+ * One bin per PROGRAM, not per emitter: emitters compiled from the same graph share a program id
+ * (see {@link ../runtime/ProgramArena.js}) and belong in one wave-coherent run. Keying on the
+ * emitter index would split a run that was already coherent into one padded bucket per emitter.
+ *
+ * The emitter's program id is read by direct indexing rather than through
+ * `particle_emitter_read` — decoding a whole 41-word record, transform matrix included, to reach one
+ * word would be pure waste in a pass that touches every live particle.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_histogram: ComputeShader;
+/**
+ * Round every bin up to a whole workgroup, keeping the raw count in `bucket_counts` for the fill
+ * pass (which needs to know where the real entries stop and the padding starts).
+ *
+ * This is THE step that makes the bucketing worth doing. Scanning the raw counts would put a
+ * bucket boundary at an arbitrary index, and the wave straddling it would span two programs again —
+ * the exact divergence the pass exists to remove. An empty bin rounds up to zero, so a program with
+ * no live particles costs no lanes and shifts nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_pad: ComputeShader;
+/**
+ * Place each alive entry's pool slot at its bucket's exclusive offset plus an atomic rank.
+ *
+ * Order within a bucket is therefore arbitrary, which is exactly as much order as the simulation
+ * needs: every lane in the bucket runs the same program, so which of them runs where changes
+ * nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_scatter: ComputeShader;
+/**
+ * Stamp the padding sentinel into the tail of every bucket, and publish the padded total.
+ *
+ * Dispatched over one workgroup per bucket — a bucket's padding is at most `BUCKET_ALIGNMENT - 1`
+ * entries, so a workgroup always covers it. It cannot ride along with the scatter, which has no
+ * thread at all for a bucket whose particles all died.
+ *
+ * The padded total is the last bucket's inclusive scan value. It, and not the alive count, is what
+ * sizes next frame's simulate dispatch — the build-indirect pass reads it out of
+ * {@link PARTICLE_COUNTER.SIM_PADDED}.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_fill: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_particle_bucket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/shader_particle_bucket.js"],"names":[],"mappings":"AAwGA;;;;;;;GAOG;AACH,2CAFU,aAAa,CAyCpB;AAcH;;;;;;;;;;GAUG;AACH,+CAFU,aAAa,CAyBpB;AAYH;;;;;;;;;;GAUG;AACH,yCAFU,aAAa,CAmBpB;AAeH;;;;;;;;GAQG;AACH,6CAFU,aAAa,CAwBpB;AAcH;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAiCpB;8BArV2B,+BAA+B"}

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

@@ -0,0 +1,344 @@
+import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
+import {
+    PARTICLE_RECORD_HEADER_EMITTER,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+    PARTICLE_SIM_PAD_SLOT,
+} from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { EMITTER_FIELD, EMITTER_STRIDE } from "../data/PARTICLE_EMITTER_LAYOUT.js";
+
+/**
+ * Simulation-order bucketing — the passes that make each simulate wave run ONE VM program.
+ *
+ * ## Why
+ *
+ * The alive list is produced by compaction (`atomicAdd(&counters[ALIVE])`), so its order is
+ * arbitrary with respect to emitters and a single wave routinely holds particles running different
+ * programs. That costs twice: the interpreter's ~40-case opcode `switch` diverges, so the wave
+ * serially executes the union of the opcodes its lanes want; and `vm_reg[dst]` / `vm_reg[s0]` index
+ * a VGPR-resident register file dynamically, which AMD reaches with `v_movrels`/`v_movreld` behind
+ * a waterfall loop whose trip count is the number of DISTINCT register indices live in the wave.
+ * Grouping the wave by program collapses both at once.
+ *
+ * ## Shape
+ *
+ * The same three-phase shape the depth sort uses, with two small passes added for the padding:
+ *
+ *   reset -> histogram -> pad -> graph_prefix_scan_csdldf -> scatter -> fill
+ *
+ * 0. {@link shader_particle_bucket_reset} — write the `{count}` header the scan sizes itself from,
+ *    clear the bins and the scatter cursors, and build the indirect args the next two passes are
+ *    dispatched with (one thread per alive particle, from the GPU's own alive count).
+ * 1. {@link shader_particle_bucket_histogram} — per alive entry, look up the owning emitter's
+ *    program id and bump that bin.
+ * 2. {@link shader_particle_bucket_pad} — round every bin up to a whole simulate workgroup, keeping
+ *    the raw count aside. Rounding BEFORE the scan is what puts every bucket boundary on a wave
+ *    boundary; rounding after would leave the offsets unpadded and each boundary back mid-wave.
+ * 3. `graph_prefix_scan_csdldf`, reused as-is — inclusive prefix sums of the padded bins, so every
+ *    bucket's start offset is a multiple of the workgroup size.
+ * 4. {@link shader_particle_bucket_scatter} — per alive entry, exclusive offset plus an atomic rank
+ *    within the bucket, then write the pool slot there.
+ * 5. {@link shader_particle_bucket_fill} — write the padding sentinel into the tail of each bucket
+ *    and publish the padded total, which sizes next frame's simulate dispatch.
+ *
+ * ## Invariants this file rests on
+ *
+ * - **Indirection only.** Everything here permutes indices into `pool`. Records never move: slots
+ *   are referenced by the dead (free) list and across frames, and relocating one would leave both
+ *   pointing at the wrong particle.
+ * - **No CPU readback.** Only the bucket COUNT is host-known, and that is static topology (it
+ *   changes when the emitter set does, not per frame). Every per-frame quantity — the alive count,
+ *   the bin sizes, the padded total — is produced and consumed on the GPU.
+ * - **This is not the render order.** `../sort/` produces the camera-dependent back-to-front list
+ *   the billboard draw consumes. Separate buffers, separate passes, separate counter slots.
+ *
+ * @see ./particle_program_buckets.js for the CPU statement of the same answer.
+ */
+
+/** @type {number} words of `{count, elements}` header in front of the scan's bins */
+const HEADER = PREFIX_SCAN_CSDLDF_HEADER_WORDS;
+
+const WG = PARTICLE_SIMULATE_WORKGROUP_SIZE;
+
+/**
+ * Mask that rounds a count down to a whole workgroup; `(n + WG - 1) & PAD_MASK` rounds up.
+ *
+ * A mask rather than `(n + WG - 1u) / WG * WG` because the WGSL emulator's `/` is float division —
+ * the divide form would read differently there than on a device, and the round-up is exactly the
+ * property the specs have to pin. Correct only because {@link PARTICLE_SIMULATE_WORKGROUP_SIZE} is
+ * a power of two.
+ *
+ * @type {number}
+ */
+const PAD_MASK = (~(WG - 1)) >>> 0;
+
+/** log2 of the workgroup size — the fill pass splits its thread id into (bucket, lane) with it. */
+const WG_LOG = Math.log2(WG);
+
+/** Constants every pass in this file interpolates. */
+const COMMON = /* wgsl */ `
+const BUCKET_HEADER_WORDS : u32 = ${HEADER}u;
+const BUCKET_ALIGNMENT : u32 = ${WG}u;
+const BUCKET_PAD_MASK : u32 = ${PAD_MASK}u;
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
+const COUNTER_SIM_PADDED : u32 = ${PARTICLE_COUNTER.SIM_PADDED}u;
+`;
+
+// --- 0. reset ---------------------------------------------------------------------------------
+
+const reset_resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+reset_resources.setImmediate("u_bucket_count", u32);
+reset_resources.createGroup()
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true) // atomics need read_write even for atomicLoad
+    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("sim_dispatch_args", WebGPUArray.u32, true); // {x,y,z}
+
+/**
+ * Per-frame reset, and the only place the bucketing decides how big it is.
+ *
+ * WebGPU zero-fills a buffer on CREATION only, so without this the scan would consume last frame's
+ * bins and the scatter would compound last frame's ranks.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_reset = ComputeShader.from({
+    label: "Particle Bucket Reset",
+    resources: reset_resources,
+    body: CodeChunk.from(/* wgsl */ `
+${COMMON}
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+
+    if (i == 0u) {
+        // The {count, elements} header the csdldf scan sizes itself from.
+        atomicStore(&histogram[0], u_bucket_count);
+
+        // One thread per alive particle for the histogram and the scatter. The alive count exists
+        // only on the GPU — the host's copy is a frame stale at best — so the dispatch that
+        // consumes it is built here rather than passed in.
+        let alive = atomicLoad(&counters[COUNTER_ALIVE]);
+        sim_dispatch_args[0] = (alive + BUCKET_ALIGNMENT - 1u) / BUCKET_ALIGNMENT;
+        sim_dispatch_args[1] = 1u;
+        sim_dispatch_args[2] = 1u;
+    }
+
+    // Header padding: never read by the scan, but it shares the buffer and the pool may have left
+    // something in it.
+    if (i > 0u && i < BUCKET_HEADER_WORDS) {
+        atomicStore(&histogram[i], 0u);
+    }
+
+    // The scan reads whole vec4s, so the bins are cleared up to the vec4 the last one lands in.
+    if (i < ((u_bucket_count + 3u) & 0xfffffffcu)) {
+        atomicStore(&histogram[BUCKET_HEADER_WORDS + i], 0u);
+    }
+
+    if (i < u_bucket_count) {
+        atomicStore(&cursor[i], 0u);
+    }
+}
+`),
+});
+
+// --- 1. histogram -----------------------------------------------------------------------------
+
+const histogram_resources = new ShaderResourceSetDescriptor();
+
+histogram_resources.createGroup()
+    .addStorageBuffer("emitters", WebGPUArray.u32, false)
+    .addStorageBuffer("pool", WebGPUArray.u32, false)
+    .addStorageBuffer("alive", WebGPUArray.u32, false)
+    .addStorageBuffer("keys", WebGPUArray.u32, true)
+    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * One bin per PROGRAM, not per emitter: emitters compiled from the same graph share a program id
+ * (see {@link ../runtime/ProgramArena.js}) and belong in one wave-coherent run. Keying on the
+ * emitter index would split a run that was already coherent into one padded bucket per emitter.
+ *
+ * The emitter's program id is read by direct indexing rather than through
+ * `particle_emitter_read` — decoding a whole 41-word record, transform matrix included, to reach one
+ * word would be pure waste in a pass that touches every live particle.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_histogram = ComputeShader.from({
+    label: "Particle Bucket Histogram",
+    resources: histogram_resources,
+    body: CodeChunk.from(/* wgsl */ `
+${COMMON}
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const PARTICLE_EMITTER_RECORD_WORDS : u32 = ${EMITTER_STRIDE}u;
+const EMITTER_WORD_PROGRAM_ID : u32 = ${EMITTER_FIELD.PROGRAM_ID}u;
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
+
+    let slot = alive[i];
+    let emitter_index = pool[slot * PARTICLE_RECORD_WORDS + PARTICLE_HEADER_EMITTER];
+    let program = emitters[emitter_index * PARTICLE_EMITTER_RECORD_WORDS + EMITTER_WORD_PROGRAM_ID];
+
+    keys[i] = program;
+    atomicAdd(&histogram[BUCKET_HEADER_WORDS + program], 1u);
+}
+`),
+});
+
+// --- 2. pad -----------------------------------------------------------------------------------
+
+const pad_resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+pad_resources.setImmediate("u_bucket_count", u32);
+pad_resources.createGroup()
+    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("bucket_counts", WebGPUArray.u32, true);
+
+/**
+ * Round every bin up to a whole workgroup, keeping the raw count in `bucket_counts` for the fill
+ * pass (which needs to know where the real entries stop and the padding starts).
+ *
+ * This is THE step that makes the bucketing worth doing. Scanning the raw counts would put a
+ * bucket boundary at an arbitrary index, and the wave straddling it would span two programs again —
+ * the exact divergence the pass exists to remove. An empty bin rounds up to zero, so a program with
+ * no live particles costs no lanes and shifts nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_pad = ComputeShader.from({
+    label: "Particle Bucket Pad",
+    resources: pad_resources,
+    body: CodeChunk.from(/* wgsl */ `
+${COMMON}
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let b = gid.x;
+    if (b >= u_bucket_count) { return; }
+
+    let raw = atomicLoad(&histogram[BUCKET_HEADER_WORDS + b]);
+
+    bucket_counts[b] = raw;
+    atomicStore(&histogram[BUCKET_HEADER_WORDS + b], (raw + BUCKET_ALIGNMENT - 1u) & BUCKET_PAD_MASK);
+}
+`),
+});
+
+// --- 3. (graph_prefix_scan_csdldf) ------------------------------------------------------------
+// --- 4. scatter -------------------------------------------------------------------------------
+
+const scatter_resources = new ShaderResourceSetDescriptor();
+
+scatter_resources.createGroup()
+    .addStorageBuffer("keys", WebGPUArray.u32, false)
+    .addStorageBuffer("alive", WebGPUArray.u32, false)
+    .addStorageBuffer("scanned", WebGPUArray.u32, false)
+    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("sim_list", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Place each alive entry's pool slot at its bucket's exclusive offset plus an atomic rank.
+ *
+ * Order within a bucket is therefore arbitrary, which is exactly as much order as the simulation
+ * needs: every lane in the bucket runs the same program, so which of them runs where changes
+ * nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_scatter = ComputeShader.from({
+    label: "Particle Bucket Scatter",
+    resources: scatter_resources,
+    body: CodeChunk.from(/* wgsl */ `
+${COMMON}
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
+
+    let bucket = keys[i];
+
+    // The scan is inclusive, so bucket b's exclusive offset is bucket b-1's inclusive value, one
+    // word earlier. For bucket 0 the index lands on the last header word — in bounds, and unused,
+    // because select() takes the 0 branch there.
+    let exclusive = select(0u, scanned[BUCKET_HEADER_WORDS + bucket - 1u], bucket > 0u);
+    let rank = atomicAdd(&cursor[bucket], 1u);
+
+    sim_list[exclusive + rank] = alive[i];
+}
+`),
+});
+
+// --- 5. fill ----------------------------------------------------------------------------------
+
+const fill_resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+fill_resources.setImmediate("u_bucket_count", u32);
+fill_resources.createGroup()
+    .addStorageBuffer("bucket_counts", WebGPUArray.u32, false)
+    .addStorageBuffer("scanned", WebGPUArray.u32, false)
+    .addStorageBuffer("sim_list", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Stamp the padding sentinel into the tail of every bucket, and publish the padded total.
+ *
+ * Dispatched over one workgroup per bucket — a bucket's padding is at most `BUCKET_ALIGNMENT - 1`
+ * entries, so a workgroup always covers it. It cannot ride along with the scatter, which has no
+ * thread at all for a bucket whose particles all died.
+ *
+ * The padded total is the last bucket's inclusive scan value. It, and not the alive count, is what
+ * sizes next frame's simulate dispatch — the build-indirect pass reads it out of
+ * {@link PARTICLE_COUNTER.SIM_PADDED}.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bucket_fill = ComputeShader.from({
+    label: "Particle Bucket Fill",
+    resources: fill_resources,
+    body: CodeChunk.from(/* wgsl */ `
+${COMMON}
+const PARTICLE_SIM_PAD_SLOT : u32 = ${PARTICLE_SIM_PAD_SLOT}u;
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    // One workgroup per bucket. Shift and mask rather than / and %: the emulator's / is float
+    // division, and BUCKET_ALIGNMENT is a power of two anyway.
+    let bucket = gid.x >> ${WG_LOG}u;
+    let lane = gid.x & (BUCKET_ALIGNMENT - 1u);
+
+    if (gid.x == 0u) {
+        // Inclusive scan, so the last bucket's value is the whole padded length.
+        atomicStore(&counters[COUNTER_SIM_PADDED], scanned[BUCKET_HEADER_WORDS + u_bucket_count - 1u]);
+    }
+
+    if (bucket >= u_bucket_count) { return; }
+
+    let raw = bucket_counts[bucket];
+    let padded = (raw + BUCKET_ALIGNMENT - 1u) & BUCKET_PAD_MASK;
+    // The scan is inclusive, so subtracting this bucket's own (padded) size gives its start.
+    let start = scanned[BUCKET_HEADER_WORDS + bucket] - padded;
+
+    if (lane < padded - raw) {
+        sim_list[start + raw + lane] = PARTICLE_SIM_PAD_SLOT;
+    }
+}
+`),
+});

package/src/shade/renderer/particles/data/PARTICLE_COUNTERS.d.ts

@@ -10,15 +10,37 @@ export const PARTICLE_COUNTER: Readonly<{
     DEAD: 1;
     /** number of particles requested to spawn this frame */
     SPAWN: 2;
-    /** length of the sorted index list */
+    /**
+     * Length of the depth-sorted index list — the RENDER order (`../sort/`), back-to-front by view
+     * depth so premultiplied transparency composites correctly. Belongs to the camera-dependent
+     * ordering and to nothing else; the simulation order has its own slot, {@link SIM_PADDED}.
+     * Sharing one slot between the two would silently couple a camera-driven ordering to a
+     * program-driven one.
+     */
     SORTED: 3;
     /**
-     * Snapshot of the previous frame's final ALIVE — the exact length of the alive list the
-     * simulate pass consumes this frame. Written by the build-indirect pass at the end of each
-     * frame and NOT zeroed by the reset pass, so the loop stays fully GPU-driven (no CPU readback
-     * can be trusted for dispatch sizing: a stale count orphans or double-simulates slots).
+     * The exact length of the index list the simulate pass consumes this frame — the padded,
+     * program-coherent list the coherence pass built at the end of last frame, so this is
+     * {@link SIM_PADDED}'s value from then, NOT the alive count (padding makes it larger, and a
+     * multiple of the simulate workgroup size).
+     *
+     * Written by the build-indirect pass at the end of each frame, from the same value it derives
+     * the indirect dispatch args from — which is what makes the dispatch's thread count and the
+     * shader's bound agree by construction. NOT zeroed by the reset pass, so the loop stays fully
+     * GPU-driven (no CPU readback can be trusted for dispatch sizing: a stale count orphans or
+     * double-simulates slots).
      */
     ALIVE_IN: 4;
+    /**
+     * Length of the padded, program-coherent simulate input list the coherence pass (`../coherence/`)
+     * produced this frame — the SIMULATION order. Camera-independent; it changes only when the
+     * emitter/program set does. Read by the build-indirect pass, which turns it into next frame's
+     * {@link ALIVE_IN} and dispatch args.
+     *
+     * Zeroed by the reset pass: if the coherence passes are ever left out of a frame, simulate then
+     * reads a length of zero and does nothing, rather than re-running last frame's stale list.
+     */
+    SIM_PADDED: 5;
 }>;
 /** Number of `u32` atomic slots in the counters buffer. */
 export const PARTICLE_COUNTER_COUNT: 8;

package/src/shade/renderer/particles/data/PARTICLE_COUNTERS.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_COUNTERS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_COUNTERS.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC,wDAAwD;;IAExD,sCAAsC;;IAEtC;;;;;OAKG;;GAEJ;AAEH,2DAA2D;AAC3D,uCAAwC;AAExC;;;GAGG;AACH,0CAFU,YAAY,CAQG;6BAtCI,mCAAmC"}
+{"version":3,"file":"PARTICLE_COUNTERS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_COUNTERS.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC,wDAAwD;;IAExD;;;;;;OAMG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;GAEJ;AAEH,2DAA2D;AAC3D,uCAAwC;AAExC;;;GAGG;AACH,0CAFU,YAAY,CAQG;6BA5DI,mCAAmC"}

package/src/shade/renderer/particles/data/PARTICLE_COUNTERS.js

@@ -13,15 +13,37 @@ export const PARTICLE_COUNTER = Object.freeze({
     DEAD: 1,
     /** number of particles requested to spawn this frame */
     SPAWN: 2,
-    /** length of the sorted index list */
+    /**
+     * Length of the depth-sorted index list — the RENDER order (`../sort/`), back-to-front by view
+     * depth so premultiplied transparency composites correctly. Belongs to the camera-dependent
+     * ordering and to nothing else; the simulation order has its own slot, {@link SIM_PADDED}.
+     * Sharing one slot between the two would silently couple a camera-driven ordering to a
+     * program-driven one.
+     */
     SORTED: 3,
     /**
-     * Snapshot of the previous frame's final ALIVE — the exact length of the alive list the
-     * simulate pass consumes this frame. Written by the build-indirect pass at the end of each
-     * frame and NOT zeroed by the reset pass, so the loop stays fully GPU-driven (no CPU readback
-     * can be trusted for dispatch sizing: a stale count orphans or double-simulates slots).
+     * The exact length of the index list the simulate pass consumes this frame — the padded,
+     * program-coherent list the coherence pass built at the end of last frame, so this is
+     * {@link SIM_PADDED}'s value from then, NOT the alive count (padding makes it larger, and a
+     * multiple of the simulate workgroup size).
+     *
+     * Written by the build-indirect pass at the end of each frame, from the same value it derives
+     * the indirect dispatch args from — which is what makes the dispatch's thread count and the
+     * shader's bound agree by construction. NOT zeroed by the reset pass, so the loop stays fully
+     * GPU-driven (no CPU readback can be trusted for dispatch sizing: a stale count orphans or
+     * double-simulates slots).
      */
     ALIVE_IN: 4,
+    /**
+     * Length of the padded, program-coherent simulate input list the coherence pass (`../coherence/`)
+     * produced this frame — the SIMULATION order. Camera-independent; it changes only when the
+     * emitter/program set does. Read by the build-indirect pass, which turns it into next frame's
+     * {@link ALIVE_IN} and dispatch args.
+     *
+     * Zeroed by the reset pass: if the coherence passes are ever left out of a frame, simulate then
+     * reads a length of zero and does nothing, rather than re-running last frame's stale list.
+     */
+    SIM_PADDED: 5,
 });
 
 /** Number of `u32` atomic slots in the counters buffer. */

package/src/shade/renderer/particles/data/PARTICLE_EMITTER_LAYOUT.d.ts

@@ -42,6 +42,7 @@ export function emitter_flags_projection(flags: number): number;
  * @param {object} [def.render] { position, size, color, rotation, frame } attribute word offsets
  * @param {number[]} [def.atlas_region] length-4 [uvOffsetX, uvOffsetY, uvScaleX, uvScaleY]
  * @param {number[]} [def.flipbook] length-2 [cols, rows]
+ * @param {number} [def.program_id] dense program id, the simulation-order bucket key
  */
 export function pack_emitter(u32: Uint32Array, f32: Float32Array, index: number, def: {
     spawn_offset: number;
@@ -58,6 +59,7 @@ export function pack_emitter(u32: Uint32Array, f32: Float32Array, index: number,
     render?: object;
     atlas_region?: number[];
     flipbook?: number[];
+    program_id?: number;
 }): void;
 /**
  * Overwrite just an emitter's world transform in a packed buffer.
@@ -104,9 +106,19 @@ export const EMITTER_FIELD: Readonly<{
     ATLAS_REGION: 33;
     FLIPBOOK: 37;
     RENDER_VELOCITY: 39;
+    /**
+     * u32 — dense id of the compiled program this emitter runs, assigned by
+     * {@link ../runtime/ProgramArena.js}. Emitters sharing a program share an id.
+     *
+     * The simulation-order bucketing (`coherence/`) histograms on this: it needs a small dense
+     * integer to index a bin with, which neither the emitter index (one bucket per emitter, even
+     * when they run the same code) nor `UPDATE_OFFSET` (an arena word offset, arbitrarily large
+     * and sparse) gives it.
+     */
+    PROGRAM_ID: 40;
 }>;
 /** Number of `u32` words per emitter record. */
-export const EMITTER_STRIDE: 40;
+export const EMITTER_STRIDE: 41;
 /** Sentinel for an absent render-attribute binding. */
 export const EMITTER_ATTRIBUTE_ABSENT: 4294967295;
 /** Sentinel for "not attached to a scene node". */

package/src/shade/renderer/particles/data/PARTICLE_EMITTER_LAYOUT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_EMITTER_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js"],"names":[],"mappings":"AAiFA;;;;;;;;;;GAUG;AACH;IAR6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAWlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AAOD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,kCAnBW,WAAW,OACX,YAAY,SACZ,MAAM;IAEM,YAAY,EAAxB,MAAM;IACM,WAAW,EAAvB,MAAM;IACM,aAAa,EAAzB,MAAM;IACM,YAAY,EAAxB,MAAM;IACM,eAAe,EAA3B,MAAM;IACM,IAAI,EAAhB,MAAM;IACM,KAAK,EAAjB,MAAM;IACM,UAAU,EAAtB,MAAM;IACQ,SAAS,EAAvB,MAAM,EAAE;IACO,aAAa,GAA5B,MAAM,EAAE;IACK,aAAa,GAA1B,MAAM;IACO,MAAM,GAAnB,MAAM;IACS,YAAY,GAA3B,MAAM,EAAE;IACO,QAAQ,GAAvB,MAAM,EAAE;SAwClB;AAED;;;;;;;;;;;GAWG;AACH,6CAJW,YAAY,SACZ,MAAM,UACN,UAAU,MAAM,CAAC,QAO3B;AArMD;;;;;;;;;;GAUG;AAEH,6CAA6C;AAC7C;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,gDAAgD;AAChD,gCAAiC;AAEjC,uDAAuD;AACvD,kDAAmD;AAEnD,mDAAmD;AACnD,6CAA8C;AAE9C;;GAEG;AACH;;;;;GAKG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH,kEAAkE;AAClE;;;;;;GAMG;AAqCH,uEAAuE;AACvE;;;;;GAEG"}
+{"version":3,"file":"PARTICLE_EMITTER_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_LAYOUT.js"],"names":[],"mappings":"AA4FA;;;;;;;;;;GAUG;AACH;IAR6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAWlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AAOD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,kCApBW,WAAW,OACX,YAAY,SACZ,MAAM;IAEM,YAAY,EAAxB,MAAM;IACM,WAAW,EAAvB,MAAM;IACM,aAAa,EAAzB,MAAM;IACM,YAAY,EAAxB,MAAM;IACM,eAAe,EAA3B,MAAM;IACM,IAAI,EAAhB,MAAM;IACM,KAAK,EAAjB,MAAM;IACM,UAAU,EAAtB,MAAM;IACQ,SAAS,EAAvB,MAAM,EAAE;IACO,aAAa,GAA5B,MAAM,EAAE;IACK,aAAa,GAA1B,MAAM;IACO,MAAM,GAAnB,MAAM;IACS,YAAY,GAA3B,MAAM,EAAE;IACO,QAAQ,GAAvB,MAAM,EAAE;IACK,UAAU,GAAvB,MAAM;SA0ChB;AAED;;;;;;;;;;;GAWG;AACH,6CAJW,YAAY,SACZ,MAAM,UACN,UAAU,MAAM,CAAC,QAO3B;AAnND;;;;;;;;;;GAUG;AAEH,6CAA6C;AAC7C;;;;;;;;;;;;;;;;;;;;IA0BI;;;;;;;;OAQG;;GAEJ;AAEH,gDAAgD;AAChD,gCAAiC;AAEjC,uDAAuD;AACvD,kDAAmD;AAEnD,mDAAmD;AACnD,6CAA8C;AAE9C;;GAEG;AACH;;;;;GAKG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH,kEAAkE;AAClE;;;;;;GAMG;AAqCH,uEAAuE;AACvE;;;;;GAEG"}