@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"PARTICLE_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_DATABASE_SPEC.js"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,yCAFU,MAAM,CAEwC;AAExD;;;;;;GAMG;AACH,6CAFU,MAAM,CAE4C;AAE5D,uEAAuE;AACvE,gDAAiD;AAEjD,uFAAuF;AACvF,2DAA4D;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,qCAFU,qBAAqB,CAKA;AAE/B;;;;;;GAMG;AACH,kEAA8F;AAE9F;;;;;GAKG;AACH,wEAA0G;sCAlEpE,6CAA6C"}

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

@@ -0,0 +1,68 @@
+import { KILOBYTE } from "../../../../core/science/units/memory/KILOBYTE.js";
+import { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.js";
+import { PARTICLE_EMITTER_STATE_STRUCT } from "./PARTICLE_EMITTER_STATE.js";
+import { PARTICLE_EMITTER_STRUCT } from "./PARTICLE_EMITTER_STRUCT.js";
+
+/**
+ * Emitters are counted in tens, not thousands, so the engine-wide default page (128 KB) would
+ * reserve two orders of magnitude more than a scene ever fills. 16 KB still holds ~140 emitters per
+ * page and the table grows a page at a time past that.
+ *
+ * @type {number}
+ */
+export const PARTICLE_EMITTER_PAGE_SIZE = 16 * KILOBYTE;
+
+/**
+ * How big an emitter database's buffer starts out. The page address table takes 32 KB (two tables'
+ * worth of `GPU_DATABASE_PAGE_LIMIT` u32 slots), so this leaves room for one page of each table —
+ * around a hundred and forty emitters — before the database grows itself.
+ *
+ * @type {number}
+ */
+export const PARTICLE_DATABASE_INITIAL_SIZE = 64 * KILOBYTE;
+
+/** Name of the emitter table within {@link PARTICLE_DATABASE_SPEC}. */
+export const PARTICLE_EMITTER_TABLE = "emitters";
+
+/** Name of the GPU-owned emitter state table within {@link PARTICLE_DATABASE_SPEC}. */
+export const PARTICLE_EMITTER_STATE_TABLE = "emitter_state";
+
+/**
+ * Schema of the particle system's GPU database. Two tables, one row per emitter in each, at the
+ * same row index:
+ *
+ * - `emitters` — CPU-authored and low-churn, exactly the shape `GPUDatabase` is for. Adding or
+ *   removing one emitter queues that one record for upload; the rest of the table is not touched,
+ *   and the pass shaders address rows by a stable id that survives its neighbours coming and going.
+ * - `emitter_state` — GPU-owned ({@link ./PARTICLE_EMITTER_STATE.js}): claimed with a zero record
+ *   when the emitter's row is, then written only by the tick and spawn-command passes.
+ *
+ * One buffer for both is what keeps every pass that reads an emitter at one binding for the pair.
+ *
+ * Programs and their constant pools are NOT here: they are variable-length and shared between
+ * emitters, so they live in the packed {@link ../runtime/ProgramArena.js} buffer, referenced by the
+ * offsets each emitter record carries.
+ *
+ * @type {GPUDatabaseDefinition}
+ */
+export const PARTICLE_DATABASE_SPEC = GPUDatabaseDefinition.from({
+    [PARTICLE_EMITTER_TABLE]: PARTICLE_EMITTER_STRUCT,
+    [PARTICLE_EMITTER_STATE_TABLE]: PARTICLE_EMITTER_STATE_STRUCT,
+}, PARTICLE_EMITTER_PAGE_SIZE);
+
+/**
+ * Descriptor for the emitter table — the source of the WGSL reader every emitter-consuming pass
+ * pulls in ({@link GPUTypedTableDescriptor#chunk_read}, and
+ * {@link GPUTypedTableDescriptor#chunk_read_field} for the passes that want a single field).
+ *
+ * @type {GPUTypedTableDescriptor}
+ */
+export const PARTICLE_EMITTER_DESCRIPTOR = PARTICLE_DATABASE_SPEC.get(PARTICLE_EMITTER_TABLE);
+
+/**
+ * Descriptor for the state table — the tick pass reads and writes whole rows through it, the
+ * spawn-command pass adds to one, and the emit / simulate passes read the age off it.
+ *
+ * @type {GPUTypedTableDescriptor}
+ */
+export const PARTICLE_EMITTER_STATE_DESCRIPTOR = PARTICLE_DATABASE_SPEC.get(PARTICLE_EMITTER_STATE_TABLE);

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

@@ -0,0 +1,39 @@
+/**
+ * The GPU-owned per-emitter state: the values the emitter tick pass integrates from frame to
+ * frame. A row of the `emitter_state` table of the particle database
+ * ({@link ./PARTICLE_DATABASE_SPEC.js}), at the same row index as the emitter's record in the
+ * `emitters` table.
+ *
+ * It is a table of its own, not extra fields on the emitter record, because the record is
+ * CPU-shadowed and restaged whole whenever the author changes a field — and that restage would
+ * overwrite an accumulator the GPU has been adding to for a hundred frames with whatever the CPU
+ * shadow last held. The scene's transforms table gets away with mixing CPU fields and a
+ * GPU-written `global` in one row only because `global` is recomputed from scratch every frame;
+ * nothing here is. In its own table the CPU touches a row exactly twice: a zero record when the
+ * emitter's row is claimed, and the table's own zero-fill when it is released.
+ *
+ * Sharing the database buffer with the emitter table is what keeps the tick, emit and simulate
+ * passes at one binding for both, which matters against the eight storage buffers a stage gets by
+ * default. Nothing in it is atomic: each row is visited by one thread of the tick, and the
+ * spawn-command pass that adds to `pending` is handed one command per row, merged on the CPU.
+ *
+ * Rows are recognised by generation, not cleared by the CPU: the tick pass compares `generation`
+ * against the record's and starts the row over on a mismatch. A freshly allocated page and a reused
+ * row both fall out of that one rule.
+ *
+ * @type {WebGPUStruct}
+ */
+export const PARTICLE_EMITTER_STATE_STRUCT: WebGPUStruct;
+/**
+ * A state row as the CPU stages it when an emitter claims a row: nothing yet. Generation zero is
+ * never a live emitter's, so the first tick starts the row over whatever it held before.
+ */
+export const PARTICLE_EMITTER_STATE_EMPTY: Readonly<{
+    generation: 0;
+    accumulator: 0;
+    age: 0;
+    sleep: 0;
+    pending: 0;
+}>;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=PARTICLE_EMITTER_STATE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PARTICLE_EMITTER_STATE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STATE.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,4CAFU,YAAY,CAaY;AAElC;;;GAGG;AACH;;;;;;GAMG;6BAlD0B,mCAAmC"}

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

@@ -0,0 +1,52 @@
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * The GPU-owned per-emitter state: the values the emitter tick pass integrates from frame to
+ * frame. A row of the `emitter_state` table of the particle database
+ * ({@link ./PARTICLE_DATABASE_SPEC.js}), at the same row index as the emitter's record in the
+ * `emitters` table.
+ *
+ * It is a table of its own, not extra fields on the emitter record, because the record is
+ * CPU-shadowed and restaged whole whenever the author changes a field — and that restage would
+ * overwrite an accumulator the GPU has been adding to for a hundred frames with whatever the CPU
+ * shadow last held. The scene's transforms table gets away with mixing CPU fields and a
+ * GPU-written `global` in one row only because `global` is recomputed from scratch every frame;
+ * nothing here is. In its own table the CPU touches a row exactly twice: a zero record when the
+ * emitter's row is claimed, and the table's own zero-fill when it is released.
+ *
+ * Sharing the database buffer with the emitter table is what keeps the tick, emit and simulate
+ * passes at one binding for both, which matters against the eight storage buffers a stage gets by
+ * default. Nothing in it is atomic: each row is visited by one thread of the tick, and the
+ * spawn-command pass that adds to `pending` is handed one command per row, merged on the CPU.
+ *
+ * Rows are recognised by generation, not cleared by the CPU: the tick pass compares `generation`
+ * against the record's and starts the row over on a mismatch. A freshly allocated page and a reused
+ * row both fall out of that one rule.
+ *
+ * @type {WebGPUStruct}
+ */
+export const PARTICLE_EMITTER_STATE_STRUCT = WebGPUStruct.from({
+    /** the emitter generation this state belongs to; a mismatch with the record resets the row */
+    generation: u32,
+    /** fractional particles owed, carried across frames */
+    accumulator: f32,
+    /** seconds since the emitter's row was (re)started — the EMITTER_AGE builtin */
+    age: f32,
+    /** seconds spent culled since last visible; paid back as a bounded burst on wake */
+    sleep: f32,
+    /** particles requested by the spawn-command pass since the last tick, consumed by the tick */
+    pending: u32,
+}, "ParticleEmitterState").pack();
+
+/**
+ * A state row as the CPU stages it when an emitter claims a row: nothing yet. Generation zero is
+ * never a live emitter's, so the first tick starts the row over whatever it held before.
+ */
+export const PARTICLE_EMITTER_STATE_EMPTY = Object.freeze({
+    generation: 0,
+    accumulator: 0,
+    age: 0,
+    sleep: 0,
+    pending: 0,
+});

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

@@ -0,0 +1,83 @@
+/**
+ * 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, soft_depth, sort, cull, blend, projection }?: {
+    lighting?: boolean;
+    soft_depth?: boolean;
+    sort?: boolean;
+    cull?: boolean;
+    blend?: number;
+    projection?: number;
+}): number;
+/** @param {number} flags @returns {number} the blend mode */
+export function emitter_flags_blend(flags: number): number;
+/** @param {number} flags @returns {number} the projection mode */
+export function emitter_flags_projection(flags: number): number;
+/**
+ * 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;
+/** Sentinel for an absent render-attribute binding. */
+export const EMITTER_ATTRIBUTE_ABSENT: 4294967295;
+/**
+ * Emitter flag bits. Blend mode occupies bits [4,6), projection mode bits [6,9).
+ */
+export const EMITTER_FLAG: Readonly<{
+    LIGHTING: number;
+    SOFT_DEPTH: number;
+    SORT: number;
+    CULL: number;
+}>;
+/** Blend modes (stored in flag bits [4,6)). All expressed by one premultiplied blend pipeline. */
+export const EMITTER_BLEND: Readonly<{
+    ALPHA: 0;
+    ADDITIVE: 1;
+    PREMULTIPLIED: 2;
+}>;
+/** Projection / orientation modes (stored in flag bits [6,9)). */
+export const EMITTER_PROJECTION: Readonly<{
+    BILLBOARD: 0;
+    STRETCHED: 1;
+    HORIZONTAL: 2;
+    VERTICAL: 3;
+    FACING_WORLD: 4;
+}>;
+/** Shift/mask constants exposed for the WGSL reader to interpolate. */
+export const EMITTER_FLAG_ENCODING: Readonly<{
+    BLEND_SHIFT: 4;
+    BLEND_MASK: number;
+    PROJECTION_SHIFT: 6;
+    PROJECTION_MASK: number;
+}>;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=PARTICLE_EMITTER_STRUCT.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,166 @@
+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,
+});

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

