@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/optimizer/dag/particle_vector_lift.js

@@ -0,0 +1,462 @@
+import { PARTICLE_RECORD_WORD_COUNT } from "../../ParticleConstants.js";
+import {
+    VM_KIND,
+    VM_MAX_WIDTH,
+    VM_OP,
+    VM_SWIZZLE_IDENTITY,
+    pack_swizzle,
+    swizzle_selector,
+    vm_dest_width,
+    vm_f32_value,
+    vm_operand_base,
+} from "../../isa/ParticleVMISA.js";
+import { decode_particle_instruction } from "../particle_program_analysis.js";
+import { vm_semantics_of } from "../particle_vm_semantics.js";
+import { PV } from "./particle_vector_graph.js";
+import { identity_lanes, identity_of } from "./particle_vector_rules.js";
+
+/**
+ * Read one section of a compiled program into a {@link ./particle_vector_graph.js vector graph}.
+ *
+ * What a section MEANS is its final record, the kill flag it sets and the RNG state it ends on, and
+ * everything that draws out of that is done here: a load of a word that was stored is the stored
+ * value, a word put back as it was found is not stored, kills are a set, draws are a sequence that
+ * may be re-cut, and nothing past a `HALT` is read.
+ *
+ * What is different is the unit. The register file holds not values but PLACES IN values: slot `s`
+ * holds lane `l` of value `v`. Reading a run of slots then asks one question — do they all come from
+ * one value? If they do, the read is that value through a swizzle, which is what a source word is and
+ * costs nothing. If they do not, it is a `BUILD`, and the copies it costs are visible from here on
+ * rather than discovered at the end.
+ *
+ * That is the whole of the change, and it is why the frontend's vectors reach the other side: a
+ * `vec3` the compiler emitted as one instruction is read back as one value, not inferred from three.
+ */
+
+/**
+ * @typedef {object} ParticleVectorPlace
+ * @property {number} value the class the slot's value belongs to
+ * @property {number} lane which lane of it the slot holds
+ */
+
+/**
+ * @typedef {object} ParticleLiftedVectorSection
+ * @property {Array<{word: number, place: ParticleVectorPlace, origin: number}>} stores record words
+ *   whose final contents differ from what the section found, in word order
+ * @property {ParticleVectorPlace[]} kills distinct kill conditions, in the order they were met
+ * @property {number} draw_count draws taken off the RNG
+ * @property {number[]} draws per draw, the class of the `RANDOM` that takes it
+ * @property {number[]} draw_lanes per draw, which lane of that class it is
+ */
+
+/**
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {ArrayLike<ArrayLike<number>>} instructions four-word tuples, in program order
+ * @param {object} params
+ * @param {ArrayLike<number>} params.constants
+ * @param {number} params.register_slots
+ * @returns {ParticleLiftedVectorSection|null} `null` when the section reaches outside that file, or
+ *   uses an opcode this lift has no model for
+ */
+export function lift_particle_vector_section(graph, instructions, { constants, register_slots }) {
+    const zero = { value: graph.constant(0), lane: 0 };
+    /** @type {ParticleVectorPlace[]} what each slot holds; both executors start a particle with a zeroed file */
+    const reg = new Array(register_slots).fill(zero);
+    /** @type {Map<number, ParticleVectorPlace>} per record word, what it held when the section began */
+    const initial = new Map();
+    /** @type {Map<number, ParticleVectorPlace>} per record word, what it holds now */
+    const record = new Map();
+    /** @type {Map<number, number>} per record word, which store last wrote it */
+    const origin = new Map();
+    /** @type {ParticleVectorPlace[]} */
+    const kills = [];
+    /** @type {number[]} */
+    const draws = [];
+    /** @type {number[]} */
+    const draw_lanes = [];
+
+    /**
+     * The record as the section found it, over a run of words — one `ATTR` for the whole run, so that
+     * a `vec3` read out of the record is one value and not three to be glued together.
+     *
+     * @param {number} word
+     * @param {number} width
+     * @returns {ParticleVectorPlace[]}
+     */
+    const found = (word, width) => {
+        const fresh = [];
+
+        for (let lane = 0; lane < width; lane++) {
+            if (initial.has(word + lane) || record.has(word + lane)) {
+                fresh.push(-1);
+            } else {
+                fresh.push(lane);
+            }
+        }
+
+        // Only a run nothing has touched can be one load; anything else is read word by word, and
+        // whatever those turn out to be is the BUILD's business.
+        if (fresh.every(lane => lane >= 0)) {
+            const value = graph.make({ op: PV.ATTR, width, imm: [word] });
+
+            for (let lane = 0; lane < width; lane++) {
+                initial.set(word + lane, { value, lane });
+            }
+        }
+
+        const places = [];
+
+        for (let lane = 0; lane < width; lane++) {
+            const at = word + lane;
+
+            if (!initial.has(at)) {
+                initial.set(at, { value: graph.make({ op: PV.ATTR, width: 1, imm: [at] }), lane: 0 });
+            }
+
+            places.push(record.get(at) ?? initial.get(at));
+        }
+
+        return places;
+    };
+
+    for (let i = 0; i < instructions.length; i++) {
+        const instruction = decode_particle_instruction(instructions[i], i);
+
+        const { op, operation_width: width, write } = instruction;
+
+        if (op === VM_OP.HALT) {
+            break;
+        }
+
+        if (op === VM_OP.NOP) {
+            continue;
+        }
+
+        if (write !== null && write.base + write.span > register_slots) {
+            return null;
+        }
+
+        /** @type {Array<{value: number, pattern: number}|null>} one per source slot */
+        const operands = [];
+        let refused = false;
+
+        for (const source of instruction.sources) {
+            if (source.kind === VM_KIND.IMM) {
+                const literal = vm_f32_value(source.word);
+
+                operands[source.operand] = {
+                    value: graph.constant(literal),
+                    pattern: pack_swizzle(0, 0, 0, 0),
+                };
+                continue;
+            }
+
+            const places = [];
+
+            for (let lane = 0; lane < source.lanes; lane++) {
+                const slot = vm_operand_base(source.word) + swizzle_selector(source.pattern, lane);
+
+                if (slot < 0 || slot >= register_slots) {
+                    refused = true;
+                    break;
+                }
+
+                places.push(reg[slot]);
+            }
+
+            if (refused) {
+                break;
+            }
+
+            operands[source.operand] = read(graph, places);
+        }
+
+        if (refused) {
+            return null;
+        }
+
+        const places = evaluate(graph, instruction, operands, {
+            constants,
+            zero,
+            record,
+            origin,
+            found,
+            kills,
+            draws,
+            draw_lanes,
+        });
+
+        if (places === null) {
+            return null;
+        }
+
+        for (let lane = 0; lane < places.length; lane++) {
+            reg[write.base + lane] = places[lane];
+        }
+    }
+
+    /** @type {Array<{word: number, place: ParticleVectorPlace, origin: number}>} */
+    const stores = [];
+
+    for (let word = 0; word < PARTICLE_RECORD_WORD_COUNT; word++) {
+        const place = record.get(word);
+
+        if (place === undefined) {
+            continue;
+        }
+
+        const was = initial.get(word);
+
+        if (was !== undefined && graph.find(was.value) === graph.find(place.value) && was.lane === place.lane) {
+            continue;
+        }
+
+        stores.push({ word, place, origin: origin.get(word) });
+    }
+
+    return { stores, kills, draw_count: draws.length, draws, draw_lanes };
+}
+
+/**
+ * A run of places, as one source operand — or as a `BUILD` when they do not all come from one value.
+ *
+ * This is the whole of what keeping vectors buys, in one function. A frontend put a value in a run
+ * and its consumers read that run, so the places agree and the read is a swizzle: free. Where they do
+ * not agree, the copies are counted here, in the open.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {ParticleVectorPlace[]} places one per lane read
+ * @returns {{value: number, pattern: number}}
+ */
+export function read(graph, places) {
+    const first = graph.find(places[0].value);
+    const together = places.every(place => graph.find(place.value) === first);
+
+    if (together && places.every(place => place.lane < VM_MAX_WIDTH)) {
+        return { value: first, pattern: selectors(places.map(place => place.lane)) };
+    }
+
+    return {
+        value: graph.make({
+            op: PV.BUILD,
+            width: places.length,
+            children: places.map(place => place.value),
+            patterns: places.map(place => place.lane),
+        }),
+        pattern: VM_SWIZZLE_IDENTITY,
+    };
+}
+
+/**
+ * @param {number[]} lanes
+ * @returns {number} a swizzle reading those lanes, with the identity above them
+ */
+function selectors(lanes) {
+    return pack_swizzle(
+        lanes[0] ?? 0,
+        lanes[1] ?? 1,
+        lanes[2] ?? 2,
+        lanes[3] ?? 3
+    );
+}
+
+/**
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {number} value
+ * @param {number} width
+ * @returns {ParticleVectorPlace[]} the lanes of a value, as places
+ */
+function lanes_of(graph, value, width) {
+    return Array.from({ length: width }, (unused, lane) => ({ value, lane }));
+}
+
+/**
+ * One instruction, as the places it leaves in its destination.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {import("../particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {Array<{value: number, pattern: number}|null>} operands
+ * @param {object} state
+ * @returns {ParticleVectorPlace[]|null}
+ */
+function evaluate(graph, instruction, operands, state) {
+    const { op, words, operation_width: width } = instruction;
+    const dest = vm_dest_width(op, instruction.width);
+    const semantics = vm_semantics_of(op);
+    const source = slot => operands[slot];
+    const node = shape => lanes_of(graph, graph.make(shape), shape.width);
+
+    switch (op) {
+        // A copy is not a value: it is the same value, read through a swizzle, and whoever reads the
+        // copy can read the original the same way.
+        case VM_OP.MOV: {
+            const from = source(0);
+            const places = [];
+
+            for (let lane = 0; lane < dest; lane++) {
+                places.push({ value: from.value, lane: swizzle_selector(from.pattern, lane) });
+            }
+
+            return places;
+        }
+
+        case VM_OP.LOAD_CONST: {
+            if (words[1] + dest > state.constants.length) {
+                return null;
+            }
+
+            const values = [];
+
+            for (let lane = 0; lane < dest; lane++) {
+                values.push(state.constants[words[1] + lane]);
+            }
+
+            return lanes_of(graph, graph.constant(...values), dest);
+        }
+
+        case VM_OP.LOAD_ATTR: {
+            if (words[1] + Math.min(dest, words[2]) > PARTICLE_RECORD_WORD_COUNT) {
+                return null;
+            }
+
+            const held = state.found(words[1], Math.min(dest, words[2]));
+            const places = [];
+
+            for (let lane = 0; lane < dest; lane++) {
+                // Lanes past the component count are the zero an over-wide load reads on both
+                // executors.
+                places.push(lane < words[2] ? held[lane] : state.zero);
+            }
+
+            return places;
+        }
+
+        case VM_OP.STORE_ATTR: {
+            if (words[2] + words[3] > PARTICLE_RECORD_WORD_COUNT) {
+                return null;
+            }
+
+            const from = source(0);
+
+            for (let lane = 0; lane < words[3]; lane++) {
+                state.record.set(words[2] + lane, {
+                    value: from.value,
+                    lane: swizzle_selector(from.pattern, lane),
+                });
+                state.origin.set(words[2] + lane, instruction.index);
+            }
+
+            return [];
+        }
+
+        // Never folded past the builtin's component count: `EMITTER_POSITION` reads `1.0` in its
+        // fourth lane on both executors.
+        case VM_OP.LOAD_BUILTIN:
+            return node({ op, width: dest, imm: [words[1]] });
+
+        case VM_OP.KILL: {
+            const from = source(0);
+            const place = { value: from.value, lane: swizzle_selector(from.pattern, 0) };
+            const literal = graph.constant_at(place.value, place.lane);
+
+            // A condition that cannot be positive is a kill that never fires.
+            if (literal !== null && !(literal > 0)) {
+                return [];
+            }
+
+            if (!state.kills.some(other => graph.find(other.value) === graph.find(place.value) && other.lane === place.lane)) {
+                state.kills.push(place);
+            }
+
+            return [];
+        }
+
+        case VM_OP.RANDOM: {
+            const first = state.draws.length;
+            const value = graph.make({ op, width: dest, imm: [first] });
+
+            for (let lane = 0; lane < dest; lane++) {
+                state.draws.push(value);
+                state.draw_lanes.push(lane);
+            }
+
+            return lanes_of(graph, value, dest);
+        }
+
+        // Every lane is the same sample, so one lane holds it and a consumer reading it wide reads a
+        // broadcast.
+        case VM_OP.CURVE: {
+            const value = graph.make({
+                op,
+                width: 1,
+                children: [source(1).value],
+                patterns: [source(1).pattern],
+                imm: [words[1]],
+            });
+
+            return Array.from({ length: dest }, () => ({ value, lane: 0 }));
+        }
+
+        default: {
+            if (semantics.side_effects) {
+                return null;
+            }
+
+            // An instruction that merely copies one of its operands is not a value — it is that
+            // operand, read the way it was already being read. Recognised here rather than as a graph
+            // rule because a view is something only an instruction's RESULT can be.
+            const copied = identity_of(graph, op, operands, width);
+
+            if (copied !== null) {
+                return Array.from({ length: dest }, (unused, lane) => ({
+                    value: copied.value,
+                    lane: swizzle_selector(copied.pattern, lane),
+                }));
+            }
+
+            const children = [];
+            const patterns = [];
+
+            for (let slot = 0; slot < 3; slot++) {
+                if (operands[slot] !== undefined) {
+                    children.push(operands[slot].value);
+                    patterns.push(operands[slot].pattern);
+                }
+            }
+
+            // And an instruction only SOME of whose lanes are copies is the narrower instruction over
+            // the lanes that are left, with those lanes still read where they already were.
+            const copies = dest === width ? identity_lanes(graph, op, operands, width) : null;
+
+            if (copies !== null) {
+                const keep = [];
+
+                for (let lane = 0; lane < width; lane++) {
+                    if (copies[lane] < 0) {
+                        keep.push(lane);
+                    }
+                }
+
+                const narrowed = keep.length === 0 ? -1 : graph.make({
+                    op,
+                    width: keep.length,
+                    operand_width: keep.length,
+                    children,
+                    patterns: patterns.map(pattern => pack_swizzle(
+                        ...[0, 1, 2, 3].map(lane =>
+                            swizzle_selector(pattern, keep[Math.min(lane, keep.length - 1)]))
+                    )),
+                });
+
+                return Array.from({ length: dest }, (unused, lane) => (copies[lane] >= 0
+                    ? {
+                        value: operands[copies[lane]].value,
+                        lane: swizzle_selector(operands[copies[lane]].pattern, lane),
+                    }
+                    : { value: narrowed, lane: keep.indexOf(lane) }));
+            }
+
+            return node({ op, width: dest, operand_width: width, children, patterns });
+        }
+    }
+}

