Major changes
Refactored Dispatch Between `wgpu-core` and `webgpu`
The crate `wgpu` has two different "backends", one which targets webgpu in the browser, one which targets `wgpu_core` on native platforms and webgl. This was previously very difficult to traverse and add new features to. The entire system was refactored to make it simpler. Additionally the new system has zero overhead if there is only one "backend" in use. You can see the new system in action by using go-to-definition on any wgpu functions in your IDE.
By cwfitzgerald in [6619](https://github.com/gfx-rs/wgpu/pull/6619).
Most objects in `wgpu` are now `Clone`
All types in the `wgpu` API are now `Clone`.
This is implemented with internal reference counting, so cloning for instance a `Buffer` does copies only the "handle" of the GPU buffer, not the underlying resource.
Previously, libraries using `wgpu` objects like `Device`, `Buffer` or `Texture` etc. often had to manually wrap them in a `Arc` to allow passing between libraries.
This caused a lot of friction since if one library wanted to use a `Buffer` by value, calling code had to give up ownership of the resource which may interfere with other subsystems.
Note that this also mimics how the WebGPU javascript API works where objects can be cloned and moved around freely.
By cwfitzgerald in [6665](https://github.com/gfx-rs/wgpu/pull/6665).
Render and Compute Passes Now Properly Enforce Their Lifetime
A regression introduced in 23.0.0 caused lifetimes of render and compute passes to be incorrectly enforced. While this is not
a soundness issue, the intent is to move an error from runtime to compile time. This issue has been fixed and restored to the 22.0.0 behavior.
Bindless (`binding_array`) Grew More Capabilities
- DX12 now supports `PARTIALLY_BOUND_BINDING_ARRAY` on Resource Binding Tier 3 Hardware. This is most D3D12 hardware [D3D12 Feature Table] for more information on what hardware supports this feature. By cwfitzgerald in [6734](https://github.com/gfx-rs/wgpu/pull/6734).
[D3D12 Feature Table]: https://d3d12infodb.boolka.dev/FeatureTable.html
`Device::create_shader_module_unchecked` Renamed and Now Has Configuration Options
`create_shader_module_unchecked` became `create_shader_module_trusted`.
This allows you to customize which exact checks are omitted so that you can get the correct balance of performance and safety for your use case. Calling the function is still unsafe, but now can be used to skip certain checks only on certain builds.
This also allows users to disable the workarounds in the `msl-out` backend to prevent the compiler from optimizing infinite loops. This can have a big impact on performance, but is not recommended for untrusted shaders.
diff
let desc: ShaderModuleDescriptor = include_wgsl!(...)
- let module = unsafe { device.create_shader_module_unchecked(desc) };
+ let module = unsafe { device.create_shader_module_trusted(desc, wgpu::ShaderRuntimeChecks::unchecked()) };
By cwfitzgerald and rudderbucky in [6662](https://github.com/gfx-rs/wgpu/pull/6662).
`wgpu::Instance::new` now takes `InstanceDescriptor` by reference
Previously `wgpu::Instance::new` took `InstanceDescriptor` by value (which is overall fairly uncommon in wgpu).
Furthermore, `InstanceDescriptor` is now cloneable.
diff
- let instance = wgpu::Instance::new(instance_desc);
+ let instance = wgpu::Instance::new(&instance_desc);
By wumpf in [6849](https://github.com/gfx-rs/wgpu/pull/6849).
Environment Variable Handling Overhaul
Previously how various bits of code handled reading settings from environment variables was inconsistent and unideomatic.
We have unified it to (`Type::from_env()` or `Type::from_env_or_default()`) and `Type::with_env` for all types.
diff
- wgpu::util::backend_bits_from_env()
+ wgpu::Backends::from_env()
- wgpu::util::power_preference_from_env()
+ wgpu::PowerPreference::from_env()
- wgpu::util::dx12_shader_compiler_from_env()
+ wgpu::Dx12Compiler::from_env()
- wgpu::util::gles_minor_version_from_env()
+ wgpu::Gles3MinorVersion::from_env()
- wgpu::util::instance_descriptor_from_env()
+ wgpu::InstanceDescriptor::from_env_or_default()
- wgpu::util::parse_backends_from_comma_list(&str)
+ wgpu::Backends::from_comma_list(&str)
By cwfitzgerald in [6895](https://github.com/gfx-rs/wgpu/pull/6895)
Backend-specific instance options are now in separate structs
In order to better facilitate growing more interesting backend options, we have put them into individual structs. This allows users to more easily understand what options can be defaulted and which they care about. All of these new structs implement `from_env()` and delegate to their respective `from_env()` methods.
diff
- let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
- backends: wgpu::Backends::all(),
- flags: wgpu::InstanceFlags::default(),
- dx12_shader_compiler: wgpu::Dx12Compiler::Dxc,
- gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
- });
+ let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
+ backends: wgpu::Backends::all(),
+ flags: wgpu::InstanceFlags::default(),
+ backend_options: wgpu::BackendOptions {
+ dx12: wgpu::Dx12BackendOptions {
+ shader_compiler: wgpu::Dx12ShaderCompiler::Dxc,
+ },
+ gl: wgpu::GlBackendOptions {
+ gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
+ },
+ },
+ });
If you do not need any of these options, or only need one backend's info use the `default()` impl to fill out the remaining feelds.
By cwfitzgerald in [6895](https://github.com/gfx-rs/wgpu/pull/6895)
The `diagnostic(…);` directive is now supported in WGSL
Naga now parses `diagnostic(…);` directives according to the WGSL spec. This allows users to control certain lints, similar to Rust's `allow`, `warn`, and `deny` attributes. For example, in standard WGSL (but, notably, not Naga yet—see <https://github.com/gfx-rs/wgpu/issues/4369>) this snippet would emit a uniformity error:
wgsl
group(0) binding(0) var s : sampler;
group(0) binding(2) var tex : texture_2d<f32>;
group(1) binding(0) var<storage, read> ro_buffer : array<f32, 4>;
fragment
fn main(builtin(position) p : vec4f) -> location(0) vec4f {
if ro_buffer[0] == 0 {
// Emits a derivative uniformity error during validation.
return textureSample(tex, s, vec2(0.,0.));
}
return vec4f(0.);
}
…but we can now silence it with the `off` severity level, like so:
wgsl
// Disable the diagnosic with this…
diagnostic(off, derivative_uniformity);
group(0) binding(0) var s : sampler;
group(0) binding(2) var tex : texture_2d<f32>;
group(1) binding(0) var<storage, read> ro_buffer : array<f32, 4>;
fragment
fn main(builtin(position) p : vec4f) -> location(0) vec4f {
if ro_buffer[0] == 0 {
// Look ma, no error!
return textureSample(tex, s, vec2(0.,0.));
}
return vec4f(0.);
}
There are some limitations to keep in mind with this new functionality:
- We support `diagnostic(…)` rules as `fn` attributes, but prioritization for rules in statement positions (i.e., `if (…) diagnostic(…) { … }` is unclear. If you are blocked by not being able to parse `diagnostic(…)` rules in statement positions, please let us know in <https://github.com/gfx-rs/wgpu/issues/5320>, so we can determine how to prioritize it!
- Standard WGSL specifies `error`, `warning`, `info`, and `off` severity levels. These are all technically usable now! A caveat, though: warning- and info-level are only emitted to `stderr` via the `log` façade, rather than being reported through a `Result::Err` in Naga or the `CompilationInfo` interface in `wgpu{,-core}`. This will require breaking changes in Naga to fix, and is being tracked by <https://github.com/gfx-rs/wgpu/issues/6458>.
- Not all lints can be controlled with `diagnostic(…)` rules. In fact, only the `derivative_uniformity` triggering rule exists in the WGSL standard. That said, Naga contributors are excited to see how this level of control unlocks a new ecosystem of configurable diagnostics.
- Finally, `diagnostic(…)` rules are not yet emitted in WGSL output. This means that `wgsl-in` → `wgsl-out` is currently a lossy process. We felt that it was important to unblock users who needed `diagnostic(…)` rules (i.e., <https://github.com/gfx-rs/wgpu/issues/3135>) before we took significant effort to fix this (tracked in <https://github.com/gfx-rs/wgpu/issues/6496>).
By ErichDonGubler in [6456](https://github.com/gfx-rs/wgpu/pull/6456), [#6148](https://github.com/gfx-rs/wgpu/pull/6148), [#6533](https://github.com/gfx-rs/wgpu/pull/6533), [#6353](https://github.com/gfx-rs/wgpu/pull/6353), [#6537](https://github.com/gfx-rs/wgpu/pull/6537).
New Features
Naga
- Support atomic operations on fields of global structs in the SPIR-V frontend. By schell in [6693](https://github.com/gfx-rs/wgpu/pull/6693).
- Clean up tests for atomic operations support in SPIR-V frontend. By schell in [6692](https://github.com/gfx-rs/wgpu/pull/6692)
- Fix an issue where `naga` CLI would incorrectly skip the first positional argument when `--stdin-file-path` was specified. By ErichDonGubler in [6480](https://github.com/gfx-rs/wgpu/pull/6480).
- Fix textureNumLevels in the GLSL backend. By magcius in [6483](https://github.com/gfx-rs/wgpu/pull/6483).
- Support 64-bit hex literals and unary operations in constants [6616](https://github.com/gfx-rs/wgpu/pull/6616).
- Implement `quantizeToF16()` for WGSL frontend, and WGSL, SPIR-V, HLSL, MSL, and GLSL backends. By jamienicol in [6519](https://github.com/gfx-rs/wgpu/pull/6519).
- Add support for GLSL `usampler*` and `isampler*`. By DavidPeicho in [6513](https://github.com/gfx-rs/wgpu/pull/6513).
- Expose Ray Query flags as constants in WGSL. Implement candidate intersections. By kvark in [5429](https://github.com/gfx-rs/wgpu/pull/5429)
- Add new vertex formats (`{U,S}{int,norm}{8,16}`, `Float16` and `Unorm8x4Bgra`). By nolanderc in [6632](https://github.com/gfx-rs/wgpu/pull/6632)
- Allow for override-expressions in `workgroup_size`. By KentSlaney in [6635](https://github.com/gfx-rs/wgpu/pull/6635).
- Add support for OpAtomicCompareExchange in SPIR-V frontend. By schell in [6590](https://github.com/gfx-rs/wgpu/pull/6590).
- Implement type inference for abstract arguments to user-defined functions. By jamienicol in [6577](https://github.com/gfx-rs/wgpu/pull/6577).
- Allow for override-expressions in array sizes. By KentSlaney in [6654](https://github.com/gfx-rs/wgpu/pull/6654).
- [`pointer_composite_access` WGSL language extension](https://www.w3.org/TR/WGSL/#language_extension-pointer_composite_access) is implemented. By sagudev in [6913](https://github.com/gfx-rs/wgpu/pull/6913)
General
- Add unified documentation for ray-tracing. By Vecvec in [6747](https://github.com/gfx-rs/wgpu/pull/6747)
- Return submission index in `map_async` and `on_submitted_work_done` to track down completion of async callbacks. By eliemichel in [6360](https://github.com/gfx-rs/wgpu/pull/6360).
- Move raytracing alignments into HAL instead of in core. By Vecvec in [6563](https://github.com/gfx-rs/wgpu/pull/6563).
- Allow for statically linking DXC rather than including separate `.dll` files. By DouglasDwyer in [6574](https://github.com/gfx-rs/wgpu/pull/6574).
- `DeviceType` and `AdapterInfo` now impl `Hash` by cwfitzgerald in [6868](https://github.com/gfx-rs/wgpu/pull/6868)
- Add build support for Apple Vision Pro. By guusw in [6611](https://github.com/gfx-rs/wgpu/pull/6611).
- Add `wgsl_language_features` for obtaining available WGSL language feature by sagudev in [6814](https://github.com/gfx-rs/wgpu/pull/6814)
- Image atomic support in shaders. By atlv24 in [6706](https://github.com/gfx-rs/wgpu/pull/6706)
- 64 bit image atomic support in shaders. By atlv24 in [5537](https://github.com/gfx-rs/wgpu/pull/5537)
- Add `no_std` support to `wgpu-types`. By bushrat011899 in [6892](https://github.com/gfx-rs/wgpu/pull/6892).
Vulkan
- Allow using some 32-bit floating-point atomic operations (load, store, add, sub, exchange) in shaders. It requires the extension `VK_EXT_shader_atomic_float`. By AsherJingkongChen in [6234](https://github.com/gfx-rs/wgpu/pull/6234).
Metal
- Allow using some 32-bit floating-point atomic operations (load, store, add, sub, exchange) in shaders. It requires Metal 3.0+ with Apple 7, 8, 9 or Mac 2. By AsherJingkongChen in [6234](https://github.com/gfx-rs/wgpu/pull/6234).
- Add build support for Apple Vision Pro. By guusw in [6611](https://github.com/gfx-rs/wgpu/pull/6611).
- Add `raw_handle` method to access raw Metal textures in [6894](https://github.com/gfx-rs/wgpu/pull/6894).
D3D12
- Support DXR (DirectX Ray-tracing) in wgpu-hal. By Vecvec in [6777](https://github.com/gfx-rs/wgpu/pull/6777)
Changes
Naga
- Show types of LHS and RHS in binary operation type mismatch errors. By ErichDonGubler in [6450](https://github.com/gfx-rs/wgpu/pull/6450).
- The GLSL parser now uses less expressions for function calls. By magcius in [6604](https://github.com/gfx-rs/wgpu/pull/6604).
- Add a note to help with a common syntax error case for global diagnostic filter directives. By e-hat in [6718](https://github.com/gfx-rs/wgpu/pull/6718)
- Change arithmetic operations between two i32 variables to wrap on overflow to match WGSL spec. By matthew-wong1 in [6835](https://github.com/gfx-rs/wgpu/pull/6835).
- Add directives to suggestions in error message for parsing global items. By e-hat in [6723](https://github.com/gfx-rs/wgpu/pull/6723).
- Automatic conversion for `override` initializers. By sagudev in [6920](https://github.com/gfx-rs/wgpu/pull/6920)
General
- Align Storage Access enums to the webgpu spec. By atlv24 in [6642](https://github.com/gfx-rs/wgpu/pull/6642)
- Make `Surface::as_hal` take an immutable reference to the surface. By jerzywilczek in [9999](https://github.com/gfx-rs/wgpu/pull/9999)
- Add actual sample type to `CreateBindGroupError::InvalidTextureSampleType` error message. By ErichDonGubler in [6530](https://github.com/gfx-rs/wgpu/pull/6530).
- Improve binding error to give a clearer message when there is a mismatch between resource binding as it is in the shader and as it is in the binding layout. By eliemichel in [6553](https://github.com/gfx-rs/wgpu/pull/6553).
- `Surface::configure` and `Surface::get_current_texture` are no longer fatal. By alokedesai in [6253](https://github.com/gfx-rs/wgpu/pull/6253)
- Rename `BlasTriangleGeometry::index_buffer_offset` to `BlasTriangleGeometry::first_index`. By Vecvec in [6873](https://github.com/gfx-rs/wgpu/pull/6873/files)
D3D12
- Avoid using FXC as fallback when the DXC container was passed at instance creation. Paths to `dxcompiler.dll` & `dxil.dll` are also now required. By teoxoy in [6643](https://github.com/gfx-rs/wgpu/pull/6643).
Vulkan
- Add a cache for samplers, deduplicating any samplers, allowing more programs to stay within the global sampler limit. By cwfitzgerald in [6847](https://github.com/gfx-rs/wgpu/pull/6847)
HAL
- Replace `usage: Range<T>`, for `BufferUses`, `TextureUses`, and `AccelerationStructureBarrier` with a new `StateTransition<T>`. By atlv24 in [6703](https://github.com/gfx-rs/wgpu/pull/6703)
- Change the `DropCallback` API to use `FnOnce` instead of `FnMut`. By jerzywilczek in [6482](https://github.com/gfx-rs/wgpu/pull/6482)
Bug Fixes
General
- Handle query set creation failure as an internal error that loses the `Device`, rather than panicking. By ErichDonGubler in [6505](https://github.com/gfx-rs/wgpu/pull/6505).
- Ensure that `Features::TIMESTAMP_QUERY` is set when using timestamp writes in render and compute passes. By ErichDonGubler in [6497](https://github.com/gfx-rs/wgpu/pull/6497).
- Check for device mismatches when beginning render and compute passes. By ErichDonGubler in [6497](https://github.com/gfx-rs/wgpu/pull/6497).
- Lower `QUERY_SET_MAX_QUERIES` (and enforced limits) from 8192 to 4096 to match WebGPU spec. By ErichDonGubler in [6525](https://github.com/gfx-rs/wgpu/pull/6525).
- Allow non-filterable float on texture bindings never used with samplers when using a derived bind group layout. By ErichDonGubler in [6531](https://github.com/gfx-rs/wgpu/pull/6531/).
- Replace potentially unsound usage of `PreHashedMap` with `FastHashMap`. By jamienicol in [6541](https://github.com/gfx-rs/wgpu/pull/6541).
- Add missing validation for timestamp writes in compute and render passes. By ErichDonGubler in [6578](https://github.com/gfx-rs/wgpu/pull/6578), [#6583](https://github.com/gfx-rs/wgpu/pull/6583).
- Check the status of the `TIMESTAMP_QUERY` feature before other validation.
- Check that indices are in-bounds for the query set.
- Check that begin and end indices are not equal.
- Check that at least one index is specified.
- Reject destroyed buffers in query set resolution. By ErichDonGubler in [6579](https://github.com/gfx-rs/wgpu/pull/6579).
- Fix panic when dropping `Device` on some environments. By Dinnerbone in [6681](https://github.com/gfx-rs/wgpu/pull/6681).
- Reduced the overhead of command buffer validation. By nical in [6721](https://github.com/gfx-rs/wgpu/pull/6721).
- Set index type to NONE in `get_acceleration_structure_build_sizes`. By Vecvec in [6802](https://github.com/gfx-rs/wgpu/pull/6802).
- Fix `wgpu-info` not showing dx12 adapters. By wumpf in [6844](https://github.com/gfx-rs/wgpu/pull/6844).
- Use `transform_buffer_offset` when initialising `transform_buffer`. By Vecvec in [6864](https://github.com/gfx-rs/wgpu/pull/6864).
Naga
- Fix crash when a texture argument is missing. By aedm in [6486](https://github.com/gfx-rs/wgpu/pull/6486)
- Emit an error in constant evaluation, rather than crash, in certain cases where `vecN` constructors have less than N arguments. By ErichDonGubler in [6508](https://github.com/gfx-rs/wgpu/pull/6508).
- Fix an error in template list matching `>=` in `a<b>=c`. By KentSlaney in [6898](https://github.com/gfx-rs/wgpu/pull/6898).
- Correctly validate handles in override-sized array types. By jimblandy in [6882](https://github.com/gfx-rs/wgpu/pull/6882).
- Clean up validation of `Statement::ImageStore`. By jimblandy in [6729](https://github.com/gfx-rs/wgpu-pull/6729).
- In compaction, avoid cloning the type arena. By jimblandy in [6790](https://github.com/gfx-rs/wgpu-pull/6790)
- In validation, forbid cycles between global expressions and types. By jimblandy in [6800](https://github.com/gfx-rs/wgpu-pull/6800)
- Allow abstract scalars in modf and frexp results. By jimblandy in [6821](https://github.com/gfx-rs/wgpu-pull/6821)
- In the WGSL front end, apply automatic conversions to values being assigned. By jimblandy in [6822](https://github.com/gfx-rs/wgpu-pull/6822)
- Fix a leak by ensuring that types that depend on expressions are correctly compacted. By KentSlaney in [6934](https://github.com/gfx-rs/wgpu/pull/6934).
Vulkan
- Allocate descriptors for acceleration structures. By Vecvec in [6861](https://github.com/gfx-rs/wgpu/pull/6861).
- `max_color_attachment_bytes_per_sample` is now correctly set to 128. By cwfitzgerald in [6866](https://github.com/gfx-rs/wgpu/pull/6866)
D3D12
- Fix no longer showing software rasterizer adapters. By wumpf in [6843](https://github.com/gfx-rs/wgpu/pull/6843).
- `max_color_attachment_bytes_per_sample` is now correctly set to 128. By cwfitzgerald in [6866](https://github.com/gfx-rs/wgpu/pull/6866)
Examples
- Add multiple render targets example. By kaphula in [5297](https://github.com/gfx-rs/wgpu/pull/5313)
Testing
- Tests the early returns in the acceleration structure build calls with empty calls. By Vecvec in [6651](https://github.com/gfx-rs/wgpu/pull/6651).