C Specification

The VkSwapchainCreateInfoKHR structure is defined as:

// Provided by VK_KHR_swapchain
typedef struct VkSwapchainCreateInfoKHR {
    VkStructureType                  sType;
    const void*                      pNext;
    VkSwapchainCreateFlagsKHR        flags;
    VkSurfaceKHR                     surface;
    uint32_t                         minImageCount;
    VkFormat                         imageFormat;
    VkColorSpaceKHR                  imageColorSpace;
    VkExtent2D                       imageExtent;
    uint32_t                         imageArrayLayers;
    VkImageUsageFlags                imageUsage;
    VkSharingMode                    imageSharingMode;
    uint32_t                         queueFamilyIndexCount;
    const uint32_t*                  pQueueFamilyIndices;
    VkSurfaceTransformFlagBitsKHR    preTransform;
    VkCompositeAlphaFlagBitsKHR      compositeAlpha;
    VkPresentModeKHR                 presentMode;
    VkBool32                         clipped;
    VkSwapchainKHR                   oldSwapchain;
} VkSwapchainCreateInfoKHR;


  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkSwapchainCreateFlagBitsKHR indicating parameters of the swapchain creation.

  • surface is the surface onto which the swapchain will present images. If the creation succeeds, the swapchain becomes associated with surface.

  • minImageCount is the minimum number of presentable images that the application needs. The implementation will either create the swapchain with at least that many images, or it will fail to create the swapchain.

  • imageFormat is a VkFormat value specifying the format the swapchain image(s) will be created with.

  • imageColorSpace is a VkColorSpaceKHR value specifying the way the swapchain interprets image data.

  • imageExtent is the size (in pixels) of the swapchain image(s). The behavior is platform-dependent if the image extent does not match the surface’s currentExtent as returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR.


    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 a pointer to 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. Fragment shaders may not execute for these pixels, and thus any side effects they would have had will not occur. Setting VK_TRUE does not guarantee any clipping will occur, but allows more efficient 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.


      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 fragment shaders do not have any side effects that require them to run for all pixels in the presentable image.

  • oldSwapchain must be VK_NULL_HANDLE in Vulkan SC https://registry.khronos.org/vulkansc/specs/1.0-extensions/html/vkspec.html#SCID-4.


Valid Usage
  • VUID-VkSwapchainCreateInfoKHR-surface-01270
    surface must be a surface that is supported by the device as determined using vkGetPhysicalDeviceSurfaceSupportKHR

  • VUID-VkSwapchainCreateInfoKHR-minImageCount-01272
    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

  • VUID-VkSwapchainCreateInfoKHR-presentMode-02839
    If presentMode is not VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR nor VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, then 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

  • VUID-VkSwapchainCreateInfoKHR-minImageCount-01383

  • VUID-VkSwapchainCreateInfoKHR-imageFormat-01273
    imageFormat and imageColorSpace must match the format and colorSpace members, respectively, of one of the VkSurfaceFormatKHR structures returned by vkGetPhysicalDeviceSurfaceFormatsKHR for the surface

  • VUID-VkSwapchainCreateInfoKHR-pNext-07781
    imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface

  • VUID-VkSwapchainCreateInfoKHR-imageExtent-01689
    imageExtent members width and height must both be non-zero

  • VUID-VkSwapchainCreateInfoKHR-imageArrayLayers-01275
    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

  • VUID-VkSwapchainCreateInfoKHR-presentMode-01427
    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

  • VUID-VkSwapchainCreateInfoKHR-imageUsage-01384
    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

  • VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01277
    If imageSharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values

  • VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01278
    If imageSharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1

  • VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01428
    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

  • VUID-VkSwapchainCreateInfoKHR-preTransform-01279
    preTransform must be one of the bits present in the supportedTransforms member of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface

  • VUID-VkSwapchainCreateInfoKHR-compositeAlpha-01280
    compositeAlpha must be one of the bits present in the supportedCompositeAlpha member of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface

  • VUID-VkSwapchainCreateInfoKHR-presentMode-01281
    presentMode must be one of the VkPresentModeKHR values returned by vkGetPhysicalDeviceSurfacePresentModesKHR for the surface

  • VUID-VkSwapchainCreateInfoKHR-physicalDeviceCount-01429

  • VUID-VkSwapchainCreateInfoKHR-oldSwapchain-05073
    oldSwapchain must be VK_NULL_HANDLE

  • VUID-VkSwapchainCreateInfoKHR-imageFormat-01778
    The implied image creation parameters of the swapchain must be supported as reported by vkGetPhysicalDeviceImageFormatProperties

  • VUID-VkSwapchainCreateInfoKHR-flags-03168
    If flags contains VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR then the pNext chain must include a VkImageFormatListCreateInfo structure with a viewFormatCount greater than zero and pViewFormats must have an element equal to imageFormat

  • VUID-VkSwapchainCreateInfoKHR-pNext-04099
    If a VkImageFormatListCreateInfo structure was included in the pNext chain and VkImageFormatListCreateInfo::viewFormatCount is not zero then all of the formats in VkImageFormatListCreateInfo::pViewFormats must be compatible with the format as described in the compatibility table

  • VUID-VkSwapchainCreateInfoKHR-flags-04100
    If flags does not contain VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR and the pNext chain include a VkImageFormatListCreateInfo structure then VkImageFormatListCreateInfo::viewFormatCount must be 0 or 1

Valid Usage (Implicit)
  • VUID-VkSwapchainCreateInfoKHR-sType-sType

  • VUID-VkSwapchainCreateInfoKHR-pNext-pNext
    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, VkImageFormatListCreateInfo, or VkSwapchainCounterCreateInfoEXT

  • VUID-VkSwapchainCreateInfoKHR-sType-unique
    The sType value of each struct in the pNext chain must be unique

  • VUID-VkSwapchainCreateInfoKHR-flags-parameter
    flags must be a valid combination of VkSwapchainCreateFlagBitsKHR values

  • VUID-VkSwapchainCreateInfoKHR-surface-parameter
    surface must be a valid VkSurfaceKHR handle

  • VUID-VkSwapchainCreateInfoKHR-imageFormat-parameter
    imageFormat must be a valid VkFormat value

  • VUID-VkSwapchainCreateInfoKHR-imageColorSpace-parameter
    imageColorSpace must be a valid VkColorSpaceKHR value

  • VUID-VkSwapchainCreateInfoKHR-imageUsage-parameter
    imageUsage must be a valid combination of VkImageUsageFlagBits values

  • VUID-VkSwapchainCreateInfoKHR-imageUsage-requiredbitmask
    imageUsage must not be 0

  • VUID-VkSwapchainCreateInfoKHR-imageSharingMode-parameter
    imageSharingMode must be a valid VkSharingMode value

  • VUID-VkSwapchainCreateInfoKHR-preTransform-parameter
    preTransform must be a valid VkSurfaceTransformFlagBitsKHR value

  • VUID-VkSwapchainCreateInfoKHR-compositeAlpha-parameter
    compositeAlpha must be a valid VkCompositeAlphaFlagBitsKHR value

  • VUID-VkSwapchainCreateInfoKHR-presentMode-parameter
    presentMode must be a valid VkPresentModeKHR value

  • VUID-VkSwapchainCreateInfoKHR-commonparent
    Both of oldSwapchain, and surface that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkInstance

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 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0