@woosh/meep-engine 3.17.1 → 3.18.0

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

@@ -0,0 +1,102 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_hash_to_float01 } from "../../shader/chunk/random/chunk_hash_to_float01.js";
+import { chunk_hash_lowbias32_vec3u } from "../../shader/chunk/random/lowbias/chunk_hash_lowbias32_vec3u.js";
+import {
+    PARTICLE_RECORD_HEADER_EMITTER,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_WARMUP_DT_JITTER,
+} from "../ParticleConstants.js";
+import { chunk_particle_header } from "../data/particle_header.js";
+import { chunk_particle_emitter_age } from "../shaders/chunk_particle_emitter_age.js";
+import { chunk_particle_setup_context } from "../shaders/chunk_particle_setup_context.js";
+
+/**
+ * What a warm-up tick does to one particle: run its emitter's UPDATE program over it, by a tick
+ * jittered for it alone, and say whether it lived.
+ *
+ * Shared by `./shader_particle_warmup_advance.js` and `./shader_particle_warmup_advance_wide.js`
+ * the way the main simulate's step is shared by its two register backings.
+ *
+ * ## Why this is not `particle_simulate_one`
+ *
+ * It is the same shape — header, record, node, context, program, verdict — and it differs in two
+ * things that are each the whole point of a separate pipeline.
+ *
+ * It decodes the program section **per lane**. The main step reads the section parameters from the
+ * wave's first lane, and is correct only because the bucketing passes regrouped the list so every
+ * wave holds one program. The warm-up feeds its advance the raw alive list — spawned by emitters that
+ * may run different programs, appended in whatever order the atomics landed — and would need the
+ * bucketing's six passes per tick to earn the broadcast. Per-lane decode costs the warm-up some of
+ * its own occupancy and nothing else, and the warm-up's occupancy is its own business: nothing here
+ * is linked into the main passes, and their compiled code is unchanged by this file existing.
+ *
+ * It **jitters the tick per particle**. Every particle born in one tick would otherwise reach the
+ * end of the loop with exactly that tick's age, and a warm-up of N ticks would arrive as N cohorts.
+ * A program does not care what `DELTA_TIME` it is handed, so each particle is advanced by
+ * `dt * (1 + PARTICLE_WARMUP_DT_JITTER * (u - 0.5))` for a `u` hashed from its slot and the tick —
+ * a hash and not a draw from `random()`, so the program's own random stream is exactly what it would
+ * have been.
+ *
+ * There is no padding sentinel to recognise: the list this reads is the alive list, which holds real
+ * slots only. The generation test is kept — the host holds the queue for one frame and an emitter
+ * cannot leave mid-loop, but the header carries the generation and honouring it is one compare.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_warmup_step = CodeChunk.from(/* language=wgsl */ `
+const WARMUP_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const WARMUP_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const WARMUP_DT_JITTER : f32 = ${PARTICLE_WARMUP_DT_JITTER};
+// A lane of the jitter hash that is neither the slot nor the tick, so the jitter is not the RNG
+// seed's hash of the same two numbers.
+const WARMUP_JITTER_SALT : u32 = 0x9e3779b9u;
+
+// Advance one particle by one warm-up tick. Returns whether it is still alive.
+fn particle_warmup_advance_one(
+    scene_database : ptr<storage, array<u32>>,
+    emitter_database : ptr<storage, array<u32>>,
+    program : ptr<storage, array<u32>>,
+    pool : ptr<storage, array<u32>, read_write>,
+    slot : u32,
+    dt : f32,
+    time : f32,
+    frame : u32,
+) -> bool {
+    let record_base = slot * WARMUP_RECORD_WORDS;
+    let header = (*pool)[record_base + WARMUP_HEADER_EMITTER];
+    let emitter_index = particle_header_emitter(header);
+
+    let em = particle_emitter_read(emitter_database, emitter_index);
+
+    if (particle_header_generation(header) != em.generation) { return false; }
+
+    let node = scene_read_node(scene_database, em.node);
+
+    let u = hash_to_float01(hash_lowbias32_vec3u(vec3<u32>(slot, frame, WARMUP_JITTER_SALT)));
+    let dt_jittered = dt * (1.0 + WARMUP_DT_JITTER * (u - 0.5));
+
+    particle_vm_reset();
+    particle_setup_context(
+        em, node, slot,
+        dt_jittered, time,
+        particle_emitter_age(emitter_database, emitter_index),
+        0.0, frame,
+    );
+    particle_vm_execute(
+        program,
+        em.update_offset * PARTICLE_VM_INSTRUCTION_WORDS,
+        em.update_count,
+        em.constant_offset,
+        pool,
+        record_base,
+    );
+
+    return !vm_killed;
+}
+`, [
+    chunk_particle_setup_context,
+    chunk_particle_emitter_age,
+    chunk_particle_header,
+    chunk_hash_lowbias32_vec3u,
+    chunk_hash_to_float01,
+]);

