@woosh/meep-engine 2.168.0 → 2.169.0

package/src/engine/graphics/GraphicsEngine.js

@@ -24,6 +24,7 @@ import { MetricsCategory } from "../metrics/MetricsCategory.js";
 import { CompositingStages } from "./composit/CompositingStages.js";
 
 import LayerCompositer from "./composit/LayerCompositer.js";
+import { WebGLContextMonitor } from "./context/WebGLContextMonitor.js";
 import { Camera } from "./ecs/camera/Camera.js";
 import { MaterialManager } from "./material/manager/MaterialManager.js";
 import { ColorAndDepthFrameBuffer } from "./render/buffer/buffers/ColorAndDepthFrameBuffer.js";
@@ -39,10 +40,16 @@ import { three_setSceneAutoUpdate } from "./three/three_setSceneAutoUpdate.js";
 import { EnvironmentTextureProjection } from "./texture/EnvironmentTextureProjection.js";
 
 /**
+ * Applies the renderer configuration the engine relies on.
+ *
+ * Must be re-applied after a context restore: three.js rebuilds its internal modules from scratch in
+ * that case, and some of the settings live inside those modules rather than on the renderer itself -
+ * most notably the clear colour and alpha, which are owned by `WebGLBackground` and silently revert to
+ * transparent black.
  *
  * @param {WebGLRenderer} webGLRenderer
  */
