@woosh/meep-engine 3.16.0 → 3.17.1

package/src/shade/renderer/particles/optimizer/pass_dedup_constants.js

@@ -1,197 +1,198 @@
-import { VM_OP, vm_decode_op, vm_decode_width, vm_operation_width } from "../isa/ParticleVMISA.js";
-
-/** @type {string} */
-export const PARTICLE_PASS_DEDUP_CONSTANTS = "dedup_constants";
-
-/**
- * Point every `LOAD_CONST` at the first copy of the value it loads, and drop the pool words that
- * nothing reads any more.
- *
- * `LOAD_CONST` is the only instruction that reads the constant pool, and it reads a *run* — `base`
- * from the operand and as many words as the instruction is wide. So two loads of the same value are
- * the same instruction only when they name the same base, and when they do not, every pass
- * downstream is looking at two different things:
- *
- *     LOAD_CONST.1 r1, c0        LOAD_CONST.1 r1, c0
- *     MUL.1 r2, r0, r1           MUL.1 r2, r0, r1
- *     LOAD_CONST.1 r3, c1        LOAD_CONST.1 r3, c0
- *     MUL.1 r4, r0, r3           MUL.1 r4, r0, r3
- *     ADD.1 r5, r2, r4           ADD.1 r5, r2, r4
- *
- * With `c0` and `c1` holding the same number those two programs compute the same thing, but only the
- * right-hand one collapses: subexpression sharing folds the second load, copy propagation rewrites
- * the second `MUL` to read the first load's register, sharing then folds the two identical `MUL`s,
- * and dead code removes what is left. Seven instructions become five and six registers become four.
- * The left-hand one does not move at all. Canonicalizing the base is what makes the two the same
- * program, so this pass buys nothing on its own and everything through the passes after it.
- *
- * ## Where the duplicates come from
- *
- * Not from the node-graph compiler: {@link ../isa/ParticleAssembler.js}'s `constant` already scans
- * the whole pool for a matching run before appending, so a graph lowers to a pool with no duplicate
- * runs and no dead words — measured on the starter effect and on `simplex3`/`curl3`/`curl4` graphs,
- * every one of which comes out with nothing for this pass to find.
- *
- * They come from the other frontends:
- *
- * - **hand-written assembly**, where `.const c0 3` / `.const c1 3` is laid out exactly as typed,
- *   because the indices are the author's to choose and the parser will not renumber them;
- * - **the optimizer itself**, whose folds intern new literals and whose lane-peeling speculation
- *   runs the whole pipeline twice against one shared pool — so the literals belonging to the run
- *   that lost are still sitting in it;
- * - **`f32` rounding**, since the pool is built as doubles and only becomes a `Float32Array` at the
- *   end: two values that `constant` saw as distinct can land on the same float.
- *
- * ## Two halves, one switch
- *
- * The pass proper is the operand rewrite above: per section, and it never touches the pool, which is
- * what makes it safe when both sections share one. Compacting the pool needs to see every reference
- * in the program at once, so it is a step of
- * {@link ./optimize_particle_program.js optimize_compiled_particle_program} rather than a pass, and
- * it runs under this same switch — the rewrite is what makes words dead and the compaction is the
- * only thing that shows it, so a caller turning one off wants the other off too. A caller using the
- * per-section entry point gets the rewrite alone; there is no pool for it to compact.
- *
- * ## What must not change
- *
- * Runs are compared as `f32` **bit patterns**, not as numbers. That keeps `-0` out of `+0` — the two
- * are a visible difference the moment anything divides by one — and keeps two `NaN`s with different
- * payloads apart, which costs nothing since neither is a literal any frontend emits. Comparing the
- * bits the pool will actually hold, rather than the doubles it holds on the way there, is also what
- * catches the rounding case above.
- */
-
-/** Scratch for reading a value's `f32` bits. Module-level because this runs per pool word. */
-const F32_SCRATCH = new Float32Array(1);
-
-/** @type {Uint32Array} the same four bytes, as an integer */
-const U32_SCRATCH = new Uint32Array(F32_SCRATCH.buffer);
-
-/**
- * @param {number} value
- * @returns {number} the bits `value` has once the pool is a `Float32Array`
- */
-function f32_bits(value) {
-    F32_SCRATCH[0] = value;
-
-    return U32_SCRATCH[0];
-}
-
-/**
- * @param {ArrayLike<number>} constants
- * @param {number} base
- * @param {number} span
- * @returns {string} an identity for the run of values at `base`, distinct for every distinct run
- */
-function run_key(constants, base, span) {
-    let key = `${span}`;
-
-    for (let i = 0; i < span; i++) {
-        key += `:${f32_bits(constants[base + i])}`;
-    }
-
-    return key;
-}
-
-/**
- * The span of pool words an instruction reads, or 0 when it is not a `LOAD_CONST`.
- *
- * @param {ArrayLike<number>} words the five words of one instruction
- * @returns {number}
- */
-function constant_span(words) {
-    const op = vm_decode_op(words[0]);
-
-    if (op !== VM_OP.LOAD_CONST) {
-        return 0;
-    }
-
-    return vm_operation_width(op, vm_decode_width(words[0]));
-}
-
-/**
- * Every `(base, span)` a section loads from the pool.
- *
- * @param {ArrayLike<ArrayLike<number>>} instructions five-word tuples
- * @param {function(number, number, number): void} visit `(index, base, span)`
- */
-export function visit_particle_constant_reads(instructions, visit) {
-    for (let index = 0; index < instructions.length; index++) {
-        const words = instructions[index];
-        const span = constant_span(words);
-
-        if (span > 0) {
-            visit(index, words[2], span);
-        }
-    }
-}
-
-/**
- * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
- */
-export function pass_dedup_constants(instructions, context) {
-    const constants = context.constants;
-
-    if (constants === undefined || constants.length === 0) {
-        return null;
-    }
-
-    /** @type {Array<{index: number, base: number, span: number}>} */
-    const reads = [];
-
-    /** @type {Set<number>} only the spans something actually loads are worth indexing */
-    const spans = new Set();
-
-    // One walk rather than one per question: this pass sits in the sweep loop and a `curl3` effect
-    // is four thousand instructions, so decoding them all twice per invocation was most of what it
-    // cost — and on a pool the assembler built there is nothing at the end of it to find.
-    visit_particle_constant_reads(instructions, (index, base, span) => {
-        if (base < 0 || base + span > constants.length) {
-            // Out of the pool: a malformed program, which `validate` reports and this pass leaves
-            // exactly as it found it rather than rewriting into a different kind of wrong.
-            return;
-        }
-
-        reads.push({ index, base, span });
-        spans.add(span);
-    });
-
-    if (reads.length === 0) {
-        return null;
-    }
-
-    /** @type {Map<string, number>} run identity -> the first base holding it */
-    const earliest = new Map();
-
-    for (const span of spans) {
-        for (let base = 0; base + span <= constants.length; base++) {
-            const key = run_key(constants, base, span);
-
-            // ascending, and only the first wins: the canonical base for a run is the earliest one,
-            // which is a fixed point — running this pass again moves nothing — and monotonically
-            // decreasing, so it cannot ping-pong with anything in the sweep it sits in.
-            if (!earliest.has(key)) {
-                earliest.set(key, base);
-            }
-        }
-    }
-
-    /** @type {number[][]|null} */
-    let out = null;
-
-    for (const read of reads) {
-        const canonical = earliest.get(run_key(constants, read.base, read.span));
-
-        if (canonical === undefined || canonical === read.base) {
-            continue;
-        }
-
-        if (out === null) {
-            out = instructions.map(words => Array.from(words));
-        }
-
-        out[read.index][2] = canonical;
-    }
-
-    return out;
-}
+import { VM_OP, vm_decode_op, vm_decode_width, vm_operation_width } from "../isa/ParticleVMISA.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_DEDUP_CONSTANTS = "dedup_constants";
+
+/**
+ * Point every `LOAD_CONST` at the first copy of the value it loads, and drop the pool words that
+ * nothing reads any more.
+ *
+ * `LOAD_CONST` is the only instruction that reads the constant pool, and it reads a *run* — `base`
+ * from the operand and as many words as the instruction is wide. So two loads of the same value are
+ * the same instruction only when they name the same base, and when they do not, every pass
+ * downstream is looking at two different things:
+ *
+ *     LOAD_CONST.1 r1, c0        LOAD_CONST.1 r1, c0
+ *     MUL.1 r2, r0, r1           MUL.1 r2, r0, r1
+ *     LOAD_CONST.1 r3, c1        LOAD_CONST.1 r3, c0
+ *     MUL.1 r4, r0, r3           MUL.1 r4, r0, r3
+ *     ADD.1 r5, r2, r4           ADD.1 r5, r2, r4
+ *
+ * With `c0` and `c1` holding the same number those two programs compute the same thing, but only the
+ * right-hand one collapses: subexpression sharing folds the second load, copy propagation rewrites
+ * the second `MUL` to read the first load's register, sharing then folds the two identical `MUL`s,
+ * and dead code removes what is left. Seven instructions become five and six registers become four.
+ * The left-hand one does not move at all. Canonicalizing the base is what makes the two the same
+ * program, so this pass buys nothing on its own and everything through the passes after it.
+ *
+ * ## Where the duplicates come from
+ *
+ * Not from the node-graph compiler: {@link ../isa/ParticleAssembler.js}'s `constant` already scans
+ * the whole pool for a matching run before appending, so a graph lowers to a pool with no duplicate
+ * runs and no dead words — measured on the starter effect and on `simplex3`/`curl3`/`curl4` graphs,
+ * every one of which comes out with nothing for this pass to find.
+ *
+ * They come from the other frontends:
+ *
+ * - **hand-written assembly**, where `.const c0 3` / `.const c1 3` is laid out exactly as typed,
+ *   because the indices are the author's to choose and the parser will not renumber them;
+ * - **the optimizer itself**, whose folds intern new literals and whose lane-peeling speculation
+ *   runs the whole pipeline twice against one shared pool — so the literals belonging to the run
+ *   that lost are still sitting in it;
+ * - **`f32` rounding**, since the pool is built as doubles and only becomes a `Float32Array` at the
+ *   end: two values that `constant` saw as distinct can land on the same float.
+ *
+ * ## Two halves, one switch
+ *
+ * The pass proper is the operand rewrite above: per section, and it never touches the pool, which is
+ * what makes it safe when both sections share one. Compacting the pool needs to see every reference
+ * in the program at once, so it is a step of
+ * {@link ./optimize_particle_program.js optimize_particle_program} rather than a pass, and
+ * it runs under this same switch — the rewrite is what makes words dead and the compaction is the
+ * only thing that shows it, so a caller turning one off wants the other off too. A caller using the
+ * per-section entry point gets the rewrite alone; there is no pool for it to compact.
+ *
+ * ## What must not change
+ *
+ * Runs are compared as `f32` **bit patterns**, not as numbers. That keeps `-0` out of `+0` — the two
+ * are a visible difference the moment anything divides by one — and keeps two `NaN`s with different
+ * payloads apart, which costs nothing since neither is a literal any frontend emits. Comparing the
+ * bits the pool will actually hold, rather than the doubles it holds on the way there, is also what
+ * catches the rounding case above.
+ */
+
+/** Scratch for reading a value's `f32` bits. Module-level because this runs per pool word. */
+const F32_SCRATCH = new Float32Array(1);
+
+/** @type {Uint32Array} the same four bytes, as an integer */
+const U32_SCRATCH = new Uint32Array(F32_SCRATCH.buffer);
+
+/**
+ * @param {number} value
+ * @returns {number} the bits `value` has once the pool is a `Float32Array`
+ */
+function f32_bits(value) {
+    F32_SCRATCH[0] = value;
+
+    return U32_SCRATCH[0];
+}
+
+/**
+ * @param {ArrayLike<number>} constants
+ * @param {number} base
+ * @param {number} span
+ * @returns {string} an identity for the run of values at `base`, distinct for every distinct run
+ */
+function run_key(constants, base, span) {
+    let key = `${span}`;
+
+    for (let i = 0; i < span; i++) {
+        key += `:${f32_bits(constants[base + i])}`;
+    }
+
+    return key;
+}
+
+/**
+ * The span of pool words an instruction reads, or 0 when it is not a `LOAD_CONST`.
+ *
+ * @param {ArrayLike<number>} words the five words of one instruction
+ * @returns {number}
+ */
+function constant_span(words) {
+    const op = vm_decode_op(words[0]);
+
+    if (op !== VM_OP.LOAD_CONST) {
+        return 0;
+    }
+
+    return vm_operation_width(op, vm_decode_width(words[0]));
+}
+
+/**
+ * Every `(base, span)` a section loads from the pool. A `LOAD_CONST` is the one instruction that
+ * reads it, and its pool index is its first source word.
+ *
+ * @param {ArrayLike<ArrayLike<number>>} instructions four-word tuples
+ * @param {function(number, number, number): void} visit `(index, base, span)`
+ */
+export function visit_particle_constant_reads(instructions, visit) {
+    for (let index = 0; index < instructions.length; index++) {
+        const words = instructions[index];
+        const span = constant_span(words);
+
+        if (span > 0) {
+            visit(index, words[1], span);
+        }
+    }
+}
+
+/**
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_dedup_constants(instructions, context) {
+    const constants = context.constants;
+
+    if (constants === undefined || constants.length === 0) {
+        return null;
+    }
+
+    /** @type {Array<{index: number, base: number, span: number}>} */
+    const reads = [];
+
+    /** @type {Set<number>} only the spans something actually loads are worth indexing */
+    const spans = new Set();
+
+    // One walk rather than one per question: this pass sits in the sweep loop and a `curl3` effect
+    // is four thousand instructions, so decoding them all twice per invocation was most of what it
+    // cost — and on a pool the assembler built there is nothing at the end of it to find.
+    visit_particle_constant_reads(instructions, (index, base, span) => {
+        if (base < 0 || base + span > constants.length) {
+            // Out of the pool: a malformed program, which `validate` reports and this pass leaves
+            // exactly as it found it rather than rewriting into a different kind of wrong.
+            return;
+        }
+
+        reads.push({ index, base, span });
+        spans.add(span);
+    });
+
+    if (reads.length === 0) {
+        return null;
+    }
+
+    /** @type {Map<string, number>} run identity -> the first base holding it */
+    const earliest = new Map();
+
+    for (const span of spans) {
+        for (let base = 0; base + span <= constants.length; base++) {
+            const key = run_key(constants, base, span);
+
+            // ascending, and only the first wins: the canonical base for a run is the earliest one,
+            // which is a fixed point — running this pass again moves nothing — and monotonically
+            // decreasing, so it cannot ping-pong with anything in the sweep it sits in.
+            if (!earliest.has(key)) {
+                earliest.set(key, base);
+            }
+        }
+    }
+
+    /** @type {number[][]|null} */
+    let out = null;
+
+    for (const read of reads) {
+        const canonical = earliest.get(run_key(constants, read.base, read.span));
+
+        if (canonical === undefined || canonical === read.base) {
+            continue;
+        }
+
+        if (out === null) {
+            out = instructions.map(words => Array.from(words));
+        }
+
+        out[read.index][1] = canonical;
+    }
+
+    return out;
+}