package/src/shade/renderer/particles/warmup/graph_particle_warmup.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Run a batch of newly added emitters' simulations forward before they are first shown, so that a
+ * continuous effect arrives at its steady state instead of growing into it in front of the player.
+ *
+ * ## What a warm-up is
+ *
+ * The ordinary loop — spawn, init, advance — run over a population of its own until every emitter
+ * in the batch has been running for its `prewarm`. It is not a batch of particles dumped in one
+ * tick and aged: an emitter keeps spawning throughout, the ones that die are replaced the way they
+ * are in a live scene, and whatever drives the rate (a curve, `EMITTER_AGE`, the program itself)
+ * drives it here, because it is the same program being run. What the loop leaves is the population
+ * the emitter would have had, moved into the main pool.
+ *
+ * ## Why it is a pipeline of its own
+ *
+ * Because the main one is tuned and it must not pay for this. Emit and simulate are the passes whose
+ * register pressure sets the system's occupancy, and their waves are kept program-uniform by the
+ * bucketing; a warm-up folded into either would spend registers on every frame for work that
+ * happens on one, and a loop inside a lane would break the uniform flow across a wave. So this
+ * shares code with the main frame and integrates nothing into it: the emit pass is reused unchanged
+ * over the warm-up's buffers, the advance is a pass of the warm-up's own (`./chunk_particle_warmup_step.js`
+ * says why), and the main passes' compiled code is byte-identical whether this file exists or not.
+ *
+ * ## The population is transient
+ *
+ * Pool, alive lists, free list and counters are graph transients that exist for this frame's loop
+ * and are then moved — record by record — into the main pool by the migrate pass. That is what keeps
+ * the separation clean: the loop's free-list traffic never touches the main free list, the main
+ * passes never see a half-warmed particle, and the one point of contact is a pass that pops from the
+ * main pool and pushes nothing back.
+ *
+ * ## Bounded
+ *
+ * The tick count is at most `PARTICLE_WARMUP_MAX_TICKS`, with the tick length stretched to cover the
+ * longest pre-warm in the batch (`./warmup_schedule.js`), so the frame that pays for a warm-up pays
+ * for a known number of dispatches whatever was asked. Per tick: reset, tick, the scan, the emit
+ * command, emit, advance — six or seven passes, all sized by constants or by the scan.
+ *
+ * ## Where it sits in the frame
+ *
+ * After the frame's own emit and simulate, before the bucketing. Migrate appends to the same alive
+ * list they did, so the bucketing puts the warmed particles in next frame's simulate list, the bounds
+ * pass measures them into their emitter's box this frame, and the draw draws them this frame. Which
+ * is also what closes the culling fixed point the bounds passes describe: an emitter that arrives
+ * with a warmed population is measured on its first frame, whatever the frustum thinks of its origin.
+ *
+ * Recorded only on a frame with something queued. The host knows: an emitter is queued when it is
+ * registered with a `prewarm`, and the queue is consumed by the frame that records it.
+ *
+ * @param {object} params
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.scene_database graph handle
+ * @param {number} params.emitter_database graph handle, threaded: the warm-up tick writes ages
+ * @param {number} params.program graph handle of the packed program buffer
+ * @param {number} params.pool main pool, threaded
+ * @param {number} params.alive_out main alive list, threaded
+ * @param {number} params.dead main free list, threaded
+ * @param {number} params.counters main counters, threaded
+ * @param {number} params.vm_registers the wide register file's handle, or -1 when the system is on
+ *   the fast file
+ * @param {GPUBuffer} params.queue the host's queue buffer, `PARTICLE_WARMUP_QUEUE_WORDS` per entry
+ * @param {number} params.queue_count entries in the queue
+ * @param {number} params.warm_capacity slots in the transient pool
+ * @param {number} params.capacity main pool capacity
+ * @param {number} params.emitter_capacity element capacity of the emitter table
+ * @param {import("./warmup_schedule.js").WarmupSchedule} params.schedule
+ * @param {boolean} params.wide_registers
+ * @param {object} params.frame
+ * @param {number} params.frame.time the frame's clock — the loop counts down to it
+ * @param {number} params.frame.index
+ * @returns {{pool: number, alive_out: number, dead: number, counters: number, emitter_database: number, vm_registers: number}}
+ */
+export function graph_particle_warmup({ graph, scene_database, emitter_database, program, pool, alive_out, dead, counters, vm_registers, queue, queue_count, warm_capacity, capacity, emitter_capacity, schedule, wide_registers, frame, }: {
+    graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    scene_database: number;
+    emitter_database: number;
+    program: number;
+    pool: number;
+    alive_out: number;
+    dead: number;
+    counters: number;
+    vm_registers: number;
+    queue: GPUBuffer;
+    queue_count: number;
+    warm_capacity: number;
+    capacity: number;
+    emitter_capacity: number;
+    schedule: import("./warmup_schedule.js").WarmupSchedule;
+    wide_registers: boolean;
+    frame: {
+        time: number;
+        index: number;
+    };
+}): {
+    pool: number;
+    alive_out: number;
+    dead: number;
+    counters: number;
+    emitter_database: number;
+    vm_registers: number;
+};
+//# sourceMappingURL=graph_particle_warmup.d.ts.map

