@babylonjs/lite-gl 0.1.0 → 0.2.0

package/state.js

@@ -0,0 +1,153 @@
+/* ─── Deferred render-state index-array layout ────────────────────────────────
+ * The deferred render-state (blend / depth / cull / stencil / color-mask) lives
+ * in a single flat `Float64Array(46)` on `GLState.rs`: slots `0..20` hold the
+ * ACTUAL applied GL state, slots `21..41` (`RS_X + RS_DESIRED`) the DESIRED twin,
+ * and slots `42..45` the standalone (no-desired-twin) cached `gl.clearColor` RGBA.
+ *
+ * These `@internal` index consts are imported by blend.ts / depth-stencil.ts /
+ * apply-states.ts. Because they are plain `const` integers, esbuild inlines each
+ * to a 1–2 char literal (`rs[RS_BLEND_SRC_RGB + RS_DESIRED]` → `rs[22]`) when
+ * bundling a scene — far smaller than the old cross-module `.dBlendSrcRGB` named
+ * props, which could not be mangled and shipped verbatim in every bundle.
+ *
+ * Float64Array (NOT Int32Array) is required: `RS_STENCIL_MASK` /
+ * `RS_STENCIL_FUNC_MASK` can be `0xFFFFFFFF`, which Int32 would store as `-1` and
+ * collide with the `-1` "unset" sentinel; Float64 keeps `4294967295` distinct. */
+/** @internal */ export const RS_BLEND_ENABLED = 0;
+/** @internal */ export const RS_BLEND_SRC_RGB = 1;
+/** @internal */ export const RS_BLEND_DST_RGB = 2;
+/** @internal */ export const RS_BLEND_SRC_A = 3;
+/** @internal */ export const RS_BLEND_DST_A = 4;
+/** @internal */ export const RS_BLEND_EQ_RGB = 5;
+/** @internal */ export const RS_BLEND_EQ_A = 6;
+/** @internal */ export const RS_DEPTH_TEST = 7;
+/** @internal */ export const RS_DEPTH_MASK = 8;
+/** @internal */ export const RS_DEPTH_FUNC = 9;
+/** @internal */ export const RS_CULL_ENABLED = 10;
+/** @internal */ export const RS_CULL_FACE = 11;
+/** @internal */ export const RS_STENCIL_TEST = 12;
+/** @internal */ export const RS_STENCIL_MASK = 13;
+/** @internal */ export const RS_STENCIL_FUNC_FUNC = 14;
+/** @internal */ export const RS_STENCIL_FUNC_REF = 15;
+/** @internal */ export const RS_STENCIL_FUNC_MASK = 16;
+/** @internal */ export const RS_STENCIL_OP_FAIL = 17;
+/** @internal */ export const RS_STENCIL_OP_ZFAIL = 18;
+/** @internal */ export const RS_STENCIL_OP_ZPASS = 19;
+/** @internal */ export const RS_COLOR_MASK = 20;
+/** @internal Offset from an ACTUAL slot (`0..20`) to its DESIRED twin (`21..41`). */
+export const RS_DESIRED = 21;
+/* Standalone cached gl.clearColor RGBA slots (`42..45`) — NO desired twin; a
+ * simple apply-on-clear cache like viewport/scissor, stored in `rs` (not as named
+ * GLState fields) so the index access mangles small instead of shipping
+ * `.clearColorR` verbatim in every bundle. */
+/** @internal */ export const RS_CLEAR_R = 42;
+/** @internal */ export const RS_CLEAR_G = 43;
+/** @internal */ export const RS_CLEAR_B = 44;
+/** @internal */ export const RS_CLEAR_A = 45;
+/** Indices in `rs` whose unset sentinel is `-1` (the tri-state enables + the
+ *  `stencilMask` / `colorMask` caches). Every other slot defaults to `0`. The
+ *  sentinel is written to BOTH the actual (`i`) and desired (`i + RS_DESIRED`)
+ *  halves. Kept as a function-local literal so it stays a runtime value (no
+ *  module-level allocation / side effect). */
+function applyRenderStateSentinels(rs) {
+    for (const i of [RS_BLEND_ENABLED, RS_DEPTH_TEST, RS_DEPTH_MASK, RS_CULL_ENABLED, RS_STENCIL_TEST, RS_STENCIL_MASK, RS_COLOR_MASK]) {
+        rs[i] = -1;
+        rs[i + RS_DESIRED] = -1;
+    }
+    // clearColor RGBA (standalone, no DESIRED twin) — `-1` forces the first clear
+    // to issue gl.clearColor (valid components are 0..1).
+    rs[RS_CLEAR_R] = rs[RS_CLEAR_G] = rs[RS_CLEAR_B] = rs[RS_CLEAR_A] = -1;
+}
+/** Allocate the 46-slot deferred render-state array (21 actual + 21 desired + 4
+ *  standalone clearColor) initialised to its unset sentinels — a fresh
+ *  `Float64Array` is already all `0`, so only the `-1` slots need writing. */
+function createRenderStateArray() {
+    const rs = new Float64Array(46);
+    applyRenderStateSentinels(rs);
+    return rs;
+}
+/** Re-initialise a live render-state array in place: zero every slot, then
+ *  restore the `-1` sentinels. */
+function resetRenderStateArray(rs) {
+    rs.fill(0);
+    applyRenderStateSentinels(rs);
+}
+/** Allocate a fresh, fully-null GLState sized for `maxTextureUnits`. */
+export function createGLState(maxTextureUnits) {
+    return {
+        currentProgram: null,
+        activeTextureUnit: 0,
+        boundTextures: new Array(maxTextureUnits).fill(null),
+        boundArrayBuffer: null,
+        boundElementBuffer: null,
+        boundVao: null,
+        viewportX: 0,
+        viewportY: 0,
+        viewportW: 0,
+        viewportH: 0,
+        boundFramebuffer: null,
+        rs: createRenderStateArray(),
+        statesDirty: false,
+        scissorEnabled: -1,
+        scissorX: 0,
+        scissorY: 0,
+        scissorW: 0,
+        scissorH: 0,
+        unpackAlignment: -1,
+        unpackFlipY: -1,
+        unpackPremultiplyAlpha: -1,
+        enabledAttribs: [],
+        instanceLocations: [],
+        quadVbo: null,
+        quadIbo: null,
+        quadVao: null,
+    };
+}
+/** Reset only the cached "current GL state" — every binding (program / buffers /
+ *  textures / VAO / framebuffer) and render-state (blend / depth / stencil /
+ *  scissor / color-mask / viewport / unpack) field, including the whole `rs`
+ *  deferred render-state array (BOTH the actual applied values and the DESIRED
+ *  twins) plus `statesDirty` — to its unset sentinel, WITHOUT discarding owned
+ *  GPU resources (the shared quad). After this, the next setter in each category
+ *  is re-issued rather than elided.
+ *
+ *  Used by `resetGLState` (context-lost) and by `wipeGLStateCache` (a host that
+ *  shares the GL context calling in after mutating raw `gl.*` state). The shared
+ *  quad's GL objects are still alive in the latter case, so they are preserved
+ *  here to avoid leaking + needlessly rebuilding them every render scope. */
+export function resetGLStateCache(state) {
+    state.currentProgram = null;
+    state.activeTextureUnit = 0;
+    state.boundTextures.fill(null);
+    state.boundArrayBuffer = null;
+    state.boundElementBuffer = null;
+    state.boundVao = null;
+    state.viewportX = 0;
+    state.viewportY = 0;
+    state.viewportW = 0;
+    state.viewportH = 0;
+    state.boundFramebuffer = null;
+    resetRenderStateArray(state.rs);
+    state.statesDirty = false;
+    state.scissorEnabled = -1;
+    state.scissorX = 0;
+    state.scissorY = 0;
+    state.scissorW = 0;
+    state.scissorH = 0;
+    state.unpackAlignment = -1;
+    state.unpackFlipY = -1;
+    state.unpackPremultiplyAlpha = -1;
+    state.enabledAttribs.length = 0;
+    state.instanceLocations.length = 0;
+}
+/** Zero the cache in-place. Used by the context-lost handler — GL handles are
+ *  already dead per WebGL spec; we forget what we knew about them (including the
+ *  shared quad, whose GL objects are gone and must be rebuilt) so the next
+ *  bind/use after restore is NOT incorrectly elided. */
+export function resetGLState(state) {
+    resetGLStateCache(state);
+    state.quadVbo = null;
+    state.quadIbo = null;
+    state.quadVao = null;
+}
+//# sourceMappingURL=state.js.map

