@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -17,28 +17,145 @@
  */
 export const PARTICLE_RECORD_WORD_COUNT: number;
 /**
- * Word index (within a record) that stores the owning emitter's index.
+ * Word index (within a record) of the header word: the owning emitter's row and that row's
+ * generation, packed as {@link ./data/particle_header.js} describes.
  * @type {number}
  */
 export const PARTICLE_RECORD_HEADER_EMITTER: number;
+/**
+ * Threads per workgroup in the emitter tick dispatch, which walks the emitter table a page group at
+ * a time through the table's page iterator. That iterator caches one occupancy word per 32 lanes,
+ * so this has to be a multiple of 32.
+ *
+ * @type {number}
+ */
+export const PARTICLE_EMITTER_TICK_WORKGROUP_SIZE: number;
+/**
+ * Words per entry of the spawn-command list the host hands the GPU: `[emitter row, count]`.
+ * @type {number}
+ */
+export const PARTICLE_SPAWN_COMMAND_WORDS: number;
+/**
+ * Words in front of the packed program buffer: word {@link PARTICLE_PROGRAM_CODE_BASE_WORD} holds
+ * the word index the instruction section starts at; the constant pool follows the header, so the
+ * one buffer is `[header][constants][code]` — data, then code, and one binding for both.
+ *
+ * Four words is now just room to grow the header: the pool is addressed by word, so nothing after
+ * it needs a `vec4` boundary to land on. That was the original reason for the number.
+ *
+ * @type {number}
+ */
+export const PARTICLE_PROGRAM_HEADER_WORDS: number;
+/**
+ * Header word holding the instruction section's first word index.
+ * @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}
  */
 export const PARTICLE_RECORD_USER_WORD_START: number;
 /**
- * Number of vec4f registers in the VM register file. Each register is 4 lanes; scalars live in `.x`.
+ * Register slots the INSTRUCTION SET can name. A register IS a slot: a `vec3` value is three
+ * consecutive ones, and an instruction's width says how many its operands span.
+ *
+ * This is an encoding fact, not a shader's budget. A destination is the 8-bit `VM_DST_MASK` field
+ * of word 0 and every source base is the 8-bit `VM_OPERAND_BASE_MASK` field of its own word, so 256
+ * is exactly what an instruction can address and reaching the ceiling costs nothing. Past it the
+ * instruction word would have to grow — there is room (word 0 has bits 11..15 and 22..23 free, and
+ * each operand word uses only its low 16) — but nothing needs it yet.
+ *
+ * What a *shader* can afford is a different and much smaller number, see
+ * {@link PARTICLE_VM_FAST_REGISTER_SLOTS}. The graph compiler allocates against this one, records
+ * the peak as the program's `register_count`, and the runtime picks an interpreter from it.
+ *
+ * @type {number}
+ */
+export const PARTICLE_VM_REGISTER_SLOTS: number;
+/**
+ * Register slots the FAST interpreter's file holds — `vm_reg` in
+ * {@link ./vm/chunk_particle_vm_registers_fast.js}, a `var<private>` array the VM indexes
+ * dynamically. It lands in registers rather than scratch, so this number is the shader's register
+ * footprint outright, and every program pays it rather than only the ones that need it.
+ *
+ * Compiled to RDNA2 (gfx1030, wave32), 32 slots cost 47 VGPRs; sixteen `vec4` registers — what this
+ * was — cost 81 and held the shader to 10 waves against a 16-wave cap that anything at or below 64
+ * VGPRs reaches. Scalar slots are also what makes the number go further than the same count of
+ * floats did as `vec4`s: eight `vec4` registers hold eight values whatever their width, while 32
+ * slots hold ten `vec3`s or 32 scalars.
+ *
+ * ## Why 48 and not 32
+ *
+ * The node library gained {@link ./graph/ParticleNodeGroup.js groups}, and with them simplex and curl
+ * noise. Those are hundreds of instructions with a wide working set, and 32 slots is not enough for
+ * any of them: measured peaks are 26 for `simplex3`, 33 for `simplex4`, 32 for `curl3` and 40 for
+ * `curl4` — the last with a whole effect's worth of arithmetic still to fit around it.
+ *
+ * 48 was picked by extrapolating the 32-slot measurement: a slot is about a VGPR, so 48 should land
+ * near 63, at or under the 64 that reaches the occupancy cap. **That extrapolation was wrong.** The
+ * measured table in {@link ./vm/chunk_particle_vm.js} puts this interpreter at 80 VGPRs on a 48-slot
+ * file, well past the cap it was sized to stay under. The number stays because it is measured and
+ * shipped, not because the model that chose it holds; anyone moving it should compile the simulate
+ * shader offline and read the register count rather than extrapolate again.
+ *
+ * ## What happens above it
+ *
+ * Nothing fails. A program whose `register_count` exceeds this is one the fast file cannot hold, and
+ * the system falls back to the wide interpreter for the frame — every program, not only the one that
+ * overflowed. That is the library declining to have an authoring ceiling, at the price of an
+ * interpreter that keeps its registers in storage. See {@link PARTICLE_VM_WIDE_LAUNCH_LANES} and
+ * {@link ./vm/chunk_particle_vm_registers_wide.js}.
+ *
  * @type {number}
  */
