@woosh/meep-engine 3.15.0 → 3.17.0

package/editor/view/particles/effect/ParticleCurveEditorView.js

@@ -0,0 +1,574 @@
+import { AnimationCurve } from "../../../../src/engine/animation/curve/AnimationCurve.js";
+import { Keyframe } from "../../../../src/engine/animation/curve/Keyframe.js";
+import { clamp01 } from "../../../../src/core/math/clamp01.js";
+import {
+    particle_curve_animation,
+    particle_curve_from_animation,
+} from "../../../../src/shade/renderer/particles/graph/particle_ramp.js";
+import View from "../../../../src/view/View.js";
+
+/**
+ * A curve, edited in the unit square: `t` across, the value up, and the keys that make it draggable.
+ *
+ * Drag a key to move it. Click where there is no key and one is added there, with tangents that
+ * leave the curve looking like it did — so adding a key is somewhere to make an edit *from* rather
+ * than an edit in itself. Middle-click a key, or press the remove button, and it goes. The picker
+ * below sets the selected key's tangents, which is what shapes the curve on either side of it.
+ *
+ * ## It is an AnimationCurve
+ *
+ * Not a lookalike. The model here is the engine's own {@link AnimationCurve}, the curve is drawn by
+ * asking it what it is at each pixel, and what the node stores is that class's own JSON. So the
+ * picture is the engine's evaluation rather than a second opinion about it, and a curve authored
+ * here means the same thing anywhere else a curve is wanted.
+ *
+ * The compiled program is a third thing again — the curve written out as VM arithmetic, see
+ * {@link ../../../../src/shade/renderer/particles/graph/particle_ramp.js} — and its agreeing with
+ * this one is what `particle_ramp.spec.js` checks.
+ *
+ * ## The unit square
+ *
+ * Drawn from 0 to 1 on both axes, and keys are held inside it, because that is what the node is for:
+ * `t` normalised in, a factor out. A curve that wants to go to eleven is that curve times eleven,
+ * which is a `mul` node and is visible in the graph — where a value of eleven hidden inside a
+ * control would not be.
+ *
+ * ## When an edit is committed
+ *
+ * On pointer up, for the reason set out in {@link ./ParticleGradientEditorView.js}: a key dragged
+ * across the square is one thing to undo, not the hundred pointer events it was made of.
+ */
+
+/** @type {number} */
+const WIDTH = 208;
+
+/** @type {number} */
+const HEIGHT = 84;
+
+/** Room around the plot, so a key at 0 or 1 is drawn whole rather than clipped in half. */
+const MARGIN = 7;
+
+/** How near a key a press has to be to take hold of it rather than make a new one. */
+const GRAB_RADIUS = 8;
+
+/**
+ * What the tangent picker offers. Each is a way of deciding a key's two tangents, and between them
+ * they cover what anybody actually wants from a curve of this size.
+ * @type {Object<string, string>}
+ */
+const TANGENT_MODES = Object.freeze({
+    Smooth: "smooth",
+    Linear: "linear",
+    Flat: "flat",
+});
+
+export class ParticleCurveEditorView extends View {
+    /**
+     * The curve being edited — a working copy, drawn continuously and committed on release.
+     * @type {AnimationCurve}
+     */
+    #curve = new AnimationCurve();
+
+    /** @type {HTMLCanvasElement} */
+    #canvas;
+
+    /** @type {CanvasRenderingContext2D|null} */
+    #context = null;
+
+    /** @type {number} */
+    #selected = 0;
+
+    /** @type {boolean} */
+    #dragging = false;
+
+    /** @type {function():object} */
+    #read;
+
+    /** @type {function(object):void} */
+    #commit;
+
+    /**
+     * Which rule each key's tangents came from, by key.
+     *
+     * A curve is keys and tangents and nothing else — that is the format the rest of the engine
+     * reads, and putting a mode in it would be inventing one nobody else understands. So the mode is
+     * *read off* the numbers when a curve arrives ({@link #modeOf}) and remembered here for as long
+     * as it is being edited.
+     *
+     * Remembered rather than re-derived, because re-deriving it is exactly wrong at the one moment it
+     * is wanted: moving a key changes the slope to its neighbours, so a key that was linear stops
+     * looking linear the instant it needs re-deriving, and asking the curve after the move would
+     * answer "smooth" every time.
+     *
+     * @type {WeakMap<import("../../../../src/engine/animation/curve/Keyframe.js").Keyframe, string>}
+     */
+    #modes = new WeakMap();
+
+    /** @type {HTMLSelectElement} */
+    #tangents;
+
+    /**
+     * @param {object} options
+     * @param {function():object} options.read the parameter's current value
+     * @param {function(object):void} options.write commit a new value
+     */
+    constructor({ read, write }) {
+        super();
+
+        this.#read = read;
+        this.#commit = write;
+
+        this.el = document.createElement('div');
+
+        this.addClass('ui-particle-curve');
+
+        const canvas = this.#canvas = document.createElement('canvas');
+
+        canvas.width = WIDTH;
+        canvas.height = HEIGHT;
+        canvas.classList.add('plot');
+
+        this.el.appendChild(canvas);
+
+        const fields = document.createElement('div');
+
+        fields.classList.add('key-fields');
+
+        this.el.appendChild(fields);
+
+        const tangents = this.#tangents = document.createElement('select');
+
+        tangents.classList.add('ui-particle-parameter-select', 'tangents');
+        tangents.title = "How the selected key's tangents are decided";
+
+        for (const [label, mode] of Object.entries(TANGENT_MODES)) {
+            const option = document.createElement('option');
+
+            option.value = mode;
+            option.textContent = label;
+
+            tangents.appendChild(option);
+        }
+
+        fields.appendChild(tangents);
+
+        const remove = document.createElement('button');
+
+        remove.type = 'button';
+        remove.classList.add('remove');
+        remove.textContent = '−';
+        remove.title = "Remove the selected key (or middle-click it)";
+
+        fields.appendChild(remove);
+
+        canvas.addEventListener('pointerdown', event => this.#press(event));
+        canvas.addEventListener('pointermove', event => this.#move(event));
+        canvas.addEventListener('pointerup', event => this.#release(event));
+        canvas.addEventListener('pointercancel', event => this.#release(event));
+
+        tangents.addEventListener('change', () => {
+            const key = this.#curve.keys[this.#selected];
+
+            if (key === undefined) {
+                return;
+            }
+
+            this.#modes.set(key, tangents.value);
+            this.#applyTangents(this.#selected, tangents.value);
+
+            this.#commit(particle_curve_from_animation(this.#curve));
+            this.render();
+        });
+
+        remove.addEventListener('click', () => this.#removeSelected());
+
+        this.on.linked.add(() => {
+            if (this.#context === null) {
+                this.#context = canvas.getContext('2d');
+            }
+
+            this.refresh();
+        });
+
+        this.refresh();
+    }
+
+    /**
+     * Re-read the parameter and redraw.
+     */
+    refresh() {
+        const value = this.#read();
+
+        this.#curve = particle_curve_animation(
+            value !== null && typeof value === "object" && Array.isArray(value.keys) ? value : { keys: [] }
+        );
+
+        this.#selected = Math.min(this.#selected, Math.max(0, this.#curve.keys.length - 1));
+
+        // read off the numbers now, while they still say what rule made them
+        this.#curve.keys.forEach((key, index) => this.#modes.set(key, this.#modeOf(index)));
+
+        this.#writeFields();
+        this.render();
+    }
+
+    /**
+     * @param {PointerEvent} event
+     * @returns {{time: number, value: number}} where in the unit square the pointer is
+     */
+    #pointOf(event) {
+        const rect = this.#canvas.getBoundingClientRect();
+
+        const scale = rect.width / WIDTH;
+
+        const x = (event.clientX - rect.left) / scale - MARGIN;
+        const y = (event.clientY - rect.top) / (rect.height / HEIGHT) - MARGIN;
+
+        return {
+            time: clamp01(x / (WIDTH - MARGIN * 2)),
+            // the plot runs upward and the canvas runs downward
+            value: clamp01(1 - y / (HEIGHT - MARGIN * 2)),
+        };
+    }
+
+    /**
+     * @param {number} time
+     * @param {number} value
+     * @returns {{x: number, y: number}} the point in canvas pixels
+     */
+    #plot(time, value) {
+        return {
+            x: MARGIN + clamp01(time) * (WIDTH - MARGIN * 2),
+            y: MARGIN + (1 - clamp01(value)) * (HEIGHT - MARGIN * 2),
+        };
+    }
+
+    /**
+     * @param {PointerEvent} event
+     * @returns {number} the index of the key under the pointer, or -1
+     */
+    #keyUnder(event) {
+        const rect = this.#canvas.getBoundingClientRect();
+
+        const scale = rect.width / WIDTH;
+
+        const x = (event.clientX - rect.left) / scale;
+        const y = (event.clientY - rect.top) / (rect.height / HEIGHT);
+
+        let nearest = -1;
+        let distance = Infinity;
+
+        this.#curve.keys.forEach((key, index) => {
+            const point = this.#plot(key.time, key.value);
+
+            const away = Math.hypot(point.x - x, point.y - y);
+
+            if (away <= GRAB_RADIUS && away < distance) {
+                nearest = index;
+                distance = away;
+            }
+        });
+
+        return nearest;
+    }
+
+    /**
+     * @param {PointerEvent} event
+     */
+    #press(event) {
+        const key = this.#keyUnder(event);
+
+        if (event.button === 1) {
+            if (key !== -1) {
+                this.#selected = key;
+                this.#removeSelected();
+            }
+
+            event.preventDefault();
+            return;
+        }
+
+        if (event.button !== 0) {
+            return;
+        }
+
+        if (key !== -1) {
+            this.#selected = key;
+        } else {
+            const { time } = this.#pointOf(event);
+
+            // On the curve where it already is, with tangents that keep it looking the same, so the
+            // click is somewhere to edit from rather than an edit.
+            this.#selected = this.#curve.add(Keyframe.from(time, this.#curve.evaluate(time)));
+
+            this.#modes.set(this.#curve.keys[this.#selected], TANGENT_MODES.Smooth);
+            this.#applyTangents(this.#selected, TANGENT_MODES.Smooth);
+
+            this.#commit(particle_curve_from_animation(this.#curve));
+        }
+
+        this.#dragging = true;
+
+        if (typeof this.#canvas.setPointerCapture === "function") {
+            this.#canvas.setPointerCapture(event.pointerId);
+        }
+
+        this.#writeFields();
+        this.render();
+    }
+
+    /**
+     * @param {PointerEvent} event
+     */
+    #move(event) {
+        if (!this.#dragging) {
+            return;
+        }
+
+        const key = this.#curve.keys[this.#selected];
+
+        if (key === undefined) {
+            return;
+        }
+
+        const { time, value } = this.#pointOf(event);
+
+        key.time = time;
+        key.value = value;
+
+        // The curve keeps its keys in time order and this one may have crossed a neighbour. Sorting
+        // by hand rather than removing and re-adding, so that the key object — and the selection
+        // pointing at it — survive the move.
+        this.#selected = resort(this.#curve.keys, this.#selected);
+
+        this.render();
+    }
+
+    /**
+     * @param {PointerEvent} event
+     */
+    #release(event) {
+        if (!this.#dragging) {
+            return;
+        }
+
+        this.#dragging = false;
+
+        if (typeof this.#canvas.releasePointerCapture === "function" && this.#canvas.hasPointerCapture?.(event.pointerId)) {
+            this.#canvas.releasePointerCapture(event.pointerId);
+        }
+
+        // A key that moved changed the slope on both sides of it, so whichever rule its neighbours
+        // were following has to be applied again — otherwise a "Linear" segment stops being straight
+        // the moment either of its ends is dragged.
+        this.#reapplyAround(this.#selected);
+
+        this.#commit(particle_curve_from_animation(this.#curve));
+
+        this.#writeFields();
+        this.render();
+    }
+
+    #removeSelected() {
+        // A curve with one key is a constant, which is a thing to be; a curve with none is nothing,
+        // and evaluates to zero whatever it is asked. The last key stays.
+        if (this.#curve.keys.length <= 1) {
+            return;
+        }
+
+        this.#curve.keys.splice(this.#selected, 1);
+
+        this.#selected = Math.min(this.#selected, this.#curve.keys.length - 1);
+
+        this.#reapplyAround(this.#selected);
+
+        this.#commit(particle_curve_from_animation(this.#curve));
+        this.#writeFields();
+        this.render();
+    }
+
+    /**
+     * Re-derive the tangents of a key and its neighbours from the rule each of them was following.
+     *
+     * Both Linear and Smooth are claims about where the neighbours are, so moving a key falsifies
+     * them on all three; Flat is a claim about nothing and re-applying it changes no number. The
+     * rules come from {@link #modes} rather than from the curve, for the reason set out there.
+     *
+     * @param {number} index
+     */
+    #reapplyAround(index) {
+        for (const neighbour of [index - 1, index, index + 1]) {
+            const key = this.#curve.keys[neighbour];
+
+            if (key !== undefined) {
+                this.#applyTangents(neighbour, this.#modes.get(key) ?? TANGENT_MODES.Smooth);
+            }
+        }
+    }
+
+    /**
+     * @param {number} index
+     * @param {string} mode a {@link TANGENT_MODES}
+     */
+    #applyTangents(index, mode) {
+        const keys = this.#curve.keys;
+
+        const key = keys[index];
+
+        if (key === undefined) {
+            return;
+        }
+
+        if (mode === TANGENT_MODES.Flat) {
+            key.inTangent = 0;
+            key.outTangent = 0;
+            return;
+        }
+
+        if (mode === TANGENT_MODES.Linear) {
+            // each side takes the slope to its own neighbour, which is what makes the segment on
+            // that side a straight line
+            this.#curve.alignTangents(index);
+            return;
+        }
+
+        // Smooth: one slope for both sides, taken across the key rather than up to it — the
+        // Catmull-Rom tangent, which is what makes a curve pass through its keys without a corner
+        // at any of them.
+        const previous = keys[index - 1] ?? key;
+        const next = keys[index + 1] ?? key;
+
+        const span = next.time - previous.time;
+
+        const slope = span === 0 ? 0 : (next.value - previous.value) / span;
+
+        key.inTangent = slope;
+        key.outTangent = slope;
+    }
+
+    /**
+     * Which rule a key's tangents look like they came from. There is nowhere to *store* the answer —
+     * a curve is keys and tangents, and adding a mode to it would be inventing a format the rest of
+     * the engine does not read — so it is recovered from the numbers, which is exact for the two
+     * cases that matter and falls back to Smooth.
+     *
+     * @param {number} index
+     * @returns {string} a {@link TANGENT_MODES}
+     */
+    #modeOf(index) {
+        const key = this.#curve.keys[index];
+
+        if (key === undefined) {
+            return TANGENT_MODES.Smooth;
+        }
+
+        if (key.inTangent === 0 && key.outTangent === 0) {
+            return TANGENT_MODES.Flat;
+        }
+
+        const linear = new AnimationCurve();
+
+        linear.keys = this.#curve.keys.map(other => other.clone());
+        linear.alignTangents(index);
+
+        return linear.keys[index].inTangent === key.inTangent && linear.keys[index].outTangent === key.outTangent
+            ? TANGENT_MODES.Linear
+            : TANGENT_MODES.Smooth;
+    }
+
+    #writeFields() {
+        const key = this.#curve.keys[this.#selected];
+
+        this.#tangents.value = (key === undefined ? undefined : this.#modes.get(key)) ?? TANGENT_MODES.Smooth;
+    }
+
+    render() {
+        const context = this.#context;
+
+        if (context === null) {
+            return;
+        }
+
+        const canvas = this.#canvas;
+
+        context.clearRect(0, 0, canvas.width, canvas.height);
+
+        context.fillStyle = '#171b21';
+        context.fillRect(0, 0, canvas.width, canvas.height);
+
+        // the unit square, so "0" and "1" are somewhere rather than implied
+        context.strokeStyle = '#2c323b';
+        context.lineWidth = 1;
+        context.beginPath();
+
+        for (const fraction of [0, 0.5, 1]) {
+            const horizontal = this.#plot(0, fraction);
+            const vertical = this.#plot(fraction, 0);
+
+            context.moveTo(MARGIN, horizontal.y + 0.5);
+            context.lineTo(WIDTH - MARGIN, horizontal.y + 0.5);
+
+            context.moveTo(vertical.x + 0.5, MARGIN);
+            context.lineTo(vertical.x + 0.5, HEIGHT - MARGIN);
+        }
+
+        context.stroke();
+
+        // The curve itself, asked of the AnimationCurve a pixel at a time — the same evaluation the
+        // rest of the engine does, so what is drawn is what the curve is.
+        context.strokeStyle = '#7fb5ff';
+        context.lineWidth = 1.5;
+        context.beginPath();
+
+        for (let x = MARGIN; x <= WIDTH - MARGIN; x++) {
+            const time = (x - MARGIN) / (WIDTH - MARGIN * 2);
+
+            const point = this.#plot(time, this.#curve.evaluate(time));
+
+            if (x === MARGIN) {
+                context.moveTo(point.x, point.y);
+            } else {
+                context.lineTo(point.x, point.y);
+            }
+        }
+
+        context.stroke();
+
+        this.#curve.keys.forEach((key, index) => {
+            const point = this.#plot(key.time, key.value);
+
+            context.beginPath();
+            context.arc(point.x, point.y, index === this.#selected ? 4 : 3, 0, Math.PI * 2);
+
+            context.fillStyle = index === this.#selected ? '#ffd35c' : '#d6d8da';
+            context.fill();
+
+            context.lineWidth = 1;
+            context.strokeStyle = '#171b21';
+            context.stroke();
+        });
+    }
+}
+
+/**
+ * Move one element of an already-sorted-but-for-it array back into place, and say where it went.
+ *
+ * @param {Array<{time: number}>} keys sorted by time, except possibly at `index`
+ * @param {number} index
+ * @returns {number} where the element is now
+ */
+function resort(keys, index) {
+    let at = index;
+
+    while (at > 0 && keys[at - 1].time > keys[at].time) {
+        [keys[at - 1], keys[at]] = [keys[at], keys[at - 1]];
+        at--;
+    }
+
+    while (at < keys.length - 1 && keys[at + 1].time < keys[at].time) {
+        [keys[at + 1], keys[at]] = [keys[at], keys[at + 1]];
+        at++;
+    }
+
+    return at;
+}

