gfx-rs / wgpu

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 the [WebGPU standard][webgpu], but is a fully native Rust library. It serves as the core of the WebGPU integration in Firefox, Servo, and Deno. Getting Started See our examples online at . You can see the Rust sources at examples and run them directly with . Learning If you are new to and graphics programming, we recommend starting with [Learn Wgpu]. Additionally, [WebGPU Fundamentals] is a tutorial for WebGPU which is very similar to our API, minus differences between Rust and Javascript. [Learn Wgpu]: https://sotrh.github.io/learn-wgpu/ [WebGPU Fundamentals]: https://webgpufundamentals.org/ Wiki We have a wiki which has information on useful architecture patterns, debugging tips, and more getting started information. Need Help? Want to Contribute? The wgpu community uses Matrix and Discord to discuss. • - discussion of wgpu's development. • - discussion of using the library and the surrounding ecosystem. • - Dedicated support channel on the Rust Gamedev Discord. Other Languages To use wgpu in C or dozens of other languages, look at wgpu-native. These are C bindings to wgpu and has an up-to-date list of libraries bringing support to other languages. [Learn WebGPU (for C++)] is a good resource for learning how to use wgpu-native from C++. [Learn WebGPU (for C++)]: https://eliemichel.github.io/LearnWebGPU/ [webgpu]: https://gpuweb.github.io/gpuweb/ Quick Links | Docs | Examples | Changelog | |:---------------------:|:-------------------------:|:-----------------------:| | [v28][rel-docs] | [v28][rel-examples] | [v28][rel-change] | | [ ][trunk-docs] | [ ][trunk-examples] | [ ][trunk-change] | Contributors are welcome! See [CONTRIBUTING.md][contrib] for more information. [rel-docs]: https://docs.rs/wgpu/ [rel-examples]: https://github.com/gfx-rs/wgpu/tree/v28/examples#readme [rel-change]: https://github.com/gfx-rs/wgpu/releases [trunk-docs]: https://wgpu.rs/doc/wgpu/ [trunk-examples]: https://github.com/gfx-rs/wgpu/tree/trunk/examples#readme [trunk-change]: https://github.com/gfx-rs/wgpu/blob/trunk/CHANGELOG.md#unreleased [contrib]: CONTRIBUTING.md Supported Platforms | API | Windows | Linux/Android | macOS/iOS | Web (wasm) | | ------ | ------------------ | ------------------ | ------------------ | ------------------ | | Vulkan | ✅ | ✅ | 🌋 | | | Metal | | | ✅ | | | DX12 | ✅ | | | | | OpenGL | 🆗 (GL 3.3+) | 🆗 (GL ES 3.0+) | 📐 | 🆗 (WebGL2) | | WebGPU | | | | ✅ | ✅ = First Class Support 🆗 = Downlevel/Best Effort Support 📐 = Requires the ANGLE translation layer (GL ES 3.0 only) 🌋 = Requires the MoltenVK translation layer 🛠️ = Unsupported, though open to contributions Environment Variables Testing, examples, and methods use a standardized set of environment variables to control wgpu's behavior. • with a comma-separated list of the backends you want to use ( , , , or ). • with a case-insensitive substring of the name of the adapter you want to use (ex. will match ). • with the DX12 shader compiler you wish to use ( , , or ). Note that requires (min v1.8.2502) to be in the working directory, and requires the crate feature to be enabled. Otherwise, it will fall back to . See the documentation for more environment variables. When running the CTS, use the variables , , , and . Repo Overview For an overview of all the components in the gfx-rs ecosystem, see the big picture. MSRV policy TL;DR: If you're using , our MSRV is **1.87**. If you're running our tests or examples, our MSRV is **1.93**. We will avoid bumping the MSRV of without good reason, and such a change is considered breaking. Specific Details Due to complex dependants, we have three MSRV policies: • 's MSRV is **1.87** • (and hence , , and )'s MSRV is **1.87**. • The rest of the workspace has an MSRV of **1.93**. It is enforced on CI (in "/.github/workflows/ci.yml") with the , , and variables, respectively. This version can only be upgraded in breaking releases, though we release a breaking version every three months. The following rules apply: • The crate should never require an MSRV ahead of Firefox's MSRV for nightly builds, as determined by the value of in [ ][moz-msrv]. • The crate should never require an MSRV ahead of Servo's MSRV, as determined by the value of their rust-version declaration in [ ][servo-msrv] • The repository MSRV should never require an MSRV higher than . For example, if stable is at 1.97, the repository MSRV should be no higher than 1.94. This is to allow people who are using a decently-updated OS-provided rust to be able to build our repository. Consider cross checking with [NixOS][nixos-msrv], though this is not required. [moz-msrv]: https://searchfox.org/mozilla-central/source/python/mozboot/mozboot/util.py [servo-msrv]: https://github.com/servo/servo/blob/main/Cargo.toml#L23 [nixos-msrv]: https://search.nixos.org/packages?show=rustc Testing and Environment Variables Information about testing, including where tests of various kinds live, and how to run the tests. Tracking the WebGPU and WGSL draft specifications The 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 crate and the version of WGSL it implements will likely differ from what is specified, as the implementation catches up. Exactly which WGSL features supports depends on how you are using it: • When running as native code, uses [Naga][naga] to translate WGSL code into the shading language of your platform's native GPU API. Naga is working on catching up to the WGSL specification, with [bugs][naga bugs] tracking various issues, but there is no concise summary of diffe…