Package: wgpu
wgpu-pyA Python implementation of WebGPU - the next generation GPU API.IntroductionIn short, this is a Python lib wrappingwgpu-nativeand exposing it with a Pythonic
API similar to theWebGPU 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 Pythonwgpulibrary brings the WebGPU API to
Python.To get an idea of what this API looks like have a look attriangle.pyand the otherexamples.StatusNoteThe 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 close to 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 thechangelogwhen you
upgrade!Installationpip install wgpu glfwLinux users should make sure thatpip >= 20.3. That should do the
trick on most systems. Seegetting startedfor details.UsageAlso see theonline documentationand theexamples.The full API is accessable via the main namespace:importwgpuTo render to the screen you can use a variety of GUI toolkits:# The auto backend selects either the glfw, qt or jupyter backendfromwgpu.gui.autoimportWgpuCanvas,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.fromwgpu.gui.qtimportWgpuCanvas# Visualizations can be embedded as a widget in a wx application.fromwgpu.gui.wximportWgpuCanvasSome functions in the originalwgpu-nativeAPI 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.LicenseThis code is distributed under the 2-clause BSD license.Projects usingwgpu-pypygfx- A python render engine running on wgpu.shadertoy- Shadertoy implementation using wgpu-py.tinygrad- deep learning frameworkfastplotlib- A fast plotting libraryxdsl- A Python Compiler Design Toolkit (optional wgpu interpreter)DevelopersClone the repo.Install devtools usingpip install -r dev-requirements.txt(you can replacepipwithpipenvto install to a virtualenv).Install wgpu-py in editable mode by runningpip install -e ., this will also
install runtime dependencies as needed.Runpython download-wgpu-native.pyto download the upstream wgpu-native
binaries.Or alternatively point theWGPU_LIB_PATHenvironment variable to a custom
build.Useblack .to apply autoformatting.Useflake8 .to check for flake errors.Usepytest .to run the tests.Usepip wheel --no-deps .to build a wheel.Updating to a later version of WebGPU or wgpu-nativeTo update to upstream changes, we use a combination of automatic code
generation and manual updating. Seethe codegen utilityfor more information.TestingThe 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 runWhen 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 = falsein the module.Type 2: Checking if examples output an imageYou can also (independently) opt-in to output testing for examples, by including
the comment# test_example = truein the module. Output testing means the test
suite will attempt to import thecanvasinstance 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:TheWgpuCanvasclass is imported from thewgpu.gui.automodule.Thecanvasinstance is exposed as a global in the module.A rendering callback has been registered withcanvas.request_draw(fn).Reference screenshots are stored in theexamples/screenshotsfolder, 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 theexamples/screenshots/diffsfolder. On CI, theexamples/screenshotsfolder
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.