@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -3,49 +3,81 @@ import {
     PARTICLE_RECORD_WORD_COUNT,
     PARTICLE_VM_INSTRUCTION_WORDS,
     PARTICLE_VM_MAX_INSTRUCTIONS,
-    PARTICLE_VM_REGISTER_COUNT,
+    PARTICLE_VM_REGISTER_SLOTS,
 } from "../ParticleConstants.js";
-import { VM_ISA, VM_OP } from "./ParticleVMISA.js";
+import {
+    swizzle_span,
+    VM_DEST,
+    VM_ISA,
+    VM_MAX_WIDTH,
+    VM_OP,
+    VM_OPERAND,
+    VM_WIDTH,
+    vm_decode_op,
+    vm_decode_width,
+    vm_dest_width,
+    vm_operation_width,
+} from "./ParticleVMISA.js";
 
 /**
- * A compiled particle program: two instruction streams (SPAWN and UPDATE) plus a shared constant
+ * A compiled particle program: two instruction streams (INIT and UPDATE) plus a shared constant
  * pool. This is the value the node compiler emits and the runtime packs into the program arena.
  *
  * Instruction streams are flat `Uint32Array`s, {@link PARTICLE_VM_INSTRUCTION_WORDS} words per
  * instruction. The constant pool is a flat `Float32Array`, 4 floats (one `vec4f`) per constant.
  */
 export class ParticleProgram {
+
+    /**
+     * Instruction words for the INIT section.
+     * @type {Uint32Array}
+     */
+    init;
+
+    /**
+     * Instruction words for the UPDATE section.
+     * @type {Uint32Array}
+     */
+    update;
+
+    /**
+     * Constant pool, 4 floats (one `vec4f`) per entry.
+     * @type {Float32Array}
+     */
+    constants;
+
+    /**
+     * Number of vec4 registers the program needs.
+     * @type {number}
+     */
+    register_count;
+
     /**
      * @param {object} params
-     * @param {Uint32Array} params.spawn instruction words for the SPAWN section
+     * @param {Uint32Array} params.init instruction words for the INIT section
      * @param {Uint32Array} params.update instruction words for the UPDATE section
-     * @param {Float32Array} params.constants constant pool, 4 floats per entry
-     * @param {number} params.register_count number of vec4 registers the program needs
+     * @param {Float32Array} params.constants constant pool, one float per word
+     * @param {number} params.register_count register slots the program needs
      */
-    constructor({ spawn, update, constants, register_count }) {
-        assert.ok(spawn instanceof Uint32Array, "spawn must be a Uint32Array");
+    constructor({ init, update, constants, register_count }) {
+        assert.ok(init instanceof Uint32Array, "init must be a Uint32Array");
         assert.ok(update instanceof Uint32Array, "update must be a Uint32Array");
         assert.ok(constants instanceof Float32Array, "constants must be a Float32Array");
         assert.isNonNegativeInteger(register_count, "register_count");
 
-        assert.equal(spawn.length % PARTICLE_VM_INSTRUCTION_WORDS, 0, "spawn length must be a multiple of the instruction width");
+        assert.equal(init.length % PARTICLE_VM_INSTRUCTION_WORDS, 0, "init length must be a multiple of the instruction width");
         assert.equal(update.length % PARTICLE_VM_INSTRUCTION_WORDS, 0, "update length must be a multiple of the instruction width");
-        assert.equal(constants.length % 4, 0, "constants length must be a multiple of 4");
-        assert.lessThanOrEqual(register_count, PARTICLE_VM_REGISTER_COUNT, "register_count exceeds the VM register file size");
+        assert.lessThanOrEqual(register_count, PARTICLE_VM_REGISTER_SLOTS, "register_count exceeds the VM register file size");
 
-        /** @type {Uint32Array} */
-        this.spawn = spawn;
-        /** @type {Uint32Array} */
+        this.init = init;
         this.update = update;
-        /** @type {Float32Array} */
         this.constants = constants;
-        /** @type {number} */
         this.register_count = register_count;
     }
 
-    /** @returns {number} number of instructions in the SPAWN section */
-    get spawn_instruction_count() {
-        return this.spawn.length / PARTICLE_VM_INSTRUCTION_WORDS;
+    /** @returns {number} number of instructions in the INIT section */
+    get init_instruction_count() {
+        return this.init.length / PARTICLE_VM_INSTRUCTION_WORDS;
     }
 
     /** @returns {number} number of instructions in the UPDATE section */
@@ -53,9 +85,9 @@ export class ParticleProgram {
         return this.update.length / PARTICLE_VM_INSTRUCTION_WORDS;
     }
 
-    /** @returns {number} number of vec4 constants */
-    get constant_count() {
-        return this.constants.length / 4;
+    /** @returns {number} words in the constant pool — it is addressed by word, not by `vec4` */
+    get constant_word_count() {
+        return this.constants.length;
     }
 
     /**
@@ -64,9 +96,9 @@ export class ParticleProgram {
      * ingestion, not the hot path.
      */
     validate() {
-        validate_stream(this.spawn, "spawn", this.constant_count, this.register_count);
-        validate_stream(this.update, "update", this.constant_count, this.register_count);
-        assert.lessThanOrEqual(this.spawn_instruction_count, PARTICLE_VM_MAX_INSTRUCTIONS, "spawn exceeds instruction budget");
+        validate_stream(this.init, "init", this.constant_word_count, this.register_count);
+        validate_stream(this.update, "update", this.constant_word_count, this.register_count);
+        assert.lessThanOrEqual(this.init_instruction_count, PARTICLE_VM_MAX_INSTRUCTIONS, "init exceeds instruction budget");
         assert.lessThanOrEqual(this.update_instruction_count, PARTICLE_VM_MAX_INSTRUCTIONS, "update exceeds instruction budget");
     }
 }
@@ -74,15 +106,17 @@ export class ParticleProgram {
 /**
  * @param {Uint32Array} words
  * @param {string} label
- * @param {number} constant_count
+ * @param {number} constant_word_count
  * @param {number} register_count
  */
-function validate_stream(words, label, constant_count, register_count) {
+function validate_stream(words, label, constant_word_count, register_count) {
     const instruction_count = words.length / PARTICLE_VM_INSTRUCTION_WORDS;
 
     for (let i = 0; i < instruction_count; i++) {
         const base = i * PARTICLE_VM_INSTRUCTION_WORDS;
-        const op = words[base];
+        const word0 = words[base];
+        const op = vm_decode_op(word0);
+        const width = vm_decode_width(word0);
         const meta = VM_ISA.get(op);
 
         if (meta === undefined) {
@@ -92,21 +126,82 @@ function validate_stream(words, label, constant_count, register_count) {
         const dst = words[base + 1];
         const s0 = words[base + 2];
 
-        // Destination (and KILL/STORE_ATTR source, which live in the dst slot) must be a valid register.
+        if (meta.width !== VM_WIDTH.NONE) {
+            assert.greaterThanOrEqual(
+                width,
+                meta.min_width,
+                `${label}[${i}] (${meta.name}): width must be >= ${meta.min_width}`
+            );
+            assert.lessThanOrEqual(width, VM_MAX_WIDTH, `${label}[${i}] (${meta.name}): width must be <= ${VM_MAX_WIDTH}`);
+        }
+
+        const operation_width = vm_operation_width(op, width);
+
+        // Every register operand names a RUN of slots, and a run that overshoots the file reads
+        // whatever the next value holds rather than failing — so the bound is on its end.
+        /** @type {Array<{label: string, base: number, span: number}>} */
+        const ranges = [];
+
         if (meta.dst) {
-            assert.lessThan(dst, register_count, `${label}[${i}] (${meta.name}): dst register ${dst} out of range`);
+            // Destination for value-producing ops; for STORE_ATTR/KILL the dst slot holds a SOURCE,
+            // and its span is what the instruction reads.
+            const span = meta.dest === VM_DEST.NONE ? operation_width : vm_dest_width(op, width);
+            ranges.push({ label: "dst", base: dst, span });
         }
 
-        // Register-valued source slots must be in range.
         const operands = meta.operands;
         for (let s = 0; s < 3; s++) {
-            if (operands[s] === "reg") {
-                assert.lessThan(words[base + 2 + s], register_count, `${label}[${i}] (${meta.name}): src register out of range`);
+            if (operands[s] !== VM_OPERAND.REG) {
+                continue;
+            }
+
+            // A swizzle reaches into its source by the lanes its pattern names, which bear no
+            // relation to the destination's width — a four-lane broadcast reads one slot, and a
+            // three-lane reversal reads four.
+            const span = op === VM_OP.SWIZZLE
+                ? swizzle_span(words[base + 3])
+                : (meta.scalar_operands.includes(s) ? 1 : operation_width);
+
+            ranges.push({ label: `s${s}`, base: words[base + 2 + s], span });
+        }
+
+        for (const range of ranges) {
+            assert.lessThanOrEqual(
+                range.base + range.span,
+                register_count,
+                `${label}[${i}] (${meta.name}): ${range.label} range `
+                + `[${range.base}, ${range.base + range.span}) exceeds the ${register_count}-slot register file`
+            );
+        }
+
+        // Two operands may name the same slots or none of the same ones, but not overlap partially.
+        // Every executor reads slot `c` of its sources to write slot `c` of its destination, so an
+        // exact alias is fine — the allocator relies on it to let a result reuse a consumed input —
+        // and a shifted one would read slots the same instruction has already overwritten.
+        for (let a = 0; a < ranges.length; a++) {
+            for (let b = a + 1; b < ranges.length; b++) {
+                const x = ranges[a];
+                const y = ranges[b];
+                const overlaps = x.base < y.base + y.span && y.base < x.base + x.span;
+
+                if (overlaps && x.base !== y.base) {
+                    throw new Error(
+                        `${label}[${i}] (${meta.name}): ${x.label} range [${x.base}, ${x.base + x.span}) and `
+                        + `${y.label} range [${y.base}, ${y.base + y.span}) overlap partially; operands must name `
+                        + `the same slots or disjoint ones`
+                    );
+                }
             }
         }
 
         if (op === VM_OP.LOAD_CONST) {
-            assert.lessThan(s0, constant_count, `${label}[${i}] (LOAD_CONST): constant index ${s0} out of range`);
+            // The load reads one word per lane, so the whole run has to be inside the pool.
+            assert.lessThanOrEqual(
+                s0 + operation_width,
+                constant_word_count,
+                `${label}[${i}] (LOAD_CONST): words [${s0}, ${s0 + operation_width}) exceed the `
+                + `${constant_word_count}-word constant pool`
+            );
         }
 
         // Attribute accesses must stay inside one record. An out-of-range offset is NOT caught by
@@ -123,6 +218,16 @@ function validate_stream(words, label, constant_count, register_count) {
                 PARTICLE_RECORD_WORD_COUNT,
                 `${label}[${i}] (${name}): attribute access [${offset}, ${offset + components}) exceeds the ${PARTICLE_RECORD_WORD_COUNT}-word record`
             );
+
+            // A store writes one record word per lane, so it cannot be asked for more words than
+            // the register holds — the extra ones would come out of the next value.
+            if (op === VM_OP.STORE_ATTR) {
+                assert.equal(
+                    width,
+                    components,
+                    `${label}[${i}] (STORE_ATTR): width ${width} must equal the component count ${components}`
+                );
+            }
         }
     }
 }

package/src/shade/renderer/particles/isa/ParticleVMISA.d.ts

@@ -1,3 +1,38 @@
+/**
+ * Pack an opcode and its width into an instruction's first word.
+ * @param {number} op
+ * @param {number} width lane count, `0..4`
+ * @returns {number}
+ */
+export function vm_encode_word0(op: number, width: number): number;
+/**
+ * @param {number} word0
+ * @returns {number} opcode
+ */
+export function vm_decode_op(word0: number): number;
+/**
+ * @param {number} word0
+ * @returns {number} lane count
+ */
+export function vm_decode_width(word0: number): number;
+/**
+ * The lane count an opcode actually operates on, given the width its instruction carries.
+ *
+ * Opcodes whose width is fixed ignore the field entirely, so a malformed program cannot talk a
+ * `CROSS` into reading two lanes.
+ *
+ * @param {number} op
+ * @param {number} width the instruction's width field
+ * @returns {number}
+ */
+export function vm_operation_width(op: number, width: number): number;
+/**
+ * How many lanes an instruction writes to its destination register.
+ * @param {number} op
+ * @param {number} width the instruction's width field
+ * @returns {number}
+ */
+export function vm_dest_width(op: number, width: number): number;
 /**
  * @param {number} op
  * @returns {string} mnemonic, or `OP_<n>` if unknown
@@ -13,6 +48,37 @@ export function vm_op_name(op: number): string;
  * @returns {number}
  */
 export function pack_swizzle(x: number, y: number, z: number, w: number): number;
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @param {number} pattern
+ * @returns {number}
+ */
+export function swizzle_span(pattern: number): number;
+/**
+ * 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.
+ *
+ * @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
+ */
+export function vm_visit_register_operands(words: ArrayLike<number>, base: number, visit: (arg0: number, arg1: number) => void): void;
 /**
  * Operand slot roles, used for documentation, assembler validation and disassembly.
  */
@@ -26,7 +92,6 @@ export namespace VM_OPERAND {
     let COMP: string;
     let BUILTIN: string;
     let CURVE: string;
-    let RANDOM_MODE: string;
     let SWIZZLE: string;
 }
 /**
@@ -44,15 +109,15 @@ export namespace VM_BUILTIN {
     let TIME: number;
 }
 /**
- * Random distribution modes for the `RANDOM` opcode.
+ * How many lanes each builtin fills. The lanes past that read zero when a load is wider — see
+ * `vm_load_builtin` in {@link ../vm/chunk_particle_vm.js} — so this is a builtin's type as far as
+ * a program is concerned, and it is what types a `builtin` node in a graph.
+ *
+ * @type {Object<number, number>}
  */
-export type VM_RANDOM_MODE = number;
-export namespace VM_RANDOM_MODE {
-    let UNIFORM: number;
-    let UNIFORM_SIGNED: number;
-    let UNIT_SPHERE: number;
-    let UNIT_DISK: number;
-}
+export const VM_BUILTIN_COMPONENTS: {
+    [x: number]: number;
+};
 /**
  * Opcodes. Numbers are stable wire values — never renumber, only append.
  */
@@ -105,6 +170,49 @@ export namespace VM_OP {
     let CURVE_1: number;
     export { CURVE_1 as CURVE };
 }
+/**
+ * How an opcode reads the instruction's width field — the lane count it operates on.
+ */
+export type VM_WIDTH = string;
+export namespace VM_WIDTH {
+    let NONE_1: string;
+    export { NONE_1 as NONE };
+    export let VARIABLE: string;
+    export let ONE: string;
+    export let THREE: string;
+}
+/**
+ * How many lanes an opcode writes to its destination, relative to the operation's width.
+ */
+export type VM_DEST = string;
+export namespace VM_DEST {
+    let NONE_2: string;
+    export { NONE_2 as NONE };
+    export let WIDTH: string;
+    let ONE_1: string;
+    export { ONE_1 as ONE };
+}
+/**
+ * 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.
+ * @type {number}
+ */
+export const VM_MAX_WIDTH: number;
+/**
+ * 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.
+ *
+ * @type {number}
+ */
+export const VM_WIDTH_SHIFT: number;
+/** Mask selecting the opcode out of an instruction's first word. @type {number} */
+export const VM_OP_MASK: number;
+/** Mask selecting the width out of an instruction's first word, once shifted down. @type {number} */
+export const VM_WIDTH_MASK: number;
 /**
  * Per-opcode metadata: mnemonic + the role of each of the three operand slots `[s0, s1, s2]`.
  *

package/src/shade/renderer/particles/isa/ParticleVMISA.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleVMISA.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleVMISA.js"],"names":[],"mappings":"AAyNA;;;GAGG;AACH,+BAHW,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;;;;GAQG;AACH,gCANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB;;;;yBApNS,MAAM;;;;;;;;;;;;;;;;yBA2BN,MAAM;;;;;;;;;;;;;;6BA0BN,MAAM;;;;;;;;;;oBAeN,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DhB;;;;;;GAMG;AACH,qBAFU,IAAI,MAAM,EAAE;IAAC,MAAM,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAC,CAAC,CAEvD"}
+{"version":3,"file":"ParticleVMISA.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleVMISA.js"],"names":[],"mappings":"AAiNA;;;;;GAKG;AACH,oCAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;GAGG;AACH,oCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;GAGG;AACH,uCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;GASG;AACH,uCAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAelB;AAED;;;;;GAKG;AACH,kCAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAclB;AA4HD;;;GAGG;AACH,+BAHW,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;;;;GAQG;AACH,gCANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;GAUG;AACH,sCAHW,MAAM,GACJ,MAAM,CAclB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,kDAJW,UAAU,MAAM,CAAC,QACjB,MAAM,gBACG,MAAM,QAAE,MAAM,KAAE,IAAI,QA+BvC;;;;yBA/cS,MAAM;;;;;;;;;;;;;;;yBAyBN,MAAM;;;;;;;;;;;AAwBhB;;;;;;GAMG;AACH;QAFiB,MAAM,GAAE,MAAM;EAW5B;;;;oBAIO,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAwDN,MAAM;;;;;;;;;;;sBAeN,MAAM;;;;;;;;AAWhB;;;;GAIG;AACH,2BAFU,MAAM,CAEc;AAE9B;;;;;;;;;GASG;AACH,6BAFU,MAAM,CAEgB;AAEhC,mFAAmF;AACnF,yBADyE,MAAM,CAChD;AAE/B,qGAAqG;AACrG,4BAD2F,MAAM,CAChE;AA6EjC;;;;;;GAMG;AACH,qBAFU,IAAI,MAAM,EAAE;IAAC,MAAM,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAC,CAAC,CAEvD"}