@@ -1,13 +1,29 @@
 /**
- * WGSL reader for emitter records stored in an `array<u32>` (see
- * {@link ./PARTICLE_EMITTER_LAYOUT.js}). `particle_emitter_read` decodes one record into a value-type
- * `ParticleEmitter` struct; helpers extract the blend and projection sub-fields from `flags`.
+ * WGSL access to emitter records.
  *
- * Reading via explicit indexing (rather than an `array<Struct>` binding) keeps every consuming shader
- * reliable under the WGSL emulator.
+ * The reader itself is not written here: emitters live in a `GPUDatabase` table, so the
+ * `ParticleEmitter` struct declaration and the function that decodes one row of it are both
+ * generated from {@link ./PARTICLE_EMITTER_STRUCT.js} by the table descriptor. Pulling this chunk in
+ * brings them along; call {@link particle_emitter_read} with the database binding and a row id.
+ * There is no second, hand-maintained copy of the layout for them to disagree with.
+ *
+ * What is written here is the part the struct cannot express: `flags` packs four feature bits, a
+ * two-bit blend mode and a three-bit projection mode into one word, and these two helpers are the
+ * shift/mask pair that gets the sub-fields back out.
  *
  * @type {CodeChunk}
  */
 export const chunk_particle_emitter: CodeChunk;
