Vulkan-Docs/doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt

// Copyright (c) 2014-2016 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

== WSI Swapchain

A sname:VkSwapchainKHR object (a.k.a.
swapchain) provides the ability to present rendering results to a surface.
A swapchain is an abstraction for an array of presentable images that are
associated with a surface.
The swapchain images are represented by sname:VkImage 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 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
hardware/software display engine.

[NOTE]
.Note
====
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
fname:vkAcquireNextImageKHR, and before it is presented by
fname:vkQueuePresentKHR.
This includes transitioning the image layout and rendering commands.

An application can: acquire use of a presentable image with
fname:vkAcquireNextImageKHR.
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 fname:vkQueuePresentKHR,
which releases the acquisition of the image.

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

[NOTE]
.Note
====
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.
====

How this all works is described below.

// refBegin vkCreateSwapchainKHR - Create a swapchain

To create a swapchain, call:

include::../../api/protos/vkCreateSwapchainKHR.txt[]

  * pname:device is the device to create the swapchain for.
  * pname:pCreateInfo is a pointer to an instance of the
    slink:VkSwapchainCreateInfoKHR structure specifying the parameters of
    the created swapchain.
  * pname:pAllocator is the allocator used for host memory allocated for the
    swapchain object when there is no more specific allocator available (see
    <<memory-allocation,Memory Allocation>>).
  * pname:pSwapchain is a pointer to a sname:VkSwapchainKHR handle in which
    the created swapchain object will be returned.

include::../../validity/protos/vkCreateSwapchainKHR.txt[]

// refBegin VkSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object

The sname:VkSwapchainCreateInfoKHR structure is defined as:

include::../../api/structs/VkSwapchainCreateInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:flags is reserved for future use, and must: be zero.
  * pname:surface is the surface that the swapchain will present images to.
  * pname:minImageCount is the minimum number of presentable images that the
    application needs.
    The platform will either create the swapchain with at least that many
    images, or will fail to create the swapchain.
  * pname:imageFormat is a slink:VkFormat that is valid for swapchains on
    the specified surface.
  * pname:imageColorSpace is a slink:VkColorSpaceKHR that is valid for
    swapchains on the specified surface.
  * pname:imageExtent is the size (in pixels) of the swapchain.
    Behavior is platform-dependent when the image extent does not match the
    surface's pname:currentExtent as returned by
    fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR.
  * pname:imageArrayLayers is the number of views in a multiview/stereo
    surface.
    For non-stereoscopic-3D applications, this value is 1.
  * pname:imageUsage is a bitmask of elink:VkImageUsageFlagBits, indicating
    how the application will use the swapchain's presentable images.
  * pname:imageSharingMode is the sharing mode used for the images of the
    swapchain.
  * pname:queueFamilyIndexCount is the number of queue families having
    access to the images of the swapchain in case pname:imageSharingMode is
    ename:VK_SHARING_MODE_CONCURRENT.
  * pname:pQueueFamilyIndices is an array of queue family indices having
    access to the images of the swapchain in case pname:imageSharingMode is
    ename:VK_SHARING_MODE_CONCURRENT.
  * pname:preTransform is a bitmask of elink:VkSurfaceTransformFlagBitsKHR,
    describing the transform, relative to the presentation engine's natural
    orientation, applied to the image content prior to presentation.
    If it does not match the pname:currentTransform value returned by
    fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, the presentation engine
    will transform the image content as part of the presentation operation.
  * pname:compositeAlpha is a bitmask of elink:VkCompositeAlphaFlagBitsKHR,
    indicating the alpha compositing mode to use when this surface is
    composited together with other surfaces on certain window systems.
  * pname:presentMode is the presentation mode the swapchain will use.
    A swapchain's present mode determines how incoming present requests will
    be processed and queued internally.
  * pname:clipped indicates whether the Vulkan implementation is allowed to
    discard rendering operations that affect regions of the surface which
    are not visible.
  ** If set to ename:VK_TRUE, the presentable images associated with the
     swapchain may: not own all of their pixels.
     Pixels in the presentable images that correspond to regions of the
     target surface obscured by another window on the desktop or subject to
     some other clipping mechanism will have undefined content when read
     back.
     Pixel shaders may: not execute for these pixels, and thus any side
     affects they would have had will not occur.
  ** If set to ename:VK_FALSE, presentable images associated with the
     swapchain will own all the pixels they contain.
     Setting this value to ename:VK_TRUE does not guarantee any clipping
     will occur, but allows more optimal presentation methods to be used on
     some platforms.

