@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,206 @@
+import { VM_MAX_WIDTH, VM_OP, swizzle_span } from "../isa/ParticleVMISA.js";
+
+/**
+ * What the optimizer is allowed to assume about each opcode.
+ *
+ * {@link ../isa/ParticleVMISA.js} says what an instruction *does*; this says what may be done *to*
+ * it — whether it can be deleted when its result is unread, narrowed when its high lanes are dead,
+ * evaluated at compile time, or recognised as a recomputation of something already in a register.
+ * Those are four different questions and an opcode can answer them differently: `LOAD_ATTR` is
+ * removable but not shareable across a store, `RANDOM` is neither, and `CURVE` is both.
+ *
+ * Every opcode has to appear in {@link VM_SEMANTICS} — the spec asserts it — because the safe
+ * default for a new one is "assume nothing", and a table that silently omitted it would instead have
+ * the optimizer assume everything.
+ */
+
+/**
+ * @typedef {object} ParticleOpSemantics
+ * @property {boolean} side_effects execution changes something other than the destination register:
+ *   the RNG stream, the record, the kill flag, or where the section stops. Never removable, never
+ *   duplicated, never widened or narrowed.
+ * @property {boolean} lanewise output lane `i` is a function of lane `i` of every non-scalar source
+ *   (and of the whole of a scalar one). The reductions and `CROSS` are not; `SWIZZLE` is lane-mapped
+ *   rather than lanewise and is handled by {@link vm_source_lane}.
+ * @property {boolean} narrowable dropping trailing output lanes leaves the remaining ones unchanged.
+ *   Weaker than `lanewise` — `CROSS` writes a fourth lane nothing else depends on — and not implied
+ *   by it for `RANDOM`, whose lanes are independent but whose count is the draw count.
+ * @property {boolean} shareable two executions with equal operand values produce equal results, so a
+ *   second one can read the first one's register instead. False for anything reading the record or
+ *   the RNG.
+ * @property {boolean} broadcasts every lane of the destination holds the same value, by construction
+ *   rather than by what the operands happen to be. Lane `i` is then a copy of lane 0 and may be read
+ *   as one.
+ * @property {boolean} foldable the JS reference and the WGSL interpreter are both obliged to produce
+ *   the *same bits* for this operation, so evaluating it here and baking a constant changes nothing
+ *   on either. Correctly-rounded IEEE arithmetic qualifies; a transcendental does not — JS
+ *   `Math.sin` and a GPU's `sin` agree to about a part in 10^7, which is what the parity spec's
+ *   tolerance is for, and folding would quietly pick the CPU's answer for the GPU.
+ */
+
+/** @type {Map<number, ParticleOpSemantics>} */
+export const VM_SEMANTICS = new Map();
+
+/**
+ * @param {number} op
+ * @param {Partial<ParticleOpSemantics>} flags
+ */
+function semantics(op, flags) {
+    VM_SEMANTICS.set(op, {
+        side_effects: false,
+        lanewise: false,
+        narrowable: false,
+        shareable: false,
+        broadcasts: false,
+        foldable: false,
+        ...flags,
+    });
+}
+
+/** Pure element-wise arithmetic whose two executors are bit-for-bit obliged to agree. */
+const EXACT = { lanewise: true, narrowable: true, shareable: true, foldable: true };
+
+/** The same, minus the folding: correct to narrow and to share, but the executors may round apart. */
+const INEXACT = { lanewise: true, narrowable: true, shareable: true };
+
+semantics(VM_OP.HALT, { side_effects: true });
+semantics(VM_OP.NOP, {});
+semantics(VM_OP.MOV, EXACT);
+semantics(VM_OP.LOAD_CONST, EXACT);
+// Reads the record, so it is removable when dead but may not be shared across a store that could
+// touch the same words — which is why it is not `shareable` and the CSE pass never sees it.
+semantics(VM_OP.LOAD_ATTR, { lanewise: true, narrowable: true });
+semantics(VM_OP.STORE_ATTR, { side_effects: true });
+semantics(VM_OP.LOAD_BUILTIN, { lanewise: true, narrowable: true, shareable: true });
+semantics(VM_OP.KILL, { side_effects: true });
+
+semantics(VM_OP.ADD, EXACT);
+semantics(VM_OP.SUB, EXACT);
+semantics(VM_OP.MUL, EXACT);
+semantics(VM_OP.DIV, EXACT);
+// `a * b + c` is one rounding on hardware that contracts it into an FMA and two in the reference.
+semantics(VM_OP.MAD, INEXACT);
+semantics(VM_OP.MIN, EXACT);
+semantics(VM_OP.MAX, EXACT);
+// The reference spells it `a + (b - a) * t`; WGSL's `mix` is free to round it differently.
+semantics(VM_OP.MIX, INEXACT);
+semantics(VM_OP.CLAMP, EXACT);
+semantics(VM_OP.SCALE, EXACT);
+
+semantics(VM_OP.NEG, EXACT);
+semantics(VM_OP.ABS, EXACT);
+semantics(VM_OP.FLOOR, EXACT);
+semantics(VM_OP.FRACT, EXACT);
+semantics(VM_OP.SQRT, EXACT);
+semantics(VM_OP.SIN, INEXACT);
+semantics(VM_OP.COS, INEXACT);
+semantics(VM_OP.EXP, INEXACT);
+semantics(VM_OP.LOG, INEXACT);
+semantics(VM_OP.POW, INEXACT);
+semantics(VM_OP.STEP, EXACT);
+semantics(VM_OP.SMOOTHSTEP, INEXACT);
+
+// The reductions read every lane to write one, so there are no trailing lanes to drop.
+semantics(VM_OP.DOT, { shareable: true });
+// Three lanes of cross product plus, optionally, the zero `w`. Dropping that `w` is the one
+// narrowing available, and `min_width` already floors it at three.
+semantics(VM_OP.CROSS, { narrowable: true, shareable: true });
+semantics(VM_OP.LENGTH, { shareable: true });
+semantics(VM_OP.NORMALIZE, { shareable: true });
+semantics(VM_OP.DISTANCE, { shareable: true });
+// Lane-MAPPED rather than lanewise: output lane `i` is source lane `pattern[i]`.
+semantics(VM_OP.SWIZZLE, { narrowable: true, shareable: true, foldable: true });
+
+semantics(VM_OP.CMP_LT, EXACT);
+semantics(VM_OP.CMP_LE, EXACT);
+semantics(VM_OP.CMP_GT, EXACT);
+semantics(VM_OP.CMP_GE, EXACT);
+semantics(VM_OP.CMP_EQ, EXACT);
+semantics(VM_OP.SELECT, EXACT);
+
+// Ordered and side-effecting: it advances the shared RNG, and its width IS the number of draws it
+// takes. Removing, duplicating, reordering or narrowing one moves every value drawn after it.
+semantics(VM_OP.RANDOM, { side_effects: true });
+// An external WGSL symbol, but a pure function of (handle, t) — so a dead one goes and a repeated
+// one is shared. Every lane of the result is the same sample, which is what makes it narrowable —
+// and what makes it a broadcast, so a consumer reading it wide is a consumer that wants `SCALE`.
+semantics(VM_OP.CURVE, { lanewise: true, narrowable: true, shareable: true, broadcasts: true });
+
+/**
+ * What may be assumed about an opcode. An unknown one is assumed to do everything, so a new opcode
+ * is inert to the optimizer until somebody adds it to the table above.
+ *
+ * @param {number} op
+ * @returns {ParticleOpSemantics}
+ */
+export function vm_semantics_of(op) {
+    return VM_SEMANTICS.get(op) ?? {
+        side_effects: true,
+        lanewise: false,
+        narrowable: false,
+        shareable: false,
+        broadcasts: false,
+        foldable: false,
+    };
+}
+
+/**
+ * Which lane of a source operand feeds a given output lane.
+ *
+ * A scalar operand feeds every output lane from lane 0, a `SWIZZLE` reads the lane its pattern
+ * names, and everything lanewise reads straight across.
+ *
+ * @param {number} op
+ * @param {number} lane output lane
+ * @param {boolean} is_scalar whether the ISA marks this source slot scalar
+ * @param {number} pattern packed swizzle pattern, read only for `SWIZZLE`
+ * @returns {number} lane of the source operand read into `lane`
+ */
+export function vm_source_lane(op, lane, is_scalar, pattern) {
+    if (is_scalar) {
+        return 0;
+    }
+
+    if (op === VM_OP.SWIZZLE) {
+        return (pattern >> (2 * lane)) & 3;
+    }
+
+    return lane;
+}
+
+/**
+ * Rewrite a swizzle pattern so its lanes past `width` name nothing new.
+ *
+ * A pattern's four selectors are read whatever the instruction's width, so a narrowed broadcast
+ * still reaches as far as its widest selector — {@link swizzle_span} counts all four. Pointing the
+ * unused ones at lane 0's selector shrinks the source run to what the live lanes actually read,
+ * which is what frees the slots above it.
+ *
+ * @param {number} pattern
+ * @param {number} width lanes the instruction still writes
+ * @returns {number} a pattern equivalent at that width
+ */
+export function vm_trim_swizzle(pattern, width) {
+    const first = pattern & 3;
+
+    let out = 0;
+
+    for (let lane = 0; lane < VM_MAX_WIDTH; lane++) {
+        const selector = lane < width ? (pattern >> (2 * lane)) & 3 : first;
+
+        out |= selector << (2 * lane);
+    }
+
+    return out >>> 0;
+}
+
+/**
+ * How far into its source a swizzle reaches once trimmed to `width`.
+ *
+ * @param {number} pattern
+ * @param {number} width
+ * @returns {number}
+ */
+export function vm_trimmed_swizzle_span(pattern, width) {
+    return swizzle_span(vm_trim_swizzle(pattern, width));
+}

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

