GPUCanvasContext

class wgpu.GPUCanvasContext

Bases: object

Represents a context to configure a canvas and render to it.

Can be obtained with wgpu.gpu.get_canvas_context().

When rendercanvas is used, it will automatically wrap a GPUCanvasContext if necessary. From the perspective of rendercanvas, this implements the ‘screen’ present method.

The purpose of the canvas-context is to connecting the wgpu API to the GUI/window/canvas layer, in a way that allows the GUI to be agnostic about wgpu, and wgpu to remain agnostic about a canvas. It combines (and checks) the user’s preferences with the capabilities and preferences of the canvas.

configure(**parameters)

Configures the presentation context for the associated canvas.

Destroys any textures produced with a previous configuration. This clears the drawing buffer to transparent black.

Parameters:

  • device (WgpuDevice) – The GPU device object to create compatible textures for.

  • format (enums.TextureFormat) – The format that textures returned by get_current_texture() will have. Must be one of the supported context formats. Can be None to use the canvas’ preferred format.

  • usage (flags.TextureUsage) – Default TextureUsage.OUTPUT_ATTACHMENT.

  • view_formats (list[enums.TextureFormat]) – The formats that views created from textures returned by get_current_texture() may use.

  • color_space (PredefinedColorSpace) – The color space that values written into textures returned by get_current_texture() should be displayed with. Default “srgb”. Not yet supported.

  • tone_mapping (enums.CanvasToneMappingMode) – Not yet supported.

  • alpha_mode (structs.CanvasAlphaMode) – Determines the effect that alpha values will have on the content of textures returned by get_current_texture() when read, displayed, or used as an image source. Default “opaque”.

get_configuration() → CanvasConfiguration | dict

Get the current configuration (or None if the context is not yet configured).

get_current_texture() → GPUTexture

Get the GPUTexture that will be composited to the canvas next.

get_preferred_format(adapter: GPUAdapter) → Literal['r8unorm', 'r8snorm', 'r8uint', 'r8sint', 'r16unorm', 'r16snorm', 'r16uint', 'r16sint', 'r16float', 'rg8unorm', 'rg8snorm', 'rg8uint', 'rg8sint', 'r32uint', 'r32sint', 'r32float', 'rg16unorm', 'rg16snorm', 'rg16uint', 'rg16sint', 'rg16float', 'rgba8unorm', 'rgba8unorm-srgb', 'rgba8snorm', 'rgba8uint', 'rgba8sint', 'bgra8unorm', 'bgra8unorm-srgb', 'rgb9e5ufloat', 'rgb10a2uint', 'rgb10a2unorm', 'rg11b10ufloat', 'rg32uint', 'rg32sint', 'rg32float', 'rgba16unorm', 'rgba16snorm', 'rgba16uint', 'rgba16sint', 'rgba16float', 'rgba32uint', 'rgba32sint', 'rgba32float', 'stencil8', 'depth16unorm', 'depth24plus', 'depth24plus-stencil8', 'depth32float', 'depth32float-stencil8', 'bc1-rgba-unorm', 'bc1-rgba-unorm-srgb', 'bc2-rgba-unorm', 'bc2-rgba-unorm-srgb', 'bc3-rgba-unorm', 'bc3-rgba-unorm-srgb', 'bc4-r-unorm', 'bc4-r-snorm', 'bc5-rg-unorm', 'bc5-rg-snorm', 'bc6h-rgb-ufloat', 'bc6h-rgb-float', 'bc7-rgba-unorm', 'bc7-rgba-unorm-srgb', 'etc2-rgb8unorm', 'etc2-rgb8unorm-srgb', 'etc2-rgb8a1unorm', 'etc2-rgb8a1unorm-srgb', 'etc2-rgba8unorm', 'etc2-rgba8unorm-srgb', 'eac-r11unorm', 'eac-r11snorm', 'eac-rg11unorm', 'eac-rg11snorm', 'astc-4x4-unorm', 'astc-4x4-unorm-srgb', 'astc-5x4-unorm', 'astc-5x4-unorm-srgb', 'astc-5x5-unorm', 'astc-5x5-unorm-srgb', 'astc-6x5-unorm', 'astc-6x5-unorm-srgb', 'astc-6x6-unorm', 'astc-6x6-unorm-srgb', 'astc-8x5-unorm', 'astc-8x5-unorm-srgb', 'astc-8x6-unorm', 'astc-8x6-unorm-srgb', 'astc-8x8-unorm', 'astc-8x8-unorm-srgb', 'astc-10x5-unorm', 'astc-10x5-unorm-srgb', 'astc-10x6-unorm', 'astc-10x6-unorm-srgb', 'astc-10x8-unorm', 'astc-10x8-unorm-srgb', 'astc-10x10-unorm', 'astc-10x10-unorm-srgb', 'astc-12x10-unorm', 'astc-12x10-unorm-srgb', 'astc-12x12-unorm', 'astc-12x12-unorm-srgb'] | str

Get the preferred surface texture format.

property physical_size: tuple[int, int]

The physical size of the underlying surface in integer pixels.

present() → None

Present what has been drawn to the current texture, by compositing it to the canvas.

set_physical_size(width: int, height: int) → None

Set the current framebuffer physical size.

The application must call this to keep the context informed about the window/framebuffer size.

unconfigure() → None

Removes the presentation context configuration. Destroys any textures produced while configured.