package/src/shade/renderer/particles/optimizer/dag/particle_vector_lower.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Give the groups an order and a register file, and write the instructions.
+ *
+ * By the time this runs there is nothing left to decide about WHAT the program computes — only when
+ * each instruction runs and which slots it uses. Those are the two halves of the register-count
+ * problem, and the notes' pipeline is exactly this: schedule for the fewest values alive at once,
+ * then colour, which for straight-line code is an interval graph and so optimal for a fixed order.
+ *
+ * ## Ordering
+ *
+ * The value graph left almost nothing to obey. There are no anti-dependencies at all — a value is
+ * not a register until this module makes it one, so the write-after-read and write-after-write
+ * hazards that constrain `../pass_schedule.js` do not exist here. What remains is the true data
+ * dependencies and ONE chain: the RNG draws come off a sequence, so the `RANDOM` groups keep their
+ * order among themselves. Stores and kills are free to go anywhere after the values they read, which
+ * is the practical difference between the two optimizers' schedules — over there a store is a
+ * barrier nothing crosses.
+ *
+ * The order is chosen by the same backward greedy `../pass_schedule.js` uses: place last the
+ * instruction that leaves fewest slots alive above it. It is a greedy, and a greedy can be fooled;
+ * an exact minimum-register schedule is a constraint-programming problem, which is where the notes
+ * point next and where a solver would be needed.
+ *
+ * ## Colouring
+ *
+ * A group's run is live from where it is written to the last instruction that reads it, so the live
+ * ranges are intervals and the lowest-base first fit is the classic optimal left-edge colouring —
+ * for SCALARS. A run of two or more is a shape rather than a point and first fit is then a
+ * heuristic; the same caveat `../pass_allocate_registers.js` carries, and the reason it is worth
+ * running that pass over the result afterwards.
+ *
+ * One exception to "sources are read before the destination is written", which is otherwise true of
+ * every instruction in this ISA and is what lets a destination reuse a slot that dies at the same
+ * instruction: a GATHER is several `MOV`s, and the first of them would clobber a slot a later one
+ * still has to read. So a gather's run is allocated before its operands are released and never
+ * overlaps them.
+ */
+/**
+ * @typedef {object} ParticleLoweredSection
+ * @property {InstructionStream} stream
+ * @property {number} peak the most slots alive at once, which is what the file has to hold
+ * @property {number[]} order the group indices, in the order they run
+ */
+/**
+ * @param {import("./particle_vector_groups.js").ParticleValuePacking} packing
+ * @param {object} params
+ * @param {number} params.register_slots
+ * @param {function(number[]): number} params.intern_constant adds a run to the shared pool and
+ *   returns its first word
+ * @returns {ParticleLoweredSection|null} `null` when the program does not fit the register file
+ */
+export function lower_particle_values(packing: import("./particle_vector_groups.js").ParticleValuePacking, { register_slots, intern_constant }: {
+    register_slots: number;
+    intern_constant: (arg0: number[]) => number;
+}): ParticleLoweredSection | null;
+/**
+ * Per group, the groups it must come after.
+ *
+ * @param {import("./particle_vector_groups.js").ParticleValueGroup[]} groups
+ * @returns {Set<number>[]}
+ */
+export function build_group_dependencies(groups: import("./particle_vector_groups.js").ParticleValueGroup[]): Set<number>[];
+/**
+ * The order the groups run in: whichever of two candidate schedules holds fewer slots at once.
+ *
+ * The first is the section's own order, rebuilt — a forward topological walk that always takes the
+ * ready group whose work came earliest. It is not clever and it is not meant to be; it is the
+ * schedule the program arrived with, which is a schedule somebody's frontend already thought about,
+ * and it is what stops this stage from ever being the reason a program stopped fitting.
+ *
+ * The second is the backward greedy `../pass_schedule.js` uses: place last the group that leaves
+ * fewest slots alive above it. It wins on programs whose values were computed a long way from where
+ * they are used — which is most hand-lowered code — and loses on programs made of many independent
+ * chains, where the liveness measure is flat and it interleaves twelve noise samples that should
+ * have been done one at a time.
+ *
+ * Neither is the minimum. An exact minimum-register schedule of a DAG is NP-complete and the answer
+ * at this size is a constraint solver, which is the next thing the notes point at; measuring two
+ * cheap orders and keeping the better is what is here instead, and it is at least never worse than
+ * the program's own.
+ *
+ * @param {import("./particle_vector_groups.js").ParticleValueGroup[]} groups
+ * @returns {number[]} group indices, in the order they run
+ */
+export function schedule_groups(groups: import("./particle_vector_groups.js").ParticleValueGroup[]): number[];
+/**
+ * The most slots an order holds at once — what the register file has to be.
+ *
+ * @param {import("./particle_vector_groups.js").ParticleValueGroup[]} groups
+ * @param {number[]} order
+ * @returns {number}
+ */
+export function peak_slots(groups: import("./particle_vector_groups.js").ParticleValueGroup[], order: number[]): number;
+/**
+ * Give each group's run the lowest base that is free for as long as it lives.
+ *
+ * @param {import("./particle_vector_groups.js").ParticleValueGroup[]} groups
+ * @param {number[]} order
+ * @param {number} register_slots
+ * @param {number[][]} [coalitions] runs that have to end up end to end, in that order
+ * @returns {Int32Array|null} per group, the slot its run starts at; `null` when the file is too small
+ */
+export function allocate_groups(groups: import("./particle_vector_groups.js").ParticleValueGroup[], order: number[], register_slots: number, coalitions?: number[][]): Int32Array | null;
+export type ParticleLoweredSection = {
+    stream: InstructionStream;
+    /**
+     * the most slots alive at once, which is what the file has to hold
+     */
+    peak: number;
+    /**
+     * the group indices, in the order they run
+     */
+    order: number[];
+};
+import { InstructionStream } from "../../isa/InstructionStream.js";
+//# sourceMappingURL=particle_vector_lower.d.ts.map

