@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -74,24 +74,34 @@ export const PARTICLE_SORT_BUCKET_COUNT = 1024;
 export const PARTICLE_RECORD_USER_WORD_START = 1;
 
 /**
- * Size of the VM register file, in `f32` slots. A register IS a slot: a `vec3` value is three
+ * 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 the interpreter's single largest cost and it is paid by every program, not just the ones
- * that need it: `vm_reg` is a `var<private>` array the VM indexes dynamically, which lands in
- * registers rather than scratch, so the file's size sets the shader's register footprint outright.
- * Compiled to RDNA2 (gfx1030, wave32), 32 slots cost 47 VGPRs against a 16-wave occupancy cap that
- * anything at or below 64 VGPRs reaches. Sixteen `vec4` registers — what this was — cost 81 and
- * held the shader to 10 waves.
+ * 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.
  *
- * 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. The playground's fire effect, the most involved in the tree, peaks at 11
- * slots live.
+ * 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.
  *
- * A graph that needs more gets a clear error out of `compile_particle_graph.js` rather than silent
- * corruption, and the fix for it is to raise this number and re-measure — not to assume the headroom
- * was free.
+ * @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
  *
@@ -100,22 +110,55 @@ export const PARTICLE_RECORD_USER_WORD_START = 1;
  * 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 is the largest number that the measurement above says is free. At 32 slots the shader compiled
- * to 47 VGPRs, and a slot is about a VGPR, so 48 lands around 63 — still at or under the 64 that
- * reaches the 16-wave occupancy cap. **That arithmetic has not been re-measured against a real
- * driver.** It is the model the paragraphs above were written from, and it is a model; anyone
- * changing this number again, or wanting to be sure of this one, should compile the simulate shader
- * offline and read the register count rather than trust 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_SLOTS = 48;
+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

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/data/PARTICLE_EMITTER_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_EMITTER_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js"],"names":[],"mappings":"AAkIA;;;;;;;;;;GAUG;AACH;IAR6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAWlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AA7JD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAFU,YAAY,CAmEO;AAE7B,uDAAuD;AACvD,kDAAmD;AAEnD;;GAEG;AACH;;;;;GAKG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH,kEAAkE;AAClE;;;;;;GAMG;AAqCH,uEAAuE;AACvE;;;;;GAEG;6BApK0B,mCAAmC"}
+{"version":3,"file":"PARTICLE_EMITTER_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js"],"names":[],"mappings":"AAmIA;;;;;;;;;;GAUG;AACH;IAR6B,QAAQ,GAA1B,OAAO;IACW,UAAU,GAA5B,OAAO;IACW,IAAI,GAAtB,OAAO;IACW,IAAI,GAAtB,OAAO;IACU,KAAK,GAAtB,MAAM;IACW,UAAU,GAA3B,MAAM;IACJ,MAAM,CAWlB;AAED,6DAA6D;AAC7D,2CADY,MAAM,GAAkB,MAAM,CAGzC;AAED,kEAAkE;AAClE,gDADY,MAAM,GAAkB,MAAM,CAGzC;AA9JD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAFU,YAAY,CAoEO;AAE7B,uDAAuD;AACvD,kDAAmD;AAEnD;;GAEG;AACH;;;;;GAKG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH,kEAAkE;AAClE;;;;;;GAMG;AAqCH,uEAAuE;AACvE;;;;;GAEG;6BArK0B,mCAAmC"}

package/src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js

@@ -1,166 +1,167 @@
-import { f32, u32, vec2f, vec3f, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
-
-/**
- * One emitter's GPU record: which compiled program it runs and where that program's code and
- * constants sit in the {@link ../runtime/ProgramArena.js} buffers, plus the instance parameters the
- * tick / emit / simulate / sort / render passes read — the scene node it hangs off, spawn rate,
- * feature flags, bounds sphere, render-attribute bindings, atlas region and flipbook grid.
- *
- * There is no transform here. An emitter is a scene node, and its world matrix is the `global` of
- * its row in the scene database's `transforms` table, composed on the GPU by the hierarchy pass
- * from whatever the node is parented to. The passes that need it read it through `node`.
- *
- * Nor is there any per-frame state: what the GPU integrates for an emitter (spawn accumulator, age,
- * sleep) lives in {@link ./PARTICLE_EMITTER_STATE.js}, keyed by the same row, for the reason given
- * there.
- *
- * It lives in a `GPUDatabase` table (see {@link ./PARTICLE_DATABASE_SPEC.js}), so the layout below
- * is the *only* description of it that exists: the JS writer is
- * {@link ../../shader/type/serde/write_gpu_typed_buffer.js} and the WGSL reader is generated from
- * this same struct by the table descriptor. Nothing hand-packs an emitter word by word any more,
- * and there is no second copy of the offsets to keep in step.
- *
- * `.pack()` reorders the fields to close the padding a declaration-order layout would leave; WGSL
- * field names are what shaders address, never offsets, so the reordering is invisible to them.
- *
- * @type {WebGPUStruct}
- */
-export const PARTICLE_EMITTER_STRUCT = WebGPUStruct.from({
-    /** first instruction of the INIT program, in instruction units */
-    init_offset: u32,
-    /** INIT instruction count */
-    init_count: u32,
-    /** first instruction of the UPDATE program, in instruction units */
-    update_offset: u32,
-    /** UPDATE instruction count */
-    update_count: u32,
-    /** base into the shared constant pool, in vec4 units */
-    constant_offset: u32,
-    /** base RNG seed */
-    seed: u32,
-    /** see {@link EMITTER_FLAG} */
-    flags: u32,
-    /** continuous emission rate, particles/second, integrated on the GPU by the tick pass */
-    spawn_rate: f32,
-
-    /**
-     * Row of the scene database's `transforms` table this emitter is — its world matrix is that
-     * row's `global`.
-     */
-    node: u32,
-
-    /**
-     * Which tenancy of this row the record describes. Bumped every time the row is handed to a new
-     * emitter, never zero for a live row. Every particle carries the generation of the emitter that
-     * spawned it, and the simulate pass kills one whose generation no longer matches its row's —
-     * see {@link ./particle_header.js}.
-     */
-    generation: u32,
-
-    /** local-space bounding sphere centre */
-    bounds_center: vec3f,
-    /** bounding sphere radius */
-    bounds_radius: f32,
-
-    /** attribute word offset of world position (or {@link EMITTER_ATTRIBUTE_ABSENT}) */
-    render_position: u32,
-    /** attribute word offset of size */
-    render_size: u32,
-    /** attribute word offset of rgba colour */
-    render_color: u32,
-    /** attribute word offset of roll angle, radians */
-    render_rotation: u32,
-    /** attribute word offset of flipbook frame index */
-    render_frame: u32,
-    /** attribute word offset of velocity (STRETCHED projection) */
-    render_velocity: u32,
-
-    /** uv offset .xy + uv scale .zw */
-    atlas_region: vec4f,
-    /** flipbook grid: columns, rows */
-    flipbook: vec2f,
-
-    /**
-     * Dense id of the compiled program this emitter runs, assigned by
-     * {@link ../runtime/ProgramArena.js}. Emitters sharing a program share an id.
-     *
-     * The simulation-order bucketing (`coherence/`) histograms on this: it needs a small dense
-     * integer to index a bin with, which neither the emitter id (one bucket per emitter, even when
-     * they run the same code) nor `update_offset` (an arena offset, arbitrarily large and sparse)
-     * gives it.
-     */
-    program_id: u32,
-}, "ParticleEmitter").pack();
-
-/** Sentinel for an absent render-attribute binding. */
-export const EMITTER_ATTRIBUTE_ABSENT = 0xffffffff;
-
-/**
- * Emitter flag bits. Blend mode occupies bits [4,6), projection mode bits [6,9).
- */
-export const EMITTER_FLAG = Object.freeze({
-    LIGHTING: 1 << 0,      // forward-shade billboards with scene lighting
-    SOFT_DEPTH: 1 << 1,    // fade against scene depth
-    SORT: 1 << 2,          // depth-sort this emitter's particles for correct transparency
-    CULL: 1 << 3,          // frustum + occlusion simulation culling (sleep when culled)
-});
-
-/** Blend modes (stored in flag bits [4,6)). All expressed by one premultiplied blend pipeline. */
-export const EMITTER_BLEND = Object.freeze({
-    ALPHA: 0,      // premultiplied alpha (normal transparency)
-    ADDITIVE: 1,   // additive (emissive glow)
-    PREMULTIPLIED: 2, // colour already premultiplied by alpha upstream
-});
-
-const BLEND_SHIFT = 4;
-const BLEND_MASK = 0b11 << BLEND_SHIFT;
-
-/** Projection / orientation modes (stored in flag bits [6,9)). */
-export const EMITTER_PROJECTION = Object.freeze({
-    BILLBOARD: 0,          // face the camera
-    STRETCHED: 1,          // billboard stretched along velocity
-    HORIZONTAL: 2,         // lie flat on the ground plane (XZ)
-    VERTICAL: 3,           // axis-locked to world up, yaw toward camera
-    FACING_WORLD: 4,       // oriented by the particle's own rotation attribute in world space
-});
-
-const PROJECTION_SHIFT = 6;
-const PROJECTION_MASK = 0b111 << PROJECTION_SHIFT;
-
-/**
- * Compose the flags word from feature toggles + blend + projection.
- * @param {object} options
- * @param {boolean} [options.lighting]
- * @param {boolean} [options.soft_depth]
- * @param {boolean} [options.sort]
- * @param {boolean} [options.cull]
- * @param {number} [options.blend] see {@link EMITTER_BLEND}
- * @param {number} [options.projection] see {@link EMITTER_PROJECTION}
- * @returns {number}
- */
-export function make_emitter_flags({ lighting = false, soft_depth = false, sort = false, cull = false, blend = EMITTER_BLEND.ALPHA, projection = EMITTER_PROJECTION.BILLBOARD } = {}) {
-    let flags = 0;
-    if (lighting) flags |= EMITTER_FLAG.LIGHTING;
-    if (soft_depth) flags |= EMITTER_FLAG.SOFT_DEPTH;
-    if (sort) flags |= EMITTER_FLAG.SORT;
-    if (cull) flags |= EMITTER_FLAG.CULL;
-    flags |= (blend << BLEND_SHIFT) & BLEND_MASK;
-    flags |= (projection << PROJECTION_SHIFT) & PROJECTION_MASK;
-    return flags >>> 0;
-}
-
-/** @param {number} flags @returns {number} the blend mode */
-export function emitter_flags_blend(flags) {
-    return (flags & BLEND_MASK) >>> BLEND_SHIFT;
-}
-
-/** @param {number} flags @returns {number} the projection mode */
-export function emitter_flags_projection(flags) {
-    return (flags & PROJECTION_MASK) >>> PROJECTION_SHIFT;
-}
-
-/** Shift/mask constants exposed for the WGSL reader to interpolate. */
-export const EMITTER_FLAG_ENCODING = Object.freeze({
-    BLEND_SHIFT, BLEND_MASK, PROJECTION_SHIFT, PROJECTION_MASK,
-});
+import { f32, u32, vec2f, vec3f, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * One emitter's GPU record: which compiled program it runs and where that program's code and
+ * constants sit in the {@link ../runtime/ProgramArena.js} buffers, plus the instance parameters the
+ * tick / emit / simulate / sort / render passes read — the scene node it hangs off, spawn rate,
+ * feature flags, bounds sphere, render-attribute bindings, atlas region and flipbook grid.
+ *
+ * There is no transform here. An emitter is a scene node, and its world matrix is the `global` of
+ * its row in the scene database's `transforms` table, composed on the GPU by the hierarchy pass
+ * from whatever the node is parented to. The passes that need it read it through `node`.
+ *
+ * Nor is there any per-frame state: what the GPU integrates for an emitter (spawn accumulator, age,
+ * sleep) lives in {@link ./PARTICLE_EMITTER_STATE.js}, keyed by the same row, for the reason given
+ * there.
+ *
+ * It lives in a `GPUDatabase` table (see {@link ./PARTICLE_DATABASE_SPEC.js}), so the layout below
+ * is the *only* description of it that exists: the JS writer is
+ * {@link ../../shader/type/serde/write_gpu_typed_buffer.js} and the WGSL reader is generated from
+ * this same struct by the table descriptor. Nothing hand-packs an emitter word by word any more,
+ * and there is no second copy of the offsets to keep in step.
+ *
+ * `.pack()` reorders the fields to close the padding a declaration-order layout would leave; WGSL
+ * field names are what shaders address, never offsets, so the reordering is invisible to them.
+ *
+ * @type {WebGPUStruct}
+ */
+export const PARTICLE_EMITTER_STRUCT = WebGPUStruct.from({
+    /** first instruction of the INIT program, in instruction units */
+    init_offset: u32,
+    /** INIT instruction count */
+    init_count: u32,
+    /** first instruction of the UPDATE program, in instruction units */
+    update_offset: u32,
+    /** UPDATE instruction count */
+    update_count: u32,
+    /** base into the shared constant pool, in vec4 units */
+    constant_offset: u32,
+    /** base RNG seed */
+    seed: u32,
+    /** see {@link EMITTER_FLAG} */
+    flags: u32,
+    /** continuous emission rate, particles/second, integrated on the GPU by the tick pass */
+    spawn_rate: f32,
+
+    /**
+     * Row of the scene database's `transforms` table this emitter is — its world matrix is that
+     * row's `global`.
+     */
+    node: u32,
+
+    /**
+     * Which tenancy of this row the record describes. Bumped every time the row is handed to a new
+     * emitter, never zero for a live row. Every particle carries the generation of the emitter that
+     * spawned it, and the simulate pass kills one whose generation no longer matches its row's —
+     * see {@link ./particle_header.js}.
+     */
+    generation: u32,
+
+    /** local-space bounding sphere centre */
+    bounds_center: vec3f,
+    /** bounding sphere radius */
+    bounds_radius: f32,
+
+    /** attribute word offset of world position (or {@link EMITTER_ATTRIBUTE_ABSENT}) */
+    render_position: u32,
+    /** attribute word offset of size */
+    render_size: u32,
+    /** attribute word offset of rgba colour */
+    render_color: u32,
+    /** attribute word offset of roll angle, radians */
+    render_rotation: u32,
+    /** attribute word offset of flipbook frame index */
+    render_frame: u32,
+    /** attribute word offset of velocity (STRETCHED projection) */
+    render_velocity: u32,
+
+    /** uv offset .xy + uv scale .zw */
+    atlas_region: vec4f,
+    /** flipbook grid: columns, rows */
+    flipbook: vec2f,
+
+    /**
+     * Id of the compiled program this emitter runs, assigned by {@link ../runtime/ProgramHeap.js}.
+     * Emitters sharing a program share an id.
+     *
+     * The simulation-order bucketing (`coherence/`) histograms on this: it needs a small integer to
+     * index a bin with, which neither the emitter id (one bucket per emitter, even when they run the
+     * same code) nor `update_offset` (a heap offset, arbitrarily large and sparse) gives it. Ids are
+     * reused as effects come and go, so they stay below the set's peak program count rather than
+     * climbing with churn.
+     */
+    program_id: u32,
+}, "ParticleEmitter").pack();
+
+/** Sentinel for an absent render-attribute binding. */
+export const EMITTER_ATTRIBUTE_ABSENT = 0xffffffff;
+
+/**
+ * Emitter flag bits. Blend mode occupies bits [4,6), projection mode bits [6,9).
+ */
+export const EMITTER_FLAG = Object.freeze({
+    LIGHTING: 1 << 0,      // forward-shade billboards with scene lighting
+    SOFT_DEPTH: 1 << 1,    // fade against scene depth
+    SORT: 1 << 2,          // depth-sort this emitter's particles for correct transparency
+    CULL: 1 << 3,          // frustum + occlusion simulation culling (sleep when culled)
+});
+
+/** Blend modes (stored in flag bits [4,6)). All expressed by one premultiplied blend pipeline. */
+export const EMITTER_BLEND = Object.freeze({
+    ALPHA: 0,      // premultiplied alpha (normal transparency)
+    ADDITIVE: 1,   // additive (emissive glow)
+    PREMULTIPLIED: 2, // colour already premultiplied by alpha upstream
+});
+
+const BLEND_SHIFT = 4;
+const BLEND_MASK = 0b11 << BLEND_SHIFT;
+
+/** Projection / orientation modes (stored in flag bits [6,9)). */
+export const EMITTER_PROJECTION = Object.freeze({
+    BILLBOARD: 0,          // face the camera
+    STRETCHED: 1,          // billboard stretched along velocity
+    HORIZONTAL: 2,         // lie flat on the ground plane (XZ)
+    VERTICAL: 3,           // axis-locked to world up, yaw toward camera
+    FACING_WORLD: 4,       // oriented by the particle's own rotation attribute in world space
+});
+
+const PROJECTION_SHIFT = 6;
+const PROJECTION_MASK = 0b111 << PROJECTION_SHIFT;
+
+/**
+ * Compose the flags word from feature toggles + blend + projection.
+ * @param {object} options
+ * @param {boolean} [options.lighting]
+ * @param {boolean} [options.soft_depth]
+ * @param {boolean} [options.sort]
+ * @param {boolean} [options.cull]
+ * @param {number} [options.blend] see {@link EMITTER_BLEND}
+ * @param {number} [options.projection] see {@link EMITTER_PROJECTION}
+ * @returns {number}
+ */
+export function make_emitter_flags({ lighting = false, soft_depth = false, sort = false, cull = false, blend = EMITTER_BLEND.ALPHA, projection = EMITTER_PROJECTION.BILLBOARD } = {}) {
+    let flags = 0;
+    if (lighting) flags |= EMITTER_FLAG.LIGHTING;
+    if (soft_depth) flags |= EMITTER_FLAG.SOFT_DEPTH;
+    if (sort) flags |= EMITTER_FLAG.SORT;
+    if (cull) flags |= EMITTER_FLAG.CULL;
+    flags |= (blend << BLEND_SHIFT) & BLEND_MASK;
+    flags |= (projection << PROJECTION_SHIFT) & PROJECTION_MASK;
+    return flags >>> 0;
+}
+
+/** @param {number} flags @returns {number} the blend mode */
+export function emitter_flags_blend(flags) {
+    return (flags & BLEND_MASK) >>> BLEND_SHIFT;
+}
+
+/** @param {number} flags @returns {number} the projection mode */
+export function emitter_flags_projection(flags) {
+    return (flags & PROJECTION_MASK) >>> PROJECTION_SHIFT;
+}
+
+/** Shift/mask constants exposed for the WGSL reader to interpolate. */
+export const EMITTER_FLAG_ENCODING = Object.freeze({
+    BLEND_SHIFT, BLEND_MASK, PROJECTION_SHIFT, PROJECTION_MASK,
+});

package/src/shade/renderer/particles/data/particle_emitter_record.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The translation between an emitter and the row the GPU reads for it: one function that fills a
+ * {@link ./PARTICLE_EMITTER_STRUCT.js} record from a {@link ../runtime/ParticleEmitter.js} and the
+ * {@link ../runtime/GPUParticleEmitterContext.js} the registry holds for it.
+ *
+ * It sits here, with the struct, rather than on the emitter. Half of what a row says is the
+ * context's — the program placement, the tenancy, the `transforms` row, the atlas patch — and the other
+ * half only means anything in the terms this struct sets: `render_position` is a word offset
+ * because that is what the render pass indexes a particle record with. An emitter that knew how to
+ * write one would be an emitter that knew what a table row is.
+ */
+/**
+ * Fill `record` with an emitter as the value the emitter table stores — every field of
+ * {@link ./PARTICLE_EMITTER_STRUCT.js}, none omitted.
+ *
+ * Omitting one would not write zeros: the serializer skips absent fields, and table pages are
+ * recycled buffers, so a skipped field keeps whatever the previous tenant of the slot left there.
+ *
+ * Writes into a caller-supplied object rather than returning a fresh one so the registry can stage
+ * every row of a frame through one module-static record — the table serializes it synchronously, so
+ * nothing outlives the call.
+ *
+ * @param {object} record the staging object, see {@link create_emitter_record}
+ * @param {import("../runtime/ParticleEmitter.js").ParticleEmitter} emitter
+ * @param {import("../runtime/GPUParticleEmitterContext.js").GPUParticleEmitterContext} context the
+ *        registry's bookkeeping for `emitter`
+ * @returns {object} `record`
+ */
+export function write_emitter_record(record: object, emitter: import("../runtime/ParticleEmitter.js").ParticleEmitter, context: import("../runtime/GPUParticleEmitterContext.js").GPUParticleEmitterContext): object;
+/**
+ * An empty staging record with every field of {@link ./PARTICLE_EMITTER_STRUCT.js} present, typed
+ * arrays for the vector fields so {@link write_emitter_record} can copy into them.
+ *
+ * @returns {object}
+ */
+export function create_emitter_record(): object;
+//# sourceMappingURL=particle_emitter_record.d.ts.map

package/src/shade/renderer/particles/data/particle_emitter_record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_emitter_record.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/particle_emitter_record.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,6CANW,MAAM,WACN,OAAO,+BAA+B,EAAE,eAAe,WACvD,OAAO,yCAAyC,EAAE,yBAAyB,GAEzE,MAAM,CA2ClB;AAED;;;;;GAKG;AACH,yCAFa,MAAM,CA8BlB"}