@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/vm/chunk_particle_vm.js

@@ -1,86 +1,124 @@
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { chunk_random } from "../../shader/chunk/random/chunk_random.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import {
-    PARTICLE_PROGRAM_CODE_BASE_WORD,
-    PARTICLE_PROGRAM_HEADER_WORDS,
-    PARTICLE_VM_MAX_INSTRUCTIONS,
-    PARTICLE_VM_REGISTER_SLOTS,
-} from "../ParticleConstants.js";
-import {
+    PARTICLE_VM_INSTRUCTION_WORDS,
     VM_BUILTIN,
+    VM_DST_MASK,
+    VM_DST_SHIFT,
+    VM_KIND,
+    VM_KIND_BITS,
+    VM_KIND_MASK,
+    VM_KIND_SHIFT,
     VM_OP,
     VM_OP_MASK,
+    VM_OPERAND_BASE_MASK,
+    VM_OPERAND_SWIZZLE_SHIFT,
+    VM_SWIZZLE_IDENTITY,
     VM_WIDTH_MASK,
     VM_WIDTH_SHIFT,
 } from "../isa/ParticleVMISA.js";
+import {
+    PARTICLE_PROGRAM_CODE_BASE_WORD,
+    PARTICLE_PROGRAM_HEADER_WORDS,
+    PARTICLE_VM_MAX_INSTRUCTIONS,
+} from "../ParticleConstants.js";
+import { PARTICLE_VM_CONTEXT_STRUCT } from "./PARTICLE_VM_CONTEXT_STRUCT.js";
 
 /**
  * WGSL implementation of the particle VM — the interpreter a single simulation dispatch runs over
  * every particle. It is written to match {@link ../vm/ParticleVMReference.js} exactly; the parity
  * spec cross-checks the two through the emulator.
  *
- * Opcode numbers, register-file size and the instruction budget are interpolated straight from the
- * ISA / constants so the WGSL can never drift from the JS side.
+ * Opcode numbers, field positions, register-file size and the instruction budget are interpolated
+ * straight from the ISA / constants so the WGSL can never drift from the JS side.
+ *
+ * ## Resolve, compute, write
+ *
+ * Every instruction runs in three steps, and only the middle one knows the opcode. {@link vm_source}
+ * resolves each of the three sources into a four-lane value by the kind word 0 gives it — a register
+ * run read through its swizzle, or a literal — with the lanes past the instruction's width zero.
+ * The opcode body is then one expression over those values, `d = a + b`, and the lanes the opcode
+ * writes go back to the register file afterwards. Because every source is read before anything is
+ * written, a source may overlap the destination in any way; there is no aliasing rule to keep.
+ *
+ * That shape is what the operand swizzles and the literal kind bought: there is no `SWIZZLE` case,
+ * no `SCALE` case, no per-opcode operand loop, and the reductions sum four lanes of which the unread
+ * ones are zero.
+ *
+ * ## A lane per statement, never a computed component
+ *
+ * Nothing here indexes a vector by a variable. {@link vm_source} fills `v.x`, `v.y`, `v.z`, `v.w`
+ * one statement each behind a width test; the stores, the pool and attribute loads and the RNG draws
+ * do the same; the write-back is four predicated stores. The obvious loop — `for (c < lanes) {
+ * v[c] = ... }` — is the same program and three times slower on an RTX 4090 (5.0 ms against 1.7 ms
+ * for the simulate pass of a 4876-instruction effect at 20k alive): a vector written through a
+ * computed index is addressable memory as far as the compiler is concerned, so `a`, `b`, `c` and `d`
+ * all moved to local memory and every lane became a store and a reload. Spelled out, they stay in
+ * registers, and an instruction costs what it did under the per-opcode loops (within noise at 50k
+ * and 200k alive on the same effect), with the literal kind's savings on top. The register file is
+ * the one dynamically indexed array, as it always was.
+ *
+ * ## Registers are scalars, and they are not declared here
  *
- * ## Registers are scalars
+ * A register is one `f32` slot, not a `vec4`, and an instruction's width says how many consecutive
+ * slots each of its operands spans. The same count of floats as slots holds far more values than it
+ * did as `vec4`s, because a `vec3` costs three of them instead of four: as `vec4`s the file cost 81
+ * VGPRs on RDNA2 and held the shader to 10 waves against a cap of 16.
  *
- * `vm_reg` is an `array<f32>`, not an `array<vec4<f32>>`, and an instruction's width says how many
- * consecutive slots each of its operands spans. The file is dynamically indexed, so it lives in
- * registers rather than scratch and its size is the shader's register footprint: as `vec4`s it cost
- * 81 VGPRs on RDNA2 and held the shader to 10 waves against a cap of 16, and the same count of
- * floats as slots holds far more values, because a `vec3` costs three of them instead of four.
- * Spanning only the lanes an instruction needs also roughly halves both the arithmetic and the
- * interpreter's own size — a `vec4` op against a dynamically indexed file is twelve `v_movrel`,
- * where a loop over its width is emitted once.
+ * Where those slots LIVE is not this chunk's business. The interpreter reads and writes them through
+ * `vm_reg_read` and `vm_reg_write`, which a backing chunk supplies — the same external-symbol seam
+ * `particle_vm_sample_curve` uses. There are two backings and they are the two interpreters:
+ *
+ * - {@link ./chunk_particle_vm_registers_fast.js} — a `var<private>` array of
+ *   {@link ../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS}. Dynamically indexed, so it
+ *   lives in registers rather than scratch, and its size is the shader's register footprint. This
+ *   is the interpreter everything runs on.
+ * - {@link ./chunk_particle_vm_registers_wide.js} — a storage buffer of
+ *   {@link ../ParticleConstants.js PARTICLE_VM_REGISTER_SLOTS}, which is every slot the ISA can
+ *   name. Slow, and the fallback for a program the fast file cannot hold.
+ *
+ * The seam is deliberately narrow: two functions, no opcode knows which backing it has, and the
+ * measurements below were taken on the fast one and describe it.
  *
  * ## The builtin context stays a struct
  *
  * `vm_load_builtin`'s `switch` looks like something an `array<f32, 8 * 4>` indexed by builtin id
  * would delete outright — the shape the JS reference's `builtins` already has. It is measured, not
- * assumed, and the array loses: on RDNA2 (gfx1030, amdspv) the register file stops living in
- * registers the moment a SECOND dynamically indexed array exists, whatever its size. Same
- * interpreter, one builtin load:
- *
- * | builtin context             | VGPRs | scratch   | waves |
- * |-----------------------------|-------|-----------|-------|
- * | struct + switch (this)      | 53    | 0         | 16    |
- * | `array<f32, 32>` by id      | 46    | 64 dwords | 16    |
- * | `array<vec4<f32>, 8>`       | 47    | 64 dwords | 16    |
- * | context atop a 64-slot file | 78    | 0         | 12    |
+ * assumed, and the array loses: on RDNA2 (gfx1030, amdspv, simulate's wave-uniform form, a 48-slot
+ * file) a SECOND dynamically indexed array costs sixteen VGPRs whatever its size — as much as growing
+ * the register file by a third — for 28 more instructions and nothing back. Same interpreter, one
+ * builtin load:
  *
- * 64 dwords is `vm_reg` plus the context spilled together: the promotion pass gives up on both
- * rather than picking one, and every register access becomes memory traffic. Folding the context
- * into the register file instead keeps it out of scratch and costs a quarter of the occupancy. So
- * the id stays a `switch` over named fields — a select chain fed from the registers the setup
- * wrote — and only the per-lane pick was worth deleting.
+ * | builtin context             | VGPRs | scratch | instructions |
+ * |-----------------------------|-------|---------|--------------|
+ * | struct + switch (this)      | 80    | 0       | 917          |
+ * | `array<f32, 32>` by id      | 96    | 0       | 945          |
+ * | `array<vec4<f32>, 8>`       | 96    | 0       | 945          |
+ * | this atop a 64-slot file    | 96    | 0       | 925          |
  *
- * Dispatch uses a `switch` over the opcode — a jump table on real hardware and (since the emulator
- * gained switch support) directly emulator-runnable. Register-file writes are the only per-instruction
- * state mutation, which the emulator handles reliably; the RNG state (RANDOM opcode) is a running
- * read-modify-write, and now that the emulator wraps u32 arithmetic at 32 bits it runs through the
- * interpreter loop too and is cross-checked against the reference by the parity spec.
+ * Under the per-opcode interpreter this replaced it was worse still: the promotion pass gave up on
+ * both arrays rather than picking one and spilled the register file to scratch. So the id stays a
+ * `switch` over named fields.
  *
- * The RNG is the engine's house generator: `RANDOM` draws through `random()`, over the shared
- * `rnd_state`. The VM used to carry its own PCG and its own state word, which by the end differed
- * from `random()` in nothing but the names — an implementation fork with no reason to exist.
+ * Dispatch uses a `switch` over the opcode — a jump table on real hardware and directly
+ * emulator-runnable. Register-file writes are the only per-instruction state mutation; the RNG
+ * state (`RANDOM`) is a running read-modify-write over the shared `rnd_state`, which the emulator
+ * wraps at 32 bits and the parity spec holds to the reference draw for draw.
  *
  * ## The RNG has no distributions
  *
- * `RANDOM` is one uniform draw per lane, and that is the whole opcode. It used to switch over a
- * distribution mode — signed, unit sphere, unit disk — and each of those is arithmetic a program
- * can write over this draw for itself: with their constants hoisted, a unit sphere is ten
- * instructions and a unit disk seven, bit-identical to what the switch computed, because they are
- * the same expression. A sampler is a useful thing to have and there is no principled place to stop
- * adding them, which is the argument for the VM having none: they belong in a library over the
- * instruction set, not inside it — see ../graph/particle_graph_distributions.js.
+ * `RANDOM` is one uniform draw per lane, and that is the whole opcode. A shaped distribution is
+ * arithmetic a program writes over the draw — see ../graph/particle_graph_distributions.js.
  *
  * ## Contract
  *
- * - Register file, kill flag and the builtin context are module-scope `var<private>`, as is the
- *   shared `rnd_state` the RNG runs on. Call `particle_vm_reset()` at the start of each particle,
- *   seed `rnd_state`, and populate `vm_ctx` before invoking {@link particle_vm_execute}.
+ * - The enclosing shader must include exactly one register backing chunk — see above. Nothing in
+ *   here declares `vm_reg_read` / `vm_reg_write`.
+ * - Kill flag and the builtin context are module-scope `var<private>`, as is the shared `rnd_state`
+ *   the RNG runs on. Call `particle_vm_reset()` at the start of each particle, seed `rnd_state`, and
+ *   populate `vm_ctx` before invoking {@link particle_vm_execute}.
  * - `particle_vm_execute(program, code_offset, instruction_count, constant_offset, pool,
- *   record_base)` runs one section. `program` is the packed arena buffer — header, constant pool,
+ *   record_base)` runs one section. `program` is the packed program buffer — header, constant pool,
  *   code, see `ParticleConstants.PARTICLE_PROGRAM_HEADER_WORDS` — so code and data are one binding.
  *   Attributes are read/written as f32 bit patterns inside `pool` at `record_base +
  *   attribute_offset`.
@@ -94,36 +132,21 @@ import {
  *   f32`. The enclosing shader must define it (production: animation-curve backed; tests: a stub).
  */
 
