GUI API

You can use wgpu for compute tasks and to render offscreen. Rendering to screen is also possible, but we need a canvas for that. Since the Python ecosystem provides many different GUI toolkits, we need an interface.

For convenience, the wgpu library has builtin support for a few GUI toolkits. At the moment these include GLFW, Jupyter, Qt, and wx.

The canvas interface

To render to a window, an object is needed that implements the few functions on the canvas interface, and provide that object to request_adapter(). This is the minimal interface required to hook wgpu-py to any GUI that supports GPU rendering.

class wgpu.gui.WgpuCanvasInterface(*args, **kwargs)

This is the interface that a canvas object must implement in order to be a valid canvas that wgpu can work with.

get_context(kind='gpupresent')

Get the GPUCanvasContext object corresponding to this canvas, which can be used to e.g. obtain a texture to render to.

get_display_id()

Get the native display id on Linux. This is needed in addition to the window id to obtain a surface id. The default implementation calls into the X11 lib to get the display id.

get_physical_size()

Get the physical size of the canvas in integer pixels.

get_window_id()

Get the native window id. This is used to obtain a surface id, so that wgpu can render to the region of the screen occupied by the canvas.

The WgpuCanvas base class

For each supported GUI toolkit there are specific WgpuCanvas classes, which are detailed in the following sections. These all derive from the same base class, which defines the common API.

class wgpu.gui.WgpuCanvasBase(*args, max_fps=30, vsync=True, **kwargs)

An abstract class extending WgpuCanvasInterface, that provides a base canvas for various GUI toolkits, so that basic canvas functionality is available via a common API.

It is convenient - but not required - to use this class (or any of its subclasses) to use wgpu-py.

This class applies draw rate limiting, which can be set with the max_fps attribute (default 30). For benchmarks you may also want to set vsync to False.

close()

Close the window.

draw_frame()

The function that gets called at each draw. You can implement this method in a subclass, or set it via a call to request_draw().

get_logical_size()

Get the logical size in float pixels.

get_physical_size()

Get the physical size in integer pixels.

get_pixel_ratio()

Get the float ratio between logical and physical pixels.

is_closed()

Get whether the window is closed.

request_draw(draw_function=None)

Request from the main loop to schedule a new draw event, so that the canvas will be updated. If draw_function is not given, the last set drawing function is used.

set_logical_size(width, height)

Set the window size (in logical pixels).

Base offscreen class

A base class is provided to implement off-screen canvases for different purposes.

class wgpu.gui.WgpuOffscreenCanvas(*args, **kwargs)

Base class for off-screen canvases, providing a custom presentation context that renders to a tetxure instead of a surface/screen. The resulting texture view is passed to the present() method.

get_context(kind='gpupresent')

Get the GPUCanvasContext object to obtain a texture to render to.

get_preferred_format()

Get the preferred format for this canvas. This method can be overloaded to control the used texture format. The default is “rgba8unorm-srgb”.

get_window_id()

This canvas does not correspond to an on-screen window.

present(texture_view)

Method that gets called at the end of each draw event. Subclasses should provide the approproate implementation.

The auto GUI backend

The default approach for examples and small applications is to use the automatically selected GUI backend.

from wgpu.gui.auto import WgpuCanvas, run, call_later

canvas = WgpuCanvas(title="Example")
canvas.request_draw(your_draw_function)

run()

At the moment this selects either the GLFW, Qt, or Jupyter backend, depending on the enviornment. The WgpuCanvas has a handle_event() method that can be overloaded (by subclassing WgpuCanvas) to process user events. See the event spec.

Gui backends that support the auto-gui mechanics, implement WgpuAutoGui.

class wgpu.gui.WgpuAutoGui(*args, **kwargs)

Mixin class for canvases implementing autogui.

add_event_handler(*args)

Register an event handler.

Parameters:
  • callback (callable) – The event handler. Must accept a single event argument.
  • *types (list of strings) – A list of event types.

For the available events, see https://jupyter-rfb.readthedocs.io/en/latest/events.html

Can also be used as a decorator.

Example:

def my_handler(event):
    print(event)

canvas.add_event_handler(my_handler, "pointer_up", "pointer_down")

Decorator usage example:

@canvas.add_event_handler("pointer_up", "pointer_down")
def my_handler(event):
    print(event)

Catch ‘m all:

canvas.add_event_handler(my_handler, "*")
handle_event(event)

Handle an incoming event.

Subclasses can overload this method. Events include widget resize, mouse/touch interaction, key events, and more. An event is a dict with at least the key event_type. For details, see https://jupyter-rfb.readthedocs.io/en/latest/events.html

The default implementation dispatches the event to the registered event handlers.

remove_event_handler(callback, *types)

Unregister an event handler.

Parameters:
  • callback (callable) – The event handler.
  • *types (list of strings) – A list of event types.

Support for Qt

There is support for PyQt5, PyQt6, PySide2 and PySide6. The wgpu library detects what library you are using by looking what module has been imported.

# Import any of the Qt libraries before importing the WgpuCanvas.
# This way wgpu knows which Qt library to use.
from PySide6 import QtWidgets
from wgpu.gui.qt import WgpuCanvas

app = QtWidgets.QApplication([])

# Instantiate the canvas
canvas = WgpuCanvas(title="Example")

# Tell the canvas what drawing function to call
canvas.request_draw(your_draw_function)

app.exec_()

For a toplevel widget, the WgpuCanvas class can be imported. If you want to embed the canvas as a subwidget, use WgpuWidget instead.

Also see the Qt triangle example and Qt triangle embed example.

Support for wx

There is support for embedding a wgpu visualization in wxPython.

import wx
from wgpu.gui.wx import WgpuCanvas

app = wx.App()

# Instantiate the canvas
canvas = WgpuCanvas(title="Example")

# Tell the canvas what drawing function to call
canvas.request_draw(your_draw_function)

app.MainLoop()

For a toplevel widget, the WgpuCanvas class can be imported. If you want to embed the canvas as a subwidget, use WgpuWidget instead.

Also see the wx triangle example and wx triangle embed example.

Support for offscreen

You can also use a “fake” canvas to draw offscreen and get the result as a numpy array. Note that you can render to a texture without using any canvas object, but in some cases it’s convenient to do so with a canvas-like API.

from wgpu.gui.offscreen import WgpuCanvas

# Instantiate the canvas
canvas = WgpuCanvas(640, 480)

# ...

# Tell the canvas what drawing function to call
canvas.request_draw(your_draw_function)

# Perform a draw
array = canvas.draw()

Support for GLFW

GLFW is a lightweight windowing toolkit. Install it with pip install glfw. The preferred approach is to use the auto backend, but you can replace from wgpu.gui.auto with from wgpu.gui.glfw to force using GLFW.

To implement interaction, create a subclass and overload the handle_event() method (and call super().handle_event(event)). See the event spec.

Support for Jupyter lab and notebook

WGPU can be used in Jupyter lab and the Jupyter notebook. This canvas is based on jupyter_rfb an ipywidget subclass implementing a remote frame-buffer. There are also some wgpu examples.

To implement interaction, create a subclass and overload the handle_event() method (and call super().handle_event(event)). See the event spec.

# from wgpu.gui.jupyter import WgpuCanvas  # Direct approach
from wgpu.gui.auto import WgpuCanvas  # Approach compatible with desktop usage

canvas = WgpuCanvas()

# ... wgpu code

canvas  # Use as cell output