@babylonjs/lite-gl 0.1.0 → 0.2.0

package/effect-renderer.d.ts

@@ -0,0 +1,65 @@
+import type { GLEngineContext } from "./context.js";
+import { type GLEffect } from "./effect.js";
+/** Inputs to `createEffectWrapper`. Mirrors lite's `EffectWrapperOptions`: the
+ *  wrapper compiles and OWNS the effect built from this shader source. */
+export interface GLEffectWrapperOptions {
+    /** Human-readable label for the wrapper and its effect. Defaults to
+     *  `"effect-wrapper"`. */
+    name?: string;
+    /** GLSL ES 3.00 vertex source. Defaults to a built-in fullscreen-quad
+     *  vertex shader (exposing a `vUv` varying), mirroring lite's default
+     *  `vertexWGSL`. */
+    vertexSource?: string;
+    /** GLSL ES 3.00 fragment source (≙ lite's `fragmentWGSL`). Required. */
+    fragmentSource: string;
+    /** Declared uniform names. Defaults to none. */
+    uniformNames?: readonly string[];
+    /** Declared sampler names, in unit-assignment order. Defaults to none. */
+    samplerNames?: readonly string[];
+    /** Attribute names; the first is bound to location 0. Defaults to
+     *  `["position"]`. */
+    attributeNames?: readonly string[];
+    /** Optional `#define` block prepended to both shader stages. */
+    defines?: string;
+}
+/** A reusable fullscreen effect that compiles and OWNS its `GLEffect` — the
+ *  WebGL counterpart of lite's `EffectWrapper`. The wrapper retains the engine
+ *  it was created for, so `disposeEffectWrapper` / `applyEffectWrapper` take
+ *  only the wrapper. */
+export interface GLEffectWrapper {
+    /** Name alias for the wrapper (and its effect). */
+    readonly name: string;
+    /** The compiled effect this wrapper owns. Exposed so the per-uniform
+     *  setters (`setEffectFloat`/`setEffectTexture`/…) can target it — the
+     *  WebGL divergence from lite's UBO-based `setEffectUniforms(wrapper, …)`. */
+    readonly effect: GLEffect;
+}
+/** Compile a fullscreen effect from shader source and wrap it; the wrapper OWNS
+ *  the resulting `GLEffect`. Mirrors lite's `createEffectWrapper(engine, options)`.
+ *  When `vertexSource` is omitted, a built-in fullscreen-quad vertex shader is
+ *  used, so callers can supply only `fragmentSource`. */
+export declare function createEffectWrapper(engine: GLEngineContext, options: GLEffectWrapperOptions): GLEffectWrapper;
+/** Dispose the wrapper and the effect it owns (idempotent). Mirrors lite's
+ *  `disposeEffectWrapper(wrapper)`. */
+export declare function disposeEffectWrapper(wrapper: GLEffectWrapper): void;
+/** Pixel-space viewport rectangle passed to `setViewport`. */
+export interface GLViewport {
+    /** Lower-left X origin in physical pixels. */
+    x: number;
+    /** Lower-left Y origin in physical pixels. */
+    y: number;
+    /** Width in physical pixels. */
+    w: number;
+    /** Height in physical pixels. */
+    h: number;
+}
+/** Cached `gl.viewport`. Defaults to the full canvas in pixel coordinates. */
+export declare function setViewport(engine: GLEngineContext, viewport?: GLViewport): void;
+/** Make `wrapper.effect` current and ensure the shared fullscreen quad VAO
+ *  is bound. This MUST be called BEFORE any `setEffect*` call for the same
+ *  effect in the current frame (uniform setters write to the currently bound
+ *  program). */
+export declare function applyEffectWrapper(wrapper: GLEffectWrapper): void;
+/** `gl.drawElements(TRIANGLES, 6, UNSIGNED_SHORT, 0)`. No-op when the
+ *  context is lost or there is no current program. */
+export declare function drawEffect(engine: GLEngineContext): void;

package/effect-renderer.js

