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, Qt, and wx (experimental).

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, **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.

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” (not including srgb colormapping).

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.

Support for Qt¶

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

# First import any of the Qt libraries
from PySide6 import QtWidgets

# Then import the WgpuCanvas, which is a subclass of QWidget
from wgpu.gui.qt import WgpuCanvas

# Create a Qt app, as usual
app = QtWidgets.QApplication([])

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

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

# Enter Qt's event loop, as usual
app.exec_()

Also see the Qt triangle example.

Support for glfw¶

Glfw is a lightweight windowing toolkit. Install it with pip install glfw.

# Import glfw itself
import glfw

# Then import the WgpuCanvas
from wgpu.gui.glfw import update_glfw_canvasses, WgpuCanvas

# Initialize glfw, as usual
glfw.init()

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

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

# Enter a main loop (this stops when all windows are closed)
while update_glfw_canvasses():
    glfw.poll_events()

Also see the GLFW triangle example and the async GLFW 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 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)).

from wgpu.gui.jupyter import WgpuCanvas

canvas = WgpuCanvas()

# ... wgpu code

canvas  # Use as cell output