Context API

A context provides an API to provide a rendered image, and implements a mechanism to present that image for display. The concept of a context is heavily inspired by the <canvas> and its contexts in the browser.

Available context classes

  • The BaseContext exposes the common API.

  • The BitmapContext exposes an API that takes image bitmaps in RAM.

  • The WgpuContext exposes an API that provides image textures on the GPU to render to.

Getting a context

Context objects must be created using context = canvas.get_context(..), or the dedicated canvas.get_bitmap_context() and canvas.get_wgpu_context().

Using a context

All contexts provide detailed size information (which is kept up-to-date by the canvas). A rendering system should generally be capable to perform the rendering with just the context object; without a reference to the canvas. With this, we try to promote a clear separation of concerns, where one system listens to events from the canvas to update a certain state, and the renderer uses this state and the context to render the image.

Advanced: creating a custom context API

It’s possible for users to create their own context sub-classes. This can be a good solution, e.g. when your system needs to handle the presentation by itself. In general it’s better, when possible, to create an object that wraps a built-in context object: my_ob = MyClass(canvas.get_context(..)). That way your code will not break if the internal interface between the context and the canvas is changed.

class rendercanvas.contexts.BaseContext(present_info: dict)

The base class for context objects in rendercanvas.

property logical_size: tuple[float, float]

The logical size (width, height) of the render target in float pixels.

The logical size can be smaller than the physical size, e.g. on HiDPI monitors or when the user’s system has the display-scale set to e.g. 125%. The logical size can in theory also be larger than the physical size, but this is much less common.

property looks_like_hidpi: bool

Whether it looks like the window is on a hipdi screen.

This is determined by checking whether the native pixel-ratio (i.e. the ratio reported by the canvas backend) is larger or equal dan 2.0.

property physical_size: tuple[int, int]

The physical size of the render target in integer pixels.

property pixel_ratio: float

The float ratio between logical and physical pixels.

The pixel ratio is typically 1.0 for normal screens and 2.0 for HiDPI screens, but fractional values are also possible if the system display-scale is set to e.g. 125%.

class rendercanvas.contexts.BitmapContext(present_info: dict)

A context that exposes an API that takes a (grayscale or rgba) images bitmap.

This is loosely inspired by JS’ ImageBitmapRenderingContext. Rendering bitmaps is a simple way to use rendercanvas, but usually not as performant as a wgpu context. Use canvas.get_bitmap_context() to create a BitmapContext.

set_bitmap(bitmap)

Set the rendered bitmap image.

Call this in the draw event. The bitmap must be an object that can be converted to a numpy array. It must represent a 2D image in either grayscale or rgba format, with uint8 values

class rendercanvas.contexts.WgpuContext(present_info: dict)

A context that exposes an API that provides a GPU texture to render to.

This is inspired by JS’ GPUCanvasContext, and the more performant approach for rendering to a rendercanvas. Use canvas.get_wgpu_context() to create a WgpuContext.

configure(*, device: object, format: str, usage: str | int = 'RENDER_ATTACHMENT', view_formats: Sequence[str] = (), alpha_mode: str = 'opaque') → None

Configures the presentation context for the associated canvas. Destroys any textures produced with a previous configuration.

Parameters:

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

  • format (wgpu.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 (wgpu.TextureUsage) – Default “RENDER_ATTACHMENT”.

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

  • alpha_mode (wgpu.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() → dict | None

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

get_current_texture() → object

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

get_preferred_format(adapter: object) → str

Get the preferred surface texture format.

unconfigure() → None

Removes the presentation context configuration.