package/editor/view/particles/effect/ParticleEffectEditorView.d.ts

@@ -0,0 +1,61 @@
+export class ParticleEffectEditorView extends View {
+    /**
+     * @param {object} options
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument} options.effect
+     * @param {ActionProcessor} [options.actionProcessor]
+     * @param {number} [options.previewCapacity]
+     */
+    constructor({ effect, actionProcessor, previewCapacity }: {
+        effect: import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument;
+        actionProcessor?: ActionProcessor<any, any>;
+        previewCapacity?: number;
+    });
+    el: HTMLDivElement;
+    /**
+     * @type {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument}
+     */
+    effect: import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument;
+    /**
+     * @type {ActionProcessor}
+     */
+    actionProcessor: ActionProcessor<any, any>;
+    /**
+     * @type {ParticleGraphEditorView}
+     */
+    graphEditor: ParticleGraphEditorView;
+    /**
+     * @type {ParticleCodeEditorView}
+     */
+    codeEditor: ParticleCodeEditorView;
+    /**
+     * @type {ParticlePreviewView}
+     */
+    preview: ParticlePreviewView;
+    /**
+     * @type {ParticleEmitterInspectorView}
+     */
+    inspector: ParticleEmitterInspectorView;
+    /**
+     * Show one authoring layer. Both stay built: the graph keeps its cameras and selections while
+     * the code pane is up, and the code pane keeps its scroll position while the graph is up.
+     *
+     * Which layer is *shown* is not which layer is *authoritative* — that is the document's, and the
+     * code pane's own header says which it is.
+     *
+     * @param {string} id `"graph"` or `"code"`
+     */
+    setLayer(id: string): void;
+    /**
+     * @returns {string}
+     */
+    activeLayer(): string;
+    layout(): void;
+    #private;
+}
+import View from "../../../../src/view/View.js";
+import { ActionProcessor } from "../../../../src/core/process/undo/ActionProcessor.js";
+import { ParticleGraphEditorView } from "./ParticleGraphEditorView.js";
+import { ParticleCodeEditorView } from "./ParticleCodeEditorView.js";
+import { ParticlePreviewView } from "./ParticlePreviewView.js";
+import { ParticleEmitterInspectorView } from "./ParticleEmitterInspectorView.js";
+//# sourceMappingURL=ParticleEffectEditorView.d.ts.map

package/editor/view/particles/effect/ParticleEffectEditorView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleEffectEditorView.d.ts","sourceRoot":"","sources":["../../../../../editor/view/particles/effect/ParticleEffectEditorView.js"],"names":[],"mappings":"AAwCA;IAgBI;;;;;OAKG;IACH;QAJyG,MAAM,EAApG,OAAO,qDAAqD,EAAE,sBAAsB;QAC1D,eAAe;QACxB,eAAe,GAAhC,MAAM;OA6DhB;IAxDG,mBAAuC;IAIvC;;OAEG;IACH,QAFU,OAAO,qDAAqD,EAAE,sBAAsB,CAE1E;IAEpB;;OAEG;IACH,2CAAsC;IAEtC;;OAEG;IACH,aAFU,uBAAuB,CAE0C;IAE3E;;OAEG;IACH,YAFU,sBAAsB,CAEwB;IAExD;;OAEG;IACH,SAFU,mBAAmB,CAEgD;IAE7E;;OAEG;IACH,WAFU,4BAA4B,CAEuB;IA0DjE;;;;;;;;OAQG;IACH,aAFW,MAAM,QAahB;IAED;;OAEG;IACH,eAFa,MAAM,CAIlB;IAED,eAuBC;;CACJ;iBA7MgB,8BAA8B;gCAHf,sDAAsD;wCAM9C,8BAA8B;uCAF/B,6BAA6B;oCAGhC,0BAA0B;6CAFjB,mCAAmC"}