@woosh/meep-engine 3.17.1 → 3.18.0

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

@@ -30,6 +30,70 @@ export const PARTICLE_RECORD_HEADER_EMITTER: number;
  * @type {number}
  */
 export const PARTICLE_EMITTER_TICK_WORKGROUP_SIZE: number;
+/**
+ * Most ticks a warm-up runs an emitter's simulation forward in, whatever it owes — see `warmup/`.
+ *
+ * A warm-up is the ordinary loop (spawn, init, advance) run over a transient population until the
+ * emitter has been running for its `prewarm`. Each tick is a handful of dispatches, so this bounds
+ * the frame that pays for it; the tick length stretches to cover the debt rather than the count
+ * growing to cover it ({@link ./warmup/warmup_schedule.js}). Thirty-two ticks of a three-second
+ * warm-up are ninety-millisecond steps — coarse, and smeared by the jitter below so it does not
+ * read as thirty-two bands; a stiff program will not reproduce under it and nothing here claims to.
+ *
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_MAX_TICKS: number;
+/**
+ * Shortest a warm-up tick gets, in seconds — a frame at sixty. A warm-up shorter than
+ * {@link PARTICLE_WARMUP_MAX_TICKS} of these runs fewer ticks rather than finer ones: there is nothing
+ * to be gained from integrating a two-hundred-millisecond warm-up at a finer grain than the frame
+ * loop will from then on.
+ *
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_TICK_SECONDS: number;
+/**
+ * How far a warm-up tick's length is jittered per particle, as a fraction of the tick: each
+ * particle advances by `dt * (1 + this * (u - 0.5))` for a `u` hashed from its slot and the tick.
+ *
+ * Without it every particle born in one tick has exactly the age of that tick at the end, and a
+ * warm-up of N ticks arrives as N cohorts — visible banding on exactly the effects that wanted
+ * warming. A program does not care what `DELTA_TIME` it is handed, so the smear is free. Half a
+ * tick each way is enough to close the gaps between cohorts and not enough to reorder them.
+ *
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_DT_JITTER: number;
+/**
+ * Per-emitter counterpart of {@link PARTICLE_WARMUP_DT_JITTER}: an emitter's own clock runs at
+ * `1 + this * (u - 0.5)` times the tick, for a `u` the host hashes from its row. Two emitters warmed
+ * in the same batch then do not spawn on the same beat, which is what aligns their bands with each
+ * other even after the per-particle smear has hidden each one's own.
+ *
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_EMITTER_JITTER: number;
+/**
+ * Words per entry of the warm-up queue the host hands the GPU: see
+ * {@link ./warmup/shader_particle_warmup.js WARMUP_QUEUE_ENTRY}.
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_QUEUE_WORDS: number;
+/**
+ * Lanes the warm-up's per-particle passes launch. A bounded launch with a grid-stride loop, so the
+ * loop's passes are sized by a constant rather than by a count that changes every tick and would
+ * otherwise need an indirect-args pass of its own per tick. Equal to
+ * {@link PARTICLE_VM_WIDE_LAUNCH_LANES} so that the wide register file, sized by that, fits the
+ * warm-up's wide advance pass without a second file.
+ *
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_LAUNCH_LANES: number;
+/**
+ * Threads per workgroup in the warm-up passes.
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_WORKGROUP_SIZE: number;
 /**
  * Words per entry of the spawn-command list the host hands the GPU: `[emitter row, count]`.
  * @type {number}

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;GAMG;AACH,yCAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,yCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAFU,MAAM,CAEkC;AAElD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAFU,MAAM,CAEkC;;AASlD;;;;;;;;;;;;;;;GAeG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,+CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;;;GAYG;AACH,oCAFU,MAAM,CAEgC;AAEhD;;;;;;;;;;GAUG;AACH,uCAFU,MAAM,CAE4B"}
+{"version":3,"file":"ParticleConstants.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/ParticleConstants.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;GAIG;AACH,6CAFU,MAAM,CAEgC;AAEhD;;;;;;GAMG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;;;;;;;;;GAWG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;;;GAOG;AACH,2CAFU,MAAM,CAEmC;AAEnD;;;;;;;;;;GAUG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;GAOG;AACH,6CAFU,MAAM,CAEkC;AAElD;;;;GAIG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,2CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AAEjD;;;GAGG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;GASG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;GAGG;AACH,8CAFU,MAAM,CAEiC;AAEjD;;;;;;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

@@ -34,6 +34,77 @@ export const PARTICLE_RECORD_HEADER_EMITTER = 0;
  */
 export const PARTICLE_EMITTER_TICK_WORKGROUP_SIZE = 64;
 
