@woosh/meep-engine 3.20.0 → 3.22.0

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

@@ -1,14 +1,11 @@
 import { assert } from "../../../core/assert.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 { hash_mix2 } from "../../../core/math/hash/hash_mix2.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,
     PARTICLE_WARMUP_EMITTER_JITTER,
@@ -27,22 +24,50 @@ import {
     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 { create_particle_billboard_pipeline } from "./shaders/shader_particle_render.js";
-import { graph_particle_sort } from "./sort/graph_particle_sort.js";
 import { WARMUP_QUEUE } from "./warmup/shader_particle_warmup.js";
 import { warmup_schedule } from "./warmup/warmup_schedule.js";
 import { GPUTextureContext } from "../texture/GPUTextureContext.js";
+import { inspect_gpu_buffer } from "../buffer/inspect_gpu_buffer.js";
 
 const WORD = Uint32Array.BYTES_PER_ELEMENT;
 
-const STORAGE = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
+/*
+ A wide usage mask costs bandwidth: the driver places a buffer by what it was told the buffer might
+ have to do, and the flags below are what each one actually does. `pool` and the alive lists are the
+ big ones and are touched by nothing but shaders. Adding a flag "just in case" moves 64 MiB onto a
+ slower path for a copy nobody makes — see `BufferResourceDescriptor`.
+*/
+/** Written only by shaders. */
+const STORAGE = GPUBufferUsage.STORAGE;
+/** Seeded or refilled from the host with `writeBuffer`. */
+const STORAGE_UPLOAD = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST;
+/** Uploaded, and copied forward into its replacement when the emitter set outgrows it. */
+const STORAGE_GROWABLE = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC;
+/**
+ * An indirect command the GPU writes and the GPU consumes. COPY_SRC is for {@link
+ * GPUParticleSystem#read_stats}, which reads the args back to show that the dispatch really is
+ * sized on-device — twelve bytes.
+ */
 const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_SRC;
 
 const DEFAULT_CAPACITY = 524288;
 
+/**
+ * What {@link GPUParticleSystem#read_stats} decodes: the counts the GPU keeps between frames, named.
+ *
+ * @typedef {object} ParticleSystemStats
+ * @property {number} alive live particles the frame ended with
+ * @property {number} dead length of the free list
+ * @property {number} spawn_budget free slots the frame never promised to a spawn — its headroom
+ * @property {number} alive_in entries the frame's simulate consumed — the padded, program-coherent
+ *   list the frame before it built, so never fewer than that frame's `alive`
+ * @property {number} sim_padded length of the padded, program-coherent simulate list built this
+ *   frame; the gap to `alive` is what keeping each wave on one VM program costs in lanes
+ * @property {number} sim_workgroups workgroups the NEXT simulate will dispatch — read out of the
+ *   indirect args rather than derived, so it is what the GPU will actually launch
+ */
+
 /**
  * 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
@@ -50,15 +75,23 @@ const DEFAULT_CAPACITY = 524288;
  *
  * ## 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
+ * Persistent GPU state, and only that: a buffer is reserved here if and only if its contents have
+ * to survive to the next frame. That is the particle pool, the ping-pong alive lists, the dead
+ * free-list, the counters, the simulation-order (coherence) list, simulate's indirect dispatch args
+ * (written at the end of one frame, read by the next), the emitter database (the emitter table and
+ * the GPU-owned state table, one buffer), the packed program buffer, and the two CPU-uploaded
+ * queues — the spawn-command ring and the warm-up queue. Buffers that depend on the emitter set —
+ * the coherence list on the number of distinct programs, the program buffer on the heap, the
  * database on its own pages, the counters on the emitter table's element capacity (they carry the
- * per-emitter bounds accumulator, see `bounds/`) — 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.
+ * per-emitter bounds accumulator, see `bounds/`) — are grown inside {@link execute}, the way
+ * ReSTIR's reservoirs follow the resolution.
+ *
+ * Everything else a frame touches is the frame graph's. The bucketing's bins, cursors and keys, the
+ * draw args, the spawn counts and the VM's wide register file are produced and consumed inside one
+ * graph, so the pass that first writes each one declares it and the graph allocates it just in time
+ * and releases it after its last reader — into the pool the rest of the renderer allocates from.
+ * Reserving them here instead would be megabytes at the default capacity that no other feature
+ * could ever borrow, and most of them are cleared by a reset pass every frame regardless.
  *
  * 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
@@ -93,20 +126,18 @@ const DEFAULT_CAPACITY = 524288;
  * 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.
  *
- * ## Drawing, and the one thing the mode changes
+ * ## Drawing
  *
- * {@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.
+ * {@link execute} is the whole per-frame call, once per frame, and it records only the simulation:
+ * everything that moves particles, leaving the alive list and the indirect draw args as graph
+ * handles. It draws nothing.
  *
- * `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.
+ * The drawing is the transparency pipeline's. The system is an `AVBOITSideChannel`, and the AVBOIT
+ * 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 handles `execute` produced and composite into a voxel volume
+ * and a set of accumulators that are sums — so the particles need no depth ordering at all, and
+ * none is ever built.
  *
  * ## Allocation
  *
@@ -158,13 +189,6 @@ export class GPUParticleSystem {
      */
     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.
@@ -177,8 +201,9 @@ export class GPUParticleSystem {
 
     /**
      * 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.
+     * inspection — {@link bufferSizes} measures them, {@link read_stats} reads the counts out of
+     * them — never for the frame loop, which reads nothing back. Entries that grow with the
+     * emitter set are replaced in place.
      *
      * @type {object}
      */
@@ -261,12 +286,6 @@ export class GPUParticleSystem {
      */
     #program_assignment_version = 0;
 
-    /** @type {object|null} */
-    #pipeline = null;
-
-    /** @type {string} */
-    #pipeline_key = "";
-
     /**
      * Per-frame scalars handed to {@link graph_particles_simulate}, reused rather than rebuilt.
      * @type {object}
@@ -281,19 +300,13 @@ export class GPUParticleSystem {
     #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.
+     * This frame's simulation, for the side channels that draw it later in the frame: 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
@@ -395,18 +408,37 @@ export class GPUParticleSystem {
     }
 
     /**
-     * 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.
+     * The system's whole contribution to the frame, once per 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.
+     *
+     * It draws nothing and touches no colour target. The handles it returns are what the AVBOIT
+     * side channels ({@link avboit_occupancy}, {@link avboit_splat}, {@link avboit_draw}) consume
+     * later in the same frame, off this same graph, once the transparent meshes have contributed
+     * theirs.
      *
-     * @param {object} params see {@link execute}
+     * 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
-     * @param {number} params.scene_database
-     * @param {number} params.dt
+     * @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
      * @returns {import("./graph_particles.js").ParticleSimulationHandles}
      */
-    #simulate({ graph, camera, scene_database, dt }) {
+    execute({ graph, camera, scene_database, dt }) {
+        assert.defined(graph, "graph");
+        assert.isNumber(dt, "dt");
+
         this.sync_membership();
         this.#upload();
 
@@ -447,7 +479,7 @@ export class GPUParticleSystem {
             frame,
         });
 
-        // Kept for the draw that follows, whichever it is, and for nothing past this frame.
+        // Kept for the side channels that draw later in this frame, and for nothing past it.
         const current = this.#simulated;
         current.graph = graph;
         current.scene_database = scene_database;
@@ -465,104 +497,7 @@ export class GPUParticleSystem {
     }
 
     /**
-     * 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
-     */
-    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,
-        });
-    }
-
-    /**
-     * What this frame's {@link simulate} left, checked against the graph a side-channel call names:
+     * What this frame's {@link execute} 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.
      *
      * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
@@ -854,7 +789,7 @@ export class GPUParticleSystem {
 
         if (this.buffers.warmup_queue.size < bytes) {
             this.buffers.warmup_queue.destroy();
-            this.buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: bytes, usage: STORAGE });
+            this.buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: bytes, usage: STORAGE_UPLOAD });
         }
 
         device.queue.writeBuffer(this.buffers.warmup_queue, 0, words.buffer, words.byteOffset, bytes);
@@ -948,7 +883,7 @@ export class GPUParticleSystem {
         }
 
         const device = this.graphics.device;
-        const grown = device.createBuffer({ label: "particles/counters", size, usage: STORAGE });
+        const grown = device.createBuffer({ label: "particles/counters", size, usage: STORAGE_GROWABLE });
 
         const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/counters grow");
 
@@ -968,8 +903,14 @@ export class GPUParticleSystem {
     }
 
     /**
-     * Scratch follows the peak number of program ids. The coherence list itself is persistent:
-     * the next simulate consumes its entries and padding with the previous frame's saved count.
+     * The coherence list follows the peak number of program ids. It is the one thing the bucketing
+     * leaves behind: the next simulate consumes its entries and padding with the previous frame's
+     * saved count, so it cannot be a transient and it cannot be reallocated empty. Growth copies it
+     * forward; the old count and dispatch stay valid because the entries keep their places.
+     *
+     * The bins, cursors, keys and dispatch args the bucketing needs alongside it live and die inside
+     * one frame graph, so `coherence/` declares them on the passes that write them and the graph
+     * owns them.
      *
      * @param {number} buckets
      */
