Skip to main content


A CanvasContext holds a connection between a GPU Device and an HTML canvas or OffscreenCanvas into which it can render.

Canvas contexts are created using device.createCanvasContext(). Depending on options passed, this either:

  • creates a new canvas element, or
  • attaches the context to an existing canvas element
  • (see remarks below for WebGL limitations).

a CanvasContext handles the following responsibilities:

  • Provides a Framebuffer representing the display, with freshly updated and resized textures for every render frame. On WebGPU it manages the "swap chain".
  • Handles canvas resizing
  • Manages device pixel ratio (mapping between device and CSS pixels)


Use a device's default canvas context:

const renderPass = device.beginRenderPass({
framebuffer: device.canvasContext.getFramebuffer()

Create additional canvas contexts (WebGPU only):

const canvasContext2 = device.createCanvasContext({canvas: ...});
const renderPass = device.beginRenderPass({
framebuffer: canvasContext2.getFramebuffer()



canvas?HTMLCanvasElement | OffscreenCanvas | stringA new canvas will be created if not supplied.
container?HTMLElementParent DOM element for new canvas. Defaults to first child of document.body
width?numberWidth in pixels of the canvas
height?numberHeight in pixels of the canvas
useDevicePixels?boolean | numberDevice pixels scale factor (true uses browser DPI)
autoResize?booleanWhether to track resizes
visible?booleanVisibility (only used if new canvas is created).
colorSpace?'srgb'WebGPU only
compositingAlphaMode?'opaque' | 'premultiplied'WebGPU only

Static Fields

CanvasContext.isPageLoaded: boolean

A boolean that indicates if the web page has been loaded. This is sometimes useful as a canvas element specified in the page HTML will not be available until the page has loaded.

CanvasContext.pageLoaded: Promise<void>

A promise that resolves when the page is loaded.

  await CanvasContex.isPageLoaded;
const canvas = document.getElementById('canvas');


canvas: HMTLCanvas | OffscreenCanvas

useDevicePixels: boolean | number

Whether the framebuffer backing this canvas context is sized using device pixels.

  • false - Framebuffer is sized according to CSS pixel size.
  • true - Framebuffer is sized according to the device pixel ratio reported by the browser.
  • number - Framebuffer is sized according to the provided ratio.




A CanvasContext should not be constructed directly. Default canvas contexts are created when instantiating a WebGPUDevice or a WebGLDevice, and can be accessed through the device.canvasContext field. Additional canvas contexts can be explicitly created through WebGPUDevice.createCanvasContext(...).

getDevicePixelResolution(): [number, number]


getPixelSize(): [number, number]

Returns the size in pixels required to cover the canvas at the current device pixel resolution.

resize(): void

Resize the drawing surface.

  • width: New drawing surface width.
  • height: New drawing surface height.
  • useDevicePixels: Whether to scale the drawing surface using the device pixel ratio.


  • Note that a WebGPU Device can have multiple associated CanvasContext instances (or none, if only used for compute).
  • However a WebGL Device always has exactly one CanvasContext and can only render into that single canvas. (This is a fundamental limitation of WebGL.)
  • useDevicePixels can accept a custom ratio (Number), instead of true or false. This allows rendering to a much smaller or higher resolutions. When using high value (usually more than device pixel ratio), it is possible it can get clamped down outside of's control due to system memory limitation, in such cases a warning will be logged to the browser console.