vkCreateSwapchainKHR - Create a swapchain

Description

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

Note

This implicit transfer is intended to avoid exiting and entering full-screen exclusive mode, which may otherwise cause unwanted visual updates to the display.

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, ERROR_INITIALIZATION_FAILED will be returned.

Note

In particular, it will fail if the imageExtent member of pCreateInfo does not match the extents of the monitor. Other reasons for failure may include the app not being set as high-dpi aware, or if the physical device and monitor are not compatible in this mode.

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid SwapchainCreateInfoKHR structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pSwapchain must be a valid pointer to a SwapchainKHR handle

Host Synchronization

• Host access to pCreateInfo->surface must be externally synchronized

• Host access to pCreateInfo->oldSwapchain must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_DEVICE_LOST
• ERROR_SURFACE_LOST_KHR
• ERROR_NATIVE_WINDOW_IN_USE_KHR
• ERROR_INITIALIZATION_FAILED

See Also

AllocationCallbacks, Device, SwapchainCreateInfoKHR, SwapchainKHR

A convenience wrapper to make a compatible pair of calls to createSwapchainKHR and destroySwapchainKHR

To ensure that destroySwapchainKHR is always called: pass bracket (or the allocate function from your favourite resource management library) as the first argument. To just extract the pair pass (,) as the first argument.

vkDestroySwapchainKHR - Destroy a swapchain object

Description

The application must not destroy a swapchain until after completion of all outstanding operations on images that were acquired from the swapchain. swapchain and all associated Image handles are destroyed, and must not be acquired or used any more by the application. The memory of each Image will only be freed after that image is no longer used by the presentation engine. For example, if one image of the swapchain is being displayed in a window, the memory for that image may not be freed until the window is destroyed, or another swapchain is created for the window. Destroying the swapchain does not invalidate the parent SurfaceKHR, and a new swapchain can be created with it.

When a swapchain associated with a display surface is destroyed, if the image most recently presented to the display surface is from the swapchain being destroyed, then either any display resources modified by presenting images from any swapchain associated with the display surface must be reverted by the implementation to their state prior to the first present performed on one of these swapchains, or such resources must be left in their current state.

If swapchain has exclusive full-screen access, it is released before the swapchain is destroyed.

Valid Usage

• All uses of presentable images acquired from swapchain must have completed execution

• If AllocationCallbacks were provided when swapchain was created, a compatible set of callbacks must be provided here
• If no AllocationCallbacks were provided when swapchain was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• If swapchain is not NULL_HANDLE, swapchain must be a valid SwapchainKHR handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• Both of device, and swapchain that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Instance

Host Synchronization

• Host access to swapchain must be externally synchronized

See Also

AllocationCallbacks, Device, SwapchainKHR

vkGetSwapchainImagesKHR - Obtain the array of presentable images associated with a swapchain

Description

If pSwapchainImages is NULL, then the number of presentable images for swapchain is returned in pSwapchainImageCount. Otherwise, pSwapchainImageCount must point to a variable set by the user to the number of elements in the pSwapchainImages array, and on return the variable is overwritten with the number of structures actually written to pSwapchainImages. If the value of pSwapchainImageCount is less than the number of presentable images for swapchain, at most pSwapchainImageCount structures will be written. If pSwapchainImageCount is smaller than the number of presentable images for swapchain, INCOMPLETE will be returned instead of SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)

• device must be a valid Device handle

• swapchain must be a valid SwapchainKHR handle
• pSwapchainImageCount must be a valid pointer to a uint32_t value
• If the value referenced by pSwapchainImageCount is not 0, and pSwapchainImages is not NULL, pSwapchainImages must be a valid pointer to an array of pSwapchainImageCount Image handles
• Both of device, and swapchain must have been created, allocated, or retrieved from the same Instance

Return Codes

Success

• SUCCESS
• INCOMPLETE

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

Device, Image, SwapchainKHR

vkAcquireNextImageKHR - Retrieve the index of the next available presentable image

