v25.0.0

Major Features

Hashmaps Removed from APIs

Both PipelineCompilationOptions::constants and ShaderSource::Glsl::defines now take
slices of key-value pairs instead of hashmaps. This is to prepare for no_std
support and allow us to keep which hashmap hasher and such as implementation details. It
also allows more easily creating these structures inline.

By @cwfitzgerald in #7133

All Backends Now Have Features

Previously, the vulkan and gles backends were non-optional on windows, linux, and android and there was no way to disable them. We have now figured out how to properly make them disablable! Additionally, if you turn on the webgl feature, you will only get the GLES backend on WebAssembly, it won't leak into native builds, like previously it might have.

Warning

If you use wgpu with default-features = false and you want to retain the vulkan and gles backends, you will need to add them to your feature list.

-wgpu = { version = "24", default-features = false, features = ["metal", "wgsl", "webgl"] }
+wgpu = { version = "25", default-features = false, features = ["metal", "wgsl", "webgl", "vulkan", "gles"] }

By @cwfitzgerald in #7076.

device.poll Api Reworked

This release reworked the poll api significantly to allow polling to return errors when polling hits internal timeout limits.

Maintain was renamed PollType. Additionally, poll now returns a result containing information about what happened during the poll.

-pub fn wgpu::Device::poll(&self, maintain: wgpu::Maintain) -> wgpu::MaintainResult
+pub fn wgpu::Device::poll(&self, poll_type: wgpu::PollType) -> Result<wgpu::PollStatus, wgpu::PollError>

-device.poll(wgpu::Maintain::Poll);
+device.poll(wgpu::PollType::Poll).unwrap();

pub enum PollType<T> {
    /// On wgpu-core based backends, block until the given submission has
    /// completed execution, and any callbacks have been invoked.
    ///
    /// On WebGPU, this has no effect. Callbacks are invoked from the
    /// window event loop.
    WaitForSubmissionIndex(T),
    /// Same as WaitForSubmissionIndex but waits for the most recent submission.
    Wait,
    /// Check the device for a single time without blocking.
    Poll,
}

pub enum PollStatus {
    /// There are no active submissions in flight as of the beginning of the poll call.
    /// Other submissions may have been queued on other threads during the call.
    ///
    /// This implies that the given Wait was satisfied before the timeout.
    QueueEmpty,

    /// The requested Wait was satisfied before the timeout.
    WaitSucceeded,

    /// This was a poll.
    Poll,
}

pub enum PollError {
    /// The requested Wait timed out before the submission was completed.
    Timeout,
}

Warning

As part of this change, WebGL's default behavior has changed. Previously device.poll(Wait) appeared as though it functioned correctly. This was a quirk caused by the bug that these PRs fixed. Now it will always return Timeout if the submission has not already completed. As many people rely on this behavior on WebGL, there is a new options in BackendOptions. If you want the old behavior, set the following on instance creation:

instance_desc.backend_options.gl.fence_behavior = wgpu::GlFenceBehavior::AutoFinish;

You will lose the ability to know exactly when a submission has completed, but device.poll(Wait) will behave the same as it does on native.

By @cwfitzgerald in #6942 and #7030.

wgpu::Device::start_capture renamed, documented, and made unsafe

- device.start_capture();
+ unsafe { device.start_graphics_debugger_capture() }
// Your code here
- device.stop_capture();
+ unsafe { device.stop_graphics_debugger_capture() }

There is now documentation to describe how this maps to the various debuggers' apis.

By @cwfitzgerald in #7470

Ensure loops generated by SPIR-V and HLSL Naga backends are bounded

Make sure that all loops in shaders generated by these naga backends are bounded
to avoid undefined behaviour due to infinite loops. Note that this may have a
performance cost. As with the existing implementation for the MSL backend this
can be disabled by using Device::create_shader_module_trusted().

By @jamienicol in #6929 and #7080.

Split up Features internally

Internally split up the Features struct and recombine them internally using a macro. There should be no breaking
changes from this. This means there are also namespaces (as well as the old Features::*) for all wgpu specific
features and webgpu feature (FeaturesWGPU and FeaturesWebGPU respectively) and Features::from_internal_flags which
allow you to be explicit about whether features you need are available on the web too.

By @Vecvec in #6905, #7086

WebGPU compliant dual source blending feature

Previously, dual source blending was implemented with a wgpu native only feature flag and used a custom syntax in wgpu.
By now, dual source blending was added to the WebGPU spec as an extension.
We're now following suite and implement the official syntax.

Existing shaders using dual source blending need to be updated:

struct FragmentOutput{
-    @location(0) source0: vec4<f32>,
-    @location(0) @second_blend_source source1: vec4<f32>,
+    @location(0) @blend_src(0) source0: vec4<f32>,
+    @location(0) @blend_src(1) source1: vec4<f32>,
}

With that wgpu::Features::DUAL_SOURCE_BLENDING is now available on WebGPU.

Furthermore, GLSL shaders now support dual source blending as well via the index layout qualifier:

layout(location = 0, index = 0) out vec4 output0;
layout(location = 0, index = 1) out vec4 output1;

By @Wumpf in #7144

Unify interface for SpirV shader passthrough

Replace device create_shader_module_spirv function with a generic create_shader_module_passthrough function
taking a ShaderModuleDescriptorPassthrough enum as parameter.

Update your calls to create_shader_module_spirv and use create_shader_module_passthrough instead:

-    device.create_shader_module_spirv(
-        wgpu::ShaderModuleDescriptorSpirV {
-            label: Some(&name),
-            source: Cow::Borrowed(&source),
-        }
-    )
+    device.create_shader_module_passthrough(
+        wgpu::ShaderModuleDescriptorPassthrough::SpirV(
+            wgpu::ShaderModuleDescriptorSpirV {
+                label: Some(&name),
+                source: Cow::Borrowed(&source),
+            },
+        ),
+    )

By @syl20bnr in #7326.

Noop Backend

It is now possible to create a dummy wgpu device even when no GPU is available. This may be useful for testing of code which manages graphics resources. Currently, it supports reading and writing buffers, and other resource types can be created but do nothing.

To use it, enable the noop feature of wgpu, and either call Device::noop(), or add NoopBackendOptions { enable: true } to the backend options of your Instance (this is an additional safeguard beyond the Backends bits).

By @kpreid in #7063 and #7342.

SHADER_F16 feature is now available with naga shaders

Previously this feature only allowed you to use f16 on SPIR-V passthrough shaders. Now you can use it on all shaders, including WGSL, SPIR-V, and GLSL!

enable f16;

fn hello_world(a: f16) -> f16 {
    return a + 1.0h;
}

By @FL33TW00D, @ErichDonGubler, and @cwfitzgerald in #5701

Bindless support improved and validation rules changed.

Metal support for bindless has significantly improved and the limits for binding arrays have been increased.

Previously, all resources inside binding arrays contributed towards the standard limit of their type (texture_2d arrays for example would contribute to max_sampled_textures_per_shader_stage). Now these resources will only contribute towards binding-array specific limits:

• max_binding_array_elements_per_shader_stage for all non-sampler resources
• max_binding_array_sampler_elements_per_shader_stage for sampler resources.

This change has allowed the metal binding array limits to go from between 32 and 128 resources, all the way 500,000 sampled textures. Additionally binding arrays are now bound more efficiently on Metal.

This change also enabled legacy Intel GPUs to support 1M bindless resources, instead of the previous 1800.

To facilitate this change, there was an additional validation rule put in place: if there is a binding array in a bind group, you may not use dynamic offset buffers or uniform buffers in that bind group. This requirement comes from vulkan rules on UpdateAfterBind descriptors.
By @cwfitzgerald in #6811, #6815, and #6952.

New Features

General

• Add Buffer methods corresponding to BufferSlice methods, so you can skip creating a BufferSlice when it offers no benefit, and BufferSlice::slice() for sub-slicing a slice. By @kpreid in #7123.
• Add BufferSlice::buffer(), BufferSlice::offset() and BufferSlice::size(). By @kpreid in #7148.
• Add impl From<BufferSlice> for BufferBinding and impl From<BufferSlice> for BindingResource, allowing BufferSlices to be easily used in creating bind groups. By @kpreid in #7148.
• Add util::StagingBelt::allocate() so the staging belt can be used to write textures. By @kpreid in #6900.
• Added CommandEncoder::transition_resources() for native API interop, and allowing users to slightly optimize barriers. By @JMS55 in #6678.
• Add wgpu_hal::vulkan::Adapter::texture_format_as_raw for native API interop. By @JMS55 in #7228.
• Support getting vertices of the hit triangle when raytracing. By @Vecvec in #7183.
• Add as_hal for both acceleration structures. By @Vecvec in #7303.
• Add Metal compute shader passthrough. Use create_shader_module_passthrough on device. By @syl20bnr in #7326.
• new Features::MSL_SHADER_PASSTHROUGH run-time feature allows providing pass-through MSL Metal shaders. By @syl20bnr in #7326.
• Added mesh shader support to wgpu_hal. By @SupaMaggie70Incorporated in #7089

Naga

