@babylonjs/lite-gl 0.1.0 → 0.2.0

package/mesh.d.ts

@@ -1,307 +1,210 @@
-/**
- * Configure vertex attributes from `vb`, reproducing Babylon's
- * `bindInstancesBuffer` exactly. For each descriptor: resolves the location
- * (explicit `index` or via the effect), enables the attribute array, issues
- * `vertexAttribPointer`, and sets the vertex divisor (`undefined → 1`). Every
- * touched location is tracked so {@link unbindInstanceAttributes} can reset its
- * divisor afterwards.
- *
- * `computeStride` controls the GL stride passed to `vertexAttribPointer`:
- * - `false` (default) → stride `0`: each attribute is independently tightly
- *   packed. Combined with overlapping `offset`s this yields the "sliding window"
- *   ShapeBuilder uses for distance-field tape buffers.
- * - `true` → stride = Σ(`size`·4 bytes): interleaved per-vertex/per-instance.
- *
- * Runs on the default (null) VAO — never corrupts the quad / sprite VAOs.
- * No-op on a lost/disposed context or before the effect is ready.
- *
- * @param engine - The engine.
- * @param vb - The buffer supplying the attribute data.
- * @param descriptors - The attribute layout.
- * @param effect - The effect whose attribute locations resolve unnamed indices.
- * @param computeStride - See above. Default `false`.
- */
-export declare function bindAttributes(engine: GLEngineContext, vb: GLVertexBuffer, descriptors: readonly GLAttributeDescriptor[], effect: GLEffect, computeStride?: boolean): void;
-
-/**
- * Bind an index buffer as the current element-array buffer (on the default
- * VAO). Cached. The lite-gl equivalent of Babylon's `_bindIndexBufferWithCache`.
- *
- * @param engine - The engine.
- * @param ib - The index buffer to bind.
- */
-export declare function bindIndexBuffer(engine: GLEngineContext, ib: GLIndexBuffer): void;
-
-/**
- * Bind a {@link GLMeshVao} (cached `gl.bindVertexArray`). Rarely called directly —
- * {@link drawMesh} binds it for you. Binding restores the VAO's recorded element
- * binding, so the element-buffer cache is updated in lock-step.
- *
- * @param engine - The engine.
- * @param vao - The mesh VAO to bind.
- */
-export declare function bindMeshVao(engine: GLEngineContext, vao: GLMeshVao): void;
-
-/**
- * Create a GPU index buffer. `Uint16Array` → 16-bit indices, `Uint32Array` →
- * 32-bit. Binds the default VAO first so it never corrupts the quad / sprite
- * VAO element bindings.
- *
- * @param engine - The engine.
- * @param data - The index data. Retained by reference for context-restore.
- * @returns The new {@link GLIndexBuffer}.
- */
-export declare function createIndexBuffer(engine: GLEngineContext, data: Uint16Array | Uint32Array): GLIndexBuffer;
-
-/**
- * Record a static mesh's attribute layout + index binding into a new VAO. The
- * effect MUST be ready (its attribute locations are resolved here, once). Returns
- * a {@link GLMeshVao} to draw with {@link drawMesh}.
- *
- * @param engine - The engine.
- * @param vertexBuffers - One or more buffers + their attribute layouts.
- * @param indexBuffer - The index buffer recorded into the VAO.
- * @param effect - The effect whose attribute locations resolve unnamed indices.
- * @returns The recorded {@link GLMeshVao}.
- */
-export declare function createMeshVao(engine: GLEngineContext, vertexBuffers: readonly GLMeshVertexBuffer[], indexBuffer: GLIndexBuffer, effect: GLEffect): GLMeshVao;
-
-/**
- * Create a GPU vertex buffer from interleaved float data.
- *
- * @param engine - The engine.
- * @param data - The vertex data. Retained by reference for context-restore — do
- *  not mutate it in place; use {@link updateVertexBuffer} to change contents.
- * @param dynamic - Hint that the buffer will be updated frequently
- *  (`DYNAMIC_DRAW`). Default `false` (`STATIC_DRAW`).
- * @returns The new {@link GLVertexBuffer}.
- */
-export declare function createVertexBuffer(engine: GLEngineContext, data: Float32Array, dynamic?: boolean): GLVertexBuffer;
-
-/** Dispose a vertex or index buffer (delete the GL buffer + unregister). Clears
- *  the array/element-buffer cache slot if it pointed at this buffer. Idempotent. */
-export declare function disposeBuffer(engine: GLEngineContext, buffer: GLVertexBuffer | GLIndexBuffer): void;
-
-/** Dispose a {@link GLMeshVao}: delete the VAO and unregister its restore hook.
- *  Does NOT dispose the vertex/index buffers (the caller owns those). Idempotent. */
-export declare function disposeMeshVao(engine: GLEngineContext, vao: GLMeshVao): void;
-
-/**
- * Draw indexed triangles from `ib` — the lite-gl equivalent of Babylon's
- * `drawElementsType` (triangle fill mode). When `instanceCount > 0` issues
- * `drawElementsInstanced`, otherwise `drawElements`. No-op on a lost/disposed
- * context or when no program is current.
- *
- * @param engine - The engine.
- * @param ib - The index buffer (also bound as a side-effect, cached).
- * @param indexCount - Number of indices to draw.
- * @param indexStart - First index offset (in indices, not bytes). Default 0.
- * @param instanceCount - Instance count for instanced draws. Default 0
- *  (non-instanced).
- */
-export declare function drawIndexed(engine: GLEngineContext, ib: GLIndexBuffer, indexCount: number, indexStart?: number, instanceCount?: number): void;
-
-/**
- * Draw a static mesh recorded with {@link createMeshVao}: binds its VAO (cached),
- * flushes deferred GL state, and issues ONE `drawElements` (or
- * `drawElementsInstanced` when `instanceCount > 0`) over the VAO's full index
- * buffer. No per-draw attribute (re)binding. No-op on a lost/disposed context, a
- * disposed VAO, or when no program is current.
- *
- * @param engine - The engine.
- * @param vao - The mesh VAO to draw.
- * @param instanceCount - Instance count for instanced draws. Default 0 (non-instanced).
- */
-export declare function drawMesh(engine: GLEngineContext, vao: GLMeshVao, instanceCount?: number): void;
-
-/**
- * Describes one vertex attribute fed from a buffer — the lite-gl equivalent of
- * Babylon's `InstancingAttributeInfo`. Pass an array of these to
- * {@link bindAttributes}.
- */
-export declare interface GLAttributeDescriptor {
-    /** Attribute name; resolved to a location via the effect when `index` is
-     *  omitted (`Effect.getAttributeLocationByName`). */
-    name?: string;
-    /** Explicit attribute location. When set, overrides the `name` lookup. */
-    index?: number;
-    /** Number of components, 1–4. */
-    size: number;
-    /** Byte offset of this attribute's first element within the buffer. Default 0. */
-    offset?: number;
-    /**
-     * Per-instance vertex divisor. **Omitted/`undefined` → `1` (instanced)**,
-     * matching Babylon's `bindInstancesBuffer`. Pass `0` explicitly for a
-     * per-vertex attribute (e.g. the base mesh position).
-     */
-    divisor?: number;
-    /** GL component type. Default `gl.FLOAT`. */
-    type?: GLenum;
-    /** Normalize fixed-point integer data to `[0,1]`/`[-1,1]`. Default `false`. */
-    normalized?: boolean;
-}
-
-/** A compiled + linked shader program with cached uniform, sampler and
- *  attribute locations. Created by `createEffect`; most fields are managed
- *  internally — drive it via `isEffectReady` / `useEffect` / the `setEffect*`
- *  setters rather than mutating it directly. */
-declare interface GLEffect {
-    /** The `name` from the originating `GLEffectOptions`. */
-    readonly name: string;
-    /** The options this effect was created from (retained for context-restore). */
-    readonly options: GLEffectOptions;
-    /** The live `WebGLProgram`. Swapped for a fresh handle after context-restore. */
-    program: WebGLProgram;
    /** Resolved during readiness finalization. Missing names map to `null` —
-     *  setters with a `null` location are silent no-ops (matches Babylon). */
-    uniformLocations: {
-        [name: string]: WebGLUniformLocation | null;
-    };
-    /** Fixed unit assignment for declared samplers, index into
-     *  `_state.boundTextures`. */
-    samplerUnits: {
-        [name: string]: number;
-    };
    /** Resolved attribute locations, keyed by attribute name. */
-    attributeLocations: {
-        [name: string]: number;
-    };
    /** True once the program has linked and finalization has run; the
-     *  `setEffect*` setters are no-ops until then. Poll `isEffectReady` to advance it. */
-    isReady: boolean;
-
-/** Inputs to `createEffect`: shader sources plus the uniform, sampler and
- *  attribute names whose locations are resolved during readiness finalization. */
-declare interface GLEffectOptions {
-    /** Human-readable label, surfaced in compile/link error messages. */
-    name: string;
-    /** GLSL ES 3.00 source, ready for `gl.shaderSource`. */
-    vertexSource: string;
-    /** GLSL ES 3.00 source, ready for `gl.shaderSource`. */
-    fragmentSource: string;
-    /** Declared uniform names. Locations are resolved during readiness
-     *  finalization. Names not declared here are legal but allocate cache
-     *  slots lazily on first setter use. */
-    uniformNames: readonly string[];
-    /** Declared sampler names, in unit-assignment order. Each gets a fixed
-     *  texture unit assigned during readiness finalization, and
-     *  `gl.uniform1i(loc, unit)` is called exactly once per program lifetime
-     *  (re-run after `webglcontextrestored`). */
-    samplerNames: readonly string[];
-    /** Default `["position"]`. The first attribute is bound to location 0 via
-     *  `gl.bindAttribLocation(program, 0, name)` BEFORE link, so the shared
-     *  fullscreen-quad VAO always feeds the same location. */
-    attributeNames?: readonly string[];
-    /** Optional `#define` block. Each unique `defines` string must be paired
-     *  with the same vertex/fragment source via a separate `createEffect` call —
-     *  the package does NOT cache compiled variants. */
-    defines?: string;
-}
-
-/** Read-only WebGL2 capability limits, queried once at context creation. */
-declare 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.)
- */
-declare 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;
-
-/** A GPU index buffer. The lite-gl counterpart of Babylon's `DataBuffer` for
- *  index data. */
-export declare interface GLIndexBuffer {
-    /** The live `WebGLBuffer`. Swapped on `webglcontextrestored`. */
-    handle: WebGLBuffer;
-    /** Number of indices. */
-    count: number;
-    /** `true` for 32-bit (`Uint32Array`) indices, `false` for 16-bit. */
-    is32Bits: boolean;
-
-/** A recorded Vertex Array Object capturing a static mesh's attribute layout +
- *  index binding. Bind + draw it with {@link drawMesh} each frame — the GPU
- *  replays the entire attribute setup from one `bindVertexArray`. Re-recorded
- *  automatically on `webglcontextrestored`. */
-export declare interface GLMeshVao {
-    /** The live `WebGLVertexArrayObject`. Swapped on `webglcontextrestored`. */
-    handle: WebGLVertexArrayObject;
-
-/** One vertex buffer + its attribute layout, for {@link createMeshVao}. */
-export declare interface GLMeshVertexBuffer {
-    /** The buffer supplying this group's attributes. */
-    buffer: GLVertexBuffer;
-    /** The attributes read from `buffer` (same shape as {@link bindAttributes}). */
-    attributes: readonly GLAttributeDescriptor[];
-    /** Stride mode (see {@link bindAttributes}): `false` (default) → stride `0`
-     *  per attribute; `true` → interleaved stride = Σ(`size`·4). */
-    computeStride?: boolean;
-}
-
-/** A GPU vertex buffer holding interleaved float vertex data. The lite-gl
- *  counterpart of Babylon's `DataBuffer` for vertex data. */
-export declare interface GLVertexBuffer {
-    /** The live `WebGLBuffer`. Swapped on `webglcontextrestored`. */
-    handle: WebGLBuffer;
-    /** Size of the GL buffer in bytes. */
-    byteLength: number;
-
-/**
- * Reset the vertex divisor of every attribute touched by {@link bindAttributes}
- * back to 0 — the lite-gl equivalent of Babylon's `unbindInstanceAttributes`.
- * Call after an instanced draw so a following non-instanced draw is not skewed.
- * No-op on a lost/disposed context.
- *
- * @param engine - The engine.
- */
-export declare function unbindInstanceAttributes(engine: GLEngineContext): void;
-
-/**
- * Upload new contents into (part of) a vertex buffer via `bufferSubData`. A
- * full-buffer update from offset 0 also refreshes the retained CPU data used
- * for context-restore.
- *
- * @param engine - The engine.
- * @param vb - The vertex buffer to update.
- * @param data - The new float data.
- * @param dstByteOffset - Destination byte offset within the buffer. Default 0.
- */
-export declare function updateVertexBuffer(engine: GLEngineContext, vb: GLVertexBuffer, data: Float32Array, dstByteOffset?: number): void;
-
-export { }
+/**
+ * Indexed meshes, dynamic vertex/index buffers, and hardware instancing.
+ *
+ * Part of the public API via the `@babylonjs/lite-gl` barrel. The package is
+ * `sideEffects: false`, so consumers that only render the fullscreen quad /
+ * sprites tree-shake the mesh code out.
+ *
+ * This is the lite-gl equivalent of Babylon's `ThinEngine.createVertexBuffer` /
+ * `createIndexBuffer` / `_releaseBuffer` / `bindIndexBuffer` /
+ * `bindInstancesBuffer` / `unbindInstanceAttributes` / `drawElementsType`. The
+ * attribute binder reproduces Babylon's instancing semantics EXACTLY, including
+ * the `computeStride = false → stride 0` "sliding window" used by ShapeBuilder's
+ * tape buffers (consecutive instances read overlapping vec4 windows) and the
+ * `divisor === undefined → 1` default.
+ *
+ * The mesh path runs on the DEFAULT (null) VAO — every buffer/attribute op binds
+ * `gl.bindVertexArray(null)` first, so it never corrupts the quad / sprite VAOs.
+ * Vertex and index buffers retain their CPU data and re-upload automatically on
+ * `webglcontextrestored`.
+ */
+import type { GLEngineContext } from "./context.js";
+import { type GLEffect } from "./effect.js";
+/** A GPU vertex buffer holding interleaved float vertex data. The lite-gl
+ *  counterpart of Babylon's `DataBuffer` for vertex data. */
+export interface GLVertexBuffer {
+    /** The live `WebGLBuffer`. Swapped on `webglcontextrestored`. */
+    handle: WebGLBuffer;
+    /** Size of the GL buffer in bytes. */
+    byteLength: number;
+}
+/** A GPU index buffer. The lite-gl counterpart of Babylon's `DataBuffer` for
+ *  index data. */
+export interface GLIndexBuffer {
+    /** The live `WebGLBuffer`. Swapped on `webglcontextrestored`. */
+    handle: WebGLBuffer;
+    /** Number of indices. */
+    count: number;
+    /** `true` for 32-bit (`Uint32Array`) indices, `false` for 16-bit. */
+    is32Bits: boolean;
+}
+/**
+ * Describes one vertex attribute fed from a buffer — the lite-gl equivalent of
+ * Babylon's `InstancingAttributeInfo`. Pass an array of these to
+ * {@link bindAttributes}.
+ */
+export interface GLAttributeDescriptor {
+    /** Attribute name; resolved to a location via the effect when `index` is
+     *  omitted (`Effect.getAttributeLocationByName`). */
+    name?: string;
+    /** Explicit attribute location. When set, overrides the `name` lookup. */
+    index?: number;
+    /** Number of components, 1–4. */
+    size: number;
+    /** Byte offset of this attribute's first element within the buffer. Default 0. */
+    offset?: number;
+    /**
+     * Per-instance vertex divisor. **Omitted/`undefined` → `1` (instanced)**,
+     * matching Babylon's `bindInstancesBuffer`. Pass `0` explicitly for a
+     * per-vertex attribute (e.g. the base mesh position).
+     */
+    divisor?: number;
+    /** GL component type. Default `gl.FLOAT`. */
+    type?: GLenum;
+    /** Normalize fixed-point integer data to `[0,1]`/`[-1,1]`. Default `false`. */
+    normalized?: boolean;
+}
+/**
+ * Create a GPU vertex buffer from interleaved float data.
+ *
+ * @param engine - The engine.
+ * @param data - The vertex data. Retained by reference for context-restore — do
+ *  not mutate it in place; use {@link updateVertexBuffer} to change contents.
+ * @param dynamic - Hint that the buffer will be updated frequently
+ *  (`DYNAMIC_DRAW`). Default `false` (`STATIC_DRAW`).
+ * @returns The new {@link GLVertexBuffer}.
+ */
+export declare function createVertexBuffer(engine: GLEngineContext, data: Float32Array, dynamic?: boolean): GLVertexBuffer;
+/**
+ * Upload new contents into (part of) a vertex buffer via `bufferSubData`. A
+ * full-buffer update from offset 0 also refreshes the retained CPU data used
+ * for context-restore.
+ *
+ * @param engine - The engine.
+ * @param vb - The vertex buffer to update.
+ * @param data - The new float data.
+ * @param dstByteOffset - Destination byte offset within the buffer. Default 0.
+ */
+export declare function updateVertexBuffer(engine: GLEngineContext, vb: GLVertexBuffer, data: Float32Array, dstByteOffset?: number): void;
+/**
+ * Create a GPU index buffer. `Uint16Array` → 16-bit indices, `Uint32Array` →
+ * 32-bit. Binds the default VAO first so it never corrupts the quad / sprite
+ * VAO element bindings.
+ *
+ * @param engine - The engine.
+ * @param data - The index data. Retained by reference for context-restore.
+ * @returns The new {@link GLIndexBuffer}.
+ */
+export declare function createIndexBuffer(engine: GLEngineContext, data: Uint16Array | Uint32Array): GLIndexBuffer;
+/** Dispose a vertex or index buffer (delete the GL buffer + unregister). Clears
+ *  the array/element-buffer cache slot if it pointed at this buffer. Idempotent. */
+export declare function disposeBuffer(engine: GLEngineContext, buffer: GLVertexBuffer | GLIndexBuffer): void;
+/**
+ * Bind an index buffer as the current element-array buffer (on the default
+ * VAO). Cached. The lite-gl equivalent of Babylon's `_bindIndexBufferWithCache`.
+ *
+ * @param engine - The engine.
+ * @param ib - The index buffer to bind.
+ */
+export declare function bindIndexBuffer(engine: GLEngineContext, ib: GLIndexBuffer): void;
+/**
+ * Configure vertex attributes from `vb`, reproducing Babylon's
+ * `bindInstancesBuffer` exactly. For each descriptor: resolves the location
+ * (explicit `index` or via the effect), enables the attribute array, issues
+ * `vertexAttribPointer`, and sets the vertex divisor (`undefined → 1`). Every
+ * touched location is tracked so {@link unbindInstanceAttributes} can reset its
+ * divisor afterwards.
+ *
+ * `computeStride` controls the GL stride passed to `vertexAttribPointer`:
+ * - `false` (default) → stride `0`: each attribute is independently tightly
+ *   packed. Combined with overlapping `offset`s this yields the "sliding window"
+ *   ShapeBuilder uses for distance-field tape buffers.
+ * - `true` → stride = Σ(`size`·4 bytes): interleaved per-vertex/per-instance.
+ *
+ * Runs on the default (null) VAO — never corrupts the quad / sprite VAOs.
+ * No-op on a lost/disposed context or before the effect is ready.
+ *
+ * @param engine - The engine.
+ * @param vb - The buffer supplying the attribute data.
+ * @param descriptors - The attribute layout.
+ * @param effect - The effect whose attribute locations resolve unnamed indices.
+ * @param computeStride - See above. Default `false`.
+ */
+export declare function bindAttributes(engine: GLEngineContext, vb: GLVertexBuffer, descriptors: readonly GLAttributeDescriptor[], effect: GLEffect, computeStride?: boolean): void;
+/**
+ * Reset the vertex divisor of every attribute touched by {@link bindAttributes}
+ * back to 0 — the lite-gl equivalent of Babylon's `unbindInstanceAttributes`.
+ * Call after an instanced draw so a following non-instanced draw is not skewed.
+ * No-op on a lost/disposed context.
+ *
+ * @param engine - The engine.
+ */
+export declare function unbindInstanceAttributes(engine: GLEngineContext): void;
+/**
+ * Draw indexed triangles from `ib` — the lite-gl equivalent of Babylon's
+ * `drawElementsType` (triangle fill mode). When `instanceCount > 0` issues
+ * `drawElementsInstanced`, otherwise `drawElements`. No-op on a lost/disposed
+ * context or when no program is current.
+ *
+ * @param engine - The engine.
+ * @param ib - The index buffer (also bound as a side-effect, cached).
+ * @param indexCount - Number of indices to draw.
+ * @param indexStart - First index offset (in indices, not bytes). Default 0.
+ * @param instanceCount - Instance count for instanced draws. Default 0
+ *  (non-instanced).
+ */
+export declare function drawIndexed(engine: GLEngineContext, ib: GLIndexBuffer, indexCount: number, indexStart?: number, instanceCount?: number): void;
+/** One vertex buffer + its attribute layout, for {@link createMeshVao}. */
+export interface GLMeshVertexBuffer {
+    /** The buffer supplying this group's attributes. */
+    buffer: GLVertexBuffer;
+    /** The attributes read from `buffer` (same shape as {@link bindAttributes}). */
+    attributes: readonly GLAttributeDescriptor[];
+    /** Stride mode (see {@link bindAttributes}): `false` (default) → stride `0`
+     *  per attribute; `true` → interleaved stride = Σ(`size`·4). */
+    computeStride?: boolean;
+}
+/** A recorded Vertex Array Object capturing a static mesh's attribute layout +
+ *  index binding. Bind + draw it with {@link drawMesh} each frame — the GPU
+ *  replays the entire attribute setup from one `bindVertexArray`. Re-recorded
+ *  automatically on `webglcontextrestored`. */
+export interface GLMeshVao {
+    /** The live `WebGLVertexArrayObject`. Swapped on `webglcontextrestored`. */
+    handle: WebGLVertexArrayObject;
+}
+/**
+ * Record a static mesh's attribute layout + index binding into a new VAO. The
+ * effect MUST be ready (its attribute locations are resolved here, once). Returns
+ * a {@link GLMeshVao} to draw with {@link drawMesh}.
+ *
+ * @param engine - The engine.
+ * @param vertexBuffers - One or more buffers + their attribute layouts.
+ * @param indexBuffer - The index buffer recorded into the VAO.
+ * @param effect - The effect whose attribute locations resolve unnamed indices.
+ * @returns The recorded {@link GLMeshVao}.
+ */
+export declare function createMeshVao(engine: GLEngineContext, vertexBuffers: readonly GLMeshVertexBuffer[], indexBuffer: GLIndexBuffer, effect: GLEffect): GLMeshVao;
+/**
+ * Bind a {@link GLMeshVao} (cached `gl.bindVertexArray`). Rarely called directly —
+ * {@link drawMesh} binds it for you. Binding restores the VAO's recorded element
+ * binding, so the element-buffer cache is updated in lock-step.
+ *
+ * @param engine - The engine.
+ * @param vao - The mesh VAO to bind.
+ */
+export declare function bindMeshVao(engine: GLEngineContext, vao: GLMeshVao): void;
+/**
+ * Draw a static mesh recorded with {@link createMeshVao}: binds its VAO (cached),
+ * flushes deferred GL state, and issues ONE `drawElements` (or
+ * `drawElementsInstanced` when `instanceCount > 0`) over the VAO's full index
+ * buffer. No per-draw attribute (re)binding. No-op on a lost/disposed context, a
+ * disposed VAO, or when no program is current.
+ *
+ * @param engine - The engine.
+ * @param vao - The mesh VAO to draw.
+ * @param instanceCount - Instance count for instanced draws. Default 0 (non-instanced).
+ */
+export declare function drawMesh(engine: GLEngineContext, vao: GLMeshVao, instanceCount?: number): void;
+/** Dispose a {@link GLMeshVao}: delete the VAO and unregister its restore hook.
+ *  Does NOT dispose the vertex/index buffers (the caller owns those). Idempotent. */
+export declare function disposeMeshVao(engine: GLEngineContext, vao: GLMeshVao): void;