@@ -0,0 +1,132 @@
+import { createEffect, disposeEffect, useEffect } from "./effect.js";
+import { applyGLStates } from "./apply-states.js";
+/** Built-in fullscreen-quad vertex shader, used when `GLEffectWrapperOptions`
+ *  omits `vertexSource`. Maps the package's fullscreen-quad positions
+ *  (attribute location 0) to clip space and forwards a 0..1 `vUv` varying —
+ *  the WebGL counterpart of lite's default `vertexWGSL`, so callers can pass
+ *  only `fragmentSource`. */
+const DEFAULT_FULLSCREEN_VERTEX_SOURCE = `#version 300 es
+layout(location = 0) in vec2 position;
+out vec2 vUv;
+void main() {
+    vUv = position * 0.5 + 0.5;
+    gl_Position = vec4(position, 0.0, 1.0);
+}`;
+/** Compile a fullscreen effect from shader source and wrap it; the wrapper OWNS
+ *  the resulting `GLEffect`. Mirrors lite's `createEffectWrapper(engine, options)`.
+ *  When `vertexSource` is omitted, a built-in fullscreen-quad vertex shader is
+ *  used, so callers can supply only `fragmentSource`. */
+export function createEffectWrapper(engine, options) {
+    const name = options.name ?? "effect-wrapper";
+    const effect = createEffect(engine, {
+        name,
+        vertexSource: options.vertexSource ?? DEFAULT_FULLSCREEN_VERTEX_SOURCE,
+        fragmentSource: options.fragmentSource,
+        uniformNames: options.uniformNames ?? [],
+        samplerNames: options.samplerNames ?? [],
+        attributeNames: options.attributeNames,
+        defines: options.defines,
+    });
+    return { name, effect, _engine: engine, _disposed: false };
+}
+/** Dispose the wrapper and the effect it owns (idempotent). Mirrors lite's
+ *  `disposeEffectWrapper(wrapper)`. */
+export function disposeEffectWrapper(wrapper) {
+    if (wrapper._disposed) {
+        return;
+    }
+    wrapper._disposed = true;
+    disposeEffect(wrapper._engine, wrapper.effect);
+}
+/** Cached `gl.viewport`. Defaults to the full canvas in pixel coordinates. */
+export function setViewport(engine, viewport) {
+    if (engine._isLost || engine._disposed) {
+        return;
+    }
+    const x = viewport?.x ?? 0;
+    const y = viewport?.y ?? 0;
+    const w = viewport?.w ?? engine.canvas.width;
+    const h = viewport?.h ?? engine.canvas.height;
+    const s = engine._state;
+    if (s.viewportX === x && s.viewportY === y && s.viewportW === w && s.viewportH === h) {
+        return;
+    }
+    s.viewportX = x;
+    s.viewportY = y;
+    s.viewportW = w;
+    s.viewportH = h;
+    engine.gl.viewport(x, y, w, h);
+}
+/** Make `wrapper.effect` current and ensure the shared fullscreen quad VAO
+ *  is bound. This MUST be called BEFORE any `setEffect*` call for the same
+ *  effect in the current frame (uniform setters write to the currently bound
+ *  program). */
+export function applyEffectWrapper(wrapper) {
+    const engine = wrapper._engine;
+    if (engine._isLost || engine._disposed || wrapper._disposed) {
+        return;
+    }
+    ensureQuad(engine);
+    useEffect(engine, wrapper.effect);
+}
+/** `gl.drawElements(TRIANGLES, 6, UNSIGNED_SHORT, 0)`. No-op when the
+ *  context is lost or there is no current program. */
+export function drawEffect(engine) {
+    if (engine._isLost || engine._disposed) {
+        return;
+    }
+    if (engine._state.currentProgram === null) {
+        return;
+    }
+    applyGLStates(engine);
+    engine.gl.drawElements(engine.gl.TRIANGLES, 6, engine.gl.UNSIGNED_SHORT, 0);
+}
+/** Lazy fullscreen quad. Built on first call; thereafter the VAO is cached on
+ *  `_state.quadVao` and rebinding is a single cached call. Cleared by
+ *  `webglcontextlost` and transparently rebuilt by the next
+ *  `applyEffectWrapper` after restore.
+ *
+ *  Position attribute is enabled at location 0 — every effect's
+ *  `createEffect` calls `gl.bindAttribLocation(program, 0, attributeNames[0])`
+ *  BEFORE link, so the shared VAO is correct across all programs. */
+function ensureQuad(engine) {
+    const s = engine._state;
+    const gl = engine.gl;
+    if (s.quadVao !== null) {
+        if (s.boundVao !== s.quadVao) {
+            gl.bindVertexArray(s.quadVao);
+            s.boundVao = s.quadVao;
+        }
+        return;
+    }
+    const vao = gl.createVertexArray();
+    if (vao === null) {
+        throw new Error("lite-gl: gl.createVertexArray returned null");
+    }
+    s.quadVao = vao;
+    gl.bindVertexArray(vao);
+    s.boundVao = vao;
+    const vbo = gl.createBuffer();
+    if (vbo === null) {
+        throw new Error("lite-gl: gl.createBuffer returned null (VBO)");
+    }
+    s.quadVbo = vbo;
+    gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
+    s.boundArrayBuffer = vbo;
+    gl.bufferData(gl.ARRAY_BUFFER, QUAD_POSITIONS, gl.STATIC_DRAW);
+    const ibo = gl.createBuffer();
+    if (ibo === null) {
+        throw new Error("lite-gl: gl.createBuffer returned null (IBO)");
+    }
+    s.quadIbo = ibo;
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);
+    s.boundElementBuffer = ibo;
+    gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, QUAD_INDICES, gl.STATIC_DRAW);
+    gl.enableVertexAttribArray(0);
+    gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
+}
+/** Typed-array literal — pure per bundler convention. Matches Babylon's
+ *  `EffectRenderer` default geometry exactly. */
+const QUAD_POSITIONS = new Float32Array([1, 1, -1, 1, -1, -1, 1, -1]);
+const QUAD_INDICES = new Uint16Array([0, 1, 2, 0, 2, 3]);
+//# sourceMappingURL=effect-renderer.js.map

