* 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_hal: a cross-platform unsafe graphics abstraction
This crate defines a set of traits abstracting over modern graphics APIs, with implementations ("backends") for Vulkan, Metal, Direct3D, and GL.
wgpu_hal is a spiritual successor to
gfx-hal, but with reduced scope, and
oriented towards WebGPU implementation goals. It has no overhead for
validation or tracking, and the API translation overhead is kept to the bare
minimum by the design of WebGPU. This API can be used for resource-demanding
applications and engines.
The wgpu_hal crate's main design choices:
-
Our traits are meant to be portable: proper use should get equivalent results regardless of the backend.
-
Our traits' contracts are unsafe: implementations perform minimal validation, if any, and incorrect use will often cause undefined behavior. This allows us to minimize the overhead we impose over the underlying graphics system. If you need safety, the
wgpu-corecrate provides a safe API for drivingwgpu_hal, implementing all necessary validation, resource state tracking, and so on. (Note thatwgpu-coreis designed for use via FFI; thewgpucrate provides more idiomatic Rust bindings forwgpu-core.) Or, you can do your own validation. -
In the same vein, returned errors only cover cases the user can't anticipate, like running out of memory or losing the device. Any errors that the user could reasonably anticipate are their responsibility to avoid. For example,
wgpu_halreturns no error for mapping a buffer that's not mappable: as the buffer creator, the user should already know if they can map it. -
We use static dispatch. The traits are not generally object-safe. You must select a specific backend type like
vulkan::Apiormetal::Api, and then use that according to the main traits, or call backend-specific methods. -
We use idiomatic Rust parameter passing, taking objects by reference, returning them by value, and so on, unlike
wgpu-core, which refers to objects by ID. -
We map buffer contents persistently. This means that the buffer can remain mapped on the CPU while the GPU reads or writes to it. You must explicitly indicate when data might need to be transferred between CPU and GPU, if
wgpu_halindicates that the mapping is not coherent (that is, automatically synchronized between the two devices). -
You must record explicit barriers between different usages of a resource. For example, if a buffer is written to by a compute shader, and then used as and index buffer to a draw call, you must use [
CommandEncoder::transition_buffers] between those two operations. -
Pipeline layouts are explicitly specified when setting bind group. Incompatible layouts disturb groups bound at higher indices.
-
The API accepts collections as iterators, to avoid forcing the user to store data in particular containers. The implementation doesn't guarantee that any of the iterators are drained, unless stated otherwise by the function documentation. For this reason, we recommend that iterators don't do any mutating work.
Unfortunately, wgpu_hal's safety requirements are not fully documented.
Ideally, all trait methods would have doc comments setting out the
requirements users must meet to ensure correct and portable behavior. If you
are aware of a specific requirement that a backend imposes that is not
ensured by the traits' documented rules, please file an issue. Or, if you are
a capable technical writer, please file a pull request!
Primary backends
The wgpu_hal crate has full-featured backends implemented on the following
platform graphics APIs:
-
Vulkan, available on Linux, Android, and Windows, using the
ashcrate's Vulkan bindings. It's also available on macOS, if you install MoltenVK. -
Metal on macOS, using the
metalcrate's bindings. -
Direct3D 12 on Windows, using the
windowscrate's bindings.
Secondary backends
The wgpu_hal crate has a partial implementation based on the following
platform graphics API:
- The GL backend is available anywhere OpenGL, OpenGL ES, or WebGL are
available. See the
glesmodule documentation for details.
You can see what capabilities an adapter is missing by checking the
DownlevelCapabilities in [ExposedAdapter::capabilities], available
from [Instance::enumerate_adapters].
The API is generally designed to fit the primary backends better than the secondary backends, so the latter may impose more overhead.
Debugging
Most of the information on the wiki Debugging wgpu Applications
page still applies to this API, with the exception of API tracing/replay
functionality, which is only available in wgpu-core.