Repository files navigation

wgpu is a cross-platform, safe, pure-rust graphics API. It runs natively on Vulkan, Metal, D3D12, and OpenGL; and on top of WebGL2 and WebGPU on wasm.

The API is based on theWebGPU standard. It serves as the core of the WebGPU integration in Firefox, Servo, and Deno.

Contributors are welcome! SeeCONTRIBUTING.md for more information.

The repository hosts the following libraries:

• - User facing Rust API.
• - Internal safe implementation.
• - Internal unsafe GPU API abstraction layer.
• - Rust types shared between all crates.
• - Stand-alone shader translation library.
• - WebGPU implementation for the Deno JavaScript/TypeScript runtime

The following binaries:

• - Tool for translating shaders between different languages usingnaga.
• - Tool for getting information on GPUs in the system.
• cts_runner - WebGPU Conformance Test Suite runner usingdeno_webgpu.
• player - standalone application for replaying the API traces.

For an overview of all the components in the gfx-rs ecosystem, seethe big picture.

Go tohttps://wgpu.rs/examples/ to play with our examples in your browser. Requires a browser supporting WebGPU for the WebGPU examples.

Rust examples can be found atexamples. You can run the examples natively withcargo run --bin wgpu-examples <example>.

If you are new to wgpu and graphics programming, we recommend starting withhttps://sotrh.github.io/learn-wgpu/.

To run the examples in a browser, runcargo xtask run-wasm.Then openhttp://localhost:8000 in your browser, and you can choose an example to run.Naturally, in order to display any of the WebGPU based examples, you need to make sure your browser supports it.

To use wgpu in C/C++, you needwgpu-native.

If you are looking for a wgpu C++ tutorial, look at the following:

• https://eliemichel.github.io/LearnWebGPU/

If you want to use wgpu in other languages, there are many bindings to wgpu-native from languages such as Python, D, Julia, Kotlin, and more. Seethe list.

We have the Matrix space with a few different rooms that form the wgpu community:

• - discussion of the wgpu's development.
• - discussion of the naga's development.
• - discussion of using the library and the surrounding ecosystem.
• - discussion of everything else.

We have awiki that serves as a knowledge base.

While the core of wgpu is based on the WebGPU standard, we also support extensions that allow for features that the standard does not have yet.For high-level documentation on how to use these extensions, see the individual specifications:

🧪EXPERIMENTAL🧪 APIs are subject to change and may allow undefined behavior if used incorrectly.

• 🧪EXPERIMENTAL🧪Ray Tracing.

✅ = First Class Support
🆗 = Downlevel/Best Effort Support
📐 = Requires theANGLE translation layer (GL ES 3.0 only)
🌋 = Requires theMoltenVK translation layer
🛠️ = Unsupported, though open to contributions

wgpu supports shaders inWGSL, SPIR-V, and GLSL.BothHLSL andGLSLhave compilers to target SPIR-V. All of these shader languages can be used with any backend as we handle all of the conversions. Additionally, support for these shader inputs is not going away.

While WebGPU does not support any shading language other than WGSL, we will automatically convert yournon-WGSL shaders if you're running on WebGPU.

WGSL is always supported by default, but GLSL and SPIR-V need features enabled to compile in support.

Note that the WGSL specification is still under development,so thedraft specification does not exactly describe whatwgpu supports.Seebelow for details.

To enable SPIR-V shaders, enable thespirv feature of wgpu.To enable GLSL shaders, enable theglsl feature of wgpu.

Angle is a translation layer from GLES to other backends developed by Google.We support running our GLES3 backend over it in order to reach platforms DX11 support, which aren't accessible otherwise.In order to run with Angle, the "angle" feature has to be enabled, and Angle libraries placed in a location visible to the application.These binaries can be downloaded fromgfbuild-angle artifacts,manual compilation may be required on Macs with Apple silicon.

On Windows, you generally need to copy them into the working directory, in the same directory as the executable, or somewhere in your path.On Linux, you can point to them usingLD_LIBRARY_PATH environment.

Due to complex dependants, we have two MSRV policies:

