@babylonjs/lite-gl 0.1.0 → 0.2.0

package/README.md

@@ -25,17 +25,7 @@ npm install @babylonjs/lite-gl
 ## Quick start — an animated fullscreen effect
 
 ```ts
-import {
-    createGLEngine,
-    createEffectWrapper,
-    isEffectReady,
-    applyEffectWrapper,
-    drawEffect,
-    setViewport,
-    setEffectFloat,
-    runRenderLoop,
-    resizeGLEngine,
-} from "@babylonjs/lite-gl";
+import { createGLEngine, createEffectWrapper, isEffectReady, applyEffectWrapper, drawEffect, setViewport, setEffectFloat, runRenderLoop, resizeGLEngine } from "@babylonjs/lite-gl";
 
 const canvas = document.getElementById("renderCanvas") as HTMLCanvasElement;
 const engine = createGLEngine(canvas, { alpha: false });
@@ -69,23 +59,13 @@ runRenderLoop(engine, () => {
 
 ## Entry points
 
-The full public API is available from the main `@babylonjs/lite-gl` barrel.
-`/sprites`, `/html-texture`, `/render-target`, `/mesh`, `/depth-stencil`,
-`/scissor` and `/dynamic-texture` are **also** exposed as dedicated sub-entries
-for consumers who prefer an explicit import — the package is `sideEffects: false`,
-so a bundler tree-shakes away whichever features you don't use no matter which
-path you import from.
-
-| Import | Provides |
-| --- | --- |
-| `@babylonjs/lite-gl` | Everything: engine + render loop, effects & uniform setters, textures (incl. float / HDR + dynamic), the `EffectWrapper` fullscreen-quad renderer, render targets, meshes / vertex-index buffers + instancing, depth / stencil / color-mask / clear, scissor, blend modes, the sprite renderer, and HTML-element textures. |
-| `@babylonjs/lite-gl/sprites` | Just the sprite / instanced-quad renderer (`createSpriteRenderer`, `renderSprites`, `setSpriteRendererTexture`, `disposeSpriteRenderer`, `GLSprite`) — the lite-gl equivalent of Babylon's `SpriteRenderer`. |
-| `@babylonjs/lite-gl/html-texture` | Just textures backed by a `<canvas>` / `<img>` / `<video>` element (`createHtmlElementTexture`, `updateHtmlElementTexture`, `GLSamplingMode`). |
-| `@babylonjs/lite-gl/render-target` | Render-to-texture (FBO) + a ping-pong feedback helper (`createRenderTarget`, `createFloatRenderTarget`, `bindRenderTarget`, `resizeRenderTarget`, `generateRenderTargetMipMaps`, `readRenderTargetPixels`, `disposeRenderTarget`, `createPingPong`, `resizePingPong`, `disposePingPong`) — the lite-gl equivalent of Babylon's `RenderTargetTexture` / `createRenderTargetTexture`, for multi-pass and self-feedback effects. |
-| `@babylonjs/lite-gl/mesh` | Vertex / index buffers, attribute binding and instanced `drawIndexed` (`createVertexBuffer`, `updateVertexBuffer`, `createIndexBuffer`, `bindAttributes`, `drawIndexed`, …) — the lite-gl equivalent of Babylon's `VertexBuffer` / `Geometry`. |
-| `@babylonjs/lite-gl/depth-stencil` | Cached depth / stencil / cull / color-mask state + `clearEngine` (`setDepthState`, `setStencilState`, `setCullState`, `setColorMask`, `clearEngine`). |
-| `@babylonjs/lite-gl/scissor` | The cached scissor-test rectangle (`setScissor`, `disableScissor`). |
-| `@babylonjs/lite-gl/dynamic-texture` | Textures whose pixels are replayed from a retained source on context-restore (`createDynamicTexture`, `updateDynamicTexture`, `clearDynamicTextureSource`). |
+The entire public API is available from the single `@babylonjs/lite-gl` entry:
+engine + render loop, effects & uniform setters, textures (incl. float / HDR +
+dynamic), the `EffectWrapper` fullscreen-quad renderer, render targets, meshes /
+vertex-index buffers + instancing, depth / stencil / color-mask / clear, scissor,
+blend modes, the sprite renderer, and HTML-element textures. The package is
+`sideEffects: false`, so a bundler tree-shakes away whichever features you don't
+use.
 
 ### Core API (`@babylonjs/lite-gl`)
 
@@ -107,20 +87,16 @@ path you import from.
   `updateTextureWrapMode`, `createTextureFromHandle`.
 - **Dynamic textures** — `createDynamicTexture`, `updateDynamicTexture`,
   `clearDynamicTextureSource` (the retained source is replayed on context-restore).
-  Also at `@babylonjs/lite-gl/dynamic-texture`.
 - **Render targets** — `createRenderTarget` (RGBA8 FBO with a sampleable color
   `GLTexture` + optional depth / stencil renderbuffer), `createFloatRenderTarget`
   (float / half-float HDR opt-in), `bindRenderTarget` (cached, null = the canvas),
   `resizeRenderTarget`, `generateRenderTargetMipMaps`, `readRenderTargetPixels`,
   `disposeRenderTarget`, plus the `createPingPong` / `resizePingPong` /
-  `disposePingPong` feedback helper. Also at `@babylonjs/lite-gl/render-target`.
+  `disposePingPong` feedback helper.
 - **Meshes / buffers** — `createVertexBuffer`, `updateVertexBuffer`,
   `createIndexBuffer`, `bindAttributes`, `drawIndexed` (instanced), `disposeBuffer`.
-  Also at `@babylonjs/lite-gl/mesh`.
 - **Depth / stencil / scissor** — `setDepthState`, `setStencilState`,
-  `setCullState`, `setColorMask`, `clearEngine` (also at
-  `@babylonjs/lite-gl/depth-stencil`); `setScissor`, `disableScissor` (also at
-  `@babylonjs/lite-gl/scissor`).
+  `setCullState`, `setColorMask`, `clearEngine`; `setScissor`, `disableScissor`.
 - **Blend** — `setBlendMode` + `GLBlendMode` (`DISABLE` / `ADD` / `ALPHA` /
   `PREMULTIPLIED`), matching Babylon's `setAlphaMode` parameters.
 

package/apply-states.d.ts

@@ -0,0 +1 @@
+export {};

package/apply-states.js

@@ -0,0 +1,30 @@
+/**
+ * Flush the deferred blend / depth+cull / stencil / color-mask state to GL by
+ * invoking each installed per-category reconciler in order. No-op on a
+ * lost/disposed context or when nothing has been marked dirty since the last
+ * flush. Reconcilers are installed lazily by their setters, so an uninstalled
+ * category is skipped at zero cost.
+ *
+ * @param engine - The engine whose deferred state is flushed.
+ * @internal
+ */
+export function applyGLStates(engine) {
+    const s = engine._state;
+    if (engine._isLost || engine._disposed || !s.statesDirty) {
+        return;
+    }
+    if (s._flushBlend !== undefined) {
+        s._flushBlend(engine);
+    }
+    if (s._flushDepthCull !== undefined) {
+        s._flushDepthCull(engine);
+    }
+    if (s._flushStencil !== undefined) {
+        s._flushStencil(engine);
+    }
+    if (s._flushColorMask !== undefined) {
+        s._flushColorMask(engine);
+    }
+    s.statesDirty = false;
+}
+//# sourceMappingURL=apply-states.js.map

package/apply-states.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-states.js","sourceRoot":"","sources":["../src/apply-states.ts"],"names":[],"mappings":"AAqCA;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,MAAuB;IACjD,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;IACxB,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACvD,OAAO;IACX,CAAC;IACD,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IACD,IAAI,CAAC,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QAClC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IACD,IAAI,CAAC,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IACD,IAAI,CAAC,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QAClC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IACD,CAAC,CAAC,WAAW,GAAG,KAAK,CAAC;AAC1B,CAAC","sourcesContent":["/**\n * Deferred render-state flush dispatcher — the lite-gl counterpart of Babylon's\n * `Engine.applyStates()` (`_depthCullingState.apply` / `_alphaState.apply` /\n * `_stencilState.apply`).\n *\n * blend.ts and depth-stencil.ts setters record only the DESIRED state (the\n * `rs[RS_X + RS_DESIRED]` slots of {@link GLState.rs}), raise `statesDirty`, and\n * INSTALL their per-category reconciler onto a `_state._flush*` slot the first\n * time they run. {@link applyGLStates} then simply dispatches through whichever\n * slots are populated — it owns NO reconciliation code itself.\n *\n * Why a dispatcher (not a monolith): the reconcilers (`flushBlend` in blend.ts;\n * `flushDepthCull` / `flushStencil` / `flushColorMask` in depth-stencil.ts) are\n * reachable ONLY through the engine-state slots their setters populate, so a\n * category whose setter is absent from a scene tree-shakes its reconciler — and\n * its GL code — out of the bundle. A clear-only scene (e.g. `gl-scissor`) that\n * never touches blend/depth/stencil/color-mask therefore ships none of them;\n * `applyGLStates` collapses to four cheap \"is it installed?\" checks. The fixed\n * dispatch order (blend → depth+cull → stencil → color-mask) reproduces the\n * former monolith's GL call order exactly.\n *\n * Each reconciler still issues only the `gl.*` calls that actually change and\n * updates the actual slots in lock-step, so intra-frame churn collapses and\n * cross-frame elision is preserved, matching Babylon exactly.\n *\n * Flush sites (call `applyGLStates` immediately before the GPU op):\n *  - effect-renderer.ts `drawEffect`\n *  - sprites.ts `renderSprites`\n *  - mesh.ts `drawIndexed`\n *  - depth-stencil.ts `clearEngine` (clear respects the depth/stencil/color\n *    write masks, so they must be current first — Babylon parity)\n *\n * Kept dependency-light (type-only import of {@link GLEngineContext}) so it never\n * introduces an import cycle.\n */\nimport type { GLEngineContext } from \"./context.js\";\n\n/**\n * Flush the deferred blend / depth+cull / stencil / color-mask state to GL by\n * invoking each installed per-category reconciler in order. No-op on a\n * lost/disposed context or when nothing has been marked dirty since the last\n * flush. Reconcilers are installed lazily by their setters, so an uninstalled\n * category is skipped at zero cost.\n *\n * @param engine - The engine whose deferred state is flushed.\n * @internal\n */\nexport function applyGLStates(engine: GLEngineContext): void {\n    const s = engine._state;\n    if (engine._isLost || engine._disposed || !s.statesDirty) {\n        return;\n    }\n    if (s._flushBlend !== undefined) {\n        s._flushBlend(engine);\n    }\n    if (s._flushDepthCull !== undefined) {\n        s._flushDepthCull(engine);\n    }\n    if (s._flushStencil !== undefined) {\n        s._flushStencil(engine);\n    }\n    if (s._flushColorMask !== undefined) {\n        s._flushColorMask(engine);\n    }\n    s.statesDirty = false;\n}\n"]}

package/blend.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Blend-mode state — the WebGL counterpart of Babylon's `Engine.setAlphaMode`
+ * (presets) and `AlphaState.setAlphaBlendFunctionParameters` /
+ * `setAlphaEquationParameters` (the arbitrary separate func + equation path).
+ *
+ * The numeric {@link GLBlendMode} values intentionally match Babylon's
+ * `Constants.ALPHA_*` (`ALPHA_DISABLE = 0`, `ALPHA_ADD = 1`, `ALPHA_COMBINE = 2`,
+ * `ALPHA_PREMULTIPLIED = 7`) so a consumer can forward raw Babylon constants
+ * without a translation table.
+ *
+ * DEFERRED MODEL (matches Babylon's `AlphaState`): these setters do NOT touch
+ * `gl.*`. They record only the DESIRED blend config into the `d*` mirror fields
+ * of `GLState` and raise `statesDirty`; `applyGLStates` (apply-states.ts) flushes
+ * the diff to GL right before each draw / clear. Setting blend A then B then A
+ * with no draw in between therefore applies exactly one blend state (A), and a
+ * blend left unchanged across frames re-issues nothing.
+ *
+ * Both {@link setBlendMode} and {@link setBlendState} feed the same desired
+ * fields, so the preset and arbitrary paths can never desync.
+ */
+import { type GLEngineContext } from "./context.js";
+/**
+ * Supported blend presets. Values mirror Babylon's `Constants.ALPHA_*` so the
+ * raw Babylon integers can be passed straight through.
+ */
+export declare const GLBlendMode: {
+    /** No blending — `gl.disable(gl.BLEND)`. (`Constants.ALPHA_DISABLE`) */
+    readonly DISABLE: 0;
+    /** Additive — `blendFuncSeparate(SRC_ALPHA, ONE, ZERO, ONE)`. (`Constants.ALPHA_ADD`) */
+    readonly ADD: 1;
+    /** Standard (non-premultiplied) alpha — `blendFuncSeparate(SRC_ALPHA, ONE_MINUS_SRC_ALPHA, ONE, ONE)`. (`Constants.ALPHA_COMBINE`) */
+    readonly ALPHA: 2;
+    /** Premultiplied alpha — `blendFuncSeparate(ONE, ONE_MINUS_SRC_ALPHA, ONE, ONE)`. (`Constants.ALPHA_PREMULTIPLIED`) */
+    readonly PREMULTIPLIED: 7;
+};
+/** One of the {@link GLBlendMode} preset values (`0`, `1`, `2` or `7`). */
+export type GLBlendMode = (typeof GLBlendMode)[keyof typeof GLBlendMode];
+/**
+ * Blend equation presets — the values WebGL2 accepts for
+ * `gl.blendEquationSeparate`. Numeric values equal the GL enums so raw GL
+ * integers (or Babylon's identical `Constants.GL_ALPHA_EQUATION_*`) pass
+ * straight through.
+ */
+export declare const GLBlendEquation: {
+    /** `src + dst` (the GL default). */
+    readonly ADD: 32774;
+    /** `src - dst`. */
+    readonly SUBTRACT: 32778;
+    /** `dst - src`. */
+    readonly REVERSE_SUBTRACT: 32779;
+    /** `min(src, dst)`. */
+    readonly MIN: 32775;
+    /** `max(src, dst)`. */
+    readonly MAX: 32776;
+};
+/** One of the {@link GLBlendEquation} preset values. */
+export type GLBlendEquation = (typeof GLBlendEquation)[keyof typeof GLBlendEquation];
+/**
+ * Arbitrary separate-channel blend configuration — the lite-gl equivalent of
+ * Babylon's `AlphaState.setAlphaBlendFunctionParameters` +
+ * `setAlphaEquationParameters`. All factor / equation fields are raw WebGL2
+ * enums (`gl.ONE`, `gl.SRC_ALPHA`, `gl.MIN`, …); use {@link GLBlendEquation} for
+ * the equations if you prefer named presets.
+ */
+export interface GLBlendState {
+    /** RGB source factor (`gl.blendFuncSeparate` arg 1). */
+    srcRGB: GLenum;
+    /** RGB destination factor (`gl.blendFuncSeparate` arg 2). */
+    dstRGB: GLenum;
+    /** Alpha source factor (`gl.blendFuncSeparate` arg 3). */
+    srcAlpha: GLenum;
+    /** Alpha destination factor (`gl.blendFuncSeparate` arg 4). */
+    dstAlpha: GLenum;
+    /** RGB blend equation. Defaults to `FUNC_ADD`. */
+    equationRGB?: GLenum;
+    /** Alpha blend equation. Defaults to `FUNC_ADD`. */
+    equationAlpha?: GLenum;
+}
+/**
+ * Set the GL blend state to match Babylon's `setAlphaMode(mode)` exactly.
+ *
+ * | Mode               | `gl.blendFuncSeparate(srcRGB, dstRGB, srcA, dstA)`          |
+ * |--------------------|------------------------------------------------------------|
+ * | `DISABLE` (0)      | — (`gl.disable(gl.BLEND)`)                                  |
+ * | `ADD` (1)          | `SRC_ALPHA, ONE, ZERO, ONE`                                 |
+ * | `ALPHA` (2)        | `SRC_ALPHA, ONE_MINUS_SRC_ALPHA, ONE, ONE`                  |
+ * | `PREMULTIPLIED` (7)| `ONE, ONE_MINUS_SRC_ALPHA, ONE, ONE`                        |
+ *
+ * No-op when the context is lost or disposed.
+ *
+ * @param engine - The engine whose GL blend state is updated.
+ * @param mode - The {@link GLBlendMode} preset to apply.
+ */
+export declare function setBlendMode(engine: GLEngineContext, mode: GLBlendMode): void;
+/**
+ * Enable blending with an arbitrary separate-channel function and equation —
+ * the lite-gl equivalent of Babylon's `AlphaState` with
+ * `setAlphaBlendFunctionParameters` + `setAlphaEquationParameters`.
+ *
+ * Supports every WebGL2 blend equation, including `MIN`, `MAX`,
+ * `FUNC_SUBTRACT` and `FUNC_REVERSE_SUBTRACT` (used by ShapeBuilder's darken /
+ * cutout blend modes). Records the desired config (flushed by `applyGLStates`
+ * before the next draw); at flush time the enable flag, the equation and the func
+ * are each cached independently, so a redundant state is fully elided and only
+ * the call whose params changed is re-issued — mirroring Babylon's `AlphaState`
+ * dirty flags. Because GL keeps the equation + func across `gl.disable(BLEND)`,
+ * re-enabling with unchanged params re-issues neither.
+ *
+ * No-op when the context is lost or disposed.
+ *
+ * @param engine - The engine whose desired blend state is updated.
+ * @param state - The separate-channel blend factors + equations to apply.
+ */
+export declare function setBlendState(engine: GLEngineContext, state: GLBlendState): void;
+/**
+ * Disable blending — the equivalent of Babylon's `AlphaState.alphaBlend = false`.
+ * Records the desired "blend off" state (flushed by `applyGLStates` before the
+ * next draw); the actual `gl.disable(gl.BLEND)` is elided when blending is
+ * already off at flush time. No-op when the context is lost or disposed.
+ *
+ * @param engine - The engine whose desired blend state is updated.
+ */
+export declare function disableBlend(engine: GLEngineContext): void;

package/blend.js

@@ -0,0 +1,194 @@
+import { RS_BLEND_DST_A, RS_BLEND_DST_RGB, RS_BLEND_ENABLED, RS_BLEND_EQ_A, RS_BLEND_EQ_RGB, RS_BLEND_SRC_A, RS_BLEND_SRC_RGB, RS_DESIRED } from "./state.js";
+/**
+ * Supported blend presets. Values mirror Babylon's `Constants.ALPHA_*` so the
+ * raw Babylon integers can be passed straight through.
+ */
+export const GLBlendMode = {
+    /** No blending — `gl.disable(gl.BLEND)`. (`Constants.ALPHA_DISABLE`) */
+    DISABLE: 0,
+    /** Additive — `blendFuncSeparate(SRC_ALPHA, ONE, ZERO, ONE)`. (`Constants.ALPHA_ADD`) */
+    ADD: 1,
+    /** Standard (non-premultiplied) alpha — `blendFuncSeparate(SRC_ALPHA, ONE_MINUS_SRC_ALPHA, ONE, ONE)`. (`Constants.ALPHA_COMBINE`) */
+    ALPHA: 2,
+    /** Premultiplied alpha — `blendFuncSeparate(ONE, ONE_MINUS_SRC_ALPHA, ONE, ONE)`. (`Constants.ALPHA_PREMULTIPLIED`) */
+    PREMULTIPLIED: 7,
+};
+/**
+ * Blend equation presets — the values WebGL2 accepts for
+ * `gl.blendEquationSeparate`. Numeric values equal the GL enums so raw GL
+ * integers (or Babylon's identical `Constants.GL_ALPHA_EQUATION_*`) pass
+ * straight through.
+ */
+export const GLBlendEquation = {
+    /** `src + dst` (the GL default). */
+    ADD: 0x8006,
+    /** `src - dst`. */
+    SUBTRACT: 0x800a,
+    /** `dst - src`. */
+    REVERSE_SUBTRACT: 0x800b,
+    /** `min(src, dst)`. */
+    MIN: 0x8007,
+    /** `max(src, dst)`. */
+    MAX: 0x8008,
+};
+/** GL `FUNC_ADD` — the implicit equation used by the {@link GLBlendMode}
+ *  presets (matching Babylon's `setAlphaMode`, which leaves it at the default). */
+const FUNC_ADD = 0x8006;
+/** GL `gl.BLEND`. */
+const BLEND = 0x0be2;
+/**
+ * Set the GL blend state to match Babylon's `setAlphaMode(mode)` exactly.
+ *
+ * | Mode               | `gl.blendFuncSeparate(srcRGB, dstRGB, srcA, dstA)`          |
+ * |--------------------|------------------------------------------------------------|
+ * | `DISABLE` (0)      | — (`gl.disable(gl.BLEND)`)                                  |
+ * | `ADD` (1)          | `SRC_ALPHA, ONE, ZERO, ONE`                                 |
+ * | `ALPHA` (2)        | `SRC_ALPHA, ONE_MINUS_SRC_ALPHA, ONE, ONE`                  |
+ * | `PREMULTIPLIED` (7)| `ONE, ONE_MINUS_SRC_ALPHA, ONE, ONE`                        |
+ *
+ * No-op when the context is lost or disposed.
+ *
+ * @param engine - The engine whose GL blend state is updated.
+ * @param mode - The {@link GLBlendMode} preset to apply.
+ */
+export function setBlendMode(engine, mode) {
+    if (engine._isLost || engine._disposed) {
+        return;
+    }
+    const gl = engine.gl;
+    switch (mode) {
+        case GLBlendMode.DISABLE:
+            disableBlend(engine);
+            return;
+        case GLBlendMode.ADD:
+            applyBlend(engine, gl.SRC_ALPHA, gl.ONE, gl.ZERO, gl.ONE, FUNC_ADD, FUNC_ADD);
+            return;
+        case GLBlendMode.ALPHA:
+            applyBlend(engine, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE, FUNC_ADD, FUNC_ADD);
+            return;
+        case GLBlendMode.PREMULTIPLIED:
+            applyBlend(engine, gl.ONE, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE, FUNC_ADD, FUNC_ADD);
+            return;
+    }
+}
+/**
+ * Enable blending with an arbitrary separate-channel function and equation —
+ * the lite-gl equivalent of Babylon's `AlphaState` with
+ * `setAlphaBlendFunctionParameters` + `setAlphaEquationParameters`.
+ *
+ * Supports every WebGL2 blend equation, including `MIN`, `MAX`,
+ * `FUNC_SUBTRACT` and `FUNC_REVERSE_SUBTRACT` (used by ShapeBuilder's darken /
+ * cutout blend modes). Records the desired config (flushed by `applyGLStates`
+ * before the next draw); at flush time the enable flag, the equation and the func
+ * are each cached independently, so a redundant state is fully elided and only
+ * the call whose params changed is re-issued — mirroring Babylon's `AlphaState`
+ * dirty flags. Because GL keeps the equation + func across `gl.disable(BLEND)`,
+ * re-enabling with unchanged params re-issues neither.
+ *
+ * No-op when the context is lost or disposed.
+ *
+ * @param engine - The engine whose desired blend state is updated.
+ * @param state - The separate-channel blend factors + equations to apply.
+ */
+export function setBlendState(engine, state) {
+    if (engine._isLost || engine._disposed) {
+        return;
+    }
+    applyBlend(engine, state.srcRGB, state.dstRGB, state.srcAlpha, state.dstAlpha, state.equationRGB ?? FUNC_ADD, state.equationAlpha ?? FUNC_ADD);
+}
+/**
+ * Disable blending — the equivalent of Babylon's `AlphaState.alphaBlend = false`.
+ * Records the desired "blend off" state (flushed by `applyGLStates` before the
+ * next draw); the actual `gl.disable(gl.BLEND)` is elided when blending is
+ * already off at flush time. No-op when the context is lost or disposed.
+ *
+ * @param engine - The engine whose desired blend state is updated.
+ */
+export function disableBlend(engine) {
+    if (engine._isLost || engine._disposed) {
+        return;
+    }
+    const s = engine._state;
+    s.rs[RS_BLEND_ENABLED + RS_DESIRED] = 0;
+    s._flushBlend = flushBlend;
+    s.statesDirty = true;
+}
+/* ────────────────────────────  internal apply  ──────────────────────────── */
+/** Record a granular blend config into the DESIRED (`rs[RS_* + RS_DESIRED]`)
+ *  slots and mark it dirty. No `gl.*` here — `applyGLStates` reconciles
+ *  desired→actual at the next flush, caching the enable flag, equation and func
+ *  independently so each is re-issued only when its params change (and never on a
+ *  bare re-enable). */
+function applyBlend(engine, srcRGB, dstRGB, srcAlpha, dstAlpha, eqRGB, eqAlpha) {
+    const rs = engine._state.rs;
+    rs[RS_BLEND_ENABLED + RS_DESIRED] = 1;
+    rs[RS_BLEND_SRC_RGB + RS_DESIRED] = srcRGB;
+    rs[RS_BLEND_DST_RGB + RS_DESIRED] = dstRGB;
+    rs[RS_BLEND_SRC_A + RS_DESIRED] = srcAlpha;
+    rs[RS_BLEND_DST_A + RS_DESIRED] = dstAlpha;
+    rs[RS_BLEND_EQ_RGB + RS_DESIRED] = eqRGB;
+    rs[RS_BLEND_EQ_A + RS_DESIRED] = eqAlpha;
+    engine._state._flushBlend = flushBlend;
+    engine._state.statesDirty = true;
+}
+/**
+ * Reconcile the deferred blend state DESIRED → ACTUAL — the per-category half of
+ * Babylon's `_alphaState.apply`. Installed onto `_state._flushBlend` by the blend
+ * setters and dispatched by {@link applyGLStates}; co-located here so a scene that
+ * never sets a blend mode tree-shakes both this reconciler and its GL code out of
+ * the bundle.
+ *
+ * The enable flag, the equation and the func are reconciled as THREE independent
+ * cached sub-states (mirroring Babylon's `_AlphaState` `_isAlphaBlendDirty` /
+ * `_isBlendEquationParametersDirty` / `_isBlendFunctionParametersDirty`). GL
+ * retains the blend equation + func across `gl.disable(BLEND)`, so their cached
+ * actual values stay valid while blending is off — re-enabling with unchanged
+ * params therefore issues ONLY `gl.enable(BLEND)` and re-issues neither
+ * `blendEquationSeparate` nor `blendFuncSeparate`. A desired `-1` (never
+ * requested) leaves GL untouched. @internal
+ */
+function flushBlend(engine) {
+    const gl = engine.gl;
+    const rs = engine._state.rs;
+    const dBlend = rs[RS_BLEND_ENABLED + RS_DESIRED];
+    if (dBlend === -1) {
+        return;
+    }
+    // 1. enable / disable — independent of the func + equation cache below.
+    if (dBlend !== rs[RS_BLEND_ENABLED]) {
+        rs[RS_BLEND_ENABLED] = dBlend;
+        if (dBlend === 1) {
+            gl.enable(BLEND);
+        }
+        else {
+            gl.disable(BLEND);
+        }
+    }
+    // While blending is off the equation/func are not observable and GL keeps the
+    // last values, so leave their cache untouched (Babylon does the same) — the
+    // next enable with identical params then re-issues nothing.
+    if (dBlend !== 1) {
+        return;
+    }
+    // 2. equation — re-issued only when the params actually changed.
+    const eqRGB = rs[RS_BLEND_EQ_RGB + RS_DESIRED];
+    const eqA = rs[RS_BLEND_EQ_A + RS_DESIRED];
+    if (rs[RS_BLEND_EQ_RGB] !== eqRGB || rs[RS_BLEND_EQ_A] !== eqA) {
+        gl.blendEquationSeparate(eqRGB, eqA);
+        rs[RS_BLEND_EQ_RGB] = eqRGB;
+        rs[RS_BLEND_EQ_A] = eqA;
+    }
+    // 3. func — re-issued only when the params actually changed.
+    const srcRGB = rs[RS_BLEND_SRC_RGB + RS_DESIRED];
+    const dstRGB = rs[RS_BLEND_DST_RGB + RS_DESIRED];
+    const srcA = rs[RS_BLEND_SRC_A + RS_DESIRED];
+    const dstA = rs[RS_BLEND_DST_A + RS_DESIRED];
+    if (rs[RS_BLEND_SRC_RGB] !== srcRGB || rs[RS_BLEND_DST_RGB] !== dstRGB || rs[RS_BLEND_SRC_A] !== srcA || rs[RS_BLEND_DST_A] !== dstA) {
+        gl.blendFuncSeparate(srcRGB, dstRGB, srcA, dstA);
+        rs[RS_BLEND_SRC_RGB] = srcRGB;
+        rs[RS_BLEND_DST_RGB] = dstRGB;
+        rs[RS_BLEND_SRC_A] = srcA;
+        rs[RS_BLEND_DST_A] = dstA;
+    }
+}
+//# sourceMappingURL=blend.js.map

package/blend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blend.js","sourceRoot":"","sources":["../src/blend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Blend-mode state — the WebGL counterpart of Babylon's `Engine.setAlphaMode`\n * (presets) and `AlphaState.setAlphaBlendFunctionParameters` /\n * `setAlphaEquationParameters` (the arbitrary separate func + equation path).\n *\n * The numeric {@link GLBlendMode} values intentionally match Babylon's\n * `Constants.ALPHA_*` (`ALPHA_DISABLE = 0`, `ALPHA_ADD = 1`, `ALPHA_COMBINE = 2`,\n * `ALPHA_PREMULTIPLIED = 7`) so a consumer can forward raw Babylon constants\n * without a translation table.\n *\n * DEFERRED MODEL (matches Babylon's `AlphaState`): these setters do NOT touch\n * `gl.*`. They record only the DESIRED blend config into the `d*` mirror fields\n * of `GLState` and raise `statesDirty`; `applyGLStates` (apply-states.ts) flushes\n * the diff to GL right before each draw / clear. Setting blend A then B then A\n * with no draw in between therefore applies exactly one blend state (A), and a\n * blend left unchanged across frames re-issues nothing.\n *\n * Both {@link setBlendMode} and {@link setBlendState} feed the same desired\n * fields, so the preset and arbitrary paths can never desync.\n */\nimport { type GLEngineContext } from \"./context.js\";\nimport { RS_BLEND_DST_A, RS_BLEND_DST_RGB, RS_BLEND_ENABLED, RS_BLEND_EQ_A, RS_BLEND_EQ_RGB, RS_BLEND_SRC_A, RS_BLEND_SRC_RGB, RS_DESIRED } from \"./state.js\";\n\n/**\n * Supported blend presets. Values mirror Babylon's `Constants.ALPHA_*` so the\n * raw Babylon integers can be passed straight through.\n */\nexport const GLBlendMode = {\n    /** No blending — `gl.disable(gl.BLEND)`. (`Constants.ALPHA_DISABLE`) */\n    DISABLE: 0,\n    /** Additive — `blendFuncSeparate(SRC_ALPHA, ONE, ZERO, ONE)`. (`Constants.ALPHA_ADD`) */\n    ADD: 1,\n    /** Standard (non-premultiplied) alpha — `blendFuncSeparate(SRC_ALPHA, ONE_MINUS_SRC_ALPHA, ONE, ONE)`. (`Constants.ALPHA_COMBINE`) */\n    ALPHA: 2,\n    /** Premultiplied alpha — `blendFuncSeparate(ONE, ONE_MINUS_SRC_ALPHA, ONE, ONE)`. (`Constants.ALPHA_PREMULTIPLIED`) */\n    PREMULTIPLIED: 7,\n} as const;\n\n/** One of the {@link GLBlendMode} preset values (`0`, `1`, `2` or `7`). */\nexport type GLBlendMode = (typeof GLBlendMode)[keyof typeof GLBlendMode];\n\n/**\n * Blend equation presets — the values WebGL2 accepts for\n * `gl.blendEquationSeparate`. Numeric values equal the GL enums so raw GL\n * integers (or Babylon's identical `Constants.GL_ALPHA_EQUATION_*`) pass\n * straight through.\n */\nexport const GLBlendEquation = {\n    /** `src + dst` (the GL default). */\n    ADD: 0x8006,\n    /** `src - dst`. */\n    SUBTRACT: 0x800a,\n    /** `dst - src`. */\n    REVERSE_SUBTRACT: 0x800b,\n    /** `min(src, dst)`. */\n    MIN: 0x8007,\n    /** `max(src, dst)`. */\n    MAX: 0x8008,\n} as const;\n\n/** One of the {@link GLBlendEquation} preset values. */\nexport type GLBlendEquation = (typeof GLBlendEquation)[keyof typeof GLBlendEquation];\n\n/**\n * Arbitrary separate-channel blend configuration — the lite-gl equivalent of\n * Babylon's `AlphaState.setAlphaBlendFunctionParameters` +\n * `setAlphaEquationParameters`. All factor / equation fields are raw WebGL2\n * enums (`gl.ONE`, `gl.SRC_ALPHA`, `gl.MIN`, …); use {@link GLBlendEquation} for\n * the equations if you prefer named presets.\n */\nexport interface GLBlendState {\n    /** RGB source factor (`gl.blendFuncSeparate` arg 1). */\n    srcRGB: GLenum;\n    /** RGB destination factor (`gl.blendFuncSeparate` arg 2). */\n    dstRGB: GLenum;\n    /** Alpha source factor (`gl.blendFuncSeparate` arg 3). */\n    srcAlpha: GLenum;\n    /** Alpha destination factor (`gl.blendFuncSeparate` arg 4). */\n    dstAlpha: GLenum;\n    /** RGB blend equation. Defaults to `FUNC_ADD`. */\n    equationRGB?: GLenum;\n    /** Alpha blend equation. Defaults to `FUNC_ADD`. */\n    equationAlpha?: GLenum;\n}\n\n/** GL `FUNC_ADD` — the implicit equation used by the {@link GLBlendMode}\n *  presets (matching Babylon's `setAlphaMode`, which leaves it at the default). */\nconst FUNC_ADD = 0x8006;\n/** GL `gl.BLEND`. */\nconst BLEND = 0x0be2;\n\n/**\n * Set the GL blend state to match Babylon's `setAlphaMode(mode)` exactly.\n *\n * | Mode               | `gl.blendFuncSeparate(srcRGB, dstRGB, srcA, dstA)`          |\n * |--------------------|------------------------------------------------------------|\n * | `DISABLE` (0)      | — (`gl.disable(gl.BLEND)`)                                  |\n * | `ADD` (1)          | `SRC_ALPHA, ONE, ZERO, ONE`                                 |\n * | `ALPHA` (2)        | `SRC_ALPHA, ONE_MINUS_SRC_ALPHA, ONE, ONE`                  |\n * | `PREMULTIPLIED` (7)| `ONE, ONE_MINUS_SRC_ALPHA, ONE, ONE`                        |\n *\n * No-op when the context is lost or disposed.\n *\n * @param engine - The engine whose GL blend state is updated.\n * @param mode - The {@link GLBlendMode} preset to apply.\n */\nexport function setBlendMode(engine: GLEngineContext, mode: GLBlendMode): void {\n    if (engine._isLost || engine._disposed) {\n        return;\n    }\n    const gl = engine.gl;\n    switch (mode) {\n        case GLBlendMode.DISABLE:\n            disableBlend(engine);\n            return;\n        case GLBlendMode.ADD:\n            applyBlend(engine, gl.SRC_ALPHA, gl.ONE, gl.ZERO, gl.ONE, FUNC_ADD, FUNC_ADD);\n            return;\n        case GLBlendMode.ALPHA:\n            applyBlend(engine, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE, FUNC_ADD, FUNC_ADD);\n            return;\n        case GLBlendMode.PREMULTIPLIED:\n            applyBlend(engine, gl.ONE, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE, FUNC_ADD, FUNC_ADD);\n            return;\n    }\n}\n\n/**\n * Enable blending with an arbitrary separate-channel function and equation —\n * the lite-gl equivalent of Babylon's `AlphaState` with\n * `setAlphaBlendFunctionParameters` + `setAlphaEquationParameters`.\n *\n * Supports every WebGL2 blend equation, including `MIN`, `MAX`,\n * `FUNC_SUBTRACT` and `FUNC_REVERSE_SUBTRACT` (used by ShapeBuilder's darken /\n * cutout blend modes). Records the desired config (flushed by `applyGLStates`\n * before the next draw); at flush time the enable flag, the equation and the func\n * are each cached independently, so a redundant state is fully elided and only\n * the call whose params changed is re-issued — mirroring Babylon's `AlphaState`\n * dirty flags. Because GL keeps the equation + func across `gl.disable(BLEND)`,\n * re-enabling with unchanged params re-issues neither.\n *\n * No-op when the context is lost or disposed.\n *\n * @param engine - The engine whose desired blend state is updated.\n * @param state - The separate-channel blend factors + equations to apply.\n */\nexport function setBlendState(engine: GLEngineContext, state: GLBlendState): void {\n    if (engine._isLost || engine._disposed) {\n        return;\n    }\n    applyBlend(engine, state.srcRGB, state.dstRGB, state.srcAlpha, state.dstAlpha, state.equationRGB ?? FUNC_ADD, state.equationAlpha ?? FUNC_ADD);\n}\n\n/**\n * Disable blending — the equivalent of Babylon's `AlphaState.alphaBlend = false`.\n * Records the desired \"blend off\" state (flushed by `applyGLStates` before the\n * next draw); the actual `gl.disable(gl.BLEND)` is elided when blending is\n * already off at flush time. No-op when the context is lost or disposed.\n *\n * @param engine - The engine whose desired blend state is updated.\n */\nexport function disableBlend(engine: GLEngineContext): void {\n    if (engine._isLost || engine._disposed) {\n        return;\n    }\n    const s = engine._state;\n    s.rs[RS_BLEND_ENABLED + RS_DESIRED] = 0;\n    s._flushBlend = flushBlend;\n    s.statesDirty = true;\n}\n\n/* ────────────────────────────  internal apply  ──────────────────────────── */\n\n/** Record a granular blend config into the DESIRED (`rs[RS_* + RS_DESIRED]`)\n *  slots and mark it dirty. No `gl.*` here — `applyGLStates` reconciles\n *  desired→actual at the next flush, caching the enable flag, equation and func\n *  independently so each is re-issued only when its params change (and never on a\n *  bare re-enable). */\nfunction applyBlend(engine: GLEngineContext, srcRGB: number, dstRGB: number, srcAlpha: number, dstAlpha: number, eqRGB: number, eqAlpha: number): void {\n    const rs = engine._state.rs;\n    rs[RS_BLEND_ENABLED + RS_DESIRED] = 1;\n    rs[RS_BLEND_SRC_RGB + RS_DESIRED] = srcRGB;\n    rs[RS_BLEND_DST_RGB + RS_DESIRED] = dstRGB;\n    rs[RS_BLEND_SRC_A + RS_DESIRED] = srcAlpha;\n    rs[RS_BLEND_DST_A + RS_DESIRED] = dstAlpha;\n    rs[RS_BLEND_EQ_RGB + RS_DESIRED] = eqRGB;\n    rs[RS_BLEND_EQ_A + RS_DESIRED] = eqAlpha;\n    engine._state._flushBlend = flushBlend;\n    engine._state.statesDirty = true;\n}\n\n/**\n * Reconcile the deferred blend state DESIRED → ACTUAL — the per-category half of\n * Babylon's `_alphaState.apply`. Installed onto `_state._flushBlend` by the blend\n * setters and dispatched by {@link applyGLStates}; co-located here so a scene that\n * never sets a blend mode tree-shakes both this reconciler and its GL code out of\n * the bundle.\n *\n * The enable flag, the equation and the func are reconciled as THREE independent\n * cached sub-states (mirroring Babylon's `_AlphaState` `_isAlphaBlendDirty` /\n * `_isBlendEquationParametersDirty` / `_isBlendFunctionParametersDirty`). GL\n * retains the blend equation + func across `gl.disable(BLEND)`, so their cached\n * actual values stay valid while blending is off — re-enabling with unchanged\n * params therefore issues ONLY `gl.enable(BLEND)` and re-issues neither\n * `blendEquationSeparate` nor `blendFuncSeparate`. A desired `-1` (never\n * requested) leaves GL untouched. @internal\n */\nfunction flushBlend(engine: GLEngineContext): void {\n    const gl = engine.gl;\n    const rs = engine._state.rs;\n    const dBlend = rs[RS_BLEND_ENABLED + RS_DESIRED]!;\n    if (dBlend === -1) {\n        return;\n    }\n    // 1. enable / disable — independent of the func + equation cache below.\n    if (dBlend !== rs[RS_BLEND_ENABLED]) {\n        rs[RS_BLEND_ENABLED] = dBlend;\n        if (dBlend === 1) {\n            gl.enable(BLEND);\n        } else {\n            gl.disable(BLEND);\n        }\n    }\n    // While blending is off the equation/func are not observable and GL keeps the\n    // last values, so leave their cache untouched (Babylon does the same) — the\n    // next enable with identical params then re-issues nothing.\n    if (dBlend !== 1) {\n        return;\n    }\n    // 2. equation — re-issued only when the params actually changed.\n    const eqRGB = rs[RS_BLEND_EQ_RGB + RS_DESIRED]!;\n    const eqA = rs[RS_BLEND_EQ_A + RS_DESIRED]!;\n    if (rs[RS_BLEND_EQ_RGB] !== eqRGB || rs[RS_BLEND_EQ_A] !== eqA) {\n        gl.blendEquationSeparate(eqRGB, eqA);\n        rs[RS_BLEND_EQ_RGB] = eqRGB;\n        rs[RS_BLEND_EQ_A] = eqA;\n    }\n    // 3. func — re-issued only when the params actually changed.\n    const srcRGB = rs[RS_BLEND_SRC_RGB + RS_DESIRED]!;\n    const dstRGB = rs[RS_BLEND_DST_RGB + RS_DESIRED]!;\n    const srcA = rs[RS_BLEND_SRC_A + RS_DESIRED]!;\n    const dstA = rs[RS_BLEND_DST_A + RS_DESIRED]!;\n    if (rs[RS_BLEND_SRC_RGB] !== srcRGB || rs[RS_BLEND_DST_RGB] !== dstRGB || rs[RS_BLEND_SRC_A] !== srcA || rs[RS_BLEND_DST_A] !== dstA) {\n        gl.blendFuncSeparate(srcRGB, dstRGB, srcA, dstA);\n        rs[RS_BLEND_SRC_RGB] = srcRGB;\n        rs[RS_BLEND_DST_RGB] = dstRGB;\n        rs[RS_BLEND_SRC_A] = srcA;\n        rs[RS_BLEND_DST_A] = dstA;\n    }\n}\n"]}

package/context.d.ts

@@ -0,0 +1,130 @@
+/** Constructor options forwarded to `canvas.getContext('webgl2', …)`. */
+export interface GLEngineOptions {
+    /** Default: true. */
+    alpha?: boolean;
+    /** Default: true. */
+    premultipliedAlpha?: boolean;
+    /** Default: false. */
+    antialias?: boolean;
+    /** Default: false. */
+    preserveDrawingBuffer?: boolean;
+    /** Default: false — disabled for fullscreen-quad workloads. */
+    depth?: boolean;
+    /** Default: false. */
+    stencil?: boolean;
+    /** Default: "default". */
+    powerPreference?: WebGLPowerPreference;
+    /** Default: false. */
+    failIfMajorPerformanceCaveat?: boolean;
+}
+/** Read-only WebGL2 capability limits, queried once at context creation. */
+export interface GLEngineCaps {
+    /** `gl.MAX_TEXTURE_SIZE` — largest supported texture dimension, in texels. */
+    readonly maxTextureSize: number;
+    /** `gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS` — number of sampler binding slots. */
+    readonly maxTextureUnits: number;
+    /** The `KHR_parallel_shader_compile` extension used for async link polling,
+     *  or null when unsupported — linking is then treated as synchronous. */
+    readonly parallelShaderCompile: {
+        COMPLETION_STATUS_KHR: number;
+    } | null;
+    /** True when 32-bit float color attachments are renderable
+     *  (`EXT_color_buffer_float`). Mirrors Babylon's `caps.textureFloatRender`. */
+    readonly textureFloatRender: boolean;
+    /** True when 32-bit float textures support linear filtering
+     *  (`OES_texture_float_linear`). Mirrors `caps.textureFloatLinearFiltering`. */
+    readonly textureFloatLinearFiltering: boolean;
+    /** True when 16-bit half-float color attachments are renderable
+     *  (`EXT_color_buffer_float` or `EXT_color_buffer_half_float`). Mirrors
+     *  `caps.textureHalfFloatRender`. */
+    readonly textureHalfFloatRender: boolean;
+    /** Half-float linear filtering — always `true` in WebGL2 (it is core).
+     *  Kept as a field to mirror Babylon's `caps.textureHalfFloatLinearFiltering`. */
+    readonly textureHalfFloatLinearFiltering: boolean;
+    /** Whether non-power-of-two textures need POT dimensions for mips / wrap.
+     *  Always `false` in WebGL2 (NPOT is core). Mirrors `engine.needPOTTextures`. */
+    readonly needPOTTextures: boolean;
+}
+/**
+ * Pure-state handle for a WebGL2 canvas + its cached GL state.
+ *
+ * INVARIANT: consumers MUST NOT mutate GL state directly through `engine.gl`.
+ * Doing so silently corrupts the cache in `_state`. The package owns every
+ * GL call. (`engine.gl` is exposed only so downstream code that already has the
+ * pattern of poking `engine._gl.getExtension(...)` can do that, but must NOT
+ * call `bindTexture`/`useProgram`/`bindBuffer`/`viewport`/etc.)
+ */
+export interface GLEngineContext {
+    /** The canvas the WebGL2 context was acquired from. An `OffscreenCanvas` is
+     *  supported for worker render paths (e.g. the Lottie player); it has no CSS
+     *  box, so it must be sized explicitly via `setGLEngineSize` rather than the
+     *  CSS-derived `resizeGLEngine`. */
+    readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+    /** The raw WebGL2 context. Do NOT mutate GL state through it — see the
+     *  type-level invariant above; the package owns every state-changing call. */
+    readonly gl: WebGL2RenderingContext;
+    /** Queried capability limits for this context. */
+    readonly caps: GLEngineCaps;
+}
+/** 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 declare function createGLEngine(canvas: HTMLCanvasElement | OffscreenCanvas, options?: GLEngineOptions): GLEngineContext;
+/** 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 declare function disposeGLEngine(engine: GLEngineContext): void;
+/** Match drawing-buffer size to (clientSize × devicePixelRatio / _hsl). No-op
+ *  if size already matches. Never touches viewport — `setViewport` owns that. */
+export declare function resizeGLEngine(engine: GLEngineContext): void;
+/**
+ * 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 declare function setGLEngineSize(engine: GLEngineContext, width: number, height: number): void;
+/**
+ * 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 declare function wipeGLStateCache(engine: GLEngineContext): void;
+/** Drawing-buffer width in physical pixels (`canvas.width`). */
+export declare function getRenderWidth(engine: GLEngineContext): number;
+/** Drawing-buffer height in physical pixels (`canvas.height`). */
+export declare function getRenderHeight(engine: GLEngineContext): number;
+/** Current hardware-scaling factor — drawing-buffer = clientSize × dpr / level. */
+export declare function getHardwareScalingLevel(engine: GLEngineContext): number;
+/** Updates the hardware-scaling factor and triggers a resize. */
+export declare function setHardwareScalingLevel(engine: GLEngineContext, level: number): void;
+/** The backing canvas element (an `HTMLCanvasElement`, or an `OffscreenCanvas`
+ *  for worker render paths). */
+export declare function getRenderingCanvas(engine: GLEngineContext): HTMLCanvasElement | OffscreenCanvas;
+/** Register a `webglcontextlost` callback. Duplicate registrations are ignored. */
+export declare function onContextLost(engine: GLEngineContext, cb: () => void): void;
+/** Remove a previously-registered context-lost callback. */
+export declare function offContextLost(engine: GLEngineContext, cb: () => void): void;
+/** Register a `webglcontextrestored` callback. Duplicate registrations are ignored. */
+export declare function onContextRestored(engine: GLEngineContext, cb: () => void): void;
+/** Remove a previously-registered context-restored callback. */
+export declare function offContextRestored(engine: GLEngineContext, cb: () => void): void;