package/src/shade/renderer/particles/optimizer/dag/particle_vector_lower.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_vector_lower.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/optimizer/dag/particle_vector_lower.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,+CAPW,OAAO,6BAA6B,EAAE,oBAAoB;IAE3C,cAAc,EAA7B,MAAM;IAC6B,eAAe,SAAzC,MAAM,EAAE,KAAG,MAAM;IAExB,sBAAsB,GAAC,IAAI,CAiBvC;AAED;;;;;GAKG;AACH,iDAHW,OAAO,6BAA6B,EAAE,kBAAkB,EAAE,GACxD,IAAI,MAAM,CAAC,EAAE,CA0CzB;AAaD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wCAHW,OAAO,6BAA6B,EAAE,kBAAkB,EAAE,GACxD,MAAM,EAAE,CAoCpB;AAqGD;;;;;;GAMG;AACH,mCAJW,OAAO,6BAA6B,EAAE,kBAAkB,EAAE,SAC1D,MAAM,EAAE,GACN,MAAM,CAoClB;AAkID;;;;;;;;GAQG;AACH,wCANW,OAAO,6BAA6B,EAAE,kBAAkB,EAAE,SAC1D,MAAM,EAAE,kBACR,MAAM,eACN,MAAM,EAAE,EAAE,GACR,UAAU,GAAC,IAAI,CAoE3B;;YA5ea,iBAAiB;;;;UACjB,MAAM;;;;WACN,MAAM,EAAE;;kCA9CY,gCAAgC"}