C Specification

When the VK_KHR_display_swapchain extension is enabled, multiple swapchains that share presentable images are created by calling:

VkResult vkCreateSharedSwapchainsKHR(
    VkDevice                                    device,
    uint32_t                                    swapchainCount,
    const VkSwapchainCreateInfoKHR*             pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkSwapchainKHR*                             pSwapchains);

Parameters

  • device is the device to create the swapchains for.

  • swapchainCount is the number of swapchains to create.

  • pCreateInfos is a pointer to an array of VkSwapchainCreateInfoKHR structures specifying the parameters of the created swapchains.

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

  • pSwapchains is a pointer to an array of VkSwapchainKHR handles in which the created swapchain objects will be returned.

Description

vkCreateSharedSwapchainsKHR is similar to vkCreateSwapchainKHR, except that it takes an array of VkSwapchainCreateInfoKHR structures, and returns an array of swapchain objects.

The swapchain creation parameters that affect the properties and number of presentable images must match between all the swapchains. If the displays used by any of the swapchains do not use the same presentable image layout or are incompatible in a way that prevents sharing images, swapchain creation will fail with the result code VK_ERROR_INCOMPATIBLE_DISPLAY_KHR. If any error occurs, no swapchains will be created. Images presented to multiple swapchains must be re-acquired from all of them before transitioning away from VK_IMAGE_LAYOUT_PRESENT_SRC_KHR. After destroying one or more of the swapchains, the remaining swapchains and the presentable images can continue to be used.

Valid Usage (Implicit)
  • device must be a valid VkDevice handle

  • pCreateInfos must be a valid pointer to an array of swapchainCount valid VkSwapchainCreateInfoKHR structures

  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • pSwapchains must be a valid pointer to an array of swapchainCount VkSwapchainKHR handles

  • swapchainCount must be greater than 0

Host Synchronization
  • Host access to pCreateInfos[].surface must be externally synchronized

  • Host access to pCreateInfos[].oldSwapchain must be externally synchronized

Return Codes
On success, this command returns
  • VK_SUCCESS

On failure, this command returns
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INCOMPATIBLE_DISPLAY_KHR

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_SURFACE_LOST_KHR

See Also

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.