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

== WSI Swapchain

[open,refpage='VkSwapchainKHR',desc='Opaque handle to a swapchain object',type='handles']
--
A swapchain object (a.k.a.
swapchain) provides the ability to present rendering results to a surface.
Swapchain objects are represented by sname:VkSwapchainKHR handles:

include::{generated}/api/handles/VkSwapchainKHR.txt[]

A swapchain is an abstraction for an array of presentable images that are
associated with a surface.
The presentable 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 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.

[NOTE]
.Note
====
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
fname:vkAcquireNextImageKHR, and before it is released 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.

ifdef::VK_KHR_shared_presentable_image[]
include::{chapters}/VK_KHR_shared_presentable_image/wsi.txt[]
endif::VK_KHR_shared_presentable_image[]

[open,refpage='vkCreateSwapchainKHR',desc='Create a swapchain',type='protos']
--
To create a swapchain, call:

include::{generated}/api/protos/vkCreateSwapchainKHR.txt[]

  * pname:device is the device to create the swapchain for.
  * pname:pCreateInfo is a pointer to a 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 slink:VkSwapchainKHR handle in which
    the created swapchain object will be returned.

ifdef::VK_EXT_full_screen_exclusive[]
If the pname:oldSwapchain parameter of pname:pCreateInfo is a valid
swapchain, which has exclusive full-screen access, that access is released
from pname:oldSwapchain.
If the command succeeds in this case, the newly created swapchain will
automatically acquire exclusive full-screen access from pname:oldSwapchain.

[NOTE]
.Note
====
This implicit transfer is intended to avoid exiting and entering full-screen
exclusive mode, which may otherwise cause unwanted visual updates to the
display.
====

In some cases, swapchain creation may: fail if exclusive full-screen mode is
requested for application control, but for some implementation-specific
reason exclusive full-screen access is unavailable for the particular
combination of parameters provided.
If this occurs, ename:VK_ERROR_INITIALIZATION_FAILED will be returned.

[NOTE]
.Note
====
In particular, it will fail if the pname:imageExtent member of
pname:pCreateInfo does not match the extents of the monitor.
ifdef::VK_KHR_win32_surface[]
Other reasons for failure may include the app not being set as high-dpi
aware, or if the physical device and monitor are not compatible in this
mode.
endif::VK_KHR_win32_surface[]
====

endif::VK_EXT_full_screen_exclusive[]

ifdef::VK_NV_acquire_winrt_display[]
When the slink:VkSurfaceKHR in slink:VkSwapchainCreateInfoKHR is a display
surface, then the slink:VkDisplayModeKHR in display surface's
slink:VkDisplaySurfaceCreateInfoKHR is associated with a particular
slink:VkDisplayKHR.
Swapchain creation may: fail if that slink:VkDisplayKHR is not acquired by
the application.
In this scenario ename:VK_ERROR_INITIALIZATION_FAILED is returned.
endif::VK_NV_acquire_winrt_display[]

include::{generated}/validity/protos/vkCreateSwapchainKHR.txt[]
--

[open,refpage='VkSwapchainCreateInfoKHR',desc='Structure specifying parameters of a newly created swapchain object',type='structs']
--
The sname:VkSwapchainCreateInfoKHR structure is defined as:

include::{generated}/api/structs/VkSwapchainCreateInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is a bitmask of elink:VkSwapchainCreateFlagBitsKHR
    indicating parameters of the swapchain creation.
  * pname:surface is the surface onto which the swapchain will present
    images.
    If the creation succeeds, the swapchain becomes associated with
    pname:surface.
  * pname:minImageCount is the minimum number of presentable images that the
    application needs.
    The implementation will either create the swapchain with at least that
    many images, or it will fail to create the swapchain.
  * pname:imageFormat is a elink:VkFormat value specifying the format the
    swapchain image(s) will be created with.
  * pname:imageColorSpace is a elink:VkColorSpaceKHR value specifying the
    way the swapchain interprets image data.
  * pname:imageExtent is the size (in pixels) of the swapchain image(s).
    The behavior is platform-dependent if the image extent does not match
    the surface's pname:currentExtent as returned by
    fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR.
+
[NOTE]
.Note
====
On some platforms, it is normal that pname:maxImageExtent may: become `(0,
0)`, for example when the window is minimized.
In such a case, it is not possible to create a swapchain due to the Valid
Usage requirements.
====
  * 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 describing
    the intended usage of the (acquired) swapchain images.
  * pname:imageSharingMode is the sharing mode used for the image(s) of the
    swapchain.
  * pname:queueFamilyIndexCount is the number of queue families having
    access to the image(s) of the swapchain when pname:imageSharingMode is
    ename:VK_SHARING_MODE_CONCURRENT.
  * pname:pQueueFamilyIndices is a pointer to an array of queue family
    indices having access to the images(s) of the swapchain when
    pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT.
  * pname:preTransform is a elink:VkSurfaceTransformFlagBitsKHR value
    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 elink:VkCompositeAlphaFlagBitsKHR value
    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 specifies whether the Vulkan implementation is allowed to
    discard rendering operations that affect regions of the surface that 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.
     Fragment shaders may: not execute for these pixels, and thus any side
     effects they would have had will not occur.
     Setting ename:VK_TRUE does not guarantee any clipping will occur, but
     allows more efficient presentation methods to be used on some
     platforms.
  ** If set to ename:VK_FALSE, presentable images associated with the
     swapchain will own all of the pixels they contain.
