@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -0,0 +1,403 @@
+import { AnimationCurve } from "../../../../engine/animation/curve/AnimationCurve.js";
+
+/**
+ * Ramps: a curve and a colour gradient, and the arithmetic either one becomes.
+ *
+ * Both are the same shape of thing — a value that depends on one number `t`, written down as a
+ * handful of points with something interpolated between them — and both are *authored data* rather
+ * than wiring, so neither can be a {@link ./ParticleNodeGroup.js node group}: a group's body is
+ * fixed when the group is built, and a gradient with five stops is different arithmetic from a
+ * gradient with two. They are expanding node types instead (see
+ * {@link ./ParticleNodeDescription.js ParticleNodeDescription#expand}), and this is what they expand
+ * *into*: stock nodes, which is to say VM instructions, with the curve rolled out along them.
+ *
+ * ## Rolled out, not sampled
+ *
+ * There is a `CURVE` opcode, and it is not this. That one samples a row of the animation-curve table
+ * a host uploads, which is the right answer for a curve an author is dragging around at runtime and
+ * the wrong one for a curve that is part of the effect: it costs a table, a row, a handle to keep in
+ * step with it, and a texture fetch. A ramp with four stops rolls out to about twenty instructions
+ * of pure arithmetic, needs nothing from the host, and constant-folds where an author has left a
+ * segment flat.
+ *
+ * ## How a piecewise function becomes straight-line code
+ *
+ * There is no control flow to pick a segment with, so every segment is evaluated and the ones that
+ * do not apply are made to contribute nothing. Each segment gets a weight
+ *
+ *     u = clamp((t - t0) / (t1 - t0), 0, 1)
+ *
+ * which is 0 everywhere before the segment, 1 everywhere after it, and the position within it in
+ * between. Contributions are then written as *differences* and summed:
+ *
+ *     f(t) = v0 + sum over segments of c(u), where c(0) = 0 and c(1) = v1 - v0
+ *
+ * Before a segment, `u` is 0 and it adds nothing. After it, `u` is 1 and it has added exactly the
+ * step from its start value to its end value, so the segments before the one `t` is in telescope to
+ * "the value at the start of this segment" and the ones after it are silent. Only one segment is
+ * ever partway through, and its `c(u)` is the interpolation. The sum is therefore the piecewise
+ * function exactly — not an approximation of it — and it is three or four instructions per segment
+ * with no comparisons and no branches.
+ *
+ * It also gives the endpoint behaviour for free: `t` below the first stop leaves every weight at 0
+ * and the value is the first stop's, and above the last stop every weight is 1. That is what
+ * {@link AnimationCurve#evaluate} does at the ends, so the rollout and the editor's own preview
+ * agree there as well as in the middle.
+ *
+ * ## Why a gradient is not four curves
+ *
+ * A curve is an {@link AnimationCurve} — keys with tangents, the same class the rest of the engine
+ * animates with, so a curve authored here can be moved anywhere a curve is wanted and the editor's
+ * preview is the engine's own evaluation rather than a second opinion about it.
+ *
+ * A gradient is *not* four of those. A colour stop is one position with a colour on it, and that is
+ * the whole reason a gradient is easy to author: drag the stop and the colour moves. Four
+ * independent curves would let the red key drift away from the green one, and the interface the
+ * stops are for — Photoshop's, and everybody else's — could no longer be drawn over the data. So a
+ * gradient keeps a shared position per stop and interpolates linearly, and shares with the curve the
+ * thing actually worth sharing: the weights above, and the sum they go into.
+ */
+
+/**
+ * One key of a curve, as it is stored in a node's parameters — the shape {@link AnimationCurve}
+ * writes and reads.
+ *
+ * @typedef {object} ParticleCurveKey
+ * @property {number} time
+ * @property {number} value
+ * @property {number} inTangent
+ * @property {number} outTangent
+ */
+
+/**
+ * A curve, as a node parameter holds one.
+ *
+ * @typedef {{keys: ParticleCurveKey[]}} ParticleCurveParameter
+ */
+
+/**
+ * One stop of a gradient: where it sits along `t`, and the colour there. The colour is always four
+ * numbers, whatever the node reads of it — an RGB gradient uses the first three — so that a gradient
+ * survives being moved between the two node types with its alpha intact.
+ *
+ * @typedef {{position: number, color: number[]}} ParticleGradientStop
+ */
+
+/**
+ * How many lanes a gradient's colour is written with, whichever node reads it.
+ * @type {number}
+ */
+export const PARTICLE_GRADIENT_COLOR_COMPONENTS = 4;
+
+/**
+ * A fresh straight 0..1 ramp: what a curve node starts as.
+ *
+ * Linear rather than eased, because a curve node's first job is almost always to be *changed*, and a
+ * straight line is the shape whose change is easiest to see. Tangents of 1 are what make it straight
+ * — see {@link roll_out_particle_curve}.
+ *
+ * @returns {ParticleCurveParameter}
+ */
+export function particle_curve_default() {
+    return {
+        keys: [
+            { time: 0, value: 0, inTangent: 1, outTangent: 1 },
+            { time: 1, value: 1, inTangent: 1, outTangent: 1 },
+        ],
+    };
+}
+
+/**
+ * A fresh black-to-white gradient: what a gradient node starts as.
+ *
+ * @returns {ParticleGradientStop[]}
+ */
+export function particle_gradient_default() {
+    return [
+        { position: 0, color: [0, 0, 0, 1] },
+        { position: 1, color: [1, 1, 1, 1] },
+    ];
+}
+
+/**
+ * @param {*} value
+ * @returns {boolean} whether it is a finite number
+ */
+function is_number(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+
+/**
+ * Whether a value is a curve parameter this can lower — every key a record of four finite numbers.
+ *
+ * The validator's question and the editor's, asked in one place so that "a curve" means the same
+ * thing to both. Not a repair: something that fails this is reported against the node rather than
+ * quietly turned into a curve nobody asked for.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function is_particle_curve(value) {
+    if (value === null || typeof value !== "object" || !Array.isArray(value.keys)) {
+        return false;
+    }
+
+    return value.keys.every(key => key !== null
+        && typeof key === "object"
+        && is_number(key.time)
+        && is_number(key.value)
+        && is_number(key.inTangent)
+        && is_number(key.outTangent));
+}
+
+/**
+ * Whether a value is a gradient parameter this can lower.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function is_particle_gradient(value) {
+    if (!Array.isArray(value)) {
+        return false;
+    }
+
+    return value.every(stop => stop !== null
+        && typeof stop === "object"
+        && is_number(stop.position)
+        && Array.isArray(stop.color)
+        && stop.color.length === PARTICLE_GRADIENT_COLOR_COMPONENTS
+        && stop.color.every(is_number));
+}
+
+/**
+ * A curve's keys in time order.
+ *
+ * Sorted here rather than trusted, because a key dragged past its neighbour in the editor is an
+ * ordinary thing to do and the rollout's telescoping sum is only the piecewise function if the
+ * segments are walked in order.
+ *
+ * @param {ParticleCurveParameter} value
+ * @returns {ParticleCurveKey[]}
+ */
+export function particle_curve_keys(value) {
+    return value.keys.slice().sort((a, b) => a.time - b.time);
+}
+
+/**
+ * The same curve as the engine's own {@link AnimationCurve} — what the editor draws and evaluates,
+ * and what a spec checks the rolled-out instructions against.
+ *
+ * @param {ParticleCurveParameter} value
+ * @returns {AnimationCurve}
+ */
+export function particle_curve_animation(value) {
+    const curve = new AnimationCurve();
+
+    curve.fromJSON(value);
+
+    return curve;
+}
+
+/**
+ * A curve parameter holding what this {@link AnimationCurve} holds.
+ *
+ * @param {AnimationCurve} curve
+ * @returns {ParticleCurveParameter}
+ */
+export function particle_curve_from_animation(curve) {
+    return {
+        keys: curve.keys.map(key => ({
+            time: key.time,
+            value: key.value,
+            inTangent: key.inTangent,
+            outTangent: key.outTangent,
+        })),
+    };
+}
+
+/**
+ * A gradient's stops in position order, each with its colour copied.
+ *
+ * @param {ParticleGradientStop[]} value
+ * @returns {ParticleGradientStop[]}
+ */
+export function particle_gradient_stops(value) {
+    return value
+        .map(stop => ({ position: stop.position, color: stop.color.slice() }))
+        .sort((a, b) => a.position - b.position);
+}
+
+/**
+ * What a gradient is at `t`, in JavaScript: the same piecewise-linear function the rollout computes,
+ * for an editor to draw the strip with and for a spec to check the instructions against.
+ *
+ * @param {ParticleGradientStop[]} value
+ * @param {number} t
+ * @returns {number[]} four channels
+ */
+export function particle_gradient_sample(value, t) {
+    const stops = particle_gradient_stops(value);
+
+    if (stops.length === 0) {
+        return new Array(PARTICLE_GRADIENT_COLOR_COMPONENTS).fill(0);
+    }
+
+    let result = stops[0].color.slice();
+
+    for (let i = 1; i < stops.length; i++) {
+        const span = stops[i].position - stops[i - 1].position;
+
+        const u = span > 0
+            ? Math.min(1, Math.max(0, (t - stops[i - 1].position) / span))
+            : (t < stops[i].position ? 0 : 1);
+
+        result = result.map((channel, lane) => channel + (stops[i].color[lane] - stops[i - 1].color[lane]) * u);
+    }
+
+    return result;
+}
+
+/**
+ * One segment's weight: 0 before it, 1 after it, and where along it `t` is in between.
+ *
+ * The divide is done here in JavaScript rather than by the program — `t * (1/span) - t0/span` is one
+ * multiply-add against two literals, where dividing at runtime would be a subtract and a divide
+ * against two more. Both of the literals fold into the constant pool, and the optimizer's constant
+ * inlining puts them in the instruction word itself.
+ *
+ * A segment of zero width is a jump rather than a ramp, and there is no `(t - t0) / 0` that says so.
+ * `step` does: it is 1 from the segment's position onward, which is what the sum needs to carry the
+ * whole of that segment's difference across in one place.
+ *
+ * @param {import("./ParticleGroupBuilder.js").ParticleGroupBuilder} g
+ * @param {*} t the value being looked up
+ * @param {number} start where the segment begins
+ * @param {number} end where it ends
+ * @returns {*} a scalar in `[0, 1]`
+ */
+function segment_weight(g, t, start, end) {
+    const span = end - start;
+
+    if (span <= 0) {
+        return g.step(g.f(end), t);
+    }
+
+    return g.saturate(g.mad(t, g.f(1 / span), g.f(-start / span)));
+}
+
+/**
+ * Roll a curve out into arithmetic: `t` in, the curve's value at `t` out, as a scalar.
+ *
+ * Each segment is a cubic Hermite in its own weight, written in the form the sum wants — `c(0) = 0`
+ * and `c(1)` the step across the segment — which is the standard basis with the leading value
+ * subtracted back off:
+ *
+ *     c(u) = ((A·u + B)·u + C)·u,   A = m0 + m1 - 2Δv,  B = 3Δv - 2m0 - m1,  C = m0
+ *
+ * where `Δv` is the segment's rise and `m0`, `m1` are its tangents scaled by its width — exactly what
+ * {@link ../../../../engine/animation/curve/evaluate_two_key_curve.js} hands
+ * {@link ../../../../core/math/spline/spline3_hermite.js}, so a curve evaluates here to what it
+ * evaluates to anywhere else in the engine. Three multiply-adds, the last of which is also the
+ * accumulation.
+ *
+ * A segment whose tangents are its own slope has `A` and `B` at zero, which is a straight line and
+ * one instruction instead of three. A segment that neither rises nor turns contributes nothing at
+ * all and is not emitted — which is how the flat tail an author leaves on a fade costs nothing.
+ *
+ * @param {import("./ParticleGroupBuilder.js").ParticleGroupBuilder} g
+ * @param {*} t
+ * @param {ParticleCurveParameter} value
+ * @returns {*} a scalar
+ */
+export function roll_out_particle_curve(g, t, value) {
+    const keys = particle_curve_keys(value);
+
+    // An empty curve is zero and a single key is a constant, which is what AnimationCurve evaluates
+    // them to — a node with nothing in it still compiles, and shows what it is worth.
+    if (keys.length === 0) {
+        return g.f(0);
+    }
+
+    let result = g.f(keys[0].value);
+
+    for (let i = 1; i < keys.length; i++) {
+        const k0 = keys[i - 1];
+        const k1 = keys[i];
+
+        const span = k1.time - k0.time;
+
+        // the tangents are per unit of `t`, and the polynomial is in the segment's own 0..1
+        const m0 = k0.outTangent * span;
+        const m1 = k1.inTangent * span;
+
+        const rise = k1.value - k0.value;
+
+        const a = m0 + m1 - 2 * rise;
+        const b = 3 * rise - 2 * m0 - m1;
+        const c = m0;
+
+        if (a === 0 && b === 0 && c === 0) {
+            continue;
+        }
+
+        const u = segment_weight(g, t, k0.time, k1.time);
+
+        if (a === 0 && b === 0) {
+            result = g.mad(u, g.f(c), result);
+            continue;
+        }
+
+        const cubic = g.mad(g.mad(u, g.f(a), g.f(b)), u, g.f(c));
+
+        result = g.mad(cubic, u, result);
+    }
+
+    return result;
+}
+
+/**
+ * Roll a gradient out into arithmetic: `t` in, the colour at `t` out.
+ *
+ * The same sum as the curve's, with a vector where the curve has a number and a straight line where
+ * it has a cubic — a stop's difference times the segment's weight, scaled and added. The weight is
+ * one lane and the difference is three or four, which is what `scale` is for: a vector times a
+ * broadcast scalar, one instruction, no widening.
+ *
+ * A segment between two stops of the same colour adds a zero vector and is not emitted, so the flat
+ * run an author leaves at either end of a gradient is free.
+ *
+ * @param {import("./ParticleGroupBuilder.js").ParticleGroupBuilder} g
+ * @param {*} t
+ * @param {ParticleGradientStop[]} value
+ * @param {number} components how many channels to produce: 3 for an RGB gradient, 4 for RGBA
+ * @returns {*} a vector of `components` lanes
+ */
+export function roll_out_particle_gradient(g, t, value, components) {
+    const stops = particle_gradient_stops(value);
+
+    const channels = stop => stop.color.slice(0, components);
+
+    if (stops.length === 0) {
+        return g.f(...new Array(components).fill(0));
+    }
+
+    let result = g.f(...channels(stops[0]));
+
+    for (let i = 1; i < stops.length; i++) {
+        const from = channels(stops[i - 1]);
+        const to = channels(stops[i]);
+
+        const difference = to.map((channel, lane) => channel - from[lane]);
+
+        if (difference.every(channel => channel === 0)) {
+            continue;
+        }
+
+        const u = segment_weight(g, t, stops[i - 1].position, stops[i].position);
+
+        result = g.add(result, g.scale(g.f(...difference), u));
+    }
+
+    return result;
+}
+

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

@@ -40,6 +40,12 @@ export type PARTICLE_GRAPH_PHASE = string;
  * 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}.
  *