+/**
+ * Most ticks a warm-up runs an emitter's simulation forward in, whatever it owes — see `warmup/`.
+ *
+ * A warm-up is the ordinary loop (spawn, init, advance) run over a transient population until the
+ * emitter has been running for its `prewarm`. Each tick is a handful of dispatches, so this bounds
+ * the frame that pays for it; the tick length stretches to cover the debt rather than the count
+ * growing to cover it ({@link ./warmup/warmup_schedule.js}). Thirty-two ticks of a three-second
+ * warm-up are ninety-millisecond steps — coarse, and smeared by the jitter below so it does not
+ * read as thirty-two bands; a stiff program will not reproduce under it and nothing here claims to.
+ *
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_MAX_TICKS = 32;
+
+/**
+ * Shortest a warm-up tick gets, in seconds — a frame at sixty. A warm-up shorter than
+ * {@link PARTICLE_WARMUP_MAX_TICKS} of these runs fewer ticks rather than finer ones: there is nothing
+ * to be gained from integrating a two-hundred-millisecond warm-up at a finer grain than the frame
+ * loop will from then on.
+ *
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_TICK_SECONDS = 1 / 60;
+
+/**
+ * How far a warm-up tick's length is jittered per particle, as a fraction of the tick: each
+ * particle advances by `dt * (1 + this * (u - 0.5))` for a `u` hashed from its slot and the tick.
+ *
+ * Without it every particle born in one tick has exactly the age of that tick at the end, and a
+ * warm-up of N ticks arrives as N cohorts — visible banding on exactly the effects that wanted
+ * warming. A program does not care what `DELTA_TIME` it is handed, so the smear is free. Half a
+ * tick each way is enough to close the gaps between cohorts and not enough to reorder them.
+ *
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_DT_JITTER = 0.5;
+
+/**
+ * Per-emitter counterpart of {@link PARTICLE_WARMUP_DT_JITTER}: an emitter's own clock runs at
+ * `1 + this * (u - 0.5)` times the tick, for a `u` the host hashes from its row. Two emitters warmed
+ * in the same batch then do not spawn on the same beat, which is what aligns their bands with each
+ * other even after the per-particle smear has hidden each one's own.
+ *
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_EMITTER_JITTER = 0.1;
+
+/**
+ * Words per entry of the warm-up queue the host hands the GPU: see
+ * {@link ./warmup/shader_particle_warmup.js WARMUP_QUEUE_ENTRY}.
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_QUEUE_WORDS = 4;
+
+/**
+ * Lanes the warm-up's per-particle passes launch. A bounded launch with a grid-stride loop, so the
+ * loop's passes are sized by a constant rather than by a count that changes every tick and would
+ * otherwise need an indirect-args pass of its own per tick. Equal to
+ * {@link PARTICLE_VM_WIDE_LAUNCH_LANES} so that the wide register file, sized by that, fits the
+ * warm-up's wide advance pass without a second file.
+ *
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_LAUNCH_LANES = 8192;
+
+/**
+ * Threads per workgroup in the warm-up passes.
+ * @type {number}
+ */
+export const PARTICLE_WARMUP_WORKGROUP_SIZE = 64;
+
 /**
  * Words per entry of the spawn-command list the host hands the GPU: `[emitter row, count]`.
  * @type {number}

package/src/shade/renderer/particles/bounds/chunk_particle_bounds.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The per-emitter bounds accumulator: where a measured box is built up, and how it is read back.
+ *
+ * An emitter has no bounds it could declare. Its particles are simulated in world space by arbitrary
+ * bytecode — they go where the program sends them, at whatever size it gives them, for as long as it
+ * keeps them alive — so the only bound an author could write down and still be right is an infinite
+ * one, which culls nothing and reserves every depth slice. What CAN be known is where the particles
+ * actually are, and that is what the two passes in {@link ./shader_particle_bounds.js} measure.
+ *
+ * One accumulator per emitter table row, six words of the counters buffer (see
+ * {@link ../data/PARTICLE_COUNTERS.js} for why it lives there rather than in a binding of its own),
+ * holding `min.xyz` then `max.xyz` as plain f32 bit patterns.
+ *
+ * ## Why f32 in the buffer, and not an order-preserving encoding
+ *
+ * `aabb_atomic_min_f32` / `aabb_atomic_max_f32` are the engine's, shared with the skinned-mesh
+ * bounds refresh, and they CAS-spin over the plain float so the words are readable as floats at
+ * every moment of the frame. The sign-flip encoding that would let `atomicMin` do it in one
+ * instruction leaves the buffer in a form only a decoder understands, and the publish pass reads
+ * these words in the same frame the accumulate pass writes them.
+ *
+ * The spin is cheaper than it looks at particle counts: both helpers load first and return without a
+ * CAS when the box already holds the contribution. It is the record-breaking argument — over `n`
+ * particles in arbitrary order, the number that actually extend an axis is `O(log n)` in
+ * expectation, so `n` threads produce `n` loads and a handful of exchanges per word rather than `n`
+ * of each. What is left is the load traffic, and a subgroup reduction ahead of the atomic is the
+ * lever if it ever matters; the pass is separate partly so there is somewhere to pull it.
+ *
+ * ## What this chunk needs from its shader
+ *
+ * The `counters` binding, by that name and read-write, the way
+ * {@link ../shaders/chunk_particle_billboard_vertex.js} takes `pool` and `camera`. Both bounds
+ * passes bind it — that is the point of the accumulator living there.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_bounds_store: CodeChunk;
+/**
+ * One live particle's contribution to its emitter's box: where its quad is, and how far the quad
+ * reaches from there.
+ *
+ * Read in exactly the terms {@link ../shaders/chunk_particle_billboard_vertex.js} reads a particle
+ * in — same record offsets, same defaults for an unbound channel, same radius as the corner
+ * expansion it performs — because the box has to hold what is drawn, not what is simulated. An
+ * emitter with no `position` binding really does draw every particle at the world origin, and this
+ * really does book the origin for it; the box stays a true statement about where the quads are, and
+ * an author who sees their effect culled at the origin has been told something accurate about their
+ * bindings.
+ *
+ * Five words of a record, no VM and no scene: that is the whole reason the measurement is a pass of
+ * its own rather than a tail on `particle_simulate_one`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_bounds_of_record: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_bounds.d.ts.map

package/src/shade/renderer/particles/bounds/chunk_particle_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/bounds/chunk_particle_bounds.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,0CAFU,SAAS,CAwEyC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,SAAS,CA4CsC;0BApL/B,oCAAoC"}

package/src/shade/renderer/particles/bounds/chunk_particle_bounds.js

@@ -0,0 +1,181 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_aabb_atomic_f32 } from "../../animation/skinning/bounds_refresh/chunk_aabb_atomic_f32.js";
+import { AABB3_STRUCT } from "../../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
+import {
+    PARTICLE_BOUNDS_BASE,
+    PARTICLE_BOUNDS_MINUS_INF,
+    PARTICLE_BOUNDS_PLUS_INF,
+    PARTICLE_BOUNDS_WORDS,
+} from "../data/PARTICLE_COUNTERS.js";
+import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_STRUCT.js";
+import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
+import { chunk_particle_render_math } from "../shaders/chunk_particle_render_math.js";
+
+/**
+ * The per-emitter bounds accumulator: where a measured box is built up, and how it is read back.
+ *
+ * An emitter has no bounds it could declare. Its particles are simulated in world space by arbitrary
+ * bytecode — they go where the program sends them, at whatever size it gives them, for as long as it
+ * keeps them alive — so the only bound an author could write down and still be right is an infinite
+ * one, which culls nothing and reserves every depth slice. What CAN be known is where the particles
+ * actually are, and that is what the two passes in {@link ./shader_particle_bounds.js} measure.
+ *
+ * One accumulator per emitter table row, six words of the counters buffer (see
+ * {@link ../data/PARTICLE_COUNTERS.js} for why it lives there rather than in a binding of its own),
+ * holding `min.xyz` then `max.xyz` as plain f32 bit patterns.
+ *
+ * ## Why f32 in the buffer, and not an order-preserving encoding
+ *
+ * `aabb_atomic_min_f32` / `aabb_atomic_max_f32` are the engine's, shared with the skinned-mesh
+ * bounds refresh, and they CAS-spin over the plain float so the words are readable as floats at
+ * every moment of the frame. The sign-flip encoding that would let `atomicMin` do it in one
+ * instruction leaves the buffer in a form only a decoder understands, and the publish pass reads
+ * these words in the same frame the accumulate pass writes them.
+ *
+ * The spin is cheaper than it looks at particle counts: both helpers load first and return without a
+ * CAS when the box already holds the contribution. It is the record-breaking argument — over `n`
+ * particles in arbitrary order, the number that actually extend an axis is `O(log n)` in
+ * expectation, so `n` threads produce `n` loads and a handful of exchanges per word rather than `n`
+ * of each. What is left is the load traffic, and a subgroup reduction ahead of the atomic is the
+ * lever if it ever matters; the pass is separate partly so there is somewhere to pull it.
+ *
+ * ## What this chunk needs from its shader
+ *
+ * The `counters` binding, by that name and read-write, the way
+ * {@link ../shaders/chunk_particle_billboard_vertex.js} takes `pool` and `camera`. Both bounds
+ * passes bind it — that is the point of the accumulator living there.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_bounds_store = CodeChunk.from(/* language=wgsl */ `
+const PARTICLE_BOUNDS_BASE : u32 = ${PARTICLE_BOUNDS_BASE}u;
+const PARTICLE_BOUNDS_WORDS : u32 = ${PARTICLE_BOUNDS_WORDS}u;
+
+// The empty interval, as bit patterns because WGSL has no literal for either infinity. The same two
+// words the host writes over a newly grown region, from the same constants.
+const PARTICLE_BOUNDS_PLUS_INF : u32 = ${PARTICLE_BOUNDS_PLUS_INF}u;
+const PARTICLE_BOUNDS_MINUS_INF : u32 = ${PARTICLE_BOUNDS_MINUS_INF}u;
+
+fn particle_bounds_base(row : u32) -> u32 {
+    return PARTICLE_BOUNDS_BASE + row * PARTICLE_BOUNDS_WORDS;
+}
+
+// Book one particle's quad into its emitter's accumulator: the sphere of radius \`radius\` about
+// \`center\`, as an axis-aligned box.
+//
+// A sphere rather than the quad itself because the quad's plane is the camera's, and this box is
+// read on a later frame with the camera somewhere else. See \`particle_billboard_radius\`.
+fn particle_bounds_contribute(row : u32, center : vec3<f32>, radius : f32) {
+    let base = particle_bounds_base(row);
+
+    let lo = center - vec3<f32>(radius);
+    let hi = center + vec3<f32>(radius);
+
+    aabb_atomic_min_f32(&counters[base + 0u], lo.x);
+    aabb_atomic_min_f32(&counters[base + 1u], lo.y);
+    aabb_atomic_min_f32(&counters[base + 2u], lo.z);
+    aabb_atomic_max_f32(&counters[base + 3u], hi.x);
+    aabb_atomic_max_f32(&counters[base + 4u], hi.y);
+    aabb_atomic_max_f32(&counters[base + 5u], hi.z);
+}
+
+// What the frame accumulated for one row. Empty (see \`particle_bounds_is_empty\`) when nothing
+// contributed — the emitter had no live particles.
+fn particle_bounds_read(row : u32) -> ${AABB3_STRUCT.wgsl_ref} {
+    let base = particle_bounds_base(row);
+
+    let lo = vec3<f32>(
+        bitcast<f32>(atomicLoad(&counters[base + 0u])),
+        bitcast<f32>(atomicLoad(&counters[base + 1u])),
+        bitcast<f32>(atomicLoad(&counters[base + 2u])),
+    );
+    let hi = vec3<f32>(
+        bitcast<f32>(atomicLoad(&counters[base + 3u])),
+        bitcast<f32>(atomicLoad(&counters[base + 4u])),
+        bitcast<f32>(atomicLoad(&counters[base + 5u])),
+    );
+
+    return ${AABB3_STRUCT.make({ min: "lo", max: "hi" })};
+}
+
+// Start a row's next frame of measurement. All six axes are set together and no contribution ever
+// touches one without the others, so "min above max on any axis" is exactly "nothing contributed".
+//
+// Unconditional in the publish pass, which is what lets a row that changes hands start clean: the
+// last publish before it was freed left it empty, and it stays that way until somebody measures.
+fn particle_bounds_reset(row : u32) {
+    let base = particle_bounds_base(row);
+
+    atomicStore(&counters[base + 0u], PARTICLE_BOUNDS_PLUS_INF);
+    atomicStore(&counters[base + 1u], PARTICLE_BOUNDS_PLUS_INF);
+    atomicStore(&counters[base + 2u], PARTICLE_BOUNDS_PLUS_INF);
+    atomicStore(&counters[base + 3u], PARTICLE_BOUNDS_MINUS_INF);
+    atomicStore(&counters[base + 4u], PARTICLE_BOUNDS_MINUS_INF);
+    atomicStore(&counters[base + 5u], PARTICLE_BOUNDS_MINUS_INF);
+}
+
+fn particle_bounds_is_empty(box : ${AABB3_STRUCT.wgsl_ref}) -> bool {
+    return any(box.min > box.max);
+}
+`, [chunk_aabb_atomic_f32, AABB3_STRUCT.declaration_chunk]);
+
+/**
+ * One live particle's contribution to its emitter's box: where its quad is, and how far the quad
+ * reaches from there.
+ *
+ * Read in exactly the terms {@link ../shaders/chunk_particle_billboard_vertex.js} reads a particle
+ * in — same record offsets, same defaults for an unbound channel, same radius as the corner
+ * expansion it performs — because the box has to hold what is drawn, not what is simulated. An
+ * emitter with no `position` binding really does draw every particle at the world origin, and this
+ * really does book the origin for it; the box stays a true statement about where the quads are, and
+ * an author who sees their effect culled at the origin has been told something accurate about their
+ * bindings.
+ *
+ * Five words of a record, no VM and no scene: that is the whole reason the measurement is a pass of
+ * its own rather than a tail on `particle_simulate_one`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_bounds_of_record = CodeChunk.from(/* language=wgsl */ `
+const PARTICLE_BOUNDS_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
+
+struct ParticleBoundsSample {
+    center : vec3<f32>,
+    radius : f32,
+}
+
+fn particle_bounds_read_vec3(pool : ptr<storage, array<u32>>, base : u32, offset : u32) -> vec3<f32> {
+    return vec3<f32>(
+        bitcast<f32>((*pool)[base + offset]),
+        bitcast<f32>((*pool)[base + offset + 1u]),
+        bitcast<f32>((*pool)[base + offset + 2u]),
+    );
+}
+
+fn particle_bounds_of_record(
+    em : ParticleEmitter,
+    pool : ptr<storage, array<u32>>,
+    record_base : u32,
+) -> ParticleBoundsSample {
+    var center = vec3<f32>(0.0);
+    if (em.render_position != PARTICLE_BOUNDS_ATTRIBUTE_ABSENT) {
+        center = particle_bounds_read_vec3(pool, record_base, em.render_position);
+    }
+
+    var size = 1.0;
+    if (em.render_size != PARTICLE_BOUNDS_ATTRIBUTE_ABSENT) {
+        size = bitcast<f32>((*pool)[record_base + em.render_size]);
+    }
+
+    var velocity = vec3<f32>(0.0);
+    if (em.render_velocity != PARTICLE_BOUNDS_ATTRIBUTE_ABSENT) {
+        velocity = particle_bounds_read_vec3(pool, record_base, em.render_velocity);
+    }
+
+    var sample : ParticleBoundsSample;
+    sample.center = center;
+    sample.radius = particle_billboard_radius(size, velocity, particle_emitter_projection(em.flags));
+
+    return sample;
+}
+`, [chunk_particle_emitter, chunk_particle_render_math]);

