Cross-platform, safe, pure-rust graphics api.
Go to file
Aaron O'Mullan 6b60037a6a
chore(deno_webgpu): bump deno crates (#2405)
* chore(deno_webgpu): bump deno_core to 0.114.0

ca75752e5a dates back to Aug 30 2021, so is nearly 5 months old.

There are no breaking changes updating `deno_core` to `0.114.0` (released 6 days ago)

Also by using the crate directly from cargo we avoid cloning https://github.com/denoland/deno and https://github.com/denoland/deno_third_party which can be quite large so crate DL/install is much faster

* bump cts_runner's deno crates

* minor cts_runner fixes
2022-01-18 09:30:41 -05:00
.cargo Replace run-wasm-example.sh with aliased rust crate (xtask) 2022-01-04 23:56:47 -05:00
.github Test WebGPU backend with extra features 2022-01-06 12:48:40 -05:00
cts_runner chore(deno_webgpu): bump deno crates (#2405) 2022-01-18 09:30:41 -05:00
deno_webgpu chore(deno_webgpu): bump deno crates (#2405) 2022-01-18 09:30:41 -05:00
dummy Remove MPL 2.0 header in files 2021-06-19 21:06:08 +03:00
etc Adds background to images used in README 2021-09-15 14:02:58 +10:00
player Trace push/pop debug group on command encoder (#2294) 2021-12-15 17:48:48 +00:00
run-wasm Replace run-wasm-example.sh with aliased rust crate (xtask) 2022-01-04 23:56:47 -05:00
wgpu chore: bump naga to a1840be (#2401) 2022-01-17 19:17:31 -05:00
wgpu-core chore: bump naga to a1840be (#2401) 2022-01-17 19:17:31 -05:00
wgpu-hal chore: bump naga to a1840be (#2401) 2022-01-17 19:17:31 -05:00
wgpu-info Test WebGPU backend with extra features 2022-01-06 12:48:40 -05:00
wgpu-types add AddressMode::ClampToZero (#2364) 2022-01-15 05:16:35 +00:00
.gitattributes [rs] Demonstrate obj loading in the skybox example 2021-02-12 22:33:17 -05:00
.gitignore Bring back the root lockfile 2021-10-04 08:47:13 -04:00
Cargo.lock chore: bump naga to a1840be (#2401) 2022-01-17 19:17:31 -05:00
Cargo.toml Replace run-wasm-example.sh with aliased rust crate (xtask) 2022-01-04 23:56:47 -05:00
CHANGELOG.md Release 0.12 2021-12-18 12:36:41 -05:00
LICENSE.APACHE Relicense to MIT/Apache 2021-06-18 13:40:31 -04:00
LICENSE.MIT Relicense to MIT/Apache 2021-06-18 13:40:31 -04:00
logo.png Adds white background to main logo for better visibility on black backgrounds 2021-09-27 10:50:30 -02:30
README.md Fix link to angle project 2021-12-10 10:25:32 -05:00
rustfmt.toml Rustfmt stable pass 2020-04-06 08:55:39 -04:00

wgpu

Matrix Space Dev Matrix  User Matrix Build Status codecov.io

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. It serves as the core of the WebGPU integration in Firefox, Servo, and Deno.

Repo Overview

The repository hosts the following libraries:

  • Crates.io docs.rs - User facing Rust API.
  • Crates.io docs.rs - Internal WebGPU implementation.
  • Crates.io docs.rs - Internal unsafe GPU API abstraction layer.
  • Crates.io docs.rs - Rust types shared between all crates.
  • Crates.io - 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.

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. For detailed instructions, look at our Get Started wiki.

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

C/C++

To use wgpu in C/C++, you need 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.

Community

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

  • Dev Matrix - discussion of the library's development.
  • User Matrix - discussion of using the library and the surrounding ecosystem.
  • Random Matrix - discussion of everything else.

Wiki

We have a wiki that serves as a knowledge base.

Supported Platforms

API Windows Linux & Android macOS & iOS
Vulkan
Metal
DX12 (W10 only)
DX11 🛠️
GLES3 🆗
Angle 🆗 🆗 🛠️

= First Class Support — 🆗 = Best Effort Support — 🛠️ = Unsupported, but support in progress

Angle

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 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. These binaries can be downloaded from gfbuild-angle artifacts.

On Windows, you generally need to copy them into the working directory, or in the same directory as the executable. On Linux, you can point to them using LD_LIBRARY_PATH environment.

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 ✔️ (over WARP)
DX11/Windows 10 🚧 (over WARP)
Metal/MacOS (no CPU runner)
Vulkan/Linux 🆗 (cts hangs)
GLES/Linux (egl fails init)

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 <example-name> --no-fail-fast

Or run a part of the integration test suite:

cargo test -p wgpu -- <name-of-test>

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 -- ./tools/run_deno --verbose "<test string>"

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

The list of currently enabled CTS tests can be found here.

Coordinate Systems

wgpu uses the coordinate systems of D3D and Metal:

Render Depth Texture
render_coordinates depth_coordinates texture_coordinates