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

Cherry-picked PRs:

• #9264: fix(core): implement value comparison for max_inter_stage_shader_variables
• #9284: fix(metal): Check respondsToSelector before feature detection calls
• #9302: fix(gles): texture height initialized incorrectly in create_texture
• #8808: Fix up CreateTextureViewError::TooManyMipLevels/ArrayLayers crashes
  Plus revert of c819484

Bump workspace version to 29.0.1 and update changelog.

v29.0.1 (2026-03-26)

This release includes wgpu-core, wgpu-hal, naga, wgpu-naga-bridge and wgpu-types version 29.0.1. All other crates remain at their previous versions.

Bug Fixes

General

• Fix limit comparison logic for max_inter_stage_shader_variables. By @ErichDonGubler in #9264.

Metal

• Added guards to avoid calling some feature detection methods that are not implemented on CaptureMTLDevice. By @andyleiserson in #9284.
• Fix a regression where buffer limits were too conservative. This comes at the cost of non-compliant WebGPU limit validation. A future major release will keep the relaxed buffer limits on native while allowing WebGPU-mandated validation to be opted in. See #9287.

GLES / OpenGL

• Fix texture height initialized incorrectly in create_texture. By @umajho in #9302.

Validation

• Don't crash in the Display implementation of CreateTextureViewError::TooMany{MipLevels,ArrayLayers} when their base and offset overflow. By @ErichDonGubler in #8808.

This release includes wgpu-core, wgpu-hal and wgpu-types version 29.0.1. All other crates remain at their previous versions.

Bug Fixes

General

• Fix limit comparison logic for max_inter_stage_shader_variables. By @ErichDonGubler in #9264.

Metal

• Added guards to avoid calling some feature detection methods that are not implemented on CaptureMTLDevice. By @andyleiserson in #9284.
• Fix a regression where buffer limits were too conservative. This comes at the cost of non-compliant WebGPU limit validation. A future major release will keep the relaxed buffer limits on native while allowing WebGPU-mandated validation to be opted in. See #9287.

GLES / OpenGL

• Fix texture height initialized incorrectly in create_texture. By @umajho in #9302.

Validation

• Don't crash in the Display implementation of CreateTextureViewError::TooMany{MipLevels,ArrayLayers} when their base and offset overflow. By @ErichDonGubler in #8808.

v29.0.1

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

Bug Fixes

• Fixed the build on docs.rs. By @cwfitzgerald in #8292.

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.

Major changes

Refactored Dispatch Between wgpu-core and webgpu

The crate wgpu has two different "backends", one which targets webgpu in the browser, one which targets wgpu_core on native platforms and webgl. This was previously very difficult to traverse and add new features to. The entire system was refactored to make it simpler. Additionally the new system has zero overhead if there is only one "backend" in use. You can see the new system in action by using go-to-definition on any wgpu functions in your IDE.

By @cwfitzgerald in #6619.

Most objects in wgpu are now Clone

All types in the wgpu API are now Clone. This is implemented with internal reference counting, so cloning for instance a Buffer does copies only the "handle" of the GPU buffer, not the underlying resource.

Previously, libraries using wgpu objects like Device, Buffer or Texture etc. often had to manually wrap them in a Arc to allow passing between libraries. This caused a lot of friction since if one library wanted to use a Buffer by value, calling code had to give up ownership of the resource which may interfere with other subsystems. Note that this also mimics how the WebGPU javascript API works where objects can be cloned and moved around freely.

By @cwfitzgerald in #6665.

Render and Compute Passes Now Properly Enforce Their Lifetime

A regression introduced in 23.0.0 caused lifetimes of render and compute passes to be incorrectly enforced. While this is not a soundness issue, the intent is to move an error from runtime to compile time. This issue has been fixed and restored to the 22.0.0 behavior.

Bindless (binding_array) Grew More Capabilities

• DX12 now supports PARTIALLY_BOUND_BINDING_ARRAY on Resource Binding Tier 3 Hardware. This is most D3D12 hardware D3D12 Feature Table for more information on what hardware supports this feature. By @cwfitzgerald in #6734.

Device::create_shader_module_unchecked Renamed and Now Has Configuration Options

create_shader_module_unchecked became create_shader_module_trusted.

This allows you to customize which exact checks are omitted so that you can get the correct balance of performance and safety for your use case. Calling the function is still unsafe, but now can be used to skip certain checks only on certain builds.

This also allows users to disable the workarounds in the msl-out backend to prevent the compiler from optimizing infinite loops. This can have a big impact on performance, but is not recommended for untrusted shaders.

let desc: ShaderModuleDescriptor = include_wgsl!(...)
- let module = unsafe { device.create_shader_module_unchecked(desc) };
+ let module = unsafe { device.create_shader_module_trusted(desc, wgpu::ShaderRuntimeChecks::unchecked()) };

By @cwfitzgerald and @rudderbucky in #6662.

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

Previously wgpu::Instance::new took InstanceDescriptor by value (which is overall fairly uncommon in wgpu). Furthermore, InstanceDescriptor is now cloneable.

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

By @wumpf in #6849.

Environment Variable Handling Overhaul

Previously how various bits of code handled reading settings from environment variables was inconsistent and unideomatic. We have unified it to (Type::from_env() or Type::from_env_or_default()) and Type::with_env for all types.

- wgpu::util::backend_bits_from_env()
+ wgpu::Backends::from_env()

- wgpu::util::power_preference_from_env()
+ wgpu::PowerPreference::from_env()

- wgpu::util::dx12_shader_compiler_from_env()
+ wgpu::Dx12Compiler::from_env()

- wgpu::util::gles_minor_version_from_env()
+ wgpu::Gles3MinorVersion::from_env()

- wgpu::util::instance_descriptor_from_env()
+ wgpu::InstanceDescriptor::from_env_or_default()

- wgpu::util::parse_backends_from_comma_list(&str)
+ wgpu::Backends::from_comma_list(&str)

By @cwfitzgerald in #6895

Backend-specific instance options are now in separate structs

In order to better facilitate growing more interesting backend options, we have put them into individual structs. This allows users to more easily understand what options can be defaulted and which they care about. All of these new structs implement from_env() and delegate to their respective from_env() methods.

- let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
-     backends: wgpu::Backends::all(),
-     flags: wgpu::InstanceFlags::default(),
-     dx12_shader_compiler: wgpu::Dx12Compiler::Dxc,
-     gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
- });
+ let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
+     backends: wgpu::Backends::all(),
+     flags: wgpu::InstanceFlags::default(),
+     backend_options: wgpu::BackendOptions {
+         dx12: wgpu::Dx12BackendOptions {
+             shader_compiler: wgpu::Dx12ShaderCompiler::Dxc,
+         },
+         gl: wgpu::GlBackendOptions {
+             gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
+         },
+     },
+ });

If you do not need any of these options, or only need one backend's info use the default() impl to fill out the remaining feelds.

By @cwfitzgerald in #6895

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

naga now parses diagnostic(…); directives according to the WGSL spec. This allows users to control certain lints, similar to Rust's allow, warn, and deny attributes. For example, in standard WGSL (but, notably, not naga yet—see https://github.com/gfx-rs/wgpu/issues/4369) this snippet would emit a uniformity error:

@group(0) @binding(0) var s : sampler;
@group(0) @binding(2) var tex : texture_2d<f32>;
@group(1) @binding(0) var<storage, read> ro_buffer : array<f32, 4>;

@fragment
fn main(@builtin(position) p : vec4f) -> @location(0) vec4f {
  if ro_buffer[0] == 0 {
    // Emits a derivative uniformity error during validation.
    return textureSample(tex, s, vec2(0.,0.));
  }

  return vec4f(0.);
}

…but we can now silence it with the off severity level, like so:

// Disable the diagnostic with this…
diagnostic(off, derivative_uniformity);

@group(0) @binding(0) var s : sampler;
@group(0) @binding(2) var tex : texture_2d<f32>;
@group(1) @binding(0) var<storage, read> ro_buffer : array<f32, 4>;

@fragment
fn main(@builtin(position) p : vec4f) -> @location(0) vec4f {
  if ro_buffer[0] == 0 {
    // Look ma, no error!
    return textureSample(tex, s, vec2(0.,0.));
  }

  return vec4f(0.);
}

There are some limitations to keep in mind with this new functionality:

• We support @diagnostic(…) rules as fn attributes, but prioritization for rules in statement positions (i.e., if (…) @diagnostic(…) { … } is unclear. If you are blocked by not being able to parse diagnostic(…) rules in statement positions, please let us know in https://github.com/gfx-rs/wgpu/issues/5320, so we can determine how to prioritize it!
• Standard WGSL specifies error, warning, info, and off severity levels. These are all technically usable now! A caveat, though: warning- and info-level are only emitted to stderr via the log façade, rather than being reported through a Result::Err in naga or the CompilationInfo interface in wgpu{,-core}. This will require breaking changes in naga to fix, and is being tracked by https://github.com/gfx-rs/wgpu/issues/6458.
• Not all lints can be controlled with diagnostic(…) rules. In fact, only the derivative_uniformity triggering rule exists in the WGSL standard. That said, naga contributors are excited to see how this level of control unlocks a new ecosystem of configurable diagnostics.
• Finally, diagnostic(…) rules are not yet emitted in WGSL output. This means that wgsl-in → wgsl-out is currently a lossy process. We felt that it was important to unblock users who needed diagnostic(…) rules (i.e., https://github.com/gfx-rs/wgpu/issues/3135) before we took significant effort to fix this (tracked in https://github.com/gfx-rs/wgpu/issues/6496).

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

New Features

naga

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

General

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

Vulkan

• Allow using some 32-bit floating-point atomic operations (load, store, add, sub, exchange) in shaders. It requires the extension VK_EXT_shader_atomic_float. By @AsherJingkongChen in #6234.

Metal

• Allow using some 32-bit floating-point atomic operations (load, store, add, sub, exchange) in shaders. It requires Metal 3.0+ with Apple 7, 8, 9 or Mac 2. By @AsherJingkongChen in #6234.
• Add build support for Apple Vision Pro. By @guusw in #6611.
• Add raw_handle method to access raw Metal textures in #6894.

D3D12

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

Changes

naga

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

General

• Align Storage Access enums to the webgpu spec. By @atlv24 in #6642
• Make Surface::as_hal take an immutable reference to the surface. By @jerzywilczek in #9999
• Add actual sample type to CreateBindGroupError::InvalidTextureSampleType error message. By @ErichDonGubler in #6530.
• Improve binding error to give a clearer message when there is a mismatch between resource binding as it is in the shader and as it is in the binding layout. By @eliemichel in #6553.
• Surface::configure and Surface::get_current_texture are no longer fatal. By @alokedesai in #6253
• Rename BlasTriangleGeometry::index_buffer_offset to BlasTriangleGeometry::first_index. By @Vecvec in #6873

D3D12

• Avoid using FXC as fallback when the DXC container was passed at instance creation. Paths to dxcompiler.dll & dxil.dll are also now required. By @teoxoy in #6643.

Vulkan

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

HAL

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

Bug Fixes

General

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

naga

• Fix crash when a texture argument is missing. By @aedm in #6486
• Emit an error in constant evaluation, rather than crash, in certain cases where vecN constructors have less than N arguments. By @ErichDonGubler in #6508.
• Fix an error in template list matching >= in a<b>=c. By @KentSlaney in #6898.
• Correctly validate handles in override-sized array types. By @jimblandy in #6882.
• Clean up validation of Statement::ImageStore. By @jimblandy in #6729.
• In compaction, avoid cloning the type arena. By @jimblandy in #6790
• In validation, forbid cycles between global expressions and types. By @jimblandy in #6800
• Allow abstract scalars in modf and frexp results. By @jimblandy in #6821
• In the WGSL front end, apply automatic conversions to values being assigned. By @jimblandy in #6822
• Fix a leak by ensuring that types that depend on expressions are correctly compacted. By @KentSlaney in #6934.

Vulkan

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

D3D12

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

Examples

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

Testing

• Tests the early returns in the acceleration structure build calls with empty calls. By @Vecvec in #6651.

Themes of this release

This release's theme is one that is likely to repeat for a few releases: convergence with the WebGPU specification! wgpu's design and base functionality are actually determined by two specifications: one for WebGPU, and one for the WebGPU Shading Language.

This may not sound exciting, but let us convince you otherwise! All major web browsers have committed to offering WebGPU in their environment. Even JS runtimes like Node and Deno have communities that are very interested in providing WebGPU! WebGPU is slowly eating the world, as it were. 😀 It's really important, then, that WebGPU implementations behave in ways that one would expect across all platforms. For example, if Firefox's WebGPU implementation were to break when running scripts and shaders that worked just fine in Chrome, that would mean sad users for both application authors and browser authors.

wgpu also benefits from standard, portable behavior in the same way as web browsers. Because of this behavior, it's generally fairly easy to port over usage of WebGPU in JavaScript to wgpu. It is also what lets wgpu go full circle: wgpu can be an implementation of WebGPU on native targets, but also it can use other implementations of WebGPU as a backend in JavaScript when compiled to WASM. Therefore, the same dynamic applies: if wgpu's own behavior were significantly different, then wgpu and end users would be sad, sad humans as soon as they discover places where their nice apps are breaking, right?

The answer is: yes, we do have sad, sad humans that really want their wgpu code to work everywhere. As Firefox and others use wgpu to implement WebGPU, the above example of Firefox diverging from standard is, unfortunately, today's reality. It mostly behaves the same as a standards-compliant WebGPU, but it still doesn't in many important ways. Of particular note is naga, its implementation of the WebGPU Shader Language. Shaders are pretty much a black-and-white point of failure in GPU programming; if they don't compile, then you can't use the rest of the API! And yet, it's extremely easy to run into a case like that from https://github.com/gfx-rs/wgpu/issues/4400:

fn gimme_a_float() -> f32 {
  return 42; // fails in naga, but standard WGSL happily converts to `f32`
}

We intend to continue making visible strides in converging with specifications for WebGPU and WGSL, as this release has. This is, unfortunately, one of the major reasons that wgpu has no plans to work hard at keeping a SemVer-stable interface for the foreseeable future; we have an entire platform of GPU programming functionality we have to catch up with, and SemVer stability is unfortunately in tension with that. So, for now, you're going to keep seeing major releases and breaking changes. Where possible, we'll try to make that painless, but compromises to do so don't always make sense with our limited resources.

This is also the last planned major version release of 2024; the next milestone is set for January 1st, 2025, according to our regular 12-week cadence (offset from the originally planned date of 2024-10-09 for this release 😅). We'll see you next year!

Contributor spotlight: @sagudev

This release, we'd like to spotlight the work of @sagudev, who has made significant contributions to the wgpu ecosystem this release. Among other things, they contributed a particularly notable feature where runtime-known indices are finally allowed for use with const array values. For example, this WGSL shader previously wasn't allowed:

const arr: array<u32, 4> = array(1, 2, 3, 4);

fn what_number_should_i_use(idx: u32) -> u32 {
  return arr[idx];
}

…but now it works! This is significant because this sort of shader rejection was one of the most impactful issues we are aware of for converging with the WGSL specification. There are more still to go—some of which we expect to even more drastically change how folks author shaders—but we suspect that many more will come in the next few releases, including with @sagudev's help.

We're excited for more of @sagudev's contributions via the Servo community. Oh, did we forget to mention that these contributions were motivated by their work on Servo? That's right, a third well-known JavaScript runtime is now using wgpu to implement its WebGPU implementation. We're excited to support Servo to becoming another fully fledged browsing environment this way.

Major Changes

In addition to the above spotlight, we have the following particularly interesting items to call out for this release:

wgpu-core is no longer generic over wgpu-hal backends

Dynamic dispatch between different backends has been moved from the user facing wgpu crate, to a new dynamic dispatch mechanism inside the backend abstraction layer wgpu-hal.

Whenever targeting more than a single backend (default on Windows & Linux) this leads to faster compile times and smaller binaries! This also solves a long standing issue with cargo doc failing to run for wgpu-core.

Benchmarking indicated that compute pass recording is slower as a consequence, whereas on render passes speed improvements have been observed. However, this effort simplifies many of the internals of the wgpu family of crates which we're hoping to build performance improvements upon in the future.

By @wumpf in #6069, #6099, #6100.

wgpu's resources no longer have .global_id() getters

wgpu-core's internals no longer use nor need IDs and we are moving towards removing IDs completely. This is a step in that direction.

Current users of .global_id() are encouraged to make use of the PartialEq, Eq, Hash, PartialOrd and Ord traits that have now been implemented for wgpu resources.

By @teoxoy in #6134.

set_bind_group now takes an Option for the bind group argument.

https://gpuweb.github.io/gpuweb/#programmable-passes-bind-groups specifies that bindGroup is nullable. This change is the start of implementing this part of the spec. Callers that specify a Some() value should have unchanged behavior. Handling of None values still needs to be implemented by backends.

For convenience, the set_bind_group on compute/render passes & encoders takes impl Into<Option<&BindGroup>>, so most code should still work the same.

By @bradwerth in #6216.

entry_points are now Optional

One of the changes in the WebGPU spec. (from about this time last year 😅) was to allow optional entry points in GPUProgrammableStage. In wgpu, this corresponds to a subset of fields in FragmentState, VertexState, and ComputeState as the entry_point member:

let render_pipeline = device.createRenderPipeline(wgpu::RenderPipelineDescriptor {
    module,
    entry_point: Some("cs_main"), // This is now `Option`al.
    // …
});

let compute_pipeline = device.createComputePipeline(wgpu::ComputePipelineDescriptor {
    module,
    entry_point: None, // This is now `Option`al.
    // …
});

When set to None, it's assumed that the shader only has a single entry point associated with the pipeline stage (i.e., @compute, @fragment, or @vertex). If there is not one and only one candidate entry point, then a validation error is returned. To continue the example, we might have written the above API usage with the following shader module:

// We can't use `entry_point: None` for compute pipelines with this module,
// because there are two `@compute` entry points.

@compute
fn cs_main() { /* … */ }

@compute
fn other_cs_main() { /* … */ }

// The following entry points _can_ be inferred from `entry_point: None` in a
// render pipeline, because they're the only `@vertex` and `@fragment` entry
// points:

@vertex
fn vs_main() { /* … */ }

@fragment
fn fs_main() { /* … */ }

wgpu's DX12 backend is now based on the windows crate ecosystem, instead of the d3d12 crate

wgpu has retired the d3d12 crate (based on winapi), and now uses the windows crate for interfacing with Windows. For many, this may not be a change that affects day-to-day work. However, for users who need to vet their dependencies, or who may vendor in dependencies, this may be a nontrivial migration.

By @MarijnS95 in #6006.

New Features

Wgpu

• Added initial acceleration structure and ray query support into wgpu. By @expenses @daniel-keitel @Vecvec @JMS55 @atlv24 in #6291

naga

• Support constant evaluation for firstLeadingBit and firstTrailingBit numeric built-ins in WGSL. Front-ends that translate to these built-ins also benefit from constant evaluation. By @ErichDonGubler in #5101.
• Add first and either sampling types for @interpolate(flat, …) in WGSL. By @ErichDonGubler in #6181.
• Support for more atomic ops in the SPIR-V frontend. By @schell in #5824.
• Support local const declarations in WGSL. By @sagudev in #6156.
• Implemented const_assert in WGSL. By @sagudev in #6198.
• Support polyfilling inverse in WGSL. By @chyyran in #6385.
• Add base support for parsing requires, enable, and diagnostic directives. No extensions or diagnostic filters are yet supported, but diagnostics have improved dramatically. By @ErichDonGubler in #6352, #6424, #6437.
• Include error chain information as a message and notes in shader compilation messages. By @ErichDonGubler in #6436.
• Unify naga CLI error output with the format of shader compilation messages. By @ErichDonGubler in #6436.

General

• Add VideoFrame to ExternalImageSource enum. By @jprochazk in #6170.
• Add wgpu::util::new_instance_with_webgpu_detection & wgpu::util::is_browser_webgpu_supported to make it easier to support WebGPU & WebGL in the same binary. By @wumpf in #6371.

Vulkan

• Allow using VK_GOOGLE_display_timing unsafely with the VULKAN_GOOGLE_DISPLAY_TIMING feature. By @DJMcNab in #6149.

Metal

• Implement atomicCompareExchangeWeak. By @AsherJingkongChen in #6265.
• Unless an explicit CAMetalLayer is provided, surfaces now render to a sublayer. This improves resizing behavior, fixing glitches during on window resize. By @madsmtm in #6107.

Bug Fixes

• Fix incorrect hlsl image output type conversion. By @atlv24 in #6123.

naga

• SPIR-V frontend splats depth texture sample and load results. Fixes issue #4551. By @schell in #6384.
• Accept only vec3 (not vecN) for the cross built-in. By @ErichDonGubler in #6171.
• Configure SourceLanguage when enabling debug info in SPV-out. By @kvark in #6256.
• Do not consider per-polygon and flat inputs subgroup uniform. By @magcius in #6276.
• Validate all swizzle components are either color (rgba) or dimension (xyzw) in WGSL. By @sagudev in #6187.
• Fix detection of shl overflows to detect arithmetic overflows. By @sagudev in #6186.
• Fix type parameters to vec/mat type constructors to also support aliases. By @sagudev in #6189.
• Accept global vars without explicit type. By @sagudev in #6199.
• Fix handling of phony statements, so they are actually emitted. By @sagudev in #6328.
• Added gl_DrawID to glsl and DrawIndex to spv. By @ChosenName in #6325.
• Matrices can now be indexed by value (#4337), and indexing arrays by value no longer causes excessive spilling (#6358). By @jimblandy in #6390.
• Add support for textureQueryLevels to the GLSL parser. By @magcius in #6325.
• Fix unescaped identifiers in the Metal backend shader I/O structures causing shader miscompilation. By @ErichDonGubler in #6438.

General

• If GL context creation fails retry with GLES. By @Rapdorian in #5996.
• Bump MSRV for d3d12/naga/wgpu-core/wgpu-hal/wgpu-types' to 1.76. By @wumpf in #6003.
• Print requested and supported usages on UnsupportedUsage error. By @VladasZ in #6007.
• Deduplicate bind group layouts that are created from pipelines with "auto" layouts. By @teoxoy #6049.
• Document wgpu_hal bounds-checking promises, and adapt wgpu_core's lazy initialization logic to the slightly weaker-than-expected guarantees. By @jimblandy in #6201.
• Raise validation error instead of panicking in {Render,Compute}Pipeline::get_bind_group_layout on native / WebGL. By @bgr360 in #6280.
• BREAKING: Remove the last exposed C symbols in project, located in wgpu_core::render::bundle::bundle_ffi, to allow multiple versions of wgpu to compile together. By @ErichDonGubler in #6272.
• Call flush_mapped_ranges when unmapping write-mapped buffers. By @teoxoy in #6089.
• When mapping buffers for reading, mark buffers as initialized only when they have MAP_WRITE usage. By @teoxoy in #6178.
• Add a separate pipeline constants error. By @teoxoy in #6094.
• Ensure safety of indirect dispatch by injecting a compute shader that validates the content of the indirect buffer. By @teoxoy in #5714.
• Add conversions between TextureFormat and StorageFormat. By @caelunshun in #6185

GLES / OpenGL

• Fix GL debug message callbacks not being properly cleaned up (causing UB). By @Imberflur in #6114.
• Fix calling slice::from_raw_parts with unaligned pointers in push constant handling. By @Imberflur in #6341.
• Optimise fence checking when Queue::submit is called many times per frame. By @dinnerbone in #6427.

WebGPU

• Fix JS TypeError exception in Instance::request_adapter when browser doesn't support WebGPU but wgpu not compiled with webgl support. By @bgr360 in #6197.

Vulkan

• Avoid undefined behaviour with adversarial debug label. By @DJMcNab in #6257.
• Add .index_type(vk::IndexType::NONE_KHR) when creating AccelerationStructureGeometryTrianglesDataKHR in the raytraced triangle example to prevent a validation error. By @Vecvec in #6282.

Changes

• wgpu_hal::gles::Adapter::new_external now requires the context to be current when dropping the adapter and related objects. By @Imberflur in #6114.
• Reduce the amount of debug and trace logs emitted by wgpu-core and wgpu-hal. By @nical in #6065.
• Rename Rg11b10Float to Rg11b10Ufloat. By @sagudev in #6108.
• Invalidate the device when we encounter driver-induced device loss or on unexpected errors. By @teoxoy in #6229.
• Make Vulkan error handling more robust. By @teoxoy in #6119.
• Add bounds checking to Buffer slice method. By @beholdnec in #6432.
• Replace impl From<StorageFormat> for ScalarKind with impl From<StorageFormat> for Scalar so that byte width is included. By @atlv24 in #6451.

Internal

• Tracker simplifications. By @teoxoy in #6073 & #6088.
• D3D12 cleanup. By @teoxoy in #6200.
• Use ManuallyDrop in remaining places. By @teoxoy in #6092.
• Move out invalidity from the Registry. By @teoxoy in #6243.
• Remove backend from ID. By @teoxoy in #6263.

HAL

• Change the inconsistent DropGuard based API on Vulkan and GLES to a consistent, callback-based one. By @jerzywilczek in #6164.

Documentation

• Removed some OpenGL and Vulkan references from wgpu-types documentation. Fixed Storage texel types in examples. By @Nelarius in #6271.
• Used wgpu::include_wgsl!(…) more in examples and tests. By @ErichDonGubler in #6326.

Dependency Updates

GLES

• Replace winapi code in WGL wrapper to use the windows crate. By @MarijnS95 in #6006.
• Update glutin to 0.31 with glutin-winit crate. By @MarijnS95 in #6150 and #6176.
• Implement Adapter::new_external() for WGL (just like EGL) to import an external OpenGL ES context. By @MarijnS95 in #6152.

DX12

• Replace winapi code to use the windows crate. By @MarijnS95 in #5956 and #6173.
• Get num_workgroups builtin working for indirect dispatches. By @teoxoy in #5730.

HAL

• Update parking_lot to 0.12. By @mahkoh in #6287.

Overview

Our first major version release!

For the first time ever, wgpu is being released with a major version (i.e., 22.* instead of 0.22.*)! Maintainership has decided to fully adhere to Semantic Versioning's recommendations for versioning production software. According to SemVer 2.0.0's Q&A about when to use 1.0.0 versions (and beyond):

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backward compatibility, you should probably already be 1.0.0.

It is a well-known fact that wgpu has been used for applications and platforms already in production for years, at this point. We are often concerned with tracking breaking changes, and affecting these consumers' ability to ship. By releasing our first major version, we publicly acknowledge that this is the case. We encourage other projects in the Rust ecosystem to follow suit.

Note that while we start to use the major version number, wgpu is not "going stable", as many Rust projects do. We anticipate many breaking changes before we fully comply with the WebGPU spec., which we expect to take a small number of years.

Overview

A major (pun intended) theme of this release is incremental improvement. Among the typically large set of bug fixes, new features, and other adjustments to wgpu by the many contributors listed below, @wumpf and @teoxoy have merged a series of many simplifications to wgpu's internals and, in one case, to the render and compute pass recording APIs. Many of these change wgpu to use atomically reference-counted resource tracking (i.e., Arc<…>), rather than using IDs to manage the lifetimes of platform-specific graphics resources in a registry of separate reference counts. This has led us to diagnose and fix many long-standing bugs, and net some neat performance improvements on the order of 40% or more of some workloads.

While the above is exciting, we acknowledge already finding and fixing some (easy-to-fix) regressions from the above work. If you migrate to wgpu 22 and encounter such bugs, please engage us in the issue tracker right away!

Major Changes

Lifetime bounds on wgpu::RenderPass & wgpu::ComputePass

wgpu::RenderPass & wgpu::ComputePass recording methods (e.g. wgpu::RenderPass:set_render_pipeline) no longer impose a lifetime constraint to objects passed to a pass (like pipelines/buffers/bindgroups/query-sets etc.).

This means the following pattern works now as expected:

let mut pipelines: Vec<wgpu::RenderPipeline> = ...;
// ...
let mut cpass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor::default());
cpass.set_pipeline(&pipelines[123]);
// Change pipeline container - this requires mutable access to `pipelines` while one of the pipelines is in use.
pipelines.push(/* ... */);
// Continue pass recording.
cpass.set_bindgroup(...);

Previously, a set pipeline (or other resource) had to outlive pass recording which often affected wider systems, meaning that users needed to prove to the borrow checker that Vec<wgpu::RenderPipeline> (or similar constructs) aren't accessed mutably for the duration of pass recording.

Furthermore, you can now opt out of wgpu::RenderPass/wgpu::ComputePass's lifetime dependency on its parent wgpu::CommandEncoder using wgpu::RenderPass::forget_lifetime/wgpu::ComputePass::forget_lifetime:

fn independent_cpass<'enc>(encoder: &'enc mut wgpu::CommandEncoder) -> wgpu::ComputePass<'static> {
    let cpass: wgpu::ComputePass<'enc> = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor::default());
    cpass.forget_lifetime()
}