[NOTE]
.Note
====
Applications should: set this value to ename:VK_TRUE if they do not expect
to read back the content of presentable images before presenting them or
after reacquiring them and if their pixel shaders do not have any side
effects that require them to run for all pixels in the presentable image.
====

  * pname:oldSwapchain, if not code:VK_NULL_HANDLE, specifies the swapchain
    that will be replaced by the new swapchain being created.
    The new swapchain will be a descendant of pname:oldSwapchain.
    Further, any descendants of the new swapchain will also be descendants
    of pname:oldSwapchain.
    Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that
    is not code:VK_NULL_HANDLE, any images not acquired by the application
    may: be freed by the implementation, which may: occur even if creation
    of the new swapchain fails.
    The application must: destroy the old swapchain to free all memory
    associated with the old swapchain.
    The application must: wait for the completion of any outstanding
    rendering to images it currently has acquired at the time the swapchain
    is destroyed.
    The application can: continue to present any images it acquired and has
    not yet presented using the old swapchain, as long as it has not entered
    a state that causes it to return ename:VK_ERROR_OUT_OF_DATE_KHR.
    However, the application cannot: acquire any more images from the old
    swapchain regardless of whether or not creation of the new swapchain
    succeeds.

.Valid Usage
****
  * pname:surface must: be a surface that is supported by the device as
    determined using fname:vkGetPhysicalDeviceSurfaceSupportKHR
  * pname:minImageCount must: be greater than or equal to the value returned
    in the pname:minImageCount member of the sname:VkSurfaceCapabilitiesKHR
    structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR
    for the surface
  * pname:minImageCount must: be less than or equal to the value returned in
    the pname:maxImageCount member of the sname:VkSurfaceCapabilitiesKHR
    structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR
    for the surface if the returned pname:maxImageCount is not zero
  * pname:imageFormat and pname:imageColorSpace must: match the pname:format
    and pname:colorSpace members, respectively, of one of the
    sname:VkSurfaceFormatKHR structures returned by
    fname:vkGetPhysicalDeviceSurfaceFormatsKHR for the surface
  * pname:imageExtent must: be between pname:minImageExtent and
    pname:maxImageExtent, inclusive, where pname:minImageExtent and
    pname:maxImageExtent are members of the sname:VkSurfaceCapabilitiesKHR
    structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR
    for the surface
  * pname:imageArrayLayers must: be greater than `0` and less than or equal
    to the pname:maxImageArrayLayers member of the
    sname:VkSurfaceCapabilitiesKHR structure returned by
    fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface
  * pname:imageUsage must: be a subset of the supported usage flags present
    in the pname:supportedUsageFlags member of the
    sname:VkSurfaceCapabilitiesKHR structure returned by
    fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface
  * If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT,
    pname:pQueueFamilyIndices must: be a pointer to an array of
    pname:queueFamilyIndexCount basetype:uint32_t values
  * If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT,
    pname:queueFamilyIndexCount must: be greater than `1`
  * pname:preTransform must: be one of the bits present in the
    pname:supportedTransforms member of the sname:VkSurfaceCapabilitiesKHR
    structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR
    for the surface
  * pname:compositeAlpha must: be one of the bits present in the
    pname:supportedCompositeAlpha member of the
    sname:VkSurfaceCapabilitiesKHR structure returned by
    fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface
  * pname:presentMode must: be one of the ename:VkPresentModeKHR values
    returned by fname:vkGetPhysicalDeviceSurfacePresentModesKHR for the
    surface
****

include::../../validity/structs/VkSwapchainCreateInfoKHR.txt[]

As mentioned above, if fname:vkCreateSwapchainKHR succeeds, it will return a
handle to a swapchain that contains an array of at least pname:minImageCount
presentable images.

While acquired by the application, swapchain images can: be used in any way
that equivalent non-swapchain images can: be used.
A swapchain image is equivalent to a non-swapchain image created with the
following sname:VkImageCreateInfo parameters:

[options="header"]
|====
| sname:VkImageCreateInfo Field | Value
| pname:flags                   | 0
| pname:imageType               | ename:VK_IMAGE_TYPE_2D
| pname:format                  | `pCreateInfo->imageFormat`
| pname:extent                  | `{pCreateInfo->imageExtent.width, pCreateInfo->imageExtent.height, 1}`
| pname:mipLevels               | 1
| pname:arrayLayers             | `pCreateInfo->imageArrayLayers`
| pname:samples                 | ename:VK_SAMPLE_COUNT_1_BIT
| pname:tiling                  | ename:VK_IMAGE_TILING_OPTIMAL
| pname:usage                   | `pCreateInfo->imageUsage`
| pname:sharingMode             | `pCreateInfo->imageSharingMode`
| pname:queueFamilyIndexCount   | `pCreateInfo->queueFamilyIndexCount`
| pname:pQueueFamilyIndices     | `pCreateInfo->pQueueFamilyIndices`
| pname:initialLayout           | ename:VK_IMAGE_LAYOUT_UNDEFINED
|====

The sname:VkSurfaceKHR associated with a swapchain must: not be destroyed
until after the swapchain is destroyed.

The native window referred to by pname:surface must: not already be
associated with a swapchain other than pname:oldSwapchain, or with a
non-Vulkan graphics API surface.

Like core functions, several WSI functions, including
fname:vkCreateSwapchainKHR return ename:VK_ERROR_DEVICE_LOST if the logical
device was lost.
See <<devsandqueues-lost-device,Lost Device>>.
As with most core objects, sname:VkSwapchainKHR is a child of the device and
is affected by the lost state; it must: be destroyed before destroying the
sname:VkDevice.
However, sname:VkSurfaceKHR is not a child of any sname:VkDevice and is not
otherwise affected by the lost device.
After successfully recreating a sname:VkDevice, the same sname:VkSurfaceKHR
can: be used to create a new sname:VkSwapchainKHR, provided the previous one
was destroyed.

[NOTE]
.Note
====
As mentioned in <<devsandqueues-lost-device,Lost Device>>, after a lost
device event, the sname:VkPhysicalDevice may: also be lost.
If other sname:VkPhysicalDevice are available, they can: be used together
with the same sname:VkSurfaceKHR to create the new sname:VkSwapchainKHR,
however the application must: query the surface capabilities again, because
they may: differ on a per-physical device basis.
====

// refBegin vkDestroySwapchainKHR - Destroy a swapchain object

To destroy a swapchain object call:

include::../../api/protos/vkDestroySwapchainKHR.txt[]

  * pname:device is the sname:VkDevice associated with pname:swapchain.
  * pname:swapchain is the swapchain to destroy.
  * pname:pAllocator is the allocator used for host memory allocated for the
    swapchain object when there is no more specific allocator available (see
    <<memory-allocation,Memory Allocation>>).

pname:swapchain and all associated sname:VkImage handles are destroyed, and
must: not be acquired or used any more by the application.
The memory of each sname:VkImage will only be freed after that image is no
longer used by the platform.
For example, if one image of the swapchain is being displayed in a window,
the memory for that image may: not be freed until the window is destroyed,
or another swapchain is created for the window.
Destroying the swapchain does not invalidate the parent sname:VkSurfaceKHR,
and a new swapchain can: be created with it.

ifdef::VK_KHR_display_swapchain[]
include::../VK_KHR_display_swapchain/destroy_swapchain_interactions.txt[]
endif::VK_KHR_display_swapchain[]

.Valid Usage
****
  * All uses of presentable images acquired from pname:swapchain must: have
    completed execution
  * If sname:VkAllocationCallbacks were provided when pname:swapchain was
    created, a compatible set of callbacks must: be provided here
  * If no sname:VkAllocationCallbacks were provided when pname:swapchain was
    created, pname:pAllocator must: be `NULL`
****

include::../../validity/protos/vkDestroySwapchainKHR.txt[]

ifdef::VK_KHR_display_swapchain[]
include::../VK_KHR_display_swapchain/create_shared_swapchains.txt[]
endif::VK_KHR_display_swapchain[]

// refBegin vkGetSwapchainImagesKHR - Obtain the array of presentable images associated with a swapchain

To obtain the array of presentable images associated with a swapchain, call:

include::../../api/protos/vkGetSwapchainImagesKHR.txt[]

  * pname:device is the device associated with pname:swapchain.
  * pname:swapchain is the swapchain to query.
  * pname:pSwapchainImageCount is a pointer to an integer related to the
    number of swapchain images available or queried, as described below.
  * pname:pSwapchainImages is either `NULL` or a pointer to an array of
    sname:VkImage handles.

