v24.0.0

2025-01-16T16:01:29Z

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.

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.

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.

`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.

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.

`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.

- let instance = wgpu::Instance::new(instance_desc);
+ let instance = wgpu::Instance::new(&instance_desc);

By @Wumpf in #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.

- 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

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.

- 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

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 #4369) this snippet would emit a uniformity error:

@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:

// 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 #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 #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., #3135) before we took significant effort to fix this (tracked in #6496).

By @ErichDonGubler in #6456, #6148, #6533, #6353, #6537.

New Features

Naga

Support atomic operations on fields of global structs in the SPIR-V frontend. By @schell in #6693.
Clean up tests for atomic operations support in SPIR-V frontend. By @schell in #6692
Fix an issue where naga CLI would incorrectly skip the first positional argument when --stdin-file-path was specified. By @ErichDonGubler in #6480.
Fix textureNumLevels in the GLSL backend. By @magcius in #6483.
Support 64-bit hex literals and unary operations in constants #6616.
Implement quantizeToF16() for WGSL frontend, and WGSL, SPIR-V, HLSL, MSL, and GLSL backends. By @jamienicol in #6519.
Add support for GLSL usampler* and isampler*. By @DavidPeicho in #6513.
Expose Ray Query flags as constants in WGSL. Implement candidate intersections. By @kvark in #5429
Add new vertex formats ({U,S}{int,norm}{8,16}, Float16 and Unorm8x4Bgra). By @nolanderc in #6632
Allow for override-expressions in workgroup_size. By @kentslaney in #6635.
Add support for OpAtomicCompareExchange in SPIR-V frontend. By @schell in #6590.
Implement type inference for abstract arguments to user-defined functions. By @jamienicol in #6577.
Allow for override-expressions in array sizes. By @kentslaney in #6654.

General

Add unified documentation for ray-tracing. By @Vecvec in #6747
Return submission index in map_async and on_submitted_work_done to track down completion of async callbacks. By @eliemichel in #6360.
Move raytracing alignments into HAL instead of in core. By @Vecvec in #6563.
Allow for statically linking DXC rather than including separate .dll files. By @DouglasDwyer in #6574.
DeviceType and AdapterInfo now impl Hash by @cwfitzgerald in #6868
Add build support for Apple Vision Pro. By @guusw in #6611.
Add wgsl_language_features for obtaining available WGSL language feature by @sagudev in #6814
Image atomic support in shaders. By @atlv24 in #6706
64 bit image atomic support in shaders. By @atlv24 in #5537
Add no_std support to wgpu-types. By @bushrat011899 in #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.

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.
Add build support for Apple Vision Pro. By @guusw in #6611.
Add raw_handle method to access raw Metal textures in #6894.

D3D12

Support DXR (DirectX Ray-tracing) in wgpu-hal. By @Vecvec in #6777

Changes

Naga

Show types of LHS and RHS in binary operation type mismatch errors. By @ErichDonGubler in #6450.
The GLSL parser now uses less expressions for function calls. By @magcius in #6604.
Add a note to help with a common syntax error case for global diagnostic filter directives. By @e-hat in #6718
Change arithmetic operations between two i32 variables to wrap on overflow to match WGSL spec. By @matthew-wong1 in #6835.
Add directives to suggestions in error message for parsing global items. By @e-hat in #6723.
Automatic conversion for override initializers. By @sagudev in 6920

General

Align Storage Access enums to the webgpu spec. By @atlv24 in #6642
Make Surface::as_hal take an immutable reference to the surface. By @jerzywilczek in #9999
Add actual sample type to CreateBindGroupError::InvalidTextureSampleType error message. By @ErichDonGubler in #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.
Surface::configure and Surface::get_current_texture are no longer fatal. By @alokedesai in #6253
Rename BlasTriangleGeometry::index_buffer_offset to BlasTriangleGeometry::first_index. By @Vecvec in #6873

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.

Vulkan

Add a cache for samplers, deduplicating any samplers, allowing more programs to stay within the global sampler limit. By @cwfitzgerald in #6847

HAL

