@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -1,81 +1,157 @@
+import { chunk_random } from "../../shader/chunk/random/chunk_random.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.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,
-    PARTICLE_VM_REGISTER_COUNT,
 } from "../ParticleConstants.js";
-import { VM_BUILTIN, VM_OP, VM_RANDOM_MODE } from "../isa/ParticleVMISA.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
+ *
+ * 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.
+ *
+ * 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, 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:
  *
- * 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 can't be verified through the interpreter loop under the emulator, so it is
- * checked in isolation (see the parity spec + the reference known-answer test).
+ * | 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          |
+ *
+ * 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.
+ *
+ * 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. A shaped distribution is
+ * arithmetic a program writes over the draw — see ../graph/particle_graph_distributions.js.
  *
  * ## Contract
  *
- * - Register file, RNG state, kill flag and the builtin context are module-scope `var<private>`.
- *   Call `particle_vm_reset()` at the start of each particle, seed `vm_rng_state`, and populate
- *   `vm_ctx` before invoking {@link particle_vm_execute}.
- * - `particle_vm_execute(program, program_offset, instruction_count, constants, constant_offset,
- *   pool, record_base)` runs one section. Attributes are read/written as f32 bit patterns inside
- *   `pool` at `record_base + attribute_offset`.
+ * - 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 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`.
+ * - The three section parameters may be per-lane or wave-uniform; the interpreter is the same
+ *   either way, but not its cost. Simulate passes them through `subgroupBroadcastFirst` because
+ *   its waves are one program by construction (`../shaders/shader_particle_simulate.js`), and the
+ *   driver then fetches the instruction words through the scalar unit, branches the switch on a
+ *   scalar and indexes `vm_reg` through M0 without the per-lane waterfall. Emit cannot: its waves
+ *   span emitters.
  * - The `CURVE` opcode calls the external symbol `particle_vm_sample_curve(handle: u32, t: f32) ->
  *   f32`. The enclosing shader must define it (production: animation-curve backed; tests: a stub).
  */
 
-const R = PARTICLE_VM_REGISTER_COUNT;
-
 const source = /* language=wgsl */ `
-const PARTICLE_VM_REGISTER_COUNT : u32 = ${R}u;
 const PARTICLE_VM_MAX_INSTRUCTIONS : u32 = ${PARTICLE_VM_MAX_INSTRUCTIONS}u;
-const PARTICLE_VM_TWO_PI : f32 = 6.28318530717958647692;
-
-// 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>,
-}
+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;
 
-var<private> vm_reg : array<vec4<f32>, ${R}>;
-var<private> vm_rng_state : u32;
 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_COUNT; i = i + 1u) {
-        vm_reg[i] = vec4<f32>(0.0);
-    }
     vm_killed = false;
 }
 