package/effect-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-renderer.js","sourceRoot":"","sources":["../src/effect-renderer.ts"],"names":[],"mappings":"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","sourcesContent":["import type { GLEngineContext } from \"./context.js\";\nimport { createEffect, disposeEffect, type GLEffect, useEffect } from \"./effect.js\";\nimport { applyGLStates } from \"./apply-states.js\";\n\n/** Built-in fullscreen-quad vertex shader, used when `GLEffectWrapperOptions`\n *  omits `vertexSource`. Maps the package's fullscreen-quad positions\n *  (attribute location 0) to clip space and forwards a 0..1 `vUv` varying —\n *  the WebGL counterpart of lite's default `vertexWGSL`, so callers can pass\n *  only `fragmentSource`. */\nconst DEFAULT_FULLSCREEN_VERTEX_SOURCE = `#version 300 es\nlayout(location = 0) in vec2 position;\nout vec2 vUv;\nvoid main() {\n    vUv = position * 0.5 + 0.5;\n    gl_Position = vec4(position, 0.0, 1.0);\n}`;\n\n/** Inputs to `createEffectWrapper`. Mirrors lite's `EffectWrapperOptions`: the\n *  wrapper compiles and OWNS the effect built from this shader source. */\nexport interface GLEffectWrapperOptions {\n    /** Human-readable label for the wrapper and its effect. Defaults to\n     *  `\"effect-wrapper\"`. */\n    name?: string;\n    /** GLSL ES 3.00 vertex source. Defaults to a built-in fullscreen-quad\n     *  vertex shader (exposing a `vUv` varying), mirroring lite's default\n     *  `vertexWGSL`. */\n    vertexSource?: string;\n    /** GLSL ES 3.00 fragment source (≙ lite's `fragmentWGSL`). Required. */\n    fragmentSource: string;\n    /** Declared uniform names. Defaults to none. */\n    uniformNames?: readonly string[];\n    /** Declared sampler names, in unit-assignment order. Defaults to none. */\n    samplerNames?: readonly string[];\n    /** Attribute names; the first is bound to location 0. Defaults to\n     *  `[\"position\"]`. */\n    attributeNames?: readonly string[];\n    /** Optional `#define` block prepended to both shader stages. */\n    defines?: string;\n}\n\n/** A reusable fullscreen effect that compiles and OWNS its `GLEffect` — the\n *  WebGL counterpart of lite's `EffectWrapper`. The wrapper retains the engine\n *  it was created for, so `disposeEffectWrapper` / `applyEffectWrapper` take\n *  only the wrapper. */\nexport interface GLEffectWrapper {\n    /** Name alias for the wrapper (and its effect). */\n    readonly name: string;\n    /** The compiled effect this wrapper owns. Exposed so the per-uniform\n     *  setters (`setEffectFloat`/`setEffectTexture`/…) can target it — the\n     *  WebGL divergence from lite's UBO-based `setEffectUniforms(wrapper, …)`. */\n    readonly effect: GLEffect;\n    /** @internal The engine the wrapper was created for. */\n    _engine: GLEngineContext;\n    /** @internal */\n    _disposed: boolean;\n}\n\n/** Compile a fullscreen effect from shader source and wrap it; the wrapper OWNS\n *  the resulting `GLEffect`. Mirrors lite's `createEffectWrapper(engine, options)`.\n *  When `vertexSource` is omitted, a built-in fullscreen-quad vertex shader is\n *  used, so callers can supply only `fragmentSource`. */\nexport function createEffectWrapper(engine: GLEngineContext, options: GLEffectWrapperOptions): GLEffectWrapper {\n    const name = options.name ?? \"effect-wrapper\";\n    const effect = createEffect(engine, {\n        name,\n        vertexSource: options.vertexSource ?? DEFAULT_FULLSCREEN_VERTEX_SOURCE,\n        fragmentSource: options.fragmentSource,\n        uniformNames: options.uniformNames ?? [],\n        samplerNames: options.samplerNames ?? [],\n        attributeNames: options.attributeNames,\n        defines: options.defines,\n    });\n    return { name, effect, _engine: engine, _disposed: false };\n}\n\n/** Dispose the wrapper and the effect it owns (idempotent). Mirrors lite's\n *  `disposeEffectWrapper(wrapper)`. */\nexport function disposeEffectWrapper(wrapper: GLEffectWrapper): void {\n    if (wrapper._disposed) {\n        return;\n    }\n    wrapper._disposed = true;\n    disposeEffect(wrapper._engine, wrapper.effect);\n}\n\n/** Pixel-space viewport rectangle passed to `setViewport`. */\nexport interface GLViewport {\n    /** Lower-left X origin in physical pixels. */\n    x: number;\n    /** Lower-left Y origin in physical pixels. */\n    y: number;\n    /** Width in physical pixels. */\n    w: number;\n    /** Height in physical pixels. */\n    h: number;\n}\n\n/** Cached `gl.viewport`. Defaults to the full canvas in pixel coordinates. */\nexport function setViewport(engine: GLEngineContext, viewport?: GLViewport): void {\n    if (engine._isLost || engine._disposed) {\n        return;\n    }\n    const x = viewport?.x ?? 0;\n    const y = viewport?.y ?? 0;\n    const w = viewport?.w ?? engine.canvas.width;\n    const h = viewport?.h ?? engine.canvas.height;\n    const s = engine._state;\n    if (s.viewportX === x && s.viewportY === y && s.viewportW === w && s.viewportH === h) {\n        return;\n    }\n    s.viewportX = x;\n    s.viewportY = y;\n    s.viewportW = w;\n    s.viewportH = h;\n    engine.gl.viewport(x, y, w, h);\n}\n\n/** Make `wrapper.effect` current and ensure the shared fullscreen quad VAO\n *  is bound. This MUST be called BEFORE any `setEffect*` call for the same\n *  effect in the current frame (uniform setters write to the currently bound\n *  program). */\nexport function applyEffectWrapper(wrapper: GLEffectWrapper): void {\n    const engine = wrapper._engine;\n    if (engine._isLost || engine._disposed || wrapper._disposed) {\n        return;\n    }\n    ensureQuad(engine);\n    useEffect(engine, wrapper.effect);\n}\n\n/** `gl.drawElements(TRIANGLES, 6, UNSIGNED_SHORT, 0)`. No-op when the\n *  context is lost or there is no current program. */\nexport function drawEffect(engine: GLEngineContext): void {\n    if (engine._isLost || engine._disposed) {\n        return;\n    }\n    if (engine._state.currentProgram === null) {\n        return;\n    }\n    applyGLStates(engine);\n    engine.gl.drawElements(engine.gl.TRIANGLES, 6, engine.gl.UNSIGNED_SHORT, 0);\n}\n\n/** Lazy fullscreen quad. Built on first call; thereafter the VAO is cached on\n *  `_state.quadVao` and rebinding is a single cached call. Cleared by\n *  `webglcontextlost` and transparently rebuilt by the next\n *  `applyEffectWrapper` after restore.\n *\n *  Position attribute is enabled at location 0 — every effect's\n *  `createEffect` calls `gl.bindAttribLocation(program, 0, attributeNames[0])`\n *  BEFORE link, so the shared VAO is correct across all programs. */\nfunction ensureQuad(engine: GLEngineContext): void {\n    const s = engine._state;\n    const gl = engine.gl;\n    if (s.quadVao !== null) {\n        if (s.boundVao !== s.quadVao) {\n            gl.bindVertexArray(s.quadVao);\n            s.boundVao = s.quadVao;\n        }\n        return;\n    }\n    const vao = gl.createVertexArray();\n    if (vao === null) {\n        throw new Error(\"lite-gl: gl.createVertexArray returned null\");\n    }\n    s.quadVao = vao;\n    gl.bindVertexArray(vao);\n    s.boundVao = vao;\n\n    const vbo = gl.createBuffer();\n    if (vbo === null) {\n        throw new Error(\"lite-gl: gl.createBuffer returned null (VBO)\");\n    }\n    s.quadVbo = vbo;\n    gl.bindBuffer(gl.ARRAY_BUFFER, vbo);\n    s.boundArrayBuffer = vbo;\n    gl.bufferData(gl.ARRAY_BUFFER, QUAD_POSITIONS, gl.STATIC_DRAW);\n\n    const ibo = gl.createBuffer();\n    if (ibo === null) {\n        throw new Error(\"lite-gl: gl.createBuffer returned null (IBO)\");\n    }\n    s.quadIbo = ibo;\n    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);\n    s.boundElementBuffer = ibo;\n    gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, QUAD_INDICES, gl.STATIC_DRAW);\n\n    gl.enableVertexAttribArray(0);\n    gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);\n}\n\n/** Typed-array literal — pure per bundler convention. Matches Babylon's\n *  `EffectRenderer` default geometry exactly. */\nconst QUAD_POSITIONS = new Float32Array([1, 1, -1, 1, -1, -1, 1, -1]);\nconst QUAD_INDICES = new Uint16Array([0, 1, 2, 0, 2, 3]);\n"]}

