@woosh/meep-engine 3.11.1 → 3.11.2

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

@@ -1,7 +1,10 @@
+import package_json from "../../../../package.json";
 import Quaternion from "../../../core/geom/Quaternion.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
 import { MIE_PARTICLES_STANDARD_PRECOMPUTED } from "../../../core/math/physics/mie/MIE_PARTICLES_STANDARD_PRECOMPUTED.js";
+import { GPUProfileLevel } from "../../device/timing/profile/GPUProfileLevel.js";
+import { GPUProfileSession } from "../../device/timing/profile/GPUProfileSession.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";
@@ -143,6 +146,32 @@ const VIEWS = [
         position: { x: -36.56903863396318, y: 19.1017887067011, z: 13.881382214134083 },
         rotation: { x: -0.0961072760435774, y: 0.9036695806244697, z: -0.3054532939528032, w: -0.28432897453277794 }
     },
+    {
+        id: 'fog_box_0',
+        label: 'Beside the fog box',
+        c: 'Q-04',
+        hint: 'the sun crosses three units of medium here — where sixteen march steps read +58',
+        position: { x: -49.64917207609583, y: 3.9195318273572317, z: -4.211048766762115 },
+        rotation: {
+            x: -0.037898077937503966,
+            y: 0.6176094542736352,
+            z: 0.029816629610983452,
+            w: 0.7850052651282708
+        }
+    },
+    {
+        id: 'fog_box_1',
+        label: 'Beside the fog box, deeper',
+        c: 'Q-04',
+        hint: 'the same medium a little further in; +70 for the march, and where the volume strobed',
+        position: { x: -50.28590468756837, y: 4.239170044321892, z: -3.9966900541348767 },
+        rotation: {
+            x: -0.03789807793750395,
+            y: 0.6176094542736352,
+            z: 0.02981662961098345,
+            w: 0.7850052651282708
+        }
+    },
     {
         id: 'inside_out',
         label: 'Under the island',
@@ -317,6 +346,72 @@ function aim_light(light, azimuth_degrees, elevation_degrees) {
     light.updateMatrices();
 }
 
+/**
+ * How much each profile capture records. `WORKLOAD` is the highest of the three levels the proposal
+ * calls shippable: pass spans, the frame graph, and dispatch/draw counts.
+ *
+ * Measured on this page it runs ~11 KB a frame over ~393 spans, so ~660 KB/s at 60 Hz — the
+ * proposal's estimate of 6 KB assumed ~200 passes and this graph is about twice that. Still small
+ * enough that a hand-driven recording will not notice. `VERBOSE` above it adds bind group contents
+ * at roughly seven times the rate and wants a frame limit set, not a key you can lean on.
+ *
+ * @type {number}
+ */
+const PROFILE_LEVEL = GPUProfileLevel.WORKLOAD;
+
+/**
+ * Hand an ArrayBuffer to the browser as a file.
+ *
+ * @param {ArrayBuffer} bytes
+ * @param {string} filename
+ */
+function download_bytes(bytes, filename) {
+    const url = URL.createObjectURL(new Blob([bytes], { type: 'application/octet-stream' }));
+
+    const anchor = document.createElement('a');
+
+    anchor.href = url;
+    anchor.download = filename;
+
+    document.body.appendChild(anchor);
+    anchor.click();
+    anchor.remove();
+
+    // Revoking in the same task cancels the download in some browsers — the click only schedules it.
+    setTimeout(() => URL.revokeObjectURL(url), 60000);
+}
+
+/**
+ * `YYYYMMDD-HHMMSS` in local time, matching the naming the other `.sgpt` captures on this machine
+ * already use — same sort order, and it reads as the clock you took it by rather than as UTC.
+ *
+ * @returns {string}
+ */
+function file_timestamp() {
+    const now = new Date();
+
+    const pad = value => String(value).padStart(2, '0');
+
+    return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`
+        + `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function format_bytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    }
+
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+
 export async function start() {
 
     const element = id => document.getElementById(id);
@@ -407,8 +502,17 @@ export async function start() {
 
     const views_element = element('views');
 
+    /**
+     * Which placement the camera was last sent to, for the profile capture's note — a capture that
+     * cannot say where it was taken is much less use a week later.
+     * @type {object|null}
+     */
+    let current_view = null;
+
     /** @param {object} view */
     function go_to(view) {
+        current_view = view;
+
         camera.transform.fromJSON({ position: view.position, rotation: view.rotation });
 
         // the controller holds its own spherical state and would otherwise snap the camera back on
@@ -559,6 +663,200 @@ export async function start() {
         repaint();
     });
 
+    // -- profiling: T starts a recording, T again stops it and downloads the capture
+
+    const profile_status = element('profile_status');
+
+    /**
+     * The recording in progress, or null.
+     *
+     * The engine never constructs one of these — `Renderer.profile_session` is a nullable field and
+     * the null checks around it are the entire integration, which is what keeps the profiler out of
+     * a bundle that does not ask for it. The two imports at the top of this file are the whole
+     * opt-in.
+     *
+     * @type {GPUProfileSession|null}
+     */
+    let profile_session = null;
+
+    /** Guards against T being leaned on while a stop is still draining. */
+    let profile_busy = false;
+
+    function set_profile_status(text, recording = false) {
+        profile_status.textContent = text;
+        profile_status.className = recording ? 'recording' : '';
+    }
+
+    function start_profile() {
+        const device = renderer.device;
+
+        const settings = [
+            current_view === null ? 'free camera' : current_view.label,
+            `fov ${Math.round(camera.fov / DEG_TO_RAD)}°`,
+            `volumetric TAA ${(globalThis.__VOL_TAA_ENABLED ?? true) ? 'on' : 'off'}`,
+            `${renderer.pixel_ratio.toFixed(2)}x`,
+        ];
+
+        const session = new GPUProfileSession({
+            level: PROFILE_LEVEL,
+            note: `volumetrics_froxel — ${settings.join(' · ')}`,
+        });
+
+        // Populate before start(): the meta record is written into the stream there and not read
+        // again. Without it the capture is unreadable in the sense that matters — a pass taking
+        // 0.4 ms says nothing until you know which GPU and at what resolution.
+        const meta = session.meta;
+
+        // `GPUDevice.adapterInfo` is recent enough that a browser running this page may not have it,
+        // and several browsers withhold the fields even when they do. Empty is what the format
+        // expects in that case.
+        const info = device.adapterInfo;
+
+        if (info !== undefined && info !== null) {
+            meta.adapter_vendor = info.vendor ?? "";
+            meta.adapter_architecture = info.architecture ?? "";
+            meta.adapter_device = info.device ?? "";
+            meta.adapter_description = info.description ?? "";
+        }
+
+        meta.features = [...device.features];
+        meta.engine_version = package_json.version;
+
+        session.onBytesWritten.add(bytes => {
+            set_profile_status(
+                `● recording — ${session.frames_recorded} frames, ${format_bytes(bytes)}  ·  T to stop`,
+                true
+            );
+        });
+
+        renderer.profile_session = session;
+        session.start();
+
+        profile_session = session;
+
+        // The timers go quiet without this rather than failing, so the capture still carries the
+        // frame graph and the workload — it just has no durations in it. Worth knowing before you
+        // record for a minute and then look.
+        const timed = device.features.has('timestamp-query');
+
+        set_profile_status(
+            timed
+                ? '● recording — 0 frames  ·  T to stop'
+                : '● recording without timestamp-query — structure only, no durations  ·  T to stop',
+            true
+        );
+    }
+
+    /**
+     * Wait for frames already submitted to finish landing in the session.
+     *
+     * A frame is committed when its timestamp readback resolves — a `mapAsync` a frame or two behind
+     * submit, see `ShadeGPUCommandContext.profiling_absorbed` — and `record_frame` silently ignores
+     * anything arriving after `stop()`. Stopping the instant the key goes down therefore discards
+     * the last few frames, which are the ones you were most likely looking at.
+     *
+     * Drains the queue, then waits for the frame count to stop moving. Capped, because a recording
+     * taken while the page is paused never moves at all.
+     *
+     * @param {GPUProfileSession} session
+     */
+    async function drain_profile(session) {
+        const DEADLINE_MS = 1000;
+        const QUIET_MS = 60;
+
+        await renderer.device.queue.onSubmittedWorkDone();
+
+        const deadline = performance.now() + DEADLINE_MS;
+
+        let previous = session.frames_recorded;
+
+        while (performance.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, QUIET_MS));
+
+            if (session.frames_recorded === previous) {
+                return;
+            }
+
+            previous = session.frames_recorded;
+        }
+    }
+
+    async function stop_profile() {
+        const session = profile_session;
+
+        profile_session = null;
+
+        // Detach first, so nothing encoded during the drain below joins the recording. Frames
+        // already encoded are unaffected: Renderer captures the session into a local before it
+        // subscribes to the readback.
+        renderer.profile_session = null;
+
+        set_profile_status('stopping — draining in-flight frames…');
+
+        await drain_profile(session);
+
+        const bytes = session.stop();
+
+        const filename = `volumetrics_froxel-${file_timestamp()}.sgpt`;
+
+        download_bytes(bytes, filename);
+
+        // Also to the console, because the status line is the only other place the name appears and
+        // a browser that declines the save says nothing about which capture it declined.
+        console.log(
+            `profile: ${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}, `
+            + `${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'} -> ${filename}`
+        );
+
+        set_profile_status(
+            `${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}`
+            + `, ${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'}`
+            + `  ·  ${filename}`
+        );
+    }
+
+    window.addEventListener('keydown', event => {
+        if (event.ctrlKey || event.metaKey || event.altKey || event.repeat) {
+            return;
+        }
+
+        // `key` first, because it is the letter actually printed on the key the user pressed —
+        // `code` is physical position, so on AZERTY it names the key where T sits on QWERTY. `code`
+        // is the fallback for layouts whose `key` is not Latin at all (Cyrillic gives "е" here).
+        if (event.key.toLowerCase() !== 't' && event.code !== 'KeyT') {
+            return;
+        }
+
+        // the panel's sliders and buttons are focusable; do not steal a key from a field
+        const target = event.target;
+
+        if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) {
+            return;
+        }
+
+        if (profile_busy) {
+            return;
+        }
+
+        event.preventDefault();
+
+        profile_busy = true;
+
+        const done = profile_session === null
+            ? Promise.resolve(start_profile())
+            : stop_profile();
+
+        done.catch(error => {
+            set_profile_status(`profiling failed: ${error?.message ?? error}`);
+            console.error(error);
+
+            profile_session = null;
+            renderer.profile_session = null;
+        }).finally(() => {
+            profile_busy = false;
+        });
+    });
+
     element('pause').addEventListener('click', () => {
         paused = !paused;
         element('pause').textContent = paused ? 'Resume' : 'Pause';

package/src/shade/playground/volumetrics_froxel/measure.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The measurement protocol from this page's README, as code.
+ *
+ * Not imported by the page — it is loaded from the console when there is something to measure:
+ *
+ * ```js
+ * const m = await (await import('./measure.js')).attach();
+ * await m.ab(v => globalThis.__VOL_TAA_ENABLED = v, false, true);
+ * ```
+ *
+ * It exists because every trap the README lists is a trap about *procedure*, and a procedure
+ * written down in prose gets followed differently each time. Three of them are structural and are
+ * dealt with here rather than left to the operator:
+ *
+ *  - **The canvas cannot be read back.** A canvas texture is configured by the presentation path,
+ *    cannot carry `COPY_SRC`, and is rotated away the moment the frame is presented — a `drawImage`
+ *    off it a task later returns an empty bitmap, and a comparison of two blanks reports perfect
+ *    agreement. Everything here renders into a texture this module owns, via
+ *    `Renderer.render_to_target`, which shares the view context (and therefore all the temporal
+ *    history) with the canvas path.
+ *
+ *  - **Presentation throttling.** Whole-frame timing off the page's own loop is paced by the swap
+ *    chain, which is why the README says two settings that plainly differ can report the same
+ *    number. Driving the frames from here removes the swap chain from the measurement entirely.
+ *
+ *  - **The noise floor has to pay the same costs the signal does.** `ab` takes the floor by making
+ *    an identical no-op change and settling exactly as the real change does, and it interleaves the
+ *    two sides so drift lands on both.
+ *
+ * The camera-path helpers exist for a narrower reason: a structure that is fitted to the camera can
+ * be perfectly correct standing still and swim under motion, and the froxel volume then goes
+ * through a 0.95-blend temporal filter that turns swimming into either ghosting or flicker. Neither
+ * is visible in a still. `fly` drives a pose sequence one frame at a time and records what the
+ * image does while it happens.
+ */
+/**
+ * @param {object} [context] defaults to the globals the page publishes
+ * @param {Renderer} [context.renderer]
+ * @param {Scene} [context.scene]
+ * @param {PerspectiveCamera} [context.camera]
+ * @param {OrbitalCameraController} [context.controller]
+ */
+export function attach({ renderer, scene, camera, controller, }?: {
+    renderer?: Renderer;
+    scene?: Scene;
+    camera?: PerspectiveCamera;
+    controller?: OrbitalCameraController;
+}): Promise<{
+    renderer: Renderer;
+    scene: Scene;
+    camera: PerspectiveCamera;
+    controller: OrbitalCameraController;
+    device: any;
+    readonly capture: ({ settle: settle_frames, average }?: {
+        settle?: number;
+        average?: number;
+    }) => Promise<Float32Array>;
+    make_target: () => any;
+    target: () => any;
+    frame: (time_delta_s?: number) => void;
+    settle: (n: any) => Promise<void>;
+    accumulate_luminance: (out: Float32Array) => Promise<void>;
+    compare: (a: any, b: any) => {
+        signed_mean: number;
+        mean_abs: number;
+        max_abs: number;
+        mean_a: number;
+        mean_b: number;
+    };
+    mean: (values: any) => number;
+    ab: (apply: any, a: any, b: any, options?: {}) => Promise<{
+        floor: {
+            signed_mean: number;
+            mean_abs: number;
+            max_abs: number;
+            mean_a: number;
+            mean_b: number;
+        }[];
+        signal: {
+            signed_mean: number;
+            mean_abs: number;
+            max_abs: number;
+            mean_a: number;
+            mean_b: number;
+        }[];
+    }>;
+    read_pose: () => {
+        position: any[];
+        rotation: any[];
+    };
+    write_pose: (pose: any) => void;
+    interpolate: (from: any, to: any, t: any) => {
+        position: any;
+        rotation: any;
+    };
+    fly: (to: any, { frames, hold }?: {
+        frames?: number;
+        hold?: number;
+    }) => Promise<number[]>;
+    series_stats: (series: any) => {
+        frames: any;
+        mean: number;
+        flicker: number;
+        max_step: number;
+        drift: number;
+    };
+    converge_at: (pose: any, options?: {}) => Promise<Float32Array>;
+    time: ({ frames }?: {
+        frames?: number;
+    }) => Promise<number>;
+    profile: ({ frames, settle: settle_frames }?: {
+        frames?: number;
+        settle?: number;
+    }) => Promise<{
+        [x: string]: number;
+    }>;
+    set_pixel_ratio: (ratio: any) => void;
+}>;
+//# sourceMappingURL=measure.d.ts.map

package/src/shade/playground/volumetrics_froxel/measure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/volumetrics_froxel/measure.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;GAMG;AACH;IAL8B,QAAQ;IACX,KAAK;IACO,MAAM;IACA,UAAU;;;;;;;;;;UAuLtC,QAAQ,YAAY,CAAC;;;;;gCA5DvB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA4MV,QAAQ,MAAM,EAAE,CAAC;;;;;;;;;;;;;QAsGF,MAAM,GAAvB,MAAM;QACW,MAAM,GAAvB,MAAM;UACJ;YAAe,MAAM,GAAE,MAAM;MAAE;;GAsF/C"}