If pname:pSwapchainImages is `NULL`, then the number of presentable images
for pname:swapchain is returned in pname:pSwapchainImageCount.
Otherwise, pname:pSwapchainImageCount must: point to a variable set by the
user to the number of elements in the pname:pSwapchainImages array, and on
return the variable is overwritten with the number of structures actually
written to pname:pSwapchainImages.
If the value of pname:pSwapchainImageCount is less than the number of
presentable images for pname:swapchain, at most pname:pSwapchainImageCount
structures will be written.
If pname:pSwapchainImageCount is smaller than the number of presentable
images for pname:swapchain, ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS to indicate that not all the available values were
returned.

include::../../validity/protos/vkGetSwapchainImagesKHR.txt[]

[NOTE]
.Note
====
By knowing all presentable images used in the swapchain, the application
can: create command buffers that reference these images prior to entering
its main rendering loop.
====

The implementation will have already allocated and bound the memory backing
the sname:VkImages returned by fname:vkGetSwapchainImagesKHR.
The memory for each image will not alias with the memory for other images or
with any sname:VkDeviceMemory object.
As such, performing any operation affecting the binding of memory to a
presentable image results in undefined behavior.
All presentable images are initially in the ename:VK_IMAGE_LAYOUT_UNDEFINED
layout, thus before using presentable images, the application must:
transition them to a valid layout for the intended use.

Further, the lifetime of presentable images is controlled by the
implementation so destroying a presentable image with flink:vkDestroyImage
results in undefined behavior.
See flink:vkDestroySwapchainKHR for further details on the lifetime of
presentable images.

// refBegin vkAcquireNextImageKHR - Retrieve the index of the next available presentable image

To acquire an available presentable image to use, and retrieve the index of
that image, call:

include::../../api/protos/vkAcquireNextImageKHR.txt[]

  * pname:device is the device associated with pname:swapchain.
  * pname:swapchain is the swapchain from which an image is being acquired.
  * pname:timeout indicates how long the function waits, in nanoseconds, if
    no image is available.
  * pname:semaphore is code:VK_NULL_HANDLE or a semaphore to signal.
  * pname:fence is code:VK_NULL_HANDLE or a fence to signal.
  * pname:pImageIndex is a pointer to a code:uint32_t that is set to the
    index of the next image to use (i.e. an index into the array of images
    returned by fname:vkGetSwapchainImagesKHR).

.Valid Usage
****
  * If pname:semaphore is not dlink:VK_NULL_HANDLE it must: be unsignaled
  * If pname:fence is not dlink:VK_NULL_HANDLE it must: be unsignaled and
    must: not be associated with any other queue command that has not yet
    completed execution on that queue
****

include::../../validity/protos/vkAcquireNextImageKHR.txt[]

When successful, fname:vkAcquireNextImageKHR acquires a presentable image
that the application can: use, and sets pname:pImageIndex to the index of
that image.
The presentation engine may: not have finished reading from the image at the
time it is acquired, so the application must: use pname:semaphore and/or
pname:fence to ensure that the image layout and contents are not modified
until the presentation engine reads have completed.

As mentioned above, the presentation engine controls the order in which
presentable images are made available to the application.
This allows the platform to handle special situations.
The order in which images are acquired is implementation-dependent.
Images may: be acquired in a seemingly random order that is not a simple
round-robin.

If a swapchain has enough presentable images, applications can: acquire
multiple images without an intervening fname:vkQueuePresentKHR.
Applications can: present images in a different order than the order in
which they were acquired.

If pname:timeout is 0, fname:vkAcquireNextImageKHR will not block, but will
either succeed or return ename:VK_NOT_READY.
If pname:timeout is `UINT64_MAX`, the function will not return until an
image is acquired from the presentation engine.
Other values for pname:timeout will cause the function to return when an
image becomes available, or when the specified number of nanoseconds have
passed (in which case it will return ename:VK_TIMEOUT).
An error can: also cause fname:vkAcquireNextImageKHR to return early.

[NOTE]
.Note
====
As mentioned above, the presentation engine may: be asynchronous with
respect to the application and/or logical device.
fname:vkAcquireNextImageKHR may: return as soon as it can: identify which
image will be acquired, and can: guarantee that pname:semaphore and
pname:fence will be signaled by the presentation engine; and may: not
successfully return sooner.
The application uses pname:timeout to specify how long
fname:vkAcquireNextImageKHR waits for an image to become acquired.
====