-export const PARTICLE_VM_REGISTER_COUNT: number;
+export const PARTICLE_VM_FAST_REGISTER_SLOTS: number;
 /**
- * Number of `u32` words per VM instruction: `[op, dst, s0, s1, s2]`.
+ * Invocations the wide-register simulate and emit passes launch, whatever the particle count.
+ *
+ * The wide interpreter keeps its register file in a storage buffer, so it needs one file per
+ * *invocation in flight*. One lane per particle would size that buffer by pool capacity — a million
+ * particles would want a gigabyte — so the wide passes do not run one lane per particle. They launch
+ * this many lanes and walk their input with a grid-stride loop, which caps the file count at a
+ * constant chosen here instead of at whatever the pool holds.
+ *
+ * The buffer is `PARTICLE_VM_WIDE_LAUNCH_LANES * PARTICLE_VM_REGISTER_SLOTS * 4` bytes — 8 MiB at
+ * these values. It is transient: never cleared, never read back, and shared by the emit and simulate
+ * passes, which cannot overlap. See {@link ./vm/chunk_particle_vm_registers_wide.js} for why not
+ * clearing it is safe.
+ *
+ * Must be a multiple of {@link PARTICLE_SIMULATE_WORKGROUP_SIZE}, and of
+ * {@link PARTICLE_EMIT_WORKGROUP_SIZE}. The grid stride IS this number, so every iteration has to
+ * cover a workgroup-aligned span of the coherence pass's list; a misaligned stride would put two
+ * programs in one wave and the wave-uniform section decode would then run one program's code over
+ * the other's particles.
+ *
  * @type {number}
  */
-export const PARTICLE_VM_INSTRUCTION_WORDS: number;
+export const PARTICLE_VM_WIDE_LAUNCH_LANES: number;
+export { PARTICLE_VM_INSTRUCTION_WORDS } from "./isa/ParticleVMISA.js";
 /**
  * Hard cap on instructions executed by a single VM program invocation. A safety bound so a malformed
  * program can never spin the GPU; the interpreter's loop is `for (i in 0..LIMIT)`.
+ *
+ * A bound and not a cost: the loop runs `min(instruction_count, LIMIT)` times, so a program of forty
+ * instructions costs forty whatever this says. What it does cost is the refusal — a program past it
+ * does not assemble — and the effects that library groups make possible are far past what 256 was.
+ * `curl4` alone is about six thousand instructions, being twelve four-dimensional simplex samples
+ * with no loop to put them in.
+ *
+ * Which is worth saying plainly rather than only in a constant: an effect built on curl noise runs
+ * thousands of VM instructions per particle per frame. That is not a budget anyone should spend
+ * without meaning to, and it is why the expensive groups say what they cost in their own help text.
+ *
  * @type {number}
  */
 export const PARTICLE_VM_MAX_INSTRUCTIONS: number;
