@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -6,7 +6,6 @@ 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,
@@ -25,14 +24,11 @@ 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;
 
@@ -49,14 +45,29 @@ 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 the playground's HUD,
- * which reads the args back to show that the dispatch really is sized on-device — twelve bytes, and
- * the only thing in this file read back at all.
+ * 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
@@ -76,12 +87,11 @@ const DEFAULT_CAPACITY = 524288;
  * ReSTIR's reservoirs follow the resolution.
  *
  * Everything else a frame touches is the frame graph's. The bucketing's bins, cursors and keys, the
- * whole depth sort, 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 six megabytes at the default
- * capacity that no other feature could ever borrow, and four of them are cleared by a reset pass
- * every frame regardless.
+ * 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
@@ -116,21 +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. Under `AVBOIT` none of those passes is recorded, so the graph never allocates
- * their buffers either.
+ * 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
  *
@@ -182,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.
@@ -201,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}
      */
@@ -285,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}
@@ -305,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
@@ -419,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();
 
@@ -471,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;
@@ -489,101 +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;
-        }
-
-        // 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, and every buffer it needs is the graph's — a system the
-        // renderer drives through AVBOIT records none of these passes and so pays for none of them.
-        const sorted = graph_particle_sort({
-            graph,
-            camera,
-            emitter_database: simulated.emitter_database,
-            pool: simulated.pool,
-            alive: simulated.alive,
-            counters: simulated.counters,
-            dispatch_args: simulated.sim_dispatch_args,
-            capacity: this.capacity,
-            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
@@ -1096,27 +1010,6 @@ 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 — one entry per distinct buffer, so
      * this is the feature's reserved footprint and not a list of the names it binds them under.
@@ -1143,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,

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"}

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

@@ -129,15 +129,6 @@ export const PARTICLE_PROGRAM_HEADER_WORDS = 4;
  */
 export const PARTICLE_PROGRAM_CODE_BASE_WORD = 0;
 
-/**
- * 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 = 1024;
-
 /**
  * First word index available for user-defined attributes.
  * @type {number}
@@ -286,10 +277,12 @@ export const PARTICLE_SIM_PAD_SLOT = 0xffffffff;
  * 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/coherence/graph_particle_bucket.d.ts

@@ -10,10 +10,10 @@
  * ({@link PARTICLE_COUNTER.SIM_PADDED}) and turns it into next frame's dispatch args and bound.
  *
  * Six passes, the middle one being `graph_prefix_scan_csdldf` reused unchanged — the same scan the
- * radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan in this
- * codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so the pass
- * makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here would be
- * a second place to get that wrong.
+ * engine's radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan
+ * in this codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so
+ * the pass makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here
+ * would be a second place to get that wrong.
  *
  * Nothing on this path reads back to the CPU. The only host-supplied number is `bucket_count`, and
  * that is static topology — it changes when the emitter set does, never as particles are born and

package/src/shade/renderer/particles/coherence/graph_particle_bucket.js

@@ -31,10 +31,10 @@ const WORD = Uint32Array.BYTES_PER_ELEMENT;
  * ({@link PARTICLE_COUNTER.SIM_PADDED}) and turns it into next frame's dispatch args and bound.
  *
  * Six passes, the middle one being `graph_prefix_scan_csdldf` reused unchanged — the same scan the
- * radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan in this
- * codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so the pass
- * makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here would be
- * a second place to get that wrong.
+ * engine's radix sort runs its spine through. Reusing it is deliberate: it is the one prefix scan
+ * in this codebase whose only cross-workgroup wait is CSDLDF's own bounded-spin-then-fallback, so
+ * the pass makes progress on a scheduler that offers no fairness guarantee. A hand-rolled scan here
+ * would be a second place to get that wrong.
  *
  * Nothing on this path reads back to the CPU. The only host-supplied number is `bucket_count`, and
  * that is static topology — it changes when the emitter set does, never as particles are born and
@@ -93,7 +93,7 @@ export function graph_particle_bucket({ graph, emitter_database, pool, alive, co
     let cursor = scratch?.cursor ?? BufferResourceDescriptor.from(bucket_count * WORD, GPUBufferUsage.STORAGE);
     let bucket_counts = scratch?.bucket_counts ?? BufferResourceDescriptor.from(bucket_count * WORD, GPUBufferUsage.STORAGE);
     // Indirect args this pass writes and the two per-particle passes below consume, along with the
-    // depth sort's and the bounds pass's — hence INDIRECT on top of STORAGE.
+    // bounds pass — hence INDIRECT on top of STORAGE.
     let dispatch_args = scratch?.dispatch_args ?? BufferResourceDescriptor.from(
         3 * WORD,
         GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
@@ -175,7 +175,7 @@ export function graph_particle_bucket({ graph, emitter_database, pool, alive, co
     }
 
     // `dispatch_args` goes back too: it holds one workgroup per live particle, written from the
-    // GPU's own alive count, which is exactly the shape the depth sort's per-particle passes need.
+    // GPU's own alive count, which is the shape every per-particle pass after this one needs.
     return { counters, sim_list, dispatch_args, scratch: { keys, histogram: scanned, cursor, bucket_counts, dispatch_args } };
 }
 

package/src/shade/renderer/particles/coherence/particle_program_buckets.d.ts

@@ -18,7 +18,8 @@ export function particle_bucket_round_up(value: number): number;
 /**
  * Bucket sizes and start offsets, exactly as the GPU derives them: an atomic histogram, a round-up
  * of each bin to a whole workgroup, and an exclusive prefix sum of the *padded* bins (the GPU takes
- * that sum from `graph_prefix_scan_csdldf`, the same scan the radix sort runs its spine through).
+ * that sum from `graph_prefix_scan_csdldf`, the same scan the engine's radix sort runs its spine
+ * through).
  *
  * A program with no particles contributes nothing: `round_up(0)` is 0, so empty buckets neither
  * consume a workgroup nor shift the offsets of the buckets after them.

package/src/shade/renderer/particles/coherence/particle_program_buckets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_program_buckets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/particle_program_buckets.js"],"names":[],"mappings":"AAwCA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,yDAJW,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,2BAA2B,CAkBvC;AAED;;;;;;;;;;;;GAYG;AACH,oDALW,UAAU,MAAM,CAAC,YACjB,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,MAAM,EAAE,CAapB;;;;;YA5Da,MAAM,EAAE;;;;mBACR,MAAM,EAAE;;;;aACR,MAAM,EAAE;;;;WACR,MAAM"}
+{"version":3,"file":"particle_program_buckets.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/particle_program_buckets.js"],"names":[],"mappings":"AAqCA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AACH,yDAJW,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,2BAA2B,CAkBvC;AAED;;;;;;;;;;;;GAYG;AACH,oDALW,UAAU,MAAM,CAAC,YACjB,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ,MAAM,EAAE,CAapB;;;;;YA7Da,MAAM,EAAE;;;;mBACR,MAAM,EAAE;;;;aACR,MAAM,EAAE;;;;WACR,MAAM"}

package/src/shade/renderer/particles/coherence/particle_program_buckets.js

@@ -2,8 +2,7 @@ import { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_SIM_PAD_SLOT } from "../Part
 
 /**
  * CPU reference for the simulation-order bucketing — the readable statement of the answer the GPU
- * passes in {@link ./shader_particle_bucket.js} have to produce, the same role
- * {@link ../sort/particle_counting_sort.js} plays for the render-order depth sort.
+ * passes in {@link ./shader_particle_bucket.js} have to produce.
  *
  * ## What it is for
  *
@@ -22,11 +21,9 @@ import { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_SIM_PAD_SLOT } from "../Part
  *
  * ## What it is NOT
  *
- * This is the *simulation* order: camera-independent, changing only when emitters and their
- * programs change. It is a different ordering from the *render* order in `../sort/`, which is
- * back-to-front by view depth and exists so premultiplied transparency composites correctly. The
- * two must stay in separate buffers and separate passes — reordering the render list for coherence
- * breaks transparency, and depth-sorting the simulation list destroys the coherence.
+ * This is the *simulation* list, and nothing else reads it. The draws walk the alive list, which is
+ * compacted and unpadded; this one is permuted and padded with sentinels, and drawing it would draw
+ * them. The two stay in separate buffers, with separate counter slots, for that reason.
  *
  * ## Indirection only
  *
@@ -62,7 +59,8 @@ export function particle_bucket_round_up(value) {
 /**
  * Bucket sizes and start offsets, exactly as the GPU derives them: an atomic histogram, a round-up
  * of each bin to a whole workgroup, and an exclusive prefix sum of the *padded* bins (the GPU takes
- * that sum from `graph_prefix_scan_csdldf`, the same scan the radix sort runs its spine through).
+ * that sum from `graph_prefix_scan_csdldf`, the same scan the engine's radix sort runs its spine
+ * through).
  *
  * A program with no particles contributes nothing: `round_up(0)` is 0, so empty buckets neither
  * consume a workgroup nor shift the offsets of the buckets after them.

package/src/shade/renderer/particles/coherence/shader_particle_bucket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/shader_particle_bucket.js"],"names":[],"mappings":"AA+GA;;;;;;;GAOG;AACH,2CAFU,aAAa,CAyCpB;AAcH;;;;;;;;;;GAUG;AACH,+CAFU,aAAa,CAuBpB;AAYH;;;;;;;;;;GAUG;AACH,yCAFU,aAAa,CAmBpB;AAeH;;;;;;;;GAQG;AACH,6CAFU,aAAa,CAwBpB;AAcH;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAiCpB;8BA1V2B,+BAA+B"}
+{"version":3,"file":"shader_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/shader_particle_bucket.js"],"names":[],"mappings":"AAgHA;;;;;;;GAOG;AACH,2CAFU,aAAa,CAyCpB;AAcH;;;;;;;;;;GAUG;AACH,+CAFU,aAAa,CAuBpB;AAYH;;;;;;;;;;GAUG;AACH,yCAFU,aAAa,CAmBpB;AAeH;;;;;;;;GAQG;AACH,6CAFU,aAAa,CAwBpB;AAcH;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAiCpB;8BA3V2B,+BAA+B"}

package/src/shade/renderer/particles/coherence/shader_particle_bucket.js

@@ -35,7 +35,7 @@ import { chunk_particle_header } from "../data/particle_header.js";
  *
  * ## Shape
  *
- * The same three-phase shape the depth sort uses, with two small passes added for the padding:
+ * A counting sort in three phases, with two small passes added for the padding:
  *
  *   reset -> histogram -> pad -> graph_prefix_scan_csdldf -> scatter -> fill
  *
@@ -62,8 +62,9 @@ import { chunk_particle_header } from "../data/particle_header.js";
  * - **No CPU readback.** Only the bucket COUNT is host-known, and that is static topology (it
  *   changes when the emitter set does, not per frame). Every per-frame quantity — the alive count,
  *   the bin sizes, the padded total — is produced and consumed on the GPU.
- * - **This is not the render order.** `../sort/` produces the camera-dependent back-to-front list
- *   the billboard draw consumes. Separate buffers, separate passes, separate counter slots.
+ * - **This is not the draw list.** The draws walk the compacted, unpadded alive list; this one is
+ *   permuted and padded with sentinels, and an instance per sentinel would read a garbage record.
+ *   Separate buffers, separate passes, separate counter slots.
  *
  * @see ./particle_program_buckets.js for the CPU statement of the same answer.
  */