Applications cannot: rely on fname:vkAcquireNextImageKHR blocking in order
to meter their rendering speed.
Various factors can: interrupt fname:vkAcquireNextImageKHR from blocking.

[NOTE]
.Note
====
For example, if an error occurs, fname:vkAcquireNextImageKHR may: return
even though no image is available.
As another example, some presentation engines are able to enqueue an
unbounded number of presentation and acquire next image operations such that
fname:vkAcquireNextImageKHR never needs to wait for completion of
outstanding present operations before returning.
====

The availability of presentable images is influenced by factors such as the
implementation of the presentation engine, the ename:VkPresentModeKHR being
used, the number of images in the swapchain, the number of images that the
application has acquired at any given time, and the performance of the
application.
The value of sname:VkSurfaceCapabilitiesKHR::pname:minImageCount indicates
how many images must: be in the swapchain in order for
fname:vkAcquireNextImageKHR to acquire an image if the application currently
has no acquired images.

Let _n_ be the total number of images in the swapchain, _m_ be the value of
sname:VkSurfaceCapabilitiesKHR::pname:minImageCount, and _a_ be the number
of presentable images that the application has currently acquired (i.e.
images acquired with fname:vkAcquireNextImageKHR, but not yet presented with
fname:vkQueuePresentKHR).
fname:vkAcquireNextImageKHR can: always succeed if [eq]#a {leq} n - m# at
the time fname:vkAcquireNextImageKHR is called.
fname:vkAcquireNextImageKHR should: not be called if [eq]#a > n - m# with a
pname:timeout of code:UINT64_MAX; in such a case,
fname:vkAcquireNextImageKHR may: block indefinitely.

[NOTE]
.Note
====
For example, if the pname:minImageCount member of
sname:VkSurfaceCapabilitiesKHR is 2, and the application creates a swapchain
with 2 presentable images, the application can: acquire one image, and must:
present it before trying to acquire another image.

If we modify this example so that the application wishes to acquire up to 3
presentable images simultaneously, it must: request a minimum image count of
4 when creating the swapchain.
====

If pname:semaphore is not code:VK_NULL_HANDLE, the semaphore must: be
unsignaled and not have any uncompleted signal or wait operations pending.
It will become signaled when the application can: use the image.
Queue operations that access the image contents must: wait until the
semaphore signals; typically applications should: include the semaphore in
the pname:pWaitSemaphores list for the queue submission that transitions the
image away from the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout.
Use of the semaphore allows rendering operations to be recorded and
submitted before the presentation engine has completed its use of the image.

If pname:fence is not equal to code:VK_NULL_HANDLE, the fence must: be
unsignaled and not have any uncompleted signal operations pending.
It will become signaled when the application can: use the image.
Applications can: use this to meter their frame generation work to match the
presentation rate.

pname:semaphore and pname:fence must: not both be equal to
code:VK_NULL_HANDLE.
An application must: wait until either the pname:semaphore or pname:fence is
signaled before using the presentable image.

pname:semaphore and pname:fence may: already be signaled when
fname:vkAcquireNextImageKHR returns, if the image is being acquired for the
first time, or if the presentable image is immediately ready for use.

A successful call to fname:vkAcquireNextImageKHR counts as a signal
operation on pname:semaphore for the purposes of queue forward-progress
requirements.
The semaphore is guaranteed to signal, so a wait operation can: be queued
for the semaphore without risk of deadlock.

The fname:vkCmdWaitEvents or fname:vkCmdPipelineBarrier used to transition
the image away from ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout must: have
pname:dstStageMask and pname:dstAccessMask parameters set based on the next
use of the image.
The application must: use <<synchronization-submission-host-writes, implicit
ordering guarantees>> and <<synchronization-dependencies,execution
dependencies>> to prevent the image transition from occurring before the
semaphore passed to fname:vkAcquireNextImageKHR has signaled.

[NOTE]
.Note
====
When the swapchain image will be written by some stage [eq]#S#, the
recommended idiom for ensuring the semaphore signals before the transition
occurs is:

  * The batch that contains the transition includes the image-acquire
    semaphore in the list of semaphores to wait for, with a wait stage mask
    that includes [eq]#S#.
  * The pipeline barrier that performs the transition includes [eq]#S# in
    both the pname:srcStageMask and pname:dstStageMask.