Valid Usage

• swapchain must not be in the retired state

• If semaphore is not NULL_HANDLE it must be unsignaled
• If semaphore is not NULL_HANDLE it must not have any uncompleted signal or wait operations pending
• If fence is not NULL_HANDLE it must be unsignaled and must not be associated with any other queue command that has not yet completed execution on that queue
• semaphore and fence must not both be equal to NULL_HANDLE
• If the number of currently acquired images is greater than the difference between the number of images in swapchain and the value of SurfaceCapabilitiesKHR::minImageCount as returned by a call to getPhysicalDeviceSurfaceCapabilities2KHR with the surface used to create swapchain, timeout must not be UINT64_MAX
• semaphore must have a SemaphoreType of SEMAPHORE_TYPE_BINARY

Valid Usage (Implicit)

• device must be a valid Device handle

• swapchain must be a valid SwapchainKHR handle
• If semaphore is not NULL_HANDLE, semaphore must be a valid Semaphore handle
• If fence is not NULL_HANDLE, fence must be a valid Fence handle
• pImageIndex must be a valid pointer to a uint32_t value
• If semaphore is a valid handle, it must have been created, allocated, or retrieved from device
• If fence is a valid handle, it must have been created, allocated, or retrieved from device
• Both of device, and swapchain that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Instance

Host Synchronization

• Host access to swapchain must be externally synchronized

• Host access to semaphore must be externally synchronized
• Host access to fence must be externally synchronized

Return Codes

Success

• SUCCESS
• TIMEOUT
• NOT_READY
• SUBOPTIMAL_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_DEVICE_LOST
• ERROR_OUT_OF_DATE_KHR
• ERROR_SURFACE_LOST_KHR
• ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

See Also

Device, Fence, Semaphore, SwapchainKHR

A variant of acquireNextImageKHR which makes a *safe* FFI call

vkQueuePresentKHR - Queue an image for presentation

Description

Note

There is no requirement for an application to present images in the same order that they were acquired - applications can arbitrarily present any image that is currently acquired.

Valid Usage

• Each element of pSwapchains member of pPresentInfo must be a swapchain that is created for a surface for which presentation is supported from queue as determined using a call to getPhysicalDeviceSurfaceSupportKHR

• If more than one member of pSwapchains was created from a display surface, all display surfaces referenced that refer to the same display must use the same display mode
• When a semaphore wait operation referring to a binary semaphore defined by the elements of the pWaitSemaphores member of pPresentInfo executes on queue, there must be no other queues waiting on the same semaphore
• All elements of the pWaitSemaphores member of pPresentInfo must be semaphores that are signaled, or have semaphore signal operations previously submitted for execution
• All elements of the pWaitSemaphores member of pPresentInfo must be created with a SemaphoreType of SEMAPHORE_TYPE_BINARY
• All elements of the pWaitSemaphores member of pPresentInfo must reference a semaphore signal operation that has been submitted for execution and any semaphore signal operations on which it depends (if any) must have also been submitted for execution

Any writes to memory backing the images referenced by the pImageIndices and pSwapchains members of pPresentInfo, that are available before queuePresentKHR is executed, are automatically made visible to the read access performed by the presentation engine. This automatic visibility operation for an image happens-after the semaphore signal operation, and happens-before the presentation engine accesses the image.

Queueing an image for presentation defines a set of queue operations, including waiting on the semaphores and submitting a presentation request to the presentation engine. However, the scope of this set of queue operations does not include the actual processing of the image by the presentation engine.

Note

The origin of the native orientation of the surface coordinate system is not specified in the Vulkan specification; it depends on the platform. For most platforms the origin is by default upper-left, meaning the pixel of the presented Image at coordinates (0,0) would appear at the upper left pixel of the platform surface (assuming SURFACE_TRANSFORM_IDENTITY_BIT_KHR, and the display standing the right way up).

