@babylonjs/lite-gl 0.1.0 → 0.2.0

package/render-target.d.ts

@@ -1,290 +1,233 @@
-/**
- * Bind the render target's framebuffer as the draw target and set the viewport
- * to cover it. `rt = null` binds the default (canvas) framebuffer and resets the
- * viewport to the full canvas — the counterpart of Babylon's
- * `restoreDefaultFramebuffer`. Subsequent `drawEffect` / `drawIndexed` /
- * `clearEngine` calls write into the bound target.
- *
- * Cached. No-op on a lost/disposed context or a disposed `rt`. Mipmaps are NOT
- * regenerated here — refresh a target's mip chain explicitly via
- * {@link generateRenderTargetMipMaps} after rendering into it.
- *
- * @param engine - The engine.
- * @param rt - The render target to draw into, or `null` for the canvas.
- */
-export declare function bindRenderTarget(engine: GLEngineContext, rt: GLRenderTarget | null): void;
-
-/**
- * Create an offscreen **float / half-float** render target — the HDR opt-in
- * counterpart of {@link createRenderTarget}. This is the only render-target
- * factory that references the `RGBA16F` / `RGBA32F` sized-format table, so RGBA8
- * consumers ship none of it.
- *
- * Defaults to `gl.HALF_FLOAT`; pass `options.type = gl.FLOAT` for full 32-bit.
- * The requested type is downgraded to the best renderable type the engine
- * supports (mirroring Babylon's `getTextureType`).
- *
- * @param engine - The engine to allocate GL resources on.
- * @param options - See {@link GLFloatRenderTargetOptions}.
- * @returns The new {@link GLRenderTarget}.
- * @throws As {@link createRenderTarget}.
- */
-export declare function createFloatRenderTarget(engine: GLEngineContext, options: GLFloatRenderTargetOptions): GLRenderTarget;
-
-/**
- * Create a {@link GLPingPong}: two same-sized {@link GLRenderTarget}s for
- * self-feedback effects. `read` starts as the first target and `write` the
- * second; {@link GLPingPong.swap} exchanges them allocation-free.
- *
- * @param engine - The engine to create GL resources on.
- * @param options - Applied identically to both targets.
- * @returns The new {@link GLPingPong}.
- * @throws As {@link createRenderTarget}. If the second target fails to build the
- *  first is disposed before rethrowing (no leak).
- */
-export declare function createPingPong(engine: GLEngineContext, options: GLRenderTargetOptions): GLPingPong;
-
-/**
- * Create an offscreen **RGBA8** render target.
- *
- * The color attachment is an owned {@link GLTexture} (rebuilt by this target's
- * own restore hook), unless {@link GLRenderTargetOptions.colorTexture} supplies a
- * caller-managed (BYO) one. Mirrors Babylon's `createRenderTargetTexture`.
- *
- * @param engine - The engine to allocate GL resources on.
- * @param options - See {@link GLRenderTargetOptions} (`width`/`height` required).
- * @returns The new {@link GLRenderTarget}.
- * @throws If `width`/`height` are not positive integers, a GL handle could not
- *  be allocated, or the resulting framebuffer is not complete. On failure every
- *  partial GPU object (including an owned color texture) is released first.
- */
-export declare function createRenderTarget(engine: GLEngineContext, options: GLRenderTargetOptions): GLRenderTarget;
-
-/**
- * Release both targets of a {@link GLPingPong}. Idempotent, and a no-op for
- * `null`/`undefined` (matching {@link disposeRenderTarget}).
- *
- * @param engine - The engine that owns `pp`.
- * @param pp - The ping-pong pair to release, or `null`/`undefined` for a no-op.
- */
-export declare function disposePingPong(engine: GLEngineContext, pp: GLPingPong | null | undefined): void;
-
-/**
- * Release the render target's framebuffer, depth/stencil renderbuffer and (iff
- * owned) color texture, and unregister it from the engine. Idempotent, and a
- * no-op for `null`/`undefined` (so an optional target can be released
- * unconditionally). Clears the bound-framebuffer cache if it pointed at this
- * target, and any sampler slot that held the color texture handle.
- *
- * A BYO {@link GLRenderTargetOptions.colorTexture} is NOT disposed here — it is
- * engine-managed and the caller owns its lifetime.
- *
- * @param engine - The engine.
- * @param rt - The render target to dispose, or `null`/`undefined` for a no-op.
- */
-export declare function disposeRenderTarget(engine: GLEngineContext, rt: GLRenderTarget | null | undefined): void;
-
-/** Regenerate a render target's color-attachment mip chain from its (freshly
- *  rendered) level-0 — mipmaps for render targets are a pure manual opt-in
- *  (call this after rendering into the target). No-op for a disposed target, a
- *  handle-less color attachment, or a lost/disposed context. */
-export declare function generateRenderTargetMipMaps(engine: GLEngineContext, rt: GLRenderTarget): void;
-
-/** 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;
-
-/** Options for {@link createFloatRenderTarget} — {@link GLRenderTargetOptions}
- *  plus the float color `type`. */
-export declare interface GLFloatRenderTargetOptions extends GLRenderTargetOptions {
-    /** Float color attachment type. Default `gl.HALF_FLOAT`. Pass `gl.FLOAT` for
-     *  full 32-bit. Downgraded to the best renderable type the engine supports
-     *  (`caps.textureFloatRender` / `caps.textureHalfFloatRender`), mirroring
-     *  Babylon's `getTextureType`. */
-    type?: GLenum;
-}
-
-/**
- * A pair of {@link GLRenderTarget}s for self-feedback effects: SAMPLE the
- * {@link GLPingPong.read | read} target (last frame's output) while RENDERING
- * into the {@link GLPingPong.write | write} target, then {@link GLPingPong.swap}.
- */
-export declare interface GLPingPong {
-    /** The target to SAMPLE this frame (the previous frame's output). */
-    readonly read: GLRenderTarget;
-    /** The target to RENDER into this frame. */
-    readonly write: GLRenderTarget;
-    /** Exchange `read` and `write`. Call after rendering the `write` target each
-     *  frame. Allocation-free — flips an internal index, no objects created. */
-    swap(): void;
-
-/**
- * An offscreen render target — a `WebGLFramebuffer` wrapping a color
- * {@link GLTexture} and an optional depth / stencil renderbuffer. The lite-gl
- * counterpart of Babylon's `RenderTargetWrapper`.
- */
-export declare interface GLRenderTarget {
-    /** The color attachment, sampleable like any other {@link GLTexture}
-     *  (`setEffectTexture` / `bindTexture`). For an owned attachment its handle
-     *  is swapped on `webglcontextrestored` while consumers keep this same
-     *  reference. */
-    texture: GLTexture;
-    /** Color attachment width in texels. */
-    width: number;
-    /** Color attachment height in texels. */
-    height: number;
-    /** True once the color attachment + framebuffer are allocated. */
-    isReady: boolean;
-
-/** Options for {@link createRenderTarget}. `width`/`height` are required; every
- *  other field has a Babylon-matching default. The bare
- *  `createRenderTarget(engine, { width, height })` makes an RGBA8 color-only
- *  target with linear filtering and clamp wrapping. */
-export declare interface GLRenderTargetOptions {
-    /** Color attachment width in texels. Must be a positive integer. */
-    width: number;
-    /** Color attachment height in texels. Must be a positive integer. */
-    height: number;
-    /** Allocate a depth renderbuffer (`DEPTH_COMPONENT16`). Default `false`.
-     *  Stencil is NOT a create option — opt in (packed depth+stencil, or
-     *  stencil-only) via `generateRenderTargetStencil`
-     *  (`@babylonjs/lite-gl/depth-stencil`), which keeps the stencil/packed
-     *  renderbuffer code out of the render-target core bundle. */
-    generateDepthBuffer?: boolean;
-    /** Color texture minification filter. Default `gl.LINEAR`. */
-    minFilter?: GLenum;
-    /** Color texture magnification filter. Default `gl.LINEAR`. */
-    magFilter?: GLenum;
-    /** Color texture S wrap. Default `gl.CLAMP_TO_EDGE`. */
-    wrapS?: GLenum;
-    /** Color texture T wrap. Default `gl.CLAMP_TO_EDGE`. */
-    wrapT?: GLenum;
-    /** Attach a caller-supplied (BYO) color {@link GLTexture} instead of creating
-     *  one. When supplied the render target does NOT own or restore it — the
-     *  texture is engine-managed (restored by the standard texture-restore path
-     *  first) and the RT re-attaches its swapped handle afterwards. The caller is
-     *  responsible for sizing it to `width`×`height` and for disposing it. */
-    colorTexture?: GLTexture;
-}
-
-/**
- * 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.
- */
-declare 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;
-
-/**
- * Synchronously read back a rectangle of the render target's color attachment
- * via `gl.readPixels` — the lite-gl equivalent of Babylon's
- * `_readTexturePixelsSync`. Binds the target's framebuffer (leaving it bound,
- * matching Babylon).
- *
- * The returned array element type follows the color attachment type:
- * `Uint8Array` for `UNSIGNED_BYTE`, `Float32Array` for `FLOAT`, `Uint16Array`
- * for `HALF_FLOAT`. Origin is GL bottom-left.
- *
- * @param engine - The engine.
- * @param rt - The render target to read from.
- * @param x - Lower-left X of the read rectangle, in texels.
- * @param y - Lower-left Y of the read rectangle, in texels.
- * @param width - Read rectangle width in texels.
- * @param height - Read rectangle height in texels.
- * @param into - Optional preallocated buffer (`width*height*4` elements of the
- *  matching type). Reused to avoid per-call allocation.
- * @returns The pixel buffer (the provided `into`, or a freshly allocated one).
- *  Empty buffer on a lost/disposed context.
- */
-export declare function readRenderTargetPixels(engine: GLEngineContext, rt: GLRenderTarget, x: number, y: number, width: number, height: number, into?: ArrayBufferView): ArrayBufferView;
-
-/**
- * Resize both targets of a {@link GLPingPong}. No-op when disposed.
- *
- * @param engine - The engine that owns `pp`.
- * @param pp - The ping-pong pair to resize.
- * @param width - New width in texels (positive integer).
- * @param height - New height in texels (positive integer).
- */
-export declare function resizePingPong(engine: GLEngineContext, pp: GLPingPong, width: number, height: number): void;
-
-/**
- * Resize the render target's color attachment (and depth/stencil renderbuffer).
- * Reallocates storage at the new size; the contents are discarded. The
- * `GLRenderTarget` / `GLTexture` identity is preserved, so consumers and
- * effect-sampler bindings holding the reference stay valid. If this target was
- * the live draw target, it is rebound (with the new-size viewport) afterwards.
- *
- * No-op when the size is unchanged or `rt` is disposed. While the context is
- * lost the new size is recorded but the GL reallocation is deferred to the
- * restore hook.
- *
- * @param engine - The engine.
- * @param rt - The render target to resize.
- * @param width - New width in texels (≥ 1).
- * @param height - New height in texels (≥ 1).
- */
-export declare function resizeRenderTarget(engine: GLEngineContext, rt: GLRenderTarget, width: number, height: number): void;
-
-export { }
+/**
+ * Render-to-texture (offscreen framebuffer) support.
+ *
+ * Part of the public API via the `@babylonjs/lite-gl` barrel. The package is
+ * `sideEffects: false`, so consumers that only render fullscreen effects to the
+ * canvas tree-shake the FBO code out.
+ *
+ * This is the lite-gl equivalent of Babylon's `RenderTargetWrapper` +
+ * `ThinEngine.createRenderTargetTexture` / `bindFramebuffer` /
+ * `restoreDefaultFramebuffer` / `_readTexturePixelsSync`. A render target owns a
+ * color {@link GLTexture} (or attaches a caller-supplied one) plus an optional
+ * depth and/or stencil renderbuffer, all wrapped in a single
+ * `WebGLFramebuffer`.
+ *
+ * The default {@link createRenderTarget} makes an **RGBA8** color target and
+ * ships none of the HDR sized-format knowledge; {@link createFloatRenderTarget}
+ * is the separate opt-in for float / half-float color attachments (it alone
+ * carries the `RGBA16F` / `RGBA32F` table, so RGBA8 consumers tree-shake it
+ * away).
+ *
+ * The full color/depth/stencil GPU set is rebuilt automatically on
+ * `webglcontextrestored` — the render target registers itself with the engine's
+ * `_renderTargets` registry, and the context-restore protocol calls its
+ * `_restore` closure AFTER the standalone texture replay. A caller-supplied
+ * (BYO) color texture lives in the engine's `_textures` registry and is restored
+ * there first; the RT then re-attaches its freshly-swapped handle.
+ */
+import { type GLTexture } from "./texture.js";
+import type { GLEngineContext } from "./context.js";
+/** Options for {@link createRenderTarget}. `width`/`height` are required; every
+ *  other field has a Babylon-matching default. The bare
+ *  `createRenderTarget(engine, { width, height })` makes an RGBA8 color-only
+ *  target with linear filtering and clamp wrapping. */
+export interface GLRenderTargetOptions {
+    /** Color attachment width in texels. Must be a positive integer. */
+    width: number;
+    /** Color attachment height in texels. Must be a positive integer. */
+    height: number;
+    /** Allocate a depth renderbuffer (`DEPTH_COMPONENT16`). Default `false`.
+     *  Stencil is NOT a create option — opt in (packed depth+stencil, or
+     *  stencil-only) via `generateRenderTargetStencil`
+     *  (`@babylonjs/lite-gl`), which keeps the stencil/packed
+     *  renderbuffer code out of the render-target core bundle. */
+    generateDepthBuffer?: boolean;
+    /** Color texture minification filter. Default `gl.LINEAR`. */
+    minFilter?: GLenum;
+    /** Color texture magnification filter. Default `gl.LINEAR`. */
+    magFilter?: GLenum;
+    /** Color texture S wrap. Default `gl.CLAMP_TO_EDGE`. */
+    wrapS?: GLenum;
+    /** Color texture T wrap. Default `gl.CLAMP_TO_EDGE`. */
+    wrapT?: GLenum;
+    /** Attach a caller-supplied (BYO) color {@link GLTexture} instead of creating
+     *  one. When supplied the render target does NOT own or restore it — the
+     *  texture is engine-managed (restored by the standard texture-restore path
+     *  first) and the RT re-attaches its swapped handle afterwards. The caller is
+     *  responsible for sizing it to `width`×`height` and for disposing it. */
+    colorTexture?: GLTexture;
+}
+/** Options for {@link createFloatRenderTarget} — {@link GLRenderTargetOptions}
+ *  plus the float color `type`. */
+export interface GLFloatRenderTargetOptions extends GLRenderTargetOptions {
+    /** Float color attachment type. Default `gl.HALF_FLOAT`. Pass `gl.FLOAT` for
+     *  full 32-bit. Downgraded to the best renderable type the engine supports
+     *  (`caps.textureFloatRender` / `caps.textureHalfFloatRender`), mirroring
+     *  Babylon's `getTextureType`. */
+    type?: GLenum;
+}
+/**
+ * An offscreen render target — a `WebGLFramebuffer` wrapping a color
+ * {@link GLTexture} and an optional depth / stencil renderbuffer. The lite-gl
+ * counterpart of Babylon's `RenderTargetWrapper`.
+ */
+export interface GLRenderTarget {
+    /** The color attachment, sampleable like any other {@link GLTexture}
+     *  (`setEffectTexture` / `bindTexture`). For an owned attachment its handle
+     *  is swapped on `webglcontextrestored` while consumers keep this same
+     *  reference. */
+    texture: GLTexture;
+    /** Color attachment width in texels. */
+    width: number;
+    /** Color attachment height in texels. */
+    height: number;
+    /** True once the color attachment + framebuffer are allocated. */
+    isReady: boolean;
+}
+/**
+ * A pair of {@link GLRenderTarget}s for self-feedback effects: SAMPLE the
+ * {@link GLPingPong.read | read} target (last frame's output) while RENDERING
+ * into the {@link GLPingPong.write | write} target, then {@link GLPingPong.swap}.
+ */
+export interface GLPingPong {
+    /** The target to SAMPLE this frame (the previous frame's output). */
+    readonly read: GLRenderTarget;
+    /** The target to RENDER into this frame. */
+    readonly write: GLRenderTarget;
+    /** Exchange `read` and `write`. Call after rendering the `write` target each
+     *  frame. Allocation-free — flips an internal index, no objects created. */
+    swap(): void;
+}
+/**
+ * Create an offscreen **RGBA8** render target.
+ *
+ * The color attachment is an owned {@link GLTexture} (rebuilt by this target's
+ * own restore hook), unless {@link GLRenderTargetOptions.colorTexture} supplies a
+ * caller-managed (BYO) one. Mirrors Babylon's `createRenderTargetTexture`.
+ *
+ * @param engine - The engine to allocate GL resources on.
+ * @param options - See {@link GLRenderTargetOptions} (`width`/`height` required).
+ * @returns The new {@link GLRenderTarget}.
+ * @throws If `width`/`height` are not positive integers, a GL handle could not
+ *  be allocated, or the resulting framebuffer is not complete. On failure every
+ *  partial GPU object (including an owned color texture) is released first.
+ */
+export declare function createRenderTarget(engine: GLEngineContext, options: GLRenderTargetOptions): GLRenderTarget;
+/**
+ * Create an offscreen **float / half-float** render target — the HDR opt-in
+ * counterpart of {@link createRenderTarget}. This is the only render-target
+ * factory that references the `RGBA16F` / `RGBA32F` sized-format table, so RGBA8
+ * consumers ship none of it.
+ *
+ * Defaults to `gl.HALF_FLOAT`; pass `options.type = gl.FLOAT` for full 32-bit.
+ * The requested type is downgraded to the best renderable type the engine
+ * supports (mirroring Babylon's `getTextureType`).
+ *
+ * @param engine - The engine to allocate GL resources on.
+ * @param options - See {@link GLFloatRenderTargetOptions}.
+ * @returns The new {@link GLRenderTarget}.
+ * @throws As {@link createRenderTarget}.
+ */
+export declare function createFloatRenderTarget(engine: GLEngineContext, options: GLFloatRenderTargetOptions): GLRenderTarget;
+/**
+ * Bind the render target's framebuffer as the draw target and set the viewport
+ * to cover it. `rt = null` binds the default (canvas) framebuffer and resets the
+ * viewport to the full canvas — the counterpart of Babylon's
+ * `restoreDefaultFramebuffer`. Subsequent `drawEffect` / `drawIndexed` /
+ * `clearEngine` calls write into the bound target.
+ *
+ * Cached. No-op on a lost/disposed context or a disposed `rt`. Mipmaps are NOT
+ * regenerated here — refresh a target's mip chain explicitly via
+ * {@link generateRenderTargetMipMaps} after rendering into it.
+ *
+ * @param engine - The engine.
+ * @param rt - The render target to draw into, or `null` for the canvas.
+ */
+export declare function bindRenderTarget(engine: GLEngineContext, rt: GLRenderTarget | null): void;
+/** Regenerate a render target's color-attachment mip chain from its (freshly
+ *  rendered) level-0 — mipmaps for render targets are a pure manual opt-in
+ *  (call this after rendering into the target). No-op for a disposed target, a
+ *  handle-less color attachment, or a lost/disposed context. */
+export declare function generateRenderTargetMipMaps(engine: GLEngineContext, rt: GLRenderTarget): void;
+/**
+ * Resize the render target's color attachment (and depth/stencil renderbuffer).
+ * Reallocates storage at the new size; the contents are discarded. The
+ * `GLRenderTarget` / `GLTexture` identity is preserved, so consumers and
+ * effect-sampler bindings holding the reference stay valid. If this target was
+ * the live draw target, it is rebound (with the new-size viewport) afterwards.
+ *
+ * No-op when the size is unchanged or `rt` is disposed. While the context is
+ * lost the new size is recorded but the GL reallocation is deferred to the
+ * restore hook.
+ *
+ * @param engine - The engine.
+ * @param rt - The render target to resize.
+ * @param width - New width in texels (≥ 1).
+ * @param height - New height in texels (≥ 1).
+ */
+export declare function resizeRenderTarget(engine: GLEngineContext, rt: GLRenderTarget, width: number, height: number): void;
+/**
+ * Synchronously read back a rectangle of the render target's color attachment
+ * via `gl.readPixels` — the lite-gl equivalent of Babylon's
+ * `_readTexturePixelsSync`. Binds the target's framebuffer (leaving it bound,
+ * matching Babylon).
+ *
+ * The returned array element type follows the color attachment type:
+ * `Uint8Array` for `UNSIGNED_BYTE`, `Float32Array` for `FLOAT`, `Uint16Array`
+ * for `HALF_FLOAT`. Origin is GL bottom-left.
+ *
+ * @param engine - The engine.
+ * @param rt - The render target to read from.
+ * @param x - Lower-left X of the read rectangle, in texels.
+ * @param y - Lower-left Y of the read rectangle, in texels.
+ * @param width - Read rectangle width in texels.
+ * @param height - Read rectangle height in texels.
+ * @param into - Optional preallocated buffer (`width*height*4` elements of the
+ *  matching type). Reused to avoid per-call allocation.
+ * @returns The pixel buffer (the provided `into`, or a freshly allocated one).
+ *  Empty buffer on a lost/disposed context.
+ */
+export declare function readRenderTargetPixels(engine: GLEngineContext, rt: GLRenderTarget, x: number, y: number, width: number, height: number, into?: ArrayBufferView): ArrayBufferView;
+/**
+ * Release the render target's framebuffer, depth/stencil renderbuffer and (iff
+ * owned) color texture, and unregister it from the engine. Idempotent, and a
+ * no-op for `null`/`undefined` (so an optional target can be released
+ * unconditionally). Clears the bound-framebuffer cache if it pointed at this
+ * target, and any sampler slot that held the color texture handle.
+ *
+ * A BYO {@link GLRenderTargetOptions.colorTexture} is NOT disposed here — it is
+ * engine-managed and the caller owns its lifetime.
+ *
+ * @param engine - The engine.
+ * @param rt - The render target to dispose, or `null`/`undefined` for a no-op.
+ */
+export declare function disposeRenderTarget(engine: GLEngineContext, rt: GLRenderTarget | null | undefined): void;
+/**
+ * Create a {@link GLPingPong}: two same-sized {@link GLRenderTarget}s for
+ * self-feedback effects. `read` starts as the first target and `write` the
+ * second; {@link GLPingPong.swap} exchanges them allocation-free.
+ *
+ * @param engine - The engine to create GL resources on.
+ * @param options - Applied identically to both targets.
+ * @returns The new {@link GLPingPong}.
+ * @throws As {@link createRenderTarget}. If the second target fails to build the
+ *  first is disposed before rethrowing (no leak).
+ */
+export declare function createPingPong(engine: GLEngineContext, options: GLRenderTargetOptions): GLPingPong;
+/**
+ * Resize both targets of a {@link GLPingPong}. No-op when disposed.
+ *
+ * @param engine - The engine that owns `pp`.
+ * @param pp - The ping-pong pair to resize.
+ * @param width - New width in texels (positive integer).
+ * @param height - New height in texels (positive integer).
+ */
+export declare function resizePingPong(engine: GLEngineContext, pp: GLPingPong, width: number, height: number): void;
+/**
+ * Release both targets of a {@link GLPingPong}. Idempotent, and a no-op for
+ * `null`/`undefined` (matching {@link disposeRenderTarget}).
+ *
+ * @param engine - The engine that owns `pp`.
+ * @param pp - The ping-pong pair to release, or `null`/`undefined` for a no-op.
+ */
+export declare function disposePingPong(engine: GLEngineContext, pp: GLPingPong | null | undefined): void;