Next generation GPU API for Python
Project description
wgpu-py
A Python implementation of WebGPU - the next generation GPU API.
Introduction
In short, this is a Python lib wrapping wgpu-native and exposing it with a Pythonic API similar to the WebGPU spec.
The OpenGL API is old and showing it's cracks. New API's like Vulkan, Metal and
DX12 provide a modern way to control the GPU, but these API's are too low-level
for general use. The WebGPU API follows the same concepts, but with a simpler
(higher level) spelling. The Python wgpu library brings the WebGPU API to
Python.
To get an idea of what this API looks like have a look at triangle.py and the other examples.
Status
Note
The wgpu-API has not settled yet, use with care!
- Coverage of the WebGPU spec is complete enough to build e.g. pygfx.
- Test coverage of the API is 100%.
- Support for Windows, Linux, and MacOS (Intel and M1).
- Until WebGPU settles as a standard, its specification may change, and with that our API will probably too. Check the changelog when you upgrade!
Installation
pip install wgpu glfw
Linux users should make sure that pip >= 20.3. That should do the trick on most systems. See getting started for details.
Usage
Also see the online documentation and the examples.
The full API is accessable via the main namespace:
import wgpu
But to use it, you need to select a backend first. You do this by importing it. There is currently only one backend:
import wgpu.backends.rs
To render to the screen you can use a variety of GUI toolkits:
# The auto backend selects either the glfw, qt or jupyter backend
from wgpu.gui.auto import WgpuCanvas, run, call_later
# Visualizations can be embedded as a widget in a Qt application.
# Import PySide6, PyQt6, PySide2 or PyQt5 before running the line below.
# The code will detect and use the library that is imported.
from wgpu.gui.qt import WgpuCanvas
# Visualizations can be embedded as a widget in a wx application.
from wgpu.gui.wx import WgpuCanvas
Some functions in the original wgpu-native API are async. In the Python API,
the default functions are all sync (blocking), making things easy for general use.
Async versions of these functions are available, so wgpu can also work
well with Asyncio or Trio.
License
This code is distributed under the 2-clause BSD license.
Developers
- Clone the repo.
- Install devtools using
pip install -r dev-requirements.txt(you can replacepipwithpipenvto install to a virtualenv). - Install wgpu-py in editable mode by running
pip install -e ., this will also install runtime dependencies as needed. - Run
python download-wgpu-native.pyto download the upstream wgpu-native binaries.- Or alternatively point the
WGPU_LIB_PATHenvironment variable to a custom build.
- Or alternatively point the
- Use
black .to apply autoformatting. - Use
flake8 .to check for flake errors. - Use
pytest .to run the tests. - Use
pip wheel --no-deps .to build a wheel.
Changing the upstream wgpu-native version
- Use the optional arguments to
python download-wgpu-native.py --helpto download a different version of the upstream wgpu-native binaries. - The file
wgpu/resources/wgpu_native-versionwill be updated by the script to track which version we depend upon.
Testing
The test suite is divided into multiple parts:
pytest -v testsruns the core unit tests.pytest -v examplestests the examples.pytest -v wgpu/__pyinstallertests if wgpu is properly supported by pyinstaller.pytest -v codegenlints the generated binding code.
There are two types of tests for examples included:
Type 1: Checking if examples can run
When running the test suite, pytest will run every example in a subprocess, to
see if it can run and exit cleanly. You can opt out of this mechanism by
including the comment # run_example = false in the module.
Type 2: Checking if examples output an image
You can also (independently) opt-in to output testing for examples, by including
the comment # test_example = true in the module. Output testing means the test
suite will attempt to import the canvas instance global from your example, and
call it to see if an image is produced.
To support this type of testing, ensure the following requirements are met:
- The
WgpuCanvasclass is imported from thewgpu.gui.automodule. - The
canvasinstance is exposed as a global in the module. - A rendering callback has been registered with
canvas.request_draw(fn).
Reference screenshots are stored in the examples/screenshots folder, the test
suite will compare the rendered image with the reference.
Note: this step will be skipped when not running on CI. Since images will have subtle differences depending on the system on which they are rendered, that would make the tests unreliable.
For every test that fails on screenshot verification, diffs will be generated
for the rgb and alpha channels and made available in the
examples/screenshots/diffs folder. On CI, the examples/screenshots folder
will be published as a build artifact so you can download and inspect the
differences.
If you want to update the reference screenshot for a given example, you can grab those from the build artifacts as well and commit them to your branch.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
File details
Details for the file wgpu-0.9.3.tar.gz.
File metadata
- Download URL: wgpu-0.9.3.tar.gz
- Upload date:
- Size: 130.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | fb2f524376da6e59541a6dd922f232e72719a598b618d655f35489840a9523c5 |
|
| MD5 | 6bbc4bc82f30cbbb1b477cdf2eac4acf |
|
| BLAKE2b-256 | 7286d9e4cd39925e18593158d91655b681afd4e76788fc230959e264e4f5828e |
File details
Details for the file wgpu-0.9.3-py3-none-win_amd64.whl.
File metadata
- Download URL: wgpu-0.9.3-py3-none-win_amd64.whl
- Upload date:
- Size: 2.0 MB
- Tags: Python 3, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 0a8489c47f4ded526338163e80f53ee5561b2fe8ae92792684cac3b7ebb77f85 |
|
| MD5 | bfda0a6e2203c3b1adf9a56314af050c |
|
| BLAKE2b-256 | 2dfb53a69d99dba511216f56a5dfab1077c06c10432e7140fb4bffdcd3ebf5fd |
File details
Details for the file wgpu-0.9.3-py3-none-win32.whl.
File metadata
- Download URL: wgpu-0.9.3-py3-none-win32.whl
- Upload date:
- Size: 1.9 MB
- Tags: Python 3, Windows x86
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 37393585e55c92b43dd363c954953274d21f3fee6973219e9d6c5843b8bb85a9 |
|
| MD5 | b31a4db1718500589b6181eff1209eb5 |
|
| BLAKE2b-256 | c1e7695a791f37da9efe39a434f3600c39e80368dd89eaa7dec9e2e04f096403 |
File details
Details for the file wgpu-0.9.3-py3-none-manylinux_2_24_x86_64.whl.
File metadata
- Download URL: wgpu-0.9.3-py3-none-manylinux_2_24_x86_64.whl
- Upload date:
- Size: 3.3 MB
- Tags: Python 3, manylinux: glibc 2.24+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 6be3db34708e0b2040109d121aacc9084bf0c25896838f045bea4244dedd4570 |
|
| MD5 | f32bc0e46f05922db33af2ef977da576 |
|
| BLAKE2b-256 | 9ae5bcedc8de941a001df7c2e14330ce406410041cc82b2fded7c0521ec42951 |
File details
Details for the file wgpu-0.9.3-py3-none-manylinux_2_24_i686.whl.
File metadata
- Download URL: wgpu-0.9.3-py3-none-manylinux_2_24_i686.whl
- Upload date:
- Size: 3.5 MB
- Tags: Python 3, manylinux: glibc 2.24+ i686
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 12753eba2bded53da7871de56358590a5da6289c2ba788159f4cda966231dd7e |
|
| MD5 | cb50208db8075d48e3bc4826e92fa63e |
|
| BLAKE2b-256 | caf3c5ca4d03f8e3933786e804f900603941741e202e020b02a3cd06136d373b |
File details
Details for the file wgpu-0.9.3-py3-none-macosx_11_0_arm64.whl.
File metadata
- Download URL: wgpu-0.9.3-py3-none-macosx_11_0_arm64.whl
- Upload date:
- Size: 1.6 MB
- Tags: Python 3, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 3ee3e4a10ba2a5f204ffc3f940436f7c3ddfad7092a6d994db5245fd1089cd15 |
|
| MD5 | 473ac35e16c5344ba9a1b9724b5864c5 |
|
| BLAKE2b-256 | 2afe22419f258fd734f52d88deb5ea09f3a8e07ce290ab54f0bc2717d35c893f |
File details
Details for the file wgpu-0.9.3-py3-none-macosx_10_9_x86_64.whl.
File metadata
- Download URL: wgpu-0.9.3-py3-none-macosx_10_9_x86_64.whl
- Upload date:
- Size: 1.7 MB
- Tags: Python 3, macOS 10.9+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.16
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 52f69e0b26e4c438f55c61c2d9972e9d2bfe15f896863e0f2c7320a521c1ba1f |
|
| MD5 | 9891502b81728ba91e9fe796b38edfcf |
|
| BLAKE2b-256 | 146b1c683f4959ec398ae4e2b99a846d327e044368fef62058da5f4a6d7e00a1 |
