VKSWAPCHAINCREATEINF(3)

NAME
VkSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object

C SPECIFICATION

The VkSwapchainCreateInfoKHR structure is defined as:

    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;

MEMBERS

    • sType is the type of this structure and must be VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR.

    • pNext is NULL or a pointer to an extension-specific structure.

    • flags is reserved for future use, and must be zero.

    • surface is the surface that the swapchain will present images to.

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

    • imageFormat is a VkFormat that is valid for swapchains on the specified surface.

    • imageColorSpace is a VkColorSpaceKHR that is valid for swapchains on the specified surface.

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

    • imageArrayLayers is the number of views in a multiview/stereo surface. For non-stereoscopic-3D applications, this value is 1.

    • imageUsage is a bitfield of VkImageUsageFlagBits, indicating how the application will use the swapchain’s presentable images.

    • imageSharingMode is the sharing mode used for the images of the swapchain.

    • queueFamilyIndexCount is the number of queue families having access to the images of the swapchain in case imageSharingMode is VK_SHARING_MODE_CONCURRENT.

    • pQueueFamilyIndices is an array of queue family indices having access to the images of the swapchain in case imageSharingMode is VK_SHARING_MODE_CONCURRENT.

    • preTransform is a bitfield of VkSurfaceTransformFlagBitsKHR, 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 bitfield of VkCompositeAlphaFlagBitsKHR, 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 indicates whether the Vulkan implementation is allowed to discard rendering operations that affect regions of the surface which aren’t 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. Pixel shaders maynot: execute for these pixels, and thus any side affects they would have had will not occur.

        • If set to VK_FALSE, presentable images associated with the swapchain will own all the pixels they contain. Setting this value to VK_TRUE does not guarantee any clipping will occur, but allows more optimal presentation methods to be used on some platforms.

DESCRIPTION

    Note

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

    • oldSwapchain, if not VK_NULL_HANDLE, specifies the swapchain that will be replaced by the new swapchain being created. The new swapchain will: be a descendant of oldSwapchain. Further, any descendants of the new swapchain will also be descendants of oldSwapchain. Upon calling vkCreateSwapchainKHR with a oldSwapchain that is not VK_NULL_HANDLE, any images not acquired by the application may be freed by the implementation, which may occur even if creation of the new swapchain fails. The application must destroy the old swapchain to free all memory associated with the old swapchain. The application must wait for the completion of any outstanding rendering to images it currently has acquired at the time the swapchain is destroyed. The application can continue to present any images it acquired and has not yet presented using the old swapchain, as long as it has not entered a state that causes it to return VK_ERROR_OUT_OF_DATE_KHR. However, the application cannot acquire any more images from the old swapchain regardless of whether or not creation of the new swapchain succeeds.

VALID USAGE

    • sType must be VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR

    • pNext must be NULL

    • flags must be 0

    • surface must be a valid VkSurfaceKHR handle

    • imageFormat must be a valid VkFormat value

    • imageColorSpace must be a valid VkColorSpaceKHR value

    • imageUsage must be a valid combination of VkImageUsageFlagBits values

    • imageUsage must not be 0

    • imageSharingMode must be a valid VkSharingMode value

    • preTransform must be a valid VkSurfaceTransformFlagBitsKHR value

    • compositeAlpha must be a valid VkCompositeAlphaFlagBitsKHR value

    • presentMode must be a valid VkPresentModeKHR value

    • If oldSwapchain is not VK_NULL_HANDLE, oldSwapchain must be a valid VkSwapchainKHR handle

    • If oldSwapchain is a valid handle, it must have been created, allocated, or retrieved from surface

    • surface must be a surface that is supported by the device as determined using vkGetPhysicalDeviceSurfaceSupportKHR

    • The native window referred to by surface must not already be associated with a swapchain other than oldSwapchain, or with a non-Vulkan graphics API surface

    • 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

    • 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

    • imageFormat and imageColorspace must match the format and colorSpace members, respectively, of one of the VkSurfaceFormatKHR structures returned by vkGetPhysicalDeviceSurfaceFormatsKHR for the surface

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

    • 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

    • imageUsage must be a subset of the supported usage flags present in the supportedUsageFlags member of the VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface

    • If imageSharingMode is VK_SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a pointer to an array of queueFamilyIndexCount uint32_t values

    • If imageSharingMode is VK_SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1

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

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

    • presentMode must be one of the VkPresentModeKHR values returned by vkGetPhysicalDeviceSurfacePresentModesKHR for the surface

SEE ALSO

VkBool32, VkColorSpaceKHR, VkCompositeAlphaFlagBitsKHR, VkExtent2D, VkFormat, VkImageUsageFlags, VkPresentModeKHR, VkSharingMode, VkStructureType, VkSurfaceKHR, VkSurfaceTransformFlagBitsKHR, VkSwapchainCreateFlagsKHR, VkSwapchainKHR, vkCreateSharedSwapchainsKHR, vkCreateSwapchainKHR

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkSwapchainCreateInfoKHR

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

COPYRIGHT

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

AUTHOR

Khronos Group
    Author.