@@ -73,4 +190,16 @@ export const PARTICLE_SIMULATE_WORKGROUP_SIZE: number;
  * @type {number}
  */
 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.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SOFT_FADE_RANGE: number;
 //# sourceMappingURL=ParticleConstants.d.ts.map

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;;;GAGG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;GAIG;AACH,2CAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC"}
+{"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;;;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"}

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

@@ -19,11 +19,54 @@
 export const PARTICLE_RECORD_WORD_COUNT = 32;
 
 /**
- * Word index (within a record) that stores the owning emitter's index.
+ * Word index (within a record) of the header word: the owning emitter's row and that row's
+ * generation, packed as {@link ./data/particle_header.js} describes.
  * @type {number}
  */
 export const PARTICLE_RECORD_HEADER_EMITTER = 0;
 
+/**
+ * Threads per workgroup in the emitter tick dispatch, which walks the emitter table a page group at
+ * a time through the table's page iterator. That iterator caches one occupancy word per 32 lanes,
+ * so this has to be a multiple of 32.
+ *
+ * @type {number}
+ */
+export const PARTICLE_EMITTER_TICK_WORKGROUP_SIZE = 64;
+
+/**
+ * Words per entry of the spawn-command list the host hands the GPU: `[emitter row, count]`.
+ * @type {number}
+ */
+export const PARTICLE_SPAWN_COMMAND_WORDS = 2;
+
+/**
+ * Words in front of the packed program buffer: word {@link PARTICLE_PROGRAM_CODE_BASE_WORD} holds
+ * the word index the instruction section starts at; the constant pool follows the header, so the
+ * one buffer is `[header][constants][code]` — data, then code, and one binding for both.
+ *
+ * Four words is now just room to grow the header: the pool is addressed by word, so nothing after
+ * it needs a `vec4` boundary to land on. That was the original reason for the number.
+ *
+ * @type {number}
+ */
+export const PARTICLE_PROGRAM_HEADER_WORDS = 4;
+
+/**
+ * Header word holding the instruction section's first word index.
+ * @type {number}
+ */
+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}
@@ -31,23 +74,109 @@ export const PARTICLE_RECORD_HEADER_EMITTER = 0;
 export const PARTICLE_RECORD_USER_WORD_START = 1;
 
 /**
- * Number of vec4f registers in the VM register file. Each register is 4 lanes; scalars live in `.x`.
+ * Register slots the INSTRUCTION SET can name. A register IS a slot: a `vec3` value is three
+ * consecutive ones, and an instruction's width says how many its operands span.
+ *
+ * This is an encoding fact, not a shader's budget. A destination is the 8-bit `VM_DST_MASK` field
+ * of word 0 and every source base is the 8-bit `VM_OPERAND_BASE_MASK` field of its own word, so 256
+ * is exactly what an instruction can address and reaching the ceiling costs nothing. Past it the
+ * instruction word would have to grow — there is room (word 0 has bits 11..15 and 22..23 free, and
+ * each operand word uses only its low 16) — but nothing needs it yet.
+ *
+ * What a *shader* can afford is a different and much smaller number, see
+ * {@link PARTICLE_VM_FAST_REGISTER_SLOTS}. The graph compiler allocates against this one, records
+ * the peak as the program's `register_count`, and the runtime picks an interpreter from it.
+ *
+ * @type {number}
+ */
+export const PARTICLE_VM_REGISTER_SLOTS = 256;
+
+/**
+ * Register slots the FAST interpreter's file holds — `vm_reg` in
+ * {@link ./vm/chunk_particle_vm_registers_fast.js}, a `var<private>` array the VM indexes
+ * dynamically. It lands in registers rather than scratch, so this number is the shader's register
+ * footprint outright, and every program pays it rather than only the ones that need it.
+ *
+ * Compiled to RDNA2 (gfx1030, wave32), 32 slots cost 47 VGPRs; sixteen `vec4` registers — what this
+ * was — cost 81 and held the shader to 10 waves against a 16-wave cap that anything at or below 64
+ * VGPRs reaches. Scalar slots are also what makes the number go further than the same count of
+ * floats did as `vec4`s: eight `vec4` registers hold eight values whatever their width, while 32
+ * slots hold ten `vec3`s or 32 scalars.
+ *
+ * ## Why 48 and not 32
+ *
+ * The node library gained {@link ./graph/ParticleNodeGroup.js groups}, and with them simplex and curl
+ * noise. Those are hundreds of instructions with a wide working set, and 32 slots is not enough for
+ * any of them: measured peaks are 26 for `simplex3`, 33 for `simplex4`, 32 for `curl3` and 40 for
+ * `curl4` — the last with a whole effect's worth of arithmetic still to fit around it.
+ *
+ * 48 was picked by extrapolating the 32-slot measurement: a slot is about a VGPR, so 48 should land
+ * near 63, at or under the 64 that reaches the occupancy cap. **That extrapolation was wrong.** The
+ * measured table in {@link ./vm/chunk_particle_vm.js} puts this interpreter at 80 VGPRs on a 48-slot
+ * file, well past the cap it was sized to stay under. The number stays because it is measured and
+ * shipped, not because the model that chose it holds; anyone moving it should compile the simulate
+ * shader offline and read the register count rather than extrapolate again.
+ *
+ * ## What happens above it
+ *
+ * Nothing fails. A program whose `register_count` exceeds this is one the fast file cannot hold, and
+ * the system falls back to the wide interpreter for the frame — every program, not only the one that
+ * overflowed. That is the library declining to have an authoring ceiling, at the price of an
+ * interpreter that keeps its registers in storage. See {@link PARTICLE_VM_WIDE_LAUNCH_LANES} and
+ * {@link ./vm/chunk_particle_vm_registers_wide.js}.
+ *
  * @type {number}
  */
