@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -0,0 +1,533 @@
+import { EMITTER_BLEND } from "../../../../src/shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
+import View from "../../../../src/view/View.js";
+import { ParticleReferenceSimulation } from "../../../particles/effect/ParticleReferenceSimulation.js";
+
+/**
+ * The effect, running, next to the editors that are changing it.
+ *
+ * The simulation is the reference VM — the same bytecode a device would run, see
+ * {@link ParticleReferenceSimulation}. What this adds is a way to look at it: a turntable camera, a
+ * ground grid to place the particles against, and a painter's-order draw of one soft sprite per
+ * particle in the emitter's blend mode.
+ *
+ * It is a preview, not the renderer. There is no depth buffer, no lighting, no atlas and no
+ * transparency pipeline; a billboard is a radial-gradient disc. What it does show honestly is
+ * everything the *effect* decides — where particles go, how long they live, how big they are, what
+ * colour they are, and how many of them there are at once — which is what an author is editing.
+ *
+ * ## Why it keeps running while the effect is broken
+ *
+ * A graph is invalid for most of the time an author spends wiring it, and a preview that blanked out
+ * every time would be useless exactly when it is needed. So the last program that compiled keeps
+ * running, and the panel says it is doing so. Nothing else changes.
+ */
+
+/** Grid extent either side of the origin, in world units. @type {number} */
+const GRID_EXTENT = 6;
+
+/** Grid spacing, in world units. @type {number} */
+const GRID_STEP = 1;
+
+/** Longest frame the simulation is asked to take, so a stalled tab does not jump the effect. */
+const MAX_STEP_SECONDS = 1 / 20;
+
+/** Turntable limits, radians. */
+const PITCH_LIMIT = Math.PI / 2 - 0.05;
+
+export class ParticlePreviewView extends View {
+    /**
+     * @type {HTMLCanvasElement}
+     */
+    #canvas;
+
+    /**
+     * @type {CanvasRenderingContext2D|null}
+     */
+    #context = null;
+
+    /**
+     * @type {HTMLElement}
+     */
+    #hud;
+
+    /**
+     * @type {number}
+     */
+    #frame_handle = 0;
+
+    /**
+     * @type {number}
+     */
+    #last_frame_time = 0;
+
+    /**
+     * Smoothed frames per second, for the overlay.
+     * @type {number}
+     */
+    #fps = 0;
+
+    /**
+     * The version of the document the simulation was last given an effect from.
+     * @type {number}
+     */
+    #effect_version = -1;
+
+    /**
+     * Whether the effect on screen is the last one that compiled rather than the current document.
+     * @type {boolean}
+     */
+    #stale = false;
+
+    /**
+     * Turntable camera.
+     * @type {{yaw: number, pitch: number, distance: number, height: number}}
+     */
+    #camera = { yaw: 0.6, pitch: 0.35, distance: 9, height: 1.6 };
+
+    /**
+     * Device pixels per CSS pixel, capped — a few thousand soft sprites at 3x cost more than they
+     * show.
+     * @type {number}
+     */
+    #pixel_ratio = 1;
+
+    /**
+     * @param {object} options
+     * @param {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument} options.effect
+     * @param {number} [options.capacity] most particles the preview will hold at once
+     */
+    constructor({ effect, capacity }) {
+        super();
+
+        this.el = document.createElement('div');
+
+        this.addClass('ui-particle-preview');
+
+        /**
+         * @type {import("../../../particles/effect/ParticleEffectDocument.js").ParticleEffectDocument}
+         */
+        this.effect = effect;
+
+        /**
+         * @type {ParticleReferenceSimulation}
+         */
+        this.simulation = new ParticleReferenceSimulation(capacity === undefined ? {} : { capacity });
+
+        /**
+         * Whether the simulation is advancing. Paused, the picture stays and the camera still works.
+         * @type {boolean}
+         */
+        this.running = true;
+
+        this.#canvas = document.createElement('canvas');
+        this.#canvas.classList.add('surface');
+
+        this.el.appendChild(this.#canvas);
+
+        this.#hud = document.createElement('div');
+        this.#hud.classList.add('hud');
+
+        this.el.appendChild(this.#hud);
+
+        this.#installCameraControls();
+
+        this.bindSignal(effect.on.changed, this.syncEffect, this);
+        this.bindSignal(this.size.onChanged, this.layout, this);
+
+        this.on.linked.add(this.#start, this);
+        this.on.unlinked.add(this.#stop, this);
+    }
+
+    /**
+     * Give the simulation the document's current program, if it compiles.
+     *
+     * A document that does not compile leaves the simulation running whatever it had — see the class
+     * comment. `#stale` is what the overlay says so.
+     */
+    syncEffect() {
+        if (this.#effect_version === this.effect.version) {
+            return;
+        }
+
+        this.#effect_version = this.effect.version;
+
+        const { program, layout } = this.effect.compile();
+
+        if (program === null) {
+            this.#stale = true;
+            return;
+        }
+
+        this.#stale = false;
+
+        this.simulation.setEffect({ program, layout, emitter: this.effect.emitter });
+    }
+
+    /**
+     * Drop every particle and start the effect over.
+     */
+    restart() {
+        this.simulation.reset();
+    }
+
+    #start() {
+        this.syncEffect();
+
+        this.#last_frame_time = 0;
+
+        const frame = now => {
+            this.#frame_handle = requestAnimationFrame(frame);
+
+            const dt = this.#last_frame_time === 0
+                ? 1 / 60
+                : Math.min((now - this.#last_frame_time) / 1000, MAX_STEP_SECONDS);
+
+            this.#last_frame_time = now;
+
+            this.step(dt);
+        };
+
+        this.#frame_handle = requestAnimationFrame(frame);
+    }
+
+    #stop() {
+        if (this.#frame_handle !== 0) {
+            cancelAnimationFrame(this.#frame_handle);
+            this.#frame_handle = 0;
+        }
+    }
+
+    /**
+     * Advance and draw one frame. Public so a headless caller — a test, a screenshot script — can
+     * drive the preview without a frame loop.
+     *
+     * @param {number} dt seconds
+     */
+    step(dt) {
+        if (this.running) {
+            this.simulation.step(dt);
+        }
+
+        this.#fps = dt > 0 ? this.#fps * 0.9 + 0.1 / dt : this.#fps;
+
+        this.draw();
+        this.#writeHud();
+    }
+
+    /**
+     * Paint the current state.
+     */
+    draw() {
+        const context = this.#context;
+
+        if (context === null) {
+            return;
+        }
+
+        const width = this.#canvas.width;
+        const height = this.#canvas.height;
+
+        if (width === 0 || height === 0) {
+            return;
+        }
+
+        context.setTransform(1, 0, 0, 1, 0, 0);
+        context.globalCompositeOperation = "source-over";
+        context.globalAlpha = 1;
+        context.fillStyle = "#0a0d12";
+        context.fillRect(0, 0, width, height);
+
+        const view = this.#viewTransform(width, height);
+
+        this.#drawGrid(context, view);
+        this.#drawParticles(context, view);
+    }
+
+    /**
+     * The camera, as everything the projection needs: where it is, which way its axes point, and how
+     * world units become pixels.
+     *
+     * @param {number} width device pixels
+     * @param {number} height device pixels
+     * @returns {object}
+     */
+    #viewTransform(width, height) {
+        const { yaw, pitch, distance, height: target_height } = this.#camera;
+
+        const cos_pitch = Math.cos(pitch);
+        const sin_pitch = Math.sin(pitch);
+        const cos_yaw = Math.cos(yaw);
+        const sin_yaw = Math.sin(yaw);
+
+        // forward runs from the camera toward the point it orbits
+        const forward = [-cos_pitch * sin_yaw, -sin_pitch, -cos_pitch * cos_yaw];
+        const right = [cos_yaw, 0, -sin_yaw];
+        const up = [
+            right[1] * forward[2] - right[2] * forward[1],
+            right[2] * forward[0] - right[0] * forward[2],
+            right[0] * forward[1] - right[1] * forward[0],
+        ];
+
+        const eye = [
+            -forward[0] * distance,
+            target_height - forward[1] * distance,
+            -forward[2] * distance,
+        ];
+
+        // one focal length for both axes, so the picture is not stretched by the panel's shape
+        const focal = Math.min(width, height) * 0.9;
+
+        return { eye, forward, right, up, focal, width, height };
+    }
+
+    /**
+     * Project a world point.
+     *
+     * @param {object} view
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number[]} out `[screen x, screen y, view depth]`
+     * @returns {boolean} whether the point is in front of the camera
+     */
+    #project(view, x, y, z, out) {
+        const dx = x - view.eye[0];
+        const dy = y - view.eye[1];
+        const dz = z - view.eye[2];
+
+        const depth = dx * view.forward[0] + dy * view.forward[1] + dz * view.forward[2];
+
+        if (depth <= 0.05) {
+            return false;
+        }
+
+        const sx = dx * view.right[0] + dy * view.right[1] + dz * view.right[2];
+        const sy = dx * view.up[0] + dy * view.up[1] + dz * view.up[2];
+
+        out[0] = view.width / 2 + (sx / depth) * view.focal;
+        out[1] = view.height / 2 - (sy / depth) * view.focal;
+        out[2] = depth;
+
+        return true;
+    }
+
+    /**
+     * @param {CanvasRenderingContext2D} context
+     * @param {object} view
+     */
+    #drawGrid(context, view) {
+        const a = [0, 0, 0];
+        const b = [0, 0, 0];
+
+        context.lineWidth = Math.max(1, this.#pixel_ratio);
+
+        for (let i = -GRID_EXTENT; i <= GRID_EXTENT; i += GRID_STEP) {
+            const axis = i === 0;
+
+            context.strokeStyle = axis ? "rgba(120, 150, 190, 0.55)" : "rgba(90, 105, 130, 0.22)";
+
+            for (const [from, to] of [
+                [[i, 0, -GRID_EXTENT], [i, 0, GRID_EXTENT]],
+                [[-GRID_EXTENT, 0, i], [GRID_EXTENT, 0, i]],
+            ]) {
+                if (!this.#project(view, from[0], from[1], from[2], a)) {
+                    continue;
+                }
+
+                if (!this.#project(view, to[0], to[1], to[2], b)) {
+                    continue;
+                }
+
+                context.beginPath();
+                context.moveTo(a[0], a[1]);
+                context.lineTo(b[0], b[1]);
+                context.stroke();
+            }
+        }
+    }
+
+    /**
+     * Draw every particle, farthest first.
+     *
+     * Sorting is what makes alpha blending read correctly, and it costs nothing here — the preview
+     * holds a few thousand particles and the sort is over an array of numbers. It is also the one
+     * place this differs in kind from the engine, which resolves order out of a voxel volume rather
+     * than by sorting.
+     *
+     * @param {CanvasRenderingContext2D} context
+     * @param {object} view
+     */
+    #drawParticles(context, view) {
+        /** @type {Array<{x: number, y: number, radius: number, depth: number, r: number, g: number, b: number, a: number}>} */
+        const drawn = [];
+
+        const projected = [0, 0, 0];
+
+        this.simulation.forEachParticle(particle => {
+            if (!this.#project(view, particle.x, particle.y, particle.z, projected)) {
+                return;
+            }
+
+            const radius = Math.max(1, (particle.size * view.focal) / projected[2]);
+
+            // A particle whose size or position has gone non-finite would otherwise take the whole
+            // canvas call down; the effect is broken, and the preview says so by not drawing it.
+            if (!Number.isFinite(projected[0]) || !Number.isFinite(projected[1]) || !Number.isFinite(radius)) {
+                return;
+            }
+
+            drawn.push({
+                x: projected[0],
+                y: projected[1],
+                radius,
+                depth: projected[2],
+                r: particle.r,
+                g: particle.g,
+                b: particle.b,
+                a: particle.a,
+            });
+        });
+
+        drawn.sort((left, right) => right.depth - left.depth);
+
+        const additive = this.effect.emitter.blend === EMITTER_BLEND.ADDITIVE;
+
+        context.globalCompositeOperation = additive ? "lighter" : "source-over";
+
+        for (const particle of drawn) {
+            const alpha = clamp01(particle.a);
+
+            if (alpha <= 0) {
+                continue;
+            }
+
+            const gradient = context.createRadialGradient(
+                particle.x, particle.y, 0,
+                particle.x, particle.y, particle.radius
+            );
+
+            const rgb = `${channel(particle.r)}, ${channel(particle.g)}, ${channel(particle.b)}`;
+
+            gradient.addColorStop(0, `rgba(${rgb}, ${alpha})`);
+            gradient.addColorStop(1, `rgba(${rgb}, 0)`);
+
+            context.fillStyle = gradient;
+
+            context.beginPath();
+            context.arc(particle.x, particle.y, particle.radius, 0, Math.PI * 2);
+            context.fill();
+        }
+
+        context.globalCompositeOperation = "source-over";
+    }
+
+    #writeHud() {
+        const parts = [
+            `${this.simulation.count} alive`,
+            `${this.#fps.toFixed(0)} fps`,
+        ];
+
+        if (!this.running) {
+            parts.push("paused");
+        }
+
+        if (this.#stale) {
+            parts.push("showing the last program that compiled");
+        }
+
+        this.#hud.textContent = parts.join(" · ");
+    }
+
+    /**
+     * Drag to orbit, wheel to dolly.
+     */
+    #installCameraControls() {
+        let dragging = false;
+        let last_x = 0;
+        let last_y = 0;
+
+        this.#canvas.addEventListener('pointerdown', event => {
+            dragging = true;
+            last_x = event.clientX;
+            last_y = event.clientY;
+
+            if (typeof this.#canvas.setPointerCapture === "function") {
+                this.#canvas.setPointerCapture(event.pointerId);
+            }
+        });
+
+        this.#canvas.addEventListener('pointermove', event => {
+            if (!dragging) {
+                return;
+            }
+
+            this.#camera.yaw -= (event.clientX - last_x) * 0.008;
+            this.#camera.pitch = clamp(
+                this.#camera.pitch + (event.clientY - last_y) * 0.008,
+                -PITCH_LIMIT,
+                PITCH_LIMIT
+            );
+
+            last_x = event.clientX;
+            last_y = event.clientY;
+        });
+
+        const release = () => {
+            dragging = false;
+        };
+
+        this.#canvas.addEventListener('pointerup', release);
+        this.#canvas.addEventListener('pointercancel', release);
+
+        this.#canvas.addEventListener('wheel', event => {
+            event.preventDefault();
+
+            this.#camera.distance = clamp(this.#camera.distance * (1 + event.deltaY * 0.001), 1.5, 60);
+        }, { passive: false });
+    }
+
+    layout() {
+        const width = Math.max(0, Math.round(this.size.x));
+        const height = Math.max(0, Math.round(this.size.y));
+
+        this.#pixel_ratio = Math.min(globalThis.devicePixelRatio || 1, 2);
+
+        this.#canvas.style.width = `${width}px`;
+        this.#canvas.style.height = `${height}px`;
+
+        this.#canvas.width = Math.round(width * this.#pixel_ratio);
+        this.#canvas.height = Math.round(height * this.#pixel_ratio);
+
+        if (this.#context === null) {
+            this.#context = this.#canvas.getContext("2d");
+        }
+
+        this.draw();
+    }
+}
+
+/**
+ * @param {number} value
+ * @returns {number} 0..255
+ */
+function channel(value) {
+    return Math.round(clamp01(value) * 255);
+}
+
+/**
+ * @param {number} value
+ * @returns {number}
+ */
+function clamp01(value) {
+    return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0;
+}
+
+/**
+ * @param {number} value
+ * @param {number} low
+ * @param {number} high
+ * @returns {number}
+ */
+function clamp(value, low, high) {
+    return Math.min(high, Math.max(low, value));
+}