VkSwapchainCreateFlagBitsKHR - Bitmask controlling swapchain creation

See Also

VkSwapchainCreateFlagsKHR

VkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modes

See Also

VkDeviceGroupPresentInfoKHR, VkDeviceGroupPresentModeFlagsKHR

VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR specifies that any physical device with a presentation engine can present its own swapchain images.

VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR specifies that any physical device with a presentation engine can present swapchain images from any physical device in its presentMask.

VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR specifies that any physical device with a presentation engine can present the sum of swapchain images from any physical devices in its presentMask.

VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR specifies that multiple physical devices with a presentation engine can each present their own swapchain images.

VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR specifies that images created from the swapchain (i.e. with the swapchain member of VkImageSwapchainCreateInfoKHR set to this swapchain’s handle) must use VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT.

VkSwapchainKHR - Opaque handle to a swapchain object

Description

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

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 vkAcquireNextImageKHR, and before it is presented by vkQueuePresentKHR. This includes transitioning the image layout and rendering commands.

An application can acquire use of a presentable image with 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 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

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

See Also

VkAcquireNextImageInfoKHR, VkBindImageMemorySwapchainInfoKHR, VkImageSwapchainCreateInfoKHR, VkPresentInfoKHR, VkSwapchainCreateInfoKHR, vkAcquireNextImageKHR, vkCreateSharedSwapchainsKHR, vkCreateSwapchainKHR, vkDestroySwapchainKHR, vkGetPastPresentationTimingGOOGLE, vkGetRefreshCycleDurationGOOGLE, vkGetSwapchainCounterEXT, vkGetSwapchainImagesKHR, vkGetSwapchainStatusKHR, vkSetHdrMetadataEXT

vkCreateSwapchainKHR - Create a swapchain

Parameters

• device is the device to create the swapchain for.

• pCreateInfo is a pointer to an instance of the VkSwapchainCreateInfoKHR structure specifying the parameters of the created swapchain.
• pAllocator is the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation).
• pSwapchain is a pointer to a VkSwapchainKHR handle in which the created swapchain object will be returned.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pCreateInfo must be a valid pointer to a valid VkSwapchainCreateInfoKHR structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• pSwapchain must be a valid pointer to a VkSwapchainKHR handle

Host Synchronization

• Host access to pCreateInfo.surface must be externally synchronized

• Host access to pCreateInfo.oldSwapchain must be externally synchronized

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_DEVICE_LOST

• VK_ERROR_SURFACE_LOST_KHR

• VK_ERROR_NATIVE_WINDOW_IN_USE_KHR

See Also

VkAllocationCallbacks, VkDevice, VkSwapchainCreateInfoKHR, VkSwapchainKHR

vkDestroySwapchainKHR - Destroy a swapchain object

Parameters

• device is the VkDevice associated with swapchain.

• swapchain is the swapchain to destroy.
• pAllocator is the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation).

Description

The application must not destroy a swapchain until after completion of all outstanding operations on images that were acquired from the swapchain. swapchain and all associated VkImage handles are destroyed, and must not be acquired or used any more by the application. The memory of each 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 VkSurfaceKHR, and a new swapchain can be created with it.

When a swapchain associated with a display surface is destroyed, if the image most recently presented to the display surface is from the swapchain being destroyed, then either any display resources modified by presenting images from any swapchain associated with the display surface must be reverted by the implementation to their state prior to the first present performed on one of these swapchains, or such resources must be left in their current state.

Valid Usage

• All uses of presentable images acquired from swapchain must have completed execution

• If VkAllocationCallbacks were provided when swapchain was created, a compatible set of callbacks must be provided here
• If no VkAllocationCallbacks were provided when swapchain was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• If swapchain is not VK_NULL_HANDLE, swapchain must be a valid VkSwapchainKHR handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• Both of device, and swapchain that are valid handles must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

• Host access to swapchain must be externally synchronized

See Also

VkAllocationCallbacks, VkDevice, VkSwapchainKHR

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

Parameters

• device is the device associated with swapchain.

• swapchain is the swapchain to query.
• pSwapchainImageCount is a pointer to an integer related to the number of presentable images available or queried, as described below.
• pSwapchainImages is either NULL or a pointer to an array of VkImage handles.

Description

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

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• swapchain must be a valid VkSwapchainKHR handle
• pSwapchainImageCount must be a valid pointer to a uint32_t value
• If the value referenced by pSwapchainImageCount is not 0, and pSwapchainImages is not NULL, pSwapchainImages must be a valid pointer to an array of pSwapchainImageCount VkImage handles
• Both of device, and swapchain must have been created, allocated, or retrieved from the same VkInstance

