registry/vulkan/chapters/VK_KHR_present_wait/present_wait.txt

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

[[present-wait]]
== Present Wait

Applications wanting to control the pacing of the application by monitoring
when presentation processes have completed to limit the number of
outstanding images queued for presentation, need to have a method of being
signaled during the presentation process.

ifdef::VK_GOOGLE_display_timing,VK_KHR_present_timing[]
Using
ifdef::VK_KHR_present_timing[]
the `VK_KHR_present_timing` extension
ifdef::VK_GOOGLE_display_timing[or]
endif::VK_KHR_present_timing[]
ifdef::VK_GOOGLE_display_timing[]
the `VK_GOOGLE_display_timing` extension
endif::VK_GOOGLE_display_timing[]
applications can discover when images were presented, but only
asynchronously.
endif::VK_GOOGLE_display_timing,VK_KHR_present_timing[]

Providing a mechanism which allows applications to block, waiting for a
specific step of the presentation process to complete allows them to control
the amount of outstanding work (and hence the potential lag in responding to
user input or changes in the rendering environment).

The `apiext:VK_KHR_present_wait` extension allows applications to tell the
presentation engine at the flink:vkQueuePresentKHR call that it plans on
waiting for presentation by passing a slink:VkPresentIdKHR structure.
The pname:presentId passed in that structure may then be passed to a future
flink:vkWaitForPresentKHR call to cause the application to block until that
presentation is finished.