-export const PARTICLE_VM_REGISTER_COUNT = 16;
+export const PARTICLE_VM_FAST_REGISTER_SLOTS = 48;
 
 /**
- * Number of `u32` words per VM instruction: `[op, dst, s0, s1, s2]`.
+ * Invocations the wide-register simulate and emit passes launch, whatever the particle count.
+ *
+ * The wide interpreter keeps its register file in a storage buffer, so it needs one file per
+ * *invocation in flight*. One lane per particle would size that buffer by pool capacity — a million
+ * particles would want a gigabyte — so the wide passes do not run one lane per particle. They launch
+ * this many lanes and walk their input with a grid-stride loop, which caps the file count at a
+ * constant chosen here instead of at whatever the pool holds.
+ *
+ * The buffer is `PARTICLE_VM_WIDE_LAUNCH_LANES * PARTICLE_VM_REGISTER_SLOTS * 4` bytes — 8 MiB at
+ * these values. It is transient: never cleared, never read back, and shared by the emit and simulate
+ * passes, which cannot overlap. See {@link ./vm/chunk_particle_vm_registers_wide.js} for why not
+ * clearing it is safe.
+ *
+ * Must be a multiple of {@link PARTICLE_SIMULATE_WORKGROUP_SIZE}, and of
+ * {@link PARTICLE_EMIT_WORKGROUP_SIZE}. The grid stride IS this number, so every iteration has to
+ * cover a workgroup-aligned span of the coherence pass's list; a misaligned stride would put two
+ * programs in one wave and the wave-uniform section decode would then run one program's code over
+ * the other's particles.
+ *
  * @type {number}
  */
