@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,361 @@
+import { VM_KIND, VM_OP, vm_operand_with_base, vm_register, vm_repack_instruction, vm_with_dst } from "../isa/ParticleVMISA.js";
+import {
+    ParticleValueNumbering,
+    decode_particle_instructions,
+    particle_instruction_is_well_formed,
+    particle_read_slots,
+    particle_run_is_dead_after,
+    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 `MOV` through
+ * `.xxxx` because some consumer asked for four lanes; when the consumer can read the scalar through
+ * that same swizzle, the copy 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, through whatever swizzle it read its source with. A read can
+ * then be redirected to where its lanes' values live, as long as the originals still hold them —
+ * which is exactly "the value numbers still match", so a slot overwritten since fails the test rather
+ * than needing a separate invalidation. The redirected operand names the homes through a swizzle of
+ * its own, so a permutation, a broadcast and a plain copy are all read through alike: `MUL r0, r1,
+ * r2` where r2 is `r5.xxxx` becomes `MUL r0, r1, r5.xxxx`, and the broadcast is then dead.
+ *
+ * ## 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, and nothing after may read the source.
+ * Retargeting a `RANDOM` is allowed — where its result lands is not part of the draw sequence.
+ *
+ * ## Copies spelled as something else
+ *
+ * A lane picked out of a vector — `MOV.1 r4, r0.y` — is the run at `r1`, and the assembler spells
+ * every operand canonically, so the pass never sees the difference. What is left to reduce here is
+ * a `MOV` of a register onto itself, which is nothing at all.
+ *
+ * @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 slots their values were first computed in, and drop a `MOV` of a
+ * register onto itself.
+ *
+ * @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;
+            }
+        }
+
+        // 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 (is_copy_onto_itself(words, instruction)) {
+            changed = true;
+        } else {
+            out.push(words);
+        }
+
+        values.publish(words);
+    }
+
+    return changed ? out : null;
+}
+
+/**
+ * @param {number[]} words the instruction as it stands after redirection
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @returns {boolean} whether it is a `MOV` reading its own destination run as it lies
+ */
+function is_copy_onto_itself(words, instruction) {
+    return instruction.op === VM_OP.MOV
+        && instruction.sources[0].kind === VM_KIND.REG
+        && words[1] === vm_register(instruction.dst);
+}
+
+/**
+ * @returns {number[]|null} the instruction with this read redirected, or `null` to leave it
+ */
+function redirect(words, read, values) {
+    const origin = values.origin_of_read(read);
+
+    if (origin < 0) {
+        return null;
+    }
+
+    const candidate = words.slice();
+
+    candidate[1 + read.operand] = origin;
+
+    const repacked = vm_repack_instruction(candidate);
+
+    if (repacked[1 + read.operand] === words[1 + read.operand]) {
+        return null;
+    }
+
+    return particle_instruction_is_well_formed(repacked) ? repacked : 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];
+
+        // Only a plain copy of a register run has producers to retarget: a swizzled one reorders
+        // lanes the producers computed in order, and a MOV from a literal is a load, which the
+        // inlining pass deals with.
+        if (move.op !== VM_OP.MOV || move.sources[0].kind !== VM_KIND.REG) {
+            continue;
+        }
+
+        const source = move.sources[0];
+
+        if (source.word !== vm_register(source.base)) {
+            continue;
+        }
+
+        const destination = move.write.base;
+        const span = move.write.span;
+
+        // Overlapping runs would have the producers shift into each other's lanes; a copy of that
+        // shape is what a swizzle is for, and not worth the bookkeeping.
+        if (particle_runs_overlap(destination, span, source.base, span)) {
+            continue;
+        }
+
+        const plan = plan_forwarding(decoded, copy, source.base, span, destination);
+
+        if (plan === null) {
+            continue;
+        }
+
+        const out = instructions.slice();
+
+        for (const [index, words] of plan) {
+            out[index] = words;
+        }
+
+        out.splice(copy, 1);
+
+        return out;
+    }
+
+    return null;
+}
+
+/**
+ * How to have the producers of `[base, base + span)` write into `[destination, ...)` instead, so the
+ * copy at `copy` can go.
+ *
+ * Each lane has a producer — the last write to it before the copy — and every producer has to write
+ * within the run, so that moving it by `destination - base` moves lanes and nothing else. From the
+ * earliest producer to the copy, nothing may touch the destination: not a write, since the value is
+ * now being built there, and not a read, since what it read was the destination's old contents. A
+ * read of the source in that gap is a read of the value on its way to the copy and follows it to the
+ * destination — unless it comes before the producer of a lane it reads, in which case it wanted what
+ * the slot held before and stays as it is. A read that is half one and half the other is left
+ * alone, and so is the whole copy. After the copy, the source has to be dead.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction[]} decoded
+ * @param {number} copy index of the `MOV`
+ * @param {number} base first slot of the source run
+ * @param {number} span
+ * @param {number} destination first slot of the destination run
+ * @returns {Array<[number, number[]]>|null} rewritten instructions by index, or `null` to leave the copy
+ */
+function plan_forwarding(decoded, copy, base, span, destination) {
+    /** @type {Int32Array} per lane, the instruction that produced it; `-1` until found */
+    const producer = new Int32Array(span).fill(-1);
+
+    let unproduced = span;
+
+    for (let i = copy - 1; i >= 0 && unproduced > 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 null;
+        }
+
+        const write = instruction.write;
+
+        if (write === null || !particle_runs_overlap(write.base, write.span, base, span)) {
+            continue;
+        }
+
+        if (write.base < base || write.base + write.span > base + span) {
+            return null;
+        }
+
+        for (let lane = write.base - base; lane < write.base - base + write.span; lane++) {
+            if (producer[lane] < 0) {
+                producer[lane] = i;
+                unproduced--;
+            }
+        }
+    }
+
+    if (unproduced > 0) {
+        return null;
+    }
+
+    const earliest = Math.min(...producer);
+
+    /** @type {Map<number, number[]>} instruction index -> its rewritten words */
+    const rewritten = new Map();
+
+    const words_of = (index) => {
+        if (!rewritten.has(index)) {
+            rewritten.set(index, decoded[index].words.slice());
+        }
+
+        return rewritten.get(index);
+    };
+
+    for (let i = earliest + 1; i < copy; i++) {
+        const instruction = decoded[i];
+
+        if (instruction.op === VM_OP.HALT) {
+            return null;
+        }
+
+        if (instruction.write !== null
+            && particle_runs_overlap(instruction.write.base, instruction.write.span, destination, span)) {
+            return null;
+        }
+
+        for (const read of instruction.reads) {
+            if (particle_runs_overlap(read.base, read.span, destination, span)) {
+                return null;
+            }
+
+            const slots = particle_read_slots(read);
+            const inside = slots.filter(slot => slot >= base && slot < base + span);
+
+            if (inside.length === 0) {
+                continue;
+            }
+
+            if (inside.length !== slots.length) {
+                return null;
+            }
+
+            const produced = slots.filter(slot => producer[slot - base] < i).length;
+
+            if (produced === 0) {
+                continue;
+            }
+
+            if (produced !== slots.length) {
+                return null;
+            }
+
+            words_of(i)[1 + read.operand] = vm_operand_with_base(read.word, read.base - base + destination);
+        }
+    }
+
+    if (!particle_run_is_dead_after(decoded, copy, base, span)) {
+        return null;
+    }
+
+    for (const index of new Set(producer)) {
+        const words = words_of(index);
+
+        words[0] = vm_with_dst(words[0], decoded[index].write.base - base + destination);
+    }
+
+    const plan = [];
+
+    for (const [index, words] of rewritten) {
+        if (!particle_instruction_is_well_formed(words)) {
+            return null;
+        }
+
+        plan.push([index, words]);
+    }
+
+    return plan;
+}

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

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

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

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

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

