Bug Fixes

Vulkan

• Stop passing an un-waited fence to vkAcquireNextImageKHR on non-Windows platforms, which triggered VUID-vkAcquireNextImageKHR-fence-10066 validation errors every frame since v30.0.0. By @ErichDonGubler in #9855.

Metal

• Resolve metal color space constants dynamically. By @andyleiserson in #9819.

WebGPU

• Upgrade vendored WebGPU bindings and wasm-bindgen to 0.2.127. This fixes a panic “can't access property "info", arg0 is null” when using the WebGPU backend and requestAdapter() fails. By @beicause in #10034, backported in #10105.

v30.0.1 Latest

Latest

Compare

Choose a tag to compare

Major changes

Optional vertex buffer slots

This allows gaps in VertexState's buffers and adds support for unbinding vertex buffers, bringing us in compliance with the WebGPU spec. As a result of this, VertexState's buffers field now has type of &[Option<VertexBufferLayout>]. To migrate, wrap vertex buffer layouts in Some:

  let vertex_state = wgpu::VertexState {
      module: &vs_module,
      entry_point: Some("vs_main"),
      compilation_options: wgpu::PipelineCompilationOptions::default(),
      buffers: &[
-         &vertex_buffer_layout
+         Some(&vertex_buffer_layout)
      ],
  };

By @teoxoy in #9351.

Integer shader I/O no longer defaults to @interpolate(flat)

To align with the shading language specifications, naga no longer assumes that integer-typed shader I/O should have flat interpolation, i.e., should not be interpolated. Even though flat interpolation is the only choice for integer I/O, it must be still specified explicitly.

WGSL:

 struct FragmentInput {
     @location(0) tex_coord: vec2<f32>,
-    @location(1) index: i32,
+    @location(1) @interpolate(flat) index: i32,
 }

GLSL:

-layout(location = 1) in int index;
+layout(location = 1) flat in int index;

By @andyleiserson in #9321.

Empty buffer slices are now permitted

Creating a BufferSlice with a length of 0 no longer causes a panic.

Empty buffer slices can be:

• Instantiated
• Mapped (the result is an empty slice of bytes)

Empty buffer slices cannot be:

• Used in buffer bindings
• Passed to set_index_buffer or set_vertex_buffer

#3170 tracks making it possible to pass a zero-size BufferSlice to set_vertex_buffer and set_index_buffer in the future.

Zero-size buffer bindings are still not permitted. BufferBinding and BindingResource now implement TryFrom<BufferSlice> instead of From<BufferSlice>. The TryFrom conversion will fail if the slice is zero-size.

-let slice = buffer.slice(0..0); // panic!
-let mapping = BufferBinding::from(slice); // infallible
+let slice = buffer.slice(0..0); // okay
+let mapping = BufferBinding::try_from(slice).unwrap(); // panic

Relatedly, BufferSlice::size() now returns BufferAddress (u64) instead of BufferSize (NonZero<u64>), since an empty slice has size 0.

By @beholdnec in #8505.

Surface color space selection (HDR output)

Surfaces can now be configured with an explicit color space, enabling HDR and wide-gamut output where the platform supports it. SurfaceConfiguration has a new color_space field, and SurfaceCapabilities reports the supported color spaces for every supported format in a new format_capabilities field. SurfaceColorSpace::is_hdr() classifies a color space (the extended-range and PQ/HLG spaces are HDR) so you can branch after picking one.

The new SurfaceColorSpace::Auto default reproduces wgpu's historical behavior (extended linear scRGB for Rgba16Float where supported, sRGB otherwise; never a wide-gamut or HDR color space). To migrate, add the field:

  let config = wgpu::SurfaceConfiguration {
      usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
      format: surface_format,
+     color_space: wgpu::SurfaceColorSpace::Auto,
      ..
  };

Support by backend:

¹ Vulkan support for extended color spaces depends on the driver/platform.

The current state of HDR on the current monitor can be queried with Surface::display_hdr_info.

For wgpu-hal users: hal::SurfaceConfiguration gained a color_space field (never Auto), and hal::SurfaceCapabilities::formats is now Vec<SurfaceFormatCapabilities> instead of Vec<TextureFormat>.

A new standalone example, examples/standalone/03_hdr_surface, prints a surface's (format, color space) capabilities and renders an HDR luminance test pattern through the most capable color space available.

By @stuartparmenter in #9658.

New naga-types crate

To better re-use code between internal crates and prepare for future additions, there is a new crate called naga-types which contains some useful datatypes used by naga and wgpu, without pulling in naga itself.

Some types have changed canonical locations, but are re-exported in their previous places, so there should not be any breaking changes caused by this.

By @inner-daemons in #9434.

Added/New Features

General

• Add StagingBelt::finish_and_recall_on_submit, a convenience that combines finish and recall by deferring the buffer re-map via CommandEncoder::map_buffer_on_submit, so no explicit recall() call is needed after submission. By @ruihe774.
• Implement i16/u16 16-bit integer support in WGSL shaders, gated behind Features::SHADER_I16 and enable wgpu_int16;. Supported on Vulkan, Metal, and DX12 (SM 6.2+). By @JMS55 in #9412.
• Add BLAS support for procedural AABB geometry (BlasGeometrySizeDescriptors::AABBs, BlasAabbGeometry, and related descriptors). By @dylanblokhuis in #9290
• Added "limit bucketing" functionality which can adjust adapter limits and features to match one of several pre-defined buckets. This is controlled by the new apply_limit_buckets member in RequestAdapterOptions, which is false by default. By @andyleiserson in #9119.
• Make wgpu_types::texture::format::TextureChannel accessible as wgpu::TextureChannel. By @TornaxO7 in #9349.
• Add support for per_vertex in Metal and DX12, as well as some validation for per_vertex, and a new enable extension, wgpu_per_vertex. By @inner-daemons in #9219.
• Add ComputePass version of CommandEncoder::transition_resources that allows intra-pass transitions. By @wingertge in #9371.
• Device::create_texture_from_hal now takes an explicit initial_state: wgt::TextureUses parameter declaring the state the wrapped foreign resource is already in. Previously the tracker hard-coded TextureUses::UNINITIALIZED for the wrapped texture, which is a content-discarding transition under the Vulkan spec. This affected zero-copy hardware-decoded video imports on the platforms where compressed modifiers are used. To migrate, pass wgpu::TextureUses::UNINITIALIZED to preserve the previous behaviour:

    let texture = unsafe {
  -     device.create_texture_from_hal::<Vulkan>(hal_texture, &desc)
  +     device.create_texture_from_hal::<Vulkan>(hal_texture, &desc, wgpu::TextureUses::UNINITIALIZED)
    };

  By @AdrianEddy in #9496.
• Add as_custom to many new API types and expose Tlas::lowest_unmodified (letting custom backends perform partial TLAS updates), increasing the capabilities of custom backends. Also fixed render bundles on custom backends. By @inner-daemons in #9605.
• Extend copy_texture_to_texture to allow copying a single plane of a multi-planar source (NV12, P010) into a single-plane destination of the matching format (e.g. NV12 Plane0 → R8Unorm, NV12 Plane1 → Rg8Unorm). copy_size is interpreted in plane texels, not luma texels. By @AdrianEddy in #9551.
• Added InstanceFlags::STRICT_WEBGPU_COMPLIANCE flag, which restricts the available feature set to the one defined by the WebGPU specification. By @teoxoy in #9586.
• Implemented QuerySet::destroy by @sagudev in #9671
• Add QuerySet::ty and QuerySet::count getters. By @sagudev in #9672.
• Implemented query set initialization tracking, ensuring unwritten query slots resolve to 0; avoiding UB. By @teoxoy in #9664.
• Add Surface::display_hdr_info, a read-only snapshot of the backing display's HDR characteristics (luminance in nits, EDR headroom, primaries, bit depth, and a coarse dynamic-range/gamut bucket) for tone-mapping. DisplayHdrInfo::tone_map_headroom() folds it into the one multiplier most tone-mappers want; whether to request an HDR surface at all is a separate, capability question answered by SurfaceCapabilities, not by this live value. Populated on DX12 and Vulkan on Windows, Metal on macOS, and the web. By @stuartparmenter.
• Added Limits::max_buffers_and_acceleration_structures_per_shader_stage, a combined limit for all buffer types (storage, uniform, vertex buffers, and acceleration structures) that share Metal's buffer argument table. On Metal without InstanceFlags::STRICT_WEBGPU_COMPLIANCE set, the new limit and the individual per-type limits (max_storage_buffers_per_shader_stage, max_uniform_buffers_per_shader_stage, max_vertex_buffers, max_acceleration_structures_per_shader_stage) are set to 29. By @teoxoy in #9709.

naga

• Add spirv-out ray tracing pipelines. By @Vecvec in #9085.
• Add naga::front::wgsl::ParseError::notes(). By @kwillemsen in #9572.
• Add MSL support for cooperative matrix multiply-add with lower-precision A/B operands and a higher-precision accumulator/result, such as coopMultiplyAdd(f16, f16, f32) -> f32. By @seddonm1 in #9629.

DX12

• Added support for mesh shaders in naga's HLSL writer, completing DX12 support for mesh shaders. By @inner-daemons in #8752.
• Added dx12::Queue::add_wait_fence / add_signal_fence (and matching remove_* companions). They stage ID3D12CommandQueue::Wait / Signal calls on the next Queue::submit. The wait calls are issued before the submit's ExecuteCommandLists, the signal calls after wgpu's own Signal(signal_fence, signal_value). Cross-API interop crates use this to GPU-side gate / publish wgpu submits against foreign-API fences. By @AdrianEddy in #9463.
• Added dx12::Texture::with_plane_slice so cross-API importers can wrap one plane of a multi-plane DXGI resource (e.g. DXGI_FORMAT_NV12) as a single-plane wgpu texture. By @AdrianEddy in #9551.

Vulkan

• Add vulkan::Queue::add_wait_semaphore and vulkan::Queue::remove_wait_semaphore. Lets external producers (CUDA / OpenCL / D3D12 imported via VK_KHR_external_semaphore_*) be waited on at the next Queue::submit call without a CPU block. By @AdrianEddy in #9461.
• Add vulkan::Device::texture_from_dmabuf_fd() for importing DMA-buf textures on Linux, with VULKAN_EXTERNAL_MEMORY_FD and VULKAN_EXTERNAL_MEMORY_DMA_BUF feature flags. By @todo in #9412.
• Add support for RawWindowHandle::Drm on Unix, conditional on the drm feature.
  • DRM support by @rectalogic in #9182.
  • Conditional compilation by @jimblandy in #9390
• Add wgpu_hal::vulkan::Buffer::raw_handle() for retrieving the underlying vk::Buffer resource. By @WillowGriffiths in #9459.

Metal

• Add metal::Queue::add_wait_event / add_signal_event (with remove_* companions) to stage MTLSharedEvent waits/signals on the next Queue::submit, for GPU-side interop with foreign APIs. Waits run on an internal CB committed before user CBs. By @AdrianEddy in #9483.
• Unconditionally enable Features::CLIP_DISTANCES. By @ErichDonGubler in #9270.
• Added full support for mesh shaders, including in WGSL shaders. By @inner-daemons in #8739.
• Added support for bindless storage buffers (buffer binding arrays) on Metal. By @mate-h in #9081.
• Added DropCallbacks to Metal textures. By @jerzywilczek in #9634.

GLES

• Added support for GLSL passthrough. By @inner-daemons in #9064.
• Implement Adapter::new_external() for WebGL2 (just like EGL/WGL) to import an external WebGL2 rendering context, and expose the imported context back through Adapter::adapter_context() / Device::context(). By @pepperoni505 in #9438.
• Add gles::Device::buffer_from_raw for wrapping an externally-owned GL buffer as a wgpu_hal::gles::Buffer. By @AdrianEddy in #9550.
• Advertise Features::TEXTURE_FORMAT_16BIT_NORM on OpenGL, including storage-texture usage where the driver supports it. By @AdrianEddy in #9601.

Changes

General

• SurfaceTexture::present() has been replaced by Queue::present(surface_texture). By @inner-daemons and @atlv24 in #9361.
• Features::CLIP_DISTANCE, naga::Capabilities::CLIP_DISTANCE, and naga::BuiltIn::ClipDistance have been renamed to CLIP_DISTANCES and ClipDistances (viz., pluralized) as appropriate, to match the WebGPU spec. By @ErichDonGubler in #9267.
• Added more granular limits for mesh shaders. By @inner-daemons in #8739.
• Added new InvalidWorkgroupSizeError, which is now used by DrawError::InvalidGroupSize and StageError::InvalidWorkgroupSize. By @andyleiserson in #9357.
• Zero-size Queue::write_buffer now returns an error if the offset is invalid or the buffer lacks COPY_DST. By @39ali in #9374.
• Buffer::get_mapped_range and variants now return Result<_, MapRangeError>> instead of panicking, in line with WebGPU spec. By @atlv24 in #9281.
• Passthrough shaders now require a list of entry points when being created. by @inner-daemons in #9064.
• BREAKING: The dispatch and dispatch_indirect methods on pass and bundle encoders have been renamed to dispatch_workgroups and dispatch_workgroups_indirect, respectively, to match the WebGPU spec. By @ErichDonGubler in #9362.
• LoadOp::DontCare can no longer be deserialized, and the LoadOpDontCare token no longer implements Default. This ensures that DontCare can only be used with unsafe, as intended. By @kpreid in #9428.
• Minor changes to various error enums to support improved validation. By @andyleiserson in #9357, #9363, and #9425:
  • Added new InvalidWorkgroupSizeError, which is now used by DrawError::InvalidGroupSize and StageError::InvalidWorkgroupSize.
  • Added BuildAccelerationStructureError variant OffsetLimitedTo4GB and changed IndirectBufferOverrun to contain offset and size rather than start and end offsets.
  • IndexFormat::byte_size now returns u32 instead of usize.