+
[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 fragment shaders do not have any side
effects that require them to run for all pixels in the presentable image.
====
  * pname:oldSwapchain is dlink:VK_NULL_HANDLE, or the existing non-retired
    swapchain currently associated with pname:surface.
    Providing a valid pname:oldSwapchain may: aid in the resource reuse, and
    also allows the application to still present any images that are already
    acquired from it.

Upon calling fname:vkCreateSwapchainKHR with an pname:oldSwapchain that is
not dlink:VK_NULL_HANDLE, pname:oldSwapchain is retired -- even if creation
of the new swapchain fails.
The new swapchain is created in the non-retired state whether or not
pname:oldSwapchain is dlink:VK_NULL_HANDLE.

Upon calling fname:vkCreateSwapchainKHR with an pname:oldSwapchain that is
not dlink:VK_NULL_HANDLE, any images from pname:oldSwapchain that are not
acquired by the application may: be freed by the implementation, which may:
occur even if creation of the new swapchain fails.
The application can: destroy pname:oldSwapchain to free all memory
associated with pname:oldSwapchain.

[NOTE]
.Note
====
Multiple retired swapchains can: be associated with the same
sname:VkSurfaceKHR through multiple uses of pname:oldSwapchain that
outnumber calls to flink:vkDestroySwapchainKHR.

After pname:oldSwapchain is retired, the application can: pass to
flink:vkQueuePresentKHR any images it had already acquired from
pname:oldSwapchain.
E.g., an application may present an image from the old swapchain before an
image from the new swapchain is ready to be presented.
As usual, flink:vkQueuePresentKHR may: fail if pname:oldSwapchain has
entered a state that causes ename:VK_ERROR_OUT_OF_DATE_KHR to be returned.

ifdef::VK_KHR_shared_presentable_image[]
The application can: continue to use a shared presentable image obtained
from pname:oldSwapchain until a presentable image is acquired from the new
swapchain, as long as it has not entered a state that causes it to return
ename:VK_ERROR_OUT_OF_DATE_KHR.
endif::VK_KHR_shared_presentable_image[]
====

.Valid Usage
****
  * [[VUID-VkSwapchainCreateInfoKHR-surface-01270]]
    pname:surface must: be a surface that is supported by the device as
    determined using flink:vkGetPhysicalDeviceSurfaceSupportKHR
ifndef::VK_KHR_shared_presentable_image[]
  * [[VUID-VkSwapchainCreateInfoKHR-minImageCount-01271]]
    pname:minImageCount must: be greater than or equal to the value returned
    in the pname:minImageCount member of the sname:VkSurfaceCapabilitiesKHR
    structure returned by flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR
    for the surface
endif::VK_KHR_shared_presentable_image[]
  * [[VUID-VkSwapchainCreateInfoKHR-minImageCount-01272]]
    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
ifdef::VK_KHR_shared_presentable_image[]
  * [[VUID-VkSwapchainCreateInfoKHR-presentMode-02839]]
    If pname:presentMode is not
    ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR nor
    ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, then
    pname:minImageCount must: be greater than or equal to the value returned
    in the pname:minImageCount member of the sname:VkSurfaceCapabilitiesKHR
    structure returned by flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR
    for the surface
  * [[VUID-VkSwapchainCreateInfoKHR-minImageCount-01383]]
    pname:minImageCount must: be `1` if pname:presentMode is either
    ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or
    ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
endif::VK_KHR_shared_presentable_image[]
  * [[VUID-VkSwapchainCreateInfoKHR-imageFormat-01273]]
    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
  * [[VUID-VkSwapchainCreateInfoKHR-imageExtent-01274]]
    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
  * [[VUID-VkSwapchainCreateInfoKHR-imageExtent-01689]]
    pname:imageExtent members pname:width and pname:height must: both be
    non-zero
  * [[VUID-VkSwapchainCreateInfoKHR-imageArrayLayers-01275]]
    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
ifndef::VK_KHR_shared_presentable_image[]
  * [[VUID-VkSwapchainCreateInfoKHR-imageUsage-01276]]
    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
endif::VK_KHR_shared_presentable_image[]
ifdef::VK_KHR_shared_presentable_image[]
  * [[VUID-VkSwapchainCreateInfoKHR-presentMode-01427]]
    If pname:presentMode is ename:VK_PRESENT_MODE_IMMEDIATE_KHR,
    ename:VK_PRESENT_MODE_MAILBOX_KHR, ename:VK_PRESENT_MODE_FIFO_KHR or
    ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR, pname:imageUsage must: be a
    subset of the supported usage flags present in the
    pname:supportedUsageFlags member of the slink:VkSurfaceCapabilitiesKHR
    structure returned by flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR
    for pname:surface
  * [[VUID-VkSwapchainCreateInfoKHR-imageUsage-01384]]
    If pname:presentMode is ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
    or ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, pname:imageUsage
    must: be a subset of the supported usage flags present in the
    pname:sharedPresentSupportedUsageFlags member of the
    slink:VkSharedPresentSurfaceCapabilitiesKHR structure returned by
    flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR for pname:surface
endif::VK_KHR_shared_presentable_image[]
  * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01277]]
    If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT,
    pname:pQueueFamilyIndices must: be a valid pointer to an array of
    pname:queueFamilyIndexCount code:uint32_t values
  * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01278]]
    If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT,
    pname:queueFamilyIndexCount must: be greater than `1`
ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
  * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01393]]
    If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, each
    element of pname:pQueueFamilyIndices must: be unique and must: be less
    than pname:pQueueFamilyPropertyCount returned by
    flink:vkGetPhysicalDeviceQueueFamilyProperties for the
    pname:physicalDevice that was used to create pname:device
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
  * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01428]]
    If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, each
    element of pname:pQueueFamilyIndices must: be unique and must: be less
    than pname:pQueueFamilyPropertyCount returned by either
    flink:vkGetPhysicalDeviceQueueFamilyProperties or
    flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the
    pname:physicalDevice that was used to create pname:device
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
  * [[VUID-VkSwapchainCreateInfoKHR-preTransform-01279]]
    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
  * [[VUID-VkSwapchainCreateInfoKHR-compositeAlpha-01280]]
    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
  * [[VUID-VkSwapchainCreateInfoKHR-presentMode-01281]]
    pname:presentMode must: be one of the elink:VkPresentModeKHR values
    returned by fname:vkGetPhysicalDeviceSurfacePresentModesKHR for the
    surface
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
  * [[VUID-VkSwapchainCreateInfoKHR-physicalDeviceCount-01429]]
    If the logical device was created with
    slink:VkDeviceGroupDeviceCreateInfo::pname:physicalDeviceCount equal to
    1, pname:flags must: not contain
    ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
