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