C Specification

To create a swapchain, call:

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

Parameters

  • 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.

Description

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:

VkImageCreateInfo Field Value

flags

VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT is set if VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR is set

VK_IMAGE_CREATE_PROTECTED_BIT is set if VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR is set

VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT and VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR are both set if VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR is set

all other bits are unset

imageType

VK_IMAGE_TYPE_2D

format

pCreateInfo->imageFormat

extent

{pCreateInfo->imageExtent.width, pCreateInfo->imageExtent.height, 1}

mipLevels

1

arrayLayers

pCreateInfo->imageArrayLayers

samples

VK_SAMPLE_COUNT_1_BIT

tiling

VK_IMAGE_TILING_OPTIMAL

usage

pCreateInfo->imageUsage

sharingMode

pCreateInfo->imageSharingMode

queueFamilyIndexCount

pCreateInfo->queueFamilyIndexCount

pQueueFamilyIndices

pCreateInfo->pQueueFamilyIndices

initialLayout

VK_IMAGE_LAYOUT_UNDEFINED

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

If the native window referred to by pCreateInfo->surface is already associated with a Vulkan swapchain, VK_ERROR_NATIVE_WINDOW_IN_USE_KHR must 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. However, VkSurfaceKHR is not a child of any VkDevice and is not affected by the lost device. After successfully recreating a VkDevice, the same VkSurfaceKHR can be used to create a new VkSwapchainKHR, provided the previous one was destroyed.

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.

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

Valid Usage

  • VUID-vkCreateSwapchainKHR-device-05068
    The number of swapchains currently allocated from device plus 1 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-vkCreateSwapchainKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateSwapchainKHR-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkSwapchainCreateInfoKHR structure

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

  • VUID-vkCreateSwapchainKHR-pSwapchain-parameter
    pSwapchain must be a valid pointer to a VkSwapchainKHR handle

  • VUID-vkCreateSwapchainKHR-device-queuecount
    The device must have been created with at least 1 queue

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_DEVICE_LOST

  • VK_ERROR_SURFACE_LOST_KHR

  • VK_ERROR_NATIVE_WINDOW_IN_USE_KHR

  • VK_ERROR_INITIALIZATION_FAILED

See Also

VK_KHR_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-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0