@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/isa/ParticleVMISA.js

@@ -7,40 +7,72 @@
  *
  * ## Encoding
  *
- * Every instruction is a fixed run of {@link PARTICLE_VM_INSTRUCTION_WORDS} `u32` words:
- *
- *     [ op | width << 8, dst, s0, s1, s2 ]
- *
- * `dst` is the destination register for value-producing ops. `s0/s1/s2` are usually source register
- * indices, but some opcodes reinterpret them as immediates (constant-pool index, attribute word
- * offset + component count, curve handle, builtin id, swizzle pattern). The
- * `operands` array below documents, per opcode, what each slot means.
- *
- * Registers hold single floats. An instruction's `width` says how many consecutive registers the
- * operation spans, so a `vec3` value is three registers and `ADD` with width 3 adds three lanes.
- * Widths are what stop every value costing four registers whether or not it has four components:
- * the register file is the interpreter's dominant register cost, and roughly half the lane work in
- * a real effect was padding before this existed. A few opcodes ignore the field because their lane
- * count is fixed (see {@link VM_WIDTH}), and the reductions write a single lane whatever they read
- * (see {@link VM_DEST}).
- *
- * There is no control flow: conditionals are expressed with CMP + SELECT and destruction with KILL,
- * which keeps the interpreter a single flat `switch` inside a bounded loop — friendly to both the
- * WGSL emulator and real hardware.
+ * Every instruction is {@link PARTICLE_VM_INSTRUCTION_WORDS} `u32` words — the size of one
+ * `vec4<u32>`, so the four loads that fetch it are one 16-byte load by the time a shader compiler is
+ * done with them:
+ *
+ *     [ op | width << 8 | kinds << 16 | dst << 24,   s0,   s1,   s2 ]
+ *
+ * Word 0 packs the opcode (bits 0..7), the lane count the operation spans (8..10), the kind of each
+ * source (two bits per slot at 16..21) and the destination register (24..31). The other three words
+ * are the sources. Registers hold single floats, so a `vec3` value is three consecutive slots and an
+ * `ADD` with width 3 adds three lanes; widths are what stop every value costing four registers.
+ *
+ * ## Operands
+ *
+ * A source word means what its kind says — see {@link VM_KIND}:
+ *
+ * - `NONE`: not an operand the VM resolves — an unused slot, or a raw field the opcode reads for
+ *   itself: an attribute offset, a component count, a builtin id, a curve handle, a pool index.
+ * - `REG`: a register operand. Bits 0..7 are the first slot, bits 8..15 a swizzle — see below.
+ * - `IMM`: the word IS the `f32` bit pattern of a literal, read in every lane. A scalar or a
+ *   lane-uniform vector costs no register and no load; only a vector whose lanes differ still goes
+ *   through the pool with `LOAD_CONST`.
+ *
+ * The kinds exist so the interpreter can resolve every source the same way, before the opcode runs
+ * and without consulting a table: it reads the kind, gathers the lanes, and the opcode body sees
+ * three four-lane values whatever they came from. A kind is encoding, not an opcode mode.
+ *
+ * ## Swizzles
+ *
+ * Every register operand carries a swizzle: four two-bit lane selectors in bits 8..15, packed as
+ * {@link pack_swizzle} packs them, and stored XOR the identity pattern `.xyzw`
+ * ({@link VM_SWIZZLE_IDENTITY}). That choice is what makes a bare slot index a register operand:
+ * with a zero swizzle byte lane `c` reads slot `base + c`, the run as it lies, and `r5.xxxx` is the
+ * same word with the selectors that name lane 0 four times. Lane `c` of an operand reads slot
+ * `base + selector[c]`, so an operand reaches as far into the file as its widest selector below the
+ * instruction's width — never further, whatever the selectors above the width say.
+ *
+ * Swizzles are why there is no `SWIZZLE` opcode and no `SCALE`: a permutation or a broadcast is a
+ * `MOV` whose source is swizzled, and a vector times a scalar is `MUL v, s.xxxx`. Both were
+ * opcodes that existed to do what an operand can now say for itself, which is the direction the
+ * ISA takes whenever it can — see {@link VM_OP} for the holes they left.
+ *
+ * ## Resolution before execution
+ *
+ * The interpreter reads every source lane before it writes any destination lane. Operands may
+ * therefore overlap the destination in any way — `MOV.2 r0, r0.yx` swaps two slots in place — and
+ * there is no aliasing rule for a program to break. The reductions write one lane whatever they
+ * read (see {@link VM_DEST}); a few opcodes fix their lane count (see {@link VM_WIDTH}).
+ *
+ * There is no control flow: conditionals are `CMP` + `SELECT` and destruction is `KILL`, which
+ * keeps the interpreter a flat `switch` inside a bounded loop.
  */
 
