glCanvas()

function glCanvas<U>(params: {
  uniforms?: U;
  webglAttributes?: {
    alpha?: boolean;
    antialias?: boolean;
    depth?: boolean;
    desynchronized?: boolean;
    failIfMajorPerformanceCaveat?: boolean;
    powerPreference?: "default" | "high-performance" | "low-power";
    premultipliedAlpha?: boolean;
    preserveDrawingBuffer?: boolean;
    stencil?: boolean;
  };
  dpr?: number;
  renderMode?: "auto" | "continuous" | "manual";
  canvas: string | HTMLCanvasElement | OffscreenCanvas;
  colorSpace?: "srgb" | "display-p3";
  immediate?: boolean;
  postEffects?: (EffectPass | CompositeEffectPass)[];
  vertex?: string;
  gl?: WebGL2RenderingContext;
  target?: RenderTarget | null;
  fragment: string;
  attributes?: Record<string, Attribute>;
  blending?: "none" | "normal" | "additive";
  depthTest?: boolean;
  drawMode?:
    | "POINTS"
    | "LINES"
    | "LINE_STRIP"
    | "LINE_LOOP"
    | "TRIANGLES"
    | "TRIANGLE_STRIP"
    | "TRIANGLE_FAN";
  transformFeedbackVaryings?: string[];
  resolutionScale?: number;
}): GLCanvas<U>;

The main high-level function for managing a WebGL canvas.

It combines WebGL2 context creation, a full-screen render pass, a post-processing compositor, resize handling, render scheduling, and an optional animation clock. Uniform functions receive a UniformContext; promise sources are resolved for both the main pass and effects.

Type Parameters

U

U extends UniformSources<UniformContext>

Parameters

params

uniforms?

U

Initial uniform sources, including contextual functions and promises.

webglAttributes?

{ alpha?: boolean; antialias?: boolean; depth?: boolean; desynchronized?: boolean; failIfMajorPerformanceCaveat?: boolean; powerPreference?: "default" | "high-performance" | "low-power"; premultipliedAlpha?: boolean; preserveDrawingBuffer?: boolean; stencil?: boolean; }

Native WebGL2 context attributes.

webglAttributes.alpha?

boolean

webglAttributes.antialias?

boolean

webglAttributes.depth?

boolean

webglAttributes.desynchronized?

boolean

webglAttributes.failIfMajorPerformanceCaveat?

boolean

webglAttributes.powerPreference?

"default" | "high-performance" | "low-power"

webglAttributes.premultipliedAlpha?

boolean

webglAttributes.preserveDrawingBuffer?

boolean

webglAttributes.stencil?

boolean

dpr?

number

Device pixel ratio used when sizing a CSS-sized canvas.

Default

Math.min(globalThis.devicePixelRatio || 1, 2);

renderMode?

"auto" | "continuous" | "manual"

Rendering policy.

• auto schedules renders when needed ((uniform updated, canvas resized, image texture loaded...)
• manual renders only when GLCanvas.render is called
• continuous renders every animation frame.

Default

continuous when the main pass has a uniform function with "time" in its name, otherwise auto

canvas

string | HTMLCanvasElement | OffscreenCanvas

The canvas element to use or CSS selector to query it.

colorSpace?

"srgb" | "display-p3"

The color space to use for the drawing buffer.

immediate?

boolean

If true, the loop will start immediately.

If false, the loop will start when the play method is called.

Default

true;

postEffects?

( | EffectPass | CompositeEffectPass)[]

Post-processing effects rendered after the main scene pass.

vertex?

string

Optional vertex shader. If omitted, the built-in full-screen triangle vertex shader is used and its UV varying is adapted to the fragment shader.

gl?

WebGL2RenderingContext

Optional WebGL2 context used to initialize the pass immediately.

Passes without a context are initialized by calling pass.initialize(gl) or using the compositor. Calling initialize() multiple times with the same context is a no-op.

target?

| RenderTarget | null

Optional initial render target for the pass. If not provided, it will render directly to the canvas or can be set later.

fragment

string

Fragment shader source code.

attributes?

Record<string, Attribute>

Mapping of attribute names to their data and configuration.

blending?

"none" | "normal" | "additive"

Blending mode to use for this pass.

Default

"none";

depthTest?

boolean

Whether to enable depth testing.

Default

false;

drawMode?

| "POINTS" | "LINES" | "LINE_STRIP" | "LINE_LOOP" | "TRIANGLES" | "TRIANGLE_STRIP" | "TRIANGLE_FAN"

WebGL draw mode.

Default

"POINTS" if gl_PointSize is found in the vertex shader, otherwise "TRIANGLES".

transformFeedbackVaryings?

string[]

Array of varying names for Transform Feedback.

resolutionScale?

number

Scaling factor applied to the resolution when the pass is resized.

Default

1;

Returns

GLCanvas<U>