gui API¶

You can use vanilla wgpu for compute tasks and to render offscreen. To render to a window on screen we need a canvas. Since the Python ecosystem provides many different GUI toolkits, wgpu implements a base canvas class, and has builtin support for a few GUI toolkits. At the moment these include GLFW, Jupyter, Qt, and wx.

The Canvas base classes¶

`WgpuCanvasInterface`	The minimal interface to be a valid canvas.
`WgpuCanvasBase`	A convenient base canvas class.
`WgpuAutoGui`	Mixin class for canvases implementing autogui.
`WgpuOffscreenCanvasBase`	Base class for off-screen canvases.

For each supported GUI toolkit there is a module that implements a WgpuCanvas class, which inherits from WgpuCanvasBase, providing a common API. The GLFW, Qt, and Jupyter backends also inherit from WgpuAutoGui to include support for events (interactivity). In the next sections we demonstrates the different canvas classes that you can use.

The auto GUI backend¶

The default approach for examples and small applications is to use the automatically selected GUI backend. At the moment this selects either the GLFW, Qt, or Jupyter backend, depending on the environment.

To implement interaction, the canvas has a WgpuAutoGui.handle_event() method that can be overloaded. Alternatively you can use it’s WgpuAutoGui.add_event_handler() method. See the event spec for details about the event objects.

Also see the triangle auto example and cube example.

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

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

run()

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.

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

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

run()

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. For a toplevel widget, the gui.qt.WgpuCanvas class can be imported. If you want to embed the canvas as a subwidget, use gui.qt.WgpuWidget instead.

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

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

Support for wx¶

There is support for embedding a wgpu visualization in wxPython. For a toplevel widget, the gui.wx.WgpuCanvas class can be imported. If you want to embed the canvas as a subwidget, use gui.wx.WgpuWidget instead.

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

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

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(size=(500, 400), pixel_ratio=1)

# ...

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

# Perform a draw
array = canvas.draw()  # numpy array with shape (400, 500, 4)

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.

# 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