This causes the pipeline barrier to wait at [eq]#S# until the semaphore
signals before performing the transition and memory barrier, while allowing
earlier pipeline stages of subsequent commands to proceed.
====

After a successful return, the image indicated by pname:pImageIndex will
still be in the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout if it was
previously presented, or in the ename:VK_IMAGE_LAYOUT_UNDEFINED layout if
this is the first time it has been acquired.

[NOTE]
.Note
====
Exclusive ownership of presentable images corresponding to a swapchain
created with ename:VK_SHARING_MODE_EXCLUSIVE as defined in
<<resources-sharing,Resource Sharing>> is not altered by a call to
fname:vkAcquireNextImageKHR.
That means upon the first acquisition from such a swapchain presentable
images are not owned by any queue family, while at subsequent acquisitions
the presentable images remain owned by the queue family the image was
previously presented on.
====

The possible return values for fname:vkAcquireNextImageKHR() depend on the
pname:timeout provided:

  * ename:VK_SUCCESS is returned if an image became available.
  * ename:VK_ERROR_SURFACE_LOST_KHR if the surface becomes no longer
    available.
  * ename:VK_NOT_READY is returned if pname:timeout is zero and no image was
    available.
  * ename:VK_TIMEOUT is returned if pname:timeout is greater than zero and
    less than `UINT64_MAX`, and no image became available within the time
    allowed.
  * ename:VK_SUBOPTIMAL_KHR is returned if an image became available, and
    the swapchain no longer matches the surface properties exactly, but can:
    still be used to present to the surface successfully.

[NOTE]
.Note
====
This may: happen, for example, if the platform surface has been resized but
the platform is able to scale the presented images to the new size to
produce valid surface updates.
It is up to applications to decide whether they prefer to continue using the
current swapchain indefinitely or temporarily in this state, or to re-create
the swapchain to better match the platform surface properties.
====

  * ename:VK_ERROR_OUT_OF_DATE_KHR is returned if the surface has changed in
    such a way that it is no longer compatible with the swapchain, and
    further presentation requests using the swapchain will fail.
    Applications must: query the new surface properties and recreate their
    swapchain if they wish to continue presenting to the surface.

If the native surface and presented image sizes no longer match,
presentation may: fail.
If presentation does succeed, parts of the native surface may: be undefined,
parts of the presented image may: have been clipped before presentation,
and/or the image may: have been scaled (uniformly or not uniformly) before
presentation.
It is the application's responsibility to detect surface size changes and
react appropriately.
If presentation fails because of a mismatch in the surface and presented
image sizes, a ename:VK_ERROR_OUT_OF_DATE_KHR error will be returned.

Before an application can: present an image, the image's layout must: be
transitioned to the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout.

.Note
[NOTE]
====
When transitioning the image to ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR, there
is no need to delay subsequent processing, or perform any visibility
operations (as flink:vkQueuePresentKHR performs automatic visibility
operations).
To achieve this, the pname:dstAccessMask member of the
slink:VkImageMemoryBarrier should: be set to `0`, and the pname:dstStageMask
parameter should: be set to ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT.
====

// refBegin vkQueuePresentKHR - Queue an image for presentation

After queueing all rendering commands and transitioning the image to the
correct layout, to queue an image for presentation, call:

include::../../api/protos/vkQueuePresentKHR.txt[]

  * pname:queue is a queue that is capable of presentation to the target
    surface's platform on the same device as the image's swapchain.
  * pname:pPresentInfo is a pointer to an instance of the
    slink:VkPresentInfoKHR structure specifying the parameters of the
    presentation.

.Valid Usage
****
  * Any given element of pname:pSwapchains member of pname:pPresentInfo
    must: be a swapchain that is created for a surface for which
    presentation is supported from pname:queue as determined using a call to
    fname:vkGetPhysicalDeviceSurfaceSupportKHR
ifdef::VK_KHR_display_swapchain[]
  * If more than one member of pname:pSwapchains was created from a display
    surface, all display surfaces referenced that refer to the same display
    must: use the same display mode
endif::VK_KHR_display_swapchain[]
****

Any writes to memory backing the images referenced by the
pname:pImageIndices and pname:pSwapchains members of pname:pPresentInfo,
that are available before flink:VkQueuePresentKHR is executed, are
automatically made visible to the read access performed by the presentation
engine.
This automatic visibility operation for an image happens-after the semaphore
signal operation, and happens-before the presentation engine accesses the
image.

