@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -0,0 +1,286 @@
+/**
+ * What a person sees of each particle node type: what it is called, the glyph it carries, and the
+ * one line of help a palette offers under its name.
+ *
+ * The library's own names are addresses — they are what a saved graph holds and what
+ * {@link ./ParticleNodeRegistry.js get_particle_node_description} looks a type up by — so they are
+ * terse and they do not change. `div`, `mad`, `setAttribute`. Nobody reads those as "divide",
+ * "multiply-add" and "write attribute" without translating, and an editor that shows only them
+ * makes every author do that translation on every node, every time.
+ *
+ * So the names stay what they are and this says what to draw instead. Kept out of the registry
+ * because that file is about lowering nodes to instructions and this is about none of that; kept
+ * out of the views because all of them — the node, the palette, whatever lists node types next —
+ * have to agree, and a table each is three tables that drift.
+ *
+ * ## The icons
+ *
+ * SVG path data in a 24x24 box, no colour and no stroke width: see
+ * {@link ../../../../core/model/node-graph/node/NodeDescription.js NodeDescription#icon}, which is
+ * where these end up, and `NodeIconView`, which draws them.
+ *
+ * They are drawn on a shared skeleton — strokes between 4 and 20, nothing thinner than a couple of
+ * units apart — because these are read at about fourteen pixels in a node's header, where detail is
+ * lost and only the silhouette survives. Where an operation already has a symbol everybody knows,
+ * that symbol is the icon: `add` is a plus, `mul` is a cross, `compare` is a pair of angle
+ * brackets. Inventing a picture for arithmetic would be worse than the arithmetic.
+ */
+
+/**
+ * A dot, as a path: two half-arcs closing on themselves. Zero-length subpaths with a round cap draw
+ * a dot too, but only where the stroke is round — and these are drawn by a stylesheet that a host
+ * may have opinions about.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @param {number} r
+ * @returns {string}
+ */
+function dot(x, y, r) {
+    return `M${x} ${y - r}a${r} ${r} 0 1 0 0 ${r * 2}a${r} ${r} 0 1 0 0 ${-r * 2}`;
+}
+
+/**
+ * Everything the editor shows about a node type, by the type's name.
+ *
+ * Every type in the library has an entry, and no entry names a type the library does not have —
+ * both directions are checked by `ParticleNodeRegistry.spec.js`, so a node type added without a
+ * label fails a test rather than quietly showing up in the graph as `smoothstep`.
+ *
+ * @type {Object<string, {label: string, icon: string, help: string}>}
+ */
+export const PARTICLE_NODE_PRESENTATION = Object.freeze({
+    // --- sources ---
+    const: {
+        label: "Constant",
+        icon: `M6 6h12v12H6z ${dot(12, 12, 1.6)}`,
+        help: "a literal: one number is a scalar, two to four a vector",
+    },
+    color: {
+        label: "Colour",
+        icon: "M12 4c0 0 6 6.6 6 10.4a6 6 0 0 1-12 0C6 10.6 12 4 12 4z",
+        help: "a literal colour — a vec4 that says it is one",
+    },
+    builtin: {
+        label: "Built-in Value",
+        icon: "M6 7h12v10H6z M9 4v3 M15 4v3 M9 17v3 M15 17v3",
+        help: "a value the host provides — delta time, emitter position…",
+    },
+    attribute: {
+        label: "Read Attribute",
+        icon: "M5 5v14 M8 12h11 M16 9l3 3-3 3",
+        help: "read one of this effect's per-particle attributes",
+    },
+    random: {
+        label: "Random",
+        icon: `M5 5h14v14H5z ${dot(9, 9, 1.3)} ${dot(15, 15, 1.3)}`,
+        help: "uniform draws in [0, 1), one per lane, as many lanes as asked",
+    },
+
+    // --- sinks ---
+    setAttribute: {
+        label: "Write Attribute",
+        icon: "M19 5v14 M5 12h11 M13 9l3 3-3 3",
+        help: "write a per-particle attribute",
+    },
+    kill: {
+        label: "Kill Particle",
+        icon: "M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18 M9 9l6 6 M15 9l-6 6",
+        help: "destroy the particle where the condition is positive",
+    },
+
+    // --- arithmetic ---
+    add: {
+        label: "Add",
+        icon: "M12 5v14 M5 12h14",
+        help: "a + b",
+    },
+    sub: {
+        label: "Subtract",
+        icon: "M5 12h14",
+        help: "a - b",
+    },
+    mul: {
+        label: "Multiply",
+        icon: "M6 6l12 12 M18 6L6 18",
+        help: "a * b, lane by lane",
+    },
+    div: {
+        label: "Divide",
+        icon: `M5 12h14 ${dot(12, 8, 1.3)} ${dot(12, 16, 1.3)}`,
+        help: "a / b",
+    },
+    min: {
+        label: "Minimum",
+        icon: "M5 8l7 8 7-8",
+        help: "the smaller of the two, lane by lane",
+    },
+    max: {
+        label: "Maximum",
+        icon: "M5 16l7-8 7 8",
+        help: "the larger of the two, lane by lane",
+    },
+    pow: {
+        label: "Power",
+        icon: "M5 19C9 19 11 5 19 5",
+        help: "a raised to b",
+    },
+    step: {
+        label: "Step",
+        icon: "M4 18h7V6h9",
+        help: "0 below the edge, 1 at or above it",
+    },
+    mad: {
+        label: "Multiply Add",
+        icon: "M4 5l5 5 M9 5l-5 5 M18 13v7 M14.5 16.5h7",
+        help: "a * b + c",
+    },
+    mix: {
+        label: "Mix",
+        icon: "M4 6h5c5 0 4 12 9 12h2 M4 18h5c5 0 4-12 9-12h2",
+        help: "a and b blended by t",
+    },
+    clamp: {
+        label: "Clamp",
+        icon: "M6 5v14 M18 5v14 M6 12h12",
+        help: "held between a low and a high bound",
+    },
+    smoothstep: {
+        label: "Smooth Step",
+        icon: "M4 18C8 18 8 6 12 6s4 12 8 12",
+        help: "a smooth 0..1 ramp between two edges",
+    },
+    scale: {
+        label: "Scale",
+        icon: "M6 18L18 6 M13 6h5v5",
+        help: "a vector times a scalar",
+    },
+
+    // --- unary math ---
+    neg: {
+        label: "Negate",
+        icon: "M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18 M8 12h8",
+        help: "the same value with its sign flipped",
+    },
+    abs: {
+        label: "Absolute",
+        icon: "M7 5v14 M17 5v14 M10 8l2 8 2-8",
+        help: "the magnitude, sign discarded",
+    },
+    floor: {
+        label: "Floor",
+        icon: "M6 5v13h12 M6 12h4",
+        help: "rounded down to a whole number",
+    },
+    fract: {
+        label: "Fraction",
+        icon: `M7 17L17 7 ${dot(8.5, 9, 1.6)} ${dot(15.5, 15, 1.6)}`,
+        help: "what is left after the whole part",
+    },
+    sqrt: {
+        label: "Square Root",
+        icon: "M4 13h3l3 7 5-15h9",
+        help: "the square root",
+    },
+    sin: {
+        label: "Sine",
+        icon: "M3 12c3-8 6-8 9 0s6 8 9 0",
+        help: "the sine, in radians",
+    },
+    cos: {
+        label: "Cosine",
+        icon: "M3 7c4.5 0 4.5 10 9 10s4.5-10 9-10",
+        help: "the cosine, in radians",
+    },
+    exp: {
+        label: "Exponential",
+        icon: "M4 4v16h16 M7 18C13 18 13 8 18 6",
+        help: "e raised to x",
+    },
+    log: {
+        label: "Logarithm",
+        icon: "M4 4v16h16 M7 19c1-9 5-12 11-13",
+        help: "the natural logarithm",
+    },
+
+    // --- vector ---
+    normalize: {
+        label: "Normalize",
+        icon: "M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18 M12 12l6-6",
+        help: "the same direction, length one",
+    },
+    length: {
+        label: "Length",
+        icon: "M4 8v8 M20 8v8 M4 12h16",
+        help: "how long the vector is",
+    },
+    dot: {
+        label: "Dot Product",
+        icon: `M4 6l5 6-5 6 M20 6l-5 6 5 6 ${dot(12, 12, 1.3)}`,
+        help: "how much two vectors point the same way",
+    },
+    cross: {
+        label: "Cross Product",
+        icon: "M12 21V12 M12 12L4 7 M12 12l8-5",
+        help: "the vector perpendicular to both",
+    },
+    distance: {
+        label: "Distance",
+        icon: `${dot(6, 12, 2)} ${dot(18, 12, 2)} M9 12h6`,
+        help: "how far apart two points are",
+    },
+    swizzle: {
+        label: "Swizzle",
+        icon: "M4 7h5c5 0 4 10 9 10h2 M4 17h5c5 0 4-10 9-10h2",
+        help: "pick and reorder lanes; the pattern's length is the result's width",
+    },
+    // "Combine", rather than the type's own name, so that these and the `decompose` groups read as
+    // the pair they are — and so that looking for either half finds it. The constructors were here
+    // long before anything took a vector apart, and were named after what they produce.
+    vec2: {
+        label: "Combine vec2",
+        icon: "M6 9h12 M6 15h12",
+        help: "two scalars as one vector, x and y",
+    },
+    vec3: {
+        label: "Combine vec3",
+        icon: "M6 7h12 M6 12h12 M6 17h12",
+        help: "three scalars as one vector, x, y and z",
+    },
+    vec4: {
+        label: "Combine vec4",
+        icon: "M6 6h12 M6 10h12 M6 14h12 M6 18h12",
+        help: "four scalars as one vector, x, y, z and w",
+    },
+
+    // --- logic ---
+    compare: {
+        label: "Compare",
+        icon: "M9 7l-5 5 5 5 M15 7l5 5-5 5",
+        help: "component-wise comparison, 1 where it holds",
+    },
+    select: {
+        label: "Select",
+        icon: "M4 8h6l4 4h7 M4 16h6l3-3 M18 9l3 3-3 3",
+        help: "b where the condition is positive, a elsewhere",
+    },
+
+    // --- curves ---
+    curve: {
+        label: "Curve",
+        icon: `M5 18C10 18 9 6 19 6 ${dot(5, 18, 1.6)} ${dot(19, 6, 1.6)}`,
+        help: "sample an animation curve at t",
+    },
+});
+
+/**
+ * What to show for a node type. A type with no entry falls back to its own name and no artwork,
+ * which is what the base {@link NodeDescription} does anyway — a library extended at runtime shows
+ * up plainly rather than not at all.
+ *
+ * @param {string} name node type name
+ * @returns {{label: string, icon: string, help: string}}
+ */
+export function particle_node_presentation(name) {
+    return PARTICLE_NODE_PRESENTATION[name] ?? { label: "", icon: "", help: "" };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * @param {NodeGraph} graph
+ * @param {object} [context]
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
+ *   attribute schema; without it, attribute references cannot be checked and are left alone
+ * @param {string} [context.phase] which {@link PARTICLE_GRAPH_PHASE} this graph is; without it the
+ *   checks that only hold for one phase are skipped rather than guessed at
+ * @returns {ParticleGraphDiagnostic[]}
+ */
+export function validate_particle_graph(graph: NodeGraph, { layout, phase }?: {
+    layout?: import("../layout/ParticleLayout.js").ParticleLayout;
+    phase?: string;
+}): ParticleGraphDiagnostic[];
+/**
+ * The two phases of an effect, one graph each.
+ *
+ * INIT runs once when a particle is spawned, UPDATE once per frame while it lives. Named here
+ * because which of the two a graph is changes what is wrong with it, so it is something
+ * {@link validate_particle_graph } is told rather than something each caller decides for itself.
+ */
+export type PARTICLE_GRAPH_PHASE = string;
+/**
+ * Check a particle graph and say what is wrong with it, per node.
+ *
+ * {@link ./compile_particle_graph.js} throws at the first problem, which is right for a compiler
+ * and useless for an editor: an author with three unbound inputs wants to see three markers, not to
+ * fix one and be told about the next. This walks the whole graph and reports everything, each
+ * finding carrying the node it belongs to so a view can put a marker on it.
+ *
+ * It is a pre-flight check, not a second compiler. It finds what can be seen from the graph's
+ * structure and its nodes' parameters; anything that only shows up while lowering — running out of
+ * registers, most obviously — is left to the compiler, whose exception the caller reports as a
+ * problem with the graph as a whole.
+ *
+ * A graph is one phase of an effect, and a caller that says which phase gets the checks that only
+ * mean something for one of them. Keeping that here rather than in the caller is what keeps every
+ * question about a graph answered in one place.
+ *
+ * The types are checked here too, by way of {@link ./infer_particle_graph_types.js}: a value read
+ * narrower or wider than it is comes back as a warning naming the lanes, against the node reading
+ * it. The shape of a finding is {@link ./particle_graph_diagnostic.js ParticleGraphDiagnostic}.
+ *
+ * ## Groups
+ *
+ * A {@link ./ParticleNodeGroup.js group} is checked as the node it looks like — its inputs must be
+ * bound, its ports are typed by what it declares — and not opened. What is inside one was settled
+ * when the group was built, and reporting a problem against a node an author cannot see, in a body
+ * they may not be allowed to edit, would be a diagnostic with nowhere to go. The compiler flattens
+ * the groups away and still refuses what it cannot lower, so nothing goes unchecked; it is only
+ * reported against the effect rather than against a node.
+ */
+/**
+ * The two phases of an effect, one graph each.
+ *
+ * INIT runs once when a particle is spawned, UPDATE once per frame while it lives. Named here
+ * because which of the two a graph is changes what is wrong with it, so it is something
+ * {@link validate_particle_graph} is told rather than something each caller decides for itself.
+ *
+ * @enum {string}
+ */
+export const PARTICLE_GRAPH_PHASE: Readonly<{
+    INIT: "init";
+    UPDATE: "update";
+}>;
+export { PARTICLE_GRAPH_ERROR, PARTICLE_GRAPH_WARNING } from "./particle_graph_diagnostic.js";
+//# sourceMappingURL=validate_particle_graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate_particle_graph.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/validate_particle_graph.js"],"names":[],"mappings":"AAsDA;;;;;;;;GAQG;AACH;IAN0E,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAEnC,KAAK,GAAtB,MAAM;IAEJ,yBAAyB,CAqDrC;;;;;;;;mCAnES,MAAM;AAtChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;GAQG;AACH;;;GAGG"}