@woosh/meep-engine 3.16.0 → 3.17.1

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

@@ -1,234 +1,312 @@
-import { VM_BUILTIN } from "../isa/ParticleVMISA.js";
-import { PARTICLE_COMPARE_OPCODES, particle_node_descriptions } from "./ParticleNodeRegistry.js";
-import { PARTICLE_VALUE_TYPES } from "./ParticleValueType.js";
-
-/**
- * What each particle node type's static parameters *are* — the contract between the `emit` closures
- * in {@link ./ParticleNodeRegistry.js}, which read `context.parameters.<name>`, and anything that
- * has to produce those parameters without being told: an editor building controls, a default-value
- * factory, a serializer checking an authored graph.
- *
- * The engine's generic {@link ../../../../core/model/node-graph/node/NodeDescription.js} parameter
- * mechanism is not used for these. Its parameters are keyed by a numeric id and typed as
- * number / string / boolean, and a particle node's are keyed by name and are vectors, layout
- * attribute references, ISA enum members and swizzle patterns. Rather than flatten them into three
- * scalar types and lose what they mean, they are described here in their own terms, and the editor
- * renders a control per kind.
- *
- * Living beside the node library rather than in the editor is what keeps the two honest:
- * {@link ./particle_node_parameters.spec.js} asserts that every registered type is described here,
- * and that a node built from nothing but these defaults compiles.
- */
-
-/**
- * The kinds of value a particle node parameter can hold.
- * @enum {string}
- */
-export const PARTICLE_PARAMETER_KIND = Object.freeze({
-    /** one to four floats; how many there are is the value's type, a scalar or a `vec2..4` */
-    VECTOR: "vector",
-    /** four floats that are a colour: red, green, blue and alpha, each in `[0, 1]` */
-    COLOR: "color",
-    /** the name of an attribute in the effect's {@link ../layout/ParticleLayout.js} */
-    ATTRIBUTE: "attribute",
-    /** one member of {@link PARTICLE_NODE_PARAMETER_SCHEMA}'s `options` map */
-    ENUM: "enum",
-    /** one to four lane selectors in `[0, 4)`, one per output lane */
-    SWIZZLE: "swizzle",
-    /** a non-negative integer — a curve handle */
-    INTEGER: "integer",
-});
-
-/**
- * One parameter of one node type.
- *
- * @typedef {object} ParticleNodeParameter
- * @property {string} name the key the node's `emit` reads off `context.parameters`
- * @property {string} kind a {@link PARTICLE_PARAMETER_KIND}
- * @property {*} [default] the value a freshly created node takes; absent for
- *   {@link PARTICLE_PARAMETER_KIND.ATTRIBUTE}, whose default can only come from the effect's layout
- * @property {Object<string, *>} [options] for {@link PARTICLE_PARAMETER_KIND.ENUM}: label -> value
- * @property {string} [description] one line of help, shown by the editor
- */
-
-/**
- * The node types whose whole configuration is their wiring — every arithmetic, vector and logic
- * operation, plus the two sinks that take only a value.
- *
- * Listed rather than inferred so that "takes no parameters" is a claim someone made, and a node
- * type added to the library without a word about its parameters is caught by
- * {@link ./particle_node_parameters.spec.js} instead of silently reading as taking none.
- *
- * @type {string[]}
- */
-export const PARTICLE_NODES_WITHOUT_PARAMETERS = Object.freeze([
-    "kill",
-    "add", "sub", "mul", "div", "min", "max", "pow", "step",
-    "mad", "mix", "clamp", "smoothstep", "scale",
-    "neg", "abs", "floor", "fract", "sqrt", "sin", "cos", "exp", "log", "normalize", "length",
-    "dot", "cross", "distance",
-    "vec2", "vec3", "vec4",
-    "select",
-]);
-
-/**
- * A lane count offered as a type: what a `random` is asked to be, and what a literal's width picker
- * says. Labelled by the type's name, valued by its width.
- *
- * @type {Object<string, number>}
- */
-export const PARTICLE_WIDTH_OPTIONS = Object.freeze(
-    Object.fromEntries(PARTICLE_VALUE_TYPES.map(type => [type.name, type.components]))
-);
-
-/**
- * Node type name -> its parameters, in the order an editor should present them. A type with no
- * static parameters is present with an empty array, so "missing" and "has none" are distinct.
- *
- * @type {Object<string, ParticleNodeParameter[]>}
- */
-export const PARTICLE_NODE_PARAMETER_SCHEMA = Object.freeze({
-    ...Object.fromEntries(PARTICLE_NODES_WITHOUT_PARAMETERS.map(name => [name, Object.freeze([])])),
-
-    const: [{
-        name: "value",
-        kind: PARTICLE_PARAMETER_KIND.VECTOR,
-        default: [0],
-        description: "The literal this node produces — a scalar, or a vector as wide as there are numbers. "
-            + "Interned into the program's constant pool.",
-    }],
-
-    // Opaque white by default, which is the colour that changes nothing about whatever it is
-    // multiplied into and is visible against any background it is written to.
-    color: [{
-        name: "value",
-        kind: PARTICLE_PARAMETER_KIND.COLOR,
-        default: [1, 1, 1, 1],
-        description: "The colour this node produces. A vec4 of red, green, blue and alpha, "
-            + "interned into the program's constant pool like any other literal.",
-    }],
-
-    builtin: [{
-        name: "id",
-        kind: PARTICLE_PARAMETER_KIND.ENUM,
-        options: VM_BUILTIN,
-        default: VM_BUILTIN.DELTA_TIME,
-        description: "Which per-invocation value the host shader hands the VM.",
-    }],
-
-    attribute: [{
-        name: "name",
-        kind: PARTICLE_PARAMETER_KIND.ATTRIBUTE,
-        description: "The per-particle attribute to read, by name in the effect's layout.",
-    }],
-
-    // Four is the width a draw had before it had one — as wide as anything could read it — so an
-    // effect saved without saying is read the way it was written. A draw that is meant to be one
-    // value says so, and reads as a scalar.
-    random: [{
-        name: "components",
-        kind: PARTICLE_PARAMETER_KIND.ENUM,
-        options: PARTICLE_WIDTH_OPTIONS,
-        default: 4,
-        description: "How many independent draws, one per lane: a scalar, or a vector of them.",
-    }],
-
-    setAttribute: [{
-        name: "name",
-        kind: PARTICLE_PARAMETER_KIND.ATTRIBUTE,
-        description: "The per-particle attribute to write, by name in the effect's layout.",
-    }],
-
-    compare: [{
-        name: "op",
-        kind: PARTICLE_PARAMETER_KIND.ENUM,
-        // the operator NAMES are the values here: `emit` looks the opcode up by name
-        options: Object.fromEntries(Object.keys(PARTICLE_COMPARE_OPCODES).map(key => [key, key])),
-        default: "lt",
-        description: "Comparison to apply, component-wise. Produces 1 where it holds and 0 where it does not.",
-    }],
-
-    swizzle: [{
-        name: "pattern",
-        kind: PARTICLE_PARAMETER_KIND.SWIZZLE,
-        default: [0, 1, 2, 3],
-        description: "Which input lane each output lane reads; one to four of them, and that count is the result's width.",
-    }],
-
-    curve: [{
-        name: "handle",
-        kind: PARTICLE_PARAMETER_KIND.INTEGER,
-        default: 0,
-        description: "Row of the animation-curve table to sample.",
-    }],
-});
-
-/**
- * The parameters of one node type.
- *
- * @param {string} type node type name
- * @returns {ParticleNodeParameter[]} empty when the type takes none
- * @throws if the type is not described — which is a missing entry above, not an unknown node
- */
-export function particle_node_parameters(type) {
-    const parameters = PARTICLE_NODE_PARAMETER_SCHEMA[type];
-
-    if (parameters === undefined) {
-        throw new Error(
-            `Particle node type '${type}' has no parameter description. `
-            + `Add one to PARTICLE_NODE_PARAMETER_SCHEMA, even if it is empty.`
-        );
-    }
-
-    return parameters;
-}
-
-/**
- * The parameter object a freshly created node of this type should start with.
- *
- * Every parameter the type declares is present, so a new node compiles without the author having to
- * fill anything in — which is the difference between a palette that drops working nodes into a
- * graph and one that drops broken ones.
- *
- * Attribute parameters have no default of their own: the only sensible one is a name from the
- * effect being authored, so the layout has to be supplied. With no layout (or an empty one) they
- * come back as the empty string, which will not compile — the caller is expected to know that and
- * either pass a layout or fill the name in.
- *
- * @param {string} type node type name
- * @param {object} [context]
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
- *   attribute schema, used to pick a default for attribute parameters
- * @returns {object}
- */
-export function particle_node_default_parameters(type, { layout } = {}) {
-    const result = {};
-
-    const first_attribute = layout === undefined ? undefined : layout.attributes.keys().next().value;
-
-    for (const parameter of particle_node_parameters(type)) {
-        if (parameter.kind === PARTICLE_PARAMETER_KIND.ATTRIBUTE) {
-            result[parameter.name] = first_attribute ?? "";
-        } else if (Array.isArray(parameter.default)) {
-            // arrays are mutable and a node writes through to its own; a shared one would make two
-            // nodes of the same type the same node
-            result[parameter.name] = parameter.default.slice();
-        } else {
-            result[parameter.name] = parameter.default;
-        }
-    }
-
-    return result;
-}
-
-/**
- * Every node type in the library paired with its parameters, for a palette to list.
- *
- * @returns {Array<{description: import("./ParticleNodeDescription.js").ParticleNodeDescription, parameters: ParticleNodeParameter[]}>}
- */
-export function particle_node_catalogue() {
-    return particle_node_descriptions().map(description => ({
-        description,
-        parameters: particle_node_parameters(description.name),
-    }));
-}
+import { VM_BUILTIN } from "../isa/ParticleVMISA.js";
+import { PARTICLE_COMPARE_OPCODES } from "./particle_compare_ops.js";
+import { particle_curve_default, particle_gradient_default } from "./particle_ramp.js";
+import { particle_node_descriptions } from "./ParticleNodeRegistry.js";
+import { PARTICLE_VALUE_TYPES } from "./ParticleValueType.js";
+
+/**
+ * What each particle node type's static parameters *are* — the contract between the `emit` closures
+ * in {@link ./ParticleNodeRegistry.js}, which read `context.parameters.<name>`, and anything that
+ * has to produce those parameters without being told: an editor building controls, a default-value
+ * factory, a serializer checking an authored graph.
+ *
+ * The engine's generic {@link ../../../../core/model/node-graph/node/NodeDescription.js} parameter
+ * mechanism is not used for these. Its parameters are keyed by a numeric id and typed as
+ * number / string / boolean, and a particle node's are keyed by name and are vectors, layout
+ * attribute references, ISA enum members and swizzle patterns. Rather than flatten them into three
+ * scalar types and lose what they mean, they are described here in their own terms, and the editor
+ * renders a control per kind.
+ *
+ * Living beside the node library rather than in the editor is what keeps the two honest:
+ * {@link ./particle_node_parameters.spec.js} asserts that every registered type is described here,
+ * and that a node built from nothing but these defaults compiles.
+ */
+
+/**
+ * The kinds of value a particle node parameter can hold.
+ * @enum {string}
+ */
+export const PARTICLE_PARAMETER_KIND = Object.freeze({
+    /** one to four floats; how many there are is the value's type, a scalar or a `vec2..4` */
+    VECTOR: "vector",
+    /** four floats that are a colour: red, green, blue and alpha, each in `[0, 1]` */
+    COLOR: "color",
+    /** the name of an attribute in the effect's {@link ../layout/ParticleLayout.js} */
+    ATTRIBUTE: "attribute",
+    /** one member of {@link PARTICLE_NODE_PARAMETER_SCHEMA}'s `options` map */
+    ENUM: "enum",
+    /** one to four lane selectors in `[0, 4)`, one per output lane */
+    SWIZZLE: "swizzle",
+    /** a non-negative integer — a curve handle */
+    INTEGER: "integer",
+    /**
+     * an {@link ../../../../engine/animation/curve/AnimationCurve.js AnimationCurve}, as the
+     * `{keys: [...]}` record that class writes and reads
+     */
+    CURVE: "curve",
+    /**
+     * a colour gradient: a list of `{position, color}` stops, see
+     * {@link ./particle_ramp.js ParticleGradientStop}
+     */
+    GRADIENT: "gradient",
+});
+
+/**
+ * One parameter of one node type.
+ *
+ * @typedef {object} ParticleNodeParameter
+ * @property {string} name the key the node's `emit` reads off `context.parameters`
+ * @property {string} kind a {@link PARTICLE_PARAMETER_KIND}
+ * @property {*} [default] the value a freshly created node takes; absent for
+ *   {@link PARTICLE_PARAMETER_KIND.ATTRIBUTE}, whose default can only come from the effect's layout
+ * @property {Object<string, *>} [options] for {@link PARTICLE_PARAMETER_KIND.ENUM}: label -> value
+ * @property {boolean} [alpha] for {@link PARTICLE_PARAMETER_KIND.GRADIENT}: whether the node reads
+ *   the alpha channel. Both gradients *store* one — see {@link ./particle_ramp.js} — so that a
+ *   gradient moved from the RGBA node to the RGB one and back keeps it; this says whether to offer
+ *   it for editing.
+ * @property {string} [description] one line of help, shown by the editor
+ */
+
+/**
+ * The node types whose whole configuration is their wiring — every arithmetic, vector and logic
+ * operation, plus the two sinks that take only a value.
+ *
+ * Listed rather than inferred so that "takes no parameters" is a claim someone made, and a node
+ * type added to the library without a word about its parameters is caught by
+ * {@link ./particle_node_parameters.spec.js} instead of silently reading as taking none.
+ *
+ * @type {string[]}
+ */
+export const PARTICLE_NODES_WITHOUT_PARAMETERS = Object.freeze([
+    "kill",
+    "add", "sub", "mul", "div", "min", "max", "pow", "step",
+    "mad", "mix", "clamp", "saturate", "smoothstep", "scale",
+    "neg", "abs", "floor", "fract", "sqrt", "rsqrt", "sin", "cos", "tan", "asin", "acos", "atan2",
+    "exp", "log", "normalize", "length",
+    "dot", "cross", "distance",
+    "vec2", "vec3", "vec4",
+    "select",
+]);
+
+/**
+ * A lane count offered as a type: what a `random` is asked to be, and what a literal's width picker
+ * says. Labelled by the type's name, valued by its width.
+ *
+ * @type {Object<string, number>}
+ */
+export const PARTICLE_WIDTH_OPTIONS = Object.freeze(
+    Object.fromEntries(PARTICLE_VALUE_TYPES.map(type => [type.name, type.components]))
+);
+
+/**
+ * Node type name -> its parameters, in the order an editor should present them. A type with no
+ * static parameters is present with an empty array, so "missing" and "has none" are distinct.
+ *
+ * @type {Object<string, ParticleNodeParameter[]>}
+ */
+export const PARTICLE_NODE_PARAMETER_SCHEMA = Object.freeze({
+    ...Object.fromEntries(PARTICLE_NODES_WITHOUT_PARAMETERS.map(name => [name, Object.freeze([])])),
+
+    const: [{
+        name: "value",
+        kind: PARTICLE_PARAMETER_KIND.VECTOR,
+        default: [0],
+        description: "The literal this node produces — a scalar, or a vector as wide as there are numbers. "
+            + "Interned into the program's constant pool.",
+    }],
+
+    // Opaque white by default, which is the colour that changes nothing about whatever it is
+    // multiplied into and is visible against any background it is written to.
+    color: [{
+        name: "value",
+        kind: PARTICLE_PARAMETER_KIND.COLOR,
+        default: [1, 1, 1, 1],
+        description: "The colour this node produces. A vec4 of red, green, blue and alpha, "
+            + "interned into the program's constant pool like any other literal.",
+    }],
+
+    builtin: [{
+        name: "id",
+        kind: PARTICLE_PARAMETER_KIND.ENUM,
+        options: VM_BUILTIN,
+        default: VM_BUILTIN.DELTA_TIME,
+        description: "Which per-invocation value the host shader hands the VM.",
+    }],
+
+    attribute: [{
+        name: "name",
+        kind: PARTICLE_PARAMETER_KIND.ATTRIBUTE,
+        description: "The per-particle attribute to read, by name in the effect's layout.",
+    }],
+
+    // Four is the width a draw had before it had one — as wide as anything could read it — so an
+    // effect saved without saying is read the way it was written. A draw that is meant to be one
+    // value says so, and reads as a scalar.
+    random: [{
+        name: "components",
+        kind: PARTICLE_PARAMETER_KIND.ENUM,
+        options: PARTICLE_WIDTH_OPTIONS,
+        default: 4,
+        description: "How many independent draws, one per lane: a scalar, or a vector of them.",
+    }],
+
+    setAttribute: [{
+        name: "name",
+        kind: PARTICLE_PARAMETER_KIND.ATTRIBUTE,
+        description: "The per-particle attribute to write, by name in the effect's layout.",
+    }],
+
+    compare: [{
+        name: "op",
+        kind: PARTICLE_PARAMETER_KIND.ENUM,
+        // the operator NAMES are the values here: `emit` looks the opcode up by name
+        options: Object.fromEntries(Object.keys(PARTICLE_COMPARE_OPCODES).map(key => [key, key])),
+        default: "lt",
+        description: "Comparison to apply, component-wise. Produces 1 where it holds and 0 where it does not.",
+    }],
+
+    swizzle: [{
+        name: "pattern",
+        kind: PARTICLE_PARAMETER_KIND.SWIZZLE,
+        default: [0, 1, 2, 3],
+        description: "Which input lane each output lane reads; one to four of them, and that count is the result's width.",
+    }],
+
+    curve: [{
+        name: "handle",
+        kind: PARTICLE_PARAMETER_KIND.INTEGER,
+        default: 0,
+        description: "Row of the animation-curve table to sample.",
+    }],
+
+    curveLiteral: [{
+        name: "curve",
+        kind: PARTICLE_PARAMETER_KIND.CURVE,
+        default: particle_curve_default(),
+        description: "The curve this node is. Written into the program as arithmetic rather than "
+            + "sampled from a table, so it costs no upload and no fetch.",
+    }],
+
+    // Both gradients hold the same thing, so that copying one to the other keeps every channel.
+    ...Object.fromEntries([["gradientRGBA", true], ["gradientRGB", false]].map(([name, alpha]) => [name, [{
+        name: "stops",
+        kind: PARTICLE_PARAMETER_KIND.GRADIENT,
+        alpha,
+        default: particle_gradient_default(),
+        description: "The gradient's stops: where each sits along t, and the colour there. "
+            + "Interpolated linearly, and written into the program as arithmetic.",
+    }]])),
+});
+
+/**
+ * A node's parameters, copied deeply enough that the copy and the original cannot write through to
+ * each other.
+ *
+ * There are four places a parameter object is copied — flattening a group, making one, taking one
+ * apart again, and handing a fresh node its defaults — and until the library had a parameter with a
+ * shape inside it they were all one level deep and all correct. A gradient's stops are a level
+ * further down than a literal's lanes, and a copy that stopped at the array would have left an
+ * ungrouped gradient sharing its stops with the group definition it came out of: edit the colour on
+ * one and it changes on the other, and on every other instance of that group.
+ *
+ * So there is one of these now, and it goes all the way down. Values are numbers, strings, and arrays
+ * and plain records of those; it is written out rather than handed to `structuredClone` because
+ * flattening a `curl4` runs it four thousand times and none of these values needs the machinery.
+ *
+ * @param {object} parameters
+ * @returns {object}
+ */
+export function clone_particle_parameters(parameters) {
+    return clone_parameter(parameters);
+}
+
+/**
+ * @param {*} value
+ * @returns {*}
+ */
+function clone_parameter(value) {
+    if (Array.isArray(value)) {
+        return value.map(clone_parameter);
+    }
+
+    if (value !== null && typeof value === "object") {
+        const copy = {};
+
+        for (const key of Object.keys(value)) {
+            copy[key] = clone_parameter(value[key]);
+        }
+
+        return copy;
+    }
+
+    return value;
+}
+
+/**
+ * The parameters of one node type.
+ *
+ * @param {string} type node type name
+ * @returns {ParticleNodeParameter[]} empty when the type takes none
+ * @throws if the type is not described — which is a missing entry above, not an unknown node
+ */
+export function particle_node_parameters(type) {
+    const parameters = PARTICLE_NODE_PARAMETER_SCHEMA[type];
+
+    if (parameters === undefined) {
+        throw new Error(
+            `Particle node type '${type}' has no parameter description. `
+            + `Add one to PARTICLE_NODE_PARAMETER_SCHEMA, even if it is empty.`
+        );
+    }
+
+    return parameters;
+}
+
+/**
+ * The parameter object a freshly created node of this type should start with.
+ *
+ * Every parameter the type declares is present, so a new node compiles without the author having to
+ * fill anything in — which is the difference between a palette that drops working nodes into a
+ * graph and one that drops broken ones.
+ *
+ * Attribute parameters have no default of their own: the only sensible one is a name from the
+ * effect being authored, so the layout has to be supplied. With no layout (or an empty one) they
+ * come back as the empty string, which will not compile — the caller is expected to know that and
+ * either pass a layout or fill the name in.
+ *
+ * @param {string} type node type name
+ * @param {object} [context]
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
+ *   attribute schema, used to pick a default for attribute parameters
+ * @returns {object}
+ */
+export function particle_node_default_parameters(type, { layout } = {}) {
+    const result = {};
+
+    const first_attribute = layout === undefined ? undefined : layout.attributes.keys().next().value;
+
+    for (const parameter of particle_node_parameters(type)) {
+        if (parameter.kind === PARTICLE_PARAMETER_KIND.ATTRIBUTE) {
+            result[parameter.name] = first_attribute ?? "";
+        } else {
+            // A default that is not a number is mutable, and a node writes through to its own: a
+            // shared one would make every node of the type the same node, and editing one gradient
+            // would edit the library's idea of what a gradient starts as.
+            result[parameter.name] = clone_parameter(parameter.default);
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Every node type in the library paired with its parameters, for a palette to list.
+ *
+ * @returns {Array<{description: import("./ParticleNodeDescription.js").ParticleNodeDescription, parameters: ParticleNodeParameter[]}>}
+ */
+export function particle_node_catalogue() {
+    return particle_node_descriptions().map(description => ({
+        description,
+        parameters: particle_node_parameters(description.name),
+    }));
+}

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

@@ -1 +1 @@
-{"version":3,"file":"particle_node_presentation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_node_presentation.js"],"names":[],"mappings":"AAmRA;;;;;;;GAOG;AACH,iDAHW,MAAM,GACJ;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAIvD;AAnPD;;;;;;;;GAQG;AACH;QAFiB,MAAM,GAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC;EAgOjE"}
+{"version":3,"file":"particle_node_presentation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_node_presentation.js"],"names":[],"mappings":"AA2UA;;;;;;;GAOG;AACH,iDAHW,MAAM,GACJ;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAIvD;AA3SD;;;;;;;;GAQG;AACH;QAFiB,MAAM,GAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC;EAwRjE"}