NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
crates.io · #1498 most downloaded on crates.io
Shader translator and validator. Part of the wgpu project
Last release 1 months ago
22 Aug 2026
Ships fairly regularly
a new release about every 2 months
Most releases are documented
notes for 40 of 57 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
57 releases · first in 2020
One column per quarter.
Stop passing an un-waited fence to vkAcquireNextImageKHR on non-Windows platforms, which triggered VUID-vkAcquireNextImageKHR-fence-10066 validation e
vkAcquireNextImageKHR on non-Windows platforms, which triggered VUID-vkAcquireNextImageKHR-fence-10066 validation errors every frame since v30.0.0. By @ErichDonGubler in #9855.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.
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)
],
};@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.
Creating a BufferSlice with a length of 0 no longer causes a panic.
Empty buffer slices can be:
Empty buffer slices cannot be:
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(); // panicRelatedly, BufferSlice::size() now returns BufferAddress (u64) instead of BufferSize (NonZero<u64>), since an empty slice has size 0.
By @beholdnec in #8505.
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:
| Color space / feature | Vulkan | DX12 | Metal | WebGPU | GLES |
|---|---|---|---|---|---|
Srgb |
✅ | ✅ | ✅ | ✅ | ✅ |
ExtendedSrgb |
✅¹ | ❌ | ✅ | ✅ | ❌ |
ExtendedSrgbLinear (scRGB) |
✅¹ | ✅ | ✅ | ❌ | ❌ |
DisplayP3 |
✅¹ | ❌ | ✅ | ✅ | ❌ |
ExtendedDisplayP3 |
❌ | ❌ | ✅ | ✅ | ❌ |
Bt2100Pq (HDR10) |
✅¹ | ✅ | ✅ | ❌ | ❌ |
Bt2100Hlg |
✅¹ | ❌ | ✅ | ❌ | ❌ |
¹ 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.
naga-types crateTo 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.
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.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.BlasGeometrySizeDescriptors::AABBs, BlasAabbGeometry, and related descriptors). By @dylanblokhuis in #9290apply_limit_buckets member in RequestAdapterOptions, which is false by default. By @andyleiserson in #9119.wgpu_types::texture::format::TextureChannel accessible as wgpu::TextureChannel. By @TornaxO7 in #9349.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.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)
};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.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.InstanceFlags::STRICT_WEBGPU_COMPLIANCE flag, which restricts the available feature set to the one defined by the WebGPU specification. By @teoxoy in #9586.QuerySet::destroy by @sagudev in #9671QuerySet::ty and QuerySet::count getters. By @sagudev in #9672.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.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.spirv-out ray tracing pipelines. By @Vecvec in #9085.naga::front::wgsl::ParseError::notes(). By @kwillemsen in #9572.coopMultiplyAdd(f16, f16, f32) -> f32. By @seddonm1 in #9629.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.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::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.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.RawWindowHandle::Drm on Unix, conditional on the drm feature.
wgpu_hal::vulkan::Buffer::raw_handle() for retrieving the underlying vk::Buffer resource. By @WillowGriffiths in #9459.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.Features::CLIP_DISTANCES. By @ErichDonGubler in #9270.DropCallbacks to Metal textures. By @jerzywilczek in #9634.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.gles::Device::buffer_from_raw for wrapping an externally-owned GL buffer as a wgpu_hal::gles::Buffer. By @AdrianEddy in #9550.Features::TEXTURE_FORMAT_16BIT_NORM on OpenGL, including storage-texture usage where the driver supports it. By @AdrianEddy in #9601.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.InvalidWorkgroupSizeError, which is now used by DrawError::InvalidGroupSize and StageError::InvalidWorkgroupSize. By @andyleiserson in #9357.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.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.InvalidWorkgroupSizeError, which is now used by DrawError::InvalidGroupSize and StageError::InvalidWorkgroupSize.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.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).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).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.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.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.intersector to using an intersection_query on metal so AABBs and non-opaque triangles can be handled. By @Vecvec in #9304.maxInterStageShaderVariables. By @ErichDonGubler in #8762. This may break some existing programs, but it compiles with the WebGPU spec.LoadOp and StoreOp are None for attachments without corresponding depth or stencil aspect. By @beicause in #9567.SYNC-HAZARD-WRITE-AFTER-PRESENT on Vulkan when a surface texture is presented without being rendered to. By @inner-daemons and @atlv24 in #9361.set_bind_group in passes and bundles. By @ErichDonGubler in #9308.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.-Znext-solver. By @nazar-pc in #9609SurfaceTexture 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.acosh, length, normalize, and pow in constant evaluation. By @ecoricemon in #9249.f16. WGSL does not currently allow this, although it may be added in the future. By @andyleiserson in #9154.let x = myAtomic;). By @ecoricemon in #9262.@must_use appear only on function declarations. By @dnsn021 in #9367.naga::back::msl::Error::UnsupportedWritable* variant names. By @ErichDonGubler in #9376.enable wgpu_binding_array;. By @39ali in #9298.matCx2 fixes. By @teoxoy in #9507.packSnorm2x16 and packUnorm2x16 swap in the GLSL frontend. By @treylutton in #9675.var declarations without explicit initializers so they are zero-initialized each iteration. By @ruihe774 in #9592.TextureUsage::TEXTURE_BINDING as a read-only depth attachment. By @andyleiserson in #9346.debug_assert during stride validation for indirect multi draw. By @kristoff3r in #9332textureLoad appearing in G instead of R. By @andyleiserson in #9520.textureNum{Layers,Levels,Samples} functions returned incorrect results. By @andyleiserson in #9542.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.PARTIALLY_BOUND_BINDING_ARRAY) reading garbage in create_bind_group. By @holg in #9653.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.MatrixStride for mat2x2 in SPIR-V uniform blocks. By @39ali #9369.libvulkan.so on OpenHarmony (target_env = "ohos"). By @jschwe in #9649.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.% (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.Device::poll(PollType::wait_indefinitely()) when a Metal command buffer exits with an error.Queue::as_raw method, which was removed without good reason in v29. It now returns &ProtocolObject<dyn MTLCommandQueue>. By @andyleiserson in #9560.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 #9530Device::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 #9530wasm-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.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.XCB window handles can now be used to initialize OpenGL on Linux. By @reflectronic in #9271 .
Queue::as_raw method, which was removed without good reason in v29. It now returns &ProtocolObject<dyn MTLCommandQueue>. By @andyleiserson in #9560.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.Fix compilation error when cfg(debug_assertions) is not active. wgpu-core v29.0.2 has been yanked. By @Elabajaba in #9352 .
cfg(debug_assertions) is not active. wgpu-core v29.0.2 has been yanked. By @Elabajaba in #9352.Fix late bindings not being updated for identical pipeline layouts. By @kristoff3r in #9341 .
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.
debug_assert during stride validation for indirect multi draw. By @kristoff3r in #9332.max_binding_array_sampler_elements_per_shader_stage limit reported on DX12. By @kristoff3r in #9330.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.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 version
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.
max_inter_stage_shader_variables. By @ErichDonGubler in #9264.CaptureMTLDevice. By @andyleiserson in #9284.Display implementation of CreateTextureViewError::TooMany{MipLevels,ArrayLayers} when their base and offset overflow. By @ErichDonGubler in #8808.As before, MSRV bumps will always be breaking changes.
Surface::get_current_texture now returns CurrentSurfaceTexture enumSurface::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 changesA 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_handlenew_with_display_handle_from_envnew_without_display_handlenew_without_display_handle_from_envIf 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
PipelineLayoutDescriptorThis 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.
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.
WriteOnlyTo 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.
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(),
)),
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 extensionWGSL 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 maxInterStageShaderVariablesMigrated 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
StageError::InvalidWorkgroupSize. By @ErichDonGubler in #9192.ACCELERATION_STRUCTURE_BINDING_ARRAY. By @kvark in #8923.wgpu-naga-bridge crate with conversions between naga and wgpu-types (features to capabilities, storage format mapping, shader stage mapping). By @atlv24 in #9201.AdapterInfo from Device. By @sagudev in #8807.Limits::or_worse_values_from. By @atlv24 in #8870.Features::FLOAT32_BLENDABLE on Vulkan and Metal. By @timokoesters in #8963 and @andyleiserson in #9032.Dx12BackendOptions::force_shader_model to allow using advanced features in passthrough shaders without bundling DXC. By @inner-daemons in #8984.Dx12Compiler::Auto to automatically use static or dynamic DXC if available, before falling back to FXC. By @inner-daemons in #8882.insert_debug_marker, push_debug_group and pop_debug_group on WebGPU. By @evilpie in #9017.@builtin(draw_index) to the vulkan backend. By @inner-daemons in #8883.TextureFormat::channels method to get some information about which color channels are covered by the texture format. By @TornaxO7 in #9167V6_8 variant to DxcShaderModel and naga::back::hlsl::ShaderModel. By @inner-daemons in #8882 and @ErichDonGubler in #9083.V6_9 variant to DxcShaderModel and naga::back::hlsl::ShaderModel. By @ErichDonGubler in #9083.SPV_KHR_non_semantic_info for debug info. Also removes naga::front::spv::SUPPORTED_EXT_SETS. By @inner-daemons in #8827.coherent, supported on all native backends, and volatile, only on Vulkan and GL. By @atlv24 in #9168.const contexts; by @ErichDonGubler in #8943:
naga
Arena::lenArena::is_emptyRange::first_and_lastfront::wgsl::Frontend::set_optionsir::Block::is_emptyir::Block::lenGlDebugFns 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.insert_debug_marker, push_debug_group and pop_debug_group. By @evilpie in #9017.begin_occlusion_query and end_occlusion_query. By @evilpie in #9039..metal extension for metal source files, instead of .msl. By @inner-daemons in #8880.BufferAccessError:
OutOfBoundsOverrun variant into new OutOfBoundsStartOffsetOverrun and OutOfBoundsEndOffsetOverrun variants.NegativeRange variant in favor of new MapStartOffsetUnderrun and MapStartOffsetOverrun variants.TransferError::BufferOverrun variant into new BufferStartOffsetOverrun and BufferEndOffsetOverrun variants.ImmediateUploadError:
TooLarge variant in favor of new StartOffsetOverrun and EndOffsetOverrun variants.Unaligned variant in favor of new StartOffsetUnaligned and SizeUnaligned variants.ValueStartIndexOverrun and ValueEndIndexOverrun invariantsmax_bindings_per_bind_group, as required by WebGPU. By @andyleiserson in #9118.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.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.supported_capabilities to all backends. By @inner-daemons in #9068.objc2 bindings internally, which should resolve a lot of leaks and unsoundness. By @madsmtm in #5641.MTLCommandQueue because the Metal object is thread-safe. By @andyleiserson in #9217.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.@blend_src members whether or not they are used by an entry point.TypeFlags::IO_SHAREABLE is not set for structs other than @blend_src structs.strip_index_format isn't None and equals index buffer format for indexed drawing with strip topology. By @beicause in #8850.EXPERIMENTAL_PASSTHROUGH_SHADERS to PASSTHROUGH_SHADERS and made this no longer an experimental feature. By @inner-daemons in #9054.player commands are now represented using offset + size instead. By @ErichDonGubler in #9073.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.u32. By @andyleiserson in #8912.@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.workgroupUniformLoad incorrectly returning an atomic when called on an atomic, it now returns the inner T as per the spec. By @cryvosh in #8791.sign() builtin to return zero when the argument is zero. By @mandryskowski in #8942.u32 and i32). By @BKDaugherty in #9142.+=) LHS and RHS. By @andyleiserson in #9181.float16-format vertex input data was accessed via an f16-type variable in a vertex shader. By @andyleiserson in #9166.frag_depth, then the pipeline must have a depth attachment. By @andyleiserson in #8856.const v = vec2<i32>(); let r = v.xyz. By @andyleiserson in #8949.beginOcclusionQuery. By @andyleiserson in #9086.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.first_vertex field. By @Vecvec in #9220DisplayHandle 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.GL_EXT_multisampled_render_to_texture extension when applicable to skip the multi-sample resolve operation. By @opstic in #8536.QuerySet, QueryType, and resolve_query_set() describing how to use queries. By @kpreid in #8776.BREAKING CHANGE: enumerate_adapters is now async:
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);
}
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:
wgpu Contributions:
naga Contributions:
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.Testing Assistance:
Thank you to everyone to made this happen!
gpu-alloc to gpu-allocator in the vulkan backendgpu-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 WebGPUBREAKING 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:
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.By @R-Cramer4 in #8230
LoadOp::DontCareIn 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 FilterModeThis is a breaking change that aligns wgpu with spec.
SamplerDescriptor {
...
- mipmap_filter: FilterMode::Nearest
+ mipmap_filter: MipmapFilterMode::Nearest
...
}
By @sagudev in #8314.
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.
- 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
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:
wgpu or application developers.By @cwfitzgerald in #8579.
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 -> AdapterInfoTo 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.
MULTISAMPLE_ARRAY. By @LaylBongers in #8571.get_configuration to wgpu::Surface, that returns the current configuration of wgpu::Surface. By @sagudev in #8664.wgpu_core::Global::create_bind_group_layout_error. By @ErichDonGubler in #8650.wgpu_ray_query, wgpu_ray_query_vertex_return). By @Vecvec in #8545.from_custom. By @R-Cramer4 in #8315.CommandEncoder::as_hal_mut on the same encoder will now result in a panic.include_spirv! and include_spirv_raw! macros to be used in constants and statics. By @clarfonthey in #8250.CommandEncoder::finish() will report the label of the invalid encoder. By @kpreid in #8449.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.maxColorAttachmentBytesPerSample limit. By @andyleiserson in #8697.wgpu features, and this change should not be user-visible. By @andyleiserson in #8671.var<function> syntax for declaring local variables. By @andyleiserson in #8710.OperationError: GPUBuffer.getMappedRange: GetMappedRange range extends beyond buffer's mapped range. By @ryankaplan in #8349locations > max_color_attachments limit. By @ErichDonGubler in #8316.maxColorAttachments and maxColorAttachmentBytesPerSample. By @evilpie in #8328wgpu_types::Limits::max_bindings_per_bind_group when deriving a bind group layout for a pipeline. By @jimblandy in #8325.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.STORAGE_READ_ONLY texture usage is now permitted to coexist with other read-only usages. By @andyleiserson in #8490.write_buffer calls. By @ErichDonGubler in #8454.|| 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.program scope variable must reside in constant address space in some cases. By @teoxoy in #8311.rayQueryTerminate in spv-out instead of ignoring it. By @Vecvec in #8581.D3D12_FEATURE_DATA_D3D12_OPTIONS13.UnrestrictedBufferTextureCopyPitchSupported is false. By @ErichDonGubler in #7721.copy_texture_to_buffer in WebGPU, causing the copy to fail for depth/stencil textures. By @Tim-Evans-Seequent in #8445.VertexFormat::Unorm10_10_10_2 can now be used on gl backends. By @mooori in #8717.DropCallbacks are now called after dropping all other fields of their parent structs. By @jerzywilczek in #8353v28.0.0 - Mesh Shaders, Immediates, and More!
Compare
This release includes naga, wgpu-core and wgpu-hal version 27.0.3. All other crates remain at their previous versions.
This release includes naga, wgpu-core and wgpu-hal version 27.0.3. All other crates remain at their previous versions.
program scope variable must reside in constant address space in some cases. Backport of #8311 by @teoxoy.CommandEncoder::as_hal_mut is used. By @andyleiserson in #8387.You may schedule buffer mapping and a submission-complete callback to run automatically after you submit, directly from encoders, command buffers, and
map_buffer_on_submit and on_submitted_work_doneYou 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.
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_QUERYWe 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.
EXPERIMENTAL_PRECOMPILED_SHADERS APIWe 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::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 enableWe 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.
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 timeoutWe 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());
wgpu, with examples. Requires passthrough. By @SupaMaggie70Incorporated in #7345.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 & #8285naga::front::wgsl::UnimplementedEnableExtension. By @ErichDonGubler in #8237.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.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.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.
bytes_per_row on the buffer side must be 256B-aligned, even if the transfer is a single row.set_vertex_buffer and set_index_buffer must be 4B aligned. By @andyleiserson in #7929.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.min_subgroup_size <= max_subgroup_size. By @andyleiserson in #8085.BufferViews]. By @cwfitzgerald in #8150.F16_IN_F32 downlevel flag for quantizeToF16, pack2x16float, and unpack2x16float in WGSL input. By @aleiserson in #8130.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.storageInputOutput16. By @cryvosh in #7884.naga::proc::Namer now accepts reserved keywords using two new dedicated types, proc::{KeywordSet, CaseInsensitiveKeywordSet}. By @kpreid in #8136.rg11b10float was incorrectly accepted and generated by naga, but now only accepts the the correct name rg11b10ufloat instead. By @ErikWDev in #8219.source() method of ShaderError no longer reports the error as its own source. By @andyleiserson in #8258.create_swapchain(). By @MarijnS95 in #8226.@blend_src(…) attributes. By @ErichDonGubler in #8137.case values inside a switch. By @reima in #8165.SUBGROUP and SUBGROUP_BARRIER features / capabilities. By @andyleiserson in #8203.This release includes wgpu-hal version 26.0.6. All other crates remain at their previous versions.
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.You can now call texture_view.texture() to get access to the texture that a given texture view points to.
TextureView::textureYou 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.
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.
no_std support with default features disabled. By @Bushrat011899 in #7585.naga::front::glsl::Frontend::new_with_options. By @Vrixyz in #6364.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.SUBGROUP feature to be enabled). By @dzamkov and @valaphee in #7683.atomicCompareExchangeWeak in HLSL and GLSL backends. By @cryvosh in #7658wgpu_hal::dx12::Adapter::as_raw(). By @tronical in ##7852VK_KHR_maintenance1 which should be widely available on newer drivers). By @teoxoy in #7596wgpu_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.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()._. By @andyleiserson in #7540.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.pack4x{I,U}8Clamped built-ins to all backends and WGSL frontend. By @ErichDonGubler in #7546.value argument of textureStore. By @jimblandy in #7567.abs(most negative abstract int). By @jimblandy in #7507.[un]pack4x{I,U}8[Clamp] on SPIR-V and MSL 2.1+. By @robamler in #7664.select, which had issues particularly with a lack of automatic type conversion. By @ErichDonGubler in #7572.distance built-in function. By @bernhl in #7530.f16 for pipeline constants, i.e., overrides in WGSL. By @ErichDonGubler in #7801.vertex_index & instance_index builtins working for indirect draws. By @teoxoy in #7535wgpu_hal::vulkan::drm. By @ErichDonGubler in #7810.fn surface_capabilities(). By @jamesordner in #7692on_submitted_work_done for WebGPU backend. By @drewcrawford in #7864wgpu 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.MaintainBase in favor of using PollType. By @waywardmonkeys in #7508.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.CommandEncoder::build_acceleration_structures_unsafe_tlas in favour of as_hal and apply
simplifications allowed by this. By @Vecvec in #7513size 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.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().CommandEncoderError in the error enums ClearError, ComputePassErrorInner, QueryError, and RenderPassErrorInner have been replaced with variants holding an EncoderStateError.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).readonly_and_readwrite_storage_textures & packed_4x8_integer_dot_product language extensions as implemented. By @teoxoy in #7543naga::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.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.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.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.IDXGIFactory4 from Instance. By @MendyBerger in #7827no_std support to wgpu-hal. By @bushrat011899 in #7599Adapter::request_device. By @tesselode in #7768Fix typos in various documentation. By @waywardmonkeys in #7510.
profiling/profile-with-* feature enabled. By @waywardmonkeys in #7509.once_cell::race::OnceBox instead of std::sync::LazyLock to allow naga::proc::Namer::default() to be available without backend features being enabled. By @cwfitzgerald in #7517.Internally split up the Features struct and recombine them internally using a macro. There should be no breaking changes from this. This means there a…
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
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 = falseand you want to retain thevulkanandglesbackends, 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 ReworkedThis 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 returnTimeoutif the submission has not already completed. As many people rely on this behavior on WebGL, there is a new options inBackendOptions. 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
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.
Features internallyInternally 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.
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
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.
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 shadersPreviously 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
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 resourcesmax_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.
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.BufferSlice::buffer(), BufferSlice::offset() and BufferSlice::size(). By @kpreid in #7148.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.util::StagingBelt::allocate() so the staging belt can be used to write textures. By @kpreid in #6900.CommandEncoder::transition_resources() for native API interop, and allowing users to slightly optimize barriers. By @JMS55 in #6678.wgpu_hal::vulkan::Adapter::texture_format_as_raw for native API interop. By @JMS55 in #7228.as_hal for both acceleration structures. By @Vecvec in #7303.create_shader_module_passthrough on device. By @syl20bnr in #7326.Features::MSL_SHADER_PASSTHROUGH run-time feature allows providing pass-through MSL Metal shaders. By @syl20bnr in #7326.wgpu_hal. By @SupaMaggie70Incorporated in #7089unpackSnorm4x8, unpackUnorm4x8, unpackSnorm2x16, unpackUnorm2x16 for GLSL versions they aren't supported in. By @DJMcNab in #7408.GPUBuffer by distributing it across many buffers, and then having the shader receive them as a binding_array of storage buffers. By @alphastrata in #6138wgpu::Instance::request_adapter() now returns Result instead of Option; the error provides information about why no suitable adapter was returned. By @kpreid in #7330.hashbrown to simplify no-std support. By Brody in #6938 & #6925.instance_id and instance_custom_index to instance_index and instance_custom_data by @Vecvec in
#6780naga::ir (e.g. naga::ir::Module).
The original names (e.g. naga::Module) remain present for compatibility.
By @kpreid in #7365.use statements to simplify future no_std support. By @bushrat011899 in #7256& operator to take the address of a component of a vector,
which is not permitted by the WGSL specification. By @andyleiserson in #7284termcolor and stderr are now optional behind features of the same names. By @bushrat011899 in #7482Queue::submit() to Vulkan's vk::Semaphore allocated outside of wgpu. By @sotaroikeda in #6813.let declarations, and accept vecN() as a constructor for vectors (in any context). By @andyleiserson in #7367.&& and || operators are no longer allowed on vectors. By @andyleiserson in #7368.MathFunction builtins. By @jimblandy in #6833.max_color_attachments limit from 8 to 4 for better GLES compatibility. By @adrian17 in #6994.Device::last_acceleration_structure_build_command_index into queue submit. By @Vecvec in #7462.gles. By @richerfu in #7085unicode-xid with unicode-ident. By @CrazyboyQCD in #7135Improved 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.
pre_present_notify() before presenting. By @kjarosh in #7074.…interface in wgpu{,-core}. This will require breaking changes in naga to fix, and is being tracked by .
wgpu-core and webgpuThe 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.
wgpu are now CloneAll 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.
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.
binding_array) Grew More CapabilitiesPARTIALLY_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 Optionscreate_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 referencePreviously 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.
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
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
diagnostic(…); directive is now supported in WGSLnaga 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:
@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!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.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.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.
naga CLI would incorrectly skip the first positional argument when --stdin-file-path was specified. By @ErichDonGubler in #6480.quantizeToF16() for WGSL frontend, and WGSL, SPIR-V, HLSL, MSL, and GLSL backends. By @jamienicol in #6519.usampler* and isampler*. By @DavidPeicho in #6513.{U,S}{int,norm}{8,16}, Float16 and Unorm8x4Bgra). By @nolanderc in #6632workgroup_size. By @KentSlaney in #6635.pointer_composite_access WGSL language extension is implemented. By @sagudev in #6913map_async and on_submitted_work_done to track down completion of async callbacks. By @eliemichel in #6360..dll files. By @DouglasDwyer in #6574.DeviceType and AdapterInfo now impl Hash by @cwfitzgerald in #6868wgsl_language_features for obtaining available WGSL language feature by @sagudev in #6814no_std support to wgpu-types. By @bushrat011899 in #6892.VK_EXT_shader_atomic_float. By @AsherJingkongChen in #6234.raw_handle method to access raw Metal textures in #6894.override initializers. By @sagudev in 6920Surface::as_hal take an immutable reference to the surface. By @jerzywilczek in #9999CreateBindGroupError::InvalidTextureSampleType error message. By @ErichDonGubler in #6530.Surface::configure and Surface::get_current_texture are no longer fatal. By @alokedesai in #6253BlasTriangleGeometry::index_buffer_offset to BlasTriangleGeometry::first_index. By @Vecvec in #6873dxcompiler.dll & dxil.dll are also now required. By @teoxoy in #6643.usage: Range<T>, for BufferUses, TextureUses, and AccelerationStructureBarrier with a new StateTransition<T>. By @atlv24 in #6703DropCallback API to use FnOnce instead of FnMut. By @jerzywilczek in #6482Device, rather than panicking. By @ErichDonGubler in #6505.Features::TIMESTAMP_QUERY is set when using timestamp writes in render and compute passes. By @ErichDonGubler in #6497.QUERY_SET_MAX_QUERIES (and enforced limits) from 8192 to 4096 to match WebGPU spec. By @ErichDonGubler in #6525.PreHashedMap with FastHashMap. By @jamienicol in #6541.TIMESTAMP_QUERY feature before other validation.Device on some environments. By @Dinnerbone in #6681.get_acceleration_structure_build_sizes. By @Vecvec in #6802.wgpu-info not showing dx12 adapters. By @wumpf in #6844.transform_buffer_offset when initialising transform_buffer. By @Vecvec in #6864.vecN constructors have less than N arguments. By @ErichDonGubler in #6508.>= in a<b>=c. By @KentSlaney in #6898.Statement::ImageStore. By @jimblandy in #6729.max_color_attachment_bytes_per_sample is now correctly set to 128. By @cwfitzgerald in #6866max_color_attachment_bytes_per_sample is now correctly set to 128. By @cwfitzgerald in #6866Nothing published for this version
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 s…
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!
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.
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 backendsDynamic 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() getterswgpu-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 OptionalOne 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() { /* … */ }
windows crate ecosystem, instead of the d3d12 cratewgpu 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.
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.first and either sampling types for @interpolate(flat, …) in WGSL. By @ErichDonGubler in #6181.const declarations in WGSL. By @sagudev in #6156.const_assert in WGSL. By @sagudev in #6198.inverse in WGSL. By @chyyran in #6385.requires, enable, and diagnostic directives. No extensions or diagnostic filters are yet supported, but diagnostics have improved dramatically. By @ErichDonGubler in #6352, #6424, #6437.VideoFrame to ExternalImageSource enum. By @jprochazk in #6170.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_GOOGLE_DISPLAY_TIMING feature. By @DJMcNab in #6149.atomicCompareExchangeWeak. By @AsherJingkongChen in #6265.CAMetalLayer is provided, surfaces now render to a sublayer. This improves resizing behavior, fixing glitches during on window resize. By @madsmtm in #6107.vec3 (not vecN) for the cross built-in. By @ErichDonGubler in #6171.SourceLanguage when enabling debug info in SPV-out. By @kvark in #6256.vars without explicit type. By @sagudev in #6199.gl_DrawID to glsl and DrawIndex to spv. By @ChosenName in #6325.textureQueryLevels to the GLSL parser. By @magcius in #6325.d3d12/naga/wgpu-core/wgpu-hal/wgpu-types' to 1.76. By @wumpf in #6003.UnsupportedUsage error. By @VladasZ in #6007.wgpu_hal bounds-checking promises, and adapt wgpu_core's lazy initialization logic to the slightly weaker-than-expected guarantees. By @jimblandy in #6201.{Render,Compute}Pipeline::get_bind_group_layout on native / WebGL. By @bgr360 in #6280.wgpu_core::render::bundle::bundle_ffi, to allow multiple versions of wgpu to compile together. By @ErichDonGubler in #6272.flush_mapped_ranges when unmapping write-mapped buffers. By @teoxoy in #6089.MAP_WRITE usage. By @teoxoy in #6178.TextureFormat and StorageFormat. By @caelunshun in #6185slice::from_raw_parts with unaligned pointers in push constant handling. By @Imberflur in #6341.Queue::submit is called many times per frame. By @dinnerbone in #6427.TypeError exception in Instance::request_adapter when browser doesn't support WebGPU but wgpu not compiled with webgl support. By @bgr360 in #6197..index_type(vk::IndexType::NONE_KHR) when creating AccelerationStructureGeometryTrianglesDataKHR in the raytraced triangle example to prevent a validation error. By @Vecvec in #6282.wgpu_hal::gles::Adapter::new_external now requires the context to be current when dropping the adapter and related objects. By @Imberflur in #6114.Rg11b10Float to Rg11b10Ufloat. By @sagudev in #6108.impl From<StorageFormat> for ScalarKind with impl From<StorageFormat> for Scalar so that byte width is included. By @atlv24 in #6451.ManuallyDrop in remaining places. By @teoxoy in #6092.Registry. By @teoxoy in #6243.backend from ID. By @teoxoy in #6263.DropGuard based API on Vulkan and GLES to a consistent, callback-based one. By @jerzywilczek in #6164.wgpu-types documentation. Fixed Storage texel types in examples. By @Nelarius in #6271.wgpu::include_wgsl!(…) more in examples and tests. By @ErichDonGubler in #6326.winapi code in WGL wrapper to use the windows crate. By @MarijnS95 in #6006.glutin to 0.31 with glutin-winit crate. By @MarijnS95 in #6150 and #6176.Adapter::new_external() for WGL (just like EGL) to import an external OpenGL ES context. By @MarijnS95 in #6152.winapi code to use the windows crate. By @MarijnS95 in #5956 and #6173.num_workgroups builtin working for indirect dispatches. By @teoxoy in #5730.parking_lot to 0.12. By @mahkoh in #6287.This release includes wgpu, wgpu-core and naga. All other crates remain at 22.0.0.
This release includes wgpu, wgpu-core and naga. All other crates remain at 22.0.0.
tracy. By @waywardmonkeys in #5988queue_write_texture. By @teoxoy in #6009compute_pass. By @matthew-wong1 #6041wgpu-core is undocumented unless --cfg wgpu_core_doc feature is enabled. By @kpreid in #5987We are often concerned with tracking breaking changes, and affecting these consumers' ability to ship. By releasing our first major version, we public…
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.
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!
wgpu::RenderPass & wgpu::ComputePasswgpu::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.
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
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
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
as_hal for Buffer to access wgpu created buffers form wgpu-hal. By @JasondeWolff in #5724include_wgsl! is now callable in const contexts by @9SMTM6 in #5872DeviceDescriptor 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.HTMLImageElement and ImageData as external source for copying images. By @Valaphee in #5668Added -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
PipelineCache resource to allow using Vulkan pipeline caches. By @DJMcNab in #5319StageError::InputNotConsumed, Features::SHADER_UNUSED_VERTEX_OUTPUT, and associated validation. By @Imberflur in #5531wgpu::Error is now Sync, making it possible to be wrapped in anyhow::Error or eyre::Report. By @nolanderc in #5820.submit() by 39-64% (.submit() + .poll() by 22-32%). By @teoxoy in #5910trace wgpu feature has been temporarily removed. By @teoxoy in #5975Removed 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
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 #5671queue_write_texture (causing UB). By @teoxoy in #5973ClearColorF, ClearColorU and ClearColorI commands being issued before SetDrawColorBuffers #5666glClear with glClearBufferF because glDrawBuffers requires that the ith buffer must be COLOR_ATTACHMENTi or NONE #5666Breaking change: `wgpu_core::ProgrammableStageDescriptor is now optional. By @ErichDonGubler in #5305.
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
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
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
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 Vulkanwgpu::Features::SUBGROUP_BARRIER, for support of the subgroupBarrier operation, supported on Vulkan & MetalNote that there currently some differences between wgpu's native-only implementation and the open WebGPU proposal.
By @exrook and @lichtso in #5301
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
Unorm10_10_10_2 VertexFormat by @McMackety in #5477wgpu-types's trace and replay features have been replaced by the serde feature. By @KirmesBude in #5149wgpu-core's serial-pass feature has been removed. Use serde instead. By @KirmesBude in #5149InstanceFlags::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.
InstanceFlags::VALIDATION.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.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()
wgpu_core::pipeline::ProgrammableStageDescriptor is now optional. By @ErichDonGubler in #5305.Features::downlevel{_webgl2,}_features was made const by @MultisampledNight in #5343wgpu_core::pipeline::ShaderError has been moved to naga. By @stefnotch in #5410wgpu::CommandEncoder::as_hal_mutwgpu::TextureView::as_halwgpu::Texture::as_hal now returns a user-defined type to match the other as_hal functions--metal-version with naga CLI. By @pcleavelin in #5392arrayLength for runtime-sized arrays inside binding arrays (for WGSL input and SPIR-V output). By @kvark in #5428--shader-stage and --input-kind options to naga-cli for specifying vertex/fragment/compute shaders, and frontend. by @ratmice in #5411create_validator function to wgpu_core Device to create naga Validators. By @atlv24 #5606device_set_device_lost_callback method for ContextWebGpu. By @suti in #5438ReadOnly and ReadWrite. By @JolifantoBambla in #5434get_texture_format_features cheap. By @Dinnerbone in #5346DEPTH32FLOAT_STENCIL8 as supported in GLES. By @Dinnerbone in #5370TEXTURE_COMPRESSION_ETC2. By @Valaphee in #5568driver and driver_info, with the OpenGL flavor and version, similar to Vulkan. By @valaphee in #5482wgpu_hal documentation. By @jimblandy in #5516, #5524, #5562, #5563, #5566, #5617, #5618PrimitiveState::strip_index_format. By @cpsdqs in #5350SourceLocation. By @stefnotch in #5386 and #5410push_constant syntax. By @waywardmonkeys in #5393Limits::max_compute_workgroup_storage_size default value. By @atlv24 in #5601serde feature not compiling for wgpu-types. By @KirmesBude in #5149storage and uniform vars. By @jimblandy #5222extern "C" + [no_mangle]) from RenderPass & ComputePass recording. By @wumpf in #5409.Expression::ZeroValue. By @Imberflur in #5587.extractBits and insertBits when offset + count overflows the bit width. By @cwfitzgerald in #5305clamp when min argument > max argument. By @cwfitzgerald in #5300.TypeInner::scalar_width to be consistent with the rest of the codebase and return values in bytes not bits. By @atlv24 in #5532.first_instance getting ignored in draw indexed when ARB_shader_draw_parameters feature is present and base_vertex is 0. By @valaphee in #5482wgpu_hal::vulkan::CommandEncoder to make sure discard_encoding is not called in the closed state. By @villuna in #5557LocalType caching. By @atlv24 in #5590ash to 0.38. By @MarijnS95 in #5504.multithreaded_compute test. By @jimblandy in #5129.This release includes wgpu, wgpu-core, wgpu-hal, wgpu-types, and naga. All other crates are unchanged.
This release includes wgpu, wgpu-core, wgpu-hal, wgpu-types, and naga. All other crates are unchanged.
wgpu::Id now implements PartialOrd/Ord allowing it to be put in BTreeMaps. By @cwfitzgerald and @9291Sam in #5176wgsl-outwgpu::Instance::create_surface documentation. By @HexoKnight in #5280.wgpu::CommandEncoder::clear_buffer documentation. By @PWhiddy in #5281.Surface configuration incorrectly claimed that wgpu::Instance::create_surface was unsafe. By @hackaugusto in #5265.clone during GLSL shader ingestion. By @a1phyr in #5118.Device::clear_buffer where offset + size > buffer.size was not checked when size was omitted. By @ErichDonGubler in #5282.panic! when dropping Instance without InstanceFlags::VALIDATION. By @hakolao in #5134Etc2Rgba8Unorm format. By @andristarr in #5178libX11.so.6 in addition to libX11.so on linux. #5307GL_EXT_texture_shadow_lod to support sampling a cube depth texture with an explicit LOD. By @cmrschwarz in #5171.glsl-inTextureFormat::block_size is deprecated, use TextureFormat::block_copy_size instead: By @wumpf in #4647.
This release includes:
wgpuwgpu-corewgpu-halwgpu-typeswgpu-infonaga (skipped from 0.14 to 0.19)naga-cli (skipped from 0.14 to 0.19)d3d12 (skipped from 0.7 to 0.19)Large refactoring of wgpu’s internals aiming at reducing lock contention, and providing better performance when using wgpu on multiple threads.
By @gents83 in #3626 and thanks also to @jimblandy, @nical, @Wumpf, @Elabajaba & @cwfitzgerald
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:
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 FeatureThe 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 unconditionallyThis 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 Featureswgpu 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.
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 VariableThis 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 DataPreviously, 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.
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
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 ExactSizeIteratorThis 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 boolThis 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
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.FLOAT32_FILTERABLE feature (web and native, corresponds to WebGPU's float32-filterable). By @almarklein in #4759.TextureFormat::block_size is deprecated, use TextureFormat::block_copy_size instead: By @wumpf in #4647.DispatchIndirect, DrawIndexedIndirect, and DrawIndirect types in the wgpu::util module to DispatchIndirectArgs, DrawIndexedIndirectArgs, and DrawIndirectArgs. By @cwfitzgerald in #4723.encoder.clear_buffer an Option<u64> instead of Option<NonZero<u64>>. By @nical in #4737.info log level noise. By @nical in #4769, #4711 and #4772features & 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@builtin(instance_index) now properly reflects the range provided in the draw call instead of always counting from 0. By @cwfitzgerald in #4722.POLYGON_MODE_LINE and POLYGON_MODE_POINT. By @valaphee in #4836.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.--bulk-validate option to naga CLI. By @jimblandy in #4871.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.span and validate features. Always fully validate shader modules, and always track source positions for use in error messages. By @teoxoy in #4706.Scalar struct type for use in naga's IR, and update all frontend, middle, and backend code appropriately. By @jimblandy in #4673.naga::Literal variant, I64, for signed 64-bit literals. #4711.struct member padding always. By @ErichDonGubler in #4701.i suffix on i32 literals. By @jimblandy in #4863.f suffix on f32 literals. By @jimblandy in #4869.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.wgpu_types::CompositeAlphaMode serde serialization to spec. By @littledivy in #4940.ConfigureSurfaceError::TooLarge. By @Dinnerbone in #4960.DeviceLostCallbackC params. By @bradwerth in #5032.Queue::write_texture on DX12. By @DTZxPorter in #4990.VK_EXT_robustness2 only when not using an outdated intel iGPU driver. By @TheoDulka in #4602.BufferSlice::get_mapped_range multiple times on the same buffer slice (instead of throwing a Javascript exception). By @DouglasDwyer in #4726.wgpu::Instance instead of sharing a global one. By @Zoxc in #4603dot, 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.alias declarations in naga IR Types. By @jimblandy in #4733.COPY_SRC usage flag in surface configuration. By @Toqozz in #4852.Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
(Backport) Output @interpolate(flat) attribute for integer locations. (#2318) @expenses
@interpolate(flat) attribute for integer locations. (#2318) @expenses(Backport) Support array bindings of buffers. (#2282) @kvark
(Backport) Convert conditional backedges to break if. (#2290) @eddyb
break if. (#2290) @eddybNothing published for this version
(Backport) Convert conditional backedges to break if. (#2290) @eddyb
break if. (#2290) @eddybNothing published for this version
Backport #2389 (Use IndexSet instead of HashSet for iterated sets (capabilities/extensions)) by @eddyb, @jimblandy in https://github.com/gfx-rs/naga/p
SPV-OUT
IndexSet instead of HashSet for iterated sets (capabilities/extensions)) by @eddyb, @jimblandy in https://github.com/gfx-rs/naga/pull/2391SPV-IN
break if) by @eddyb in https://github.com/gfx-rs/naga/pull/2387Nothing published for this version
Nothing published for this version
Make VS-output positions invariant on even more systems (#1697) @cwfitzgerald
Make VS-output positions invariant if possible (#1687) @kvark
Don't pin indexmap version (#1666) @a1phyr
Check structure resource types (#1639) @kvark
Make WithSpan cloneable (#1620) @jakobhellermann
Nothing published for this version
reflect textures without samplers
view_index builtincheck stores for proper pointer class
mat3implement casts from and to booleans in the backends
Nothing published for this version
Reduced heap allocations when generating WGSL, HLSL, and GLSL
let type inferenceselect() orderOpNamerequested capabilities for 1D and cube images, storage formats
break and continue in a switch statementOpTypeImage typesswitch casestracking sampling across function parameters
Nothing published for this version
Nothing published for this version
fix auto-deriving the capabilities
numerous additions and improvements to SPIR-V frontend:
OpArrayLength, OpCopyMemory, OpInBoundsAccessChain, OpLogicalXxxEqualfwidth in WGSLNothing published for this version
derive block status of structures
fix block decorations on nested structures
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →