@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,179 @@
+/**
+ * Writing a node group's body in JavaScript.
+ *
+ * A group like `simplex3` is two hundred nodes. Assembling that by hand — create a node, look up a
+ * port id, create a connection, repeat — is unreadable and unreviewable, and the thing being written
+ * is an expression, which JavaScript already spells perfectly well. So this builds the graph out of
+ * calls: `g.mul(g.sub(x, low), scale)` creates three nodes and two wires, and reads as what it
+ * computes.
+ *
+ * Every stock operation that takes no parameters of its own is a method here, taken from the library
+ * rather than listed — a type added to it is callable the same day. The rest — `const`, `swizzle`,
+ * `random`, `curve` and the attribute nodes — need a parameter and are reached through
+ * {@link #op}, or through the shorthands below where there is an obvious one.
+ *
+ * A number where a value is expected becomes a literal, so `g.mul(v, 0.5)` is what it looks like.
+ *
+ * Each mention of a number is its own node, deliberately. Sharing one would be fewer instructions and
+ * a great deal worse: a value's registers are held from where it is produced to its last reader, so a
+ * `2.0` shared between the first line of a body and the last would pin its slots across the whole
+ * group. The fast interpreter's register file is the scarce thing here — see
+ * {@link ../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS} — and the constant pool interns
+ * the words anyway, so what the duplication costs is one `LOAD_CONST` and nothing else.
+ *
+ * ## What comes back
+ *
+ * Every call returns a **port reference** — a node and one of its output ports — which is the thing
+ * wires are made between. Multi-output nodes (another group) hand back a map of them.
+ */
+export class ParticleGroupBuilder {
+    /**
+     * @param {object} options see {@link ParticleNodeGroup.create}
+     */
+    constructor(options: object);
+    /**
+     * The group being built.
+     * @type {ParticleNodeGroup}
+     */
+    group: ParticleNodeGroup;
+    /**
+     * The group's inputs, by name: what the body reads its arguments from.
+     * @type {Object<string, {node: NodeInstance, port: Port}>}
+     */
+    in: {
+        [x: string]: {
+            node: NodeInstance;
+            port: Port;
+        };
+    };
+    /**
+     * Create one node of a stock type, wired to the values given.
+     *
+     * Arguments are matched to the type's input ports in declaration order — which is the order the
+     * library declares its operands in, so `op("mad", [a, b, c])` is `a * b + c`. A number stands in
+     * for a literal of that number.
+     *
+     * @param {string} type node type name
+     * @param {Array<{node: NodeInstance, port: Port}|number>} [args] one per input port, in order
+     * @param {object} [parameters] overrides on top of the type's defaults
+     * @returns {{node: NodeInstance, port: Port}} the node's `out` port
+     */
+    op(type: string, args?: (number | {
+        node: NodeInstance;
+        port: Port;
+    })[], parameters?: object): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /**
+     * Create one instance of another group, wired to the values given by name.
+     *
+     * How a group is built out of groups: `curl3` is twelve `simplex3`s and the arithmetic between
+     * them, and says so.
+     *
+     * @param {ParticleNodeGroup} group
+     * @param {Object<string, {node: NodeInstance, port: Port}|number>} args value per input port name
+     * @returns {Object<string, {node: NodeInstance, port: Port}>} a reference per output port name
+     */
+    call(group: ParticleNodeGroup, args?: {
+        [x: string]: number | {
+            node: NodeInstance;
+            port: Port;
+        };
+    }): {
+        [x: string]: {
+            node: NodeInstance;
+            port: Port;
+        };
+    };
+    /**
+     * A literal. One number is a scalar; several are a vector as wide as there are of them.
+     *
+     * @param {...number} components
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    f(...components: number[]): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /**
+     * Pick and reorder lanes, spelled the way the assembly spells it.
+     *
+     * @param {{node: NodeInstance, port: Port}|number} value
+     * @param {string} pattern one to four of `xyzw`
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    swz(value: {
+        node: NodeInstance;
+        port: Port;
+    } | number, pattern: string): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    x(v: {
+        node: NodeInstance;
+        port: Port;
+    } | number): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    y(v: {
+        node: NodeInstance;
+        port: Port;
+    } | number): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    z(v: {
+        node: NodeInstance;
+        port: Port;
+    } | number): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    w(v: {
+        node: NodeInstance;
+        port: Port;
+    } | number): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /**
+     * A value read as a builtin the host provides.
+     *
+     * @param {number} id a {@link ../isa/ParticleVMISA.js VM_BUILTIN}
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    builtin(id: number): {
+        node: NodeInstance;
+        port: Port;
+    };
+    /**
+     * Expose a value as one of the group's outputs.
+     *
+     * @param {string} name one of the group's declared output ports
+     * @param {{node: NodeInstance, port: Port}|number} value
+     * @returns {void}
+     */
+    out(name: string, value: number | {
+        node: NodeInstance;
+        port: Port;
+    }): void;
+    /**
+     * Finish the group, having checked that it is one.
+     *
+     * Everything caught here is caught at the moment the library loads, which is where a broken
+     * built-in group should fail: a group missing an output is a node whose result is nothing, and
+     * finding that out at the far end of a compile in somebody's editor is finding it out too late.
+     *
+     * @returns {ParticleNodeGroup}
+     */
+    build(): ParticleNodeGroup;
+    #private;
+}
+import { ParticleNodeGroup } from "./ParticleNodeGroup.js";
+//# sourceMappingURL=ParticleGroupBuilder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleGroupBuilder.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleGroupBuilder.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAaI;;OAEG;IACH,qBAFW,MAAM,EAoBhB;IAjCD;;;OAGG;IACH,OAFU,iBAAiB,CAErB;IAEN;;;OAGG;IACH;YAFiB,MAAM,GAAE;YAAC,IAAI,eAAe;YAAC,IAAI,OAAM;SAAC;MAEjD;IAyBR;;;;;;;;;;;OAWG;IACH,SALW,MAAM;;;uBAEN,MAAM;;;MAoBhB;IAED;;;;;;;;;OASG;IACH,YAJW,iBAAiB;;;;;;;;;;MA0B3B;IAED;;;;;OAKG;IACH,iBAHc,MAAM,KACP;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAI5C;IAED;;;;;;OAMG;IACH,WAJW;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,WACvC,MAAM,GACJ;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAU5C;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED,qGAAqG;IACrG,KADY;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,GAAC,MAAM,GAAc;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAGhG;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ;QAAC,IAAI,eAAe;QAAC,IAAI,OAAM;KAAC,CAI5C;IAED;;;;;;OAMG;IACH,UAJW,MAAM;;;QAEJ,IAAI,CAehB;IAED;;;;;;;;OAQG;IACH,SAFa,iBAAiB,CA+B7B;;CAgDJ;kCA7SiC,wBAAwB"}

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

