@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -9,16 +9,20 @@ import {
     PARTICLE_SIMULATE_WORKGROUP_SIZE,
     PARTICLE_SORT_BUCKET_COUNT,
     PARTICLE_SPAWN_COMMAND_WORDS,
+    PARTICLE_VM_FAST_REGISTER_SLOTS,
 } from "./ParticleConstants.js";
 import { PARTICLE_COUNTER, PARTICLE_COUNTER_COUNT } from "./data/PARTICLE_COUNTERS.js";
-import { graph_particles_render, graph_particles_simulate } from "./graph_particles.js";
+import { graph_particles_simulate } from "./graph_particles.js";
 import {
     graph_particle_avboit_draw,
     graph_particle_avboit_occupancy,
     graph_particle_avboit_splat,
 } from "./graph_particles_avboit.js";
+import { graph_particles_billboard } from "./graph_particles_billboard.js";
+import { ParticleRenderMode } from "./ParticleRenderMode.js";
 import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
 import { create_particle_billboard_pipeline } from "./shaders/shader_particle_render.js";
+import { graph_particle_sort } from "./sort/graph_particle_sort.js";
 
 const WORD = Uint32Array.BYTES_PER_ELEMENT;
 
@@ -33,16 +37,29 @@ const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsa
  * ## What it owns
  *
  * Every piece of persistent GPU state: the particle pool, the ping-pong alive lists, the dead
- * free-list, the counters, both indirect-args buffers, the simulation-order (coherence) and
- * render-order (sort) scratch, the emitter database (the emitter table and the GPU-owned state
- * table, one buffer), the packed program buffer, and the spawn-command ring. Buffers that depend
- * on the emitter set — the coherence scratch on the number of distinct programs, the program
- * buffer on the arena, the database on its own pages — are grown inside {@link execute}, the way
- * ReSTIR's reservoirs follow the resolution.
+ * free-list, the counters, both indirect-args buffers, the simulation-order (coherence) scratch,
+ * the emitter database (the emitter table and the GPU-owned state table, one buffer), the packed
+ * program buffer, and the spawn-command ring. Buffers that depend on the emitter set — the
+ * coherence scratch on the number of distinct programs, the program buffer on the heap, the
+ * database on its own pages — are grown inside {@link execute}, the way ReSTIR's reservoirs follow
+ * the resolution. The render-order (sort) scratch is not in that list because it is not
+ * unconditional: see below.
  *
  * Every pass stays within the eight storage buffers a stage gets by default: the emitter record
  * and the GPU-owned state are two tables of one database buffer, and the VM's constants and code
- * are one packed buffer.
+ * are one packed buffer. The one exception is the wide-register fallback (below), whose emit and
+ * simulate passes bind a ninth for the register file — inside the ten the engine already demands of
+ * an adapter, but past the default.
+ *
+ * ## Two interpreters
+ *
+ * The VM's register file normally lives in shader registers, and is therefore small — see
+ * {@link ./ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS}. An effect whose compiled program
+ * needs more than it holds does not fail: the whole system swaps emit and simulate for variants
+ * that keep the file in a storage buffer, which is far slower and effectively unbounded. The choice
+ * is per-frame, whole-system, and made here — the registry reports `max_register_count` over the
+ * effects it holds and this is where that number meets the VM's; nothing about authoring a graph has
+ * a register ceiling.
  *
  * ## Emitters are scene nodes
  *
@@ -61,15 +78,20 @@ const INDIRECT = GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsa
  * command list that a pass adds to the emitter's pending spawns, on the same path as everything
  * else. See `graph_particles.js` for the frame.
  *
- * ## Drawing
+ * ## Drawing, and the one thing the mode changes
+ *
+ * {@link execute} is the whole per-frame call, once per frame. It always records everything that
+ * moves particles and leaves the alive list and the indirect draw args as graph handles; what it
+ * records after that is the {@link ParticleRenderMode} it was given.
  *