include::../../validity/protos/vkQueuePresentKHR.txt[]

// refBegin VkPresentInfoKHR - Structure describing parameters of a queue presentation

The sname:VkPresentInfoKHR structure is defined as:

include::../../api/structs/VkPresentInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:waitSemaphoreCount is the number of semaphores to wait for before
    issuing the present request.
    The number may: be zero.
  * pname:pWaitSemaphores, if not code:VK_NULL_HANDLE, is an array of
    sname:VkSemaphore objects with pname:waitSemaphoreCount entries, and
    specifies the semaphores to wait for before issuing the present request.
  * pname:swapchainCount is the number of swapchains being presented to by
    this command.
  * pname:pSwapchains is an array of sname:VkSwapchainKHR objects with
    pname:swapchainCount entries.
    A given swapchain must: not appear in this list more than once.
  * pname:pImageIndices is an array of indices into the array of each
    swapchain's presentable images, with pname:swapchainCount entries.
    Each entry in this array identifies the image to present on the
    corresponding entry in the pname:pSwapchains array.
  * pname:pResults is an array of ename:VkResult typed elements with
    pname:swapchainCount entries.
    Applications that do not need per-swapchain results can: use `NULL` for
    pname:pResults.
    If non-`NULL`, each entry in pname:pResults will be set to the
    ename:VkResult for presenting the swapchain corresponding to the same
    index in pname:pSwapchains.

.Valid Usage
****
  * Any given element of pname:pImageIndices must: be the index of a
    presentable image acquired from the swapchain specified by the
    corresponding element of the pname:pSwapchains array, and the presented
    image subresource must: be in the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
    layout at the time the operation is executed on a sname:VkDevice
  * Any given element of sname:VkSemaphore in pname:pWaitSemaphores must:
    refer to a prior signal of that sname:VkSemaphore that will not be
    consumed by any other wait on that semaphore
****

include::../../validity/structs/VkPresentInfoKHR.txt[]

ifdef::VK_KHR_display_swapchain[]
include::../VK_KHR_display_swapchain/display_swapchain_present.txt[]
endif::VK_KHR_display_swapchain[]

fname:vkQueuePresentKHR, releases the acquisition of the images referenced
by pname:imageIndices.
The queue family corresponding to the queue fname:vkQueuePresentKHR is
executed on must: have ownership of the presented images as defined in
<<resource-sharing,Resource Sharing>>.
fname:vkQueuePresentKHR does not alter the queue family ownership, but the
presented images must: not be used again before they have been reacquired
using fname:vkAcquireNextImageKHR.

The processing of the presentation happens in issue order with other queue
operations, but semaphores have to be used to ensure that prior rendering
and other commands in the specified queue complete before the presentation
begins.
The presentation command itself does not delay processing of subsequent
commands on the queue, however, presentation requests sent to a particular
queue are always performed in order.
Exact presentation timing is controlled by the semantics of the presentation
engine and native platform in use.

ifdef::VK_KHR_display_swapchain[]
include::../VK_KHR_display_swapchain/queue_present_interactions.txt[]
endif::VK_KHR_display_swapchain[]

The result codes ename:VK_ERROR_OUT_OF_DATE_KHR and ename:VK_SUBOPTIMAL_KHR
have the same meaning when returned by fname:vkQueuePresentKHR as they do
when returned by fname:vkAcquireNextImageKHR().
If multiple swapchains are presented, the result code is determined applying
the following rules in order:

  * If the device is lost, ename:VK_ERROR_DEVICE_LOST is returned.
  * If any of the target surfaces are no longer available the error
    ename:VK_ERROR_SURFACE_LOST_KHR is returned.
  * If any of the presents would have a result of
    ename:VK_ERROR_OUT_OF_DATE_KHR if issued separately then
    ename:VK_ERROR_OUT_OF_DATE_KHR is returned.
  * If any of the presents would have a result of ename:VK_SUBOPTIMAL_KHR if
    issued separately then ename:VK_SUBOPTIMAL_KHR is returned.
  * Otherwise ename:VK_SUCCESS is returned.

Presentation is a read-only operation that will not affect the content of
the presentable images.
Upon reacquiring the image and transitioning it away from the
ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout, the contents will be the same
as they were prior to transitioning the image to the present source layout
and presenting it.
However, if a mechanism other than Vulkan is used to modify the platform
window associated with the swapchain, the content of all presentable images
in the swapchain becomes undefined.