@babylonjs/lite-gl 0.1.0 → 0.2.0

package/depth-stencil.d.ts

@@ -1,231 +1,155 @@
-/**
- * Clear the currently-bound framebuffer's color / depth / stencil buffers — the
- * lite-gl equivalent of Babylon's `clear(color, backBuffer, depth, stencil)`.
- * Depth/stencil clears respect the current write masks (set them first via
- * {@link setDepthState} / {@link setStencilState}). No-op when nothing is
- * requested or the context is lost/disposed.
- *
- * @param engine - The engine.
- * @param options - Which buffers to clear (and the color value).
- */
-export declare function clearEngine(engine: GLEngineContext, options: GLClearOptions): void;
-
-/**
- * Opt-in: give a `/render-target` {@link GLRenderTarget} a stencil attachment,
- * replacing the core's depth-only `DEPTH_COMPONENT16` renderbuffer with either a
- * packed **`DEPTH24_STENCIL8`** buffer (default — depth *and* stencil) or a
- * stencil-only **`STENCIL_INDEX8`** buffer.
- *
- * Stencil is intentionally NOT a {@link createRenderTarget} option: keeping this
- * helper in the `/depth-stencil` sub-entry means the stencil/packed renderbuffer
- * code tree-shakes out of every bundle that only needs a color (and optional
- * depth) target.
- *
- * The attachment is **restore-correct**: it is rebuilt automatically — at the new
- * size on {@link resizeRenderTarget}, and into the fresh framebuffer after a
- * `webglcontextrestored` event — so the stencil survives for the life of the
- * target, and {@link disposeRenderTarget} releases it along with the target.
- *
- * No-op on a lost/disposed context or a disposed target.
- *
- * @param engine - The engine that owns `rt`.
- * @param rt - The render target to attach the stencil buffer to.
- * @param options - `depth` (default `true`): when `true` the attachment is a
- *  packed depth+stencil buffer (`DEPTH24_STENCIL8` on `DEPTH_STENCIL_ATTACHMENT`)
- *  — the common case, and the correct choice when the target was created with
- *  `generateDepthBuffer: true`. When `false` the attachment is stencil-only
- *  (`STENCIL_INDEX8` on `STENCIL_ATTACHMENT`).
- * @throws If a renderbuffer handle could not be allocated or the framebuffer is
- *  incomplete after attaching.
- */
-export declare function generateRenderTargetStencil(engine: GLEngineContext, rt: GLRenderTarget, options?: {
-    depth?: boolean;
-}): void;
-
-/** Options for {@link clearEngine}. */
-export declare interface GLClearOptions {
-    /** When set, clears the color buffer to this RGBA color (alpha default 1). */
-    color?: {
-        r: number;
-        g: number;
-        b: number;
-        a?: number;
-    };
-    /** Clear the depth buffer (respects the current depth write mask). */
-    depth?: boolean;
-    /** Clear the stencil buffer (respects the current stencil write mask). */
-    stencil?: boolean;
-}
-
-/** Depth-buffer configuration for {@link setDepthState}. Omitted fields are
- *  left unchanged. */
-export declare interface GLDepthState {
-    /** Enable/disable the depth test (`gl.enable/disable(DEPTH_TEST)`). */
-    test?: boolean;
-    /** Enable/disable depth writes (`gl.depthMask`). */
-    write?: boolean;
-    /** Depth comparison function (`gl.depthFunc`), e.g. `gl.LESS`. */
-    func?: GLenum;
-}
-
-/** 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;
-
-/**
- * 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`.
- */
-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_2;
-    /** Color attachment width in texels. */
-    width: number;
-    /** Color attachment height in texels. */
-    height: number;
-    /** True once the color attachment + framebuffer are allocated. */
-    isReady: boolean;
-
-/** Stencil configuration for {@link setStencilState}. Omitted fields are left
- *  unchanged. The `func`/`ref`/`funcMask` triple and the
- *  `opFail`/`opZFail`/`opZPass` triple are each applied as a unit (any member
- *  present re-issues that GL call, merging the unspecified members from cache). */
-export declare interface GLStencilState {
-    /** Enable/disable the stencil test (`gl.enable/disable(STENCIL_TEST)`). */
-    test?: boolean;
-    /** Stencil write mask (`gl.stencilMask`). */
-    mask?: number;
-    /** Comparison function (`gl.stencilFunc` arg 1), e.g. `gl.ALWAYS`. */
-    func?: GLenum;
-    /** Reference value (`gl.stencilFunc` arg 2). */
-    ref?: number;
-    /** Comparison mask (`gl.stencilFunc` arg 3). */
-    funcMask?: number;
-    /** Op when the stencil test fails (`gl.stencilOp` arg 1). */
-    opFail?: GLenum;
-    /** Op when the stencil test passes but depth fails (`gl.stencilOp` arg 2). */
-    opZFail?: GLenum;
-    /** Op when both stencil and depth pass (`gl.stencilOp` arg 3). */
-    opZPass?: 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.
- */
-declare interface GLTexture_2 {
-    /** 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;
-
-/**
- * Buffer the color write mask into the DESIRED state — the lite-gl equivalent of
- * Babylon's `setColorWrite` (which passes the same flag to all four channels).
- * Flushed to GL (`gl.colorMask`) by `applyGLStates` before the next draw /
- * clear.
- *
- * @param engine - The engine.
- * @param r - Write red.
- * @param g - Write green.
- * @param b - Write blue.
- * @param a - Write alpha.
- */
-export declare function setColorMask(engine: GLEngineContext, r: boolean, g: boolean, b: boolean, a: boolean): void;
-
-/**
- * Enable/disable face culling and (optionally) set the cull face — the lite-gl
- * equivalent of `engine.depthCullingState.cull` + `cullFace`.
- *
- * @param engine - The engine.
- * @param enabled - Enable (`true`) or disable (`false`) `gl.CULL_FACE`.
- * @param face - Optional cull face (`gl.BACK` / `gl.FRONT` / `gl.FRONT_AND_BACK`).
- */
-export declare function setCullState(engine: GLEngineContext, enabled: boolean, face?: GLenum): void;
-
-/**
- * Buffer depth-buffer state (test enable, write mask, comparison function) into
- * the DESIRED state — the lite-gl equivalent of mutating Babylon's
- * `engine.depthCullingState.{depthTest,depthMask,depthFunc}`. Flushed to GL by
- * `applyGLStates` before the next draw / clear; omitted fields are untouched.
- *
- * @param engine - The engine.
- * @param state - The depth fields to change. Omitted fields are untouched.
- */
-export declare function setDepthState(engine: GLEngineContext, state: GLDepthState): void;
-
-/**
- * Buffer stencil state (test enable, write mask, comparison func triple, op
- * triple) into the DESIRED state — the lite-gl equivalent of mutating Babylon's
- * `engine.stencilState.*`. Flushed by `applyGLStates` before the next draw /
- * clear; omitted fields are untouched (merge-from-desired).
- *
- * @param engine - The engine.
- * @param state - The stencil fields to change. Omitted fields are untouched.
- */
-export declare function setStencilState(engine: GLEngineContext, state: GLStencilState): void;
-
-export { }
+/**
+ * Depth, stencil, color-mask and clear state — the lite-gl counterpart of
+ * Babylon's `_depthCullingState` / `_stencilState` / `setColorWrite` / `clear`.
+ *
+ * Like Babylon, these setters are DEFERRED: they buffer the requested values
+ * into the DESIRED (`d*`) mirror fields of `GLState` and raise `statesDirty`,
+ * issuing NO `gl.*` calls themselves. `applyGLStates` (apply-states.ts) flushes
+ * the diff to GL right before each draw (and before `clearEngine`'s `gl.clear`,
+ * since a clear respects the current write masks). Every field is reconciled
+ * independently, so a flush that changes only one sub-state (e.g. just the
+ * stencil op triple) issues only that GL call. Omitted setter fields leave the
+ * corresponding desired value untouched (merge-from-desired).
+ *
+ * All setters are no-ops on a lost/disposed context.
+ *
+ * This module also hosts {@link generateRenderTargetStencil} — the tree-shakeable
+ * opt-in that gives a `/render-target` {@link GLRenderTarget} a stencil (or packed
+ * depth+stencil) attachment. Keeping the STENCIL_INDEX8 / DEPTH24_STENCIL8
+ * renderbuffer code here (rather than in the render-target core) means a consumer
+ * that only needs a depth buffer never ships it. The one-way type import below
+ * (`depth-stencil` importing `render-target`) introduces NO cycle: render-target
+ * must not import this module.
+ */
+import type { GLEngineContext } from "./context.js";
+import type { GLRenderTarget } from "./render-target.js";
+/** Depth-buffer configuration for {@link setDepthState}. Omitted fields are
+ *  left unchanged. */
+export interface GLDepthState {
+    /** Enable/disable the depth test (`gl.enable/disable(DEPTH_TEST)`). */
+    test?: boolean;
+    /** Enable/disable depth writes (`gl.depthMask`). */
+    write?: boolean;
+    /** Depth comparison function (`gl.depthFunc`), e.g. `gl.LESS`. */
+    func?: GLenum;
+}
+/** Stencil configuration for {@link setStencilState}. Omitted fields are left
+ *  unchanged. The `func`/`ref`/`funcMask` triple and the
+ *  `opFail`/`opZFail`/`opZPass` triple are each applied as a unit (any member
+ *  present re-issues that GL call, merging the unspecified members from cache). */
+export interface GLStencilState {
+    /** Enable/disable the stencil test (`gl.enable/disable(STENCIL_TEST)`). */
+    test?: boolean;
+    /** Stencil write mask (`gl.stencilMask`). */
+    mask?: number;
+    /** Comparison function (`gl.stencilFunc` arg 1), e.g. `gl.ALWAYS`. */
+    func?: GLenum;
+    /** Reference value (`gl.stencilFunc` arg 2). */
+    ref?: number;
+    /** Comparison mask (`gl.stencilFunc` arg 3). */
+    funcMask?: number;
+    /** Op when the stencil test fails (`gl.stencilOp` arg 1). */
+    opFail?: GLenum;
+    /** Op when the stencil test passes but depth fails (`gl.stencilOp` arg 2). */
+    opZFail?: GLenum;
+    /** Op when both stencil and depth pass (`gl.stencilOp` arg 3). */
+    opZPass?: GLenum;
+}
+/** Options for {@link clearEngine}. */
+export interface GLClearOptions {
+    /** When set, clears the color buffer to this RGBA color (alpha default 1). */
+    color?: {
+        r: number;
+        g: number;
+        b: number;
+        a?: number;
+    };
+    /** Clear the depth buffer (respects the current depth write mask). */
+    depth?: boolean;
+    /** Clear the stencil buffer (respects the current stencil write mask). */
+    stencil?: boolean;
+}
+/**
+ * Buffer depth-buffer state (test enable, write mask, comparison function) into
+ * the DESIRED state — the lite-gl equivalent of mutating Babylon's
+ * `engine.depthCullingState.{depthTest,depthMask,depthFunc}`. Flushed to GL by
+ * `applyGLStates` before the next draw / clear; omitted fields are untouched.
+ *
+ * @param engine - The engine.
+ * @param state - The depth fields to change. Omitted fields are untouched.
+ */
+export declare function setDepthState(engine: GLEngineContext, state: GLDepthState): void;
+/**
+ * Enable/disable face culling and (optionally) set the cull face — the lite-gl
+ * equivalent of `engine.depthCullingState.cull` + `cullFace`.
+ *
+ * @param engine - The engine.
+ * @param enabled - Enable (`true`) or disable (`false`) `gl.CULL_FACE`.
+ * @param face - Optional cull face (`gl.BACK` / `gl.FRONT` / `gl.FRONT_AND_BACK`).
+ */
+export declare function setCullState(engine: GLEngineContext, enabled: boolean, face?: GLenum): void;
+/**
+ * Buffer stencil state (test enable, write mask, comparison func triple, op
+ * triple) into the DESIRED state — the lite-gl equivalent of mutating Babylon's
+ * `engine.stencilState.*`. Flushed by `applyGLStates` before the next draw /
+ * clear; omitted fields are untouched (merge-from-desired).
+ *
+ * @param engine - The engine.
+ * @param state - The stencil fields to change. Omitted fields are untouched.
+ */
+export declare function setStencilState(engine: GLEngineContext, state: GLStencilState): void;
+/**
+ * Buffer the color write mask into the DESIRED state — the lite-gl equivalent of
+ * Babylon's `setColorWrite` (which passes the same flag to all four channels).
+ * Flushed to GL (`gl.colorMask`) by `applyGLStates` before the next draw /
+ * clear.
+ *
+ * @param engine - The engine.
+ * @param r - Write red.
+ * @param g - Write green.
+ * @param b - Write blue.
+ * @param a - Write alpha.
+ */
+export declare function setColorMask(engine: GLEngineContext, r: boolean, g: boolean, b: boolean, a: boolean): void;
+/**
+ * Clear the currently-bound framebuffer's color / depth / stencil buffers — the
+ * lite-gl equivalent of Babylon's `clear(color, backBuffer, depth, stencil)`.
+ * Depth/stencil clears respect the current write masks (set them first via
+ * {@link setDepthState} / {@link setStencilState}). No-op when nothing is
+ * requested or the context is lost/disposed.
+ *
+ * @param engine - The engine.
+ * @param options - Which buffers to clear (and the color value).
+ */
+export declare function clearEngine(engine: GLEngineContext, options: GLClearOptions): void;
+/**
+ * Opt-in: give a `/render-target` {@link GLRenderTarget} a stencil attachment,
+ * replacing the core's depth-only `DEPTH_COMPONENT16` renderbuffer with either a
+ * packed **`DEPTH24_STENCIL8`** buffer (default — depth *and* stencil) or a
+ * stencil-only **`STENCIL_INDEX8`** buffer.
+ *
+ * Stencil is intentionally NOT a {@link createRenderTarget} option: keeping this
+ * helper in the depth-stencil module means the stencil/packed renderbuffer
+ * code tree-shakes out of every bundle that only needs a color (and optional
+ * depth) target.
+ *
+ * The attachment is **restore-correct**: it is rebuilt automatically — at the new
+ * size on {@link resizeRenderTarget}, and into the fresh framebuffer after a
+ * `webglcontextrestored` event — so the stencil survives for the life of the
+ * target, and {@link disposeRenderTarget} releases it along with the target.
+ *
+ * No-op on a lost/disposed context or a disposed target.
+ *
+ * @param engine - The engine that owns `rt`.
+ * @param rt - The render target to attach the stencil buffer to.
+ * @param options - `depth` (default `true`): when `true` the attachment is a
+ *  packed depth+stencil buffer (`DEPTH24_STENCIL8` on `DEPTH_STENCIL_ATTACHMENT`)
+ *  — the common case, and the correct choice when the target was created with
+ *  `generateDepthBuffer: true`. When `false` the attachment is stencil-only
+ *  (`STENCIL_INDEX8` on `STENCIL_ATTACHMENT`).
+ * @throws If a renderbuffer handle could not be allocated or the framebuffer is
+ *  incomplete after attaching.
+ */
+export declare function generateRenderTargetStencil(engine: GLEngineContext, rt: GLRenderTarget, options?: {
+    depth?: boolean;
+}): void;