@woosh/meep-engine 3.0.1 → 3.1.0

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

@@ -1,341 +0,0 @@
-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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,24 +0,0 @@
-/**
- * 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/ecs/animation/animator/graph/AnimationGraph.d.ts

@@ -1,231 +0,0 @@
-export class AnimationGraph {
-    /**
-     *
-     * @param j
-     * @returns {AnimationGraph}
-     */
-    static fromJSON(j: any): AnimationGraph;
-    /**
-     *
-     * @type {AnimationGraphDefinition}
-     */
-    def: AnimationGraphDefinition;
-    /**
-     *
-     * @type {AnimationState}
-     */
-    state: AnimationState;
-    /**
-     *
-     * @type {AnimationTransition[]}
-     */
-    transitions: AnimationTransition[];
-    /**
-     *
-     * @type {AnimationState[]}
-     */
-    states: AnimationState[];
-    /**
-     *
-     * @type {AnimationTransition[]}
-     */
-    activeTransitions: AnimationTransition[];
-    /**
-     *
-     * @type {AnimationState[]}
-     */
-    simulatedStates: AnimationState[];
-    /**
-     *
-     * @type {BlendStateMatrix}
-     */
-    blendState: BlendStateMatrix;
-    /**
-     *
-     * @type {number}
-     */
-    debtTime: number;
-    /**
-     * Where in its starting clip the graph begins, as a fraction of that clip's duration.
-     *
-     * A fraction rather than a time because a clip's duration comes from the model, and the model
-     * loads long after the entity that wants the offset does: {@link attach} is what teaches the
-     * clip definitions their durations, and a spawner that reads `duration` itself reads
-     * `undefined`. Its purpose is to keep identical units from moving in lockstep, and it is
-     * applied once, at {@link link}, without dispatching the notifications it skips over -- a unit
-     * that spawns mid-stride should not also spawn the footstep it missed.
-     *
-     * @type {number}
-     */
-    start_phase: number;
-    /**
-     *
-     * @type {EntityComponentDataset}
-     * @private
-     */
-    private __dataset;
-    /**
-     *
-     * @type {number}
-     * @private
-     */
-    private __entity;
-    /**
-     *
-     * @type {AnimationMixer}
-     * @private
-     */
-    private __mixer;
-    /**
-     *
-     * @type {AnimationAction[]}
-     * @private
-     */
-    private __actions;
-    /**
-     *
-     * @type {Object3D}
-     * @private
-     */
-    private __mesh;
-    /**
-     *
-     * @type {number}
-     */
-    flags: number;
-    /**
-     *
-     * @param {AnimationGraph} other
-     * @returns {boolean}
-     */
-    equals(other: AnimationGraph): boolean;
-    /**
-     * @returns {number}
-     */
-    hash(): number;
-    toJSON(): {
-        def: any;
-        state: any;
-        debtTime: number;
-        flags: number;
-    };
-    /**
-     *
-     * @param {*} def Graph definition JSON
-     * @param {number} state
-     * @param {number} debtTime
-     * @param {number} flags
-     */
-    fromJSON({ def, state, debtTime, flags }: any): void;
-    /**
-     *
-     * @param {number|AnimationGraphFlag} flag
-     * @returns {void}
-     */
-    setFlag(flag: number | AnimationGraphFlag): void;
-    /**
-     *
-     * @param {number|AnimationGraphFlag} flag
-     * @returns {void}
-     */
-    clearFlag(flag: number | AnimationGraphFlag): void;
-    /**
-     *
-     * @param {number|AnimationGraphFlag} flag
-     * @param {boolean} value
-     */
-    writeFlag(flag: number | AnimationGraphFlag, value: boolean): void;
-    /**
-     *
-     * @param {number|AnimationGraphFlag} flag
-     * @returns {boolean}
-     */
-    getFlag(flag: number | AnimationGraphFlag): boolean;
-    /**
-     *
-     * @param {AnimationStateDefinition} stateDefinition
-     * @returns {AnimationState}
-     */
-    getStateByDefinition(stateDefinition: AnimationStateDefinition): AnimationState;
-    /**
-     *
-     * @param {string} name
-     * @return {AnimationState}
-     */
-    getStateByClipName(name: string): AnimationState;
-    /**
-     *
-     * @param {string} name
-     * @return {AnimationState|undefined}
-     */
-    getStateByName(name: string): AnimationState | undefined;
-    /**
-     *
-     * @param {AnimationTransitionDefinition} transitionDefinition
-     * @returns {AnimationTransition|undefined}
-     */
-    getTransitionByDefinition(transitionDefinition: AnimationTransitionDefinition): AnimationTransition | undefined;
-    /**
-     *
-     * @param {AnimationGraphDefinition} def
-     */
-    initialize(def: AnimationGraphDefinition): void;
-    /**
-     *
-     * @param {Object3D} mesh
-     */
-    attach(mesh: Object3D): void;
-    link(entity: any, ecd: any): void;
-    /**
-     * Move the starting state to {@link start_phase} of its clip.
-     *
-     * Two clocks are moved because this path keeps two: {@link AnimationState#time} is what
-     * notifications are measured against, and the mixer action carries the one the pose is drawn
-     * from. Offsetting either alone desynchronises a unit's footstep events from its feet.
-     *
-     * Called from {@link link}, which {@link attach} always precedes, so the durations are known
-     * by the time this runs.
-     */
-    applyStartPhase(): void;
-    unlink(): void;
-    /**
-     *
-     * @param {AnimationState} state
-     * @returns {boolean}
-     */
-    stopStateSimulation(state: AnimationState): boolean;
-    updateBlendState(): void;
-    writeBlendState(): void;
-    /**
-     *
-     * @param {number} timeDelta in seconds
-     */
-    tick(timeDelta: number): void;
-    /**
-     *
-     * @param {AnimationState} state
-     */
-    enterState(state: AnimationState): void;
-    /**
-     *
-     * @param {AnimationState} state
-     */
-    exitState(state: AnimationState): void;
-    /**
-     *
-     * @param {AnimationState} state
-     */
-    activateState(state: AnimationState): void;
-    /**
-     *
-     * @param {AnimationTransition} transition
-     */
-    transition(transition: AnimationTransition): void;
-}
-export namespace AnimationGraph {
-    let typeName: string;
-}
-import { AnimationState } from "./AnimationState.js";
-import { AnimationTransition } from "./AnimationTransition.js";
-import { AnimationGraphFlag } from "./AnimationGraphFlag.js";
-//# sourceMappingURL=AnimationGraph.d.ts.map

