2020-01-24 15:21:59 +00:00
< img align = "right" width = "25%" src = "logo.png" >
2021-05-06 17:22:18 +00:00
# wgpu
2020-03-03 03:40:04 +00:00
2021-09-28 12:50:09 +00:00
[](https://matrix.to/#/#Wgpu:matrix.org)
[](https://matrix.to/#/#wgpu:matrix.org)
[](https://matrix.to/#/#wgpu-users:matrix.org)
2020-05-02 09:10:29 +00:00
[](https://github.com/gfx-rs/wgpu/actions)
2023-10-26 05:28:27 +00:00
[](https://codecov.io/gh/gfx-rs/wgpu)
2018-09-14 13:23:15 +00:00
2023-12-01 19:02:00 +00:00
`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.
2018-09-26 14:54:26 +00:00
2023-12-01 19:02:00 +00:00
The API is based on the [WebGPU standard ](https://gpuweb.github.io/gpuweb/ ). It serves as the core of the WebGPU integration in Firefox and Deno.
2020-03-03 03:40:04 +00:00
2021-09-15 08:00:48 +00:00
## Repo Overview
2019-02-06 11:32:39 +00:00
2021-09-15 08:00:48 +00:00
The repository hosts the following libraries:
2023-06-15 20:05:26 +00:00
- [](https://crates.io/crates/wgpu) [](https://docs.rs/wgpu/) - User facing Rust API.
2023-10-26 05:28:27 +00:00
- [](https://crates.io/crates/wgpu-core) [](https://docs.rs/wgpu-core/) - Internal safe implementation.
2023-06-15 20:05:26 +00:00
- [](https://crates.io/crates/wgpu-hal) [](https://docs.rs/wgpu-hal/) - Internal unsafe GPU API abstraction layer.
- [](https://crates.io/crates/wgpu-types) [](https://docs.rs/wgpu-types/) - Rust types shared between all crates.
2023-10-26 05:28:27 +00:00
- [](https://crates.io/crates/naga) [](https://docs.rs/naga/) - Stand-alone shader translation library.
2023-10-27 04:15:51 +00:00
- [](https://crates.io/crates/d3d12) [](https://docs.rs/d3d12/) - Collection of thin abstractions over d3d12.
2023-06-15 20:05:26 +00:00
- [](https://crates.io/crates/deno_webgpu) - WebGPU implementation for the Deno JavaScript/TypeScript runtime
2021-09-15 08:00:48 +00:00
2021-10-03 16:50:39 +00:00
The following binaries:
2023-06-15 20:05:26 +00:00
2023-12-01 19:02:00 +00:00
- [](https://crates.io/crates/naga-cli) - Tool for translating shaders between different languages using `naga` .
2023-10-26 05:28:27 +00:00
- [](https://crates.io/crates/wgpu-info) - Tool for getting information on GPUs in the system.
2023-06-15 20:05:26 +00:00
- `cts_runner` - WebGPU Conformance Test Suite runner using `deno_webgpu` .
- `player` - standalone application for replaying the API traces.
2021-08-19 16:51:55 +00:00
2021-09-09 13:47:40 +00:00
For an overview of all the components in the gfx-rs ecosystem, see [the big picture ](./etc/big-picture.png ).
2021-08-19 16:51:55 +00:00
2021-09-15 08:00:48 +00:00
## Getting Started
### Rust
2023-11-23 10:26:42 +00:00
Rust examples can be found at [wgpu/examples ](examples ). You can run the examples on native with `cargo run --bin wgpu-examples <example>` . See the [list of examples ](examples ).
2023-10-04 02:12:52 +00:00
2023-12-20 20:15:35 +00:00
To run the examples on WebGPU on wasm, run `cargo xtask run-wasm --bin wgpu-examples` . Then connect to `http://localhost:8000` in your WebGPU-enabled browser, and you can choose an example to run.
2023-10-04 02:12:52 +00:00
2023-12-20 20:15:35 +00:00
To run the examples on WebGL on wasm, run `cargo xtask run-wasm --bin wgpu-examples --features webgl` . Then connect to `http://localhost:8000` in your WebGL-enabled browser, and you can choose an example to run.
2021-09-15 08:00:48 +00:00
If you are looking for a wgpu tutorial, look at the following:
2023-06-15 20:05:26 +00:00
2021-09-15 08:00:48 +00:00
- https://sotrh.github.io/learn-wgpu/
### C/C++
2022-03-24 06:23:58 +00:00
To use wgpu in C/C++, you need [wgpu-native ](https://github.com/gfx-rs/wgpu-native ).
2021-09-15 08:00:48 +00:00
2023-04-30 10:08:56 +00:00
If you are looking for a wgpu C++ tutorial, look at the following:
2023-06-15 20:05:26 +00:00
2023-04-30 10:08:56 +00:00
- https://eliemichel.github.io/LearnWebGPU/
2021-09-15 08:00:48 +00:00
### Others
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. See [the list ](https://github.com/gfx-rs/wgpu-native#bindings ).
2021-06-03 01:42:15 +00:00
2021-09-15 08:00:48 +00:00
## Community
2021-09-28 12:50:09 +00:00
We have the Matrix space [](https://matrix.to/#/#Wgpu:matrix.org) with a few different rooms that form the wgpu community:
2023-06-15 20:05:26 +00:00
2023-10-26 05:28:27 +00:00
- [](https://matrix.to/#/#wgpu:matrix.org) - discussion of the wgpu's development.
- [](https://matrix.to/#/#naga:matrix.org) - discussion of the naga's development.
- [](https://matrix.to/#/#wgpu-users:matrix.org) - discussion of using the library and the surrounding ecosystem.
2021-09-28 12:50:09 +00:00
- [](https://matrix.to/#/#wgpu-random:matrix.org) - discussion of everything else.
2021-09-15 08:00:48 +00:00
## Wiki
We have a [wiki ](https://github.com/gfx-rs/wgpu/wiki ) that serves as a knowledge base.
2020-03-03 03:40:04 +00:00
2019-07-29 21:27:30 +00:00
## Supported Platforms
2019-07-27 10:54:31 +00:00
2023-12-20 20:15:35 +00:00
| API | Windows | Linux/Android | macOS/iOS | Web (wasm) |
| ------ | ------------------ | ------------------ | ------------------ | ------------------ |
| Vulkan | :white_check_mark: | :white_check_mark: | :volcano: | |
| Metal | | | :white_check_mark: | |
| DX12 | :white_check_mark: | | | |
| OpenGL | :ok: (GL 3.3+) | :ok: (GL ES 3.0+) | :triangular_ruler: | :ok: (WebGL2) |
| WebGPU | | | | :white_check_mark: |
2021-12-05 07:24:10 +00:00
2023-10-22 04:34:00 +00:00
:white_check_mark: = First Class Support
:ok: = Downlevel/Best Effort Support
2023-11-13 19:17:54 +00:00
:triangular_ruler: = Requires the [ANGLE ](#angle ) translation layer (GL ES 3.0 only)
2023-10-22 04:34:00 +00:00
:volcano: = Requires the [MoltenVK ](https://vulkan.lunarg.com/sdk/home#mac ) translation layer
2024-02-27 19:43:05 +00:00
:hammer_and_wrench: = Unsupported, though open to contributions
2021-12-05 07:24:10 +00:00
2022-02-23 03:17:15 +00:00
### Shader Support
2022-03-24 06:23:58 +00:00
wgpu supports shaders in [WGSL ](https://gpuweb.github.io/gpuweb/wgsl/ ), SPIR-V, and GLSL.
Both [HLSL ](https://github.com/Microsoft/DirectXShaderCompiler ) and [GLSL ](https://github.com/KhronosGroup/glslang )
2023-12-01 19:02:00 +00:00
have 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.
2022-02-23 03:17:15 +00:00
2022-02-23 05:18:01 +00:00
While WebGPU does not support any shading language other than WGSL, we will automatically convert your
2022-02-23 03:17:15 +00:00
non-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.
2022-09-03 03:26:46 +00:00
Note that the WGSL specification is still under development,
so the [draft specification][wgsl spec] does not exactly describe what `wgpu` supports.
2022-09-04 16:22:25 +00:00
See [below ](#tracking-the-webgpu-and-wgsl-draft-specifications ) for details.
2022-09-03 03:26:46 +00:00
2022-11-07 18:32:23 +00:00
To enable SPIR-V shaders, enable the `spirv` feature of wgpu.
2022-02-23 03:17:15 +00:00
To enable GLSL shaders, enable the `glsl` feature of wgpu.
2021-12-05 07:24:10 +00:00
### Angle
2023-12-01 19:02:00 +00:00
[Angle ](http://angleproject.org ) is a translation layer from GLES to other backends developed by Google.
2023-10-22 04:34:00 +00:00
We support running our GLES3 backend over it in order to reach platforms DX11 support, which aren't accessible otherwise.
2023-12-01 19:02:00 +00:00
In order to run with Angle, the "angle" feature has to be enabled, and Angle libraries placed in a location visible to the application.
2022-11-07 18:32:23 +00:00
These binaries can be downloaded from [gfbuild-angle ](https://github.com/DileSoft/gfbuild-angle ) artifacts, [manual compilation ](https://github.com/google/angle/blob/main/doc/DevSetup.md ) may be required on Macs with Apple silicon.
2021-12-05 07:24:10 +00:00
2022-02-23 21:39:47 +00:00
On Windows, you generally need to copy them into the working directory, in the same directory as the executable, or somewhere in your path.
2021-12-05 07:24:10 +00:00
On Linux, you can point to them using `LD_LIBRARY_PATH` environment.
2021-09-15 08:00:48 +00:00
2023-10-04 02:12:52 +00:00
### MSRV policy
Due to complex dependants, we have two MSRV policies:
2024-02-27 19:43:05 +00:00
2024-03-14 17:00:43 +00:00
- `d3d12` , `naga` , `wgpu-core` , `wgpu-hal` , and `wgpu-types` 's MSRV is **1.74** .
2024-02-27 19:43:05 +00:00
- The rest of the workspace has an MSRV of **1.76** .
2023-10-04 02:12:52 +00:00
2023-12-01 19:02:00 +00:00
It is enforced on CI (in "/.github/workflows/ci.yml") with the `CORE_MSRV` and `REPO_MSRV` variables.
This version can only be upgraded in breaking releases, though we release a breaking version every three months.
2023-10-04 02:12:52 +00:00
2023-10-26 05:28:27 +00:00
The `naga` , `wgpu-core` , `wgpu-hal` , and `wgpu-types` crates should never
2023-10-04 02:12:52 +00:00
require an MSRV ahead of Firefox's MSRV for nightly builds, as
determined by the value of `MINIMUM_RUST_VERSION` in
[`python/mozboot/mozboot/util.py`][util].
[util]: https://searchfox.org/mozilla-central/source/python/mozboot/mozboot/util.py
2021-09-15 08:00:48 +00:00
## Environment Variables
2023-12-01 19:02:00 +00:00
All testing and example infrastructure share the same set of environment variables that determine which Backend/GPU it will run on.
2021-09-15 08:00:48 +00:00
- `WGPU_ADAPTER_NAME` with a substring of the name of the adapter you want to use (ex. `1080` will match `NVIDIA GeForce 1080ti` ).
2023-12-06 20:12:46 +00:00
- `WGPU_BACKEND` with a comma-separated list of the backends you want to use (`vulkan`, `metal` , `dx12` , or `gl` ).
2023-08-18 09:05:34 +00:00
- `WGPU_POWER_PREF` with the power preference to choose when a specific adapter name isn't specified (`high`, `low` or `none` )
2023-01-18 21:25:56 +00:00
- `WGPU_DX12_COMPILER` with the DX12 shader compiler you wish to use (`dxc` or `fxc` , note that `dxc` requires `dxil.dll` and `dxcompiler.dll` to be in the working directory otherwise it will fall back to `fxc` )
2023-08-16 15:51:56 +00:00
- `WGPU_GLES_MINOR_VERSION` with the minor OpenGL ES 3 version number to request (`0`, `1` , `2` or `automatic` ).
2023-11-24 19:29:54 +00:00
- `WGPU_ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER` with a boolean whether non-compliant drivers are enumerated (`0` for false, `1` for true).
2021-09-15 08:00:48 +00:00
When running the CTS, use the variables `DENO_WEBGPU_ADAPTER_NAME` , `DENO_WEBGPU_BACKEND` , `DENO_WEBGPU_POWER_PREFERENCE` .
## Testing
2020-04-24 18:31:02 +00:00
2023-10-22 04:34:00 +00:00
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:
2023-12-20 20:15:35 +00:00
| Platform/Backend | Tests | Notes |
| ---------------- | ------------------ | --------------------- |
| Windows/DX12 | :heavy_check_mark: | using WARP |
| Windows/OpenGL | :heavy_check_mark: | using llvmpipe |
| MacOS/Metal | :heavy_check_mark: | using hardware runner |
| Linux/Vulkan | :heavy_check_mark: | using lavapipe |
| Linux/OpenGL ES | :heavy_check_mark: | using llvmpipe |
| Chrome/WebGL | :heavy_check_mark: | using swiftshader |
| Chrome/WebGPU | :x: | not set up |
2021-06-22 01:13:38 +00:00
2021-09-15 08:00:48 +00:00
### Core Test Infrastructure
2021-06-22 01:13:38 +00:00
2022-02-25 21:46:03 +00:00
We use a tool called [`cargo nextest` ](https://github.com/nextest-rs/nextest ) to run our tests.
To install it, run `cargo install cargo-nextest` .
2021-09-15 08:00:48 +00:00
2023-10-04 02:12:52 +00:00
To run the test suite:
2021-06-22 01:13:38 +00:00
```
2023-10-19 16:06:42 +00:00
cargo xtask test
2021-06-22 01:13:38 +00:00
```
2023-10-04 02:12:52 +00:00
To run the test suite on WebGL (currently incomplete):
2021-06-22 01:13:38 +00:00
2021-09-15 08:00:48 +00:00
```
2023-10-04 02:12:52 +00:00
cd wgpu
2024-01-14 09:45:52 +00:00
wasm-pack test --headless --chrome --no-default-features --features webgl --workspace
2021-09-15 08:00:48 +00:00
```
2023-10-04 02:12:52 +00:00
This will automatically run the tests using a packaged browser. Remove `--headless` to run the tests with whatever browser you wish at `http://localhost:8000` .
2021-06-22 01:13:38 +00:00
2022-03-24 06:23:58 +00:00
If you are a user and want a way to help contribute to wgpu, we always need more help writing test cases.
2021-07-24 18:31:51 +00:00
2021-09-15 08:00:48 +00:00
### WebGPU Conformance Test Suite
WebGPU includes a Conformance Test Suite to validate that implementations are working correctly. We can run this CTS against wgpu.
2023-12-01 19:02:00 +00:00
To run the CTS, first, you need to check it out:
2021-09-15 08:00:48 +00:00
```
git clone https://github.com/gpuweb/cts.git
cd cts
# works in bash and powershell
git checkout $(cat ../cts_runner/revision.txt)
```
To run a given set of tests:
```
2023-12-01 19:02:00 +00:00
# Must be inside the `cts` folder we just checked out, else this will fail
2023-10-26 05:28:27 +00:00
cargo run --manifest-path ../Cargo.toml --bin cts_runner -- ./tools/run_deno --verbose "< test string > "
2021-09-15 08:00:48 +00:00
```
2021-10-07 22:52:56 +00:00
To find the full list of tests, go to the [online cts viewer ](https://gpuweb.github.io/cts/standalone/?runnow=0&worker=0&debug=0&q=webgpu:* ).
2021-09-15 08:00:48 +00:00
The list of currently enabled CTS tests can be found [here ](./cts_runner/test.lst ).
2022-09-03 03:26:46 +00:00
## Tracking the WebGPU and WGSL draft specifications
The `wgpu` crate is meant to be an idiomatic Rust translation of the [WebGPU API][webgpu spec].
That specification, along with its shading language, [WGSL][wgsl spec],
are both still in the "Working Draft" phase,
and while the general outlines are stable,
details change frequently.
Until the specification is stabilized, the `wgpu` crate and the version of WGSL it implements
will likely differ from what is specified,
as the implementation catches up.
Exactly which WGSL features `wgpu` supports depends on how you are using it:
- When running as native code, `wgpu` uses the [Naga][naga] crate
to translate WGSL code into the shading language of your platform's native GPU API.
Naga has [a milestone][naga wgsl milestone]
for catching up to the WGSL specification,
2023-12-01 19:02:00 +00:00
but in general, there is no up-to-date summary
2022-09-03 03:26:46 +00:00
of the differences between Naga and the WGSL spec.
2022-11-07 18:32:23 +00:00
2022-09-03 03:26:46 +00:00
- 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 with `wgpu` 's `"webgl"` feature enabled,
`wgpu` uses Naga to translate WGSL programs into GLSL.
This uses the same version of Naga as if you were running `wgpu` as native code.
[webgpu spec]: https://www.w3.org/TR/webgpu/
[wgsl spec]: https://gpuweb.github.io/gpuweb/wgsl/
[naga]: https://github.com/gfx-rs/naga/
[naga wgsl milestone]: https://github.com/gfx-rs/naga/milestone/4
2021-07-24 18:31:51 +00:00
## Coordinate Systems
2021-09-15 08:00:48 +00:00
wgpu uses the coordinate systems of D3D and Metal:
2021-07-24 18:31:51 +00:00
2023-06-15 20:05:26 +00:00
| Render | Texture |
| --------------------------------------------------- | ----------------------------------------------------- |
|  |  |