Replace usage: Range<T>, for BufferUses, TextureUses, and AccelerationStructureBarrier with a new StateTransition<T>. By @atlv24 in #6703
Change the DropCallback API to use FnOnce instead of FnMut. By @jerzywilczek in #6482

Bug Fixes

General

Handle query set creation failure as an internal error that loses the Device, rather than panicking. By @ErichDonGubler in #6505.
Ensure that Features::TIMESTAMP_QUERY is set when using timestamp writes in render and compute passes. By @ErichDonGubler in #6497.
Check for device mismatches when beginning render and compute passes. By @ErichDonGubler in #6497.
Lower QUERY_SET_MAX_QUERIES (and enforced limits) from 8192 to 4096 to match WebGPU spec. By @ErichDonGubler in #6525.
Allow non-filterable float on texture bindings never used with samplers when using a derived bind group layout. By @ErichDonGubler in #6531.
Replace potentially unsound usage of PreHashedMap with FastHashMap. By @jamienicol in #6541.
Add missing validation for timestamp writes in compute and render passes. By @ErichDonGubler in #6578, #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.
Fix panic when dropping Device on some environments. By @Dinnerbone in #6681.
Reduced the overhead of command buffer validation. By @nical in #6721.
Set index type to NONE in get_acceleration_structure_build_sizes. By @Vecvec in #6802.
Fix wgpu-info not showing dx12 adapters. By @Wumpf in #6844.
Use transform_buffer_offset when initialising transform_buffer. By @Vecvec in #6864.

Naga

Fix crash when a texture argument is missing. By @aedm in #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.
Fix an error in template list matching >= in a<b>=c. By @kentslaney in #6898.
Correctly validate handles in override-sized array types. By @jimblandy in #6882.
Clean up validation of Statement::ImageStore. By @jimblandy in #6729.
In compaction, avoid cloning the type arena. By @jimblandy in #6790
In validation, forbid cycles between global expressions and types. By @jimblandy in #6800
Allow abstract scalars in modf and frexp results. By @jimblandy in #6821
In the WGSL front end, apply automatic conversions to values being assigned. By @jimblandy in #6822

Vulkan

Allocate descriptors for acceleration structures. By @Vecvec in #6861.
max_color_attachment_bytes_per_sample is now correctly set to 128. By @cwfitzgerald in #6866

D3D12

Fix no longer showing software rasterizer adapters. By @Wumpf in #6843.
max_color_attachment_bytes_per_sample is now correctly set to 128. By @cwfitzgerald in #6866

Examples

Add multiple render targets example. By @kaphula in #5297

Release notes from wgpu

wgpu-hal-v24.0.2

wgpu-core-v24.0.2

v24.0.2

Bug Fixes

wgpu-v24.0.1

v24.0.1

Bug Fixes

v24.0.0

Major changes

Refactored Dispatch Between wgpu-core and webgpu

Most objects in wgpu are now Clone

Render and Compute Passes Now Properly Enforce Their Lifetime

Bindless (binding_array) Grew More Capabilities

Device::create_shader_module_unchecked Renamed and Now Has Configuration Options

wgpu::Instance::new now takes InstanceDescriptor by reference

Environment Variable Handling Overhaul

Backend-specific instance options are now in separate structs

The diagnostic(…); directive is now supported in WGSL

New Features

Naga

General

Vulkan

Metal

D3D12

Changes

Naga

General

D3D12

Vulkan

HAL

Bug Fixes

General

Naga

Vulkan

D3D12

Examples

v23.1.0 (2024-12-16)

New Features

Naga

naga-v23.1.0

23.0.1 (2024-11-25)

Bug fixes

General

Metal

Vulkan

wgpu-hal-v23.0.1

Refactored Dispatch Between `wgpu-core` and `webgpu`

Most objects in `wgpu` are now `Clone`

Bindless (`binding_array`) Grew More Capabilities

`Device::create_shader_module_unchecked` Renamed and Now Has Configuration Options

`wgpu::Instance::new` now takes `InstanceDescriptor` by reference

The `diagnostic(…);` directive is now supported in WGSL