@@ -0,0 +1,11 @@
+/**
+ * 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: ArrayLike<ArrayLike<number>>, visit: (arg0: number, arg1: number, arg2: number) => void): void;
+export function pass_dedup_constants(instructions: number[][], context: import("./optimize_particle_program.js").ParticleOptimizerContext): number[][];
+/** @type {string} */
+export const PARTICLE_PASS_DEDUP_CONSTANTS: string;
+//# sourceMappingURL=pass_dedup_constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pass_dedup_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_dedup_constants.js"],"names":[],"mappings":"AA+GA;;;;;GAKG;AACH,4DAHW,UAAU,UAAU,MAAM,CAAC,CAAC,gBACnB,MAAM,QAAE,MAAM,QAAE,MAAM,KAAG,IAAI,QAWhD;AA1E+B,uJAKkB;AAvDlD,qBAAqB;AACrB,4CADW,MAAM,CAC8C"}

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

@@ -0,0 +1,197 @@
+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;
+}

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

@@ -0,0 +1,4 @@
+export function pass_eliminate_dead_code(instructions: number[][], context: import("./optimize_particle_program.js").ParticleOptimizerContext): number[][];
+/** @type {string} */
+export const PARTICLE_PASS_DEAD_CODE: string;
+//# sourceMappingURL=pass_eliminate_dead_code.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,51 @@
+import { analyze_particle_lanes, decode_particle_instructions } from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_DEAD_CODE = "dead_code";
+
+/**
+ * Drop instructions that cannot affect the program's meaning: the ones nothing reads, and the ones
+ * that never run.
+ *
+ * A program means the record it leaves, the kill flag it sets and the RNG state it ends on.
+ * Registers do not survive the section, so an instruction whose every written lane goes unread — and
+ * which does nothing else on the way — could not have been observed. `NOP` is the degenerate case
+ * and goes for the same reason.
+ *
+ * What stays whatever its result:
+ *
+ * - `RANDOM`, always. It advances the shared RNG, so a draw nobody reads still moves every draw
+ *   after it. This is the one place where "the result is dead" and "the instruction is dead" come
+ *   apart, and getting it wrong would not fail loudly — it would quietly reseed the effect.
+ * - `STORE_ATTR` and `KILL`, which are the program's output.
+ * - `LOAD_ATTR` is removable when dead; it reads the record but changes nothing.
+ *
+ * Deadness is transitive in one backward sweep, because {@link analyze_particle_lanes} walks in
+ * reverse and a dead instruction contributes none of its reads: the sole consumer of a value being
+ * dead makes its producer dead in the same pass, however long the chain.
+ *
+ * ## Unreachable code
+ *
+ * A `HALT` returns, so everything after the first one is deleted — and the `HALT` is then the last
+ * instruction in the section, which is where execution stops anyway, so it goes too. Both executors
+ * run exactly `instruction_count` instructions and neither needs a terminator.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_eliminate_dead_code(instructions, context) {
+    const decoded = decode_particle_instructions(instructions);
+    const { keep, halt_index } = analyze_particle_lanes(decoded, context.register_slots);
+
+    const end = halt_index >= 0 ? halt_index : instructions.length;
+
+    /** @type {number[][]} */
+    const out = [];
+
+    for (let i = 0; i < end; i++) {
+        if (keep[i]) {
+            out.push(instructions[i]);
+        }
+    }
+
+    return out.length === instructions.length ? null : out;
+}

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

@@ -0,0 +1,4 @@
+export function pass_fold_constants(instructions: number[][], context: import("./optimize_particle_program.js").ParticleOptimizerContext): number[][];
+/** @type {string} */
+export const PARTICLE_PASS_FOLD_CONSTANTS: string;
+//# sourceMappingURL=pass_fold_constants.d.ts.map

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

@@ -0,0 +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"}