package/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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","sourcesContent":["import type { GLEngineContext } from \"./context.js\";\n\n/* ─── Deferred render-state index-array layout ────────────────────────────────\n * The deferred render-state (blend / depth / cull / stencil / color-mask) lives\n * in a single flat `Float64Array(46)` on `GLState.rs`: slots `0..20` hold the\n * ACTUAL applied GL state, slots `21..41` (`RS_X + RS_DESIRED`) the DESIRED twin,\n * and slots `42..45` the standalone (no-desired-twin) cached `gl.clearColor` RGBA.\n *\n * These `@internal` index consts are imported by blend.ts / depth-stencil.ts /\n * apply-states.ts. Because they are plain `const` integers, esbuild inlines each\n * to a 1–2 char literal (`rs[RS_BLEND_SRC_RGB + RS_DESIRED]` → `rs[22]`) when\n * bundling a scene — far smaller than the old cross-module `.dBlendSrcRGB` named\n * props, which could not be mangled and shipped verbatim in every bundle.\n *\n * Float64Array (NOT Int32Array) is required: `RS_STENCIL_MASK` /\n * `RS_STENCIL_FUNC_MASK` can be `0xFFFFFFFF`, which Int32 would store as `-1` and\n * collide with the `-1` \"unset\" sentinel; Float64 keeps `4294967295` distinct. */\n/** @internal */ export const RS_BLEND_ENABLED = 0;\n/** @internal */ export const RS_BLEND_SRC_RGB = 1;\n/** @internal */ export const RS_BLEND_DST_RGB = 2;\n/** @internal */ export const RS_BLEND_SRC_A = 3;\n/** @internal */ export const RS_BLEND_DST_A = 4;\n/** @internal */ export const RS_BLEND_EQ_RGB = 5;\n/** @internal */ export const RS_BLEND_EQ_A = 6;\n/** @internal */ export const RS_DEPTH_TEST = 7;\n/** @internal */ export const RS_DEPTH_MASK = 8;\n/** @internal */ export const RS_DEPTH_FUNC = 9;\n/** @internal */ export const RS_CULL_ENABLED = 10;\n/** @internal */ export const RS_CULL_FACE = 11;\n/** @internal */ export const RS_STENCIL_TEST = 12;\n/** @internal */ export const RS_STENCIL_MASK = 13;\n/** @internal */ export const RS_STENCIL_FUNC_FUNC = 14;\n/** @internal */ export const RS_STENCIL_FUNC_REF = 15;\n/** @internal */ export const RS_STENCIL_FUNC_MASK = 16;\n/** @internal */ export const RS_STENCIL_OP_FAIL = 17;\n/** @internal */ export const RS_STENCIL_OP_ZFAIL = 18;\n/** @internal */ export const RS_STENCIL_OP_ZPASS = 19;\n/** @internal */ export const RS_COLOR_MASK = 20;\n/** @internal Offset from an ACTUAL slot (`0..20`) to its DESIRED twin (`21..41`). */\nexport const RS_DESIRED = 21;\n/* Standalone cached gl.clearColor RGBA slots (`42..45`) — NO desired twin; a\n * simple apply-on-clear cache like viewport/scissor, stored in `rs` (not as named\n * GLState fields) so the index access mangles small instead of shipping\n * `.clearColorR` verbatim in every bundle. */\n/** @internal */ export const RS_CLEAR_R = 42;\n/** @internal */ export const RS_CLEAR_G = 43;\n/** @internal */ export const RS_CLEAR_B = 44;\n/** @internal */ export const RS_CLEAR_A = 45;\n\n/**\n * GL-state cache type. Owned by `GLEngineContext._state`.\n *\n * Two flavours of cached state coexist here:\n *\n *  - **Eager bindings** (program / buffers / textures / VAO / framebuffer /\n *    viewport / scissor / unpack). Each binding setter issues its `gl.*` call\n *    immediately and updates the matching field in lock-step, eliding the call\n *    when the cache already matches.\n *  - **Deferred render-state** (blend / depth / cull / stencil / color-mask),\n *    stored in the {@link GLState.rs} index-array. These follow Babylon's\n *    `applyStates()` model: each setter records only the DESIRED slot\n *    (`rs[RS_X + RS_DESIRED]`) and sets `statesDirty`; the real `gl.*` calls are\n *    flushed by {@link applyGLStates} (apply-states.ts) immediately before each\n *    draw / clear, reconciling DESIRED → ACTUAL and writing the actual slots\n *    (`rs[RS_X]`) in lock-step. Both halves keep their `-1`/`0` unset sentinels.\n *\n * See `00-lite-gl.md` §4 for the full table of cached operations and the\n * deferred-state flush sites.\n *\n * INVARIANTS:\n *  - The cache is the source of truth. If consumers poke `engine.gl.*` directly\n *    they will silently corrupt this state.\n *  - On `webglcontextlost` the whole `rs` array (both the actual and desired\n *    halves) is reset to its initial sentinels (handles are dead anyway;\n *    subsequent setters bail out on `engine._isLost`, and a post-restore setter\n *    re-marks `statesDirty`).\n */\nexport interface GLState {\n    currentProgram: WebGLProgram | null;\n    activeTextureUnit: number;\n    /** Per-unit binding; length === caps.maxTextureUnits. */\n    boundTextures: (WebGLTexture | null)[];\n    boundArrayBuffer: WebGLBuffer | null;\n    boundElementBuffer: WebGLBuffer | null;\n    boundVao: WebGLVertexArrayObject | null;\n    viewportX: number;\n    viewportY: number;\n    viewportW: number;\n    viewportH: number;\n    /**\n     * Currently-bound draw framebuffer, or `null` for the default (canvas)\n     * framebuffer. Owned by the render-target module's `bindRenderTarget`\n     * (binding `null` returns to the canvas). Reset to `null` on context-lost.\n     */\n    boundFramebuffer: WebGLFramebuffer | null;\n    /**\n     * Deferred render-state (blend / depth / cull / stencil / color-mask) packed\n     * into ONE flat `Float64Array(46)`. Slots `0..20` (indexed by the `RS_*`\n     * consts) are the ACTUAL applied GL state — what {@link applyGLStates} last\n     * wrote to the context; slots `21..41` (`rs[RS_X + RS_DESIRED]`) are the\n     * DESIRED twin the setters record. The setters write ONLY the desired half\n     * (never `gl.*`, never the actual half) and raise `statesDirty`;\n     * `applyGLStates` reconciles each desired → its actual twin right before a\n     * draw / clear, issuing only the GL calls that changed and updating the\n     * actual half in lock-step. Both preset and arbitrary blend paths feed the\n     * same desired slots, so they can never desync.\n     *\n     * Sentinels (identical for both halves): `-1` for the tri-state enables\n     * (`RS_BLEND_ENABLED` / `RS_DEPTH_TEST` / `RS_DEPTH_MASK` / `RS_CULL_ENABLED`\n     * / `RS_STENCIL_TEST`) and the mask caches (`RS_STENCIL_MASK` /\n     * `RS_COLOR_MASK`); `0` for every func / equation / op / ref slot (no GL enum\n     * is `0`). An unset desired equals its unset actual and is never flushed; the\n     * `-1` blend/test sentinels guarantee the first applied state is never elided.\n     * The blend func/equation slots are only trusted while `RS_BLEND_ENABLED` is\n     * `1` — the disabled→enabled transition re-issues both (matching Babylon's\n     * `AlphaState`, which does not track them while blending is off).\n     *\n     * Float64 (not Int32): `RS_STENCIL_MASK` / `RS_STENCIL_FUNC_MASK` can be\n     * `0xFFFFFFFF`, which Int32 stores as `-1` — colliding with the `-1` unset\n     * sentinel. Reset on context-lost. */\n    rs: Float64Array;\n    /** `true` when at least one deferred-state setter ran since the last\n     *  {@link applyGLStates}. Gates the flush so an unchanged frame issues no\n     *  reconciliation work. */\n    statesDirty: boolean;\n    /* ─── Deferred render-state appliers (per-category, lazily installed) ──────\n     * Each category's reconciler (blend / depth+cull / stencil / color-mask) is\n     * installed onto its slot the first time the matching setter runs — a runtime\n     * assignment, NOT a module-level side effect. `applyGLStates` dispatches ONLY\n     * through these slots, so the reconcilers (and their GL reconciliation code)\n     * are reachable only when their setter is in the bundle: a scene that never\n     * touches a category tree-shakes its reconciler out entirely (e.g. a clear-\n     * only scene drops all four). Left undefined until installed; never cleared on\n     * context-lost (a post-restore setter re-installs idempotently). */\n    /** @internal Blend reconciler (Babylon's `_alphaState`). */\n    _flushBlend?: (engine: GLEngineContext) => void;\n    /** @internal Depth + cull reconciler (Babylon's `_depthCullingState`). */\n    _flushDepthCull?: (engine: GLEngineContext) => void;\n    /** @internal Stencil reconciler (Babylon's `_stencilState`). */\n    _flushStencil?: (engine: GLEngineContext) => void;\n    /** @internal Color-write-mask reconciler (Babylon's `setColorWrite`). */\n    _flushColorMask?: (engine: GLEngineContext) => void;\n    /** Scissor-test enable tri-state (`-1` unset, `0` off, `1` on). */\n    scissorEnabled: number;\n    scissorX: number;\n    scissorY: number;\n    scissorW: number;\n    scissorH: number;\n    /** Cached `gl.pixelStorei(UNPACK_ALIGNMENT)`, or `-1` when unset. */\n    unpackAlignment: number;\n    /** Cached `gl.pixelStorei(UNPACK_FLIP_Y_WEBGL)`, or `-1` when unset. */\n    unpackFlipY: number;\n    /** Cached `gl.pixelStorei(UNPACK_PREMULTIPLY_ALPHA_WEBGL)`, or `-1` unset. */\n    unpackPremultiplyAlpha: number;\n    /**\n     * Per-location vertex-attribute enable flags for the DEFAULT (null) VAO —\n     * the mesh / instancing path (mirrors Babylon's `_vertexAttribArraysEnabled`).\n     * Index is the attribute location. lite-gl's quad / sprite paths use their\n     * own VAOs and do not touch this. Cleared on context-lost.\n     */\n    enabledAttribs: boolean[];\n    /**\n     * Attribute locations currently configured with a non-default vertex divisor\n     * (instanced attributes), mirroring Babylon's `_currentInstanceLocations`.\n     * `unbindInstanceAttributes` resets each back to divisor 0 and clears this.\n     */\n    instanceLocations: number[];\n    /** Shared fullscreen quad — lazily created on first `applyEffectWrapper`. */\n    quadVbo: WebGLBuffer | null;\n    quadIbo: WebGLBuffer | null;\n    quadVao: WebGLVertexArrayObject | null;\n}\n\n/** Indices in `rs` whose unset sentinel is `-1` (the tri-state enables + the\n *  `stencilMask` / `colorMask` caches). Every other slot defaults to `0`. The\n *  sentinel is written to BOTH the actual (`i`) and desired (`i + RS_DESIRED`)\n *  halves. Kept as a function-local literal so it stays a runtime value (no\n *  module-level allocation / side effect). */\nfunction applyRenderStateSentinels(rs: Float64Array): void {\n    for (const i of [RS_BLEND_ENABLED, RS_DEPTH_TEST, RS_DEPTH_MASK, RS_CULL_ENABLED, RS_STENCIL_TEST, RS_STENCIL_MASK, RS_COLOR_MASK]) {\n        rs[i] = -1;\n        rs[i + RS_DESIRED] = -1;\n    }\n    // clearColor RGBA (standalone, no DESIRED twin) — `-1` forces the first clear\n    // to issue gl.clearColor (valid components are 0..1).\n    rs[RS_CLEAR_R] = rs[RS_CLEAR_G] = rs[RS_CLEAR_B] = rs[RS_CLEAR_A] = -1;\n}\n\n/** Allocate the 46-slot deferred render-state array (21 actual + 21 desired + 4\n *  standalone clearColor) initialised to its unset sentinels — a fresh\n *  `Float64Array` is already all `0`, so only the `-1` slots need writing. */\nfunction createRenderStateArray(): Float64Array {\n    const rs = new Float64Array(46);\n    applyRenderStateSentinels(rs);\n    return rs;\n}\n\n/** Re-initialise a live render-state array in place: zero every slot, then\n *  restore the `-1` sentinels. */\nfunction resetRenderStateArray(rs: Float64Array): void {\n    rs.fill(0);\n    applyRenderStateSentinels(rs);\n}\n\n/** Allocate a fresh, fully-null GLState sized for `maxTextureUnits`. */\nexport function createGLState(maxTextureUnits: number): GLState {\n    return {\n        currentProgram: null,\n        activeTextureUnit: 0,\n        boundTextures: new Array<WebGLTexture | null>(maxTextureUnits).fill(null),\n        boundArrayBuffer: null,\n        boundElementBuffer: null,\n        boundVao: null,\n        viewportX: 0,\n        viewportY: 0,\n        viewportW: 0,\n        viewportH: 0,\n        boundFramebuffer: null,\n        rs: createRenderStateArray(),\n        statesDirty: false,\n        scissorEnabled: -1,\n        scissorX: 0,\n        scissorY: 0,\n        scissorW: 0,\n        scissorH: 0,\n        unpackAlignment: -1,\n        unpackFlipY: -1,\n        unpackPremultiplyAlpha: -1,\n        enabledAttribs: [],\n        instanceLocations: [],\n        quadVbo: null,\n        quadIbo: null,\n        quadVao: null,\n    };\n}\n\n/** Reset only the cached \"current GL state\" — every binding (program / buffers /\n *  textures / VAO / framebuffer) and render-state (blend / depth / stencil /\n *  scissor / color-mask / viewport / unpack) field, including the whole `rs`\n *  deferred render-state array (BOTH the actual applied values and the DESIRED\n *  twins) plus `statesDirty` — to its unset sentinel, WITHOUT discarding owned\n *  GPU resources (the shared quad). After this, the next setter in each category\n *  is re-issued rather than elided.\n *\n *  Used by `resetGLState` (context-lost) and by `wipeGLStateCache` (a host that\n *  shares the GL context calling in after mutating raw `gl.*` state). The shared\n *  quad's GL objects are still alive in the latter case, so they are preserved\n *  here to avoid leaking + needlessly rebuilding them every render scope. */\nexport function resetGLStateCache(state: GLState): void {\n    state.currentProgram = null;\n    state.activeTextureUnit = 0;\n    state.boundTextures.fill(null);\n    state.boundArrayBuffer = null;\n    state.boundElementBuffer = null;\n    state.boundVao = null;\n    state.viewportX = 0;\n    state.viewportY = 0;\n    state.viewportW = 0;\n    state.viewportH = 0;\n    state.boundFramebuffer = null;\n    resetRenderStateArray(state.rs);\n    state.statesDirty = false;\n    state.scissorEnabled = -1;\n    state.scissorX = 0;\n    state.scissorY = 0;\n    state.scissorW = 0;\n    state.scissorH = 0;\n    state.unpackAlignment = -1;\n    state.unpackFlipY = -1;\n    state.unpackPremultiplyAlpha = -1;\n    state.enabledAttribs.length = 0;\n    state.instanceLocations.length = 0;\n}\n\n/** Zero the cache in-place. Used by the context-lost handler — GL handles are\n *  already dead per WebGL spec; we forget what we knew about them (including the\n *  shared quad, whose GL objects are gone and must be rebuilt) so the next\n *  bind/use after restore is NOT incorrectly elided. */\nexport function resetGLState(state: GLState): void {\n    resetGLStateCache(state);\n    state.quadVbo = null;\n    state.quadIbo = null;\n    state.quadVao = null;\n}\n"]}

