@woosh/meep-engine 3.39.0 → 3.41.0

package/src/shade/playground/vsm/main.js

@@ -0,0 +1,389 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { ShadeIndirectLightingMode } from "../../renderer/ShadeIndirectLightingMode.js";
+import { FrameRateMeter } from "../frame_rate_meter.js";
+import { install_profile_hotkey } from "../profile_hotkey.js";
+import { draw_clipmap_panel } from "./clipmap_panel.js";
+import { aim_sun, create_courtyard, create_crowd } from "./scenes.js";
+import { VSMDebugOverlay, VSMDebugView } from "./VSMDebugOverlay.js";
+
+const element = id => document.getElementById(id);
+
+const RUNNING = 'Running. Drag to orbit, right-drag to pan, wheel to zoom. T records a GPU profile.';
+
+/**
+ * Camera framings, as [from, to].
+ * @type {Object<string, number[][]>}
+ */
+const PRESETS = {
+    near: [[-1.5, 1.7, 6.5], [0.5, 0.9, 1]],
+    overview: [[22, 18, 16], [0, 0, -6]],
+    avenue: [[0, 2.2, -24], [0, 2, -120]],
+    crowd: [[0, 30, 45], [0, 0, 0]],
+};
+
+/**
+ * @param {string} text
+ * @param {boolean} [error]
+ */
+function report(text, error = false) {
+    const status = element('status');
+
+    status.textContent = text;
+    status.className = error ? 'fail' : '';
+}
+
+export async function start() {
+    const canvas = element('view');
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = 0.1;
+    camera.far = 400;
+    camera.fov = 55 * Math.PI / 180;
+
+    const controller = new OrbitalCameraController(camera, canvas);
+
+    /**
+     * Where the camera goes, and the controller with it.
+     *
+     * @param {string} name
+     */
+    const frame_preset = name => {
+        const [from, to] = PRESETS[name];
+
+        controller.look(new Vector3(...from), new Vector3(...to));
+    };
+
+    frame_preset('near');
+
+    const renderer = new Renderer();
+
+    report('Acquiring GPU…');
+
+    await renderer.initialize({ context: canvas.getContext('webgpu'), pixelRatio: 1 });
+
+    renderer.indirect_lighting_mode = ShadeIndirectLightingMode.IBL;
+    renderer.feature_shadows_enabled = true;
+    renderer.feature_virtual_shadow_maps = true;
+    renderer.feature_automatic_exposure_enabled = false;
+    renderer.exposure_compensation = 0.5;
+    renderer.feature_taa_enabled = false;
+    renderer.feature_ssao_enabled = false;
+    renderer.feature_bloom_enabled = false;
+
+    const overlay = new VSMDebugOverlay(renderer.graphics);
+
+    renderer.add_extension(overlay);
+
+    report('Building the courtyard…');
+
+    /**
+     * The scenes built so far, by name; the crowd is built once and resized in place.
+     */
+    const worlds = { courtyard: await create_courtyard(renderer), crowd: null };
+
+    let world = worlds.courtyard;
+
+    let time = 0;
+    let azimuth = 0.6;
+    let stopped = false;
+
+    const meter = new FrameRateMeter();
+
+    /**
+     * The scene on screen, built if it has to be.
+     */
+    async function select_world() {
+        const name = element('scene').value;
+        const size = Number(element('crowd').value);
+
+        if (name === 'crowd') {
+            if (worlds.crowd === null) {
+                report(`Building a crowd of ${size}…`);
+
+                worlds.crowd = await create_crowd(renderer, size);
+            } else {
+                worlds.crowd.resize(size);
+            }
+
+            world = worlds.crowd;
+        } else {
+            world = worlds.courtyard;
+        }
+
+        aim_sun(world.sun, azimuth);
+        renderer.indicate_view_change();
+
+        report(RUNNING);
+    }
+
+    /**
+     * The shadow context of the scene on screen.
+     */
+    function shadow_context() {
+        return renderer.scenes.obtain(world.scene).lights.shadow_context;
+    }
+
+    /**
+     * The scene's virtual map, or null while the sun has cascades.
+     */
+    function virtual_map() {
+        const map = shadow_context().get_map(world.sun);
+
+        return map !== undefined && map.isVirtualShadowMap === true ? map : null;
+    }
+
+    function apply_settings() {
+        renderer.feature_virtual_shadow_maps = element('technique').value === 'vsm';
+        renderer.shadow_virtual_page_budget = element('pause').checked ? 0 : Number(element('budget').value);
+        renderer.shadow_virtual_lod_bias = Number(element('bias').value);
+        renderer.shadow_virtual_first_texel_size = Number(element('texel').value);
+        renderer.feature_taa_enabled = element('taa').checked;
+
+        overlay.mode = Number(element('debug').value);
+        overlay.inset = element('inset').checked;
+
+        element('budget-value').textContent = element('budget').value;
+        element('bias-value').textContent = Number(element('bias').value).toFixed(1);
+        element('crowd-value').textContent = element('crowd').value;
+    }
+
+    for (const id of ['technique', 'budget', 'bias', 'texel', 'debug', 'inset', 'pause', 'taa']) {
+        element(id).addEventListener('input', apply_settings);
+    }
+
+    element('scene').addEventListener('change', () => select_world().catch(error => report(String(error), true)));
+    element('crowd').addEventListener('change', () => select_world().catch(error => report(String(error), true)));
+    element('crowd').addEventListener('input', apply_settings);
+
+    for (const name of Object.keys(PRESETS)) {
+        element(`preset-${name}`).addEventListener('click', () => frame_preset(name));
+    }
+
+    element('nudge').addEventListener('click', () => {
+        azimuth += 0.02;
+        aim_sun(world.sun, azimuth);
+    });
+
+    apply_settings();
+
+    // a reload restores the controls; the scene they name is the one to show
+    await select_world();
+
+    const stats_element = element('stats');
+    const panel = element('clipmap');
+
+    let last_panel = 0;
+
+    function update_readouts(now) {
+        if (now - last_panel < 250) {
+            return;
+        }
+
+        last_panel = now;
+
+        const shadows = shadow_context();
+        const map = virtual_map();
+
+        const lines = [
+            `${meter.fps.toFixed(1)} fps, ${meter.mean_ms.toFixed(2)} ms mean, ${meter.hitches} hitches`,
+        ];
+
+        if (map === null) {
+            lines.push('cascaded shadow maps');
+        } else {
+            const s = map.manager.stats;
+            const slots = map.manager.slots;
+
+            lines.push(
+                `movers in scene: ${world.mover_count}`,
+                `pages: ${slots.used} / ${slots.capacity} resident`,
+                `this frame: ${s.renders} rendered, ${s.backlog} waiting`,
+                `reading: ${s.wants} wanted, ${s.uncovered} uncovered, ${s.requests_dropped} dropped`,
+                `movers: ${s.movers}${s.movers > 4096 ? ' (overflow: all stale)' : ''}`,
+                `stale marked ${s.stale_marked}, re-rendered ${s.re_rendered}`,
+                `installs ${s.installs}, evictions ${s.evictions}, scrolled ${s.scroll_evictions}, refused ${s.refused}`,
+                `invalidations ${s.invalidations}, readings ${s.readings_applied} (${s.readings_dropped} dropped), in flight ${map.readbacks_in_flight}`,
+                `depth range ${map.near.toFixed(0)} … ${map.far.toFixed(0)} m`,
+            );
+
+            if (element('panel-on').checked) {
+                const t = camera.transform;
+
+                draw_clipmap_panel(panel, map, [t.translation_x, t.translation_y, t.translation_z], Number(element('panel-level').value));
+            }
+        }
+
+        lines.push(`shadow views drawn: ${shadows.debug_render_count}`);
+
+        stats_element.textContent = lines.join('\n');
+    }
+
+    function resize() {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+
+        camera.aspect = width / height;
+        renderer.resize(width, height);
+    }
+
+    /**
+     * One frame: movers, sun, camera, render, readouts.
+     *
+     * @param {number} dt seconds, clamped
+     * @param {number} raf_dt seconds, real
+     */
+    function frame(dt, raf_dt) {
+        if (stopped) {
+            return;
+        }
+
+        meter.add(raf_dt);
+
+        if (element('animate').checked) {
+            time += dt;
+        }
+
+        if (element('sweep').checked) {
+            azimuth += dt * Number(element('sweep-speed').value);
+            aim_sun(world.sun, azimuth);
+        }
+
+        world.update(time);
+
+        resize();
+        controller.update();
+
+        // before the render, so the overlay draws this scene's map; a map the render rebuilds is
+        // destroyed, and the overlay skips it for that one frame
+        overlay.map = virtual_map();
+        overlay.shadows = shadow_context();
+
+        renderer.render(camera, world.scene, dt);
+
+        update_readouts(performance.now());
+    }
+
+    let stop_loop = create_frame_loop((dt, raf_dt) => {
+        try {
+            frame(Math.min(dt, 0.1), raf_dt);
+        } catch (error) {
+            stopped = true;
+            stop_loop?.();
+            report(String(error?.stack ?? error), true);
+            console.error(error);
+        }
+    });
+
+    window.addEventListener('pagehide', () => {
+        stopped = true;
+        stop_loop?.();
+        overlay.destroy();
+        renderer.destroy();
+    });
+
+    // back from the back/forward cache, the renderer is gone: start again
+    window.addEventListener('pageshow', event => {
+        if (event.persisted) {
+            location.reload();
+        }
+    });
+
+    install_profile_hotkey({
+        renderer,
+        name: 'vsm',
+        status: element('status'),
+        settings: () => [
+            `technique=${element('technique').value}`,
+            `budget=${element('budget').value}`,
+            `bias=${element('bias').value}`,
+            `texel=${element('texel').value}`,
+            `scene=${element('scene').value}`,
+        ],
+    });
+
+    /**
+     * Run `body` with the movers and the sun held still, so that what it reads back describes one
+     * state of the scene — the readbacks it waits on span frames. Page updates are put back as they
+     * were after, whatever `body` did with them.
+     *
+     * @template T
+     * @param {function(): Promise<T>} body
+     * @returns {Promise<T>}
+     */
+    async function paused(body) {
+        const animate = element('animate').checked;
+        const sweep = element('sweep').checked;
+        const pause = element('pause').checked;
+
+        element('animate').checked = false;
+        element('sweep').checked = false;
+
+        try {
+            return await body();
+        } finally {
+            element('animate').checked = animate;
+            element('sweep').checked = sweep;
+            element('pause').checked = pause;
+
+            apply_settings();
+        }
+    }
+
+    globalThis.vsm_lab = {
+        renderer,
+        camera,
+        controller,
+        overlay,
+        get world() {
+            return world;
+        },
+        map: virtual_map,
+        stats: () => ({ ...virtual_map()?.manager.stats }),
+        frame_preset,
+        /**
+         * Set controls by element id, as a person would: a scene or crowd change rebuilds what it
+         * would rebuild from the panel.
+         *
+         * @param {Object<string, *>} settings control id to value
+         * @returns {Promise<void>} once a scene change is in place
+         */
+        async configure(settings) {
+            for (const [id, value] of Object.entries(settings)) {
+                const control = element(id);
+
+                if (control.type === 'checkbox') {
+                    control.checked = Boolean(value);
+                } else {
+                    control.value = String(value);
+                }
+            }
+
+            apply_settings();
+
+            if ('scene' in settings || 'crowd' in settings) {
+                await select_world();
+            }
+        },
+    };
+
+    globalThis.verify = () => paused(async () => {
+        const { verify_vsm } = await import('./verify_vsm.js');
+
+        return verify_vsm({
+            renderer,
+            map: virtual_map(),
+            scene: world.scene,
+            hold_pages: hold => {
+                element('pause').checked = hold;
+                apply_settings();
+            },
+        });
+    });
+
+    report(RUNNING);
+}

