@woosh/meep-engine 2.168.0 → 2.169.0

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

@@ -0,0 +1,341 @@
+import { assert } from "../../../core/assert.js";
+import Signal from "../../../core/events/signal/Signal.js";
+import { WebGLContextFailureReason } from "./WebGLContextFailureReason.js";
+import { WebGLContextState } from "./WebGLContextState.js";
+
+/**
+ * Detects WebGL context loss on a canvas and tracks whether the context may be used.
+ *
+ * The browser is only allowed to restore a lost context if `preventDefault()` was called on the loss
+ * event, which is what this class does. Restoration is still the browser's decision - it will refuse
+ * when the page caused the loss itself (typically by exceeding the per-page context limit) or when
+ * acceleration has been disabled for the page. That is why recovery is bounded: after
+ * {@link WebGLContextMonitor#restore_timeout} seconds without a restore, or after more than
+ * {@link WebGLContextMonitor#max_loss_count} losses, the monitor gives up and reports
+ * {@link WebGLContextMonitor#on}.failed so the application can tell the user instead of presenting a
+ * permanently black canvas.
+ *
+ * The restore deadline only runs while the page is visible. The browser does not restore a context in a
+ * hidden tab, so counting hidden time would fail sessions that were merely backgrounded when the loss
+ * happened - a common case, since background tabs are where the browser prefers to evict contexts. Each
+ * return to visibility restarts the full {@link WebGLContextMonitor#restore_timeout} wait.
+ *
+ * Detection is entirely event driven. Nothing here runs per frame; consumers read
+ * {@link WebGLContextMonitor#is_live} (a single field compare) and subscribe to the signals.
+ */
+export class WebGLContextMonitor {
+    /**
+     *
+     * @type {HTMLCanvasElement|null}
+     */
+    #canvas = null;
+
+    /**
+     *
+     * @type {WebGLContextState}
+     */
+    #state = WebGLContextState.Live;
+
+    /**
+     * Incremented every time the context is restored. Async work that spans a loss can compare the
+     * generation it started in against the current one to find out whether its GPU-side results are
+     * still meaningful.
+     * @type {number}
+     */
+    #generation = 0;
+
+    /**
+     * How many times the context has been lost since {@link WebGLContextMonitor#attach}
+     * @type {number}
+     */
+    #loss_count = 0;
+
+    /**
+     * Timestamps of recent losses, in milliseconds, oldest first. Entries older than
+     * {@link WebGLContextMonitor#loss_window} are dropped, so this measures a burst rather than a
+     * lifetime total - a session that hits an unrelated loss every couple of hours should keep
+     * recovering, one that dies four times in a minute should not.
+     * @type {number[]}
+     */
+    #recent_losses = [];
+
+    /**
+     * Handle of the pending restore watchdog, `-1` when none is scheduled
+     * @type {number}
+     */
+    #restore_watchdog = -1;
+
+    /**
+     * Timestamp of the most recent loss, in milliseconds
+     * @type {number}
+     */
+    #time_of_loss = 0;
+
+    /**
+     * How long the most recent recovery took, in seconds. `-1` until the first recovery.
+     * @type {number}
+     */
+    #restore_duration = -1;
+
+    /**
+     * How long to wait for the browser to restore a lost context before declaring failure, in seconds.
+     * Only visible time counts - the browser will not restore while the tab is hidden, so the deadline is
+     * suspended for as long as the page is, and restarts in full when the page is revealed.
+     * @type {number}
+     */
+    restore_timeout = 5;
+
+    /**
+     * How many losses within {@link WebGLContextMonitor#loss_window} to recover from before giving up. A
+     * context that keeps dying is usually a symptom of something recovery cannot fix, such as a driver
+     * that crashes on our workload.
+     * @type {number}
+     */
+    max_loss_count = 3;
+
+    /**
+     * Window over which {@link WebGLContextMonitor#max_loss_count} is counted, in seconds
+     * @type {number}
+     */
+    loss_window = 60;
+
+    on = {
+        /**
+         * Context has been lost. Rendering must stop until `restored` or `failed`.
+         * @type {Signal}
+         */
+        lost: new Signal(),
+        /**
+         * Context has been restored, carries the new generation number. GPU-side state must be
+         * considered empty; anything not re-derivable from CPU-side data has to be rebuilt here.
+         * @type {Signal<number>}
+         */
+        restored: new Signal(),
+        /**
+         * Recovery was abandoned, carries a {@link WebGLContextFailureReason}. Terminal.
+         * @type {Signal<string>}
+         */
+        failed: new Signal()
+    };
+
+    /**
+     * @returns {WebGLContextState}
+     */
+    get state() {
+        return this.#state;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get generation() {
+        return this.#generation;
+    }
+
+    /**
+     * Total number of losses observed since {@link WebGLContextMonitor#attach}
+     * @returns {number}
+     */
+    get loss_count() {
+        return this.#loss_count;
+    }
+
+    /**
+     * Number of losses within the last {@link WebGLContextMonitor#loss_window} seconds, including the
+     * current one if the context is presently lost
+     * @returns {number}
+     */
+    get recent_loss_count() {
+        const window_start = performance.now() - this.loss_window * 1000;
+
+        const recent = this.#recent_losses;
+
+        let result = 0;
+
+        for (let i = 0; i < recent.length; i++) {
+            if (recent[i] >= window_start) {
+                result++;
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Duration of the most recent recovery in seconds, `-1` if the context has never been restored
+     * @returns {number}
+     */
+    get restore_duration() {
+        return this.#restore_duration;
+    }
+
+    /**
+     * Whether the context may be used for rendering. This is the per-frame gate, keep it cheap.
+     * @returns {boolean}
+     */
+    get is_live() {
+        return this.#state === WebGLContextState.Live;
+    }
+
+    /**
+     * Start watching a canvas, whose context is assumed to be live. Must be called before the context is
+     * used, and at most once without an intervening {@link WebGLContextMonitor#detach}.
+     *
+     * Loss bookkeeping is reset, so attaching to a freshly created canvas after giving up on the previous
+     * one starts with a clean slate. The generation counter is not reset - it is monotonic for the
+     * lifetime of the monitor, so that stale async results can always be recognised.
+     *
+     * @param {HTMLCanvasElement} canvas
+     */
+    attach(canvas) {
+        assert.defined(canvas, 'canvas');
+        assert.equal(this.#canvas, null, 'monitor is already attached');
+
+        this.#canvas = canvas;
+        this.#state = WebGLContextState.Live;
+        this.#loss_count = 0;
+        this.#recent_losses.length = 0;
+
+        canvas.addEventListener('webglcontextlost', this.#handle_lost, false);
+        canvas.addEventListener('webglcontextrestored', this.#handle_restored, false);
+
+        canvas.ownerDocument.addEventListener('visibilitychange', this.#handle_visibility_change, false);
+    }
+
+    /**
+     * Stop watching the canvas and cancel any pending watchdog
+     */
+    detach() {
+        const canvas = this.#canvas;
+
+        if (canvas === null) {
+            return;
+        }
+
+        canvas.removeEventListener('webglcontextlost', this.#handle_lost, false);
+        canvas.removeEventListener('webglcontextrestored', this.#handle_restored, false);
+
+        canvas.ownerDocument.removeEventListener('visibilitychange', this.#handle_visibility_change, false);
+
+        this.#cancel_watchdog();
+
+        this.#canvas = null;
+    }
+
+    #cancel_watchdog() {
+        if (this.#restore_watchdog !== -1) {
+            clearTimeout(this.#restore_watchdog);
+            this.#restore_watchdog = -1;
+        }
+    }
+
+    #arm_watchdog() {
+        this.#restore_watchdog = setTimeout(
+            () => {
+                this.#restore_watchdog = -1;
+                this.#fail(WebGLContextFailureReason.RestoreTimeout);
+            },
+            this.restore_timeout * 1000
+        );
+    }
+
+    /**
+     * Whether the page holding the canvas is currently hidden
+     * @returns {boolean}
+     */
+    #is_page_hidden() {
+        return this.#canvas.ownerDocument.visibilityState === 'hidden';
+    }
+
+    /**
+     *
+     * @param {WebGLContextFailureReason} reason
+     */
+    #fail(reason) {
+        this.#cancel_watchdog();
+
+        this.#state = WebGLContextState.Failed;
+
+        this.on.failed.send1(reason);
+    }
+
+    /**
+     *
+     * @param {WebGLContextEvent} event
+     */
+    #handle_lost = (event) => {
+        // by default a lost context is never handed back; preventing the default behaviour is what makes
+        // the browser consider restoring it
+        event.preventDefault();
+
+        if (this.#state === WebGLContextState.Failed) {
+            // already given up, nothing more to do
+            return;
+        }
+
+        this.#cancel_watchdog();
+
+        const now = performance.now();
+
+        this.#loss_count++;
+        this.#time_of_loss = now;
+        this.#state = WebGLContextState.Lost;
+
+        const recent = this.#recent_losses;
+
+        // drop losses that have aged out of the window
+        const window_start = now - this.loss_window * 1000;
+
+        let surviving = 0;
+        for (let i = 0; i < recent.length; i++) {
+            if (recent[i] >= window_start) {
+                recent[surviving++] = recent[i];
+            }
+        }
+        recent.length = surviving;
+
+        recent.push(now);
+
+        this.on.lost.send0();
+
+        if (recent.length > this.max_loss_count) {
+            this.#fail(WebGLContextFailureReason.TooManyLosses);
+            return;
+        }
+
+        if (!this.#is_page_hidden()) {
+            // a hidden tab's context cannot be restored, so the deadline would be unmeetable; it is
+            // armed by #handle_visibility_change once the page is revealed
+            this.#arm_watchdog();
+        }
+    };
+
+    #handle_visibility_change = () => {
+        if (this.#state !== WebGLContextState.Lost) {
+            return;
+        }
+
+        if (this.#is_page_hidden()) {
+            this.#cancel_watchdog();
+        } else if (this.#restore_watchdog === -1) {
+            this.#arm_watchdog();
+        }
+    };
+
+    #handle_restored = () => {
+        if (this.#state === WebGLContextState.Failed) {
+            // we already told the application that the device is gone and it may have torn down its
+            // presentation state; coming back to life here would leave it in an inconsistent state
+            return;
+        }
+
+        this.#cancel_watchdog();
+
+        this.#restore_duration = (performance.now() - this.#time_of_loss) / 1000;
+
+        this.#generation++;
+        this.#state = WebGLContextState.Live;
+
+        this.on.restored.send1(this.#generation);
+    };
+}

package/src/engine/graphics/context/WebGLContextState.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Lifecycle state of the WebGL context tracked by {@link WebGLContextMonitor }.
+ *
+ * There is deliberately no separate "restoring" state: the monitor always calls `preventDefault()` on
+ * the loss event, so `Lost` already means "gone, waiting for the browser to hand it back". Recovery
+ * fix-ups run synchronously inside the restore handler, so no state is observable in between.
+ */
+export type WebGLContextState = number;
+export namespace WebGLContextState {
+    let Live: number;
+    let Lost: number;
+    let Failed: number;
+}
+//# sourceMappingURL=WebGLContextState.d.ts.map

package/src/engine/graphics/context/WebGLContextState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebGLContextState.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/context/WebGLContextState.js"],"names":[],"mappings":";;;;;;;gCAOU,MAAM"}

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

@@ -0,0 +1,24 @@
+/**
+ * Lifecycle state of the WebGL context tracked by {@link WebGLContextMonitor}.
+ *
+ * There is deliberately no separate "restoring" state: the monitor always calls `preventDefault()` on
+ * the loss event, so `Lost` already means "gone, waiting for the browser to hand it back". Recovery
+ * fix-ups run synchronously inside the restore handler, so no state is observable in between.
+ *
+ * @enum {number}
+ */
+export const WebGLContextState = {
+    /**
+     * Context is usable, rendering is allowed
+     */
+    Live: 0,
+    /**
+     * Context is gone and we are waiting for the browser to restore it. Rendering is suppressed.
+     */
+    Lost: 1,
+    /**
+     * Recovery was given up on. Terminal - the context will not come back without recreating the
+     * renderer or reloading the page.
+     */
+    Failed: 2
+};

package/src/engine/graphics/context/testWebGLContextLoss.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=testWebGLContextLoss.d.ts.map

package/src/engine/graphics/context/testWebGLContextLoss.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testWebGLContextLoss.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/context/testWebGLContextLoss.js"],"names":[],"mappings":""}