-function configureThreeRenderer(webGLRenderer) {
+export function configureThreeRenderer(webGLRenderer) {
 
     webGLRenderer.autoClear = false;
     webGLRenderer.setClearColor(0xBBBBFF, 0.0);
@@ -66,6 +73,40 @@ function configureThreeRenderer(webGLRenderer) {
 export class GraphicsEngine {
     #debug = false;
 
+    /**
+     * Source texture the environment map was baked from, retained so that the bake can be repeated
+     * after a context loss. `null` when no environment has been set.
+     * @type {THREE.Texture|null}
+     */
+    #environment_source = null;
+
+    /**
+     * @type {EnvironmentTextureProjection}
+     */
+    #environment_projection = EnvironmentTextureProjection.Equirectangular;
+
+    /**
+     * Prefiltered radiance target produced from {@link GraphicsEngine##environment_source}. Kept so it
+     * can be disposed when the environment is replaced or re-baked.
+     * @type {THREE.WebGLRenderTarget|null}
+     */
+    #environment_target = null;
+
+    /**
+     * Tracks WebGL context loss. Rendering is suppressed while the context is gone, and GPU-side state
+     * that is not re-derived every frame is rebuilt when it comes back.
+     * @readonly
+     * @type {WebGLContextMonitor}
+     */
+    context = new WebGLContextMonitor();
+
+    /**
+     * GPU identification string, read once at startup. Queried through an extension, which is unavailable
+     * on a lost context, so it has to be captured while the context is alive to be usable in loss reports.
+     * @type {string}
+     */
+    #gpu_name = 'Unknown';
+
     get isGraphicsEngine(){
         return true;
     }
@@ -112,7 +153,27 @@ export class GraphicsEngine {
 
             buffersRendered: new Signal(),
             visibilityConstructionStarted: new Signal(),
-            visibilityConstructionEnded: new Signal()
+            visibilityConstructionEnded: new Signal(),
+
+            /**
+             * WebGL context has been lost. No rendering happens until the context comes back; GPU-side
+             * resources must be treated as gone.
+             * @type {Signal}
+             */
+            contextLost: new Signal(),
+            /**
+             * WebGL context has been restored, carries the context generation number. Dispatched after
+             * the graphics engine has re-applied its own renderer state, so subscribers can render.
+             * Anything held on the GPU that is not rebuilt every frame has to be rebuilt here.
+             * @type {Signal<number>}
+             */
+            contextRestored: new Signal(),
+            /**
+             * Context recovery was abandoned, carries a {@link WebGLContextFailureReason}. Terminal -
+             * there will be no further rendering.
+             * @type {Signal<string>}
+             */
+            contextFailed: new Signal()
         };
 
         /**
@@ -271,28 +332,61 @@ export class GraphicsEngine {
     }
 
     /**
-     * Set the scene's environment map. The supplied texture is treated as BOTH:
-     *   - the skybox background (shown directly), and
-     *   - the image-based-lighting (IBL) source for physically based materials.
+     * Set the scene's image-based-lighting (IBL) source.
      *
-     * The texture is run through three.js' PMREMGenerator to produce the
-     * prefiltered radiance assigned to `scene.environment`, while the original
-     * texture is assigned to `scene.background`.
+     * The texture is run through three.js' PMREMGenerator to produce the prefiltered radiance assigned
+     * to `scene.environment`. The scene background is left alone, use
+     * {@link GraphicsEngine#set_environment_texture} to show the same texture as a skybox as well.
+     *
+     * The source texture is retained: the prefiltered radiance lives in a render target, which means its
+     * contents are lost along with the WebGL context, so the bake has to be repeatable. The bake is
+     * re-run automatically on context restore.
      *
      * Must be called after the renderer has started up.
      *
      * @param {THREE.Texture} texture environment texture (equirectangular or cube)
      * @param {EnvironmentTextureProjection} [projection=EnvironmentTextureProjection.Equirectangular] how the texture is projected
      */
-    set_environment_texture(texture, projection = EnvironmentTextureProjection.Equirectangular) {
+    set_environment_map(texture, projection = EnvironmentTextureProjection.Equirectangular) {
         assert.defined(texture, 'texture');
 
+        this.#environment_source = texture;
+        this.#environment_projection = projection;
+
+        this.#bake_environment();
+    }
+
+    /**
+     * Set the scene's environment map. The supplied texture is treated as BOTH:
+     *   - the skybox background (shown directly), and
+     *   - the image-based-lighting (IBL) source for physically based materials.
+     *
+     * @param {THREE.Texture} texture environment texture (equirectangular or cube)
+     * @param {EnvironmentTextureProjection} [projection=EnvironmentTextureProjection.Equirectangular] how the texture is projected
+     */
+    set_environment_texture(texture, projection = EnvironmentTextureProjection.Equirectangular) {
+        this.set_environment_map(texture, projection);
+
+        // original texture shown as the skybox. Unlike the prefiltered radiance this survives a context
+        // loss on its own, three.js re-uploads it from the image it still holds
+        this.scene.background = texture;
+    }
+
+    /**
+     * Produces prefiltered radiance from the retained environment source and installs it on the scene.
+     * Safe to call repeatedly, the previous bake is released first.
+     */
+    #bake_environment() {
+        const texture = this.#environment_source;
+
         const renderer = this.renderer;
 
         if (renderer === null || renderer === undefined) {
-            throw new Error('GraphicsEngine.set_environment_texture: renderer is not initialized, call after startup');
+            throw new Error('GraphicsEngine: renderer is not initialized, set the environment after startup');
         }
 
+        const projection = this.#environment_projection;
+
         const pmrem = new PMREMGenerator(renderer);
 
         let target;
@@ -305,17 +399,21 @@ export class GraphicsEngine {
             target = pmrem.fromCubemap(texture);
         } else {
             pmrem.dispose();
-            throw new Error(`GraphicsEngine.set_environment_texture: unsupported projection '${projection}'`);
+            throw new Error(`GraphicsEngine: unsupported environment projection '${projection}'`);
         }
 
         pmrem.dispose();
 
-        const scene = this.scene;
+        const previous_target = this.#environment_target;
+
+        this.#environment_target = target;
 
         // prefiltered radiance used by PBR materials as the IBL source
-        scene.environment = target.texture;
-        // original texture shown as the skybox
-        scene.background = texture;
+        this.scene.environment = target.texture;
+
+        if (previous_target !== null) {
+            previous_target.dispose();
+        }
     }
 
     updateSize() {
@@ -408,7 +506,7 @@ export class GraphicsEngine {
         const webGLRenderer = this.renderer = new WebGLRenderer(rendererParameters);
 
         //print GPU info
-        const GPU_NAME = this.getGPUName();
+        const GPU_NAME = this.#gpu_name = this.getGPUName();
 
         console.log("GL renderer : ", GPU_NAME);
 
@@ -418,16 +516,13 @@ export class GraphicsEngine {
         });
 
 
-        webGLRenderer.domElement.addEventListener("webglcontextrestored", function (event) {
-            console.warn("webgl cotnext restored", event);
-        }, false);
+        const context_monitor = this.context;
 
-        webGLRenderer.domElement.addEventListener("webglcontextlost", function (event) {
-            // By default when a WebGL program loses the context it never gets it back.  To recover, we prevent default behaviour
-            event.preventDefault();
+        context_monitor.on.lost.add(this.#handle_context_lost, this);
+        context_monitor.on.restored.add(this.#handle_context_restored, this);
+        context_monitor.on.failed.add(this.#handle_context_failed, this);
 
-            console.warn("webgl context lost", event);
-        }, false);
+        context_monitor.attach(webGLRenderer.domElement);
 
         const domElement = this.domElement = webGLRenderer.domElement;
         //disable selection
@@ -456,6 +551,75 @@ export class GraphicsEngine {
         viewport.el = webGLRenderer.domElement;
     }
 
+    #handle_context_lost() {
+        console.warn('WebGL context lost, rendering suspended');
+
+        globalMetrics.record("webgl-context-lost", {
+            category: MetricsCategory.System,
+            label: this.#gpu_name
+        });
+
+        this.on.contextLost.send0();
+    }
+
+    /**
+     * Rebuilds the renderer state that a context restore does not carry over, then lets everyone else
+     * rebuild theirs.
+     *
+     * Deliberately narrow: three.js re-uploads textures, geometry, render targets and shader programs by
+     * itself, because it drops its GPU-object bookkeeping wholesale on restore. Re-running the graphics
+     * engine's own initialization here would instead allocate a second set of frame buffers and leak the
+     * first one, which would turn a recoverable event into an out-of-memory crash after a few losses.
+     *
+     * @param {number} generation
+     */
+    #handle_context_restored(generation) {
+        const t0 = performance.now();
+
+        const renderer = this.renderer;
+
+        // clear colour/alpha and a few other settings live inside three.js modules that were replaced
+        configureThreeRenderer(renderer);
+
+        renderer.debug.checkShaderErrors = this.#debug;
+
+        this.enableExtensions();
+
+        // re-push size, pixel ratio and the derived output resolution
+        this.updateSize();
+
+        if (this.#environment_source !== null) {
+            // prefiltered radiance lives in a render target, so it died with the context
+            this.#bake_environment();
+        }
+
+        const duration = performance.now() - t0;
+
+        console.warn(`WebGL context restored (generation ${generation}), engine state re-applied in ${duration.toFixed(1)}ms`);
+
+        globalMetrics.record("webgl-context-restored", {
+            category: MetricsCategory.System,
+            label: this.#gpu_name
+        });
+
+        this.on.contextRestored.send1(generation);
+    }
+
+    /**
+     *
+     * @param {WebGLContextFailureReason} reason
+     */
+    #handle_context_failed(reason) {
+        console.error(`WebGL context recovery abandoned: ${reason}`);
+
+        globalMetrics.record("webgl-context-failed", {
+            category: MetricsCategory.System,
+            label: reason
+        });
+
+        this.on.contextFailed.send1(reason);
+    }
+
     /**
      * Produces GPU identification string via WebGL extension if available
      * @returns {string}
@@ -476,6 +640,8 @@ export class GraphicsEngine {
      * Shut down renderer engine. After calling this method the engine may no longer be used.
      */
     stop() {
+        this.context.detach();
+
         const renderer = this.renderer;
         if (renderer !== undefined) {
             renderer.forceContextLoss();
@@ -632,6 +798,12 @@ export class GraphicsEngine {
      *
      */
     render() {
+        if (!this.context.is_live) {
+            // no context to draw with. GL calls would silently do nothing, and readbacks would hand out
+            // zeroes that are indistinguishable from a valid black frame
+            return;
+        }
+
         if (this.needDraw && !this.autoDraw) {
             this.needDraw = false;
         }

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

@@ -0,0 +1,9 @@
+/**
+ * Why {@link WebGLContextMonitor } gave up on recovery.
+ */
+export type WebGLContextFailureReason = string;
+export namespace WebGLContextFailureReason {
+    let RestoreTimeout: string;
+    let TooManyLosses: string;
+}
+//# sourceMappingURL=WebGLContextFailureReason.d.ts.map

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

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

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

@@ -0,0 +1,17 @@
+/**
+ * Why {@link WebGLContextMonitor} gave up on recovery.
+ * @enum {string}
+ */
+export const WebGLContextFailureReason = {
+    /**
+     * The browser never delivered `webglcontextrestored` within the allotted time. Happens when the
+     * browser refuses to restore, for example because the page itself caused the loss by exceeding the
+     * per-page context limit, or because acceleration was disabled for the page.
+     */
+    RestoreTimeout: 'restore-timeout',
+    /**
+     * The context was lost more times than {@link WebGLContextMonitor#max_loss_count}. Recovering again
+     * would most likely just lead to another loss.
+     */
+    TooManyLosses: 'too-many-losses'
+};

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

@@ -0,0 +1,106 @@
+/**
+ * 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 {
+    /**
+     * 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: number;
+    /**
+     * 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: number;
+    /**
+     * Window over which {@link WebGLContextMonitor#max_loss_count} is counted, in seconds
+     * @type {number}
+     */
+    loss_window: number;
+    on: {
+        /**
+         * Context has been lost. Rendering must stop until `restored` or `failed`.
+         * @type {Signal}
+         */
+        lost: 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: any;
+        /**
+         * Recovery was abandoned, carries a {@link WebGLContextFailureReason}. Terminal.
+         * @type {Signal<string>}
+         */
+        failed: any;
+    };
+    /**
+     * @returns {WebGLContextState}
+     */
+    get state(): number;
+    /**
+     * @returns {number}
+     */
+    get generation(): number;
+    /**
+     * Total number of losses observed since {@link WebGLContextMonitor#attach}
+     * @returns {number}
+     */
+    get loss_count(): number;
+    /**
+     * 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(): number;
+    /**
+     * Duration of the most recent recovery in seconds, `-1` if the context has never been restored
+     * @returns {number}
+     */
+    get restore_duration(): number;
+    /**
+     * Whether the context may be used for rendering. This is the per-frame gate, keep it cheap.
+     * @returns {boolean}
+     */
+    get is_live(): boolean;
+    /**
+     * 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: HTMLCanvasElement): void;
+    /**
+     * Stop watching the canvas and cancel any pending watchdog
+     */
+    detach(): void;
+    #private;
+}
+import Signal from "../../../core/events/signal/Signal.js";
+//# sourceMappingURL=WebGLContextMonitor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebGLContextMonitor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/context/WebGLContextMonitor.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAsDI;;;;;OAKG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;;OAKG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,aAFU,MAAM,CAEC;IAEjB;QACI;;;WAGG;cADO,MAAM;QAGhB;;;;WAIG;;QAEH;;;WAGG;;MAEL;IAEF;;OAEG;IACH,oBAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;;OAIG;IACH,gCAcC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;;;;;OASG;IACH,eAFW,iBAAiB,QAe3B;IAED;;OAEG;IACH,eAeC;;CAsHJ;mBAnVkB,uCAAuC"}