Return Codes

[Success] - VK_SUCCESS

• VK_INCOMPLETE

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkDevice, VkImage, VkSwapchainKHR

vkAcquireNextImageKHR - Retrieve the index of the next available presentable image

Parameters

• device is the device associated with swapchain.

• swapchain is the non-retired swapchain from which an image is being acquired.
• timeout specifies how long the function waits, in nanoseconds, if no image is available.
• semaphore is VK_NULL_HANDLE or a semaphore to signal.
• fence is VK_NULL_HANDLE or a fence to signal.
• pImageIndex is a pointer to a 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 vkGetSwapchainImagesKHR).

Valid Usage

• swapchain must not be in the retired state

• If semaphore is not VK_NULL_HANDLE it must be unsignaled
• If semaphore is not VK_NULL_HANDLE it must not have any uncompleted signal or wait operations pending
• If fence is not 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
• semaphore and fence must not both be equal to VK_NULL_HANDLE
• If the number of currently acquired images is greater than the difference between the number of images in swapchain and the value of VkSurfaceCapabilitiesKHR::minImageCount as returned by a call to vkGetPhysicalDeviceSurfaceCapabilities2KHR with the surface used to create swapchain, timeout must not be UINT64_MAX

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• swapchain must be a valid VkSwapchainKHR handle
• If semaphore is not VK_NULL_HANDLE, semaphore must be a valid VkSemaphore handle
• If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle
• pImageIndex must be a valid pointer to a uint32_t value
• If semaphore is a valid handle, it must have been created, allocated, or retrieved from device
• If fence is a valid handle, it must have been created, allocated, or retrieved from device
• Both of device, and swapchain that are valid handles must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

• Host access to swapchain must be externally synchronized

• Host access to semaphore must be externally synchronized
• Host access to fence must be externally synchronized

Return Codes

[Success] - VK_SUCCESS

• VK_TIMEOUT

• VK_NOT_READY

• VK_SUBOPTIMAL_KHR

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_DEVICE_LOST

• VK_ERROR_OUT_OF_DATE_KHR

• VK_ERROR_SURFACE_LOST_KHR

See Also

VkDevice, VkFence, VkSemaphore, VkSwapchainKHR

vkQueuePresentKHR - Queue an image for presentation

Parameters

• queue is a queue that is capable of presentation to the target surface’s platform on the same device as the image’s swapchain.

• pPresentInfo is a pointer to an instance of the VkPresentInfoKHR structure specifying the parameters of the presentation.

Description

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

• Each element of pSwapchains member of pPresentInfo must be a swapchain that is created for a surface for which presentation is supported from queue as determined using a call to vkGetPhysicalDeviceSurfaceSupportKHR

• If more than one member of pSwapchains was created from a display surface, all display surfaces referenced that refer to the same display must use the same display mode
• When a semaphore unsignal operation defined by the elements of the pWaitSemaphores member of pPresentInfo executes on queue, no other queue must be waiting on the same semaphore.
• All elements of the pWaitSemaphores member of pPresentInfo must be semaphores that are signaled, or have semaphore signal operations previously submitted for execution.

Any writes to memory backing the images referenced by the pImageIndices and pSwapchains members of pPresentInfo, that are available before 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.

If vkQueuePresentKHR fails to enqueue the corresponding set of queue operations, it may return VK_ERROR_OUT_OF_HOST_MEMORY or 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 vkQueuePresentKHR fails in such a way that the implementation is unable to make that guarantee, the implementation must return VK_ERROR_DEVICE_LOST.

However, if the presentation request is rejected by the presentation engine with an error VK_ERROR_OUT_OF_DATE_KHR or VK_ERROR_SURFACE_LOST_KHR, the set of queue operations are still considered to be enqueued and thus any semaphore to be waited on gets unsignaled when the corresponding queue operation is complete.

Valid Usage (Implicit)

• queue must be a valid VkQueue handle

• pPresentInfo must be a valid pointer to a valid VkPresentInfoKHR structure

Host Synchronization

• Host access to queue must be externally synchronized

• Host access to pPresentInfo.pWaitSemaphores[] must be externally synchronized
• Host access to pPresentInfo.pSwapchains[] must be externally synchronized

Command Properties

'

Return Codes

[Success] - VK_SUCCESS

• VK_SUBOPTIMAL_KHR

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_DEVICE_LOST