-const R = PARTICLE_VM_REGISTER_SLOTS;
-
 const source = /* language=wgsl */ `
-const PARTICLE_VM_REGISTER_SLOTS : u32 = ${R}u;
 const PARTICLE_VM_MAX_INSTRUCTIONS : u32 = ${PARTICLE_VM_MAX_INSTRUCTIONS}u;
+const PARTICLE_VM_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
 const PARTICLE_PROGRAM_HEADER_WORDS : u32 = ${PARTICLE_PROGRAM_HEADER_WORDS}u;
 const PARTICLE_PROGRAM_CODE_BASE_WORD : u32 = ${PARTICLE_PROGRAM_CODE_BASE_WORD}u;
 
-// Per-invocation builtin inputs the host assembles before running a program.
-struct ParticleVMContext {
-    delta_time : f32,
-    emitter_age : f32,
-    time : f32,
-    spawn_fraction : f32,
-    particle_index : f32,
-    emitter_position : vec3<f32>,
-    emitter_direction : vec3<f32>,
-    emitter_up : vec3<f32>,
-}
-
-// One f32 per slot. A value of width w occupies w consecutive slots, and an operand names the first.
-var<private> vm_reg : array<f32, ${R}>;
 var<private> vm_killed : bool;
-var<private> vm_ctx : ParticleVMContext;
+var<private> vm_ctx : ${PARTICLE_VM_CONTEXT_STRUCT.wgsl_ref};
 
-// Zero the register file and reset the kill flag. Call once per particle before executing a section.
+// Ready the interpreter for one particle: clear the kill flag, and nothing else. Neither backing
+// resets its register file — the private one is zero at the start of every invocation by language
+// rule, the storage one is undefined until written — so there is nothing to call. The flag is reset
+// because a wide invocation walks many particles in a grid-stride loop, and the second must not
+// inherit the first's verdict.
 fn particle_vm_reset() {
-    for (var i = 0u; i < PARTICLE_VM_REGISTER_SLOTS; i = i + 1u) {
-        vm_reg[i] = 0.0;
-    }
     vm_killed = false;
 }
 
@@ -143,38 +166,29 @@ fn vm_load_builtin(id : u32) -> vec4<f32> {
     }
 }
 
-// Sum of products over \`width\` slots of each operand. The reductions are all this plus a square root.
-fn vm_dot_slots(a : u32, b : u32, width : u32) -> f32 {
-    var sum = 0.0;
-    for (var c = 0u; c < width; c = c + 1u) {
-        sum = sum + vm_reg[a + c] * vm_reg[b + c];
-    }
-    return sum;
-}
-
-// Read an attribute (f32 bits) out of the record into \`width\` slots. Slots past the attribute's
-// component count read zero, which is how a narrow attribute reaches a wider operation for free.
-fn vm_load_attr(pool : ptr<storage, array<u32>, read_write>, base : u32, off : u32, comp : u32, dst : u32, width : u32) {
-    for (var c = 0u; c < width; c = c + 1u) {
-        if (c < comp) {
-            vm_reg[dst + c] = bitcast<f32>((*pool)[base + off + c]);
-        } else {
-            vm_reg[dst + c] = 0.0;
-        }
-    }
-}
-
-// One record word per component, and the width is the component count — a store cannot write slots
-// the value does not have.
-fn vm_store_attr(pool : ptr<storage, array<u32>, read_write>, base : u32, off : u32, comp : u32, src : u32) {
-    for (var c = 0u; c < comp; c = c + 1u) {
-        (*pool)[base + off + c] = bitcast<u32>(vm_reg[src + c]);
+// One source, resolved by the kind word 0 gives it: a register run read through its swizzle, or a
+// literal in every lane. Lanes past \`lanes\` are zero, so a reduction may sum all four. The only
+// place the kinds and swizzles are read; every opcode below sees a value.
+fn vm_source(kind : u32, word : u32, lanes : u32) -> vec4<f32> {
+    // One lane per statement, each behind its own width test: a component written through a
+    // computed index would put the vector in local memory, and that is the whole cost of the VM.
+    var v = vec4<f32>(0.0);
+    if (kind == ${VM_KIND.REG}u) {
+        let base = word & ${VM_OPERAND_BASE_MASK}u;
+        let swizzle = ((word >> ${VM_OPERAND_SWIZZLE_SHIFT}u) & 0xffu) ^ ${VM_SWIZZLE_IDENTITY}u;
+        v.x = vm_reg_read(base + (swizzle & 3u));
+        if (lanes > 1u) { v.y = vm_reg_read(base + ((swizzle >> 2u) & 3u)); }
+        if (lanes > 2u) { v.z = vm_reg_read(base + ((swizzle >> 4u) & 3u)); }
+        if (lanes > 3u) { v.w = vm_reg_read(base + ((swizzle >> 6u) & 3u)); }
+    } else if (kind == ${VM_KIND.IMM}u) {
+        v = select(vec4<f32>(0.0), vec4<f32>(bitcast<f32>(word)), vec4<bool>(true, lanes > 1u, lanes > 2u, lanes > 3u));
     }
+    return v;
 }
 
 // Execute one program section against a particle record living in pool at record_base.
 //
-// \`program\` is the packed arena buffer: a header, the constant pool, then the code. The header's
+// \`program\` is the packed program buffer: a header, the constant pool, then the code. The header's
 // first word says where the code starts; \`code_offset\` is a word offset into the code section and
 // \`constant_offset\` a WORD index into the pool — both as the emitter record carries them.
 fn particle_vm_execute(
@@ -187,184 +201,132 @@ fn particle_vm_execute(
 ) {
     let count = min(instruction_count, PARTICLE_VM_MAX_INSTRUCTIONS);
     let code_base = (*program)[PARTICLE_PROGRAM_CODE_BASE_WORD] + code_offset;
+    let pool_base = PARTICLE_PROGRAM_HEADER_WORDS + constant_offset;
 
     for (var pc = 0u; pc < count; pc = pc + 1u) {
-        let ib = code_base + pc * 5u;
+        let ib = code_base + pc * PARTICLE_VM_INSTRUCTION_WORDS;
         let word0 = (*program)[ib];
+        let s0 = (*program)[ib + 1u];
+        let s1 = (*program)[ib + 2u];
+        let s2 = (*program)[ib + 3u];
+
         let op = word0 & ${VM_OP_MASK}u;
-        // Lane count this instruction spans. The opcodes whose count is fixed ignore it.
+        // Lane count this instruction spans. The opcodes whose count is fixed have it encoded so.
         let w = (word0 >> ${VM_WIDTH_SHIFT}u) & ${VM_WIDTH_MASK}u;
-        let dst = (*program)[ib + 1u];
-        let s0 = (*program)[ib + 2u];
-        let s1 = (*program)[ib + 3u];
-        let s2 = (*program)[ib + 4u];
+        let dst = (word0 >> ${VM_DST_SHIFT}u) & ${VM_DST_MASK}u;
+
+        let a = vm_source((word0 >> ${VM_KIND_SHIFT}u) & ${VM_KIND_MASK}u, s0, w);
+        let b = vm_source((word0 >> ${VM_KIND_SHIFT + VM_KIND_BITS}u) & ${VM_KIND_MASK}u, s1, w);
+        let c = vm_source((word0 >> ${VM_KIND_SHIFT + 2 * VM_KIND_BITS}u) & ${VM_KIND_MASK}u, s2, w);
+
+        var d = vec4<f32>(0.0);
+        // How many lanes of d reach the register file: the width, one for a reduction, none for an
+        // opcode whose effect is elsewhere.
+        var lanes = w;
 
         switch op {
             case ${VM_OP.HALT}u: { return; }
-            case ${VM_OP.NOP}u: {}
-            case ${VM_OP.MOV}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = vm_reg[s0 + c]; }
-            }
+            case ${VM_OP.NOP}u: { lanes = 0u; }
+            case ${VM_OP.MOV}u: { d = a; }
             case ${VM_OP.LOAD_CONST}u: {
-                let cb = PARTICLE_PROGRAM_HEADER_WORDS + constant_offset + s0;
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = bitcast<f32>((*program)[cb + c]); }
-            }
-            case ${VM_OP.LOAD_ATTR}u: { vm_load_attr(pool, record_base, s0, s1, dst, w); }
-            case ${VM_OP.STORE_ATTR}u: { vm_store_attr(pool, record_base, s0, s1, dst); }
-            case ${VM_OP.LOAD_BUILTIN}u: {
-                // The lane is a dynamic index into a vec4 VALUE, not into memory: no second array,
-                // and five instructions fewer than the switch that used to pick it.
-                let v = vm_load_builtin(s0);
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = v[c]; }
+                let k = pool_base + s0;
+                d.x = bitcast<f32>((*program)[k]);
+                if (w > 1u) { d.y = bitcast<f32>((*program)[k + 1u]); }
+                if (w > 2u) { d.z = bitcast<f32>((*program)[k + 2u]); }
+                if (w > 3u) { d.w = bitcast<f32>((*program)[k + 3u]); }
+            }
+            case ${VM_OP.LOAD_ATTR}u: {
+                // Lanes past the attribute's component count read zero, which is how a narrow
+                // attribute reaches a wider operation for free.
+                let k = record_base + s0;
+                let n = min(w, s1);
+                d.x = bitcast<f32>((*pool)[k]);
+                if (n > 1u) { d.y = bitcast<f32>((*pool)[k + 1u]); }
+                if (n > 2u) { d.z = bitcast<f32>((*pool)[k + 2u]); }
+                if (n > 3u) { d.w = bitcast<f32>((*pool)[k + 3u]); }
+            }
+            case ${VM_OP.STORE_ATTR}u: {
+                // One record word per component; the width is the component count.
+                let k = record_base + s1;
+                (*pool)[k] = bitcast<u32>(a.x);
+                if (s2 > 1u) { (*pool)[k + 1u] = bitcast<u32>(a.y); }
+                if (s2 > 2u) { (*pool)[k + 2u] = bitcast<u32>(a.z); }
+                if (s2 > 3u) { (*pool)[k + 3u] = bitcast<u32>(a.w); }
+                lanes = 0u;
+            }
+            case ${VM_OP.LOAD_BUILTIN}u: { d = vm_load_builtin(s0); }
+            case ${VM_OP.KILL}u: {
+                if (a.x > 0.0) { vm_killed = true; }
+                lanes = 0u;
             }
-            case ${VM_OP.KILL}u: { if (vm_reg[dst] > 0.0) { vm_killed = true; } }
 
-            case ${VM_OP.ADD}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = vm_reg[s0 + c] + vm_reg[s1 + c]; }
-            }
-            case ${VM_OP.SUB}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = vm_reg[s0 + c] - vm_reg[s1 + c]; }
-            }
-            case ${VM_OP.MUL}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = vm_reg[s0 + c] * vm_reg[s1 + c]; }
-            }
-            case ${VM_OP.DIV}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = vm_reg[s0 + c] / vm_reg[s1 + c]; }
-            }
-            case ${VM_OP.MAD}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = vm_reg[s0 + c] * vm_reg[s1 + c] + vm_reg[s2 + c]; }
-            }
-            case ${VM_OP.MIN}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = min(vm_reg[s0 + c], vm_reg[s1 + c]); }
-            }
-            case ${VM_OP.MAX}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = max(vm_reg[s0 + c], vm_reg[s1 + c]); }
-            }
-            case ${VM_OP.MIX}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = mix(vm_reg[s0 + c], vm_reg[s1 + c], vm_reg[s2 + c]); }
-            }
-            case ${VM_OP.CLAMP}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = clamp(vm_reg[s0 + c], vm_reg[s1 + c], vm_reg[s2 + c]); }
-            }
-            case ${VM_OP.SCALE}u: {
-                let k = vm_reg[s1];
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = vm_reg[s0 + c] * k; }
-            }
+            case ${VM_OP.ADD}u: { d = a + b; }
+            case ${VM_OP.SUB}u: { d = a - b; }
+            case ${VM_OP.MUL}u: { d = a * b; }
+            case ${VM_OP.DIV}u: { d = a / b; }
+            case ${VM_OP.MAD}u: { d = a * b + c; }
+            case ${VM_OP.MIN}u: { d = min(a, b); }
+            case ${VM_OP.MAX}u: { d = max(a, b); }
+            case ${VM_OP.MIX}u: { d = mix(a, b, c); }
+            case ${VM_OP.CLAMP}u: { d = clamp(a, b, c); }
 
-            case ${VM_OP.NEG}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = -vm_reg[s0 + c]; }
-            }
-            case ${VM_OP.ABS}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = abs(vm_reg[s0 + c]); }
-            }
-            case ${VM_OP.FLOOR}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = floor(vm_reg[s0 + c]); }
-            }
-            case ${VM_OP.FRACT}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = fract(vm_reg[s0 + c]); }
-            }
-            case ${VM_OP.SQRT}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = sqrt(vm_reg[s0 + c]); }
-            }
-            case ${VM_OP.SIN}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = sin(vm_reg[s0 + c]); }
-            }
-            case ${VM_OP.COS}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = cos(vm_reg[s0 + c]); }
-            }
-            case ${VM_OP.EXP}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = exp(vm_reg[s0 + c]); }
-            }
-            case ${VM_OP.LOG}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = log(vm_reg[s0 + c]); }
-            }
-            case ${VM_OP.POW}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = pow(vm_reg[s0 + c], vm_reg[s1 + c]); }
-            }
-            case ${VM_OP.STEP}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = step(vm_reg[s0 + c], vm_reg[s1 + c]); }
-            }
-            case ${VM_OP.SMOOTHSTEP}u: {
-                for (var c = 0u; c < w; c = c + 1u) {
-                    vm_reg[dst + c] = smoothstep(vm_reg[s0 + c], vm_reg[s1 + c], vm_reg[s2 + c]);
-                }
-            }
+            case ${VM_OP.NEG}u: { d = -a; }
+            case ${VM_OP.ABS}u: { d = abs(a); }
+            case ${VM_OP.FLOOR}u: { d = floor(a); }
+            case ${VM_OP.FRACT}u: { d = fract(a); }
+            case ${VM_OP.SQRT}u: { d = sqrt(a); }
+            case ${VM_OP.SIN}u: { d = sin(a); }
+            case ${VM_OP.COS}u: { d = cos(a); }
+            case ${VM_OP.EXP}u: { d = exp(a); }
+            case ${VM_OP.LOG}u: { d = log(a); }
+            case ${VM_OP.POW}u: { d = pow(a, b); }
+            case ${VM_OP.STEP}u: { d = step(a, b); }
+            case ${VM_OP.SMOOTHSTEP}u: { d = smoothstep(a, b, c); }
+            case ${VM_OP.RSQRT}u: { d = inverseSqrt(a); }
+            case ${VM_OP.TAN}u: { d = tan(a); }
+            case ${VM_OP.ASIN}u: { d = asin(a); }
+            case ${VM_OP.ACOS}u: { d = acos(a); }
+            case ${VM_OP.ATAN2}u: { d = atan2(a, b); }
 
-            // The reductions write ONE slot. Whatever wants the result wider gets an explicit
-            // broadcast from the compiler; the implicit fill-all-four is gone.
-            case ${VM_OP.DOT}u: { vm_reg[dst] = vm_dot_slots(s0, s1, w); }
-            case ${VM_OP.CROSS}u: {
-                // Both operands are read out before either is written: the destination is allowed to
-                // be one of them.
-                let ax = vm_reg[s0]; let ay = vm_reg[s0 + 1u]; let az = vm_reg[s0 + 2u];
-                let bx = vm_reg[s1]; let by = vm_reg[s1 + 1u]; let bz = vm_reg[s1 + 2u];
-                vm_reg[dst] = ay * bz - az * by;
-                vm_reg[dst + 1u] = az * bx - ax * bz;
-                vm_reg[dst + 2u] = ax * by - ay * bx;
-                // A fourth slot, if asked for, is the zero the opcode used to append.
-                for (var c = 3u; c < w; c = c + 1u) { vm_reg[dst + c] = 0.0; }
-            }
-            case ${VM_OP.LENGTH}u: { vm_reg[dst] = sqrt(vm_dot_slots(s0, s0, w)); }
+            // The reductions write ONE lane; the lanes past the width are zero and add nothing.
+            case ${VM_OP.DOT}u: { d.x = dot(a, b); lanes = 1u; }
+            case ${VM_OP.CROSS}u: { d = vec4<f32>(cross(a.xyz, b.xyz), 0.0); }
+            case ${VM_OP.LENGTH}u: { d.x = sqrt(dot(a, a)); lanes = 1u; }
             case ${VM_OP.NORMALIZE}u: {
-                let len = sqrt(vm_dot_slots(s0, s0, w));
-                let inv = select(0.0, 1.0 / len, len > 0.0);
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = vm_reg[s0 + c] * inv; }
+                let len = sqrt(dot(a, a));
+                d = a * select(0.0, 1.0 / len, len > 0.0);
             }
             case ${VM_OP.DISTANCE}u: {
-                var sum = 0.0;
-                for (var c = 0u; c < w; c = c + 1u) {
-                    let e = vm_reg[s0 + c] - vm_reg[s1 + c];
-                    sum = sum + e * e;
-                }
-                vm_reg[dst] = sqrt(sum);
-            }
-            case ${VM_OP.SWIZZLE}u: {
-                // Every selected slot is read before any is written, so an in-place swizzle — which
-                // is what a broadcast is — reads the value it meant to.
-                let l0 = vm_reg[s0 + (s1 & 3u)];
-                let l1 = vm_reg[s0 + ((s1 >> 2u) & 3u)];
-                let l2 = vm_reg[s0 + ((s1 >> 4u) & 3u)];
-                let l3 = vm_reg[s0 + ((s1 >> 6u) & 3u)];
-                if (w > 0u) { vm_reg[dst] = l0; }
-                if (w > 1u) { vm_reg[dst + 1u] = l1; }
-                if (w > 2u) { vm_reg[dst + 2u] = l2; }
-                if (w > 3u) { vm_reg[dst + 3u] = l3; }
+                let e = a - b;
+                d.x = sqrt(dot(e, e));
+                lanes = 1u;
             }
 
-            case ${VM_OP.CMP_LT}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = select(0.0, 1.0, vm_reg[s0 + c] < vm_reg[s1 + c]); }
-            }
-            case ${VM_OP.CMP_LE}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = select(0.0, 1.0, vm_reg[s0 + c] <= vm_reg[s1 + c]); }
-            }
-            case ${VM_OP.CMP_GT}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = select(0.0, 1.0, vm_reg[s0 + c] > vm_reg[s1 + c]); }
-            }
-            case ${VM_OP.CMP_GE}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = select(0.0, 1.0, vm_reg[s0 + c] >= vm_reg[s1 + c]); }
-            }
-            case ${VM_OP.CMP_EQ}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = select(0.0, 1.0, vm_reg[s0 + c] == vm_reg[s1 + c]); }
-            }
-            case ${VM_OP.SELECT}u: {
-                for (var c = 0u; c < w; c = c + 1u) {
-                    vm_reg[dst + c] = select(vm_reg[s0 + c], vm_reg[s1 + c], vm_reg[s2 + c] > 0.5);
-                }
-            }
+            case ${VM_OP.CMP_LT}u: { d = select(vec4<f32>(0.0), vec4<f32>(1.0), a < b); }
+            case ${VM_OP.CMP_LE}u: { d = select(vec4<f32>(0.0), vec4<f32>(1.0), a <= b); }
+            case ${VM_OP.CMP_GT}u: { d = select(vec4<f32>(0.0), vec4<f32>(1.0), a > b); }
+            case ${VM_OP.CMP_GE}u: { d = select(vec4<f32>(0.0), vec4<f32>(1.0), a >= b); }
+            case ${VM_OP.CMP_EQ}u: { d = select(vec4<f32>(0.0), vec4<f32>(1.0), a == b); }
+            case ${VM_OP.SELECT}u: { d = select(a, b, c > vec4<f32>(0.5)); }
 
             // \`random()\` off the shared \`rnd_state\`, which has to match
             // u32_to_unit_f32(pcg_next()) in ParticleVMReference.js bit-for-bit; the parity spec
-            // holds them to it. One draw per lane, so the draw count is the width.
+            // holds them to it. One draw per lane, in lane order, so the draw count is the width.
             case ${VM_OP.RANDOM}u: {
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = random(); }
-            }
-            case ${VM_OP.CURVE}u: {
-                let v = particle_vm_sample_curve(s0, vm_reg[s1]);
-                for (var c = 0u; c < w; c = c + 1u) { vm_reg[dst + c] = v; }
+                d.x = random();
+                if (w > 1u) { d.y = random(); }
+                if (w > 2u) { d.z = random(); }
+                if (w > 3u) { d.w = random(); }
             }
+            case ${VM_OP.CURVE}u: { d = vec4<f32>(particle_vm_sample_curve(s0, b.x)); }
 
-            default: {}
+            default: { lanes = 0u; }
         }
+
+        if (lanes > 0u) { vm_reg_write(dst, d.x); }
+        if (lanes > 1u) { vm_reg_write(dst + 1u, d.y); }
+        if (lanes > 2u) { vm_reg_write(dst + 2u, d.z); }
+        if (lanes > 3u) { vm_reg_write(dst + 3u, d.w); }
     }
 }
 `;
