@babylonjs/lite-gl 0.1.0 → 0.2.0

package/context.js

@@ -0,0 +1,354 @@
+import { createGLState, resetGLState, resetGLStateCache } from "./state.js";
+/** Acquire a WebGL2 context on the canvas and build the pure-state handle.
+ *  Accepts an `HTMLCanvasElement` or an `OffscreenCanvas` (worker render paths —
+ *  e.g. the Lottie player — which size the drawing buffer via `setGLEngineSize`).
+ *  Throws if WebGL2 is unsupported. */
+export function createGLEngine(canvas, options) {
+    const o = options ?? {};
+    const attrs = {
+        alpha: o.alpha ?? true,
+        premultipliedAlpha: o.premultipliedAlpha ?? true,
+        antialias: o.antialias ?? false,
+        preserveDrawingBuffer: o.preserveDrawingBuffer ?? false,
+        depth: o.depth ?? false,
+        stencil: o.stencil ?? false,
+        powerPreference: o.powerPreference ?? "default",
+        failIfMajorPerformanceCaveat: o.failIfMajorPerformanceCaveat ?? false,
+    };
+    const gl = canvas.getContext("webgl2", attrs);
+    if (gl === null) {
+        throw new Error("lite-gl: WebGL2 is not supported on this canvas");
+    }
+    const parallelExt = gl.getExtension("KHR_parallel_shader_compile");
+    // Probe color-buffer-float support. `getExtension` both queries AND enables
+    // the extension, so this call is what makes float/half-float attachments
+    // renderable for the render-target module.
+    const colorBufferFloat = gl.getExtension("EXT_color_buffer_float") !== null;
+    const colorBufferHalfFloat = gl.getExtension("EXT_color_buffer_half_float") !== null;
+    const floatLinear = gl.getExtension("OES_texture_float_linear") !== null;
+    const caps = {
+        maxTextureSize: gl.getParameter(gl.MAX_TEXTURE_SIZE),
+        maxTextureUnits: gl.getParameter(gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS),
+        parallelShaderCompile: parallelExt,
+        textureFloatRender: colorBufferFloat,
+        textureFloatLinearFiltering: floatLinear,
+        // In WebGL2, EXT_color_buffer_float also makes RGBA16F renderable; the
+        // half-float-only extension is the fallback for drivers exposing just it.
+        textureHalfFloatRender: colorBufferFloat || colorBufferHalfFloat,
+        // Half-float linear filtering is core in WebGL2 (no extension needed).
+        textureHalfFloatLinearFiltering: true,
+        // NPOT textures are core in WebGL2 — mips/wrap work at any size.
+        needPOTTextures: false,
+    };
+    const engine = {
+        canvas,
+        gl,
+        caps,
+        _hsl: 1,
+        _rafId: 0,
+        _loops: [],
+        _prevNow: 0,
+        _state: createGLState(caps.maxTextureUnits),
+        _effects: [],
+        _effectCache: new Map(),
+        _textures: [],
+        _renderTargets: [],
+        _currentRenderTarget: null,
+        _buffers: [],
+        _onLost: [],
+        _onRestored: [],
+        _isLost: false,
+        _disposed: false,
+        _lostHandler: () => { },
+        _restoredHandler: () => { },
+        _wasLoopActive: false,
+        _scheduleFrame: null,
+    };
+    engine._lostHandler = (e) => handleContextLost(engine, e);
+    engine._restoredHandler = () => handleContextRestored(engine);
+    canvas.addEventListener("webglcontextlost", engine._lostHandler, false);
+    canvas.addEventListener("webglcontextrestored", engine._restoredHandler, false);
+    return engine;
+}
+/** Stops the render loop, removes DOM listeners, releases all known effects
+ *  and textures, then marks the context disposed. The browser-owned canvas
+ *  is left intact. */
+export function disposeGLEngine(engine) {
+    if (engine._disposed) {
+        return;
+    }
+    engine._disposed = true;
+    if (engine._rafId !== 0) {
+        cancelAnimationFrame(engine._rafId);
+        engine._rafId = 0;
+    }
+    engine._loops.length = 0;
+    engine.canvas.removeEventListener("webglcontextlost", engine._lostHandler, false);
+    engine.canvas.removeEventListener("webglcontextrestored", engine._restoredHandler, false);
+    const gl = engine.gl;
+    // Iterate snapshots — the dispose paths splice into the registries.
+    const effects = engine._effects.slice();
+    for (const eff of effects) {
+        if (!eff._disposed) {
+            eff._disposed = true;
+            eff.isReady = false;
+            gl.deleteProgram(eff.program);
+            gl.deleteShader(eff._vs);
+            gl.deleteShader(eff._fs);
+        }
+    }
+    engine._effects.length = 0;
+    engine._effectCache.clear();
+    const textures = engine._textures.slice();
+    for (const tex of textures) {
+        if (!tex._disposed) {
+            tex._disposed = true;
+            gl.deleteTexture(tex.handle);
+        }
+    }
+    engine._textures.length = 0;
+    // Render targets own their FBO + renderbuffer + color texture; free them via
+    // the per-RT closure so context.ts needs no runtime import of render-target.
+    const rts = engine._renderTargets.slice();
+    for (const rt of rts) {
+        if (!rt._disposed) {
+            rt._disposed = true;
+            rt._deleteGpu(gl);
+        }
+    }
+    engine._renderTargets.length = 0;
+    // Mesh vertex/index buffers own a single GL buffer each; free via closure.
+    const buffers = engine._buffers.slice();
+    for (const buf of buffers) {
+        if (!buf._disposed) {
+            buf._disposed = true;
+            buf._deleteGpu(gl);
+        }
+    }
+    engine._buffers.length = 0;
+    resetGLState(engine._state);
+    engine._currentRenderTarget = null;
+    engine._onLost.length = 0;
+    engine._onRestored.length = 0;
+}
+/** Match drawing-buffer size to (clientSize × devicePixelRatio / _hsl). No-op
+ *  if size already matches. Never touches viewport — `setViewport` owns that. */
+export function resizeGLEngine(engine) {
+    if (engine._disposed || engine._isLost) {
+        return;
+    }
+    const canvas = engine.canvas;
+    // An OffscreenCanvas has no CSS box (no clientWidth/clientHeight); it is sized
+    // explicitly via setGLEngineSize, so CSS-derived auto-resize is a no-op for it.
+    if (!("clientWidth" in canvas)) {
+        return;
+    }
+    const dpr = typeof devicePixelRatio === "number" ? devicePixelRatio : 1;
+    const w = Math.max(1, Math.floor((canvas.clientWidth * dpr) / engine._hsl));
+    const h = Math.max(1, Math.floor((canvas.clientHeight * dpr) / engine._hsl));
+    if (canvas.width !== w) {
+        canvas.width = w;
+    }
+    if (canvas.height !== h) {
+        canvas.height = h;
+    }
+}
+/**
+ * Set the drawing-buffer size to an EXPLICIT width/height in physical pixels
+ * (each divided by `_hsl`), independent of the canvas client/CSS size — the
+ * counterpart of Babylon's `ThinEngine.setSize`. Use when the render resolution
+ * is computed directly (e.g. animation dimensions × scale × dpr) rather than
+ * derived from CSS layout via {@link resizeGLEngine}. No-op on a disposed
+ * engine. Never touches the viewport — `setViewport` owns that.
+ *
+ * @param engine - The engine to resize.
+ * @param width - Target drawing-buffer width in physical pixels.
+ * @param height - Target drawing-buffer height in physical pixels.
+ */
+export function setGLEngineSize(engine, width, height) {
+    if (engine._disposed) {
+        return;
+    }
+    const canvas = engine.canvas;
+    const w = Math.max(1, Math.floor(width / engine._hsl));
+    const h = Math.max(1, Math.floor(height / engine._hsl));
+    if (canvas.width !== w) {
+        canvas.width = w;
+    }
+    if (canvas.height !== h) {
+        canvas.height = h;
+    }
+}
+/**
+ * Invalidate lite-gl's cached GL state so the next state-setting call in each
+ * category (program / buffer / texture / VAO / framebuffer bindings, blend,
+ * depth, stencil, scissor, color-mask, viewport, unpack) is re-issued instead
+ * of elided.
+ *
+ * Use this when a host application that SHARES this WebGL2 context mutates raw
+ * `gl.*` state outside lite-gl — e.g. a save/restore wrapper that resets the
+ * context to GL defaults around each render scope, or any interop layer that
+ * issues GL calls directly. Without it, lite-gl's redundant-call elision would
+ * skip the state changes needed to re-establish the scope, producing corrupted
+ * output. Owned GPU resources (the shared quad, render targets, meshes,
+ * effects, textures) are preserved — only the cached "current GL state" is
+ * reset. Mirrors Babylon's `Engine.wipeCaches()`.
+ *
+ * No-op while the context is lost or the engine is disposed.
+ */
+export function wipeGLStateCache(engine) {
+    if (engine._disposed || engine._isLost) {
+        return;
+    }
+    resetGLStateCache(engine._state);
+}
+/** Drawing-buffer width in physical pixels (`canvas.width`). */
+export function getRenderWidth(engine) {
+    return engine.canvas.width;
+}
+/** Drawing-buffer height in physical pixels (`canvas.height`). */
+export function getRenderHeight(engine) {
+    return engine.canvas.height;
+}
+/** Current hardware-scaling factor — drawing-buffer = clientSize × dpr / level. */
+export function getHardwareScalingLevel(engine) {
+    return engine._hsl;
+}
+/** Updates the hardware-scaling factor and triggers a resize. */
+export function setHardwareScalingLevel(engine, level) {
+    if (level <= 0 || !isFinite(level)) {
+        return;
+    }
+    engine._hsl = level;
+    resizeGLEngine(engine);
+}
+/** The backing canvas element (an `HTMLCanvasElement`, or an `OffscreenCanvas`
+ *  for worker render paths). */
+export function getRenderingCanvas(engine) {
+    return engine.canvas;
+}
+/** Register a `webglcontextlost` callback. Duplicate registrations are ignored. */
+export function onContextLost(engine, cb) {
+    if (engine._onLost.indexOf(cb) === -1) {
+        engine._onLost.push(cb);
+    }
+}
+/** Remove a previously-registered context-lost callback. */
+export function offContextLost(engine, cb) {
+    const i = engine._onLost.indexOf(cb);
+    if (i !== -1) {
+        engine._onLost.splice(i, 1);
+    }
+}
+/** Register a `webglcontextrestored` callback. Duplicate registrations are ignored. */
+export function onContextRestored(engine, cb) {
+    if (engine._onRestored.indexOf(cb) === -1) {
+        engine._onRestored.push(cb);
+    }
+}
+/** Remove a previously-registered context-restored callback. */
+export function offContextRestored(engine, cb) {
+    const i = engine._onRestored.indexOf(cb);
+    if (i !== -1) {
+        engine._onRestored.splice(i, 1);
+    }
+}
+/* ─────────────────────────  internal: loss / restore  ───────────────────── */
+function handleContextLost(engine, e) {
+    // Opt-in to restore. Without preventDefault() the browser will NOT fire
+    // webglcontextrestored later.
+    e.preventDefault();
+    if (engine._isLost || engine._disposed) {
+        return;
+    }
+    engine._isLost = true;
+    engine._wasLoopActive = engine._rafId !== 0;
+    if (engine._rafId !== 0) {
+        cancelAnimationFrame(engine._rafId);
+        engine._rafId = 0;
+    }
+    resetGLState(engine._state);
+    engine._currentRenderTarget = null;
+    for (const eff of engine._effects) {
+        eff.isReady = false;
+        eff._samplersAssigned = false;
+        eff.uniformLocations = {};
+        eff.attributeLocations = {};
+        // Clear value caches so the first frame after restore re-uploads
+        // every uniform into the freshly-linked program.
+        clearObject(eff._lastF1);
+        clearObject(eff._lastVec);
+        clearObject(eff._lastI1);
+        // Do NOT gl.deleteProgram — handle is already dead per WebGL spec.
+    }
+    for (const tex of engine._textures) {
+        tex._wasReady = tex.isReady;
+        tex.isReady = false;
+    }
+    const cbs = engine._onLost.slice();
+    for (const cb of cbs) {
+        try {
+            cb();
+        }
+        catch (err) {
+            console.error("lite-gl: onLost callback threw", err);
+        }
+    }
+}
+function handleContextRestored(engine) {
+    if (engine._disposed) {
+        return;
+    }
+    for (const eff of engine._effects) {
+        if (!eff._disposed) {
+            eff._restore(engine);
+        }
+    }
+    for (const tex of engine._textures) {
+        if (!tex._disposed) {
+            const newHandle = engine.gl.createTexture();
+            if (newHandle !== null) {
+                tex.handle = newHandle;
+                tex._upload(engine);
+                tex.isReady = tex._wasReady;
+            }
+        }
+    }
+    // Clear the lost flag BEFORE the render-target / buffer rebuilds: their
+    // `_restore` closures route through the same guarded build/upload paths used
+    // at create time (which no-op while `_isLost`), whereas the effect / texture
+    // replay above is unguarded and unaffected by the flag's value.
+    engine._isLost = false;
+    // Render targets rebuild their own color texture + FBO + renderbuffer AFTER
+    // the standalone texture replay above (an RT's color texture is owned by the
+    // RT, not the `_textures` registry).
+    for (const rt of engine._renderTargets) {
+        if (!rt._disposed) {
+            rt._restore(engine);
+        }
+    }
+    // Mesh buffers re-upload their retained CPU data into fresh GL buffers.
+    for (const buf of engine._buffers) {
+        if (!buf._disposed) {
+            buf._restore(engine);
+        }
+    }
+    if (engine._wasLoopActive && engine._loops.length > 0 && engine._scheduleFrame !== null) {
+        engine._scheduleFrame(engine);
+    }
+    const cbs = engine._onRestored.slice();
+    for (const cb of cbs) {
+        try {
+            cb();
+        }
+        catch (err) {
+            console.error("lite-gl: onRestored callback threw", err);
+        }
+    }
+}
+function clearObject(o) {
+    for (const key in o) {
+        delete o[key];
+    }
+}
+//# sourceMappingURL=context.js.map