• VK_ERROR_OUT_OF_DATE_KHR

• VK_ERROR_SURFACE_LOST_KHR

See Also

VkPresentInfoKHR, VkQueue

vkGetDeviceGroupPresentCapabilitiesKHR - Query present capabilities from other physical devices

Parameters

• device is the logical device.

• pDeviceGroupPresentCapabilities is a pointer to a structure of type VkDeviceGroupPresentCapabilitiesKHR that is filled with the logical device’s capabilities.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pDeviceGroupPresentCapabilities must be a valid pointer to a VkDeviceGroupPresentCapabilitiesKHR structure

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkDevice, VkDeviceGroupPresentCapabilitiesKHR

vkGetDeviceGroupSurfacePresentModesKHR - Query present capabilities for a surface

Parameters

• device is the logical device.

• surface is the surface.
• pModes is a pointer to a value of type VkDeviceGroupPresentModeFlagsKHR that is filled with the supported device group present modes for the surface.

Description

The modes returned by this command are not invariant, and may change in response to the surface being moved, resized, or occluded. These modes must be a subset of the modes returned by vkGetDeviceGroupPresentCapabilitiesKHR.

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• surface must be a valid VkSurfaceKHR handle
• pModes must be a valid pointer to a VkDeviceGroupPresentModeFlagsKHR value
• Both of device, and surface must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

• Host access to surface must be externally synchronized

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_SURFACE_LOST_KHR

See Also

VkDevice, VkDeviceGroupPresentModeFlagsKHR, VkSurfaceKHR

vkAcquireNextImage2KHR - Retrieve the index of the next available presentable image

Parameters

• device is the device associated with swapchain.

• pAcquireInfo is a pointer to a structure of type VkAcquireNextImageInfoKHR containing parameters of the acquire.
• pImageIndex is a pointer to a uint32_t that is set to the index of the next image to use.

Valid Usage

• If the number of currently acquired images is greater than the difference between the number of images in the swapchain member of pAcquireInfo and the value of VkSurfaceCapabilitiesKHR::minImageCount as returned by a call to vkGetPhysicalDeviceSurfaceCapabilities2KHR with the surface used to create swapchain, the timeout member of pAcquireInfo must not be UINT64_MAX

Valid Usage (Implicit)

• device must be a valid VkDevice handle

• pAcquireInfo must be a valid pointer to a valid VkAcquireNextImageInfoKHR structure
• pImageIndex must be a valid pointer to a uint32_t value

Return Codes

[Success] - VK_SUCCESS

• VK_TIMEOUT

• VK_NOT_READY

• VK_SUBOPTIMAL_KHR

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_DEVICE_LOST

• VK_ERROR_OUT_OF_DATE_KHR

• VK_ERROR_SURFACE_LOST_KHR

See Also

VkAcquireNextImageInfoKHR, VkDevice

vkGetPhysicalDevicePresentRectanglesKHR - Query present rectangles for a surface on a physical device

Parameters

• physicalDevice is the physical device.

• surface is the surface.
• pRectCount is a pointer to an integer related to the number of rectangles available or queried, as described below.
• pRects is either NULL or a pointer to an array of VkRect2D structures.

Description

If pRects is NULL, then the number of rectangles used when presenting the given surface is returned in pRectCount. Otherwise, pRectCount must point to a variable set by the user to the number of elements in the pRects array, and on return the variable is overwritten with the number of structures actually written to pRects. If the value of pRectCount is less than the number of rectangles, at most pRectCount structures will be written. If pRectCount is smaller than the number of rectangles used for the given surface, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

The values returned by this command are not invariant, and may change in response to the surface being moved, resized, or occluded.

The rectangles returned by this command must not overlap.

Valid Usage (Implicit)

• physicalDevice must be a valid VkPhysicalDevice handle

• surface must be a valid VkSurfaceKHR handle
• pRectCount must be a valid pointer to a uint32_t value
• If the value referenced by pRectCount is not 0, and pRects is not NULL, pRects must be a valid pointer to an array of pRectCount VkRect2D structures
• Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

• Host access to surface must be externally synchronized

Return Codes

[Success] - VK_SUCCESS

• VK_INCOMPLETE

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VkPhysicalDevice, VkRect2D, VkSurfaceKHR

VkSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object

Description

Note

On some platforms, it is normal that 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.

