Struct wgpu_hal::vulkan::SwapchainImageSemaphores

struct SwapchainImageSemaphores {
    acquire: Semaphore,
    should_wait_for_acquire: bool,
    present: Vec<Semaphore>,
    present_index: usize,
    previously_used_submission_index: FenceValue,
}

The semaphores needed to use one image in a swapchain.

Fields

acquire: Semaphore

A semaphore that is signaled when this image is safe for us to modify.

When vkAcquireNextImageKHR returns the index of the next swapchain image that we should use, that image may actually still be in use by the presentation engine, and is not yet safe to modify. However, that function does accept a semaphore that it will signal when the image is indeed safe to begin messing with.

This semaphore is:

• waited for by the first queue submission to operate on this image since it was acquired, and

• signaled by vkAcquireNextImageKHR when the acquired image is ready for us to use.

should_wait_for_acquire: bool

True if the next command submission operating on this image should wait for acquire.

We must wait for acquire before drawing to this swapchain image, but because wgpu-hal queue submissions are always strongly ordered, only the first submission that works with a swapchain image actually needs to wait. We set this flag when this image is acquired, and clear it the first time it’s passed to Queue::submit as a surface texture.

present: Vec<Semaphore>

A pool of semaphores for ordering presentation after drawing.

The first present_index semaphores in this vector are:

• all waited on by the call to vkQueuePresentKHR that presents this image, and

• each signaled by some vkQueueSubmit queue submission that draws to this image, when the submission finishes execution.

This vector accumulates one semaphore per submission that writes to this image. This is awkward, but hard to avoid: vkQueuePresentKHR requires a semaphore to order it with respect to drawing commands, and we can’t attach new completion semaphores to a command submission after it’s been submitted. This means that, at submission time, we must create the semaphore we might need if the caller’s next action is to enqueue a presentation of this image.

An alternative strategy would be for presentation to enqueue an empty submit, ordered relative to other submits in the usual way, and signaling a single presentation semaphore. But we suspect that submits are usually expensive enough, and semaphores usually cheap enough, that performance-sensitive users will avoid making many submits, so that the cost of accumulated semaphores will usually be less than the cost of an additional submit.

Only the first present_index semaphores in the vector are actually going to be signalled by submitted commands, and need to be waited for by the next present call. Any semaphores beyond that index were created for prior presents and are simply being retained for recycling.

present_index: usize

The number of semaphores in present to be signalled for this submission.

previously_used_submission_index: FenceValue

The fence value of the last command submission that wrote to this image.

The next time we try to acquire this image, we’ll block until this submission finishes, proving that acquire is ready to pass to vkAcquireNextImageKHR again.

Implementations

impl SwapchainImageSemaphores

fn new(device: &DeviceShared) -> Result<Self, DeviceError>

fn set_used_fence_value(&mut self, value: FenceValue)

fn get_acquire_wait_semaphore(&mut self) -> Option<Semaphore>

Return the semaphore that commands drawing to this image should wait for, if any.

This only returns Some once per acquisition; see SwapchainImageSemaphores::should_wait_for_acquire for details.

fn get_submit_signal_semaphore( &mut self, device: &DeviceShared, ) -> Result<Semaphore, DeviceError>

Return a semaphore that a submission that writes to this image should signal when it’s done.

See SwapchainImageSemaphores::present for details.

fn get_present_wait_semaphores(&mut self) -> &[Semaphore]

Return the semaphores that a presentation of this image should wait on.

Return a slice of semaphores that the call to vkQueueSubmit that ends this image’s acquisition should wait for. See SwapchainImageSemaphores::present for details.

Reset self to be ready for the next acquisition cycle.

unsafe fn destroy(&self, device: &Device)

Trait Implementations

impl Debug for SwapchainImageSemaphores

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.