@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -1,133 +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";
-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;
-
-    /**
-     * 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/ParticleNodeRegistry.d.ts

@@ -59,17 +59,6 @@ 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":"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"}
+{"version":3,"file":"ParticleNodeRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/ParticleNodeRegistry.js"],"names":[],"mappings":"AAqrBA;;;;;;;GAOG;AACH,8CAFa,uBAAuB,EAAE,CAIrC;AAED;;;;;GAKG;AACH,oDAJW,MAAM,GACJ,uBAAuB,CAWnC;AAhrBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;GASG;AACH,kCAFU,QAAQ,CAE2C;AAE7D;;;GAGG;AACH,wCAFU,MAAM,CAE+B;AAE/C;;GAEG;AACH,qCAFU,YAAY,CAEmC;wCAhEjB,8BAA8B;yBAZ7C,oDAAoD;6BAFhD,wDAAwD"}