@@ -0,0 +1,303 @@
+import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
+import { ParticleNodeGroup } from "./ParticleNodeGroup.js";
+import { get_particle_node_description, PARTICLE_NODE_OUTPUT_PORT } from "./ParticleNodeRegistry.js";
+import {
+    particle_node_default_parameters,
+    PARTICLE_NODES_WITHOUT_PARAMETERS,
+} from "./particle_node_parameters.js";
+
+/**
+ * Writing a node group's body in JavaScript.
+ *
+ * A group like `simplex3` is two hundred nodes. Assembling that by hand — create a node, look up a
+ * port id, create a connection, repeat — is unreadable and unreviewable, and the thing being written
+ * is an expression, which JavaScript already spells perfectly well. So this builds the graph out of
+ * calls: `g.mul(g.sub(x, low), scale)` creates three nodes and two wires, and reads as what it
+ * computes.
+ *
+ * Every stock operation that takes no parameters of its own is a method here, taken from the library
+ * rather than listed — a type added to it is callable the same day. The rest — `const`, `swizzle`,
+ * `random`, `curve` and the attribute nodes — need a parameter and are reached through
+ * {@link #op}, or through the shorthands below where there is an obvious one.
+ *
+ * A number where a value is expected becomes a literal, so `g.mul(v, 0.5)` is what it looks like.
+ *
+ * Each mention of a number is its own node, deliberately. Sharing one would be fewer instructions and
+ * a great deal worse: a value's registers are held from where it is produced to its last reader, so a
+ * `2.0` shared between the first line of a body and the last would pin its slots across the whole
+ * group. The fast interpreter's register file is the scarce thing here — see
+ * {@link ../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS} — and the constant pool interns
+ * the words anyway, so what the duplication costs is one `LOAD_CONST` and nothing else.
+ *
+ * ## What comes back
+ *
+ * Every call returns a **port reference** — a node and one of its output ports — which is the thing
+ * wires are made between. Multi-output nodes (another group) hand back a map of them.
+ */
+export class ParticleGroupBuilder {
+    /**
+     * The group being built.
+     * @type {ParticleNodeGroup}
+     */
+    group;
+
+    /**
+     * The group's inputs, by name: what the body reads its arguments from.
+     * @type {Object<string, {node: NodeInstance, port: Port}>}
+     */
+    in = {};
+
+    /**
+     * @param {object} options see {@link ParticleNodeGroup.create}
+     */
+    constructor(options) {
+        this.group = ParticleNodeGroup.create(options);
+
+        for (const port of this.group.description.inPorts) {
+            // the input block's port of the same name: inside the group, an input is read from
+            this.in[port.name] = {
+                node: this.group.inputNode,
+                port: this.group.inputNode.description.findPortByNameAndDirection(port.name, PortDirection.Out),
+            };
+        }
+
+        for (const name of PARTICLE_NODES_WITHOUT_PARAMETERS) {
+            if (this[name] !== undefined) {
+                continue;
+            }
+
+            this[name] = (...args) => this.op(name, args);
+        }
+    }
+
+    /**
+     * Create one node of a stock type, wired to the values given.
+     *
+     * Arguments are matched to the type's input ports in declaration order — which is the order the
+     * library declares its operands in, so `op("mad", [a, b, c])` is `a * b + c`. A number stands in
+     * for a literal of that number.
+     *
+     * @param {string} type node type name
+     * @param {Array<{node: NodeInstance, port: Port}|number>} [args] one per input port, in order
+     * @param {object} [parameters] overrides on top of the type's defaults
+     * @returns {{node: NodeInstance, port: Port}} the node's `out` port
+     */
+    op(type, args = [], parameters = {}) {
+        const description = get_particle_node_description(type);
+
+        const node = this.#create(description, parameters);
+
+        const ports = description.inPorts;
+
+        if (args.length !== ports.length) {
+            throw new Error(
+                `'${type}' takes ${ports.length} input${ports.length === 1 ? "" : "s"} `
+                + `(${ports.map(port => port.name).join(", ") || "none"}), given ${args.length}.`
+            );
+        }
+
+        ports.forEach((port, index) => this.#wire(this.#value(args[index]), node, port));
+
+        return { node, port: description.findPortByNameAndDirection(PARTICLE_NODE_OUTPUT_PORT, PortDirection.Out) };
+    }
+
+    /**
+     * Create one instance of another group, wired to the values given by name.
+     *
+     * How a group is built out of groups: `curl3` is twelve `simplex3`s and the arithmetic between
+     * them, and says so.
+     *
+     * @param {ParticleNodeGroup} group
+     * @param {Object<string, {node: NodeInstance, port: Port}|number>} args value per input port name
+     * @returns {Object<string, {node: NodeInstance, port: Port}>} a reference per output port name
+     */
+    call(group, args = {}) {
+        const description = group.description;
+
+        const node = this.#create(description, {});
+
+        for (const port of description.inPorts) {
+            const argument = args[port.name];
+
+            if (argument === undefined) {
+                throw new Error(`Group '${group.name}' has an input '${port.name}' and nothing was given for it.`);
+            }
+
+            this.#wire(this.#value(argument), node, port);
+        }
+
+        const result = {};
+
+        for (const port of description.outPorts) {
+            result[port.name] = { node, port };
+        }
+
+        return result;
+    }
+
+    /**
+     * A literal. One number is a scalar; several are a vector as wide as there are of them.
+     *
+     * @param {...number} components
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    f(...components) {
+        return this.op("const", [], { value: components.slice() });
+    }
+
+    /**
+     * Pick and reorder lanes, spelled the way the assembly spells it.
+     *
+     * @param {{node: NodeInstance, port: Port}|number} value
+     * @param {string} pattern one to four of `xyzw`
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    swz(value, pattern) {
+        const lanes = Array.from(pattern).map(lane => "xyzw".indexOf(lane));
+
+        if (lanes.length === 0 || lanes.some(lane => lane === -1)) {
+            throw new Error(`'${pattern}' is not a swizzle: one to four of x, y, z, w.`);
+        }
+
+        return this.op("swizzle", [value], { pattern: lanes });
+    }
+
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    x(v) {
+        return this.swz(v, "x");
+    }
+
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    y(v) {
+        return this.swz(v, "y");
+    }
+
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    z(v) {
+        return this.swz(v, "z");
+    }
+
+    /** @param {{node: NodeInstance, port: Port}|number} v @returns {{node: NodeInstance, port: Port}} */
+    w(v) {
+        return this.swz(v, "w");
+    }
+
+    /**
+     * A value read as a builtin the host provides.
+     *
+     * @param {number} id a {@link ../isa/ParticleVMISA.js VM_BUILTIN}
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    builtin(id) {
+        return this.op("builtin", [], { id });
+    }
+
+    /**
+     * Expose a value as one of the group's outputs.
+     *
+     * @param {string} name one of the group's declared output ports
+     * @param {{node: NodeInstance, port: Port}|number} value
+     * @returns {void}
+     */
+    out(name, value) {
+        const outputNode = this.group.outputNode;
+
+        const port = outputNode.description.findPortByNameAndDirection(name, PortDirection.In);
+
+        if (port === undefined) {
+            throw new Error(
+                `Group '${this.group.name}' has no output called '${name}'. It has: `
+                + `${this.group.outputs.map(o => o.name).join(", ") || "none"}.`
+            );
+        }
+
+        this.#wire(this.#value(value), outputNode, port);
+    }
+
+    /**
+     * Finish the group, having checked that it is one.
+     *
+     * Everything caught here is caught at the moment the library loads, which is where a broken
+     * built-in group should fail: a group missing an output is a node whose result is nothing, and
+     * finding that out at the far end of a compile in somebody's editor is finding it out too late.
+     *
+     * @returns {ParticleNodeGroup}
+     */
+    build() {
+        const group = this.group;
+
+        for (const port of group.outputNode.description.inPorts) {
+            const wired = group.outputNode.getEndpoint(port.id).inConnections.length;
+
+            if (wired !== 1) {
+                throw new Error(
+                    `Group '${group.name}' output '${port.name}' has ${wired} sources; it takes exactly one.`
+                );
+            }
+        }
+
+        for (const node of group.graph.getNodes()) {
+            if (node === group.inputNode || node === group.outputNode) {
+                continue;
+            }
+
+            for (const port of node.description.inPorts) {
+                if (node.getEndpoint(port.id).inConnections.length !== 1) {
+                    throw new Error(
+                        `Group '${group.name}': input '${port.name}' of a '${node.description.name}' `
+                        + "is not wired to exactly one source."
+                    );
+                }
+            }
+        }
+
+        return group;
+    }
+
+    /**
+     * @param {ParticleNodeDescription} description
+     * @param {object} parameters
+     * @returns {NodeInstance}
+     */
+    #create(description, parameters) {
+        const graph = this.group.graph;
+
+        const node = graph.getNodeSafe(graph.createNode(description));
+
+        // the type's own defaults underneath, so a body written before a type gained a parameter
+        // still builds a node that compiles
+        node.setParameters({
+            ...(description.isParticleGroupNodeDescription === true
+                ? {}
+                : particle_node_default_parameters(description.name)),
+            ...parameters,
+        });
+
+        return node;
+    }
+
+    /**
+     * @param {{node: NodeInstance, port: Port}|number} value
+     * @returns {{node: NodeInstance, port: Port}}
+     */
+    #value(value) {
+        if (typeof value === "number") {
+            return this.f(value);
+        }
+
+        if (value === undefined || value === null || value.node === undefined || value.port === undefined) {
+            throw new Error(`Group '${this.group.name}': ${value} is not a value.`);
+        }
+
+        return value;
+    }
+
+    /**
+     * @param {{node: NodeInstance, port: Port}} source
+     * @param {NodeInstance} node
+     * @param {Port} port
+     */
+    #wire(source, node, port) {
+        this.group.graph.createConnection(source.node.id, source.port.id, node.id, port.id);
+    }
+}

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

