@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,86 @@
+import { decode_particle_instructions, particle_instruction_is_well_formed } from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_PACK_REGISTERS = "pack_registers";
+
+/**
+ * Close the holes the other passes left in the register file.
+ *
+ * Everything before this frees slots without moving anything into them: dead code takes whole values
+ * out of the middle of the file, narrowing takes the top lanes off the ones that remain, and both
+ * leave the survivors exactly where the frontend's allocator put them. The declared register count
+ * is then the high-water mark of a file that is mostly gaps — and the count is what the interpreter
+ * actually pays for, since `vm_reg` is a `var<private>` array indexed dynamically and its size sets
+ * the shader's register footprint outright (see the occupancy note in `vm/chunk_particle_vm.js`).
+ *
+ * ## Why it is a compaction and not a re-allocation
+ *
+ * Registers are not in SSA form: a slot is written, read, and written again by something unrelated,
+ * and two values that never overlap in time may already be sharing one. Reassigning slots by live
+ * range would mean reconstructing what the frontend's allocator knew and discarding what it decided.
+ *
+ * Deleting the slots nothing touches at all needs none of that, and is safe by construction. The
+ * remap is order-preserving and injective over used slots, so every operand run — whose slots are
+ * all used, by definition of being an operand — stays contiguous and keeps its length; two runs that
+ * named the same slots still do, and two that were disjoint still are. Nothing about the operand
+ * overlap rule can be broken by squeezing out slots that appear in no operand at all.
+ *
+ * A slot read but never written stays in the file, holding the zero the reset gave it.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_pack_registers(instructions, context) {
+    const decoded = decode_particle_instructions(instructions);
+    const slots = context.register_slots;
+    const used = new Uint8Array(slots);
+
+    for (const instruction of decoded) {
+        const runs = instruction.write === null ? instruction.reads : [instruction.write, ...instruction.reads];
+
+        for (const run of runs) {
+            for (let lane = 0; lane < run.span; lane++) {
+                if (run.base + lane < slots) {
+                    used[run.base + lane] = 1;
+                }
+            }
+        }
+    }
+
+    const remap = new Int32Array(slots).fill(-1);
+
+    let next = 0;
+    let moved = false;
+
+    for (let slot = 0; slot < slots; slot++) {
+        if (used[slot]) {
+            moved = moved || next !== slot;
+            remap[slot] = next++;
+        }
+    }
+
+    if (!moved) {
+        return null;
+    }
+
+    /** @type {number[][]} */
+    const out = [];
+
+    for (const instruction of decoded) {
+        const words = instruction.words.slice();
+        const runs = instruction.write === null ? instruction.reads : [instruction.write, ...instruction.reads];
+
+        for (const run of runs) {
+            // The destination slot carries a register for value-producing opcodes and a source for
+            // `STORE_ATTR` and `KILL`; either way it is word 1, and a source operand is word 2 + n.
+            words[run.operand < 0 ? 1 : 2 + run.operand] = remap[run.base];
+        }
+
+        if (!particle_instruction_is_well_formed(words)) {
+            return null;
+        }
+
+        out.push(words);
+    }
+
+    return out;
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"pass_peephole.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_peephole.js"],"names":[],"mappings":"AAsF6C,gJAO1B;AApFnB,qBAAqB;AACrB,qCADW,MAAM,CACgC"}

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