+/**
+ * Reader for just the emitter's `program_id` — the simulation-order bucket key.
+ *
+ * Split out from {@link chunk_particle_emitter} because the histogram pass that wants it runs once
+ * per live PARTICLE, and decoding a whole emitter record (transform matrix included) to reach one
+ * word would be pure waste at that rate. Call
+ * {@link PARTICLE_EMITTER_DESCRIPTOR#marshalling_method_read_field}`('program_id')`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter_program_id: CodeChunk;
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 //# sourceMappingURL=chunk_particle_emitter.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_emitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/chunk_particle_emitter.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,qCAFU,SAAS,CAuEhB;0BApFuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_emitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/chunk_particle_emitter.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,qCAFU,SAAS,CAc0B;AAE7C;;;;;;;;;GASG;AACH,gDAFU,SAAS,CAEyF;0BA3ClF,oCAAoC"}

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

@@ -1,85 +1,44 @@
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { EMITTER_FIELD, EMITTER_FLAG_ENCODING, EMITTER_STRIDE } from "./PARTICLE_EMITTER_LAYOUT.js";
-
-const F = EMITTER_FIELD;
-
-/**
- * WGSL reader for emitter records stored in an `array<u32>` (see
- * {@link ./PARTICLE_EMITTER_LAYOUT.js}). `particle_emitter_read` decodes one record into a value-type
- * `ParticleEmitter` struct; helpers extract the blend and projection sub-fields from `flags`.
- *
- * Reading via explicit indexing (rather than an `array<Struct>` binding) keeps every consuming shader
- * reliable under the WGSL emulator.
- *
- * @type {CodeChunk}
- */
-export const chunk_particle_emitter = CodeChunk.from(/* language=wgsl */ `
-const PARTICLE_EMITTER_STRIDE : u32 = ${EMITTER_STRIDE}u;
-const EMITTER_BLEND_SHIFT : u32 = ${EMITTER_FLAG_ENCODING.BLEND_SHIFT}u;
-const EMITTER_BLEND_MASK : u32 = ${EMITTER_FLAG_ENCODING.BLEND_MASK}u;
-const EMITTER_PROJECTION_SHIFT : u32 = ${EMITTER_FLAG_ENCODING.PROJECTION_SHIFT}u;
-const EMITTER_PROJECTION_MASK : u32 = ${EMITTER_FLAG_ENCODING.PROJECTION_MASK}u;
-
-struct ParticleEmitter {
-    spawn_offset : u32,
-    spawn_count : u32,
-    update_offset : u32,
-    update_count : u32,
-    constant_offset : u32,
-    seed : u32,
-    flags : u32,
-    spawn_rate : f32,
-    transform : mat4x4<f32>,
-    bounds_center : vec3<f32>,
-    bounds_radius : f32,
-    render_position : u32,
-    render_size : u32,
-    render_color : u32,
-    render_rotation : u32,
-    render_frame : u32,
-    render_velocity : u32,
-    atlas_region : vec4<f32>,
-    flipbook : vec2<f32>,
-    program_id : u32,
-}
-
-fn particle_emitter_read(e : ptr<storage, array<u32>, read>, index : u32) -> ParticleEmitter {
-    let b = index * PARTICLE_EMITTER_STRIDE;
-    var r : ParticleEmitter;
-    r.spawn_offset = (*e)[b + ${F.SPAWN_OFFSET}u];
-    r.spawn_count = (*e)[b + ${F.SPAWN_COUNT}u];
-    r.update_offset = (*e)[b + ${F.UPDATE_OFFSET}u];
-    r.update_count = (*e)[b + ${F.UPDATE_COUNT}u];
-    r.constant_offset = (*e)[b + ${F.CONSTANT_OFFSET}u];
-    r.seed = (*e)[b + ${F.SEED}u];
-    r.flags = (*e)[b + ${F.FLAGS}u];
-    r.spawn_rate = bitcast<f32>((*e)[b + ${F.SPAWN_RATE}u]);
-
-    let t = b + ${F.TRANSFORM}u;
-    r.transform = mat4x4<f32>(
-        vec4<f32>(bitcast<f32>((*e)[t + 0u]), bitcast<f32>((*e)[t + 1u]), bitcast<f32>((*e)[t + 2u]), bitcast<f32>((*e)[t + 3u])),
-        vec4<f32>(bitcast<f32>((*e)[t + 4u]), bitcast<f32>((*e)[t + 5u]), bitcast<f32>((*e)[t + 6u]), bitcast<f32>((*e)[t + 7u])),
-        vec4<f32>(bitcast<f32>((*e)[t + 8u]), bitcast<f32>((*e)[t + 9u]), bitcast<f32>((*e)[t + 10u]), bitcast<f32>((*e)[t + 11u])),
-        vec4<f32>(bitcast<f32>((*e)[t + 12u]), bitcast<f32>((*e)[t + 13u]), bitcast<f32>((*e)[t + 14u]), bitcast<f32>((*e)[t + 15u])),
-    );
-
-    r.bounds_center = vec3<f32>(bitcast<f32>((*e)[b + ${F.BOUNDS_CENTER}u]), bitcast<f32>((*e)[b + ${F.BOUNDS_CENTER + 1}u]), bitcast<f32>((*e)[b + ${F.BOUNDS_CENTER + 2}u]));
-    r.bounds_radius = bitcast<f32>((*e)[b + ${F.BOUNDS_RADIUS}u]);
-
-    r.render_position = (*e)[b + ${F.RENDER_POSITION}u];
-    r.render_size = (*e)[b + ${F.RENDER_SIZE}u];
-    r.render_color = (*e)[b + ${F.RENDER_COLOR}u];
-    r.render_rotation = (*e)[b + ${F.RENDER_ROTATION}u];
-    r.render_frame = (*e)[b + ${F.RENDER_FRAME}u];
-    r.render_velocity = (*e)[b + ${F.RENDER_VELOCITY}u];
-
-    r.atlas_region = vec4<f32>(bitcast<f32>((*e)[b + ${F.ATLAS_REGION}u]), bitcast<f32>((*e)[b + ${F.ATLAS_REGION + 1}u]), bitcast<f32>((*e)[b + ${F.ATLAS_REGION + 2}u]), bitcast<f32>((*e)[b + ${F.ATLAS_REGION + 3}u]));
-    r.flipbook = vec2<f32>(bitcast<f32>((*e)[b + ${F.FLIPBOOK}u]), bitcast<f32>((*e)[b + ${F.FLIPBOOK + 1}u]));
-
-    r.program_id = (*e)[b + ${F.PROGRAM_ID}u];
-    return r;
-}
-
-fn particle_emitter_blend(flags : u32) -> u32 { return (flags & EMITTER_BLEND_MASK) >> EMITTER_BLEND_SHIFT; }
-fn particle_emitter_projection(flags : u32) -> u32 { return (flags & EMITTER_PROJECTION_MASK) >> EMITTER_PROJECTION_SHIFT; }
-`);
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_EMITTER_DESCRIPTOR } from "./PARTICLE_DATABASE_SPEC.js";
+import { EMITTER_FLAG_ENCODING } from "./PARTICLE_EMITTER_STRUCT.js";
+
+/**
+ * WGSL access to emitter records.
+ *
+ * The reader itself is not written here: emitters live in a `GPUDatabase` table, so the
+ * `ParticleEmitter` struct declaration and the function that decodes one row of it are both
+ * generated from {@link ./PARTICLE_EMITTER_STRUCT.js} by the table descriptor. Pulling this chunk in
+ * brings them along; call {@link particle_emitter_read} with the database binding and a row id.
+ * There is no second, hand-maintained copy of the layout for them to disagree with.
+ *
+ * What is written here is the part the struct cannot express: `flags` packs four feature bits, a
+ * two-bit blend mode and a three-bit projection mode into one word, and these two helpers are the
+ * shift/mask pair that gets the sub-fields back out.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter = CodeChunk.from(/* language=wgsl */ `
+const EMITTER_BLEND_SHIFT : u32 = ${EMITTER_FLAG_ENCODING.BLEND_SHIFT}u;
+const EMITTER_BLEND_MASK : u32 = ${EMITTER_FLAG_ENCODING.BLEND_MASK}u;
+const EMITTER_PROJECTION_SHIFT : u32 = ${EMITTER_FLAG_ENCODING.PROJECTION_SHIFT}u;
+const EMITTER_PROJECTION_MASK : u32 = ${EMITTER_FLAG_ENCODING.PROJECTION_MASK}u;
+
+fn particle_emitter_read(database : ptr<storage, array<u32>>, index : u32) -> ParticleEmitter {
+    return ${PARTICLE_EMITTER_DESCRIPTOR.marshalling_method_read}(database, index);
+}
+
+fn particle_emitter_blend(flags : u32) -> u32 { return (flags & EMITTER_BLEND_MASK) >> EMITTER_BLEND_SHIFT; }
+fn particle_emitter_projection(flags : u32) -> u32 { return (flags & EMITTER_PROJECTION_MASK) >> EMITTER_PROJECTION_SHIFT; }
+`, [PARTICLE_EMITTER_DESCRIPTOR.chunk_read]);
+
+/**
+ * Reader for just the emitter's `program_id` — the simulation-order bucket key.
+ *
+ * Split out from {@link chunk_particle_emitter} because the histogram pass that wants it runs once
+ * per live PARTICLE, and decoding a whole emitter record (transform matrix included) to reach one
+ * word would be pure waste at that rate. Call
+ * {@link PARTICLE_EMITTER_DESCRIPTOR#marshalling_method_read_field}`('program_id')`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter_program_id = PARTICLE_EMITTER_DESCRIPTOR.chunk_read_field('program_id');

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

@@ -0,0 +1,62 @@
+/**
+ * The generation that follows `generation` when a row is reused — skips zero on wrap.
+ *
+ * @param {number} generation
+ * @returns {number}
+ */
+export function particle_generation_next(generation: number): number;
+/**
+ * @param {number} emitter_row
+ * @param {number} generation
+ * @returns {number} the packed header word
+ */
+export function particle_header_pack(emitter_row: number, generation: number): number;
+/**
+ * @param {number} header
+ * @returns {number} emitter row
+ */
+export function particle_header_emitter(header: number): number;
+/**
+ * @param {number} header
+ * @returns {number} generation
+ */
+export function particle_header_generation(header: number): number;
+/**
+ * Encoding of a particle record's header word: which emitter row the particle belongs to, and the
+ * generation that row had when the particle was born.
+ *
+ * The row alone is not enough. Rows are reused — a removed emitter's row goes to the next emitter
+ * added — and the particles of the removed one are still in flight, carrying that row. Without a
+ * generation they would adopt the newcomer: run its program, follow its node, draw with its atlas.
+ * With one, the simulate pass compares the particle's generation against the row's and kills any
+ * particle whose emitter has gone, within a frame of it going. A freed row is zero-filled by the
+ * table, and a live row's generation is never zero, so the check also covers the window between a
+ * removal and the next add.
+ *
+ * Layout: low 16 bits = emitter row, high 16 bits = generation. Sixteen bits of row is the same
+ * bound the emitter table's page limit implies; sixteen bits of generation wraps after 65535
+ * reuses of one row, which at a removal per frame is eighteen minutes of churn on one row before a
+ * collision is even possible, and the colliding particle would have to have lived that long.
+ *
+ * The WGSL side is {@link chunk_particle_header}; the two must agree, so both read the constants
+ * below.
+ */
+/** @type {number} */
+export const PARTICLE_HEADER_EMITTER_MASK: number;
+/** @type {number} */
+export const PARTICLE_HEADER_GENERATION_SHIFT: number;
+/** @type {number} */
+export const PARTICLE_HEADER_GENERATION_MASK: number;
+/**
+ * The first generation a row is given. Zero is what a freed row reads as, so it is never live.
+ * @type {number}
+ */
+export const PARTICLE_GENERATION_FIRST: number;
+/**
+ * The same encoding, for every pass that reads a record's header word.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_header: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=particle_header.d.ts.map