-// PCG-RXS-M-XS-32 — must match pcg_next() in ParticleVMReference.js bit-for-bit.
-fn vm_rng_next() -> u32 {
-    let s = vm_rng_state * 747796405u + 2891336453u;
-    let shift = (s >> 28u) + 4u;
-    let word = ((s >> shift) ^ s) * 277803737u;
-    vm_rng_state = s;
-    return (word >> 22u) ^ word;
-}
-
-fn vm_rng_unit() -> f32 {
-    return f32(vm_rng_next() >> 8u) * (1.0 / 16777216.0);
-}
-
+// The lanes a builtin does not fill are the padding an over-wide read is defined to see: zero
+// behind a scalar, and behind a vector the \`w\` its window closes with.
 fn vm_load_builtin(id : u32) -> vec4<f32> {
     switch id {
         case ${VM_BUILTIN.DELTA_TIME}u: { return vec4<f32>(vm_ctx.delta_time, 0.0, 0.0, 0.0); }
@@ -90,149 +166,167 @@ fn vm_load_builtin(id : u32) -> vec4<f32> {
     }
 }
 
-fn vm_lane(v : vec4<f32>, i : u32) -> f32 {
-    switch i {
-        case 0u: { return v.x; }
-        case 1u: { return v.y; }
-        case 2u: { return v.z; }
-        default: { return v.w; }
-    }
-}
-
-fn vm_normalize_keep_w(v : vec4<f32>) -> vec4<f32> {
-    let len = length(v.xyz);
-    let inv = select(0.0, 1.0 / len, len > 0.0);
-    return vec4<f32>(v.xyz * inv, v.w);
-}
-
-fn vm_random(mode : u32) -> vec4<f32> {
-    switch mode {
-        case ${VM_RANDOM_MODE.UNIFORM}u: {
-            return vec4<f32>(vm_rng_unit(), vm_rng_unit(), vm_rng_unit(), vm_rng_unit());
-        }
-        case ${VM_RANDOM_MODE.UNIFORM_SIGNED}u: {
-            return vec4<f32>(vm_rng_unit() * 2.0 - 1.0, vm_rng_unit() * 2.0 - 1.0, vm_rng_unit() * 2.0 - 1.0, vm_rng_unit() * 2.0 - 1.0);
-        }
-        case ${VM_RANDOM_MODE.UNIT_SPHERE}u: {
-            let z = vm_rng_unit() * 2.0 - 1.0;
-            let ang = vm_rng_unit() * PARTICLE_VM_TWO_PI;
-            let r = sqrt(max(0.0, 1.0 - z * z));
-            return vec4<f32>(r * cos(ang), r * sin(ang), z, 0.0);
-        }
-        default: { // UNIT_DISK
-            let r = sqrt(vm_rng_unit());
-            let ang = vm_rng_unit() * PARTICLE_VM_TWO_PI;
-            return vec4<f32>(r * cos(ang), r * sin(ang), 0.0, 0.0);
-        }
-    }
-}
-
-// Load a vec4 attribute (f32 bits) from the record, honouring the component count.
-fn vm_load_attr(pool : ptr<storage, array<u32>, read_write>, base : u32, off : u32, comp : u32) -> vec4<f32> {
+// 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 (comp > 0u) { v.x = bitcast<f32>((*pool)[base + off]); }
-    if (comp > 1u) { v.y = bitcast<f32>((*pool)[base + off + 1u]); }
-    if (comp > 2u) { v.z = bitcast<f32>((*pool)[base + off + 2u]); }
-    if (comp > 3u) { v.w = bitcast<f32>((*pool)[base + off + 3u]); }
+    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;
 }
 
-fn vm_store_attr(pool : ptr<storage, array<u32>, read_write>, base : u32, off : u32, comp : u32, v : vec4<f32>) {
-    if (comp > 0u) { (*pool)[base + off] = bitcast<u32>(v.x); }
-    if (comp > 1u) { (*pool)[base + off + 1u] = bitcast<u32>(v.y); }
-    if (comp > 2u) { (*pool)[base + off + 2u] = bitcast<u32>(v.z); }
-    if (comp > 3u) { (*pool)[base + off + 3u] = bitcast<u32>(v.w); }
-}
-
 // Execute one program section against a particle record living in pool at record_base.
+//
+// \`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(
     program : ptr<storage, array<u32>, read>,
-    program_offset : u32,
+    code_offset : u32,
     instruction_count : u32,
-    constants : ptr<storage, array<u32>, read>,
     constant_offset : u32,
     pool : ptr<storage, array<u32>, read_write>,
     record_base : u32,
 ) {
     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 = program_offset + pc * 5u;
-        let op = (*program)[ib];
-        let dst = (*program)[ib + 1u];
-        let s0 = (*program)[ib + 2u];
-        let s1 = (*program)[ib + 3u];
-        let s2 = (*program)[ib + 4u];
+        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 have it encoded so.
+        let w = (word0 >> ${VM_WIDTH_SHIFT}u) & ${VM_WIDTH_MASK}u;
+        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: { vm_reg[dst] = vm_reg[s0]; }
+            case ${VM_OP.NOP}u: { lanes = 0u; }
+            case ${VM_OP.MOV}u: { d = a; }
             case ${VM_OP.LOAD_CONST}u: {
-                let cb = (constant_offset + s0) * 4u;
-                vm_reg[dst] = vec4<f32>(
-                    bitcast<f32>((*constants)[cb]),
-                    bitcast<f32>((*constants)[cb + 1u]),
-                    bitcast<f32>((*constants)[cb + 2u]),
-                    bitcast<f32>((*constants)[cb + 3u]),
-                );
+                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.LOAD_ATTR}u: { vm_reg[dst] = vm_load_attr(pool, record_base, s0, s1); }
-            case ${VM_OP.STORE_ATTR}u: { vm_store_attr(pool, record_base, s0, s1, vm_reg[dst]); }
-            case ${VM_OP.LOAD_BUILTIN}u: { vm_reg[dst] = vm_load_builtin(s0); }
-            case ${VM_OP.KILL}u: { if (vm_reg[dst].x > 0.0) { vm_killed = true; } }
-
-            case ${VM_OP.ADD}u: { vm_reg[dst] = vm_reg[s0] + vm_reg[s1]; }
-            case ${VM_OP.SUB}u: { vm_reg[dst] = vm_reg[s0] - vm_reg[s1]; }
-            case ${VM_OP.MUL}u: { vm_reg[dst] = vm_reg[s0] * vm_reg[s1]; }
-            case ${VM_OP.DIV}u: { vm_reg[dst] = vm_reg[s0] / vm_reg[s1]; }
-            case ${VM_OP.MAD}u: { vm_reg[dst] = vm_reg[s0] * vm_reg[s1] + vm_reg[s2]; }
-            case ${VM_OP.MIN}u: { vm_reg[dst] = min(vm_reg[s0], vm_reg[s1]); }
-            case ${VM_OP.MAX}u: { vm_reg[dst] = max(vm_reg[s0], vm_reg[s1]); }
-            case ${VM_OP.MIX}u: { vm_reg[dst] = mix(vm_reg[s0], vm_reg[s1], vm_reg[s2]); }
-            case ${VM_OP.CLAMP}u: { vm_reg[dst] = clamp(vm_reg[s0], vm_reg[s1], vm_reg[s2]); }
-            case ${VM_OP.SCALE}u: { vm_reg[dst] = vm_reg[s0] * vm_reg[s1].x; }
-
-            case ${VM_OP.NEG}u: { vm_reg[dst] = -vm_reg[s0]; }
-            case ${VM_OP.ABS}u: { vm_reg[dst] = abs(vm_reg[s0]); }
-            case ${VM_OP.FLOOR}u: { vm_reg[dst] = floor(vm_reg[s0]); }
-            case ${VM_OP.FRACT}u: { vm_reg[dst] = fract(vm_reg[s0]); }
-            case ${VM_OP.SQRT}u: { vm_reg[dst] = sqrt(vm_reg[s0]); }
-            case ${VM_OP.SIN}u: { vm_reg[dst] = sin(vm_reg[s0]); }
-            case ${VM_OP.COS}u: { vm_reg[dst] = cos(vm_reg[s0]); }
-            case ${VM_OP.EXP}u: { vm_reg[dst] = exp(vm_reg[s0]); }
-            case ${VM_OP.LOG}u: { vm_reg[dst] = log(vm_reg[s0]); }
-            case ${VM_OP.POW}u: { vm_reg[dst] = pow(vm_reg[s0], vm_reg[s1]); }
-            case ${VM_OP.STEP}u: { vm_reg[dst] = step(vm_reg[s0], vm_reg[s1]); }
-            case ${VM_OP.SMOOTHSTEP}u: { vm_reg[dst] = smoothstep(vm_reg[s0], vm_reg[s1], vm_reg[s2]); }
-
-            case ${VM_OP.DOT}u: { vm_reg[dst] = vec4<f32>(dot(vm_reg[s0].xyz, vm_reg[s1].xyz)); }
-            case ${VM_OP.CROSS}u: { vm_reg[dst] = vec4<f32>(cross(vm_reg[s0].xyz, vm_reg[s1].xyz), 0.0); }
-            case ${VM_OP.LENGTH}u: { vm_reg[dst] = vec4<f32>(length(vm_reg[s0].xyz)); }
-            case ${VM_OP.NORMALIZE}u: { vm_reg[dst] = vm_normalize_keep_w(vm_reg[s0]); }
-            case ${VM_OP.DISTANCE}u: { vm_reg[dst] = vec4<f32>(distance(vm_reg[s0].xyz, vm_reg[s1].xyz)); }
-            case ${VM_OP.SWIZZLE}u: {
-                let v = vm_reg[s0];
-                vm_reg[dst] = vec4<f32>(
-                    vm_lane(v, s1 & 3u),
-                    vm_lane(v, (s1 >> 2u) & 3u),
-                    vm_lane(v, (s1 >> 4u) & 3u),
-                    vm_lane(v, (s1 >> 6u) & 3u),
-                );
+
+            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: { 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 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(dot(a, a));
+                d = a * select(0.0, 1.0 / len, len > 0.0);
+            }
+            case ${VM_OP.DISTANCE}u: {
+                let e = a - b;
+                d.x = sqrt(dot(e, e));
+                lanes = 1u;
             }
 
-            case ${VM_OP.CMP_LT}u: { vm_reg[dst] = select(vec4<f32>(0.0), vec4<f32>(1.0), vm_reg[s0] < vm_reg[s1]); }
-            case ${VM_OP.CMP_LE}u: { vm_reg[dst] = select(vec4<f32>(0.0), vec4<f32>(1.0), vm_reg[s0] <= vm_reg[s1]); }
-            case ${VM_OP.CMP_GT}u: { vm_reg[dst] = select(vec4<f32>(0.0), vec4<f32>(1.0), vm_reg[s0] > vm_reg[s1]); }
-            case ${VM_OP.CMP_GE}u: { vm_reg[dst] = select(vec4<f32>(0.0), vec4<f32>(1.0), vm_reg[s0] >= vm_reg[s1]); }
-            case ${VM_OP.CMP_EQ}u: { vm_reg[dst] = select(vec4<f32>(0.0), vec4<f32>(1.0), vm_reg[s0] == vm_reg[s1]); }
-            case ${VM_OP.SELECT}u: { vm_reg[dst] = select(vm_reg[s0], vm_reg[s1], vm_reg[s2] > vec4<f32>(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)); }
 
-            case ${VM_OP.RANDOM}u: { vm_reg[dst] = vm_random(s0); }
-            case ${VM_OP.CURVE}u: { vm_reg[dst] = vec4<f32>(particle_vm_sample_curve(s0, vm_reg[s1].x)); }
+            // \`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, in lane order, so the draw count is the width.
+            case ${VM_OP.RANDOM}u: {
+                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); }
     }
 }
 `;
@@ -241,4 +335,4 @@ fn particle_vm_execute(
  * The particle VM interpreter.
  * @type {CodeChunk}
  */
-export const chunk_particle_vm = CodeChunk.from(source);
+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"}

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

@@ -0,0 +1,55 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_VM_FAST_REGISTER_SLOTS } from "../ParticleConstants.js";
+
+/**
+ * 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.from(/* language=wgsl */ `
+// 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, ${PARTICLE_VM_FAST_REGISTER_SLOTS}>;
+
+fn vm_reg_read(index : u32) -> f32 {
+    return vm_reg[index];
+}
+
+fn vm_reg_write(index : u32, value : f32) {
+    vm_reg[index] = value;
+}
+`);