@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -145,6 +145,12 @@ export const PARTICLE_NODE_PRESENTATION = Object.freeze({
         icon: "M6 5v14 M18 5v14 M6 12h12",
         help: "held between a low and a high bound",
     },
+    saturate: {
+        // `clamp`'s two walls, drawn where its bounds actually are: at 0 and at 1.
+        label: "Saturate",
+        icon: "M6 5v14 M18 5v14 M6 18h12 M6 18l12-12 M6 6h12",
+        help: "held between 0 and 1",
+    },
     smoothstep: {
         label: "Smooth Step",
         icon: "M4 18C8 18 8 6 12 6s4 12 8 12",
@@ -202,6 +208,35 @@ export const PARTICLE_NODE_PRESENTATION = Object.freeze({
         icon: "M4 4v16h16 M7 19c1-9 5-12 11-13",
         help: "the natural logarithm",
     },
+    rsqrt: {
+        // The radical under a fraction bar: one over what `sqrt` draws.
+        label: "Inverse Square Root",
+        icon: "M6 6h12 M5 14h2.5l2.5 5 4-11h5",
+        help: "one over the square root",
+    },
+    tan: {
+        // Steep at both ends and shallow through the middle, which is the curve between two poles.
+        label: "Tangent",
+        icon: "M6 20c2-4 3-6 6-8s4-4 6-8",
+        help: "the tangent, in radians",
+    },
+    asin: {
+        // The sine wave on its side: an inverse is its function reflected about the diagonal.
+        label: "Arcsine",
+        icon: "M12 4c-7 2.5-7 5.5 0 8s7 5.5 0 8",
+        help: "the angle whose sine this is, in radians",
+    },
+    acos: {
+        label: "Arccosine",
+        icon: "M7 4c0 4 10 4 10 8s-10 4-10 8",
+        help: "the angle whose cosine this is, in radians",
+    },
+    atan2: {
+        // A ray from the origin with the angle it makes marked off against the axis.
+        label: "Arctangent",
+        icon: "M5 19h13 M5 19L16 8 M11 19a6 6 0 0 0 -1.8 -4.2",
+        help: "the angle of the point (x, y), in radians",
+    },
 
     // --- vector ---
     normalize: {
@@ -265,11 +300,32 @@ export const PARTICLE_NODE_PRESENTATION = Object.freeze({
         help: "b where the condition is positive, a elsewhere",
     },
 
-    // --- curves ---
+    // --- ramps ---
+    // Two ways to have a curve, and the labels say which is which. The table one came first and was
+    // called just "Curve"; it is renamed here rather than leaving the new one to explain itself,
+    // because "the one that samples the host's table" is the surprising half of the pair and the
+    // one an author has to have decided to want.
     curve: {
-        label: "Curve",
+        label: "Curve Table",
         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",
+        help: "sample a row of the host's animation-curve table at t",
+    },
+    curveLiteral: {
+        // the same curve with its keys on it: this one is the curve rather than a handle to one
+        label: "Curve",
+        icon: `M4 19C10 19 8 5 20 5 ${dot(4, 19, 1.8)} ${dot(12, 12, 1.8)} ${dot(20, 5, 1.8)}`,
+        help: "a curve of your own, written into the program: t in, its value out",
+    },
+    gradientRGBA: {
+        // a strip with its stops underneath, which is what the control is
+        label: "RGBA Gradient",
+        icon: `M4 5h16v8H4z M4 9h16 ${dot(6, 18, 1.8)} ${dot(12, 18, 1.8)} ${dot(18, 18, 1.8)}`,
+        help: "a colour gradient looked up at t, with alpha",
+    },
+    gradientRGB: {
+        label: "RGB Gradient",
+        icon: `M4 5h16v8H4z ${dot(6, 18, 1.8)} ${dot(12, 18, 1.8)} ${dot(18, 18, 1.8)}`,
+        help: "a colour gradient looked up at t, no alpha",
     },
 });
 

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

@@ -0,0 +1,230 @@
+/**
+ * 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(): ParticleCurveParameter;
+/**
+ * A fresh black-to-white gradient: what a gradient node starts as.
+ *
+ * @returns {ParticleGradientStop[]}
+ */
+export function particle_gradient_default(): ParticleGradientStop[];
+/**
+ * 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: any): boolean;
+/**
+ * Whether a value is a gradient parameter this can lower.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function is_particle_gradient(value: any): boolean;
+/**
+ * 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: ParticleCurveParameter): ParticleCurveKey[];
+/**
+ * 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: ParticleCurveParameter): AnimationCurve;
+/**
+ * A curve parameter holding what this {@link AnimationCurve} holds.
+ *
+ * @param {AnimationCurve} curve
+ * @returns {ParticleCurveParameter}
+ */
+export function particle_curve_from_animation(curve: AnimationCurve): ParticleCurveParameter;
+/**
+ * A gradient's stops in position order, each with its colour copied.
+ *
+ * @param {ParticleGradientStop[]} value
+ * @returns {ParticleGradientStop[]}
+ */
+export function particle_gradient_stops(value: ParticleGradientStop[]): ParticleGradientStop[];
+/**
+ * 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: ParticleGradientStop[], t: number): number[];
+/**
+ * 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: import("./ParticleGroupBuilder.js").ParticleGroupBuilder, t: any, value: ParticleCurveParameter): any;
+/**
+ * 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: import("./ParticleGroupBuilder.js").ParticleGroupBuilder, t: any, value: ParticleGradientStop[], components: number): any;
+/**
+ * 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: number;
+/**
+ * One key of a curve, as it is stored in a node's parameters — the shape {@link AnimationCurve }
+ * writes and reads.
+ */
+export type ParticleCurveKey = {
+    time: number;
+    value: number;
+    inTangent: number;
+    outTangent: number;
+};
+/**
+ * A curve, as a node parameter holds one.
+ */
+export type ParticleCurveParameter = {
+    keys: ParticleCurveKey[];
+};
+/**
+ * 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.
+ */
+export type ParticleGradientStop = {
+    position: number;
+    color: number[];
+};
+import { AnimationCurve } from "../../../../engine/animation/curve/AnimationCurve.js";
+//# sourceMappingURL=particle_ramp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_ramp.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_ramp.js"],"names":[],"mappings":"AA2FA;;;;;;;;GAQG;AACH,0CAFa,sBAAsB,CASlC;AAED;;;;GAIG;AACH,6CAFa,oBAAoB,EAAE,CAOlC;AAUD;;;;;;;;;GASG;AACH,+CAFa,OAAO,CAanB;AAED;;;;;GAKG;AACH,kDAFa,OAAO,CAanB;AAED;;;;;;;;;GASG;AACH,2CAHW,sBAAsB,GACpB,gBAAgB,EAAE,CAI9B;AAED;;;;;;GAMG;AACH,gDAHW,sBAAsB,GACpB,cAAc,CAQ1B;AAED;;;;;GAKG;AACH,qDAHW,cAAc,GACZ,sBAAsB,CAWlC;AAED;;;;;GAKG;AACH,+CAHW,oBAAoB,EAAE,GACpB,oBAAoB,EAAE,CAMlC;AAED;;;;;;;GAOG;AACH,gDAJW,oBAAoB,EAAE,KACtB,MAAM,GACJ,MAAM,EAAE,CAsBpB;AA8BD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,2CALW,OAAO,2BAA2B,EAAE,oBAAoB,iBAExD,sBAAsB,OA+ChC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,8CANW,OAAO,2BAA2B,EAAE,oBAAoB,iBAExD,oBAAoB,EAAE,cACtB,MAAM,OA8BhB;AA/YD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;;;;;;;;;GASG;AAEH;;;;GAIG;AAEH;;;;;;GAMG;AAEH;;;GAGG;AACH,iDAFU,MAAM,CAEoC;;;;;;UAxBtC,MAAM;WACN,MAAM;eACN,MAAM;gBACN,MAAM;;;;;qCAMP;IAAC,IAAI,EAAE,gBAAgB,EAAE,CAAA;CAAC;;;;;;mCAQ1B;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAC;+BAlFjB,sDAAsD"}