• BREAKING: map_label helpers have changed slightly. By @beicause and @andyleiserson in #9480, #9481, and #9526.
  • TextureDescriptor::map_label_and_view_formats and SurfaceConfiguration::map_view_formats now take FnOnce(&V) instead of FnOnce(V).
  • All map_label helpers except CreateShaderModuleDescriptorPassthrough now have the signature map_label<'a, K>(&'a self, fun: impl FnOnce(&'a L) -> K) (previously the lifetimes were implicit and thus could differ).
• Relaxed locking within wgpu-core to enable queue submission processing on one thread to proceed while another thread is blocked in a device poll. To facilitate this, wgpu-hal fences are now internally synchronized. By @Vecvec in #9475.
• AdapterInfo::transient_saves_memory now is Option<bool> instead of bool. It is None on web and Some on native platforms. By @beicause in #9568.
• BREAKING: TextureUsages::TRANSIENT is renamed to TextureUsages::TRANSIENT_ATTACHMENT and brought in line with WebGPU spec. Transient textures may now only be used with LoadOp::Clear or LoadOp::DontCare (if it is available) and StoreOp::Discard. By @beicause in #9568.
• Added missing Debug implementations across the public API (including TextureBlitter and its builder, SurfaceTarget, ErrorScopeGuard, and QueueWriteBufferView) and enabled the missing_debug_implementations lint. By @euclio in #9730 and @kpreid in #9744.

naga

• Switched from using an intersector to using an intersection_query on metal so AABBs and non-opaque triangles can be handled. By @Vecvec in #9304.
• Guard against invalid calls to ray query functions on Metal. By @Vecvec in #9442.

Validation

• Add clip distances validation for maxInterStageShaderVariables. By @ErichDonGubler in #8762. This may break some existing programs, but it compiles with the WebGPU spec.
• Bring immediates in line with webgpu spec. By @atlv24 in #9280.
• Validate LoadOp and StoreOp are None for attachments without corresponding depth or stencil aspect. By @beicause in #9567.

DX12

• Prefix FeatureLevel and ShaderModel enum variants with V instead of _. By @teoxoy in #9337.

Bug Fixes

General

• Fix SYNC-HAZARD-WRITE-AFTER-PRESENT on Vulkan when a surface texture is presented without being rendered to. By @inner-daemons and @atlv24 in #9361.
• Fix incorrect checks for dynamic binding bounds when calling an encoder's set_bind_group in passes and bundles. By @ErichDonGubler in #9308.
• Writes from Queue::write_buffer are now flushed by calls to Buffer::map_async for that same buffer, to prevent reading stale data. on_submitted_work_done also now flushes pending writes. By @andyleiserson in #9307.
• Fix missing dependency feature activations when building wgpu-hal with gles/dx12 in isolation. By @Wumpf in #9325
• Increase recursion limits to please -Znext-solver. By @nazar-pc in #9609
• Stencil clear and reference values are now truncated to 8 bits. By @beicause in #9607.
• Fixed missing initialization of other aspects when writing to a single aspect of a multi-aspect texture. By @andyleiserson in #9626.
• Fix process abort when a SurfaceTexture is dropped during panic unwind between get_current_texture and Queue::present. The acquired texture reference is now released without calling HAL discard. By @hack3rmann in #9678.
• Fixed incorrect initialization tracking for 3D textures. By @andyleiserson in #9765.

naga

• Fixed atomic load and store operations being incorrectly generated as non-atomic memory accesses in GLSL and HLSL. By @CldStlkr in #9242.
• Fixed overflow detection and argument domain validation for acosh, length, normalize, and pow in constant evaluation. By @ecoricemon in #9249.
• Naga no longer allows derivative operations on f16. WGSL does not currently allow this, although it may be added in the future. By @andyleiserson in #9154.
• Disallow direct access to atomic variables in WGSL front-end (e.g. let x = myAtomic;). By @ecoricemon in #9262.
• Fixed handling of unterminated block comments. By @BKDaugherty in #9356.
• Enforce that @must_use appear only on function declarations. By @dnsn021 in #9367.
• Fix typo in naga::back::msl::Error::UnsupportedWritable* variant names. By @ErichDonGubler in #9376.
• Added support for enable wgpu_binding_array;. By @39ali in #9298.
• Ability to disable integer division safety checks on Vulkan and Metal. By @kvark in #9443.
• [hlsl] more matCx2 fixes. By @teoxoy in #9507.
• Fix packSnorm2x16 and packUnorm2x16 swap in the GLSL frontend. By @treylutton in #9675.
• Fixed WGSL loop-local var declarations without explicit initializers so they are zero-initialized each iteration. By @ruihe774 in #9592.
• Fixed logic errors in the ray query spirv writer. By @Vecvec in #9731.

DX12

• Fixed use of a texture view without TextureUsage::TEXTURE_BINDING as a read-only depth attachment. By @andyleiserson in #9346.
• Fixed a debug_assert during stride validation for indirect multi draw. By @kristoff3r in #9332
• Fixed stencil values read with textureLoad appearing in G instead of R. By @andyleiserson in #9520.
• Fixed some cases where the textureNum{Layers,Levels,Samples} functions returned incorrect results. By @andyleiserson in #9542.
• Fixed map_texture_format_for_copy panicking on (planar_format, single_plane_aspect) during buffer<->texture transfers, and TextureView::subresource_index previously being hard-coded to plane 0. By @AdrianEddy in #9551.
• Fixed partially-bound texture and storage-texture binding arrays (PARTIALLY_BOUND_BINDING_ARRAY) reading garbage in create_bind_group. By @holg in #9653.

Vulkan

• Fixed SHADER_I16 not enabling storage_buffer16_bit_access or storage_input_output16, causing Vulkan validation errors when using 16-bit integers in buffers. By @JMS55 in #9412.
• Fixed validation errors when frames take longer than the specified swapchain acquire timeout. By @atlv24 in #9405.
• Fixed limits on Mesa's Honeykrisp / Asahi Linux. By @im-0 in #9393.
• Fixed vkAcquireNextImage fence being awaited on non-Windows platforms causing frametime spikes on nvidia drivers. By @cohaereo in #9486.
• Fixed alignment and MatrixStride for mat2x2 in SPIR-V uniform blocks. By @39ali #9369.
• Fixed loading of libvulkan.so on OpenHarmony (target_env = "ohos"). By @jschwe in #9649.
• Fixed VUID-RuntimeSpirv-vulkanMemoryModel-06265 validation errors by enabling vulkanMemoryModelDeviceScope whenever the Vulkan memory model is enabled, since the SPIR-V backend emits storage atomics with Device scope. By @francisdb in #9741.
• Fixed some cases where out-of-memory errors were reported incorrectly. By @andyleiserson in #9643 and #9747.
• Fixed signed integer % (and %=) returning the wrong result for negative operands in the SPIR-V backend, e.g. -1 % 768 yielding 255 instead of -1 on NVIDIA. OpSRem is poison for negative operands in the Vulkan SPIR-V environment without VK_KHR_maintenance8, even though WGSL defines % for these operands, so signed remainder is now always lowered as a - b * (a / b). By @mstampfli in #9674.

Metal

• Detect BC texture support on newer iOS, tvOS, and visionOS devices. By @bmisiak in #9656.
• Fix crash on fence creation when running in a MacOS Seatbelt sandbox. By @Wumpf in #9415
• Improved command buffer completion handling. By @39ali in #9328.
  • Wait using a condition variable, instead of polling.
  • Fixed a hang in Device::poll(PollType::wait_indefinitely()) when a Metal command buffer exits with an error.
• Fixed structure field names incorrectly ignoring reserved keywords in the Metal (MSL) backend. By @39ali #9379.
• Restore the Queue::as_raw method, which was removed without good reason in v29. It now returns &ProtocolObject<dyn MTLCommandQueue>. By @andyleiserson in #9560.

WebGPU

• Expose the underlying JS handles of WebGPU-backed resources via new as_webgpu accessors on Texture, TextureView, Buffer, Queue, and Device, returning Option<&wgpu::webgpu::Gpu*>. This is the WebGPU counterpart of as_hal (which returns None on the WebGPU backend, since WebGPU is not a wgpu_hal API). The vendored handle types are re-exported under the new wgpu::webgpu module. By @AdrianEddy in #9530
• Add Device::create_texture_from_webgpu_handle(texture, desc, drop_callback) for wrapping a foreign webgpu::GpuTexture (e.g. a canvas getCurrentTexture() result) as a wgpu::Texture without copy. Use the drop_callback to decide if you want to call GpuTexture.destroy() when wgpu is done with the texture. By @AdrianEddy in #9530

Dependency Updates

WebGPU

• Upgrade vendored wasm-bindgen WebGPU bindings to 0.2.115 and adapt the webgpu backend to the new API. ExternalImageSource::VideoFrame no longer requires --cfg=web_sys_unstable_apis, as web_sys::VideoFrame is now stable. The GLES backend still requires the cfg to upload VideoFrames, since glow still needs to adapt. By @evilpie in #9090.

Testing/Internal

• We now use tombi as our TOML formatter instead of taplo, which has been unmaintained for some time. If you currently use taplo as part of your workflow, we recommend you migrate, or change your editor settings while working with wgpu.

Major changes

Optional vertex buffer slots

This allows gaps in VertexState's buffers and adds support for unbinding vertex buffers, bringing us in compliance with the WebGPU spec. As a result of this, VertexState's buffers field now has type of &[Option<VertexBufferLayout>]. To migrate, wrap vertex buffer layouts in Some:

  let vertex_state = wgpu::VertexState {
      module: &vs_module,
      entry_point: Some("vs_main"),
      compilation_options: wgpu::PipelineCompilationOptions::default(),
      buffers: &[
-         &vertex_buffer_layout
+         Some(&vertex_buffer_layout)
      ],
  };

By @teoxoy in #9351.

Integer shader I/O no longer defaults to @interpolate(flat)

To align with the shading language specifications, naga no longer assumes that integer-typed shader I/O should have flat interpolation, i.e., should not be interpolated. Even though flat interpolation is the only choice for integer I/O, it must be still specified explicitly.

WGSL:

 struct FragmentInput {
     @location(0) tex_coord: vec2<f32>,
-    @location(1) index: i32,
+    @location(1) @interpolate(flat) index: i32,
 }

GLSL:

-layout(location = 1) in int index;
+layout(location = 1) flat in int index;

By @andyleiserson in #9321.

Empty buffer slices are now permitted

Creating a BufferSlice with a length of 0 no longer causes a panic.

Empty buffer slices can be:

• Instantiated
• Mapped (the result is an empty slice of bytes)

Empty buffer slices cannot be:

• Used in buffer bindings
• Passed to set_index_buffer or set_vertex_buffer

#3170 tracks making it possible to pass a zero-size BufferSlice to set_vertex_buffer and set_index_buffer in the future.

Zero-size buffer bindings are still not permitted. BufferBinding and BindingResource now implement TryFrom<BufferSlice> instead of From<BufferSlice>. The TryFrom conversion will fail if the slice is zero-size.

-let slice = buffer.slice(0..0); // panic!
-let mapping = BufferBinding::from(slice); // infallible
+let slice = buffer.slice(0..0); // okay
+let mapping = BufferBinding::try_from(slice).unwrap(); // panic

Relatedly, BufferSlice::size() now returns BufferAddress (u64) instead of BufferSize (NonZero<u64>), since an empty slice has size 0.

By @beholdnec in #8505.

Surface color space selection (HDR output)

Surfaces can now be configured with an explicit color space, enabling HDR and wide-gamut output where the platform supports it. SurfaceConfiguration has a new color_space field, and SurfaceCapabilities reports the supported color spaces for every supported format in a new format_capabilities field. SurfaceColorSpace::is_hdr() classifies a color space (the extended-range and PQ/HLG spaces are HDR) so you can branch after picking one.

The new SurfaceColorSpace::Auto default reproduces wgpu's historical behavior (extended linear scRGB for Rgba16Float where supported, sRGB otherwise; never a wide-gamut or HDR color space). To migrate, add the field:

  let config = wgpu::SurfaceConfiguration {
      usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
      format: surface_format,
+     color_space: wgpu::SurfaceColorSpace::Auto,
      ..
  };

Support by backend:

¹ Vulkan support for extended color spaces depends on the driver/platform.

The current state of HDR on the current monitor can be queried with Surface::display_hdr_info.

For wgpu-hal users: hal::SurfaceConfiguration gained a color_space field (never Auto), and hal::SurfaceCapabilities::formats is now Vec<SurfaceFormatCapabilities> instead of Vec<TextureFormat>.

A new standalone example, examples/standalone/03_hdr_surface, prints a surface's (format, color space) capabilities and renders an HDR luminance test pattern through the most capable color space available.

By @stuartparmenter in #9658.

New naga-types crate

To better re-use code between internal crates and prepare for future additions, there is a new crate called naga-types which contains some useful datatypes used by naga and wgpu, without pulling in naga itself.

Some types have changed canonical locations, but are re-exported in their previous places, so there should not be any breaking changes caused by this.

By @inner-daemons in #9434.

Added/New Features

General

• Add StagingBelt::finish_and_recall_on_submit, a convenience that combines finish and recall by deferring the buffer re-map via CommandEncoder::map_buffer_on_submit, so no explicit recall() call is needed after submission. By @ruihe774.
• Implement i16/u16 16-bit integer support in WGSL shaders, gated behind Features::SHADER_I16 and enable wgpu_int16;. Supported on Vulkan, Metal, and DX12 (SM 6.2+). By @JMS55 in #9412.
• Add BLAS support for procedural AABB geometry (BlasGeometrySizeDescriptors::AABBs, BlasAabbGeometry, and related descriptors). By @dylanblokhuis in #9290
• Added "limit bucketing" functionality which can adjust adapter limits and features to match one of several pre-defined buckets. This is controlled by the new apply_limit_buckets member in RequestAdapterOptions, which is false by default. By @andyleiserson in #9119.
• Make wgpu_types::texture::format::TextureChannel accessible as wgpu::TextureChannel. By @TornaxO7 in #9349.
• Add support for per_vertex in Metal and DX12, as well as some validation for per_vertex, and a new enable extension, wgpu_per_vertex. By @inner-daemons in #9219.
• Add ComputePass version of CommandEncoder::transition_resources that allows intra-pass transitions. By @wingertge in #9371.
• Device::create_texture_from_hal now takes an explicit initial_state: wgt::TextureUses parameter declaring the state the wrapped foreign resource is already in. Previously the tracker hard-coded TextureUses::UNINITIALIZED for the wrapped texture, which is a content-discarding transition under the Vulkan spec. This affected zero-copy hardware-decoded video imports on the platforms where compressed modifiers are used. To migrate, pass wgpu::TextureUses::UNINITIALIZED to preserve the previous behaviour:

    let texture = unsafe {
  -     device.create_texture_from_hal::<Vulkan>(hal_texture, &desc)
  +     device.create_texture_from_hal::<Vulkan>(hal_texture, &desc, wgpu::TextureUses::UNINITIALIZED)
    };
  

  By @AdrianEddy in #9496.
• Add as_custom to many new API types and expose Tlas::lowest_unmodified (letting custom backends perform partial TLAS updates), increasing the capabilities of custom backends. Also fixed render bundles on custom backends. By @inner-daemons in #9605.
• Extend copy_texture_to_texture to allow copying a single plane of a multi-planar source (NV12, P010) into a single-plane destination of the matching format (e.g. NV12 Plane0 → R8Unorm, NV12 Plane1 → Rg8Unorm). copy_size is interpreted in plane texels, not luma texels. By @AdrianEddy in #9551.
• Added InstanceFlags::STRICT_WEBGPU_COMPLIANCE flag, which restricts the available feature set to the one defined by the WebGPU specification. By @teoxoy in #9586.
• Implemented QuerySet::destroy by @sagudev in #9671
• Add QuerySet::ty and QuerySet::count getters. By @sagudev in #9672.
• Implemented query set initialization tracking, ensuring unwritten query slots resolve to 0; avoiding UB. By @teoxoy in #9664.
• Add Surface::display_hdr_info, a read-only snapshot of the backing display's HDR characteristics (luminance in nits, EDR headroom, primaries, bit depth, and a coarse dynamic-range/gamut bucket) for tone-mapping. DisplayHdrInfo::tone_map_headroom() folds it into the one multiplier most tone-mappers want; whether to request an HDR surface at all is a separate, capability question answered by SurfaceCapabilities, not by this live value. Populated on DX12 and Vulkan on Windows, Metal on macOS, and the web. By @stuartparmenter.
• Added Limits::max_buffers_and_acceleration_structures_per_shader_stage, a combined limit for all buffer types (storage, uniform, vertex buffers, and acceleration structures) that share Metal's buffer argument table. On Metal without InstanceFlags::STRICT_WEBGPU_COMPLIANCE set, the new limit and the individual per-type limits (max_storage_buffers_per_shader_stage, max_uniform_buffers_per_shader_stage, max_vertex_buffers, max_acceleration_structures_per_shader_stage) are set to 29. By @teoxoy in #9709.

naga

• Add spirv-out ray tracing pipelines. By @Vecvec in #9085.
• Add naga::front::wgsl::ParseError::notes(). By @kwillemsen in #9572.
• Add MSL support for cooperative matrix multiply-add with lower-precision A/B operands and a higher-precision accumulator/result, such as coopMultiplyAdd(f16, f16, f32) -> f32. By @seddonm1 in #9629.

DX12

• Added support for mesh shaders in naga's HLSL writer, completing DX12 support for mesh shaders. By @inner-daemons in #8752.
• Added dx12::Queue::add_wait_fence / add_signal_fence (and matching remove_* companions). They stage ID3D12CommandQueue::Wait / Signal calls on the next Queue::submit. The wait calls are issued before the submit's ExecuteCommandLists, the signal calls after wgpu's own Signal(signal_fence, signal_value). Cross-API interop crates use this to GPU-side gate / publish wgpu submits against foreign-API fences. By @AdrianEddy in #9463.
• Added dx12::Texture::with_plane_slice so cross-API importers can wrap one plane of a multi-plane DXGI resource (e.g. DXGI_FORMAT_NV12) as a single-plane wgpu texture. By @AdrianEddy in #9551.

Vulkan

• Add vulkan::Queue::add_wait_semaphore and vulkan::Queue::remove_wait_semaphore. Lets external producers (CUDA / OpenCL / D3D12 imported via VK_KHR_external_semaphore_*) be waited on at the next Queue::submit call without a CPU block. By @AdrianEddy in #9461.
• Add vulkan::Device::texture_from_dmabuf_fd() for importing DMA-buf textures on Linux, with VULKAN_EXTERNAL_MEMORY_FD and VULKAN_EXTERNAL_MEMORY_DMA_BUF feature flags. By @TODO in #9412.
• Add support for RawWindowHandle::Drm on Unix, conditional on the drm feature.
  • DRM support by @rectalogic in #9182.
  • Conditional compilation by @jimblandy in #9390
• Add wgpu_hal::vulkan::Buffer::raw_handle() for retrieving the underlying vk::Buffer resource. By @WillowGriffiths in #9459.

Metal

• Add metal::Queue::add_wait_event / add_signal_event (with remove_* companions) to stage MTLSharedEvent waits/signals on the next Queue::submit, for GPU-side interop with foreign APIs. Waits run on an internal CB committed before user CBs. By @AdrianEddy in #9483.
• Unconditionally enable Features::CLIP_DISTANCES. By @ErichDonGubler in #9270.
• Added full support for mesh shaders, including in WGSL shaders. By @inner-daemons in #8739.
• Added support for bindless storage buffers (buffer binding arrays) on Metal. By @mate-h in #9081.
• Added DropCallbacks to Metal textures. By @jerzywilczek in #9634.

GLES

• Added support for GLSL passthrough. By @inner-daemons in #9064.
• Implement Adapter::new_external() for WebGL2 (just like EGL/WGL) to import an external WebGL2 rendering context, and expose the imported context back through Adapter::adapter_context() / Device::context(). By @pepperoni505 in #9438.
• Add gles::Device::buffer_from_raw for wrapping an externally-owned GL buffer as a wgpu_hal::gles::Buffer. By @AdrianEddy in #9550.
• Advertise Features::TEXTURE_FORMAT_16BIT_NORM on OpenGL, including storage-texture usage where the driver supports it. By @AdrianEddy in #9601.

Changes

General

• SurfaceTexture::present() has been replaced by Queue::present(surface_texture). By @inner-daemons and @atlv24 in #9361.
• Features::CLIP_DISTANCE, naga::Capabilities::CLIP_DISTANCE, and naga::BuiltIn::ClipDistance have been renamed to CLIP_DISTANCES and ClipDistances (viz., pluralized) as appropriate, to match the WebGPU spec. By @ErichDonGubler in #9267.
• Added more granular limits for mesh shaders. By @inner-daemons in #8739.
• Added new InvalidWorkgroupSizeError, which is now used by DrawError::InvalidGroupSize and StageError::InvalidWorkgroupSize. By @andyleiserson in #9357.
• Zero-size Queue::write_buffer now returns an error if the offset is invalid or the buffer lacks COPY_DST. By @39ali in #9374.
• Buffer::get_mapped_range and variants now return Result<_, MapRangeError>> instead of panicking, in line with WebGPU spec. By @atlv24 in #9281.
• Passthrough shaders now require a list of entry points when being created. by @inner-daemons in #9064.
• BREAKING: The dispatch and dispatch_indirect methods on pass and bundle encoders have been renamed to dispatch_workgroups and dispatch_workgroups_indirect, respectively, to match the WebGPU spec. By @ErichDonGubler in #9362.
• LoadOp::DontCare can no longer be deserialized, and the LoadOpDontCare token no longer implements Default. This ensures that DontCare can only be used with unsafe, as intended. By @kpreid in #9428.
• Minor changes to various error enums to support improved validation. By @andyleiserson in #9357, #9363, and #9425:
  • Added new InvalidWorkgroupSizeError, which is now used by DrawError::InvalidGroupSize and StageError::InvalidWorkgroupSize.
  • Added BuildAccelerationStructureError variant OffsetLimitedTo4GB and changed IndirectBufferOverrun to contain offset and size rather than start and end offsets.
  • IndexFormat::byte_size now returns u32 instead of usize.
• BREAKING: map_label helpers have changed slightly. By @beicause and @andyleiserson in #9480, #9481, and #9526.
  • TextureDescriptor::map_label_and_view_formats and SurfaceConfiguration::map_view_formats now take FnOnce(&V) instead of FnOnce(V).
  • All map_label helpers except CreateShaderModuleDescriptorPassthrough now have the signature map_label<'a, K>(&'a self, fun: impl FnOnce(&'a L) -> K) (previously the lifetimes were implicit and thus could differ).
• Relaxed locking within wgpu-core to enable queue submission processing on one thread to proceed while another thread is blocked in a device poll. To facilitate this, wgpu-hal fences are now internally synchronized. By @Vecvec in #9475.
• AdapterInfo::transient_saves_memory now is Option<bool> instead of bool. It is None on web and Some on native platforms. By @beicause in #9568.
• BREAKING: TextureUsages::TRANSIENT is renamed to TextureUsages::TRANSIENT_ATTACHMENT and brought in line with WebGPU spec. Transient textures may now only be used with LoadOp::Clear or LoadOp::DontCare (if it is available) and StoreOp::Discard. By @beicause in #9568.
• Added missing Debug implementations across the public API (including TextureBlitter and its builder, SurfaceTarget, ErrorScopeGuard, and QueueWriteBufferView) and enabled the missing_debug_implementations lint. By @euclio in #9730 and @kpreid in #9744.

naga

• Switched from using an intersector to using an intersection_query on metal so AABBs and non-opaque triangles can be handled. By @Vecvec in #9304.
• Guard against invalid calls to ray query functions on Metal. By @Vecvec in #9442.

Validation

• Add clip distances validation for maxInterStageShaderVariables. By @ErichDonGubler in #8762. This may break some existing programs, but it compiles with the WebGPU spec.
• Bring immediates in line with webgpu spec. By @atlv24 in #9280.
• Validate LoadOp and StoreOp are None for attachments without corresponding depth or stencil aspect. By @beicause in #9567.

DX12

• Prefix FeatureLevel and ShaderModel enum variants with V instead of _. By @teoxoy in #9337.

Bug Fixes

General

• Fix SYNC-HAZARD-WRITE-AFTER-PRESENT on Vulkan when a surface texture is presented without being rendered to. By @inner-daemons and @atlv24 in #9361.
• Fix incorrect checks for dynamic binding bounds when calling an encoder's set_bind_group in passes and bundles. By @ErichDonGubler in #9308.
• Writes from Queue::write_buffer are now flushed by calls to Buffer::map_async for that same buffer, to prevent reading stale data. on_submitted_work_done also now flushes pending writes. By @andyleiserson in #9307.
• Fix missing dependency feature activations when building wgpu-hal with gles/dx12 in isolation. By @wumpf in #9325
• Increase recursion limits to please -Znext-solver. By @nazar-pc in #9609
• Stencil clear and reference values are now truncated to 8 bits. By @beicause in #9607.
• Fixed missing initialization of other aspects when writing to a single aspect of a multi-aspect texture. By @andyleiserson in #9626.
• Fix process abort when a SurfaceTexture is dropped during panic unwind between get_current_texture and Queue::present. The acquired texture reference is now released without calling HAL discard. By @hack3rmann in #9678.
• Fixed incorrect initialization tracking for 3D textures. By @andyleiserson in #9765.

naga

• Fixed atomic load and store operations being incorrectly generated as non-atomic memory accesses in GLSL and HLSL. By @CldStlkr in #9242.
• Fixed overflow detection and argument domain validation for acosh, length, normalize, and pow in constant evaluation. By @ecoricemon in #9249.
• Naga no longer allows derivative operations on f16. WGSL does not currently allow this, although it may be added in the future. By @andyleiserson in #9154.
• Disallow direct access to atomic variables in WGSL front-end (e.g. let x = myAtomic;). By @ecoricemon in #9262.
• Fixed handling of unterminated block comments. By @BKDaugherty in #9356.
• Enforce that @must_use appear only on function declarations. By @dnsn021 in #9367.
• Fix typo in naga::back::msl::Error::UnsupportedWritable* variant names. By @ErichDonGubler in #9376.
• Added support for enable wgpu_binding_array;. By @39ali in #9298.
• Ability to disable integer division safety checks on Vulkan and Metal. By @kvark in #9443.
• [hlsl] more matCx2 fixes. By @teoxoy in #9507.
• Fix packSnorm2x16 and packUnorm2x16 swap in the GLSL frontend. By @treylutton in #9675.
• Fixed WGSL loop-local var declarations without explicit initializers so they are zero-initialized each iteration. By @ruihe774 in #9592.
• Fixed logic errors in the ray query spirv writer. By @Vecvec in #9731.

DX12

• Fixed use of a texture view without TextureUsage::TEXTURE_BINDING as a read-only depth attachment. By @andyleiserson in #9346.
• Fixed a debug_assert during stride validation for indirect multi draw. By @kristoff3r in #9332
• Fixed stencil values read with textureLoad appearing in G instead of R. By @andyleiserson in #9520.
• Fixed some cases where the textureNum{Layers,Levels,Samples} functions returned incorrect results. By @andyleiserson in #9542.
• Fixed map_texture_format_for_copy panicking on (planar_format, single_plane_aspect) during buffer<->texture transfers, and TextureView::subresource_index previously being hard-coded to plane 0. By @AdrianEddy in #9551.
• Fixed partially-bound texture and storage-texture binding arrays (PARTIALLY_BOUND_BINDING_ARRAY) reading garbage in create_bind_group. By @holg in #9653.

Vulkan

• Use the imported queue family's supported shader stages when building buffer, texture, and acceleration structure barriers for raw Vulkan devices. By @ruihe774 in #9594.
• Fixed SHADER_I16 not enabling storage_buffer16_bit_access or storage_input_output16, causing Vulkan validation errors when using 16-bit integers in buffers. By @JMS55 in #9412.
• Fixed validation errors when frames take longer than the specified swapchain acquire timeout. By @atlv24 in #9405.
• Fixed limits on Mesa's Honeykrisp / Asahi Linux. By @im-0 in #9393.
• Fixed vkAcquireNextImage fence being awaited on non-Windows platforms causing frametime spikes on nvidia drivers. By @cohaereo in #9486.
• Fixed alignment and MatrixStride for mat2x2 in SPIR-V uniform blocks. By @39ali #9369.
• Fixed loading of libvulkan.so on OpenHarmony (target_env = "ohos"). By @jschwe in #9649.
• Fixed some cases where out-of-memory errors were reported incorrectly. By @andyleiserson in #9643 and #9747.
• Fixed signed integer % (and %=) returning the wrong result for negative operands in the SPIR-V backend, e.g. -1 % 768 yielding 255 instead of -1 on NVIDIA. OpSRem is poison for negative operands in the Vulkan SPIR-V environment without VK_KHR_maintenance8, even though WGSL defines % for these operands, so signed remainder is now always lowered as a - b * (a / b). By @mstampfli in #9674.

Metal

• Detect BC texture support on newer iOS, tvOS, and visionOS devices. By @bmisiak in #9656.
• Fix crash on fence creation when running in a MacOS Seatbelt sandbox. By @wumpf in #9415
• Improved command buffer completion handling. By @39ali in #9328.
  • Wait using a condition variable, instead of polling.
  • Fixed a hang in Device::poll(PollType::wait_indefinitely()) when a Metal command buffer exits with an error.
• Fixed structure field names incorrectly ignoring reserved keywords in the Metal (MSL) backend. By @39ali #9379.

WebGPU

• Expose the underlying JS handles of WebGPU-backed resources via new as_webgpu accessors on Texture, TextureView, Buffer, Queue, and Device, returning Option<&wgpu::webgpu::Gpu*>. This is the WebGPU counterpart of as_hal (which returns None on the WebGPU backend, since WebGPU is not a wgpu_hal API). The vendored handle types are re-exported under the new wgpu::webgpu module. By @AdrianEddy in #9530
• Add Device::create_texture_from_webgpu_handle(texture, desc, drop_callback) for wrapping a foreign webgpu::GpuTexture (e.g. a canvas getCurrentTexture() result) as a wgpu::Texture without copy. Use the drop_callback to decide if you want to call GpuTexture.destroy() when wgpu is done with the texture. By @AdrianEddy in #9530

Dependency Updates

WebGPU

• Upgrade vendored wasm-bindgen WebGPU bindings to 0.2.115 and adapt the webgpu backend to the new API. ExternalImageSource::VideoFrame no longer requires --cfg=web_sys_unstable_apis, as web_sys::VideoFrame is now stable. The GLES backend still requires the cfg to upload VideoFrames, since glow still needs to adapt. By @evilpie in #9090.

Testing/Internal

• We now use tombi as our TOML formatter instead of taplo, which has been unmaintained for some time. If you currently use taplo as part of your workflow, we recommend you migrate, or change your editor settings while working with wgpu.

v30.0.0

Compare

Choose a tag to compare

New Features

GLES

• XCB window handles can now be used to initialize OpenGL on Linux. By @reflectronic in #9271.

Bug Fixes

Metal

• Restore the Queue::as_raw method, which was removed without good reason in v29. It now returns &ProtocolObject<dyn MTLCommandQueue>. By @andyleiserson in #9560.

Vulkan

• Fixed VUID-RuntimeSpirv-vulkanMemoryModel-06265 validation errors by enabling vulkanMemoryModelDeviceScope whenever the Vulkan memory model is enabled, since the SPIR-V backend emits storage atomics with Device scope. By @francisdb in #9741.

New Features

GLES

• XCB window handles can now be used to initialize OpenGL on Linux. By @reflectronic in #9271.

Bug Fixes

Metal

• Restore the Queue::as_raw method, which was removed without good reason in v29. It now returns &ProtocolObject<dyn MTLCommandQueue>. By @andyleiserson in #9560.

Vulkan

• Fixed VUID-RuntimeSpirv-vulkanMemoryModel-06265 validation errors by enabling vulkanMemoryModelDeviceScope whenever the Vulkan memory model is enabled, since the SPIR-V backend emits storage atomics with Device scope. By @francisdb in #9741.

v29.0.4

Compare

Choose a tag to compare

Bug Fixes

• Fix compilation error when cfg(debug_assertions) is not active. wgpu-core v29.0.2 has been yanked. By @Elabajaba in #9352.

Bug Fixes

• Fix compilation error when cfg(debug_assertions) is not active. wgpu-core v29.0.2 has been yanked. By @Elabajaba in #9352.

v29.0.3

Compare

Choose a tag to compare

Bug Fixes

General

• Fix late bindings not being updated for identical pipeline layouts. By @kristoff3r in #9341.

• Fix missing dependency feature activations when building wgpu-hal with gles/dx12 in isolation. By @Wumpf in #9325.

• Make wgpu_types::texture::format::TextureChannel accessible as wgpu::TextureChannel. By @TornaxO7 in #9349.

DX12

• Fixed a debug_assert during stride validation for indirect multi draw. By @kristoff3r in #9332.
• Fix incorrect max_binding_array_sampler_elements_per_shader_stage limit reported on DX12. By @kristoff3r in #9330.

Vulkan

• Only request shaderDrawParameters when SHADER_DRAW_INDEX is requested, avoiding device creation failures on drivers that don't support it (e.g. V3DV, SwiftShader). By @mohamedtahaguelzim in #9331.

Metal

• Fix crash on fence creation when running in a MacOS sandbox. By @Wumpf in #9415.

Bug Fixes

General

• Fix late bindings not being updated for identical pipeline layouts. By @kristoff3r in #9341.

• Fix missing dependency feature activations when building wgpu-hal with gles/dx12 in isolation. By @wumpf in #9325.

• Make wgpu_types::texture::format::TextureChannel accessible as wgpu::TextureChannel. By @TornaxO7 in #9349.

DX12

• Fixed a debug_assert during stride validation for indirect multi draw. By @kristoff3r in #9332.
• Fix incorrect max_binding_array_sampler_elements_per_shader_stage limit reported on DX12. By @kristoff3r in #9330.

Vulkan

• Only request shaderDrawParameters when SHADER_DRAW_INDEX is requested, avoiding device creation failures on drivers that don't support it (e.g. V3DV, SwiftShader). By @mohamedtahaguelzim in #9331.

Metal

• Fix crash on fence creation when running in a MacOS sandbox. By @wumpf in #9415.

v29.0.2

Compare

Choose a tag to compare

Major Changes

Surface::get_current_texture now returns CurrentSurfaceTexture enum

Surface::get_current_texture no longer returns Result<SurfaceTexture, SurfaceError>. Instead, it returns a single CurrentSurfaceTexture enum that represents all possible outcomes as variants. SurfaceError has been removed, and the suboptimal field on SurfaceTexture has been replaced by a dedicated Suboptimal variant.

match surface.get_current_texture() {
    wgpu::CurrentSurfaceTexture::Success(frame) => { /* render */ }
    wgpu::CurrentSurfaceTexture::Timeout
      | wgpu::CurrentSurfaceTexture::Occluded => { /* skip frame */ }
    wgpu::CurrentSurfaceTexture::Outdated
      | wgpu::CurrentSurfaceTexture::Suboptimal(frame) => { /* reconfigure surface */ }
    wgpu::CurrentSurfaceTexture::Lost => { /* reconfigure surface, or recreate device if device lost */ }
    wgpu::CurrentSurfaceTexture::Validation => {
        /* Only happens if there is a validation error and you
           have registered a error scope or uncaptured error handler. */
    }
}

By @cwfitzgerald, @Wumpf, and @emilk in #9141 and #9257.

InstanceDescriptor initialization APIs and display handle changes

A display handle represents a connection to the platform's display server (e.g. a Wayland or X11 connection on Linux). This is distinct from a window — a display handle is the system-level connection through which windows are created and managed.

InstanceDescriptor's convenience constructors (an implementation of Default and the static from_env_or_default method) have been removed. In their place are new static methods that force recognition of whether a display handle is used:

• new_with_display_handle
• new_with_display_handle_from_env
• new_without_display_handle
• new_without_display_handle_from_env

If you are using winit, this can be populated using EventLoop::owned_display_handle.

- InstanceDescriptor::default();
- InstanceDescriptor::from_env_or_default();
+ InstanceDescriptor::new_with_display_handle(Box::new(event_loop.owned_display_handle()));
+ InstanceDescriptor::new_with_display_handle_from_env(Box::new(event_loop.owned_display_handle()));

Additionally, DisplayHandle is now optional when creating a surface if a display handle was already passed to InstanceDescriptor. This means that once you've provided the display handle at instance creation time, you no longer need to pass it again for each surface you create.

By @MarijnS95 in #8782

Bind group layouts now optional in PipelineLayoutDescriptor

This allows gaps in bind group layouts and adds full support for unbinding, bring us in compliance with the WebGPU spec. As a result of this PipelineLayoutDescriptor's bind_group_layouts field now has type of &[Option<&BindGroupLayout>]. To migrate wrap bind group layout references in Some:

  let pl_desc = wgpu::PipelineLayoutDescriptor {
      label: None,
      bind_group_layouts: &[
-         &bind_group_layout
+         Some(&bind_group_layout)
      ],
      immediate_size: 0,
  });

By @teoxoy in #9034.

MSRV update

wgpu now has a new MSRV policy. This release has an MSRV of 1.87. This is lower than v27's 1.88 and v28's 1.92. Going forward, we will only bump wgpu's MSRV if it has tangible benefits for the code, and we will never bump to an MSRV higher than stable - 3. So if stable is at 1.97 and 1.94 brought benefit to our code, we could bump it no higher than 1.94. As before, MSRV bumps will always be breaking changes.

By @cwfitzgerald in #8999.

WriteOnly

To ensure memory safety when accessing mapped GPU memory, MapMode::Write buffer mappings (BufferViewMut and also QueueWriteBufferView) can no longer be dereferenced to Rust &mut [u8]. Instead, they must be used through the new pointer type wgpu::WriteOnly<[u8]>, which does not allow reading at all.

WriteOnly<[u8]> is designed to offer similar functionality to &mut [u8] and have almost no performance overhead, but you will probably need to make some changes for anything more complicated than get_mapped_range_mut().copy_from_slice(my_data); in particular, replacing view[start..end] with view.slice(start..end).

By @kpreid in #9042.

Depth/stencil state changes

The depth_write_enabled and depth_compare members of DepthStencilState are now optional, and may be omitted when they do not apply, to match WebGPU.

depth_write_enabled is applicable, and must be Some, if format has a depth aspect, i.e., is a depth or depth/stencil format. Otherwise, a value of None best reflects that it does not apply, although Some(false) is also accepted.

depth_compare is applicable, and must be Some, if depth_write_enabled is Some(true), or if depth_fail_op for either stencil face is not Keep. Otherwise, a value of None best reflects that it does not apply, although Some(CompareFunction::Always) is also accepted.

There is also a new constructor DepthStencilState::stencil which may be used instead of a struct literal for stencil operations.

Example 1: A configuration that does a depth test and writes updated values:

 depth_stencil: Some(wgpu::DepthStencilState {
     format: wgpu::TextureFormat::Depth32Float,
-    depth_write_enabled: true,
-    depth_compare: wgpu::CompareFunction::Less,
+    depth_write_enabled: Some(true),
+    depth_compare: Some(wgpu::CompareFunction::Less),
     stencil: wgpu::StencilState::default(),
     bias: wgpu::DepthBiasState::default(),
 }),

Example 2: A configuration with only stencil:

 depth_stencil: Some(wgpu::DepthStencilState {
     format: wgpu::TextureFormat::Stencil8,
-    depth_write_enabled: false,
-    depth_compare: wgpu::CompareFunction::Always,
+    depth_write_enabled: None,
+    depth_compare: None,
     stencil: wgpu::StencilState::default(),
     bias: wgpu::DepthBiasState::default(),
 }),

Example 3: The previous example written using the new stencil() constructor:

depth_stencil: Some(wgpu::DepthStencilState::stencil(
    wgpu::TextureFormat::Stencil8,
    wgpu::StencilState::default(),
)),

D3D12 Agility SDK support

Added support for loading a specific DirectX 12 Agility SDK runtime via the Independent Devices API. The Agility SDK lets applications ship a newer D3D12 runtime alongside their binary, unlocking the latest D3D12 features without waiting for an OS update.

Configure it programmatically:

let options = wgpu::Dx12BackendOptions {
    agility_sdk: Some(wgpu::Dx12AgilitySDK {
        sdk_version: 619,
        sdk_path: "path/to/sdk/bin/x64".into(),
    }),
    ..Default::default()
};

Or via environment variables:

WGPU_DX12_AGILITY_SDK_PATH=path/to/sdk/bin/x64
WGPU_DX12_AGILITY_SDK_VERSION=619

The sdk_version must match the version of the D3D12Core.dll in the provided path exactly, or loading will fail.

If the Agility SDK fails to load (e.g. version mismatch, missing DLL, or unsupported OS), wgpu logs a warning and falls back to the system D3D12 runtime.

By @cwfitzgerald in #9130.

primitive_index is now a WGSL enable extension

WGSL shaders using @builtin(primitive_index) must now request it with enable primitive_index;. The SHADER_PRIMITIVE_INDEX feature has been renamed to PRIMITIVE_INDEX and moved from FeaturesWGPU to FeaturesWebGPU. By @inner-daemons in #8879 and @andyleiserson in #9101.

- device.features().contains(wgpu::FeaturesWGPU::SHADER_PRIMITIVE_INDEX)
+ device.features().contains(wgpu::FeaturesWebGPU::PRIMITIVE_INDEX)

// WGSL shaders must now include this directive:
enable primitive_index;

maxInterStageShaderComponents replaced by maxInterStageShaderVariables

Migrated from the max_inter_stage_shader_components limit to max_inter_stage_shader_variables, following the latest WebGPU spec. Components counted individual scalars (e.g. a vec4 = 4 components), while variables counts locations (e.g. a vec4 = 1 variable). This changes validation in a way that should not affect most programs. By @ErichDonGubler in #8652, #8792.

- limits.max_inter_stage_shader_components
+ limits.max_inter_stage_shader_variables

Other Breaking Changes

• Use clearer field names for StageError::InvalidWorkgroupSize. By @ErichDonGubler in #9192.

New Features

General

• Added TLAS binding array support via ACCELERATION_STRUCTURE_BINDING_ARRAY. By @kvark in #8923.
• Added wgpu-naga-bridge crate with conversions between naga and wgpu-types (features to capabilities, storage format mapping, shader stage mapping). By @atlv24 in #9201.
• Added support for cooperative load/store operations in shaders. Currently only WGSL on the input and SPIR-V, METAL, and WGSL on the output are supported. By @kvark in #8251.
• Added support for per-vertex attributes in fragment shaders. Currently only WGSL input is supported, and only SPIR-V or WGSL output is supported. By @atlv24 in #8821.
• Added support for no-perspective barycentric coordinates. By @atlv24 in #8852.
• Added support for obtaining AdapterInfo from Device. By @sagudev in #8807.
• Added Limits::or_worse_values_from. By @atlv24 in #8870.
• Added Features::FLOAT32_BLENDABLE on Vulkan and Metal. By @timokoesters in #8963 and @andyleiserson in #9032.
• Added Dx12BackendOptions::force_shader_model to allow using advanced features in passthrough shaders without bundling DXC. By @inner-daemons in #8984.
• Changed passthrough shaders to not require an entry point parameter, so that the same shader module may be used in multiple entry points. Also added support for metallib passthrough. By @inner-daemons in #8886.
• Added Dx12Compiler::Auto to automatically use static or dynamic DXC if available, before falling back to FXC. By @inner-daemons in #8882.
• Added support for insert_debug_marker, push_debug_group and pop_debug_group on WebGPU. By @evilpie in #9017.
• Added support for @builtin(draw_index) to the vulkan backend. By @inner-daemons in #8883.
• Added TextureFormat::channels method to get some information about which color channels are covered by the texture format. By @TornaxO7 in #9167
• BREAKING: Add V6_8 variant to DxcShaderModel and naga::back::hlsl::ShaderModel. By @inner-daemons in #8882 and @ErichDonGubler in #9083.
• BREAKING: Add V6_9 variant to DxcShaderModel and naga::back::hlsl::ShaderModel. By @ErichDonGubler in #9083.

naga

• Initial wgsl-in ray tracing pipelines. By @Vecvec in #8570.
• wgsl-out ray tracing pipelines. By @Vecvec in #8970.
• Allow parsing shaders which make use of SPV_KHR_non_semantic_info for debug info. Also removes naga::front::spv::SUPPORTED_EXT_SETS. By @inner-daemons in #8827.
• Added memory decorations for storage buffers: coherent, supported on all native backends, and volatile, only on Vulkan and GL. By @atlv24 in #9168.
• Made the following available in const contexts; by @ErichDonGubler in #8943:
  • naga
    • Arena::len
    • Arena::is_empty
    • Range::first_and_last
    • front::wgsl::Frontend::set_options
    • ir::Block::is_empty
    • ir::Block::len

GLES

• Added GlDebugFns option in GlBackendOptions to control OpenGL debug functions (glPushDebugGroup, glPopDebugGroup, glObjectLabel, etc.). Automatically disables them on Mali GPUs to work around a driver crash. By @Xavientois in #8931.

WebGPU

• Added support for insert_debug_marker, push_debug_group and pop_debug_group. By @evilpie in #9017.
• Added support for begin_occlusion_query and end_occlusion_query. By @evilpie in #9039.

Changes

General

• Tracing now uses the .metal extension for metal source files, instead of .msl. By @inner-daemons in #8880.
• BREAKING: Several error APIs were changed by @ErichDonGubler in #9073 and #9205:
  • BufferAccessError:
    • Split the OutOfBoundsOverrun variant into new OutOfBoundsStartOffsetOverrun and OutOfBoundsEndOffsetOverrun variants.
    • Removed the NegativeRange variant in favor of new MapStartOffsetUnderrun and MapStartOffsetOverrun variants.
  • Split the TransferError::BufferOverrun variant into new BufferStartOffsetOverrun and BufferEndOffsetOverrun variants.
  • ImmediateUploadError:
    • Removed the TooLarge variant in favor of new StartOffsetOverrun and EndOffsetOverrun variants.
    • Removed the Unaligned variant in favor of new StartOffsetUnaligned and SizeUnaligned variants.
    • Added the ValueStartIndexOverrun and ValueEndIndexOverrun invariants
• The various "max resources per stage" limits are now capped at 100, so that their total remains below max_bindings_per_bind_group, as required by WebGPU. By @andyleiserson in #9118.
• The max_uniform_buffer_binding_size and max_storage_buffer_binding_size limits are now u64 instead of u32, to match WebGPU. By @wingertge in #9146.
• The main 3 native backends now report their limits properly. By @teoxoy in #9196.

naga

• Naga and wgpu now reject shaders with an enable directive for functionality that is not available, even if that functionality is not used by the shader. By @andyleiserson in #8913.
• Prevent UB from incorrectly using ray queries on HLSL. By @Vecvec in #8763.
• Added support for dual-source blending in SPIR-V shaders. By @andyleiserson in #8865.
• Added supported_capabilities to all backends. By @inner-daemons in #9068.
• Updated codespan-reporting to 0.13. By @cwfitzgerald in #9243.

Metal

• Use autogenerated objc2 bindings internally, which should resolve a lot of leaks and unsoundness. By @madsmtm in #5641.
• Implements ray-tracing acceleration structures for metal backend. By @lichtso in #8071.
• Remove mutex for MTLCommandQueue because the Metal object is thread-safe. By @andyleiserson in #9217.

deno_webgpu

• Expose the GPU.wgslLanguageFeatures property. By @andyleiserson in #8884.
• GPUFeatureName now includes all wgpu extensions. Feature names for extensions should be written with a wgpu- prefix, although unprefixed names that were accepted previously are still accepted. By @andyleiserson in #9163.

Hal

• Make ordered texture and buffer uses hal specific. By @NiklasEi in #8924.

Bug Fixes

General

• Tracing support has been restored. By @andyleiserson in #8429.
• Pipelines using passthrough shaders now correctly require explicit pipeline layout. By @inner-daemons in #8881.
• Allow using a shader that defines I/O for dual-source blending in a pipeline that does not make use of it. By @andyleiserson in #8856.
• Improve validation of dual-source blending, by @andyleiserson in #9200:
  • Validate structs with @blend_src members whether or not they are used by an entry point.
  • Dual-source blending is not supported when there are multiple color attachments.
  • TypeFlags::IO_SHAREABLE is not set for structs other than @blend_src structs.
• Validate strip_index_format isn't None and equals index buffer format for indexed drawing with strip topology. By @beicause in #8850.
• BREAKING: Renamed EXPERIMENTAL_PASSTHROUGH_SHADERS to PASSTHROUGH_SHADERS and made this no longer an experimental feature. By @inner-daemons in #9054.
• BREAKING: End offsets in trace and player commands are now represented using offset + size instead. By @ErichDonGubler in #9073.
• Validate some uncaught cases where buffer transfer operations could overflow when computing an end offset. By @ErichDonGubler in #9073.
• Fix local_invocation_id and local_invocation_index being written multiple times in HLSL/MSL backends, and naming conflicts when users name variables __local_invocation_id or __local_invocation_index. By @inner-daemons in #9099.
• Added internal labels to validation GPU objects and timestamp normalization code to improve clarity in graphics debuggers. By @szostid in #9094
• Fix multi-planar texture copying. By @noituri in #9069

naga

• The validator checks that override-sized arrays have a positive size, if overrides have been resolved. By @andyleiserson in #8822.
• Fix some cases where f16 constants were not working. By @andyleiserson in #8816.
• Use wrapping arithmetic when evaluating constant expressions involving u32. By @andyleiserson in #8912.
• Fix missing side effects from sequence expressions in GLSL. By @Vipitis in #8787.
• Naga now enforces the @must_use attribute on WGSL built-in functions, when applicable. You can waive the error with a phony assignment, e.g., _ = subgroupElect(). By @andyleiserson in #8713.
• Reject zero-value construction of a runtime-sized array with a validation error. Previously it would crash in the HLSL backend. By @mooori in #8741.
• Reject splat vector construction if the argument type does not match the type of the vector's scalar. Previously it would succeed. By @mooori in #8829.
• Fixed workgroupUniformLoad incorrectly returning an atomic when called on an atomic, it now returns the inner T as per the spec. By @cryvosh in #8791.
• Fixed constant evaluation for sign() builtin to return zero when the argument is zero. By @mandryskowski in #8942.
• Allow array generation to compile with the macOS 10.12 Metal compiler. By @madsmtm in #8953
• Naga now detects bitwise shifts by a constant exceeding the operand bit width at compile time, and disallows scalar-by-vector and vector-by-scalar shifts in constant evaluation. By @andyleiserson in #8907.
• Naga uses wrapping arithmetic when evaluating dot products on concrete integer types (u32 and i32). By @BKDaugherty in #9142.
• Disallow negation of a matrix in WGSL. By @andyleiserson in #9157.
• Fix evaluation order of compound assignment (e.g. +=) LHS and RHS. By @andyleiserson in #9181.
• Fixed invalid MSL when float16-format vertex input data was accessed via an f16-type variable in a vertex shader. By @andyleiserson in #9166.

Validation

• Fixed validation of the texture format in GPUDepthStencilState when neither depth nor stencil is actually enabled. By @andyleiserson in #8766.
• Check that depth bias is not used with non-triangle topologies. By @andyleiserson in #8856.
• Check that if the shader outputs frag_depth, then the pipeline must have a depth attachment. By @andyleiserson in #8856.
• Fix incorrect acceptance of some swizzle selectors that are not valid for their operand, e.g. const v = vec2<i32>(); let r = v.xyz. By @andyleiserson in #8949.
• Fixed calculation of the total number of bindings in a pipeline layout when validating against device limits. By @andyleiserson in #8997.
• Reject non-constructible types (runtime- and override-sized arrays, and structs containing non-constructible types) in more places where they should not be allowed. By @andyleiserson in #8873.
• The query set type for an occlusion query is now validated when opening the render pass, in addition to within the call to beginOcclusionQuery. By @andyleiserson in #9086.
• Require that the blend factor is One when the blend operation is Min or Max. The BlendFactorOnUnsupportedTarget error is now reported within ColorStateError rather than directly in CreateRenderPipelineError. By @andyleiserson in #9110.

Vulkan

• Fixed a variety of mesh shader SPIR-V writer issues from the original implementation. By @inner-daemons in #8756
• Offset the vertex buffer device address when building a BLAS instead of using the first_vertex field. By @Vecvec in #9220
• Remove incorrect ordered texture uses. By @NiklasEi in #8924.

Metal / macOS

• Fix one-second delay when switching a wgpu app to the foreground. By @emilk in #9141
• Work around Metal driver bug with atomic textures. By @atlv24 in #9185
• Fix setting an immediate for a Mesh shader. By @waywardmonkeys in #9254

GLES

• DisplayHandle should now be passed to InstanceDescriptor for correct EGL initialization on Wayland. By @MarijnS95 in #8012 Note that the existing workaround to create surfaces before the adapter is no longer valid.
• Changing shader constants now correctly recompiles the shader. By @DerSchmale in #8291.

Performance

GLES

• The GL backend would now try to take advantage of GL_EXT_multisampled_render_to_texture extension when applicable to skip the multi-sample resolve operation. By @opstic in #8536.

Documentation

General

• Expanded documentation of QuerySet, QueryType, and resolve_query_set() describing how to use queries. By @kpreid in #8776.

v29.0.0

Compare

Choose a tag to compare

Major Changes

Mesh Shaders

This has been a long time coming. See the tracking issue for more information. They are now fully supported on Vulkan, and supported on Metal and DX12 with passthrough shaders. WGSL parsing and rewriting is supported, meaning they can be used through WESL or naga_oil.

Mesh shader pipelines replace the standard vertex shader pipelines and allow new ways to render meshes. They are ideal for meshlet rendering, a form of rendering where small groups of triangles are handled together, for both culling and rendering.

They are compute-like shaders, and generate primitives which are passed directly to the rasterizer, rather than having a list of vertices generated individually and then using a static index buffer. This means that certain computations on nearby groups of triangles can be done together, the relationship between vertices and primitives is more programmable, and you can even pass non-interpolated per-primitive data to the fragment shader, independent of vertices.

Mesh shaders are very versatile, and are powerful enough to replace vertex shaders, tesselation shaders, and geometry shaders on their own or with task shaders.

A full example of mesh shaders in use can be seen in the mesh_shader example. For the full specification of mesh shaders in wgpu, go to docs/api-specs/mesh_shading.md. Below is a small snippet of shader code demonstrating their usage:

@task
@payload(taskPayload)
@workgroup_size(1)
fn ts_main() -> @builtin(mesh_task_size) vec3<u32> {
    // Task shaders can use workgroup variables like compute shaders
    workgroupData = 1.0;
    // Pass some data to all mesh shaders dispatched by this workgroup
    taskPayload.colorMask = vec4(1.0, 1.0, 0.0, 1.0);
    taskPayload.visible = 1;
    // Dispatch a mesh shader grid with one workgroup
    return vec3(1, 1, 1);
}

@mesh(mesh_output)
@payload(taskPayload)
@workgroup_size(1)
fn ms_main(@builtin(local_invocation_index) index: u32, @builtin(global_invocation_id) id: vec3<u32>) {
    // Set how many outputs this workgroup will generate
    mesh_output.vertex_count = 3;
    mesh_output.primitive_count = 1;
    // Can also use workgroup variables
    workgroupData = 2.0;

    // Set vertex outputs
    mesh_output.vertices[0].position = positions[0];
    mesh_output.vertices[0].color = colors[0] * taskPayload.colorMask;

    mesh_output.vertices[1].position = positions[1];
    mesh_output.vertices[1].color = colors[1] * taskPayload.colorMask;

    mesh_output.vertices[2].position = positions[2];
    mesh_output.vertices[2].color = colors[2] * taskPayload.colorMask;

    // Set the vertex indices for the only primitive
    mesh_output.primitives[0].indices = vec3<u32>(0, 1, 2);
    // Cull it if the data passed by the task shader says to
    mesh_output.primitives[0].cull = taskPayload.visible == 1;
    // Give a noninterpolated per-primitive vec4 to the fragment shader
    mesh_output.primitives[0].colorMask = vec4<f32>(1.0, 0.0, 1.0, 1.0);
}

Thanks

This was a monumental effort from many different people, but it was championed by @inner-daemons, without whom it would not have happened. Thank you @cwfitzgerald for doing the bulk of the code review. Finally thank you @ColinTimBarndt for coordinating the testing effort.

Reviewers:

• @cwfitzgerald
• @jimblandy
• @ErichDonGubler

wgpu Contributions:

• Metal implementation in wgpu-hal. By @inner-daemons in #8139.
• DX12 implementation in wgpu-hal. By @inner-daemons in #8110.
• Vulkan implementation in wgpu-hal. By @inner-daemons in #7089.
• wgpu/wgpu-core implementation. By @inner-daemons in #7345.
• New mesh shader limits and validation. By @inner-daemons in #8507.

naga Contributions:

• Naga IR implementation. By @inner-daemons in #8104.
• wgsl-in implementation in naga. By @inner-daemons in #8370.
• spv-out implementation in naga. By @inner-daemons in #8456.
• wgsl-out implementation in naga. By @Slightlyclueless in #8481.
• Allow barriers in mesh/task shaders. By @inner-daemons in #8749

Testing Assistance:

• @ColinTimBarndt
• @AdamK2003
• @Mhowser
• @9291Sam
• 3 more testers who wished to remain anonymous.

Thank you to everyone to made this happen!

Switch from gpu-alloc to gpu-allocator in the vulkan backend

gpu-allocator is the allocator used in the dx12 backend, allowing to configure the allocator the same way in those two backends converging their behavior.

This also brings the Device::generate_allocator_report feature to the vulkan backend.

By @DeltaEvo in #8158.

wgpu::Instance::enumerate_adapters is now async & available on WebGPU

BREAKING CHANGE: enumerate_adapters is now async:

- pub fn enumerate_adapters(&self, backends: Backends) -> Vec<Adapter> {
+ pub fn enumerate_adapters(&self, backends: Backends) -> impl Future<Output = Vec<Adapter>> {

This yields two benefits:

• This method is now implemented on non-native using the standard Adapter::request_adapter(…), making enumerate_adapters a portable surface. This was previously a nontrivial pain point when an application wanted to do some of its own filtering of adapters.
• This method can now be implemented in custom backends.

By @R-Cramer4 in #8230

New LoadOp::DontCare

In the case where a renderpass unconditionally writes to all pixels in the rendertarget, Load can cause unnecessary memory traffic, and Clear can spend time unnecessarily clearing the rendertargets. DontCare is a new LoadOp which will leave the contents of the rendertarget undefined. Because this could lead to undefined behavior, this API requires that the user gives an unsafe token to use the api.

While you can use this unconditionally, on platforms where DontCare is not available, it will internally use a different load op.

load: LoadOp::DontCare(unsafe { wgpu::LoadOpDontCare::enabled() })

By @cwfitzgerald in #8549

MipmapFilterMode is split from FilterMode

This is a breaking change that aligns wgpu with spec.

SamplerDescriptor {
...
-     mipmap_filter: FilterMode::Nearest
+     mipmap_filter: MipmapFilterMode::Nearest
...
}

By @sagudev in #8314.

Multiview on all major platforms and support for multiview bitmasks

Multiview is a feature that allows rendering the same content to multiple layers of a texture. This is useful primarily in VR where you wish to display almost identical content to 2 views, just with a different perspective. Instead of using 2 draw calls or 2 instances for each object, you can use this feature.

Multiview is also called view instancing in DX12 or vertex amplification in Metal.

Multiview has been reworked, adding support for Metal and DX12, and adding testing and validation to wgpu itself. This change also introduces a view bitmask, a new field in RenderPassDescriptor that allows a render pass to render to multiple non-adjacent layers when using the SELECTIVE_MULTIVIEW feature. If you don't use multi-view, you can set this field to none.

- wgpu::RenderPassDescriptor {
-     label: None,
-     color_attachments: &color_attachments,
-     depth_stencil_attachment: None,
-     timestamp_writes: None,
-     occlusion_query_set: None,
- }
+ wgpu::RenderPassDescriptor {
+     label: None,
+     color_attachments: &color_attachments,
+     depth_stencil_attachment: None,
+     timestamp_writes: None,
+     occlusion_query_set: None,
+     multiview_mask: NonZero::new(3),
+ }

One other breaking change worth noting is that in WGSL @builtin(view_index) now requires a type of u32, where previously it required i32.

By @inner-daemons in #8206.

Error scopes now use guards and are thread-local.

- device.push_error_scope(wgpu::ErrorFilter::Validation);
+ let scope = device.push_error_scope(wgpu::ErrorFilter::Validation);
  // ... perform operations on the device ...
- let error: Option<Error> = device.pop_error_scope().await;
+ let error: Option<Error> = scope.pop().await;

Device error scopes now operate on a per-thread basis. This allows them to be used easily within multithreaded contexts, without having the error scope capture errors from other threads.

When the std feature is not enabled, we have no way to differentiate between threads, so error scopes return to be global operations.

By @cwfitzgerald in #8685

Log Levels

We have received complaints about wgpu being way too log spammy at log levels info/warn/error. We have adjusted our log policy and changed logging such that info and above should be silent unless some exceptional event happens. Our new log policy is as follows:

• Error: if we can’t (for some reason, usually a bug) communicate an error any other way.
• Warning: similar, but there may be one-shot warnings about almost certainly sub-optimal.
• Info: do not use
• Debug: Used for interesting events happening inside wgpu.
• Trace: Used for all events that might be useful to either wgpu or application developers.

By @cwfitzgerald in #8579.

Push constants renamed immediates, API brought in line with spec.

As the "immediate data" api is getting close to stabilization in the WebGPU specification, we're bringing our implementation in line with what the spec dictates.

First, in the PipelineLayoutDescriptor, you now pass a unified size for all stages:

- push_constant_ranges: &[wgpu::PushConstantRange {
-     stages: wgpu::ShaderStages::VERTEX_FRAGMENT,
-     range: 0..12,
- }]
+ immediate_size: 12,

Second, on the command encoder you no longer specify a shader stage, uploads apply to all shader stages that use immediate data.

- rpass.set_push_constants(wgpu::ShaderStages::FRAGMENT, 0, bytes);
+ rpass.set_immediates(0, bytes);

Third, immediates are now declared with the immediate address space instead of the push_constant address space. Due to a known issue on DX12 it is advised to always use a structure for your immediates until that issue is fixed.

- var<push_constant> my_pc: MyPushConstant;
+ var<immediate> my_imm: MyImmediate;

Finally, our implementation currently still zero-initializes the immediate data range you declared in the pipeline layout. This is not spec compliant and failing to populate immediate "slots" that are used in the shader will be a validation error in a future version. See the proposal for details for determining which slots are populated in a given shader.

By @cwfitzgerald in #8724.

subgroup_{min,max}_size renamed and moved from Limits -> AdapterInfo

To bring our code in line with the WebGPU spec, we have moved information about subgroup size from limits to adapter info. Limits was not the correct place for this anyway, and we had some code special casing those limits.

Additionally we have renamed the fields to match the spec.

- let min = limits.min_subgroup_size;
+ let min = info.subgroup_min_size;
- let max = limits.max_subgroup_size;
+ let max = info.subgroup_max_size;

By @cwfitzgerald in #8609.

New Features

• Added support for transient textures on Vulkan and Metal. By @opstic in #8247
• Implement shader triangle barycentric coordinate builtins. By @atlv24 in #8320.
• Added support for binding arrays of storage textures on Metal. By @msvbg in #8464
• Added support for multisampled texture arrays on Vulkan through adapter feature MULTISAMPLE_ARRAY. By @LaylBongers in #8571.
• Added get_configuration to wgpu::Surface, that returns the current configuration of wgpu::Surface. By @sagudev in #8664.
• Add wgpu_core::Global::create_bind_group_layout_error. By @ErichDonGubler in #8650.

Changes

General

• Require new enable extensions when using ray queries and position fetch (wgpu_ray_query, wgpu_ray_query_vertex_return). By @Vecvec in #8545.
• Texture now has from_custom. By @R-Cramer4 in #8315.
• Using both the wgpu command encoding APIs and CommandEncoder::as_hal_mut on the same encoder will now result in a panic.
• Allow include_spirv! and include_spirv_raw! macros to be used in constants and statics. By @clarfonthey in #8250.
• Added support for rendering onto multi-planar textures. By @noituri in #8307.
• Validation errors from CommandEncoder::finish() will report the label of the invalid encoder. By @kpreid in #8449.
• Corrected documentation of the minimum alignment of the end of a mapped range of a buffer (it is 4, not 8). By @kpreid in #8450.
• util::StagingBelt now takes a Device when it is created instead of when it is used. By @kpreid in #8462.
• wgpu_hal::vulkan::Texture API changes to handle externally-created textures and memory more flexibly. By @s-ol in #8512, #8521.
• Render passes are now validated against the maxColorAttachmentBytesPerSample limit. By @andyleiserson in #8697.

Metal

• Expose render layer. By @xiaopengli89 in #8707
• MTLDevice is thread-safe. By @uael in #8168

naga

• Prevent UB with invalid ray query calls on spirv. By @Vecvec in #8390.
• Update the set of binding_array capabilities. In most cases, they are set automatically from wgpu features, and this change should not be user-visible. By @andyleiserson in #8671.
• Naga now accepts the var<function> syntax for declaring local variables. By @andyleiserson in #8710.

Bug Fixes

General

• Fixed a bug where mapping sub-ranges of a buffer on web would fail with OperationError: GPUBuffer.getMappedRange: GetMappedRange range extends beyond buffer's mapped range. By @ryankaplan in #8349
• Reject fragment shader output locations > max_color_attachments limit. By @ErichDonGubler in #8316.
• WebGPU device requests now support the required limits maxColorAttachments and maxColorAttachmentBytesPerSample. By @evilpie in #8328
• Reject binding indices that exceed wgpu_types::Limits::max_bindings_per_bind_group when deriving a bind group layout for a pipeline. By @jimblandy in #8325.
• Removed three features from wgpu-hal which did nothing useful: "cargo-clippy", "gpu-allocator", and "rustc-hash". By @kpreid in #8357.
• wgpu_types::PollError now always implements the Error trait. By @kpreid in #8384.
• The texture subresources used by the color attachments of a render pass are no longer allowed to overlap when accessed via different texture views. By @andyleiserson in #8402.
• The STORAGE_READ_ONLY texture usage is now permitted to coexist with other read-only usages. By @andyleiserson in #8490.
• Validate that buffers are unmapped in write_buffer calls. By @ErichDonGubler in #8454.
• Shorten critical section inside present such that the snatch write lock is no longer held during present, preventing other work happening on other threads. By @cwfitzgerald in #8608.

naga

• The || and && operators now "short circuit", i.e., do not evaluate the RHS if the result can be determined from just the LHS. By @andyleiserson in #7339.
• Fix a bug that resulted in the Metal error program scope variable must reside in constant address space in some cases. By @teoxoy in #8311.
• Handle rayQueryTerminate in spv-out instead of ignoring it. By @Vecvec in #8581.

DX12

• Align copies b/w textures and buffers via a single intermediate buffer per copy when D3D12_FEATURE_DATA_D3D12_OPTIONS13.UnrestrictedBufferTextureCopyPitchSupported is false. By @ErichDonGubler in #7721.
• Fix detection of Int64 Buffer/Texture atomic features. By @cwfitzgerald in #8667.

Vulkan

• Fixed a validation error regarding atomic memory semantics. By @atlv24 in #8391.

Metal

• Fixed a variety of feature detection related bugs. By @inner-daemons in #8439.

WebGPU

• Fixed a bug where the texture aspect was not passed through when calling copy_texture_to_buffer in WebGPU, causing the copy to fail for depth/stencil textures. By @Tim-Evans-Seequent in #8445.

GLES

• Fix race when downloading texture from compute shader pass. By @SpeedCrash100 in #8527
• Fix double window class registration when dynamic libraries are used. By @Azorlogh in #8548
• Fix context loss on device initialization on GL3.3-4.1 contexts. By @cwfitzgerald in #8674.
• VertexFormat::Unorm10_10_10_2 can now be used on gl backends. By @mooori in #8717.

hal

• DropCallbacks are now called after dropping all other fields of their parent structs. By @jerzywilczek in #8353

v28.0.0 - Mesh Shaders, Immediates, and More!

Compare

Choose a tag to compare

Major Changes

Deferred command buffer actions: map_buffer_on_submit and on_submitted_work_done

You may schedule buffer mapping and a submission-complete callback to run automatically after you submit, directly from encoders, command buffers, and passes.

// Record some GPU work so the submission isn't empty and touches `buffer`.
encoder.clear_buffer(&buffer, 0, None);

// Defer mapping until this encoder is submitted.
encoder.map_buffer_on_submit(&buffer, wgpu::MapMode::Read, 0..size, |result| { .. });

// Fires after the command buffer's work is finished.
encoder.on_submitted_work_done(|| { .. });

// Automatically calls `map_async` and `on_submitted_work_done` after this submission finishes.
queue.submit([encoder.finish()]);

Available on CommandEncoder, CommandBuffer, RenderPass, and ComputePass.

By @cwfitzgerald in #8125.

Builtin Support for DXGI swapchains on top of of DirectComposition Visuals in DX12

By enabling DirectComposition support, the dx12 backend can now support transparent windows.

This creates a single IDCompositionVisual over the entire window that is used by the mfSurface. If a user wants to manage the composition tree themselves, they should create their own device and composition, and pass the relevant visual down into wgpu via SurfaceTargetUnsafe::CompositionVisual.

let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
    backend_options: wgpu::BackendOptions {
        dx12: wgpu::Dx12BackendOptions {
            presentation_system: wgpu::Dx12SwapchainKind::DxgiFromVisual,
            ..
        },
        ..
    },
    ..
});

By @n1ght-hunter in #7550.

EXPERIMENTAL_RAY_TRACING_ACCELERATION_STRUCTURE has been merged into EXPERIMENTAL_RAY_QUERY

We have merged the acceleration structure feature into the RayQuery feature. This is to help work around an AMD driver bug and reduce the feature complexity of ray tracing. In the future when ray tracing pipelines are implemented, if either feature is enabled, acceleration structures will be available.

- Features::EXPERIMENTAL_RAY_TRACING_ACCELERATION_STRUCTURE
+ Features::EXPERIMENTAL_RAY_QUERY

By @Vecvec in #7913.

New EXPERIMENTAL_PRECOMPILED_SHADERS API

We have added Features::EXPERIMENTAL_PRECOMPILED_SHADERS, replacing existing passthrough types with a unified CreateShaderModuleDescriptorPassthrough which allows passing multiple shader codes for different backends. By @SupaMaggie70Incorporated in #7834

Difference for SPIR-V passthrough:

- device.create_shader_module_passthrough(wgpu::ShaderModuleDescriptorPassthrough::SpirV(
-     wgpu::ShaderModuleDescriptorSpirV {
-         label: None,
-         source: spirv_code,
-     },
- ))
+ device.create_shader_module_passthrough(wgpu::ShaderModuleDescriptorPassthrough {
+     entry_point: "main".into(),
+     label: None,
+     spirv: Some(spirv_code),
+     ..Default::default()
})

This allows using precompiled shaders without manually checking which backend's code to pass, for example if you have shaders precompiled for both DXIL and SPIR-V.

Buffer mapping apis no longer have lifetimes

Buffer::get_mapped_range(), Buffer::get_mapped_range_mut(), and Queue::write_buffer_with() now return guard objects without any lifetimes. This makes it significantly easier to store these types in structs, which is useful for building utilities that build the contents of a buffer over time.

- let buffer_mapping_ref: wgpu::BufferView<'_>           = buffer.get_mapped_range(..);
- let buffer_mapping_mut: wgpu::BufferViewMut<'_>        = buffer.get_mapped_range_mut(..);
- let queue_write_with:   wgpu::QueueWriteBufferView<'_> = queue.write_buffer_with(..);
+ let buffer_mapping_ref: wgpu::BufferView               = buffer.get_mapped_range(..);
+ let buffer_mapping_mut: wgpu::BufferViewMut            = buffer.get_mapped_range_mut(..);
+ let queue_write_with:   wgpu::QueueWriteBufferView     = queue.write_buffer_with(..);

By @sagudev in #8046 and @cwfitzgerald in #8070.

EXPERIMENTAL_* features now require unsafe code to enable

We want to be able to expose potentially experimental features to our users before we have ensured that they are fully sound to use. As such, we now require any feature that is prefixed with EXPERIMENTAL to have a special unsafe token enabled in the device descriptor acknowledging that the features may still have bugs in them and to report any they find.

adapter.request_device(&wgpu::DeviceDescriptor {
    features: wgpu::Features::EXPERIMENTAL_MESH_SHADER,
    experimental_features: unsafe { wgpu::ExperimentalFeatures::enabled() }
    ..
})

By @cwfitzgerald in #8163.

Multi-draw indirect is now unconditionally supported when indirect draws are supported

We have removed Features::MULTI_DRAW_INDIRECT as it was unconditionally available on all platforms. RenderPass::multi_draw_indirect is now available if the device supports downlevel flag DownlevelFlags::INDIRECT_EXECUTION.

If you are using spirv-passthrough with multi-draw indirect and gl_DrawID, you can know if MULTI_DRAW_INDIRECT is being emulated by if the Feature::MULTI_DRAW_INDIRECT_COUNT feature is available on the device, this feature cannot be emulated efficicently.

By @cwfitzgerald in #8162.

wgpu::PollType::Wait has now an optional timeout

We removed wgpu::PollType::WaitForSubmissionIndex and added fields to wgpu::PollType::Wait in order to express timeouts.

Before/after for wgpu::PollType::Wait:

-device.poll(wgpu::PollType::Wait).unwrap();
-device.poll(wgpu::PollType::wait_indefinitely()).unwrap();
+device.poll(wgpu::PollType::Wait {
+      submission_index: None, // Wait for most recent submission
+      timeout: Some(std::time::Duration::from_secs(60)), // Previous behavior, but more likely you want `None` instead.
+  })
+  .unwrap();

Before/after for wgpu::PollType::WaitForSubmissionIndex:

-device.poll(wgpu::PollType::WaitForSubmissionIndex(index_to_wait_on))
+device.poll(wgpu::PollType::Wait {
+      submission_index: Some(index_to_wait_on),
+      timeout: Some(std::time::Duration::from_secs(60)), // Previous behavior, but more likely you want `None` instead.
+  })
+  .unwrap();

⚠️ Previously, both wgpu::PollType::WaitForSubmissionIndex and wgpu::PollType::Wait had a hard-coded timeout of 60 seconds.

To wait indefinitely on the latest submission, you can also use the wait_indefinitely convenience function:

device.poll(wgpu::PollType::wait_indefinitely());

By @wumpf in #8282, #8285

New Features

General

• Added mesh shader support to wgpu, with examples. Requires passthrough. By @SupaMaggie70Incorporated in #7345.
• Added support for external textures based on WebGPU's GPUExternalTexture. These allow shaders to transparently operate on potentially multiplanar source texture data in either RGB or YCbCr formats via WGSL's texture_external type. This is gated behind the Features::EXTERNAL_TEXTURE feature, which is currently only supported on DX12. By @jamienicol in #4386.
• wgpu::Device::poll can now specify a timeout via wgpu::PollType::Wait. By @wumpf in #8282 & #8285

naga

• Expose naga::front::wgsl::UnimplementedEnableExtension. By @ErichDonGubler in #8237.

Changes

General

• Command encoding now happens when CommandEncoder::finish is called, not when the individual operations are requested. This does not affect the API, but may affect performance characteristics. By @andyleiserson in #8220.
• Prevent resources for acceleration structures being created if acceleration structures are not enabled. By @Vecvec in #8036.
• Validate that each push_debug_group pairs with exactly one pop_debug_group. By @andyleiserson in #8048.
• set_viewport now requires that the supplied minimum depth value is less than the maximum depth value. By @andyleiserson in #8040.
• Validation of copy_texture_to_buffer, copy_buffer_to_texture, and copy_texture_to_texture operations more closely follows the WebGPU specification. By @andyleiserson in various PRs.
  • Copies within the same texture must not overlap.
  • Copies of multisampled or depth/stencil formats must span an entire subresource (layer).
  • Copies of depth/stencil formats must be 4B aligned.
  • For texture-buffer copies, bytes_per_row on the buffer side must be 256B-aligned, even if the transfer is a single row.
• The offset for set_vertex_buffer and set_index_buffer must be 4B aligned. By @andyleiserson in #7929.
• The offset and size of bindings are validated as fitting within the underlying buffer in more cases. By @andyleiserson in #7911.
• The function you pass to Device::on_uncaptured_error() must now implement Sync in addition to Send, and be wrapped in Arc instead of Box. In exchange for this, it is no longer possible for calling wgpu functions while in that callback to cause a deadlock (not that we encourage you to actually do that). By @kpreid in #8011.
• Make a compacted hal acceleration structure inherit a label from the base BLAS. By @Vecvec in #8103.
• The limits requested for a device must now satisfy min_subgroup_size <= max_subgroup_size. By @andyleiserson in #8085.
• Improve errors when buffer mapping is done incorrectly. Allow aliasing immutable [BufferViews]. By @cwfitzgerald in #8150.
• Require new F16_IN_F32 downlevel flag for quantizeToF16, pack2x16float, and unpack2x16float in WGSL input. By @aleiserson in #8130.
• The error message for non-copyable depth/stencil formats no longer mentions the aspect when it is not relevant. By @reima in #8156.
• Track the initialization status of buffer memory correctly when copy_texture_to_buffer skips over padding space between rows or layers, or when the start/end of a texture-buffer transfer is not 4B aligned. By @andyleiserson in #8099.

naga

• naga now requires that no type be larger than 1 GB. This limit may be lowered in the future; feedback on an appropriate value for the limit is welcome. By @andyleiserson in #7950.
• If the shader source contains control characters, naga now replaces them with U+FFFD ("replacement character") in diagnostic output. By @andyleiserson in #8049.
• Add f16 IO polyfill on Vulkan backend to enable SHADER_F16 use without requiring storageInputOutput16. By @cryvosh in #7884.
• For custom Naga backend authors: naga::proc::Namer now accepts reserved keywords using two new dedicated types, proc::{KeywordSet, CaseInsensitiveKeywordSet}. By @kpreid in #8136.
• BREAKING: Previously the WGSL storage-texture format rg11b10float was incorrectly accepted and generated by naga, but now only accepts the the correct name rg11b10ufloat instead. By @ErikWDev in #8219.
• The source() method of ShaderError no longer reports the error as its own source. By @andyleiserson in #8258.
• naga correctly ingests SPIR-V that use descriptor runtime indexing, which in turn is correctly converted into WGSLs binding array. By @hasenbanck in 8256.
• naga correctly ingests SPIR-V that loads from multi-sampled textures, which in turn is correctly converted into WGSLs texture_multisampled_2d and load operations. By @hasenbanck in 8270.
• naga implement OpImageGather and OpImageDrefGather operations when ingesting SPIR-V. By @hasenbanck in 8280.

DX12

• Allow disabling waiting for latency waitable object. By @marcpabst in #7400
• Add mesh shader support, including to the example. By @SupaMaggie70Incorporated in #8110

Bug Fixes

General

• Validate that effective buffer binding size is aligned to 4 when creating bind groups with buffer entries.. By @ErichDonGubler in 8041.

DX12

• Create an event per wait to prevent 60 second hangs in certain multithreaded scenarios. By @Vecvec in #8273.
• Fixed a bug where access to matrices with 2 rows would not work in some cases. By @andyleiserson in #7438.

EGL

• Fixed unwrap failed in context creation for some Android devices. By @uael in #8024.

Vulkan

• Fixed wrong color format+space being reported versus what is hardcoded in create_swapchain(). By @MarijnS95 in #8226.

naga

• [wgsl-in] Allow a trailing comma in @blend_src(…) attributes. By @ErichDonGubler in #8137.
• [wgsl-in] Allow a trailing comma in the list of case values inside a switch. By @reima in #8165.
• Escape, rather than strip, identifiers with Unicode. By @ErichDonGubler in 7995.

Documentation

General

• Clarify that subgroup barriers require both the SUBGROUP and SUBGROUP_BARRIER features / capabilities. By @andyleiserson in #8203.

v26.0.6 (2025-10-23)

This release includes wgpu-hal version 26.0.6. All other crates remain at their previous versions.

Bug Fixes

Vulkan

• Work around extremely poor frame pacing from AMD and Nvidia cards on Windows in Fifo and FifoRelaxed present modes. This is due to the drivers implicitly using a DXGI (Direct3D) swapchain to implement these modes and it having vastly different timing properties. See https://github.com/gfx-rs/wgpu/issues/8310 and https://github.com/gfx-rs/wgpu/issues/8354 for more information. By @cwfitzgerald in #8420.

Major Features

New method TextureView::texture

You can now call texture_view.texture() to get access to the texture that a given texture view points to.

By @cwfitzgerald and @Wumpf in #7907.

as_hal calls now return guards instead of using callbacks.

Previously, if you wanted to get access to the wgpu-hal or underlying api types, you would call as_hal and get the hal type as a callback. Now the function returns a guard which dereferences to the hal type.

- device.as_hal::<hal::api::Vulkan>(|hal_device| {...});
+ let hal_device: impl Deref<Item = hal::vulkan::Device> = device.as_hal::<hal::api::Vulkan>();

By @cwfitzgerald in #7863.

Enabling Vulkan Features/Extensions

For those who are doing vulkan/wgpu interop or passthrough and need to enable features/extensions that wgpu does not expose, there is a new wgpu_hal::vulkan::Adapter::open_with_callback that allows the user to modify the pnext chains and extension lists populated by wgpu before we create a vulkan device. This should vastly simplify the experience, as previously you needed to create a device yourself.

Underlying api interop is a quickly evolving space, so we welcome all feedback!

type VkApi = wgpu::hal::api::Vulkan;
let adapter: wgpu::Adapter = ...;

let mut buffer_device_address_create_info = ash::vk::PhysicalDeviceBufferDeviceAddressFeatures { .. };
let hal_device: wgpu::hal::OpenDevice<VkApi> = adapter
    .as_hal::<VkApi>()
    .unwrap()
    .open_with_callback(
        wgpu::Features::empty(),
        &wgpu::MemoryHints::Performance,
        Some(Box::new(|args| {
            // Add the buffer device address extension.
            args.extensions.push(ash::khr::buffer_device_address::NAME);
            // Extend the create info with the buffer device address create info.
            *args.create_info = args
                .create_info
                .push_next(&mut buffer_device_address_create_info);
            // We also have access to the queue create infos if we need them.
            let _ = args.queue_create_infos;
        })),
    )
    .unwrap();

let (device, queue) = adapter
    .create_device_from_hal(hal_device, &wgpu::DeviceDescriptor { .. })
    .unwrap();

By @Vecvec in #7829.

naga

• Added no_std support with default features disabled. By @Bushrat011899 in #7585.
• [wgsl-in,ir] Add support for parsing rust-style doc comments via naga::front::glsl::Frontend::new_with_options. By @Vrixyz in #6364.
• When emitting GLSL, Uniform and Storage Buffer memory layouts are now emitted even if no explicit binding is given. By @cloone8 in #7579.
• Diagnostic rendering methods (i.e., naga::{front::wgsl::ParseError,WithSpan}::emit_error_to_string_with_path) now accept more types for their path argument via a new sealed AsDiagnosticFilePath trait. By @atlv24, @bushrat011899, and @ErichDonGubler in #7643.
• Add support for quad operations (requires SUBGROUP feature to be enabled). By @dzamkov and @valaphee in #7683.
• Add support for atomicCompareExchangeWeak in HLSL and GLSL backends. By @cryvosh in #7658

General

• Add support for astc-sliced-3d feature. By @mehmetoguzderin in #7577
• Added wgpu_hal::dx12::Adapter::as_raw(). By @tronical in ##7852
• Add support for rendering to slices of 3D texture views and single layered 2D-Array texture views (this requires VK_KHR_maintenance1 which should be widely available on newer drivers). By @teoxoy in #7596
• Add extra acceleration structure vertex formats. By @Vecvec in #7580.
• Add acceleration structure limits. By @Vecvec in #7845.
• Add support for clip-distances feature for Vulkan and GL backends. By @dzamkov in #7730
• Added wgpu_types::error::{ErrorType, WebGpuError} for classification of errors according to WebGPU's GPUError's classification scheme, and implement WebGpuError for existing errors. This allows users of wgpu-core to offload error classification onto the wgpu ecosystem, rather than having to do it themselves without sufficient information. By @ErichDonGubler in #6547.

Bug Fixes

General

• Fix error message for sampler array limit. By @LPGhatguy in #7704.
• Fix bug where using BufferSlice::get_mapped_range_as_array_buffer() on a buffer would prevent you from ever unmapping it. Note that this API has changed and is now BufferView::as_uint8array().

naga

• naga now infers the correct binding layout when a resource appears only in an assignment to _. By @andyleiserson in #7540.
• Implement dot4U8Packed and dot4I8Packed for all backends, using specialized intrinsics on SPIR-V, HLSL, and Metal if available, and polyfills everywhere else. By @robamler in #7494, #7574, and #7653.
• Add polyfilled pack4x{I,U}8Clamped built-ins to all backends and WGSL frontend. By @ErichDonGubler in #7546.
• Allow textureLoad's sample index arg to be unsigned. By @jimblandy in #7625.
• Properly convert arguments to atomic operations. By @jimblandy in #7573.
• Apply necessary automatic conversions to the value argument of textureStore. By @jimblandy in #7567.
• Properly apply WGSL's automatic conversions to the arguments to texture sampling functions. By @jimblandy in #7548.
• Properly evaluate abs(most negative abstract int). By @jimblandy in #7507.
• Generate vectorized code for [un]pack4x{I,U}8[Clamp] on SPIR-V and MSL 2.1+. By @robamler in #7664.
• Fix typing for select, which had issues particularly with a lack of automatic type conversion. By @ErichDonGubler in #7572.
• Allow scalars as the first argument of the distance built-in function. By @bernhl in #7530.
• Don't panic when handling f16 for pipeline constants, i.e., overrides in WGSL. By @ErichDonGubler in #7801.
• Prevent aliased ray queries crashing naga when writing SPIR-V out. By @Vecvec in #7759.

DX12

• Get vertex_index & instance_index builtins working for indirect draws. By @teoxoy in #7535

Vulkan

• Fix OpenBSD compilation of wgpu_hal::vulkan::drm. By @ErichDonGubler in #7810.
• Fix warnings for unrecognized present mode. By @Wumpf in #7850.

Metal

• Remove extraneous main thread warning in fn surface_capabilities(). By @jamesordner in #7692

WebGPU

• Fix setting unclipped_depth. By @atlv24 in #7841
• Implement on_submitted_work_done for WebGPU backend. By @drewcrawford in #7864

Changes

• Loosen Viewport validation requirements to match the new specs. By @ebbdrop in #7564
• wgpu and deno_webgpu now use wgpu-types::error::WebGpuError to classify errors. Any changes here are likely to be regressions; please report them if you find them! By @ErichDonGubler in #6547.

General

• Support BLAS compaction in wgpu. By @Vecvec in #7285.
• Removed MaintainBase in favor of using PollType. By @waywardmonkeys in #7508.
• The destroy functions for buffers and textures in wgpu-core are now infallible. Previously, they returned an error if called multiple times for the same object. This only affects the wgpu-core API; the wgpu API already allowed multiple destroy calls. By @andyleiserson in #7686 and #7720.
• Remove CommandEncoder::build_acceleration_structures_unsafe_tlas in favour of as_hal and apply simplifications allowed by this. By @Vecvec in #7513
• The type of the size parameter to copy_buffer_to_buffer has changed from BufferAddress to impl Into<Option<BufferAddress>>. This achieves the spec-defined behavior of the value being optional, while still accepting existing calls without changes. By @andyleiserson in #7659.
• To bring wgpu's error reporting into compliance with the WebGPU specification, the error type returned from some functions has changed, and some errors may be raised at a different time than they were previously.
  • The error type returned by many methods on CommandEncoder, RenderPassEncoder, ComputePassEncoder, and RenderBundleEncoder has changed to EncoderStateError or PassStateError. These functions will return the Ended variant of these errors if called on an encoder that is no longer active. Reporting of all other errors is deferred until a call to finish().
  • Variants holding a CommandEncoderError in the error enums ClearError, ComputePassErrorInner, QueryError, and RenderPassErrorInner have been replaced with variants holding an EncoderStateError.
  • The definition of enum CommandEncoderError has changed significantly, to reflect which errors can be raised by CommandEncoder.finish(). There are also some errors that no longer appear directly in CommandEncoderError, and instead appear nested within the RenderPass or ComputePass variants.
  • CopyError has been removed. Errors that were previously a CopyError are now a CommandEncoderError returned by finish(). (The detailed reasons for copies to fail were and still are described by TransferError, which was previously a variant of CopyError, and is now a variant of CommandEncoderError).

naga

• Mark readonly_and_readwrite_storage_textures & packed_4x8_integer_dot_product language extensions as implemented. By @teoxoy in #7543
• naga::back::hlsl::Writer::new has a new pipeline_options argument. hlsl::PipelineOptions::default() can be passed as a default. The shader_stage and entry_point members of pipeline_options can be used to write only a single entry point when using the HLSL and MSL backends (GLSL and SPIR-V already had this functionality). The Metal and DX12 HALs now write only a single entry point when loading shaders. By @andyleiserson in #7626.
• Implemented early_depth_test for SPIR-V backend, enabling SHADER_EARLY_DEPTH_TEST for Vulkan. Additionally, fixed conservative depth optimizations when using early_depth_test. The syntax for forcing early depth tests is now @early_depth_test(force) instead of @early_depth_test. By @dzamkov in #7676.
• ImplementedLanguageExtension::VARIANTS is now implemented manually rather than derived using strum (allowing strum to become a dev-only dependency) so it is no longer a member of the strum::VARIANTS trait. Unless you are using this trait as a bound this should have no effect.
• Compaction changes, by @andyleiserson in #7703:
  • process_overrides now compacts the module to remove unused items. It is no longer necessary to supply values for overrides that are not used by the active entry point.
  • The compact Cargo feature has been removed. It is no longer possible to exclude compaction support from the build.
  • compact now has an additional argument that specifies whether to remove unused functions, globals, and named types and overrides. For the previous behavior, pass KeepUnused::Yes.

D3D12

• Remove the need for dxil.dll. By @teoxoy in #7566
• Ability to get the raw IDXGIFactory4 from Instance. By @MendyBerger in #7827

Vulkan

• Use highest SPIR-V version supported by Vulkan API version. By @robamler in #7595

HAL

• Added initial no_std support to wgpu-hal. By @bushrat011899 in #7599

Documentation

General

• Remove outdated information about Adapter::request_device. By @tesselode in #7768

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
• naga's use of termcolor and stderr are now optional behind features of the same names. By @bushrat011899 in #7482

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.
• Prevent ray intersection function overwriting each other. By @Vecvec in #7497.
• Require that the level operand of an ImageQuery::Size expression is i32 or u32, per spec. By @jimblandy in #7426.
• Implement constant evaluation for the cross builtin. By @jimblandy in #7404.
• Properly handle automatic type conversions in calls to MathFunction builtins. By @jimblandy in #6833.

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.
• Implement indirect draw validation. By @teoxoy in #7140

Vulkan

• Stop naga causing undefined behavior when a ray query misses. By @Vecvec in #6752.
• In naga's SPIR-V backend, avoid duplicating SPIR-V OpTypePointer instructions. By @jimblandy in #7246.

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
• Bound check dynamic buffers. By @teoxoy in #6931
• Fix size of buffer. By @teoxoy in #7310

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.