@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,495 @@
+import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
+import { VM_MAX_WIDTH } from "../isa/ParticleVMISA.js";
+import { infer_particle_graph_types } from "./infer_particle_graph_types.js";
+import { is_particle_group_description } from "./ParticleNodeGroup.js";
+import {
+    PARTICLE_GRAPH_ERROR,
+    PARTICLE_GRAPH_INFO,
+    PARTICLE_GRAPH_WARNING,
+} from "./particle_graph_diagnostic.js";
+import { PARTICLE_PARAMETER_KIND, particle_node_parameters } from "./particle_node_parameters.js";
+import { is_particle_curve, is_particle_gradient } from "./particle_ramp.js";
+
+export {
+    PARTICLE_GRAPH_ERROR,
+    PARTICLE_GRAPH_INFO,
+    PARTICLE_GRAPH_WARNING,
+} from "./particle_graph_diagnostic.js";
+
+/**
+ * Check a particle graph and say what is wrong with it, per node.
+ *
+ * {@link ./compile_particle_graph.js} throws at the first problem, which is right for a compiler
+ * and useless for an editor: an author with three unbound inputs wants to see three markers, not to
+ * fix one and be told about the next. This walks the whole graph and reports everything, each
+ * finding carrying the node it belongs to so a view can put a marker on it.
+ *
+ * It is a pre-flight check, not a second compiler. It finds what can be seen from the graph's
+ * structure and its nodes' parameters; anything that only shows up while lowering — running out of
+ * registers, most obviously — is left to the compiler, whose exception the caller reports as a
+ * problem with the graph as a whole.
+ *
+ * A graph is one phase of an effect, and a caller that says which phase gets the checks that only
+ * mean something for one of them. Keeping that here rather than in the caller is what keeps every
+ * question about a graph answered in one place.
+ *
+ * The types are checked here too, by way of {@link ./infer_particle_graph_types.js}: a value read
+ * narrower or wider than it is comes back as a warning naming the lanes, against the node reading
+ * it. The shape of a finding is {@link ./particle_graph_diagnostic.js ParticleGraphDiagnostic}.
+ *
+ * ## What is not a problem
+ *
+ * Only what reaches a sink is compiled, so only what reaches a sink can be wrong. A node no sink
+ * depends on is reported once, as information, and nothing else found against it is reported at
+ * all — see {@link report_unreachable}, which has the last word on every finding here.
+ *
+ * ## Groups
+ *
+ * A {@link ./ParticleNodeGroup.js group} is checked as the node it looks like — its inputs must be
+ * bound, its ports are typed by what it declares — and not opened. What is inside one was settled
+ * when the group was built, and reporting a problem against a node an author cannot see, in a body
+ * they may not be allowed to edit, would be a diagnostic with nowhere to go. The compiler flattens
+ * the groups away and still refuses what it cannot lower, so nothing goes unchecked; it is only
+ * reported against the effect rather than against a node.
+ */
+
+/**
+ * The two phases of an effect, one graph each.
+ *
+ * INIT runs once when a particle is spawned, UPDATE once per frame while it lives. Named here
+ * because which of the two a graph is changes what is wrong with it, so it is something
+ * {@link validate_particle_graph} is told rather than something each caller decides for itself.
+ *
+ * @enum {string}
+ */
+export const PARTICLE_GRAPH_PHASE = Object.freeze({
+    INIT: "init",
+    UPDATE: "update",
+});
+
+/**
+ * @param {NodeGraph} graph
+ * @param {object} [context]
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
+ *   attribute schema; without it, attribute references cannot be checked and are left alone
+ * @param {string} [context.phase] which {@link PARTICLE_GRAPH_PHASE} this graph is; without it the
+ *   checks that only hold for one phase are skipped rather than guessed at
+ * @returns {ParticleGraphDiagnostic[]}
+ */
+export function validate_particle_graph(graph, { layout, phase } = {}) {
+    /** @type {ParticleGraphDiagnostic[]} */
+    const diagnostics = [];
+
+    const error = (node, message) => diagnostics.push({ node, message, severity: PARTICLE_GRAPH_ERROR });
+    const warning = (node, message) => diagnostics.push({ node, message, severity: PARTICLE_GRAPH_WARNING });
+
+    const nodes = graph.getNodes();
+
+    if (nodes.length === 0) {
+        // An empty phase is legitimate — an effect may have no UPDATE at all — so this is only worth
+        // saying about a graph someone is looking at, and it is not an error.
+        warning(-1, "This graph is empty, so it compiles to no instructions.");
+
+        return diagnostics;
+    }
+
+    /** @type {NodeInstance[]} */
+    const sinks = [];
+
+    for (const node of nodes) {
+        const description = node.description;
+
+        if (description === null || description === undefined || description.isParticleNodeDescription !== true) {
+            error(node.id, `'${description?.name ?? description}' is not a particle node and cannot be compiled.`);
+            continue;
+        }
+
+        if (description.is_sink) {
+            sinks.push(node);
+        }
+
+        check_inputs(node, description, error);
+        check_parameters(node, description, layout, error);
+    }
+
+    if (sinks.length === 0) {
+        error(
+            -1,
+            "Nothing in this graph writes an attribute or kills a particle, so none of it runs. "
+            + "Compilation starts from the sinks."
+        );
+    }
+
+    report_duplicate_writes(sinks, layout, error);
+    report_missing_kill(sinks, phase, warning);
+    report_cycles(nodes, error);
+    report_conversions(graph, layout, diagnostics);
+
+    return report_unreachable(nodes, sinks, diagnostics);
+}
+
+/**
+ * Every input must be driven by exactly one source. More than one is not a merge — the compiler has
+ * no rule for picking — and none leaves a register with nothing in it.
+ *
+ * @param {NodeInstance} node
+ * @param {ParticleNodeDescription} description
+ * @param {function(number, string):void} error
+ */
+function check_inputs(node, description, error) {
+    for (const port of description.getPortsByDirection(PortDirection.In)) {
+        const connections = node.getEndpoint(port.id).inConnections;
+
+        if (connections.length === 0) {
+            error(node.id, `Input '${port.name}' has nothing connected to it.`);
+        } else if (connections.length > 1) {
+            error(
+                node.id,
+                `Input '${port.name}' has ${connections.length} sources connected to it; an input takes one.`
+            );
+        }
+    }
+}
+
+/**
+ * @param {NodeInstance} node
+ * @param {ParticleNodeDescription} description
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} layout
+ * @param {function(number, string):void} error
+ */
+function check_parameters(node, description, layout, error) {
+    if (is_particle_group_description(description)) {
+        // A group's configuration is its wiring and its boundary blocks are its edge; neither
+        // declares parameters, and what is inside a group was checked when the group was built.
+        return;
+    }
+
+    let parameters;
+
+    try {
+        parameters = particle_node_parameters(description.name);
+    } catch (e) {
+        error(node.id, e.message);
+        return;
+    }
+
+    for (const parameter of parameters) {
+        const value = node.getParameterValue(parameter.name);
+
+        if (value === undefined) {
+            error(node.id, `Parameter '${parameter.name}' has no value.`);
+            continue;
+        }
+
+        switch (parameter.kind) {
+            case PARTICLE_PARAMETER_KIND.ATTRIBUTE:
+                if (layout !== undefined && !layout.has(value)) {
+                    error(
+                        node.id,
+                        `'${value}' is not an attribute of this effect. It has: `
+                        + `${Array.from(layout.attributes.keys()).join(", ") || "none"}.`
+                    );
+                }
+                break;
+
+            case PARTICLE_PARAMETER_KIND.ENUM:
+                if (!Object.values(parameter.options).includes(value)) {
+                    error(
+                        node.id,
+                        `'${value}' is not a value '${parameter.name}' takes. `
+                        + `Expected one of: ${Object.keys(parameter.options).join(", ")}.`
+                    );
+                }
+                break;
+
+            case PARTICLE_PARAMETER_KIND.COLOR:
+                // A colour is a vec4 and only ever a vec4: unlike a literal, its width is what the
+                // node's type says rather than what the value happens to hold.
+                if (!Array.isArray(value) || value.length !== 4 || value.some(v => typeof v !== "number")) {
+                    error(node.id, `Parameter '${parameter.name}' must be four numbers: red, green, blue and alpha.`);
+                }
+                break;
+
+            case PARTICLE_PARAMETER_KIND.VECTOR:
+                if (
+                    !Array.isArray(value) || value.length < 1 || value.length > VM_MAX_WIDTH
+                    || value.some(v => typeof v !== "number")
+                ) {
+                    error(node.id, `Parameter '${parameter.name}' must be one to ${VM_MAX_WIDTH} numbers.`);
+                }
+                break;
+
+            case PARTICLE_PARAMETER_KIND.SWIZZLE:
+                if (
+                    !Array.isArray(value) || value.length < 1 || value.length > VM_MAX_WIDTH
+                    || value.some(v => !Number.isInteger(v) || v < 0 || v >= VM_MAX_WIDTH)
+                ) {
+                    error(
+                        node.id,
+                        `Parameter '${parameter.name}' must be one to ${VM_MAX_WIDTH} lane selectors in 0..${VM_MAX_WIDTH - 1}.`
+                    );
+                }
+                break;
+
+            case PARTICLE_PARAMETER_KIND.INTEGER:
+                if (!Number.isInteger(value) || value < 0) {
+                    error(node.id, `Parameter '${parameter.name}' must be a non-negative whole number.`);
+                }
+                break;
+
+            // A curve and a gradient are the only parameters with a shape underneath them, and both
+            // are written out into instructions rather than read at runtime — so a malformed one is
+            // a compile that throws rather than a value that misbehaves, and it is worth catching
+            // here where it can be put on the node.
+            case PARTICLE_PARAMETER_KIND.CURVE:
+                if (!is_particle_curve(value)) {
+                    error(
+                        node.id,
+                        `Parameter '${parameter.name}' must be a curve: `
+                        + "keys of time, value, inTangent and outTangent, all finite numbers."
+                    );
+                }
+                break;
+
+            case PARTICLE_PARAMETER_KIND.GRADIENT:
+                if (!is_particle_gradient(value)) {
+                    error(
+                        node.id,
+                        `Parameter '${parameter.name}' must be a gradient: `
+                        + "stops of a finite position and four finite colour channels."
+                    );
+                } else if (value.length === 0) {
+                    error(node.id, `Parameter '${parameter.name}' has no stops, so it has no colour.`);
+                }
+                break;
+
+            default:
+                break;
+        }
+    }
+}
+
+/**
+ * The two sinks the checks below are about, by the names {@link ./ParticleNodeRegistry.js} gives
+ * them. What each check tests is what a sink *does* — store a value, end a life — and the library
+ * says which does what by type, so a sink added to it that also stores or also kills belongs here.
+ */
+const SET_ATTRIBUTE_NODE = "setAttribute";
+const KILL_NODE = "kill";
+
+/**
+ * A `setAttribute` node lowers to a store at its attribute's offset, and the program is
+ * straight-line: two stores to one attribute both run, and which of them is last — which is to say
+ * which value survives — is whatever order the compiler's traversal happened to take. That is not a
+ * merge anyone asked for. Combining two values is a `select` or a `mix` in front of one write.
+ *
+ * Reported against every node that writes the attribute, for the reason {@link report_cycles}
+ * reports against every node on a cycle: no one of them is the offender.
+ *
+ * Per graph, not per effect. Writing `age` in INIT and again in UPDATE is how a particle ages —
+ * two programs, one store each.
+ *
+ * @param {NodeInstance[]} sinks
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} layout
+ * @param {function(number, string):void} error
+ */
+function report_duplicate_writes(sinks, layout, error) {
+    /** @type {Map<*, NodeInstance[]>} attribute -> the nodes writing it */
+    const writers = new Map();
+
+    for (const node of sinks) {
+        if (node.description.name !== SET_ATTRIBUTE_NODE) {
+            continue;
+        }
+
+        const attribute = node.getParameterValue("name");
+
+        if (attribute === undefined) {
+            // the node names no attribute at all; check_parameters has already said so
+            continue;
+        }
+
+        if (layout !== undefined && !layout.has(attribute)) {
+            // The attribute does not exist, so neither store is one the compiler will ever emit and
+            // there is no race to report. What is wrong with these nodes is the name they carry, and
+            // check_parameters has already said that about each of them.
+            continue;
+        }
+
+        const written = writers.get(attribute);
+
+        if (written === undefined) {
+            writers.set(attribute, [node]);
+        } else {
+            written.push(node);
+        }
+    }
+
+    for (const [attribute, written] of writers) {
+        if (written.length < 2) {
+            continue;
+        }
+
+        for (const node of written) {
+            error(
+                node.id,
+                `${written.length} nodes write '${attribute}' in this phase, and nothing orders them. `
+                + "Every store runs, so the value that survives is whichever one the compiler reaches "
+                + "last. Combine them with a 'select' or a 'mix' and write the attribute once."
+            );
+        }
+    }
+}
+
+/**
+ * A particle nothing kills lives until the emitter's pool comes round to its slot and spawns over
+ * it, which is almost never the effect someone meant to build. Almost never rather than never — a
+ * host may be managing lifetime itself — so this is a warning.
+ *
+ * Only for UPDATE, and only for a graph that does something. An INIT with no kill is ordinary: a
+ * particle that dies in the frame it is born is the odd one. A graph with no sinks at all is
+ * already an error that says more than this would.
+ *
+ * @param {NodeInstance[]} sinks
+ * @param {string|undefined} phase a {@link PARTICLE_GRAPH_PHASE}, or nothing if the caller did not
+ *   say which graph this is
+ * @param {function(number, string):void} warning
+ */
+function report_missing_kill(sinks, phase, warning) {
+    if (phase !== PARTICLE_GRAPH_PHASE.UPDATE || sinks.length === 0) {
+        return;
+    }
+
+    if (sinks.some(node => node.description.name === KILL_NODE)) {
+        return;
+    }
+
+    warning(
+        -1,
+        "Nothing in this graph kills a particle, so one lives until the emitter recycles its slot. "
+        + "A 'kill' node fed a condition — usually age against lifetime — is what ends one on time."
+    );
+}
+
+/**
+ * A value wired into a port that reads it as a different shape is converted on the way in — a
+ * wider vector keeps its leading lanes, a narrower one reads zero past its content — and each such
+ * conversion is worth a word, because a `vec4` literal feeding a three-component attribute is
+ * either a slip or a literal that ought to be a `vec3`. A scalar meeting a vector broadcasts, which
+ * is what a scalar is for, and says nothing.
+ *
+ * The types come from the same pass the compiler runs, so what is reported is what will be lowered.
+ * It is tolerant of everything reported above — an unbound input has no type and no conversion —
+ * so nothing is said twice.
+ *
+ * @param {NodeGraph} graph
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} layout
+ * @param {ParticleGraphDiagnostic[]} diagnostics
+ */
+function report_conversions(graph, layout, diagnostics) {
+    diagnostics.push(...infer_particle_graph_types(graph, { layout }).diagnostics);
+}
+
+/**
+ * Have the last word on the nodes no sink depends on.
+ *
+ * Compilation starts from the sinks, so a node nothing downstream reads is never lowered: it cannot
+ * break the effect and it cannot cost an instruction. Half a graph waiting to be wired up is what
+ * most of authoring looks like, and an editor that called that an error would refuse to compile the
+ * working half over it — so everything found against such a node is dropped, and what is said in
+ * its place is the one thing an author cannot see for themselves: that it is not running.
+ *
+ * The note is {@link PARTICLE_GRAPH_INFO}, which is not a problem with the graph. Findings about the
+ * graph as a whole are left alone, being about no node and so about none of this.
+ *
+ * @param {NodeInstance[]} nodes
+ * @param {NodeInstance[]} sinks
+ * @param {ParticleGraphDiagnostic[]} diagnostics everything the checks above found
+ * @returns {ParticleGraphDiagnostic[]}
+ */
+function report_unreachable(nodes, sinks, diagnostics) {
+    const reached = new Set();
+    const stack = sinks.slice();
+
+    while (stack.length > 0) {
+        const node = stack.pop();
+
+        if (reached.has(node.id)) {
+            continue;
+        }
+
+        reached.add(node.id);
+
+        for (const connection of node.inConnections) {
+            stack.push(connection.source.instance);
+        }
+    }
+
+    const kept = diagnostics.filter(diagnostic => diagnostic.node < 0 || reached.has(diagnostic.node));
+
+    for (const node of nodes) {
+        if (!reached.has(node.id)) {
+            kept.push({
+                node: node.id,
+                message: "Nothing downstream reads this node, so it is left out when the graph is compiled.",
+                severity: PARTICLE_GRAPH_INFO,
+            });
+        }
+    }
+
+    return kept;
+}
+
+/**
+ * A cycle has no evaluation order, so the compiler cannot flatten it. Reported against every node on
+ * the cycle, because which one is "the" offender is a matter of where you started walking.
+ *
+ * @param {NodeInstance[]} nodes
+ * @param {function(number, string):void} error
+ */
+function report_cycles(nodes, error) {
+    const WHITE = 0;
+    const GREY = 1;
+    const BLACK = 2;
+
+    const colour = new Map(nodes.map(node => [node.id, WHITE]));
+
+    /** @type {Set<number>} nodes found on some cycle */
+    const on_cycle = new Set();
+
+    /**
+     * @param {NodeInstance} node
+     * @param {NodeInstance[]} path the grey stack, innermost last
+     */
+    function visit(node, path) {
+        colour.set(node.id, GREY);
+        path.push(node);
+
+        for (const connection of node.inConnections) {
+            const source = connection.source.instance;
+            const state = colour.get(source.id);
+
+            if (state === GREY) {
+                // everything from where the source sits on the stack down to here is on the cycle
+                for (let i = path.lastIndexOf(source); i < path.length; i++) {
+                    on_cycle.add(path[i].id);
+                }
+            } else if (state === WHITE) {
+                visit(source, path);
+            }
+        }
+
+        path.pop();
+        colour.set(node.id, BLACK);
+    }
+
+    for (const node of nodes) {
+        if (colour.get(node.id) === WHITE) {
+            visit(node, []);
+        }
+    }
+
+    for (const id of on_cycle) {
+        error(id, "This node is part of a loop. A particle graph has no evaluation order for one.");
+    }
+}