@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/particles/graph/compile_particle_graph.js

@@ -1,205 +1,469 @@
-import { PARTICLE_VM_REGISTER_COUNT } from "../ParticleConstants.js";
-import { ParticleAssembler } from "../isa/ParticleAssembler.js";
-
-/**
- * Lower a single-phase particle {@link ../../../../core/model/node-graph/NodeGraph.js NodeGraph}
- * into a VM instruction stream.
- *
- * The graph describes one lifecycle phase (SPAWN or UPDATE) of a particle effect: nodes are
- * {@link ParticleNodeDescription} instances, and every connection wires a producing node's `out`
- * port to a consuming node's named input port.
- *
- * The pipeline:
- * 1. Walk the graph from its sinks (attribute writes / kill), flattening it into an SSA-style value
- *    list in dependency order. Shared sub-expressions are evaluated once (DAG sharing via
- *    memoisation).
- * 2. Compute each value's last use.
- * 3. Linear-scan register allocation: registers are returned to the pool at a value's last use, so a
- *    result can reuse a just-consumed input register (VM ops read all sources before writing dst).
- * 4. Emit each value's opcode via its node description.
- *
- * @param {NodeGraph} graph
- * @param {import("../isa/ParticleAssembler.js").InstructionStream} stream target section
- * @param {ParticleAssembler} asm assembler owning the shared constant pool
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout attribute schema
- */
-export function compile_particle_graph(graph, stream, asm, layout) {
-    const values = flatten(graph);
-    const last_use = compute_last_use(values);
-
-    const register_of = new Array(values.length).fill(-1);
-    const free = [];
-    for (let r = PARTICLE_VM_REGISTER_COUNT - 1; r >= 0; r--) {
-        free.push(r);
-    }
-
-    for (let i = 0; i < values.length; i++) {
-        const value = values[i];
-        const description = value.description;
-
-        // Capture the current registers of all inputs before we recycle any of them.
-        const input_registers = {};
-        for (const port of Object.keys(value.inputs)) {
-            input_registers[port] = register_of[value.inputs[port]];
-        }
-
-        // Return registers whose owning value dies at this instruction (its last consumer).
-        const freed = new Set();
-        for (const port of Object.keys(value.inputs)) {
-            const source = value.inputs[port];
-            if (last_use[source] === i && register_of[source] >= 0 && !freed.has(source)) {
-                free.push(register_of[source]);
-                register_of[source] = -1;
-                freed.add(source);
-            }
-        }
-
-        let out;
-        if (!description.is_sink) {
-            if (free.length === 0) {
-                throw new Error(
-                    `Particle graph exceeds the VM register file (${PARTICLE_VM_REGISTER_COUNT} registers). ` +
-                    `Simplify the effect or split it.`
-                );
-            }
-            out = free.pop();
-            register_of[i] = out;
-        }
-
-        description.emit(stream, {
-            in: (port) => input_registers[port],
-            out,
-            parameters: value.parameters,
-            layout,
-            asm,
-        });
-    }
-}
-
-/**
- * Compile a full effect (SPAWN + UPDATE) into a {@link ../isa/ParticleProgram.js}.
- *
- * @param {object} params
- * @param {NodeGraph} [params.spawn]
- * @param {NodeGraph} [params.update]
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @returns {import("../isa/ParticleProgram.js").ParticleProgram}
- */
-export function compile_particle_effect({ spawn, update, layout }) {
-    const asm = new ParticleAssembler();
-    if (spawn !== undefined) {
-        compile_particle_graph(spawn, asm.spawn, asm, layout);
-    }
-    if (update !== undefined) {
-        compile_particle_graph(update, asm.update, asm, layout);
-    }
-    const program = asm.build();
-    program.validate();
-    return program;
-}
-
-/**
- * Flatten a graph into a dependency-ordered value list. Each value is
- * `{ description, parameters, inputs: { port_name -> value_index } }`. The array order is a valid
- * topological order (every input has a lower index).
- * @param {NodeGraph} graph
- * @returns {Array<{description: ParticleNodeDescription, parameters: object, inputs: object}>}
- */
-function flatten(graph) {
-    const values = [];
-    const node_to_value = new Map();
-    const visiting = new Set();
-
-    /**
-     * @param {NodeInstance} node
-     * @returns {number} index of the node's value
-     */
-    function visit(node) {
-        const existing = node_to_value.get(node.id);
-        if (existing !== undefined) {
-            return existing;
-        }
-        if (visiting.has(node.id)) {
-            throw new Error(`Cycle detected in particle graph at node ${node.id}`);
-        }
-        visiting.add(node.id);
-
-        const description = require_particle_description(node);
-
-        const inputs = {};
-        for (const port of description.inPorts) {
-            inputs[port.name] = visit(resolve_input(node, port));
-        }
-
-        const vid = values.length;
-        values.push({ description, parameters: node.parameters, inputs });
-        node_to_value.set(node.id, vid);
-        visiting.delete(node.id);
-        return vid;
-    }
-
-    for (const node of graph.getNodes()) {
-        if (require_particle_description(node).is_sink) {
-            visit(node);
-        }
-    }
-
-    return values;
-}
-
-/**
- * @param {NodeInstance} node
- * @returns {ParticleNodeDescription}
- */
-function require_particle_description(node) {
-    const description = node.description;
-
-    if (description === null || description === undefined || description.isParticleNodeDescription !== true) {
-        throw new Error(`Node ${node.id} (${description}) is not a particle node, it cannot be compiled`);
-    }
-
-    return description;
-}
-
-/**
- * Find the node driving one input port of a node.
- * @param {NodeInstance} node
- * @param {Port} port an input port of the node's description
- * @returns {NodeInstance}
- * @throws if the port has no source, or more than one
- */
-function resolve_input(node, port) {
-    const endpoint = node.getEndpoint(port.id);
-
-    const connections = endpoint.inConnections;
-
-    if (connections.length === 0) {
-        throw new Error(`Node ${node.id} (${node.description.name}) is missing a binding for input '${port.name}'`);
-    }
-
-    if (connections.length > 1) {
-        throw new Error(
-            `Node ${node.id} (${node.description.name}) has ${connections.length} connections into input '${port.name}', ` +
-            `an input may have at most one`
-        );
-    }
-
-    return connections[0].source.instance;
-}
-
-/**
- * @param {Array} values
- * @returns {number[]} last_use[i] = highest index that consumes value i (or -1 if never consumed)
- */
-function compute_last_use(values) {
-    const last_use = new Array(values.length).fill(-1);
-    for (let i = 0; i < values.length; i++) {
-        for (const port of Object.keys(values[i].inputs)) {
-            const source = values[i].inputs[port];
-            if (i > last_use[source]) {
-                last_use[source] = i;
-            }
-        }
-    }
-    return last_use;
-}
+import { PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
+import { ParticleAssembler } from "../isa/ParticleAssembler.js";
+import { VM_MAX_WIDTH } from "../isa/ParticleVMISA.js";
+import { validate_particle_program } from "../isa/validate_particle_program.js";
+import { flatten_particle_graph } from "./flatten_particle_graph.js";
+import { infer_particle_graph_types } from "./infer_particle_graph_types.js";
+
+/**
+ * Lower a single-phase particle {@link ../../../../core/model/node-graph/NodeGraph.js NodeGraph}
+ * into a VM instruction stream.
+ *
+ * The graph describes one lifecycle phase (INIT or UPDATE) of a particle effect: nodes are
+ * {@link ParticleNodeDescription} instances, and every connection wires a producing node's `out`
+ * port to a consuming node's named input port.
+ *
+ * The pipeline:
+ * 0. Replace every node group with the nodes it is made of, until none is left — see
+ *    {@link ./flatten_particle_graph.js}. Everything after this point works on one flat expression
+ *    over the stock library, and so is written as though groups did not exist.
+ * 1. Walk the graph from its sinks (attribute writes / kill), flattening it into an SSA-style value
+ *    list in dependency order. Shared sub-expressions are evaluated once (DAG sharing via
+ *    memoisation).
+ * 2. Resolve every value's type — see {@link ./infer_particle_graph_types.js} — which is how many
+ *    lanes it has. A value whose type cannot be told is a graph that cannot be compiled.
+ * 3. Compute each value's last use, and how many lanes wide it has to be — see {@link compute_widths}.
+ * 4. Linear-scan register allocation. Registers are `f32` slots, so a value occupies a RUN of them
+ *    and allocation is first-fit over an occupancy map; runs are returned at a value's last use, so
+ *    a result can reuse a just-consumed input's slots (VM ops read all sources before writing dst).
+ * 5. Emit each value's opcode via its node description, at the width step 3 decided, and widen the
+ *    result where a consumer reads more lanes than the value's type has.
+ *
+ * @param {NodeGraph} graph
+ * @param {import("../isa/ParticleAssembler.js").InstructionStream} stream target section
+ * @param {ParticleAssembler} asm assembler owning the shared constant pool
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout attribute schema
+ */
+export function compile_particle_graph(graph, stream, asm, layout) {
+    // A graph with no groups in it comes back unchanged, so the node ids in anything raised below
+    // are the ids the author sees.
+    const source = flatten_particle_graph(graph);
+
+    if (source !== graph) {
+        // And where it does not, they are not. A node id in a message from here would name a node
+        // inside a group, under a number that exists nowhere an author can look — so the message
+        // says as much rather than sending them to hunt for it.
+        try {
+            return lower(source, stream, asm, layout);
+        } catch (e) {
+            throw new Error(`${e.message} (inside a node group, where node ids are not the graph's)`);
+        }
+    }
+
+    return lower(source, stream, asm, layout);
+}
+
+/**
+ * The compiler proper, over a graph that has no groups left in it.
+ *
+ * @param {NodeGraph} graph
+ * @param {import("../isa/ParticleAssembler.js").InstructionStream} stream
+ * @param {ParticleAssembler} asm
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout
+ */
+function lower(graph, stream, asm, layout) {
+    const values = flatten(graph);
+
+    resolve_types(values, graph, layout);
+
+    const last_use = compute_last_use(values);
+    const widths = compute_widths(values, layout);
+
+    const register_of = new Array(values.length).fill(-1);
+    const span_of = new Array(values.length).fill(0);
+
+    // A value now occupies a RUN of slots, so the free list is an occupancy map rather than a pool
+    // of interchangeable registers: allocation is first-fit over it, and can fail on fragmentation
+    // where a pool of equal-sized registers would not have.
+    const occupied = new Array(PARTICLE_VM_REGISTER_SLOTS).fill(false);
+
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+        const description = value.description;
+
+        // Capture the current registers of all inputs before we recycle any of them.
+        const input_registers = {};
+        for (const port of Object.keys(value.inputs)) {
+            input_registers[port] = register_of[value.inputs[port]];
+        }
+
+        // Return slots whose owning value dies at this instruction (its last consumer).
+        const freed = new Set();
+        for (const port of Object.keys(value.inputs)) {
+            const source = value.inputs[port];
+            if (last_use[source] === i && register_of[source] >= 0 && !freed.has(source)) {
+                release(occupied, register_of[source], span_of[source]);
+                register_of[source] = -1;
+                freed.add(source);
+            }
+        }
+
+        let out;
+        if (!description.is_sink) {
+            // The value has to hold everything asked of it — the result the instruction writes, and
+            // the width the widest consumer will read back.
+            const span = Math.max(widths[i].result, widths[i].demand);
+
+            // The slots just released are the ones the result would like to reuse, but it may only
+            // take them if it lands exactly on a source's run — an instruction reads slot `c` of a
+            // source to write slot `c` of its destination, so an aliased operand is fine and a
+            // shifted one would read slots it has already overwritten. Runs make that possible in a
+            // way interchangeable registers never did.
+            const sources = source_ranges(value, description, input_registers, widths[i], layout);
+
+            out = allocate(occupied, span, (base) => sources.every(
+                (range) => base === range.base || base + span <= range.base || range.base + range.span <= base
+            ));
+
+            if (out === -1) {
+                // The ISA's ceiling, not a shader's. A program that needs more than the fast
+                // interpreter's file has already been dealt with by the time it gets here — the
+                // runtime picks the wide interpreter for it — so reaching this is a graph too big
+                // for anything an instruction can address.
+                throw new Error(
+                    `Particle graph exceeds what a VM instruction can address: no run of ${span} free ` +
+                    `register slots in ${PARTICLE_VM_REGISTER_SLOTS}. Simplify the effect or split it.`
+                );
+            }
+
+            register_of[i] = out;
+            span_of[i] = span;
+        }
+
+        const width = widths[i];
+
+        description.emit(stream, {
+            in: (port) => input_registers[port],
+            out,
+            width: width.operation,
+            type: value.type,
+            input_types: value.input_types,
+            source_types: value.source_types,
+            parameters: value.parameters,
+            layout,
+            asm,
+        });
+
+        // A consumer that reads more lanes than the value has is a conversion, and it is made here,
+        // once, after the value is produced: a scalar is broadcast — in place, since the swizzle
+        // reads the lane it names before writing any — and a vector is extended with zeros. Either
+        // is what the four-lane register file used to hold past a value's content, less the work
+        // of computing lanes nobody reads.
+        if (!description.is_sink && width.result < width.demand) {
+            if (value.type.is_scalar) {
+                stream.broadcast(out, out, width.demand);
+            } else {
+                const missing = width.demand - width.result;
+
+                stream.loadConst(out + width.result, asm.constant(...new Array(missing).fill(0)), missing);
+            }
+        }
+    }
+}
+
+/**
+ * First-fit: the lowest run of `span` free slots that `is_acceptable` allows, or -1 when the file
+ * has no room for one.
+ *
+ * Lowest-first keeps allocations packed against the bottom of the file, which is what keeps the
+ * declared register count — and so the fragmentation a later allocation has to work around — as
+ * small as the graph allows.
+ *
+ * @param {boolean[]} occupied
+ * @param {number} span
+ * @param {function(number):boolean} [is_acceptable] rejects a base the caller cannot use
+ * @returns {number}
+ */
+function allocate(occupied, span, is_acceptable = () => true) {
+    for (let base = 0; base + span <= occupied.length; base++) {
+        let fits = true;
+
+        for (let slot = base; slot < base + span; slot++) {
+            if (occupied[slot]) {
+                fits = false;
+                break;
+            }
+        }
+
+        if (!fits || !is_acceptable(base)) {
+            continue;
+        }
+
+        for (let slot = base; slot < base + span; slot++) {
+            occupied[slot] = true;
+        }
+
+        return base;
+    }
+
+    return -1;
+}
+
+/**
+ * The slot runs an instruction's register sources name, so the allocator can keep the destination
+ * off any of them that it does not land on exactly.
+ *
+ * @param {{inputs: object, parameters: object, type: ParticleValueType|null, input_types: object, source_types: object}} value
+ * @param {ParticleNodeDescription} description
+ * @param {Object<string, number>} input_registers port -> the slot its value sits at
+ * @param {{operation: number}} width
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout
+ * @returns {Array<{base: number, span: number}>}
+ */
+function source_ranges(value, description, input_registers, width, layout) {
+    const overrides = description.input_widths(width_context(value, layout, { operation_width: width.operation }));
+
+    const ranges = [];
+
+    for (const port of Object.keys(value.inputs)) {
+        const base = input_registers[port];
+
+        if (base >= 0) {
+            ranges.push({ base, span: clamp_width(overrides[port] ?? width.operation) });
+        }
+    }
+
+    return ranges;
+}
+
+/**
+ * @param {boolean[]} occupied
+ * @param {number} base
+ * @param {number} span
+ */
+function release(occupied, base, span) {
+    for (let slot = base; slot < base + span; slot++) {
+        occupied[slot] = false;
+    }
+}
+
+/**
+ * What a description's width rules are told about a value.
+ *
+ * @param {{parameters: object, type: ParticleValueType|null, input_types: object, source_types: object}} value
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout
+ * @param {object} extra `demand` or `operation_width`, whichever the rule takes
+ * @returns {object}
+ */
+function width_context(value, layout, extra) {
+    return {
+        type: value.type,
+        input_types: value.input_types,
+        source_types: value.source_types,
+        parameters: value.parameters,
+        layout,
+        ...extra,
+    };
+}
+
+/**
+ * Decide how many lanes each value occupies, and how wide the instruction producing it runs.
+ *
+ * Backward pass: a value is as wide as the widest thing that asks for it, and a sink asks for
+ * exactly the attribute it writes. An instruction runs at the lanes wanted of it and never more
+ * than its type has — so a `vec4` literal feeding a three-component attribute is loaded three
+ * wide, and a `vec3` nobody reads past `.x` of is computed one wide. Where a consumer wants more
+ * lanes than the type has, the value is widened after it is produced (see the compile loop), and
+ * `demand` is what says by how much.
+ *
+ * @param {Array<{description: ParticleNodeDescription, parameters: object, inputs: object, type: ParticleValueType|null, input_types: object, source_types: object}>} values
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout
+ * @returns {Array<{operation: number, result: number, demand: number}>} indexed by value
+ */
+function compute_widths(values, layout) {
+    const demand = new Array(values.length).fill(1);
+
+    // Values are in dependency order, so walking backwards visits every consumer of a value before
+    // the value itself — one pass is enough, no fixed point to reach.
+    const result = new Array(values.length);
+
+    for (let i = values.length - 1; i >= 0; i--) {
+        const value = values[i];
+        const description = value.description;
+
+        const operation = clamp_width(description.operation_width(width_context(value, layout, { demand: demand[i] })));
+        const produced = clamp_width(description.result_width({ operation_width: operation, type: value.type }));
+
+        result[i] = { operation, result: produced, demand: demand[i] };
+
+        const overrides = description.input_widths(width_context(value, layout, { operation_width: operation }));
+
+        for (const port of Object.keys(value.inputs)) {
+            const wanted = clamp_width(overrides[port] ?? operation);
+            const source = value.inputs[port];
+
+            if (wanted > demand[source]) {
+                demand[source] = wanted;
+            }
+        }
+    }
+
+    return result;
+}
+
+/**
+ * @param {number} width
+ * @returns {number} width, held inside what a register operand can express
+ */
+function clamp_width(width) {
+    return Math.min(VM_MAX_WIDTH, Math.max(1, width));
+}
+
+/**
+ * Compile a full effect (INIT + UPDATE) into a {@link ../isa/ParticleProgram.js}.
+ *
+ * @param {object} params
+ * @param {NodeGraph} [params.init]
+ * @param {NodeGraph} [params.update]
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
+ * @returns {import("../isa/ParticleProgram.js").ParticleProgram}
+ */
+export function compile_particle_effect({ init, update, layout }) {
+    const asm = new ParticleAssembler();
+    if (init !== undefined) {
+        compile_particle_graph(init, asm.init, asm, layout);
+    }
+    if (update !== undefined) {
+        compile_particle_graph(update, asm.update, asm, layout);
+    }
+    const program = asm.build();
+    validate_particle_program(program);
+    return program;
+}
+
+/**
+ * Flatten a graph into a dependency-ordered value list. Each value is
+ * `{ node, description, parameters, inputs: { port_name -> value_index } }`. The array order is a
+ * valid topological order (every input has a lower index).
+ * @param {NodeGraph} graph
+ * @returns {Array<{node: number, description: ParticleNodeDescription, parameters: object, inputs: object}>}
+ */
+function flatten(graph) {
+    const values = [];
+    const node_to_value = new Map();
+    const visiting = new Set();
+
+    /**
+     * @param {NodeInstance} node
+     * @returns {number} index of the node's value
+     */
+    function visit(node) {
+        const existing = node_to_value.get(node.id);
+        if (existing !== undefined) {
+            return existing;
+        }
+        if (visiting.has(node.id)) {
+            throw new Error(`Cycle detected in particle graph at node ${node.id}`);
+        }
+        visiting.add(node.id);
+
+        const description = require_particle_description(node);
+
+        const inputs = {};
+        for (const port of description.inPorts) {
+            inputs[port.name] = visit(resolve_input(node, port));
+        }
+
+        const vid = values.length;
+        values.push({ node: node.id, description, parameters: node.parameters, inputs });
+        node_to_value.set(node.id, vid);
+        visiting.delete(node.id);
+        return vid;
+    }
+
+    for (const node of graph.getNodes()) {
+        if (require_particle_description(node).is_sink) {
+            visit(node);
+        }
+    }
+
+    return values;
+}
+
+/**
+ * Give every value its type, the type it reads each input as, and the type of each input's
+ * source. A value that produces something and has no type is a node whose parameters do not
+ * describe one — a literal with no components, a builtin that does not exist — and that is a
+ * graph the validator has a message for and the compiler does not go on with.
+ *
+ * @param {Array<{node: number, description: ParticleNodeDescription, inputs: object}>} values
+ * @param {NodeGraph} graph
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout
+ */
+function resolve_types(values, graph, layout) {
+    const types = infer_particle_graph_types(graph, { layout });
+
+    for (const value of values) {
+        value.type = types.output(value.node);
+        value.input_types = types.inputs(value.node);
+
+        if (!value.description.is_sink && value.type === null) {
+            throw new Error(
+                `Node ${value.node} (${value.description.name}) has no value type: its parameters do not describe one`
+            );
+        }
+
+        value.source_types = {};
+
+        for (const port of Object.keys(value.inputs)) {
+            value.source_types[port] = values[value.inputs[port]].type;
+        }
+    }
+}
+
+/**
+ * @param {NodeInstance} node
+ * @returns {ParticleNodeDescription}
+ */
+function require_particle_description(node) {
+    const description = node.description;
+
+    if (description === null || description === undefined || description.isParticleNodeDescription !== true) {
+        throw new Error(`Node ${node.id} (${description}) is not a particle node, it cannot be compiled`);
+    }
+
+    return description;
+}
+
+/**
+ * Find the node driving one input port of a node.
+ * @param {NodeInstance} node
+ * @param {Port} port an input port of the node's description
+ * @returns {NodeInstance}
+ * @throws if the port has no source, or more than one
+ */
+function resolve_input(node, port) {
+    const endpoint = node.getEndpoint(port.id);
+
+    const connections = endpoint.inConnections;
+
+    if (connections.length === 0) {
+        throw new Error(`Node ${node.id} (${node.description.name}) is missing a binding for input '${port.name}'`);
+    }
+
+    if (connections.length > 1) {
+        throw new Error(
+            `Node ${node.id} (${node.description.name}) has ${connections.length} connections into input '${port.name}', ` +
+            `an input may have at most one`
+        );
+    }
+
+    return connections[0].source.instance;
+}
+
+/**
+ * @param {Array} values
+ * @returns {number[]} last_use[i] = highest index that consumes value i (or -1 if never consumed)
+ */
+function compute_last_use(values) {
+    const last_use = new Array(values.length).fill(-1);
+    for (let i = 0; i < values.length; i++) {
+        for (const port of Object.keys(values[i].inputs)) {
+            const source = values[i].inputs[port];
+            if (i > last_use[source]) {
+                last_use[source] = i;
+            }
+        }
+    }
+    return last_use;
+}