@@ -0,0 +1,244 @@
+import { decode_particle_instructions, particle_peak_live_slots, particle_read_slots } from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_SCHEDULE = "schedule";
+
+/**
+ * Reorder the instructions so that fewer values are alive at once.
+ *
+ * A frontend lowers in whatever order it visits, and the node compiler's order is the graph's: a
+ * constant is loaded where the graph mentions it and a corner offset is computed alongside the
+ * others, both a long way above their one consumer. Every instruction in between then carries that
+ * value in the file. The register allocator can only reuse slots whose values have died, so a
+ * value that lives longer than it needs to is a slot the allocator cannot give back — the
+ * curl-noise effect held a vec4 across seventy instructions this way.
+ *
+ * ## What may be reordered
+ *
+ * Straight-line code has three hazards per slot — a read must follow the write it reads, a write
+ * must follow the reads of the value it replaces, and two writes keep their order — and the
+ * schedule keeps every one of them, so the sequence of writes and reads of each slot is the one the
+ * program had. Instructions with side effects are barriers: nothing crosses a draw, a store, a kill
+ * or a halt in either direction, and they keep their order among themselves. That is stricter than
+ * a pure instruction crossing a store needs, and it is what keeps the ordering promises of
+ * `optimize_particle_program.js` — the draw sequence, attribute aliasing — structural for this pass
+ * as for every other.
+ *
+ * ## How the order is chosen
+ *
+ * Backwards, one instruction at a time, from the set whose consumers are all already placed: the
+ * one whose placement leaves the fewest slots alive above it, which is the one that frees the most
+ * of what it writes against what it reads. Ties go to the instruction that came last in the program
+ * as it was, so an order that is already as good as this greedy can make it comes back unchanged —
+ * and the schedule is kept only when its peak is strictly lower than the program's, so the pass is
+ * a fixed point of itself and never makes a program worse by the one measure it is for.
+ *
+ * It is a greedy, and a greedy can be fooled; the differential harness holds it to bit-identity
+ * whatever order it picks, and the peak is measured rather than assumed.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_schedule(instructions, context) {
+    const decoded = decode_particle_instructions(instructions);
+    const slots = context.register_slots;
+    const order = schedule(decoded, slots);
+
+    if (order === null) {
+        return null;
+    }
+
+    const scheduled = order.map(index => decoded[index]);
+
+    if (particle_peak_live_slots(scheduled, slots) >= particle_peak_live_slots(decoded, slots)) {
+        return null;
+    }
+
+    return order.map(index => instructions[index]);
+}
+
+/**
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction[]} decoded
+ * @param {number} slots size of the register file
+ * @returns {number[]|null} instruction indices in their new order, or `null` when an operand
+ *   reaches outside the file
+ */
+function schedule(decoded, slots) {
+    const count = decoded.length;
+    const predecessors = build_dependencies(decoded, slots);
+
+    if (predecessors === null) {
+        return null;
+    }
+
+    /** @type {Int32Array} per instruction, how many of its dependents are still unplaced */
+    const pending = new Int32Array(count);
+
+    for (let i = 0; i < count; i++) {
+        for (const predecessor of predecessors[i]) {
+            pending[predecessor]++;
+        }
+    }
+
+    /** @type {Set<number>} instructions whose dependents are all placed */
+    const ready = new Set();
+
+    for (let i = 0; i < count; i++) {
+        if (pending[i] === 0) {
+            ready.add(i);
+        }
+    }
+
+    /** @type {Uint8Array} slots alive just above the instructions placed so far */
+    const live = new Uint8Array(slots);
+    /** @type {Uint8Array} scratch for scoring a candidate */
+    const trial = new Uint8Array(slots);
+    /** @type {number[]} placed instructions, last first */
+    const reversed = [];
+
+    while (reversed.length < count) {
+        let best = -1;
+        let best_live = Infinity;
+
+        for (const candidate of ready) {
+            const alive = live_above(decoded[candidate], live, trial);
+
+            if (alive < best_live || (alive === best_live && candidate > best)) {
+                best = candidate;
+                best_live = alive;
+            }
+        }
+
+        live_above(decoded[best], live, trial);
+        live.set(trial);
+        reversed.push(best);
+        ready.delete(best);
+
+        for (const predecessor of predecessors[best]) {
+            if (--pending[predecessor] === 0) {
+                ready.add(predecessor);
+            }
+        }
+    }
+
+    return reversed.reverse();
+}
+
+/**
+ * The slots alive just above an instruction, given those alive just below it: what it reads, plus
+ * whatever was alive that it does not write.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {Uint8Array} below
+ * @param {Uint8Array} above written here
+ * @returns {number} how many
+ */
+function live_above(instruction, below, above) {
+    above.set(below);
+
+    if (instruction.write !== null) {
+        for (let lane = 0; lane < instruction.write.span; lane++) {
+            above[instruction.write.base + lane] = 0;
+        }
+    }
+
+    for (const read of instruction.reads) {
+        for (const slot of particle_read_slots(read)) {
+            above[slot] = 1;
+        }
+    }
+
+    let alive = 0;
+
+    for (let slot = 0; slot < above.length; slot++) {
+        alive += above[slot];
+    }
+
+    return alive;
+}
+
+/**
+ * Per instruction, the instructions it must come after.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction[]} decoded
+ * @param {number} slots
+ * @returns {Set<number>[]|null} `null` when an operand reaches outside the file
+ */
+function build_dependencies(decoded, slots) {
+    const predecessors = decoded.map(() => new Set());
+    /** @type {Int32Array} per slot, the last instruction to write it */
+    const writer = new Int32Array(slots).fill(-1);
+    /** @type {number[][]} per slot, the instructions that read its current value */
+    const readers = Array.from({ length: slots }, () => []);
+
+    let barrier = -1;
+
+    for (let i = 0; i < decoded.length; i++) {
+        const instruction = decoded[i];
+        const read_slots = new Set();
+
+        for (const read of instruction.reads) {
+            for (const slot of particle_read_slots(read)) {
+                if (slot < 0 || slot >= slots) {
+                    return null;
+                }
+
+                read_slots.add(slot);
+            }
+        }
+
+        // After the write it reads.
+        for (const slot of read_slots) {
+            if (writer[slot] >= 0) {
+                predecessors[i].add(writer[slot]);
+            }
+        }
+
+        const write = instruction.write;
+
+        if (write !== null) {
+            if (write.base + write.span > slots) {
+                return null;
+            }
+
+            // After the previous write, and after every read of the value it replaces.
+            for (let lane = 0; lane < write.span; lane++) {
+                const slot = write.base + lane;
+
+                if (writer[slot] >= 0) {
+                    predecessors[i].add(writer[slot]);
+                }
+
+                for (const reader of readers[slot]) {
+                    predecessors[i].add(reader);
+                }
+            }
+        }
+
+        for (const slot of read_slots) {
+            readers[slot].push(i);
+        }
+
+        if (write !== null) {
+            for (let lane = 0; lane < write.span; lane++) {
+                writer[write.base + lane] = i;
+                readers[write.base + lane] = [];
+            }
+        }
+
+        // A barrier comes after everything above it — the previous barrier included, since two of
+        // them may be adjacent — and everything below it comes after it.
+        if (instruction.semantics.side_effects) {
+            for (let j = Math.max(barrier, 0); j < i; j++) {
+                predecessors[i].add(j);
+            }
+
+            barrier = i;
+        } else if (barrier >= 0) {
+            predecessors[i].add(barrier);
+        }
+
+        predecessors[i].delete(i);
+    }
+
+    return predecessors;
+}

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":"AA8GU,4JAM8C;AA7GxD,qBAAqB;AACrB,iDADW,MAAM,CACwD"}