package/src/engine/graphics/ecs/animation/animator/graph/AnimationGraph.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"AnimationGraph.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/animation/animator/graph/AnimationGraph.js"],"names":[],"mappings":"AA0CA;IAmKI;;;;OAIG;IACH,yBAFa,cAAc,CAQ1B;IA7KD;;;OAGG;IACH,8BAAW;IAEX;;;OAGG;IACH,OAFU,cAAc,CAEX;IAEb;;;OAGG;IACH,aAFU,mBAAmB,EAAE,CAEd;IAEjB;;;OAGG;IACH,QAFU,cAAc,EAAE,CAEd;IAEZ;;;OAGG;IACH,mBAFU,mBAAmB,EAAE,CAER;IAEvB;;;OAGG;IACH,iBAFU,cAAc,EAAE,CAEL;IAErB;;;OAGG;IACH,6BAAkB;IAElB;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;;;;;;;;;OAWG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,kBAAiB;IAEjB;;;;OAIG;IACH,iBAAc;IAEd;;;;OAIG;IACH,gBAAe;IAEf;;;;OAIG;IACH,kBAAe;IAEf;;;;OAIG;IACH,eAAc;IAEd;;;OAGG;IACH,OAFU,MAAM,CAE2B;IAE3C;;;;OAIG;IACH,cAHW,cAAc,GACZ,OAAO,CAYnB;IAED;;OAEG;IACH,QAFa,MAAM,CASlB;IAED;;;;;MAOC;IAED;;;;;;OAMG;IACH,qDAYC;IAeD;;;;OAIG;IACH,cAHW,MAAM,GAAC,kBAAkB,GACvB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,kBAAkB,GACvB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,kBAAkB,SACzB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,kBAAkB,GACvB,OAAO,CAInB;IAED;;;;OAIG;IACH,iEAFa,cAAc,CAiB1B;IAED;;;;OAIG;IACH,yBAHW,MAAM,GACL,cAAc,CAqBzB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACL,cAAc,GAAC,SAAS,CAkBnC;IAED;;;;OAIG;IACH,gFAFa,mBAAmB,GAAC,SAAS,CAazC;IAED;;;OAGG;IACH,gDAkEC;IAED;;;OAGG;IACH,6BA6DC;IAED,kCAmBC;IAED;;;;;;;;;OASG;IACH,wBAwBC;IAED,eASC;IAED;;;;OAIG;IACH,2BAHW,cAAc,GACZ,OAAO,CAanB;IAED,yBA8CC;IAED,wBA0BC;IAED;;;OAGG;IACH,gBAFW,MAAM,QA+DhB;IAGD;;;OAGG;IACH,kBAFW,cAAc,QA8CxB;IAED;;;OAGG;IACH,iBAFW,cAAc,QASxB;IAED;;;OAGG;IACH,qBAFW,cAAc,QAQxB;IAED;;;OAGG;IACH,uBAFW,mBAAmB,QAY7B;CACJ;;kBAIS,MAAM;;+BAnyBe,qBAAqB;oCAEhB,0BAA0B;mCAH3B,yBAAyB"}