- * {@link simulate} records everything that moves particles and leaves the alive list and the
- * indirect draw args as graph handles. Two things draw them. Under the renderer the system is an
- * `AVBOITSideChannel`: the transparency orchestrator asks it for its occupancy, its extinction and
- * its draw at the three points where the transparent meshes have contributed theirs
- * ({@link avboit_occupancy}, {@link avboit_splat}, {@link avboit_draw}), and the particles
- * composite order-independently with them. A page without that pipeline calls {@link execute},
- * which sorts and draws the billboards straight over a colour target.
+ * `BILLBOARD` sorts the alive list back-to-front and draws it over a colour target, because
+ * premultiplied over-blending is order-dependent. `AVBOIT` records neither: under the renderer the
+ * system is an `AVBOITSideChannel`, and the transparency orchestrator asks it for its occupancy, its
+ * extinction and its draw at the three points where the transparent meshes have contributed theirs
+ * ({@link avboit_occupancy}, {@link avboit_splat}, {@link avboit_draw}). Those read the same handles
+ * and composite into a volume and a set of accumulators that are sums, so an ordering would buy
+ * nothing — and the sort is four passes and a scan over every live particle, plus two lists a word
+ * per particle each, which is why the mode also decides whether those buffers exist at all.
  *
  * ## Allocation
  *
