1// Copyright 2019-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[open,refpage='vkWaitForPresentKHR',desc='Wait for presentation',type='protos'] 6-- 7When the <<features-presentWait, pname:presentWait>> feature is enabled, an 8application can: wait for an image to be presented to the user by first 9specifying a presentId for the target presentation by adding a 10sname:VkPresentIdKHR structure to the pname:pNext chain of the 11slink:VkPresentInfoKHR structure and then waiting for that presentation to 12complete by calling: 13 14include::{generated}/api/protos/vkWaitForPresentKHR.adoc[] 15 16 * pname:device is the device associated with pname:swapchain. 17 * pname:swapchain is the non-retired swapchain on which an image was 18 queued for presentation. 19 * pname:presentId is the presentation presentId to wait for. 20 * pname:timeout is the timeout period in units of nanoseconds. 21 pname:timeout is adjusted to the closest value allowed by the 22 implementation-dependent timeout accuracy, which may: be substantially 23 longer than one nanosecond, and may: be longer than the requested 24 period. 25 26fname:vkWaitForPresentKHR waits for the presentId associated with 27pname:swapchain to be increased in value so that it is at least equal to 28pname:presentId. 29 30For ename:VK_PRESENT_MODE_MAILBOX_KHR (or other present mode where images 31may be replaced in the presentation queue) any wait of this type associated 32with such an image must: be signaled no later than a wait associated with 33the replacing image would be signaled. 34 35When the presentation has completed, the presentId associated with the 36related pname:pSwapchains entry will be increased in value so that it is at 37least equal to the value provided in the sname:VkPresentIdKHR structure. 38 39There is no requirement for any precise timing relationship between the 40presentation of the image to the user and the update of the presentId value, 41but implementations should: make this as close as possible to the 42presentation of the first pixel in the next image being presented to the 43user. 44 45The call to fname:vkWaitForPresentKHR will block until either the presentId 46associated with pname:swapchain is greater than or equal to pname:presentId, 47or pname:timeout nanoseconds passes. 48When the swapchain becomes OUT_OF_DATE, the call will either return 49ename:VK_SUCCESS (if the image was delivered to the presentation engine and 50may have been presented to the user) or will return early with status 51ename:VK_ERROR_OUT_OF_DATE_KHR (if the image was not presented to the user). 52 53As an exception to the normal rules for objects which are externally 54synchronized, the pname:swapchain passed to fname:vkWaitForPresentKHR may: 55be simultaneously used by other threads in calls to functions other than 56flink:vkDestroySwapchainKHR. 57Access to the swapchain data associated with this extension must: be atomic 58within the implementation. 59 60.Valid Usage 61**** 62 * [[VUID-vkWaitForPresentKHR-swapchain-04997]] 63 pname:swapchain must: not be in the retired state 64 * [[VUID-vkWaitForPresentKHR-presentWait-06234]] 65 The <<features-presentWait, pname:presentWait>> feature must: be enabled 66**** 67 68include::{generated}/validity/protos/vkWaitForPresentKHR.adoc[] 69-- 70