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 and Qt.

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() and device.configure_swap_chain(). This interface makes it possible 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_display_id()

Get the native display id on Linux. This is used by the backends to obtain a surface id on Linux. The default implementation calls into the X11 lib to get the display id.

get_physical_size()

Get the physical size in integer pixels.

get_window_id()

Get the native window id. This is used by the backends to obtain a surface id.

The WgpuCanvas classes

For each GUI toolkit that wgpu-py has builtin support, there is a WgpuCanvas class, which all derive from the following class. This thus provides a single (simple) API to work with windows.

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 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 assign the attribute directly.

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()

Request from the main loop to schedule a new draw event, so that the canvas will be updated.

set_logical_size(width, height)

Set the window size (in logical pixels).

Support for Qt

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

# First import any of the Qt libraries
from PyQt5 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 function to draw to update itself.
# Alternatively you can create a subclass and implement draw_frame().
canvas.draw_frame = 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
glfw.init()

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

# Initialize glfw, as usual
import glfw

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

# Tell the canvas what function to draw to update itself.
# Alternatively you can create a subclass and implement draw_frame().
canvas.draw_frame = 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.