@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -11,7 +11,9 @@ import {
     PARTICLE_SIM_PAD_SLOT,
 } from "../ParticleConstants.js";
 import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import { EMITTER_FIELD, EMITTER_STRIDE } from "../data/PARTICLE_EMITTER_LAYOUT.js";
+import { PARTICLE_EMITTER_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+import { chunk_particle_emitter_program_id } from "../data/chunk_particle_emitter.js";
+import { chunk_particle_header } from "../data/particle_header.js";
 
 /**
  * Simulation-order bucketing — the passes that make each simulate wave run ONE VM program.
@@ -26,6 +28,11 @@ import { EMITTER_FIELD, EMITTER_STRIDE } from "../data/PARTICLE_EMITTER_LAYOUT.j
  * a waterfall loop whose trip count is the number of DISTINCT register indices live in the wave.
  * Grouping the wave by program collapses both at once.
  *
+ * It is also load-bearing, not only a speed-up: the simulate pass reads its section parameters
+ * from the wave's first lane (`particle_wave_uniform` in `../shaders/shader_particle_simulate.js`),
+ * so a wave holding two programs would run one of them over the other's particles. The grouping is
+ * the contract that pass compiles against.
+ *
  * ## Shape
  *
  * The same three-phase shape the depth sort uses, with two small passes added for the padding:
@@ -82,7 +89,7 @@ const PAD_MASK = (~(WG - 1)) >>> 0;
 const WG_LOG = Math.log2(WG);
 
 /** Constants every pass in this file interpolates. */
-const COMMON = /* wgsl */ `
+const COMMON = /* language=wgsl */ `
 const BUCKET_HEADER_WORDS : u32 = ${HEADER}u;
 const BUCKET_ALIGNMENT : u32 = ${WG}u;
 const BUCKET_PAD_MASK : u32 = ${PAD_MASK}u;
@@ -113,7 +120,7 @@ reset_resources.createGroup()
 export const shader_particle_bucket_reset = ComputeShader.from({
     label: "Particle Bucket Reset",
     resources: reset_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(/* language=wgsl */ `
 ${COMMON}
 
 @compute @workgroup_size(${WG}, 1, 1)
@@ -156,7 +163,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
 const histogram_resources = new ShaderResourceSetDescriptor();
 
 histogram_resources.createGroup()
-    .addStorageBuffer("emitters", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
     .addStorageBuffer("pool", WebGPUArray.u32, false)
     .addStorageBuffer("alive", WebGPUArray.u32, false)
     .addStorageBuffer("keys", WebGPUArray.u32, true)
@@ -168,8 +175,8 @@ histogram_resources.createGroup()
  * (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}
@@ -177,12 +184,10 @@ histogram_resources.createGroup()
 export const shader_particle_bucket_histogram = ComputeShader.from({
     label: "Particle Bucket Histogram",
     resources: histogram_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(/* language=wgsl */ `
 ${COMMON}
 const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
 const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
-const PARTICLE_EMITTER_RECORD_WORDS : u32 = ${EMITTER_STRIDE}u;
-const EMITTER_WORD_PROGRAM_ID : u32 = ${EMITTER_FIELD.PROGRAM_ID}u;
 
 @compute @workgroup_size(${WG}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
@@ -190,13 +195,13 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
 
     let slot = alive[i];
-    let emitter_index = pool[slot * PARTICLE_RECORD_WORDS + PARTICLE_HEADER_EMITTER];
-    let program = emitters[emitter_index * PARTICLE_EMITTER_RECORD_WORDS + EMITTER_WORD_PROGRAM_ID];
+    let emitter_index = particle_header_emitter(pool[slot * PARTICLE_RECORD_WORDS + PARTICLE_HEADER_EMITTER]);
+    let program = ${PARTICLE_EMITTER_DESCRIPTOR.marshalling_method_read_field('program_id')}(&emitter_database, emitter_index);
 
     keys[i] = program;
     atomicAdd(&histogram[BUCKET_HEADER_WORDS + program], 1u);
 }
-`),
+`, [chunk_particle_emitter_program_id, chunk_particle_header]),
 });
 
 // --- 2. pad -----------------------------------------------------------------------------------
@@ -223,7 +228,7 @@ pad_resources.createGroup()
 export const shader_particle_bucket_pad = ComputeShader.from({
     label: "Particle Bucket Pad",
     resources: pad_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(/* language=wgsl */ `
 ${COMMON}
 
 @compute @workgroup_size(${WG}, 1, 1)
@@ -264,7 +269,7 @@ scatter_resources.createGroup()
 export const shader_particle_bucket_scatter = ComputeShader.from({
     label: "Particle Bucket Scatter",
     resources: scatter_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(/* language=wgsl */ `
 ${COMMON}
 
 @compute @workgroup_size(${WG}, 1, 1)
@@ -313,7 +318,7 @@ fill_resources.createGroup()
 export const shader_particle_bucket_fill = ComputeShader.from({
     label: "Particle Bucket Fill",
     resources: fill_resources,
-    body: CodeChunk.from(/* wgsl */ `
+    body: CodeChunk.from(/* language=wgsl */ `
 ${COMMON}
 const PARTICLE_SIM_PAD_SLOT : u32 = ${PARTICLE_SIM_PAD_SLOT}u;
 

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

@@ -8,8 +8,13 @@ export const PARTICLE_COUNTER: Readonly<{
     ALIVE: 0;
     /** length of the dead (free) list */
     DEAD: 1;
-    /** number of particles requested to spawn this frame */
-    SPAWN: 2;
+    /**
+     * Free slots not yet promised to a spawn this frame. The reset pass seeds it from
+     * {@link DEAD}; the emitter tick pass takes from it as it decides each emitter's spawn count,
+     * so an emitter is only ever debited for particles the pool can actually hold. What is left at
+     * the end of the frame is the headroom the frame had.
+     */
+    SPAWN_BUDGET: 2;
     /**
      * Length of the depth-sorted index list — the RENDER order (`../sort/`), back-to-front by view
      * depth so premultiplied transparency composites correctly. Belongs to the camera-dependent
@@ -44,10 +49,4 @@ export const PARTICLE_COUNTER: Readonly<{
 }>;
 /** Number of `u32` atomic slots in the counters buffer. */
 export const PARTICLE_COUNTER_COUNT: 8;
-/**
- * Per-dispatch uniform for the simulate/emit passes.
- * @type {WebGPUStruct}
- */
-export const PARTICLE_SIM_UNIFORM_STRUCT: WebGPUStruct;
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 //# sourceMappingURL=PARTICLE_COUNTERS.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PARTICLE_COUNTERS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_COUNTERS.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC,wDAAwD;;IAExD;;;;;;OAMG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;GAEJ;AAEH,2DAA2D;AAC3D,uCAAwC;AAExC;;;GAGG;AACH,0CAFU,YAAY,CAQG;6BA5DI,mCAAmC"}
+{"version":3,"file":"PARTICLE_COUNTERS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_COUNTERS.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;GAEJ;AAEH,2DAA2D;AAC3D,uCAAwC"}

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

@@ -1,6 +1,3 @@
-import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
-
 /**
  * Indices into the particle counters buffer (an `array<atomic<u32>>`). The simulate/emit passes use
  * atomics on these slots to append to the alive/dead lists; a finalize pass turns the counts into
@@ -11,8 +8,13 @@ export const PARTICLE_COUNTER = Object.freeze({
     ALIVE: 0,
     /** length of the dead (free) list */
     DEAD: 1,
-    /** number of particles requested to spawn this frame */
-    SPAWN: 2,
+    /**
+     * Free slots not yet promised to a spawn this frame. The reset pass seeds it from
+     * {@link DEAD}; the emitter tick pass takes from it as it decides each emitter's spawn count,
+     * so an emitter is only ever debited for particles the pool can actually hold. What is left at
+     * the end of the frame is the headroom the frame had.
+     */
+    SPAWN_BUDGET: 2,
     /**
      * Length of the depth-sorted index list — the RENDER order (`../sort/`), back-to-front by view
      * depth so premultiplied transparency composites correctly. Belongs to the camera-dependent
@@ -48,15 +50,3 @@ export const PARTICLE_COUNTER = Object.freeze({
 
 /** Number of `u32` atomic slots in the counters buffer. */
 export const PARTICLE_COUNTER_COUNT = 8;
-
-/**
- * Per-dispatch uniform for the simulate/emit passes.
- * @type {WebGPUStruct}
- */
-export const PARTICLE_SIM_UNIFORM_STRUCT = WebGPUStruct.from({
-    dt: f32,
-    time: f32,
-    frame: u32,
-    /** number of items in the input list (alive-in for simulate, spawn requests for emit) */
-    count: u32,
-}, "ParticleSimUniform");

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

@@ -0,0 +1,56 @@
+/**
+ * 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: number;
+/**
+ * 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: number;
+/** 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;
+/**
+ * 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: GPUTypedTableDescriptor;
+/**
+ * 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: GPUTypedTableDescriptor;
+import { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.js";
+//# sourceMappingURL=PARTICLE_DATABASE_SPEC.d.ts.map

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