@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -1,217 +1,991 @@
 import { assert } from "../../../core/assert.js";
-import { PARTICLE_RECORD_WORD_COUNT, PARTICLE_SIMULATE_WORKGROUP_SIZE } from "./ParticleConstants.js";
+import { align_4 } from "../../../core/binary/align_4.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { warn_limited } from "../../util/warn_limited.js";
 import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
-import { EMITTER_STRIDE, write_emitter_transform } from "./data/PARTICLE_EMITTER_LAYOUT.js";
+import {
+    PARTICLE_EMITTER_TICK_WORKGROUP_SIZE,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+    PARTICLE_SORT_BUCKET_COUNT,
+    PARTICLE_SPAWN_COMMAND_WORDS,
+    PARTICLE_VM_FAST_REGISTER_SLOTS,
+} from "./ParticleConstants.js";
 import { PARTICLE_COUNTER, PARTICLE_COUNTER_COUNT } from "./data/PARTICLE_COUNTERS.js";
+import { graph_particles_simulate } from "./graph_particles.js";
+import {
+    graph_particle_avboit_draw,
+    graph_particle_avboit_occupancy,
+    graph_particle_avboit_splat,
+} from "./graph_particles_avboit.js";
+import { graph_particles_billboard } from "./graph_particles_billboard.js";
+import { ParticleRenderMode } from "./ParticleRenderMode.js";
 import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
