* Initial commit * Other initial changes * Updated shader snapshots * Added new HLSL limitation * Moved error to global variable error * Added docs to per_primitive * Added a little bit more docs here and there in IR * Adding validation to ensure that task shaders have a task payload * Updated spec to reflect the change to payload variables * Updated the mesh shading spec because it was goofy * some doc tweaks * Tried to clarify docs a little * Tried to update spec * Removed a warning * Addressed comment about docs mistake * Review in progress - Extensive revisions to `docs/api-specs/mesh_shading.md`. - Doc comments. - Ensure `Module` stays at the bottom of `ir/mod.rs`. - Avoid a clone. - Rename some arguments to be more specific. - Minor readability tweaks. * mesh_shading.md: more tweaks * Ran cargo fmt * Small tweaks * [naga] Move definition of `ShaderStage::compute_like` to `proc`. Move the definition of `naga::ShaderStage::compute_like` from `naga::ir` into `naga::proc`. We generally want ot keep methods out of `naga::ir`, since the IR itself is complicated enough already. * Replace TODO comment with followup issue. * Update analyzer.rs Co-authored-by: Jim Blandy <jimb@red-bean.com> * Removed stuff in accordance with Jim's recommendation * minor changes for readability * Pull mesh shader output type validation out into its own function. * doc fixes * remove duplicated task payload validation * Quick little changes * Another quick fix * Quick fix * Removed unnecessary TODO statement * A * Tried to be more expressive * Made functions only work in mesh shader entry points * Various validation fix attempts * Undid capabilities resize * WGSL PR is up :) * Update naga/src/ir/mod.rs Co-authored-by: Erich Gubler <erichdongubler@gmail.com> * Update naga/src/front/wgsl/error.rs Co-authored-by: Erich Gubler <erichdongubler@gmail.com> * Update naga/src/ir/mod.rs Co-authored-by: Erich Gubler <erichdongubler@gmail.com> * Other Erich suggestion * Updated docs & validation for some builtins * Added some docs & removed contentious "// TODO" * Fixed bad validation, formatted mesh shader wgsl * Rewrote the IR and parser significantly * Improved validation slightly, remvoed obselete crap, fixed bug in compaction, made clippy happy * Added changelog entry * Made parser respect enable extension * Updated mesh shader spec * Cleaned up the mesh shader analyzer function * Updated changelog * Updated validation from spv-write * Slight tweaks * Added capabilitiy thing blah blah blah * Fixed compaction & clean stuff up * Fixed compaction and such pt 2 * Paved the way for primitive-index stuff * Little bit of cleanup * Added new features/capabilities for point primitives and added snapshots for stuff * Updated spec to rename something * Updated some limits stuff * Made some improvements * Fixed doctests & webgpu stuff * Fixed experimental features stuff * A little more scaffolding * Added some initial validation * Added per primitive validation * Improved per primitive validation * Added some more validation * Fixed primitive index validation * Updated the spec * Updated comments on some limits * Made some fixes * Fixed new validation rule for task payload size * Update wgpu-core/src/validation.rs Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com> * Update wgpu-core/src/validation.rs Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com> * A small tweak to mesh shader recommended minimums * Addressed 2 comments * A few more comments addressed with limits * Addressed more comments * Update wgpu-core/src/validation.rs Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com> * Split up error * Addressed another comment by changing workgroup size validation * Final comment addressed * Update wgpu-info/src/human.rs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update wgpu-core/src/validation.rs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update wgpu-info/src/human.rs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Fixed compilation and added some new test functions --------- Co-authored-by: SupaMaggie70Incorporated <85136135+SupaMaggie70Incorporated@users.noreply.github.com> Co-authored-by: Jim Blandy <jimb@red-bean.com> Co-authored-by: Erich Gubler <erichdongubler@gmail.com> Co-authored-by: Connor Fitzgerald <connorwadefitzgerald@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
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, 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 https://wgpu.rs/examples/. You can see the Rust sources at examples and run them directly with cargo run --bin wgpu-examples <example>.
Learning wgpu
If you are new to wgpu 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.
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++.
Quick Links
| Docs | Examples | Changelog |
|---|---|---|
| v27 | v27 | v27 |
trunk |
trunk |
trunk |
Contributors are welcome! See CONTRIBUTING.md for more information.
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 ::from_env() methods use a standardized set of environment variables to control wgpu's behavior.
WGPU_BACKENDwith a comma-separated list of the backends you want to use (vulkan,metal,dx12, orgl).WGPU_ADAPTER_NAMEwith a case-insensitive substring of the name of the adapter you want to use (ex.1080will matchNVIDIA GeForce 1080ti).WGPU_DX12_COMPILERwith the DX12 shader compiler you wish to use (dxc,static-dxc, orfxc). Note thatdxcrequiresdxcompiler.dll(min v1.8.2502) to be in the working directory, andstatic-dxcrequires thestatic-dxccrate feature to be enabled. Otherwise, it will fall back tofxc.
See the documentation for more environment variables.
When running the CTS, use the variables DENO_WEBGPU_ADAPTER_NAME, DENO_WEBGPU_BACKEND, DENO_WEBGPU_POWER_PREFERENCE.
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 wgpu, our MSRV is 1.88.
Specific Details
Due to complex dependants, we have two MSRV policies:
naga,wgpu-core,wgpu-hal, andwgpu-types's MSRV is 1.82.- The rest of the workspace has an MSRV of 1.88.
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.
The naga, 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.
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 wgpu crate is meant to be an idiomatic Rust translation of the WebGPU API.
That specification, along with its shading language, WGSL,
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,
wgpuuses 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 tracking various issues, but there is no concise summary of differences from the specification. -
When running in a web browser (by compilation to WebAssembly) without the
"webgl"feature enabled,wgpurelies 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,wgpuuses Naga to translate WGSL programs into GLSL. This uses the same version of Naga as if you were runningwgpuas native code.