registry/vulkan/chapters/VK_KHR_present_wait/WaitForPresent.txt

// Copyright 2019-2021 The Khronos Group, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[open,refpage='vkWaitForPresentKHR',desc='Wait for presentation',type='protos']
--
When the <<features-presentWait, pname: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
sname:VkPresentIdKHR structure to the pname:pNext chain of the
slink:VkPresentInfoKHR structure and then waiting for that presentation to
complete by calling:

include::{generated}/api/protos/vkWaitForPresentKHR.txt[]

  * pname:device is the device associated with pname:swapchain.
  * pname:swapchain is the non-retired swapchain on which an image was
    queued for presentation.
  * pname:presentId is the presentation presentId to wait for.
  * pname:timeout is the timeout period in units of nanoseconds.
    pname:timeout is 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.

fname:vkWaitForPresentKHR waits for the presentId associated with
pname:swapchain to be increased in value so that it is at least equal to
pname:presentId.

For ename: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 pname:pSwapchains entry will be increased in value so that it is at
least equal to the value provided in the sname: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 new image to the user.

The call to fname:vkWaitForPresentKHR will block until either the presentId
associated with pname:swapchain is greater than or equal to pname:presentId,
or pname:timeout nanoseconds passes.
When the swapchain becomes OUT_OF_DATE, the call will either return
ename: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
ename: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 pname:swapchain passed to fname:vkWaitForPresentKHR may:
be simultaneously used by other threads in calls to functions other than
flink:vkDestroySwapchainKHR.
Access to the swapchain data associated with this extension must: be atomic
within the implementation.

.Valid Usage
****
  * [[VUID-vkWaitForPresentKHR-swapchain-04997]]
    pname:swapchain must: not be in the retired state
  * [[VUID-vkWaitForPresentKHR-presentWait-06234]]
    The <<features-presentWait, pname:presentWait>> feature must: be enabled
****

include::{generated}/validity/protos/vkWaitForPresentKHR.txt[]
--