Allow chaining extension structs onto VkSwapchainCreateInfoKHR and VkSubmitInfo (#10095)

This commit is contained in:
Stuart Parmenter authored and GitHub committed 2026-08-29 16:19:38 -04:00
1 parent e9a873e5d2
commit b82df96eb3
5 files changed
+145 -25

No files matched your search

+1
View File
@@ -86,6 +86,7 @@ By @sagudev in [#10115](https://github.com/gfx-rs/wgpu/pull/10115).
- Add `BufferBinding::buffer`, a public read accessor for the bound buffer, which was previously inaccessible to out-of-tree `wgpu_hal::Api` implementations. By @danlehmann in [#9820](https://github.com/gfx-rs/wgpu/pull/9820).
- Allow specifying a queue family ownership transfer when transitioning a texture. `hal::TextureBarrier` gained an optional `queue_family_ownership_transfer` field (honored only by the Vulkan backend) so that images imported from external memory can be acquired from and released back to the queue family of an external or foreign owner, described by the new `hal::QueueFamily` enum. Resolves [#2948](https://github.com/gfx-rs/wgpu/issues/2948). By @alexander-bruun in [#9668](https://github.com/gfx-rs/wgpu/pull/9668).
- Add `wgpu_hal::vulkan::Surface::set_next_present_chain`, which attaches a caller-provided `pNext` chain to the `VkPresentInfoKHR` of the surface's next presentation. With `Adapter::open_with_callback` to enable the device extension, this supports presentation extensions wgpu has no dedicated support for, such as [VK_NV_present_metering](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_NV_present_metering.html) for metering the display timing of frame-generation frames. By @stuartparmenter in [#9847](https://github.com/gfx-rs/wgpu/pull/9847).
- Add `wgpu_hal::vulkan::Surface::set_next_swapchain_create_chain` and `wgpu_hal::vulkan::Queue::set_next_submit_chain`. The first attaches a caller-provided `pNext` chain to the `VkSwapchainCreateInfoKHR` of the surface's next configuration. The second attaches one to the `VkSubmitInfo` of the queue's next submission. Together with `set_next_present_chain` and the existing raw-handle accessors, this makes [VK_NV_low_latency2](https://registry.khronos.org/vulkan/specs/latest/man/html/VK_NV_low_latency2.html) usable on a wgpu swapchain. That extension is the Vulkan interface for NVIDIA Reflex. By @stuartparmenter in [#10095](https://github.com/gfx-rs/wgpu/pull/10095).
#### Metal
+1
View File
@@ -2998,6 +2998,7 @@ impl super::Adapter {
relay_semaphores: Mutex::new(relay_semaphores),
signal_semaphores: Mutex::new(SemaphoreList::new(SemaphoreListMode::Signal)),
wait_semaphores: Mutex::new(SemaphoreList::new(SemaphoreListMode::Wait)),
next_submit_chain: Mutex::new(None),
};
let allocation_sizes = AllocationSizes::from_memory_hints(memory_hints).into();
+79
View File
@@ -31,11 +31,13 @@ mod descriptor;
mod device;
mod drm;
mod instance;
mod pnext_chain;
mod sampler;
mod semaphore_list;
mod swapchain;
pub use adapter::PhysicalDeviceFeatures;
pub(crate) use pnext_chain::PnextChain;
use alloc::{boxed::Box, ffi::CString, sync::Arc, vec::Vec};
use core::{
@@ -320,6 +322,43 @@ impl Surface {
.expect("Surface should have a native Vulkan swapchain");
unsafe { swapchain.set_next_present_chain(chain) };
}
/// Set a `pNext` chain of extension structs to attach to the
/// [`vk::SwapchainCreateInfoKHR`] used by the next configuration of this surface.
///
/// This supports swapchain extensions that `wgpu-hal` has no dedicated support
/// for. One example is `VkSwapchainLatencyCreateInfoNV` from [VK_NV_low_latency2].
/// The device extension itself must be enabled at device creation, for example
/// with [`Adapter::open_with_callback()`](super::vulkan::Adapter::open_with_callback).
///
/// The next configuration consumes the chain. A later call replaces a chain that
/// hasn't been consumed yet. If the surface is dropped first, the chain is
/// discarded unread. Every configuration creates a new swapchain, so you must set
/// the chain again before each configuration, including on resize.
///
/// # Safety
///
/// - `chain` must point to a valid `pNext` chain of structs that can extend
/// [`vk::SwapchainCreateInfoKHR`]. The extensions in the chain must be enabled
/// on the device the surface is configured with.
/// - The chain must stay valid until the configuration that consumes it returns
/// or the surface is dropped. Don't read or write the chain during that time.
/// Fields the driver wrote during swapchain creation may be read afterwards.
///
/// # Panics
///
/// - If the surface isn't a native Vulkan surface, such as a DXGI surface.
///
/// [VK_NV_low_latency2]: https://registry.khronos.org/vulkan/specs/latest/man/html/VK_NV_low_latency2.html
#[track_caller]
pub unsafe fn set_next_swapchain_create_chain(&self, chain: *mut c_void) {
let surface = self
.inner
.as_any()
.downcast_ref::<swapchain::NativeSurface>()
.expect("Surface should be a native Vulkan surface");
unsafe { surface.set_next_swapchain_create_chain(chain) };
}
}
#[derive(Debug)]
@@ -709,6 +748,11 @@ pub struct Queue {
relay_semaphores: Mutex<RelaySemaphores>,
signal_semaphores: Mutex<SemaphoreList>,
wait_semaphores: Mutex<SemaphoreList>,
/// A caller-provided `pNext` chain to attach to the [`vk::SubmitInfo`] of the
/// next call to [`submit()`](crate::Queue::submit).
///
/// Set only through [`Queue::set_next_submit_chain()`].
next_submit_chain: Mutex<Option<PnextChain>>,
}
impl fmt::Debug for Queue {
@@ -720,6 +764,7 @@ impl fmt::Debug for Queue {
relay_semaphores: _,
signal_semaphores: _,
wait_semaphores: _,
next_submit_chain: _,
} = self;
f.debug_struct("Queue")
.field("family_index", family_index)
@@ -1545,6 +1590,13 @@ impl crate::Queue for Queue {
&mut vk_timeline_info,
);
let submit_chain = self.next_submit_chain.lock().take();
if let Some(chain) = submit_chain {
// SAFETY: The contract on `Queue::set_next_submit_chain()` keeps the chain
// valid and unaliased until this submission is made.
vk_info.p_next = unsafe { chain.splice_into(vk_info.p_next) };
}
profiling::scope!("vkQueueSubmit");
unsafe {
self.device
@@ -1629,6 +1681,33 @@ impl Queue {
pub fn remove_wait_semaphore(&self, semaphore: vk::Semaphore) -> bool {
self.wait_semaphores.lock().remove(semaphore)
}
/// Set a `pNext` chain of extension structs to attach to the [`vk::SubmitInfo`]
/// of the next [`submit()`](crate::Queue::submit) on this queue.
///
/// This supports submission extensions that `wgpu-hal` has no dedicated support
/// for. One example is `VkLatencySubmissionPresentIdNV` from `VK_NV_low_latency2`.
/// The device extension itself must be enabled at device creation, for example
/// with [`Adapter::open_with_callback()`](super::vulkan::Adapter::open_with_callback).
///
/// The next submission on this queue consumes the chain, and a later call
/// replaces a chain that hasn't been submitted yet. One `wgpu` or `wgpu-core`
/// submit maps to one submission here, but layers above `wgpu-hal` also make
/// housekeeping submissions of their own, for example when a buffer is mapped,
/// and those consume the chain too. Set the chain right before the submission
/// it applies to, with no other queue or buffer-mapping work in between.
///
/// # Safety
///
/// - `chain` must point to a valid `pNext` chain of structs that can extend
/// [`vk::SubmitInfo`]. The extensions in the chain must be enabled on this
/// queue's device.
/// - The chain must stay valid until the next submission on this queue is made
/// or the queue is dropped. Don't read or write the chain during that time.
/// Fields the driver wrote during submission may be read afterwards.
pub unsafe fn set_next_submit_chain(&self, chain: *mut c_void) {
*self.next_submit_chain.lock() = Some(PnextChain::new(chain));
}
}
/// Maps
+37
View File
@@ -0,0 +1,37 @@
use core::ffi::c_void;
use ash::vk;
/// A caller-provided `pNext` chain, stashed by one of the `set_next_*_chain`
/// setters until the Vulkan call that consumes it.
pub(crate) struct PnextChain(*mut vk::BaseOutStructure<'static>);
// SAFETY: The pointer is only dereferenced at the Vulkan call that consumes the
// chain. Each setter's contract keeps the chain valid and unaliased until then.
unsafe impl Send for PnextChain {}
unsafe impl Sync for PnextChain {}
impl PnextChain {
/// Wraps the raw chain pointer that a `set_next_*_chain` setter received.
pub(crate) fn new(chain: *mut c_void) -> Self {
Self(chain.cast())
}
/// Splices this chain in front of `existing`, the current `p_next` of a
/// Vulkan info struct, and returns the new chain head.
///
/// # Safety
///
/// The chain must still be valid, and the info struct must be passed to the
/// Vulkan call that consumes the chain.
pub(crate) unsafe fn splice_into(self, existing: *const c_void) -> *const c_void {
unsafe {
let mut tail = self.0;
while !(*tail).p_next.is_null() {
tail = (*tail).p_next;
}
(*tail).p_next = existing.cast_mut().cast();
}
self.0.cast()
}
}
+27 -25
View File
@@ -12,7 +12,7 @@ use crate::vulkan::{
swapchain::{
Surface, SurfaceTextureMetadata, Swapchain, SwapchainSubmissionSemaphoreGuard, WindowHandle,
},
DeviceShared, InstanceShared,
DeviceShared, InstanceShared, PnextChain,
};
pub(crate) struct NativeSurface {
@@ -23,6 +23,12 @@ pub(crate) struct NativeSurface {
/// query; `None` for non-Win32 surfaces.
#[cfg(windows)]
hdr_source: Option<crate::auxil::dxgi::hdr::DxgiHdrSource>,
/// A caller-provided `pNext` chain to attach to the [`vk::SwapchainCreateInfoKHR`]
/// of the next swapchain created for this surface.
///
/// Set only through
/// [`Surface::set_next_swapchain_create_chain()`](crate::vulkan::Surface::set_next_swapchain_create_chain).
next_swapchain_create_chain: Mutex<Option<PnextChain>>,
}
impl NativeSurface {
@@ -40,12 +46,20 @@ impl NativeSurface {
instance: Arc::clone(&instance.shared),
#[cfg(windows)]
hdr_source: hwnd.map(|wh| crate::auxil::dxgi::hdr::DxgiHdrSource::new(wh.0)),
next_swapchain_create_chain: Mutex::new(None),
}
}
pub fn as_raw(&self) -> vk::SurfaceKHR {
self.raw
}
/// # Safety
///
/// See [`Surface::set_next_swapchain_create_chain()`](crate::vulkan::Surface::set_next_swapchain_create_chain).
pub unsafe fn set_next_swapchain_create_chain(&self, chain: *mut core::ffi::c_void) {
*self.next_swapchain_create_chain.lock() = Some(PnextChain::new(chain));
}
}
impl Drop for NativeSurface {
@@ -233,6 +247,13 @@ impl Surface for NativeSurface {
info = info.push_next(&mut format_list_info);
}
let create_chain = self.next_swapchain_create_chain.lock().take();
if let Some(chain) = create_chain {
// SAFETY: The contract on `Surface::set_next_swapchain_create_chain()` keeps
// the chain valid and unaliased until this swapchain creation returns.
info.p_next = unsafe { chain.splice_into(info.p_next) };
}
let result = {
profiling::scope!("vkCreateSwapchainKHR");
unsafe { functor.create_swapchain(&info, None) }
@@ -370,22 +391,11 @@ pub(crate) struct NativeSwapchain {
/// A caller-provided `pNext` chain to attach to the [`vk::PresentInfoKHR`] of the next
/// call to [`present()`](crate::Queue::present()).
///
/// # Safety
///
/// Set only through
/// [`Surface::set_next_present_chain()`](crate::vulkan::Surface::set_next_present_chain),
/// whose contract keeps the chain valid and unaliased until the next present.
next_present_chain: Option<PresentChain>,
/// [`Surface::set_next_present_chain()`](crate::vulkan::Surface::set_next_present_chain).
next_present_chain: Option<PnextChain>,
}
/// See [`NativeSwapchain::next_present_chain`].
struct PresentChain(*mut vk::BaseOutStructure<'static>);
// SAFETY: The pointer is only dereferenced during the next present, and the contract on
// `Surface::set_next_present_chain()` keeps the chain valid and unaliased until then.
unsafe impl Send for PresentChain {}
unsafe impl Sync for PresentChain {}
impl Drop for NativeSwapchain {
fn drop(&mut self) {
unsafe {
@@ -629,18 +639,10 @@ impl Swapchain for NativeSwapchain {
vk_info
};
if let Some(PresentChain(chain)) = self.next_present_chain.take() {
// Splice the caller's chain in front of anything already chained onto `vk_info`.
if let Some(chain) = self.next_present_chain.take() {
// SAFETY: The contract on `Surface::set_next_present_chain()` keeps the chain
// valid and unaliased until this present completes.
unsafe {
let mut tail = chain;
while !(*tail).p_next.is_null() {
tail = (*tail).p_next;
}
(*tail).p_next = vk_info.p_next.cast_mut().cast();
vk_info.p_next = chain.cast();
}
vk_info.p_next = unsafe { chain.splice_into(vk_info.p_next) };
}
let suboptimal = {
@@ -700,7 +702,7 @@ impl NativeSwapchain {
///
/// See [`Surface::set_next_present_chain()`](crate::vulkan::Surface::set_next_present_chain).
pub unsafe fn set_next_present_chain(&mut self, chain: *mut core::ffi::c_void) {
self.next_present_chain = Some(PresentChain(chain.cast()));
self.next_present_chain = Some(PnextChain::new(chain));
}
/// Mark the current frame finished, advancing to the next acquire semaphore.