package/src/shade/renderer/particles/bounds/chunk_particle_bounds_unknown.d.ts

@@ -0,0 +1,7 @@
+/** Infinite bounds mean no live particles have supplied a measurement. Test before any geometry
+ * arithmetic: multiplying infinity by a zero plane component or adding opposite infinities is NaN.
+ * @type {CodeChunk}
+ */
+export const chunk_particle_bounds_unknown: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_bounds_unknown.d.ts.map

package/src/shade/renderer/particles/bounds/chunk_particle_bounds_unknown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_bounds_unknown.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/bounds/chunk_particle_bounds_unknown.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,4CAFU,SAAS,CAOhB;0BAXuB,oCAAoC"}

package/src/shade/renderer/particles/bounds/chunk_particle_bounds_unknown.js

@@ -0,0 +1,12 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/** Infinite bounds mean no live particles have supplied a measurement. Test before any geometry
+ * arithmetic: multiplying infinity by a zero plane component or adding opposite infinities is NaN.
+ * @type {CodeChunk}
+ */
+export const chunk_particle_bounds_unknown = CodeChunk.from(/* wgsl */ `
+fn particle_bounds_unknown(bounds_min : vec3<f32>) -> bool {
+    // Compare stored bits: a constant bitcast to an infinite f32 is a WGSL creation error.
+    return bitcast<u32>(bounds_min.x) == 0xff800000u;
+}
+`);