package/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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","sourcesContent":["import type { GLEffect } from \"./effect.js\";\nimport type { GLTexture } from \"./texture.js\";\nimport type { GLRenderTarget } from \"./render-target.js\";\nimport { createGLState, resetGLState, resetGLStateCache, type GLState } from \"./state.js\";\n\n/**\n * Minimal shape of a context-restorable GL buffer (vertex / index), kept local\n * to this module so the public `GLEngineContext` type carries no dependency on\n * the tree-shakeable `mesh` entry. `mesh.ts`'s `GLVertexBuffer` /\n * `GLIndexBuffer` satisfy it structurally.\n * @internal\n */\nexport interface GLManagedBuffer {\n    handle: WebGLBuffer;\n    /** @internal */\n    _disposed: boolean;\n    /** @internal */\n    _deleteGpu: (gl: WebGL2RenderingContext) => void;\n    /** @internal */\n    _restore: (engine: GLEngineContext) => void;\n}\n\n/** Constructor options forwarded to `canvas.getContext('webgl2', …)`. */\nexport interface GLEngineOptions {\n    /** Default: true. */\n    alpha?: boolean;\n    /** Default: true. */\n    premultipliedAlpha?: boolean;\n    /** Default: false. */\n    antialias?: boolean;\n    /** Default: false. */\n    preserveDrawingBuffer?: boolean;\n    /** Default: false — disabled for fullscreen-quad workloads. */\n    depth?: boolean;\n    /** Default: false. */\n    stencil?: boolean;\n    /** Default: \"default\". */\n    powerPreference?: WebGLPowerPreference;\n    /** Default: false. */\n    failIfMajorPerformanceCaveat?: boolean;\n}\n\n/** Read-only WebGL2 capability limits, queried once at context creation. */\nexport interface GLEngineCaps {\n    /** `gl.MAX_TEXTURE_SIZE` — largest supported texture dimension, in texels. */\n    readonly maxTextureSize: number;\n    /** `gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS` — number of sampler binding slots. */\n    readonly maxTextureUnits: number;\n    /** The `KHR_parallel_shader_compile` extension used for async link polling,\n     *  or null when unsupported — linking is then treated as synchronous. */\n    readonly parallelShaderCompile: { COMPLETION_STATUS_KHR: number } | null;\n    /** True when 32-bit float color attachments are renderable\n     *  (`EXT_color_buffer_float`). Mirrors Babylon's `caps.textureFloatRender`. */\n    readonly textureFloatRender: boolean;\n    /** True when 32-bit float textures support linear filtering\n     *  (`OES_texture_float_linear`). Mirrors `caps.textureFloatLinearFiltering`. */\n    readonly textureFloatLinearFiltering: boolean;\n    /** True when 16-bit half-float color attachments are renderable\n     *  (`EXT_color_buffer_float` or `EXT_color_buffer_half_float`). Mirrors\n     *  `caps.textureHalfFloatRender`. */\n    readonly textureHalfFloatRender: boolean;\n    /** Half-float linear filtering — always `true` in WebGL2 (it is core).\n     *  Kept as a field to mirror Babylon's `caps.textureHalfFloatLinearFiltering`. */\n    readonly textureHalfFloatLinearFiltering: boolean;\n    /** Whether non-power-of-two textures need POT dimensions for mips / wrap.\n     *  Always `false` in WebGL2 (NPOT is core). Mirrors `engine.needPOTTextures`. */\n    readonly needPOTTextures: boolean;\n}\n\n/**\n * Pure-state handle for a WebGL2 canvas + its cached GL state.\n *\n * INVARIANT: consumers MUST NOT mutate GL state directly through `engine.gl`.\n * Doing so silently corrupts the cache in `_state`. The package owns every\n * GL call. (`engine.gl` is exposed only so downstream code that already has the\n * pattern of poking `engine._gl.getExtension(...)` can do that, but must NOT\n * call `bindTexture`/`useProgram`/`bindBuffer`/`viewport`/etc.)\n */\nexport interface GLEngineContext {\n    /** The canvas the WebGL2 context was acquired from. An `OffscreenCanvas` is\n     *  supported for worker render paths (e.g. the Lottie player); it has no CSS\n     *  box, so it must be sized explicitly via `setGLEngineSize` rather than the\n     *  CSS-derived `resizeGLEngine`. */\n    readonly canvas: HTMLCanvasElement | OffscreenCanvas;\n    /** The raw WebGL2 context. Do NOT mutate GL state through it — see the\n     *  type-level invariant above; the package owns every state-changing call. */\n    readonly gl: WebGL2RenderingContext;\n    /** Queried capability limits for this context. */\n    readonly caps: GLEngineCaps;\n    /**\n     * Hardware-scaling-level — drawingBufferWidth = clientWidth * dpr / _hsl.\n     * @internal\n     */\n    _hsl: number;\n    /**\n     * rAF id when a render loop is active, 0 otherwise.\n     * @internal\n     */\n    _rafId: number;\n    /**\n     * Per-frame callbacks. `runRenderLoop` is a no-op if `fn` is already\n     * registered (matches Babylon `AbstractEngine.runRenderLoop`).\n     * @internal\n     */\n    _loops: ((dt: number) => void)[];\n    /**\n     * Timestamp of last frame for delta computation.\n     * @internal\n     */\n    _prevNow: number;\n    /**\n     * Cached GL state. See §4 of 00-lite-gl.md.\n     * @internal\n     */\n    _state: GLState;\n    /**\n     * Live effect registry — populated by `createEffect`, removed by\n     * `disposeEffect`. Used by the context-restored protocol to rebuild\n     * programs.\n     * @internal\n     */\n    _effects: GLEffect[];\n    /**\n     * Per-engine effect cache keyed by source descriptor (vertex+fragment\n     * source, defines, attribute/uniform/sampler names). `createEffect` returns\n     * (and ref-counts) the cached `GLEffect` when an identical descriptor is\n     * requested, so identical shaders share ONE WebGLProgram — letting\n     * `useEffect`'s current-program cache elide redundant `gl.useProgram`.\n     * @internal\n     */\n    _effectCache: Map<string, GLEffect>;\n    /**\n     * Live texture registry — populated by `createRawTexture` /\n     * `loadTexture2D` / `createHtmlElementTexture`. Used by the\n     * context-restored protocol to replay uploads.\n     * @internal\n     */\n    _textures: GLTexture[];\n    /**\n     * Live render-target registry — populated by `createRenderTarget`. Used by\n     * the context-restored protocol to rebuild framebuffers + attachments after\n     * their color textures have been replayed. Empty (and tree-shaken) when the\n     * render-target module is unused.\n     * @internal\n     */\n    _renderTargets: GLRenderTarget[];\n    /**\n     * The render target currently bound for drawing (`bindRenderTarget`), or\n     * `null` for the default canvas framebuffer. Tracked so that leaving a\n     * mipmapped target (`bindRenderTarget(engine, null)` or switching to\n     * another target) can regenerate its mip chain — mirroring Babylon's\n     * auto-mipmap on `unBindFramebuffer`. Reset to `null` on context-lost.\n     * @internal\n     */\n    _currentRenderTarget: GLRenderTarget | null;\n    /**\n     * Live vertex / index buffer registry — populated by `createVertexBuffer` /\n     * `createIndexBuffer`. Used by the context-restored protocol to re-upload\n     * the retained CPU data into fresh GL buffers. Empty (and tree-shaken) when\n     * the mesh module is unused.\n     * @internal\n     */\n    _buffers: GLManagedBuffer[];\n    /** @internal */\n    _onLost: (() => void)[];\n    /** @internal */\n    _onRestored: (() => void)[];\n    /**\n     * True between `webglcontextlost` and `webglcontextrestored`. While\n     * true, every `setEffect*` / `bindTexture` / `drawEffect` is a no-op.\n     * @internal\n     */\n    _isLost: boolean;\n    /**\n     * True once the context has been disposed; subsequent calls become no-ops.\n     * @internal\n     */\n    _disposed: boolean;\n    /**\n     * DOM handlers — retained so dispose can `removeEventListener` them.\n     * @internal\n     */\n    _lostHandler: (e: Event) => void;\n    /** @internal */\n    _restoredHandler: () => void;\n    /**\n     * True when a render loop was active at the moment of `webglcontextlost`,\n     * so we can resume it from the restored handler.\n     * @internal\n     */\n    _wasLoopActive: boolean;\n    /**\n     * Installed by `runRenderLoop` on first call. Lets the context-restored\n     * handler resume a loop without a circular runtime import from render-loop.\n     * Null if the render-loop module is tree-shaken out.\n     * @internal\n     */\n    _scheduleFrame: ((engine: GLEngineContext) => void) | null;\n}\n\n/** Acquire a WebGL2 context on the canvas and build the pure-state handle.\n *  Accepts an `HTMLCanvasElement` or an `OffscreenCanvas` (worker render paths —\n *  e.g. the Lottie player — which size the drawing buffer via `setGLEngineSize`).\n *  Throws if WebGL2 is unsupported. */\nexport function createGLEngine(canvas: HTMLCanvasElement | OffscreenCanvas, options?: GLEngineOptions): GLEngineContext {\n    const o = options ?? {};\n    const attrs: WebGLContextAttributes = {\n        alpha: o.alpha ?? true,\n        premultipliedAlpha: o.premultipliedAlpha ?? true,\n        antialias: o.antialias ?? false,\n        preserveDrawingBuffer: o.preserveDrawingBuffer ?? false,\n        depth: o.depth ?? false,\n        stencil: o.stencil ?? false,\n        powerPreference: o.powerPreference ?? \"default\",\n        failIfMajorPerformanceCaveat: o.failIfMajorPerformanceCaveat ?? false,\n    };\n    const gl = canvas.getContext(\"webgl2\", attrs) as WebGL2RenderingContext | null;\n    if (gl === null) {\n        throw new Error(\"lite-gl: WebGL2 is not supported on this canvas\");\n    }\n\n    const parallelExt = gl.getExtension(\"KHR_parallel_shader_compile\") as { COMPLETION_STATUS_KHR: number } | null;\n    // Probe color-buffer-float support. `getExtension` both queries AND enables\n    // the extension, so this call is what makes float/half-float attachments\n    // renderable for the render-target module.\n    const colorBufferFloat = gl.getExtension(\"EXT_color_buffer_float\") !== null;\n    const colorBufferHalfFloat = gl.getExtension(\"EXT_color_buffer_half_float\") !== null;\n    const floatLinear = gl.getExtension(\"OES_texture_float_linear\") !== null;\n    const caps: GLEngineCaps = {\n        maxTextureSize: gl.getParameter(gl.MAX_TEXTURE_SIZE) as number,\n        maxTextureUnits: gl.getParameter(gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS) as number,\n        parallelShaderCompile: parallelExt,\n        textureFloatRender: colorBufferFloat,\n        textureFloatLinearFiltering: floatLinear,\n        // In WebGL2, EXT_color_buffer_float also makes RGBA16F renderable; the\n        // half-float-only extension is the fallback for drivers exposing just it.\n        textureHalfFloatRender: colorBufferFloat || colorBufferHalfFloat,\n        // Half-float linear filtering is core in WebGL2 (no extension needed).\n        textureHalfFloatLinearFiltering: true,\n        // NPOT textures are core in WebGL2 — mips/wrap work at any size.\n        needPOTTextures: false,\n    };\n\n    const engine: GLEngineContext = {\n        canvas,\n        gl,\n        caps,\n        _hsl: 1,\n        _rafId: 0,\n        _loops: [],\n        _prevNow: 0,\n        _state: createGLState(caps.maxTextureUnits),\n        _effects: [],\n        _effectCache: new Map(),\n        _textures: [],\n        _renderTargets: [],\n        _currentRenderTarget: null,\n        _buffers: [],\n        _onLost: [],\n        _onRestored: [],\n        _isLost: false,\n        _disposed: false,\n        _lostHandler: () => {},\n        _restoredHandler: () => {},\n        _wasLoopActive: false,\n        _scheduleFrame: null,\n    };\n\n    engine._lostHandler = (e: Event) => handleContextLost(engine, e);\n    engine._restoredHandler = () => handleContextRestored(engine);\n    canvas.addEventListener(\"webglcontextlost\", engine._lostHandler as EventListener, false);\n    canvas.addEventListener(\"webglcontextrestored\", engine._restoredHandler, false);\n\n    return engine;\n}\n\n/** Stops the render loop, removes DOM listeners, releases all known effects\n *  and textures, then marks the context disposed. The browser-owned canvas\n *  is left intact. */\nexport function disposeGLEngine(engine: GLEngineContext): void {\n    if (engine._disposed) {\n        return;\n    }\n    engine._disposed = true;\n    if (engine._rafId !== 0) {\n        cancelAnimationFrame(engine._rafId);\n        engine._rafId = 0;\n    }\n    engine._loops.length = 0;\n    engine.canvas.removeEventListener(\"webglcontextlost\", engine._lostHandler as EventListener, false);\n    engine.canvas.removeEventListener(\"webglcontextrestored\", engine._restoredHandler, false);\n\n    const gl = engine.gl;\n    // Iterate snapshots — the dispose paths splice into the registries.\n    const effects = engine._effects.slice();\n    for (const eff of effects) {\n        if (!eff._disposed) {\n            eff._disposed = true;\n            eff.isReady = false;\n            gl.deleteProgram(eff.program);\n            gl.deleteShader(eff._vs);\n            gl.deleteShader(eff._fs);\n        }\n    }\n    engine._effects.length = 0;\n    engine._effectCache.clear();\n    const textures = engine._textures.slice();\n    for (const tex of textures) {\n        if (!tex._disposed) {\n            tex._disposed = true;\n            gl.deleteTexture(tex.handle);\n        }\n    }\n    engine._textures.length = 0;\n    // Render targets own their FBO + renderbuffer + color texture; free them via\n    // the per-RT closure so context.ts needs no runtime import of render-target.\n    const rts = engine._renderTargets.slice();\n    for (const rt of rts) {\n        if (!rt._disposed) {\n            rt._disposed = true;\n            rt._deleteGpu(gl);\n        }\n    }\n    engine._renderTargets.length = 0;\n\n    // Mesh vertex/index buffers own a single GL buffer each; free via closure.\n    const buffers = engine._buffers.slice();\n    for (const buf of buffers) {\n        if (!buf._disposed) {\n            buf._disposed = true;\n            buf._deleteGpu(gl);\n        }\n    }\n    engine._buffers.length = 0;\n\n    resetGLState(engine._state);\n    engine._currentRenderTarget = null;\n    engine._onLost.length = 0;\n    engine._onRestored.length = 0;\n}\n\n/** Match drawing-buffer size to (clientSize × devicePixelRatio / _hsl). No-op\n *  if size already matches. Never touches viewport — `setViewport` owns that. */\nexport function resizeGLEngine(engine: GLEngineContext): void {\n    if (engine._disposed || engine._isLost) {\n        return;\n    }\n    const canvas = engine.canvas;\n    // An OffscreenCanvas has no CSS box (no clientWidth/clientHeight); it is sized\n    // explicitly via setGLEngineSize, so CSS-derived auto-resize is a no-op for it.\n    if (!(\"clientWidth\" in canvas)) {\n        return;\n    }\n    const dpr = typeof devicePixelRatio === \"number\" ? devicePixelRatio : 1;\n    const w = Math.max(1, Math.floor((canvas.clientWidth * dpr) / engine._hsl));\n    const h = Math.max(1, Math.floor((canvas.clientHeight * dpr) / engine._hsl));\n    if (canvas.width !== w) {\n        canvas.width = w;\n    }\n    if (canvas.height !== h) {\n        canvas.height = h;\n    }\n}\n\n/**\n * Set the drawing-buffer size to an EXPLICIT width/height in physical pixels\n * (each divided by `_hsl`), independent of the canvas client/CSS size — the\n * counterpart of Babylon's `ThinEngine.setSize`. Use when the render resolution\n * is computed directly (e.g. animation dimensions × scale × dpr) rather than\n * derived from CSS layout via {@link resizeGLEngine}. No-op on a disposed\n * engine. Never touches the viewport — `setViewport` owns that.\n *\n * @param engine - The engine to resize.\n * @param width - Target drawing-buffer width in physical pixels.\n * @param height - Target drawing-buffer height in physical pixels.\n */\nexport function setGLEngineSize(engine: GLEngineContext, width: number, height: number): void {\n    if (engine._disposed) {\n        return;\n    }\n    const canvas = engine.canvas;\n    const w = Math.max(1, Math.floor(width / engine._hsl));\n    const h = Math.max(1, Math.floor(height / engine._hsl));\n    if (canvas.width !== w) {\n        canvas.width = w;\n    }\n    if (canvas.height !== h) {\n        canvas.height = h;\n    }\n}\n\n/**\n * Invalidate lite-gl's cached GL state so the next state-setting call in each\n * category (program / buffer / texture / VAO / framebuffer bindings, blend,\n * depth, stencil, scissor, color-mask, viewport, unpack) is re-issued instead\n * of elided.\n *\n * Use this when a host application that SHARES this WebGL2 context mutates raw\n * `gl.*` state outside lite-gl — e.g. a save/restore wrapper that resets the\n * context to GL defaults around each render scope, or any interop layer that\n * issues GL calls directly. Without it, lite-gl's redundant-call elision would\n * skip the state changes needed to re-establish the scope, producing corrupted\n * output. Owned GPU resources (the shared quad, render targets, meshes,\n * effects, textures) are preserved — only the cached \"current GL state\" is\n * reset. Mirrors Babylon's `Engine.wipeCaches()`.\n *\n * No-op while the context is lost or the engine is disposed.\n */\nexport function wipeGLStateCache(engine: GLEngineContext): void {\n    if (engine._disposed || engine._isLost) {\n        return;\n    }\n    resetGLStateCache(engine._state);\n}\n\n/** Drawing-buffer width in physical pixels (`canvas.width`). */\nexport function getRenderWidth(engine: GLEngineContext): number {\n    return engine.canvas.width;\n}\n\n/** Drawing-buffer height in physical pixels (`canvas.height`). */\nexport function getRenderHeight(engine: GLEngineContext): number {\n    return engine.canvas.height;\n}\n\n/** Current hardware-scaling factor — drawing-buffer = clientSize × dpr / level. */\nexport function getHardwareScalingLevel(engine: GLEngineContext): number {\n    return engine._hsl;\n}\n\n/** Updates the hardware-scaling factor and triggers a resize. */\nexport function setHardwareScalingLevel(engine: GLEngineContext, level: number): void {\n    if (level <= 0 || !isFinite(level)) {\n        return;\n    }\n    engine._hsl = level;\n    resizeGLEngine(engine);\n}\n\n/** The backing canvas element (an `HTMLCanvasElement`, or an `OffscreenCanvas`\n *  for worker render paths). */\nexport function getRenderingCanvas(engine: GLEngineContext): HTMLCanvasElement | OffscreenCanvas {\n    return engine.canvas;\n}\n\n/** Register a `webglcontextlost` callback. Duplicate registrations are ignored. */\nexport function onContextLost(engine: GLEngineContext, cb: () => void): void {\n    if (engine._onLost.indexOf(cb) === -1) {\n        engine._onLost.push(cb);\n    }\n}\n\n/** Remove a previously-registered context-lost callback. */\nexport function offContextLost(engine: GLEngineContext, cb: () => void): void {\n    const i = engine._onLost.indexOf(cb);\n    if (i !== -1) {\n        engine._onLost.splice(i, 1);\n    }\n}\n\n/** Register a `webglcontextrestored` callback. Duplicate registrations are ignored. */\nexport function onContextRestored(engine: GLEngineContext, cb: () => void): void {\n    if (engine._onRestored.indexOf(cb) === -1) {\n        engine._onRestored.push(cb);\n    }\n}\n\n/** Remove a previously-registered context-restored callback. */\nexport function offContextRestored(engine: GLEngineContext, cb: () => void): void {\n    const i = engine._onRestored.indexOf(cb);\n    if (i !== -1) {\n        engine._onRestored.splice(i, 1);\n    }\n}\n\n/* ─────────────────────────  internal: loss / restore  ───────────────────── */\n\nfunction handleContextLost(engine: GLEngineContext, e: Event): void {\n    // Opt-in to restore. Without preventDefault() the browser will NOT fire\n    // webglcontextrestored later.\n    e.preventDefault();\n    if (engine._isLost || engine._disposed) {\n        return;\n    }\n    engine._isLost = true;\n    engine._wasLoopActive = engine._rafId !== 0;\n    if (engine._rafId !== 0) {\n        cancelAnimationFrame(engine._rafId);\n        engine._rafId = 0;\n    }\n    resetGLState(engine._state);\n    engine._currentRenderTarget = null;\n    for (const eff of engine._effects) {\n        eff.isReady = false;\n        eff._samplersAssigned = false;\n        eff.uniformLocations = {};\n        eff.attributeLocations = {};\n        // Clear value caches so the first frame after restore re-uploads\n        // every uniform into the freshly-linked program.\n        clearObject(eff._lastF1);\n        clearObject(eff._lastVec);\n        clearObject(eff._lastI1);\n        // Do NOT gl.deleteProgram — handle is already dead per WebGL spec.\n    }\n    for (const tex of engine._textures) {\n        tex._wasReady = tex.isReady;\n        tex.isReady = false;\n    }\n    const cbs = engine._onLost.slice();\n    for (const cb of cbs) {\n        try {\n            cb();\n        } catch (err) {\n            console.error(\"lite-gl: onLost callback threw\", err);\n        }\n    }\n}\n\nfunction handleContextRestored(engine: GLEngineContext): void {\n    if (engine._disposed) {\n        return;\n    }\n    for (const eff of engine._effects) {\n        if (!eff._disposed) {\n            eff._restore(engine);\n        }\n    }\n    for (const tex of engine._textures) {\n        if (!tex._disposed) {\n            const newHandle = engine.gl.createTexture();\n            if (newHandle !== null) {\n                tex.handle = newHandle;\n                tex._upload(engine);\n                tex.isReady = tex._wasReady;\n            }\n        }\n    }\n    // Clear the lost flag BEFORE the render-target / buffer rebuilds: their\n    // `_restore` closures route through the same guarded build/upload paths used\n    // at create time (which no-op while `_isLost`), whereas the effect / texture\n    // replay above is unguarded and unaffected by the flag's value.\n    engine._isLost = false;\n    // Render targets rebuild their own color texture + FBO + renderbuffer AFTER\n    // the standalone texture replay above (an RT's color texture is owned by the\n    // RT, not the `_textures` registry).\n    for (const rt of engine._renderTargets) {\n        if (!rt._disposed) {\n            rt._restore(engine);\n        }\n    }\n    // Mesh buffers re-upload their retained CPU data into fresh GL buffers.\n    for (const buf of engine._buffers) {\n        if (!buf._disposed) {\n            buf._restore(engine);\n        }\n    }\n    if (engine._wasLoopActive && engine._loops.length > 0 && engine._scheduleFrame !== null) {\n        engine._scheduleFrame(engine);\n    }\n    const cbs = engine._onRestored.slice();\n    for (const cb of cbs) {\n        try {\n            cb();\n        } catch (err) {\n            console.error(\"lite-gl: onRestored callback threw\", err);\n        }\n    }\n}\n\nfunction clearObject(o: { [k: string]: unknown }): void {\n    for (const key in o) {\n        delete o[key];\n    }\n}\n"]}