@@ -980,56 +921,26 @@ export class GPUParticleSystem {
 
         const device = this.graphics.device;
         const buffers = this.buffers;
-        const capacity = this.capacity;
-
-        for (const name of ["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.
         const previous = buffers.sim_list;
-        buffers.sim_list = device.createBuffer({ label: "particles/sim_list", size: (capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * WORD, usage: STORAGE });
+        buffers.sim_list = device.createBuffer({
+            label: "particles/sim_list",
+            size: (this.capacity + buckets * PARTICLE_SIMULATE_WORKGROUP_SIZE) * WORD,
+            usage: STORAGE_GROWABLE,
+        });
+
         if (previous !== undefined) {
             const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/coherence grow");
             cmd.gpu_encoder.copyBufferToBuffer(previous, 0, buffers.sim_list, 0, previous.size);
             cmd.finish();
             previous.destroy();
         }
-        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.
      */
@@ -1043,21 +954,21 @@ export class GPUParticleSystem {
             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.dead = device.createBuffer({ label: "particles/dead", size: capacity * WORD, usage: STORAGE_UPLOAD });
         // Just the counters to begin with. The per-emitter bounds accumulator that shares this
         // buffer follows the emitter table's capacity, and there is no table yet.
-        buffers.counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * WORD, usage: STORAGE });
+        buffers.counters = device.createBuffer({ label: "particles/counters", size: PARTICLE_COUNTER_COUNT * WORD, usage: STORAGE_GROWABLE });
 
-        // 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.
+        // Simulate's workgroup count, written by the END of one frame's build-indirect and read by
+        // the NEXT frame's dispatch — the one indirect buffer that crosses the boundary, and so the
+        // one the graph cannot own. Zero-initialised (WebGPU spec), so the first frame's indirect
+        // dispatch is a no-op 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 });
+        buffers.spawn_commands = device.createBuffer({ label: "particles/spawn_commands", size: this.#spawn_commands.byteLength, usage: STORAGE_UPLOAD });
 
         // The warm-up queue: one entry to start with, grown on upload to what a frame registers.
-        buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: PARTICLE_WARMUP_QUEUE_WORDS * WORD, usage: STORAGE });
+        buffers.warmup_queue = device.createBuffer({ label: "particles/warmup_queue", size: PARTICLE_WARMUP_QUEUE_WORDS * WORD, usage: STORAGE_UPLOAD });
 
         // Every slot free, and the counters saying so.
         const dead = new Uint32Array(capacity);
@@ -1100,37 +1011,24 @@ export class GPUParticleSystem {
     }
 
     /**
-     * @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.
+     * Sizes of the persistent buffers, in bytes, as they stand — one entry per distinct buffer, so
+     * this is the feature's reserved footprint and not a list of the names it binds them under.
+     * `alive_read` and `alive_write` are the two `alive` entries under the frame's names for them,
+     * and would otherwise be counted a second time each. Exposed for tests.
+     *
      * @returns {Object<string, number>}
      */
     bufferSizes() {
         const sizes = {};
+        const counted = new Set();
 
-        for (const [name, buffer] of Object.entries(this.buffers)) {
-            if (Array.isArray(buffer)) {
-                sizes[name] = buffer[0].size;
-            } else if (buffer !== undefined && buffer !== null) {
+        for (const [name, value] of Object.entries(this.buffers)) {
+            for (const buffer of Array.isArray(value) ? value : [value]) {
+                if (buffer === undefined || buffer === null || counted.has(buffer)) {
+                    continue;
+                }
+
+                counted.add(buffer);
                 sizes[name] = buffer.size;
             }
         }
@@ -1138,6 +1036,54 @@ export class GPUParticleSystem {
         return sizes;
     }
 
+    /**
+     * Copy the counts the GPU keeps back to the host and decode them, for display and diagnostics.
+     *
+     * Read back to *look at*: nothing here may size a pass. Every number describes a frame that has
+     * already been submitted, so by the time one arrives it is at best one frame stale — and sizing
+     * a dispatch or a draw from a stale count is a correctness bug, not an inaccuracy, for the
+     * reasons `shader_particle_build_indirect` sets out. This is the whole of what the feature ever
+     * reads back, and the only reason {@link INDIRECT} carries `COPY_SRC` at all.
+     *
+     * The draw args are not here and cannot be: they never leave the frame graph, which allocates
+     * them at the build-indirect pass and releases them after the last draw that reads them. Their
+     * instance count is {@link ParticleSystemStats#alive}, which the counters carry anyway.
+     *
+     * Two copies, two submissions and a map round trip, so a caller polling this for an overlay
+     * wants to rate-limit itself and to hold off while a previous read is still outstanding.
+     *
+     * @returns {Promise<ParticleSystemStats>}
+     */
+    async read_stats() {
+        const device = this.graphics.device;
+        const buffers = this.buffers;
+
+        const read = (buffer, words) => inspect_gpu_buffer({
+            device,
+            buffer,
+            buffer_size: words * WORD,
+            // The mapped range is only valid for the length of the callback, so the decode either
+            // happens inside it or takes a copy. A copy, so one `Promise.all` sees both buffers.
+            callback: bytes => new Uint32Array(bytes.slice(0)),
+        });
+
+        const [counters, dispatch] = await Promise.all([
+            // The head of the buffer only: what follows the counters is the per-emitter bounds
+            // accumulator, which is boxes rather than counts and grows with the emitter table.
+            read(buffers.counters, PARTICLE_COUNTER_COUNT),
+            read(buffers.dispatch_args, 3),
+        ]);
+
+        return {
+            alive: counters[PARTICLE_COUNTER.ALIVE],
+            dead: counters[PARTICLE_COUNTER.DEAD],
+            spawn_budget: counters[PARTICLE_COUNTER.SPAWN_BUDGET],
+            alive_in: counters[PARTICLE_COUNTER.ALIVE_IN],
+            sim_padded: counters[PARTICLE_COUNTER.SIM_PADDED],
+            sim_workgroups: dispatch[0],
+        };
+    }
+
     destroy() {
         /*
          The emitters go first, and they matter more than the buffers: they are the scene's nodes,
@@ -1183,7 +1129,7 @@ export class GPUParticleSystem {
 function replace_data_buffer(device, previous, label, data) {
     previous?.destroy();
 
-    const buffer = device.createBuffer({ label, size: Math.max(WORD, data.byteLength), usage: STORAGE });
+    const buffer = device.createBuffer({ label, size: Math.max(WORD, data.byteLength), usage: STORAGE_UPLOAD });
 
     device.queue.writeBuffer(buffer, 0, data);
 

package/src/shade/renderer/particles/ParticleConstants.d.ts

@@ -115,14 +115,6 @@ export const PARTICLE_PROGRAM_HEADER_WORDS: number;
  * @type {number}
  */
 export const PARTICLE_PROGRAM_CODE_BASE_WORD: number;
-/**
- * Bins the render-order depth sort quantises view depth into. More bins is a finer back-to-front
- * order at the cost of a longer histogram; particles that land in one bin draw in an order the
- * scatter's atomics decide.
- *
- * @type {number}
- */
-export const PARTICLE_SORT_BUCKET_COUNT: number;
 /**
  * First word index available for user-defined attributes.
  * @type {number}
@@ -258,10 +250,12 @@ export const PARTICLE_SIM_PAD_SLOT: number;
  * View-space distance, in world units, over which a soft-depth particle fades out as it approaches
  * the opaque surface behind it.
  *
- * Read by the two passes that have to agree on a fragment's coverage: the AVBOIT draw, which weights
- * the accumulators by it, and the AVBOIT splat, which records the extinction the volume then hands
- * to everything behind. A fade in one and not the other is a surface that is invisible and still
- * occludes.
+ * Above all it is what the two passes that have to agree on a fragment's coverage agree on: the
+ * AVBOIT draw, which weights the accumulators by it, and the AVBOIT splat, which records the
+ * extinction the volume then hands to everything behind. A fade in one and not the other is a
+ * surface that is invisible and still occludes. The blended billboard pipeline
+ * (`shaders/shader_particle_render.js`) reads it too, so a particle fades over the same distance
+ * whichever pipeline draws it.
  *
  * @type {number}
  */

package/src/shade/renderer/particles/ParticleConstants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;;;;;;;GAWG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;;;GAOG;AACH,2CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;GAUG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;GAOG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;GAIG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;GAMG;AACH,yCAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,yCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAFU,MAAM,CAEkC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAFU,MAAM,CAEkC;;AASlD;;;;;;;;;;;;;;;GAeG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;GAUG;AACH,uCAFU,MAAM,CAE4B"}
+{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;;;;;;;GAWG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;;;GAOG;AACH,2CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;GAUG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;GAOG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;GAIG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,yCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAFU,MAAM,CAEkC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAFU,MAAM,CAEkC;;AASlD;;;;;;;;;;;;;;;GAeG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;;;GAYG;AACH,uCAFU,MAAM,CAE4B"}