package/src/shade/renderer/particles/warmup/graph_particle_warmup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_particle_warmup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/warmup/graph_particle_warmup.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH;IAtBqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,cAAc,EAA7B,MAAM;IACS,gBAAgB,EAA/B,MAAM;IACS,OAAO,EAAtB,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,SAAS,EAAxB,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IAEY,KAAK;IACR,WAAW,EAA1B,MAAM;IACS,aAAa,EAA5B,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,gBAAgB,EAA/B,MAAM;IACgD,QAAQ,EAA9D,OAAO,sBAAsB,EAAE,cAAc;IAC7B,cAAc,EAA9B,OAAO;IACQ,KAAK;QACC,IAAI,EAAzB,MAAM;QACe,KAAK,EAA1B,MAAM;;IACJ;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAC,CAqO7H"}

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

@@ -0,0 +1,329 @@
+import { assert } from "../../../../core/assert.js";
+import { align_4 } from "../../../../core/binary/align_4.js";
+import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
+import { INDIRECT_COMPUTE_COMMAND_DESCRIPTOR } from "../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { graph_prefix_scan_csdldf } from "../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
+import { shader_prefix_sum_to_command } from "../../rasterize/expand/mesh/shader_prefix_sum_to_command.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_create_buffer } from "../../shader/graph/graph_create_buffer.js";
+import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
+import { PARTICLE_RECORD_WORD_COUNT, PARTICLE_WARMUP_WORKGROUP_SIZE } from "../ParticleConstants.js";
+import { PARTICLE_COUNTER_COUNT } from "../data/PARTICLE_COUNTERS.js";
+import { shader_particle_emit } from "../shaders/shader_particle_emit.js";
+import {
+    PARTICLE_EMIT_WIDE_WORKGROUP_COUNT,
+    shader_particle_emit_wide,
+} from "../shaders/shader_particle_emit_wide.js";
+import {
+    PARTICLE_WARMUP_WORKGROUP_COUNT,
+    shader_particle_warmup_init,
+    shader_particle_warmup_migrate,
+    shader_particle_warmup_reset,
+    shader_particle_warmup_tick,
+} from "./shader_particle_warmup.js";
+import { shader_particle_warmup_advance } from "./shader_particle_warmup_advance.js";
+import { shader_particle_warmup_advance_wide } from "./shader_particle_warmup_advance_wide.js";
+import { warmup_remaining } from "./warmup_schedule.js";
+
+/**
+ * Run a batch of newly added emitters' simulations forward before they are first shown, so that a
+ * continuous effect arrives at its steady state instead of growing into it in front of the player.
+ *
+ * ## What a warm-up is
+ *
+ * The ordinary loop — spawn, init, advance — run over a population of its own until every emitter
+ * in the batch has been running for its `prewarm`. It is not a batch of particles dumped in one
+ * tick and aged: an emitter keeps spawning throughout, the ones that die are replaced the way they
+ * are in a live scene, and whatever drives the rate (a curve, `EMITTER_AGE`, the program itself)
+ * drives it here, because it is the same program being run. What the loop leaves is the population
+ * the emitter would have had, moved into the main pool.
+ *
+ * ## Why it is a pipeline of its own
+ *
+ * Because the main one is tuned and it must not pay for this. Emit and simulate are the passes whose
+ * register pressure sets the system's occupancy, and their waves are kept program-uniform by the
+ * bucketing; a warm-up folded into either would spend registers on every frame for work that
+ * happens on one, and a loop inside a lane would break the uniform flow across a wave. So this
+ * shares code with the main frame and integrates nothing into it: the emit pass is reused unchanged
+ * over the warm-up's buffers, the advance is a pass of the warm-up's own (`./chunk_particle_warmup_step.js`
+ * says why), and the main passes' compiled code is byte-identical whether this file exists or not.
+ *
+ * ## The population is transient
+ *
+ * Pool, alive lists, free list and counters are graph transients that exist for this frame's loop
+ * and are then moved — record by record — into the main pool by the migrate pass. That is what keeps
+ * the separation clean: the loop's free-list traffic never touches the main free list, the main
+ * passes never see a half-warmed particle, and the one point of contact is a pass that pops from the
+ * main pool and pushes nothing back.
+ *
+ * ## Bounded
+ *
+ * The tick count is at most `PARTICLE_WARMUP_MAX_TICKS`, with the tick length stretched to cover the
+ * longest pre-warm in the batch (`./warmup_schedule.js`), so the frame that pays for a warm-up pays
+ * for a known number of dispatches whatever was asked. Per tick: reset, tick, the scan, the emit
+ * command, emit, advance — six or seven passes, all sized by constants or by the scan.
+ *
+ * ## Where it sits in the frame
+ *
+ * After the frame's own emit and simulate, before the bucketing. Migrate appends to the same alive
+ * list they did, so the bucketing puts the warmed particles in next frame's simulate list, the bounds
+ * pass measures them into their emitter's box this frame, and the draw draws them this frame. Which
+ * is also what closes the culling fixed point the bounds passes describe: an emitter that arrives
+ * with a warmed population is measured on its first frame, whatever the frustum thinks of its origin.
+ *
+ * Recorded only on a frame with something queued. The host knows: an emitter is queued when it is
+ * registered with a `prewarm`, and the queue is consumed by the frame that records it.
+ *
+ * @param {object} params
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.scene_database graph handle
+ * @param {number} params.emitter_database graph handle, threaded: the warm-up tick writes ages
+ * @param {number} params.program graph handle of the packed program buffer
+ * @param {number} params.pool main pool, threaded
+ * @param {number} params.alive_out main alive list, threaded
+ * @param {number} params.dead main free list, threaded
+ * @param {number} params.counters main counters, threaded
+ * @param {number} params.vm_registers the wide register file's handle, or -1 when the system is on
+ *   the fast file
+ * @param {GPUBuffer} params.queue the host's queue buffer, `PARTICLE_WARMUP_QUEUE_WORDS` per entry
+ * @param {number} params.queue_count entries in the queue
+ * @param {number} params.warm_capacity slots in the transient pool
+ * @param {number} params.capacity main pool capacity
+ * @param {number} params.emitter_capacity element capacity of the emitter table
+ * @param {import("./warmup_schedule.js").WarmupSchedule} params.schedule
+ * @param {boolean} params.wide_registers
+ * @param {object} params.frame
+ * @param {number} params.frame.time the frame's clock — the loop counts down to it
+ * @param {number} params.frame.index
+ * @returns {{pool: number, alive_out: number, dead: number, counters: number, emitter_database: number, vm_registers: number}}
+ */
+export function graph_particle_warmup({
+                                          graph,
+                                          scene_database,
+                                          emitter_database,
+                                          program,
+                                          pool,
+                                          alive_out,
+                                          dead,
+                                          counters,
+                                          vm_registers,
+                                          queue,
+                                          queue_count,
+                                          warm_capacity,
+                                          capacity,
+                                          emitter_capacity,
+                                          schedule,
+                                          wide_registers,
+                                          frame,
+                                      }) {
+    assert.defined(graph, "graph");
+    assert.isPositiveInteger(queue_count, "queue_count");
+    assert.isPositiveInteger(warm_capacity, "warm_capacity");
+    assert.isPositiveInteger(schedule.ticks, "schedule.ticks");
+
+    const WORD = Uint32Array.BYTES_PER_ELEMENT;
+    const STORAGE = GPUBufferUsage.STORAGE;
+
+    const gr_queue = graph_import_buffer(graph, queue, "particles/warmup/queue");
+
+    // The transient population. Uncleared where the init pass writes every word that will be read
+    // (the free list), cleared where a word could be read before it is written (the counters, and
+    // the alive lists' tails are bounded by counts the passes wrote).
+    // Threaded like everything a pass writes: emit and advance both rename it, and the next reader
+    // must take the renamed handle or the graph's validator rejects the frame as reading a stale
+    // version.
+    let warm_pool = graph_create_buffer(graph, "particles/warmup/pool", BufferResourceDescriptor.from(
+        warm_capacity * PARTICLE_RECORD_WORD_COUNT * WORD, STORAGE,
+    ));
+    const warm_alive = [
+        graph_create_buffer(graph, "particles/warmup/alive_a", BufferResourceDescriptor.from(warm_capacity * WORD, STORAGE)),
+        graph_create_buffer(graph, "particles/warmup/alive_b", BufferResourceDescriptor.from(warm_capacity * WORD, STORAGE)),
+    ];
+    let warm_dead = graph_create_buffer(graph, "particles/warmup/dead", BufferResourceDescriptor.from(warm_capacity * WORD, STORAGE));
+    let warm_counters = graph_create_buffer(graph, "particles/warmup/counters", BufferResourceDescriptor.empty(
+        PARTICLE_COUNTER_COUNT * WORD, STORAGE | GPUBufferUsage.COPY_DST,
+    ));
+
+    // Every slot onto the free list.
+    {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_particle_warmup_init,
+            bindings: { dead: warm_dead, counters: warm_counters, u_capacity: warm_capacity },
+            group_count: [Math.ceil(warm_capacity / PARTICLE_WARMUP_WORKGROUP_SIZE), 1, 1],
+        });
+        warm_dead = out.dead;
+        warm_counters = out.counters;
+    }
+
+    const count_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(Math.max(1, emitter_capacity));
+    const count_bytes = count_words * WORD;
+
+    let gr_queue_rw = gr_queue;
+
+    for (let tick = 0; tick < schedule.ticks; tick++) {
+        const remaining = warmup_remaining(schedule, tick);
+        // The clock at the start of this tick: the frame's, less what is still to run.
+        const time = frame.time - remaining;
+        // Distinct per tick, and unlike any frame index the main emit will seed with, so a warmed
+        // particle's random stream is not a later particle's in the same slot.
+        const frame_index = (frame.index ^ Math.imul(tick + 1, 0x9e3779b9)) >>> 0;
+
+        // Last tick's survivors are this tick's input; this tick appends to the other list.
+        const alive_in = warm_alive[(tick + 1) % 2];
+        let alive_this = warm_alive[tick % 2];
+
+        // 1. Roll the counters: alive -> alive_in, alive = 0, budget = dead.
+        warm_counters = graph_compute_pass({
+            graph,
+            shader: shader_particle_warmup_reset,
+            bindings: { counters: warm_counters },
+            group_count: [1, 1, 1],
+        }).counters;
+
+        // 2. The spawn decision, per queued emitter, into a count list as long as the emitter table.
+        //    Cleared whole: the tick writes only the queued rows.
+        let spawn_counts = graph_create_buffer(graph, "particles/warmup/spawn_counts", BufferResourceDescriptor.from(
+            count_bytes, STORAGE, 0, count_bytes,
+        ));
+
+        {
+            const out = graph_compute_pass({
+                graph,
+                shader: shader_particle_warmup_tick,
+                bindings: {
+                    queue: gr_queue_rw,
+                    emitter_database,
+                    counters: warm_counters,
+                    spawn_counts,
+                    settings: {
+                        u_dt: schedule.dt,
+                        u_remaining: remaining,
+                        u_capacity: warm_capacity,
+                        u_emitter_capacity: emitter_capacity,
+                        u_count: queue_count,
+                    },
+                },
+                group_count: [Math.ceil(queue_count / PARTICLE_WARMUP_WORKGROUP_SIZE), 1, 1],
+            });
+            gr_queue_rw = out.queue;
+            emitter_database = out.emitter_database;
+            warm_counters = out.counters;
+            spawn_counts = out.spawn_counts;
+        }
+
+        // 3. Scan the counts; the last sum is the tick's newborn count.
+        const spawn_prefix = graph_prefix_scan_csdldf({
+            graph,
+            data: spawn_counts,
+            element_max_count: Math.max(1, emitter_capacity),
+        });
+
+        // 4. That total as the emit dispatch — for the fast emit; the wide one reads the total as a
+        //    loop bound instead, as it does in the main frame.
+        const emit_command = graph_compute_pass({
+            graph,
+            shader: shader_prefix_sum_to_command,
+            bindings: {
+                prefix_sums: spawn_prefix,
+                command: graph_create_buffer(graph, "particles/warmup/emit_command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR),
+            },
+            group_count: [1, 1, 1],
+        }).command;
+
+        // 5. Emit — the main pass, unchanged, over the warm-up's buffers. It finds each newborn's
+        //    emitter in the scan, reads the record and the age off the main database, pops the
+        //    transient free list and appends to the transient alive list.
+        {
+            const bindings = {
+                scene_database,
+                emitter_database,
+                program,
+                spawn_prefix,
+                pool: warm_pool, alive_out: alive_this, dead: warm_dead, counters: warm_counters,
+                settings: { u_dt: schedule.dt, u_time: time, u_frame: frame_index, u_capacity: warm_capacity },
+            };
+
+            const out = wide_registers
+                ? graph_compute_pass({
+                    graph,
+                    shader: shader_particle_emit_wide,
+                    bindings: { ...bindings, vm_registers },
+                    group_count: [PARTICLE_EMIT_WIDE_WORKGROUP_COUNT, 1, 1],
+                })
+                : graph_compute_indirect_pass({
+                    graph,
+                    shader: shader_particle_emit,
+                    bindings,
+                    command: emit_command,
+                });
+
+            warm_pool = out.pool;
+            alive_this = out.alive_out;
+            warm_dead = out.dead;
+            warm_counters = out.counters;
+
+            if (wide_registers) { vm_registers = out.vm_registers; }
+        }
+
+        // 6. Advance last tick's survivors by one tick, into the same list the newborns went to.
+        {
+            const bindings = {
+                scene_database,
+                emitter_database,
+                program,
+                pool: warm_pool, alive_in, alive_out: alive_this, dead: warm_dead, counters: warm_counters,
+                settings: { u_dt: schedule.dt, u_time: time, u_frame: frame_index },
+            };
+
+            const out = wide_registers
+                ? graph_compute_pass({
+                    graph,
+                    shader: shader_particle_warmup_advance_wide,
+                    bindings: { ...bindings, vm_registers },
+                    group_count: [PARTICLE_WARMUP_WORKGROUP_COUNT, 1, 1],
+                })
+                : graph_compute_pass({
+                    graph,
+                    shader: shader_particle_warmup_advance,
+                    bindings,
+                    group_count: [PARTICLE_WARMUP_WORKGROUP_COUNT, 1, 1],
+                });
+
+            warm_pool = out.pool;
+            alive_this = out.alive_out;
+            warm_dead = out.dead;
+            warm_counters = out.counters;
+
+            if (wide_registers) { vm_registers = out.vm_registers; }
+        }
+
+        warm_alive[tick % 2] = alive_this;
+    }
+
+    // 7. The population is the scene's: every survivor into a main-pool slot, onto the main alive
+    //    list.
+    {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_particle_warmup_migrate,
+            bindings: {
+                warm_pool,
+                warm_alive: warm_alive[(schedule.ticks - 1) % 2],
+                warm_counters,
+                pool, alive_out, dead, counters,
+                u_capacity: capacity,
+            },
+            group_count: [PARTICLE_WARMUP_WORKGROUP_COUNT, 1, 1],
+        });
+
+        pool = out.pool;
+        alive_out = out.alive_out;
+        dead = out.dead;
+        counters = out.counters;
+    }
+
+    return { pool, alive_out, dead, counters, emitter_database, vm_registers };
+}