endif::VK_VERSION_1_1,VK_KHR_device_group[]
  * [[VUID-VkSwapchainCreateInfoKHR-oldSwapchain-01933]]
    If pname:oldSwapchain is not dlink:VK_NULL_HANDLE, pname:oldSwapchain
    must: be a non-retired swapchain associated with native window referred
    to by pname:surface
  * [[VUID-VkSwapchainCreateInfoKHR-imageFormat-01778]]
    The <<swapchain-wsi-image-create-info, implied image creation
    parameters>> of the swapchain must: be supported as reported by
    flink:vkGetPhysicalDeviceImageFormatProperties
ifdef::VK_KHR_swapchain_mutable_format[]
  * [[VUID-VkSwapchainCreateInfoKHR-flags-03168]]
    If pname:flags contains ename:VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
    then the pname:pNext chain must: include a
    slink:VkImageFormatListCreateInfo structure with a pname:viewFormatCount
    greater than zero and pname:pViewFormats must: have an element equal to
    pname:imageFormat
  * [[VUID-VkSwapchainCreateInfoKHR-pNext-04099]]
    If a slink:VkImageFormatListCreateInfo structure was included in the
    pname:pNext chain and
    slink:VkImageFormatListCreateInfo::pname:viewFormatCount is not zero
    then all of the formats in
    slink:VkImageFormatListCreateInfo::pname:pViewFormats must: be
    compatible with the pname:format as described in the
    <<formats-compatibility,compatibility table>>
  * [[VUID-VkSwapchainCreateInfoKHR-flags-04100]]
    If pname:flags does not contain
    ename:VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR and the pname:pNext
    chain include a slink:VkImageFormatListCreateInfo structure then
    slink:VkImageFormatListCreateInfo::pname:viewFormatCount must: be `0` or
    `1`
endif::VK_KHR_swapchain_mutable_format[]
ifdef::VK_KHR_surface_protected_capabilities[]
  * [[VUID-VkSwapchainCreateInfoKHR-flags-03187]]
    If pname:flags contains ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR,
    then sname:VkSurfaceProtectedCapabilitiesKHR::pname:supportsProtected
    must: be ename:VK_TRUE in the slink:VkSurfaceProtectedCapabilitiesKHR
    structure returned by flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR
    for pname:surface
endif::VK_KHR_surface_protected_capabilities[]
ifdef::VK_EXT_full_screen_exclusive+VK_KHR_win32_surface[]
  * [[VUID-VkSwapchainCreateInfoKHR-pNext-02679]]
    If the pname:pNext chain includes a
    slink:VkSurfaceFullScreenExclusiveInfoEXT structure with its
    pname:fullScreenExclusive member set to
    ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, and
    pname:surface was created using flink:vkCreateWin32SurfaceKHR, a
    slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure must: be
    included in the pname:pNext chain
endif::VK_EXT_full_screen_exclusive+VK_KHR_win32_surface[]
****

include::{generated}/validity/structs/VkSwapchainCreateInfoKHR.txt[]
--

[open,refpage='VkSwapchainCreateFlagBitsKHR',desc='Bitmask controlling swapchain creation',type='enums']
--
Bits which can: be set in slink:VkSwapchainCreateInfoKHR::pname:flags,
specifying parameters of swapchain creation, are:

include::{generated}/api/enums/VkSwapchainCreateFlagBitsKHR.txt[]

ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
  * ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR specifies
    that images created from the swapchain (i.e. with the pname:swapchain
    member of slink:VkImageSwapchainCreateInfoKHR set to this swapchain's
    handle) must: use ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT.
endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1[]
  * ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR specifies that images
    created from the swapchain are protected images.
endif::VK_VERSION_1_1[]
ifdef::VK_KHR_swapchain_mutable_format[]
  * ename:VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR specifies that the
    images of the swapchain can: be used to create a sname:VkImageView with
    a different format than what the swapchain was created with.
    The list of allowed image view formats is specified by adding a
    slink:VkImageFormatListCreateInfo structure to the pname:pNext chain of
    slink:VkSwapchainCreateInfoKHR.
    In addition, this flag also specifies that the swapchain can: be created
    with usage flags that are not supported for the format the swapchain is
    created with but are supported for at least one of the allowed image
    view formats.
endif::VK_KHR_swapchain_mutable_format[]
--

[open,refpage='VkSwapchainCreateFlagsKHR',desc='Bitmask of VkSwapchainCreateFlagBitsKHR',type='flags']
--
include::{generated}/api/flags/VkSwapchainCreateFlagsKHR.txt[]

tname:VkSwapchainCreateFlagsKHR is a bitmask type for setting a mask of zero
or more elink:VkSwapchainCreateFlagBitsKHR.
--

ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='VkDeviceGroupSwapchainCreateInfoKHR',desc='Structure specifying parameters of a newly created swapchain object',type='structs']
--
If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a
sname:VkDeviceGroupSwapchainCreateInfoKHR structure, then that structure
includes a set of device group present modes that the swapchain can: be used
with.

The sname:VkDeviceGroupSwapchainCreateInfoKHR structure is defined as:

include::{generated}/api/structs/VkDeviceGroupSwapchainCreateInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:modes is a bitfield of modes that the swapchain can: be used with.

If this structure is not present, pname:modes is considered to be
ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.

include::{generated}/validity/structs/VkDeviceGroupSwapchainCreateInfoKHR.txt[]
--
endif::VK_VERSION_1_1,VK_KHR_device_group[]

ifdef::VK_AMD_display_native_hdr[]
[open,refpage='VkSwapchainDisplayNativeHdrCreateInfoAMD',desc='Structure specifying display native HDR parameters of a newly created swapchain object',type='structs']
--
If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a
sname:VkSwapchainDisplayNativeHdrCreateInfoAMD structure, then that
structure includes additional swapchain creation parameters specific to
display native HDR support.