@@ -373,4 +335,4 @@ fn particle_vm_execute(
  * The particle VM interpreter.
  * @type {CodeChunk}
  */
-export const chunk_particle_vm = CodeChunk.from(source, [chunk_random]);
+export const chunk_particle_vm = CodeChunk.from(source, [chunk_random, PARTICLE_VM_CONTEXT_STRUCT.declaration_chunk]);

package/src/shade/renderer/particles/vm/chunk_particle_vm_registers_fast.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The fast register backing for {@link ./chunk_particle_vm.js}: the VM's register file as a
+ * `var<private>` array of {@link ../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS} floats.
+ *
+ * This is the interpreter the system runs on. The array is dynamically indexed — an operand's base
+ * comes out of the instruction word — which is what keeps it in registers rather than scratch, and
+ * therefore what makes the file's size the shader's register footprint outright. Every program pays
+ * that footprint, not only the ones with a wide working set, so the slot count is a whole-system
+ * cost and not a per-effect one. See {@link ../ParticleConstants.js} for what it was measured at.
+ *
+ * The file is zero when a program starts, and the language is what says so: WGSL zero-initialises a
+ * `var<private>` declared without an initializer, once per invocation, and a fast pass runs exactly
+ * one program per invocation ({@link ../shaders/shader_particle_simulate.js},
+ * {@link ../shaders/shader_particle_emit.js}). Nothing in the compiler's output reads a slot it has
+ * not written — the graph allocator assigns a register at the instruction that defines the value — so
+ * that zero is not what makes correct programs work. It is what makes an INCORRECT program
+ * deterministic, and that matters because it is the behaviour {@link ./ParticleVMReference.js}
+ * defines and the parity spec holds the two to. The wide backing cannot offer the same guarantee and
+ * does not try; see {@link ./chunk_particle_vm_registers_wide.js}.
+ *
+ * Nothing here clears the file. A `vm_reg_clear` used to zero it in a loop on top of the
+ * initialisation above, which could only ever be a second pass over the same slots; it outlived its
+ * reason when {@link ../../../wgsl/emulator/ComputeShaderEmulator.js} learned to reset private state
+ * per dispatch, and an empty one outlived its reason with it. Removed 2026-09-06.
+ *
+ * Measured before removing, compiled to RDNA2 (gfx1030): the two zeroing passes folded into one, so
+ * the loop cost 2 instructions of 917 at unchanged VGPRs — what a compiler that sees through it
+ * charges. One pass is about 22 instructions there (893 with no zeroing, 915 with the mandatory
+ * one), which is what a driver that does not see through it charges again on every particle.
+ *
+ * A fast pass that ran more than one program per invocation — the grid-stride shape the wide passes
+ * use — would not inherit the guarantee, since the second program would start on the first's
+ * registers. That pass would zero the file itself, in the loop it needs and where its cost is
+ * visible, rather than every pass carrying a call for it.
+ *
+ * The enclosing shader includes this chunk or the wide one, never both — they define the same two
+ * symbols.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_vm_registers_fast: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_vm_registers_fast.d.ts.map

package/src/shade/renderer/particles/vm/chunk_particle_vm_registers_fast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_vm_registers_fast.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/vm/chunk_particle_vm_registers_fast.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,+CAFU,SAAS,CAahB;0BAtDuB,oCAAoC"}