@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -1,27 +1,60 @@
+import { assert } from "../../../core/assert.js";
+import { align_4 } from "../../../core/binary/align_4.js";
+import { noop } from "../../../core/function/noop.js";
+import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
+import { TextureViewDescriptor } from "../../descriptor/texture/TextureViewDescriptor.js";
+import { DEFAULT_DEPTH_TEXTURE_VIEW } from "../depth/DEFAULT_DEPTH_TEXTURE_VIEW.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_import_buffer } from "../shader/graph/graph_import_buffer.js";
 import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "./ParticleConstants.js";
 import { graph_particle_bucket } from "./coherence/graph_particle_bucket.js";
-import { PARTICLE_EMIT_WORKGROUP_SIZE, shader_particle_emit } from "./shaders/shader_particle_emit.js";
+import { shader_particle_emit } from "./shaders/shader_particle_emit.js";
+import { shader_particle_emitter_tick } from "./shaders/shader_particle_emitter_tick.js";
 import {
     shader_particle_build_indirect,
     shader_particle_reset_counters,
 } from "./shaders/shader_particle_finalize.js";
+import { PARTICLE_BILLBOARD_RESOURCES } from "./shaders/shader_particle_render.js";
 import { shader_particle_simulate } from "./shaders/shader_particle_simulate.js";
