vkCreateSwapchainKHR

To create a swapchain, call:

VkResult vkCreateSwapchainKHR(
    VkDevice device,
    const VkSwapchainCreateInfoKHR* pCreateInfo,
    const VkAllocationCallbacks* pAllocator,
    VkSwapchainKHR* pSwapchain);

• device is the device to create the swapchain for.
• pCreateInfo is a pointer to a 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.

As mentioned above, if vkCreateSwapchainKHR succeeds, it will return a handle to a swapchain containing an array of at least pCreateInfo→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 VkImageCreateInfo parameters:

The pCreateInfo→surface must not be destroyed until after the swapchain is destroyed.

If oldSwapchain is VK_NULL_HANDLE, and the native window referred to by pCreateInfo→surface is already associated with a Vulkan swapchain, VK_ERROR_NATIVE_WINDOW_IN_USE_KHRmust be returned.

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

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

vkCreateSwapchainKHR will return VK_ERROR_DEVICE_LOST if the logical device was lost. The VkSwapchainKHR is a child of the device, and must be destroyed before the device. However, VkSurfaceKHR is not a child of any VkDevice and is not affected by the lost device. After successfully recreating a VkDevice, the same VkSurfaceKHRcan be used to create a new VkSwapchainKHR, provided the previous one was destroyed.

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

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

If the pNext chain of VkSwapchainCreateInfoKHR includes a VkSwapchainPresentBarrierCreateInfoNV structure, then that structure includes additional swapchain creation parameters specific to the present barrier. Swapchain creation may fail if the state of the current system restricts the usage of the present barrier feature VkSurfaceCapabilitiesPresentBarrierNV, or a swapchain itself does not satisfy all the required conditions. In this scenario VK_ERROR_INITIALIZATION_FAILED is returned.

When the VkSurfaceKHR in VkSwapchainCreateInfoKHR is a display surface, then the VkDisplayModeKHR in display surface’s VkDisplaySurfaceCreateInfoKHR is associated with a particular VkDisplayKHR. Swapchain creation may fail if that VkDisplayKHR is not acquired by the application. In this scenario VK_ERROR_INITIALIZATION_FAILED is returned.