luma.gl/docs/api-reference/canvas-context.md

CanvasContext

Proposed luma.gl v9 API. Open for comments.

A CanvasContext holds a connection between the 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:

• manages the "swap chain" (provides a Framebuffer representing the display, with freshly updated and resized textures for every render frame)
• manages canvas resizing
• manages device pixel ratio

Types

CanvasContextProps

Property	Type
canvas?	HTMLCanvasElement | OffscreenCanvas | string	A new canvas will be created if not supplied.
container?	HTMLElement	Parent DOM element for new canvas. Defaults to first child of document.body
width?	number	Width in pixels of the canvas
height?	number	Height in pixels of the canvas
useDevicePixels?	boolean | number	Device pixels scale factor (true uses browser DPI)
autoResize?	boolean	Whether to track resizes
visible?	boolean	Visibility (only used if new canvas is created).
colorSpace?	'srgb'	WebGPU only https://www.w3.org/TR/webgpu/#canvas-configuration
compositingAlphaMode?	'opaque' | 'premultiplied'	WebGPU only https://www.w3.org/TR/webgpu/#canvas-configuration

Static Fields

CanvasContext.isPageLoaded: boolean

CanvasContext.pageLoaded: Promise<void>

Fields

canvas: HMTLCanvas | OffscreenCanvas

useDevicePixels: boolean | number

Methods

constructor

A CanvasContext can not be constructed directly. It must be created by instantiating a WebGPUDevice or a WebGLDevice, or 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()

Resize the drawing surface.

canvasContext.resize(options)

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

Remarks

• 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 the WebGL API.)

• 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, this happens due to system memory limitation, in such cases a warning will be logged to the browser console. For additional details check device pixels document.