@@ -123,7 +145,7 @@ export class GPUParticleSystem {
 
     /**
      * View-depth range the render sort quantises: particles nearer than `[0]` share the front bin,
-     * farther than `[1]` the back one.
+     * farther than `[1]` the back one. Read only by {@link ParticleRenderMode.BILLBOARD}.
      * @type {Float32Array}
      */
     sort_depth_range = new Float32Array([0.1, 100]);
@@ -139,7 +161,7 @@ export class GPUParticleSystem {
     atlas_sampler;
 
     /**
-     * The persistent GPU buffers, by the names {@link graph_particles} binds them under. Exposed for
+     * The persistent GPU buffers, by the names the graph functions bind them under. Exposed for
      * inspection — a harness copying the counters out to display them — never for the frame loop,
      * which reads nothing back. Entries that grow with the emitter set are replaced in place.
      *
@@ -207,11 +229,11 @@ export class GPUParticleSystem {
     #pipeline_key = "";
 
     /**
-     * Per-frame scalars handed to {@link graph_particles}, reused rather than rebuilt.
+     * Per-frame scalars handed to {@link graph_particles_simulate}, reused rather than rebuilt.
      * @type {object}
      */
     #frame = {
-        dt: 0, time: 0, index: 0, max_catchup: 1, spawn_command_count: 0, sort_near: 0.1, sort_far: 100,
+        dt: 0, time: 0, index: 0, max_catchup: 1, spawn_command_count: 0,
     };
 
     /** @type {{capacity: number, group_count: number}} */
@@ -275,16 +297,20 @@ export class GPUParticleSystem {
     }
 
     /**
-     * Number of simulation-order buckets — one per distinct compiled program.
+     * Number of simulation-order buckets — one per program id the registry can hand out, which is
+     * its peak number of distinct compiled programs rather than its current one.
      *
      * This is the coherence pass's only host-provided number, and it is static topology rather than
-     * per-frame state: it changes when a new effect is registered, not as particles are born and
-     * die. Everything the pass measures per frame stays on the GPU.
+     * per-frame state: it changes when an effect the set has never held is registered, not as
+     * particles are born and die. Everything the pass measures per frame stays on the GPU. Sizing it
+     * from the peak rather than the live count is what keeps it from moving every time an effect is
+     * unregistered — the bins of released ids are empty, and an empty bin rounds up to zero
+     * workgroups and shifts nothing after it.
      *
      * @returns {number}
      */
     bucketCount() {
-        return Math.max(1, this.registry.program_count);
+        return Math.max(1, this.registry.program_id_capacity);
     }
 
     /**
@@ -305,20 +331,23 @@ export class GPUParticleSystem {
      */
     spawn(emitter, count) {
         assert.defined(emitter, "emitter");
-        assert.notEqual(emitter.row, -1, "emitter is not in the scene");
         assert.isNonNegativeInteger(count, "count");
 
+        const context = this.registry.context(emitter);
+
+        assert.defined(context, "emitter is not in the scene");
+
         const ring = this.#spawn_commands;
         const base = this.#spawn_command_count * PARTICLE_SPAWN_COMMAND_WORDS;
 
         if (base >= ring.length) {
-            // the text is the key warn_limited counts on, so it carries no burst size: one message
-            // per ring size, not one per number a caller happens to ask for
+            // the text is the key warn_limited counts on, so it carries no burst size: one message
+            // per ring size, not one per number a caller happens to ask for
             warn_limited(`GPUParticleSystem: spawn command ring is full (${ring.length / PARTICLE_SPAWN_COMMAND_WORDS} per frame); dropping this frame's remaining bursts`);
             return;
         }
 
-        ring[base] = emitter.row;
+        ring[base] = context.row;
         ring[base + 1] = count;
         this.#spawn_command_emitters[this.#spawn_command_count] = emitter;
         this.#spawn_command_count++;
@@ -327,32 +356,16 @@ export class GPUParticleSystem {
     /**
      * The simulation half of the frame: reconcile the emitter set with the scene, push what changed
      * to the GPU, and record every pass that moves particles — through to the indirect draw args.
-     * What it leaves as graph handles is what a draw consumes: {@link execute} draws them
-     * standalone, and the AVBOIT side-channel methods below draw them through the renderer's
-     * transparency pipeline.
+     * What it leaves as graph handles is what a draw consumes, whichever draw that turns out to be.
      *
-     * Call after the scene context has built for the frame (`GPUSceneContext#update`), so every
-     * emitter node has its `transforms` row, and after the hierarchy pass has run, so the rows'
-     * `global` matrices are this frame's.
-     *
-     * **Once per frame, not once per view.** This advances the simulation by `dt` and hands out
-     * handles into the graph it recorded into; a second view of the same scene records a second
-     * graph and would step the simulation twice. The renderer has one view per `render` call today,
-     * so this holds by construction; a second view of one scene needs the step and the handles
-     * separated — record the passes for the first graph, import the same buffers into the rest.
-     *
-     * @param {object} params
+     * @param {object} params see {@link execute}
      * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
-     * @param {number} params.camera graph handle of the camera uniform buffer
-     * @param {number} params.scene_database graph handle of the scene database — the one the
-     *   hierarchy pass returned, so this reads the matrices it composed
-     * @param {number} params.dt seconds since the previous frame
+     * @param {number} params.camera
+     * @param {number} params.scene_database
+     * @param {number} params.dt
      * @returns {import("./graph_particles.js").ParticleSimulationHandles}
      */
-    simulate({ graph, camera, scene_database, dt }) {
-        assert.defined(graph, "graph");
-        assert.isNumber(dt, "dt");
-
+    #simulate({ graph, camera, scene_database, dt }) {
         this.#sync_membership();
         this.#upload();
 
@@ -362,8 +375,6 @@ export class GPUParticleSystem {
         frame.index = this.frame;
         frame.max_catchup = this.max_catchup_seconds;
         frame.spawn_command_count = this.#spawn_command_count;
-        frame.sort_near = this.sort_depth_range[0];
-        frame.sort_far = this.sort_depth_range[1];
 
         const table = this.registry.table;
         const emitters = this.#emitters;
@@ -384,6 +395,11 @@ export class GPUParticleSystem {
             emitters,
             capacity: this.capacity,
             bucket_count: this.bucketCount(),
+            // Whose register file the VM runs on is decided here, once, for the whole system: the
+            // registry reports what the hungriest registered effect needs and this compares it
+            // against what the fast file holds. Re-read every frame because registering an emitter —
+            // or unregistering the one hungry effect — can flip it either way.
+            wide_registers: this.registry.max_register_count > PARTICLE_VM_FAST_REGISTER_SLOTS,
             frame,
         });
 
@@ -404,35 +420,98 @@ export class GPUParticleSystem {
     }
 
     /**
-     * The whole standalone frame: {@link simulate}, then the depth sort and one billboard draw over
-     * a colour target with fixed-function blending. For a page without the renderer's transparency
-     * pipeline; under the renderer the drawing is AVBOIT's.
+     * The system's whole contribution to the frame: the simulation, then whatever `mode` says draws
+     * it.
+     *
+     * {@link ParticleRenderMode.BILLBOARD} adds the depth sort and one billboard draw over `color`
+     * with fixed-function blending, for a page with no transparency pipeline of its own.
+     * {@link ParticleRenderMode.AVBOIT} adds nothing: the orchestrator draws the particles later in
+     * the frame through {@link avboit_occupancy}, {@link avboit_splat} and {@link avboit_draw}, off
+     * the handles this just produced, and its accumulators are order-independent — so the sort is
+     * skipped and its buffers are never allocated. `color` comes straight back either way, so a
+     * caller can assign the result unconditionally and let the mode be the only difference.
      *
-     * @param {object} params every parameter of {@link simulate}, plus a target to draw over
+     * Call after the scene context has built for the frame (`GPUSceneContext#update`), so every
+     * emitter node has its `transforms` row, and after the hierarchy pass has run, so the rows'
+     * `global` matrices are this frame's.
+     *
+     * **Once per frame, not once per view.** This advances the simulation by `dt` and hands out
+     * handles into the graph it recorded into; a second view of the same scene records a second
+     * graph and would step the simulation twice. The renderer has one view per `render` call today,
+     * so this holds by construction; a second view of one scene needs the step and the handles
+     * separated — record the passes for the first graph, import the same buffers into the rest.
+     *
+     * @param {object} params
      * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
      * @param {number} params.camera graph handle of the camera uniform buffer
-     * @param {number} params.scene_database graph handle of the scene database
+     * @param {number} params.scene_database graph handle of the scene database — the one the
+     *   hierarchy pass returned, so this reads the matrices it composed
      * @param {number} params.dt seconds since the previous frame
-     * @param {number} params.color graph handle of the colour target to draw over
-     * @param {number} params.depth graph handle of the scene depth (tested, never written)
-     * @returns {number} the colour handle after the particle draw
-     */
-    execute({ graph, camera, scene_database, color, depth, dt }) {
-        const simulated = this.simulate({ graph, camera, scene_database, dt });
+     * @param {ParticleRenderMode} [params.mode] who draws, and so whether there is a sort
+     * @param {number} [params.color] graph handle of the colour target to draw over. Required by
+     *   `BILLBOARD`; returned untouched by `AVBOIT`
+     * @param {number} [params.depth] graph handle of the scene depth (tested, never written).
+     *   Required by `BILLBOARD`
+     * @returns {number|undefined} the colour handle after the particle draw, or `color` unchanged
+     */
+    execute({ graph, camera, scene_database, color, depth, dt, mode = ParticleRenderMode.BILLBOARD }) {
+        assert.defined(graph, "graph");
+        assert.isNumber(dt, "dt");
+        assert.enum(mode, ParticleRenderMode, "mode");
+
+        const billboard = mode === ParticleRenderMode.BILLBOARD;
+
+        // Checked before the simulation rather than at the draw: the simulation advances `frame` and
+        // `time` and writes the pool, and a throw after that leaves a frame half-stepped.
+        if (billboard) {
+            assert.isNonNegativeInteger(color, "color");
+            assert.isNonNegativeInteger(depth, "depth");
+        }
+
+        const simulated = this.#simulate({ graph, camera, scene_database, dt });
+
+        if (!billboard) {
+            // AVBOIT: the side channels draw these handles later in the frame, and the colour target
+            // is not this call's to touch.
+            return color;
+        }
+
+        // Allocated here rather than in the constructor: they are two words per particle plus the
+        // bins, and only this mode ever reads them. A system the renderer drives never makes them.
+        this.#ensure_sort_buffers();
+
+        // The render order: back-to-front by view depth, so premultiplied transparency composites
+        // correctly. Its two per-particle passes take the dispatch the coherence reset wrote from
+        // the GPU's own alive count.
+        const sorted = graph_particle_sort({
+            graph,
+            gpu: this.buffers,
+            camera,
+            emitter_database: simulated.emitter_database,
+            pool: simulated.pool,
+            alive: simulated.alive,
+            counters: simulated.counters,
+            dispatch_args: simulated.sim_dispatch_args,
+            bucket_count: PARTICLE_SORT_BUCKET_COUNT,
+            near: this.sort_depth_range[0],
+            far: this.sort_depth_range[1],
+        });
 
         const render = this.#render;
         render.atlas = this.atlas;
         render.atlas_sampler = this.atlas_sampler;
 
-        return graph_particles_render({
+        // One instanced billboard draw over the sorted list, sized by the draw args this frame's
+        // build-indirect wrote.
+        return graph_particles_billboard({
             graph,
             camera,
             color,
             depth,
-            gpu: this.buffers,
-            simulated,
-            sort_bucket_count: PARTICLE_SORT_BUCKET_COUNT,
-            frame: this.#frame,
+            pool: simulated.pool,
+            draw_list: sorted,
+            emitter_database: simulated.emitter_database,
+            draw_args: simulated.draw_args,
             render,
         });
     }
@@ -447,7 +526,7 @@ export class GPUParticleSystem {
     #simulated_for(graph) {
         const current = this.#simulated;
 
-        assert.equal(current.graph, graph, "the particles were not simulated into this graph this frame — call simulate() before the transparency pipeline records");
+        assert.equal(current.graph, graph, "the particles were not simulated into this graph this frame — call execute() before the transparency pipeline records");
 
         return current;
     }
@@ -580,7 +659,7 @@ export class GPUParticleSystem {
                 continue;
             }
 
-            if (node.row === -1) {
+            if (registry.context(node) === undefined) {
                 registry.add(node, transform_row);
             } else {
                 registry.set_transform_row(node, transform_row);
@@ -672,8 +751,9 @@ export class GPUParticleSystem {
         for (let i = 0; i < count; i++) {
             const emitter = emitters[i];
             const row = ring[i * PARTICLE_SPAWN_COMMAND_WORDS];
+            const context = this.registry.context(emitter);
 
-            if (emitter.row === row) {
+            if (context !== undefined && context.row === row) {
                 rows[row] += ring[i * PARTICLE_SPAWN_COMMAND_WORDS + 1];
             }
 
@@ -732,6 +812,30 @@ export class GPUParticleSystem {
         this.#sim_bucket_capacity = buckets;
     }
 
+    /**
+     * The render-order scratch, made on the first frame that actually sorts.
+     *
+     * Only {@link ParticleRenderMode.BILLBOARD} reads any of it, and the two per-particle lists are
+     * a word per particle each — at the renderer's default capacity, half a megabyte that AVBOIT
+     * would never touch. Nothing in them outlives a frame, so there is nothing to carry over and the
+     * first sorted frame is as correct as any later one.
+     */
+    #ensure_sort_buffers() {
+        const buffers = this.buffers;
+
+        if (buffers.sorted !== undefined) {
+            return;
+        }
+
+        const device = this.graphics.device;
+        const capacity = this.capacity;
+
+        buffers.sorted = device.createBuffer({ label: "particles/sorted", size: capacity * WORD, usage: STORAGE });
+        buffers.sort_keys = device.createBuffer({ label: "particles/sort_keys", size: capacity * WORD, usage: STORAGE });
+        buffers.sort_histogram = device.createBuffer({ label: "particles/sort_histogram", size: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(PARTICLE_SORT_BUCKET_COUNT)) * WORD, usage: STORAGE });
+        buffers.sort_cursor = device.createBuffer({ label: "particles/sort_cursor", size: PARTICLE_SORT_BUCKET_COUNT * WORD, usage: STORAGE });
+    }
+
     /**
      * The buffers whose size is fixed by the pool capacity, and the free list's initial contents.
      */
@@ -754,12 +858,6 @@ export class GPUParticleSystem {
         buffers.draw_args = device.createBuffer({ label: "particles/draw_args", size: 4 * WORD, usage: INDIRECT });
         buffers.sim_dispatch_args = device.createBuffer({ label: "particles/sim_dispatch_args", size: 3 * WORD, usage: INDIRECT });
 
-        // Render order.
-        buffers.sorted = device.createBuffer({ label: "particles/sorted", size: capacity * WORD, usage: STORAGE });
-        buffers.sort_keys = device.createBuffer({ label: "particles/sort_keys", size: capacity * WORD, usage: STORAGE });
-        buffers.sort_histogram = device.createBuffer({ label: "particles/sort_histogram", size: (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(PARTICLE_SORT_BUCKET_COUNT)) * WORD, usage: STORAGE });
-        buffers.sort_cursor = device.createBuffer({ label: "particles/sort_cursor", size: PARTICLE_SORT_BUCKET_COUNT * WORD, usage: STORAGE });
-
         buffers.spawn_commands = device.createBuffer({ label: "particles/spawn_commands", size: this.#spawn_commands.byteLength, usage: STORAGE });
 
         // Every slot free, and the counters saying so.
@@ -874,7 +972,7 @@ export class GPUParticleSystem {
 /**
  * A storage buffer holding `data`, replacing `previous` (destroyed) if it exists. The program
  * buffer is monolithic — a program is variable-length, so there is no table to page it into — and
- * is rebuilt whole on the rare frame the arena grows.
+ * is rebuilt whole on the rare frame the program heap changes.
  *
  * @param {GPUDevice} device
  * @param {GPUBuffer|undefined} previous

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

@@ -65,24 +65,33 @@ export const PARTICLE_SORT_BUCKET_COUNT: number;
  */
 export const PARTICLE_RECORD_USER_WORD_START: number;
 /**
- * Size of the VM register file, in `f32` slots. A register IS a slot: a `vec3` value is three
+ * Register slots the INSTRUCTION SET can name. A register IS a slot: a `vec3` value is three
  * consecutive ones, and an instruction's width says how many its operands span.
  *
- * This is the interpreter's single largest cost and it is paid by every program, not just the ones
- * that need it: `vm_reg` is a `var<private>` array the VM indexes dynamically, which lands in
- * registers rather than scratch, so the file's size sets the shader's register footprint outright.
- * Compiled to RDNA2 (gfx1030, wave32), 32 slots cost 47 VGPRs against a 16-wave occupancy cap that
- * anything at or below 64 VGPRs reaches. Sixteen `vec4` registers — what this was — cost 81 and
- * held the shader to 10 waves.
+ * This is an encoding fact, not a shader's budget. A destination is the 8-bit `VM_DST_MASK` field
+ * of word 0 and every source base is the 8-bit `VM_OPERAND_BASE_MASK` field of its own word, so 256
+ * is exactly what an instruction can address and reaching the ceiling costs nothing. Past it the
+ * instruction word would have to grow — there is room (word 0 has bits 11..15 and 22..23 free, and
+ * each operand word uses only its low 16) — but nothing needs it yet.
  *
- * Scalar slots are also what makes the number go further than the same count of floats did as
- * `vec4`s: eight `vec4` registers hold eight values whatever their width, while 32 slots hold ten
- * `vec3`s or 32 scalars. The playground's fire effect, the most involved in the tree, peaks at 11
- * slots live.
+ * What a *shader* can afford is a different and much smaller number, see
+ * {@link PARTICLE_VM_FAST_REGISTER_SLOTS}. The graph compiler allocates against this one, records
+ * the peak as the program's `register_count`, and the runtime picks an interpreter from it.
  *
- * A graph that needs more gets a clear error out of `compile_particle_graph.js` rather than silent
- * corruption, and the fix for it is to raise this number and re-measure — not to assume the headroom
- * was free.
+ * @type {number}
+ */
+export const PARTICLE_VM_REGISTER_SLOTS: number;
+/**
+ * Register slots the FAST interpreter's file holds — `vm_reg` in
+ * {@link ./vm/chunk_particle_vm_registers_fast.js}, a `var<private>` array the VM indexes
+ * dynamically. It lands in registers rather than scratch, so this number is the shader's register
+ * footprint outright, and every program pays it rather than only the ones that need it.
+ *
+ * Compiled to RDNA2 (gfx1030, wave32), 32 slots cost 47 VGPRs; sixteen `vec4` registers — what this
+ * was — cost 81 and held the shader to 10 waves against a 16-wave cap that anything at or below 64
+ * VGPRs reaches. Scalar slots are also what makes the number go further than the same count of
+ * floats did as `vec4`s: eight `vec4` registers hold eight values whatever their width, while 32
+ * slots hold ten `vec3`s or 32 scalars.
  *
  * ## Why 48 and not 32
  *
@@ -91,21 +100,48 @@ export const PARTICLE_RECORD_USER_WORD_START: number;
  * any of them: measured peaks are 26 for `simplex3`, 33 for `simplex4`, 32 for `curl3` and 40 for
  * `curl4` — the last with a whole effect's worth of arithmetic still to fit around it.
  *
- * 48 is the largest number that the measurement above says is free. At 32 slots the shader compiled
- * to 47 VGPRs, and a slot is about a VGPR, so 48 lands around 63 — still at or under the 64 that
- * reaches the 16-wave occupancy cap. **That arithmetic has not been re-measured against a real
- * driver.** It is the model the paragraphs above were written from, and it is a model; anyone
- * changing this number again, or wanting to be sure of this one, should compile the simulate shader
- * offline and read the register count rather than trust it.
+ * 48 was picked by extrapolating the 32-slot measurement: a slot is about a VGPR, so 48 should land
+ * near 63, at or under the 64 that reaches the occupancy cap. **That extrapolation was wrong.** The
+ * measured table in {@link ./vm/chunk_particle_vm.js} puts this interpreter at 80 VGPRs on a 48-slot
+ * file, well past the cap it was sized to stay under. The number stays because it is measured and
+ * shipped, not because the model that chose it holds; anyone moving it should compile the simulate
+ * shader offline and read the register count rather than extrapolate again.
+ *
+ * ## What happens above it
+ *
+ * Nothing fails. A program whose `register_count` exceeds this is one the fast file cannot hold, and
+ * the system falls back to the wide interpreter for the frame — every program, not only the one that
+ * overflowed. That is the library declining to have an authoring ceiling, at the price of an
+ * interpreter that keeps its registers in storage. See {@link PARTICLE_VM_WIDE_LAUNCH_LANES} and
+ * {@link ./vm/chunk_particle_vm_registers_wide.js}.
  *
  * @type {number}
  */
-export const PARTICLE_VM_REGISTER_SLOTS: number;
+export const PARTICLE_VM_FAST_REGISTER_SLOTS: number;
 /**
- * Number of `u32` words per VM instruction: `[op, dst, s0, s1, s2]`.
+ * Invocations the wide-register simulate and emit passes launch, whatever the particle count.
+ *
+ * The wide interpreter keeps its register file in a storage buffer, so it needs one file per
+ * *invocation in flight*. One lane per particle would size that buffer by pool capacity — a million
+ * particles would want a gigabyte — so the wide passes do not run one lane per particle. They launch
+ * this many lanes and walk their input with a grid-stride loop, which caps the file count at a
+ * constant chosen here instead of at whatever the pool holds.
+ *
+ * The buffer is `PARTICLE_VM_WIDE_LAUNCH_LANES * PARTICLE_VM_REGISTER_SLOTS * 4` bytes — 8 MiB at
+ * these values. It is transient: never cleared, never read back, and shared by the emit and simulate
+ * passes, which cannot overlap. See {@link ./vm/chunk_particle_vm_registers_wide.js} for why not
+ * clearing it is safe.
+ *
+ * Must be a multiple of {@link PARTICLE_SIMULATE_WORKGROUP_SIZE}, and of
+ * {@link PARTICLE_EMIT_WORKGROUP_SIZE}. The grid stride IS this number, so every iteration has to
+ * cover a workgroup-aligned span of the coherence pass's list; a misaligned stride would put two
+ * programs in one wave and the wave-uniform section decode would then run one program's code over
+ * the other's particles.
+ *
  * @type {number}
  */
-export const PARTICLE_VM_INSTRUCTION_WORDS: number;
+export const PARTICLE_VM_WIDE_LAUNCH_LANES: number;
+export { PARTICLE_VM_INSTRUCTION_WORDS } from "./isa/ParticleVMISA.js";
 /**
  * Hard cap on instructions executed by a single VM program invocation. A safety bound so a malformed
  * program can never spin the GPU; the interpreter's loop is `for (i in 0..LIMIT)`.

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;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;;;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"}