@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -0,0 +1,22 @@
+export function pass_inline_constants(instructions: number[][], context: import("./optimize_particle_program.js").ParticleOptimizerContext): number[][];
+/** @type {string} */
+export const PARTICLE_PASS_INLINE_CONSTANTS: string;
+export type ParticleConstantSource = {
+    /**
+     * first register slot the constant is written to
+     */
+    base: number;
+    /**
+     * slots it fills
+     */
+    span: number;
+    /**
+     * the `f32` bit pattern each slot receives
+     */
+    bits: Uint32Array;
+    /**
+     * whether every slot receives the same bits
+     */
+    uniform: boolean;
+};
+//# sourceMappingURL=pass_inline_constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pass_inline_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_inline_constants.js"],"names":[],"mappings":"AAmHY,wJAUZ;AArHA,qBAAqB;AACrB,6CADW,MAAM,CACgD;;;;;UA0FnD,MAAM;;;;UACN,MAAM;;;;UACN,WAAW;;;;aACX,OAAO"}

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

@@ -0,0 +1,221 @@
+import { VM_KIND, VM_OP, vm_f32_bits, vm_pack_instruction, vm_with_kind } from "../isa/ParticleVMISA.js";
+import {
+    decode_particle_instruction,
+    decode_particle_instructions,
+    particle_instruction_is_well_formed,
+    particle_read_slots,
+} from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_INLINE_CONSTANTS = "inline_constants";
+
+/**
+ * Move constants out of the register file and into the instructions that read them.
+ *
+ * `LOAD_CONST r, c` puts a value that never changes into a register, so that the next instruction
+ * can read a register — which was the only thing an instruction could read, until a source could be
+ * a literal (see the operand kinds in {@link ../isa/ParticleVMISA.js}). Now the load is a detour:
+ * the consumer can name the value itself. This pass finds every instruction that reads the loaded
+ * run before anything overwrites it, rewrites that operand to carry the constant, and deletes the
+ * load. A constant read by many instructions is inlined into each of them; unlike a register, a
+ * literal costs nothing to repeat.
+ *
+ * A literal is one value in every lane, so a consumer takes it only where every lane it reads holds
+ * the same `f32` — every scalar, every lane-uniform vector, and every swizzle whose selected lanes
+ * happen to agree. A vector whose lanes differ keeps its load: the pool is where such a value lives.
+ *
+ * A load whose value is uniform but that cannot be inlined — a consumer reads past the run, or
+ * reads a lane something in between has overwritten — keeps its register, but not its opcode: it
+ * becomes a `MOV` from the literal, so that the only `LOAD_CONST`s left in a program this pass has
+ * been over are the ones the pool exists for.
+ *
+ * ## What must not change
+ *
+ * The rewrite is bit-exact: a literal is the `f32` bits the pool word held, and the interpreters
+ * fetch it through the same resolver they fetch a register with. The other passes do not have to
+ * know this one exists — a literal is not a register run, so liveness, aliasing and copy propagation
+ * see through it by construction — and it is idempotent: a program with nothing left to inline
+ * comes back as `null`.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_inline_constants(instructions, context) {
+    const constants = context.constants;
+
+    if (constants === undefined || constants.length === 0) {
+        return null;
+    }
+
+    const decoded = decode_particle_instructions(instructions);
+    /** @type {number[][]} the stream being rewritten; `decoded` is kept in step with it */
+    const out = instructions.map(words => Array.from(words));
+    const removed = new Uint8Array(decoded.length);
+
+    let changed = false;
+
+    for (let i = 0; i < decoded.length; i++) {
+        const source = constant_source(decoded[i], constants);
+
+        if (source === null) {
+            continue;
+        }
+
+        const rewrites = plan_inlining(decoded, i, source);
+
+        if (rewrites !== null) {
+            for (const [index, words] of rewrites) {
+                out[index] = words;
+                decoded[index] = decode_particle_instruction(words, index);
+            }
+
+            removed[i] = 1;
+            changed = true;
+            continue;
+        }
+
+        // The value has to stay in a register, so the instruction stays — as a MOV from the literal,
+        // which is the same work under the opcode the interpreter already has for copies.
+        if (decoded[i].op === VM_OP.LOAD_CONST && source.uniform) {
+            const words = vm_pack_instruction(
+                VM_OP.MOV, decoded[i].width, decoded[i].dst,
+                [VM_KIND.IMM, VM_KIND.NONE, VM_KIND.NONE],
+                [source.bits[0], 0, 0]
+            );
+
+            out[i] = words;
+            decoded[i] = decode_particle_instruction(words, i);
+            changed = true;
+        }
+    }
+
+    if (!changed) {
+        return null;
+    }
+
+    return out.filter((words, index) => removed[index] === 0);
+}
+
+/**
+ * @typedef {object} ParticleConstantSource
+ * @property {number} base first register slot the constant is written to
+ * @property {number} span slots it fills
+ * @property {Uint32Array} bits the `f32` bit pattern each slot receives
+ * @property {boolean} uniform whether every slot receives the same bits
+ */
+
+/**
+ * What an instruction writes into its destination when that is a constant: a `LOAD_CONST`, or a
+ * `MOV` from a literal. `null` for anything else.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {ArrayLike<number>} constants
+ * @returns {ParticleConstantSource|null}
+ */
+function constant_source(instruction, constants) {
+    if (instruction.write === null) {
+        return null;
+    }
+
+    const span = instruction.write.span;
+    const bits = new Uint32Array(span);
+
+    if (instruction.op === VM_OP.LOAD_CONST) {
+        const pool = instruction.words[1];
+
+        if (pool + span > constants.length) {
+            // Out of the pool: a malformed program, left for `validate` to name.
+            return null;
+        }
+
+        for (let lane = 0; lane < span; lane++) {
+            bits[lane] = vm_f32_bits(constants[pool + lane]);
+        }
+    } else if (instruction.op === VM_OP.MOV && instruction.sources[0].kind === VM_KIND.IMM) {
+        bits.fill(instruction.sources[0].word);
+    } else {
+        return null;
+    }
+
+    let uniform = true;
+
+    for (let lane = 1; lane < span; lane++) {
+        uniform = uniform && bits[lane] === bits[0];
+    }
+
+    return { base: instruction.write.base, span, bits, uniform };
+}
+
+/**
+ * Every consumer of the constant's run, rewritten to carry the constant — or `null` when one of
+ * them cannot.
+ *
+ * Walks forward from the load until every slot of the run has been overwritten or the section ends.
+ * Each register read that touches the run must lie entirely inside the slots the load still owns —
+ * a read reaching past it, or into a lane something has since overwritten, is reading a value the
+ * constant is not — and must see one value in every lane it reads.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction[]} decoded
+ * @param {number} index of the load
+ * @param {ParticleConstantSource} source
+ * @returns {Map<number, number[]>|null} instruction index -> its rewritten words
+ */
+function plan_inlining(decoded, index, source) {
+    /** slots of the run the load still owns */
+    const pending = new Set();
+
+    for (let lane = 0; lane < source.span; lane++) {
+        pending.add(source.base + lane);
+    }
+
+    /** @type {Map<number, number[]>} */
+    const rewrites = new Map();
+
+    for (let j = index + 1; j < decoded.length && pending.size > 0; j++) {
+        const instruction = decoded[j];
+
+        // Nothing past a HALT runs, so nothing past it consumes.
+        if (instruction.op === VM_OP.HALT) {
+            break;
+        }
+
+        for (const read of instruction.reads) {
+            const slots = particle_read_slots(read);
+
+            // A slot the run once held but something has since overwritten is not the constant any
+            // more, and a read of it is a read of that something. Only the slots still standing count.
+            if (!slots.some(slot => pending.has(slot))) {
+                continue;
+            }
+
+            // Touches the constant, so it has to be wholly the constant, and one value throughout.
+            if (!slots.every(slot => pending.has(slot))) {
+                return null;
+            }
+
+            const first = source.bits[slots[0] - source.base];
+
+            if (!slots.every(slot => source.bits[slot - source.base] === first)) {
+                return null;
+            }
+
+            const words = (rewrites.get(j) ?? instruction.words).slice();
+
+            words[0] = vm_with_kind(words[0], read.operand, VM_KIND.IMM);
+            words[1 + read.operand] = first;
+
+            if (!particle_instruction_is_well_formed(words)) {
+                return null;
+            }
+
+            rewrites.set(j, words);
+        }
+
+        if (instruction.write !== null) {
+            for (let lane = 0; lane < instruction.write.span; lane++) {
+                pending.delete(instruction.write.base + lane);
+            }
+        }
+    }
+
+    return rewrites;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"pass_narrow_widths.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_narrow_widths.js"],"names":[],"mappings":"AAwEuB,qJAAiP;AAjExQ,qBAAqB;AACrB,0CADW,MAAM,CAC0C"}
+{"version":3,"file":"pass_narrow_widths.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_narrow_widths.js"],"names":[],"mappings":"AA+DguE,qJAAqP;AAxDr9E,qBAAqB;AACrB,0CADW,MAAM,CAC0C"}

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