+ * ## What is not a problem
+ *
+ * Only what reaches a sink is compiled, so only what reaches a sink can be wrong. A node no sink
+ * depends on is reported once, as information, and nothing else found against it is reported at
+ * all — see {@link report_unreachable}, which has the last word on every finding here.
+ *
  * ## Groups
  *
  * A {@link ./ParticleNodeGroup.js group} is checked as the node it looks like — its inputs must be
@@ -62,5 +68,5 @@ export const PARTICLE_GRAPH_PHASE: Readonly<{
     INIT: "init";
     UPDATE: "update";
 }>;
-export { PARTICLE_GRAPH_ERROR, PARTICLE_GRAPH_WARNING } from "./particle_graph_diagnostic.js";
+export { PARTICLE_GRAPH_ERROR, PARTICLE_GRAPH_INFO, 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

@@ -1 +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"}
+{"version":3,"file":"validate_particle_graph.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/validate_particle_graph.js"],"names":[],"mappings":"AAqEA;;;;;;;;GAQG;AACH;IAN0E,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAEnC,KAAK,GAAtB,MAAM;IAEJ,yBAAyB,CAoDrC;;;;;;;;mCAlES,MAAM;AA5ChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;GAQG;AACH;;;GAGG"}

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

@@ -2,10 +2,19 @@ import { PortDirection } from "../../../../core/model/node-graph/node/PortDirect
 import { VM_MAX_WIDTH } from "../isa/ParticleVMISA.js";
 import { infer_particle_graph_types } from "./infer_particle_graph_types.js";
 import { is_particle_group_description } from "./ParticleNodeGroup.js";
