@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -1,6 +1,26 @@
 import { assert } from "../../../../core/assert.js";
-import { PARTICLE_VM_INSTRUCTION_WORDS, PARTICLE_VM_REGISTER_COUNT } from "../ParticleConstants.js";
-import { VM_ISA, VM_OP } from "./ParticleVMISA.js";
+import { PARTICLE_VM_INSTRUCTION_WORDS, PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
+import {
+    pack_swizzle,
+    VM_ISA,
+    VM_MAX_WIDTH,
+    VM_OP,
+    VM_WIDTH,
+    vm_encode_word0,
+    vm_visit_register_operands,
+} from "./ParticleVMISA.js";
+
+/**
+ * The attribute ops take their width from their component count, so a nonsensical count would
+ * otherwise surface as a nonsensical width. Fail where the mistake was written instead.
+ *
+ * @param {number} component_count
+ * @param {string} mnemonic
+ */
+function assert_component_count(component_count, mnemonic) {
+    assert.greaterThanOrEqual(component_count, 1, `${mnemonic} component count must be >= 1`);
+    assert.lessThanOrEqual(component_count, VM_MAX_WIDTH, `${mnemonic} component count must be <= ${VM_MAX_WIDTH}`);
+}
 
 /**
  * A single VM instruction stream (a SPAWN or UPDATE section). Instructions are appended in order;
@@ -15,11 +35,22 @@ export class InstructionStream {
     /** @type {number} highest register index referenced, plus one */
     register_count = 0;
 
-    #use_register(index) {
-        assert.isNonNegativeInteger(index, "register index");
-        assert.lessThan(index, PARTICLE_VM_REGISTER_COUNT, "register index exceeds the VM register file");
-        if (index + 1 > this.register_count) {
-            this.register_count = index + 1;
+    /**
+     * Record that an operand spanning `span` slots sits at `base`. A range running off the end of
+     * the file would read whatever the next value holds, so the bound is on its end, not its start.
+     *
+     * @param {number} base
+     * @param {number} span
+     */
+    #use_register(base, span) {
+        assert.isNonNegativeInteger(base, "register index");
+        assert.lessThanOrEqual(
+            base + span,
+            PARTICLE_VM_REGISTER_SLOTS,
+            `register range [${base}, ${base + span}) exceeds the ${PARTICLE_VM_REGISTER_SLOTS}-slot VM register file`
+        );
+        if (base + span > this.register_count) {
+            this.register_count = base + span;
         }
     }
 
@@ -27,32 +58,46 @@ export class InstructionStream {
      * Emit a raw instruction. Validates the opcode and tracks register usage. Prefer the typed
      * helpers below where they exist — they document the non-obvious operand packing.
      *
+     * `width` is the lane count the operation spans. Left out, it is the opcode's natural width —
+     * four for the element-wise ops, three for the ones that used to be spelled `.xyz`. Opcodes
+     * whose lane count is fixed ignore it.
+     *
      * @param {number} op
      * @param {number} [dst]
      * @param {number} [s0]
      * @param {number} [s1]
      * @param {number} [s2]
+     * @param {number} [width]
      * @returns {InstructionStream} this, for chaining
      */
-    emit(op, dst = 0, s0 = 0, s1 = 0, s2 = 0) {
+    emit(op, dst = 0, s0 = 0, s1 = 0, s2 = 0, width = undefined) {
         const meta = VM_ISA.get(op);
         assert.defined(meta, `unknown opcode ${op}`);
 
-        if (meta.dst) {
-            // For value-producing ops this is the destination; for STORE_ATTR/KILL it is a source
-            // register living in the dst slot. Either way it must be a valid register.
-            this.#use_register(dst);
+        let requested = width === undefined ? meta.default_width : width;
+
+        // The attribute ops measure themselves in components. A store's width IS its component
+        // count — it writes one record word per lane — so it is taken, not asked for, however the
+        // instruction was built; a load merely defaults to it, since widening a load is how a narrow
+        // attribute reaches a wider operation.
+        if (op === VM_OP.STORE_ATTR) {
+            requested = s1;
+        } else if (op === VM_OP.LOAD_ATTR && width === undefined) {
+            requested = s1;
         }
 
-        const operands = meta.operands;
-        const slots = [s0, s1, s2];
-        for (let i = 0; i < 3; i++) {
-            if (operands[i] === "reg") {
-                this.#use_register(slots[i]);
-            }
+        if (meta.width !== VM_WIDTH.NONE) {
+            assert.greaterThanOrEqual(requested, meta.min_width, `${meta.name} width`);
+            assert.lessThanOrEqual(requested, VM_MAX_WIDTH, `${meta.name} width`);
         }
 
-        this.instructions.push([op, dst >>> 0, s0 >>> 0, s1 >>> 0, s2 >>> 0]);
+        const word0 = vm_encode_word0(op, requested);
+
+        // Walked before the operands are narrowed to u32, so a nonsense index still trips the assert
+        // that names it rather than wrapping into a plausible-looking slot.
+        vm_visit_register_operands([word0, dst, s0, s1, s2], 0, (slot, span) => this.#use_register(slot, span));
+
+        this.instructions.push([word0, dst >>> 0, s0 >>> 0, s1 >>> 0, s2 >>> 0]);
         return this;
     }
 
@@ -61,48 +106,76 @@ export class InstructionStream {
     /**
      * @param {number} dst
      * @param {number} src
+     * @param {number} [width]
      * @returns {InstructionStream}
      */
-    mov(dst, src) {
-        return this.emit(VM_OP.MOV, dst, src);
+    mov(dst, src, width = undefined) {
+        return this.emit(VM_OP.MOV, dst, src, 0, 0, width);
+    }
+
+    /**
+     * Widen a single-lane value into `width` lanes.
+     *
+     * A `SWIZZLE` whose every selector names lane 0 — no opcode of its own, because that is exactly
+     * what one is. The compiler emits these where a narrow value meets a wider operation, which is
+     * the broadcast the reductions and `CURVE` used to do implicitly by filling all four lanes.
+     *
+     * @param {number} dst
+     * @param {number} src
+     * @param {number} width
+     * @returns {InstructionStream}
+     */
+    broadcast(dst, src, width) {
+        return this.emit(VM_OP.SWIZZLE, dst, src, pack_swizzle(0, 0, 0, 0), 0, width);
     }
 
     /**
      * @param {number} dst
      * @param {number} constant_index
+     * @param {number} [width]
      * @returns {InstructionStream}
      */
-    loadConst(dst, constant_index) {
-        return this.emit(VM_OP.LOAD_CONST, dst, constant_index);
+    loadConst(dst, constant_index, width = undefined) {
+        return this.emit(VM_OP.LOAD_CONST, dst, constant_index, 0, 0, width);
     }
 
     /**
+     * Lanes past `component_count` read as zero, which is how a narrow attribute widens into a
+     * wider operation without a second instruction.
+     *
      * @param {number} dst
      * @param {number} word_offset
      * @param {number} component_count
+     * @param {number} [width] defaults to the component count
      * @returns {InstructionStream}
      */
-    loadAttr(dst, word_offset, component_count) {
-        return this.emit(VM_OP.LOAD_ATTR, dst, word_offset, component_count);
+    loadAttr(dst, word_offset, component_count, width = undefined) {
+        assert_component_count(component_count, "LOAD_ATTR");
+        return this.emit(VM_OP.LOAD_ATTR, dst, word_offset, component_count, 0, width ?? component_count);
     }
 
     /**
+     * The width is the component count and cannot differ from it: a store writes exactly the lanes
+     * the register holds.
+     *
      * @param {number} src_register
      * @param {number} word_offset
      * @param {number} component_count
      * @returns {InstructionStream}
      */
     storeAttr(src_register, word_offset, component_count) {
-        return this.emit(VM_OP.STORE_ATTR, src_register, word_offset, component_count);
+        assert_component_count(component_count, "STORE_ATTR");
+        return this.emit(VM_OP.STORE_ATTR, src_register, word_offset, component_count, 0, component_count);
     }
 
     /**
      * @param {number} dst
      * @param {number} builtin_id
+     * @param {number} [width]
      * @returns {InstructionStream}
      */
-    loadBuiltin(dst, builtin_id) {
-        return this.emit(VM_OP.LOAD_BUILTIN, dst, builtin_id);
+    loadBuiltin(dst, builtin_id, width = undefined) {
+        return this.emit(VM_OP.LOAD_BUILTIN, dst, builtin_id, 0, 0, width);
     }
 
     /**
@@ -114,22 +187,27 @@ export class InstructionStream {
     }
 
     /**
+     * One independent uniform draw in `[0, 1)` per lane — so `width` draws off the shared RNG.
+     * Anything shaped (signed, a disk, a sphere) is arithmetic over these; see
+     * {@link ../graph/particle_graph_distributions.js} for the graph-level versions.
+     *
      * @param {number} dst
-     * @param {number} mode
+     * @param {number} [width]
      * @returns {InstructionStream}
      */
-    random(dst, mode) {
-        return this.emit(VM_OP.RANDOM, dst, mode);
+    random(dst, width = undefined) {
+        return this.emit(VM_OP.RANDOM, dst, 0, 0, 0, width);
     }
 
     /**
      * @param {number} dst
      * @param {number} curve_handle
      * @param {number} t_register
+     * @param {number} [width]
      * @returns {InstructionStream}
      */
-    curve(dst, curve_handle, t_register) {
-        return this.emit(VM_OP.CURVE, dst, curve_handle, t_register);
+    curve(dst, curve_handle, t_register, width = undefined) {
+        return this.emit(VM_OP.CURVE, dst, curve_handle, t_register, 0, width);
     }
 
     /**

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

@@ -4,21 +4,24 @@
  */
 export class ParticleAssembler {
     /** @type {InstructionStream} */
-    spawn: InstructionStream;
+    init: InstructionStream;
     /** @type {InstructionStream} */
     update: InstructionStream;
-    /** @type {number[]} flat constant pool, 4 floats per entry */
+    /** @type {number[]} flat constant pool, one float per word */
     constants: number[];
     /**
-     * Intern a `vec4f` constant into the shared pool, deduplicating exact matches so identical
-     * literals share a slot.
-     * @param {number} x
-     * @param {number} [y]
-     * @param {number} [z]
-     * @param {number} [w]
-     * @returns {number} constant-pool index
+     * Intern a constant into the shared pool, as many words as it has components.
+     *
+     * The pool is addressed by word, so a run that already appears anywhere in it — not merely one
+     * that starts on some fixed boundary — is reused rather than added again. That subsumes exact
+     * deduplication and also lets a narrow constant share the leading words of a wider one, which
+     * matters because most literals in a real effect are scalars: the pool used to reserve four
+     * words for every one of them.
+     *
+     * @param {...number} values one per component, at least one
+     * @returns {number} word index of the first component
      */
-    constant(x: number, y?: number, z?: number, w?: number): number;
+    constant(...values: number[]): number;
     /**
      * @returns {ParticleProgram}
      */

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleAssembler.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleAssembler.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;IACI,gCAAgC;IAChC,OADW,iBAAiB,CACI;IAEhC,gCAAgC;IAChC,QADW,iBAAiB,CACK;IAEjC,8DAA8D;IAC9D,WADW,MAAM,EAAE,CACJ;IAEf;;;;;;;;OAQG;IACH,YANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAyBlB;IAED;;OAEG;IACH,SAFa,eAAe,CAS3B;CACJ;kCA9DiC,wBAAwB;gCAC1B,sBAAsB"}
+{"version":3,"file":"ParticleAssembler.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleAssembler.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;IACI,gCAAgC;IAChC,MADW,iBAAiB,CACG;IAE/B,gCAAgC;IAChC,QADW,iBAAiB,CACK;IAEjC,8DAA8D;IAC9D,WADW,MAAM,EAAE,CACJ;IAEf;;;;;;;;;;;OAWG;IACH,oBAHc,MAAM,KACP,MAAM,CA0BlB;IAED;;OAEG;IACH,SAFa,eAAe,CAS3B;CACJ;kCAlEiC,wBAAwB;gCAC1B,sBAAsB"}

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

@@ -7,46 +7,50 @@ import { ParticleProgram } from "./ParticleProgram.js";
  */
 export class ParticleAssembler {
     /** @type {InstructionStream} */
-    spawn = new InstructionStream();
+    init = new InstructionStream();
 
     /** @type {InstructionStream} */
     update = new InstructionStream();
 
-    /** @type {number[]} flat constant pool, 4 floats per entry */
+    /** @type {number[]} flat constant pool, one float per word */
     constants = [];
 
     /**
-     * Intern a `vec4f` constant into the shared pool, deduplicating exact matches so identical
-     * literals share a slot.
-     * @param {number} x
-     * @param {number} [y]
-     * @param {number} [z]
-     * @param {number} [w]
-     * @returns {number} constant-pool index
+     * Intern a constant into the shared pool, as many words as it has components.
+     *
+     * The pool is addressed by word, so a run that already appears anywhere in it — not merely one
+     * that starts on some fixed boundary — is reused rather than added again. That subsumes exact
+     * deduplication and also lets a narrow constant share the leading words of a wider one, which
+     * matters because most literals in a real effect are scalars: the pool used to reserve four
+     * words for every one of them.
+     *
+     * @param {...number} values one per component, at least one
+     * @returns {number} word index of the first component
      */
-    constant(x, y = 0, z = 0, w = 0) {
+    constant(...values) {
         const data = this.constants;
-        const count = data.length / 4;
 
-        for (let i = 0; i < count; i++) {
-            const base = i * 4;
-
-            if (
-                data[base] === x
-                && data[base + 1] === y
-                && data[base + 2] === z
-                && data[base + 3] === w
-            ) {
-
-                return i;
+        for (let base = 0; base + values.length <= data.length; base++) {
+            let matches = true;
 
+            for (let i = 0; i < values.length; i++) {
+                // Object.is, so a negative zero never silently aliases a positive one.
+                if (!Object.is(data[base + i], values[i])) {
+                    matches = false;
+                    break;
+                }
             }
 
+            if (matches) {
+                return base;
+            }
         }
 
-        data.push(x, y, z, w);
+        const base = data.length;
+
+        data.push(...values);
 
-        return count;
+        return base;
     }
 
     /**
@@ -54,10 +58,10 @@ export class ParticleAssembler {
      */
     build() {
         return new ParticleProgram({
-            spawn: this.spawn.toWords(),
+            init: this.init.toWords(),
             update: this.update.toWords(),
             constants: new Float32Array(this.constants),
-            register_count: Math.max(this.spawn.register_count, this.update.register_count),
+            register_count: Math.max(this.init.register_count, this.update.register_count),
         });
     }
 }

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

@@ -1,5 +1,5 @@
 /**
- * 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
@@ -8,31 +8,43 @@
 export class ParticleProgram {
     /**
      * @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 }: {
-        spawn: Uint32Array;
+    constructor({ init, update, constants, register_count }: {
+        init: Uint32Array;
         update: Uint32Array;
         constants: Float32Array;
         register_count: number;
     });
-    /** @type {Uint32Array} */
-    spawn: Uint32Array;
-    /** @type {Uint32Array} */
+    /**
+     * Instruction words for the INIT section.
+     * @type {Uint32Array}
+     */
+    init: Uint32Array;
+    /**
+     * Instruction words for the UPDATE section.
+     * @type {Uint32Array}
+     */
     update: Uint32Array;
-    /** @type {Float32Array} */
+    /**
+     * Constant pool, 4 floats (one `vec4f`) per entry.
+     * @type {Float32Array}
+     */
     constants: Float32Array;
-    /** @type {number} */
+    /**
+     * Number of vec4 registers the program needs.
+     * @type {number}
+     */
     register_count: number;
-    /** @returns {number} number of instructions in the SPAWN section */
-    get spawn_instruction_count(): number;
+    /** @returns {number} number of instructions in the INIT section */
+    get init_instruction_count(): number;
     /** @returns {number} number of instructions in the UPDATE section */
     get update_instruction_count(): number;
-    /** @returns {number} number of vec4 constants */
-    get constant_count(): number;
+    /** @returns {number} words in the constant pool — it is addressed by word, not by `vec4` */
+    get constant_word_count(): number;
     /**
      * Validate structural invariants (opcodes known, register indices in range, instruction budget,
      * constant references in range). Throws on the first problem. Intended for tests and asset

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleProgram.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleProgram.js"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH;IACI;;;;;;OAMG;IACH;QAL+B,KAAK,EAAzB,WAAW;QACS,MAAM,EAA1B,WAAW;QACU,SAAS,EAA9B,YAAY;QACG,cAAc,EAA7B,MAAM;OAqBhB;IARG,0BAA0B;IAC1B,OADW,WAAW,CACJ;IAClB,0BAA0B;IAC1B,QADW,WAAW,CACF;IACpB,2BAA2B;IAC3B,WADW,YAAY,CACG;IAC1B,qBAAqB;IACrB,gBADW,MAAM,CACmB;IAGxC,oEAAoE;IACpE,sCAEC;IAED,qEAAqE;IACrE,uCAEC;IAED,iDAAiD;IACjD,6BAEC;IAED;;;;OAIG;IACH,iBAKC;CACJ"}
+{"version":3,"file":"ParticleProgram.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleProgram.js"],"names":[],"mappings":"AAqBA;;;;;;GAMG;AACH;IA0BI;;;;;;OAMG;IACH;QAL+B,IAAI,EAAxB,WAAW;QACS,MAAM,EAA1B,WAAW;QACU,SAAS,EAA9B,YAAY;QACG,cAAc,EAA7B,MAAM;OAgBhB;IA7CD;;;OAGG;IACH,MAFU,WAAW,CAEhB;IAEL;;;OAGG;IACH,QAFU,WAAW,CAEd;IAEP;;;OAGG;IACH,WAFU,YAAY,CAEZ;IAEV;;;OAGG;IACH,gBAFU,MAAM,CAED;IAyBf,mEAAmE;IACnE,qCAEC;IAED,qEAAqE;IACrE,uCAEC;IAED,4FAA4F;IAC5F,kCAEC;IAED;;;;OAIG;IACH,iBAKC;CACJ"}