package/effect.d.ts

@@ -0,0 +1,142 @@
+import type { GLEngineContext } from "./context.js";
+import { type GLTexture } from "./texture.js";
+/** Inputs to `createEffect`: shader sources plus the uniform, sampler and
+ *  attribute names whose locations are resolved during readiness finalization. */
+export 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;
+}
+/** 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. */
+export 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;
+}
+/** Compile + link a new effect. Does NOT block on link completion — `isReady`
+ *  starts false; consumers poll `isEffectReady` (typically from their render
+ *  callback) to drive finalization. */
+export declare function createEffect(engine: GLEngineContext, options: GLEffectOptions): GLEffect;
+/** Poll the link state and, on first success, run finalization (uniform-
+ *  location resolution + one-shot sampler-unit `uniform1i` assignment +
+ *  `_onCompiled` callbacks). Returns `true` once the effect is usable. */
+export declare function isEffectReady(engine: GLEngineContext, effect: GLEffect): boolean;
+/** Fires `cb` synchronously if the effect is already ready; otherwise queues
+ *  it for the next finalization. */
+export declare function executeWhenCompiled(engine: GLEngineContext, effect: GLEffect, cb: (e: GLEffect) => void): void;
+/** Decrement the share count and, on the last release, delete the effect's
+ *  program + shaders, unregister it from the context + cache, and clear the
+ *  cached current-program if it pointed at this effect. A shared effect (still
+ *  referenced by another `createEffect` caller) is kept alive. Call exactly ONCE
+ *  per `createEffect` (each call decrements the ref count); safe (no-op) once the
+ *  effect is fully torn down. */
+export declare function disposeEffect(engine: GLEngineContext, effect: GLEffect): void;
+/** Cached `gl.useProgram`. No-op when the effect is not ready or already current. */
+export declare function useEffect(engine: GLEngineContext, effect: GLEffect): void;
+/** Cached `gl.uniform1f`. No-op when context-lost, the effect isn't ready, the
+ *  uniform is absent, or the value is unchanged since last upload. */
+export declare function setEffectFloat(engine: GLEngineContext, effect: GLEffect, name: string, x: number): void;
+/** Cached `gl.uniform2f`. No-op when context-lost, the effect isn't ready, the
+ *  uniform is absent, or the value is unchanged since last upload. */
+export declare function setEffectFloat2(engine: GLEngineContext, effect: GLEffect, name: string, x: number, y: number): void;
+/** Cached `gl.uniform3f`. No-op when context-lost, the effect isn't ready, the
+ *  uniform is absent, or the value is unchanged since last upload. */
+export declare function setEffectFloat3(engine: GLEngineContext, effect: GLEffect, name: string, x: number, y: number, z: number): void;
+/** Cached `gl.uniform4f`. No-op when context-lost, the effect isn't ready, the
+ *  uniform is absent, or the value is unchanged since last upload. */
+export declare function setEffectFloat4(engine: GLEngineContext, effect: GLEffect, name: string, x: number, y: number, z: number, w: number): void;
+/** Cached `gl.uniform3f` from an r/g/b color object. Delegates to `setEffectFloat3`. */
+export declare function setEffectColor3(engine: GLEngineContext, effect: GLEffect, name: string, c: {
+    r: number;
+    g: number;
+    b: number;
+}): void;
+/** Cached `gl.uniform4f` from an r/g/b/a color object. Delegates to `setEffectFloat4`. */
+export declare function setEffectColor4(engine: GLEngineContext, effect: GLEffect, name: string, c: {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}): void;
+/** Cached `gl.uniform2f` from an `{x,y}` vector object — the lite-gl equivalent
+ *  of Babylon's `Effect.setVector2`. Delegates to `setEffectFloat2`. */
+export declare function setEffectVector2(engine: GLEngineContext, effect: GLEffect, name: string, v: {
+    x: number;
+    y: number;
+}): void;
+/** Cached `gl.uniform4f` from an r/g/b/a color WITHOUT premultiplication — the
+ *  lite-gl equivalent of Babylon's `Effect.setDirectColor4`. Delegates to
+ *  `setEffectFloat4` (lite-gl never premultiplies in the uniform setters, so
+ *  this matches `setEffectColor4`; the distinct name eases the ShapeBuilder
+ *  port). */
+export declare function setEffectDirectColor4(engine: GLEngineContext, effect: GLEffect, name: string, c: {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}): void;
+/** Cached `gl.uniform1i`. No-op when context-lost, the effect isn't ready, the
+ *  uniform is absent, or the value is unchanged since last upload. */
+export declare function setEffectInt(engine: GLEngineContext, effect: GLEffect, name: string, x: number): void;
+/** `gl.uniformMatrix4fv` from a column-major 4×4 matrix — the lite-gl
+ *  equivalent of Babylon's `Effect.setMatrix`. Not value-cached. */
+export declare function setEffectMatrix(engine: GLEngineContext, effect: GLEffect, name: string, matrix: Float32Array | number[]): void;
+/** `gl.uniformMatrix3fv` from a column-major 3×3 matrix — the lite-gl
+ *  equivalent of Babylon's `Effect.setMatrix3x3`. Not value-cached. */
+export declare function setEffectMatrix3x3(engine: GLEngineContext, effect: GLEffect, name: string, matrix: Float32Array | number[]): void;
+/** `gl.uniform1fv` — a flat float array (`Effect.setFloatArray` / `setArray`).
+ *  Not value-cached. */
+export declare function setEffectFloatArray(engine: GLEngineContext, effect: GLEffect, name: string, array: Float32Array | number[]): void;
+/** `gl.uniform4fv` — an array of `vec4`s (`Effect.setFloatArray4` / `setArray4`).
+ *  Not value-cached. */
+export declare function setEffectFloatArray4(engine: GLEngineContext, effect: GLEffect, name: string, array: Float32Array | number[]): void;
+/** `gl.uniform1iv` — a flat int array (`Effect.setIntArray`). Not value-cached. */
+export declare function setEffectIntArray(engine: GLEngineContext, effect: GLEffect, name: string, array: Int32Array | number[]): void;
+/** Bind a texture to the sampler's pre-assigned unit (§4.4). NO `gl.uniform1i`
+ *  is issued — that was done exactly once per program lifetime during
+ *  finalization. This is the key win over Babylon's `Effect.setTexture` which
+ *  re-issues the sampler binding on every call. */
+export declare function setEffectTexture(engine: GLEngineContext, effect: GLEffect, samplerName: string, tex: GLTexture): void;