-export const PARTICLE_VM_INSTRUCTION_WORDS = 5;
+export const PARTICLE_VM_WIDE_LAUNCH_LANES = 8192;
+
+/**
+ * Number of `u32` words per VM instruction. An ISA fact, defined with the encoding it describes and
+ * re-exported here so the runtime, the shaders and the tests read every build-time number from one
+ * module.
+ */
+export { PARTICLE_VM_INSTRUCTION_WORDS } from "./isa/ParticleVMISA.js";
 
 /**
  * Hard cap on instructions executed by a single VM program invocation. A safety bound so a malformed
  * program can never spin the GPU; the interpreter's loop is `for (i in 0..LIMIT)`.
+ *
+ * A bound and not a cost: the loop runs `min(instruction_count, LIMIT)` times, so a program of forty
+ * instructions costs forty whatever this says. What it does cost is the refusal — a program past it
+ * does not assemble — and the effects that library groups make possible are far past what 256 was.
+ * `curl4` alone is about six thousand instructions, being twelve four-dimensional simplex samples
+ * with no loop to put them in.
+ *
+ * Which is worth saying plainly rather than only in a constant: an effect built on curl noise runs
+ * thousands of VM instructions per particle per frame. That is not a budget anyone should spend
+ * without meaning to, and it is why the expensive groups say what they cost in their own help text.
+ *
  * @type {number}
  */
-export const PARTICLE_VM_MAX_INSTRUCTIONS = 256;
+export const PARTICLE_VM_MAX_INSTRUCTIONS = 8192;
 
 /**
  * Threads per workgroup in the simulate dispatch — and therefore the granularity the simulate input
@@ -81,3 +210,16 @@ export const PARTICLE_SIMULATE_WORKGROUP_SIZE = 64;
  * @type {number}
  */
 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.
+ *
+ * @type {number}
+ */
+export const PARTICLE_SOFT_FADE_RANGE = 0.5;

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

@@ -0,0 +1,19 @@
+/**
+ * How the frame's particles are drawn — the one thing {@link GPUParticleSystemexecute } branches on
+ * once the simulation has run.
+ *
+ * The simulation half is identical either way; the modes differ in whether anything downstream
+ * cares what ORDER the particles arrive in. Blending billboards over a colour target does —
+ * premultiplied transparency is order-dependent, so the draw list has to be back-to-front. AVBOIT's
+ * voxel volume and its accumulators do not: every contribution is a sum, and a sum has no order.
+ *
+ * That is why the depth sort is a property of the mode rather than of the simulation. It is four
+ * passes and a scan over every live particle, plus two lists a word per particle each, and under
+ * AVBOIT none of it changes a pixel.
+ */
+export type ParticleRenderMode = number;
+export namespace ParticleRenderMode {
+    let BILLBOARD: number;
+    let AVBOIT: number;
+}
+//# sourceMappingURL=ParticleRenderMode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleRenderMode.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleRenderMode.js"],"names":[],"mappings":";;;;;;;;;;;;;iCAaU,MAAM"}

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

@@ -0,0 +1,33 @@
+/**
+ * How the frame's particles are drawn — the one thing {@link GPUParticleSystem#execute} branches on
+ * once the simulation has run.
+ *
+ * The simulation half is identical either way; the modes differ in whether anything downstream
+ * cares what ORDER the particles arrive in. Blending billboards over a colour target does —
+ * premultiplied transparency is order-dependent, so the draw list has to be back-to-front. AVBOIT's
+ * voxel volume and its accumulators do not: every contribution is a sum, and a sum has no order.
+ *
+ * That is why the depth sort is a property of the mode rather than of the simulation. It is four
+ * passes and a scan over every live particle, plus two lists a word per particle each, and under
+ * AVBOIT none of it changes a pixel.
+ *
+ * @enum {number}
+ */
+export const ParticleRenderMode = {
+    /**
+     * Standalone: depth-sort the alive list back-to-front and draw it as billboards straight over a
+     * colour target with fixed-function blending. `color` and `depth` are required.
+     *
+     * For a page with no transparency pipeline of its own. See `graph_particles_billboard.js`.
+     */
+    BILLBOARD: 0,
+    /**
+     * Under the renderer: the AVBOIT transparency orchestrator draws the particles later in the
+     * frame, through the side-channel calls (`graph_particles_avboit.js`), off the same alive list
+     * and the same GPU-written draw args.
+     *
+     * Order-independent, so {@link GPUParticleSystem#execute} records no sort and no draw, allocates
+     * no sort buffers, and hands the colour target back untouched.
+     */
+    AVBOIT: 1,
+};

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

