@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -1,51 +1,76 @@
 import { assert } from "../../../../core/assert.js";
+import { is_typed_array_equals } from "../../../../core/collection/array/typed/is_typed_array_equals.js";
+import { uint32_array_hash } from "../../../../core/collection/array/typed/uint32_array_hash.js";
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
+import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
 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";
 
 /**
- * A compiled particle program: two instruction streams (SPAWN and UPDATE) plus a shared constant
- * pool. This is the value the node compiler emits and the runtime packs into the program arena.
+ * 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 heap.
  *
  * 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.
+ * instruction. The constant pool is a flat `Float32Array`, one float per word.
  */
 export class ParticleProgram {
+
+    /**
+     * Instruction words for the INIT section.
+     * @type {Uint32Array}
+     */
+    init;
+
+    /**
+     * Instruction words for the UPDATE section.
+     * @type {Uint32Array}
+     */
+    update;
+
+    /**
+     * Constant pool, one float per word.
+     * @type {Float32Array}
+     */
+    constants;
+
+    /**
+     * Register slots 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 slots a VM instruction can address"
+        );
 
-        /** @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,76 +78,101 @@ 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;
     }
 
     /**
-     * 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
-     * ingestion, not the hot path.
+     * The constant pool as the raw IEEE-754 words it is made of, without copying — a view of the
+     * same bytes, so writing through it writes the pool.
+     *
+     * This is the form the pool is compared, hashed and packed in, because it holds constants, not
+     * measurements. `-0` and `+0` are the same number and different constants — a `DIV` by each
+     * disagrees about the sign of the infinity it produces — and the assembler already keeps them
+     * apart, interning with `Object.is`; equality that read the pool as floats would put back
+     * together what interning took care to separate. Reading bits also keeps
+     * {@link ParticleProgram#equals} reflexive over a pool holding a NaN.
+     *
+     * @returns {Uint32Array}
      */
-    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");
-        assert.lessThanOrEqual(this.update_instruction_count, PARTICLE_VM_MAX_INSTRUCTIONS, "update exceeds instruction budget");
+    get constant_words() {
+        // a Float32Array is 4-byte aligned by construction, so this view always exists
+        return new Uint32Array(this.constants.buffer, this.constants.byteOffset, this.constants.length);
     }
-}
 
-/**
- * @param {Uint32Array} words
- * @param {string} label
- * @param {number} constant_count
- * @param {number} register_count
- */
-function validate_stream(words, label, constant_count, register_count) {
-    const instruction_count = words.length / PARTICLE_VM_INSTRUCTION_WORDS;
+    /**
+     * Structural equality: the same two instruction streams, the same constant pool bit for bit,
+     * and the same register budget. Two programs that compare equal are one program — the VM would
+     * execute them identically.
+     *
+     * @param {ParticleProgram} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (this === other) {
+            return true;
+        }
 
-    for (let i = 0; i < instruction_count; i++) {
-        const base = i * PARTICLE_VM_INSTRUCTION_WORDS;
-        const op = words[base];
-        const meta = VM_ISA.get(op);
+        return this.register_count === other.register_count
+            && is_typed_array_equals(this.init, other.init)
+            && is_typed_array_equals(this.update, other.update)
+            && is_typed_array_equals(this.constant_words, other.constant_words);
+    }
 
-        if (meta === undefined) {
-            throw new Error(`${label}[${i}]: unknown opcode ${op}`);
-        }
+    /**
+     * Hash over everything {@link ParticleProgram#equals} compares, and in the same terms — the pool
+     * goes through the same bit view, so equal programs hash equally.
+     *
+     * @returns {number} int32
+     */
+    hash() {
+        const constant_words = this.constant_words;
 
-        const dst = words[base + 1];
-        const s0 = words[base + 2];
+        return hash_mix2(
+            hash_mix3(
+                uint32_array_hash(this.init, 0, this.init.length),
+                uint32_array_hash(this.update, 0, this.update.length),
+                uint32_array_hash(constant_words, 0, constant_words.length)
+            ),
+            this.register_count
+        );
+    }
 
-        // Destination (and KILL/STORE_ATTR source, which live in the dst slot) must be a valid register.
-        if (meta.dst) {
-            assert.lessThan(dst, register_count, `${label}[${i}] (${meta.name}): dst register ${dst} out of range`);
-        }
+    /**
+     * Take on another program's code, becoming equal to it.
+     *
+     * The streams and the pool are duplicated rather than shared. A compiled program is treated as
+     * immutable, but nothing here enforces that — the optimizer's passes read and rewrite these
+     * arrays directly — so a copy that aliased the original would let a rewrite of one silently
+     * become a rewrite of both.
+     *
+     * @param {ParticleProgram} other
+     */
+    copy(other) {
+        this.init = other.init.slice();
+        this.update = other.update.slice();
+        this.constants = other.constants.slice();
+        this.register_count = other.register_count;
+    }
 
-        // 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`);
-            }
-        }
+    /**
+     * A second program equal to this one and sharing none of its storage.
+     *
+     * @returns {ParticleProgram}
+     */
+    clone() {
+        // the constructor wants a whole program, so it gets an empty one — the copy overwrites
+        // every word of it before anything can observe it
+        const r = new ParticleProgram({
+            init: new Uint32Array(0),
+            update: new Uint32Array(0),
+            constants: new Float32Array(0),
+            register_count: 0,
+        });
 
-        if (op === VM_OP.LOAD_CONST) {
-            assert.lessThan(s0, constant_count, `${label}[${i}] (LOAD_CONST): constant index ${s0} out of range`);
-        }
+        r.copy(this);
 
-        // Attribute accesses must stay inside one record. An out-of-range offset is NOT caught by
-        // GPU robustness — record_base + offset lands inside the pool buffer, silently reading or
-        // corrupting the NEXT PARTICLE'S record.
-        if (op === VM_OP.LOAD_ATTR || op === VM_OP.STORE_ATTR) {
-            const offset = words[base + 2];
-            const components = words[base + 3];
-            const name = VM_ISA.get(op).name;
-            assert.greaterThanOrEqual(components, 1, `${label}[${i}] (${name}): component count must be >= 1`);
-            assert.lessThanOrEqual(components, 4, `${label}[${i}] (${name}): component count must be <= 4`);
-            assert.lessThanOrEqual(
-                offset + components,
-                PARTICLE_RECORD_WORD_COUNT,
-                `${label}[${i}] (${name}): attribute access [${offset}, ${offset + components}) exceeds the ${PARTICLE_RECORD_WORD_COUNT}-word record`
-            );
-        }
+        return r;
     }
 }