The sname:VkSwapchainDisplayNativeHdrCreateInfoAMD structure is defined as:

include::{generated}/api/structs/VkSwapchainDisplayNativeHdrCreateInfoAMD.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:localDimmingEnable specifies whether local dimming is enabled for
    the swapchain.

If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR does not include
this structure, the default value for pname:localDimmingEnable is
ename:VK_TRUE, meaning local dimming is initially enabled for the swapchain.

include::{generated}/validity/structs/VkSwapchainDisplayNativeHdrCreateInfoAMD.txt[]

.Valid Usage
****
  * [[VUID-VkSwapchainDisplayNativeHdrCreateInfoAMD-localDimmingEnable-04449]]
    It is only valid to set pname:localDimmingEnable to ename:VK_TRUE if
    slink:VkDisplayNativeHdrSurfaceCapabilitiesAMD::pname:localDimmingSupport
    is supported
****
--

[open,refpage='vkSetLocalDimmingAMD',desc='Set Local Dimming',type='protos']
--
The local dimming HDR setting may also be changed over the life of a
swapchain by calling:

include::{generated}/api/protos/vkSetLocalDimmingAMD.txt[]

  * pname:device is the device associated with pname:swapChain.
  * pname:swapChain handle to enable local dimming.
  * pname:localDimmingEnable specifies whether local dimming is enabled for
    the swapchain.

include::{generated}/validity/protos/vkSetLocalDimmingAMD.txt[]

.Valid Usage
****
  * [[VUID-vkSetLocalDimmingAMD-localDimmingSupport-04618]]
    slink:VkDisplayNativeHdrSurfaceCapabilitiesAMD::pname:localDimmingSupport
    must: be supported
****
--
endif::VK_AMD_display_native_hdr[]

ifdef::VK_EXT_full_screen_exclusive[]
--

If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a
slink:VkSurfaceFullScreenExclusiveInfoEXT structure, then that structure
specifies the application's preferred full-screen presentation behavior.
If this structure is not present, pname:fullScreenExclusive is considered to
be ename:VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT.

--

endif::VK_EXT_full_screen_exclusive[]

ifdef::VK_EXT_display_control[]
include::{chapters}/VK_EXT_display_control/swapchain_counters.txt[]
endif::VK_EXT_display_control[]

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

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

[[swapchain-wsi-image-create-info]]
[options="header"]
|====
| sname:VkImageCreateInfo Field | Value
ifndef::VK_VERSION_1_1,VK_KHR_device_group,VK_KHR_swapchain_mutable_format[]
| pname:flags                   | 0
endif::VK_VERSION_1_1,VK_KHR_device_group,VK_KHR_swapchain_mutable_format[]
ifdef::VK_VERSION_1_1,VK_KHR_device_group,VK_KHR_swapchain_mutable_format[]
| pname:flags                   |
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT is set if
ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR is set

endif::VK_VERSION_1_1,VK_KHR_device_group[]
ifdef::VK_VERSION_1_1[]
ename:VK_IMAGE_CREATE_PROTECTED_BIT is set if
ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR is set

endif::VK_VERSION_1_1[]
ifdef::VK_KHR_swapchain_mutable_format[]
ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT and
ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR are both set if
ename:VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR is set

endif::VK_KHR_swapchain_mutable_format[]
all other bits are unset
endif::VK_VERSION_1_1,VK_KHR_device_group,VK_KHR_swapchain_mutable_format[]
| pname:imageType               | ename:VK_IMAGE_TYPE_2D
| pname:format                  | pname:pCreateInfo->imageFormat
| pname:extent                  | {pname:pCreateInfo->imageExtent.width, pname:pCreateInfo->imageExtent.height, `1`}
| pname:mipLevels               | 1
| pname:arrayLayers             | pname:pCreateInfo->imageArrayLayers
| pname:samples                 | ename:VK_SAMPLE_COUNT_1_BIT
| pname:tiling                  | ename:VK_IMAGE_TILING_OPTIMAL
| pname:usage                   | pname:pCreateInfo->imageUsage
| pname:sharingMode             | pname:pCreateInfo->imageSharingMode
| pname:queueFamilyIndexCount   | pname:pCreateInfo->queueFamilyIndexCount
| pname:pQueueFamilyIndices     | pname:pCreateInfo->pQueueFamilyIndices
| pname:initialLayout           | ename:VK_IMAGE_LAYOUT_UNDEFINED
|====

The pname:surface must: not be destroyed until after the swapchain is
destroyed.

If pname:oldSwapchain is dlink:VK_NULL_HANDLE, and the native window
referred to by pname:surface is already associated with a Vulkan swapchain,
ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR must: be returned.

If the native window referred to by pname:surface is already associated with
a non-Vulkan graphics API surface, ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR
must: be returned.

The native window referred to by pname:surface must: not become associated
with a non-Vulkan graphics API surface before all associated Vulkan
swapchains have been destroyed.

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

[open,refpage='vkDestroySwapchainKHR',desc='Destroy a swapchain object',type='protos']
--
To destroy a swapchain object call:

include::{generated}/api/protos/vkDestroySwapchainKHR.txt[]

  * pname:device is the slink: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>>).

The application must: not destroy a swapchain until after completion of all
outstanding operations on images that were acquired from the swapchain.
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 presentation engine.
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::{chapters}/VK_KHR_display_swapchain/destroy_swapchain_interactions.txt[]
endif::VK_KHR_display_swapchain[]

ifdef::VK_EXT_full_screen_exclusive[]
If pname:swapchain has exclusive full-screen access, it is released before
the swapchain is destroyed.
endif::VK_EXT_full_screen_exclusive[]

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

include::{generated}/validity/protos/vkDestroySwapchainKHR.txt[]
--

ifdef::VK_KHR_display_swapchain[]
include::{chapters}/VK_KHR_display_swapchain/create_shared_swapchains.txt[]
endif::VK_KHR_display_swapchain[]