package/src/shade/renderer/particles/optimizer/pass_eliminate_dead_code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pass_eliminate_dead_code.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_eliminate_dead_code.js"],"names":[],"mappings":"AAmDo5B,2JAAiP;AAjDroC,qBAAqB;AACrB,sCADW,MAAM,CACkC"}
+{"version":3,"file":"pass_eliminate_dead_code.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_eliminate_dead_code.js"],"names":[],"mappings":"AAmD8jF,2JAAqP;AAjDnzF,qBAAqB;AACrB,sCADW,MAAM,CACkC"}

package/src/shade/renderer/particles/optimizer/pass_fold_constants.d.ts

@@ -1,4 +1,23 @@
 export function pass_fold_constants(instructions: number[][], context: import("./optimize_particle_program.js").ParticleOptimizerContext): number[][];
+/**
+ * One lane of an operation, in the arithmetic the reference executes it in: `f32` operands, an
+ * `f64` computation, and the result rounded back to `f32` — which for a single correctly-rounded
+ * operation is the same number an `f32` machine produces.
+ *
+ * @param {number} op
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @returns {number}
+ */
+export function evaluate_particle_operation(op: number, a: number, b: number, c: number): number;
 /** @type {string} */
 export const PARTICLE_PASS_FOLD_CONSTANTS: string;
+/**
+ * The opcodes whose result a known zero operand decides on its own — the ones
+ * `fold_multiply_by_zero` rewrites, and therefore the ones whose results the equivalence harness's
+ * reach mode has to follow. Stated once so the two cannot drift.
+ * @type {Set<number>}
+ */
+export const PARTICLE_ZERO_ABSORBING_OPS: Set<number>;
 //# sourceMappingURL=pass_fold_constants.d.ts.map

package/src/shade/renderer/particles/optimizer/pass_fold_constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pass_fold_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_fold_constants.js"],"names":[],"mappings":"AAmDmD,sJAMnC;AArDhB,qBAAqB;AACrB,2CADW,MAAM,CAC4C"}
+{"version":3,"file":"pass_fold_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_fold_constants.js"],"names":[],"mappings":"AAyF4B,sJAEwD;AAuJpF;;;;;;;;;;GAUG;AACH,gDANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAmElB;AA9SD,qBAAqB;AACrB,2CADW,MAAM,CAC4C;AAE7D;;;;;GAKG;AACH,0CAFU,IAAI,MAAM,CAAC,CAE2C"}