@@ -5,27 +5,164 @@
  * Ports carry all the structure the compiler needs — input ports name the operands, the presence of
  * an output port says whether the node produces a value — so nothing about the graph's shape is
  * duplicated outside the description.
+ *
+ * The rest of what a node knows about itself is a handful of rules, each a function of the
+ * instance's parameters and its surroundings: what type it produces from what it is fed
+ * ({@link #infer_types}), how many lanes its instruction runs at ({@link #operation_width}), how
+ * many of each input it reads ({@link #input_widths}), how many lanes it writes
+ * ({@link #result_width}), and the lowering itself ({@link #emit}). The defaults are the
+ * element-wise case, which most of the library is; the nodes with a shape of their own override
+ * what differs.
  */
 export class ParticleNodeDescription extends NodeDescription {
+    /**
+     * One line about what this type does, for a palette or a menu to show under its name.
+     *
+     * On the description rather than looked up in a table by name, because the library is no longer
+     * one table: a node group carries its own words, and a view that asked
+     * {@link ./particle_node_presentation.js} about one would get nothing back. The stock types
+     * still take theirs from that table — this is where it is put, not where it is decided.
+     *
+     * @type {string}
+     */
+    help: string;
     /**
      * Lower one instance of this node into the target instruction stream.
      *
      * `context` provides:
      * - `context.in(port_name)` → the register holding that input's value (resolved by the compiler),
      * - `context.out` → the output register (value-producing nodes only, `undefined` for sinks),
+     * - `context.width` → the lane count to emit at, see {@link #operation_width},
+     * - `context.type` → the node's output type, see {@link #infer_types},
+     * - `context.input_types` → port name -> the type each input is read as,
+     * - `context.source_types` → port name -> the type of the value wired into each input,
      * - `context.parameters` → the {@link NodeInstance}'s parameters,
      * - `context.layout` → the {@link ../layout/ParticleLayout.js} for attribute offsets,
      * - `context.asm` → the {@link ../isa/ParticleAssembler.js} for interning constants.
      *
-     * @type {function(InstructionStream, {in: function(string):number, out: number|undefined, parameters: object, layout: ParticleLayout, asm: ParticleAssembler}):void}
+     * @type {function(InstructionStream, {in: function(string):number, out: number|undefined, width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout, asm: ParticleAssembler}):void}
      */
     emit: (arg0: InstructionStream, arg1: {
         in: (arg0: string) => number;
         out: number | undefined;
+        width: number;
+        type: ParticleValueType | null;
+        input_types: {
+            [x: string]: ParticleValueType;
+        };
+        source_types: {
+            [x: string]: ParticleValueType;
+        };
         parameters: object;
         layout: ParticleLayout;
         asm: ParticleAssembler;
     }) => void;
+    /**
+     * What type this node produces, and what type it reads each input as, given the types wired
+     * into it.
+     *
+     * `inputs` names every input port, with the type of the value connected to it or `null` where
+     * there is none or it is unknown. The answer is the output type (`null` for a sink, or where it
+     * cannot be told) and a port name -> type map saying how each input is read — which is the
+     * type a view shows on the port, and the type the compiler converts the input to where it
+     * differs from what is wired in.
+     *
+     * The default is the element-wise rule, which is the rule for most of the library: the result
+     * is as wide as the widest input, and every input is read at that width. A scalar meeting a
+     * vector broadcasts; a vector meeting a wider one is extended with zeros. A source overrides
+     * this to name its own type from its parameters; a reduction, to produce a scalar whatever it
+     * reads; a sink, to read what its attribute is.
+     *
+     * @type {function({inputs: Object<string, ParticleValueType|null>, parameters: object, layout: ParticleLayout|undefined}):{output: ParticleValueType|null, inputs: Object<string, ParticleValueType|null>}}
+     */
+    infer_types: (arg0: {
+        inputs: {
+            [x: string]: ParticleValueType | null;
+        };
+        parameters: object;
+        layout: ParticleLayout | undefined;
+    }) => {
+        output: ParticleValueType | null;
+        inputs: {
+            [x: string]: ParticleValueType | null;
+        };
+    };
+    /**
+     * How many lanes this node's instruction spans, given its type and how many lanes its consumers
+     * want of its result.
+     *
+     * Most nodes are element-wise and run at as many lanes as are wanted of them, never more than
+     * their type has: lanes nobody reads are not computed. The ones that override this are the
+     * ones with a shape of their own — a reduction reads every lane of its input however few are
+     * wanted of its one-lane result, a sink is as wide as the attribute it writes, and a source
+     * that can fill lanes for free runs at the full demand.
+     *
+     * @type {function({type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, demand: number, parameters: object, layout: ParticleLayout}):number}
+     */
+    operation_width: (arg0: {
+        type: ParticleValueType | null;
+        input_types: {
+            [x: string]: ParticleValueType;
+        };
+        source_types: {
+            [x: string]: ParticleValueType;
+        };
+        demand: number;
+        parameters: object;
+        layout: ParticleLayout;
+    }) => number;
+    /**
+     * How many lanes the node reads of each input, given the width its own operation runs at.
+     *
+     * Returns a port name -> width map; ports left out are taken to be read at the operation's
+     * width, which is the element-wise case. A demand a consumer makes beyond a value's own type is
+     * the compiler's cue to widen it: a scalar is broadcast, a vector extended with zeros, once,
+     * after the value is produced.
+     *
+     * @type {function({operation_width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout}):Object<string, number>}
+     */
+    input_widths: (arg0: {
+        operation_width: number;
+        type: ParticleValueType | null;
+        input_types: {
+            [x: string]: ParticleValueType;
+        };
+        source_types: {
+            [x: string]: ParticleValueType;
+        };
+        parameters: object;
+        layout: ParticleLayout;
+    }) => {
+        [x: string]: number;
+    };
+    /**
+     * How many lanes the node's result actually occupies. Differs from the operation's width only
+     * for the reductions, which read many lanes and write one.
+     *
+     * @type {function({operation_width: number, type: ParticleValueType|null}):number}
+     */
+    result_width: (arg0: {
+        operation_width: number;
+        type: ParticleValueType | null;
+    }) => number;
+    /**
+     * Build the body this node stands for, out of stock types, given its own parameters — or `null`
+     * for a type that lowers itself.
+     *
+     * A {@link ./ParticleNodeGroup.js group} is one node made of many whose body is fixed when the
+     * group is built. Some node types are one node made of many whose body is decided by the
+     * *instance*: a gradient with five stops is different arithmetic from a gradient with two, so
+     * there is no single body to build in advance and nothing for a group to hold. Such a type
+     * declares this instead, and {@link ./flatten_particle_graph.js} calls it and splices the result
+     * in exactly as it splices a group — so everything downstream sees stock arithmetic, and
+     * register allocation, sub-expression sharing and the optimizer all apply to it unchanged.
+     *
+     * The group that comes back has to carry the same port names this description does: they are
+     * what the wires around the node are re-made against.
+     *
+     * @type {function(object):import("./ParticleNodeGroup.js").ParticleNodeGroup|null}
+     */
+    expand: (arg0: object) => import("./ParticleNodeGroup.js").ParticleNodeGroup | null;
     /**
      * A node with no output ports produces no value, so nothing can consume it; the only reason to
      * emit it is its side effect (an attribute write, a kill). Such nodes are the roots the compiler

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleNodeDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeDescription.js"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH;IAEI;;;;;;;;;;;OAWG;IACH,sCAFsC;QAAC,EAAE,SAAW,MAAM,KAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAiB;QAAC,GAAG,oBAAmB;KAAC,KAAE,IAAI,CAExJ;IAEZ;;;;;OAKG;IACH,uBAEC;IAGL;;;OAGG;IACH,oCAFU,OAAO,CAE0C;CAN1D;gCApC+B,2DAA2D"}
+{"version":3,"file":"ParticleNodeDescription.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeDescription.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH;IAEI;;;;;;;;;OASG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;;;;OAeG;IACH,sCAFsC;QAAC,EAAE,SAAW,MAAM,KAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAC,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW;gBAAS,MAAM;UAAqB;QAAC,YAAY;gBAAS,MAAM;UAAqB;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAiB;QAAC,GAAG,oBAAmB;KAAC,KAAE,IAAI,CAEtS;IAEZ;;;;;;;;;;;;;;;;;OAiBG;IACH,oBAFmB;QAAC,MAAM;gBAAS,MAAM,GAAE,oBAAkB,IAAI;UAAE;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,iBAAe,SAAS,CAAA;KAAC,KAAE;QAAC,MAAM,EAAE,oBAAkB,IAAI,CAAC;QAAC,MAAM;gBAAS,MAAM,GAAE,oBAAkB,IAAI;UAAC;KAAC,CAYzM;IAEF;;;;;;;;;;;OAWG;IACH,wBAFmB;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW;gBAAS,MAAM;UAAqB;QAAC,YAAY;gBAAS,MAAM;UAAqB;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAgB;KAAC,KAAE,MAAM,CAE5I;IAE1E;;;;;;;;;OASG;IACH,qBAFmB;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAC;QAAC,WAAW;gBAAS,MAAM;UAAqB;QAAC,YAAY;gBAAS,MAAM;UAAqB;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,iBAAgB;KAAC;YAAS,MAAM,GAAE,MAAM;MAEpN;IAE1B;;;;;OAKG;IACH,qBAFmB;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,oBAAkB,IAAI,CAAA;KAAC,KAAE,MAAM,CAE1B;IAExD;;;;;;;;;;;;;;;;OAgBG;IACH,eAFmB,MAAM,KAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAEpE;IAEd;;;;;OAKG;IACH,uBAEC;IAGL;;;OAGG;IACH,oCAFU,OAAO,CAE0C;CAN1D;gCAhJ+B,2DAA2D"}