• imageArrayLayers is the number of views in a multiview/stereo surface. For non-stereoscopic-3D applications, this value is 1.
• imageUsage is a bitmask of VkImageUsageFlagBits describing the intended usage of the (acquired) swapchain images.
• imageSharingMode is the sharing mode used for the image(s) of the swapchain.
• queueFamilyIndexCount is the number of queue families having access to the image(s) of the swapchain when imageSharingMode is VK_SHARING_MODE_CONCURRENT.
• pQueueFamilyIndices is an array of queue family indices having access to the images(s) of the swapchain when imageSharingMode is VK_SHARING_MODE_CONCURRENT.
• preTransform is a 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 currentTransform value returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR, the presentation engine will transform the image content as part of the presentation operation.
• compositeAlpha is a VkCompositeAlphaFlagBitsKHR value indicating the alpha compositing mode to use when this surface is composited together with other surfaces on certain window systems.
• 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.

• 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 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 effects they would have had will not occur. VK_TRUE value does not guarantee any clipping will occur, but allows more optimal presentation methods to be used on some platforms.
  • If set to VK_FALSE, presentable images associated with the swapchain will own all of the pixels they contain.

Note

Applications should set this value to 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.

• oldSwapchain is VK_NULL_HANDLE, or the existing non-retired swapchain currently associated with surface. Providing a valid 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 vkCreateSwapchainKHR with an oldSwapchain that is not VK_NULL_HANDLE, oldSwapchain is retired — even if creation of the new swapchain fails. The new swapchain is created in the non-retired state whether or not oldSwapchain is VK_NULL_HANDLE.

Upon calling vkCreateSwapchainKHR with an oldSwapchain that is not VK_NULL_HANDLE, any images from 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 oldSwapchain to free all memory associated with oldSwapchain.

Note

Multiple retired swapchains can be associated with the same VkSurfaceKHR through multiple uses of oldSwapchain that outnumber calls to vkDestroySwapchainKHR.

After oldSwapchain is retired, the application can pass to vkQueuePresentKHR any images it had already acquired from 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, vkQueuePresentKHR may fail if oldSwapchain has entered a state that causes VK_ERROR_OUT_OF_DATE_KHR to be returned.

The application can continue to use a shared presentable image obtained from 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 VK_ERROR_OUT_OF_DATE_KHR.

Valid Usage

• surface must be a surface that is supported by the device as determined using vkGetPhysicalDeviceSurfaceSupportKHR

• minImageCount must be greater than or equal to the value returned in the minImageCount member of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface
• minImageCount must be less than or equal to the value returned in the maxImageCount member of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface if the returned maxImageCount is not zero
• minImageCount must be 1 if presentMode is either VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
• imageFormat and imageColorSpace must match the format and colorSpace members, respectively, of one of the VkSurfaceFormatKHR structures returned by vkGetPhysicalDeviceSurfaceFormatsKHR for the surface
• imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface
• imageExtent members width and height must both be non-zero
• imageArrayLayers must be greater than 0 and less than or equal to the maxImageArrayLayers member of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface
• If presentMode is VK_PRESENT_MODE_IMMEDIATE_KHR, VK_PRESENT_MODE_MAILBOX_KHR, VK_PRESENT_MODE_FIFO_KHR or VK_PRESENT_MODE_FIFO_RELAXED_KHR, imageUsage must be a subset of the supported usage flags present in the supportedUsageFlags member of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for surface
• If presentMode is VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, imageUsage must be a subset of the supported usage flags present in the sharedPresentSupportedUsageFlags member of the VkSharedPresentSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilities2KHR for surface
• If imageSharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values
• If imageSharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1
• If imageSharingMode is VK_SHARING_MODE_CONCURRENT, each element of pQueueFamilyIndices must be unique and must be less than pQueueFamilyPropertyCount returned by either vkGetPhysicalDeviceQueueFamilyProperties or vkGetPhysicalDeviceQueueFamilyProperties2 for the physicalDevice that was used to create device
• preTransform must be one of the bits present in the supportedTransforms member of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface
• compositeAlpha must be one of the bits present in the supportedCompositeAlpha member of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface
• presentMode must be one of the VkPresentModeKHR values returned by vkGetPhysicalDeviceSurfacePresentModesKHR for the surface
• If the logical device was created with VkDeviceGroupDeviceCreateInfo::physicalDeviceCount equal to 1, flags must not contain VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
• oldSwapchain must not be in the retired state
• imageFormat, imageUsage, imageExtent, and imageArrayLayers must be supported for VK_IMAGE_TYPE_2D VK_IMAGE_TILING_OPTIMAL images as reported by vkGetPhysicalDeviceImageFormatProperties.

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkDeviceGroupSwapchainCreateInfoKHR or VkSwapchainCounterCreateInfoEXT
• Each sType member in the pNext chain must be unique
• flags must be a valid combination of VkSwapchainCreateFlagBitsKHR values
• surface must be a valid VkSurfaceKHR handle
• imageFormat must be a valid VkFormat value
• imageColorSpace must be a valid VkColorSpaceKHR value
• imageUsage must be a valid combination of VkImageUsageFlagBits values
• imageUsage must not be 0
• imageSharingMode must be a valid VkSharingMode value
• preTransform must be a valid VkSurfaceTransformFlagBitsKHR value
• compositeAlpha must be a valid VkCompositeAlphaFlagBitsKHR value
• presentMode must be a valid VkPresentModeKHR value
• If oldSwapchain is not VK_NULL_HANDLE, oldSwapchain must be a valid VkSwapchainKHR handle
• If oldSwapchain is a valid handle, it must have been created, allocated, or retrieved from surface
• Both of oldSwapchain, and surface that are valid handles must have been created, allocated, or retrieved from the same VkInstance

