@woosh/meep-engine 3.15.0 → 3.16.0

package/src/shade/renderer/particles/graph/make_particle_group.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Turn part of a graph into a group.
+ *
+ * The counterpart of {@link ./ParticleGroupBuilder.js}, which writes a body in JavaScript: this makes
+ * one out of nodes an author already wired up and is looking at. Everything hard about it is the
+ * boundary — which wires crossed it, what the ports they become should be called, and what type each
+ * of them is — and none of that is a choice the author should have to make before they can see the
+ * result.
+ *
+ * ## What becomes a port
+ *
+ * A wire from outside into the selection becomes an input; a wire from the selection out becomes an
+ * output. Both are grouped by the *endpoint on the other side*, so one value feeding three nodes
+ * inside is one input rather than three, and one value read by three nodes outside is one output.
+ * That is what makes the group's face the shape of the thing that was selected rather than the shape
+ * of how it happened to be wired.
+ *
+ * A wire that starts and ends inside the selection is simply inside; a wire between two nodes outside
+ * it is none of the group's business.
+ *
+ * ## What the ports are called
+ *
+ * An input takes the name of the port it feeds — `a`, `x`, `t` — because that is what the value is
+ * *for*, and it is the word already on screen next to it. An output takes the name of the node that
+ * produces it. Both are made unique with a number where they collide, and both are the author's to
+ * change afterwards: a group's face is a decision, and this is only the first guess at it.
+ *
+ * ## What type they are
+ *
+ * Whatever the graph resolved them to at the moment of grouping. A port whose type could not be told
+ * — an unbound input somewhere upstream — is declared with none, which means it takes the shape of
+ * what arrives. That is the right answer for an unknown and it is also the right answer for a group
+ * that genuinely does the same thing at any width, so a first guess of `null` is never wrong in a way
+ * that has to be corrected before the group works.
+ *
+ * ## What comes back
+ *
+ * The group, and the wiring the caller has to re-make around it: which outer endpoint drives each of
+ * its inputs, and which outer endpoints each of its outputs drives. The caller does that part,
+ * because doing it is an edit to somebody's graph and this function does not edit graphs.
+ */
+/**
+ * The nodes and wires of a selection, moved into a group of their own.
+ *
+ * `graph` is not modified. What comes back describes an edit the caller is free to make, or not.
+ *
+ * @param {object} params
+ * @param {NodeGraph} params.graph the graph the selection is in
+ * @param {Iterable<number>} params.nodes ids of the nodes to group
+ * @param {string} params.name the group's library address
+ * @param {string} [params.label] what to call it; the name by default
+ * @param {string} [params.help]
+ * @param {string} [params.icon]
+ * @param {NodeGraphVisualData} [params.visual] where the selected nodes sit, so the body opens
+ *        arranged the way it was when it was grouped rather than in a heap at the origin. Without a
+ *        `visualRegistry` to go with it the arrangement is not kept, because a body with some of its
+ *        nodes placed and its boundary blocks at the origin is worse than one that arranges itself.
+ * @param {NodeDescriptionVisualRegistry} [params.visualRegistry] where the boundary blocks get their
+ *        boxes from; told about this group's own node types on the way
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [params.layout] the effect's
+ *        attribute schema, for resolving the types the ports are declared with
+ * @returns {{
+ *   group: ParticleNodeGroup,
+ *   inputs: Array<{port: string, from: {node: number, port: number}}>,
+ *   outputs: Array<{port: string, to: Array<{node: number, port: number}>}>
+ * }} the group, and the wires to re-make around the node that replaces the selection
+ * @throws if the selection is empty, holds a node the graph does not have, or holds a group's own
+ *   boundary block
+ */
+export function particle_group_from_nodes({ graph, nodes, name, label, help, icon, visual, visualRegistry, layout, }: {
+    graph: NodeGraph;
+    nodes: Iterable<number>;
+    name: string;
+    label?: string;
+    help?: string;
+    icon?: string;
+    visual?: NodeGraphVisualData;
+    visualRegistry?: NodeDescriptionVisualRegistry;
+    layout?: import("../layout/ParticleLayout.js").ParticleLayout;
+}): {
+    group: ParticleNodeGroup;
+    inputs: Array<{
+        port: string;
+        from: {
+            node: number;
+            port: number;
+        };
+    }>;
+    outputs: Array<{
+        port: string;
+        to: Array<{
+            node: number;
+            port: number;
+        }>;
+    }>;
+};
+import { ParticleNodeGroup } from "./ParticleNodeGroup.js";
+//# sourceMappingURL=make_particle_group.d.ts.map