⚠️ As long as a wgpu::RenderPass/wgpu::ComputePass is pending for a given wgpu::CommandEncoder, creation of a compute or render pass is an error and invalidates the wgpu::CommandEncoder. forget_lifetime can be very useful for library authors, but opens up an easy way for incorrect use, so use with care. This method doesn't add any additional overhead and has no side effects on pass recording.

By @wumpf in #5569, #5575, #5620, #5768 (together with @kpreid), #5671, #5794, #5884.

Querying shader compilation errors

Wgpu now supports querying shader compilation info.

This allows you to get more structured information about compilation errors, warnings and info:

...
let lighting_shader = ctx.device.create_shader_module(include_wgsl!("lighting.wgsl"));
let compilation_info = lighting_shader.get_compilation_info().await;
for message in compilation_info
    .messages
    .iter()
    .filter(|m| m.message_type == wgpu::CompilationMessageType::Error)
{
    let line = message.location.map(|l| l.line_number).unwrap_or(1);
    println!("Compile error at line {line}");
}

By @stefnotch in #5410

64 bit integer atomic support in shaders.

Add support for 64 bit integer atomic operations in shaders.

Add the following flags to wgpu_types::Features:

• SHADER_INT64_ATOMIC_ALL_OPS enables all atomic operations on atomic<i64> and atomic<u64> values.

• SHADER_INT64_ATOMIC_MIN_MAX is a subset of the above, enabling only AtomicFunction::Min and AtomicFunction::Max operations on atomic<i64> and atomic<u64> values in the Storage address space. These are the only 64-bit atomic operations available on Metal as of 3.1.

Add corresponding flags to naga::valid::Capabilities. These are supported by the WGSL front end, and all naga backends.

Platform support:

• On Direct3d 12, in D3D12_FEATURE_DATA_D3D12_OPTIONS9, if AtomicInt64OnTypedResourceSupported and AtomicInt64OnGroupSharedSupported are both available, then both wgpu features described above are available.

• On Metal, SHADER_INT64_ATOMIC_MIN_MAX is available on Apple9 hardware, and on hardware that advertises both Apple8 and Mac2 support. This also requires Metal Shading Language 2.4 or later. Metal does not yet support the more general SHADER_INT64_ATOMIC_ALL_OPS.