@@ -0,0 +1,271 @@
+import { VM_MAX_WIDTH, VM_OP, vm_encode_word0 } from "../isa/ParticleVMISA.js";
+import {
+    ParticleValueNumbering,
+    decode_particle_instructions,
+    particle_instruction_is_well_formed,
+    particle_run_is_dead_after,
+    particle_run_is_touched_between,
+} from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_PEEPHOLE = "peephole";
+
+/**
+ * Local rewrites over a couple of neighbouring instructions — the ones that need no analysis beyond
+ * "these two are really one".
+ *
+ * ## Constant loads
+ *
+ * A frontend emits one load per literal, because it lowers one value at a time. Where two of them
+ * land in adjacent registers from adjacent pool words, they are one load: the pool is addressed by
+ * word, so a two-word run is as loadable as a one-word one. The graph compiler's `mad` node — a
+ * multiplier and an addend, interned side by side — is exactly this shape.
+ *
+ * ## Multiplying by a broadcast
+ *
+ * `MUL` against a value whose every lane is the same is `SCALE`, which reads one lane and takes the
+ * broadcast out of the program. Widening a scalar to meet a wider operation is the compiler's
+ * standard move, and `SCALE` is the opcode that exists so it does not have to.
+ *
+ * ## Fusing a multiply and an add — off by default
+ *
+ * `MUL` then `ADD` is `MAD`, one instruction rather than two. It is also, unavoidably, a DIFFERENT
+ * NUMBER: the pair rounds the product to `f32` before adding, and `MAD` does not — and on hardware
+ * that contracts it into an FMA, does not round it at all. That is the ordinary compiler trade and
+ * it is a perfectly reasonable one to take for a particle effect, but it is not the bit-identity the
+ * rest of this optimizer holds itself to, so it is a switch rather than a default:
+ * `{ passes: { peephole: { fuse_multiply_add: true } } }`.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_peephole(instructions, context) {
+    const options = {
+        merge_constant_loads: true,
+        multiply_by_broadcast: true,
+        fuse_multiply_add: false,
+        ...context,
+    };
+
+    let current = instructions;
+    let changed = false;
+
+    if (options.multiply_by_broadcast) {
+        const result = scale_by_broadcast(current, context.register_slots);
+
+        if (result !== null) {
+            current = result;
+            changed = true;
+        }
+    }
+
+    for (const rewrite of [
+        options.merge_constant_loads ? merge_one_constant_load : null,
+        options.fuse_multiply_add ? fuse_one_multiply_add : null,
+    ]) {
+        if (rewrite === null) {
+            continue;
+        }
+
+        // Applied one at a time and re-derived: each rewrite deletes an instruction, and re-deriving
+        // a program of this size is cheaper than keeping indices and liveness honest across a splice.
+        for (let attempt = 0; attempt < instructions.length; attempt++) {
+            const result = rewrite(current);
+
+            if (result === null) {
+                break;
+            }
+
+            current = result;
+            changed = true;
+        }
+    }
+
+    return changed ? current : null;
+}
+
+/**
+ * `MUL` by a value whose lanes all hold the same number is `SCALE` of the register that number came
+ * from — which usually leaves the broadcast that widened it dead.
+ *
+ * @param {number[][]} instructions
+ * @param {number} slots
+ * @returns {number[][]|null}
+ */
+function scale_by_broadcast(instructions, slots) {
+    const decoded = decode_particle_instructions(instructions);
+    const values = new ParticleValueNumbering(slots);
+
+    /** @type {number[][]} */
+    const out = [];
+
+    let changed = false;
+
+    for (const instruction of decoded) {
+        let words = instruction.words;
+
+        if (instruction.op === VM_OP.MUL && instruction.operation_width > 1) {
+            // Either operand may be the broadcast one; `SCALE` keeps the vector in slot 0.
+            const candidate = as_scale(instruction, instruction.reads[1], instruction.reads[0], values)
+                ?? as_scale(instruction, instruction.reads[0], instruction.reads[1], values);
+
+            if (candidate !== null) {
+                words = candidate;
+                changed = true;
+            }
+        }
+
+        out.push(words);
+        values.publish(words);
+    }
+
+    return changed ? out : null;
+}
+
+/**
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {import("./particle_program_analysis.js").ParticleOperandRun} broadcast the operand hoped
+ *   to hold one value across every lane
+ * @param {import("./particle_program_analysis.js").ParticleOperandRun} vector the other one
+ * @param {ParticleValueNumbering} values
+ * @returns {number[]|null}
+ */
+function as_scale(instruction, broadcast, vector, values) {
+    const ids = values.ids_of(broadcast.base, broadcast.span);
+
+    if (ids === null || ids.some(id => id !== ids[0])) {
+        return null;
+    }
+
+    // The lane the value was computed in, which is the single slot SCALE will read.
+    const scalar = values.origin_of(broadcast.base, 1);
+
+    if (scalar < 0) {
+        return null;
+    }
+
+    const words = [
+        vm_encode_word0(VM_OP.SCALE, instruction.width),
+        instruction.write.base,
+        vector.base,
+        scalar,
+        0,
+    ];
+
+    return particle_instruction_is_well_formed(words) ? words : null;
+}
+
+/**
+ * Two constant loads that fill adjacent registers from adjacent pool words are one load.
+ *
+ * @param {number[][]} instructions
+ * @returns {number[][]|null}
+ */
+function merge_one_constant_load(instructions) {
+    const decoded = decode_particle_instructions(instructions);
+
+    for (let first = 0; first < decoded.length; first++) {
+        const a = decoded[first];
+
+        if (a.op !== VM_OP.LOAD_CONST) {
+            continue;
+        }
+
+        for (let second = first + 1; second < decoded.length; second++) {
+            const b = decoded[second];
+
+            if (b.op === VM_OP.HALT) {
+                break;
+            }
+
+            if (b.op !== VM_OP.LOAD_CONST
+                || b.words[1] !== a.words[1] + a.operation_width
+                || b.words[2] !== a.words[2] + a.operation_width
+                || a.operation_width + b.operation_width > VM_MAX_WIDTH) {
+                continue;
+            }
+
+            const base = a.words[1];
+            const span = a.operation_width + b.operation_width;
+
+            // The second load moves back to the first one's position, so nothing in between may
+            // read or write either register run.
+            if (particle_run_is_touched_between(decoded, first + 1, second, base, span)) {
+                continue;
+            }
+
+            const words = [vm_encode_word0(VM_OP.LOAD_CONST, span), base, a.words[2], 0, 0];
+
+            if (!particle_instruction_is_well_formed(words)) {
+                continue;
+            }
+
+            const out = instructions.slice();
+
+            out[first] = words;
+            out.splice(second, 1);
+
+            return out;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * `MUL` into a register that the very next instruction adds to something is `MAD`.
+ *
+ * Adjacent only: the pair is what a frontend emits for `a * b + c`, and looking further would buy
+ * little for a rewrite that is off by default anyway.
+ *
+ * @param {number[][]} instructions
+ * @returns {number[][]|null}
+ */
+function fuse_one_multiply_add(instructions) {
+    const decoded = decode_particle_instructions(instructions);
+
+    for (let i = 0; i + 1 < decoded.length; i++) {
+        const multiply = decoded[i];
+        const add = decoded[i + 1];
+
+        if (multiply.op !== VM_OP.MUL || add.op !== VM_OP.ADD || multiply.width !== add.width) {
+            continue;
+        }
+
+        const product = multiply.write.base;
+        const span = multiply.write.span;
+
+        // The addend is whichever operand of the ADD is not the product.
+        const addend = add.reads.find(read => read.base !== product);
+        const uses_product = add.reads.some(read => read.base === product);
+
+        if (!uses_product || addend === undefined) {
+            continue;
+        }
+
+        // The product must be nobody else's: the MAD does not leave it in a register.
+        if (product !== add.write.base && !particle_run_is_dead_after(decoded, i + 1, product, span)) {
+            continue;
+        }
+
+        const words = [
+            vm_encode_word0(VM_OP.MAD, multiply.width),
+            add.write.base,
+            multiply.reads[0].base,
+            multiply.reads[1].base,
+            addend.base,
+        ];
+
+        if (!particle_instruction_is_well_formed(words)) {
+            continue;
+        }
+
+        const out = instructions.slice();
+
+        out[i] = words;
+        out.splice(i + 1, 1);
+
+        return out;
+    }
+
+    return null;
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"pass_propagate_copies.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_propagate_copies.js"],"names":[],"mappings":"AA2EsC,wJAStB;AA1EhB,qBAAqB;AACrB,6CADW,MAAM,CACgD"}

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

@@ -0,0 +1,268 @@
+import { VM_OP, vm_decode_op, vm_encode_word0 } from "../isa/ParticleVMISA.js";
+import {
+    ParticleValueNumbering,
+    decode_particle_instructions,
+    particle_instruction_is_well_formed,
+    particle_run_is_dead_after,
+    particle_run_is_touched_between,
+    particle_runs_overlap,
+} from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_PROPAGATE_COPIES = "propagate_copies";
+
+/**
+ * Get rid of copies — by reading past them where the original is still intact, and by having the
+ * instruction that produced the value write where the copy was going.
+ *
+ * Copies are most of what a broadcast is. The node compiler widens a scalar with a `SWIZZLE` because
+ * some consumer asked for four lanes; when the lanes that survive are the ones the scalar was
+ * already in, the broadcast is a register renaming and nothing else.
+ *
+ * ## Reading past a copy
+ *
+ * Every write gives its lanes a fresh value number and records the slot the value was ORIGINALLY
+ * computed in; a copy inherits both. A read of a run can then be redirected to that original, as
+ * long as the original still holds it — which is exactly "the value numbers still match", so a slot
+ * overwritten since fails the test rather than needing a separate invalidation.
+ *
+ * A run is redirected only when its lanes trace back to CONSECUTIVE original slots. Two lanes of a
+ * broadcast trace back to the same one, which is not a run and stays where it is.
+ *
+ * ## Writing where the copy was going
+ *
+ * `MOV d, s` where `s` was produced by one instruction, read by nothing but this copy, and dead
+ * afterwards is that instruction writing to the wrong register. Retargeting it and dropping the copy
+ * is what turns the graph compiler's broadcast-and-select into the two-lane value hand-written
+ * assembly would have built directly.
+ *
+ * The conditions are the obvious ones and all of them are checked: nothing between the producer and
+ * the copy may read the source or touch the destination, nothing after may read the source, and the
+ * retargeted instruction still has to satisfy the operand-overlap rule. Retargeting a `RANDOM` is
+ * allowed — where its result lands is not part of the draw sequence.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_propagate_copies(instructions, context) {
+    const rounds = context.max_iterations ?? 3;
+
+    let current = instructions;
+    let changed = false;
+
+    for (let round = 0; round < rounds; round++) {
+        const redirected = redirect_reads(current, context);
+        const forwarded = forward_destinations(redirected ?? current);
+
+        if (redirected === null && forwarded === null) {
+            break;
+        }
+
+        current = forwarded ?? redirected;
+        changed = true;
+    }
+
+    return changed ? current : null;
+}
+
+/**
+ * Rewrite reads to name the slot the value was first computed in, and reduce the copies that are
+ * spelled as something else — an identity `SWIZZLE` is a `MOV`, and a `MOV` onto its own source is
+ * nothing at all.
+ *
+ * @param {number[][]} instructions
+ * @param {object} context
+ * @returns {number[][]|null}
+ */
+function redirect_reads(instructions, context) {
+    const decoded = decode_particle_instructions(instructions);
+    const values = new ParticleValueNumbering(context.register_slots);
+
+    /** @type {number[][]} */
+    const out = [];
+
+    let changed = false;
+
+    for (const instruction of decoded) {
+        let words = instruction.words;
+
+        for (const read of instruction.reads) {
+            const candidate = redirect(words, read, values);
+
+            if (candidate !== null) {
+                words = candidate;
+                changed = true;
+            }
+        }
+
+        const reduced = reduce_copy(words, instruction);
+
+        if (reduced !== null) {
+            words = reduced;
+            changed = true;
+        }
+
+        // A copy of a register onto itself is nothing at all — and it is not something the dead-code
+        // pass can see, because the lanes it writes are live; they were simply already correct.
+        if (vm_decode_op(words[0]) === VM_OP.MOV && words[1] === words[2]) {
+            changed = true;
+        } else {
+            out.push(words);
+        }
+
+        values.publish(words);
+    }
+
+    return changed ? out : null;
+}
+
+/**
+ * @returns {number[]|null} the instruction with this read redirected, or `null` to leave it
+ */
+function redirect(words, read, values) {
+    const base = values.origin_of(read.base, read.span);
+
+    if (base < 0 || base === read.base) {
+        return null;
+    }
+
+    const candidate = words.slice();
+
+    candidate[read.operand < 0 ? 1 : 2 + read.operand] = base;
+
+    // Moving one operand changes how it sits against the others, and two runs of an instruction may
+    // name the same slots or none of the same ones.
+    return particle_instruction_is_well_formed(candidate) ? candidate : null;
+}
+
+/**
+ * An identity `SWIZZLE` is a `MOV`, and a `MOV` whose destination is its source is nothing.
+ *
+ * @returns {number[]|null} the reduced instruction, `null` if there is nothing to reduce
+ */
+function reduce_copy(words, instruction) {
+    const op = instruction.op;
+
+    if (op === VM_OP.SWIZZLE) {
+        for (let lane = 0; lane < instruction.operation_width; lane++) {
+            if (((words[3] >> (2 * lane)) & 3) !== lane) {
+                return null;
+            }
+        }
+
+        const candidate = [vm_encode_word0(VM_OP.MOV, instruction.width), words[1], words[2], 0, 0];
+
+        return particle_instruction_is_well_formed(candidate) ? candidate : null;
+    }
+
+    return null;
+}
+
+/**
+ * Have the producer write where its copy was going.
+ *
+ * Applied one at a time and re-derived, because a forward changes what the next one is looking at:
+ * a chain of copies collapses from the far end, and the analysis it needs is cheap enough that
+ * keeping it incrementally honest would cost more than redoing it.
+ *
+ * @param {number[][]} instructions
+ * @returns {number[][]|null}
+ */
+function forward_destinations(instructions) {
+    let current = instructions;
+    let changed = false;
+
+    for (let attempt = 0; attempt < instructions.length; attempt++) {
+        const next = forward_one_destination(current);
+
+        if (next === null) {
+            break;
+        }
+
+        current = next;
+        changed = true;
+    }
+
+    return changed ? current : null;
+}
+
+/**
+ * @param {number[][]} instructions
+ * @returns {number[][]|null}
+ */
+function forward_one_destination(instructions) {
+    const decoded = decode_particle_instructions(instructions);
+
+    for (let copy = 0; copy < decoded.length; copy++) {
+        const move = decoded[copy];
+
+        if (move.op !== VM_OP.MOV) {
+            continue;
+        }
+
+        const destination = move.write.base;
+        const source = move.reads[0].base;
+        const span = move.write.span;
+
+        if (destination === source) {
+            continue;
+        }
+
+        const producer = sole_producer(decoded, copy, source, span);
+
+        if (producer < 0
+            || particle_run_is_touched_between(decoded, producer + 1, copy, destination, span)
+            || !particle_run_is_dead_after(decoded, copy, source, span)) {
+            continue;
+        }
+
+        const words = decoded[producer].words.slice();
+
+        words[1] = destination;
+
+        if (!particle_instruction_is_well_formed(words)) {
+            continue;
+        }
+
+        const out = instructions.slice();
+
+        out[producer] = words;
+        out.splice(copy, 1);
+
+        return out;
+    }
+
+    return null;
+}
+
+/**
+ * The one instruction that put the value in `[base, base + span)`, if it is the only writer, wrote
+ * exactly that run, and nothing between it and `copy` read it.
+ *
+ * @returns {number} instruction index, or `-1`
+ */
+function sole_producer(decoded, copy, base, span) {
+    for (let i = copy - 1; i >= 0; i--) {
+        const instruction = decoded[i];
+
+        // A HALT in between means the copy never runs; that is the dead-code pass's to sort out.
+        if (instruction.op === VM_OP.HALT) {
+            return -1;
+        }
+
+        // The write is checked first so a producer that reads the run it writes — `SIN r0, r0`, the
+        // in-place form the register allocator reaches for constantly — is recognised as the
+        // producer rather than rejected as an intervening reader of its own result.
+        if (instruction.write !== null
+            && particle_runs_overlap(instruction.write.base, instruction.write.span, base, span)) {
+            return instruction.write.base === base && instruction.write.span === span ? i : -1;
+        }
+
+        for (const read of instruction.reads) {
+            if (particle_runs_overlap(read.base, read.span, base, span)) {
+                return -1;
+            }
+        }
+    }
+
+    return -1;
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"pass_share_subexpressions.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_share_subexpressions.js"],"names":[],"mappings":"AA0E6E,4JAGoC;AAtEjH,qBAAqB;AACrB,iDADW,MAAM,CACwD"}