@woosh/meep-engine 3.17.2 → 3.18.0

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

@@ -0,0 +1,187 @@
+import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { AABB3_STRUCT } from "../../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import {
+    PARTICLE_EMITTER_TICK_WORKGROUP_SIZE,
+    PARTICLE_RECORD_HEADER_EMITTER,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_SIMULATE_WORKGROUP_SIZE,
+} from "../ParticleConstants.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+import { PARTICLE_EMITTER_DESCRIPTOR, PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+import { chunk_particle_header } from "../data/particle_header.js";
+import { chunk_particle_bounds_of_record, chunk_particle_bounds_store } from "./chunk_particle_bounds.js";
+
+/**
+ * The two passes that measure every emitter's bounding box, at the end of the frame that produced
+ * the particles.
+ *
+ * - {@link shader_particle_bounds_accumulate} — one thread per live particle: read where its quad
+ *   is and merge it into its emitter's accumulator.
+ * - {@link shader_particle_bounds_publish} — one thread per emitter row: hand the accumulation to
+ *   the state row the culling and occupancy passes read, and start the next frame's measurement.
+ *
+ * ## Why this is not a tail on the simulate pass
+ *
+ * It was, briefly. Two things are wrong with booking the box from inside emit and simulate. The
+ * measurement is not of one population: simulate sees last frame's survivors and emit sees this
+ * frame's newborns, so the union spans two frames and is looser than either. And the merge is six
+ * atomics in the pass whose register pressure decides the whole system's occupancy — the interpreter
+ * — paid to compute something that needs none of the VM, none of the scene, and five words of the
+ * record.
+ *
+ * Run over the alive list instead and the measurement is of exactly the set that is alive and about
+ * to be drawn, taken by a pass that reads a header, an emitter row and three attributes.
+ *
+ * ## Sizing
+ *
+ * The accumulate pass is dispatched indirectly from `sim_dispatch_args`, which the coherence reset
+ * wrote from the GPU's own alive count — the same args the render sort's two per-particle passes
+ * take, and the reason its workgroup size must stay {@link PARTICLE_SIMULATE_WORKGROUP_SIZE}, which
+ * is what those args were divided by. Its element bound is `counters[ALIVE]`, read in the shader.
+ * Nothing here is sized from the host.
+ *
+ * The publish pass walks the emitter table with the table's page iterator, one page group per
+ * workgroup, like the tick.
+ */
+
+export { PARTICLE_SIMULATE_WORKGROUP_SIZE, PARTICLE_EMITTER_TICK_WORKGROUP_SIZE };
+
+// --- accumulate -------------------------------------------------------------------------------
+
+const accumulate_resources = new ShaderResourceSetDescriptor();
+
+accumulate_resources.createGroup()
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
+    .addStorageBuffer("pool", WebGPUArray.u32, false)
+    .addStorageBuffer("alive", WebGPUArray.u32, false)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * 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.from({
+    label: "Particle Bounds Accumulate",
+    resources: accumulate_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
+
+@compute @workgroup_size(${PARTICLE_SIMULATE_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+
+    // This frame's alive count, as emit and simulate left it. The indirect dispatch was built from
+    // the same number, so the excess is at most a workgroup's tail.
+    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
+
+    let slot = alive[i];
+    let record_base = slot * PARTICLE_RECORD_WORDS;
+    let emitter_row = particle_header_emitter(pool[record_base + PARTICLE_HEADER_EMITTER]);
+
+    let em = particle_emitter_read(&emitter_database, emitter_row);
+    let sample = particle_bounds_of_record(em, &pool, record_base);
+
+    particle_bounds_contribute(emitter_row, sample.center, sample.radius);
+}
+`, [
+        chunk_particle_bounds_of_record,
+        chunk_particle_bounds_store,
+        chunk_particle_header,
+    ]),
+});
+
+// --- publish ----------------------------------------------------------------------------------
+
+const PG = PARTICLE_EMITTER_DESCRIPTOR.page_iterator_symbol_prefix(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE, true);
+const STATE = PARTICLE_EMITTER_STATE_DESCRIPTOR;
+
+// Generated once and held, because each call builds a fresh chunk declaring the same function: two
+// calls for one field would be two declarations of it in the assembled shader.
+const WRITE_BOUNDS_MIN = STATE.wgsl_gen_write_field_code("bounds_min");
+const WRITE_BOUNDS_MAX = STATE.wgsl_gen_write_field_code("bounds_max");
+
+const publish_resources = new ShaderResourceSetDescriptor();
+
+publish_resources.createGroup()
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, true)
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * 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.from({
+    label: "Particle Bounds Publish",
+    resources: publish_resources,
+    body: CodeChunk.from(/* language=wgsl */ `
+@compute @workgroup_size(${PARTICLE_EMITTER_TICK_WORKGROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg_id : vec3<u32>,
+    @builtin(local_invocation_index) local_id : u32,
+) {
+    // page_address is uniform across the workgroup, so this branch is uniform.
+    if (!${PG}_setup(&emitter_database, wg_id.x, local_id)) {
+        return;
+    }
+
+    let slot_in_page = ${PG}_slot_in_page(local_id);
+
+    if (slot_in_page >= ${PG}_ELEMENTS_PER_PAGE || !${PG}_is_occupied(slot_in_page)) {
+        return;
+    }
+
+    let row = ${PG}_slot_to_index(slot_in_page);
+
+    var box = particle_bounds_read(row);
+
+    if (particle_bounds_is_empty(box)) {
+        // The empty accumulator already holds [+inf, -inf]. Swap the loaded endpoints to
+        // publish unknown bounds without constructing forbidden infinite constant expressions.
+        box = ${AABB3_STRUCT.make({ min: "box.max", max: "box.min" })};
+    }
+
+    particle_bounds_reset(row);
+
+    // Two field writes rather than a whole-row read-modify-write: the tick wrote this row earlier in
+    // the frame, and there is no reason for this pass to carry the rest of it through registers.
+    ${STATE.marshalling_method_write_field("bounds_min")}(&emitter_database, row, box.min);
+    ${STATE.marshalling_method_write_field("bounds_max")}(&emitter_database, row, box.max);
+}
+`, [
+        PARTICLE_EMITTER_DESCRIPTOR.chunk_iterate(PARTICLE_EMITTER_TICK_WORKGROUP_SIZE, true),
+        WRITE_BOUNDS_MIN,
+        WRITE_BOUNDS_MAX,
+        chunk_particle_bounds_store,
+    ]),
+});

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

@@ -1,3 +1,6 @@
+/**
+ * @typedef {{keys: number, histogram: number, cursor: number, bucket_counts: number, dispatch_args: number}} ParticleBucketScratch
+ */
 /**
  * Frame-graph wiring for the simulation-order bucketing: turns the frame's freshly compacted alive
  * list into the program-coherent, workgroup-padded list NEXT frame's simulate consumes.
@@ -36,9 +39,10 @@
  *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
  *   and the write end up on separate dependency chains
  * @param {number} params.bucket_count number of distinct compiled programs
- * @returns {{counters: number, sim_list: number, dispatch_args: number}} the threaded handles downstream passes must read
+ * @param {ParticleBucketScratch} [params.scratch] latest handles when bucketing again in this graph
+ * @returns {{counters: number, sim_list: number, dispatch_args: number, scratch: ParticleBucketScratch}} the threaded handles downstream passes must read
  */
-export function graph_particle_bucket({ graph, gpu, emitter_database, pool, alive, counters, sim_list, bucket_count }: {
+export function graph_particle_bucket({ graph, gpu, emitter_database, pool, alive, counters, sim_list, bucket_count, scratch }: {
     graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
     gpu: {
         sim_list: GPUBuffer;
@@ -54,9 +58,18 @@ export function graph_particle_bucket({ graph, gpu, emitter_database, pool, aliv
     counters: number;
     sim_list: number;
     bucket_count: number;
+    scratch?: ParticleBucketScratch;
 }): {
     counters: number;
     sim_list: number;
     dispatch_args: number;
+    scratch: ParticleBucketScratch;
+};
+export type ParticleBucketScratch = {
+    keys: number;
+    histogram: number;
+    cursor: number;
+    bucket_counts: number;
+    dispatch_args: number;
 };
 //# sourceMappingURL=graph_particle_bucket.d.ts.map

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

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

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

@@ -16,6 +16,10 @@ import {
     shader_particle_bucket_scatter,
 } from "./shader_particle_bucket.js";
 
+/**
+ * @typedef {{keys: number, histogram: number, cursor: number, bucket_counts: number, dispatch_args: number}} ParticleBucketScratch
+ */
+
 /**
  * Frame-graph wiring for the simulation-order bucketing: turns the frame's freshly compacted alive
  * list into the program-coherent, workgroup-padded list NEXT frame's simulate consumes.
@@ -54,9 +58,10 @@ import {
  *   GPUBuffer twice makes two resource entries the graph cannot see are the same memory, so the read
  *   and the write end up on separate dependency chains
  * @param {number} params.bucket_count number of distinct compiled programs
- * @returns {{counters: number, sim_list: number, dispatch_args: number}} the threaded handles downstream passes must read
+ * @param {ParticleBucketScratch} [params.scratch] latest handles when bucketing again in this graph
+ * @returns {{counters: number, sim_list: number, dispatch_args: number, scratch: ParticleBucketScratch}} the threaded handles downstream passes must read
  */
-export function graph_particle_bucket({ graph, gpu, emitter_database, pool, alive, counters, sim_list, bucket_count }) {
+export function graph_particle_bucket({ graph, gpu, emitter_database, pool, alive, counters, sim_list, bucket_count, scratch }) {
     assert.defined(graph, "graph");
     assert.isPositiveInteger(bucket_count, "bucket_count");
     assert.isNonNegativeInteger(sim_list, "sim_list");
@@ -74,11 +79,12 @@ export function graph_particle_bucket({ graph, gpu, emitter_database, pool, aliv
     // between the two passes unexpressed — the graph's own validator rejects it, because both
     // versions name one piece of memory and the stale-looking read silently returns the new
     // contents.
-    let keys = graph_import_buffer(graph, gpu.sim_keys, "particles/sim_keys");
-    let histogram = graph_import_buffer(graph, gpu.sim_histogram, "particles/sim_histogram");
-    let cursor = graph_import_buffer(graph, gpu.sim_cursor, "particles/sim_cursor");
-    let bucket_counts = graph_import_buffer(graph, gpu.sim_bucket_counts, "particles/sim_bucket_counts");
-    let dispatch_args = graph_import_buffer(graph, gpu.sim_dispatch_args, "particles/sim_dispatch_args");
+    // An edit frame buckets twice. Reuse the latest handles so both runs share one dependency chain.
+    let keys = scratch?.keys ?? graph_import_buffer(graph, gpu.sim_keys, "particles/sim_keys");
+    let histogram = scratch?.histogram ?? graph_import_buffer(graph, gpu.sim_histogram, "particles/sim_histogram");
+    let cursor = scratch?.cursor ?? graph_import_buffer(graph, gpu.sim_cursor, "particles/sim_cursor");
+    let bucket_counts = scratch?.bucket_counts ?? graph_import_buffer(graph, gpu.sim_bucket_counts, "particles/sim_bucket_counts");
+    let dispatch_args = scratch?.dispatch_args ?? graph_import_buffer(graph, gpu.sim_dispatch_args, "particles/sim_dispatch_args");
 
     // 0. Clear the bins and cursors, write the scan's {count} header, and size the two per-particle
     //    passes below from the GPU's own alive count.
@@ -157,7 +163,7 @@ export function graph_particle_bucket({ graph, gpu, emitter_database, pool, aliv
 
     // `dispatch_args` goes back too: it holds one workgroup per live particle, written from the
     // GPU's own alive count, which is exactly the shape the depth sort's per-particle passes need.
-    return { counters, sim_list, dispatch_args };
+    return { counters, sim_list, dispatch_args, scratch: { keys, histogram: scanned, cursor, bucket_counts, dispatch_args } };
 }
 
 /**

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

@@ -1,7 +1,30 @@
 /**
- * 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
- * indirect dispatch/draw arguments.
+ * How many words the counters buffer needs to hold the counters plus one accumulator per row of an
+ * emitter table of `emitter_capacity` elements.
+ *
+ * @param {number} emitter_capacity element capacity of the emitter table
+ * @returns {number}
+ */
+export function particle_counters_word_count(emitter_capacity: number): number;
+/**
+ * `row_count` accumulators, each holding the empty interval — what the publish pass leaves behind,
+ * and what a row must hold before anything has measured it.
+ *
+ * A zero-filled accumulator is NOT that: it reads back as a valid degenerate box at the world
+ * origin, which would union the origin into the first box measured for the row. WebGPU zero-fills a
+ * new buffer, so the host writes this over a newly grown region rather than relying on the fill.
+ *
+ * @param {number} row_count
+ * @returns {Uint32Array}
+ */
+export function particle_bounds_empty_words(row_count: number): Uint32Array;
+/**
+ * Indices into the head of 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 indirect dispatch/draw arguments.
+ *
+ * The buffer does not end here: {@link PARTICLE_BOUNDS_BASE} onward is the per-emitter bounds
+ * accumulator, described below.
  */
 export const PARTICLE_COUNTER: Readonly<{
     /** length of the alive list produced this frame */
@@ -47,6 +70,37 @@ export const PARTICLE_COUNTER: Readonly<{
      */
     SIM_PADDED: 5;
 }>;
-/** Number of `u32` atomic slots in the counters buffer. */
+/** Number of `u32` atomic slots the counters themselves occupy — the head of the buffer. */
 export const PARTICLE_COUNTER_COUNT: 8;
+/**
+ * First word of the per-emitter bounds accumulator, which occupies the rest of the counters buffer:
+ * {@link PARTICLE_BOUNDS_WORDS} words per emitter table row, indexed by row.
+ *
+ * ## Why it lives here rather than in a buffer of its own
+ *
+ * The accumulator is merged into with atomics — one contribution per live particle — which means a
+ * binding declared `array<atomic<u32>>`. The emitter database cannot be it: the passes that read a
+ * record read it out of an `array<u32>` binding, and one buffer under two access types is aliasing.
+ *
+ * The counters buffer is already exactly that: bound in both bounds passes, already atomic, already
+ * read-write, and already this system's cross-pass GPU-owned scratch. Giving the accumulator a
+ * buffer of its own would add a binding and a growth path to say the same thing. So it is a section
+ * of this one: the counters keep their slots, the reset pass keeps writing the same fixed indices,
+ * and the section is addressed off this base.
+ *
+ * @type {number}
+ */
+export const PARTICLE_BOUNDS_BASE: number;
+/**
+ * Words one emitter's bounds accumulator takes: `min.xyz` then `max.xyz`, each an f32 bit pattern
+ * held in a `u32` slot (see `../bounds/chunk_particle_bounds.js` for why the storage is plain f32
+ * rather than an order-preserving encoding).
+ *
+ * @type {number}
+ */
+export const PARTICLE_BOUNDS_WORDS: number;
+/** `bitcast<u32>(f32(+inf))` — the lower corner of the empty interval. */
+export const PARTICLE_BOUNDS_PLUS_INF: 2139095040;
+/** `bitcast<u32>(f32(-inf))` — the upper corner of the empty interval. */
+export const PARTICLE_BOUNDS_MINUS_INF: 4286578688;
 //# 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":"AAAA;;;;GAIG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;GAEJ;AAEH,2DAA2D;AAC3D,uCAAwC"}
+{"version":3,"file":"PARTICLE_COUNTERS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_COUNTERS.js"],"names":[],"mappings":"AAqFA;;;;;;GAMG;AACH,+DAHW,MAAM,GACJ,MAAM,CAIlB;AAQD;;;;;;;;;;GAUG;AACH,uDAHW,MAAM,GACJ,WAAW,CAevB;AA9HD;;;;;;;GAOG;AACH;IACI,mDAAmD;;IAEnD,qCAAqC;;IAErC;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;GAEJ;AAEH,4FAA4F;AAC5F,uCAAwC;AAExC;;;;;;;;;;;;;;;;;GAiBG;AACH,mCAFU,MAAM,CAE2C;AAE3D;;;;;;GAMG;AACH,oCAFU,MAAM,CAEuB;AAavC,0EAA0E;AAC1E,kDAAmD;AAEnD,0EAA0E;AAC1E,mDAAoD"}

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

@@ -1,7 +1,10 @@
 /**
- * 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
- * indirect dispatch/draw arguments.
+ * Indices into the head of 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 indirect dispatch/draw arguments.
+ *
+ * The buffer does not end here: {@link PARTICLE_BOUNDS_BASE} onward is the per-emitter bounds
+ * accumulator, described below.
  */
 export const PARTICLE_COUNTER = Object.freeze({
     /** length of the alive list produced this frame */
@@ -48,5 +51,77 @@ export const PARTICLE_COUNTER = Object.freeze({
     SIM_PADDED: 5,
 });
 
-/** Number of `u32` atomic slots in the counters buffer. */
+/** Number of `u32` atomic slots the counters themselves occupy — the head of the buffer. */
 export const PARTICLE_COUNTER_COUNT = 8;
+
+/**
+ * First word of the per-emitter bounds accumulator, which occupies the rest of the counters buffer:
+ * {@link PARTICLE_BOUNDS_WORDS} words per emitter table row, indexed by row.
+ *
+ * ## Why it lives here rather than in a buffer of its own
+ *
+ * The accumulator is merged into with atomics — one contribution per live particle — which means a
+ * binding declared `array<atomic<u32>>`. The emitter database cannot be it: the passes that read a
+ * record read it out of an `array<u32>` binding, and one buffer under two access types is aliasing.
+ *
+ * The counters buffer is already exactly that: bound in both bounds passes, already atomic, already
+ * read-write, and already this system's cross-pass GPU-owned scratch. Giving the accumulator a
+ * buffer of its own would add a binding and a growth path to say the same thing. So it is a section
+ * of this one: the counters keep their slots, the reset pass keeps writing the same fixed indices,
+ * and the section is addressed off this base.
+ *
+ * @type {number}
+ */
+export const PARTICLE_BOUNDS_BASE = PARTICLE_COUNTER_COUNT;
+
+/**
+ * Words one emitter's bounds accumulator takes: `min.xyz` then `max.xyz`, each an f32 bit pattern
+ * held in a `u32` slot (see `../bounds/chunk_particle_bounds.js` for why the storage is plain f32
+ * rather than an order-preserving encoding).
+ *
+ * @type {number}
+ */
+export const PARTICLE_BOUNDS_WORDS = 6;
+
+/**
+ * How many words the counters buffer needs to hold the counters plus one accumulator per row of an
+ * emitter table of `emitter_capacity` elements.
+ *
+ * @param {number} emitter_capacity element capacity of the emitter table
+ * @returns {number}
+ */
+export function particle_counters_word_count(emitter_capacity) {
+    return PARTICLE_BOUNDS_BASE + emitter_capacity * PARTICLE_BOUNDS_WORDS;
+}
+
+/** `bitcast<u32>(f32(+inf))` — the lower corner of the empty interval. */
+export const PARTICLE_BOUNDS_PLUS_INF = 0x7F800000;
+
+/** `bitcast<u32>(f32(-inf))` — the upper corner of the empty interval. */
+export const PARTICLE_BOUNDS_MINUS_INF = 0xFF800000;
+
+/**
+ * `row_count` accumulators, each holding the empty interval — what the publish pass leaves behind,
+ * and what a row must hold before anything has measured it.
+ *
+ * A zero-filled accumulator is NOT that: it reads back as a valid degenerate box at the world
+ * origin, which would union the origin into the first box measured for the row. WebGPU zero-fills a
+ * new buffer, so the host writes this over a newly grown region rather than relying on the fill.
+ *
+ * @param {number} row_count
+ * @returns {Uint32Array}
+ */
+export function particle_bounds_empty_words(row_count) {
+    const words = new Uint32Array(row_count * PARTICLE_BOUNDS_WORDS);
+
+    for (let word = 0; word < words.length; word += PARTICLE_BOUNDS_WORDS) {
+        words[word] = PARTICLE_BOUNDS_PLUS_INF;
+        words[word + 1] = PARTICLE_BOUNDS_PLUS_INF;
+        words[word + 2] = PARTICLE_BOUNDS_PLUS_INF;
+        words[word + 3] = PARTICLE_BOUNDS_MINUS_INF;
+        words[word + 4] = PARTICLE_BOUNDS_MINUS_INF;
+        words[word + 5] = PARTICLE_BOUNDS_MINUS_INF;
+    }
+
+    return words;
+}

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

@@ -21,12 +21,32 @@
  * 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.
  *
+ * ## The bounds are here for the same reason everything else here is
+ *
+ * An emitter has no bounds an author could state. Its particles are simulated in world space by
+ * arbitrary bytecode and go where that bytecode sends them, at whatever size it gives them; the only
+ * honest answer written down in advance is "an infinite sphere", which culls nothing. So the box is
+ * measured instead of declared: at the end of each frame a pass over the alive list reduces the live
+ * particles' world-space quads into a per-row accumulator, and a second pass publishes that into
+ * {@link bounds_min} / {@link bounds_max} here. Both are `../bounds/`.
+ *
+ * Measured state is GPU-owned state, and this is the table GPU-owned state lives in. On the emitter
+ * record it would be overwritten by the next restage — the same hazard the accumulator has, one
+ * paragraph up.
+ *
  * @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.
+ * never a live emitter's, so the first tick starts the row over whatever it held before, and the
+ * first publish replaces the bounds with a measurement.
+ *
+ * The infinite box means unknown until the bounds passes have a live population to measure.
+ *
+ * Every field is present even though the first tick overwrites all of them, because the serializer
+ * skips absent fields and table pages are recycled buffers: a skipped field would keep the previous
+ * tenant's bytes rather than being zeroed.
  */
 export const PARTICLE_EMITTER_STATE_EMPTY: Readonly<{
     generation: 0;
@@ -34,6 +54,8 @@ export const PARTICLE_EMITTER_STATE_EMPTY: Readonly<{
     age: 0;
     sleep: 0;
     pending: 0;
+    bounds_min: readonly number[];
+    bounds_max: readonly number[];
 }>;
 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

@@ -1 +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"}
+{"version":3,"file":"PARTICLE_EMITTER_STATE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STATE.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,4CAFU,YAAY,CAwBY;AAElC;;;;;;;;;;GAUG;AACH;;;;;;;;GAQG;6BAnF0B,mCAAmC"}

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

@@ -1,4 +1,4 @@
-import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { f32, u32, vec3f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 
 /**
@@ -24,6 +24,19 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
  * 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.
  *
+ * ## The bounds are here for the same reason everything else here is
+ *
+ * An emitter has no bounds an author could state. Its particles are simulated in world space by
+ * arbitrary bytecode and go where that bytecode sends them, at whatever size it gives them; the only
+ * honest answer written down in advance is "an infinite sphere", which culls nothing. So the box is
+ * measured instead of declared: at the end of each frame a pass over the alive list reduces the live
+ * particles' world-space quads into a per-row accumulator, and a second pass publishes that into
+ * {@link bounds_min} / {@link bounds_max} here. Both are `../bounds/`.
+ *
+ * Measured state is GPU-owned state, and this is the table GPU-owned state lives in. On the emitter
+ * record it would be overwritten by the next restage — the same hazard the accumulator has, one
+ * paragraph up.
+ *
  * @type {WebGPUStruct}
  */
 export const PARTICLE_EMITTER_STATE_STRUCT = WebGPUStruct.from({
@@ -37,11 +50,29 @@ export const PARTICLE_EMITTER_STATE_STRUCT = WebGPUStruct.from({
     sleep: f32,
     /** particles requested by the spawn-command pass since the last tick, consumed by the tick */
     pending: u32,
+
+    /**
+     * World-space lower corner of the box holding this emitter's live particles, as the bounds
+     * passes left it at the end of the previous frame.
+     *
+     * Infinite while no live particles have supplied a measurement. The tick treats this as
+     * visible; AVBOIT occupancy skips it. Readers test the sentinel before arithmetic on infinity.
+     */
+    bounds_min: vec3f,
+    /** world-space upper corner; see {@link bounds_min} */
+    bounds_max: vec3f,
 }, "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.
+ * never a live emitter's, so the first tick starts the row over whatever it held before, and the
+ * first publish replaces the bounds with a measurement.
+ *
+ * The infinite box means unknown until the bounds passes have a live population to measure.
+ *
+ * Every field is present even though the first tick overwrites all of them, because the serializer
+ * skips absent fields and table pages are recycled buffers: a skipped field would keep the previous
+ * tenant's bytes rather than being zeroed.
  */
 export const PARTICLE_EMITTER_STATE_EMPTY = Object.freeze({
     generation: 0,
@@ -49,4 +80,6 @@ export const PARTICLE_EMITTER_STATE_EMPTY = Object.freeze({
     age: 0,
     sleep: 0,
     pending: 0,
+    bounds_min: Object.freeze([-Infinity, -Infinity, -Infinity]),
+    bounds_max: Object.freeze([Infinity, Infinity, Infinity]),
 });

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

@@ -25,7 +25,7 @@ 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.
+ * feature flags, 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
@@ -33,7 +33,9 @@ export function emitter_flags_projection(flags: number): number;
  *
  * 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.
+ * there. The bounding box the culling and occupancy passes test is there too, and for a second
+ * reason: it is measured from the particles rather than declared by an author, so it is the GPU's
+ * value and not the CPU's.
  *
  * 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

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":"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"}
+{"version":3,"file":"PARTICLE_EMITTER_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js"],"names":[],"mappings":"AAgIA;;;;;;;;;;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;AA3JD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sCAFU,YAAY,CA+DO;AAE7B,uDAAuD;AACvD,kDAAmD;AAEnD;;GAEG;AACH;;;;;GAKG;AAEH,kGAAkG;AAClG;;;;GAIG;AAKH,kEAAkE;AAClE;;;;;;GAMG;AAqCH,uEAAuE;AACvE;;;;;GAEG;6BAlK0B,mCAAmC"}

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

@@ -1,11 +1,11 @@
-import { f32, u32, vec2f, vec3f, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { f32, u32, vec2f, 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.
+ * feature flags, 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
@@ -13,7 +13,9 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
  *
  * 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.
+ * there. The bounding box the culling and occupancy passes test is there too, and for a second
+ * reason: it is measured from the particles rather than declared by an author, so it is the GPU's
+ * value and not the CPU's.
  *
  * 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
@@ -58,11 +60,6 @@ export const PARTICLE_EMITTER_STRUCT = WebGPUStruct.from({
      */
     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 */

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

@@ -1 +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"}
+{"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,CAwClB;AAED;;;;;GAKG;AACH,yCAFa,MAAM,CA2BlB"}