• On Vulkan, if the VK_KHR_shader_atomic_int64 extension is available with both the shader_buffer_int64_atomics and shader_shared_int64_atomics features, then both wgpu features described above are available.

By @atlv24 in #5383

A compatible surface is now required for request_adapter() on WebGL2 + enumerate_adapters() is now native only.

When targeting WebGL2, it has always been the case that a surface had to be created before calling request_adapter(). We now make this requirement explicit.

Validation was also added to prevent configuring the surface with a device that doesn't share the same underlying WebGL2 context since this has never worked.

Calling enumerate_adapters() when targeting WebGPU used to return an empty Vec and since we now require users to pass a compatible surface when targeting WebGL2, having enumerate_adapters() doesn't make sense.

By @teoxoy in #5901

New features

General

• Added as_hal for Buffer to access wgpu created buffers form wgpu-hal. By @JasondeWolff in #5724
• include_wgsl! is now callable in const contexts by @9SMTM6 in #5872
• Added memory allocation hints to DeviceDescriptor by @nical in #5875
  • MemoryHints::Performance, the default, favors performance over memory usage and will likely cause large amounts of VRAM to be allocated up-front. This hint is typically good for games.
  • MemoryHints::MemoryUsage favors memory usage over performance. This hint is typically useful for smaller applications or UI libraries.
  • MemoryHints::Manual allows the user to specify parameters for the underlying GPU memory allocator. These parameters are subject to change.
  • These hints may be ignored by some backends. Currently only the Vulkan and D3D12 backends take them into account.
• Add HTMLImageElement and ImageData as external source for copying images. By @Valaphee in #5668

naga

• Added -D, --defines option to naga CLI to define preprocessor macros by @theomonnom in #5859

• Added type upgrades to SPIR-V atomic support. Added related infrastructure. Tracking issue is here. By @schell in #5775.

• Implement WGSL's unpack4xI8,unpack4xU8,pack4xI8 and pack4xU8. By @VlaDexa in #5424

• Began work adding support for atomics to the SPIR-V frontend. Tracking issue is here. By @schell in #5702.

• In hlsl-out, allow passing information about the fragment entry point to omit vertex outputs that are not in the fragment inputs. By @Imberflur in #5531

• In spv-out, allow passing acceleration_structure as a function argument. By @kvark in #5961

  let writer: naga::back::hlsl::Writer = /* ... */;
  -writer.write(&module, &module_info);
  +writer.write(&module, &module_info, None);
  

• HLSL & MSL output can now be added conditionally on the target via the msl-out-if-target-apple and hlsl-out-if-target-windows features. This is used in wgpu-hal to no longer compile with MSL output when metal is enabled & MacOS isn't targeted and no longer compile with HLSL output when dx12 is enabled & Windows isn't targeted. By @wumpf in #5919

Vulkan

• Added a PipelineCache resource to allow using Vulkan pipeline caches. By @DJMcNab in #5319

WebGPU

• Added support for pipeline-overridable constants to the WebGPU backend by @DouglasDwyer in #5688

Changes

General

• Unconsumed vertex outputs are now always allowed. Removed StageError::InputNotConsumed, Features::SHADER_UNUSED_VERTEX_OUTPUT, and associated validation. By @Imberflur in #5531
• Avoid introducing spurious features for optional dependencies. By @bjorn3 in #5691
• wgpu::Error is now Sync, making it possible to be wrapped in anyhow::Error or eyre::Report. By @nolanderc in #5820
• Added benchmark suite. By @cwfitzgerald in #5694, compute passes by @wumpf in #5767
• Improve performance of .submit() by 39-64% (.submit() + .poll() by 22-32%). By @teoxoy in #5910
• The trace wgpu feature has been temporarily removed. By @teoxoy in #5975

Metal

• Removed the link Cargo feature.

  This was used to allow weakly linking frameworks. This can be achieved with putting something like the following in your .cargo/config.toml instead:

  [target.'cfg(target_vendor = "apple")']
  rustflags = ["-C", "link-args=-weak_framework Metal -weak_framework QuartzCore -weak_framework CoreGraphics"]
  

  By @madsmtm in #5752

Bug Fixes

General

• Ensure render pipelines have at least 1 target. By @ErichDonGubler in #5715
• wgpu::ComputePass now internally takes ownership of QuerySet for both wgpu::ComputePassTimestampWrites as well as timestamp writes and statistics query, fixing crashes when destroying QuerySet before ending the pass. By @wumpf in #5671
• Validate resources passed during compute pass recording for mismatching device. By @wumpf in #5779
• Fix staging buffers being destroyed too early. By @teoxoy in #5910
• Fix attachment byte cost validation panicking with native only formats. By @teoxoy in #5934
• [wgpu] Fix leaks from auto layout pipelines. By @teoxoy in #5971
• [wgpu-core] Fix length of copy in queue_write_texture (causing UB). By @teoxoy in #5973
• Add missing same device checks. By @teoxoy in #5980

GLES / OpenGL

• Fix ClearColorF, ClearColorU and ClearColorI commands being issued before SetDrawColorBuffers #5666
• Replace glClear with glClearBufferF because glDrawBuffers requires that the ith buffer must be COLOR_ATTACHMENTi or NONE #5666
• Return the unmodified version in driver_info. By @Valaphee in #5753

naga

• In spv-out don't decorate a BindingArray's type with Block if the type is a struct with a runtime array by @Vecvec in #5776
• Add packed as a keyword for GLSL by @kjarosh in #5855

Major Changes

Pipeline overridable constants

Wgpu supports now pipeline-overridable constants

This allows you to define constants in wgsl like this:

override some_factor: f32 = 42.1337; // Specifies a default of 42.1337 if it's not set.

And then set them at runtime like so on your pipeline consuming this shader:

// ...
fragment: Some(wgpu::FragmentState {
    compilation_options: wgpu::PipelineCompilationOptions {
        constants: &[("some_factor".to_owned(), 0.1234)].into(), // Sets `some_factor` to 0.1234.
        ..Default::default()
    },
    // ...
}),
// ...

By @teoxoy & @jimblandy in #5500

Changed feature requirements for timestamps

Due to a specification change write_timestamp is no longer supported on WebGPU. wgpu::CommandEncoder::write_timestamp requires now the new wgpu::Features::TIMESTAMP_QUERY_INSIDE_ENCODERS feature which is available on all native backends but not on WebGPU.

By @wumpf in #5188

Wgsl const evaluation for many more built-ins

Many numeric built-ins have had a constant evaluation implementation added for them, which allows them to be used in a const context:

abs, acos, acosh, asin, asinh, atan, atanh, cos, cosh, round, saturate, sin, sinh, sqrt, step, tan, tanh, ceil, countLeadingZeros, countOneBits, countTrailingZeros, degrees, exp, exp2, floor, fract, fma, inverseSqrt, log, log2, max, min, radians, reverseBits, sign, trunc

By @ErichDonGubler in #4879, #5098

New native-only wgsl features

Subgroup operations

The following subgroup operations are available in wgsl now:

subgroupBallot, subgroupAll, subgroupAny, subgroupAdd, subgroupMul, subgroupMin, subgroupMax, subgroupAnd, subgroupOr, subgroupXor, subgroupExclusiveAdd, subgroupExclusiveMul, subgroupInclusiveAdd, subgroupInclusiveMul, subgroupBroadcastFirst, subgroupBroadcast, subgroupShuffle, subgroupShuffleDown, subgroupShuffleUp, subgroupShuffleXor

Availability is governed by the following feature flags:

• wgpu::Features::SUBGROUP for all operations except subgroupBarrier in fragment & compute, supported on Vulkan, DX12 and Metal.
• wgpu::Features::SUBGROUP_VERTEX, for all operations except subgroupBarrier general operations in vertex shaders, supported on Vulkan
• wgpu::Features::SUBGROUP_BARRIER, for support of the subgroupBarrier operation, supported on Vulkan & Metal

Note that there currently some differences between wgpu's native-only implementation and the open WebGPU proposal.

By @exrook and @lichtso in #5301

Signed and unsigned 64 bit integer support in shaders.

wgpu::Features::SHADER_INT64 enables 64 bit integer signed and unsigned integer variables in wgsl (i64 and u64 respectively). Supported on Vulkan, DX12 (requires DXC) and Metal (with MSL 2.3+ support).

By @atlv24 and @cwfitzgerald in #5154

New features

General

• Implemented the Unorm10_10_10_2 VertexFormat by @McMackety in #5477
• wgpu-types's trace and replay features have been replaced by the serde feature. By @KirmesBude in #5149
• wgpu-core's serial-pass feature has been removed. Use serde instead. By @KirmesBude in #5149
• Added InstanceFlags::GPU_BASED_VALIDATION, which enables GPU-based validation for shaders. This is currently only supported on the DX12 and Vulkan backends; other platforms ignore this flag, for now. By @ErichDonGubler in #5146, #5046.
  • When set, this flag implies InstanceFlags::VALIDATION.
  • This has been added to the set of flags set by InstanceFlags::advanced_debugging. Since the overhead is potentially very large, the flag is not enabled by default in debug builds when using InstanceFlags::from_build_config.
  • As with other instance flags, this flag can be changed in calls to InstanceFlags::with_env with the new WGPU_GPU_BASED_VALIDATION environment variable.
• wgpu::Instance can now report which wgpu::Backends are available based on the build configuration. By @wumpf #5167

  -wgpu::Instance::any_backend_feature_enabled()
  +!wgpu::Instance::enabled_backend_features().is_empty()
  

• Breaking change: wgpu_core::pipeline::ProgrammableStageDescriptor is now optional. By @ErichDonGubler in #5305.
• Features::downlevel{_webgl2,}_features was made const by @MultisampledNight in #5343
• Breaking change: wgpu_core::pipeline::ShaderError has been moved to naga. By @stefnotch in #5410
• More as_hal methods and improvements by @JMS55 in #5452
  • Added wgpu::CommandEncoder::as_hal_mut
  • Added wgpu::TextureView::as_hal
  • wgpu::Texture::as_hal now returns a user-defined type to match the other as_hal functions

naga

• Allow user to select which MSL version to use via --metal-version with naga CLI. By @pcleavelin in #5392
• Support arrayLength for runtime-sized arrays inside binding arrays (for WGSL input and SPIR-V output). By @kvark in #5428
• Added --shader-stage and --input-kind options to naga-cli for specifying vertex/fragment/compute shaders, and frontend. by @ratmice in #5411
• Added a create_validator function to wgpu_core Device to create naga Validators. By @atlv24 #5606