package/src/shade/renderer/particles/bounds/graph_particle_bounds.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Frame-graph wiring for the measured emitter bounds: the frame's alive list reduced to one
+ * world-space box per emitter, published where the culling and occupancy passes read it.
+ *
+ * Runs at the end of the frame, after emit and simulate have both finished appending to the alive
+ * list and after the coherence reset has written `dispatch_args` from the resulting count. Two
+ * passes, in this order and no other: the accumulate has to see every live particle before the
+ * publish takes what it measured.
+ *
+ * @param {object} params
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.emitter_database graph handle; the publish pass writes the state rows
+ * @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, which carry the accumulator
+ * @param {number} params.dispatch_args graph handle of one workgroup per live particle
+ * @param {number} params.emitter_group_count workgroups that walk every page group of the emitter
+ *   table; zero when the table has no pages, and then there is nothing to publish
+ * @returns {{counters: number, emitter_database: number}} the threaded handles downstream passes must read
+ */
+export function graph_particle_bounds({ graph, emitter_database, pool, alive, counters, dispatch_args, emitter_group_count, }: {
+    graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    emitter_database: number;
+    pool: number;
+    alive: number;
+    counters: number;
+    dispatch_args: number;
+    emitter_group_count: number;
+}): {
+    counters: number;
+    emitter_database: number;
+};
+//# sourceMappingURL=graph_particle_bounds.d.ts.map

