@woosh/meep-engine 3.57.0 → 3.59.0

package/src/shade/renderer/particles/warmup/shader_particle_warmup.js

@@ -1,318 +1,316 @@
-import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
-import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import {
-    PARTICLE_RECORD_WORD_COUNT,
-    PARTICLE_WARMUP_LAUNCH_LANES,
-    PARTICLE_WARMUP_QUEUE_WORDS,
-    PARTICLE_WARMUP_WORKGROUP_SIZE,
-} from "../ParticleConstants.js";
-import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import { PARTICLE_EMITTER_DESCRIPTOR, PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
-import { chunk_particle_spawn_budget } from "../shaders/chunk_particle_spawn_budget.js";
-
-/**
- * The passes that are the warm-up's own. The rest of the loop is the main pipeline's, bound to a
- * population of its own — see `./graph_particle_warmup.js` for the loop and for why it is separate.
- *
- * - {@link shader_particle_warmup_init} — hand the transient pool its free list, once per warm-up.
- * - {@link shader_particle_warmup_reset} — roll the transient counters over, once per tick.
- * - {@link shader_particle_warmup_tick} — one thread per queued emitter: the spawn decision for a
- *   tick, over a queue the host wrote rather than over the emitter table.
- * - {@link shader_particle_warmup_migrate} — one thread per warmed particle: move it into the main
- *   pool, once the loop is done.
- *
- * Everything the warm-up integrates per emitter lives in the queue entry (its accumulator), not in
- * the emitter's state row — with one exception, deliberately: the emitter's *age*. INIT and UPDATE
- * read `EMITTER_AGE` off the state row through the same chunk whether the main emit pass or the
- * warm-up's runs them, so the warm-up tick writes the age the emitter has reached into that row as it
- * goes. When the loop ends the row says `prewarm`, and the next real tick adds its `dt` to that.
- */
-
-/**
- * Word offsets within one entry of the warm-up queue the host writes:
- * `[emitter row, pre-warm seconds, spawn accumulator, clock]`.
- *
- * The accumulator is the host's to seed and the GPU's from then on — a fraction in `[0, 1)` hashed
- * from the row, so that two emitters queued together do not put their first whole particle on the
- * same tick. The clock is the emitter's own tick rate, `1 ± PARTICLE_WARMUP_EMITTER_JITTER / 2`, for
- * the same reason a beat further in.
- *
- * Raw words rather than a `WebGPUStruct`, like the spawn-command list: it is a short host-authored
- * list read once a tick, and the floats are `bitcast` on the way in and out.
- */
-export const WARMUP_QUEUE = Object.freeze({
-    ROW: 0,
-    PREWARM: 1,
-    ACCUMULATOR: 2,
-    CLOCK: 3,
-});
-
-/** Workgroups the bounded per-particle passes launch. */
-export const PARTICLE_WARMUP_WORKGROUP_COUNT = PARTICLE_WARMUP_LAUNCH_LANES / PARTICLE_WARMUP_WORKGROUP_SIZE;
-
-const WG = PARTICLE_WARMUP_WORKGROUP_SIZE;
-
-// --- init -------------------------------------------------------------------------------------
-
-const init_resources = new ShaderResourceSetDescriptor();
-
-init_resources.setImmediate("u_capacity", u32);
-
-init_resources.createGroup()
-    .addStorageBuffer("dead", WebGPUArray.u32, true)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
-
-/**
- * One thread per slot of the transient pool: every slot onto the free list, and the counters to
- * match. What the main system does once on the CPU when it allocates its pool, done on the GPU here
- * because the pool is a graph transient and there is no CPU moment to write it in.
- *
- * @type {ComputeShader}
- */
-export const shader_particle_warmup_init = ComputeShader.from({
-    label: "Particle Warm-up Init",
-    resources: init_resources,
-    body: CodeChunk.from(/* language=wgsl */ `
-@compute @workgroup_size(${WG}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-
-    if (i == 0u) {
-        atomicStore(&counters[${PARTICLE_COUNTER.DEAD}u], u_capacity);
-        atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
-        atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], 0u);
-    }
-
-    if (i >= u_capacity) { return; }
-
-    dead[i] = i;
-}
-`),
-});
-
-// --- reset ------------------------------------------------------------------------------------
-
-const reset_resources = new ShaderResourceSetDescriptor();
-
-reset_resources.createGroup()
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
-
-/**
- * The top of a warm-up tick: last tick's alive list becomes this tick's advance input, the alive
- * count starts over, and the tick's spawn budget is the free list as it stands.
- *
- * The main frame splits this between its reset pass and its build-indirect pass, because its
- * simulate consumes the program-coherent list the bucketing built rather than the alive list
- * itself. The warm-up's advance consumes the alive list directly (see `./chunk_particle_warmup_step.js`
- * for why it can), so the snapshot is just the count.
- *
- * @type {ComputeShader}
- */
-export const shader_particle_warmup_reset = ComputeShader.from({
-    label: "Particle Warm-up Reset",
-    resources: reset_resources,
-    body: CodeChunk.from(/* language=wgsl */ `
-@compute @workgroup_size(1, 1, 1)
-fn main() {
-    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], atomicLoad(&counters[${PARTICLE_COUNTER.ALIVE}u]));
-    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
-    atomicStore(&counters[${PARTICLE_COUNTER.SPAWN_BUDGET}u], atomicLoad(&counters[${PARTICLE_COUNTER.DEAD}u]));
-}
-`),
-});
-
-// --- tick -------------------------------------------------------------------------------------
-
-/**
- * Per-dispatch, 20 bytes, read-only.
- * @type {WebGPUStruct}
- */
-export const WARMUP_TICK_SETTINGS = WebGPUStruct.from({
-    /** seconds this tick advances the population by */
-    u_dt: f32,
-    /** seconds from the start of this tick to "now" — the end of the loop */
-    u_remaining: f32,
-    /** transient pool capacity — the accumulator's ceiling and the budget's wrap guard */
-    u_capacity: u32,
-    /** element capacity of the emitter table — the length of the counts list the scan consumes */
-    u_emitter_capacity: u32,
-    /** entries in the queue */
-    u_count: u32,
-}, "ParticleWarmupTickSettings");
-
-const EMITTER = PARTICLE_EMITTER_DESCRIPTOR;
-const STATE = PARTICLE_EMITTER_STATE_DESCRIPTOR;
-
-// Generated once and held: each call builds a fresh chunk declaring the same function.
-const WRITE_AGE = STATE.wgsl_gen_write_field_code("age");
-
-const tick_resources = new ShaderResourceSetDescriptor();
-
-tick_resources.setImmediate("settings", WARMUP_TICK_SETTINGS);
-
-tick_resources.createGroup()
-    .addStorageBuffer("queue", WebGPUArray.u32, true)
-    .addStorageBuffer("emitter_database", WebGPUArray.u32, true)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("spawn_counts", COLLECTION_U32_STRUCT_READ, true);
-
-/**
- * One thread per queued emitter: how many particles it spawns this tick.
- *
- * The main emitter tick's spawn decision — integrate the rate, take from the budget, write the
- * count by row for the scan — over the host's queue instead of the emitter table, and without the
- * parts that belong to a live frame: no generation test (the host holds the queue for exactly one
- * frame), no culling (a warm-up is what makes an emitter measurable in the first place), no pending
- * bursts (they are the frame's, not the past's).
- *
- * ## When an emitter takes part
- *
- * Once `u_remaining` is within its own pre-warm: the loop's clock counts down to now, and an emitter
- * joins it when the time left is what it asked to have been running for. Two emitters queued with
- * different durations therefore end the same loop having each run for its own — the shorter one
- * simply sat out the start — rather than the shorter one being run for the longer's time and
- * arriving with a population that is all dead of old age.
- *
- * ## The count list is the emitter table's
- *
- * The counts are written by emitter *row*, into a list as long as the table, exactly as the main
- * tick writes them. That is what lets the main emit pass be reused unchanged: it finds a newborn's
- * emitter by searching the scan of that list, and the row it finds is the row its record reads.
- * Rows not in the queue count zero, which the cleared buffer already says.
- *
- * @type {ComputeShader}
- */
-export const shader_particle_warmup_tick = ComputeShader.from({
-    label: "Particle Warm-up Tick",
-    resources: tick_resources,
-    body: CodeChunk.from(/* language=wgsl */ `
-const WARMUP_QUEUE_WORDS : u32 = ${PARTICLE_WARMUP_QUEUE_WORDS}u;
-const WARMUP_Q_ROW : u32 = ${WARMUP_QUEUE.ROW}u;
-const WARMUP_Q_PREWARM : u32 = ${WARMUP_QUEUE.PREWARM}u;
-const WARMUP_Q_ACCUMULATOR : u32 = ${WARMUP_QUEUE.ACCUMULATOR}u;
-const WARMUP_Q_CLOCK : u32 = ${WARMUP_QUEUE.CLOCK}u;
-
-@compute @workgroup_size(${WG}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-
-    // The scan reads exactly this many counts, queued or not.
-    if (i == 0u) {
-        spawn_counts.count = settings.u_emitter_capacity;
-    }
-
-    if (i >= settings.u_count) { return; }
-
-    let base = i * WARMUP_QUEUE_WORDS;
-    let row = queue[base + WARMUP_Q_ROW];
-    let prewarm = bitcast<f32>(queue[base + WARMUP_Q_PREWARM]);
-    var accumulator = bitcast<f32>(queue[base + WARMUP_Q_ACCUMULATOR]);
-    let clock = bitcast<f32>(queue[base + WARMUP_Q_CLOCK]);
-
-    var count = 0u;
-
-    if (settings.u_remaining <= prewarm) {
-        let em = ${EMITTER.marshalling_method_read_rw}(&emitter_database, row);
-
-        // This emitter's own beat: the tick, at its own clock.
-        accumulator = min(accumulator + em.spawn_rate * settings.u_dt * clock, f32(settings.u_capacity));
-
-        let wanted = u32(floor(accumulator));
-
-        if (wanted > 0u) {
-            count = particle_take_spawn_budget(wanted, settings.u_capacity);
-            accumulator = accumulator - f32(count);
-        }
-
-        // How long the emitter has been running once this tick is done — what this tick's newborns
-        // and advances read as EMITTER_AGE, on the row the main passes read it from too.
-        ${STATE.marshalling_method_write_field("age")}(&emitter_database, row, prewarm - settings.u_remaining + settings.u_dt);
-    }
-
-    spawn_counts.elements[row] = count;
-    queue[base + WARMUP_Q_ACCUMULATOR] = bitcast<u32>(accumulator);
-}
-`, [
-        EMITTER.chunk_read_rw,
-        WRITE_AGE,
-        chunk_particle_spawn_budget,
-    ]),
-});
-
-// --- migrate ----------------------------------------------------------------------------------
-
-const migrate_resources = new ShaderResourceSetDescriptor();
-
-migrate_resources.setImmediate("u_capacity", u32);
-
-migrate_resources.createGroup()
-    .addStorageBuffer("warm_pool", WebGPUArray.u32, false)
-    .addStorageBuffer("warm_alive", WebGPUArray.u32, false)
-    .addStorageBuffer("warm_counters", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("pool", WebGPUArray.u32, true)
-    .addStorageBuffer("alive_out", WebGPUArray.u32, true)
-    .addStorageBuffer("dead", WebGPUArray.u32, true)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
-
-/**
- * One thread per particle the loop left alive: a slot from the main pool, the record copied into
- * it, and the slot onto the main alive list. The moment the warm-up's population becomes the
- * scene's.
- *
- * The pop is the emit pass's, wrap guard and all, and it is the only thing this pass does to the
- * main free list: it never pushes, so it is safe against nothing and needs no ordering beyond
- * running after the main emit and simulate of the frame, which the graph gives it. A particle the
- * main pool has no room for is dropped, as a spawn the pool has no room for is.
- *
- * The record is copied whole, header included. The header names the emitter's main-table row and
- * generation — the warm-up's emit stamped it from the same record the main emit reads — so the
- * copied particle is an ordinary one to every pass that meets it from here on.
- *
- * Bounded launch, grid stride over the transient alive count: the population is small and nothing
- * should size a dispatch from the host to cover it.
- *
- * @type {ComputeShader}
- */
-export const shader_particle_warmup_migrate = ComputeShader.from({
-    label: "Particle Warm-up Migrate",
-    resources: migrate_resources,
-    body: CodeChunk.from(/* language=wgsl */ `
-const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
-const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
-const WARMUP_LAUNCH_LANES : u32 = ${PARTICLE_WARMUP_LAUNCH_LANES}u;
-const WARMUP_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
-
-@compute @workgroup_size(${WG}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let total = atomicLoad(&warm_counters[COUNTER_ALIVE]);
-
-    for (var i = gid.x; i < total; i = i + WARMUP_LAUNCH_LANES) {
-        let src = warm_alive[i];
-
-        // Pop a free slot off the main dead-list stack; drop the particle if the pool is exhausted.
-        // The guard catches WRAPPED values, not just 0 — see chunk_particle_emit_step for why.
-        let old_dead = atomicSub(&counters[COUNTER_DEAD], 1u);
-        if (old_dead == 0u || old_dead > u_capacity) {
-            atomicAdd(&counters[COUNTER_DEAD], 1u); // undo the over-pop
-            continue;
-        }
-        let dst = dead[old_dead - 1u];
-
-        let src_base = src * WARMUP_RECORD_WORDS;
-        let dst_base = dst * WARMUP_RECORD_WORDS;
-
-        for (var w = 0u; w < WARMUP_RECORD_WORDS; w = w + 1u) {
-            pool[dst_base + w] = warm_pool[src_base + w];
-        }
-
-        let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
-        alive_out[a] = dst;
-    }
-}
-`),
-});
+import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_WARMUP_LAUNCH_LANES,
+    PARTICLE_WARMUP_QUEUE_WORDS,
+    PARTICLE_WARMUP_WORKGROUP_SIZE,
+} from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { chunk_slot_stack } from "../../gpu_primitive/slot_stack/chunk_slot_stack.js";
+import { PARTICLE_EMITTER_DESCRIPTOR, PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+import { chunk_particle_spawn_budget } from "../shaders/chunk_particle_spawn_budget.js";
+
+/**
+ * The passes that are the warm-up's own. The rest of the loop is the main pipeline's, bound to a
+ * population of its own — see `./graph_particle_warmup.js` for the loop and for why it is separate.
+ *
+ * - {@link shader_particle_warmup_init} — hand the transient pool its free list, once per warm-up.
+ * - {@link shader_particle_warmup_reset} — roll the transient counters over, once per tick.
+ * - {@link shader_particle_warmup_tick} — one thread per queued emitter: the spawn decision for a
+ *   tick, over a queue the host wrote rather than over the emitter table.
+ * - {@link shader_particle_warmup_migrate} — one thread per warmed particle: move it into the main
+ *   pool, once the loop is done.
+ *
+ * Everything the warm-up integrates per emitter lives in the queue entry (its accumulator), not in
+ * the emitter's state row — with one exception, deliberately: the emitter's *age*. INIT and UPDATE
+ * read `EMITTER_AGE` off the state row through the same chunk whether the main emit pass or the
+ * warm-up's runs them, so the warm-up tick writes the age the emitter has reached into that row as it
+ * goes. When the loop ends the row says `prewarm`, and the next real tick adds its `dt` to that.
+ */
+
+/**
+ * Word offsets within one entry of the warm-up queue the host writes:
+ * `[emitter row, pre-warm seconds, spawn accumulator, clock]`.
+ *
+ * The accumulator is the host's to seed and the GPU's from then on — a fraction in `[0, 1)` hashed
+ * from the row, so that two emitters queued together do not put their first whole particle on the
+ * same tick. The clock is the emitter's own tick rate, `1 ± PARTICLE_WARMUP_EMITTER_JITTER / 2`, for
+ * the same reason a beat further in.
+ *
+ * Raw words rather than a `WebGPUStruct`, like the spawn-command list: it is a short host-authored
+ * list read once a tick, and the floats are `bitcast` on the way in and out.
+ */
+export const WARMUP_QUEUE = Object.freeze({
+    ROW: 0,
+    PREWARM: 1,
+    ACCUMULATOR: 2,
+    CLOCK: 3,
+});
+
+/** Workgroups the bounded per-particle passes launch. */
+export const PARTICLE_WARMUP_WORKGROUP_COUNT = PARTICLE_WARMUP_LAUNCH_LANES / PARTICLE_WARMUP_WORKGROUP_SIZE;
+
+const WG = PARTICLE_WARMUP_WORKGROUP_SIZE;
+
+// --- init -------------------------------------------------------------------------------------
+
+const init_resources = new ShaderResourceSetDescriptor();
+
+init_resources.setImmediate("u_capacity", u32);
+
+init_resources.createGroup()
+    .addStorageBuffer("dead", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * One thread per slot of the transient pool: every slot onto the free list, and the counters to
+ * match. What the main system does once on the CPU when it allocates its pool, done on the GPU here
+ * because the pool is a graph transient and there is no CPU moment to write it in.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_warmup_init = ComputeShader.from({
+    label: "Particle Warm-up Init",
+    resources: init_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+
+    if (i == 0u) {
+        atomicStore(&counters[${PARTICLE_COUNTER.DEAD}u], u_capacity);
+        atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
+        atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], 0u);
+    }
+
+    if (i >= u_capacity) { return; }
+
+    dead[i] = i;
+}
+`),
+});
+
+// --- reset ------------------------------------------------------------------------------------
+
+const reset_resources = new ShaderResourceSetDescriptor();
+
+reset_resources.createGroup()
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * The top of a warm-up tick: last tick's alive list becomes this tick's advance input, the alive
+ * count starts over, and the tick's spawn budget is the free list as it stands.
+ *
+ * The main frame splits this between its reset pass and its build-indirect pass, because its
+ * simulate consumes the program-coherent list the bucketing built rather than the alive list
+ * itself. The warm-up's advance consumes the alive list directly (see `./chunk_particle_warmup_step.js`
+ * for why it can), so the snapshot is just the count.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_warmup_reset = ComputeShader.from({
+    label: "Particle Warm-up Reset",
+    resources: reset_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+@compute @workgroup_size(1, 1, 1)
+fn main() {
+    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE_IN}u], atomicLoad(&counters[${PARTICLE_COUNTER.ALIVE}u]));
+    atomicStore(&counters[${PARTICLE_COUNTER.ALIVE}u], 0u);
+    atomicStore(&counters[${PARTICLE_COUNTER.SPAWN_BUDGET}u], atomicLoad(&counters[${PARTICLE_COUNTER.DEAD}u]));
+}
+`),
+});
+
+// --- tick -------------------------------------------------------------------------------------
+
+/**
+ * Per-dispatch, 20 bytes, read-only.
+ * @type {WebGPUStruct}
+ */
+export const WARMUP_TICK_SETTINGS = WebGPUStruct.from({
+    /** seconds this tick advances the population by */
+    u_dt: f32,
+    /** seconds from the start of this tick to "now" — the end of the loop */
+    u_remaining: f32,
+    /** transient pool capacity — the accumulator's ceiling and the budget's wrap guard */
+    u_capacity: u32,
+    /** element capacity of the emitter table — the length of the counts list the scan consumes */
+    u_emitter_capacity: u32,
+    /** entries in the queue */
+    u_count: u32,
+}, "ParticleWarmupTickSettings");
+
+const EMITTER = PARTICLE_EMITTER_DESCRIPTOR;
+const STATE = PARTICLE_EMITTER_STATE_DESCRIPTOR;
+
+// Generated once and held: each call builds a fresh chunk declaring the same function.
+const WRITE_AGE = STATE.wgsl_gen_write_field_code("age");
+
+const tick_resources = new ShaderResourceSetDescriptor();
+
+tick_resources.setImmediate("settings", WARMUP_TICK_SETTINGS);
+
+tick_resources.createGroup()
+    .addStorageBuffer("queue", WebGPUArray.u32, true)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("spawn_counts", COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * One thread per queued emitter: how many particles it spawns this tick.
+ *
+ * The main emitter tick's spawn decision — integrate the rate, take from the budget, write the
+ * count by row for the scan — over the host's queue instead of the emitter table, and without the
+ * parts that belong to a live frame: no generation test (the host holds the queue for exactly one
+ * frame), no culling (a warm-up is what makes an emitter measurable in the first place), no pending
+ * bursts (they are the frame's, not the past's).
+ *
+ * ## When an emitter takes part
+ *
+ * Once `u_remaining` is within its own pre-warm: the loop's clock counts down to now, and an emitter
+ * joins it when the time left is what it asked to have been running for. Two emitters queued with
+ * different durations therefore end the same loop having each run for its own — the shorter one
+ * simply sat out the start — rather than the shorter one being run for the longer's time and
+ * arriving with a population that is all dead of old age.
+ *
+ * ## The count list is the emitter table's
+ *
+ * The counts are written by emitter *row*, into a list as long as the table, exactly as the main
+ * tick writes them. That is what lets the main emit pass be reused unchanged: it finds a newborn's
+ * emitter by searching the scan of that list, and the row it finds is the row its record reads.
+ * Rows not in the queue count zero, which the cleared buffer already says.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_warmup_tick = ComputeShader.from({
+    label: "Particle Warm-up Tick",
+    resources: tick_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+const WARMUP_QUEUE_WORDS : u32 = ${PARTICLE_WARMUP_QUEUE_WORDS}u;
+const WARMUP_Q_ROW : u32 = ${WARMUP_QUEUE.ROW}u;
+const WARMUP_Q_PREWARM : u32 = ${WARMUP_QUEUE.PREWARM}u;
+const WARMUP_Q_ACCUMULATOR : u32 = ${WARMUP_QUEUE.ACCUMULATOR}u;
+const WARMUP_Q_CLOCK : u32 = ${WARMUP_QUEUE.CLOCK}u;
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+
+    // The scan reads exactly this many counts, queued or not.
+    if (i == 0u) {
+        spawn_counts.count = settings.u_emitter_capacity;
+    }
+
+    if (i >= settings.u_count) { return; }
+
+    let base = i * WARMUP_QUEUE_WORDS;
+    let row = queue[base + WARMUP_Q_ROW];
+    let prewarm = bitcast<f32>(queue[base + WARMUP_Q_PREWARM]);
+    var accumulator = bitcast<f32>(queue[base + WARMUP_Q_ACCUMULATOR]);
+    let clock = bitcast<f32>(queue[base + WARMUP_Q_CLOCK]);
+
+    var count = 0u;
+
+    if (settings.u_remaining <= prewarm) {
+        let em = ${EMITTER.marshalling_method_read_rw}(&emitter_database, row);
+
+        // This emitter's own beat: the tick, at its own clock.
+        accumulator = min(accumulator + em.spawn_rate * settings.u_dt * clock, f32(settings.u_capacity));
+
+        let wanted = u32(floor(accumulator));
+
+        if (wanted > 0u) {
+            count = particle_take_spawn_budget(wanted, settings.u_capacity);
+            accumulator = accumulator - f32(count);
+        }
+
+        // How long the emitter has been running once this tick is done — what this tick's newborns
+        // and advances read as EMITTER_AGE, on the row the main passes read it from too.
+        ${STATE.marshalling_method_write_field("age")}(&emitter_database, row, prewarm - settings.u_remaining + settings.u_dt);
+    }
+
+    spawn_counts.elements[row] = count;
+    queue[base + WARMUP_Q_ACCUMULATOR] = bitcast<u32>(accumulator);
+}
+`, [
+        EMITTER.chunk_read_rw,
+        WRITE_AGE,
+        chunk_particle_spawn_budget,
+    ]),
+});
+
+// --- migrate ----------------------------------------------------------------------------------
+
+const migrate_resources = new ShaderResourceSetDescriptor();
+
+migrate_resources.setImmediate("u_capacity", u32);
+
+migrate_resources.createGroup()
+    .addStorageBuffer("warm_pool", WebGPUArray.u32, false)
+    .addStorageBuffer("warm_alive", WebGPUArray.u32, false)
+    .addStorageBuffer("warm_counters", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("pool", WebGPUArray.u32, true)
+    .addStorageBuffer("alive_out", WebGPUArray.u32, true)
+    .addStorageBuffer("dead", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * One thread per particle the loop left alive: a slot from the main pool, the record copied into
+ * it, and the slot onto the main alive list. The moment the warm-up's population becomes the
+ * scene's.
+ *
+ * The pop is the emit pass's, wrap guard and all, and it is the only thing this pass does to the
+ * main free list: it never pushes, so it is safe against nothing and needs no ordering beyond
+ * running after the main emit and simulate of the frame, which the graph gives it. A particle the
+ * main pool has no room for is dropped, as a spawn the pool has no room for is.
+ *
+ * The record is copied whole, header included. The header names the emitter's main-table row and
+ * generation — the warm-up's emit stamped it from the same record the main emit reads — so the
+ * copied particle is an ordinary one to every pass that meets it from here on.
+ *
+ * Bounded launch, grid stride over the transient alive count: the population is small and nothing
+ * should size a dispatch from the host to cover it.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_warmup_migrate = ComputeShader.from({
+    label: "Particle Warm-up Migrate",
+    resources: migrate_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
+const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
+const WARMUP_LAUNCH_LANES : u32 = ${PARTICLE_WARMUP_LAUNCH_LANES}u;
+const WARMUP_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+
+@compute @workgroup_size(${WG}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let total = atomicLoad(&warm_counters[COUNTER_ALIVE]);
+
+    for (var i = gid.x; i < total; i = i + WARMUP_LAUNCH_LANES) {
+        let src = warm_alive[i];
+
+        // Pop a free slot off the main dead-list stack; drop the particle if the pool is exhausted.
+        let dst = slot_stack_pop(&counters[COUNTER_DEAD], &dead, u_capacity);
+        if (dst == SLOT_STACK_NONE) {
+            continue;
+        }
+
+        let src_base = src * WARMUP_RECORD_WORDS;
+        let dst_base = dst * WARMUP_RECORD_WORDS;
+
+        for (var w = 0u; w < WARMUP_RECORD_WORDS; w = w + 1u) {
+            pool[dst_base + w] = warm_pool[src_base + w];
+        }
+
+        let a = atomicAdd(&counters[COUNTER_ALIVE], 1u);
+        alive_out[a] = dst;
+    }
+}
+`, [chunk_slot_stack]),
+});