If queuePresentKHR fails to enqueue the corresponding set of queue operations, it may return ERROR_OUT_OF_HOST_MEMORY or ERROR_OUT_OF_DEVICE_MEMORY. If it does, the implementation must ensure that the state and contents of any resources or synchronization primitives referenced is unaffected by the call or its failure.

If queuePresentKHR fails in such a way that the implementation is unable to make that guarantee, the implementation must return ERROR_DEVICE_LOST.

However, if the presentation request is rejected by the presentation engine with an error ERROR_OUT_OF_DATE_KHR, ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT, or ERROR_SURFACE_LOST_KHR, the set of queue operations are still considered to be enqueued and thus any semaphore wait operation specified in PresentInfoKHR will execute when the corresponding queue operation is complete.

If any swapchain member of pPresentInfo was created with FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT will be returned if that swapchain does not have exclusive full-screen access, possibly for implementation-specific reasons outside of the application’s control.

Valid Usage (Implicit)

• queue must be a valid Queue handle

• pPresentInfo must be a valid pointer to a valid PresentInfoKHR structure

Host Synchronization

• Host access to queue must be externally synchronized

• Host access to pPresentInfo->pWaitSemaphores[] must be externally synchronized
• Host access to pPresentInfo->pSwapchains[] must be externally synchronized

Command Properties

'

Return Codes

Success

• SUCCESS
• SUBOPTIMAL_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_DEVICE_LOST
• ERROR_OUT_OF_DATE_KHR
• ERROR_SURFACE_LOST_KHR
• ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

See Also

PresentInfoKHR, Queue

vkGetDeviceGroupPresentCapabilitiesKHR - Query present capabilities from other physical devices

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

Device, DeviceGroupPresentCapabilitiesKHR

vkGetDeviceGroupSurfacePresentModesKHR - Query present capabilities for a surface

Description

The modes returned by this command are not invariant, and may change in response to the surface being moved, resized, or occluded. These modes must be a subset of the modes returned by getDeviceGroupPresentCapabilitiesKHR.

Valid Usage (Implicit)

• device must be a valid Device handle

• surface must be a valid SurfaceKHR handle
• pModes must be a valid pointer to a DeviceGroupPresentModeFlagsKHR value
• Both of device, and surface must have been created, allocated, or retrieved from the same Instance

Host Synchronization

• Host access to surface must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_SURFACE_LOST_KHR

See Also

Device, DeviceGroupPresentModeFlagsKHR, SurfaceKHR

vkAcquireNextImage2KHR - Retrieve the index of the next available presentable image

Valid Usage

• If the number of currently acquired images is greater than the difference between the number of images in the swapchain member of pAcquireInfo and the value of SurfaceCapabilitiesKHR::minImageCount as returned by a call to getPhysicalDeviceSurfaceCapabilities2KHR with the surface used to create swapchain, the timeout member of pAcquireInfo must not be UINT64_MAX

Valid Usage (Implicit)

• device must be a valid Device handle

• pAcquireInfo must be a valid pointer to a valid AcquireNextImageInfoKHR structure
• pImageIndex must be a valid pointer to a uint32_t value

Return Codes

Success

• SUCCESS
• TIMEOUT
• NOT_READY
• SUBOPTIMAL_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_DEVICE_LOST
• ERROR_OUT_OF_DATE_KHR
• ERROR_SURFACE_LOST_KHR
• ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

See Also

AcquireNextImageInfoKHR, Device

A variant of acquireNextImage2KHR which makes a *safe* FFI call

vkGetPhysicalDevicePresentRectanglesKHR - Query present rectangles for a surface on a physical device

Description

If pRects is NULL, then the number of rectangles used when presenting the given surface is returned in pRectCount. Otherwise, pRectCount must point to a variable set by the user to the number of elements in the pRects array, and on return the variable is overwritten with the number of structures actually written to pRects. If the value of pRectCount is less than the number of rectangles, at most pRectCount structures will be written. If pRectCount is smaller than the number of rectangles used for the given surface, INCOMPLETE will be returned instead of SUCCESS to indicate that not all the available values were returned.