package/src/shade/renderer/particles/bounds/graph_particle_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_particle_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/bounds/graph_particle_bounds.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAVqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,gBAAgB,EAA/B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,aAAa,EAA5B,MAAM;IACS,mBAAmB,EAAlC,MAAM;IAEJ;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAC,CAwCxD"}

package/src/shade/renderer/particles/bounds/graph_particle_bounds.js

@@ -0,0 +1,67 @@
+import { assert } from "../../../../core/assert.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 {
+    shader_particle_bounds_accumulate,
+    shader_particle_bounds_publish,
+} from "./shader_particle_bounds.js";
+
+/**
+ * Frame-graph wiring for the measured emitter bounds: the frame's alive list reduced to one
+ * world-space box per emitter, published where the culling and occupancy passes read it.
+ *
+ * Runs at the end of the frame, after emit and simulate have both finished appending to the alive
+ * list and after the coherence reset has written `dispatch_args` from the resulting count. Two
+ * passes, in this order and no other: the accumulate has to see every live particle before the
+ * publish takes what it measured.
+ *
+ * @param {object} params
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.emitter_database graph handle; the publish pass writes the state rows
+ * @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, which carry the accumulator
+ * @param {number} params.dispatch_args graph handle of one workgroup per live particle
+ * @param {number} params.emitter_group_count workgroups that walk every page group of the emitter
+ *   table; zero when the table has no pages, and then there is nothing to publish
+ * @returns {{counters: number, emitter_database: number}} the threaded handles downstream passes must read
+ */
+export function graph_particle_bounds({
+                                          graph,
+                                          emitter_database,
+                                          pool,
+                                          alive,
+                                          counters,
+                                          dispatch_args,
+                                          emitter_group_count,
+                                      }) {
+    assert.defined(graph, "graph");
+    assert.isNonNegativeInteger(emitter_group_count, "emitter_group_count");
+
+    if (emitter_group_count === 0) {
+        // No emitter table pages: no rows to accumulate into and none to publish. The alive list is
+        // empty for the same reason, so the accumulate pass would be a no-op even if it ran.
+        return { counters, emitter_database };
+    }
+
+    // One thread per live particle. Indirect, from the count the coherence reset read on the GPU —
+    // a host-side particle count is a frame stale at best.
+    const accumulated = graph_compute_indirect_pass({
+        graph,
+        shader: shader_particle_bounds_accumulate,
+        bindings: { emitter_database, pool, alive, counters },
+        command: dispatch_args,
+    });
+
+    const published = graph_compute_pass({
+        graph,
+        shader: shader_particle_bounds_publish,
+        bindings: { emitter_database, counters: accumulated.counters },
+        group_count: [emitter_group_count, 1, 1],
+    });
+
+    return {
+        counters: published.counters,
+        emitter_database: published.emitter_database,
+    };
+}