package/src/shade/renderer/particles/graph/make_particle_group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_particle_group.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/make_particle_group.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAtB6B,KAAK;IACE,KAAK,EAA9B,SAAS,MAAM,CAAC;IACD,IAAI,EAAnB,MAAM;IACU,KAAK,GAArB,MAAM;IACU,IAAI,GAApB,MAAM;IACU,IAAI,GAApB,MAAM;IACuB,MAAM;IAII,cAAc;IAES,MAAM,GAApE,OAAO,6BAA6B,EAAE,cAAc;;WAGnD,iBAAiB;YAChB,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAC;aACxD,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAC,CAAA;KAAC,CAAC;EAgE3E;kCAnI6D,wBAAwB"}

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

@@ -0,0 +1,427 @@
+import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
+import { infer_particle_graph_types } from "./infer_particle_graph_types.js";
+import { is_particle_group_boundary, ParticleNodeGroup } from "./ParticleNodeGroup.js";
+
+/**
+ * Turn part of a graph into a group.
+ *
+ * The counterpart of {@link ./ParticleGroupBuilder.js}, which writes a body in JavaScript: this makes
+ * one out of nodes an author already wired up and is looking at. Everything hard about it is the
+ * boundary — which wires crossed it, what the ports they become should be called, and what type each
+ * of them is — and none of that is a choice the author should have to make before they can see the
+ * result.
+ *
+ * ## What becomes a port
+ *
+ * A wire from outside into the selection becomes an input; a wire from the selection out becomes an
+ * output. Both are grouped by the *endpoint on the other side*, so one value feeding three nodes
+ * inside is one input rather than three, and one value read by three nodes outside is one output.
+ * That is what makes the group's face the shape of the thing that was selected rather than the shape
+ * of how it happened to be wired.
+ *
+ * A wire that starts and ends inside the selection is simply inside; a wire between two nodes outside
+ * it is none of the group's business.
+ *
+ * ## What the ports are called
+ *
+ * An input takes the name of the port it feeds — `a`, `x`, `t` — because that is what the value is
+ * *for*, and it is the word already on screen next to it. An output takes the name of the node that
+ * produces it. Both are made unique with a number where they collide, and both are the author's to
+ * change afterwards: a group's face is a decision, and this is only the first guess at it.
+ *
+ * ## What type they are
+ *
+ * Whatever the graph resolved them to at the moment of grouping. A port whose type could not be told
+ * — an unbound input somewhere upstream — is declared with none, which means it takes the shape of
+ * what arrives. That is the right answer for an unknown and it is also the right answer for a group
+ * that genuinely does the same thing at any width, so a first guess of `null` is never wrong in a way
+ * that has to be corrected before the group works.
+ *
+ * ## What comes back
+ *
+ * The group, and the wiring the caller has to re-make around it: which outer endpoint drives each of
+ * its inputs, and which outer endpoints each of its outputs drives. The caller does that part,
+ * because doing it is an edit to somebody's graph and this function does not edit graphs.
+ */
+
+/**
+ * The nodes and wires of a selection, moved into a group of their own.
+ *
+ * `graph` is not modified. What comes back describes an edit the caller is free to make, or not.
+ *
+ * @param {object} params
+ * @param {NodeGraph} params.graph the graph the selection is in
+ * @param {Iterable<number>} params.nodes ids of the nodes to group
+ * @param {string} params.name the group's library address
+ * @param {string} [params.label] what to call it; the name by default
+ * @param {string} [params.help]
+ * @param {string} [params.icon]
+ * @param {NodeGraphVisualData} [params.visual] where the selected nodes sit, so the body opens
+ *        arranged the way it was when it was grouped rather than in a heap at the origin. Without a
+ *        `visualRegistry` to go with it the arrangement is not kept, because a body with some of its
+ *        nodes placed and its boundary blocks at the origin is worse than one that arranges itself.
+ * @param {NodeDescriptionVisualRegistry} [params.visualRegistry] where the boundary blocks get their
+ *        boxes from; told about this group's own node types on the way
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [params.layout] the effect's
+ *        attribute schema, for resolving the types the ports are declared with
+ * @returns {{
+ *   group: ParticleNodeGroup,
+ *   inputs: Array<{port: string, from: {node: number, port: number}}>,
+ *   outputs: Array<{port: string, to: Array<{node: number, port: number}>}>
+ * }} the group, and the wires to re-make around the node that replaces the selection
+ * @throws if the selection is empty, holds a node the graph does not have, or holds a group's own
+ *   boundary block
+ */
+export function particle_group_from_nodes({
+                                              graph,
+                                              nodes,
+                                              name,
+                                              label = "",
+                                              help = "",
+                                              icon = "",
+                                              visual,
+                                              visualRegistry,
+                                              layout,
+                                          }) {
+    const selected = new Set(nodes);
+
+    if (selected.size === 0) {
+        throw new Error("A group is made out of something; nothing was selected.");
+    }
+
+    for (const id of selected) {
+        const node = graph.getNode(id);
+
+        if (node === undefined) {
+            throw new Error(`Node ${id} is not in this graph, so it cannot be grouped.`);
+        }
+
+        if (is_particle_group_boundary(node)) {
+            throw new Error("A group's own input and output blocks are its edge; they cannot be grouped.");
+        }
+    }
+
+    if (selection_is_re_entered(graph, selected)) {
+        throw new Error(
+            "Grouping these would make a loop: something outside the selection reads one of them and "
+            + "is read by another, so the group would feed itself. Select what is in between as well."
+        );
+    }
+
+    const types = infer_particle_graph_types(graph, { layout });
+
+    const boundary = read_boundary(graph, selected, types);
+
+    const group = ParticleNodeGroup.create({
+        name,
+        label,
+        help,
+        icon,
+        // Made here, so it is the author's to change. Everything the library ships is locked; nothing
+        // an author makes is.
+        locked: false,
+        inputs: boundary.inputs.map(entry => ({ name: entry.port, type: entry.type })),
+        outputs: boundary.outputs.map(entry => ({ name: entry.port, type: entry.type })),
+    });
+
+    fill_body(group, graph, selected, boundary, visual, visualRegistry);
+
+    return {
+        group,
+        inputs: boundary.inputs.map(entry => ({ port: entry.port, from: entry.from })),
+        outputs: boundary.outputs.map(entry => ({ port: entry.port, to: entry.to })),
+    };
+}
+
+/**
+ * Whether a value leaves the selection and comes back into it.
+ *
+ * The one shape that cannot be grouped. A group is a single node, so everything the selection reads
+ * is read before it runs and everything it produces is produced after — and if something *outside*
+ * sits between two selected nodes, the group would have to run both before and after that thing.
+ * Made anyway, it is a graph with the group wired to itself, which the validator reports as a loop
+ * against nodes the author never touched.
+ *
+ * Walked downstream from the selection rather than reasoned about, because that is the same question
+ * and needs no cases. An outer graph that already has a cycle in it terminates on the visited set.
+ *
+ * @param {NodeGraph} graph
+ * @param {Set<number>} selected
+ * @returns {boolean}
+ */
+function selection_is_re_entered(graph, selected) {
+    /** @type {NodeInstance[]} */
+    const stack = [];
+
+    for (const id of selected) {
+        for (const connection of graph.getNodeSafe(id).outConnections) {
+            if (!selected.has(connection.target.instance.id)) {
+                stack.push(connection.target.instance);
+            }
+        }
+    }
+
+    const seen = new Set();
+
+    while (stack.length > 0) {
+        const node = stack.pop();
+
+        if (selected.has(node.id)) {
+            return true;
+        }
+
+        if (seen.has(node.id)) {
+            continue;
+        }
+
+        seen.add(node.id);
+
+        for (const connection of node.outConnections) {
+            stack.push(connection.target.instance);
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Work out what crosses the selection's edge, and what each crossing should become.
+ *
+ * @param {NodeGraph} graph
+ * @param {Set<number>} selected
+ * @param {import("./infer_particle_graph_types.js").ParticleGraphTypes} types
+ * @returns {{inputs: Array<object>, outputs: Array<object>}}
+ */
+function read_boundary(graph, selected, types) {
+    /** @type {Map<string, object>} outer source endpoint -> the input it becomes */
+    const inputs = new Map();
+
+    /** @type {Map<string, object>} inner source endpoint -> the output it becomes */
+    const outputs = new Map();
+
+    // Inputs and outputs are separate namespaces — one side of the node each — so a group may have an
+    // `x` going in and an `x` coming out without either being renamed.
+    const claimed_inputs = new Set();
+    const claimed_outputs = new Set();
+
+    for (const connection of graph.getConnections()) {
+        const source = connection.source;
+        const target = connection.target;
+
+        const source_inside = selected.has(source.instance.id);
+        const target_inside = selected.has(target.instance.id);
+
+        if (source_inside === target_inside) {
+            // wholly inside, or nothing to do with the selection
+            continue;
+        }
+
+        const key = `${source.instance.id}/${source.port.id}`;
+
+        if (target_inside) {
+            const existing = inputs.get(key);
+
+            if (existing !== undefined) {
+                // one value feeding several nodes inside is one input, not several
+                existing.into.push({ node: target.instance.id, port: target.port.id });
+
+                continue;
+            }
+
+            inputs.set(key, {
+                port: unique_name(target.port.name, claimed_inputs),
+                type: types.output(source.instance.id, source.port.name),
+                from: { node: source.instance.id, port: source.port.id },
+                into: [{ node: target.instance.id, port: target.port.id }],
+            });
+
+            continue;
+        }
+
+        const existing = outputs.get(key);
+
+        if (existing !== undefined) {
+            existing.to.push({ node: target.instance.id, port: target.port.id });
+
+            continue;
+        }
+
+        outputs.set(key, {
+            port: unique_name(source.instance.description.name, claimed_outputs),
+            type: types.output(source.instance.id, source.port.name),
+            from: { node: source.instance.id, port: source.port.id },
+            to: [{ node: target.instance.id, port: target.port.id }],
+        });
+    }
+
+    return { inputs: Array.from(inputs.values()), outputs: Array.from(outputs.values()) };
+}
+
+/**
+ * Copy the selection into the group's body, and wire its edge up to the boundary blocks.
+ *
+ * @param {ParticleNodeGroup} group
+ * @param {NodeGraph} graph
+ * @param {Set<number>} selected
+ * @param {{inputs: Array<object>, outputs: Array<object>}} boundary
+ * @param {NodeGraphVisualData|undefined} visual
+ * @param {NodeDescriptionVisualRegistry|undefined} visualRegistry
+ */
+function fill_body(group, graph, selected, boundary, visual, visualRegistry) {
+    const body = group.graph;
+
+    // An arrangement is only kept when the boundary blocks can be placed alongside it. See the note
+    // on `visual` in the signature.
+    const keep_arrangement = visual !== undefined && visualRegistry !== undefined;
+
+    /** @type {Map<number, NodeInstance>} outer node id -> its copy inside the group */
+    const copies = new Map();
+
+    for (const id of selected) {
+        const outer = graph.getNodeSafe(id);
+
+        const copy = body.getNodeSafe(body.createNode(outer.description));
+
+        copy.setParameters(clone_parameters(outer.parameters));
+
+        copies.set(id, copy);
+
+        if (keep_arrangement) {
+            // The body opens looking like what was grouped. A node's size is measured when it is
+            // drawn, but where the author put it is theirs and is worth keeping.
+            const placed = visual.getNode(id);
+
+            if (placed !== undefined) {
+                const copied = placed.clone();
+
+                copied.id = copy.id;
+
+                group.visual.addNode(copy.id, copied);
+            }
+        }
+    }
+
+    for (const connection of graph.getConnections()) {
+        const source = connection.source;
+        const target = connection.target;
+
+        if (!selected.has(source.instance.id) || !selected.has(target.instance.id)) {
+            continue;
+        }
+
+        body.createConnection(
+            copies.get(source.instance.id).id, source.port.id,
+            copies.get(target.instance.id).id, target.port.id
+        );
+    }
+
+    for (const entry of boundary.inputs) {
+        const from = group.inputNode.description.findPortByNameAndDirection(entry.port, PortDirection.Out);
+
+        for (const into of entry.into) {
+            body.createConnection(group.inputNode.id, from.id, copies.get(into.node).id, into.port);
+        }
+    }
+
+    for (const entry of boundary.outputs) {
+        const into = group.outputNode.description.findPortByNameAndDirection(entry.port, PortDirection.In);
+
+        body.createConnection(copies.get(entry.from.node).id, entry.from.port, group.outputNode.id, into.id);
+    }
+
+    if (keep_arrangement) {
+        place_boundary(group, visualRegistry);
+    }
+}
+
+/**
+ * How far to the side of the body its boundary blocks sit, in graph units.
+ * @type {number}
+ */
+const BOUNDARY_MARGIN = 220;
+
+/**
+ * Put the two boundary blocks either side of the body they belong to.
+ *
+ * A body that keeps the arrangement it was grouped from has every node placed except these two,
+ * which have never been anywhere — and left alone they would land at the origin, which is on top of
+ * the work about as often as not. Values arrive from the left and leave to the right, which is the
+ * direction every wire in the editor is already drawn in, so that is where they go.
+ *
+ * @param {ParticleNodeGroup} group
+ * @param {NodeDescriptionVisualRegistry} visualRegistry
+ */
+function place_boundary(group, visualRegistry) {
+    for (const description of [
+        group.description,
+        group.inputNode.description,
+        group.outputNode.description,
+    ]) {
+        // the group's own types are new to every registry, this one included
+        visualRegistry.generate(description);
+    }
+
+    let left = Infinity;
+    let right = -Infinity;
+    let middle = 0;
+    let counted = 0;
+
+    for (const [, placed] of group.visual.nodes) {
+        left = Math.min(left, placed.dimensions.position.x);
+        right = Math.max(right, placed.dimensions.position.x + placed.dimensions.size.x);
+        middle += placed.dimensions.position.y;
+
+        counted++;
+    }
+
+    if (counted === 0) {
+        left = 0;
+        right = 0;
+    }
+
+    const y = counted === 0 ? 0 : middle / counted;
+
+    group.visual.ensureNode(group.inputNode, visualRegistry).dimensions.position
+        .set(left - BOUNDARY_MARGIN, y);
+
+    group.visual.ensureNode(group.outputNode, visualRegistry).dimensions.position
+        .set(right + BOUNDARY_MARGIN, y);
+}
+
+/**
+ * `candidate`, or the first numbered variant of it that has not been used yet.
+ *
+ * @param {string} candidate
+ * @param {Set<string>} claimed modified
+ * @returns {string}
+ */
+function unique_name(candidate, claimed) {
+    let name = candidate;
+
+    for (let suffix = 2; claimed.has(name); suffix++) {
+        name = `${candidate}${suffix}`;
+    }
+
+    claimed.add(name);
+
+    return name;
+}
+
+/**
+ * A node's parameters, deep enough that the copy and the original cannot write through to each
+ * other. See the same function in {@link ./flatten_particle_graph.js}.
+ *
+ * @param {object} parameters
+ * @returns {object}
+ */
+function clone_parameters(parameters) {
+    const result = {};
+
+    for (const key of Object.keys(parameters)) {
+        const value = parameters[key];
+
+        result[key] = Array.isArray(value) ? value.slice() : value;
+    }
+
+    return result;
+}

package/src/shade/renderer/particles/graph/particle_graph_authoring.d.ts

@@ -10,8 +10,14 @@
 /**
  * Add a node to a particle graph.
  *
+ * Parameters the caller leaves out take the type's defaults (see
+ * {@link ./particle_node_parameters.js particle_node_default_parameters}), so what lands in the
+ * graph is a node that compiles — the same footing a node dropped from the editor's palette
+ * starts on. An attribute reference has no default worth having and is left empty.
+ *
  * @param {NodeGraph} graph
- * @param {string} type a node type name registered in {@link ./ParticleNodeRegistry.js}
+ * @param {string} type a node type name from the library — a stock type or a
+ *   {@link ./ParticleNodeGroup.js group}
  * @param {object} [parameters] static parameters (attribute name, builtin id, constant value, …)
  * @returns {number} the new node instance id
  */
@@ -22,8 +28,8 @@ export function particle_node(graph: NodeGraph, type: string, parameters?: objec
  * The source may be:
  * - a node id (number) → that node's `out` port,
  * - `{ node, port }` → an explicit port,
- * - a number array → a literal `vec4`, materialised as a `const` node (scalar broadcast is NOT
- *   applied; `[5]` means `[5,0,0,0]`).
+ * - a number array → a literal, materialised as a `const` node as wide as the array: `[5]` is a
+ *   scalar, and a scalar meeting a vector input broadcasts; `[5, 0, 0]` is a `vec3`.
  *
  * @param {NodeGraph} graph
  * @param {number} node_id
@@ -36,7 +42,8 @@ export function particle_wire(graph: NodeGraph, node_id: number, port: string, s
     port?: string;
 }): number;
 /**
- * Wrap a scalar or vector as a literal source (so it is unambiguous vs. a node id).
+ * Wrap a scalar or vector as a literal source (so it is unambiguous vs. a node id). One component
+ * is a scalar, two to four a vector of that many lanes.
  * @param {...number} components
  * @returns {number[]}
  */

package/src/shade/renderer/particles/graph/particle_graph_authoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_graph_authoring.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_authoring.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,sDAJW,MAAM,eACN,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDALW,MAAM,QACN,MAAM;UACiB,MAAM;WAAS,MAAM;IAC1C,MAAM,CA2BlB;AA6BD;;;;GAIG;AACH,uCAHc,MAAM,KACP,MAAM,EAAE,CAIpB"}
+{"version":3,"file":"particle_graph_authoring.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_authoring.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;GAaG;AACH,sDALW,MAAM,eAEN,MAAM,GACJ,MAAM,CAelB;AAED;;;;;;;;;;;;;;GAcG;AACH,yDALW,MAAM,QACN,MAAM;UACiB,MAAM;WAAS,MAAM;IAC1C,MAAM,CA2BlB;AA2BD;;;;;GAKG;AACH,uCAHc,MAAM,KACP,MAAM,EAAE,CAIpB"}