Vulkan.Extensions.VK_KHR_present_wait

vkWaitForPresentKHR - Wait for presentation

Description

The call to waitForPresentKHR 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 SUCCESS (if the image was delivered to the presentation engine and may have been presented to the user) or will return early with status ERROR_OUT_OF_DATE_KHR (if the image could not be presented to the user).

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.

For 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.

As an exception to the normal rules for objects which are externally synchronized, the swapchain passed to waitForPresentKHR may be simultaneously used by other threads in calls to functions other than destroySwapchainKHR. Access to the swapchain data associated with this extension must be atomic within the implementation.

Valid Usage

• swapchain must not be in the retired state

• The presentWait feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• swapchain must be a valid SwapchainKHR handle

• swapchain must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to swapchain must be externally synchronized

Return Codes

Success

• SUBOPTIMAL_KHR

• SUCCESS

• TIMEOUT

Failure

• ERROR_DEVICE_LOST

• ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

• ERROR_OUT_OF_DATE_KHR

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_SURFACE_LOST_KHR

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_present_wait, Device, SwapchainKHR

A variant of waitForPresentKHR which makes a *safe* FFI call

VkPhysicalDevicePresentWaitFeaturesKHR - Structure indicating support for present wait

Members

This structure describes the following feature:

Description

If the PhysicalDevicePresentWaitFeaturesKHR structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. If the application wishes to use a Device with any features described by PhysicalDevicePresentWaitFeaturesKHR, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Structure Chaining

Extends the structures

• DeviceCreateInfo

• PhysicalDeviceFeatures2

See Also

VK_KHR_present_wait, Bool32, StructureType

VkSwapchainKHR - Opaque handle to a swapchain object

Description

A swapchain is an abstraction for an array of presentable images that are associated with a surface. The presentable images are represented by Image objects created by the platform. One image (which can be an array image for multiview/stereoscopic-3D surfaces) is displayed at a time, but multiple images can be queued for presentation. An application renders to the image, and then queues the image for presentation to the surface.

A native window cannot be associated with more than one non-retired swapchain at a time. Further, swapchains cannot be created for native windows that have a non-Vulkan graphics API surface associated with them.

The presentation engine is an abstraction for the platform’s compositor or display engine.

The presentation engine may be synchronous or asynchronous with respect to the application and/or logical device.

Some implementations may use the device’s graphics queue or dedicated presentation hardware to perform presentation.

The presentable images of a swapchain are owned by the presentation engine. An application can acquire use of a presentable image from the presentation engine. Use of a presentable image must occur only after the image is returned by acquireNextImageKHR, and before it is released by queuePresentKHR. This includes transitioning the image layout and rendering commands.

An application can acquire use of a presentable image with acquireNextImageKHR. After acquiring a presentable image and before modifying it, the application must use a synchronization primitive to ensure that the presentation engine has finished reading from the image. The application can then transition the image’s layout, queue rendering commands to it, etc. Finally, the application presents the image with queuePresentKHR, which releases the acquisition of the image. The application can also release the acquisition of the image through releaseSwapchainImagesKHR, if the image is not in use by the device, and skip the present operation.

The presentation engine controls the order in which presentable images are acquired for use by the application.

This allows the platform to handle situations which require out-of-order return of images after presentation. At the same time, it allows the application to generate command buffers referencing all of the images in the swapchain at initialization time, rather than in its main loop.

See Also

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_KHR_swapchain, AcquireNextImageInfoKHR, BindImageMemorySwapchainInfoKHR, ImageSwapchainCreateInfoKHR, PastPresentationTimingInfoEXT, PresentInfoKHR, ReleaseSwapchainImagesInfoKHR, SwapchainCalibratedTimestampInfoEXT, SwapchainCreateInfoKHR, acquireFullScreenExclusiveModeEXT, acquireNextImageKHR, createSharedSwapchainsKHR, createSwapchainKHR, destroySwapchainKHR, getLatencyTimingsNV, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, getSwapchainTimeDomainPropertiesEXT, getSwapchainTimingPropertiesEXT, latencySleepNV, queuePresentKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLatencyMarkerNV, setLatencySleepModeNV, setLocalDimmingAMD, setSwapchainPresentTimingQueueSizeEXT, waitForPresent2KHR, waitForPresentKHR