@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -0,0 +1,419 @@
+import { NodeGraph } from "../../../../core/model/node-graph/NodeGraph.js";
+import { NodeInstance } from "../../../../core/model/node-graph/node/NodeInstance.js";
+import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
+import { NodeGraphVisualData } from "../../../../core/model/node-graph/visual/NodeGraphVisualData.js";
+import { ParticleNodeDescription } from "./ParticleNodeDescription.js";
+import { PARTICLE_VALUE_TYPE } from "./ParticleNodeRegistry.js";
+import { particle_widest_type } from "./ParticleValueType.js";
+
+/**
+ * A node made of other nodes.
+ *
+ * The particle VM has no calls and no control flow, so a graph is one flat expression and always
+ * will be. A group is what lets an author stop reading it that way: `simplex3` is one node with a
+ * position going in and a number coming out, and the two hundred instructions it lowers to are
+ * nobody's business until they open it. Compilation flattens every group away before anything else
+ * happens — see {@link ./flatten_particle_graph.js} — so nothing downstream of that point knows
+ * groups exist, and a group costs exactly what its contents cost and nothing more.
+ *
+ * ## The boundary
+ *
+ * A group's edge is two nodes inside its own graph. The **input block** carries one *output* port
+ * per declared input, because inside the group that is what an input is — a value arriving, which
+ * you wire *from*. The **output block** carries one *input* port per declared output, for the same
+ * reason in reverse. Wiring a node to an output block port is what exposes it, and the port's name
+ * and type are the group's to choose: a `vec4` inside can be exposed as a `color`, and a value
+ * called `a` can be exposed as `my_favourite_output_value`.
+ *
+ * That is also why the declarations are separate from the graph rather than derived from it. A
+ * group's face is a decision, and deriving it from whatever happens to be wired up would change the
+ * face every time somebody rewired the inside.
+ *
+ * ## Nesting, and why it terminates
+ *
+ * A group's body may hold other groups, and flattening is a fixed point rather than one pass. It
+ * always reaches one: a body can only wire up groups that already exist, so the reference graph
+ * cannot contain a cycle — a group cannot name itself, or anything built after it. Flattening keeps
+ * a pass cap anyway, because that argument is about how groups are *built* and the flattener should
+ * not depend on it.
+ *
+ * ## Locked
+ *
+ * The groups shipped with the editor are locked: their bodies are shared by every instance in every
+ * effect, and they are what the library's own specs pin. A view opens a locked group read-only. An
+ * unlocked one is editable in place, with the same consequence — one body, every instance.
+ */
+
+/**
+ * The id the input block always has inside a group's body; the output block takes the one after it.
+ *
+ * Fixed rather than taken from the counter, so that a body can be written down and read back without
+ * having to say which of its nodes are the boundary: a saved group's ids 0 and 1 are its edge, and
+ * everything else is the work. The two are added before anything else, so the id pool hands the rest
+ * out from 2 upward on its own.
+ *
+ * @type {number}
+ */
+export const PARTICLE_GROUP_INPUT_NODE = 0;
+
+/**
+ * @type {number}
+ */
+export const PARTICLE_GROUP_OUTPUT_NODE = 1;
+
+/**
+ * A group definition: its face, its body, and the node type an author places to use it. See the note
+ * at the top of this file.
+ */
+export class ParticleNodeGroup {
+    /**
+     * Library address. What a saved graph holds, and what a type is looked up by. Terse and
+     * unchanging, exactly like a stock node type's.
+     * @type {string}
+     */
+    name = "";
+
+    /**
+     * What to call it in front of a person.
+     * @type {string}
+     */
+    label = "";
+
+    /**
+     * Glyph, as SVG path data in a 24x24 box. See {@link NodeDescription#icon}.
+     * @type {string}
+     */
+    icon = "";
+
+    /**
+     * One line of help, for a palette to show under the name.
+     * @type {string}
+     */
+    help = "";
+
+    /**
+     * Whether the body is the author's to change. See the note above.
+     * @type {boolean}
+     */
+    locked = true;
+
+    /**
+     * The group's declared inputs, in port order. A `null` type is a port that takes the shape of
+     * whatever is wired to it — see {@link ParticleGroupNodeDescription}.
+     * @type {Array<{name: string, type: import("./ParticleValueType.js").ParticleValueType|null}>}
+     */
+    inputs = [];
+
+    /**
+     * The group's declared outputs, in port order.
+     * @type {Array<{name: string, type: import("./ParticleValueType.js").ParticleValueType|null}>}
+     */
+    outputs = [];
+
+    /**
+     * The body: the nodes the group is made of, plus its two boundary nodes.
+     * @type {NodeGraph}
+     */
+    graph = new NodeGraph();
+
+    /**
+     * Where the body's nodes sit, for a view that opens the group.
+     * @type {NodeGraphVisualData}
+     */
+    visual = new NodeGraphVisualData();
+
+    /**
+     * The type an instance of this group is, as placed in a graph.
+     * @type {ParticleGroupNodeDescription}
+     */
+    description = null;
+
+    /**
+     * The boundary node inside the body that values arrive at.
+     * @type {NodeInstance}
+     */
+    inputNode = null;
+
+    /**
+     * The boundary node inside the body that values leave from.
+     * @type {NodeInstance}
+     */
+    outputNode = null;
+
+    /**
+     * Build a group and everything that describes it: the node type an author places, and the two
+     * boundary nodes its body is wired to.
+     *
+     * The body itself arrives empty. {@link ./ParticleGroupBuilder.js} is what fills one.
+     *
+     * @param {object} options
+     * @param {string} options.name
+     * @param {string} [options.label]
+     * @param {string} [options.icon]
+     * @param {string} [options.help]
+     * @param {boolean} [options.locked]
+     * @param {Array<{name: string, type: import("./ParticleValueType.js").ParticleValueType}>} [options.inputs]
+     * @param {Array<{name: string, type: import("./ParticleValueType.js").ParticleValueType}>} [options.outputs]
+     * @returns {ParticleNodeGroup}
+     */
+    static create({ name, label = "", icon = "", help = "", locked = true, inputs = [], outputs = [] }) {
+        const group = new ParticleNodeGroup();
+
+        group.name = name;
+        group.label = label === "" ? name : label;
+        group.icon = icon;
+        group.help = help;
+        group.locked = locked;
+        group.inputs = inputs.map(port => ({ ...port }));
+        group.outputs = outputs.map(port => ({ ...port }));
+
+        reject_duplicates(group.inputs, `group '${name}' inputs`);
+        reject_duplicates(group.outputs, `group '${name}' outputs`);
+
+        group.description = new ParticleGroupNodeDescription(group);
+
+        // Inside the group the arrows point the other way: what the group takes in is what the body
+        // reads out of, and what the group produces is what the body writes into.
+        group.inputNode = boundary_node(new ParticleGroupBoundaryDescription(group, "input"), PARTICLE_GROUP_INPUT_NODE);
+        group.outputNode = boundary_node(new ParticleGroupBoundaryDescription(group, "output"), PARTICLE_GROUP_OUTPUT_NODE);
+
+        group.graph.addNode(group.inputNode);
+        group.graph.addNode(group.outputNode);
+
+        return group;
+    }
+
+    /**
+     * The declared type of one of the group's ports, whichever side it is on.
+     *
+     * @param {string} port_name
+     * @param {PortDirection} direction
+     * @returns {import("./ParticleValueType.js").ParticleValueType|null}
+     */
+    portType(port_name, direction) {
+        const declared = direction === PortDirection.In ? this.inputs : this.outputs;
+
+        return declared.find(port => port.name === port_name)?.type ?? null;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ParticleNodeGroup.prototype.isParticleNodeGroup = true;
+
+/**
+ * The type of a group node, as placed in a graph.
+ *
+ * Everything about it comes off the group's declarations: the ports, their types, the label and the
+ * glyph. It has no `emit` because it never reaches a compiler — flattening replaces it with the
+ * group's contents first — and says so rather than lowering to nothing, since a group that silently
+ * compiled to no instructions would be the hardest kind of bug to see.
+ */
+export class ParticleGroupNodeDescription extends ParticleNodeDescription {
+    /**
+     * @param {ParticleNodeGroup} group
+     */
+    constructor(group) {
+        super();
+
+        /**
+         * @readonly
+         * @type {ParticleNodeGroup}
+         */
+        this.group = group;
+
+        this.name = group.name;
+        this.display_label = group.label;
+        this.icon = group.icon;
+        this.help = group.help;
+
+        for (const port of group.inputs) {
+            this.createPort(PARTICLE_VALUE_TYPE, port.name, PortDirection.In);
+        }
+
+        for (const port of group.outputs) {
+            this.createPort(PARTICLE_VALUE_TYPE, port.name, PortDirection.Out);
+        }
+
+        // A declared type is what an instance reads or produces whatever it is wired to — that is the
+        // point of declaring one, and it is what makes a group's face hold still.
+        //
+        // A port declared `null` says the opposite on purpose: it takes the shape of what arrives,
+        // the same element-wise rule the stock arithmetic follows. That is the honest declaration for
+        // a group like `remap`, which does the same thing to one lane or to four; declaring it `f32`
+        // would report a warning about lanes for every vector fed into it, and the warning would be
+        // untrue — flattening removes the group before widths are decided, so the lanes were never
+        // in danger.
+        this.infer_types = ({ inputs }) => {
+            const arriving = group.inputs
+                .filter(port => port.type === null)
+                .map(port => inputs[port.name]);
+
+            const free = particle_widest_type(arriving);
+
+            const read = Object.fromEntries(group.inputs.map(port => [port.name, port.type ?? free]));
+            const produced = Object.fromEntries(group.outputs.map(port => [port.name, port.type ?? free]));
+
+            return {
+                output: group.outputs.length === 0 ? null : produced[group.outputs[0].name],
+                outputs: produced,
+                inputs: read,
+            };
+        };
+
+        this.emit = () => {
+            throw new Error(
+                `Group '${group.name}' reached the compiler. Groups are flattened away before lowering; `
+                + "see flatten_particle_graph.js."
+            );
+        };
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ParticleGroupNodeDescription.prototype.isParticleGroupNodeDescription = true;
+
+/**
+ * The type of one of a group's two boundary nodes.
+ *
+ * These exist only inside a group's own body, and only so that the body has something to wire to.
+ * Flattening deletes them — every wire that met one is re-made against whatever was on the other
+ * side of the group — so like a group node itself, one reaching a compiler is a bug rather than an
+ * instruction.
+ */
+export class ParticleGroupBoundaryDescription extends ParticleNodeDescription {
+    /**
+     * @param {ParticleNodeGroup} group
+     * @param {string} side `"input"` or `"output"`
+     */
+    constructor(group, side) {
+        super();
+
+        /**
+         * @readonly
+         * @type {ParticleNodeGroup}
+         */
+        this.group = group;
+
+        /**
+         * Which block this is: `"input"` or `"output"`.
+         * @readonly
+         * @type {string}
+         */
+        this.side = side;
+
+        const input_block = side === "input";
+
+        const declared = input_block ? group.inputs : group.outputs;
+
+        this.name = `${group.name}/${side}`;
+        this.display_label = input_block ? "Group Input" : "Group Output";
+        this.help = input_block
+            ? "the values this group is given"
+            : "the values this group produces";
+
+        for (const port of declared) {
+            this.createPort(
+                PARTICLE_VALUE_TYPE,
+                port.name,
+                input_block ? PortDirection.Out : PortDirection.In
+            );
+        }
+
+        this.infer_types = () => (input_block
+            ? {
+                output: declared[0]?.type ?? null,
+                outputs: Object.fromEntries(declared.map(port => [port.name, port.type])),
+                inputs: {},
+            }
+            : {
+                output: null,
+                inputs: Object.fromEntries(declared.map(port => [port.name, port.type])),
+            });
+
+        this.emit = () => {
+            throw new Error(
+                `The ${side} block of group '${group.name}' reached the compiler. A group's boundary is `
+                + "removed by flattening; see flatten_particle_graph.js."
+            );
+        };
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ParticleGroupBoundaryDescription.prototype.isParticleGroupBoundaryDescription = true;
+
+/**
+ * Whether a node in a graph is an instance of a group, and so something flattening has to open.
+ *
+ * @param {NodeInstance} node
+ * @returns {boolean}
+ */
+export function is_particle_group_node(node) {
+    return node.description?.isParticleGroupNodeDescription === true;
+}
+
+/**
+ * Whether a node is one of a group body's two boundary blocks.
+ *
+ * @param {NodeInstance} node
+ * @returns {boolean}
+ */
+export function is_particle_group_boundary(node) {
+    return node.description?.isParticleGroupBoundaryDescription === true;
+}
+
+/**
+ * Whether a node type belongs to the group machinery — a group itself, or one of the blocks that
+ * make up a group's edge — rather than to the stock library.
+ *
+ * What a caller asks before reaching for anything the stock library keeps beside its types: a
+ * parameter schema, a presentation entry, a default value. None of these has one, because none of
+ * them is one.
+ *
+ * @param {NodeDescription} description
+ * @returns {boolean}
+ */
+export function is_particle_group_description(description) {
+    return description?.isParticleGroupNodeDescription === true
+        || description?.isParticleGroupBoundaryDescription === true;
+}
+
+/**
+ * @param {ParticleNodeDescription} description
+ * @param {number} id
+ * @returns {NodeInstance}
+ */
+function boundary_node(description, id) {
+    const node = new NodeInstance();
+
+    node.id = id;
+
+    node.setDescription(description);
+
+    return node;
+}
+
+/**
+ * @param {Array<{name: string}>} ports
+ * @param {string} what
+ */
+function reject_duplicates(ports, what) {
+    const seen = new Set();
+
+    for (const port of ports) {
+        if (seen.has(port.name)) {
+            throw new Error(`Two ports named '${port.name}' in ${what}; a connection is written by name.`);
+        }
+
+        seen.add(port.name);
+    }
+}

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

@@ -1,3 +1,12 @@
+/**
+ * Every node type in the library, in declaration order.
+ *
+ * The registry is keyed by the numeric ids assigned above, so this is the only way to walk the
+ * library by the names authoring uses — which is what a node palette lists.
+ *
+ * @returns {ParticleNodeDescription[]}
+ */
+export function particle_node_descriptions(): ParticleNodeDescription[];
 /**
  * Look up a node type by name.
  * @param {string} name
@@ -12,10 +21,32 @@ export function get_particle_node_description(name: string): ParticleNodeDescrip
  *
  * These lower to the same opcodes the JS reference + WGSL interpreter agree on, so any effect
  * authored here is executable and testable end-to-end on the CPU before it ever hits the GPU.
+ *
+ * ## Types
+ *
+ * A value is a float vector of one to four lanes, and which it is is a property of the node
+ * instance rather than of its type: a `builtin` is a scalar or a `vec3` by which builtin it reads,
+ * a `const` is as wide as the literal it holds, an `add` is as wide as the wider of what it adds.
+ * So every port is declared with the one {@link PARTICLE_VALUE_TYPE} — any output may be wired to
+ * any input — and each node type says how it is typed through
+ * {@link ParticleNodeDescription#infer_types}, which {@link ./infer_particle_graph_types.js}
+ * resolves over a whole graph. The types themselves are in {@link ./ParticleValueType.js}, and
+ * registered here so a view can colour by them.
+ *
+ * A type may also say what a value *means* — {@link PARTICLE_TYPE_COLOR} is four lanes that are a
+ * colour — and the rules below never ask. They compare `components` and take the widest, so a
+ * colour is accepted wherever a `vec4` is, produces whatever a `vec4` would, and survives the
+ * arithmetic in between. The two places a colour enters a graph are the `color` node and an
+ * attribute the effect's layout has tagged as one.
  */
 /**
- * Every value the particle VM computes lives in a `vec4f` register, so a single data type describes
- * every port in the library: any output may drive any input.
+ * The declared type of every port in the library: a value goes here.
+ *
+ * Which value — one lane or four — is resolved per node instance, see the note on types above.
+ * Declared once for all ports because the graph model connects ports whose declared types are the
+ * same object, and any particle value may drive any particle input; where the widths differ, the
+ * compiler converts and the validator says so.
+ *
  * @type {DataType}
  */
 export const PARTICLE_VALUE_TYPE: DataType;
@@ -28,6 +59,17 @@ export const PARTICLE_NODE_OUTPUT_PORT: string;
  * @type {NodeRegistry}
  */
 export const PARTICLE_NODE_REGISTRY: NodeRegistry;
+/**
+ * Comparison operators the single `compare` node type covers, and the opcode each lowers to.
+ *
+ * Exported so the authoring metadata in {@link ./particle_node_parameters.js} can offer exactly the
+ * set this lowers, rather than a hand-copied list that goes stale the moment one is added.
+ *
+ * @type {Object<string, number>}
+ */
+export const PARTICLE_COMPARE_OPCODES: {
+    [x: string]: number;
+};
 import { ParticleNodeDescription } from "./ParticleNodeDescription.js";
 import { DataType } from "../../../../core/model/node-graph/type/DataType.js";
 import { NodeRegistry } from "../../../../core/model/node-graph/node/NodeRegistry.js";

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleNodeRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeRegistry.js"],"names":[],"mappings":"AA0KA;;;;;GAKG;AACH,oDAJW,MAAM,GACJ,uBAAuB,CAWnC;AAlLD;;;;;;;GAOG;AAEH;;;;GAIG;AACH,kCAFU,QAAQ,CAE0C;AAE5D;;;GAGG;AACH,wCAFU,MAAM,CAE+B;AAE/C;;GAEG;AACH,qCAFU,YAAY,CAEmC;wCA3BjB,8BAA8B;yBAF7C,oDAAoD;6BAFhD,wDAAwD"}
+{"version":3,"file":"ParticleNodeRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeRegistry.js"],"names":[],"mappings":"AAklBA;;;;;;;GAOG;AACH,8CAFa,uBAAuB,EAAE,CAIrC;AAED;;;;;GAKG;AACH,oDAJW,MAAM,GACJ,uBAAuB,CAWnC;AA3lBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;GASG;AACH,kCAFU,QAAQ,CAE2C;AAE7D;;;GAGG;AACH,wCAFU,MAAM,CAE+B;AAE/C;;GAEG;AACH,qCAFU,YAAY,CAEmC;AAuOzD;;;;;;;GAOG;AACH;QAFiB,MAAM,GAAE,MAAM;EAQ5B;wCAhTqC,8BAA8B;yBAH7C,oDAAoD;6BAFhD,wDAAwD"}