package/texture.d.ts

@@ -0,0 +1,142 @@
+import type { GLEngineContext } from "./context.js";
+/** Texture sampling / wrap options. All have GL-spec defaults. Mipmaps are NOT
+ *  a create option — generate the chain explicitly via {@link generateTextureMipMaps}. */
+export interface GLTextureOptions {
+    /** Default: false (matches Babylon's default raw-texture behaviour). */
+    invertY?: boolean;
+    /** Default: gl.LINEAR. */
+    minFilter?: GLenum;
+    /** Default: gl.LINEAR. */
+    magFilter?: GLenum;
+    /** Default: gl.CLAMP_TO_EDGE. May be `gl.REPEAT` / `gl.MIRRORED_REPEAT`
+     *  (NPOT-safe in WebGL2). */
+    wrapS?: GLenum;
+    /** Default: gl.CLAMP_TO_EDGE. May be `gl.REPEAT` / `gl.MIRRORED_REPEAT`. */
+    wrapT?: GLenum;
+    /** `gl.pixelStorei(UNPACK_ALIGNMENT)` for the upload (1/2/4/8). Default 4.
+     *  Use 1 for tightly-packed non-RGBA rows. */
+    unpackAlignment?: number;
+    /** Premultiply alpha at upload (`UNPACK_PREMULTIPLY_ALPHA_WEBGL`). Default
+     *  false. */
+    premultiplyAlpha?: boolean;
+    /** Explicit sized internalFormat for `texImage2D`. When provided it is used
+     *  verbatim and the inline LDR resolver is bypassed — this is how
+     *  {@link createFloatTexture} injects its `RGBA16F` / `RGBA32F` choice
+     *  without the byte path ever referencing the float-format table (keeping it
+     *  tree-shakeable out of RGBA8-only bundles). Default: derived from
+     *  `format`/`type` via the LDR resolver. */
+    internalFormat?: GLenum;
+}
+/**
+ * Pure-state texture handle. The `handle` field is MUTABLE so the same logical
+ * texture survives a `webglcontextrestored` event — every consumer keeps the
+ * same `GLTexture` reference; only the internal `WebGLTexture` is swapped.
+ *
+ * `loadTexture2D` also uses the same handle for the 1×1 placeholder upload AND
+ * the final image upload — so a `bindTexture(engine, unit, tex)` made before the
+ * image has decoded remains valid once the image arrives.
+ */
+export interface GLTexture {
+    /** The live `WebGLTexture`. MUTABLE — swapped for a fresh handle on
+     *  `webglcontextrestored` while consumers keep the same `GLTexture` reference. */
+    handle: WebGLTexture;
+    /** GL texture target (always `gl.TEXTURE_2D` for this package). */
+    readonly target: GLenum;
+    /** Texture width in texels. Updated once an async upload resolves. */
+    width: number;
+    /** Texture height in texels. Updated once an async upload resolves. */
+    height: number;
+    /** True when the texture is safe to sample with final content (placeholders
+     *  read as not-ready until their image/upload completes). */
+    isReady: boolean;
+}
+/** Uint8 / float raw texture upload. The pixel data can be replaced later via
+ *  {@link updateRawTexture}; the sampling and wrap can be changed via
+ *  {@link updateTextureSamplingMode} / {@link updateTextureWrapMode}. */
+export declare function createRawTexture(engine: GLEngineContext, data: ArrayBufferView | null, width: number, height: number, format: GLenum, type: GLenum, options?: GLTextureOptions): GLTexture;
+/** Options for {@link createFloatTexture} — the shared {@link GLTextureOptions}
+ *  plus the float-specific `type` / `format`. */
+export interface GLFloatTextureOptions extends GLTextureOptions {
+    /** Float texel type — `gl.HALF_FLOAT` (default) or `gl.FLOAT`. */
+    type?: GLenum;
+    /** Color format. Default `gl.RGBA`. */
+    format?: GLenum;
+}
+/**
+ * Create a float / half-float raw texture — the HDR counterpart of
+ * {@link createRawTexture}. This is the ONLY texture factory that carries the
+ * `RGBA16F` / `RGBA32F` sized-format knowledge (via {@link pickSizedInternalFormat}),
+ * so byte-only consumers calling {@link createRawTexture} ship none of it.
+ * Defaults to `gl.HALF_FLOAT`; pass `options.type = gl.FLOAT` for full 32-bit.
+ * The caller is responsible for the matching engine cap (e.g.
+ * `caps.textureFloatLinearFiltering`) when sampling these with `LINEAR`.
+ *
+ * @param engine - The engine.
+ * @param data - Initial pixels (`Float32Array` for FLOAT, `Uint16Array` for
+ *  HALF_FLOAT), or `null` for an uninitialised allocation.
+ * @param width - Texture width in texels (≥ 1).
+ * @param height - Texture height in texels (≥ 1).
+ * @param options - See {@link GLFloatTextureOptions}.
+ * @returns The new {@link GLTexture}.
+ */
+export declare function createFloatTexture(engine: GLEngineContext, data: ArrayBufferView | null, width: number, height: number, options?: GLFloatTextureOptions): GLTexture;
+/** Generate the mip chain for a texture from its level-0 contents — mipmaps as
+ *  an explicit opt-in function rather than baked into the create path. Binds for
+ *  upload (unit 0). No-op on a lost/disposed context or a handle-less texture. */
+export declare function generateTextureMipMaps(engine: GLEngineContext, tex: GLTexture): void;
+/**
+ * Re-upload the pixel data (and optionally resize) of a texture created by
+ * {@link createRawTexture} — the lite-gl equivalent of Babylon's
+ * `updateRawTexture` / `_uploadDataToTextureDirectly`. Goes through the same
+ * upload closure used by context-restore, so the new contents survive a context
+ * loss. No-op on a lost/disposed/non-raw texture.
+ *
+ * @param engine - The engine.
+ * @param tex - The raw texture to update.
+ * @param data - New pixel data (must match the original `format`/`type`).
+ * @param options - Optional new `width`/`height` (default: unchanged) and
+ *  `unpackAlignment` (default 4).
+ */
+export declare function updateRawTexture(engine: GLEngineContext, tex: GLTexture, data: ArrayBufferView | null, options?: {
+    width?: number;
+    height?: number;
+    unpackAlignment?: number;
+}): void;
+/** Update a texture's min/mag sampling filters — the lite-gl equivalent of
+ *  Babylon's `updateTextureSamplingMode`. Binds for upload (unit 0) so the
+ *  `texParameteri` lands on this texture. No-op on a lost/disposed context. */
+export declare function updateTextureSamplingMode(engine: GLEngineContext, tex: GLTexture, minFilter: GLenum, magFilter: GLenum): void;
+/** Update a texture's S/T wrap modes (`gl.CLAMP_TO_EDGE` / `gl.REPEAT` /
+ *  `gl.MIRRORED_REPEAT`) — the lite-gl equivalent of Babylon's
+ *  `updateTextureWrappingMode`. No-op on a lost/disposed context. */
+export declare function updateTextureWrapMode(engine: GLEngineContext, tex: GLTexture, wrapS: GLenum, wrapT: GLenum): void;
+/**
+ * Wrap an existing raw `WebGLTexture` (e.g. one created by a host renderer or a
+ * previous engine) as a {@link GLTexture} — the lite-gl equivalent of
+ * ShapeBuilder's `createTextureGraphicsResourceFromExternalWebGLTexture`.
+ *
+ * The wrapper does NOT own the underlying handle's upload — it is NOT registered
+ * for context-restore replay (the external owner is responsible for that) and is
+ * marked ready immediately. `disposeTexture` will still `gl.deleteTexture` it, so
+ * only wrap a handle whose deletion you intend lite-gl to manage.
+ *
+ * @param engine - The engine.
+ * @param handle - The external `WebGLTexture`.
+ * @param width - Texture width in texels.
+ * @param height - Texture height in texels.
+ * @param options - Optional sampling/wrap to apply once (min/mag/wrapS/wrapT).
+ * @returns A {@link GLTexture} wrapping the handle.
+ */
+export declare function createTextureFromHandle(engine: GLEngineContext, handle: WebGLTexture, width: number, height: number, options?: GLTextureOptions): GLTexture;
+/** Asynchronous image upload.The returned texture is immediately usable (1×1
+ *  transparent placeholder); `isReady` flips true once the image has been
+ *  decoded and uploaded. The decoded `ImageBitmap` is retained on the texture
+ *  for offline-safe `webglcontextrestored` replay. */
+export declare function loadTexture2D(engine: GLEngineContext, url: string, options?: GLTextureOptions, onLoad?: (tex: GLTexture) => void, onError?: (err: Error) => void): GLTexture;
+/** Cached bind. Skips `gl.activeTexture` and/or `gl.bindTexture` when nothing
+ *  changes. No-op when `tex._disposed` or `engine._isLost`. */
+export declare function bindTexture(engine: GLEngineContext, unit: number, tex: GLTexture | null): void;
+/** Disposes the texture. Walks `_state.boundTextures` and clears every slot
+ *  that still references the handle — otherwise a later `bindTexture(unit, B)`
+ *  to the same unit would be wrongly elided when slot still showed handle A. */
+export declare function disposeTexture(engine: GLEngineContext, tex: GLTexture): void;