1101 lines
50 KiB
Plaintext
1101 lines
50 KiB
Plaintext
// Copyright (c) 2014-2017 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
== WSI Swapchain
|
|
|
|
// refBegin VkSwapchainKHR - Opaque handle to a swapchain object
|
|
|
|
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::../../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 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.
|
|
====
|
|
|
|
// refEnd VkSwapchainKHR
|
|
|
|
How this all works is described below.
|
|
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
include::../VK_KHR_shared_presentable_image/wsi.txt[]
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
|
|
// 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 a bitmask of elink:VkSwapchainCreateFlagBitsKHR
|
|
indicating parameters of swapchain creation.
|
|
* 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 dlink: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 dlink: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.
|
|
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 fname:vkGetPhysicalDeviceSurfaceSupportKHR
|
|
* [[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 fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR
|
|
for the surface
|
|
* [[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-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-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
|
|
* [[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
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
if pname:presentMode is set to 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
|
|
* [[VUID-VkSwapchainCreateInfoKHR-imageUsage-01384]]
|
|
pname:imageUsage must: be a subset of the supported usage flags present
|
|
in the pname:sharedPresentSupportedUsageFlags member of the
|
|
sname:VkSharedPresentSurfaceCapabilitiesKHR structure returned by
|
|
fname:vkGetPhysicalDeviceSurfaceCapabilities2KHR for the surface if
|
|
pname:presentMode is set to 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-imageSharingMode-01277]]
|
|
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
|
|
* [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01278]]
|
|
If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT,
|
|
pname:queueFamilyIndexCount must: be greater than `1`
|
|
* [[VUID-VkSwapchainCreateInfoKHR-sharingMode-01393]]
|
|
If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element
|
|
of pname:pQueueFamilyIndices must: be unique and must: be less than
|
|
pname:pQueueFamilyPropertyCount returned by
|
|
ifndef::VK_KHR_get_physical_device_properties2[]
|
|
flink:vkGetPhysicalDeviceQueueFamilyProperties
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
ifdef::VK_KHR_get_physical_device_properties2[]
|
|
either flink:vkGetPhysicalDeviceQueueFamilyProperties or
|
|
flink:vkGetPhysicalDeviceQueueFamilyProperties2KHR
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
for the pname:physicalDevice that was used to create pname:device
|
|
* [[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
|
|
****
|
|
|
|
include::../../validity/structs/VkSwapchainCreateInfoKHR.txt[]
|
|
|
|
// refBegin VkSwapchainCreateFlagBitsKHR Bitmask controlling swapchain creation
|
|
|
|
Bits which can: be set in slink:VkSwapchainCreateInfoKHR::pname:flags,
|
|
specifying parameters of swapchain creation, are:
|
|
|
|
include::../../api/enums/VkSwapchainCreateFlagBitsKHR.txt[]
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
* ename:VK_SWAPCHAIN_CREATE_BIND_SFR_BIT_KHX specifies that images created
|
|
from the swapchain (i.e. with the pname:swapchain member of
|
|
slink:VkImageSwapchainCreateInfoKHX set to this swapchain's handle)
|
|
must: use ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX.
|
|
endif::VK_KHX_device_group[]
|
|
|
|
// refEnd VkSwapchainCreateFlagBitsKHR
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
// refBegin VkDeviceGroupSwapchainCreateInfoKHX Structure specifying parameters of a newly created swapchain object
|
|
|
|
If the pname:pNext list of slink:VkSwapchainCreateInfoKHR includes a
|
|
sname:VkDeviceGroupSwapchainCreateInfoKHX structure, then that structure
|
|
includes a set of device group present modes that the swapchain can: be used
|
|
with.
|
|
|
|
The sname:VkDeviceGroupSwapchainCreateInfoKHX structure is defined as:
|
|
|
|
include::../../api/structs/VkDeviceGroupSwapchainCreateInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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_KHX.
|
|
|
|
include::../../validity/structs/VkDeviceGroupSwapchainCreateInfoKHX.txt[]
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
ifdef::VK_EXT_display_control[]
|
|
include::../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 that contains 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 sname:VkImageCreateInfo parameters:
|
|
|
|
[[swapchain-wsi-image-create-info]]
|
|
[options="header"]
|
|
|====
|
|
| sname:VkImageCreateInfo Field | Value
|
|
ifdef::VK_KHX_device_group[]
|
|
| pname:flags | ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX if ename:VK_SWAPCHAIN_CREATE_BIND_SFR_BIT_KHX is set, else 0
|
|
endif::VK_KHX_device_group[]
|
|
ifndef::VK_KHX_device_group[]
|
|
| pname:flags | 0
|
|
endif::VK_KHX_device_group[]
|
|
| 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
|
|
****
|
|
* [[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::../../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 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.
|
|
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.
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
Images can: also be created by using flink:vkCreateImage with
|
|
slink:VkImageSwapchainCreateInfoKHX and bound to swapchain memory using
|
|
flink:vkBindImageMemory2KHX with slink:VkBindImageMemorySwapchainInfoKHX.
|
|
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_KHX_device_group[]
|
|
|
|
// 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 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 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
|
|
****
|
|
* [[VUID-vkAcquireNextImageKHR-swapchain-01285]]
|
|
pname:swapchain must: not have been replaced by being passed as the
|
|
sname:VkSwapchainCreateInfoKHR::pname:oldSwapchain value to
|
|
fname:vkCreateSwapchainKHR
|
|
* [[VUID-vkAcquireNextImageKHR-semaphore-01286]]
|
|
If pname:semaphore is not dlink:VK_NULL_HANDLE it must: be unsignaled
|
|
* [[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
|
|
****
|
|
|
|
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 elink: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 dlink: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 dlink: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
|
|
dlink: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 presentable 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
|
|
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.
|
|
====
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
// refBegin vkAcquireNextImage2KHX 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/vkAcquireNextImage2KHX.txt[]
|
|
|
|
* pname:device is the device associated with pname:swapchain.
|
|
* pname:pAcquireInfo is a pointer to a structure of type
|
|
slink:VkAcquireNextImageInfoKHX 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.
|
|
|
|
include::../../validity/protos/vkAcquireNextImage2KHX.txt[]
|
|
|
|
// refBegin VkAcquireNextImageInfoKHX Structure specifying parameters of the acquire
|
|
|
|
The sname:VkAcquireNextImageInfoKHX structure is defined as:
|
|
|
|
include::../../api/structs/VkAcquireNextImageInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* 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: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:vkAcquireNextImage2KHX 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-VkAcquireNextImageInfoKHX-semaphore-01288]]
|
|
If pname:semaphore is not dlink:VK_NULL_HANDLE it must: be unsignaled
|
|
* [[VUID-VkAcquireNextImageInfoKHX-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-VkAcquireNextImageInfoKHX-deviceMask-01290]]
|
|
pname:deviceMask must: be a valid device mask
|
|
* [[VUID-VkAcquireNextImageInfoKHX-deviceMask-01291]]
|
|
pname:deviceMask must: not be zero
|
|
****
|
|
|
|
include::../../validity/structs/VkAcquireNextImageInfoKHX.txt[]
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
// 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
|
|
****
|
|
* [[VUID-vkQueuePresentKHR-pSwapchains-01292]]
|
|
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[]
|
|
* [[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 unsignal operation defined by the elements of the
|
|
pname:pWaitSemaphores member of pname:pPresentInfo executes on
|
|
pname:queue, no other queue must: be 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.
|
|
****
|
|
|
|
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 `NULL`, 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 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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkPresentInfoKHR-pImageIndices-01296]]
|
|
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
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
layout at the time the operation is executed on a sname:VkDevice
|
|
****
|
|
|
|
include::../../validity/structs/VkPresentInfoKHR.txt[]
|
|
|
|
ifdef::VK_KHR_incremental_present[]
|
|
include::../VK_KHR_incremental_present/wsi.txt[]
|
|
endif::VK_KHR_incremental_present[]
|
|
|
|
ifdef::VK_KHR_display_swapchain[]
|
|
include::../VK_KHR_display_swapchain/display_swapchain_present.txt[]
|
|
endif::VK_KHR_display_swapchain[]
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
// refBegin VkDeviceGroupPresentInfoKHX Mode and mask controlling which physical devices' images are presented
|
|
|
|
If the pname:pNext list of slink:VkPresentInfoKHR includes a
|
|
sname:VkDeviceGroupPresentInfoKHX structure, then that structure includes an
|
|
array of device masks and a device group present mode.
|
|
|
|
The sname:VkDeviceGroupPresentInfoKHX structure is defined as:
|
|
|
|
include::../../api/structs/VkDeviceGroupPresentInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:swapchainCount is zero or the number of elements in
|
|
pname:pDeviceMasks.
|
|
* pname:pDeviceMasks is an array of device masks, one for each element of
|
|
slink:VkPresentInfoKHR::pSwapchains.
|
|
* pname:mode is the device group present mode that will be used for this
|
|
present.
|
|
|
|
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX, 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:VkDeviceGroupPresentCapabilitiesKHX.
|
|
|
|
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHX, 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:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask.
|
|
|
|
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHX, 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:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask.
|
|
|
|
If pname:mode is
|
|
ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHX, 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:VkDeviceGroupPresentCapabilitiesKHX.
|
|
|
|
If sname:VkDeviceGroupPresentInfoKHX is not provided or pname:swapchainCount
|
|
is zero then the masks are considered to be `1`.
|
|
If sname:VkDeviceGroupPresentInfoKHX is not provided, pname:mode is
|
|
considered to be ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkDeviceGroupPresentInfoKHX-swapchainCount-01297]]
|
|
pname:swapchainCount must: equal `0` or
|
|
slink:VkPresentInfoKHR::pname:swapchainCount
|
|
* [[VUID-VkDeviceGroupPresentInfoKHX-mode-01298]]
|
|
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHX, then
|
|
each element of pname:pDeviceMasks must: have exactly one bit set, and
|
|
the corresponding element of
|
|
slink:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask must: be
|
|
non-zero
|
|
* [[VUID-VkDeviceGroupPresentInfoKHX-mode-01299]]
|
|
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHX, 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:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask.
|
|
* [[VUID-VkDeviceGroupPresentInfoKHX-mode-01300]]
|
|
If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHX, then
|
|
each element of pname:pDeviceMasks must: have a value for which all set
|
|
bits are set in one of the elements of
|
|
slink:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask
|
|
* [[VUID-VkDeviceGroupPresentInfoKHX-mode-01301]]
|
|
If pname:mode is
|
|
ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHX, then for
|
|
each bit set in each element of pname:pDeviceMasks, the corresponding
|
|
element of slink:VkDeviceGroupPresentCapabilitiesKHX::pname:presentMask
|
|
must: be non-zero
|
|
* [[VUID-VkDeviceGroupPresentInfoKHX-pDeviceMasks-01302]]
|
|
The value of each element of pname:pDeviceMasks must: be equal to the
|
|
device mask passed in slink:VkAcquireNextImageInfoKHX::pname:deviceMask
|
|
when the image index was last acquired
|
|
* [[VUID-VkDeviceGroupPresentInfoKHX-mode-01303]]
|
|
pname:mode must: have exactly one bit set, and that bit must: have been
|
|
included in slink:VkDeviceGroupSwapchainCreateInfoKHX::pname:modes
|
|
****
|
|
|
|
include::../../validity/structs/VkDeviceGroupPresentInfoKHX.txt[]
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
ifdef::VK_GOOGLE_display_timing[]
|
|
include::../VK_GOOGLE_display_timing/PresentTimeInfo.txt[]
|
|
endif::VK_GOOGLE_display_timing[]
|
|
|
|
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::../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.
|
|
|
|
ifdef::VK_EXT_hdr_metadata[]
|
|
include::../VK_EXT_hdr_metadata.txt[]
|
|
endif::VK_EXT_hdr_metadata[]
|