@@ -27,7 +27,7 @@
  * @param {GPUBuffer} params.gpu.sim_bucket_counts raw (unpadded) per-bucket counts
  * @param {GPUBuffer} params.gpu.sim_cursor per-bucket scatter cursor
  * @param {GPUBuffer} params.gpu.sim_dispatch_args indirect args for the two per-particle passes
- * @param {number} params.emitters graph handle of the packed emitter records
+ * @param {number} params.emitter_database graph handle of the emitter database buffer
  * @param {number} params.pool graph handle of the particle pool
  * @param {number} params.alive graph handle of this frame's compacted alive list
  * @param {number} params.counters graph handle of the atomic counters
@@ -36,9 +36,9 @@
  *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
  *   and the write end up on separate dependency chains
  * @param {number} params.bucket_count number of distinct compiled programs
- * @returns {{counters: number, sim_list: number}} the threaded handles downstream passes must read
+ * @returns {{counters: number, sim_list: number, dispatch_args: number}} the threaded handles downstream passes must read
  */
-export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, counters, sim_list, bucket_count }: {
+export function graph_particle_bucket({ graph, gpu, emitter_database, pool, alive, counters, sim_list, bucket_count }: {
     graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
     gpu: {
         sim_list: GPUBuffer;
@@ -48,7 +48,7 @@ export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, count
         sim_cursor: GPUBuffer;
         sim_dispatch_args: GPUBuffer;
     };
-    emitters: number;
+    emitter_database: number;
     pool: number;
     alive: number;
     counters: number;
@@ -57,5 +57,6 @@ export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, count
 }): {
     counters: number;
     sim_list: number;
+    dispatch_args: number;
 };
 //# sourceMappingURL=graph_particle_bucket.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"graph_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/graph_particle_bucket.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;IAnBqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,GAAG;QACI,QAAQ;QACR,QAAQ;QACR,aAAa;QACb,iBAAiB;QACjB,UAAU;QACV,iBAAiB;;IACxB,QAAQ,EAAvB,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,QAAQ,EAAvB,MAAM;IAIS,YAAY,EAA3B,MAAM;IACJ;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAqGhD"}
+{"version":3,"file":"graph_particle_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/coherence/graph_particle_bucket.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;IAnBqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,GAAG;QACI,QAAQ;QACR,QAAQ;QACR,aAAa;QACb,iBAAiB;QACjB,UAAU;QACV,iBAAiB;;IACxB,gBAAgB,EAA/B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,QAAQ,EAAvB,MAAM;IAIS,YAAY,EAA3B,MAAM;;cACO,MAAM;cAAY,MAAM;mBAAiB,MAAM;EAwGtE"}

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

@@ -1,4 +1,5 @@
 import { assert } from "../../../../core/assert.js";
+import { align_4 } from "../../../../core/binary/align_4.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";
@@ -44,7 +45,7 @@ import {
  * @param {GPUBuffer} params.gpu.sim_bucket_counts raw (unpadded) per-bucket counts
  * @param {GPUBuffer} params.gpu.sim_cursor per-bucket scatter cursor
  * @param {GPUBuffer} params.gpu.sim_dispatch_args indirect args for the two per-particle passes
- * @param {number} params.emitters graph handle of the packed emitter records
+ * @param {number} params.emitter_database graph handle of the emitter database buffer
  * @param {number} params.pool graph handle of the particle pool
  * @param {number} params.alive graph handle of this frame's compacted alive list
  * @param {number} params.counters graph handle of the atomic counters
@@ -53,16 +54,17 @@ import {
  *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
  *   and the write end up on separate dependency chains
  * @param {number} params.bucket_count number of distinct compiled programs
- * @returns {{counters: number, sim_list: number}} the threaded handles downstream passes must read
+ * @returns {{counters: number, sim_list: number, dispatch_args: number}} the threaded handles downstream passes must read
  */
-export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, counters, sim_list, bucket_count }) {
+export function graph_particle_bucket({ graph, gpu, emitter_database, pool, alive, counters, sim_list, bucket_count }) {
     assert.defined(graph, "graph");
     assert.isPositiveInteger(bucket_count, "bucket_count");
     assert.isNonNegativeInteger(sim_list, "sim_list");
 
     // Sized from the bucket count, which only changes when the emitter set does — so a caller that
     // added an emitter and did not reallocate gets told here rather than scattering out of bounds.
-    const bin_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count);
+    // Aligned up because the scan reads whole `vec4`s, so the last bin's tail is part of the buffer.
+    const bin_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count);
     assert.greaterThanOrEqual(gpu.sim_histogram.size, bin_words * Uint32Array.BYTES_PER_ELEMENT, "sim_histogram is too small for the bucket count");
     assert.greaterThanOrEqual(gpu.sim_cursor.size, bucket_count * Uint32Array.BYTES_PER_ELEMENT, "sim_cursor is too small for the bucket count");
     assert.greaterThanOrEqual(gpu.sim_bucket_counts.size, bucket_count * Uint32Array.BYTES_PER_ELEMENT, "sim_bucket_counts is too small for the bucket count");
@@ -98,7 +100,7 @@ export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, count
         const out = graph_compute_indirect_pass({
             graph,
             shader: shader_particle_bucket_histogram,
-            bindings: { emitters, pool, alive, keys, histogram, counters },
+            bindings: { emitter_database, pool, alive, keys, histogram, counters },
             command: dispatch_args,
         });
         keys = out.keys;
@@ -153,7 +155,9 @@ export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, count
         counters = out.counters;
     }
 