@@ -1,72 +1,63 @@
-import { VM_OP, vm_encode_word0 } from "../isa/ParticleVMISA.js";
-import {
-    analyze_particle_lanes,
-    decode_particle_instructions,
-    particle_instruction_is_well_formed,
-} from "./particle_program_analysis.js";
-
-/** @type {string} */
-export const PARTICLE_PASS_NARROW_WIDTHS = "narrow_widths";
-
-/**
- * Shrink each instruction to the lanes anything actually reads.
- *
- * Width is what stops every value costing four registers, and a lowering that works one value at a
- * time has no way to know how wide its consumer will turn out to be — the node compiler emits a
- * four-lane broadcast, learns later that one lane of it is read, and cannot go back. Reading the
- * finished stream backwards can: {@link analyze_particle_lanes} already knows the highest live lane
- * of every destination, and this pass writes that width into the instruction.
- *
- * The saving is in slots more often than in instructions. A narrowed value stops occupying the runs
- * above it, which is what lets the register-packing pass reclaim them, and the register file is the
- * interpreter's dominant cost — see the occupancy table in `vm/chunk_particle_vm.js`.
- *
- * Lanes are a run from zero, so the width follows the *highest* live lane rather than the count of
- * them: a live lane 2 holds the instruction at three lanes however dead lanes 0 and 1 are. Clearing
- * out a hole in the middle would mean splitting the instruction, which costs more than the lane.
- *
- * A `SWIZZLE` gets its pattern trimmed as well as its width, because a pattern's four selectors are
- * read whatever the instruction writes — an untrimmed one keeps the whole source value alive to feed
- * lanes that no longer exist.
- *
- * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
- */
-export function pass_narrow_widths(instructions, context) {
-    const decoded = decode_particle_instructions(instructions);
-    const { keep, width, pattern } = analyze_particle_lanes(decoded, context.register_slots);
-
-    /** @type {number[][]} */
-    const out = instructions.slice();
-
-    let changed = false;
-
-    for (let i = 0; i < instructions.length; i++) {
-        const instruction = decoded[i];
-
-        // Instructions nothing keeps are the dead-code pass's to remove, not this one's to narrow.
-        if (!keep[i] || (width[i] === instruction.width && pattern[i] === instruction.words[3])) {
-            continue;
-        }
-
-        const words = instruction.words.slice();
-
-        words[0] = vm_encode_word0(instruction.op, width[i]);
-
-        if (instruction.op === VM_OP.SWIZZLE) {
-            words[3] = pattern[i];
-        }
-
-        // Narrowing moves no base and shrinks every run of an instruction together, so an exact
-        // alias stays exact and disjoint runs stay disjoint — except a swizzle, whose source run
-        // follows the pattern rather than the width. Rather than reason about which case this is,
-        // ask; a rejected narrowing costs a lane, and an accepted illegal one costs correctness.
-        if (!particle_instruction_is_well_formed(words)) {
-            continue;
-        }
-
-        out[i] = words;
-        changed = true;
-    }
-
-    return changed ? out : null;
-}
+import { vm_with_width } from "../isa/ParticleVMISA.js";
+import {
+    analyze_particle_lanes,
+    decode_particle_instructions,
+    particle_instruction_is_well_formed,
+} from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_NARROW_WIDTHS = "narrow_widths";
+
+/**
+ * Shrink each instruction to the lanes anything actually reads.
+ *
+ * Width is what stops every value costing four registers, and a lowering that works one value at a
+ * time has no way to know how wide its consumer will turn out to be — the node compiler emits a
+ * four-lane broadcast, learns later that one lane of it is read, and cannot go back. Reading the
+ * finished stream backwards can: {@link analyze_particle_lanes} already knows the highest live lane
+ * of every destination, and this pass writes that width into the instruction.
+ *
+ * The saving is in slots more often than in instructions. A narrowed value stops occupying the runs
+ * above it, which is what lets the register-packing pass reclaim them, and the register file is the
+ * interpreter's dominant cost — see the occupancy note in `vm/chunk_particle_vm.js`.
+ *
+ * Lanes are a run from zero, so the width follows the *highest* live lane rather than the count of
+ * them: a live lane 2 holds the instruction at three lanes however dead lanes 0 and 1 are. Clearing
+ * out a hole in the middle would mean splitting the instruction, which costs more than the lane.
+ *
+ * A source's swizzle needs no trimming: an operand reaches as far as its selectors below the width,
+ * so narrowing the instruction narrows what every source keeps alive by itself.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_narrow_widths(instructions, context) {
+    const decoded = decode_particle_instructions(instructions);
+    const { keep, width } = analyze_particle_lanes(decoded, context.register_slots);
+
+    /** @type {number[][]} */
+    const out = instructions.slice();
+
+    let changed = false;
+
+    for (let i = 0; i < instructions.length; i++) {
+        const instruction = decoded[i];
+
+        // Instructions nothing keeps are the dead-code pass's to remove, not this one's to narrow.
+        if (!keep[i] || width[i] === instruction.width) {
+            continue;
+        }
+
+        const words = instruction.words.slice();
+
+        words[0] = vm_with_width(words[0], width[i]);
+
+        if (!particle_instruction_is_well_formed(words)) {
+            continue;
+        }
+
+        out[i] = words;
+        changed = true;
+    }
+
+    return changed ? out : null;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"pass_pack_registers.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_pack_registers.js"],"names":[],"mappings":"AAyEiB,sJAKN;AA5EX,qBAAqB;AACrB,2CADW,MAAM,CAC4C"}
+{"version":3,"file":"pass_pack_registers.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_pack_registers.js"],"names":[],"mappings":"AAuF09C,sJAAqP;AApF/sD,qBAAqB;AACrB,2CADW,MAAM,CAC4C"}

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

@@ -1,86 +1,87 @@
-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;
-}
+import { vm_operand_with_base, vm_with_dst } from "../isa/ParticleVMISA.js";
+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. Every
+ * slot of every operand's span is marked used — including the ones inside a span that a swizzle
+ * skips over — so the remap is order-preserving and injective over the slots any operand can name,
+ * and every run stays contiguous with its swizzle meaning what it did.
+ *
+ * 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();
+
+        if (instruction.write !== null) {
+            words[0] = vm_with_dst(words[0], remap[instruction.write.base]);
+        }
+
+        for (const read of instruction.reads) {
+            words[1 + read.operand] = vm_operand_with_base(read.word, remap[read.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.map

@@ -1 +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"}
+{"version":3,"file":"pass_peephole.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_peephole.js"],"names":[],"mappings":"AA+GC,gJAMW;AA1GZ,qBAAqB;AACrB,qCADW,MAAM,CACgC"}