• naga,wgpu-core,wgpu-hal, andwgpu-types's MSRV is1.76.
• The rest of the workspace has an MSRV of1.85.

It is enforced on CI (in "/.github/workflows/ci.yml") with theCORE_MSRV andREPO_MSRV variables.This version can only be upgraded in breaking releases, though we release a breaking version every three months.

Thenaga,wgpu-core,wgpu-hal, andwgpu-types crates should neverrequire an MSRV ahead of Firefox's MSRV for nightly builds, asdetermined by the value ofMINIMUM_RUST_VERSION inpython/mozboot/mozboot/util.py.

All testing and example infrastructure share the same set of environment variables that determine which Backend/GPU it will run on.

• WGPU_ADAPTER_NAME with a substring of the name of the adapter you want to use (ex.1080 will matchNVIDIA GeForce 1080ti).
• WGPU_BACKEND with a comma-separated list of the backends you want to use (vulkan,metal,dx12, orgl).
• WGPU_POWER_PREF with the power preference to choose when a specific adapter name isn't specified (high,low ornone)
• WGPU_DX12_COMPILER with the DX12 shader compiler you wish to use (dxc,static-dxc, orfxc). Note thatdxc requiresdxil.dll anddxcompiler.dll to be in the working directory, andstatic-dxc requires thestatic-dxc crate feature to be enabled. Otherwise, it will fall back tofxc.
• WGPU_GLES_MINOR_VERSION with the minor OpenGL ES 3 version number to request (0,1,2 orautomatic).
• WGPU_ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER with a boolean whether non-compliant drivers are enumerated (0 for false,1 for true).

When running the CTS, use the variablesDENO_WEBGPU_ADAPTER_NAME,DENO_WEBGPU_BACKEND,DENO_WEBGPU_POWER_PREFERENCE.

We have multiple methods of testing, each of which tests different qualities about wgpu. We automatically run our tests on CI. The current state of CI testing:

We use a tool calledcargo nextest to run our tests.To install it, runcargo install cargo-nextest.

To run the test suite:

cargo xtask test

To run the test suite on WebGL (currently incomplete):

cd wgpuwasm-pack test --headless --chrome --no-default-features --features webgl --workspace

This will automatically run the tests using a packaged browser. Remove--headless to run the tests with whatever browser you wish athttp://localhost:8000.

If you are a user and want a way to help contribute to wgpu, we always need more help writing test cases.

WebGPU includes a Conformance Test Suite to validate that implementations are working correctly. We can run this CTS against wgpu.

To run the CTS, first, you need to check it out:

git clone https://github.com/gpuweb/cts.gitcd cts# works in bash and powershellgit checkout $(cat ../cts_runner/revision.txt)

To run a given set of tests:

# Must be inside the `cts` folder we just checked out, else this will failcargo run --manifest-path ../Cargo.toml -p cts_runner --bin cts_runner -- ./tools/run_deno --verbose "<test string>"

To find the full list of tests, go to theonline cts viewer.

The list of currently enabled CTS tests can be foundhere.

Thewgpu crate is meant to be an idiomatic Rust translation of theWebGPU API.That specification, along with its shading language,WGSL,are both still in the "Working Draft" phase,and while the general outlines are stable,details change frequently.Until the specification is stabilized, thewgpu crate and the version of WGSL it implementswill likely differ from what is specified,as the implementation catches up.

Exactly which WGSL featureswgpu supports depends on how you are using it:

• When running as native code,wgpu uses theNaga crateto translate WGSL code into the shading language of your platform's native GPU API.Naga hasa milestonefor catching up to the WGSL specification,but in general, there is no up-to-date summaryof the differences between Naga and the WGSL spec.

• When running in a web browser (by compilation to WebAssembly)without the"webgl" feature enabled,wgpu relies on the browser's own WebGPU implementation.WGSL shaders are simply passed through to the browser,so that determines which WGSL features you can use.

• When running in a web browser withwgpu's"webgl" feature enabled,wgpu uses Naga to translate WGSL programs into GLSL.This uses the same version of Naga as if you were runningwgpu as native code.

wgpu uses the coordinate systems of D3D and Metal:

Render	Texture