@woosh/meep-engine 3.3.0 → 3.4.0

package/src/shade/playground/FramePerformanceMonitor.js

@@ -1,468 +0,0 @@
-import { assert } from "../../core/assert.js";
-import { RingBuffer } from "../../core/collection/RingBuffer.js";
-import { computeStatisticalMean } from "../../core/math/statistics/computeStatisticalMean.js";
-import { computeStatisticalMedian } from "../../core/math/statistics/computeStatisticalMedian.js";
-import {
-    computeStatisticalPercentile
-} from "../../core/math/statistics/computeStatisticalPercentile.js";
-import {
-    computeStatisticalStandardDeviation
-} from "../../core/math/statistics/computeStatisticalStandardDeviation.js";
-
-/**
- * Overlay lines that can be drawn on top of the per-frame trace.
- * @enum {string}
- */
-export const FrameOverlayMode = Object.freeze({
-    NONE: 'none',
-    MEDIAN: 'median',
-    P10: 'p10',     // worst 10% (a.k.a. "10% lows")
-    P5: 'p5',       // worst 5%  (a.k.a. "5% lows")
-    P1: 'p1',       // worst 1%  (a.k.a. "1% lows")
-});
-
-const OVERLAY_LABELS = {
-    [FrameOverlayMode.NONE]: 'off',
-    [FrameOverlayMode.MEDIAN]: 'median',
-    [FrameOverlayMode.P10]: '10% low',
-    [FrameOverlayMode.P5]: '5% low',
-    [FrameOverlayMode.P1]: '1% low',
-};
-
-const OVERLAY_CYCLE = [
-    FrameOverlayMode.NONE,
-    FrameOverlayMode.MEDIAN,
-    FrameOverlayMode.P10,
-    FrameOverlayMode.P5,
-    FrameOverlayMode.P1,
-];
-
-/**
- * Tracks per-frame submission timestamps and reports pacing statistics over a
- * rolling window. Renders a Stats.js-style canvas with the per-frame trace,
- * an auto-scaled millisecond grid, and a selectable percentile/median overlay.
- *
- * The y-axis is auto-scaled to the maximum sample in the window (with 10%
- * headroom), so the visible graph "height" tracks the data.
- *
- * Usage:
- *   const monitor = new FramePerformanceMonitor();
- *   document.body.appendChild(monitor.dom);
- *   // each frame:
- *   monitor.record(performance.now() * 1e-3);
- */
-export class FramePerformanceMonitor {
-
-    /**
-     * Rolling window of frame deltas, in seconds.
-     * @type {RingBuffer<number>}
-     */
-    #buffer;
-
-    /**
-     *
-     * @param {number} count
-     * @returns {number[]}
-     */
-    dump_last(count) {
-        const result = [];
-
-        let n = Math.min(count, this.#buffer.count);
-
-        for (let i = n - 1; i >= 0; i--) {
-            result.push(this.#buffer.getFromHead(i));
-        }
-
-        return result;
-    }
-
-    /**
-     * Reusable scratch array for copying ring-buffer contents into a flat list
-     * for the statistics utilities.
-     * @type {number[]}
-     */
-    #scratch = [];
-
-
-    /** @type {HTMLCanvasElement} */
-    #canvas;
-
-    /** @type {CanvasRenderingContext2D} */
-    #ctx;
-
-    /** @type {number} logical (CSS) width */
-    #width;
-
-    /** @type {number} logical (CSS) height */
-    #height;
-
-    /**
-     * Currently displayed overlay line. Public — assign directly to change.
-     * Use a value from {@link FrameOverlayMode}.
-     * @type {string}
-     */
-    overlay_mode = FrameOverlayMode.MEDIAN;
-
-    /**
-     * @param {object} [options]
-     * @param {number} [options.analysis_frame_count] number of frames in the rolling window (default 512)
-     * @param {number} [options.width] canvas width in CSS pixels (default 240)
-     * @param {number} [options.height] canvas height in CSS pixels (default 110)
-     */
-    constructor({ analysis_frame_count = 512, width = 640, height = 200 } = {}) {
-        assert.isNonNegativeInteger(analysis_frame_count, 'analysis_frame_count');
-        assert.greaterThan(analysis_frame_count, 0, 'analysis_frame_count');
-
-        this.#buffer = new RingBuffer(analysis_frame_count);
-
-        this.#width = width;
-        this.#height = height;
-
-        const dpr = (typeof window !== 'undefined' && window.devicePixelRatio) || 1;
-
-        const canvas = document.createElement('canvas');
-        canvas.width = Math.round(width * dpr);
-        canvas.height = Math.round(height * dpr);
-        canvas.style.cssText = [
-            `width: ${width}px`,
-            `height: ${height}px`,
-            'background: #0d0d12',
-            'border: 1px solid #2a2a35',
-            'border-radius: 4px',
-            "font-family: 'JetBrains Mono', Consolas, monospace",
-            'cursor: pointer',
-            'user-select: none',
-            'display: block',
-        ].join('; ');
-
-        canvas.title = 'Frame Performance Monitor — click to cycle overlay (median / 10% low / 5% low / 1% low / off)';
-        canvas.addEventListener('click', () => this.cycle_overlay());
-
-        this.#ctx = canvas.getContext('2d');
-        // Draw in logical (CSS) coordinates; scale once for HiDPI.
-        this.#ctx.scale(dpr, dpr);
-
-        this.#canvas = canvas;
-
-        this.#render();
-    }
-
-    /**
-     * The HTML element to insert into the page. Mirrors stats.js convention.
-     * @returns {HTMLCanvasElement}
-     */
-    get dom() {
-        return this.#canvas;
-    }
-
-    /**
-     * Number of frame samples kept in the rolling window.
-     * @returns {number}
-     */
-    get analysis_frame_count() {
-        return this.#buffer.size;
-    }
-
-    /**
-     * @param {number} v
-     */
-    set analysis_frame_count(v) {
-        assert.isNonNegativeInteger(v, 'analysis_frame_count');
-        assert.greaterThan(v, 0, 'analysis_frame_count');
-
-        this.#buffer.resize(v);
-        this.#render();
-    }
-
-    /**
-     * Number of frames currently recorded (≤ analysis_frame_count).
-     * @returns {number}
-     */
-    get sample_count() {
-        return this.#buffer.count;
-    }
-
-    /**
-     * Record a frame submission timestamp.
-     * Successive calls produce frame deltas that feed the analysis window.
-     *
-     * @param {number} time_delta_s
-     */
-    record(time_delta_s) {
-        assert.isNumber(time_delta_s, 'time_delta_s');
-
-        // Guard against NaN and clock-backwards readings — keep the new
-        // baseline so the next delta is valid.
-        if (!Number.isFinite(time_delta_s) || time_delta_s < 0) {
-            return;
-        }
-
-        this.#buffer.push(time_delta_s);
-        this.#render();
-    }
-
-    /**
-     * Discard all recorded samples.
-     */
-    reset() {
-        this.#buffer.clear();
-        this.#render();
-    }
-
-    /**
-     * Cycle the overlay mode: off → median → 10% low → 5% low → 1% low → off …
-     */
-    cycle_overlay() {
-        const idx = OVERLAY_CYCLE.indexOf(this.overlay_mode);
-        this.overlay_mode = OVERLAY_CYCLE[(idx + 1) % OVERLAY_CYCLE.length];
-        this.#render();
-    }
-
-    // ── Stats getters (all values in seconds) ─────────────────────────────
-
-    /** @returns {number} */
-    get mean() {
-        const samples = this.#collect();
-        if (samples.length === 0) return 0;
-        return computeStatisticalMean(samples);
-    }
-
-    /**
-     * Population standard deviation across the window.
-     * @returns {number}
-     */
-    get standard_deviation() {
-        const samples = this.#collect();
-        if (samples.length === 0) return 0;
-        return computeStatisticalStandardDeviation(samples);
-    }
-
-    /** @returns {number} */
-    get median() {
-        const samples = this.#collect();
-        if (samples.length === 0) return 0;
-        return computeStatisticalMedian(samples);
-    }
-
-    /**
-     * "1% low" — median delta of the worst 1% of frames.
-     * @returns {number}
-     */
-    get low_1_percent() {
-        return this.#low_percentile(0.01);
-    }
-
-    /**
-     * "5% low" — median delta of the worst 5% of frames.
-     * @returns {number}
-     */
-    get low_5_percent() {
-        return this.#low_percentile(0.05);
-    }
-
-    /**
-     * "10% low" — median delta of the worst 10% of frames.
-     * @returns {number}
-     */
-    get low_10_percent() {
-        return this.#low_percentile(0.10);
-    }
-
-    /**
-     * @param {number} fraction 0..1 — top-fraction of slowest frames to summarise
-     * @returns {number}
-     */
-    #low_percentile(fraction) {
-        const samples = this.#collect();
-        if (samples.length < 2) return 0;
-        return computeStatisticalPercentile(samples, 1 - fraction, 1);
-    }
-
-    /**
-     * Copy the ring buffer into a flat array (reusing scratch).
-     * The returned array must not be retained — it is reused across calls.
-     * @returns {number[]}
-     */
-    #collect() {
-        const buffer = this.#buffer;
-        const count = buffer.count;
-        const scratch = this.#scratch;
-
-        scratch.length = count;
-
-        let i = 0;
-        buffer.forEach((v) => {
-            scratch[i++] = v;
-        });
-
-        return scratch;
-    }
-
-    // ── Rendering ─────────────────────────────────────────────────────────
-
-    #render() {
-        const ctx = this.#ctx;
-        const w = this.#width;
-        const h = this.#height;
-
-        ctx.fillStyle = '#0d0d12';
-        ctx.fillRect(0, 0, w, h);
-
-        const samples = this.#collect();
-
-        const header_h = 14;
-        const label_w = 32;
-        const graph_top = header_h;
-        const graph_left = label_w;
-        const graph_h = h - header_h - 2;
-        const graph_w = w - label_w - 2;
-
-        if (samples.length < 2) {
-            ctx.fillStyle = 'rgba(255,255,255,0.55)';
-            ctx.font = '10px monospace';
-            ctx.textBaseline = 'top';
-            ctx.fillText('frame perf · waiting for samples…', 4, 2);
-            return;
-        }
-
-        // Auto-scale y axis to the peak sample, with 10% headroom.
-        let max_s = 0;
-        for (let i = 0; i < samples.length; i++) {
-            const v = samples[i];
-            if (v > max_s) max_s = v;
-        }
-        if (max_s <= 0) max_s = 1 / 60;
-
-        const y_max_s = max_s * 1.1;
-        const y_max_ms = y_max_s * 1000;
-
-        // Y grid + labels.
-        const ticks = nice_ticks(y_max_ms, 4);
-        ctx.strokeStyle = 'rgba(255,255,255,0.06)';
-        ctx.fillStyle = 'rgba(255,255,255,0.4)';
-        ctx.font = '9px monospace';
-        ctx.textBaseline = 'middle';
-        ctx.lineWidth = 1;
-        for (const ms of ticks) {
-            const ratio = ms / y_max_ms;
-            const y = graph_top + graph_h - ratio * graph_h;
-
-            ctx.beginPath();
-            // +0.5 for crisp 1px lines.
-            ctx.moveTo(graph_left, y + 0.5);
-            ctx.lineTo(graph_left + graph_w, y + 0.5);
-            ctx.stroke();
-
-            ctx.fillText(format_ms_tick(ms), 2, y);
-        }
-
-        // Per-frame trace.
-        ctx.beginPath();
-        ctx.strokeStyle = '#7fc1ff';
-        ctx.lineWidth = 1;
-
-        const N = samples.length;
-        const x_step = N > 1 ? graph_w / (N - 1) : 0;
-
-        for (let i = 0; i < N; i++) {
-            const x = graph_left + i * x_step;
-            const y = graph_top + graph_h - (samples[i] / y_max_s) * graph_h;
-
-            if (i === 0) ctx.moveTo(x, y);
-            else ctx.lineTo(x, y);
-        }
-        ctx.stroke();
-
-        // Overlay line.
-        const overlay_value_s = this.#overlay_value();
-        if (overlay_value_s > 0 && overlay_value_s <= y_max_s) {
-            const y = graph_top + graph_h - (overlay_value_s / y_max_s) * graph_h;
-
-            ctx.beginPath();
-            ctx.strokeStyle = '#ffaa55';
-            ctx.lineWidth = 1;
-            ctx.setLineDash([4, 3]);
-            ctx.moveTo(graph_left, y + 0.5);
-            ctx.lineTo(graph_left + graph_w, y + 0.5);
-            ctx.stroke();
-            ctx.setLineDash([]);
-
-            ctx.fillStyle = '#ffaa55';
-            ctx.textBaseline = 'bottom';
-            const label = `${OVERLAY_LABELS[this.overlay_mode]} ${(overlay_value_s * 1000).toFixed(2)}ms`;
-            const label_y = Math.max(graph_top + 8, y - 1);
-            ctx.fillText(label, graph_left + 2, label_y);
-        }
-
-        // Header.
-        const mean_s = computeStatisticalMean(samples);
-        const sd_s = computeStatisticalStandardDeviation(samples);
-        const fps = mean_s > 0 ? 1 / mean_s : 0;
-
-        const header = `${(mean_s * 1000).toFixed(2)}ms σ${(sd_s * 1000).toFixed(2)} ${fps.toFixed(0)}fps · ${OVERLAY_LABELS[this.overlay_mode]}`;
-
-        ctx.fillStyle = 'rgba(255,255,255,0.85)';
-        ctx.font = '10px monospace';
-        ctx.textBaseline = 'top';
-        ctx.fillText(header, 4, 2);
-    }
-
-    /**
-     * @returns {number} -1 if no overlay should be drawn
-     */
-    #overlay_value() {
-        switch (this.overlay_mode) {
-            case FrameOverlayMode.MEDIAN:
-                return this.median;
-            case FrameOverlayMode.P10:
-                return this.low_10_percent;
-            case FrameOverlayMode.P5:
-                return this.low_5_percent;
-            case FrameOverlayMode.P1:
-                return this.low_1_percent;
-            default:
-                return -1;
-        }
-    }
-}
-
-/**
- * Pick "nice" tick values for an axis ranging from 0 to `max`.
- * Returns an ascending list of values (excluding 0).
- *
- * @param {number} max
- * @param {number} target_count desired number of ticks
- * @returns {number[]}
- */
-function nice_ticks(max, target_count) {
-    if (max <= 0) return [];
-    const raw_step = max / target_count;
-    const exp = Math.floor(Math.log10(raw_step));
-    const base = Math.pow(10, exp);
-    const fraction = raw_step / base;
-
-    let nice;
-    if (fraction < 1.5) nice = 1;
-    else if (fraction < 3) nice = 2;
-    else if (fraction < 7) nice = 5;
-    else nice = 10;
-
-    const step = nice * base;
-
-    const ticks = [];
-    for (let v = step; v <= max; v += step) {
-        ticks.push(v);
-    }
-    return ticks;
-}
-
-/**
- * @param {number} ms
- * @returns {string}
- */
-function format_ms_tick(ms) {
-    if (ms >= 100) return ms.toFixed(0);
-    if (ms >= 10) return ms.toFixed(1);
-    if (ms >= 1) return ms.toFixed(1);
-    return ms.toFixed(2);
-}