-import { ParticleSpawnScheduler } from "./runtime/ParticleSpawnScheduler.js";
+import { create_particle_billboard_pipeline } from "./shaders/shader_particle_render.js";
+import { graph_particle_sort } from "./sort/graph_particle_sort.js";
+
+const WORD = Uint32Array.BYTES_PER_ELEMENT;
+
+const STORAGE = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
+const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
 
 /**
- * The GPU particle system feature.
+ * The GPU particle system: a feature of a scene, in the mould of `ReSTIRDI` — construct once
+ * against a {@link GPUSceneContext}, and contribute the frame's passes through
+ * {@link execute}.
+ *
+ * ## What it owns
+ *
+ * Every piece of persistent GPU state: the particle pool, the ping-pong alive lists, the dead
+ * free-list, the counters, both indirect-args buffers, the simulation-order (coherence) scratch,
+ * the emitter database (the emitter table and the GPU-owned state table, one buffer), the packed
+ * program buffer, and the spawn-command ring. Buffers that depend on the emitter set — the
+ * coherence scratch on the number of distinct programs, the program buffer on the heap, the
+ * database on its own pages — are grown inside {@link execute}, the way ReSTIR's reservoirs follow
+ * the resolution. The render-order (sort) scratch is not in that list because it is not
+ * unconditional: see below.
+ *
+ * Every pass stays within the eight storage buffers a stage gets by default: the emitter record
+ * and the GPU-owned state are two tables of one database buffer, and the VM's constants and code
+ * are one packed buffer. The one exception is the wide-register fallback (below), whose emit and
+ * simulate passes bind a ninth for the register file — inside the ten the engine already demands of
+ * an adapter, but past the default.
+ *
+ * ## Two interpreters
+ *
+ * The VM's register file normally lives in shader registers, and is therefore small — see
+ * {@link ./ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS}. An effect whose compiled program
+ * needs more than it holds does not fail: the whole system swaps emit and simulate for variants
+ * that keep the file in a storage buffer, which is far slower and effectively unbounded. The choice
+ * is per-frame, whole-system, and made here — the registry reports `max_register_count` over the
+ * effects it holds and this is where that number meets the VM's; nothing about authoring a graph has
+ * a register ceiling.
+ *
+ * ## Emitters are scene nodes
+ *
+ * There is no `addEmitter`. A {@link ParticleEmitter} is a {@link Node3D}: put it in the scene —
+ * on its own or under a joint — and the next {@link execute} finds it in the scene's node list,
+ * gives it a row in the emitter table pointed at the `transforms` row the scene context gave the
+ * node, and it starts spawning. Take it out of the scene and its row is retired and its particles
+ * freed. The sweep runs only when the scene's membership version moves, which is how per-frame
+ * upkeep stays proportional to what changed rather than to how many emitters there are.
  *
- * Owns the persistent GPU state (particle pool, ping-pong alive lists, dead free-list, counters,
- * sort scratch, emitter/program/constant buffers, indirect args) and the CPU model (an
- * {@link EmitterRegistry}, a {@link ParticleSpawnScheduler} and bone attachments). Mirrors the
- * ReSTIR feature template: construct once, toggle with a flag, and contribute per-frame passes via
- * {@link encode}.
+ * ## Spawning is the GPU's decision
  *
- * ## Frame sequence (encode)
+ * The CPU never counts particles or walks emitters per frame. The emitter tick pass integrates
+ * every emitter's rate on the GPU, and the emit dispatch is sized by a prefix scan of what it
+ * decided. The host's one way to ask for particles is {@link spawn}: a burst queued into a small
+ * command list that a pass adds to the emitter's pending spawns, on the same path as everything
+ * else. See `graph_particles.js` for the frame.
  *
- * 1. reset counters (snapshot the previous alive count as this frame's simulate input, zero the new
- *    alive count)
- * 2. emit — run SPAWN for each scheduled spawn request (pop dead -> init -> append alive)
- * 3. simulate — one dispatch runs every emitter's UPDATE over the coherence list built last frame,
- *    compacting survivors into the new alive list and freed slots into the dead list
- * 4. bucket — regroup the new alive list by VM program, padded to whole workgroups, into the list
- *    NEXT frame's simulate consumes (`coherence/`)
- * 5. build indirect — derive next frame's simulate dispatch from the padded list length and this
- *    frame's render draw instance count from the alive count
- * 6. sort (optional) — histogram -> csdldf scan -> scatter to a back-to-front index list
- * 7. render — one instanced billboard draw over the sorted list
+ * ## Drawing, and the one thing the mode changes
  *
- * Steps 4 and 6 are two different orderings of the same particles and share nothing: the
- * simulation order is program-coherent and camera-independent, the render order is back-to-front
- * and changes with the camera. Separate buffers, separate passes, separate counter slots.
+ * {@link execute} is the whole per-frame call, once per frame. It always records everything that
+ * moves particles and leaves the alive list and the indirect draw args as graph handles; what it
+ * records after that is the {@link ParticleRenderMode} it was given.
  *
- * The alive lists ping-pong by frame parity, exactly like the ReSTIR reservoirs.
+ * `BILLBOARD` sorts the alive list back-to-front and draws it over a colour target, because
+ * premultiplied over-blending is order-dependent. `AVBOIT` records neither: under the renderer the
+ * system is an `AVBOITSideChannel`, and the transparency orchestrator asks it for its occupancy, its
+ * extinction and its draw at the three points where the transparent meshes have contributed theirs
+ * ({@link avboit_occupancy}, {@link avboit_splat}, {@link avboit_draw}). Those read the same handles
+ * and composite into a volume and a set of accumulators that are sums, so an ordering would buy
+ * nothing — and the sort is four passes and a scan over every live particle, plus two lists a word
+ * per particle each, which is why the mode also decides whether those buffers exist at all.
  *
- * ## CPU update
+ * ## Allocation
  *
- * {@link update} runs before encode: it patches bone-attached emitters' transforms from their scene
- * nodes and asks the scheduler for this frame's spawn requests (respecting cull/sleep). Keeping
- * spawn *counting* on the CPU (emitters are few) keeps the GPU emit pass a trivial one-thread-per-
- * particle kernel.
+ * The per-frame path allocates the frame graph's records and nothing else: emitter rows are
+ * staged through one shared record, spawn commands go into a preallocated ring, and the
+ * per-dispatch settings are reused objects. A command context is opened only on frames that have
+ * something to upload.
  */
 export class GPUParticleSystem {
+
+    /**
+     * Engine GraphicsContext.
+     * @type {object}
+     */
+    graphics;
+
+    /**
+     * The scene whose nodes the emitters are, and whose database their world matrices come from.
+     * @type {import("../scene/GPUSceneContext.js").GPUSceneContext}
+     */
+    scene_context;
+
+    /**
+     * Maximum number of simultaneously live particles.
+     * @type {number}
+     */
+    capacity;
+
+    /**
+     * @type {EmitterRegistry}
+     */
+    registry;
+
+    /**
+     * Frames elapsed. Drives the alive-list ping-pong and the VM's frame builtin.
+     * @type {number}
+     */
+    frame = 0;
+
+    /**
+     * Seconds since start, the VM's `TIME` builtin. Advanced by `dt` each {@link execute}.
+     * @type {number}
+     */
+    time = 0;
+
+    /**
+     * Cap on how much missed time a culled emitter makes up for when it comes back into view.
+     * @type {number}
+     */
+    max_catchup_seconds = 1;
+
+    /**
+     * View-depth range the render sort quantises: particles nearer than `[0]` share the front bin,
+     * farther than `[1]` the back one. Read only by {@link ParticleRenderMode.BILLBOARD}.
+     * @type {Float32Array}
+     */
+    sort_depth_range = new Float32Array([0.1, 100]);
+
+    /**
+     * Sprite atlas the billboards sample, and the sampler they sample it with. A 1x1 white texel by
+     * default, so an emitter with no art draws as a plain quad rather than nothing.
+     * @type {GPUTextureView}
+     */
+    atlas;
+
+    /** @type {GPUSampler} */
+    atlas_sampler;
+
+    /**
+     * The persistent GPU buffers, by the names the graph functions bind them under. Exposed for
+     * inspection — a harness copying the counters out to display them — never for the frame loop,
+     * which reads nothing back. Entries that grow with the emitter set are replaced in place.
+     *
+     * @type {object}
+     */
+    buffers = {};
+
+    /**
+     * Distinct programs the coherence scratch is currently sized for.
+     * @type {number}
+     */
+    #sim_bucket_capacity = 0;
+
+    /**
+     * The spawn-command ring: `[row, count]` pairs, filled by {@link spawn}, merged and uploaded on
+     * the next {@link execute}.
+     * @type {Uint32Array}
+     */
+    #spawn_commands;
+
+    /**
+     * The emitter each ring entry was issued for, so an entry whose emitter has since left the
+     * scene — or whose row has gone to somebody else — is dropped at upload rather than delivered
+     * to the row's next tenant.
+     * @type {import("./runtime/ParticleEmitter.js").ParticleEmitter[]}
+     */
+    #spawn_command_emitters;
+
+    /** @type {number} */
+    #spawn_command_count = 0;
+
+    /**
+     * Scratch for merging the ring: pending count by row. Grown with the emitter table, never per
+     * frame.
+     * @type {Uint32Array}
+     */
+    #spawn_by_row = new Uint32Array(0);
+
+    /**
+     * Emitter node -> the sweep that last saw it in the scene.
+     * @type {Map<import("./runtime/ParticleEmitter.js").ParticleEmitter, number>}
+     */
+    #swept = new Map();
+
+    /** @type {number} */
+    #sweep = 0;
+
+    /**
+     * The 1x1 white texture {@link atlas} points at until a caller replaces it. Held so
+     * {@link destroy} can free it; a caller that assigns its own atlas owns that one.
+     * @type {GPUTexture|null}
+     */
+    #default_atlas = null;
+
+    /**
+     * The scene membership version the emitter set was last reconciled against.
+     * @type {number}
+     */
+    #instances_version = -1;
+
+    /** @type {object|null} */
+    #pipeline = null;
+
+    /** @type {string} */
+    #pipeline_key = "";
+
+    /**
+     * Per-frame scalars handed to {@link graph_particles_simulate}, reused rather than rebuilt.
+     * @type {object}
+     */
+    #frame = {
+        dt: 0, time: 0, index: 0, max_catchup: 1, spawn_command_count: 0,
+    };
+
+    /** @type {{capacity: number, group_count: number}} */
+    #emitters = { capacity: 0, group_count: 0 };
+
+    /**
+     * This frame's simulation, for the draw that follows it: the graph it was recorded into, the
+     * scene database handle it read, and the handles it produced. Reused, never reallocated.
+     * @type {{graph: object|null, scene_database: number, emitter_group_count: number, handles: object|null}}
+     */
+    #simulated = { graph: null, scene_database: -1, emitter_group_count: 0, handles: null };
+
+    /** @type {object} */
+    #render = {
+        atlas: null,
+        atlas_sampler: null,
+        obtain_pipeline: (color_format, depth_format) => this.#obtain_pipeline(color_format, depth_format),
+    };
+
     /**
      * @param {object} graphics engine GraphicsContext (has `.device`)
+     * @param {import("../scene/GPUSceneContext.js").GPUSceneContext} scene_context
      * @param {object} [options]
      * @param {number} [options.capacity] max simultaneous particles
+     * @param {number} [options.spawn_command_capacity] most {@link spawn} calls one frame keeps
      */