WebGPU

• Implement the device_set_device_lost_callback method for ContextWebGpu. By @suti in #5438
• Add support for storage texture access modes ReadOnly and ReadWrite. By @JolifantoBambla in #5434

GLES / OpenGL

• Log an error when GLES texture format heuristics fail. By @PolyMeilex in #5266
• Cache the sample count to keep get_texture_format_features cheap. By @Dinnerbone in #5346
• Mark DEPTH32FLOAT_STENCIL8 as supported in GLES. By @Dinnerbone in #5370
• Desktop GL now also supports TEXTURE_COMPRESSION_ETC2. By @Valaphee in #5568
• Don't create a program for shader-clearing if that workaround isn't required. By @Dinnerbone in #5348.
• OpenGL will now be preferred over OpenGL ES on EGL, making it consistent with WGL. By @valaphee in #5482
• Fill out driver and driver_info, with the OpenGL flavor and version, similar to Vulkan. By @valaphee in #5482

Metal

• Metal 3.0 and 3.1 detection. By @atlv24 in #5497

DX12

• Shader Model 6.1-6.7 detection. By @atlv24 in #5498

Other performance improvements

• Simplify and speed up the allocation of internal IDs. By @nical in #5229
• Use memory pooling for UsageScopes to avoid frequent large allocations. by @robtfm in #5414
• Eager release of GPU resources comes from device.trackers. By @bradwerth in #5075
• Support disabling zero-initialization of workgroup local memory in compute shaders. By @DJMcNab in #5508

Documentation

• Improved wgpu_hal documentation. By @jimblandy in #5516, #5524, #5562, #5563, #5566, #5617, #5618
• Add mention of primitive restart in the description of PrimitiveState::strip_index_format. By @cpsdqs in #5350
• Document and tweak precise behaviour of SourceLocation. By @stefnotch in #5386 and #5410
• Give short example of WGSL push_constant syntax. By @waywardmonkeys in #5393
• Fix incorrect documentation of Limits::max_compute_workgroup_storage_size default value. By @atlv24 in #5601

Bug Fixes

General

• Fix serde feature not compiling for wgpu-types. By @KirmesBude in #5149
• Fix the validation of vertex and index ranges. By @nical in #5144 and #5156
• Fix panic when creating a surface while no backend is available. By @wumpf #5166
• Correctly compute minimum buffer size for array-typed storage and uniform vars. By @jimblandy #5222
• Fix timeout when presenting a surface where no work has been done. By @waywardmonkeys in #5200
• Fix registry leaks with de-duplicated resources. By @nical in #5244
• Fix linking when targeting android. By @ashdnazg in #5326.
• Failing to set the device lost closure will call the closure before returning. By @bradwerth in #5358.
• Fix deadlocks caused by recursive read-write lock acquisitions #5426.
• Remove exposed C symbols (extern "C" + [no_mangle]) from RenderPass & ComputePass recording. By @wumpf in #5409.
• Fix surfaces being only compatible with first backend enabled on an instance, causing failures when manually specifying an adapter. By @Wumpf in #5535.

naga

• In spv-in, remove unnecessary "gl_PerVertex" name check so unused builtins will always be skipped. Prevents validation errors caused by capability requirements of these builtins #4915. By @Imberflur in #5227.
• In spv-out, check for acceleration and ray-query types when enabling ray-query extension to prevent validation error. By @Vecvec in #5463
• Add a limit for curly brace nesting in WGSL parsing, plus a note about stack size requirements. By @ErichDonGubler in #5447.
• In hlsl-out, fix accesses on zero value expressions by generating helper functions for Expression::ZeroValue. By @Imberflur in #5587.
• Fix behavior of extractBits and insertBits when offset + count overflows the bit width. By @cwfitzgerald in #5305
• Fix behavior of integer clamp when min argument > max argument. By @cwfitzgerald in #5300.
• Fix TypeInner::scalar_width to be consistent with the rest of the codebase and return values in bytes not bits. By @atlv24 in #5532.

GLES / OpenGL

• GLSL 410 does not support layout(binding = ...), enable only for GLSL 420. By @bes in #5357
• Fixes for being able to use an OpenGL 4.1 core context provided by macOS with wgpu. By @bes in #5331.
• Fix crash when holding multiple devices on wayland/surfaceless. By @ashdnazg in #5351.
• Fix first_instance getting ignored in draw indexed when ARB_shader_draw_parameters feature is present and base_vertex is 0. By @valaphee in #5482

Vulkan

• Set object labels when the DEBUG flag is set, even if the VALIDATION flag is disabled. By @DJMcNab in #5345.
• Add safety check to wgpu_hal::vulkan::CommandEncoder to make sure discard_encoding is not called in the closed state. By @villuna in #5557
• Fix SPIR-V type capability requests to not depend on LocalType caching. By @atlv24 in #5590
• Upgrade ash to 0.38. By @MarijnS95 in #5504.

Tests

• Fix intermittent crashes on Linux in the multithreaded_compute test. By @jimblandy in #5129.
• Refactor tests to read feature flags by name instead of a hardcoded hexadecimal u64. By @atlv24 in #5155.
• Add test that verifies that we can drop the queue before using the device to create a command encoder. By @Davidster in #5211

This release includes wgpu, wgpu-core, wgpu-hal, wgpu-types, and naga. All other crates are unchanged.

Added/New Features

General

• wgpu::Id now implements PartialOrd/Ord allowing it to be put in BTreeMaps. By @cwfitzgerald and @9291Sam in #5176

OpenGL

• Log an error when OpenGL texture format heuristics fail. By @PolyMeilex in #5266

wgsl-out

• Learned to generate acceleration structure types. By @JMS55 in #5261

Documentation

• Fix link in wgpu::Instance::create_surface documentation. By @HexoKnight in #5280.
• Fix typo in wgpu::CommandEncoder::clear_buffer documentation. By @PWhiddy in #5281.
• Surface configuration incorrectly claimed that wgpu::Instance::create_surface was unsafe. By @hackaugusto in #5265.

Bug Fixes

General

• Device lost callbacks are invoked when replaced and when global is dropped. By @bradwerth in #5168
• Fix performance regression when allocating a large amount of resources of the same type. By @nical in #5229
• Fix docs.rs wasm32 builds. By @cwfitzgerald in #5310
• Improve error message when binding count limit hit. By @hackaugusto in #5298
• Remove an unnecessary clone during GLSL shader ingestion. By @a1phyr in #5118.
• Fix missing validation for Device::clear_buffer where offset + size > buffer.size was not checked when size was omitted. By @ErichDonGubler in #5282.

DX12

• Fix panic! when dropping Instance without InstanceFlags::VALIDATION. By @hakolao in #5134

OpenGL

• Fix internal format for the Etc2Rgba8Unorm format. By @andristarr in #5178
• Try to load libX11.so.6 in addition to libX11.so on linux. #5307
• Make use of GL_EXT_texture_shadow_lod to support sampling a cube depth texture with an explicit LOD. By @cmrschwarz in #5171.

glsl-in

• Fix code generation from nested loops. By @cwfitzgerald and @teoxoy in #5311

This release includes:

• wgpu
• wgpu-core
• wgpu-hal
• wgpu-types
• wgpu-info
• naga (skipped from 0.14 to 0.19)
• naga-cli (skipped from 0.14 to 0.19)
• d3d12 (skipped from 0.7 to 0.19)

Improved Multithreading through internal use of Reference Counting

Large refactoring of wgpu’s internals aiming at reducing lock contention, and providing better performance when using wgpu on multiple threads.

Check the blog post!

By @gents83 in #3626 and thanks also to @jimblandy, @nical, @Wumpf, @Elabajaba & @cwfitzgerald

All Public Dependencies are Re-Exported

All of wgpu's public dependencies are now re-exported at the top level so that users don't need to take their own dependencies. This includes:

• wgpu-core
• wgpu-hal
• naga
• raw_window_handle
• web_sys

Feature Flag Changes

WebGPU & WebGL in the same Binary

Enabling webgl no longer removes the webgpu backend.

Instead, there's a new (default enabled) webgpu feature that allows to explicitly opt-out of webgpu if so desired. If both webgl & webgpu are enabled, wgpu::Instance decides upon creation whether to target wgpu-core/WebGL or WebGPU. This means that adapter selection is not handled as with regular adapters, but still allows to decide at runtime whether webgpu or the webgl backend should be used using a single wasm binary. By @wumpf in #5044

naga-ir Dedicated Feature

The naga-ir feature has been added to allow you to add naga module shaders without guessing about what other features needed to be enabled to get access to it. By @cwfitzgerald in #5063.

expose-ids Feature available unconditionally

This feature allowed you to call global_id on any wgpu opaque handle to get a unique hashable identity for the given resource. This is now available without the feature flag. By @cwfitzgerald in #4841.

dx12 and metal Backend Crate Features

wgpu now exposes backend feature for the Direct3D 12 (dx12) and Metal (metal) backend. These are enabled by default, but don't do anything when not targeting the corresponding OS. By @daxpedda in #4815.

Direct3D 11 Backend Removal

This backend had no functionality, and with the recent support for GL on Desktop, which allows wgpu to run on older devices, there was no need to keep this backend. By @valaphee in #4828.

WGPU_ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER Environment Variable

This adds a way to allow a Vulkan driver which is non-compliant per VK_KHR_driver_properties to be enumerated. This is intended for testing new Vulkan drivers which are not Vulkan compliant yet. By @i509VCB in #4754.

DeviceExt::create_texture_with_data allows Mip-Major Data

Previously, DeviceExt::create_texture_with_data only allowed data to be provided in layer major order. There is now a order parameter which allows you to specify if the data is in layer major or mip major order.

    let tex = ctx.device.create_texture_with_data(
        &queue,
        &descriptor,
+       wgpu::util::TextureDataOrder::LayerMajor,
        src_data,
    );

By @cwfitzgerald in #4780.

Safe & unified Surface Creation

It is now possible to safely create a wgpu::Surface with wgpu::Instance::create_surface() by letting wgpu::Surface hold a lifetime to window. Passing an owned value window to Surface will return a wgpu::Surface<'static>.

All possible safe variants (owned windows and web canvases) are grouped using wgpu::SurfaceTarget. Conversion to wgpu::SurfaceTarget is automatic for any type implementing raw-window-handle's HasWindowHandle & HasDisplayHandle traits, i.e. most window types. For web canvas types this has to be done explicitly:

let surface: wgpu::Surface<'static> = instance.create_surface(wgpu::SurfaceTarget::Canvas(my_canvas))?;

