@woosh/meep-engine 2.168.1 → 2.169.0

package/src/engine/graphics/context/testWebGLContextLoss.js

@@ -0,0 +1,696 @@
+import { Color as ThreeColor, Mesh, MeshStandardMaterial, SphereGeometry, WebGLRenderer } from "three";
+import Vector3 from "../../../core/geom/Vector3.js";
+import Entity from "../../ecs/Entity.js";
+import Renderable from "../../ecs/renderable/Renderable.js";
+import RenderSystem from "../../ecs/renderable/RenderSystem.js";
+import { Transform } from "../../ecs/transform/Transform.js";
+import { EngineHarness } from "../../EngineHarness.js";
+import { configureThreeRenderer } from "../GraphicsEngine.js";
+import { load_and_set_cubemap_v0 } from "../load_and_set_cubemap_v0.js";
+import { WebGLContextState } from "./WebGLContextState.js";
+
+/**
+ * WebGL context loss / restore harness.
+ *
+ * Drives the engine by hand (no rAF, so it works in a hidden tab), forces context loss through
+ * `WEBGL_lose_context`, and compares the framebuffer before and after restore. Read the report from
+ * the console or from `window.__context_loss_report`.
+ *
+ * Scenarios:
+ *  - `window.__context_loss_test.run()`        single loss/restore cycle with a full pixel A/B
+ *  - `window.__context_loss_test.repeat(n)`    n cycles, watching `renderer.info.memory` for leaks
+ *
+ * The scene is deliberately static (no water, no behaviours) so that two consecutive frames are
+ * pixel-identical; the noise floor between two pre-loss captures is reported so the post-restore
+ * difference is interpretable.
+ */
+
+const harness = new EngineHarness();
+
+const SPHERE_POSITION = new Vector3(0, 2, 0);
+
+/**
+ * Grid resolution for the per-region luminance breakdown
+ * @type {number}
+ */
+const REGION_GRID = 4;
+
+const scratch_color = new ThreeColor();
+
+const VIEWPORT_WIDTH = 800;
+const VIEWPORT_HEIGHT = 600;
+
+/**
+ *
+ * @param {Engine} engine
+ * @returns {WebGLRenderer}
+ */
+function get_renderer(engine) {
+    return engine.graphics.renderer;
+}
+
+/**
+ * Advance the simulation and draw one frame
+ * @param {Engine} engine
+ * @param {number} [dt]
+ * @returns {number} frame duration in milliseconds
+ */
+function frame(engine, dt = 1 / 60) {
+    const t0 = performance.now();
+
+    engine.ticker.onTick.send1(dt);
+    engine.render();
+
+    return performance.now() - t0;
+}
+
+/**
+ * Reads the default framebuffer. Must run in the same task as the draw, the drawing buffer is not
+ * preserved across a compositor frame.
+ * @param {Engine} engine
+ * @returns {{width:number, height:number, mean:number[], luminance:number, regions:number[], hash:number, nonzero:number}}
+ */
+function capture(engine) {
+    const renderer = get_renderer(engine);
+    const gl = renderer.getContext();
+
+    renderer.setRenderTarget(null);
+
+    const width = gl.drawingBufferWidth;
+    const height = gl.drawingBufferHeight;
+
+    const pixels = new Uint8Array(width * height * 4);
+
+    gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+
+    const mean = [0, 0, 0, 0];
+    const regions = new Array(REGION_GRID * REGION_GRID).fill(0);
+    const region_counts = new Array(REGION_GRID * REGION_GRID).fill(0);
+
+    let nonzero = 0;
+    let hash = 0x811c9dc5;
+
+    for (let y = 0; y < height; y++) {
+        const region_y = Math.min(REGION_GRID - 1, Math.floor((y / height) * REGION_GRID));
+
+        for (let x = 0; x < width; x++) {
+            const address = (y * width + x) * 4;
+
+            const r = pixels[address];
+            const g = pixels[address + 1];
+            const b = pixels[address + 2];
+            const a = pixels[address + 3];
+
+            mean[0] += r;
+            mean[1] += g;
+            mean[2] += b;
+            mean[3] += a;
+
+            if (r !== 0 || g !== 0 || b !== 0) {
+                nonzero++;
+            }
+
+            // Rec.709 luma, close enough for an A/B
+            const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+
+            const region_x = Math.min(REGION_GRID - 1, Math.floor((x / width) * REGION_GRID));
+            const region = region_y * REGION_GRID + region_x;
+
+            regions[region] += luma;
+            region_counts[region]++;
+
+            hash = ((hash ^ r) * 0x01000193) >>> 0;
+            hash = ((hash ^ g) * 0x01000193) >>> 0;
+            hash = ((hash ^ b) * 0x01000193) >>> 0;
+        }
+    }
+
+    const pixel_count = width * height;
+
+    for (let i = 0; i < 4; i++) {
+        mean[i] = mean[i] / pixel_count;
+    }
+
+    for (let i = 0; i < regions.length; i++) {
+        regions[i] = region_counts[i] === 0 ? 0 : regions[i] / region_counts[i];
+    }
+
+    return {
+        width,
+        height,
+        mean: mean.map(v => Number(v.toFixed(3))),
+        luminance: Number((0.2126 * mean[0] + 0.7152 * mean[1] + 0.0722 * mean[2]).toFixed(3)),
+        regions: regions.map(v => Number(v.toFixed(2))),
+        hash,
+        nonzero: Number((nonzero / pixel_count).toFixed(4))
+    };
+}
+
+/**
+ *
+ * @param {{luminance:number, regions:number[], hash:number, mean:number[]}} a
+ * @param {{luminance:number, regions:number[], hash:number, mean:number[]}} b
+ */
+function compare(a, b) {
+    let region_max = 0;
+    let region_total = 0;
+
+    for (let i = 0; i < a.regions.length; i++) {
+        const d = Math.abs(a.regions[i] - b.regions[i]);
+
+        region_total += d;
+
+        if (d > region_max) {
+            region_max = d;
+        }
+    }
+
+    return {
+        identical: a.hash === b.hash,
+        luminance_delta: Number((b.luminance - a.luminance).toFixed(3)),
+        region_delta_max: Number(region_max.toFixed(3)),
+        region_delta_mean: Number((region_total / a.regions.length).toFixed(3))
+    };
+}
+
+/**
+ * Coarse luminance map of the framebuffer, printable in a console. The harness is expected to run in a
+ * hidden tab, where screenshots are not available, and an aggregate number does not tell you *what* went
+ * missing.
+ * @param {Engine} engine
+ * @returns {string}
+ */
+function ascii_image(engine, columns = 40, rows = 20) {
+    const RAMP = ' .:-=+*#%@';
+
+    const renderer = get_renderer(engine);
+    const gl = renderer.getContext();
+
+    renderer.setRenderTarget(null);
+
+    const width = gl.drawingBufferWidth;
+    const height = gl.drawingBufferHeight;
+
+    const pixels = new Uint8Array(width * height * 4);
+
+    gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+
+    const lines = [];
+
+    // readPixels returns rows bottom-up
+    for (let row = rows - 1; row >= 0; row--) {
+        let line = '';
+
+        for (let column = 0; column < columns; column++) {
+            const x0 = Math.floor(column * width / columns);
+            const x1 = Math.floor((column + 1) * width / columns);
+            const y0 = Math.floor(row * height / rows);
+            const y1 = Math.floor((row + 1) * height / rows);
+
+            let sum = 0;
+            let count = 0;
+
+            for (let y = y0; y < y1; y += 3) {
+                for (let x = x0; x < x1; x += 3) {
+                    const address = (y * width + x) * 4;
+
+                    sum += 0.2126 * pixels[address] + 0.7152 * pixels[address + 1] + 0.0722 * pixels[address + 2];
+                    count++;
+                }
+            }
+
+            const luma = sum / count;
+
+            line += RAMP[Math.min(RAMP.length - 1, Math.floor((luma / 255) * RAMP.length))];
+        }
+
+        lines.push(line);
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ *
+ * @param {Engine} engine
+ */
+function snapshot_renderer_state(engine) {
+    const renderer = get_renderer(engine);
+    const gl = renderer.getContext();
+    const info = renderer.info;
+
+    const clear_color = renderer.getClearColor(scratch_color);
+
+    return {
+        context_lost: gl.isContextLost(),
+        monitor_state: engine.graphics.context.state,
+        monitor_generation: engine.graphics.context.generation,
+        monitor_loss_count: engine.graphics.context.loss_count,
+        programs: info.programs === null ? -1 : info.programs.length,
+        textures: info.memory.textures,
+        geometries: info.memory.geometries,
+        clear_color: [
+            Number(clear_color.r.toFixed(4)),
+            Number(clear_color.g.toFixed(4)),
+            Number(clear_color.b.toFixed(4))
+        ],
+        clear_alpha: renderer.getClearAlpha(),
+        environment_set: engine.graphics.scene.environment !== null
+            && engine.graphics.scene.environment !== undefined,
+        gl_error: gl.getError()
+    };
+}
+
+/**
+ * Waits for a single event on the canvas
+ * @param {HTMLCanvasElement} canvas
+ * @param {string} name
+ * @param {number} timeout milliseconds
+ * @returns {Promise<number>} milliseconds waited, or -1 on timeout
+ */
+function wait_for_canvas_event(canvas, name, timeout) {
+    return new Promise(resolve => {
+        const t0 = performance.now();
+
+        let timeout_handle = -1;
+
+        const handler = () => {
+            clearTimeout(timeout_handle);
+            canvas.removeEventListener(name, handler);
+            resolve(performance.now() - t0);
+        };
+
+        canvas.addEventListener(name, handler, false);
+
+        timeout_handle = setTimeout(() => {
+            canvas.removeEventListener(name, handler);
+            resolve(-1);
+        }, timeout);
+    });
+}
+
+/**
+ * One loss/restore cycle
+ * @param {Engine} engine
+ * @param {number} [warmup_frames]
+ * @param {number} [lost_frames] frames driven while the context is lost
+ * @param {number} [settle_frames] frames driven after restore before the second capture
+ */
+async function run_cycle(engine, { warmup_frames = 30, lost_frames = 5, settle_frames = 20 } = {}) {
+    const renderer = get_renderer(engine);
+    const canvas = renderer.domElement;
+
+    const report = {};
+
+    // ---- baseline -------------------------------------------------------------------------------
+    for (let i = 0; i < warmup_frames; i++) {
+        frame(engine);
+    }
+
+    frame(engine);
+    const baseline = capture(engine);
+
+    frame(engine);
+    const baseline_2 = capture(engine);
+
+    report.baseline = baseline;
+    report.noise_floor = compare(baseline, baseline_2);
+    report.before = snapshot_renderer_state(engine);
+
+    // ---- lose ---------------------------------------------------------------------------------
+    const lost_promise = wait_for_canvas_event(canvas, 'webglcontextlost', 5000);
+
+    renderer.forceContextLoss();
+
+    report.lost_event_delay_ms = Number((await lost_promise).toFixed(2));
+
+    const lost_frame_errors = [];
+
+    for (let i = 0; i < lost_frames; i++) {
+        try {
+            frame(engine);
+        } catch (e) {
+            lost_frame_errors.push(String(e && e.message ? e.message : e));
+        }
+    }
+
+    report.frames_while_lost_threw = lost_frame_errors;
+    report.while_lost = snapshot_renderer_state(engine);
+
+    // ---- restore ------------------------------------------------------------------------------
+    const restored_promise = wait_for_canvas_event(canvas, 'webglcontextrestored', 10000);
+
+    renderer.forceContextRestore();
+
+    const restore_delay = await restored_promise;
+
+    report.restored_event_delay_ms = Number(restore_delay.toFixed(2));
+    report.restored = restore_delay >= 0;
+
+    if (!report.restored) {
+        report.verdict = 'context was NOT restored within 10s';
+        return report;
+    }
+
+    // first frame after restore carries the re-upload + recompile storm
+    report.first_frame_ms = Number(frame(engine).toFixed(2));
+    const first = capture(engine);
+
+    const settle_durations = [];
+
+    for (let i = 0; i < settle_frames; i++) {
+        settle_durations.push(frame(engine));
+    }
+
+    frame(engine);
+    const settled = capture(engine);
+
+    report.settle_frames_ms = {
+        max: Number(Math.max(...settle_durations).toFixed(2)),
+        mean: Number((settle_durations.reduce((a, b) => a + b, 0) / settle_durations.length).toFixed(2))
+    };
+
+    report.after = snapshot_renderer_state(engine);
+
+    report.first_frame_vs_baseline = compare(baseline, first);
+    report.settled_vs_baseline = compare(baseline, settled);
+
+    report.settled = settled;
+
+    return report;
+}
+
+/**
+ * Loss/restore lifecycle without actually killing the context: the canvas events are dispatched by hand.
+ *
+ * three.js reacts to the restore event by rebuilding all of its GPU-object bookkeeping, so everything is
+ * re-uploaded and every shader recompiled exactly as it would be after a real restore - the difference is
+ * that the underlying context stays healthy, which is what makes this runnable in a hidden tab (browsers
+ * only restore a genuinely lost context while the page is visible).
+ *
+ * What this covers: the engine's gate, the fix-up sequence, the environment re-bake, and three's own
+ * restore path. What it cannot cover: whether the browser is willing to restore, and how stale GL handles
+ * from the dead context behave.
+ *
+ * @param {Engine} engine
+ */
+function run_synthetic_cycle(engine, { warmup_frames = 40, lost_frames = 5, settle_frames = 10 } = {}) {
+    const renderer = get_renderer(engine);
+    const canvas = renderer.domElement;
+
+    const report = {};
+
+    for (let i = 0; i < warmup_frames; i++) {
+        frame(engine);
+    }
+
+    frame(engine);
+    const baseline = capture(engine);
+
+    frame(engine);
+    report.noise_floor = compare(baseline, capture(engine));
+    report.baseline = baseline;
+    report.before = snapshot_renderer_state(engine);
+    report.baseline_image = ascii_image(engine);
+
+    // ---- loss -----------------------------------------------------------------------------------
+    const frame_index_before = engine.graphics.frameIndex;
+
+    canvas.dispatchEvent(new Event('webglcontextlost', { cancelable: true }));
+
+    report.state_while_lost = engine.graphics.context.state;
+
+    const errors = [];
+
+    for (let i = 0; i < lost_frames; i++) {
+        try {
+            frame(engine);
+        } catch (e) {
+            errors.push(String(e && e.message ? e.message : e));
+        }
+    }
+
+    report.frames_while_lost_threw = errors;
+    // the gate returns before the frame counter is touched, so this proves no drawing happened
+    report.frames_drawn_while_lost = engine.graphics.frameIndex - frame_index_before;
+
+    // ---- restore --------------------------------------------------------------------------------
+    canvas.dispatchEvent(new Event('webglcontextrestored'));
+
+    report.first_frame_ms = Number(frame(engine).toFixed(2));
+    const first = capture(engine);
+
+    for (let i = 0; i < settle_frames; i++) {
+        frame(engine);
+    }
+
+    frame(engine);
+    const settled = capture(engine);
+
+    report.after = snapshot_renderer_state(engine);
+    report.first_frame_vs_baseline = compare(baseline, first);
+    report.settled_vs_baseline = compare(baseline, settled);
+    report.settled = settled;
+    report.settled_image = ascii_image(engine);
+
+    return report;
+}
+
+/**
+ * Renders the same scene through a brand new renderer on a brand new context.
+ *
+ * Note that the environment map is expected to differ here: swapping the renderer is not a context
+ * restore, so the engine's recovery hook never runs and the prefiltered radiance is never re-baked. The
+ * value of this scenario is everything else - geometry, textures, shaders, render targets and the
+ * composit chain all have to come back from CPU-side data, and any of them failing to shows up as a
+ * difference beyond the known environment delta.
+ *
+ * This is the closest analogue of a restore that can be produced in a hidden tab while still exercising
+ * real GPU work: the object graph is untouched, but the GL-side caches are empty, so everything that
+ * cannot be re-derived from CPU-side data shows up as a difference against the baseline.
+ *
+ * @param {Engine} engine
+ */
+function run_fresh_context(engine, { warmup_frames = 40, settle_frames = 10 } = {}) {
+    const graphics = engine.graphics;
+
+    const report = {};
+
+    for (let i = 0; i < warmup_frames; i++) {
+        frame(engine);
+    }
+
+    frame(engine);
+    const baseline = capture(engine);
+
+    frame(engine);
+    report.noise_floor = compare(baseline, capture(engine));
+    report.baseline = baseline;
+
+    const previous = graphics.renderer;
+
+    const canvas = document.createElement('canvas');
+    const context = canvas.getContext('webgl2', { antialias: false });
+
+    const fresh = new WebGLRenderer({
+        antialias: true,
+        logarithmicDepthBuffer: false,
+        canvas,
+        context,
+        powerPreference: 'high-performance'
+    });
+
+    configureThreeRenderer(fresh);
+
+    graphics.renderer = fresh;
+
+    graphics.updateSize();
+
+    report.first_frame_ms = Number(frame(engine).toFixed(2));
+    const first = capture(engine);
+
+    for (let i = 0; i < settle_frames; i++) {
+        frame(engine);
+    }
+
+    frame(engine);
+    const settled = capture(engine);
+
+    report.fresh_programs = fresh.info.programs.length;
+    report.fresh_textures = fresh.info.memory.textures;
+    report.fresh_geometries = fresh.info.memory.geometries;
+    report.fresh_draw_calls = fresh.info.render.calls;
+    report.fresh_triangles = fresh.info.render.triangles;
+    report.settled_image = ascii_image(engine);
+
+    graphics.renderer = previous;
+
+    graphics.updateSize();
+
+    report.first_frame_vs_baseline = compare(baseline, first);
+    report.settled_vs_baseline = compare(baseline, settled);
+
+    // and confirm the shared object graph was not disturbed by the swap
+    frame(engine);
+    report.restored_original_vs_baseline = compare(baseline, capture(engine));
+
+    fresh.forceContextLoss();
+    fresh.dispose();
+
+    return report;
+}
+
+/**
+ *
+ * @param {Engine} engine
+ */
+function install_api(engine) {
+    const api = {
+        engine,
+
+        frame: (n = 1) => {
+            const durations = [];
+            for (let i = 0; i < n; i++) {
+                durations.push(frame(engine));
+            }
+            return durations;
+        },
+
+        capture: () => {
+            frame(engine);
+            return capture(engine);
+        },
+
+        state: () => snapshot_renderer_state(engine),
+
+        image: () => ascii_image(engine),
+
+        /**
+         * Loss/restore lifecycle driven by synthetic canvas events. Works in a hidden tab.
+         */
+        synthetic(options) {
+            const report = run_synthetic_cycle(engine, options);
+
+            window.__context_loss_report = report;
+
+            console.log('[context-loss] synthetic report', report);
+            console.log('[context-loss] baseline\n' + report.baseline_image);
+            console.log('[context-loss] after restore\n' + report.settled_image);
+
+            return report;
+        },
+
+        /**
+         * Same scene, brand new context. Works in a hidden tab.
+         */
+        fresh(options) {
+            const report = run_fresh_context(engine, options);
+
+            window.__context_loss_report = report;
+
+            console.log('[context-loss] fresh-context report', report);
+
+            return report;
+        },
+
+        async run(options) {
+            const report = await run_cycle(engine, options);
+
+            window.__context_loss_report = report;
+
+            console.log('[context-loss] report', report);
+
+            return report;
+        },
+
+        async repeat(count = 3, options) {
+            const reports = [];
+
+            for (let i = 0; i < count; i++) {
+                console.log(`[context-loss] cycle ${i + 1}/${count}`);
+                reports.push(await run_cycle(engine, options));
+            }
+
+            const summary = reports.map((r, i) => ({
+                cycle: i,
+                restored: r.restored,
+                first_frame_ms: r.first_frame_ms,
+                settled_vs_baseline: r.settled_vs_baseline,
+                textures_before: r.before.textures,
+                textures_after: r.after === undefined ? -1 : r.after.textures,
+                geometries_after: r.after === undefined ? -1 : r.after.geometries,
+                programs_after: r.after === undefined ? -1 : r.after.programs
+            }));
+
+            window.__context_loss_report = { reports, summary };
+
+            console.log('[context-loss] repeat summary', summary);
+
+            return summary;
+        }
+    };
+
+    window.__context_loss_test = api;
+}
+
+/**
+ *
+ * @param {Engine} engine
+ * @returns {Promise<void>}
+ */
+async function main(engine) {
+    // fixed viewport: the pixel A/B needs a stable resolution, and the harness is expected to run in a
+    // hidden tab where the window-driven sizing path produces a 0-sized viewport
+    engine.settings.graphics_control_viewport_size.set(false);
+    engine.viewStack.size.set(VIEWPORT_WIDTH, VIEWPORT_HEIGHT);
+
+    await EngineHarness.buildBasics({
+        engine,
+        focus: SPHERE_POSITION,
+        distance: 6,
+        pitch: 0.35,
+        // static scene: animated water would make consecutive frames differ
+        enableWater: false,
+        enableTerrain: true,
+        terrainSize: { x: 32, y: 32 },
+        enableLights: true,
+        enableShadows: true,
+        cameraController: false
+    });
+
+    const ecd = engine.entityManager.dataset;
+
+    // a large mirror-metal sphere; almost all of its shading comes from scene.environment, which makes
+    // the PMREM environment map's survival directly visible in the pixel A/B
+    const material = new MeshStandardMaterial({
+        color: 0xffffff,
+        metalness: 1,
+        roughness: 0.08
+    });
+
+    const mesh = new Mesh(new SphereGeometry(2, 48, 32), material);
+
+    mesh.castShadow = true;
+
+    new Entity()
+        .add(new Renderable(mesh))
+        .add(Transform.fromJSON({
+            position: SPHERE_POSITION,
+            scale: { x: 1, y: 1, z: 1 }
+        }))
+        .build(ecd);
+
+    await load_and_set_cubemap_v0(engine.graphics, 'data/textures/cubemaps/hip_miramar/32/', '.png');
+
+    install_api(engine);
+
+    console.log('[context-loss] ready. Run window.__context_loss_test.run()');
+}
+
+harness.initialize({
+    configuration(config, engine) {
+        config.addManySystems(
+            new RenderSystem(engine.graphics)
+        );
+    }
+}).then(main);

package/src/engine/graphics/ecs/camera/serialization/CameraSerializationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CameraSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/camera/serialization/CameraSerializationAdapter.js"],"names":[],"mappings":"AAGA;;IAEI,qBAAe;IAGf;;;;OAIG;IACH,uCAFW,MAAM,QAShB;IAED;;;;OAIG;IACH,yCAFW,MAAM,QAKhB;CACJ;gDA/B+C,mEAAmE;uBAC5F,cAAc"}
+{"version":3,"file":"CameraSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/camera/serialization/CameraSerializationAdapter.js"],"names":[],"mappings":"AAeA;;IAEI,qBAAe;IAGf;;;;OAIG;IACH,uCAFW,MAAM,QAmBhB;IAED;;;;OAIG;IACH,yCAFW,MAAM,QAmBhB;CACJ;gDAnE+C,mEAAmE;uBAC5F,cAAc"}