The values returned by this command are not invariant, and may change in response to the surface being moved, resized, or occluded.

The rectangles returned by this command must not overlap.

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• surface must be a valid SurfaceKHR handle
• pRectCount must be a valid pointer to a uint32_t value
• If the value referenced by pRectCount is not 0, and pRects is not NULL, pRects must be a valid pointer to an array of pRectCount Rect2D structures
• Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same Instance

Host Synchronization

• Host access to surface must be externally synchronized

Return Codes

Success

• SUCCESS
• INCOMPLETE

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

PhysicalDevice, Rect2D, SurfaceKHR

VkSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object

Description

Note

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 ImageUsageFlagBits 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 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 SHARING_MODE_CONCURRENT.
• preTransform is a SurfaceTransformFlagBitsKHR 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 getPhysicalDeviceSurfaceCapabilitiesKHR, the presentation engine will transform the image content as part of the presentation operation.
• compositeAlpha is a CompositeAlphaFlagBitsKHR 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 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. TRUE value does not guarantee any clipping will occur, but allows more optimal presentation methods to be used on some platforms.
  • If set to FALSE, presentable images associated with the swapchain will own all of the pixels they contain.

Note

Applications should set this value to 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 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 createSwapchainKHR with an oldSwapchain that is not 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 NULL_HANDLE.

Upon calling createSwapchainKHR with an oldSwapchain that is not 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.

Note

Multiple retired swapchains can be associated with the same SurfaceKHR through multiple uses of oldSwapchain that outnumber calls to destroySwapchainKHR.

After oldSwapchain is retired, the application can pass to queuePresentKHR 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, queuePresentKHR may fail if oldSwapchain has entered a state that causes 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 ERROR_OUT_OF_DATE_KHR.

Valid Usage

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

• minImageCount must be less than or equal to the value returned in the maxImageCount member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface if the returned maxImageCount is not zero
• If presentMode is not PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR nor PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, then minImageCount must be greater than or equal to the value returned in the minImageCount member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface
• minImageCount must be 1 if presentMode is either PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
• imageFormat and imageColorSpace must match the format and colorSpace members, respectively, of one of the SurfaceFormatKHR structures returned by getPhysicalDeviceSurfaceFormatsKHR for the surface
• imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface
• imageExtent members width and height must both be non-zero
• imageArrayLayers must be greater than 0 and less than or equal to the maxImageArrayLayers member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface
• If presentMode is PRESENT_MODE_IMMEDIATE_KHR, PRESENT_MODE_MAILBOX_KHR, PRESENT_MODE_FIFO_KHR or PRESENT_MODE_FIFO_RELAXED_KHR, imageUsage must be a subset of the supported usage flags present in the supportedUsageFlags member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for surface
• If presentMode is PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, imageUsage must be a subset of the supported usage flags present in the sharedPresentSupportedUsageFlags member of the SharedPresentSurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilities2KHR for surface
• If imageSharingMode is SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values
• If imageSharingMode is SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1
• If imageSharingMode is SHARING_MODE_CONCURRENT, each element of pQueueFamilyIndices must be unique and must be less than pQueueFamilyPropertyCount returned by either getPhysicalDeviceQueueFamilyProperties or getPhysicalDeviceQueueFamilyProperties2 for the physicalDevice that was used to create device
• preTransform must be one of the bits present in the supportedTransforms member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface
• compositeAlpha must be one of the bits present in the supportedCompositeAlpha member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface
• presentMode must be one of the PresentModeKHR values returned by getPhysicalDeviceSurfacePresentModesKHR for the surface
• If the logical device was created with DeviceGroupDeviceCreateInfo::physicalDeviceCount equal to 1, flags must not contain SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
• If oldSwapchain is not NULL_HANDLE, oldSwapchain must be a non-retired swapchain associated with native window referred to by surface
• The implied image creation parameters of the swapchain must be supported as reported by getPhysicalDeviceImageFormatProperties
• If flags contains SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR then the pNext chain must include a ImageFormatListCreateInfo structure with a viewFormatCount greater than zero and pViewFormats must have an element equal to imageFormat
• If a ImageFormatListCreateInfo structure was included in the pNext chain and ImageFormatListCreateInfo::viewFormatCount is not zero then all of the formats in ImageFormatListCreateInfo::pViewFormats must be compatible with the format as described in the compatibility table
• If flags dose not contain SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR and the pNext chain include a ImageFormatListCreateInfo structure then ImageFormatListCreateInfo::viewFormatCount must be 0 or 1
• If flags contains SWAPCHAIN_CREATE_PROTECTED_BIT_KHR, then SurfaceProtectedCapabilitiesKHR::supportsProtected must be TRUE in the SurfaceProtectedCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilities2KHR for surface
• If the pNext chain includes a SurfaceFullScreenExclusiveInfoEXT structure with its fullScreenExclusive member set to FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, and surface was created using createWin32SurfaceKHR, a SurfaceFullScreenExclusiveWin32InfoEXT structure must be included in the pNext chain

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR

• 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 DeviceGroupSwapchainCreateInfoKHR, ImageFormatListCreateInfo, SurfaceFullScreenExclusiveInfoEXT, SurfaceFullScreenExclusiveWin32InfoEXT, SwapchainCounterCreateInfoEXT, or SwapchainDisplayNativeHdrCreateInfoAMD
• The sType value of each struct in the pNext chain must be unique
• flags must be a valid combination of SwapchainCreateFlagBitsKHR values
• surface must be a valid SurfaceKHR handle
• imageFormat must be a valid Format value
• imageColorSpace must be a valid ColorSpaceKHR value
• imageUsage must be a valid combination of ImageUsageFlagBits values
• imageUsage must not be 0
• imageSharingMode must be a valid SharingMode value
• preTransform must be a valid SurfaceTransformFlagBitsKHR value
• compositeAlpha must be a valid CompositeAlphaFlagBitsKHR value
• presentMode must be a valid PresentModeKHR value
• If oldSwapchain is not NULL_HANDLE, oldSwapchain must be a valid SwapchainKHR handle
• If oldSwapchain is a valid handle, it must have been created, allocated, or retrieved from surface
• Both of oldSwapchain, and surface that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Instance

See Also

Bool32, ColorSpaceKHR, CompositeAlphaFlagBitsKHR, Extent2D, Format, ImageUsageFlags, PresentModeKHR, SharingMode, StructureType, SurfaceKHR, SurfaceTransformFlagBitsKHR, SwapchainCreateFlagsKHR, SwapchainKHR, createSharedSwapchainsKHR, createSwapchainKHR

VkPresentInfoKHR - Structure describing parameters of a queue presentation

Description

Before an application can present an image, the image’s layout must be transitioned to the IMAGE_LAYOUT_PRESENT_SRC_KHR layout, or for a shared presentable image the IMAGE_LAYOUT_SHARED_PRESENT_KHR layout.

Note

When transitioning the image to IMAGE_LAYOUT_SHARED_PRESENT_KHR or IMAGE_LAYOUT_PRESENT_SRC_KHR, there is no need to delay subsequent processing, or perform any visibility operations (as queuePresentKHR performs automatic visibility operations). To achieve this, the dstAccessMask member of the ImageMemoryBarrier should be set to 0, and the dstStageMask parameter should be set to PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT.

Valid Usage

• Each element of pImageIndices must be the index of a presentable image acquired from the swapchain specified by the corresponding element of the pSwapchains array, and the presented image subresource must be in the IMAGE_LAYOUT_PRESENT_SRC_KHR or IMAGE_LAYOUT_SHARED_PRESENT_KHR layout at the time the operation is executed on a Device

• All elements of the pWaitSemaphores must have a SemaphoreType of SEMAPHORE_TYPE_BINARY

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PRESENT_INFO_KHR