+/** Words per instruction. Four, so an instruction is one `vec4<u32>` fetch. @type {number} */
+export const PARTICLE_VM_INSTRUCTION_WORDS = 4;
+
 /**
- * Operand slot roles, used for documentation, assembler validation and disassembly.
+ * Operand slot roles: what an opcode reads a source slot as. Used for assembler validation,
+ * disassembly and for deriving each slot's {@link VM_KIND}.
  * @enum {string}
  */
 export const VM_OPERAND = {
     /** unused slot (must be 0) */
     NONE: "none",
-    /** first register slot of an operand, in `[0, PARTICLE_VM_REGISTER_SLOTS)` */
+    /** a register operand — a slot with a swizzle, or a literal */
     REG: "reg",
-    /** destination register index */
-    DST: "dst",
-    /** constant-pool index */
+    /** constant-pool word index */
     CONST: "const",
     /** attribute word offset within the record */
     ATTR_OFFSET: "attr_offset",
@@ -50,8 +82,6 @@ export const VM_OPERAND = {
     BUILTIN: "builtin",
     /** curve handle (row index into the animation-curve table) */
     CURVE: "curve",
-    /** packed swizzle pattern: four 2-bit lane selectors, lane i in bits `[2i, 2i+2)` */
-    SWIZZLE: "swizzle",
 };
 
 /**
@@ -99,7 +129,8 @@ export const VM_BUILTIN_COMPONENTS = Object.freeze({
 });
 
 /**
- * Opcodes. Numbers are stable wire values — never renumber, only append.
+ * Opcodes. Numbers are stable wire values — never renumber, only append. 19 was `SCALE` and 45 was
+ * `SWIZZLE`; both are spelled by an operand swizzle now and the numbers stay unused.
  * @enum {number}
  */
 export const VM_OP = {
@@ -121,7 +152,6 @@ export const VM_OP = {
     MAX: 16,
     MIX: 17,
     CLAMP: 18,
-    SCALE: 19,
 
     NEG: 20,
     ABS: 21,
@@ -135,13 +165,17 @@ export const VM_OP = {
     POW: 29,
     STEP: 30,
     SMOOTHSTEP: 31,
+    RSQRT: 32,
+    TAN: 33,
+    ASIN: 34,
+    ACOS: 35,
+    ATAN2: 36,
 
     DOT: 40,
     CROSS: 41,
     LENGTH: 42,
     NORMALIZE: 43,
     DISTANCE: 44,
-    SWIZZLE: 45,
 
     CMP_LT: 50,
     CMP_LE: 51,
@@ -183,65 +217,304 @@ export const VM_DEST = {
 };
 
 /**
- * Widest an operation may be. Registers hold scalars; four is what a `vec4` value needs and what
- * the two-bit selectors in a `SWIZZLE` pattern can address.
+ * Widest an operation may be. Registers hold scalars; four is what a `vec4` value needs and what a
+ * two-bit lane selector can address.
  * @type {number}
  */
 export const VM_MAX_WIDTH = 4;
 
+// --- word 0 -----------------------------------------------------------------------------------
+
+/** Mask selecting the opcode out of word 0. @type {number} */
+export const VM_OP_MASK = 0xff;
+
+/** Bit position of the width field in word 0. @type {number} */
+export const VM_WIDTH_SHIFT = 8;
+
+/** Mask selecting the width out of word 0, once shifted down. @type {number} */
+export const VM_WIDTH_MASK = 0x7;
+
 /**
- * Bit position of the width field inside an instruction's first word.
- *
- * The word holds `op | (width << VM_WIDTH_SHIFT)`. Widths ride in the opcode's spare high bits
- * rather than a sixth instruction word: the code section is read through the same storage binding as
- * the constants and is fetched every instruction, so a 20% longer stream is the one cost the
- * interpreter pays on every single dispatch.
- *
+ * What a source word means. Wire values; never renumber.
+ * @enum {number}
+ */
+export const VM_KIND = {
+    /** not an operand: an unused slot, or a raw field the opcode reads itself */
+    NONE: 0,
+    /** a register operand: base slot in bits 0..7, swizzle in bits 8..15 */
+    REG: 1,
+    /** the `f32` bit pattern of a literal, read in every lane */
+    IMM: 2,
+};
+
+/**
+ * Bit position of the first source's kind in word 0. Source `n` has its two kind bits at
+ * `VM_KIND_SHIFT + 2n`, so the three together are bits 16..21.
  * @type {number}
  */
-export const VM_WIDTH_SHIFT = 8;
+export const VM_KIND_SHIFT = 16;
 
-/** Mask selecting the opcode out of an instruction's first word. @type {number} */
-export const VM_OP_MASK = 0xff;
+/** Bits per kind field. @type {number} */
+export const VM_KIND_BITS = 2;
 
-/** Mask selecting the width out of an instruction's first word, once shifted down. @type {number} */
-export const VM_WIDTH_MASK = 0x7;
+/** Mask selecting one kind field, once shifted down. @type {number} */
+export const VM_KIND_MASK = 0x3;
+
+/** Mask selecting all three kind fields, once shifted down by {@link VM_KIND_SHIFT}. @type {number} */
+const VM_KINDS_MASK = 0x3f;
+
+/** Bit position of the destination register in word 0. @type {number} */
+export const VM_DST_SHIFT = 24;
+
+/** Mask selecting the destination register out of word 0, once shifted down. @type {number} */
+export const VM_DST_MASK = 0xff;
 
 /**
- * Pack an opcode and its width into an instruction's first word.
+ * Pack word 0.
+ *
  * @param {number} op
  * @param {number} width lane count, `0..4`
+ * @param {number} dst destination register, `0..255`
+ * @param {number} kinds the three source kinds as one field — see {@link vm_pack_kinds}
  * @returns {number}
  */
-export function vm_encode_word0(op, width) {
-    return ((op & VM_OP_MASK) | ((width & VM_WIDTH_MASK) << VM_WIDTH_SHIFT)) >>> 0;
+export function vm_encode_word0(op, width, dst, kinds) {
+    return (
+        (op & VM_OP_MASK)
+        | ((width & VM_WIDTH_MASK) << VM_WIDTH_SHIFT)
+        | ((kinds & VM_KINDS_MASK) << VM_KIND_SHIFT)
+        | ((dst & VM_DST_MASK) << VM_DST_SHIFT)
+    ) >>> 0;
 }
 
 /**
- * @param {number} word0
- * @returns {number} opcode
+ * The three source kinds as the one field {@link vm_encode_word0} takes.
+ *
+ * @param {number} s0
+ * @param {number} s1
+ * @param {number} s2
+ * @returns {number}
  */
+export function vm_pack_kinds(s0, s1, s2) {
+    return (
+        (s0 & VM_KIND_MASK)
+        | ((s1 & VM_KIND_MASK) << VM_KIND_BITS)
+        | ((s2 & VM_KIND_MASK) << (2 * VM_KIND_BITS))
+    ) >>> 0;
+}
+
+/** @param {number} word0 @returns {number} opcode */
 export function vm_decode_op(word0) {
     return word0 & VM_OP_MASK;
 }
 
+/** @param {number} word0 @returns {number} lane count */
+export function vm_decode_width(word0) {
+    return (word0 >>> VM_WIDTH_SHIFT) & VM_WIDTH_MASK;
+}
+
+/** @param {number} word0 @returns {number} destination register */
+export function vm_decode_dst(word0) {
+    return (word0 >>> VM_DST_SHIFT) & VM_DST_MASK;
+}
+
+/** @param {number} word0 @returns {number} the three source kinds as one field */
+export function vm_decode_kinds(word0) {
+    return (word0 >>> VM_KIND_SHIFT) & VM_KINDS_MASK;
+}
+
 /**
  * @param {number} word0
- * @returns {number} lane count
+ * @param {number} slot source slot, `0..2`
+ * @returns {number} a {@link VM_KIND}
  */
-export function vm_decode_width(word0) {
-    return (word0 >> VM_WIDTH_SHIFT) & VM_WIDTH_MASK;
+export function vm_decode_kind(word0, slot) {
+    return (word0 >>> (VM_KIND_SHIFT + slot * VM_KIND_BITS)) & VM_KIND_MASK;
+}
+
+/** @returns {number} word 0 with its width replaced */
+export function vm_with_width(word0, width) {
+    return ((word0 & ~(VM_WIDTH_MASK << VM_WIDTH_SHIFT)) | ((width & VM_WIDTH_MASK) << VM_WIDTH_SHIFT)) >>> 0;
+}
+
+/** @returns {number} word 0 with its destination replaced */
+export function vm_with_dst(word0, dst) {
+    return ((word0 & ~(VM_DST_MASK << VM_DST_SHIFT)) | ((dst & VM_DST_MASK) << VM_DST_SHIFT)) >>> 0;
+}
+
+/** @returns {number} word 0 with one source's kind replaced */
+export function vm_with_kind(word0, slot, kind) {
+    const shift = VM_KIND_SHIFT + slot * VM_KIND_BITS;
+
+    return ((word0 & ~(VM_KIND_MASK << shift)) | ((kind & VM_KIND_MASK) << shift)) >>> 0;
+}
+
+// --- register operands ------------------------------------------------------------------------
+
+/**
+ * Pack a swizzle pattern from four lane selectors: selector `i` in bits `[2i, 2i+2)`, values
+ * 0=x, 1=y, 2=z, 3=w.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} w
+ * @returns {number}
+ */
+export function pack_swizzle(x, y, z, w) {
+    return (x & 3) | ((y & 3) << 2) | ((z & 3) << 4) | ((w & 3) << 6);
+}
+
+/**
+ * @param {number} pattern
+ * @param {number} lane
+ * @returns {number} the lane the pattern selects for output lane `lane`
+ */
+export function swizzle_selector(pattern, lane) {
+    return (pattern >>> (2 * lane)) & 3;
+}
+
+/** The pattern that reads a run as it lies: `.xyzw`. @type {number} */
+export const VM_SWIZZLE_IDENTITY = pack_swizzle(0, 1, 2, 3);
+
+/** The pattern that reads lane 0 in every lane: `.xxxx`. @type {number} */
+export const VM_SWIZZLE_BROADCAST = pack_swizzle(0, 0, 0, 0);
+
+/** Mask selecting the base slot out of a register operand word. @type {number} */
+export const VM_OPERAND_BASE_MASK = 0xff;
+
+/** Bit position of the swizzle byte in a register operand word. @type {number} */
+export const VM_OPERAND_SWIZZLE_SHIFT = 8;
+
+/**
+ * A register operand word: a base slot read through a pattern.
+ *
+ * The pattern is stored XOR {@link VM_SWIZZLE_IDENTITY}, so the identity is a zero byte and a bare
+ * slot index is the run at that slot. Nothing else about the word depends on that choice; read the
+ * pattern back with {@link vm_operand_pattern} rather than the bits.
+ *
+ * @param {number} base first register slot
+ * @param {number} [pattern] a packed swizzle; the run as it lies when left out
+ * @returns {number}
+ */
+export function vm_register(base, pattern = VM_SWIZZLE_IDENTITY) {
+    return ((base & VM_OPERAND_BASE_MASK) | (((pattern ^ VM_SWIZZLE_IDENTITY) & 0xff) << VM_OPERAND_SWIZZLE_SHIFT)) >>> 0;
+}
+
+/** @param {number} word a register operand @returns {number} its base slot */
+export function vm_operand_base(word) {
+    return word & VM_OPERAND_BASE_MASK;
+}
+
+/** @param {number} word a register operand @returns {number} its swizzle, as {@link pack_swizzle} packs one */
+export function vm_operand_pattern(word) {
+    return ((word >>> VM_OPERAND_SWIZZLE_SHIFT) & 0xff) ^ VM_SWIZZLE_IDENTITY;
+}
+
+/**
+ * @param {number} word a register operand
+ * @param {number} lane
+ * @returns {number} the slot lane `lane` of the operand reads
+ */
+export function vm_operand_slot(word, lane) {
+    return vm_operand_base(word) + swizzle_selector(vm_operand_pattern(word), lane);
+}
+
+/** @returns {number} the operand moved to another base, keeping its swizzle */
+export function vm_operand_with_base(word, base) {
+    return vm_register(base, vm_operand_pattern(word));
+}
+
+/**
+ * How far into the file a register operand reaches when `lanes` lanes of it are read: one past the
+ * widest selector among them. The selectors above `lanes` are never read and do not count.
+ *
+ * @param {number} word a register operand
+ * @param {number} lanes how many lanes the instruction reads of it
+ * @returns {number}
+ */
+export function vm_operand_span(word, lanes) {
+    const pattern = vm_operand_pattern(word);
+
+    let span = 1;
+
+    for (let lane = 0; lane < lanes; lane++) {
+        span = Math.max(span, swizzle_selector(pattern, lane) + 1);
+    }
+
+    return span;
 }
 
 /**
- * The lane count an opcode actually operates on, given the width its instruction carries.
+ * The canonical spelling of a register operand read at `lanes` lanes: the base is the lowest slot
+ * any lane reads, and selectors above the lanes read are the identity, since they name nothing. So
+ * `r0.yz` is `r1`, `r0.zy` is `r1.yx`, and a broadcast of lane 3 is the run at lane 3 — one
+ * spelling per meaning, which is what lets two instructions be compared word for word.
  *
- * Opcodes whose width is fixed ignore the field entirely, so a malformed program cannot talk a
- * `CROSS` into reading two lanes.
+ * @param {number} word a register operand
+ * @param {number} lanes how many lanes the instruction reads of it
+ * @returns {number}
+ */
+export function vm_canonical_register(word, lanes) {
+    const pattern = vm_operand_pattern(word);
+
+    let lowest = lanes > 0 ? 3 : 0;
+
+    for (let lane = 0; lane < lanes; lane++) {
+        lowest = Math.min(lowest, swizzle_selector(pattern, lane));
+    }
+
+    let canonical = 0;
+
+    for (let lane = 0; lane < VM_MAX_WIDTH; lane++) {
+        const selector = lane < lanes ? swizzle_selector(pattern, lane) - lowest : lane;
+
+        canonical |= selector << (2 * lane);
+    }
+
+    return vm_register(vm_operand_base(word) + lowest, canonical);
+}
+
+// --- immediates -------------------------------------------------------------------------------
+
+/** Scratch for converting between a literal and its bits. */
+const F32_SCRATCH = new Float32Array(1);
+
+/** @type {Uint32Array} the same four bytes */
+const U32_SCRATCH = new Uint32Array(F32_SCRATCH.buffer);
+
+/** @param {number} value @returns {number} the `f32` bit pattern the value rounds to */
+export function vm_f32_bits(value) {
+    F32_SCRATCH[0] = value;
+
+    return U32_SCRATCH[0];
+}
+
+/** @param {number} bits @returns {number} the `f32` those bits are */
+export function vm_f32_value(bits) {
+    U32_SCRATCH[0] = bits;
+
+    return F32_SCRATCH[0];
+}
+
+/**
+ * A literal source operand, as `InstructionStream.emit` takes one in a source slot.
+ *
+ * @param {number} value
+ * @returns {{kind: number, word: number}}
+ */
+export function vm_immediate(value) {
+    return { kind: VM_KIND.IMM, word: vm_f32_bits(value) };
+}
+
+// --- the opcode table -------------------------------------------------------------------------
+
+/**
+ * Widths are read out of the opcode's metadata; see {@link VM_ISA}.
  *
  * @param {number} op
  * @param {number} width the instruction's width field
- * @returns {number}
+ * @returns {number} the lane count the opcode actually operates on
  */
 export function vm_operation_width(op, width) {
     const meta = VM_ISA.get(op);
@@ -278,23 +551,22 @@ export function vm_dest_width(op, width) {
     }
 }
 
-const D = VM_OPERAND.DST;
 const R = VM_OPERAND.REG;
 const _ = VM_OPERAND.NONE;
 
 /**
- * Per-opcode metadata: mnemonic + the role of each of the three operand slots `[s0, s1, s2]`.
+ * Per-opcode metadata: mnemonic, whether it writes a destination, and the role of each source slot.
  *
  * Keyed by opcode number. Used by the assembler for validation/disassembly and by the parity
  * meta-test to enforce that every opcode is handled by both executors.
- * @type {Map<number, {name: string, dst: boolean, operands: [string, string, string]}>}
+ * @type {Map<number, {name: string, dst: boolean, operands: [string, string, string], width: string, dest: string, default_width: number, min_width: number, scalar_operands: number[]}>}
  */
 export const VM_ISA = new Map();
 
 /**
  * @param {number} op
  * @param {string} name
- * @param {boolean} dst
+ * @param {boolean} dst whether the opcode writes a destination register
  * @param {string} [s0]
  * @param {string} [s1]
  * @param {string} [s2]
@@ -311,7 +583,7 @@ function def(op, name, dst, s0 = _, s1 = _, s2 = _, options = {}) {
     }
 
     const width = options.width ?? VM_WIDTH.VARIABLE;
-    const dest = options.dest ?? (dst ? VM_DEST.WIDTH : VM_DEST.NONE);
+    const dest = dst ? (options.dest ?? VM_DEST.WIDTH) : VM_DEST.NONE;
 
     let default_width = options.default_width ?? VM_MAX_WIDTH;
 
@@ -340,12 +612,12 @@ def(VM_OP.NOP, "NOP", false, _, _, _, { width: VM_WIDTH.NONE });
 def(VM_OP.MOV, "MOV", true, R);
 def(VM_OP.LOAD_CONST, "LOAD_CONST", true, VM_OPERAND.CONST);
 def(VM_OP.LOAD_ATTR, "LOAD_ATTR", true, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP);
-// dst slot holds the SOURCE register; the width must equal the component count, since a store
-// cannot write lanes the register does not hold.
-def(VM_OP.STORE_ATTR, "STORE_ATTR", true, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP, _, { dest: VM_DEST.NONE });
+// The value to store is an ordinary source — a register run or a literal — and the width must equal
+// the component count, since a store cannot write lanes the value does not have.
+def(VM_OP.STORE_ATTR, "STORE_ATTR", false, R, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP);
 def(VM_OP.LOAD_BUILTIN, "LOAD_BUILTIN", true, VM_OPERAND.BUILTIN);
-// dst slot holds the CONDITION register, read as a single lane
-def(VM_OP.KILL, "KILL", true, _, _, _, { width: VM_WIDTH.ONE, dest: VM_DEST.NONE });
+// The condition is one lane of an ordinary source.
+def(VM_OP.KILL, "KILL", false, R, _, _, { width: VM_WIDTH.ONE });
 
 def(VM_OP.ADD, "ADD", true, R, R);
 def(VM_OP.SUB, "SUB", true, R, R);
@@ -356,7 +628,6 @@ def(VM_OP.MIN, "MIN", true, R, R);
 def(VM_OP.MAX, "MAX", true, R, R);
 def(VM_OP.MIX, "MIX", true, R, R, R);
 def(VM_OP.CLAMP, "CLAMP", true, R, R, R);
-def(VM_OP.SCALE, "SCALE", true, R, R, _, { scalar_operands: [1] });
 
 def(VM_OP.NEG, "NEG", true, R);
 def(VM_OP.ABS, "ABS", true, R);
@@ -370,18 +641,23 @@ def(VM_OP.LOG, "LOG", true, R);
 def(VM_OP.POW, "POW", true, R, R);
 def(VM_OP.STEP, "STEP", true, R, R);
 def(VM_OP.SMOOTHSTEP, "SMOOTHSTEP", true, R, R, R);
-
-// The reductions read `width` lanes and write one. They used to read `.xyz` and broadcast the
-// result over all four lanes; the broadcast is now the compiler's to emit where a wider consumer
-// actually needs it, which is the whole point of tracking widths.
+def(VM_OP.RSQRT, "RSQRT", true, R);
+def(VM_OP.TAN, "TAN", true, R);
+def(VM_OP.ASIN, "ASIN", true, R);
+def(VM_OP.ACOS, "ACOS", true, R);
+// `atan2(y, x)`: the angle of the point, with the quadrant the signs put it in — so the first
+// source is the one a plot puts on the vertical axis, as it is in every shading language.
+def(VM_OP.ATAN2, "ATAN2", true, R, R);
+
+// The reductions read `width` lanes and write one. Whatever wants the result wider reads it through
+// an `.xxxx` swizzle, which is what tracking widths is for.
 def(VM_OP.DOT, "DOT", true, R, R, _, { dest: VM_DEST.ONE, default_width: 3 });
-// A cross product is three lanes wide. It may be asked for a fourth, which it writes as zero — the
-// `w` the opcode used to append — but never for fewer, so `MIN_WIDTH` is a floor rather than a fix.
+// A cross product is three lanes wide. It may be asked for a fourth, which it writes as zero, but
+// never for fewer, so `min_width` is a floor rather than a fix.
 def(VM_OP.CROSS, "CROSS", true, R, R, _, { default_width: 3, min_width: 3 });
 def(VM_OP.LENGTH, "LENGTH", true, R, _, _, { dest: VM_DEST.ONE, default_width: 3 });
 def(VM_OP.NORMALIZE, "NORMALIZE", true, R, _, _, { default_width: 3 });
 def(VM_OP.DISTANCE, "DISTANCE", true, R, R, _, { dest: VM_DEST.ONE, default_width: 3 });
-def(VM_OP.SWIZZLE, "SWIZZLE", true, R, VM_OPERAND.SWIZZLE);
 
 def(VM_OP.CMP_LT, "CMP_LT", true, R, R);
 def(VM_OP.CMP_LE, "CMP_LE", true, R, R);
@@ -390,108 +666,201 @@ def(VM_OP.CMP_GE, "CMP_GE", true, R, R);
 def(VM_OP.CMP_EQ, "CMP_EQ", true, R, R);
 def(VM_OP.SELECT, "SELECT", true, R, R, R);
 
-// One independent uniform draw in `[0, 1)` per lane, and nothing else. `RANDOM` used to carry a
-// distribution mode — signed, unit sphere, unit disk — and every one of those is arithmetic over
-// this draw that a program can write for itself: with its constants hoisted, a unit sphere is ten
-// instructions and a unit disk seven. There is no principled place to stop adding distributions, so
-// the ISA does not start. Which means the draw count is now plainly `width`, rather than a per-mode
-// rule a reader has to look up.
+// One independent uniform draw in `[0, 1)` per lane, and nothing else: a shaped distribution is
+// arithmetic a program writes over this draw — see ../graph/particle_graph_distributions.js.
 def(VM_OP.RANDOM, "RANDOM", true);
 // `t` is one lane; the sampled value fills the destination's width.
 def(VM_OP.CURVE, "CURVE", true, VM_OPERAND.CURVE, R, _, { scalar_operands: [1] });
 
+// --- packing an instruction ---------------------------------------------------------------------
+
 /**
+ * The four words of an instruction, with every register operand in its canonical spelling.
+ *
+ * Both the assembler's `InstructionStream.emit` and the assembly parser build instructions here, so
+ * the one encoding rule that is a choice rather than a fact — how a swizzle is spelled — is made in
+ * one place: selectors above the lanes an operand is read at are the identity, and a run of
+ * consecutive selectors is the identity at a higher base. Two instructions that mean the same thing
+ * then have the same words, which is what lets the optimizer compare them.
+ *
  * @param {number} op
- * @returns {string} mnemonic, or `OP_<n>` if unknown
+ * @param {number} width lane count, `0..4`
+ * @param {number} dst destination register
+ * @param {number[]} kinds a {@link VM_KIND} per source slot
+ * @param {number[]} sources the three source words
+ * @returns {number[]}
  */
-export function vm_op_name(op) {
+export function vm_pack_instruction(op, width, dst, kinds, sources) {
     const meta = VM_ISA.get(op);
-    return meta === undefined ? `OP_${op}` : meta.name;
+    const operation_width = vm_operation_width(op, width);
+    const words = [vm_encode_word0(op, width, dst, vm_pack_kinds(kinds[0], kinds[1], kinds[2])), 0, 0, 0];
+
+    for (let slot = 0; slot < 3; slot++) {
+        const word = sources[slot] >>> 0;
+
+        words[1 + slot] = kinds[slot] === VM_KIND.REG && meta !== undefined
+            ? vm_canonical_register(word, meta.scalar_operands.includes(slot) ? 1 : operation_width)
+            : word;
+    }
+
+    return words;
 }
 
 /**
- * Pack a swizzle pattern from four lane selectors into the 8-bit form used by the `SWIZZLE` opcode.
- * Selector values: 0=x, 1=y, 2=z, 3=w.
- * @param {number} x
- * @param {number} y
- * @param {number} z
- * @param {number} w
- * @returns {number}
+ * An encoded instruction, re-spelled canonically — what a pass wants after it has moved an operand.
+ *
+ * @param {ArrayLike<number>} words the four words of a single instruction
+ * @returns {number[]}
  */
-export function pack_swizzle(x, y, z, w) {
-    return (x & 3) | ((y & 3) << 2) | ((z & 3) << 4) | ((w & 3) << 6);
+export function vm_repack_instruction(words) {
+    const word0 = words[0];
+
+    return vm_pack_instruction(
+        vm_decode_op(word0),
+        vm_decode_width(word0),
+        vm_decode_dst(word0),
+        [vm_decode_kind(word0, 0), vm_decode_kind(word0, 1), vm_decode_kind(word0, 2)],
+        [words[1], words[2], words[3]]
+    );
 }
 
+// --- reading an instruction ---------------------------------------------------------------------
+
+/**
+ * @typedef {object} ParticleVMOperand
+ * @property {number} slot source slot, `0..2`
+ * @property {number} kind a {@link VM_KIND}, never `NONE`
+ * @property {number} word the source word as encoded
+ * @property {number} lanes how many lanes the instruction reads of it: the operation's width, or one
+ *   for a slot the ISA marks scalar
+ * @property {number} span register slots the operand reaches from its base, for a register; `0` for a
+ *   literal
+ */
+
 /**
- * How many registers a `SWIZZLE` pattern reaches into, counting from the source's base: one past
- * the largest lane any of its four selectors names.
+ * Visit every source operand of an instruction — every slot whose kind is not `NONE` — with how
+ * many lanes the opcode reads of it and how far into the file it reaches.
  *
- * A swizzle's source span has nothing to do with the instruction's width — a four-lane broadcast
- * reads one register and a three-lane reversal reads four — so it is the only operand whose extent
- * has to be read out of the pattern itself.
+ * The rules for the reach are not uniform and live here rather than in each caller: a source is
+ * read as wide as the operation runs unless the ISA marks that slot scalar, and a register operand
+ * reaches as far as its widest selector among the lanes read.
  *
- * @param {number} pattern
- * @returns {number}
+ * @param {ArrayLike<number>} words an instruction stream
+ * @param {number} base index of the instruction's first word
+ * @param {function(ParticleVMOperand):void} visit the one object is reused between calls; copy it
+ *   to keep it
  */
-export function swizzle_span(pattern) {
-    let span = 1;
+export function vm_visit_operands(words, base, visit) {
+    const word0 = words[base];
+    const op = vm_decode_op(word0);
+    const meta = VM_ISA.get(op);
 
-    for (let lane = 0; lane < 4; lane++) {
-        const selector = (pattern >> (2 * lane)) & 3;
+    if (meta === undefined) {
+        return;
+    }
+
+    const operation_width = vm_operation_width(op, vm_decode_width(word0));
+    const operand = { slot: 0, kind: 0, word: 0, lanes: 0, span: 0 };
+
+    for (let slot = 0; slot < 3; slot++) {
+        const kind = vm_decode_kind(word0, slot);
 
-        if (selector + 1 > span) {
-            span = selector + 1;
+        if (kind === VM_KIND.NONE) {
+            continue;
         }
-    }
 
-    return span;
+        const word = words[base + 1 + slot];
+        const lanes = meta.scalar_operands.includes(slot) ? 1 : operation_width;
+
+        operand.slot = slot;
+        operand.kind = kind;
+        operand.word = word;
+        operand.lanes = lanes;
+        operand.span = kind === VM_KIND.REG ? vm_operand_span(word, lanes) : 0;
+        visit(operand);
+    }
 }
 
 /**
- * Visit every register operand of an instruction as the slot it starts at and how many consecutive
- * slots it reaches from there.
- *
- * Registers hold single floats, so an operand's base index says nothing on its own about how much
- * of the file it touches: a `vec3` at r0 occupies r0, r1 and r2. Anyone sizing a register file or
- * bounds-checking one needs the reach rather than the base, and the rules for it are not uniform —
- * so they live here, in one place, instead of being re-derived by each caller until they disagree:
- *
- * - a destination reaches as far as the opcode writes, which for the reductions is one lane;
- * - a source reaches as far as the operation runs, unless the ISA marks that slot scalar;
- * - a `SWIZZLE` source reaches as far as its pattern names, which the width cannot tell you;
- * - the source `STORE_ATTR` and `KILL` keep in the destination slot reaches as far as they read.
+ * Visit every run of the register file an instruction touches, as the slot it starts at and how
+ * many consecutive slots it reaches: the destination as far as the opcode writes, and each register
+ * source as far as its selectors read. What anyone sizing or bounds-checking the file wants; a
+ * literal is not a run of the file and is not visited.
  *
  * @param {ArrayLike<number>} words an instruction stream
  * @param {number} base index of the instruction's first word
- * @param {function(number, number):void} visit called `(slot, span)` per register operand
+ * @param {function(number, number):void} visit called `(slot, span)` per run
  */
-export function vm_visit_register_operands(words, base, visit) {
+export function vm_visit_register_runs(words, base, visit) {
     const word0 = words[base];
     const op = vm_decode_op(word0);
-    const meta = VM_ISA.get(op);
+    const dest = vm_dest_width(op, vm_decode_width(word0));
 
-    if (meta === undefined) {
-        return;
+    if (dest > 0) {
+        visit(vm_decode_dst(word0), dest);
     }
 
-    const width = vm_decode_width(word0);
-    const operation_width = vm_operation_width(op, width);
+    vm_visit_operands(words, base, (operand) => {
+        if (operand.kind === VM_KIND.REG) {
+            visit(vm_operand_base(operand.word), operand.span);
+        }
+    });
+}
 
-    if (meta.dst) {
-        // For value-producing ops this is the destination; for STORE_ATTR and KILL it is a source
-        // living in the dst slot, and its span is what the instruction READS, not what it writes.
-        visit(words[base + 1], meta.dest === VM_DEST.NONE ? operation_width : vm_dest_width(op, width));
+/**
+ * Whether the kind bits of an instruction agree with what its opcode reads: a register-role slot
+ * carries a register or a literal, every other slot carries nothing. Both the assembler and
+ * `ParticleProgram.validate` ask here rather than each restating the rule.
+ *
+ * @param {ArrayLike<number>} words an instruction stream
+ * @param {number} base index of the instruction's first word
+ * @returns {string|null} what is wrong, or `null` when nothing is
+ */
+export function vm_kinds_problem(words, base) {
+    const word0 = words[base];
+    const meta = VM_ISA.get(vm_decode_op(word0));
+
+    if (meta === undefined) {
+        return null;
     }
 
     for (let slot = 0; slot < 3; slot++) {
-        if (meta.operands[slot] !== VM_OPERAND.REG) {
-            continue;
+        const kind = vm_decode_kind(word0, slot);
+        const role = meta.operands[slot];
+
+        if (kind > VM_KIND.IMM) {
+            return `s${slot} has operand kind ${kind}, which the ISA does not define`;
+        }
+
+        if (role === VM_OPERAND.REG && kind === VM_KIND.NONE) {
+            return `s${slot} of ${meta.name} must be a register or a literal`;
         }
 
-        const span = op === VM_OP.SWIZZLE
-            ? swizzle_span(words[base + 3])
-            : (meta.scalar_operands.includes(slot) ? 1 : operation_width);
+        if (role !== VM_OPERAND.REG && kind !== VM_KIND.NONE) {
+            return `s${slot} of ${meta.name} is ${role === VM_OPERAND.NONE ? "unused" : `a ${role}`} and has no kind`;
+        }
+    }
+
+    return null;
+}
 
-        visit(words[base + 2 + slot], span);
+/**
+ * The kinds an opcode's sources carry when every register-role slot holds a register: the default
+ * an assembler starts from, before any literal is marked.
+ *
+ * @param {number} op
+ * @returns {number} a kinds field for {@link vm_encode_word0}
+ */
+export function vm_register_kinds(op) {
+    const meta = VM_ISA.get(op);
+
+    if (meta === undefined) {
+        return 0;
     }
+
+    return vm_pack_kinds(
+        meta.operands[0] === R ? VM_KIND.REG : VM_KIND.NONE,
+        meta.operands[1] === R ? VM_KIND.REG : VM_KIND.NONE,
+        meta.operands[2] === R ? VM_KIND.REG : VM_KIND.NONE
+    );
 }