-import { PARTICLE_GRAPH_ERROR, PARTICLE_GRAPH_WARNING } from "./particle_graph_diagnostic.js";
+import {
+    PARTICLE_GRAPH_ERROR,
+    PARTICLE_GRAPH_INFO,
+    PARTICLE_GRAPH_WARNING,
+} from "./particle_graph_diagnostic.js";
 import { PARTICLE_PARAMETER_KIND, particle_node_parameters } from "./particle_node_parameters.js";
+import { is_particle_curve, is_particle_gradient } from "./particle_ramp.js";
 
-export { PARTICLE_GRAPH_ERROR, PARTICLE_GRAPH_WARNING } from "./particle_graph_diagnostic.js";
+export {
+    PARTICLE_GRAPH_ERROR,
+    PARTICLE_GRAPH_INFO,
+    PARTICLE_GRAPH_WARNING,
+} from "./particle_graph_diagnostic.js";
 
 /**
  * Check a particle graph and say what is wrong with it, per node.
@@ -28,6 +37,12 @@ export { PARTICLE_GRAPH_ERROR, PARTICLE_GRAPH_WARNING } from "./particle_graph_d
  * 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}.
  *
+ * ## What is not a problem
+ *
+ * Only what reaches a sink is compiled, so only what reaches a sink can be wrong. A node no sink
+ * depends on is reported once, as information, and nothing else found against it is reported at
+ * all — see {@link report_unreachable}, which has the last word on every finding here.
+ *
  * ## Groups
  *
  * A {@link ./ParticleNodeGroup.js group} is checked as the node it looks like — its inputs must be
@@ -107,11 +122,10 @@ export function validate_particle_graph(graph, { layout, phase } = {}) {
 
     report_duplicate_writes(sinks, layout, error);
     report_missing_kill(sinks, phase, warning);
-    report_unreachable(graph, nodes, sinks, warning);
     report_cycles(nodes, error);
     report_conversions(graph, layout, diagnostics);
 
-    return diagnostics;
+    return report_unreachable(nodes, sinks, diagnostics);
 }
 
 /**
@@ -223,6 +237,32 @@ function check_parameters(node, description, layout, error) {
                 }
                 break;
 
+            // A curve and a gradient are the only parameters with a shape underneath them, and both
+            // are written out into instructions rather than read at runtime — so a malformed one is
+            // a compile that throws rather than a value that misbehaves, and it is worth catching
+            // here where it can be put on the node.
+            case PARTICLE_PARAMETER_KIND.CURVE:
+                if (!is_particle_curve(value)) {
+                    error(
+                        node.id,
+                        `Parameter '${parameter.name}' must be a curve: `
+                        + "keys of time, value, inTangent and outTangent, all finite numbers."
+                    );
+                }
+                break;
+
+            case PARTICLE_PARAMETER_KIND.GRADIENT:
+                if (!is_particle_gradient(value)) {
+                    error(
+                        node.id,
+                        `Parameter '${parameter.name}' must be a gradient: `
+                        + "stops of a finite position and four finite colour channels."
+                    );
+                } else if (value.length === 0) {
+                    error(node.id, `Parameter '${parameter.name}' has no stops, so it has no colour.`);
+                }
+                break;
+
             default:
                 break;
         }
@@ -351,15 +391,23 @@ function report_conversions(graph, layout, diagnostics) {
 }
 
 /**
- * Nodes no sink depends on are compiled away without a word, which is a confusing thing for an
- * author to watch happen. Saying so is worth a warning and never an error.
+ * Have the last word on the nodes no sink depends on.
+ *
+ * Compilation starts from the sinks, so a node nothing downstream reads is never lowered: it cannot
+ * break the effect and it cannot cost an instruction. Half a graph waiting to be wired up is what
+ * most of authoring looks like, and an editor that called that an error would refuse to compile the
+ * working half over it — so everything found against such a node is dropped, and what is said in
+ * its place is the one thing an author cannot see for themselves: that it is not running.
+ *
+ * The note is {@link PARTICLE_GRAPH_INFO}, which is not a problem with the graph. Findings about the
+ * graph as a whole are left alone, being about no node and so about none of this.
  *
- * @param {NodeGraph} graph
  * @param {NodeInstance[]} nodes
  * @param {NodeInstance[]} sinks
- * @param {function(number, string):void} warning
+ * @param {ParticleGraphDiagnostic[]} diagnostics everything the checks above found
+ * @returns {ParticleGraphDiagnostic[]}
  */
-function report_unreachable(graph, nodes, sinks, warning) {
+function report_unreachable(nodes, sinks, diagnostics) {
     const reached = new Set();
     const stack = sinks.slice();
 
@@ -377,11 +425,19 @@ function report_unreachable(graph, nodes, sinks, warning) {
         }
     }
 
+    const kept = diagnostics.filter(diagnostic => diagnostic.node < 0 || reached.has(diagnostic.node));
+
     for (const node of nodes) {
         if (!reached.has(node.id)) {
-            warning(node.id, "Nothing downstream reads this node, so it is dropped when the graph is compiled.");
+            kept.push({
+                node: node.id,
+                message: "Nothing downstream reads this node, so it is left out when the graph is compiled.",
+                severity: PARTICLE_GRAPH_INFO,
+            });
         }
     }
+
+    return kept;
 }
 
 /**