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)
2021-05-06 17:22:18 +00:00
[](https://codecov.io/gh/gfx-rs/wgpu)
2018-09-14 13:23:15 +00:00
2021-09-15 08:00:48 +00:00
`wgpu` is a cross-platform, safe, pure-rust graphics api. It runs natively on Vulkan, Metal, D3D12, D3D11, and OpenGLES; and on top of WebGPU on wasm.
2018-09-26 14:54:26 +00:00
2021-09-15 08:00:48 +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, Servo, 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.
- [](https://crates.io/crates/wgpu-core) [](https://docs.rs/wgpu-core/) - Internal WebGPU implementation.
- [](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.
- [](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
- `cts_runner` - WebGPU Conformance Test Suite runner using `deno_webgpu` .
- `player` - standalone application for replaying the API traces.
- `wgpu-info` - program that prints out information about all the adapters on the system or invokes a command for every adapter.
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-12-03 15:10:55 +00:00
### MSRV policy
2023-07-20 01:29:10 +00:00
Minimum Supported Rust Version is **1.65** .
2022-11-07 15:30:19 +00:00
It is enforced on CI (in "/.github/workflows/ci.yml") with `RUST_VERSION` variable.
2021-12-03 15:10:55 +00:00
This version can only be upgraded in breaking releases.
2022-11-23 21:22:03 +00:00
The `wgpu-core` , `wgpu-hal` , and `wgpu-types` crates should never
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]. However, Firefox uses `cargo
vendor` to extract only those crates it actually uses, so the
workspace's other crates can have more recent MSRVs.
2023-06-15 20:05:26 +00:00
_Note for Rust 1.64_: The workspace itself can even use a newer MSRV
2022-11-23 21:22:03 +00:00
than Firefox, as long as the vendoring step's `Cargo.toml` rewriting
removes any features Firefox's MSRV couldn't handle. For example,
`wgpu` can use manifest key inheritance, added in Rust 1.64, even
before Firefox reaches that MSRV, because `cargo vendor` copies
inherited values directly into the individual crates' `Cargo.toml`
files, producing 1.63-compatible files.
[util]: https://searchfox.org/mozilla-central/source/python/mozboot/mozboot/util.py
2021-09-15 08:00:48 +00:00
## Getting Started
### Rust
2023-06-19 01:54:09 +00:00
Rust examples can be found at `wgpu/examples` . You can run the examples with `cargo run --bin name` . See the [list of examples ](examples ). For detailed instructions, look at [Running the examples ](https://github.com/gfx-rs/wgpu/wiki/Running-the-examples ) on the wiki.
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
2021-09-28 12:50:09 +00:00
- [](https://matrix.to/#/#wgpu:matrix.org) - discussion of the library's development.
- [](https://matrix.to/#/#wgpu-users:matrix.org) - discussion of using the library and the surrounding ecosystem.
- [](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-06-15 20:05:26 +00:00
| API | Windows | Linux & Android | macOS & iOS |
| ------ | ------------------------------ | ------------------ | ------------------------- |
| Vulkan | :white_check_mark: | :white_check_mark: | :ok: (vulkan-portability) |
| Metal | | | :white_check_mark: |
| DX12 | :white_check_mark: (W10+ only) | | |
| DX11 | :hammer_and_wrench: | | |
| GLES3 | | :ok: | |
| Angle | :ok: | :ok: | :ok: (macOS only) |
2021-12-05 07:24:10 +00:00
2021-12-05 21:37:57 +00:00
:white_check_mark: = First Class Support — :ok: = Best Effort Support — :hammer_and_wrench: = Unsupported, but support in progress
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 )
2022-02-23 03:17:15 +00:00
have compilers to target SPIR-V. All of these shader languages can be used with any backend, we
will handle all of the conversion. Additionally, support for these shader inputs is not going away.
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
2021-12-10 09:27:53 +00:00
[Angle ](http://angleproject.org ) is a translation layer from GLES to other backends, developed by Google.
2021-12-05 07:24:10 +00:00
We support running our GLES3 backend over it in order to reach platforms with GLES2 or DX11 support, which aren't accessible otherwise.
In order to run with Angle, "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
## Environment Variables
All testing and example infrastructure shares 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 match `NVIDIA GeForce 1080ti` ).
- `WGPU_BACKEND` with a comma separated list of the backends you want to use (`vulkan`, `metal` , `dx12` , `dx11` , or `gl` ).
2022-06-14 05:04:14 +00:00
- `WGPU_POWER_PREF` with the power preference to choose when a specific adapter name isn't specified (`high` or `low` )
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` ).
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
2021-09-15 08:00:48 +00:00
We have multiple methods of testing, each of which tests different qualities about wgpu. We automatically run our tests on CI if possible. The current state of CI testing:
2021-06-22 01:13:38 +00:00
2023-06-15 20:05:26 +00:00
| Backend/Platform | Tests | CTS | Notes |
| ---------------- | ------------------ | ------------------ | ------------------------------------- |
| DX12/Windows 10 | :heavy_check_mark: | :heavy_check_mark: | using WARP |
| DX11/Windows 10 | :construction: | — | using WARP |
| Metal/MacOS | — | — | metal requires GPU |
| Vulkan/Linux | :heavy_check_mark: | :x: | using lavapipe, [cts hangs][cts-hang] |
| GLES/Linux | :heavy_check_mark: | — | using llvmpipe |
2022-02-25 21:46:03 +00:00
[cts-hang]: https://github.com/gfx-rs/wgpu/issues/1974
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
To run the test suite on the default device:
2021-06-22 01:13:38 +00:00
```
2022-02-25 21:46:03 +00:00
cargo nextest run --no-fail-fast
2021-06-22 01:13:38 +00:00
```
2022-02-25 21:46:03 +00:00
`wgpu-info` can run the tests once for each adapter on your system.
2021-06-22 01:13:38 +00:00
2021-09-15 08:00:48 +00:00
```
2022-02-25 21:46:03 +00:00
cargo run --bin wgpu-info -- cargo nextest run --no-fail-fast
2021-09-15 08:00:48 +00:00
```
Then to run an example's image comparison tests, run:
2021-06-22 01:13:38 +00:00
```
2022-07-10 22:18:01 +00:00
cargo nextest run < example-test-name > --no-fail-fast
2021-06-22 01:13:38 +00:00
```
Or run a part of the integration test suite:
```
2022-02-25 21:46:03 +00:00
cargo nextest run -p wgpu -- < name-of-test >
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.
To run the CTS, first you need to check it out:
```
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:
```
# Must be inside the cts folder we just checked out, else this will fail
2021-12-06 16:42:40 +00:00
cargo run --manifest-path ../cts_runner/Cargo.toml -- ./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,
but in general there is no up-to-date summary
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 |
| --------------------------------------------------- | ----------------------------------------------------- |
|  |  |
