---
url: /api/global/glCanvas/functions/glCanvas.md
---
# glCanvas()

```ts
function glCanvas<U extends UniformSources<UniformContext>>(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](../../../types/types/interfaces/UniformContext.md);
promise sources are resolved for both the main pass and effects.

## Type Parameters

### U

`U` *extends* [`UniformSources`](../../../types/types/type-aliases/UniformSources.md)<[`UniformContext`](../../../types/types/interfaces/UniformContext.md)>

## 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**

```ts
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**

```ts
true;
```

#### postEffects?

(
| [`EffectPass`](../../../passes/effectPass/type-aliases/EffectPass.md)
| [`CompositeEffectPass`](../../../passes/compositeEffectPass/type-aliases/CompositeEffectPass.md))\[]

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`](../../../core/renderTarget/type-aliases/RenderTarget.md)
| `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`](../../../types/types/interfaces/Attribute.md)>

Mapping of attribute names to their data and configuration.

#### blending?

`"none"` | `"normal"` | `"additive"`

Blending mode to use for this pass.

**Default**

```ts
"none";
```

#### depthTest?

`boolean`

Whether to enable depth testing.

**Default**

```ts
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**

```ts
1;
```

## Returns

[`GLCanvas`](../type-aliases/GLCanvas.md)<`U`>