C Specification
When the presentWait feature is enabled, an
application can wait for an image to be presented to the user by first
specifying a presentId for the target presentation by adding a
VkPresentIdKHR structure to the pNext chain of the
VkPresentInfoKHR structure and then waiting for that presentation to
complete by calling:
// Provided by VK_KHR_present_wait
VkResult vkWaitForPresentKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint64_t presentId,
uint64_t timeout);
Parameters
-
deviceis the device associated withswapchain. -
swapchainis the non-retired swapchain on which an image was queued for presentation. -
presentIdis the presentation presentId to wait for. -
timeoutis the timeout period in units of nanoseconds.timeoutis adjusted to the closest value allowed by the implementation-dependent timeout accuracy, which may be substantially longer than one nanosecond, and may be longer than the requested period.
Description
vkWaitForPresentKHR waits for the presentId associated with
swapchain to be increased in value so that it is at least equal to
presentId.
For VK_PRESENT_MODE_MAILBOX_KHR (or other present mode where images
may be replaced in the presentation queue) any wait of this type associated
with such an image must be signaled no later than a wait associated with
the replacing image would be signaled.
When the presentation has completed, the presentId associated with the
related pSwapchains entry will be increased in value so that it is at
least equal to the value provided in the VkPresentIdKHR structure.
There is no requirement for any precise timing relationship between the presentation of the image to the user and the update of the presentId value, but implementations should make this as close as possible to the presentation of the first pixel in the next image being presented to the user.
The call to vkWaitForPresentKHR will block until either the presentId
associated with swapchain is greater than or equal to presentId,
or timeout nanoseconds passes.
When the swapchain becomes OUT_OF_DATE, the call will either return
VK_SUCCESS (if the image was delivered to the presentation engine and
may have been presented to the user) or will return early with status
VK_ERROR_OUT_OF_DATE_KHR (if the image was not presented to the user).
As an exception to the normal rules for objects which are externally
synchronized, the swapchain passed to vkWaitForPresentKHR may
be simultaneously used by other threads in calls to functions other than
vkDestroySwapchainKHR.
Access to the swapchain data associated with this extension must be atomic
within the implementation.
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.