[open,refpage='vkGetSwapchainImagesKHR',desc='Obtain the array of presentable images associated with a swapchain',type='protos']
--
To obtain the array of presentable images associated with a swapchain, call:

include::{generated}/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 presentable 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, and ename:VK_INCOMPLETE will be returned instead
of ename:VK_SUCCESS, to indicate that not all the available presentable
images were returned.

include::{generated}/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.
====

Images returned by flink:vkGetSwapchainImagesKHR are fully backed by memory
before they are passed to the application.
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 applications must: not destroy a presentable image.
See flink:vkDestroySwapchainKHR for further details on the lifetime of
presentable images.

ifdef::VK_VERSION_1_1,VK_KHR_device_group[]

Images can: also be created by using flink:vkCreateImage with
slink:VkImageSwapchainCreateInfoKHR and bound to swapchain memory using
flink:vkBindImageMemory2KHR with slink:VkBindImageMemorySwapchainInfoKHR.
These images can: be used anywhere swapchain images are used, and are useful
in logical devices with multiple physical devices to create peer memory
bindings of swapchain memory.
These images and bindings have no effect on what memory is presented.
Unlike images retrieved from fname:vkGetSwapchainImagesKHR, these images
must: be destroyed with flink:vkDestroyImage.

endif::VK_VERSION_1_1,VK_KHR_device_group[]

[open,refpage='vkAcquireNextImageKHR',desc='Retrieve the index of the next available presentable image',type='protos']
--
To acquire an available presentable image to use, and retrieve the index of
that image, call:

include::{generated}/api/protos/vkAcquireNextImageKHR.txt[]

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

.Valid Usage
****
  * [[VUID-vkAcquireNextImageKHR-swapchain-01285]]
    pname:swapchain must: not be in the retired state
  * [[VUID-vkAcquireNextImageKHR-semaphore-01286]]
    If pname:semaphore is not dlink:VK_NULL_HANDLE it must: be unsignaled
  * [[VUID-vkAcquireNextImageKHR-semaphore-01779]]
    If pname:semaphore is not dlink:VK_NULL_HANDLE it must: not have any
    uncompleted signal or wait operations pending
  * [[VUID-vkAcquireNextImageKHR-fence-01287]]
    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
  * [[VUID-vkAcquireNextImageKHR-semaphore-01780]]
    pname:semaphore and pname:fence must: not both be equal to
    dlink:VK_NULL_HANDLE
  * [[VUID-vkAcquireNextImageKHR-swapchain-01802]]
    If the number of currently acquired images is greater than the
    difference between the number of images in pname:swapchain and the value
    of slink:VkSurfaceCapabilitiesKHR::pname:minImageCount as returned by a
    call to flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR with the
    pname:surface used to create pname:swapchain, pname:timeout must: not be
    code:UINT64_MAX
ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[]
  * [[VUID-vkAcquireNextImageKHR-semaphore-03265]]
    pname:semaphore must: have a elink:VkSemaphoreType of
    ename:VK_SEMAPHORE_TYPE_BINARY
endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[]
****

include::{generated}/validity/protos/vkAcquireNextImageKHR.txt[]
--

When successful, fname:vkAcquireNextImageKHR acquires a presentable image
from pname:swapchain that an application can: use, and sets
pname:pImageIndex to the index of that image within the swapchain.
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.
If pname:semaphore is not dlink:VK_NULL_HANDLE, the application may assume
that, once fname:vkAcquireNextImageKHR returns, the semaphore signal
operation referenced by pname:semaphore has been submitted for execution.
The order in which images are acquired is implementation-dependent, and may:
be different than the order the images were presented.

If pname:timeout is zero, then fname:vkAcquireNextImageKHR does not wait,
and will either successfully acquire an image, or fail and return
ename:VK_NOT_READY if no image is available.

If the specified timeout period expires before an image is acquired,
fname:vkAcquireNextImageKHR returns ename:VK_TIMEOUT.
If pname:timeout is code:UINT64_MAX, the timeout period is treated as
infinite, and fname:vkAcquireNextImageKHR will block until an image is
acquired or an error occurs.

fname:vkAcquireNextImageKHR should: not be called if the number of images
that the application has currently acquired is greater than the difference
between the number of images in pname:swapchain and the value of
slink:VkSurfaceCapabilitiesKHR::pname:minImageCount.
If fname:vkAcquireNextImageKHR is called when the number of images that the
application has currently acquired is less or equal than the difference
between the number of images in pname:swapchain and the value of
slink:VkSurfaceCapabilitiesKHR::pname:minImageCount,
fname:vkAcquireNextImageKHR must: return in finite time with an allowed
ename:VkResult code.

[NOTE]
.Note
====
Returning a result in finite time guarantees that the implementation cannot
deadlock an application, or suspend its execution indefinitely with correct
API usage.
Acquiring too many images at once may block indefinitely, which is covered
by valid usage when attempting to use code:UINT64_MAX.
For example, a scenario here is when a compositor holds on to images which
are currently being presented, and there are not any vacant images left to
be acquired.
====

If an image is acquired successfully, fname:vkAcquireNextImageKHR must:
either return ename:VK_SUCCESS or ename:VK_SUBOPTIMAL_KHR.
The implementation may: return ename:VK_SUBOPTIMAL_KHR if the swapchain no
longer matches the surface properties exactly, but can: still be used for
presentation.

[NOTE]
.Note
====
ename:VK_SUBOPTIMAL_KHR 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 the application to decide whether it prefers to continue using
the current swapchain in this state, or to re-create the swapchain to better
match the platform surface properties.
====

If the swapchain images no longer match native surface properties, either
ename:VK_SUBOPTIMAL_KHR or ename:VK_ERROR_OUT_OF_DATE_KHR must: be returned.
If ename:VK_ERROR_OUT_OF_DATE_KHR is returned, no image is acquired and
attempts to present previously acquired images to the swapchain will also
fail with ename:VK_ERROR_OUT_OF_DATE_KHR.
Applications need to create a new swapchain for the surface to continue
presenting if ename:VK_ERROR_OUT_OF_DATE_KHR is returned.