package/src/shade/renderer/particles/warmup/shader_particle_warmup.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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: Readonly<{
+    ROW: 0;
+    PREWARM: 1;
+    ACCUMULATOR: 2;
+    CLOCK: 3;
+}>;
+/** Workgroups the bounded per-particle passes launch. */
+export const PARTICLE_WARMUP_WORKGROUP_COUNT: number;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * Per-dispatch, 20 bytes, read-only.
+ * @type {WebGPUStruct}
+ */
+export const WARMUP_TICK_SETTINGS: WebGPUStruct;
+/**
+ * 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;
+/**
+ * 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;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=shader_particle_warmup.d.ts.map

package/src/shade/renderer/particles/warmup/shader_particle_warmup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_warmup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/warmup/shader_particle_warmup.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;GAWG;AACH;;;;;GAKG;AAEH,yDAAyD;AACzD,qDAA6G;AAc7G;;;;;;GAMG;AACH,0CAFU,aAAa,CAqBpB;AASH;;;;;;;;;;GAUG;AACH,2CAFU,aAAa,CAapB;AAIH;;;GAGG;AACH,mCAFU,YAAY,CAaW;AAkBjC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,0CAFU,aAAa,CAyDpB;AAiBH;;;;;;;;;;;;;;;;;;GAkBG;AACH,6CAFU,aAAa,CAuCpB;8BAzT2B,+BAA+B;6BAFhC,mCAAmC"}