-    constructor(graphics, { capacity = 1 << 16 } = {}) {
+    constructor(graphics, scene_context, { capacity = 1 << 16, spawn_command_capacity = 256 } = {}) {
         assert.defined(graphics, "graphics");
+        assert.defined(scene_context, "scene_context");
+        assert.equal(scene_context.isGPUSceneContext, true, "scene_context.isGPUSceneContext !== true");
         assert.isPositiveInteger(capacity, "capacity");
+        assert.isPositiveInteger(spawn_command_capacity, "spawn_command_capacity");
 
         this.graphics = graphics;
+        this.scene_context = scene_context;
         this.capacity = capacity;
 
-        this.registry = new EmitterRegistry();
-        this.scheduler = new ParticleSpawnScheduler();
+        this.registry = new EmitterRegistry(graphics.device);
 
-        /** @type {Map<number, object>} emitter index -> scene Node3D */
-        this.attachments = new Map();
+        this.#spawn_commands = new Uint32Array(spawn_command_capacity * PARTICLE_SPAWN_COMMAND_WORDS);
+        this.#spawn_command_emitters = new Array(spawn_command_capacity).fill(null);
 
-        /** @type {number} */
-        this.frame = 0;
+        this.#create_buffers();
+        this.#create_default_atlas();
+    }
 
-        /** built lazily on first encode */
-        this.buffers = undefined;
-        /** CPU shadow of the packed emitter buffer (for in-place transform patching) */
-        this.emitter_cpu = undefined;
-        this.emitters_dirty = true;
-        /**
-         * Distinct compiled programs across the emitter set — the number of buckets the coherence
-         * pass sorts into. Known only after {@link buildEmitterData}; until then the emitter count
-         * is a safe upper bound (programs can be shared, never invented).
-         * @type {number|undefined}
-         */
-        this.program_count = undefined;
+    /**
+     * The buffer the emitter table lives in — what every emitter-reading pass binds.
+     * @returns {GPUBuffer}
+     */
+    get emitter_database() {
+        return this.registry.database.buffer;
     }
 
     /**
-     * Register an emitter.
-     * @param {object} config see {@link EmitterRegistry#add}
-     * @returns {number} emitter index
+     * The live emitters, in no particular order.
+     * @returns {import("./runtime/ParticleEmitter.js").ParticleEmitter[]}
      */
-    addEmitter(config) {
-        const index = this.registry.add(config);
-        this.emitters_dirty = true;
-        return index;
+    get emitters() {
+        return this.registry.emitters;
     }
 
     /**
-     * Attach an emitter to a scene node (bone). Each frame the emitter's transform is copied from
-     * `node.transform_global.matrix` so it follows the bone.
-     * @param {number} emitter_index
-     * @param {object} node a Node3D with `transform_global.matrix` (column-major 16)
+     * Number of simulation-order buckets — one per program id the registry can hand out, which is
+     * its peak number of distinct compiled programs rather than its current one.
+     *
+     * This is the coherence pass's only host-provided number, and it is static topology rather than
+     * per-frame state: it changes when an effect the set has never held is registered, not as
+     * particles are born and die. Everything the pass measures per frame stays on the GPU. Sizing it
+     * from the peak rather than the live count is what keeps it from moving every time an effect is
+     * unregistered — the bins of released ids are empty, and an empty bin rounds up to zero
+     * workgroups and shifts nothing after it.
+     *
+     * @returns {number}
      */
-    attachToNode(emitter_index, node) {
-        this.attachments.set(emitter_index, node);
+    bucketCount() {
+        return Math.max(1, this.registry.program_id_capacity);
     }
 
     /**
-     * Per-frame CPU preparation. Returns the spawn requests for this frame.
+     * Index of the alive list this frame reads from / writes to (ping-pong by frame parity).
+     * @returns {number}
+     */
+    get alive_write_index() {
+        return 1 - (this.frame % 2);
+    }
+
+    /**
+     * Ask for `count` particles from an emitter, on top of its rate, on the next frame. Goes
+     * through the GPU path — the tick pass folds it into the emitter's accumulator, the budget and
+     * the culling apply — so it is a request, not a guarantee.
      *
-     * @param {number} dt seconds
-     * @param {object} [context]
-     * @param {(emitterIndex: number) => boolean} [context.is_visible] cull predicate (sleep-culling)
-     * @returns {Uint32Array} spawn requests (emitter index per particle to create)
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter a registered emitter
+     * @param {number} count
      */
-    update(dt, { is_visible } = {}) {
-        // Bone attachment: patch attached emitters' transforms from their scene nodes.
-        if (this.emitter_cpu !== undefined && this.attachments.size > 0) {
-            const f32 = new Float32Array(this.emitter_cpu.buffer);
-            for (const [index, node] of this.attachments) {
-                const matrix = node?.transform_global?.matrix;
-                if (matrix !== undefined) {
-                    write_emitter_transform(f32, index, matrix);
-                }
-            }
+    spawn(emitter, count) {
+        assert.defined(emitter, "emitter");
+        assert.isNonNegativeInteger(count, "count");
+
+        const context = this.registry.context(emitter);
+
+        assert.defined(context, "emitter is not in the scene");
+
+        const ring = this.#spawn_commands;
+        const base = this.#spawn_command_count * PARTICLE_SPAWN_COMMAND_WORDS;
+
+        if (base >= ring.length) {
+            // the text is the key warn_limited counts on, so it carries no burst size: one message
+            // per ring size, not one per number a caller happens to ask for
+            warn_limited(`GPUParticleSystem: spawn command ring is full (${ring.length / PARTICLE_SPAWN_COMMAND_WORDS} per frame); dropping this frame's remaining bursts`);
+            return;
         }
 
-        const requests = this.scheduler.tick(this.registry.emitters, dt, is_visible, this.capacity);
+        ring[base] = context.row;
+        ring[base + 1] = count;
+        this.#spawn_command_emitters[this.#spawn_command_count] = emitter;
+        this.#spawn_command_count++;
+    }
+
+    /**
+     * The simulation half of the frame: reconcile the emitter set with the scene, push what changed
+     * to the GPU, and record every pass that moves particles — through to the indirect draw args.
+     * What it leaves as graph handles is what a draw consumes, whichever draw that turns out to be.
+     *
+     * @param {object} params see {@link execute}
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+     * @param {number} params.camera
+     * @param {number} params.scene_database
+     * @param {number} params.dt
+     * @returns {import("./graph_particles.js").ParticleSimulationHandles}
+     */
+    #simulate({ graph, camera, scene_database, dt }) {
+        this.#sync_membership();
+        this.#upload();
+
+        const frame = this.#frame;
+        frame.dt = dt;
+        frame.time = this.time;
+        frame.index = this.frame;
+        frame.max_catchup = this.max_catchup_seconds;
+        frame.spawn_command_count = this.#spawn_command_count;
+
+        const table = this.registry.table;
+        const emitters = this.#emitters;
+        emitters.capacity = table.element_capacity;
+        emitters.group_count = table.dispatch_group_count(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE);
+
+        const buffers = this.buffers;
+        buffers.alive_write = buffers.alive[this.alive_write_index];
+        // The table's database owns and grows its own buffer; it is re-read every frame for that
+        // reason.
+        buffers.emitter_database = this.registry.database.buffer;
+
+        const simulated = graph_particles_simulate({
+            graph,
+            camera,
+            scene_database,
+            gpu: buffers,
+            emitters,
+            capacity: this.capacity,
+            bucket_count: this.bucketCount(),
+            // Whose register file the VM runs on is decided here, once, for the whole system: the
+            // registry reports what the hungriest registered effect needs and this compares it
+            // against what the fast file holds. Re-read every frame because registering an emitter —
+            // or unregistering the one hungry effect — can flip it either way.
+            wide_registers: this.registry.max_register_count > PARTICLE_VM_FAST_REGISTER_SLOTS,
+            frame,
+        });
+
+        // Kept for the draw that follows, whichever it is, and for nothing past this frame.
+        const current = this.#simulated;
+        current.graph = graph;
+        current.scene_database = scene_database;
+        current.emitter_group_count = emitters.group_count;
+        current.handles = simulated;
+
+        // Consumed: the count was recorded into the graph, the words were uploaded.
+        this.#spawn_command_count = 0;
+
         this.frame++;
-        return requests;
+        this.time += dt;
+
+        return simulated;
     }
 
     /**
-     * Rebuild the packed emitter/program/constant buffers when the emitter set changes.
-     * @returns {{emitters: Uint32Array, program: Uint32Array, constants: Uint32Array}}
+     * The system's whole contribution to the frame: the simulation, then whatever `mode` says draws
+     * it.
+     *
+     * {@link ParticleRenderMode.BILLBOARD} adds the depth sort and one billboard draw over `color`
+     * with fixed-function blending, for a page with no transparency pipeline of its own.
+     * {@link ParticleRenderMode.AVBOIT} adds nothing: the orchestrator draws the particles later in
+     * the frame through {@link avboit_occupancy}, {@link avboit_splat} and {@link avboit_draw}, off
+     * the handles this just produced, and its accumulators are order-independent — so the sort is
+     * skipped and its buffers are never allocated. `color` comes straight back either way, so a
+     * caller can assign the result unconditionally and let the mode be the only difference.
+     *
+     * Call after the scene context has built for the frame (`GPUSceneContext#update`), so every
+     * emitter node has its `transforms` row, and after the hierarchy pass has run, so the rows'
+     * `global` matrices are this frame's.
+     *
+     * **Once per frame, not once per view.** This advances the simulation by `dt` and hands out
+     * handles into the graph it recorded into; a second view of the same scene records a second
+     * graph and would step the simulation twice. The renderer has one view per `render` call today,
+     * so this holds by construction; a second view of one scene needs the step and the handles
+     * separated — record the passes for the first graph, import the same buffers into the rest.
+     *
+     * @param {object} params
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+     * @param {number} params.camera graph handle of the camera uniform buffer
+     * @param {number} params.scene_database graph handle of the scene database — the one the
+     *   hierarchy pass returned, so this reads the matrices it composed
+     * @param {number} params.dt seconds since the previous frame
+     * @param {ParticleRenderMode} [params.mode] who draws, and so whether there is a sort
+     * @param {number} [params.color] graph handle of the colour target to draw over. Required by
+     *   `BILLBOARD`; returned untouched by `AVBOIT`
+     * @param {number} [params.depth] graph handle of the scene depth (tested, never written).
+     *   Required by `BILLBOARD`
+     * @returns {number|undefined} the colour handle after the particle draw, or `color` unchanged
      */
-    buildEmitterData() {
-        const built = this.registry.build();
-        this.emitter_cpu = built.emitters;
-        this.program_count = built.program_count;
-        this.emitters_dirty = false;
-        return built;
+    execute({ graph, camera, scene_database, color, depth, dt, mode = ParticleRenderMode.BILLBOARD }) {
+        assert.defined(graph, "graph");
+        assert.isNumber(dt, "dt");
+        assert.enum(mode, ParticleRenderMode, "mode");
+
+        const billboard = mode === ParticleRenderMode.BILLBOARD;
+
+        // Checked before the simulation rather than at the draw: the simulation advances `frame` and
+        // `time` and writes the pool, and a throw after that leaves a frame half-stepped.
+        if (billboard) {
+            assert.isNonNegativeInteger(color, "color");
+            assert.isNonNegativeInteger(depth, "depth");
+        }
+
+        const simulated = this.#simulate({ graph, camera, scene_database, dt });
+
+        if (!billboard) {
+            // AVBOIT: the side channels draw these handles later in the frame, and the colour target
+            // is not this call's to touch.
+            return color;
+        }
+
+        // Allocated here rather than in the constructor: they are two words per particle plus the
+        // bins, and only this mode ever reads them. A system the renderer drives never makes them.
+        this.#ensure_sort_buffers();
+
+        // The render order: back-to-front by view depth, so premultiplied transparency composites
+        // correctly. Its two per-particle passes take the dispatch the coherence reset wrote from
+        // the GPU's own alive count.
+        const sorted = graph_particle_sort({
+            graph,
+            gpu: this.buffers,
+            camera,
+            emitter_database: simulated.emitter_database,
+            pool: simulated.pool,
+            alive: simulated.alive,
+            counters: simulated.counters,
+            dispatch_args: simulated.sim_dispatch_args,
+            bucket_count: PARTICLE_SORT_BUCKET_COUNT,
+            near: this.sort_depth_range[0],
+            far: this.sort_depth_range[1],
+        });
+
+        const render = this.#render;
+        render.atlas = this.atlas;
+        render.atlas_sampler = this.atlas_sampler;
+
+        // One instanced billboard draw over the sorted list, sized by the draw args this frame's
+        // build-indirect wrote.
+        return graph_particles_billboard({
+            graph,
+            camera,
+            color,
+            depth,
+            pool: simulated.pool,
+            draw_list: sorted,
+            emitter_database: simulated.emitter_database,
+            draw_args: simulated.draw_args,
+            render,
+        });
     }
 
     /**
-     * Number of simulation-order buckets — one per distinct compiled program.
+     * What this frame's {@link simulate} left, checked against the graph a side-channel call names:
+     * the AVBOIT orchestrator records its passes into the same graph, later in the same frame.
      *
-     * This is the coherence pass's only host-provided number, and it is static topology rather than
-     * per-frame state: it changes when the emitter set changes, not as particles are born and die.
-     * Everything the pass measures per frame stays on the GPU.
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
+     * @returns {{graph: object, scene_database: number, emitter_group_count: number, handles: import("./graph_particles.js").ParticleSimulationHandles}}
+     */
+    #simulated_for(graph) {
+        const current = this.#simulated;
+
+        assert.equal(current.graph, graph, "the particles were not simulated into this graph this frame — call execute() before the transparency pipeline records");
+
+        return current;
+    }
+
+    /**
+     * `AVBOITSideChannel#avboit_occupancy`: the emitters' bounds spheres, as depth slices.
      *
-     * @returns {number}
+     * @param {object} args see `AVBOITSideChannel`
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} args.graph
+     * @param {number} args.camera graph handle of the camera uniform buffer
+     * @param {ArrayLike<number>} args.cluster_parameters the frame's depth curve
+     * @param {number} args.occupancy graph handle of the occupancy bits
+     * @returns {number} the occupancy handle after the write
      */
-    bucketCount() {
-        return Math.max(1, this.program_count ?? this.registry.count);
+    avboit_occupancy({ graph, camera, cluster_parameters, occupancy }) {
+        const current = this.#simulated_for(graph);
+
+        return graph_particle_avboit_occupancy({
+            graph,
+            camera,
+            cluster_parameters,
+            occupancy,
+            scene_database: current.scene_database,
+            emitter_database: current.handles.emitter_database,
+            emitter_group_count: current.emitter_group_count,
+        });
+    }
+
+    /**
+     * `AVBOITSideChannel#avboit_splat`: the live particles' extinction, into the volume.
+     *
+     * @param {object} args see `AVBOITSideChannel`
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} args.graph
+     * @param {number} args.camera graph handle of the camera uniform buffer
+     * @param {number} args.warp graph handle of the warp LUT
+     * @param {number} args.depth_texture graph handle of the scene depth
+     * @param {{extinction: number, overflow: number, dummy: number}} args.volume the voxel volume
+     * @returns {{extinction: number, overflow: number, dummy: number}} the volume after the write
+     */
+    avboit_splat({ graph, camera, warp, depth_texture, volume }) {
+        const { handles } = this.#simulated_for(graph);
+
+        return graph_particle_avboit_splat({
+            graph,
+            camera,
+            warp,
+            depth_texture,
+            volume,
+            atlas: this.atlas,
+            atlas_sampler: this.atlas_sampler,
+            pool: handles.pool,
+            alive: handles.alive,
+            emitter_database: handles.emitter_database,
+            draw_args: handles.draw_args,
+        });
     }
 
     /**
-     * Sizes of the persistent buffers, in bytes. Exposed for tests and allocation.
-     * @returns {object}
+     * `AVBOITSideChannel#avboit_draw`: the live particles, into the accumulators.
+     *
+     * @param {object} args see `AVBOITSideChannel`
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} args.graph
+     * @param {import("../view/GPUViewContext.js").GPUViewContext} args.view_ctx
+     * @param {number} args.camera graph handle of the camera uniform buffer
+     * @param {number} args.depth_texture graph handle of the scene depth
+     * @param {number} args.warp graph handle of the warp LUT
+     * @param {number} args.integral graph handle of the integral texture
+     * @param {number} args.volumetrics_lut graph handle
+     * @param {number} args.volumetrics_metadata graph handle
+     * @param {{color: number, norm: number, extinction: number, emission: number}} args.accumulators
+     * @returns {{color: number, norm: number, extinction: number, emission: number}} after the draw
      */
-    bufferSizes() {
-        const u32 = 4;
-        const buckets = this.bucketCount();
-
-        return {
-            pool: this.capacity * PARTICLE_RECORD_WORD_COUNT * u32,
-            alive_list: this.capacity * u32,
-            dead_list: this.capacity * u32,
-            counters: PARTICLE_COUNTER_COUNT * u32,
-            // render order (sort/)
-            sorted: this.capacity * u32,
-            keys: this.capacity * u32,
-            emitter_record: EMITTER_STRIDE * u32,
-
-            // simulation order (coherence/) — a separate set of buffers on purpose; sharing any of
-            // them with the render order would couple a camera-driven ordering to a program-driven
-            // one.
-            //
-            // Padding rounds each bucket up to a whole workgroup, so it can add at most
-            // `workgroup - 1` entries per bucket; one whole workgroup per bucket is the bound.
-            sim_list: (this.capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * u32,
-            sim_keys: this.capacity * u32,
-            // `{count, elements}` for the CSDLDF scan; the scan reads whole vec4s, so the bins are
-            // rounded up to a multiple of four.
-            sim_histogram: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(buckets)) * u32,
-            sim_bucket_counts: buckets * u32,
-            sim_cursor: buckets * u32,
-            sim_dispatch_args: 3 * u32,
-        };
-    }
-
-    /**
-     * The initial dead-list contents (all slots free) and counter values for a fresh pool.
-     * @returns {{dead: Uint32Array, counters: Uint32Array}}
-     */
-    initialFreeList() {
-        const dead = new Uint32Array(this.capacity);
-        for (let i = 0; i < this.capacity; i++) {
+    avboit_draw({ graph, view_ctx, camera, depth_texture, warp, integral, volumetrics_lut, volumetrics_metadata, accumulators }) {
+        const { handles } = this.#simulated_for(graph);
+
+        return graph_particle_avboit_draw({
+            graph,
+            view_ctx,
+            camera,
+            depth_texture,
+            warp,
+            integral,
+            volumetrics_lut,
+            volumetrics_metadata,
+            accumulators,
+            atlas: this.atlas,
+            atlas_sampler: this.atlas_sampler,
+            pool: handles.pool,
+            alive: handles.alive,
+            emitter_database: handles.emitter_database,
+            draw_args: handles.draw_args,
+        });
+    }
+
+    /**
+     * Bring the emitter set in line with the scene: emitter nodes that arrived get rows, nodes that
+     * left give theirs back. Runs only when the scene's membership version has moved.
+     *
+     * A node the scene context has not placed yet (no `transforms` row) is left for the next frame,
+     * and the version is not recorded, so the sweep runs again until every emitter is bound.
+     */
+    #sync_membership() {
+        const scene = this.scene_context.scene;
+        const batch = scene.instances;
+
+        if (batch.version === this.#instances_version) {
+            return;
+        }
+
+        const sweep = ++this.#sweep;
+        const nodes = batch.nodes;
+        const node_count = nodes.length;
+        const mapping = this.scene_context.id_mapping;
+        const registry = this.registry;
+        const swept = this.#swept;
+
+        let complete = true;
+
+        for (let i = 0; i < node_count; i++) {
+            const node = nodes[i];
+
+            if (node.isParticleEmitter !== true) {
+                continue;
+            }
+
+            const transform_row = mapping.get(node.id);
+
+            if (transform_row === undefined) {
+                complete = false;
+                continue;
+            }
+
+            if (registry.context(node) === undefined) {
+                registry.add(node, transform_row);
+            } else {
+                registry.set_transform_row(node, transform_row);
+            }
+
+            swept.set(node, sweep);
+        }
+
+        for (const [emitter, seen] of swept) {
+            if (seen !== sweep) {
+                registry.remove(emitter);
+                swept.delete(emitter);
+            }
+        }
+
+        if (complete) {
+            this.#instances_version = batch.version;
+        }
+    }
+
+    /**
+     * Push everything the CPU changed to the GPU: dirty emitter rows, the state buffer's growth,
+     * rebuilt program buffers, the spawn-command ring, and the coherence scratch's growth. A
+     * command context is opened only if something needs one.
+     */
+    #upload() {
+        const registry = this.registry;
+        const device = this.graphics.device;
+
+        registry.flush();
+
+        // Both tables stage into the one database: the emitter rows the author changed, and the
+        // state rows claimed or released with them.
+        const rows_staged = registry.table.element_upload_buffer.position > 0
+            || registry.state_table.element_upload_buffer.position > 0;
+
+        if (rows_staged) {
+            const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/upload");
+
+            registry.database.update(cmd);
+
+            cmd.finish();
+        }
+
+        if (registry.programs_dirty) {
+            this.buffers.program = replace_data_buffer(device, this.buffers.program, "particles/program", registry.build_program());
+        }
+
+        this.#merge_spawn_commands();
+
+        if (this.#spawn_command_count > 0) {
+            device.queue.writeBuffer(
+                this.buffers.spawn_commands, 0,
+                this.#spawn_commands.buffer, 0,
+                this.#spawn_command_count * PARTICLE_SPAWN_COMMAND_WORDS * WORD,
+            );
+        }
+
+        this.#ensure_sim_buffers(this.bucketCount());
+    }
+
+    /**
+     * Fold the ring down to one entry per row, dropping entries whose emitter no longer holds the
+     * row it was issued against.
+     *
+     * The spawn-command pass adds to a state row with a plain read-modify-write, so two entries
+     * naming one row would lose one; and a burst issued to an emitter that left the scene this
+     * frame must not land on the row's next tenant. Both are settled here, in place, over a few
+     * dozen entries at most.
+     */
+    #merge_spawn_commands() {
+        const count = this.#spawn_command_count;
+
+        if (count === 0) {
+            return;
+        }
+
+        const ring = this.#spawn_commands;
+        const emitters = this.#spawn_command_emitters;
+
+        let rows = this.#spawn_by_row;
+        const needed = Math.max(1, this.registry.table.element_capacity);
+
+        if (rows.length < needed) {
+            rows = new Uint32Array(needed);
+            this.#spawn_by_row = rows;
+        }
+
+        for (let i = 0; i < count; i++) {
+            const emitter = emitters[i];
+            const row = ring[i * PARTICLE_SPAWN_COMMAND_WORDS];
+            const context = this.registry.context(emitter);
+
+            if (context !== undefined && context.row === row) {
+                rows[row] += ring[i * PARTICLE_SPAWN_COMMAND_WORDS + 1];
+            }
+
+            emitters[i] = null;
+        }
+
+        let merged = 0;
+
+        for (let i = 0; i < count; i++) {
+            const row = ring[i * PARTICLE_SPAWN_COMMAND_WORDS];
+            const pending = rows[row];
+
+            if (pending === 0) {
+                continue;
+            }
+
+            ring[merged * PARTICLE_SPAWN_COMMAND_WORDS] = row;
+            ring[merged * PARTICLE_SPAWN_COMMAND_WORDS + 1] = pending;
+            rows[row] = 0;
+            merged++;
+        }
+
+        this.#spawn_command_count = merged;
+    }
+
+    /**
+     * The simulation-order scratch is sized from the number of distinct programs, which only ever
+     * grows (programs are never reclaimed, see {@link EmitterRegistry}). Reallocated when it does;
+     * nothing in these buffers outlives a frame, so nothing is copied.
+     *
+     * @param {number} buckets
+     */
+    #ensure_sim_buffers(buckets) {
+        if (buckets <= this.#sim_bucket_capacity) {
+            return;
+        }
+
+        const device = this.graphics.device;
+        const buffers = this.buffers;
+        const capacity = this.capacity;
+
+        for (const name of ["sim_list", "sim_keys", "sim_histogram", "sim_bucket_counts", "sim_cursor"]) {
+            buffers[name]?.destroy();
+        }
+
+        // Padding rounds each bucket up to a whole workgroup, so it can add at most `workgroup - 1`
+        // entries per bucket; one whole workgroup per bucket is the bound.
+        buffers.sim_list = device.createBuffer({ label: "particles/sim_list", size: (capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * WORD, usage: STORAGE });
+        buffers.sim_keys = device.createBuffer({ label: "particles/sim_keys", size: capacity * WORD, usage: STORAGE });
+        // `{count, elements}` for the CSDLDF scan; the scan reads whole vec4s, so the bins are
+        // rounded up to a multiple of four.
+        buffers.sim_histogram = device.createBuffer({ label: "particles/sim_histogram", size: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(buckets)) * WORD, usage: STORAGE });
+        buffers.sim_bucket_counts = device.createBuffer({ label: "particles/sim_bucket_counts", size: buckets * WORD, usage: STORAGE });
+        buffers.sim_cursor = device.createBuffer({ label: "particles/sim_cursor", size: buckets * WORD, usage: STORAGE });
+
+        this.#sim_bucket_capacity = buckets;
+    }
+
+    /**
+     * The render-order scratch, made on the first frame that actually sorts.
+     *
+     * Only {@link ParticleRenderMode.BILLBOARD} reads any of it, and the two per-particle lists are
+     * a word per particle each — at the renderer's default capacity, half a megabyte that AVBOIT
+     * would never touch. Nothing in them outlives a frame, so there is nothing to carry over and the
+     * first sorted frame is as correct as any later one.
+     */
+    #ensure_sort_buffers() {
+        const buffers = this.buffers;
+
+        if (buffers.sorted !== undefined) {
+            return;
+        }
+
+        const device = this.graphics.device;
+        const capacity = this.capacity;
+
+        buffers.sorted = device.createBuffer({ label: "particles/sorted", size: capacity * WORD, usage: STORAGE });
+        buffers.sort_keys = device.createBuffer({ label: "particles/sort_keys", size: capacity * WORD, usage: STORAGE });
+        buffers.sort_histogram = device.createBuffer({ label: "particles/sort_histogram", size: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(PARTICLE_SORT_BUCKET_COUNT)) * WORD, usage: STORAGE });
+        buffers.sort_cursor = device.createBuffer({ label: "particles/sort_cursor", size: PARTICLE_SORT_BUCKET_COUNT * WORD, usage: STORAGE });
+    }
+
+    /**
+     * The buffers whose size is fixed by the pool capacity, and the free list's initial contents.
+     */
+    #create_buffers() {
+        const device = this.graphics.device;
+        const capacity = this.capacity;
+        const buffers = this.buffers;
+
+        buffers.pool = device.createBuffer({ label: "particles/pool", size: capacity * PARTICLE_RECORD_WORD_COUNT * WORD, usage: STORAGE });
+        buffers.alive = [
+            device.createBuffer({ label: "particles/alive_a", size: capacity * WORD, usage: STORAGE }),
+            device.createBuffer({ label: "particles/alive_b", size: capacity * WORD, usage: STORAGE }),
+        ];
+        buffers.dead = device.createBuffer({ label: "particles/dead", size: capacity * WORD, usage: STORAGE });
+        buffers.counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * WORD, usage: STORAGE });
+
+        // Indirect args, written on-GPU. Zero-initialised (WebGPU spec), so the first frame's
+        // indirect dispatch/draw are no-ops until the first build-indirect has run.
+        buffers.dispatch_args = device.createBuffer({ label: "particles/dispatch_args", size: 3 * WORD, usage: INDIRECT });
+        buffers.draw_args = device.createBuffer({ label: "particles/draw_args", size: 4 * WORD, usage: INDIRECT });
+        buffers.sim_dispatch_args = device.createBuffer({ label: "particles/sim_dispatch_args", size: 3 * WORD, usage: INDIRECT });
+
+        buffers.spawn_commands = device.createBuffer({ label: "particles/spawn_commands", size: this.#spawn_commands.byteLength, usage: STORAGE });
+
+        // Every slot free, and the counters saying so.
+        const dead = new Uint32Array(capacity);
+        for (let i = 0; i < capacity; i++) {
             dead[i] = i;
         }
         const counters = new Uint32Array(PARTICLE_COUNTER_COUNT);
-        counters[PARTICLE_COUNTER.DEAD] = this.capacity;
-        return { dead, counters };
+        counters[PARTICLE_COUNTER.DEAD] = capacity;
+
+        device.queue.writeBuffer(buffers.dead, 0, dead);
+        device.queue.writeBuffer(buffers.counters, 0, counters);
     }
 
     /**
-     * Index of the alive list this frame reads from / writes to (ping-pong by frame parity).
-     * @returns {{read: number, write: number}}
+     * A 1x1 white atlas and a linear sampler, so the system draws before anyone hands it art.
      */
-    aliveListIndices() {
-        const read = this.frame % 2;
-        return { read, write: 1 - read };
+    #create_default_atlas() {
+        const device = this.graphics.device;
+
+        const texture = device.createTexture({
+            label: "particles/default_atlas",
+            size: [1, 1],
+            format: "rgba8unorm",
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+
+        device.queue.writeTexture({ texture }, new Uint8Array([255, 255, 255, 255]), { bytesPerRow: 4 }, [1, 1]);
+
+        // kept, not just viewed: a texture nothing holds is a texture nothing can free
+        this.#default_atlas = texture;
+        this.atlas = texture.createView();
+        this.atlas_sampler = device.createSampler({
+            label: "particles/atlas_sampler",
+            magFilter: "linear",
+            minFilter: "linear",
+            addressModeU: "clamp-to-edge",
+            addressModeV: "clamp-to-edge",
+        });
+    }
+
+    /**
+     * @param {string} color_format
+     * @param {string} depth_format
+     * @returns {object} the billboard pipeline descriptor for these attachment formats
+     */
+    #obtain_pipeline(color_format, depth_format) {
+        const key = `${color_format}/${depth_format}`;
+
+        if (this.#pipeline === null || this.#pipeline_key !== key) {
+            this.#pipeline = create_particle_billboard_pipeline({
+                color_format,
+                depth_format,
+                // reverse-Z, the engine convention
+                depth_compare: "greater",
+            });
+            this.#pipeline_key = key;
+        }
+
+        return this.#pipeline;
+    }
+
+    /**
+     * Sizes of the persistent buffers, in bytes, as they stand. Exposed for tests.
+     * @returns {Object<string, number>}
+     */
+    bufferSizes() {
+        const sizes = {};
+
+        for (const [name, buffer] of Object.entries(this.buffers)) {
+            if (Array.isArray(buffer)) {
+                sizes[name] = buffer[0].size;
+            } else if (buffer !== undefined && buffer !== null) {
+                sizes[name] = buffer.size;
+            }
+        }
+
+        return sizes;
+    }
+
+    destroy() {
+        /*
+         The emitters go first, and they matter more than the buffers: they are the scene's nodes,
+         they outlive this system, and each is holding a row of the table about to be freed. A node
+         left holding one is stranded — the next system's membership sweep reads `row !== -1` as
+         "already mine", takes the moved branch rather than the arrived one, and never registers it.
+         Retiring them here puts every emitter back where it was before this system saw it.
+        */
+        for (const emitter of this.registry.emitters.slice()) {
+            this.registry.remove(emitter);
+        }
+        this.#swept.clear();
+        this.#instances_version = -1;
+
+        for (const buffer of Object.values(this.buffers)) {
+            if (Array.isArray(buffer)) {
+                buffer.forEach((b) => b.destroy());
+            } else if (buffer !== undefined && buffer !== null) {
+                buffer.destroy();
+            }
+        }
+
+        this.buffers = {};
+        this.registry.database.destroy();
+
+        // the default atlas is this system's own; a page that replaced it owns what it put there
+        this.#default_atlas?.destroy();
+        this.#default_atlas = null;
     }
 }
 
 /**
- * @param {number} value
- * @returns {number} `value` rounded up to a multiple of four
+ * A storage buffer holding `data`, replacing `previous` (destroyed) if it exists. The program
+ * buffer is monolithic — a program is variable-length, so there is no table to page it into — and
+ * is rebuilt whole on the rare frame the program heap changes.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUBuffer|undefined} previous
+ * @param {string} label
+ * @param {Uint32Array} data
+ * @returns {GPUBuffer}
  */
-function round_up_4(value) {
-    return (value + 3) & ~3;
+function replace_data_buffer(device, previous, label, data) {
+    previous?.destroy();
+
+    const buffer = device.createBuffer({ label, size: Math.max(WORD, data.byteLength), usage: STORAGE });
+
+    device.queue.writeBuffer(buffer, 0, data);
+
+    return buffer;
 }