C Specification

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

// Provided by VK_KHR_display_swapchain
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 being modified. After destroying one or more of the swapchains, the remaining swapchains and the presentable images can continue to be used.

If VkPhysicalDeviceVulkanSC10Properties::deviceNoDynamicHostAllocations is VK_TRUE, vkCreateSharedSwapchainsKHR must not return VK_ERROR_OUT_OF_HOST_MEMORY.

Valid Usage

  • VUID-vkCreateSharedSwapchainsKHR-device-05068
    The number of swapchains currently allocated from device plus swapchainCount must be less than or equal to the total number of swapchains requested via VkDeviceObjectReservationCreateInfo::swapchainRequestCount specified when device was created

Valid Usage (Implicit)

  • VUID-vkCreateSharedSwapchainsKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateSharedSwapchainsKHR-pCreateInfos-parameter
    pCreateInfos must be a valid pointer to an array of swapchainCount valid VkSwapchainCreateInfoKHR structures

  • VUID-vkCreateSharedSwapchainsKHR-pAllocator-null
    pAllocator must be NULL

  • VUID-vkCreateSharedSwapchainsKHR-pSwapchains-parameter
    pSwapchains must be a valid pointer to an array of swapchainCount VkSwapchainKHR handles

  • VUID-vkCreateSharedSwapchainsKHR-swapchainCount-arraylength
    swapchainCount must be greater than 0

Host Synchronization

  • Host access to pCreateInfos[].surface 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

VK_KHR_display_swapchain, VkAllocationCallbacks, VkDevice, VkSwapchainCreateInfoKHR, VkSwapchainKHR

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

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0