See Also

VkBool32, VkColorSpaceKHR, VkCompositeAlphaFlagBitsKHR, VkExtent2D, VkFormat, VkImageUsageFlags, VkPresentModeKHR, VkSharingMode, VkStructureType, VkSurfaceKHR, VkSurfaceTransformFlagBitsKHR, VkSwapchainCreateFlagsKHR, VkSwapchainKHR, vkCreateSharedSwapchainsKHR, vkCreateSwapchainKHR

VkPresentInfoKHR - Structure describing parameters of a queue presentation

Description

Before an application can present an image, the image’s layout must be transitioned to the VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout, or for a shared presentable image the VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR layout.

Note

When transitioning the image to VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or VK_IMAGE_LAYOUT_PRESENT_SRC_KHR, there is no need to delay subsequent processing, or perform any visibility operations (as vkQueuePresentKHR performs automatic visibility operations). To achieve this, the dstAccessMask member of the VkImageMemoryBarrier should be set to 0, and the dstStageMask parameter should be set to VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT.

Valid Usage

• Each element of pImageIndices must be the index of a presentable image acquired from the swapchain specified by the corresponding element of the pSwapchains array, and the presented image subresource must be in the VK_IMAGE_LAYOUT_PRESENT_SRC_KHR or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR layout at the time the operation is executed on a VkDevice

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_PRESENT_INFO_KHR

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of VkDeviceGroupPresentInfoKHR, VkDisplayPresentInfoKHR, VkPresentRegionsKHR, or VkPresentTimesInfoGOOGLE
• Each sType member in the pNext chain must be unique
• If waitSemaphoreCount is not 0, pWaitSemaphores must be a valid pointer to an array of waitSemaphoreCount valid VkSemaphore handles
• pSwapchains must be a valid pointer to an array of swapchainCount valid VkSwapchainKHR handles
• pImageIndices must be a valid pointer to an array of swapchainCount uint32_t values
• If pResults is not NULL, pResults must be a valid pointer to an array of swapchainCount VkResult values
• swapchainCount must be greater than 0
• Both of the elements of pSwapchains, and the elements of pWaitSemaphores that are valid handles must have been created, allocated, or retrieved from the same VkInstance

See Also

VkResult, VkSemaphore, VkStructureType, VkSwapchainKHR, vkQueuePresentKHR

VkDeviceGroupPresentCapabilitiesKHR - Present capabilities from other physical devices

Description

modes always has VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR set.

The present mode flags are also used when presenting an image, in VkDeviceGroupPresentInfoKHR::mode.

If a device group only includes a single physical device, then modes must equal VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR

• pNext must be NULL

See Also

VkDeviceGroupPresentModeFlagsKHR, VkStructureType, vkGetDeviceGroupPresentCapabilitiesKHR

VkImageSwapchainCreateInfoKHR - Specify that an image will be bound to swapchain memory

Valid Usage

• If swapchain is not VK_NULL_HANDLE, the fields of VkImageCreateInfo must match the implied image creation parameters of the swapchain

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR

• If swapchain is not VK_NULL_HANDLE, swapchain must be a valid VkSwapchainKHR handle

See Also

VkStructureType, VkSwapchainKHR

VkBindImageMemorySwapchainInfoKHR - Structure specifying swapchain image memory to bind to

Description

If swapchain is not NULL, the swapchain and imageIndex are used to determine the memory that the image is bound to, instead of memory and memoryOffset.