If device loss occurs (see <<devsandqueues-lost-device,Lost Device>>) before
the timeout has expired, fname:vkAcquireNextImageKHR must: return in finite
time with either one of the allowed success codes, or
ename:VK_ERROR_DEVICE_LOST.

If pname:semaphore is not dlink:VK_NULL_HANDLE, the semaphore must: be
unsignaled, with no signal or wait operations pending.
It will become signaled when the application can: use the image.

[NOTE]
.Note
====
Use of pname: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 dlink:VK_NULL_HANDLE, the fence must: be
unsignaled, with no signal operations pending.
It will become signaled when the application can: use the image.

[NOTE]
.Note
====
Applications should: not rely on fname:vkAcquireNextImageKHR blocking in
order to meter their rendering speed.
The implementation may: return from this function immediately regardless of
how many presentation requests are queued, and regardless of when queued
presentation requests will complete relative to the call.
Instead, applications can: use pname:fence to meter their frame generation
work to match the presentation rate.
====

An application must: wait until either the pname:semaphore or pname:fence is
signaled before accessing the image's data.

[NOTE]
.Note
====
When the presentable image will be accessed by some stage [eq]#S#, the
recommended idiom for ensuring correct synchronization is:

  * The slink:VkSubmitInfo used to submit the image layout transition for
    execution includes fname:vkAcquireNextImageKHR::pname:semaphore in its
    pname:pWaitSemaphores member, with the corresponding element of
    pname:pWaitDstStageMask including [eq]#S#.
  * The <<synchronization, synchronization command>> that performs any
    necessary image layout transition includes [eq]#S# in both the
    pname:srcStageMask and pname:dstStageMask.
====

After a successful return, the image indicated by pname:pImageIndex and its
data will be unmodified compared to when it was presented.

[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 is returned 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 code: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 the application to decide whether it prefers 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, the mapping from the presented image to the
native surface is implementation-defined.
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.

[NOTE]
.Note
====
For example, consider a 4x3 window/surface that gets resized to be 3x4
(taller than wider).
On some window systems, the portion of the window/surface that was
previously and still is visible (the 3x3 part) will contain the same
contents as before, while the remaining parts of the window will have
undefined: contents.
Other window systems may: squash/stretch the image to fill the new window
size without any undefined: contents, or apply some other mapping.
====

ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='vkAcquireNextImage2KHR',desc='Retrieve the index of the next available presentable image',type='protos']
--
To acquire an available presentable image to use, and retrieve the index of
that image, call:

include::{generated}/api/protos/vkAcquireNextImage2KHR.txt[]

  * pname:device is the device associated with pname:swapchain.
  * pname:pAcquireInfo is a pointer to a slink:VkAcquireNextImageInfoKHR
    structure containing parameters of the acquire.
  * pname:pImageIndex is a pointer to a code:uint32_t that is set to the
    index of the next image to use.

.Valid Usage
****
  * [[VUID-vkAcquireNextImage2KHR-swapchain-01803]]
    If the number of currently acquired images is greater than the
    difference between the number of images in the pname:swapchain member of
    pname:pAcquireInfo and the value of
    slink:VkSurfaceCapabilitiesKHR::pname:minImageCount as returned by a
    call to flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR with the
    pname:surface used to create pname:swapchain, the pname:timeout member
    of pname:pAcquireInfo must: not be code:UINT64_MAX
****

include::{generated}/validity/protos/vkAcquireNextImage2KHR.txt[]
--

[open,refpage='VkAcquireNextImageInfoKHR',desc='Structure specifying parameters of the acquire',type='structs']
--
The sname:VkAcquireNextImageInfoKHR structure is defined as:

include::{generated}/api/structs/VkAcquireNextImageInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:swapchain is a non-retired swapchain from which an image is
    acquired.
  * pname:timeout specifies how long the function waits, in nanoseconds, if
    no image is available.
  * pname:semaphore is dlink:VK_NULL_HANDLE or a semaphore to signal.
  * pname:fence is dlink:VK_NULL_HANDLE or a fence to signal.
  * pname:deviceMask is a mask of physical devices for which the swapchain
    image will be ready to use when the semaphore or fence is signaled.

If flink:vkAcquireNextImageKHR is used, the device mask is considered to
include all physical devices in the logical device.

[NOTE]
.Note
====
flink:vkAcquireNextImage2KHR signals at most one semaphore, even if the
application requests waiting for multiple physical devices to be ready via
the pname:deviceMask.
However, only a single physical device can: wait on that semaphore, since
the semaphore becomes unsignaled when the wait succeeds.
For other physical devices to wait for the image to be ready, it is
necessary for the application to submit semaphore signal operation(s) to
that first physical device to signal additional semaphore(s) after the wait
succeeds, which the other physical device(s) can: wait upon.
====

.Valid Usage
****
  * [[VUID-VkAcquireNextImageInfoKHR-swapchain-01675]]
    pname:swapchain must: not be in the retired state
  * [[VUID-VkAcquireNextImageInfoKHR-semaphore-01288]]
    If pname:semaphore is not dlink:VK_NULL_HANDLE it must: be unsignaled
  * [[VUID-VkAcquireNextImageInfoKHR-semaphore-01781]]
    If pname:semaphore is not dlink:VK_NULL_HANDLE it must: not have any
    uncompleted signal or wait operations pending
  * [[VUID-VkAcquireNextImageInfoKHR-fence-01289]]
    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
  * [[VUID-VkAcquireNextImageInfoKHR-semaphore-01782]]
    pname:semaphore and pname:fence must: not both be equal to
    dlink:VK_NULL_HANDLE
  * [[VUID-VkAcquireNextImageInfoKHR-deviceMask-01290]]
    pname:deviceMask must: be a valid device mask
  * [[VUID-VkAcquireNextImageInfoKHR-deviceMask-01291]]
    pname:deviceMask must: not be zero
ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[]
  * [[VUID-VkAcquireNextImageInfoKHR-semaphore-03266]]
    pname:semaphore must: have a elink:VkSemaphoreType of
    ename:VK_SEMAPHORE_TYPE_BINARY
endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[]
****

include::{generated}/validity/structs/VkAcquireNextImageInfoKHR.txt[]
--
endif::VK_VERSION_1_1,VK_KHR_device_group[]

[open,refpage='vkQueuePresentKHR',desc='Queue an image for presentation',type='protos']
--
After queueing all rendering commands and transitioning the image to the
correct layout, to queue an image for presentation, call:

include::{generated}/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 a slink:VkPresentInfoKHR structure
    specifying parameters of the presentation.

.Note
[NOTE]
====
There is no requirement for an application to present images in the same
order that they were acquired - applications can arbitrarily present any
image that is currently acquired.
====

.Valid Usage
****
  * [[VUID-vkQueuePresentKHR-pSwapchains-01292]]
    Each 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[]
  * [[VUID-vkQueuePresentKHR-pSwapchains-01293]]
    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[]
  * [[VUID-vkQueuePresentKHR-pWaitSemaphores-01294]]
    When a semaphore wait operation referring to a binary semaphore defined
    by the elements of the pname:pWaitSemaphores member of
    pname:pPresentInfo executes on pname:queue, there must: be no other
    queues waiting on the same semaphore
  * [[VUID-vkQueuePresentKHR-pWaitSemaphores-01295]]
    All elements of the pname:pWaitSemaphores member of pname:pPresentInfo
    must: be semaphores that are signaled, or have
    <<synchronization-semaphores-signaling, semaphore signal operations>>
    previously submitted for execution
ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[]
  * [[VUID-vkQueuePresentKHR-pWaitSemaphores-03267]]
    All elements of the pname:pWaitSemaphores member of pname:pPresentInfo
    must: be created with a elink:VkSemaphoreType of
    ename:VK_SEMAPHORE_TYPE_BINARY
  * [[VUID-vkQueuePresentKHR-pWaitSemaphores-03268]]
    All elements of the pname:pWaitSemaphores member of pname:pPresentInfo
    must: reference a semaphore signal operation that has been submitted for
    execution and any semaphore signal operations on which it depends (if
    any) must: have also been submitted for execution
endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[]
****

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.

Queueing an image for presentation defines a set of _queue operations_,
including waiting on the semaphores and submitting a presentation request to
the presentation engine.
However, the scope of this set of queue operations does not include the
actual processing of the image by the presentation engine.

.Note
[NOTE]
====
The origin of the native orientation of the surface coordinate system is not
specified in the Vulkan specification; it depends on the platform.
For most platforms the origin is by default upper-left, meaning the pixel of
the presented slink:VkImage at coordinates [eq]#(0,0)# would appear at the
upper left pixel of the platform surface (assuming
ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, and the display standing the
right way up).
====

If fname:vkQueuePresentKHR fails to enqueue the corresponding set of queue
operations, it may: return ename:VK_ERROR_OUT_OF_HOST_MEMORY or
ename:VK_ERROR_OUT_OF_DEVICE_MEMORY.
If it does, the implementation must: ensure that the state and contents of
any resources or synchronization primitives referenced is unaffected by the
call or its failure.

If fname:vkQueuePresentKHR fails in such a way that the implementation is
unable to make that guarantee, the implementation must: return
ename:VK_ERROR_DEVICE_LOST.

However, if the presentation request is rejected by the presentation engine
with an error ename:VK_ERROR_OUT_OF_DATE_KHR,
ifdef::VK_EXT_full_screen_exclusive[]
ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT,
endif::VK_EXT_full_screen_exclusive[]
or ename:VK_ERROR_SURFACE_LOST_KHR, the set of queue operations are still
considered to be enqueued and thus any semaphore wait operation specified in
slink:VkPresentInfoKHR will execute when the corresponding queue operation
is complete.

Calls to fname:vkQueuePresentKHR may: block, but must: return in finite
time.

ifdef::VK_EXT_full_screen_exclusive[]
If any pname:swapchain member of pname:pPresentInfo was created with
ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT,
ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT will be returned if that
swapchain does not have exclusive full-screen access, possibly for
implementation-specific reasons outside of the application's control.
endif::VK_EXT_full_screen_exclusive[]

include::{generated}/validity/protos/vkQueuePresentKHR.txt[]
--

[open,refpage='VkPresentInfoKHR',desc='Structure describing parameters of a queue presentation',type='structs']
--
The sname:VkPresentInfoKHR structure is defined as:

include::{generated}/api/structs/VkPresentInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:waitSemaphoreCount is the number of semaphores to wait for before
    issuing the present request.
    The number may: be zero.
  * pname:pWaitSemaphores is `NULL` or a pointer to an array of
    slink: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 a pointer to an array of slink:VkSwapchainKHR
    objects with pname:swapchainCount entries.
    A given swapchain must: not appear in this list more than once.
  * pname:pImageIndices is a pointer to 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 a pointer to an array of elink: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
    elink:VkResult for presenting the swapchain corresponding to the same
    index in pname:pSwapchains.

Before an application can: present an image, the image's layout must: be
transitioned to the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
ifdef::VK_KHR_shared_presentable_image[]
layout, or for a shared presentable image the
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
endif::VK_KHR_shared_presentable_image[]
layout.

.Note
[NOTE]
====
When transitioning the image to
ifdef::VK_KHR_shared_presentable_image[]
ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or
endif::VK_KHR_shared_presentable_image[]
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.
====

.Valid Usage
****
ifndef::VK_KHR_shared_presentable_image[]
  * [[VUID-VkPresentInfoKHR-pImageIndices-01296]]
    Each 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
endif::VK_KHR_shared_presentable_image[]
ifdef::VK_KHR_shared_presentable_image[]
  * [[VUID-VkPresentInfoKHR-pImageIndices-01430]]
    Each 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 or
    ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR layout at the time the
    operation is executed on a sname:VkDevice
