@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -1,44 +1,152 @@
-import { noop } from "../../../../core/function/noop.js";
-import { NodeDescription } from "../../../../core/model/node-graph/node/NodeDescription.js";
-import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
-
-/**
- * A particle node type: a {@link NodeDescription} that additionally knows how to lower an instance
- * of itself into VM instructions.
- *
- * 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.
- */
-export class ParticleNodeDescription extends NodeDescription {
-
-    /**
-     * 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.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}
-     */
-    emit = noop;
-
-    /**
-     * 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
-     * traverses from.
-     * @returns {boolean}
-     */
-    get is_sink() {
-        return !this.hasPortsByDirection(PortDirection.Out);
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-ParticleNodeDescription.prototype.isParticleNodeDescription = true;
+import { noop } from "../../../../core/function/noop.js";
+import { NodeDescription } from "../../../../core/model/node-graph/node/NodeDescription.js";
+import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
+import { particle_widest_type } from "./ParticleValueType.js";
+
+/**
+ * A particle node type: a {@link NodeDescription} that additionally knows how to lower an instance
+ * of itself into VM instructions.
+ *
+ * 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 = "";
+
+    /**
+     * 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, width: number, type: ParticleValueType|null, input_types: Object<string, ParticleValueType>, source_types: Object<string, ParticleValueType>, parameters: object, layout: ParticleLayout, asm: ParticleAssembler}):void}
+     */
+    emit = noop;
+
+    /**
+     * 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 = ({ inputs }) => {
+        const output = particle_widest_type(Object.values(inputs));
+
+        const read = {};
+
+        for (const port of Object.keys(inputs)) {
+            read[port] = output;
+        }
+
+        return { output, inputs: read };
+    };
+
+    /**
+     * 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 = ({ type, demand }) => Math.min(type.components, demand);
+
+    /**
+     * 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 = () => ({});
+
+    /**
+     * 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 = ({ operation_width }) => operation_width;
+
+    /**
+     * 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 = 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
+     * traverses from.
+     * @returns {boolean}
+     */
+    get is_sink() {
+        return !this.hasPortsByDirection(PortDirection.Out);
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ParticleNodeDescription.prototype.isParticleNodeDescription = true;

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

@@ -0,0 +1,283 @@
+/**
+ * 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: NodeInstance): boolean;
+/**
+ * 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: NodeInstance): boolean;
+/**
+ * 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: NodeDescription): boolean;
+/**
+ * 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: number;
+/**
+ * @type {number}
+ */
+export const PARTICLE_GROUP_OUTPUT_NODE: number;
+/**
+ * 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 {
+    /**
+     * 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, inputs, outputs }: {
+        name: string;
+        label?: string;
+        icon?: string;
+        help?: string;
+        locked?: boolean;
+        inputs?: Array<{
+            name: string;
+            type: import("./ParticleValueType.js").ParticleValueType;
+        }>;
+        outputs?: Array<{
+            name: string;
+            type: import("./ParticleValueType.js").ParticleValueType;
+        }>;
+    }): 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: string;
+    /**
+     * What to call it in front of a person.
+     * @type {string}
+     */
+    label: string;
+    /**
+     * Glyph, as SVG path data in a 24x24 box. See {@link NodeDescription#icon}.
+     * @type {string}
+     */
+    icon: string;
+    /**
+     * One line of help, for a palette to show under the name.
+     * @type {string}
+     */
+    help: string;
+    /**
+     * Whether the body is the author's to change. See the note above.
+     * @type {boolean}
+     */
+    locked: boolean;
+    /**
+     * 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: Array<{
+        name: string;
+        type: import("./ParticleValueType.js").ParticleValueType | null;
+    }>;
+    /**
+     * The group's declared outputs, in port order.
+     * @type {Array<{name: string, type: import("./ParticleValueType.js").ParticleValueType|null}>}
+     */
+    outputs: Array<{
+        name: string;
+        type: import("./ParticleValueType.js").ParticleValueType | null;
+    }>;
+    /**
+     * The body: the nodes the group is made of, plus its two boundary nodes.
+     * @type {NodeGraph}
+     */
+    graph: NodeGraph;
+    /**
+     * Where the body's nodes sit, for a view that opens the group.
+     * @type {NodeGraphVisualData}
+     */
+    visual: NodeGraphVisualData;
+    /**
+     * The type an instance of this group is, as placed in a graph.
+     * @type {ParticleGroupNodeDescription}
+     */
+    description: ParticleGroupNodeDescription;
+    /**
+     * The boundary node inside the body that values arrive at.
+     * @type {NodeInstance}
+     */
+    inputNode: NodeInstance;
+    /**
+     * The boundary node inside the body that values leave from.
+     * @type {NodeInstance}
+     */
+    outputNode: NodeInstance;
+    /**
+     * 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: string, direction: PortDirection): import("./ParticleValueType.js").ParticleValueType | null;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isParticleNodeGroup: boolean;
+}
+/**
+ * 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: ParticleNodeGroup);
+    /**
+     * @readonly
+     * @type {ParticleNodeGroup}
+     */
+    readonly group: ParticleNodeGroup;
+    infer_types: ({ inputs }: {
+        inputs: any;
+    }) => {
+        output: import("./ParticleValueType.js").ParticleValueType;
+        outputs: {
+            [k: string]: import("./ParticleValueType.js").ParticleValueType;
+        };
+        inputs: {
+            [k: string]: import("./ParticleValueType.js").ParticleValueType;
+        };
+    };
+    emit: () => never;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isParticleGroupNodeDescription: boolean;
+}
+/**
+ * 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: ParticleNodeGroup, side: string);
+    /**
+     * @readonly
+     * @type {ParticleNodeGroup}
+     */
+    readonly group: ParticleNodeGroup;
+    /**
+     * Which block this is: `"input"` or `"output"`.
+     * @readonly
+     * @type {string}
+     */
+    readonly side: string;
+    infer_types: () => {
+        output: import("./ParticleValueType.js").ParticleValueType;
+        outputs: {
+            [k: string]: import("./ParticleValueType.js").ParticleValueType;
+        };
+        inputs: {};
+    } | {
+        output: any;
+        inputs: {
+            [k: string]: import("./ParticleValueType.js").ParticleValueType;
+        };
+        outputs?: undefined;
+    };
+    emit: () => never;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isParticleGroupBoundaryDescription: boolean;
+}
+import { NodeInstance } from "../../../../core/model/node-graph/node/NodeInstance.js";
+import { NodeGraph } from "../../../../core/model/node-graph/NodeGraph.js";
+import { NodeGraphVisualData } from "../../../../core/model/node-graph/visual/NodeGraphVisualData.js";
+import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
+import { ParticleNodeDescription } from "./ParticleNodeDescription.js";
+//# sourceMappingURL=ParticleNodeGroup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleNodeGroup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js"],"names":[],"mappings":"AAiWA;;;;;GAKG;AACH,6CAHW,YAAY,GACV,OAAO,CAInB;AAED;;;;;GAKG;AACH,iDAHW,YAAY,GACV,OAAO,CAInB;AAED;;;;;;;;;;GAUG;AACH,6EAFa,OAAO,CAKnB;AA3XD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;GASG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;GAEG;AACH,yCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH;IA2EI;;;;;;;;;;;;;;;OAeG;IACH;QAT2B,IAAI,EAApB,MAAM;QACW,KAAK,GAAtB,MAAM;QACW,IAAI,GAArB,MAAM;QACW,IAAI,GAArB,MAAM;QACY,MAAM,GAAxB,OAAO;QACmF,MAAM,GAAhG,MAAM;YAAC,MAAM,MAAM,CAAC;YAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,CAAA;SAAC,CAAC;QACW,OAAO,GAAjG,MAAM;YAAC,MAAM,MAAM,CAAC;YAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,CAAA;SAAC,CAAC;QAC7E,iBAAiB,CA2B7B;IAnHD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,OAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,OAAO,CAEH;IAEd;;;;OAIG;IACH,QAFU,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAAA;KAAC,CAAC,CAElF;IAEZ;;;OAGG;IACH,SAFU,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAAA;KAAC,CAAC,CAEjF;IAEb;;;OAGG;IACH,OAFU,SAAS,CAEK;IAExB;;;OAGG;IACH,QAFU,mBAAmB,CAEM;IAEnC;;;OAGG;IACH,aAFU,4BAA4B,CAEnB;IAEnB;;;OAGG;IACH,WAFU,YAAY,CAEL;IAEjB;;;OAGG;IACH,YAFU,YAAY,CAEJ;IA6ClB;;;;;;OAMG;IACH,oBAJW,MAAM,aACN,aAAa,GACX,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAMnE;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;CAN9C;AAQD;;;;;;;GAOG;AACH;IACI;;OAEG;IACH,mBAFW,iBAAiB,EAwD3B;IAnDG;;;OAGG;IACH,gBAFU,iBAAiB,CAET;IAwBlB;;;;;;;;;;MAeC;IAED,kBAKC;IAIT;;;OAGG;IACH,yCAFU,OAAO,CAEoD;CANpE;AAQD;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,mBAHW,iBAAiB,QACjB,MAAM,EAqDhB;IAhDG;;;OAGG;IACH,gBAFU,iBAAiB,CAET;IAElB;;;;OAIG;IACH,eAFU,MAAM,CAEA;IAoBhB;;;;;;;;;;;;MASM;IAEN,kBAKC;IAIT;;;OAGG;IACH,6CAFU,OAAO,CAE4D;CAN5E;6BAxV4B,wDAAwD;0BAD3D,gDAAgD;oCAGtC,iEAAiE;8BADvE,yDAAyD;wCAE/C,8BAA8B"}