# wgpu [](https://matrix.to/#/#Wgpu:matrix.org) [](https://matrix.to/#/#wgpu:matrix.org) [](https://matrix.to/#/#wgpu-users:matrix.org) [](https://github.com/gfx-rs/wgpu/actions) [](https://codecov.io/gh/gfx-rs/wgpu) `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. 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. ## Repo Overview The repository hosts the following libraries: - [](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 The following binaries: - `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. For an overview of all the components in the gfx-rs ecosystem, see [the big picture](./etc/big-picture.png). ### MSRV policy Minimum Supported Rust Version is **1.53**. It is enforced on CI (in "/.github/workflows/ci.txt") with `RUST_VERSION` variable. This version can only be upgraded in breaking releases. ## Getting Started ### Rust Rust examples can be found at `wgpu/examples`. You can run the examples with `cargo run --example name`. See the [list of examples](wgpu/examples). For detailed instructions, look at our [Get Started](https://github.com/gfx-rs/wgpu/wiki/Getting-Started) wiki. If you are looking for a wgpu tutorial, look at the following: - https://sotrh.github.io/learn-wgpu/ ### C/C++ To use wgpu in C/C++, you need [wgpu-native](https://github.com/gfx-rs/wgpu-native). ### 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). ## Community We have the Matrix space [](https://matrix.to/#/#Wgpu:matrix.org) with a few different rooms that form the wgpu community: - [](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. ## Wiki We have a [wiki](https://github.com/gfx-rs/wgpu/wiki) that serves as a knowledge base. ## Supported Platforms API | Windows | Linux & Android | macOS & iOS | ----- | ----------------------------- | ------------------ | ------------------ | Vulkan | :white_check_mark: | :white_check_mark: | | Metal | | | :white_check_mark: | DX12 | :white_check_mark: (W10 only) | | | DX11 | :construction: | | | GLES3 | | :ok: | | :white_check_mark: = First Class Support — :ok: = Best Effort Support — :construction: = Unsupported, but support in progress ## 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`). - `WGPU_POWER_PREFERENCE` with the power preference to choose when a specific adapter name isn't specified (`high` or `low`) When running the CTS, use the variables `DENO_WEBGPU_ADAPTER_NAME`, `DENO_WEBGPU_BACKEND`, `DENO_WEBGPU_POWER_PREFERENCE`. ## Testing 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: | Backend/Platform | Status | | ---------------- | ---------------------------------------------------------------------- | | DX12/Windows 10 | :heavy_check_mark: (over WARP) | | DX11/Windows 10 | :construction: (over WARP) | | Metal/MacOS | :x: (no CPU runner) | | Vulkan/Linux | :ok: ([cts hangs](https://github.com/gfx-rs/wgpu/issues/1974)) | | GLES/Linux | :x: ([egl fails init](https://github.com/gfx-rs/wgpu/issues/1551)) | ### Core Test Infrastructure All framework based examples have image comparison tested against their screenshot. To run the test suite on the default device: ``` cargo test --no-fail-fast ``` There's logic which can automatically run the tests once for each adapter on your system. ``` cargo run --bin wgpu-info -- cargo test --no-fail-fast ``` Then to run an example's image comparison tests, run: ``` cargo test --example --no-fail-fast ``` Or run a part of the integration test suite: ``` cargo test -p wgpu -- ``` If you are a user and want a way to help contribute to wgpu, we always need more help writing test cases. ### 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 cargo run --manifest-path ../cts_runner/Cargo.toml --frozen -- ./tools/run_deno --verbose "" ``` 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:*). The list of currently enabled CTS tests can be found [here](./cts_runner/test.lst). ## Coordinate Systems wgpu uses the coordinate systems of D3D and Metal: Render | Depth | Texture -------|-------|--------  |  |