wgpu Files

Major Changes

Deferred command buffer actions: map_buffer_on_submit and on_submitted_work_done

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

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

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

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

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

Available on CommandEncoder, CommandBuffer, RenderPass, and ComputePass.

By @cwfitzgerald in #8125.

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

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

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

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

By @n1ght-hunter in #7550.

EXPERIMENTAL_RAY_TRACING_ACCELERATION_STRUCTURE has been merged into EXPERIMENTAL_RAY_QUERY

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

:::diff
- Features::EXPERIMENTAL_RAY_TRACING_ACCELERATION_STRUCTURE
+ Features::EXPERIMENTAL_RAY_QUERY

By @Vecvec in #7913.

New EXPERIMENTAL_PRECOMPILED_SHADERS API

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

Difference for SPIR-V passthrough:

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

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

Buffer mapping apis no longer have lifetimes

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

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

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

EXPERIMENTAL_* features now require unsafe code to enable

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

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

By @cwfitzgerald in #8163.

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

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

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

By @cwfitzgerald in #8162.

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

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

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

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

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

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

By @wumpf in #8282, #8285

New Features

General

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

naga

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

Changes

General

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

naga

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

DX12

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

Bug Fixes

General

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

DX12

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

EGL

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

Vulkan

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

naga

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

Documentation

General

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