package/src/shade/renderer/particles/bounds/shader_particle_bounds.d.ts

@@ -0,0 +1,40 @@
+/**
+ * One thread per live particle: merge its quad into its emitter's accumulator.
+ *
+ * The alive list holds real slots only — the padding sentinel belongs to the simulation-order list,
+ * and an orphan was killed by the simulate pass that built this list — so every entry is a particle
+ * whose emitter row is live and whose record has this frame's values in it.
+ *
+ * It decodes a whole emitter record to reach four of its fields, which the bucketing histogram
+ * deliberately does not (`chunk_particle_emitter_program_id`). The difference is what is being paid
+ * for: emitters are counted in tens, so the records are a working set that stays resident for the
+ * whole dispatch, while the pool reads are a gather over the free list and are what this pass costs.
+ * The billboard vertex stage reads a record the same way, per vertex.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bounds_accumulate: ComputeShader;
+/**
+ * One thread per emitter table row: publish what the accumulate pass measured into
+ * `bounds_min` / `bounds_max` of the emitter's state row, and reset the accumulator.
+ *
+ * The state row rather than the accumulator directly, because the readers — the tick's frustum test
+ * next frame, the AVBOIT occupancy later in this one — should not each have to know the
+ * accumulator's layout or repeat the empty case below. It is also where the rest of an emitter's
+ * GPU-owned state lives, for the reason {@link ../data/PARTICLE_EMITTER_STATE.js} gives.
+ *
+ * ## The empty case
+ *
+ * No measured particles means unknown bounds, represented by an infinite box. The tick lets such
+ * an emitter spawn until a finite population can be measured; occupancy skips it because there is
+ * nothing to splat. This also lets an exhausted effect restart without requiring authored bounds
+ * or prewarm. Readers recognize the sentinel before doing geometry arithmetic on infinities.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_particle_bounds_publish: ComputeShader;
+import { PARTICLE_SIMULATE_WORKGROUP_SIZE } from "../ParticleConstants.js";
+import { PARTICLE_EMITTER_TICK_WORKGROUP_SIZE } from "../ParticleConstants.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+export { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_EMITTER_TICK_WORKGROUP_SIZE };
+//# sourceMappingURL=shader_particle_bounds.d.ts.map

package/src/shade/renderer/particles/bounds/shader_particle_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/bounds/shader_particle_bounds.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;GAcG;AACH,gDAFU,aAAa,CAgCpB;AAkBH;;;;;;;;;;;;;;;;;GAiBG;AACH,6CAFU,aAAa,CA6CpB;iDA/KI,yBAAyB;qDAAzB,yBAAyB;8BARF,+BAA+B"}