All unsafe variants are now grouped under wgpu::Instance::create_surface_unsafe which takes the wgpu::SurfaceTargetUnsafe enum and always returns wgpu::Surface<'static>.

In order to create a wgpu::Surface<'static> without passing ownership of the window use wgpu::SurfaceTargetUnsafe::from_window:

let surface = unsafe {
  instance.create_surface_unsafe(wgpu::SurfaceTargetUnsafe::from_window(&my_window))?
};

The easiest way to make this code safe is to use shared ownership:

let window: Arc<winit::Window>;
// ...
let surface = instance.create_surface(window.clone())?;

All platform specific surface creation using points have moved into SurfaceTargetUnsafe as well. For example:

Safety by @daxpedda in #4597 Unification by @wumpf in #4984

Add partial Support for WGSL Abstract Types

Abstract types make numeric literals easier to use, by automatically converting literals and other constant expressions from abstract numeric types to concrete types when safe and necessary. For example, to build a vector of floating-point numbers, naga previously made you write:

vec3<f32>(1.0, 2.0, 3.0)

With this change, you can now simply write:

vec3<f32>(1, 2, 3)

Even though the literals are abstract integers, naga recognizes that it is safe and necessary to convert them to f32 values in order to build the vector. You can also use abstract values as initializers for global constants and global and local variables, like this:

var unit_x: vec2<f32> = vec2(1, 0);

The literals 1 and 0 are abstract integers, and the expression vec2(1, 0) is an abstract vector. However, naga recognizes that it can convert that to the concrete type vec2<f32> to satisfy the given type of unit_x. The WGSL specification permits abstract integers and floating-point values in almost all contexts, but naga's support for this is still incomplete. Many WGSL operators and builtin functions are specified to produce abstract results when applied to abstract inputs, but for now naga simply concretizes them all before applying the operation. We will expand naga's abstract type support in subsequent pull requests. As part of this work, the public types naga::ScalarKind and naga::Literal now have new variants, AbstractInt and AbstractFloat.

By @jimblandy in #4743, #4755.

Instance::enumerate_adapters now returns Vec<Adapter> instead of an ExactSizeIterator

This allows us to support WebGPU and WebGL in the same binary.

- let adapters: Vec<Adapter> = instance.enumerate_adapters(wgpu::Backends::all()).collect();
+ let adapters: Vec<Adapter> = instance.enumerate_adapters(wgpu::Backends::all());

By @wumpf in #5044

device.poll() now returns a MaintainResult instead of a bool

This is a forward looking change, as we plan to add more information to the MaintainResult in the future. This enum has the same data as the boolean, but with some useful helper functions.

- let queue_finished: bool = device.poll(wgpu::Maintain::Wait);
+ let queue_finished: bool = device.poll(wgpu::Maintain::Wait).is_queue_empty();

By @cwfitzgerald in #5053

New Features

General

• Added DownlevelFlags::VERTEX_AND_INSTANCE_INDEX_RESPECTS_RESPECTIVE_FIRST_VALUE_IN_INDIRECT_DRAW to know if @builtin(vertex_index) and @builtin(instance_index) will respect the first_vertex / first_instance in indirect calls. If this is not present, both will always start counting from 0. Currently enabled on all backends except DX12. By @cwfitzgerald in #4722.
• Added support for the FLOAT32_FILTERABLE feature (web and native, corresponds to WebGPU's float32-filterable). By @almarklein in #4759.
• GPU buffer memory is released during "lose the device". By @bradwerth in #4851.
• wgpu and wgpu-core cargo feature flags are now documented on docs.rs. By @wumpf in #4886.
• DeviceLostClosure is guaranteed to be invoked exactly once. By @bradwerth in #4862.
• Log vulkan validation layer messages during instance creation and destruction: By @exrook in #4586.
• TextureFormat::block_size is deprecated, use TextureFormat::block_copy_size instead: By @wumpf in #4647.
• Rename of DispatchIndirect, DrawIndexedIndirect, and DrawIndirect types in the wgpu::util module to DispatchIndirectArgs, DrawIndexedIndirectArgs, and DrawIndirectArgs. By @cwfitzgerald in #4723.
• Make the size parameter of encoder.clear_buffer an Option<u64> instead of Option<NonZero<u64>>. By @nical in #4737.
• Reduce the info log level noise. By @nical in #4769, #4711 and #4772
• Rename features & limits fields of DeviceDescriptor to required_features & required_limits. By @teoxoy in #4803.
• SurfaceConfiguration now exposes desired_maximum_frame_latency which was previously hard-coded to 2. By setting it to 1 you can reduce latency under the risk of making GPU & CPU work sequential. Currently, on DX12 this affects the MaximumFrameLatency, on all other backends except OpenGL the size of the swapchain (on OpenGL this has no effect). By @emilk & @wumpf in #4899

OpenGL

• @builtin(instance_index) now properly reflects the range provided in the draw call instead of always counting from 0. By @cwfitzgerald in #4722.
• Desktop GL now supports POLYGON_MODE_LINE and POLYGON_MODE_POINT. By @valaphee in #4836.

naga

• naga's WGSL front end now allows operators to produce values with abstract types, rather than concretizing their operands. By @jimblandy in #4850 and #4870.
• naga's WGSL front and back ends now have experimental support for 64-bit floating-point literals: 1.0lf denotes an f64 value. There has been experimental support for an f64 type for a while, but until now there was no syntax for writing literals with that type. As before, naga module validation rejects f64 values unless naga::valid::Capabilities::FLOAT64 is requested. By @jimblandy in #4747.
• naga constant evaluation can now process binary operators whose operands are both vectors. By @jimblandy in #4861.
• Add --bulk-validate option to naga CLI. By @jimblandy in #4871.
• naga's cargo xtask validate now runs validation jobs in parallel, using the jobserver protocol to limit concurrency, and offers a validate all subcommand, which runs all available validation types. By @jimblandy in #4902.
• Remove span and validate features. Always fully validate shader modules, and always track source positions for use in error messages. By @teoxoy in #4706.
• Introduce a new Scalar struct type for use in naga's IR, and update all frontend, middle, and backend code appropriately. By @jimblandy in #4673.
• Add more metal keywords. By @fornwall in #4707.
• Add a new naga::Literal variant, I64, for signed 64-bit literals. #4711.
• Emit and init struct member padding always. By @ErichDonGubler in #4701.
• In WGSL output, always include the i suffix on i32 literals. By @jimblandy in #4863.
• In WGSL output, always include the f suffix on f32 literals. By @jimblandy in #4869.

Bug Fixes

General

• BufferMappedRange trait is now WasmNotSendSync, i.e. it is Send/Sync if not on wasm or fragile-send-sync-non-atomic-wasm is enabled. By @wumpf in #4818.
• Align wgpu_types::CompositeAlphaMode serde serialization to spec. By @littledivy in #4940.
• Fix error message of ConfigureSurfaceError::TooLarge. By @Dinnerbone in #4960.
• Fix dropping of DeviceLostCallbackC params. By @bradwerth in #5032.
• Fixed a number of panics. By @nical in #4999, #5014, #5024, #5025, #5026, #5027, #5028 and #5042.
• No longer validate surfaces against their allowed extent range on configure. This caused warnings that were almost impossible to avoid. As before, the resulting behavior depends on the compositor. By @wumpf in #4796.

DX12

• Fixed D3D12_SUBRESOURCE_FOOTPRINT calculation for block compressed textures which caused a crash with Queue::write_texture on DX12. By @DTZxPorter in #4990.

Vulkan

• Use VK_EXT_robustness2 only when not using an outdated intel iGPU driver. By @TheoDulka in #4602.

WebGPU

• Allow calling BufferSlice::get_mapped_range multiple times on the same buffer slice (instead of throwing a Javascript exception). By @DouglasDwyer in #4726.

WGL

• Create a hidden window per wgpu::Instance instead of sharing a global one. By @Zoxc in #4603

naga

• Make module compaction preserve the module's named types, even if they are unused. By @jimblandy in #4734.
• Improve algorithm used by module compaction. By @jimblandy in #4662.
• When reading GLSL, fix the argument types of the double-precision floating-point overloads of the dot, reflect, distance, and ldexp builtin functions. Correct the WGSL generated for constructing 64-bit floating-point matrices. Add tests for all the above. By @jimblandy in #4684.
• Allow naga's IR types to represent matrices with elements elements of any scalar kind. This makes it possible for naga IR types to represent WGSL abstract matrices. By @jimblandy in #4735.
• Preserve the source spans for constants and expressions correctly across module compaction. By @jimblandy in #4696.
• Record the names of WGSL alias declarations in naga IR Types. By @jimblandy in #4733.

Metal

• Allow the COPY_SRC usage flag in surface configuration. By @Toqozz in #4852.

Examples

• remove winit dependency from hello-compute example. By @psvri in #4699
• hello-compute example fix failure with wgpu error: Validation Error if arguments are missing. By @vilcans in #4939.
• Made the examples page not crash on Chrome on Android, and responsive to screen sizes. By @Dinnerbone in #4958.

For naga changelogs at or before v0.14.0. See naga's changelog.

Desktop OpenGL 3.3+ Support on Windows

We now support OpenGL on Windows! This brings support for a vast majority of the hardware that used to be covered by our DX11 backend. As of this writing we support OpenGL 3.3+, though there are efforts to reduce that further.

This allows us to cover the last 12 years of Intel GPUs (starting with Ivy Bridge; aka 3xxx), and the last 16 years of AMD (starting with Terascale; aka HD 2000) / NVidia GPUs (starting with Tesla; aka GeForce 8xxx).

By @Zoxc in #4248

Timestamp Queries Supported on Metal and OpenGL

Timestamp queries are now supported on both Metal and Desktop OpenGL. On Apple chips on Metal, they only support timestamp queries in command buffers or in the renderpass descriptor, they do not support them inside a pass.

Metal: By @Wumpf in #4008 OpenGL: By @Zoxc in #4267

Render/Compute Pass Query Writes

Addition of the TimestampWrites type to compute and render pass descriptors to allow profiling on tilers which do not support timestamps inside passes.

Added an example to demonstrate the various kinds of timestamps.

Additionally, metal now supports timestamp queries!

By @FL33TW00D & @wumpf in #3636.

Occlusion Queries

We now support binary occlusion queries! This allows you to determine if any of the draw calls within the query drew any pixels.

Use the new occlusion_query_set field on RenderPassDescriptor to give a query set that occlusion queries will write to.

let mut rpass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
    // ...
+   occlusion_query_set: Some(&my_occlusion_query_set),
});

