@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -1,30 +1,19 @@
 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_SLOTS,
 } from "../ParticleConstants.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 (INIT and UPDATE) plus a shared constant
- * pool. This is the value the node compiler emits and the runtime packs into the program arena.
+ * 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 {
 
@@ -41,13 +30,13 @@ export class ParticleProgram {
     update;
 
     /**
-     * Constant pool, 4 floats (one `vec4f`) per entry.
+     * Constant pool, one float per word.
      * @type {Float32Array}
      */
     constants;
 
     /**
-     * Number of vec4 registers the program needs.
+     * Register slots the program needs.
      * @type {number}
      */
     register_count;
@@ -67,7 +56,11 @@ export class ParticleProgram {
 
         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.lessThanOrEqual(register_count, PARTICLE_VM_REGISTER_SLOTS, "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"
+        );
 
         this.init = init;
         this.update = update;
@@ -91,143 +84,95 @@ export class ParticleProgram {
     }
 
     /**
-     * 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.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");
+    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_word_count
- * @param {number} 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 word0 = words[base];
-        const op = vm_decode_op(word0);
-        const width = vm_decode_width(word0);
-        const meta = VM_ISA.get(op);
-
-        if (meta === undefined) {
-            throw new Error(`${label}[${i}]: unknown opcode ${op}`);
-        }
-
-        const dst = words[base + 1];
-        const s0 = words[base + 2];
-
-        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) {
-            // 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 });
-        }
-
-        const operands = meta.operands;
-        for (let s = 0; s < 3; s++) {
-            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 });
+    /**
+     * 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 (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`
-            );
-        }
+        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);
+    }
 
-        // 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`
-                    );
-                }
-            }
-        }
+    /**
+     * 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;
+
+        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
+        );
+    }
 
-        if (op === VM_OP.LOAD_CONST) {
-            // 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`
-            );
-        }
+    /**
+     * 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;
+    }
 
-        // 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`
-            );
-
-            // 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}`
-                );
-            }
-        }
+    /**
+     * 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,
+        });
+
+        r.copy(this);
+
+        return r;
     }
 }