Memory can be bound to a swapchain and use the pDeviceIndices or pSplitInstanceBindRegions members of VkBindImageMemoryDeviceGroupInfo.

Valid Usage

• imageIndex must be less than the number of images in swapchain

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR

• swapchain must be a valid VkSwapchainKHR handle

Host Synchronization

• Host access to swapchain must be externally synchronized

See Also

VkStructureType, VkSwapchainKHR

VkAcquireNextImageInfoKHR - Structure specifying parameters of the acquire

Description

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

Note

vkAcquireNextImage2KHR signals at most one semaphore, even if the application requests waiting for multiple physical devices to be ready via the 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

• swapchain must not be in the retired state

• If semaphore is not VK_NULL_HANDLE it must be unsignaled
• If semaphore is not VK_NULL_HANDLE it must not have any uncompleted signal or wait operations pending
• If fence is not 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
• semaphore and fence must not both be equal to VK_NULL_HANDLE
• deviceMask must be a valid device mask
• deviceMask must not be zero
• semaphore and fence must not both be equal to VK_NULL_HANDLE.

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR

• pNext must be NULL
• swapchain must be a valid VkSwapchainKHR handle
• If semaphore is not VK_NULL_HANDLE, semaphore must be a valid VkSemaphore handle
• If fence is not VK_NULL_HANDLE, fence must be a valid VkFence handle
• Each of fence, semaphore, and swapchain that are valid handles must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

• Host access to swapchain must be externally synchronized

• Host access to semaphore must be externally synchronized
• Host access to fence must be externally synchronized

See Also

VkFence, VkSemaphore, VkStructureType, VkSwapchainKHR, vkAcquireNextImage2KHR

VkDeviceGroupPresentInfoKHR - Mode and mask controlling which physical devices' images are presented

Description

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

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

If mode is VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then each element of 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 pDeviceMasks must have a value for which all set bits are set in one of the elements of VkDeviceGroupPresentCapabilitiesKHR::presentMask.

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

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

Valid Usage

• swapchainCount must equal 0 or VkPresentInfoKHR::swapchainCount

• If mode is VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then each element of pDeviceMasks must have exactly one bit set, and the corresponding element of VkDeviceGroupPresentCapabilitiesKHR::presentMask must be non-zero
• If mode is VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, then each element of pDeviceMasks must have exactly one bit set, and some physical device in the logical device must include that bit in its VkDeviceGroupPresentCapabilitiesKHR::presentMask.
• If mode is VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then each element of pDeviceMasks must have a value for which all set bits are set in one of the elements of VkDeviceGroupPresentCapabilitiesKHR::presentMask
• If mode is VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then for each bit set in each element of pDeviceMasks, the corresponding element of VkDeviceGroupPresentCapabilitiesKHR::presentMask must be non-zero
• The value of each element of pDeviceMasks must be equal to the device mask passed in VkAcquireNextImageInfoKHR::deviceMask when the image index was last acquired
• mode must have exactly one bit set, and that bit must have been included in VkDeviceGroupSwapchainCreateInfoKHR::modes

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR

• If swapchainCount is not 0, pDeviceMasks must be a valid pointer to an array of swapchainCount uint32_t values
• mode must be a valid VkDeviceGroupPresentModeFlagBitsKHR value

See Also

VkDeviceGroupPresentModeFlagBitsKHR, VkStructureType

VkDeviceGroupSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object

Description

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

Valid Usage (Implicit)

• sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR

• modes must be a valid combination of VkDeviceGroupPresentModeFlagBitsKHR values
• modes must not be 0

See Also

VkDeviceGroupPresentModeFlagsKHR, VkStructureType

VkSwapchainCreateFlagsKHR - Bitmask of VkSwapchainCreateFlagBitsKHR

Description

VkSwapchainCreateFlagsKHR is a bitmask type for setting a mask of zero or more VkSwapchainCreateFlagBitsKHR.

See Also

VkSwapchainCreateFlagBitsKHR, VkSwapchainCreateInfoKHR

VkDeviceGroupPresentModeFlagsKHR - Bitmask of VkDeviceGroupPresentModeFlagBitsKHR

Description

VkDeviceGroupPresentModeFlagsKHR is a bitmask type for setting a mask of zero or more VkDeviceGroupPresentModeFlagBitsKHR.

See Also

VkDeviceGroupPresentCapabilitiesKHR, VkDeviceGroupPresentModeFlagBitsKHR, VkDeviceGroupSwapchainCreateInfoKHR, vkGetDeviceGroupSurfacePresentModesKHR