• 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 DeviceGroupPresentInfoKHR, DisplayPresentInfoKHR, PresentFrameTokenGGP, PresentRegionsKHR, or PresentTimesInfoGOOGLE
• The sType value of each struct in the pNext chain must be unique
• If waitSemaphoreCount is not 0, pWaitSemaphores must be a valid pointer to an array of waitSemaphoreCount valid Semaphore handles
• pSwapchains must be a valid pointer to an array of swapchainCount valid SwapchainKHR handles
• pImageIndices must be a valid pointer to an array of swapchainCount uint32_t values
• If pResults is not NULL, pResults must be a valid pointer to an array of swapchainCount Result values
• swapchainCount must be greater than 0
• Both of the elements of pSwapchains, and the elements of pWaitSemaphores that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Instance

See Also

Result, Semaphore, StructureType, SwapchainKHR, queuePresentKHR

VkDeviceGroupPresentCapabilitiesKHR - Present capabilities from other physical devices

Description

modes always has DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR set.

The present mode flags are also used when presenting an image, in DeviceGroupPresentInfoKHR::mode.

If a device group only includes a single physical device, then modes must equal DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.

Valid Usage (Implicit)

See Also

DeviceGroupPresentModeFlagsKHR, StructureType, getDeviceGroupPresentCapabilitiesKHR

VkImageSwapchainCreateInfoKHR - Specify that an image will be bound to swapchain memory

Valid Usage

• If swapchain is not NULL_HANDLE, the fields of ImageCreateInfo must match the implied image creation parameters of the swapchain

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR

• If swapchain is not NULL_HANDLE, swapchain must be a valid SwapchainKHR handle

See Also

StructureType, SwapchainKHR

VkBindImageMemorySwapchainInfoKHR - Structure specifying swapchain image memory to bind to

Description

If swapchain is not NULL, the swapchain and imageIndex are used to determine the memory that the image is bound to, instead of memory and memoryOffset.

Memory can be bound to a swapchain and use the pDeviceIndices or pSplitInstanceBindRegions members of BindImageMemoryDeviceGroupInfo.

Valid Usage

• imageIndex must be less than the number of images in swapchain

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR

• swapchain must be a valid SwapchainKHR handle

Host Synchronization

• Host access to swapchain must be externally synchronized

See Also

StructureType, SwapchainKHR

VkAcquireNextImageInfoKHR - Structure specifying parameters of the acquire

Description

If acquireNextImageKHR is used, the device mask is considered to include all physical devices in the logical device.

Note

acquireNextImage2KHR signals at most one semaphore, even if the application requests waiting for multiple physical devices to be ready via the deviceMask. However, only a single physical device can wait on that semaphore, since the semaphore becomes unsignaled when the wait succeeds. For other physical devices to wait for the image to be ready, it is necessary for the application to submit semaphore signal operation(s) to that first physical device to signal additional semaphore(s) after the wait succeeds, which the other physical device(s) can wait upon.

Valid Usage

• swapchain must not be in the retired state

• If semaphore is not NULL_HANDLE it must be unsignaled
• If semaphore is not NULL_HANDLE it must not have any uncompleted signal or wait operations pending
• If fence is not NULL_HANDLE it must be unsignaled and must not be associated with any other queue command that has not yet completed execution on that queue
• semaphore and fence must not both be equal to NULL_HANDLE
• deviceMask must be a valid device mask
• deviceMask must not be zero
• semaphore must have a SemaphoreType of SEMAPHORE_TYPE_BINARY

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR

• pNext must be NULL
• swapchain must be a valid SwapchainKHR handle
• If semaphore is not NULL_HANDLE, semaphore must be a valid Semaphore handle
• If fence is not NULL_HANDLE, fence must be a valid Fence handle
• Each of fence, semaphore, and swapchain that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Instance

Host Synchronization

• Host access to swapchain must be externally synchronized

• Host access to semaphore must be externally synchronized
• Host access to fence must be externally synchronized

See Also

Fence, Semaphore, StructureType, SwapchainKHR, acquireNextImage2KHR