+import {
+    PARTICLE_SPAWN_COMMAND_WORKGROUP_SIZE,
+    shader_particle_spawn_commands,
+} from "./shaders/shader_particle_spawn_commands.js";
+import {
+    PARTICLE_SORT_WORKGROUP_SIZE,
+    shader_particle_sort_histogram,
+    shader_particle_sort_reset,
+    shader_particle_sort_scatter,
+} from "./sort/shader_particle_sort.js";
 
 /**
- * Per-frame frame-graph contribution for the GPU particle system — the reference wiring an
- * integrator (e.g. Renderer.render) calls once the CPU {@link GPUParticleSystem#update} has produced
- * this frame's spawn requests.
+ * The particle system's frame, recorded into the frame graph. {@link GPUParticleSystem} is what
+ * calls these, with the buffers it owns; nothing else needs to.
+ *
+ * Two halves. {@link graph_particles_simulate} is everything that moves particles:
+ *
+ *   reset counters -> spawn commands -> emitter tick -> scan -> spawn args -> emit -> simulate
+ *   -> bucket -> build indirect
  *
- * The passes run in dependency order:
+ * and it leaves the frame's alive list, the pool and the indirect draw args as graph handles for
+ * whoever draws. {@link graph_particles_render} is the standalone drawing: a depth sort and one
+ * billboard draw straight over a colour target. Under the renderer the drawing is AVBOIT's instead
+ * (`graph_particles_avboit.js`), which reads the same handles and needs no sort.
+ * {@link graph_particles} is the two together, for a page with no transparency pipeline of its own.
  *
- *   reset counters -> emit (spawn) -> simulate (advance + compact) -> bucket -> build indirect args
+ * ## Spawning is decided here, on the GPU
  *
- * with the depth sort + billboard render appended by the caller (the render pass needs the frame's
- * colour + depth attachments, which live in the caller's graph). Alive lists ping-pong by frame
- * parity: `alive_write` receives this frame's survivors + newborns.
+ * The emitter tick runs one thread per emitter row and writes each row's spawn count for the
+ * frame; a prefix scan turns the counts into offsets; a one-thread pass turns the scan's total into
+ * the emit dispatch; and the emit pass runs one thread per newborn, each locating its emitter in the
+ * scan. The host contributes two numbers to all of that: the table's element capacity, which sizes
+ * the scan, and the length of the spawn-command list it authored itself. Neither is a count of
+ * anything alive.
  *
  * ## Two orderings, kept apart
  *
@@ -31,62 +64,77 @@ import { shader_particle_simulate } from "./shaders/shader_particle_simulate.js"
  * ordering is camera-independent and changes only when emitters or their programs change.
  *
  * The RENDER ordering — back-to-front by view depth, from `sort/` — is a different list in a
- * different buffer, produced by different passes, and the billboard draw is what consumes it.
- * Reordering the render list for coherence would break premultiplied transparency; depth-sorting the
- * simulation list would destroy the coherence. They share no buffer and no counter slot.
- *
- * The simulate pass is fully GPU-driven: its workgroup count comes from `dispatch_args` (written by
- * LAST frame's build-indirect pass) via `dispatchWorkgroupsIndirect`, and its element bound comes
- * from the `ALIVE_IN` counter snapshot — never from a CPU count. Both are derived from one value,
- * the padded list length, so the thread count and the bound agree by construction. A CPU count is
- * inevitably stale and corrupts the pool (orphaned slots when the population grows, double-freed
- * slots when it shrinks). Only the spawn count is CPU-provided, because the CPU authored the
- * spawn-request list and knows its exact length. The caller renders with `drawIndirect(draw_args)`,
- * which build-indirect writes THIS frame, so the instance count is exact too.
+ * different buffer, produced by different passes, and the standalone billboard draw is what
+ * consumes it. Reordering the render list for coherence would break premultiplied transparency;
+ * depth-sorting the simulation list would destroy the coherence. They share no buffer and no
+ * counter slot.
+ *
+ * ## Nothing is sized from the CPU
+ *
+ * Simulate's workgroup count comes from `dispatch_args` (written by LAST frame's build-indirect
+ * pass) via `dispatchWorkgroupsIndirect`, and its element bound from the `ALIVE_IN` counter
+ * snapshot; the sort's two per-particle passes and the draw are sized the same way, from this
+ * frame's alive count. A CPU count is inevitably stale and corrupts the pool (orphaned slots when
+ * the population grows, double-freed slots when it shrinks).
  *
  * All persistent buffers are imported (owned by the feature, not the graph). Writing an imported
  * buffer marks the pass a side-effect so it always executes, and returns a renamed handle downstream
- * passes must read — exactly the ReSTIR reservoir pattern.
+ * passes must read — exactly the ReSTIR reservoir pattern. Every persistent buffer is imported
+ * exactly once: two imports of one buffer are two resource entries the graph cannot tell apart.
  *
  * On the very first frame `dispatch_args` must be zero-initialised (WebGPU zero-fills new buffers)
  * and the `ALIVE_IN` counter 0, so simulate is a no-op until the first build-indirect has run.
+ */
+
+/**
+ * @typedef {object} ParticleSimulationHandles
+ * @property {number} pool the particle pool, after this frame's INIT and UPDATE
+ * @property {number} alive this frame's compacted alive list — the render order's input
+ * @property {number} counters the atomic counters, after build-indirect
+ * @property {number} draw_args the billboard draw's indirect args: six vertices, one instance per live particle
+ * @property {number} sim_dispatch_args one workgroup per live particle, for a per-particle pass
+ * @property {number} emitter_database the emitter database, after the tick wrote its state rows
+ */
+
+/**
+ * Everything that moves particles, up to the indirect args a draw consumes.
  *
  * @param {object} params
  * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
- * @param {object} params.gpu handles/objects for the persistent buffers (GPUBuffer instances)
- * @param {GPUBuffer} params.gpu.emitters
- * @param {GPUBuffer} params.gpu.program
- * @param {GPUBuffer} params.gpu.constants
- * @param {GPUBuffer} params.gpu.pool
- * @param {GPUBuffer} params.gpu.alive_read the other half of the ping-pong. These passes no longer
- *   read it — simulate's input is `sim_list` — but the caller keeps swapping the two so this frame's
- *   render is not read-after-written by next frame's emit, which would serialise them
- * @param {GPUBuffer} params.gpu.alive_write this-frame alive list: survivors + newborns
- * @param {GPUBuffer} params.gpu.dead free-list stack
- * @param {GPUBuffer} params.gpu.counters atomic counters
- * @param {GPUBuffer} params.gpu.spawn_requests
- * @param {GPUBuffer} params.gpu.dispatch_args indirect simulate dispatch (usage must include INDIRECT)
- * @param {GPUBuffer} params.gpu.draw_args indirect billboard draw (usage must include INDIRECT)
- * @param {GPUBuffer} params.gpu.sim_list program-coherent simulate input, rebuilt here for next frame
- * @param {GPUBuffer} params.gpu.sim_keys see {@link graph_particle_bucket}
- * @param {GPUBuffer} params.gpu.sim_histogram see {@link graph_particle_bucket}
- * @param {GPUBuffer} params.gpu.sim_bucket_counts see {@link graph_particle_bucket}
- * @param {GPUBuffer} params.gpu.sim_cursor see {@link graph_particle_bucket}
- * @param {GPUBuffer} params.gpu.sim_dispatch_args see {@link graph_particle_bucket} (usage must include INDIRECT)
- * @param {number} params.capacity pool capacity in particles (bounds the emit pass's free-list pops)
+ * @param {number} params.camera graph handle of the view's camera uniform (`CAMERA_UNIFORM_STRUCT`)
+ * @param {number} params.scene_database graph handle of the scene database — the emitters' nodes
+ * @param {object} params.gpu the persistent buffers, see {@link GPUParticleSystem}
+ * @param {object} params.emitters the emitter table's shape this frame
+ * @param {number} params.emitters.capacity the table's element capacity — the length of the count
+ *   list the scan consumes
+ * @param {number} params.emitters.group_count workgroups the tick needs to walk every page group
+ * @param {number} params.capacity pool capacity in particles
  * @param {number} params.bucket_count distinct compiled programs — `GPUParticleSystem#bucketCount()`
  * @param {object} params.frame per-frame scalars
  * @param {number} params.frame.dt
  * @param {number} params.frame.time
  * @param {number} params.frame.index
- * @param {number} params.frame.spawn_count number of spawn requests this frame (CPU-authored, exact)
+ * @param {number} params.frame.max_catchup seconds of missed spawning a woken emitter makes up
+ * @param {number} params.frame.spawn_command_count entries in `gpu.spawn_commands` this frame
+ * @returns {ParticleSimulationHandles}
  */