package/src/shade/playground/add_random_lights.d.ts

@@ -1,8 +0,0 @@
-/**
- * Debug method
- * @param {Scene} scene
- * @param {number} count
- * @param normalize
- */
-export function add_random_lights(scene: Scene, count?: number, normalize?: boolean): void;
-//# sourceMappingURL=add_random_lights.d.ts.map

package/src/shade/playground/add_random_lights.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"add_random_lights.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/add_random_lights.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,wDAHW,MAAM,6BAyChB"}

package/src/shade/playground/add_random_lights.js

@@ -1,50 +0,0 @@
-import Vector3 from "../../core/geom/Vector3.js";
-import { randomFloatBetween } from "../../core/math/random/randomFloatBetween.js";
-import { seededRandom } from "../../core/math/random/seededRandom.js";
-import { PointLight } from "../renderer/light/model/PointLight.js";
-
-/**
- * Debug method
- * @param {Scene} scene
- * @param {number} count
- * @param normalize
- */
-export function add_random_lights(scene, count = 10000, normalize = true) {
-
-    const random = seededRandom();
-
-    const bounds = scene.instances.bounding_box;
-
-    const bounds_size = 1;
-
-    for (let i = 0; i < count; i++) {
-
-        const light = new PointLight();
-
-        let radius = bounds_size;
-
-        if (normalize) {
-            radius /= Math.sqrt(count);
-        }
-
-        light.radius = radius * 0.02;
-
-        light.position = new Vector3(
-            randomFloatBetween(random, bounds.x0, bounds.x1),
-            randomFloatBetween(random, bounds.y0, bounds.y1),
-            randomFloatBetween(random, bounds.z0, bounds.z1),
-        );
-
-        light.updateMatrices();
-
-        light.distance = radius;
-
-        light.casts_shadow = false;
-
-        light.color.setHSV(randomFloatBetween(random, 0, 1), 1, 1);
-
-        scene.lights.add(light);
-
-    }
-
-}