endif::VK_KHR_shared_presentable_image[]
ifdef::VK_KHR_present_id[]
  * [[VUID-VkPresentInfoKHR-pNext-06235]]
    If a slink:VkPresentIdKHR structure is included in the pname:pNext
    chain, and the <<features-presentId, pname:presentId>> feature is not
    enabled, each pname:presentIds entry in that structure must: be NULL
endif::VK_KHR_present_id[]
****

include::{generated}/validity/structs/VkPresentInfoKHR.txt[]
--

ifdef::VK_KHR_incremental_present[]
include::{chapters}/VK_KHR_incremental_present/wsi.txt[]
endif::VK_KHR_incremental_present[]

ifdef::VK_KHR_display_swapchain[]
include::{chapters}/VK_KHR_display_swapchain/display_swapchain_present.txt[]
endif::VK_KHR_display_swapchain[]

ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
[open,refpage='VkDeviceGroupPresentInfoKHR',desc='Mode and mask controlling which physical devices\' images are presented',type='structs']
--
If the pname:pNext chain of slink:VkPresentInfoKHR includes a
sname:VkDeviceGroupPresentInfoKHR structure, then that structure includes an
array of device masks and a device group present mode.

The sname:VkDeviceGroupPresentInfoKHR structure is defined as:

include::{generated}/api/structs/VkDeviceGroupPresentInfoKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:swapchainCount is zero or the number of elements in
    pname:pDeviceMasks.
  * pname:pDeviceMasks is a pointer to an array of device masks, one for
    each element of slink:VkPresentInfoKHR::pSwapchains.
  * pname:mode is a elink:VkDeviceGroupPresentModeFlagBitsKHR value
    specifying the device group present mode that will be used for this
    present.

If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then each
element of pname:pDeviceMasks selects which instance of the swapchain image
is presented.
Each element of pname:pDeviceMasks must: have exactly one bit set, and the
corresponding physical device must: have a presentation engine as reported
by slink:VkDeviceGroupPresentCapabilitiesKHR.

If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, then
each element of pname:pDeviceMasks selects which instance of the swapchain
image is presented.
Each element of pname:pDeviceMasks must: have exactly one bit set, and some
physical device in the logical device must: include that bit in its
slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask.

If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then each
element of pname:pDeviceMasks selects which instances of the swapchain image
are component-wise summed and the sum of those images is presented.
If the sum in any component is outside the representable range, the value of
that component is undefined:.
Each element of pname:pDeviceMasks must: have a value for which all set bits
are set in one of the elements of
slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask.

If pname:mode is
ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then each
element of pname:pDeviceMasks selects which instance(s) of the swapchain
images are presented.
For each bit set in each element of pname:pDeviceMasks, the corresponding
physical device must: have a presentation engine as reported by
slink:VkDeviceGroupPresentCapabilitiesKHR.

If sname:VkDeviceGroupPresentInfoKHR is not provided or pname:swapchainCount
is zero then the masks are considered to be `1`.
If sname:VkDeviceGroupPresentInfoKHR is not provided, pname:mode is
considered to be ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.

.Valid Usage
****
  * [[VUID-VkDeviceGroupPresentInfoKHR-swapchainCount-01297]]
    pname:swapchainCount must: equal `0` or
    slink:VkPresentInfoKHR::pname:swapchainCount
  * [[VUID-VkDeviceGroupPresentInfoKHR-mode-01298]]
    If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then
    each element of pname:pDeviceMasks must: have exactly one bit set, and
    the corresponding element of
    slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask must: be
    non-zero
  * [[VUID-VkDeviceGroupPresentInfoKHR-mode-01299]]
    If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, then
    each element of pname:pDeviceMasks must: have exactly one bit set, and
    some physical device in the logical device must: include that bit in its
    slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask
  * [[VUID-VkDeviceGroupPresentInfoKHR-mode-01300]]
    If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then
    each element of pname:pDeviceMasks must: have a value for which all set
    bits are set in one of the elements of
    slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask
  * [[VUID-VkDeviceGroupPresentInfoKHR-mode-01301]]
    If pname:mode is
    ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then for
    each bit set in each element of pname:pDeviceMasks, the corresponding
    element of slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask
    must: be non-zero
  * [[VUID-VkDeviceGroupPresentInfoKHR-pDeviceMasks-01302]]
    The value of each element of pname:pDeviceMasks must: be equal to the
    device mask passed in slink:VkAcquireNextImageInfoKHR::pname:deviceMask
    when the image index was last acquired
  * [[VUID-VkDeviceGroupPresentInfoKHR-mode-01303]]
    pname:mode must: have exactly one bit set, and that bit must: have been
    included in slink:VkDeviceGroupSwapchainCreateInfoKHR::pname:modes
****

include::{generated}/validity/structs/VkDeviceGroupPresentInfoKHR.txt[]
--
endif::VK_VERSION_1_1,VK_KHR_device_group[]

ifdef::VK_GOOGLE_display_timing[]
include::{chapters}/VK_GOOGLE_display_timing/PresentTimeInfo.txt[]
endif::VK_GOOGLE_display_timing[]
ifdef::VK_KHR_present_id[]
include::PresentId.txt[]
endif::VK_KHR_present_id[]

ifdef::VK_GGP_frame_token[]
include::{chapters}/VK_GGP_frame_token.txt[]
endif::VK_GGP_frame_token[]

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
<<resources-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::{chapters}/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.
ifdef::VK_EXT_full_screen_exclusive[]
  * If any of the presents would have a result of
    ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT if issued separately
    then ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT is returned.
endif::VK_EXT_full_screen_exclusive[]
  * 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:.

[NOTE]
.Note
====
The application can: continue to present any acquired images from a retired
swapchain as long as the swapchain has not entered a state that causes
flink:vkQueuePresentKHR to return ename:VK_ERROR_OUT_OF_DATE_KHR.
====

ifdef::VK_EXT_hdr_metadata[]
include::{chapters}/VK_EXT_hdr_metadata.txt[]
endif::VK_EXT_hdr_metadata[]