@woosh/meep-engine 3.15.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

@@ -0,0 +1,72 @@
+/**
+ * @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}.
+ *
+ * ## 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
+ * 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_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

@@ -0,0 +1 @@
+{"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"}