@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -0,0 +1,313 @@
+import { vm_canonical_register, vm_operand_base, vm_operand_with_base, vm_with_dst } from "../isa/ParticleVMISA.js";
+import { pass_pack_registers } from "./pass_pack_registers.js";
+import {
+    decode_particle_instructions,
+    particle_instruction_is_well_formed,
+    particle_read_slots,
+} from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_ALLOCATE_REGISTERS = "allocate_registers";
+
+/**
+ * Give every value a slot for as long as it lives, and no longer.
+ *
+ * The frontend's allocator hands out slots as it lowers, and the passes above this one then delete,
+ * narrow and forward values without ever moving one. What is left is a file where a slot holds a
+ * value that died a hundred instructions ago while a fresh one is put somewhere new — and the file's
+ * high-water mark is what the interpreter pays for, since `vm_reg` is sized by it (see the occupancy
+ * note in `vm/chunk_particle_vm.js`). Packing closes the holes nothing ever touched; this pass is
+ * the other half, reusing the slots that are touched but not at the same time.
+ *
+ * ## Segments and clusters
+ *
+ * Straight-line code has exact lifetimes: a slot's value lives from the instruction that writes it
+ * to the last one that reads it before the next write. Each such stretch is a SEGMENT, and a slot
+ * that is read before anything writes it has a segment from the reset — the zero it holds has to
+ * stay unwritten until that read. Two segments may share a slot when their stretches do not overlap,
+ * and a read at the instruction that overwrites the slot does not overlap it, because every executor
+ * reads its sources before it writes.
+ *
+ * What stops this being interval colouring one slot at a time is that operands name RUNS. A value
+ * three lanes wide is three consecutive slots, and a swizzled read names slots at fixed distances
+ * from its base. So every operand's slots are joined into one CLUSTER whose members keep their
+ * distances; the cluster is placed as a shape, and a member's slot is checked against its own
+ * stretch rather than the cluster's whole extent, so a scalar can sit in the gap of a swizzle that
+ * skips it. All of the constraints come from the layout the program already has, which is why the
+ * shapes are always consistent.
+ *
+ * Clusters are placed in order of when they are first written, each at the lowest origin that fits
+ * — the interval-graph greedy, which is optimal for scalars and a good heuristic for shapes. A
+ * placement that needs more slots than the program had is thrown away, so the pass never makes a
+ * file bigger, and one that needs the same number is thrown away too, so the pass reaches a fixed
+ * point instead of shuffling a program it cannot shrink. Packing runs after every placement, since
+ * a shape may leave a slot between its members that nothing uses, and placement runs again on the
+ * packed file until it has nothing more to give.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_allocate_registers(instructions, context) {
+    let current = instructions;
+    let changed = false;
+
+    // Every round makes the file strictly smaller, so it cannot take more of them than there are
+    // slots — and it has to run to the end, or the next run of the optimizer would find more to do.
+    for (let round = 0; round < context.register_slots; round++) {
+        const allocated = allocate_once(current, context.register_slots);
+
+        if (allocated === null) {
+            break;
+        }
+
+        current = pass_pack_registers(allocated, context) ?? allocated;
+        changed = true;
+    }
+
+    return changed ? current : null;
+}
+
+/**
+ * @typedef {object} ParticleRegisterSegment
+ * @property {number} slot the slot it occupies in the program as it stands
+ * @property {number} start the instruction that writes it, or `-1` for the reset
+ * @property {number} end the last instruction that reads it; `start` when nothing does
+ * @property {number} parent union-find link
+ * @property {number} placed the slot it is given, once the cluster is placed; `-1` until then
+ */
+
+/**
+ * @typedef {object} ParticleRegisterShape
+ * @property {number[]} members segment indices
+ * @property {number} origin the lowest slot among the members, which the others keep their distance from
+ * @property {number} extent slots from the origin to one past the highest member
+ * @property {number} start the earliest write among the members
+ */
+
+/**
+ * @typedef {object} ParticleRegisterSegments
+ * @property {ParticleRegisterSegment[]} segments
+ * @property {ParticleRegisterShape[]} shapes the clusters, in the order they are placed
+ * @property {Int32Array[]} read_segment per instruction, per source slot, the segment the operand's canonical base slot read
+ * @property {Uint32Array[]} read_word per instruction, per source slot, the operand in its canonical spelling
+ * @property {Int32Array} write_segment per instruction, the segment its destination base slot is written into
+ * @property {number} high_water one past the highest slot the program reaches
+ */
+
+/**
+ * Every stretch of every slot, and which of them have to keep their distance.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction[]} decoded
+ * @param {number} slots size of the register file
+ * @returns {ParticleRegisterSegments|null} `null` when an operand reaches outside the file
+ */
+export function analyze_particle_register_segments(decoded, slots) {
+    /** @type {ParticleRegisterSegment[]} */
+    const segments = [];
+    /** @type {Int32Array} per slot, the segment currently in it, or `-1` */
+    const current = new Int32Array(slots).fill(-1);
+    const read_segment = decoded.map(() => new Int32Array(3).fill(-1));
+    const read_word = decoded.map(() => new Uint32Array(3));
+    const write_segment = new Int32Array(decoded.length).fill(-1);
+
+    let high_water = 0;
+
+    const create = (slot, start) => {
+        segments.push({ slot, start, end: start, parent: segments.length, placed: -1 });
+        current[slot] = segments.length - 1;
+
+        return segments.length - 1;
+    };
+
+    const find = (id) => {
+        while (segments[id].parent !== id) {
+            segments[id].parent = segments[segments[id].parent].parent;
+            id = segments[id].parent;
+        }
+
+        return id;
+    };
+
+    const union = (ids) => {
+        const root = find(ids[0]);
+
+        for (let i = 1; i < ids.length; i++) {
+            segments[find(ids[i])].parent = root;
+        }
+    };
+
+    for (let i = 0; i < decoded.length; i++) {
+        const instruction = decoded[i];
+
+        // Reads first: the executors read every source before they write the destination.
+        for (const read of instruction.reads) {
+            const read_slots = particle_read_slots(read);
+
+            if (read_slots.some(slot => slot < 0 || slot >= slots)) {
+                return null;
+            }
+
+            high_water = Math.max(high_water, read.base + read.span);
+
+            const ids = read_slots.map(slot => {
+                const id = current[slot] >= 0 ? current[slot] : create(slot, -1);
+
+                segments[id].end = i;
+
+                return id;
+            });
+
+            union(ids);
+
+            // A pass that narrowed the instruction may have left the operand spelled from a base
+            // slot it no longer reads; the canonical spelling's base is the lowest slot it does.
+            const word = vm_canonical_register(read.word, read.lanes);
+
+            read_word[i][read.operand] = word;
+            read_segment[i][read.operand] = ids[read_slots.indexOf(vm_operand_base(word))];
+        }
+
+        const write = instruction.write;
+
+        if (write !== null) {
+            if (write.base + write.span > slots) {
+                return null;
+            }
+
+            high_water = Math.max(high_water, write.base + write.span);
+
+            const ids = [];
+
+            for (let lane = 0; lane < write.span; lane++) {
+                ids.push(create(write.base + lane, i));
+            }
+
+            union(ids);
+            write_segment[i] = ids[0];
+        }
+    }
+
+    /** @type {Map<number, number[]>} root -> members */
+    const clusters = new Map();
+
+    for (let id = 0; id < segments.length; id++) {
+        const root = find(id);
+
+        if (!clusters.has(root)) {
+            clusters.set(root, []);
+        }
+
+        clusters.get(root).push(id);
+    }
+
+    const shapes = Array.from(clusters.values(), members => {
+        let origin = Infinity;
+        let highest = -Infinity;
+        let start = Infinity;
+
+        for (const id of members) {
+            origin = Math.min(origin, segments[id].slot);
+            highest = Math.max(highest, segments[id].slot);
+            start = Math.min(start, segments[id].start);
+        }
+
+        return { members, origin, extent: highest - origin + 1, start };
+    });
+
+    shapes.sort((a, b) => a.start - b.start || a.origin - b.origin);
+
+    return { segments, shapes, read_segment, read_word, write_segment, high_water };
+}
+
+/**
+ * First fit: each shape at the lowest origin where every member's slot is free for the member's own
+ * stretch. Fills in `placed` on the segments.
+ *
+ * @param {ParticleRegisterSegments} analysis
+ * @param {number} slots
+ * @returns {number} one past the highest slot placed, or `-1` when a shape does not fit
+ */
+function place_shapes({ segments, shapes }, slots) {
+    /** @type {Array<Array<[number, number]>>} per slot, the stretches already placed in it */
+    const occupied = Array.from({ length: slots }, () => []);
+
+    const free = (slot, segment) => occupied[slot].every(
+        ([start, end]) => !(segment.start < end && start < segment.end)
+    );
+
+    let count = 0;
+
+    for (const shape of shapes) {
+        let placed = false;
+
+        for (let origin = 0; origin + shape.extent <= slots && !placed; origin++) {
+            if (shape.members.every(id => free(origin + segments[id].slot - shape.origin, segments[id]))) {
+                for (const id of shape.members) {
+                    const segment = segments[id];
+
+                    segment.placed = origin + segment.slot - shape.origin;
+                    occupied[segment.placed].push([segment.start, segment.end]);
+                }
+
+                count = Math.max(count, origin + shape.extent);
+                placed = true;
+            }
+        }
+
+        if (!placed) {
+            return -1;
+        }
+    }
+
+    return count;
+}
+
+/**
+ * One placement, or `null` when it would not make the file strictly smaller.
+ *
+ * @param {number[][]} instructions
+ * @param {number} slots size of the register file
+ * @returns {number[][]|null}
+ */
+function allocate_once(instructions, slots) {
+    const decoded = decode_particle_instructions(instructions);
+    const analysis = analyze_particle_register_segments(decoded, slots);
+
+    if (analysis === null) {
+        return null;
+    }
+
+    const count = place_shapes(analysis, slots);
+
+    if (count < 0 || count >= analysis.high_water) {
+        return null;
+    }
+
+    const { segments, read_segment, read_word, write_segment } = analysis;
+
+    /** @type {number[][]} */
+    const out = [];
+
+    for (let i = 0; i < decoded.length; i++) {
+        const instruction = decoded[i];
+        const words = instruction.words.slice();
+
+        if (instruction.write !== null) {
+            words[0] = vm_with_dst(words[0], segments[write_segment[i]].placed);
+        }
+
+        for (const read of instruction.reads) {
+            words[1 + read.operand] = vm_operand_with_base(
+                read_word[i][read.operand],
+                segments[read_segment[i][read.operand]].placed
+            );
+        }
+
+        if (!particle_instruction_is_well_formed(words)) {
+            return null;
+        }
+
+        out.push(words);
+    }
+
+    return out;
+}

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

@@ -1,7 +1,8 @@
 /**
- * Every `(base, span)` a section loads from the pool.
+ * Every `(base, span)` a section loads from the pool. A `LOAD_CONST` is the one instruction that
+ * reads it, and its pool index is its first source word.
  *
- * @param {ArrayLike<ArrayLike<number>>} instructions five-word tuples
+ * @param {ArrayLike<ArrayLike<number>>} instructions four-word tuples
  * @param {function(number, number, number): void} visit `(index, base, span)`
  */
 export function visit_particle_constant_reads(instructions: ArrayLike<ArrayLike<number>>, visit: (arg0: number, arg1: number, arg2: number) => void): void;

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

@@ -1 +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"}
+{"version":3,"file":"pass_dedup_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_dedup_constants.js"],"names":[],"mappings":"AA+GA;;;;;;GAMG;AACH,4DAHW,UAAU,UAAU,MAAM,CAAC,CAAC,gBACnB,MAAM,QAAE,MAAM,QAAE,MAAM,KAAG,IAAI,QAWhD;AAzB+B,uJAUkE;AA9GlG,qBAAqB;AACrB,4CADW,MAAM,CAC8C"}