-export function graph_particles({ graph, gpu, capacity, bucket_count, frame }) {
-    const gr_emitters = graph_import_buffer(graph, gpu.emitters, "particles/emitters");
+export function graph_particles_simulate({
+                                             graph,
+                                             camera,
+                                             scene_database,
+                                             gpu,
+                                             emitters,
+                                             capacity,
+                                             bucket_count,
+                                             frame,
+                                         }) {
+    assert.defined(graph, "graph");
+    assert.isNonNegativeInteger(camera, "camera");
+    assert.isNonNegativeInteger(scene_database, "scene_database");
+    assert.isPositiveInteger(capacity, "capacity");
+
     const gr_program = graph_import_buffer(graph, gpu.program, "particles/program");
-    const gr_constants = graph_import_buffer(graph, gpu.constants, "particles/constants");
     const gr_sim_list = graph_import_buffer(graph, gpu.sim_list, "particles/sim_list");
-    const gr_spawn = graph_import_buffer(graph, gpu.spawn_requests, "particles/spawn_requests");
     const gr_dispatch = graph_import_buffer(graph, gpu.dispatch_args, "particles/dispatch_args");
     const gr_draw = graph_import_buffer(graph, gpu.draw_args, "particles/draw_args");
 
@@ -97,8 +145,13 @@ export function graph_particles({ graph, gpu, capacity, bucket_count, frame }) {
     let pool = graph_import_buffer(graph, gpu.pool, "particles/pool");
     let alive_write = graph_import_buffer(graph, gpu.alive_write, "particles/alive_write");
     let dead = graph_import_buffer(graph, gpu.dead, "particles/dead");
+    // Two tables in one buffer — the emitter records the CPU authors and the state the GPU
+    // integrates — so the passes that write the state rename the handle every reader after them
+    // takes.
+    let emitter_database = graph_import_buffer(graph, gpu.emitter_database, "particles/emitter_database");
 
-    // 1. Reset the alive/spawn/sorted/sim-padded counters (dead count + ALIVE_IN snapshot persist).
+    // 1. Reset the alive/sorted/sim-padded counters (dead count + ALIVE_IN snapshot persist) and
+    //    seed the frame's spawn budget from the free count.
     counters = graph_compute_pass({
         graph,
         shader: shader_particle_reset_counters,
@@ -106,35 +159,109 @@ export function graph_particles({ graph, gpu, capacity, bucket_count, frame }) {
         group_count: [1, 1, 1],
     }).counters;
 
-    // 2. Emit — one thread per spawn request. Newborns join the new alive list.
-    if (frame.spawn_count > 0) {
+    // 2. Spawn commands — the CPU's bursts, added to the emitters' pending spawns. The one dispatch
+    //    the host sizes, because the host wrote the list.
+    if (frame.spawn_command_count > 0) {
+        const gr_commands = graph_import_buffer(graph, gpu.spawn_commands, "particles/spawn_commands");
+
+        emitter_database = graph_compute_pass({
+            graph,
+            shader: shader_particle_spawn_commands,
+            bindings: { commands: gr_commands, emitter_database, u_count: frame.spawn_command_count },
+            group_count: [Math.ceil(frame.spawn_command_count / PARTICLE_SPAWN_COMMAND_WORKGROUP_SIZE), 1, 1],
+        }).emitter_database;
+    }
+
+    // 3. Emitter tick — one thread per emitter row: integrate the rate, cull, take from the budget,
+    //    and write the row's spawn count. The counts list is transient and cleared whole, because
+    //    the tick writes only the rows it visits.
+    const count_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(Math.max(1, emitters.capacity));
+    const count_bytes = count_words * Uint32Array.BYTES_PER_ELEMENT;
+
+    let spawn_counts = create_buffer(graph, "particles/spawn_counts", BufferResourceDescriptor.from(
+        count_bytes,
+        GPUBufferUsage.STORAGE,
+        0, count_bytes,
+    ));
+
+    // A table with no pages has no rows to visit and nothing to write: the cleared counts scan to a
+    // total of zero and the emit dispatch is empty. (A dispatch of zero workgroups is refused
+    // upstream, so this is a skip rather than a no-op dispatch.)
+    if (emitters.group_count > 0) {
         const out = graph_compute_pass({
             graph,
-            shader: shader_particle_emit,
+            shader: shader_particle_emitter_tick,
             bindings: {
-                emitters: gr_emitters, program: gr_program, vm_constants: gr_constants,
-                pool, spawn_requests: gr_spawn, alive_out: alive_write, dead, counters,
+                camera,
+                scene_database,
+                emitter_database,
+                counters,
+                spawn_counts,
                 settings: {
-                    u_dt: frame.dt, u_time: frame.time, u_frame: frame.index,
-                    u_count: frame.spawn_count, u_capacity: capacity,
+                    u_dt: frame.dt,
+                    u_max_catchup: frame.max_catchup,
+                    u_capacity: capacity,
+                    u_emitter_capacity: emitters.capacity,
                 },
             },
-            group_count: [Math.ceil(frame.spawn_count / PARTICLE_EMIT_WORKGROUP_SIZE), 1, 1],
+            group_count: [emitters.group_count, 1, 1],
+        });
+        emitter_database = out.emitter_database;
+        counters = out.counters;
+        spawn_counts = out.spawn_counts;
+    }
+
+    // 4. Inclusive prefix sums of the counts: each row's batch ends at its sum, and the last sum is
+    //    the number of particles born this frame.
+    const spawn_prefix = graph_prefix_scan_csdldf({
+        graph,
+        data: spawn_counts,
+        element_max_count: Math.max(1, emitters.capacity),
+    });
+
+    // 5. That total, as the emit dispatch — the same one-thread pass that sizes meshlet expansion.
+    const emit_command = graph_compute_pass({
+        graph,
+        shader: shader_prefix_sum_to_command,
+        bindings: {
+            prefix_sums: spawn_prefix,
+            command: create_buffer(graph, "particles/emit_command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR),
+        },
+        group_count: [1, 1, 1],
+    }).command;
+
+    // 6. Emit — one thread per newborn, its emitter found in the scan. Newborns join the new alive
+    //    list.
+    {
+        const out = graph_compute_indirect_pass({
+            graph,
+            shader: shader_particle_emit,
+            bindings: {
+                scene_database,
+                emitter_database,
+                program: gr_program,
+                spawn_prefix,
+                pool, alive_out: alive_write, dead, counters,
+                settings: { u_dt: frame.dt, u_time: frame.time, u_frame: frame.index, u_capacity: capacity },
+            },
+            command: emit_command,
         });
         pool = out.pool; alive_write = out.alive_out; dead = out.dead; counters = out.counters;
     }
 
-    // 3. Simulate — one indirect dispatch runs every emitter's UPDATE over the program-coherent list
+    // 7. Simulate — one indirect dispatch runs every emitter's UPDATE over the program-coherent list
     //    the bucketing pass built LAST frame, compacting survivors into the new alive list and freed
     //    slots into the dead list. The workgroup count comes from last frame's dispatch_args and the
-    //    list itself from last frame's sim_list — both read here and re-written in steps 4 and 5,
+    //    list itself from last frame's sim_list — both read here and re-written in steps 8 and 9,
     //    with insertion order keeping the read before the write.
     {
         const out = graph_compute_indirect_pass({
             graph,
             shader: shader_particle_simulate,
             bindings: {
-                emitters: gr_emitters, program: gr_program, vm_constants: gr_constants,
+                scene_database,
+                emitter_database,
+                program: gr_program,
                 pool, sim_list: gr_sim_list, alive_out: alive_write, dead, counters,
                 settings: { u_dt: frame.dt, u_time: frame.time, u_frame: frame.index },
             },
@@ -143,24 +270,25 @@ export function graph_particles({ graph, gpu, capacity, bucket_count, frame }) {
         pool = out.pool; alive_write = out.alive_out; dead = out.dead; counters = out.counters;
     }
 
-    // 4. Bucket — regroup the frame's alive list by VM program, padded to whole workgroups, into the
+    // 8. Bucket — regroup the frame's alive list by VM program, padded to whole workgroups, into the
     //    list NEXT frame's simulate consumes. Must follow BOTH emit and simulate, since both append
     //    to the alive list.
     //    `gr_sim_list` is handed over rather than re-imported: two imports of one GPUBuffer are two
     //    resource entries the graph cannot tell apart, which would put simulate's read of the list
     //    and this pass's rewrite of it on unrelated dependency chains.
-    counters = graph_particle_bucket({
+    const bucketed = graph_particle_bucket({
         graph,
         gpu,
-        emitters: gr_emitters,
+        emitter_database,
         pool,
         alive: alive_write,
         counters,
         sim_list: gr_sim_list,
         bucket_count,
-    }).counters;
+    });
+    counters = bucketed.counters;
 
-    // 5. Snapshot the padded list length (next frame's simulate input length) and build the indirect
+    // 9. Snapshot the padded list length (next frame's simulate input length) and build the indirect
     //    dispatch args for next frame + the indirect draw args for this frame's render.
     const indirect = graph_compute_pass({
         graph,
@@ -172,15 +300,240 @@ export function graph_particles({ graph, gpu, capacity, bucket_count, frame }) {
         group_count: [1, 1, 1],
     });
 
-    // The depth sort (graph_prefix_scan_csdldf-based) and the billboard render pass are appended by
-    // the caller, which owns the frame's colour + depth attachments; the render must use
-    // drawIndirect(gpu.draw_args). See sort/shader_particle_sort.js and
-    // shaders/shader_particle_render.js.
     return {
-        alive: alive_write,
         pool,
+        alive: alive_write,
         counters: indirect.counters,
-        dispatch_args: indirect.dispatch_args,
         draw_args: indirect.draw_args,
+        sim_dispatch_args: bucketed.dispatch_args,
+        emitter_database,
+    };
+}
+
+/**
+ * The standalone drawing: the depth sort, then one billboard draw over a colour target with
+ * fixed-function blending.
+ *
+ * @param {object} params
+ * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.camera graph handle
+ * @param {number} params.color graph handle of the colour target the billboards draw over
+ * @param {number} params.depth graph handle of the scene depth, tested against and never written
+ * @param {object} params.gpu the persistent buffers
+ * @param {ParticleSimulationHandles} params.simulated what {@link graph_particles_simulate} returned
+ * @param {number} params.sort_bucket_count depth bins the render sort quantises into
+ * @param {object} params.frame
+ * @param {number} params.frame.sort_near view depth the sort's first bin starts at
+ * @param {number} params.frame.sort_far view depth the sort's last bin ends at
+ * @param {object} params.render
+ * @param {GPUTextureView} params.render.atlas sprite atlas
+ * @param {GPUSampler} params.render.atlas_sampler
+ * @param {(color_format: string, depth_format: string) => object} params.render.obtain_pipeline
+ *   the billboard pipeline for the frame's attachment formats
+ * @returns {number} the colour handle after the draw
+ */
+export function graph_particles_render({
+                                           graph,
+                                           camera,
+                                           color,
+                                           depth,
+                                           gpu,
+                                           simulated,
+                                           sort_bucket_count,
+                                           frame,
+                                           render,
+                                       }) {
+    assert.defined(simulated, "simulated");
+
+    // 10. Sort — the render order: back-to-front by view depth, so premultiplied transparency
+    //     composites correctly. Its two per-particle passes take the dispatch the bucket reset
+    //     wrote from the alive count.
+    const sorted = graph_particle_sort({
+        graph,
+        gpu,
+        camera,
+        emitter_database: simulated.emitter_database,
+        pool: simulated.pool,
+        alive: simulated.alive,
+        counters: simulated.counters,
+        dispatch_args: simulated.sim_dispatch_args,
+        bucket_count: sort_bucket_count,
+        near: frame.sort_near,
+        far: frame.sort_far,
+    });
+
+    // 11. Render — one instanced billboard draw over the sorted list, sized by the draw args this
+    //     frame's build-indirect wrote.
+    return graph_particle_render({
+        graph,
+        camera,
+        color,
+        depth,
+        pool: simulated.pool,
+        sorted,
+        emitter_database: simulated.emitter_database,
+        draw_args: simulated.draw_args,
+        render,
+    });
+}
+
+/**
+ * The whole standalone frame: simulate, then sort and draw.
+ *
+ * @param {object} params every parameter of {@link graph_particles_simulate} and
+ *   {@link graph_particles_render}
+ * @returns {{color: number, alive: number, pool: number, counters: number}}
+ */
+export function graph_particles(params) {
+    const simulated = graph_particles_simulate(params);
+
+    const color = graph_particles_render({ ...params, simulated });
+
+    return {
+        color,
+        alive: simulated.alive,
+        pool: simulated.pool,
+        counters: simulated.counters,
     };
 }
+
+/**
+ * The depth sort: reset -> histogram -> csdldf scan -> scatter, into `gpu.sorted`.
+ *
+ * @returns {number} graph handle of the sorted slot list
+ */
+function graph_particle_sort({ graph, gpu, camera, emitter_database, pool, alive, counters, dispatch_args, bucket_count, near, far }) {
+    let histogram = graph_import_buffer(graph, gpu.sort_histogram, "particles/sort_histogram");
+    let cursor = graph_import_buffer(graph, gpu.sort_cursor, "particles/sort_cursor");
+    let keys = graph_import_buffer(graph, gpu.sort_keys, "particles/sort_keys");
+    let sorted = graph_import_buffer(graph, gpu.sorted, "particles/sorted");
+
+    // The reset's widest loop is the scan header plus the bins rounded up to a whole vec4.
+    const reset_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count);
+
+    {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_particle_sort_reset,
+            bindings: { histogram, cursor, settings: { u_bucket_count: bucket_count } },
+            group_count: [Math.ceil(reset_words / PARTICLE_SORT_WORKGROUP_SIZE), 1, 1],
+        });
+        histogram = out.histogram;
+        cursor = out.cursor;
+    }
+
+    // The counters are only read here, but an atomic read needs a read_write binding, and the
+    // graph sees a write — so the handle is threaded through like any other.
+    {
+        const out = graph_compute_indirect_pass({
+            graph,
+            shader: shader_particle_sort_histogram,
+            bindings: {
+                camera, emitter_database, pool, alive, counters, keys, histogram,
+                settings: { u_near: near, u_far: far, u_bucket_count: bucket_count },
+            },
+            command: dispatch_args,
+        });
+        keys = out.keys;
+        histogram = out.histogram;
+        counters = out.counters;
+    }
+
+    const scanned = graph_prefix_scan_csdldf({
+        graph,
+        data: histogram,
+        element_max_count: bucket_count,
+    });
+
+    {
+        const out = graph_compute_indirect_pass({
+            graph,
+            shader: shader_particle_sort_scatter,
+            bindings: { keys, alive, scanned, counters, cursor, sorted },
+            command: dispatch_args,
+        });
+        sorted = out.sorted;
+    }
+
+    return sorted;
+}
+
+/** The colour attachment's view: one mip, the one the frame draws into. */
+const COLOR_VIEW = TextureViewDescriptor.from({ mipLevelCount: 1, baseMipLevel: 0 });
+
+/**
+ * The billboard draw: loads the colour target, depth-tests read-only against the scene, draws
+ * `drawIndirect(draw_args)` instances over the sorted list.
+ *
+ * @returns {number} the colour handle after the draw
+ */
+function graph_particle_render({ graph, camera, color, depth, pool, sorted, emitter_database, draw_args, render }) {
+    const data = {};
+
+    const pass = graph.add("Particle Billboard", data, (data, resources, context) => {
+        const encoder = context.encoder;
+
+        const color_texture = resources.get(data.color);
+        const depth_texture = resources.get(data.depth);
+
+        const pipeline = render.obtain_pipeline(color_texture.descriptor.format, depth_texture.descriptor.format);
+
+        // Read by the soft-depth fade and tested against by the pass: the same view, read-only in
+        // both roles.
+        const depth_view = depth_texture.obtainView(DEFAULT_DEPTH_TEXTURE_VIEW);
+
+        const bindings = PARTICLE_BILLBOARD_RESOURCES.generateBindings({
+            camera: resources.get(data.camera),
+            pool: resources.get(data.pool),
+            draw_list: resources.get(data.sorted),
+            emitter_database: resources.get(data.emitter_database),
+            atlas: render.atlas,
+            atlas_sampler: render.atlas_sampler,
+            scene_depth: depth_view,
+        }, encoder);
+
+        const render_pass = encoder.constructRenderPass({
+            label: "Particle Billboard",
+            pipeline,
+            bindings,
+            colorAttachments: [{
+                view: color_texture.obtainView(COLOR_VIEW),
+                loadOp: "load",
+                storeOp: "store",
+            }],
+            depthStencilAttachment: {
+                view: depth_view,
+                depthReadOnly: true,
+            },
+        });
+
+        render_pass.drawIndirect(resources.get(data.draw_args), 0);
+        render_pass.end();
+    });
+
+    data.camera = pass.read(camera);
+    data.pool = pass.read(pool);
+    data.sorted = pass.read(sorted);
+    data.emitter_database = pass.read(emitter_database);
+    data.draw_args = pass.read(draw_args);
+    data.depth = pass.read(depth);
+    data.color = pass.write(pass.read(color));
+
+    return data.color;
+}
+
+/**
+ * A transient buffer with no producing pass of its own, for a binding a shader both reads and
+ * writes — the compute pass helpers create a buffer only for write-only bindings, and a
+ * read-write one wants a handle.
+ *
+ * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
+ * @param {string} label
+ * @param {BufferResourceDescriptor} descriptor
+ * @returns {number}
+ */
+function create_buffer(graph, label, descriptor) {
+    const pass = graph.add(`${label} / create`, {}, noop);
+
+    return pass.create(label, descriptor);
+}