package/src/shade/playground/vsm/scenes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Turn a sun to shine down at a fixed elevation, from an azimuth about the vertical.
+ *
+ * @param {import("../../renderer/light/model/DirectionalLight.js").DirectionalLight} sun
+ * @param {number} azimuth radians
+ */
+export function aim_sun(sun: import("../../renderer/light/model/DirectionalLight.js").DirectionalLight, azimuth: number): void;
+/**
+ * The courtyard: static structure at every scale a clipmap level covers, and casters that move in
+ * every way the mover pass has to see.
+ *
+ * - a fence of 5 cm slats by the camera for the finest levels, pillars and walls a few metres out,
+ *   an overhang on posts, thin poles twenty metres off, and an avenue of pillars reaching two
+ *   hundred metres down the coarser levels;
+ * - movers: boxes orbiting (a translation), a column bobbing (a translation along the light more or
+ *   less), a bar turning about its centre (a rotation that keeps its centre still), and a block that
+ *   blinks in and out of the scene every few seconds (a row appearing and leaving).
+ *
+ * @param {Renderer} renderer
+ */
+export function create_courtyard(renderer: Renderer): Promise<{
+    scene: Scene;
+    sun: import("../../renderer/light/model/DirectionalLight.js").DirectionalLight;
+    mover_count: number;
+    /**
+     * Put every mover where it is at time `t`.
+     *
+     * @param {number} t seconds
+     */
+    update(t: number): void;
+}>;
+/**
+ * The crowd: a field of small boxes wandering, as many as asked for — past the mover list's capacity
+ * if that is the point — to load the stale pass and the page budget. {@link resize} adds walkers to
+ * the same scene or takes them away, which the mover pass sees as rows appearing and leaving.
+ *
+ * @param {Renderer} renderer
+ * @param {number} count
+ */
+export function create_crowd(renderer: Renderer, count: number): Promise<{
+    scene: Scene;
+    sun: import("../../renderer/light/model/DirectionalLight.js").DirectionalLight;
+    resize: (target: number) => void;
+    readonly mover_count: number;
+    /**
+     * @param {number} t seconds
+     */
+    update(t: number): void;
+}>;
+export type Renderer = import("../../renderer/Renderer.js").Renderer;
+import { Scene } from "../../renderer/scene/Scene.js";
+//# sourceMappingURL=scenes.d.ts.map

package/src/shade/playground/vsm/scenes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenes.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vsm/scenes.js"],"names":[],"mappings":"AAwBA;;;;;GAKG;AACH,6BAHW,OAAO,gDAAgD,EAAE,gBAAgB,WACzE,MAAM,QAWhB;AA8DD;;;;;;;;;;;;GAYG;AACH,2CAFW,QAAQ;;;;IAkFX;;;;OAIG;cADQ,MAAM;GA6BxB;AAED;;;;;;;GAOG;AACH,uCAHW,QAAQ,SACR,MAAM;;;qBAwCF,MAAM;;IAgCb;;OAEG;cADQ,MAAM;GAYxB;uBAhTY,OAAO,4BAA4B,EAAE,QAAQ;sBAJpC,+BAA+B"}