Within the renderpass do the following to write the occlusion query results to the query set at the given index:

rpass.begin_occlusion_query(index);
rpass.draw(...);
rpass.draw(...);
rpass.end_occlusion_query();

These are binary occlusion queries, so the result will be either 0 or an unspecified non-zero value.

By @Valaphee in #3402

Shader Improvements

// WGSL constant expressions are now supported!
const BLAH: u32 = 1u + 1u;

// `rgb10a2uint` and `bgra8unorm` can now be used as a storage image format.
var image: texture_storage_2d<rgb10a2uint, write>;
var image: texture_storage_2d<bgra8unorm, write>;

// You can now use dual source blending!
struct FragmentOutput{
    @location(0) source1: vec4<f32>,
    @location(0) @second_blend_source source2: vec4<f32>,
}

// `modf`/`frexp` now return structures
let result = modf(1.5);
result.fract == 0.5;
result.whole == 1.0;

let result = frexp(1.5);
result.fract == 0.75;
result.exponent == 2i;

// `modf`/`frexp` are currently disabled on GLSL and SPIR-V input.

Shader Validation Improvements

// Cannot get pointer to a workgroup variable
fn func(p: ptr<workgroup, u32>); // ERROR

// Cannot create Inf/NaN through constant expressions
const INF: f32 = 3.40282347e+38 + 1.0; // ERROR
const NAN: f32 = 0.0 / 0.0; // ERROR

// `outerProduct` function removed

// Error on repeated or missing `@workgroup_size()`
@workgroup_size(1) @workgroup_size(2) // ERROR
fn compute_main() {}

// Error on repeated attributes.
fn fragment_main(@location(0) @location(0) location_0: f32) // ERROR

RenderPass StoreOp is now Enumeration

wgpu::Operations::store used to be an underdocumented boolean value, causing misunderstandings of the effect of setting it to false.

The API now more closely resembles WebGPU which distinguishes between store and discard, see WebGPU spec on GPUStoreOp.

// ...
depth_ops: Some(wgpu::Operations {
    load: wgpu::LoadOp::Clear(1.0),
-   store: false,
+   store: wgpu::StoreOp::Discard,
}),
// ...

By @wumpf in #4147

Instance Descriptor Settings

The instance descriptor grew two more fields: flags and gles_minor_version.

flags allow you to toggle the underlying api validation layers, debug information about shaders and objects in capture programs, and the ability to discard labels

gles_minor_version is a rather niche feature that allows you to force the GLES backend to use a specific minor version, this is useful to get ANGLE to enable more than GLES 3.0.

let instance = wgpu::Instance::new(InstanceDescriptor {
    ...
+   flags: wgpu::InstanceFlags::default()
+   gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
});

gles_minor_version: By @PJB3005 in #3998 flags: By @nical in #4230

Many New Examples!

• Added the following examples: By @JustAnotherCodemonkey in #3885.
  • repeated-compute
  • storage-texture
  • render-to-texture
  • uniform-values
  • hello-workgroups
  • hello-synchronization

Revamped Testing Suite

Our testing harness was completely revamped and now automatically runs against all gpus in the system, shows the expected status of every test, and is tolerant to flakes.

Additionally, we have filled out our CI to now run the latest versions of WARP and Mesa. This means we can test even more features on CI than before.

By @cwfitzgerald in #3873

The GLES backend is now optional on macOS

The angle feature flag has to be set for the GLES backend to be enabled on Windows & macOS.

By @teoxoy in #4185

Added/New Features

• Re-export naga. By @exrook in #4172
• Add WinUI 3 SwapChainPanel support. By @ddrboxman in #4191

Changes

General

• Omit texture store bound checks since they are no-ops if out of bounds on all APIs. By @teoxoy in #3975
• Validate DownlevelFlags::READ_ONLY_DEPTH_STENCIL. By @teoxoy in #4031
• Add validation in accordance with WebGPU setViewport valid usage for x, y and this.[[attachment_size]]. By @James2022-rgb in #4058
• wgpu::CreateSurfaceError and wgpu::RequestDeviceError now give details of the failure, but no longer implement PartialEq and cannot be constructed. By @kpreid in #4066 and #4145
• Make WGPU_POWER_PREF=none a valid value. By @fornwall in 4076
• Support dual source blending in OpenGL ES, Metal, Vulkan & DX12. By @freqmod in 4022
• Add stub support for device destroy and device validity. By @bradwerth in 4163 and in 4212
• Add trace-level logging for most entry points in wgpu-core By @nical in 4183
• Add Rgb10a2Uint format. By @teoxoy in 4199
• Validate that resources are used on the right device. By @nical in 4207
• Expose instance flags.
• Add support for the bgra8unorm-storage feature. By @jinleili and @nical in #4228
• Calls to lost devices now return DeviceError::Lost instead of DeviceError::Invalid. By @bradwerth in #4238
• Let the "strict_asserts" feature enable check that wgpu-core's lock-ordering tokens are unique per thread. By @jimblandy in #4258
• Allow filtering labels out before they are passed to GPU drivers by @nical in https://github.com/gfx-rs/wgpu/pull/4246
• DeviceLostClosure callback mechanism provided so user agents can resolve GPUDevice.lost Promises at the appropriate time by @bradwerth in #4645

Vulkan

• Rename wgpu_hal::vulkan::Instance::required_extensions to desired_extensions. By @jimblandy in #4115
• Don't bother calling vkFreeCommandBuffers when vkDestroyCommandPool will take care of that for us. By @jimblandy in #4059

DX12

• Bump gpu-allocator to 0.23. By @Elabajaba in #4198

Documentation

• Use WGSL for VertexFormat example types. By @ScanMountGoat in #4035
• Fix description of Features::TEXTURE_COMPRESSION_ASTC_HDR in #4157

Bug Fixes

General

• Derive storage bindings via naga::StorageAccess instead of naga::GlobalUse. By @teoxoy in #3985.
• Queue::on_submitted_work_done callbacks will now always be called after all previous BufferSlice::map_async callbacks, even when there are no active submissions. By @cwfitzgerald in #4036.
• Fix clear texture views being leaked when wgpu::SurfaceTexture is dropped before it is presented. By @rajveermalviya in #4057.
• Add Feature::SHADER_UNUSED_VERTEX_OUTPUT to allow unused vertex shader outputs. By @Aaron1011 in #4116.
• Fix a panic in surface_configure. By @nical in #4220 and #4227
• Pipelines register their implicit layouts in error cases. By @bradwerth in #4624
• Better handle explicit destruction of textures and buffers. By @nical in #4657

Vulkan