• Add support for unsigned types when calling textureLoad with the level parameter. By @ygdrasil-io in #7058.
• Support @must_use attribute on function declarations. By @turbocrime in #6801.
• Support for generating the candidate intersections from AABB geometry, and confirming the hits. By @kvark in #7047.
• Make naga::back::spv::Function::to_words write the OpFunctionEnd instruction in itself, instead of making another call after it. By @junjunjd in #7156.
• Add support for texture memory barriers. By @Devon7925 in #7173.
• Add polyfills for unpackSnorm4x8, unpackUnorm4x8, unpackSnorm2x16, unpackUnorm2x16 for GLSL versions they aren't supported in. By @DJMcNab in #7408.

Examples

• Added an example that shows how to handle datasets too large to fit in a single GPUBuffer by distributing it across many buffers, and then having the shader receive them as a binding_array of storage buffers. By @alphastrata in #6138

Changes

General

• wgpu::Instance::request_adapter() now returns Result instead of Option; the error provides information about why no suitable adapter was returned. By @kpreid in #7330.
• Support BLAS compaction in wgpu-hal. By @Vecvec in #7101.
• Avoid using default features in many dependencies, etc. By Brody in #7031
• Use hashbrown to simplify no-std support. By Brody in #6938 & #6925.
• If you use Binding Arrays in a bind group, you may not use Dynamic Offset Buffers or Uniform Buffers in that bind group. By @cwfitzgerald in #6811
• Rename instance_id and instance_custom_index to instance_index and instance_custom_data by @Vecvec in
  #6780

Naga

• Naga IR types are now available in the module naga::ir (e.g. naga::ir::Module).
  The original names (e.g. naga::Module) remain present for compatibility.
  By @kpreid in #7365.
• Refactored use statements to simplify future no_std support. By @bushrat011899 in #7256
• Naga's WGSL frontend no longer allows using the & operator to take the address of a component of a vector,
  which is not permitted by the WGSL specification. By @andyleiserson in #7284

Vulkan

HAL queue callback support

• Add a way to notify with Queue::submit() to Vulkan's vk::Semaphore allocated outside of wgpu. By @sotaroikeda in #6813.

Bug Fixes

Naga

• Fix some instances of functions which have a return type but don't return a value being incorrectly validated. By @jamienicol in #7013.
• Allow abstract expressions to be used in WGSL function return statements. By @jamienicol in #7035.
• Error if structs have two fields with the same name. By @SparkyPotato in #7088.
• Forward '--keep-coordinate-space' flag to GLSL backend in naga-cli. By @cloone8 in #7206.
• Allow template lists to have a trailing comma. By @kentslaney in #7142.
• Allow WGSL const declarations to have abstract types. By @jamienicol in #7055 and #7222.
• Allows override-sized arrays to resolve to the same size without causing the type arena to panic. By @kentslaney in #7082.
• Allow abstract types to be used for WGSL switch statement selector and case selector expressions. By @jamienicol in #7250.
• Apply automatic conversions to let declarations, and accept vecN() as a constructor for vectors (in any context). By @andyleiserson in #7367.
• The && and || operators are no longer allowed on vectors. By @andyleiserson in #7368.

General

• Fix some validation errors when building acceleration
  structures. By @Vecvec in #7486.
• Avoid overflow in query set bounds check validation. By @ErichDonGubler in #6933.
• Add Flush to GL Queue::submit. By @cwfitzgerald in #6941.
• Reduce downlevel max_color_attachments limit from 8 to 4 for better GLES compatibility. By @adrian17 in #6994.
• Fix building a BLAS with a transform buffer by adding a flag to indicate usage of the transform buffer. By @Vecvec in
  #7062.
• Move incrementation of Device::last_acceleration_structure_build_command_index into queue submit. By @Vecvec in #7462.

Vulkan

• Stop naga causing undefined behavior when a ray query misses. By @Vecvec in #6752.

Gles

• Support OpenHarmony render with gles. By @richerfu in #7085

Dx12

• Fix HLSL storage format generation. By @Vecvec in #6993 and #7104
• Fix 3D storage texture bindings. By @SparkyPotato in #7071
• Fix DX12 composite alpha modes. By @amrbashir in #7117

WebGPU

• Improve efficiency of dropping read-only buffer mappings. By @kpreid in #7007.

Performance

Naga

• Replace unicode-xid with unicode-ident. By @CrazyboyQCD in #7135

Documentation

• Improved documentation around pipeline caches and TextureBlitter. By @DJMcNab in #6978 and #7003.

• Improved documentation of PresentMode, buffer mapping functions, memory alignment requirements, texture formats’ automatic conversions, and various types and constants. By @kpreid in #7211 and #7283.

• Added a hello window example. By @laycookie in #6992.

Examples

• Call pre_present_notify() before presenting. By @kjarosh in #7074.