Structures

VkSwapchainCreateInfoKHR

Structure specifying parameters of a newly created swapchain object

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;
} VkSwapchainCreateInfoKHR;

pub struct SwapchainCreateInfoKHR {
    s_type: vk::StructureType,
    p_next: *const c_void,
    flags: vk::SwapchainCreateFlagsKHR,
    surface: vk::SurfaceKHR, // The swapchain's target surface
    min_image_count: u32, // Minimum number of presentation images the application needs
    image_format: vk::Format, // Format of the presentation images
    image_color_space: vk::ColorSpaceKHR, // Colorspace of the presentation images
    image_extent: vk::Extent2D, // Dimensions of the presentation images
    image_array_layers: u32, // Determines the number of views for multiview/stereo presentation
    image_usage: vk::ImageUsageFlags, // Bits indicating how the presentation images will be used
    image_sharing_mode: vk::SharingMode, // Sharing mode used for the presentation images
    queue_family_index_count: u32, // Number of queue families having access to the images in case of concurrent sharing mode
    p_queue_family_indices: *const u32, // Array of queue family indices having access to the images in case of concurrent sharing mode
    pre_transform: vk::SurfaceTransformFlagBitsKHR, // The transform, relative to the device's natural orientation, applied to the image content prior to presentation
    composite_alpha: vk::CompositeAlphaFlagBitsKHR, // The alpha blending mode used when compositing this surface with other surfaces in the window system
    present_mode: vk::PresentModeKHR, // Which presentation mode to use for presents on this swap chain
    clipped: vk::Bool32, // Specifies whether presentable images may be affected by window clip regions
}

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 maxImageExtentmay 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 , unless scaling is selected through VkSwapchainPresentScalingCreateInfoKHR, if supported .
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 clipped is 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 clipped is 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 is VK_NULL_HANDLE, or the existing non-retired swapchain currently associated with surface. Providing a valid oldSwapchain may aid in the resource reuse, and also allows the application to still present any images that are already acquired from it.

Upon calling vkCreateSwapchainKHR with an oldSwapchain that is not VK_NULL_HANDLE, oldSwapchain is retired — even if creation of the new swapchain fails. The new swapchain is created in the non-retired state whether or not oldSwapchain is VK_NULL_HANDLE.

Upon calling vkCreateSwapchainKHR with an oldSwapchain that is not VK_NULL_HANDLE, any images from oldSwapchain that are not acquired by the application may be freed by the implementation, which may occur even if creation of the new swapchain fails. The application can destroy oldSwapchain to free all memory associated with oldSwapchain.

Multiple retired swapchains can be associated with the same VkSurfaceKHR through multiple uses of oldSwapchain that outnumber calls to vkDestroySwapchainKHR.After oldSwapchain is retired, the application can pass to vkQueuePresentKHR any images it had already acquired from oldSwapchain. E.g., an application may present an image from the old swapchain before an image from the new swapchain is ready to be presented. As usual, vkQueuePresentKHRmay fail if oldSwapchain has entered a state that causes VK_ERROR_OUT_OF_DATE_KHR to be returned.The application can continue to use a shared presentable image obtained from oldSwapchain until a presentable image is acquired from the new swapchain, as long as it has not entered a state that causes it to return VK_ERROR_OUT_OF_DATE_KHR.

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-swapchainMaintenance1-10155

If the swapchainMaintenance1 feature is not enabled, then the pNext chain must not include a VkSwapchainPresentModesCreateInfoKHR structure

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

minImageCount must be 1 if presentMode is either VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR

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

If a VkSwapchainPresentScalingCreateInfoKHR structure was not included in the pNext chain, or it is included and VkSwapchainPresentScalingCreateInfoKHR::scalingBehavior is zero then 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-pNext-07782

If a VkSwapchainPresentScalingCreateInfoKHR structure was included in the pNext chain and VkSwapchainPresentScalingCreateInfoKHR::scalingBehavior is not zero then imageExtent must be between minScaledImageExtent and maxScaledImageExtent, inclusive, where minScaledImageExtent and maxScaledImageExtent are members of the VkSurfacePresentScalingCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilities2KHR for the surface and presentMode

VUID-VkSwapchainCreateInfoKHR-swapchainMaintenance1-10157

If the swapchainMaintenance1 feature is not enabled, then flags must not include VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR

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_FIFO_LATEST_READY_KHR, 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, imageUsagemust 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

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

VUID-VkSwapchainCreateInfoKHR-flags-03187

If flags contains VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR, then VkSurfaceProtectedCapabilitiesKHR::supportsProtectedmust be VK_TRUE in the VkSurfaceProtectedCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilities2KHR for surface

VUID-VkSwapchainCreateInfoKHR-pNext-02679

If the pNext chain includes a VkSurfaceFullScreenExclusiveInfoEXT structure with its fullScreenExclusive member set to VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, and surface was created using vkCreateWin32SurfaceKHR, a VkSurfaceFullScreenExclusiveWin32InfoEXT structure must be included in the pNext chain

VUID-VkSwapchainCreateInfoKHR-pNext-06752

If the imageCompressionControlSwapchain feature is not enabled, the pNext chain must not include an VkImageCompressionControlEXT structure

VUID-VkSwapchainCreateInfoKHR-presentTiming-12232

If none of the presentTiming, presentAtAbsoluteTime, or presentAtRelativeTime features are enabled, flags must not contain VK_SWAPCHAIN_CREATE_PRESENT_TIMING_BIT_EXT

Valid Usage (Implicit)

VUID-VkSwapchainCreateInfoKHR-sType-sType

sType must be VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR

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, VkImageCompressionControlEXT, VkImageFormatListCreateInfo, VkSurfaceFullScreenExclusiveInfoEXT, VkSurfaceFullScreenExclusiveWin32InfoEXT, VkSwapchainCounterCreateInfoEXT, VkSwapchainDisplayNativeHdrCreateInfoAMD, VkSwapchainLatencyCreateInfoNV, VkSwapchainPresentBarrierCreateInfoNV, VkSwapchainPresentModesCreateInfoKHR, or VkSwapchainPresentScalingCreateInfoKHR

Host Synchronization

Host access to surface must be externally synchronized
Host access to oldSwapchain must be externally synchronized

Parent

VK_KHR_swapchain

Type

Structures

Extended By

VkDeviceGroupSwapchainCreateInfoKHR VkImageCompressionControlEXT VkImageFormatListCreateInfo VkSurfaceFullScreenExclusiveInfoEXT VkSurfaceFullScreenExclusiveWin32InfoEXT VkSwapchainCounterCreateInfoEXT VkSwapchainDisplayNativeHdrCreateInfoAMD VkSwapchainLatencyCreateInfoNV VkSwapchainPresentBarrierCreateInfoNV VkSwapchainPresentModesCreateInfoKHR VkSwapchainPresentScalingCreateInfoKHR