• Fix enabling wgpu::Features::PARTIALLY_BOUND_BINDING_ARRAY not being actually enabled in vulkan backend. By @39ali in#3772.
• Don't pass vk::InstanceCreateFlags::ENUMERATE_PORTABILITY_KHR unless the VK_KHR_portability_enumeration extension is available. By @jimblandy in#4038.
• Enhancement of [#4038], using ash's definition instead of hard-coded c_str. By @hybcloud in#4044.
• Enable vulkan presentation on (Linux) Intel Mesa >= v21.2. By @flukejones in#4110

DX12

• DX12 doesn't support `Features::POLYGON_MODE_POINT``. By @teoxoy in #4032.
• Set Features::VERTEX_WRITABLE_STORAGE based on the right feature level. By @teoxoy in #4033.

Metal

• Ensure that MTLCommandEncoder calls endEncoding before it is deallocated. By @bradwerth in #4023

WebGPU

• Ensure that limit requests and reporting is done correctly. By @OptimisticPeach in #4107
• Validate usage of polygon mode. By @teoxoy in #4196

GLES

• enable/disable blending per attachment only when available (on ES 3.2 or higher). By @teoxoy in #4234

Documentation

• Add an overview of RenderPass and how render state works. By @kpreid in #4055

Examples

• Created wgpu-example::utils module to contain misc functions and such that are common code but aren't part of the example framework. Add to it the functions output_image_wasm and output_image_native, both for outputting Vec<u8> RGBA images either to the disc or the web page. By @JustAnotherCodemonkey in #3885.
• Removed capture example as it had issues (did not run on wasm) and has been replaced by render-to-texture (see above). By @JustAnotherCodemonkey in #3885.

This is the first release that featured wgpu-info as a binary crate for getting information about what devices wgpu sees in your system. It can dump the information in both human readable format and json.

Major Changes

This release was fairly minor as breaking changes go.

wgpu types now !Send !Sync on wasm

Up until this point, wgpu has made the assumption that threads do not exist on wasm. With the rise of libraries like wasm_thread making it easier and easier to do wasm multithreading this assumption is no longer sound. As all wgpu objects contain references into the JS heap, they cannot leave the thread they started on.

As we understand that this change might be very inconvenient for users who don't care about wasm threading, there is a crate feature which re-enables the old behavior: fragile-send-sync-non-atomic-wasm. So long as you don't compile your code with -Ctarget-feature=+atomics, Send and Sync will be implemented again on wgpu types on wasm. As the name implies, especially for libraries, this is very fragile, as you don't know if a user will want to compile with atomics (and therefore threads) or not.

By @daxpedda in #3691

Power Preference is now optional

The power_preference field of RequestAdapterOptions is now optional. If it is PowerPreference::None, we will choose the first available adapter, preferring GPU adapters over CPU adapters.

By @Aaron1011 in #3903

initialize_adapter_from_env argument changes

Removed the backend_bits parameter from initialize_adapter_from_env and initialize_adapter_from_env_or_default. If you want to limit the backends used by this function, only enable the wanted backends in the instance.

Added a compatible surface parameter, to ensure the given device is able to be presented onto the given surface.

- wgpu::util::initialize_adapter_from_env(instance, backend_bits);
+ wgpu::util::initialize_adapter_from_env(instance, Some(&compatible_surface));

By @fornwall in #3904 and #3905

Misc Breaking Changes

• Change AdapterInfo::{device,vendor} to be u32 instead of usize. By @ameknite in #3760

Changes

• Added support for importing external buffers using buffer_from_raw (Dx12, Metal, Vulkan) and create_buffer_from_hal. By @AdrianEddy in #3355

Vulkan

• Work around Vulkan-ValidationLayers#5671 by ignoring reports of violations of VUID-vkCmdEndDebugUtilsLabelEXT-commandBuffer-01912. By @jimblandy in #3809.

Added/New Features

General

• Empty scissor rects are allowed now, matching the specification. by @PJB3005 in #3863.
• Add back components info to TextureFormats. By @teoxoy in #3843.
• Add get_mapped_range_as_array_buffer for faster buffer read-backs in wasm builds. By @ryankaplan in [#4042] (https://github.com/gfx-rs/wgpu/pull/4042).

Documentation

• Better documentation for draw, draw_indexed, set_viewport and set_scissor_rect. By @genusistimelord in #3860
• Fix link to GPUVertexBufferLayout. By @fornwall in #3906
• Document feature requirements for DEPTH32FLOAT_STENCIL8 by @ErichDonGubler in #3734.
• Flesh out docs. for AdapterInfo::{device,vendor} by @ErichDonGubler in #3763.
• Spell out which sizes are in bytes. By @jimblandy in #3773.
• Validate that descriptor.usage is not empty in create_buffer by @nical in #3928
• Update max_bindings_per_bind_group limit to reflect spec changes by @ErichDonGubler and @nical in #3943 #3942
• Add better docs for Limits, listing the actual limits returned by downlevel_defaults and downlevel_webgl2_defaults by @JustAnotherCodemonkey in #3988

Bug Fixes

General

• Fix order of arguments to glPolygonOffset by @komadori in #3783.
• Fix OpenGL/EGL backend not respecting non-sRGB texture formats in SurfaceConfiguration. by @liquidev in #3817
• Make write- and read-only marked buffers match non-readonly layouts. by @fornwall in #3893
• Fix leaking X11 connections. by @wez in #3924
• Fix ASTC feature selection in the webgl backend. by @expenses in #3934
• Fix Multiview to disable validation of TextureViewDimension and ArrayLayerCount. By @MalekiRe in #3779.

Vulkan

• Fix incorrect aspect in barriers when using emulated Stencil8 textures. By @cwfitzgerald in #3833.
• Implement depth-clip-control using depthClamp instead of VK_EXT_depth_clip_enable. By @AlbinBernhardssonARM #3892.
• Fix enabling wgpu::Features::PARTIALLY_BOUND_BINDING_ARRAY not being actually enabled in vulkan backend. By @39ali in#3772.

Metal

• Fix renderpasses being used inside of renderpasses. By @cwfitzgerald in #3828
• Support (simulated) visionOS. By @jinleili in #3883

DX12

• Disable suballocation on Intel Iris(R) Xe. By @xiaopengli89 in #3668
• Change the max_buffer_size limit from u64::MAX to i32::MAX. By @nical in #4020

WebGPU

• Use get_preferred_canvas_format() to fill formats of SurfaceCapabilities. By @jinleili in #3744

Examples

• Publish examples to wgpu.rs on updates to trunk branch instead of gecko. By @paul-hansen in #3750
• Ignore the exception values generated by the winit resize event. By @jinleili in #3916

Bug Fixes

• Fix missing 4X MSAA support on some OpenGL backends. By @emilk in #3780

General

• Fix crash on dropping wgpu::CommandBuffer. By @wumpf in #3726.
• Use u32s internally for bind group indices, rather than u8. By @ErichDonGubler in #3743.

WebGPU

• Fix crash when calling create_surface_from_canvas. By @grovesNL in #3718

Major changes

Shader Changes

type has been replaced with alias to match with upstream WebGPU.

- type MyType = vec4<u32>;
+ alias MyType = vec4<u32>;

TextureFormat info API

The TextureFormat::describe function was removed in favor of separate functions: block_dimensions, is_compressed, is_srgb, required_features, guaranteed_format_features, sample_type and block_size.

- let block_dimensions = format.describe().block_dimensions;
+ let block_dimensions = format.block_dimensions();
- let is_compressed = format.describe().is_compressed();
+ let is_compressed = format.is_compressed();
- let is_srgb = format.describe().srgb;
+ let is_srgb = format.is_srgb();
- let required_features = format.describe().required_features;
+ let required_features = format.required_features();

Additionally guaranteed_format_features now takes a set of features to assume are enabled.

- let guaranteed_format_features = format.describe().guaranteed_format_features;
+ let guaranteed_format_features = format.guaranteed_format_features(device.features());

Additionally sample_type and block_size now take an optional TextureAspect and return Options.

- let sample_type = format.describe().sample_type;
+ let sample_type = format.sample_type(None).expect("combined depth-stencil format requires specifying a TextureAspect");
- let block_size = format.describe().block_size;
+ let block_size = format.block_size(None).expect("combined depth-stencil format requires specifying a TextureAspect");

By @teoxoy in #3436

BufferUsages::QUERY_RESOLVE

Buffers used as the destination argument of CommandEncoder::resolve_query_set now have to contain the QUERY_RESOLVE usage instead of the COPY_DST usage.

  let destination = device.create_buffer(&wgpu::BufferDescriptor {
      // ...
-     usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
+     usage: wgpu::BufferUsages::QUERY_RESOLVE | wgpu::BufferUsages::MAP_READ,
      mapped_at_creation: false,
  });
  command_encoder.resolve_query_set(&query_set, query_range, &destination, destination_offset);

By @JolifantoBambla in #3489

Renamed features

The following Features have been renamed.

• SHADER_FLOAT16 -> SHADER_F16
• SHADER_FLOAT64 -> SHADER_F64
• SHADER_INT16 -> SHADER_I16
• TEXTURE_COMPRESSION_ASTC_LDR -> TEXTURE_COMPRESSION_ASTC
• WRITE_TIMESTAMP_INSIDE_PASSES -> TIMESTAMP_QUERY_INSIDE_PASSES

By @teoxoy in #3534

Anisotropic Filtering

Anisotropic filtering has been brought in line with the spec. The anisotropic clamp is now a u16 (was a Option<u8>) which must be at least 1.

If the anisotropy clamp is not 1, all the filters in a sampler must be Linear.

SamplerDescriptor {
-    anisotropic_clamp: None,
+    anisotropic_clamp: 1,
}

By @cwfitzgerald in #3610.

TextureFormat Names

Some texture format names have changed to get back in line with the spec.

- TextureFormat::Bc6hRgbSfloat
+ TextureFormat::Bc6hRgbFloat

By @cwfitzgerald in #3671.

Misc Breaking Changes

• Change type of mip_level_count and array_layer_count (members of TextureViewDescriptor and ImageSubresourceRange) from Option<NonZeroU32> to Option<u32>. By @teoxoy in #3445
• Change type of bytes_per_row and rows_per_image (members of ImageDataLayout) from Option<NonZeroU32> to Option<u32>. By @teoxoy in #3529
• On Web, Instance::create_surface_from_canvas() and create_surface_from_offscreen_canvas() now take the canvas by value. By @daxpedda in #3690

Added/New Features

General

• Added feature flags for ray-tracing (currently only hal): RAY_QUERY and RAY_TRACING @daniel-keitel (started by @expenses) in #3507

Vulkan

• Implemented basic ray-tracing api for acceleration structures, and ray-queries @daniel-keitel (started by @expenses) in #3507

Hal

• Added basic ray-tracing api for acceleration structures, and ray-queries @daniel-keitel (started by @expenses) in #3507

Changes

General

• Added TextureFormatFeatureFlags::MULTISAMPLE_X16. By @Dinnerbone in #3454
• Added BufferUsages::QUERY_RESOLVE. By @JolifantoBambla in #3489
• Support stencil-only views and copying to/from combined depth-stencil textures. By @teoxoy in #3436
• Added Features::SHADER_EARLY_DEPTH_TEST. By @teoxoy in #3494
• All fxhash dependencies have been replaced with rustc-hash. By @james7132 in #3502
• Allow copying of textures with copy-compatible formats. By @teoxoy in #3528
• Improve attachment related errors. By @cwfitzgerald in #3549
• Make error descriptions all upper case. By @cwfitzgerald in #3549
• Don't include ANSI terminal color escape sequences in shader module validation error messages. By @jimblandy in #3591
• Report error messages from DXC compile. By @Davidster in #3632
• Error in native when using a filterable TextureSampleType::Float on a multisample BindingType::Texture. By @mockersf in #3686
• On Web, the size of the canvas is adjusted when using Surface::configure(). If the canvas was given an explicit size (via CSS), this will not affect the visual size of the canvas. By @daxpedda in #3690
• Added Global::create_render_bundle_error. By @jimblandy in #3746

WebGPU

• Implement the new checks for readonly stencils. By @JCapucho in #3443
• Reimplement adapter|device_features. By @jinleili in #3428
• Implement command_encoder_resolve_query_set. By @JolifantoBambla in #3489
• Add support for Features::RG11B10UFLOAT_RENDERABLE. By @mockersf in #3689

Vulkan

• Set max_memory_allocation_size via PhysicalDeviceMaintenance3Properties. By @jinleili in #3567
• Silence false-positive validation error about surface resizing. By @seabassjh in #3627

Bug Fixes

General

• copyTextureToTexture src/dst aspects must both refer to all aspects of src/dst format. By @teoxoy in #3431
• Validate before extracting texture selectors. By @teoxoy in #3487
• Fix fatal errors (those which panic even if an error handler is set) not including all of the details. By @kpreid in #3563
• Validate shader location clashes. By @emilk in #3613
• Fix surfaces not being dropped until exit. By @benjaminschaaf in #3647

WebGPU

• Fix handling of None values for depth_ops and stencil_ops in RenderPassDescriptor::depth_stencil_attachment. By @niklaskorz in #3660
• Avoid using WasmAbi functions for WebGPU backend. By @grovesNL in #3657

DX12

• Use typeless formats for textures that might be viewed as srgb or non-srgb. By @teoxoy in #3555

GLES

• Set FORCE_POINT_SIZE if it is vertex shader with mesh consist of point list. By @REASY in 3440
• Remove unwraps inside surface.configure. By @cwfitzgerald in #3585
• Fix copy_external_image_to_texture, copy_texture_to_texture and copy_buffer_to_texture not taking the specified index into account if the target texture is a cube map, 2D texture array or cube map array. By @daxpedda #3641
• Fix disabling of vertex attributes with non-consecutive locations. By @Azorlogh in #3706

Metal

• Fix metal erroring on an array_stride of 0. By @teoxoy in #3538
• create_texture returns an error if new_texture returns NULL. By @jinleili in #3554
• Fix shader bounds checking being ignored. By @FL33TW00D in #3603

Vulkan

• Treat VK_SUBOPTIMAL_KHR as VK_SUCCESS on Android due to rotation issues. By @James2022-rgb in #3525

Examples

• Use BufferUsages::QUERY_RESOLVE instead of BufferUsages::COPY_DST for buffers used in CommandEncoder::resolve_query_set calls in mipmap example. By @JolifantoBambla in #3489