-    return { counters, sim_list };
+    // `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.
+    return { counters, sim_list, dispatch_args };
 }
 
 /**
@@ -165,15 +169,7 @@ export function graph_particle_bucket({ graph, gpu, emitters, pool, alive, count
  * @returns {number}
  */
 function reset_group_count(bucket_count) {
-    const words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + round_up_4(bucket_count);
+    const words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count);
 
     return Math.ceil(words / PARTICLE_SIMULATE_WORKGROUP_SIZE);
 }
-
-/**
- * @param {number} value
- * @returns {number} `value` rounded up to a multiple of four — the scan reads whole `vec4`s
- */
-function round_up_4(value) {
-    return (value + 3) & ~3;
-}

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

@@ -12,8 +12,8 @@ export const shader_particle_bucket_reset: ComputeShader;
  * (see {@link ../runtime/ProgramArena.js}) and belong in one wave-coherent run. Keying on the
  * emitter index would split a run that was already coherent into one padded bucket per emitter.
  *
- * The emitter's program id is read by direct indexing rather than through
- * `particle_emitter_read` — decoding a whole 41-word record, transform matrix included, to reach one
+ * The program id is read through the table's single-FIELD accessor rather than
+ * `particle_emitter_read` — decoding a whole emitter record, transform matrix included, to reach one
  * word would be pure waste in a pass that touches every live particle.
  *
  * @type {ComputeShader}

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":"AAwGA;;;;;;;GAOG;AACH,2CAFU,aAAa,CAyCpB;AAcH;;;;;;;;;;GAUG;AACH,+CAFU,aAAa,CAyBpB;AAYH;;;;;;;;;;GAUG;AACH,yCAFU,aAAa,CAmBpB;AAeH;;;;;;;;GAQG;AACH,6CAFU,aAAa,CAwBpB;AAcH;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAiCpB;8BArV2B,+BAA+B"}
+{"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"}