package/src/shade/playground/animation_prototype.d.ts

@@ -1,24 +0,0 @@
-/**
- * Build the animation prototype scene: a cube simultaneously bobbing up and
- * down, spinning around a tilted axis, and shifting through the rainbow,
- * above a flat plane and lit by a directional sun. Animation runs entirely
- * on the GPU; the only per-frame CPU work is to advance the clip's `time`.
- *
- * Two separate playbacks drive two separate tracks (one scalar Y, one
- * 4-channel quaternion) with different periods, exercising:
- *  - per-binding playback indirection (each binding picks its own `time`),
- *  - simultaneous evaluation of multiple curves on a single instance,
- *  - the `MeshRotation` apply path that writes a quaternion into the mesh
- *    transform's rotation 3×3.
- *
- * @param {object} args
- * @param {Renderer} args.renderer
- * @param {Scene} args.scene
- * @param {OrbitalCameraController} args.controller
- */
-export function animation_prototype({ renderer, scene, controller }: {
-    renderer: Renderer;
-    scene: Scene;
-    controller: OrbitalCameraController;
-}): void;
-//# sourceMappingURL=animation_prototype.d.ts.map

package/src/shade/playground/animation_prototype.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"animation_prototype.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/animation_prototype.js"],"names":[],"mappings":"AA6IA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAJ0B,QAAQ;IACX,KAAK;IACa,UAAU;SA8VlD"}