VkDeviceGroupPresentInfoKHR - Mode and mask controlling which physical devices' images are presented

Description

If mode is DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then each element of pDeviceMasks selects which instance of the swapchain image is presented. Each element of pDeviceMasks must have exactly one bit set, and the corresponding physical device must have a presentation engine as reported by DeviceGroupPresentCapabilitiesKHR.

If mode is DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, then each element of pDeviceMasks selects which instance of the swapchain image is presented. Each element of pDeviceMasks must have exactly one bit set, and some physical device in the logical device must include that bit in its DeviceGroupPresentCapabilitiesKHR::presentMask.

If mode is DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then each element of pDeviceMasks selects which instances of the swapchain image are component-wise summed and the sum of those images is presented. If the sum in any component is outside the representable range, the value of that component is undefined. Each element of pDeviceMasks must have a value for which all set bits are set in one of the elements of DeviceGroupPresentCapabilitiesKHR::presentMask.

If mode is DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then each element of pDeviceMasks selects which instance(s) of the swapchain images are presented. For each bit set in each element of pDeviceMasks, the corresponding physical device must have a presentation engine as reported by DeviceGroupPresentCapabilitiesKHR.

If DeviceGroupPresentInfoKHR is not provided or swapchainCount is zero then the masks are considered to be 1. If DeviceGroupPresentInfoKHR is not provided, mode is considered to be DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.

Valid Usage

• swapchainCount must equal 0 or PresentInfoKHR::swapchainCount

• If mode is DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then each element of pDeviceMasks must have exactly one bit set, and the corresponding element of DeviceGroupPresentCapabilitiesKHR::presentMask must be non-zero
• If mode is DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, then each element of pDeviceMasks must have exactly one bit set, and some physical device in the logical device must include that bit in its DeviceGroupPresentCapabilitiesKHR::presentMask
• If mode is DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then each element of pDeviceMasks must have a value for which all set bits are set in one of the elements of DeviceGroupPresentCapabilitiesKHR::presentMask
• If mode is DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then for each bit set in each element of pDeviceMasks, the corresponding element of DeviceGroupPresentCapabilitiesKHR::presentMask must be non-zero
• The value of each element of pDeviceMasks must be equal to the device mask passed in AcquireNextImageInfoKHR::deviceMask when the image index was last acquired
• mode must have exactly one bit set, and that bit must have been included in DeviceGroupSwapchainCreateInfoKHR::modes

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR

• If swapchainCount is not 0, pDeviceMasks must be a valid pointer to an array of swapchainCount uint32_t values
• mode must be a valid DeviceGroupPresentModeFlagBitsKHR value

See Also

DeviceGroupPresentModeFlagBitsKHR, StructureType

VkDeviceGroupSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object

Description

If this structure is not present, modes is considered to be DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.

Valid Usage (Implicit)

See Also

DeviceGroupPresentModeFlagsKHR, StructureType

VkDeviceGroupPresentModeFlagBitsKHR - Bitmask specifying supported device group present modes

See Also

DeviceGroupPresentInfoKHR, DeviceGroupPresentModeFlagsKHR

VkSwapchainCreateFlagBitsKHR - Bitmask controlling swapchain creation

See Also

SwapchainCreateFlagsKHR

VkSurfaceKHR - Opaque handle to a surface object

Description

The VK_KHR_surface extension declares the SurfaceKHR object, and provides a function for destroying SurfaceKHR objects. Separate platform-specific extensions each provide a function for creating a SurfaceKHR object for the respective platform. From the application’s perspective this is an opaque handle, just like the handles of other Vulkan objects.

See Also

PhysicalDeviceSurfaceInfo2KHR, SwapchainCreateInfoKHR, createAndroidSurfaceKHR, createDirectFBSurfaceEXT, createDisplayPlaneSurfaceKHR, createHeadlessSurfaceEXT, createIOSSurfaceMVK, createImagePipeSurfaceFUCHSIA, createMacOSSurfaceMVK, createMetalSurfaceEXT, createStreamDescriptorSurfaceGGP, createViSurfaceNN, createWaylandSurfaceKHR, createWin32SurfaceKHR, createXcbSurfaceKHR, createXlibSurfaceKHR, destroySurfaceKHR, getDeviceGroupSurfacePresentModesKHR, getPhysicalDevicePresentRectanglesKHR, getPhysicalDeviceSurfaceCapabilities2EXT, getPhysicalDeviceSurfaceCapabilitiesKHR, getPhysicalDeviceSurfaceFormatsKHR, getPhysicalDeviceSurfacePresentModesKHR, getPhysicalDeviceSurfaceSupportKHR

VkSwapchainKHR - Opaque handle to a swapchain object

Description

A swapchain is an abstraction for an array of presentable images that are associated with a surface. The presentable images are represented by Image objects created by the platform. One image (which can be an array image for multiview/stereoscopic-3D surfaces) is displayed at a time, but multiple images can be queued for presentation. An application renders to the image, and then queues the image for presentation to the surface.

A native window cannot be associated with more than one non-retired swapchain at a time. Further, swapchains cannot be created for native windows that have a non-Vulkan graphics API surface associated with them.

Note

The presentation engine is an abstraction for the platform’s compositor or display engine.

The presentation engine may be synchronous or asynchronous with respect to the application and/or logical device.

Some implementations may use the device’s graphics queue or dedicated presentation hardware to perform presentation.

The presentable images of a swapchain are owned by the presentation engine. An application can acquire use of a presentable image from the presentation engine. Use of a presentable image must occur only after the image is returned by acquireNextImageKHR, and before it is presented by queuePresentKHR. This includes transitioning the image layout and rendering commands.

An application can acquire use of a presentable image with acquireNextImageKHR. After acquiring a presentable image and before modifying it, the application must use a synchronization primitive to ensure that the presentation engine has finished reading from the image. The application can then transition the image’s layout, queue rendering commands to it, etc. Finally, the application presents the image with queuePresentKHR, which releases the acquisition of the image.

The presentation engine controls the order in which presentable images are acquired for use by the application.

Note

This allows the platform to handle situations which require out-of-order return of images after presentation. At the same time, it allows the application to generate command buffers referencing all of the images in the swapchain at initialization time, rather than in its main loop.

See Also

AcquireNextImageInfoKHR, BindImageMemorySwapchainInfoKHR, ImageSwapchainCreateInfoKHR, PresentInfoKHR, SwapchainCreateInfoKHR, acquireFullScreenExclusiveModeEXT, acquireNextImageKHR, createSharedSwapchainsKHR, createSwapchainKHR, destroySwapchainKHR, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLocalDimmingAMD

VkPresentModeKHR - presentation mode supported for a surface

Description

The supported ImageUsageFlagBits of the presentable images of a swapchain created for a surface may differ depending on the presentation mode, and can be determined as per the table below:

Presentable image usage queries

Note

For reference, the mode indicated by PRESENT_MODE_FIFO_KHR is equivalent to the behavior of {wgl|glX|egl}SwapBuffers with a swap interval of 1, while the mode indicated by PRESENT_MODE_FIFO_RELAXED_KHR is equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval of -1 (from the {WGL|GLX}_EXT_swap_control_tear extensions).

See Also

SwapchainCreateInfoKHR, getPhysicalDeviceSurfacePresentModes2EXT, getPhysicalDeviceSurfacePresentModesKHR

VkColorSpaceKHR - supported color space of the presentation engine

Description

Note

In the initial release of the VK_KHR_surface and VK_KHR_swapchain extensions, the token VK_COLORSPACE_SRGB_NONLINEAR_KHR was used. Starting in the 2016-05-13 updates to the extension branches, matching release 1.0.13 of the core API specification, COLOR_SPACE_SRGB_NONLINEAR_KHR is used instead for consistency with Vulkan naming rules. The older enum is still available for backwards compatibility.