32. Window System Integration (WSI)

This chapter discusses the window system integration (WSI) between the Vulkan API and the various forms of displaying the results of rendering to a user. Since the Vulkan API can be used without displaying results, WSI is provided through the use of optional Vulkan extensions. This chapter provides an overview of WSI. See the appendix for additional details of each WSI extension, including which extensions must be enabled in order to use each of the functions described in this chapter.

32.1. WSI Platform

A platform is an abstraction for a window system, OS, etc. Some examples include MS Windows, Android, and Wayland. The Vulkan API may be integrated in a unique manner for each platform.

The Vulkan API does not define any type of platform object. Platform-specific WSI extensions are defined, each containing platform-specific functions for using WSI. Use of these extensions is guarded by preprocessor symbols as defined in the Window System-Specific Header Control appendix.

In order for an application to be compiled to use WSI with a given platform, it must either:

  • #define the appropriate preprocessor symbol prior to including the vulkan.h header file, or

  • include vulkan_core.h and any native platform headers, followed by the appropriate platform-specific header.

The preprocessor symbols and platform-specific headers are defined in the Window System Extensions and Headers table.

Each platform-specific extension is an instance extension. The application must enable instance extensions with vkCreateInstance before using them.

32.2. WSI Surface

Native platform surface or window objects are abstracted by surface objects, which are represented by VkSurfaceKHR handles:

// Provided by VK_KHR_surface
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR)

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

Note

On certain platforms, the Vulkan loader and ICDs may have conventions that treat the handle as a pointer to a structure containing the platform-specific information about the surface. This will be described in the documentation for the loader-ICD interface, and in the vk_icd.h header file of the LoaderAndTools source-code repository. This does not affect the loader-layer interface; layers may wrap VkSurfaceKHR objects.
editing-note

TODO: Consider replacing the above note editing note with a pointer to the loader spec when it exists. However, the information is not relevant to users of the API nor does it affect conformance of a Vulkan implementation to this spec.

32.2.1. Android Platform

To create a VkSurfaceKHR object for an Android native window, call:

// Provided by VK_KHR_android_surface
VkResult vkCreateAndroidSurfaceKHR(
    VkInstance                                  instance,
    const VkAndroidSurfaceCreateInfoKHR*        pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance to associate the surface with.

  • pCreateInfo is a pointer to a VkAndroidSurfaceCreateInfoKHR structure containing parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

During the lifetime of a surface created using a particular ANativeWindow handle any attempts to create another surface for the same ANativeWindow and any attempts to connect to the same ANativeWindow through other platform mechanisms will fail.

Note

In particular, only one VkSurfaceKHR can exist at a time for a given window. Similarly, a native window cannot be used by both a VkSurfaceKHR and EGLSurface simultaneously.

If successful, vkCreateAndroidSurfaceKHR increments the ANativeWindow’s reference count, and vkDestroySurfaceKHR will decrement it.

On Android, when a swapchain’s imageExtent does not match the surface’s currentExtent, the presentable images will be scaled to the surface’s dimensions during presentation. minImageExtent is (1,1), and maxImageExtent is the maximum image size supported by the consumer. For the system compositor, currentExtent is the window size (i.e. the consumer’s preferred size).

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_NATIVE_WINDOW_IN_USE_KHR

The VkAndroidSurfaceCreateInfoKHR structure is defined as:

// Provided by VK_KHR_android_surface
typedef struct VkAndroidSurfaceCreateInfoKHR {
    VkStructureType                   sType;
    const void*                       pNext;
    VkAndroidSurfaceCreateFlagsKHR    flags;
    struct ANativeWindow*             window;
} VkAndroidSurfaceCreateInfoKHR;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • window is a pointer to the ANativeWindow to associate the surface with.

Valid Usage

  • window must point to a valid Android ANativeWindow

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR

  • pNext must be NULL

  • flags must be 0

To remove an unnecessary compile-time dependency, an incomplete type definition of ANativeWindow is provided in the Vulkan headers:

// Provided by VK_KHR_android_surface
struct ANativeWindow;

The actual ANativeWindow type is defined in Android NDK headers.

// Provided by VK_KHR_android_surface
typedef VkFlags VkAndroidSurfaceCreateFlagsKHR;

VkAndroidSurfaceCreateFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.2. Wayland Platform

To create a VkSurfaceKHR object for a Wayland surface, call:

// Provided by VK_KHR_wayland_surface
VkResult vkCreateWaylandSurfaceKHR(
    VkInstance                                  instance,
    const VkWaylandSurfaceCreateInfoKHR*        pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance to associate the surface with.

  • pCreateInfo is a pointer to a VkWaylandSurfaceCreateInfoKHR structure containing parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkWaylandSurfaceCreateInfoKHR structure is defined as:

// Provided by VK_KHR_wayland_surface
typedef struct VkWaylandSurfaceCreateInfoKHR {
    VkStructureType                   sType;
    const void*                       pNext;
    VkWaylandSurfaceCreateFlagsKHR    flags;
    struct wl_display*                display;
    struct wl_surface*                surface;
} VkWaylandSurfaceCreateInfoKHR;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • display and surface are pointers to the Wayland wl_display and wl_surface to associate the surface with.

Valid Usage

  • display must point to a valid Wayland wl_display

  • surface must point to a valid Wayland wl_surface

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR

  • pNext must be NULL

  • flags must be 0

On Wayland, currentExtent is the special value (0xFFFFFFFF, 0xFFFFFFFF), indicating that the surface size will be determined by the extent of a swapchain targeting the surface. Whatever the application sets a swapchain’s imageExtent to will be the size of the window, after the first image is presented. minImageExtent is (1,1), and maxImageExtent is the maximum supported surface size. Any calls to vkGetPhysicalDeviceSurfacePresentModesKHR on a surface created with vkCreateWaylandSurfaceKHR are required to return VK_PRESENT_MODE_MAILBOX_KHR as one of the valid present modes.

Some Vulkan functions may send protocol over the specified wl_display connection when using a swapchain or presentable images created from a VkSurfaceKHR referring to a wl_surface. Applications must therefore ensure that both the wl_display and the wl_surface remain valid for the lifetime of any VkSwapchainKHR objects created from a particular wl_display and wl_surface. Also, calling vkQueuePresentKHR will result in Vulkan sending wl_surface.commit requests to the underlying wl_surface of each VkSwapchainKHR objects referenced by pPresentInfo. If the swapchain is created with a present mode of VK_PRESENT_MODE_MAILBOX_KHR or VK_PRESENT_MODE_IMMEDIATE_KHR, then the corresponding wl_surface.attach, wl_surface.damage, and wl_surface.commit request must be issued by the implementation during the call to vkQueuePresentKHR and must not be issued by the implementation outside of vkQueuePresentKHR. This ensures that any Wayland requests sent by the client after the call to vkQueuePresentKHR returns will be received by the compositor after the wl_surface.commit. Regardless of the mode of swapchain creation, a new wl_event_queue must be created for each successful vkCreateWaylandSurfaceKHR call, and every Wayland object created by the implementation must be assigned to this event queue. If the platform provides Wayland 1.11 or greater, this must be implemented by the use of Wayland proxy object wrappers, to avoid race conditions.

If the application wishes to synchronize any window changes with a particular frame, such requests must be sent to the Wayland display server prior to calling vkQueuePresentKHR. For full control over interactions between Vulkan rendering and other Wayland protocol requests and events, a present mode of VK_PRESENT_MODE_MAILBOX_KHR should be used.

// Provided by VK_KHR_wayland_surface
typedef VkFlags VkWaylandSurfaceCreateFlagsKHR;

VkWaylandSurfaceCreateFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.3. Win32 Platform

To create a VkSurfaceKHR object for a Win32 window, call:

// Provided by VK_KHR_win32_surface
VkResult vkCreateWin32SurfaceKHR(
    VkInstance                                  instance,
    const VkWin32SurfaceCreateInfoKHR*          pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance to associate the surface with.

  • pCreateInfo is a pointer to a VkWin32SurfaceCreateInfoKHR structure containing parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkWin32SurfaceCreateInfoKHR structure is defined as:

// Provided by VK_KHR_win32_surface
typedef struct VkWin32SurfaceCreateInfoKHR {
    VkStructureType                 sType;
    const void*                     pNext;
    VkWin32SurfaceCreateFlagsKHR    flags;
    HINSTANCE                       hinstance;
    HWND                            hwnd;
} VkWin32SurfaceCreateInfoKHR;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • hinstance is the Win32 HINSTANCE for the window to associate the surface with.

  • hwnd is the Win32 HWND for the window to associate the surface with.

Valid Usage

  • hinstance must be a valid Win32 HINSTANCE

  • hwnd must be a valid Win32 HWND

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR

  • pNext must be NULL

  • flags must be 0

With Win32, minImageExtent, maxImageExtent, and currentExtent must always equal the window size.

The currentExtent of a Win32 surface must have both width and height greater than 0, or both of them 0.

Note

Due to above restrictions, it is only possible to create a new swapchain on this platform with imageExtent being equal to the current size of the window.

The window size may become (0, 0) on this platform (e.g. when the window is minimized), and so a swapchain cannot be created until the size changes.

 
// Provided by VK_KHR_win32_surface
typedef VkFlags VkWin32SurfaceCreateFlagsKHR;

VkWin32SurfaceCreateFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.4. XCB Platform

To create a VkSurfaceKHR object for an X11 window, using the XCB client-side library, call:

// Provided by VK_KHR_xcb_surface
VkResult vkCreateXcbSurfaceKHR(
    VkInstance                                  instance,
    const VkXcbSurfaceCreateInfoKHR*            pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance to associate the surface with.

  • pCreateInfo is a pointer to a VkXcbSurfaceCreateInfoKHR structure containing parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkXcbSurfaceCreateInfoKHR structure is defined as:

// Provided by VK_KHR_xcb_surface
typedef struct VkXcbSurfaceCreateInfoKHR {
    VkStructureType               sType;
    const void*                   pNext;
    VkXcbSurfaceCreateFlagsKHR    flags;
    xcb_connection_t*             connection;
    xcb_window_t                  window;
} VkXcbSurfaceCreateInfoKHR;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • connection is a pointer to an xcb_connection_t to the X server.

  • window is the xcb_window_t for the X11 window to associate the surface with.

Valid Usage

  • connection must point to a valid X11 xcb_connection_t

  • window must be a valid X11 xcb_window_t

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_XCB_SURFACE_CREATE_INFO_KHR

  • pNext must be NULL

  • flags must be 0

With Xcb, minImageExtent, maxImageExtent, and currentExtent must always equal the window size.

The currentExtent of an Xcb surface must have both width and height greater than 0, or both of them 0.

Note

Due to above restrictions, it is only possible to create a new swapchain on this platform with imageExtent being equal to the current size of the window.

The window size may become (0, 0) on this platform (e.g. when the window is minimized), and so a swapchain cannot be created until the size changes.

Some Vulkan functions may send protocol over the specified xcb connection when using a swapchain or presentable images created from a VkSurfaceKHR referring to an xcb window. Applications must therefore ensure the xcb connection is available to Vulkan for the duration of any functions that manipulate such swapchains or their presentable images, and any functions that build or queue command buffers that operate on such presentable images. Specifically, applications using Vulkan with xcb-based swapchains must

  • Avoid holding a server grab on an xcb connection while waiting for Vulkan operations to complete using a swapchain derived from a different xcb connection referring to the same X server instance. Failing to do so may result in deadlock.

// Provided by VK_KHR_xcb_surface
typedef VkFlags VkXcbSurfaceCreateFlagsKHR;

VkXcbSurfaceCreateFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.5. Xlib Platform

To create a VkSurfaceKHR object for an X11 window, using the Xlib client-side library, call:

// Provided by VK_KHR_xlib_surface
VkResult vkCreateXlibSurfaceKHR(
    VkInstance                                  instance,
    const VkXlibSurfaceCreateInfoKHR*           pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance to associate the surface with.

  • pCreateInfo is a pointer to a VkXlibSurfaceCreateInfoKHR structure containing the parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkXlibSurfaceCreateInfoKHR structure is defined as:

// Provided by VK_KHR_xlib_surface
typedef struct VkXlibSurfaceCreateInfoKHR {
    VkStructureType                sType;
    const void*                    pNext;
    VkXlibSurfaceCreateFlagsKHR    flags;
    Display*                       dpy;
    Window                         window;
} VkXlibSurfaceCreateInfoKHR;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • dpy is a pointer to an Xlib Display connection to the X server.

  • window is an Xlib Window to associate the surface with.

Valid Usage

  • dpy must point to a valid Xlib Display

  • window must be a valid Xlib Window

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR

  • pNext must be NULL

  • flags must be 0

With Xlib, minImageExtent, maxImageExtent, and currentExtent must always equal the window size.

The currentExtent of an Xlib surface must have both width and height greater than 0, or both of them 0.

Note

Due to above restrictions, it is only possible to create a new swapchain on this platform with imageExtent being equal to the current size of the window.

The window size may become (0, 0) on this platform (e.g. when the window is minimized), and so a swapchain cannot be created until the size changes.

Some Vulkan functions may send protocol over the specified Xlib Display connection when using a swapchain or presentable images created from a VkSurfaceKHR referring to an Xlib window. Applications must therefore ensure the display connection is available to Vulkan for the duration of any functions that manipulate such swapchains or their presentable images, and any functions that build or queue command buffers that operate on such presentable images. Specifically, applications using Vulkan with Xlib-based swapchains must

  • Avoid holding a server grab on a display connection while waiting for Vulkan operations to complete using a swapchain derived from a different display connection referring to the same X server instance. Failing to do so may result in deadlock.

Some implementations may require threads to implement some presentation modes so applications must call XInitThreads() before calling any other Xlib functions.

// Provided by VK_KHR_xlib_surface
typedef VkFlags VkXlibSurfaceCreateFlagsKHR;

VkXlibSurfaceCreateFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.6. DirectFB Platform

To create a VkSurfaceKHR object for a DirectFB surface, call:

// Provided by VK_EXT_directfb_surface
VkResult vkCreateDirectFBSurfaceEXT(
    VkInstance                                  instance,
    const VkDirectFBSurfaceCreateInfoEXT*       pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance to associate the surface with.

  • pCreateInfo is a pointer to a VkDirectFBSurfaceCreateInfoEXT structure containing parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDirectFBSurfaceCreateInfoEXT structure is defined as:

// Provided by VK_EXT_directfb_surface
typedef struct VkDirectFBSurfaceCreateInfoEXT {
    VkStructureType                    sType;
    const void*                        pNext;
    VkDirectFBSurfaceCreateFlagsEXT    flags;
    IDirectFB*                         dfb;
    IDirectFBSurface*                  surface;
} VkDirectFBSurfaceCreateInfoEXT;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • dfb is a pointer to the IDirectFB main interface of DirectFB.

  • surface is a pointer to a IDirectFBSurface surface interface.

Valid Usage

  • dfb must point to a valid DirectFB IDirectFB

  • surface must point to a valid DirectFB IDirectFBSurface

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DIRECTFB_SURFACE_CREATE_INFO_EXT

  • pNext must be NULL

  • flags must be 0

With DirectFB, minImageExtent, maxImageExtent, and currentExtent must always equal the surface size.

// Provided by VK_EXT_directfb_surface
typedef VkFlags VkDirectFBSurfaceCreateFlagsEXT;

VkDirectFBSurfaceCreateFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.7. Fuchsia Platform

To create a VkSurfaceKHR object for a Fuchsia ImagePipe, call:

// Provided by VK_FUCHSIA_imagepipe_surface
VkResult vkCreateImagePipeSurfaceFUCHSIA(
    VkInstance                                  instance,
    const VkImagePipeSurfaceCreateInfoFUCHSIA*  pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance to associate with the surface.

  • pCreateInfo is a pointer to a VkImagePipeSurfaceCreateInfoFUCHSIA structure containing parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkImagePipeSurfaceCreateInfoFUCHSIA structure is defined as:

// Provided by VK_FUCHSIA_imagepipe_surface
typedef struct VkImagePipeSurfaceCreateInfoFUCHSIA {
    VkStructureType                         sType;
    const void*                             pNext;
    VkImagePipeSurfaceCreateFlagsFUCHSIA    flags;
    zx_handle_t                             imagePipeHandle;
} VkImagePipeSurfaceCreateInfoFUCHSIA;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • imagePipeHandle is a zx_handle_t referring to the ImagePipe to associate with the surface.

Valid Usage

  • imagePipeHandle must be a valid zx_handle_t

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_IMAGEPIPE_SURFACE_CREATE_INFO_FUCHSIA

  • pNext must be NULL

  • flags must be 0

On Fuchsia, the surface currentExtent is the special value (0xFFFFFFFF, 0xFFFFFFFF), indicating that the surface size will be determined by the extent of a swapchain targeting the surface.

// Provided by VK_FUCHSIA_imagepipe_surface
typedef VkFlags VkImagePipeSurfaceCreateFlagsFUCHSIA;

VkImagePipeSurfaceCreateFlagsFUCHSIA is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.8. Google Games Platform

To create a VkSurfaceKHR object for a Google Games Platform stream descriptor, call:

// Provided by VK_GGP_stream_descriptor_surface
VkResult vkCreateStreamDescriptorSurfaceGGP(
    VkInstance                                  instance,
    const VkStreamDescriptorSurfaceCreateInfoGGP* pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance to associate with the surface.

  • pCreateInfo is a pointer to a VkStreamDescriptorSurfaceCreateInfoGGP structure containing parameters that affect the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_NATIVE_WINDOW_IN_USE_KHR

The VkStreamDescriptorSurfaceCreateInfoGGP structure is defined as:

// Provided by VK_GGP_stream_descriptor_surface
typedef struct VkStreamDescriptorSurfaceCreateInfoGGP {
    VkStructureType                            sType;
    const void*                                pNext;
    VkStreamDescriptorSurfaceCreateFlagsGGP    flags;
    GgpStreamDescriptor                        streamDescriptor;
} VkStreamDescriptorSurfaceCreateInfoGGP;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • streamDescriptor is a GgpStreamDescriptor referring to the GGP stream descriptor to associate with the surface.

Valid Usage

  • streamDescriptor must be a valid GgpStreamDescriptor

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_STREAM_DESCRIPTOR_SURFACE_CREATE_INFO_GGP

  • pNext must be NULL

  • flags must be 0

On Google Games Platform, the surface extents are dynamic. The minImageExtent will never be greater than 1080p and the maxImageExtent will never be less than 1080p. The currentExtent will reflect the current optimal resolution.

Applications are expected to choose an appropriate size for the swapchain’s imageExtent, within the bounds of the surface. Using the surface’s currentExtent will offer the best performance and quality. When a swapchain’s imageExtent does not match the surface’s currentExtent, the presentable images are scaled to the surface’s dimensions during presentation if possible and VK_SUBOPTIMAL_KHR is returned, otherwise presentation fails with VK_ERROR_OUT_OF_DATE_KHR.

// Provided by VK_GGP_stream_descriptor_surface
typedef VkFlags VkStreamDescriptorSurfaceCreateFlagsGGP;

VkStreamDescriptorSurfaceCreateFlagsGGP is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.9. iOS Platform

To create a VkSurfaceKHR object for an iOS UIView, call:

// Provided by VK_MVK_ios_surface
VkResult vkCreateIOSSurfaceMVK(
    VkInstance                                  instance,
    const VkIOSSurfaceCreateInfoMVK*            pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance with which to associate the surface.

  • pCreateInfo is a pointer to a VkIOSSurfaceCreateInfoMVK structure containing parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_NATIVE_WINDOW_IN_USE_KHR

The VkIOSSurfaceCreateInfoMVK structure is defined as:

// Provided by VK_MVK_ios_surface
typedef struct VkIOSSurfaceCreateInfoMVK {
    VkStructureType               sType;
    const void*                   pNext;
    VkIOSSurfaceCreateFlagsMVK    flags;
    const void*                   pView;
} VkIOSSurfaceCreateInfoMVK;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • pView is a reference to a UIView object which will display this surface. This UIView must be backed by a CALayer instance of type CAMetalLayer.

Valid Usage

  • pView must be a valid UIView and must be backed by a CALayer instance of type CAMetalLayer

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_IOS_SURFACE_CREATE_INFO_MVK

  • pNext must be NULL

  • flags must be 0

// Provided by VK_MVK_ios_surface
typedef VkFlags VkIOSSurfaceCreateFlagsMVK;

VkIOSSurfaceCreateFlagsMVK is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.10. macOS Platform

To create a VkSurfaceKHR object for a macOS NSView, call:

// Provided by VK_MVK_macos_surface
VkResult vkCreateMacOSSurfaceMVK(
    VkInstance                                  instance,
    const VkMacOSSurfaceCreateInfoMVK*          pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance with which to associate the surface.

  • pCreateInfo is a pointer to a VkMacOSSurfaceCreateInfoMVK structure containing parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_NATIVE_WINDOW_IN_USE_KHR

The VkMacOSSurfaceCreateInfoMVK structure is defined as:

// Provided by VK_MVK_macos_surface
typedef struct VkMacOSSurfaceCreateInfoMVK {
    VkStructureType                 sType;
    const void*                     pNext;
    VkMacOSSurfaceCreateFlagsMVK    flags;
    const void*                     pView;
} VkMacOSSurfaceCreateInfoMVK;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • pView is a reference to a NSView object which will display this surface. This NSView must be backed by a CALayer instance of type CAMetalLayer.

Valid Usage

  • pView must be a valid NSView and must be backed by a CALayer instance of type CAMetalLayer

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_MACOS_SURFACE_CREATE_INFO_MVK

  • pNext must be NULL

  • flags must be 0

// Provided by VK_MVK_macos_surface
typedef VkFlags VkMacOSSurfaceCreateFlagsMVK;

VkMacOSSurfaceCreateFlagsMVK is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.11. VI Platform

To create a VkSurfaceKHR object for an nn::vi::Layer, query the layer’s native handle using nn::vi::GetNativeWindow, and then call:

// Provided by VK_NN_vi_surface
VkResult vkCreateViSurfaceNN(
    VkInstance                                  instance,
    const VkViSurfaceCreateInfoNN*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance with which to associate the surface.

  • pCreateInfo is a pointer to a VkViSurfaceCreateInfoNN structure containing parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

During the lifetime of a surface created using a particular nn::vi::NativeWindowHandle, applications must not attempt to create another surface for the same nn::vi::Layer or attempt to connect to the same nn::vi::Layer through other platform mechanisms.

If the native window is created with a specified size, currentExtent will reflect that size. In this case, applications should use the same size for the swapchain’s imageExtent. Otherwise, the currentExtent will have the special value (0xFFFFFFFF, 0xFFFFFFFF), indicating that applications are expected to choose an appropriate size for the swapchain’s imageExtent (e.g., by matching the result of a call to nn::vi::GetDisplayResolution).

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_NATIVE_WINDOW_IN_USE_KHR

The VkViSurfaceCreateInfoNN structure is defined as:

// Provided by VK_NN_vi_surface
typedef struct VkViSurfaceCreateInfoNN {
    VkStructureType             sType;
    const void*                 pNext;
    VkViSurfaceCreateFlagsNN    flags;
    void*                       window;
} VkViSurfaceCreateInfoNN;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • window is the nn::vi::NativeWindowHandle for the nn::vi::Layer with which to associate the surface.

Valid Usage

  • window must be a valid nn::vi::NativeWindowHandle

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_VI_SURFACE_CREATE_INFO_NN

  • pNext must be NULL

  • flags must be 0

// Provided by VK_NN_vi_surface
typedef VkFlags VkViSurfaceCreateFlagsNN;

VkViSurfaceCreateFlagsNN is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.12. Metal Platform

To create a VkSurfaceKHR object for a CAMetalLayer, call:

// Provided by VK_EXT_metal_surface
VkResult vkCreateMetalSurfaceEXT(
    VkInstance                                  instance,
    const VkMetalSurfaceCreateInfoEXT*          pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance with which to associate the surface.

  • pCreateInfo is a pointer to a VkMetalSurfaceCreateInfoEXT structure specifying parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_NATIVE_WINDOW_IN_USE_KHR

The VkMetalSurfaceCreateInfoEXT structure is defined as:

// Provided by VK_EXT_metal_surface
typedef struct VkMetalSurfaceCreateInfoEXT {
    VkStructureType                 sType;
    const void*                     pNext;
    VkMetalSurfaceCreateFlagsEXT    flags;
    const CAMetalLayer*             pLayer;
} VkMetalSurfaceCreateInfoEXT;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

  • pLayer is a reference to a CAMetalLayer object representing a renderable surface.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_METAL_SURFACE_CREATE_INFO_EXT

  • pNext must be NULL

  • flags must be 0

To remove an unnecessary compile-time dependency, an incomplete type definition of CAMetalLayer is provided in the Vulkan headers:

// Provided by VK_EXT_metal_surface

#ifdef __OBJC__
@class CAMetalLayer;
#else
typedef void CAMetalLayer;
#endif

The actual CAMetalLayer type is defined in the QuartzCore framework.

// Provided by VK_EXT_metal_surface
typedef VkFlags VkMetalSurfaceCreateFlagsEXT;

VkMetalSurfaceCreateFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use.

32.2.13. Platform-Independent Information

Once created, VkSurfaceKHR objects can be used in this and other extensions, in particular the VK_KHR_swapchain extension.

Several WSI functions return VK_ERROR_SURFACE_LOST_KHR if the surface becomes no longer available. After such an error, the surface (and any child swapchain, if one exists) should be destroyed, as there is no way to restore them to a not-lost state. Applications may attempt to create a new VkSurfaceKHR using the same native platform window object, but whether such re-creation will succeed is platform-dependent and may depend on the reason the surface became unavailable. A lost surface does not otherwise cause devices to be lost.

To destroy a VkSurfaceKHR object, call:

// Provided by VK_KHR_surface
void vkDestroySurfaceKHR(
    VkInstance                                  instance,
    VkSurfaceKHR                                surface,
    const VkAllocationCallbacks*                pAllocator);

  • instance is the instance used to create the surface.

  • surface is the surface to destroy.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

Destroying a VkSurfaceKHR merely severs the connection between Vulkan and the native surface, and does not imply destroying the native surface, closing a window, or similar behavior.

Valid Usage

  • All VkSwapchainKHR objects created for surface must have been destroyed prior to destroying surface

  • If VkAllocationCallbacks were provided when surface was created, a compatible set of callbacks must be provided here

  • If no VkAllocationCallbacks were provided when surface was created, pAllocator must be NULL

Valid Usage (Implicit)

  • instance must be a valid VkInstance handle

  • If surface is not VK_NULL_HANDLE, surface must be a valid VkSurfaceKHR handle

  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

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

Host Synchronization

  • Host access to surface must be externally synchronized

32.3. Presenting Directly to Display Devices

In some environments applications can also present Vulkan rendering directly to display devices without using an intermediate windowing system. This can be useful for embedded applications, or implementing the rendering/presentation backend of a windowing system using Vulkan. The VK_KHR_display extension provides the functionality necessary to enumerate display devices and create VkSurfaceKHR objects that target displays.

32.3.1. Display Enumeration

Displays are represented by VkDisplayKHR handles:

// Provided by VK_KHR_display
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDisplayKHR)

Various functions are provided for enumerating the available display devices present on a Vulkan physical device. To query information about the available displays, call:

// Provided by VK_KHR_display
VkResult vkGetPhysicalDeviceDisplayPropertiesKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pPropertyCount,
    VkDisplayPropertiesKHR*                     pProperties);

  • physicalDevice is a physical device.

  • pPropertyCount is a pointer to an integer related to the number of display devices available or queried, as described below.

  • pProperties is either NULL or a pointer to an array of VkDisplayPropertiesKHR structures.

If pProperties is NULL, then the number of display devices available for physicalDevice is returned in pPropertyCount. Otherwise, pPropertyCount must point to a variable set by the user to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If the value of pPropertyCount is less than the number of display devices for physicalDevice, at most pPropertyCount structures will be written. If pPropertyCount is smaller than the number of display devices available for physicalDevice, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • pPropertyCount must be a valid pointer to a uint32_t value

  • If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount VkDisplayPropertiesKHR structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDisplayPropertiesKHR structure is defined as:

// Provided by VK_KHR_display
typedef struct VkDisplayPropertiesKHR {
    VkDisplayKHR                  display;
    const char*                   displayName;
    VkExtent2D                    physicalDimensions;
    VkExtent2D                    physicalResolution;
    VkSurfaceTransformFlagsKHR    supportedTransforms;
    VkBool32                      planeReorderPossible;
    VkBool32                      persistentContent;
} VkDisplayPropertiesKHR;

  • display is a handle that is used to refer to the display described here. This handle will be valid for the lifetime of the Vulkan instance.

  • displayName is a pointer to a null-terminated UTF-8 string containing the name of the display. Generally, this will be the name provided by the display’s EDID. It can be NULL if no suitable name is available. If not NULL, the memory it points to must remain accessible as long as display is valid.

  • physicalDimensions describes the physical width and height of the visible portion of the display, in millimeters.

  • physicalResolution describes the physical, native, or preferred resolution of the display.

Note

For devices which have no natural value to return here, implementations should return the maximum resolution supported.

  • supportedTransforms is a bitmask of VkSurfaceTransformFlagBitsKHR describing which transforms are supported by this display.

  • planeReorderPossible tells whether the planes on this display can have their z order changed. If this is VK_TRUE, the application can re-arrange the planes on this display in any order relative to each other.

  • persistentContent tells whether the display supports self-refresh/internal buffering. If this is true, the application can submit persistent present operations on swapchains created against this display.

Note

Persistent presents may have higher latency, and may use less power when the screen content is updated infrequently, or when only a portion of the screen needs to be updated in most frames.

To query information about the available displays, call:

// Provided by VK_KHR_get_display_properties2
VkResult vkGetPhysicalDeviceDisplayProperties2KHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pPropertyCount,
    VkDisplayProperties2KHR*                    pProperties);

  • physicalDevice is a physical device.

  • pPropertyCount is a pointer to an integer related to the number of display devices available or queried, as described below.

  • pProperties is either NULL or a pointer to an array of VkDisplayProperties2KHR structures.

vkGetPhysicalDeviceDisplayProperties2KHR behaves similarly to vkGetPhysicalDeviceDisplayPropertiesKHR, with the ability to return extended information via chained output structures.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • pPropertyCount must be a valid pointer to a uint32_t value

  • If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount VkDisplayProperties2KHR structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDisplayProperties2KHR structure is defined as:

// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayProperties2KHR {
    VkStructureType           sType;
    void*                     pNext;
    VkDisplayPropertiesKHR    displayProperties;
} VkDisplayProperties2KHR;

  • sType is the type of this structure.

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

  • displayProperties is a VkDisplayPropertiesKHR structure.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DISPLAY_PROPERTIES_2_KHR

  • pNext must be NULL

Acquiring and Releasing Displays

On some platforms, access to displays is limited to a single process or native driver instance. On such platforms, some or all of the displays may not be available to Vulkan if they are already in use by a native windowing system or other application.

To acquire permission to directly access a display in Vulkan from an X11 server, call:

// Provided by VK_EXT_acquire_xlib_display
VkResult vkAcquireXlibDisplayEXT(
    VkPhysicalDevice                            physicalDevice,
    Display*                                    dpy,
    VkDisplayKHR                                display);

  • physicalDevice The physical device the display is on.

  • dpy A connection to the X11 server that currently owns display.

  • display The display the caller wishes to control in Vulkan.

All permissions necessary to control the display are granted to the Vulkan instance associated with physicalDevice until the display is released or the X11 connection specified by dpy is terminated. Permission to access the display may be temporarily revoked during periods when the X11 server from which control was acquired itself loses access to display. During such periods, operations which require access to the display must fail with an approriate error code. If the X11 server associated with dpy does not own display, or if permission to access it has already been acquired by another entity, the call must return the error code VK_ERROR_INITIALIZATION_FAILED.

Note

One example of when an X11 server loses access to a display is when it loses ownership of its virtual terminal.
Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • dpy must be a valid pointer to a Display value

  • display must be a valid VkDisplayKHR handle

  • display must have been created, allocated, or retrieved from physicalDevice

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_INITIALIZATION_FAILED

When acquiring displays from an X11 server, an application may also wish to enumerate and identify them using a native handle rather than a VkDisplayKHR handle. To determine the VkDisplayKHR handle corresponding to an X11 RandR Output, call:

// Provided by VK_EXT_acquire_xlib_display
VkResult vkGetRandROutputDisplayEXT(
    VkPhysicalDevice                            physicalDevice,
    Display*                                    dpy,
    RROutput                                    rrOutput,
    VkDisplayKHR*                               pDisplay);

  • physicalDevice The physical device to query the display handle on.

  • dpy A connection to the X11 server from which rrOutput was queried.

  • rrOutput An X11 RandR output ID.

  • pDisplay The corresponding VkDisplayKHR handle will be returned here.

If there is no VkDisplayKHR corresponding to rrOutput on physicalDevice, VK_NULL_HANDLE must be returned in pDisplay.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • dpy must be a valid pointer to a Display value

  • pDisplay must be a valid pointer to a VkDisplayKHR handle

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

To release a previously acquired display, call:

// Provided by VK_EXT_direct_mode_display
VkResult vkReleaseDisplayEXT(
    VkPhysicalDevice                            physicalDevice,
    VkDisplayKHR                                display);

  • physicalDevice The physical device the display is on.

  • display The display to release control of.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • display must be a valid VkDisplayKHR handle

  • display must have been created, allocated, or retrieved from physicalDevice

Return Codes
Success

  • VK_SUCCESS

Display Planes

Images are presented to individual planes on a display. Devices must support at least one plane on each display. Planes can be stacked and blended to composite multiple images on one display. Devices may support only a fixed stacking order and fixed mapping between planes and displays, or they may allow arbitrary application specified stacking orders and mappings between planes and displays. To query the properties of device display planes, call:

// Provided by VK_KHR_display
VkResult vkGetPhysicalDeviceDisplayPlanePropertiesKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pPropertyCount,
    VkDisplayPlanePropertiesKHR*                pProperties);

  • physicalDevice is a physical device.

  • pPropertyCount is a pointer to an integer related to the number of display planes available or queried, as described below.

  • pProperties is either NULL or a pointer to an array of VkDisplayPlanePropertiesKHR structures.

If pProperties is NULL, then the number of display planes available for physicalDevice is returned in pPropertyCount. Otherwise, pPropertyCount must point to a variable set by the user to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If the value of pPropertyCount is less than the number of display planes for physicalDevice, at most pPropertyCount structures will be written.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • pPropertyCount must be a valid pointer to a uint32_t value

  • If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount VkDisplayPlanePropertiesKHR structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDisplayPlanePropertiesKHR structure is defined as:

// Provided by VK_KHR_display
typedef struct VkDisplayPlanePropertiesKHR {
    VkDisplayKHR    currentDisplay;
    uint32_t        currentStackIndex;
} VkDisplayPlanePropertiesKHR;

  • currentDisplay is the handle of the display the plane is currently associated with. If the plane is not currently attached to any displays, this will be VK_NULL_HANDLE.

  • currentStackIndex is the current z-order of the plane. This will be between 0 and the value returned by vkGetPhysicalDeviceDisplayPlanePropertiesKHR in pPropertyCount.

To query the properties of a device’s display planes, call:

// Provided by VK_KHR_get_display_properties2
VkResult vkGetPhysicalDeviceDisplayPlaneProperties2KHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t*                                   pPropertyCount,
    VkDisplayPlaneProperties2KHR*               pProperties);

  • physicalDevice is a physical device.

  • pPropertyCount is a pointer to an integer related to the number of display planes available or queried, as described below.

  • pProperties is either NULL or a pointer to an array of VkDisplayPlaneProperties2KHR structures.

vkGetPhysicalDeviceDisplayPlaneProperties2KHR behaves similarly to vkGetPhysicalDeviceDisplayPlanePropertiesKHR, with the ability to return extended information via chained output structures.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • pPropertyCount must be a valid pointer to a uint32_t value

  • If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount VkDisplayPlaneProperties2KHR structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDisplayPlaneProperties2KHR structure is defined as:

// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayPlaneProperties2KHR {
    VkStructureType                sType;
    void*                          pNext;
    VkDisplayPlanePropertiesKHR    displayPlaneProperties;
} VkDisplayPlaneProperties2KHR;

  • sType is the type of this structure.

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

  • displayPlaneProperties is a VkDisplayPlanePropertiesKHR structure.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DISPLAY_PLANE_PROPERTIES_2_KHR

  • pNext must be NULL

To determine which displays a plane is usable with, call

// Provided by VK_KHR_display
VkResult vkGetDisplayPlaneSupportedDisplaysKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t                                    planeIndex,
    uint32_t*                                   pDisplayCount,
    VkDisplayKHR*                               pDisplays);

  • physicalDevice is a physical device.

  • planeIndex is the plane which the application wishes to use, and must be in the range [0, physical device plane count - 1].

  • pDisplayCount is a pointer to an integer related to the number of displays available or queried, as described below.

  • pDisplays is either NULL or a pointer to an array of VkDisplayKHR handles.

If pDisplays is NULL, then the number of displays usable with the specified planeIndex for physicalDevice is returned in pDisplayCount. Otherwise, pDisplayCount must point to a variable set by the user to the number of elements in the pDisplays array, and on return the variable is overwritten with the number of handles actually written to pDisplays. If the value of pDisplayCount is less than the number of display planes for physicalDevice, at most pDisplayCount handles will be written. If pDisplayCount is smaller than the number of displays usable with the specified planeIndex for physicalDevice, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage

  • planeIndex must be less than the number of display planes supported by the device as determined by calling vkGetPhysicalDeviceDisplayPlanePropertiesKHR

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • pDisplayCount must be a valid pointer to a uint32_t value

  • If the value referenced by pDisplayCount is not 0, and pDisplays is not NULL, pDisplays must be a valid pointer to an array of pDisplayCount VkDisplayKHR handles

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Additional properties of displays are queried using specialized query functions.

Display Modes

Display modes are represented by VkDisplayModeKHR handles:

// Provided by VK_KHR_display
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDisplayModeKHR)

Each display has one or more supported modes associated with it by default. These built-in modes are queried by calling:

// Provided by VK_KHR_display
VkResult vkGetDisplayModePropertiesKHR(
    VkPhysicalDevice                            physicalDevice,
    VkDisplayKHR                                display,
    uint32_t*                                   pPropertyCount,
    VkDisplayModePropertiesKHR*                 pProperties);

  • physicalDevice is the physical device associated with display.

  • display is the display to query.

  • pPropertyCount is a pointer to an integer related to the number of display modes available or queried, as described below.

  • pProperties is either NULL or a pointer to an array of VkDisplayModePropertiesKHR structures.

If pProperties is NULL, then the number of display modes available on the specified display for physicalDevice is returned in pPropertyCount. Otherwise, pPropertyCount must point to a variable set by the user to the number of elements in the pProperties array, and on return the variable is overwritten with the number of structures actually written to pProperties. If the value of pPropertyCount is less than the number of display modes for physicalDevice, at most pPropertyCount structures will be written. If pPropertyCount is smaller than the number of display modes available on the specified display for physicalDevice, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • display must be a valid VkDisplayKHR handle

  • pPropertyCount must be a valid pointer to a uint32_t value

  • If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount VkDisplayModePropertiesKHR structures

  • display must have been created, allocated, or retrieved from physicalDevice

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDisplayModePropertiesKHR structure is defined as:

// Provided by VK_KHR_display
typedef struct VkDisplayModePropertiesKHR {
    VkDisplayModeKHR              displayMode;
    VkDisplayModeParametersKHR    parameters;
} VkDisplayModePropertiesKHR;

  • displayMode is a handle to the display mode described in this structure. This handle will be valid for the lifetime of the Vulkan instance.

  • parameters is a VkDisplayModeParametersKHR structure describing the display parameters associated with displayMode.

// Provided by VK_KHR_display
typedef VkFlags VkDisplayModeCreateFlagsKHR;

VkDisplayModeCreateFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.

To query the properties of a device’s built-in display modes, call:

// Provided by VK_KHR_get_display_properties2
VkResult vkGetDisplayModeProperties2KHR(
    VkPhysicalDevice                            physicalDevice,
    VkDisplayKHR                                display,
    uint32_t*                                   pPropertyCount,
    VkDisplayModeProperties2KHR*                pProperties);

  • physicalDevice is the physical device associated with display.

  • display is the display to query.

  • pPropertyCount is a pointer to an integer related to the number of display modes available or queried, as described below.

  • pProperties is either NULL or a pointer to an array of VkDisplayModeProperties2KHR structures.

vkGetDisplayModeProperties2KHR behaves similarly to vkGetDisplayModePropertiesKHR, with the ability to return extended information via chained output structures.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • display must be a valid VkDisplayKHR handle

  • pPropertyCount must be a valid pointer to a uint32_t value

  • If the value referenced by pPropertyCount is not 0, and pProperties is not NULL, pProperties must be a valid pointer to an array of pPropertyCount VkDisplayModeProperties2KHR structures

  • display must have been created, allocated, or retrieved from physicalDevice

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDisplayModeProperties2KHR structure is defined as:

// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayModeProperties2KHR {
    VkStructureType               sType;
    void*                         pNext;
    VkDisplayModePropertiesKHR    displayModeProperties;
} VkDisplayModeProperties2KHR;

  • sType is the type of this structure.

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

  • displayModeProperties is a VkDisplayModePropertiesKHR structure.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DISPLAY_MODE_PROPERTIES_2_KHR

  • pNext must be NULL

The VkDisplayModeParametersKHR structure is defined as:

// Provided by VK_KHR_display
typedef struct VkDisplayModeParametersKHR {
    VkExtent2D    visibleRegion;
    uint32_t      refreshRate;
} VkDisplayModeParametersKHR;

  • visibleRegion is the 2D extents of the visible region.

  • refreshRate is a uint32_t that is the number of times the display is refreshed each second multiplied by 1000.

Note

For example, a 60Hz display mode would report a refreshRate of 60,000.
Valid Usage

  • The width member of visibleRegion must be greater than 0

  • The height member of visibleRegion must be greater than 0

  • refreshRate must be greater than 0

Additional modes may also be created by calling:

// Provided by VK_KHR_display
VkResult vkCreateDisplayModeKHR(
    VkPhysicalDevice                            physicalDevice,
    VkDisplayKHR                                display,
    const VkDisplayModeCreateInfoKHR*           pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkDisplayModeKHR*                           pMode);

  • physicalDevice is the physical device associated with display.

  • display is the display to create an additional mode for.

  • pCreateInfo is a VkDisplayModeCreateInfoKHR structure describing the new mode to create.

  • pAllocator is the allocator used for host memory allocated for the display mode object when there is no more specific allocator available (see Memory Allocation).

  • pMode returns the handle of the mode created.

Valid Usage (Implicit)
Host Synchronization

  • Host access to display must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

The VkDisplayModeCreateInfoKHR structure is defined as:

// Provided by VK_KHR_display
typedef struct VkDisplayModeCreateInfoKHR {
    VkStructureType                sType;
    const void*                    pNext;
    VkDisplayModeCreateFlagsKHR    flags;
    VkDisplayModeParametersKHR     parameters;
} VkDisplayModeCreateInfoKHR;

  • sType is the type of this structure.

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

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

  • parameters is a VkDisplayModeParametersKHR structure describing the display parameters to use in creating the new mode. If the parameters are not compatible with the specified display, the implementation must return VK_ERROR_INITIALIZATION_FAILED.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR

  • pNext must be NULL

  • flags must be 0

  • parameters must be a valid VkDisplayModeParametersKHR structure

Applications that wish to present directly to a display must select which layer, or “plane” of the display they wish to target, and a mode to use with the display. Each display supports at least one plane. The capabilities of a given mode and plane combination are determined by calling:

// Provided by VK_KHR_display
VkResult vkGetDisplayPlaneCapabilitiesKHR(
    VkPhysicalDevice                            physicalDevice,
    VkDisplayModeKHR                            mode,
    uint32_t                                    planeIndex,
    VkDisplayPlaneCapabilitiesKHR*              pCapabilities);

  • physicalDevice is the physical device associated with display

  • mode is the display mode the application intends to program when using the specified plane. Note this parameter also implicitly specifies a display.

  • planeIndex is the plane which the application intends to use with the display, and is less than the number of display planes supported by the device.

  • pCapabilities is a pointer to a VkDisplayPlaneCapabilitiesKHR structure in which the capabilities are returned.

Valid Usage (Implicit)
Host Synchronization

  • Host access to mode must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDisplayPlaneCapabilitiesKHR structure is defined as:

// Provided by VK_KHR_display
typedef struct VkDisplayPlaneCapabilitiesKHR {
    VkDisplayPlaneAlphaFlagsKHR    supportedAlpha;
    VkOffset2D                     minSrcPosition;
    VkOffset2D                     maxSrcPosition;
    VkExtent2D                     minSrcExtent;
    VkExtent2D                     maxSrcExtent;
    VkOffset2D                     minDstPosition;
    VkOffset2D                     maxDstPosition;
    VkExtent2D                     minDstExtent;
    VkExtent2D                     maxDstExtent;
} VkDisplayPlaneCapabilitiesKHR;

  • supportedAlpha is a bitmask of VkDisplayPlaneAlphaFlagBitsKHR describing the supported alpha blending modes.

  • minSrcPosition is the minimum source rectangle offset supported by this plane using the specified mode.

  • maxSrcPosition is the maximum source rectangle offset supported by this plane using the specified mode. The x and y components of maxSrcPosition must each be greater than or equal to the x and y components of minSrcPosition, respectively.

  • minSrcExtent is the minimum source rectangle size supported by this plane using the specified mode.

  • maxSrcExtent is the maximum source rectangle size supported by this plane using the specified mode.

  • minDstPosition, maxDstPosition, minDstExtent, maxDstExtent all have similar semantics to their corresponding *Src* equivalents, but apply to the output region within the mode rather than the input region within the source image. Unlike the *Src* offsets, minDstPosition and maxDstPosition may contain negative values.

The minimum and maximum position and extent fields describe the implementation limits, if any, as they apply to the specified display mode and plane. Vendors may support displaying a subset of a swapchain’s presentable images on the specified display plane. This is expressed by returning minSrcPosition, maxSrcPosition, minSrcExtent, and maxSrcExtent values that indicate a range of possible positions and sizes may be used to specify the region within the presentable images that source pixels will be read from when creating a swapchain on the specified display mode and plane.

Vendors may also support mapping the presentable images’ content to a subset or superset of the visible region in the specified display mode. This is expressed by returning minDstPosition, maxDstPosition, minDstExtent and maxDstExtent values that indicate a range of possible positions and sizes may be used to describe the region within the display mode that the source pixels will be mapped to.

Other vendors may support only a 1-1 mapping between pixels in the presentable images and the display mode. This may be indicated by returning (0,0) for minSrcPosition, maxSrcPosition, minDstPosition, and maxDstPosition, and (display mode width, display mode height) for minSrcExtent, maxSrcExtent, minDstExtent, and maxDstExtent.

These values indicate the limits of the implementation’s individual fields. Not all combinations of values within the offset and extent ranges returned in VkDisplayPlaneCapabilitiesKHR are guaranteed to be supported. Presentation requests specifying unsupported combinations may fail.

To query the capabilities of a given mode and plane combination, call:

// Provided by VK_KHR_get_display_properties2
VkResult vkGetDisplayPlaneCapabilities2KHR(
    VkPhysicalDevice                            physicalDevice,
    const VkDisplayPlaneInfo2KHR*               pDisplayPlaneInfo,
    VkDisplayPlaneCapabilities2KHR*             pCapabilities);

  • physicalDevice is the physical device associated with pDisplayPlaneInfo.

  • pDisplayPlaneInfo is a pointer to a VkDisplayPlaneInfo2KHR structure describing the plane and mode.

  • pCapabilities is a pointer to a VkDisplayPlaneCapabilities2KHR structure in which the capabilities are returned.

vkGetDisplayPlaneCapabilities2KHR behaves similarly to vkGetDisplayPlaneCapabilitiesKHR, with the ability to specify extended inputs via chained input structures, and to return extended information via chained output structures.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDisplayPlaneInfo2KHR structure is defined as:

// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayPlaneInfo2KHR {
    VkStructureType     sType;
    const void*         pNext;
    VkDisplayModeKHR    mode;
    uint32_t            planeIndex;
} VkDisplayPlaneInfo2KHR;

  • sType is the type of this structure.

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

  • mode is the display mode the application intends to program when using the specified plane.

Note

This parameter also implicitly specifies a display.

  • planeIndex is the plane which the application intends to use with the display.

The members of VkDisplayPlaneInfo2KHR correspond to the arguments to vkGetDisplayPlaneCapabilitiesKHR, with sType and pNext added for extensibility.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DISPLAY_PLANE_INFO_2_KHR

  • pNext must be NULL

  • mode must be a valid VkDisplayModeKHR handle

Host Synchronization

  • Host access to mode must be externally synchronized

The VkDisplayPlaneCapabilities2KHR structure is defined as:

// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayPlaneCapabilities2KHR {
    VkStructureType                  sType;
    void*                            pNext;
    VkDisplayPlaneCapabilitiesKHR    capabilities;
} VkDisplayPlaneCapabilities2KHR;

  • sType is the type of this structure.

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

  • capabilities is a VkDisplayPlaneCapabilitiesKHR structure.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DISPLAY_PLANE_CAPABILITIES_2_KHR

  • pNext must be NULL

32.3.2. Display Control

To set the power state of a display, call:

// Provided by VK_EXT_display_control
VkResult vkDisplayPowerControlEXT(
    VkDevice                                    device,
    VkDisplayKHR                                display,
    const VkDisplayPowerInfoEXT*                pDisplayPowerInfo);

  • device is a logical device associated with display.

  • display is the display whose power state is modified.

  • pDisplayPowerInfo is a VkDisplayPowerInfoEXT structure specifying the new power state of display.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

The VkDisplayPowerInfoEXT structure is defined as:

// Provided by VK_EXT_display_control
typedef struct VkDisplayPowerInfoEXT {
    VkStructureType           sType;
    const void*               pNext;
    VkDisplayPowerStateEXT    powerState;
} VkDisplayPowerInfoEXT;

  • sType is the type of this structure.

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

  • powerState is a VkDisplayPowerStateEXT value specifying the new power state of the display.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DISPLAY_POWER_INFO_EXT

  • pNext must be NULL

  • powerState must be a valid VkDisplayPowerStateEXT value

Possible values of VkDisplayPowerInfoEXT::powerState, specifying the new power state of a display, are:

// Provided by VK_EXT_display_control
typedef enum VkDisplayPowerStateEXT {
    VK_DISPLAY_POWER_STATE_OFF_EXT = 0,
    VK_DISPLAY_POWER_STATE_SUSPEND_EXT = 1,
    VK_DISPLAY_POWER_STATE_ON_EXT = 2,
} VkDisplayPowerStateEXT;

  • VK_DISPLAY_POWER_STATE_OFF_EXT specifies that the display is powered down.

  • VK_DISPLAY_POWER_STATE_SUSPEND_EXT specifies that the display is put into a low power mode, from which it may be able to transition back to VK_DISPLAY_POWER_STATE_ON_EXT more quickly than if it were in VK_DISPLAY_POWER_STATE_OFF_EXT. This state may be the same as VK_DISPLAY_POWER_STATE_OFF_EXT.

  • VK_DISPLAY_POWER_STATE_ON_EXT specifies that the display is powered on.

32.3.3. Display Surfaces

A complete display configuration includes a mode, one or more display planes and any parameters describing their behavior, and parameters describing some aspects of the images associated with those planes. Display surfaces describe the configuration of a single plane within a complete display configuration. To create a VkSurfaceKHR structure for a display surface, call:

// Provided by VK_KHR_display
VkResult vkCreateDisplayPlaneSurfaceKHR(
    VkInstance                                  instance,
    const VkDisplaySurfaceCreateInfoKHR*        pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance corresponding to the physical device the targeted display is on.

  • pCreateInfo is a pointer to a VkDisplaySurfaceCreateInfoKHR structure specifying which mode, plane, and other parameters to use, as described below.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDisplaySurfaceCreateInfoKHR structure is defined as:

// Provided by VK_KHR_display
typedef struct VkDisplaySurfaceCreateInfoKHR {
    VkStructureType                   sType;
    const void*                       pNext;
    VkDisplaySurfaceCreateFlagsKHR    flags;
    VkDisplayModeKHR                  displayMode;
    uint32_t                          planeIndex;
    uint32_t                          planeStackIndex;
    VkSurfaceTransformFlagBitsKHR     transform;
    float                             globalAlpha;
    VkDisplayPlaneAlphaFlagBitsKHR    alphaMode;
    VkExtent2D                        imageExtent;
} VkDisplaySurfaceCreateInfoKHR;

  • sType is the type of this structure.

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

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

  • displayMode is a VkDisplayModeKHR handle specifying the mode to use when displaying this surface.

  • planeIndex is the plane on which this surface appears.

  • planeStackIndex is the z-order of the plane.

  • transform is a VkSurfaceTransformFlagBitsKHR value specifying the transformation to apply to images as part of the scanout operation.

  • globalAlpha is the global alpha value. This value is ignored if alphaMode is not VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR.

  • alphaMode is a VkDisplayPlaneAlphaFlagBitsKHR value specifying the type of alpha blending to use.

  • imageExtent The size of the presentable images to use with the surface.

Note

Creating a display surface must not modify the state of the displays, planes, or other resources it names. For example, it must not apply the specified mode to be set on the associated display. Application of display configuration occurs as a side effect of presenting to a display surface.
Valid Usage

  • planeIndex must be less than the number of display planes supported by the device as determined by calling vkGetPhysicalDeviceDisplayPlanePropertiesKHR

  • If the planeReorderPossible member of the VkDisplayPropertiesKHR structure returned by vkGetPhysicalDeviceDisplayPropertiesKHR for the display corresponding to displayMode is VK_TRUE then planeStackIndex must be less than the number of display planes supported by the device as determined by calling vkGetPhysicalDeviceDisplayPlanePropertiesKHR; otherwise planeStackIndex must equal the currentStackIndex member of VkDisplayPlanePropertiesKHR returned by vkGetPhysicalDeviceDisplayPlanePropertiesKHR for the display plane corresponding to displayMode

  • If alphaMode is VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR then globalAlpha must be between 0 and 1, inclusive

  • alphaMode must be 0 or one of the bits present in the supportedAlpha member of VkDisplayPlaneCapabilitiesKHR returned by vkGetDisplayPlaneCapabilitiesKHR for the display plane corresponding to displayMode

  • The width and height members of imageExtent must be less than the maxImageDimensions2D member of VkPhysicalDeviceLimits

Valid Usage (Implicit)
// Provided by VK_KHR_display
typedef VkFlags VkDisplaySurfaceCreateFlagsKHR;

VkDisplaySurfaceCreateFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.

Possible values of VkDisplaySurfaceCreateInfoKHR::alphaMode, specifying the type of alpha blending to use on a display, are:

// Provided by VK_KHR_display
typedef enum VkDisplayPlaneAlphaFlagBitsKHR {
    VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR = 0x00000001,
    VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR = 0x00000002,
    VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR = 0x00000004,
    VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR = 0x00000008,
} VkDisplayPlaneAlphaFlagBitsKHR;

  • VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR specifies that the source image will be treated as opaque.

  • VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR specifies that a global alpha value must be specified that will be applied to all pixels in the source image.

  • VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR specifies that the alpha value will be determined by the alpha channel of the source image’s pixels. If the source format contains no alpha values, no blending will be applied. The source alpha values are not premultiplied into the source image’s other color channels.

  • VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR is equivalent to VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR, except the source alpha values are assumed to be premultiplied into the source image’s other color channels.

// Provided by VK_KHR_display
typedef VkFlags VkDisplayPlaneAlphaFlagsKHR;

VkDisplayPlaneAlphaFlagsKHR is a bitmask type for setting a mask of zero or more VkDisplayPlaneAlphaFlagBitsKHR.

32.3.4. Presenting to headless surfaces

Vulkan rendering can be presented to a headless surface, where the presentation operation is a no-op producing no externally-visible result.

Note

Because there is no real presentation target, the headless presentation engine may be extended to impose an arbitrary or customisable set of restrictions and features. This makes it a useful portable test target for applications targeting a wide range of presentation engines where the actual target presentation engines might be scarce, unavailable or otherwise undesirable or inconvenient to use for general Vulkan application development.

The usual surface query mechanisms must be used to determine the actual restrictions and features of the implementation.

To create a headless VkSurfaceKHR object, call:

// Provided by VK_EXT_headless_surface
VkResult vkCreateHeadlessSurfaceEXT(
    VkInstance                                  instance,
    const VkHeadlessSurfaceCreateInfoEXT*       pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkSurfaceKHR*                               pSurface);

  • instance is the instance to associate the surface with.

  • pCreateInfo is a pointer to a VkHeadlessSurfaceCreateInfoEXT structure containing parameters affecting the creation of the surface object.

  • pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

  • pSurface is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkHeadlessSurfaceCreateInfoEXT structure is defined as:

// Provided by VK_EXT_headless_surface
typedef struct VkHeadlessSurfaceCreateInfoEXT {
    VkStructureType                    sType;
    const void*                        pNext;
    VkHeadlessSurfaceCreateFlagsEXT    flags;
} VkHeadlessSurfaceCreateInfoEXT;

  • sType is the type of this structure.

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

  • flags is reserved for future use.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_HEADLESS_SURFACE_CREATE_INFO_EXT

  • pNext must be NULL

  • flags must be 0

For headless surfaces, currentExtent is the reserved value (0xFFFFFFFF, 0xFFFFFFFF). Whatever the application sets a swapchain’s imageExtent to will be the size of the surface, after the first image is presented.

// Provided by VK_EXT_headless_surface
typedef VkFlags VkHeadlessSurfaceCreateFlagsEXT;

VkHeadlessSurfaceCreateFlagsEXT is a bitmask type for setting a mask, but is currently reserved for future use.

32.4. Querying for WSI Support

Not all physical devices will include WSI support. Within a physical device, not all queue families will support presentation. WSI support and compatibility can be determined in a platform-neutral manner (which determines support for presentation to a particular surface object) and additionally may be determined in platform-specific manners (which determine support for presentation on the specified physical device but do not guarantee support for presentation to a particular surface object).

To determine whether a queue family of a physical device supports presentation to a given surface, call:

// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfaceSupportKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t                                    queueFamilyIndex,
    VkSurfaceKHR                                surface,
    VkBool32*                                   pSupported);

  • physicalDevice is the physical device.

  • queueFamilyIndex is the queue family.

  • surface is the surface.

  • pSupported is a pointer to a VkBool32, which is set to VK_TRUE to indicate support, and VK_FALSE otherwise.

Valid Usage

  • queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by vkGetPhysicalDeviceQueueFamilyProperties for the given physicalDevice

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • surface must be a valid VkSurfaceKHR handle

  • pSupported must be a valid pointer to a VkBool32 value

  • Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

32.4.1. Android Platform

On Android, all physical devices and queue families must be capable of presentation with any native window. As a result there is no Android-specific query for these capabilities.

32.4.2. Wayland Platform

To determine whether a queue family of a physical device supports presentation to a Wayland compositor, call:

// Provided by VK_KHR_wayland_surface
VkBool32 vkGetPhysicalDeviceWaylandPresentationSupportKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t                                    queueFamilyIndex,
    struct wl_display*                          display);

  • physicalDevice is the physical device.

  • queueFamilyIndex is the queue family index.

  • display is a pointer to the wl_display associated with a Wayland compositor.

This platform-specific function can be called prior to creating a surface.

Valid Usage

  • queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by vkGetPhysicalDeviceQueueFamilyProperties for the given physicalDevice

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • display must be a valid pointer to a wl_display value

32.4.3. Win32 Platform

To determine whether a queue family of a physical device supports presentation to the Microsoft Windows desktop, call:

// Provided by VK_KHR_win32_surface
VkBool32 vkGetPhysicalDeviceWin32PresentationSupportKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t                                    queueFamilyIndex);

  • physicalDevice is the physical device.

  • queueFamilyIndex is the queue family index.

This platform-specific function can be called prior to creating a surface.

Valid Usage

  • queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by vkGetPhysicalDeviceQueueFamilyProperties for the given physicalDevice

Valid Usage (Implicit)

32.4.4. XCB Platform

To determine whether a queue family of a physical device supports presentation to an X11 server, using the XCB client-side library, call:

// Provided by VK_KHR_xcb_surface
VkBool32 vkGetPhysicalDeviceXcbPresentationSupportKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t                                    queueFamilyIndex,
    xcb_connection_t*                           connection,
    xcb_visualid_t                              visual_id);

  • physicalDevice is the physical device.

  • queueFamilyIndex is the queue family index.

  • connection is a pointer to an xcb_connection_t to the X server.

  • visual_id is an X11 visual (xcb_visualid_t).

This platform-specific function can be called prior to creating a surface.

Valid Usage

  • queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by vkGetPhysicalDeviceQueueFamilyProperties for the given physicalDevice

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • connection must be a valid pointer to an xcb_connection_t value

32.4.5. Xlib Platform

To determine whether a queue family of a physical device supports presentation to an X11 server, using the Xlib client-side library, call:

// Provided by VK_KHR_xlib_surface
VkBool32 vkGetPhysicalDeviceXlibPresentationSupportKHR(
    VkPhysicalDevice                            physicalDevice,
    uint32_t                                    queueFamilyIndex,
    Display*                                    dpy,
    VisualID                                    visualID);

  • physicalDevice is the physical device.

  • queueFamilyIndex is the queue family index.

  • dpy is a pointer to an Xlib Display connection to the server.

  • visualId is an X11 visual (VisualID).

This platform-specific function can be called prior to creating a surface.

Valid Usage

  • queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by vkGetPhysicalDeviceQueueFamilyProperties for the given physicalDevice

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • dpy must be a valid pointer to a Display value

32.4.6. DirectFB Platform

To determine whether a queue family of a physical device supports presentation with DirectFB library, call:

// Provided by VK_EXT_directfb_surface
VkBool32 vkGetPhysicalDeviceDirectFBPresentationSupportEXT(
    VkPhysicalDevice                            physicalDevice,
    uint32_t                                    queueFamilyIndex,
    IDirectFB*                                  dfb);

  • physicalDevice is the physical device.

  • queueFamilyIndex is the queue family index.

  • dfb is a pointer to the IDirectFB main interface of DirectFB.

This platform-specific function can be called prior to creating a surface.

Valid Usage

  • queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by vkGetPhysicalDeviceQueueFamilyProperties for the given physicalDevice

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • dfb must be a valid pointer to an IDirectFB value

32.4.7. Fuchsia Platform

On Fuchsia, all physical devices and queue families must be capable of presentation with any ImagePipe. As a result there is no Fuchsia-specific query for these capabilities.

32.4.8. Google Games Platform

On Google Games Platform, all physical devices and queue families with the VK_QUEUE_GRAPHICS_BIT or VK_QUEUE_COMPUTE_BIT capabilities must be capable of presentation with any Google Games Platform stream descriptor. As a result, there is no query specific to Google Games Platform for these capabilities.

32.4.9. iOS Platform

On iOS, all physical devices and queue families must be capable of presentation with any layer. As a result there is no iOS-specific query for these capabilities.

32.4.10. macOS Platform

On macOS, all physical devices and queue families must be capable of presentation with any layer. As a result there is no macOS-specific query for these capabilities.

32.4.11. VI Platform

On VI, all physical devices and queue families must be capable of presentation with any layer. As a result there is no VI-specific query for these capabilities.

32.5. Surface Queries

The capabilities of a swapchain targeting a surface are the intersection of the capabilities of the WSI platform, the native window or display, and the physical device. The resulting capabilities can be obtained with the queries listed below in this section.

Note

In addition to the surface capabilities as obtained by surface queries below, swapchain images are also subject to ordinary image creation limits as reported by vkGetPhysicalDeviceImageFormatProperties. As an application is instructed by the appropriate Valid Usage sections, both the surface capabilities and the image creation limits have to be satisfied whenever swapchain images are created.

32.5.1. Surface Capabilities

To query the basic capabilities of a surface, needed in order to create a swapchain, call:

// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfaceCapabilitiesKHR(
    VkPhysicalDevice                            physicalDevice,
    VkSurfaceKHR                                surface,
    VkSurfaceCapabilitiesKHR*                   pSurfaceCapabilities);

  • physicalDevice is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR.

  • surface is the surface that will be associated with the swapchain.

  • pSurfaceCapabilities is a pointer to a VkSurfaceCapabilitiesKHR structure in which the capabilities are returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

The VkSurfaceCapabilitiesKHR structure is defined as:

// Provided by VK_KHR_surface
typedef struct VkSurfaceCapabilitiesKHR {
    uint32_t                         minImageCount;
    uint32_t                         maxImageCount;
    VkExtent2D                       currentExtent;
    VkExtent2D                       minImageExtent;
    VkExtent2D                       maxImageExtent;
    uint32_t                         maxImageArrayLayers;
    VkSurfaceTransformFlagsKHR       supportedTransforms;
    VkSurfaceTransformFlagBitsKHR    currentTransform;
    VkCompositeAlphaFlagsKHR         supportedCompositeAlpha;
    VkImageUsageFlags                supportedUsageFlags;
} VkSurfaceCapabilitiesKHR;

  • minImageCount is the minimum number of images the specified device supports for a swapchain created for the surface, and will be at least one.

  • maxImageCount is the maximum number of images the specified device supports for a swapchain created for the surface, and will be either 0, or greater than or equal to minImageCount. A value of 0 means that there is no limit on the number of images, though there may be limits related to the total amount of memory used by presentable images.

  • currentExtent is the current width and height of the surface, or the special value (0xFFFFFFFF, 0xFFFFFFFF) indicating that the surface size will be determined by the extent of a swapchain targeting the surface.

  • minImageExtent contains the smallest valid swapchain extent for the surface on the specified device. The width and height of the extent will each be less than or equal to the corresponding width and height of currentExtent, unless currentExtent has the special value described above.

  • maxImageExtent contains the largest valid swapchain extent for the surface on the specified device. The width and height of the extent will each be greater than or equal to the corresponding width and height of minImageExtent. The width and height of the extent will each be greater than or equal to the corresponding width and height of currentExtent, unless currentExtent has the special value described above.

  • maxImageArrayLayers is the maximum number of layers presentable images can have for a swapchain created for this device and surface, and will be at least one.

  • supportedTransforms is a bitmask of VkSurfaceTransformFlagBitsKHR indicating the presentation transforms supported for the surface on the specified device. At least one bit will be set.

  • currentTransform is VkSurfaceTransformFlagBitsKHR value indicating the surface’s current transform relative to the presentation engine’s natural orientation.

  • supportedCompositeAlpha is a bitmask of VkCompositeAlphaFlagBitsKHR, representing the alpha compositing modes supported by the presentation engine for the surface on the specified device, and at least one bit will be set. Opaque composition can be achieved in any alpha compositing mode by either using an image format that has no alpha component, or by ensuring that all pixels in the presentable images have an alpha value of 1.0.

  • supportedUsageFlags is a bitmask of VkImageUsageFlagBits representing the ways the application can use the presentable images of a swapchain created with VkPresentModeKHR set to VK_PRESENT_MODE_IMMEDIATE_KHR, VK_PRESENT_MODE_MAILBOX_KHR, VK_PRESENT_MODE_FIFO_KHR or VK_PRESENT_MODE_FIFO_RELAXED_KHR for the surface on the specified device. VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT must be included in the set but implementations may support additional usages.

Note

Supported usage flags of a presentable image when using VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR presentation mode are provided by VkSharedPresentSurfaceCapabilitiesKHR::sharedPresentSupportedUsageFlags.
Note

Formulas such as min(N, maxImageCount) are not correct, since maxImageCount may be zero.

To query the basic capabilities of a surface defined by the core or extensions, call:

// Provided by VK_KHR_get_surface_capabilities2
VkResult vkGetPhysicalDeviceSurfaceCapabilities2KHR(
    VkPhysicalDevice                            physicalDevice,
    const VkPhysicalDeviceSurfaceInfo2KHR*      pSurfaceInfo,
    VkSurfaceCapabilities2KHR*                  pSurfaceCapabilities);

vkGetPhysicalDeviceSurfaceCapabilities2KHR behaves similarly to vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to specify extended inputs via chained input structures, and to return extended information via chained output structures.

Valid Usage
Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

The VkPhysicalDeviceSurfaceInfo2KHR structure is defined as:

// Provided by VK_KHR_get_surface_capabilities2
typedef struct VkPhysicalDeviceSurfaceInfo2KHR {
    VkStructureType    sType;
    const void*        pNext;
    VkSurfaceKHR       surface;
} VkPhysicalDeviceSurfaceInfo2KHR;

  • sType is the type of this structure.

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

  • surface is the surface that will be associated with the swapchain.

The members of VkPhysicalDeviceSurfaceInfo2KHR correspond to the arguments to vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with sType and pNext added for extensibility.

Additional capabilities of a surface may be available to swapchains created with different full-screen exclusive settings - particularly if exclusive full-screen access is application controlled. These additional capabilities can be queried by adding a VkSurfaceFullScreenExclusiveInfoEXT structure to the pNext chain of this structure when used to query surface properties. Additionally, for Win32 surfaces with application controlled exclusive full-screen access, chaining a VkSurfaceFullScreenExclusiveWin32InfoEXT structure may also report additional surface capabilities. These additional capabilities only apply to swapchains created with the same parameters included in the pNext chain of VkSwapchainCreateInfoKHR.

Valid Usage
Valid Usage (Implicit)

If the pNext chain of VkSwapchainCreateInfoKHR includes a VkSurfaceFullScreenExclusiveInfoEXT structure, then that structure specifies the application’s preferred full-screen transition behavior.

The VkSurfaceFullScreenExclusiveInfoEXT structure is defined as:

// Provided by VK_EXT_full_screen_exclusive
typedef struct VkSurfaceFullScreenExclusiveInfoEXT {
    VkStructureType             sType;
    void*                       pNext;
    VkFullScreenExclusiveEXT    fullScreenExclusive;
} VkSurfaceFullScreenExclusiveInfoEXT;

  • sType is the type of this structure.

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

  • fullScreenExclusive is a VkFullScreenExclusiveEXT value specifying the preferred full-screen transition behavior.

If this structure is not present, fullScreenExclusive is considered to be VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_INFO_EXT

  • fullScreenExclusive must be a valid VkFullScreenExclusiveEXT value

Possible values of VkSurfaceFullScreenExclusiveInfoEXT::fullScreenExclusive are:

// Provided by VK_EXT_full_screen_exclusive
typedef enum VkFullScreenExclusiveEXT {
    VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT = 0,
    VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT = 1,
    VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT = 2,
    VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT = 3,
} VkFullScreenExclusiveEXT;

  • VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT indicates the implementation should determine the appropriate full-screen method by whatever means it deems appropriate.

  • VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT indicates the implementation may use full-screen exclusive mechanisms when available. Such mechanisms may result in better performance and/or the availability of different presentation capabilities, but may require a more disruptive transition during swapchain initialization, first presentation and/or destruction.

  • VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT indicates the implementation should avoid using full-screen mechanisms which rely on disruptive transitions.

  • VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT indicates the application will manage full-screen exclusive mode by using the vkAcquireFullScreenExclusiveModeEXT and vkReleaseFullScreenExclusiveModeEXT commands.

The VkSurfaceFullScreenExclusiveWin32InfoEXT structure is defined as:

// Provided by VK_EXT_full_screen_exclusive with VK_KHR_win32_surface
typedef struct VkSurfaceFullScreenExclusiveWin32InfoEXT {
    VkStructureType    sType;
    const void*        pNext;
    HMONITOR           hmonitor;
} VkSurfaceFullScreenExclusiveWin32InfoEXT;

  • sType is the type of this structure.

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

  • hmonitor is the Win32 HMONITOR handle identifying the display to create the surface with.

Note

If hmonitor is invalidated (e.g. the monitor is unplugged) during the lifetime of a swapchain created with this structure, operations on that swapchain will return VK_ERROR_OUT_OF_DATE_KHR.
Note

It is the responsibility of the application to change the display settings of the targeted Win32 display using the appropriate platform APIs. Such changes may alter the surface capabilities reported for the created surface.
Valid Usage

  • hmonitor must be a valid HMONITOR

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SURFACE_FULL_SCREEN_EXCLUSIVE_WIN32_INFO_EXT

The VkSurfaceCapabilities2KHR structure is defined as:

// Provided by VK_KHR_get_surface_capabilities2
typedef struct VkSurfaceCapabilities2KHR {
    VkStructureType             sType;
    void*                       pNext;
    VkSurfaceCapabilitiesKHR    surfaceCapabilities;
} VkSurfaceCapabilities2KHR;

  • sType is the type of this structure.

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

  • surfaceCapabilities is a VkSurfaceCapabilitiesKHR structure describing the capabilities of the specified surface.

Valid Usage (Implicit)

An application queries if a protected VkSurfaceKHR is displayable on a specific windowing system using VkSurfaceProtectedCapabilitiesKHR, which can be passed in pNext parameter of VkSurfaceCapabilities2KHR.

The VkSurfaceProtectedCapabilitiesKHR structure is defined as:

// Provided by VK_KHR_surface_protected_capabilities
typedef struct VkSurfaceProtectedCapabilitiesKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           supportsProtected;
} VkSurfaceProtectedCapabilitiesKHR;

  • sType is the type of this structure.

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

  • supportsProtected specifies whether a protected swapchain created from VkPhysicalDeviceSurfaceInfo2KHR::surface for a particular windowing system can be displayed on screen or not. If supportsProtected is VK_TRUE, then creation of swapchains with the VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR flag set must be supported for surface.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SURFACE_PROTECTED_CAPABILITIES_KHR

The VkSharedPresentSurfaceCapabilitiesKHR structure is defined as:

// Provided by VK_KHR_shared_presentable_image
typedef struct VkSharedPresentSurfaceCapabilitiesKHR {
    VkStructureType      sType;
    void*                pNext;
    VkImageUsageFlags    sharedPresentSupportedUsageFlags;
} VkSharedPresentSurfaceCapabilitiesKHR;

  • sType is the type of this structure.

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

  • sharedPresentSupportedUsageFlags is a bitmask of VkImageUsageFlagBits representing the ways the application can use the shared presentable image from a swapchain created with VkPresentModeKHR set to VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR for the surface on the specified device. VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT must be included in the set but implementations may support additional usages.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SHARED_PRESENT_SURFACE_CAPABILITIES_KHR

The VkDisplayNativeHdrSurfaceCapabilitiesAMD structure is defined as:

// Provided by VK_AMD_display_native_hdr
typedef struct VkDisplayNativeHdrSurfaceCapabilitiesAMD {
    VkStructureType    sType;
    void*              pNext;
    VkBool32           localDimmingSupport;
} VkDisplayNativeHdrSurfaceCapabilitiesAMD;

  • sType is the type of this structure.

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

  • localDimmingSupport specifies whether the surface supports local dimming. If this is VK_TRUE, VkSwapchainDisplayNativeHdrCreateInfoAMD can be used to explicitly enable or disable local dimming for the surface. Local dimming may also be overriden by vkSetLocalDimmingAMD during the lifetime of the swapchain.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DISPLAY_NATIVE_HDR_SURFACE_CAPABILITIES_AMD

The VkSurfaceCapabilitiesFullScreenExclusiveEXT structure is defined as:

// Provided by VK_EXT_full_screen_exclusive
typedef struct VkSurfaceCapabilitiesFullScreenExclusiveEXT {
    VkStructureType    sType;
    void*              pNext;
    VkBool32           fullScreenExclusiveSupported;
} VkSurfaceCapabilitiesFullScreenExclusiveEXT;

  • sType is the type of this structure.

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

  • fullScreenExclusiveControlSupported is a boolean describing whether the surface is able to make use of exclusive full-screen access.

This structure can be included in the pNext chain of VkSurfaceCapabilities2KHR to determine support for exclusive full-screen access. If fullScreenExclusiveSupported is VK_FALSE, it indicates that exclusive full-screen access is not obtainable for this surface.

Applications must not attempt to create swapchains with VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT set if fullScreenExclusiveSupported is VK_FALSE.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_FULL_SCREEN_EXCLUSIVE_EXT

To query the basic capabilities of a surface, needed in order to create a swapchain, call:

// Provided by VK_EXT_display_surface_counter
VkResult vkGetPhysicalDeviceSurfaceCapabilities2EXT(
    VkPhysicalDevice                            physicalDevice,
    VkSurfaceKHR                                surface,
    VkSurfaceCapabilities2EXT*                  pSurfaceCapabilities);

  • physicalDevice is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR.

  • surface is the surface that will be associated with the swapchain.

  • pSurfaceCapabilities is a pointer to a VkSurfaceCapabilities2EXT structure in which the capabilities are returned.

vkGetPhysicalDeviceSurfaceCapabilities2EXT behaves similarly to vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to return extended information by adding extending structures to the pNext chain of its pSurfaceCapabilities parameter.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

The VkSurfaceCapabilities2EXT structure is defined as:

// Provided by VK_EXT_display_surface_counter
typedef struct VkSurfaceCapabilities2EXT {
    VkStructureType                  sType;
    void*                            pNext;
    uint32_t                         minImageCount;
    uint32_t                         maxImageCount;
    VkExtent2D                       currentExtent;
    VkExtent2D                       minImageExtent;
    VkExtent2D                       maxImageExtent;
    uint32_t                         maxImageArrayLayers;
    VkSurfaceTransformFlagsKHR       supportedTransforms;
    VkSurfaceTransformFlagBitsKHR    currentTransform;
    VkCompositeAlphaFlagsKHR         supportedCompositeAlpha;
    VkImageUsageFlags                supportedUsageFlags;
    VkSurfaceCounterFlagsEXT         supportedSurfaceCounters;
} VkSurfaceCapabilities2EXT;

All members of VkSurfaceCapabilities2EXT are identical to the corresponding members of VkSurfaceCapabilitiesKHR where one exists. The remaining members are:

  • sType is the type of this structure.

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

  • supportedSurfaceCounters is a bitmask of VkSurfaceCounterFlagBitsEXT indicating the supported surface counter types.

Valid Usage

  • supportedSurfaceCounters must not include VK_SURFACE_COUNTER_VBLANK_EXT unless the surface queried is a display surface

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_EXT

  • pNext must be NULL

Bits which can be set in VkSurfaceCapabilities2EXT::supportedSurfaceCounters, indicating supported surface counter types, are:

// Provided by VK_EXT_display_surface_counter
typedef enum VkSurfaceCounterFlagBitsEXT {
    VK_SURFACE_COUNTER_VBLANK_EXT = 0x00000001,
} VkSurfaceCounterFlagBitsEXT;

  • VK_SURFACE_COUNTER_VBLANK_EXT specifies a counter incrementing once every time a vertical blanking period occurs on the display associated with the surface.

// Provided by VK_EXT_display_surface_counter
typedef VkFlags VkSurfaceCounterFlagsEXT;

VkSurfaceCounterFlagsEXT is a bitmask type for setting a mask of zero or more VkSurfaceCounterFlagBitsEXT.

Bits which may be set in VkSurfaceCapabilitiesKHR::supportedTransforms indicating the presentation transforms supported for the surface on the specified device, and possible values of VkSurfaceCapabilitiesKHR::currentTransform is indicating the surface’s current transform relative to the presentation engine’s natural orientation, are:

// Provided by VK_KHR_surface
typedef enum VkSurfaceTransformFlagBitsKHR {
    VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR = 0x00000001,
    VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR = 0x00000002,
    VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR = 0x00000004,
    VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR = 0x00000008,
    VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR = 0x00000010,
    VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR = 0x00000020,
    VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR = 0x00000040,
    VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR = 0x00000080,
    VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR = 0x00000100,
} VkSurfaceTransformFlagBitsKHR;

  • VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR specifies that image content is presented without being transformed.

  • VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR specifies that image content is rotated 90 degrees clockwise.

  • VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR specifies that image content is rotated 180 degrees clockwise.

  • VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR specifies that image content is rotated 270 degrees clockwise.

  • VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR specifies that image content is mirrored horizontally.

  • VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR specifies that image content is mirrored horizontally, then rotated 90 degrees clockwise.

  • VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR specifies that image content is mirrored horizontally, then rotated 180 degrees clockwise.

  • VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR specifies that image content is mirrored horizontally, then rotated 270 degrees clockwise.

  • VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR specifies that the presentation transform is not specified, and is instead determined by platform-specific considerations and mechanisms outside Vulkan.

// Provided by VK_KHR_display
typedef VkFlags VkSurfaceTransformFlagsKHR;

VkSurfaceTransformFlagsKHR is a bitmask type for setting a mask of zero or more VkSurfaceTransformFlagBitsKHR.

The supportedCompositeAlpha member is of type VkCompositeAlphaFlagBitsKHR, which contains the following values:

// Provided by VK_KHR_surface
typedef enum VkCompositeAlphaFlagBitsKHR {
    VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR = 0x00000001,
    VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR = 0x00000002,
    VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR = 0x00000004,
    VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR = 0x00000008,
} VkCompositeAlphaFlagBitsKHR;

These values are described as follows:

  • VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha channel, if it exists, of the images is ignored in the compositing process. Instead, the image is treated as if it has a constant alpha of 1.0.

  • VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha channel, if it exists, of the images is respected in the compositing process. The non-alpha channels of the image are expected to already be multiplied by the alpha channel by the application.

  • VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha channel, if it exists, of the images is respected in the compositing process. The non-alpha channels of the image are not expected to already be multiplied by the alpha channel by the application; instead, the compositor will multiply the non-alpha channels of the image by the alpha channel during compositing.

  • VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the presentation engine treats the alpha channel in the images is unknown to the Vulkan API. Instead, the application is responsible for setting the composite alpha blending mode using native window system commands. If the application does not set the blending mode using native window system commands, then a platform-specific default will be used.

// Provided by VK_KHR_surface
typedef VkFlags VkCompositeAlphaFlagsKHR;

VkCompositeAlphaFlagsKHR is a bitmask type for setting a mask of zero or more VkCompositeAlphaFlagBitsKHR.

32.5.2. Surface Format Support

To query the supported swapchain format-color space pairs for a surface, call:

// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfaceFormatsKHR(
    VkPhysicalDevice                            physicalDevice,
    VkSurfaceKHR                                surface,
    uint32_t*                                   pSurfaceFormatCount,
    VkSurfaceFormatKHR*                         pSurfaceFormats);

  • physicalDevice is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR.

  • surface is the surface that will be associated with the swapchain.

  • pSurfaceFormatCount is a pointer to an integer related to the number of format pairs available or queried, as described below.

  • pSurfaceFormats is either NULL or a pointer to an array of VkSurfaceFormatKHR structures.

If pSurfaceFormats is NULL, then the number of format pairs supported for the given surface is returned in pSurfaceFormatCount. Otherwise, pSurfaceFormatCount must point to a variable set by the user to the number of elements in the pSurfaceFormats array, and on return the variable is overwritten with the number of structures actually written to pSurfaceFormats. If the value of pSurfaceFormatCount is less than the number of format pairs supported, at most pSurfaceFormatCount structures will be written. If pSurfaceFormatCount is smaller than the number of format pairs supported for the given surface, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

The number of format pairs supported must be greater than or equal to 1. pSurfaceFormats must not contain an entry whose value for format is VK_FORMAT_UNDEFINED.

If pSurfaceFormats includes an entry whose value for colorSpace is VK_COLOR_SPACE_SRGB_NONLINEAR_KHR and whose value for format is a UNORM (or SRGB) format and the corresponding SRGB (or UNORM) format is a color renderable format for VK_IMAGE_TILING_OPTIMAL, then pSurfaceFormats must also contain an entry with the same value for colorSpace and format equal to the corresponding SRGB (or UNORM) format.

Valid Usage
Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • surface must be a valid VkSurfaceKHR handle

  • pSurfaceFormatCount must be a valid pointer to a uint32_t value

  • If the value referenced by pSurfaceFormatCount is not 0, and pSurfaceFormats is not NULL, pSurfaceFormats must be a valid pointer to an array of pSurfaceFormatCount VkSurfaceFormatKHR structures

  • Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

The VkSurfaceFormatKHR structure is defined as:

// Provided by VK_KHR_surface
typedef struct VkSurfaceFormatKHR {
    VkFormat           format;
    VkColorSpaceKHR    colorSpace;
} VkSurfaceFormatKHR;

  • format is a VkFormat that is compatible with the specified surface.

  • colorSpace is a presentation VkColorSpaceKHR that is compatible with the surface.

To query the supported swapchain format tuples for a surface, call:

// Provided by VK_KHR_get_surface_capabilities2
VkResult vkGetPhysicalDeviceSurfaceFormats2KHR(
    VkPhysicalDevice                            physicalDevice,
    const VkPhysicalDeviceSurfaceInfo2KHR*      pSurfaceInfo,
    uint32_t*                                   pSurfaceFormatCount,
    VkSurfaceFormat2KHR*                        pSurfaceFormats);

  • physicalDevice is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR.

  • pSurfaceInfo is a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR.

  • pSurfaceFormatCount is a pointer to an integer related to the number of format tuples available or queried, as described below.

  • pSurfaceFormats is either NULL or a pointer to an array of VkSurfaceFormat2KHR structures.

vkGetPhysicalDeviceSurfaceFormats2KHR behaves similarly to vkGetPhysicalDeviceSurfaceFormatsKHR, with the ability to be extended via pNext chains.

If pSurfaceFormats is NULL, then the number of format tuples supported for the given surface is returned in pSurfaceFormatCount. Otherwise, pSurfaceFormatCount must point to a variable set by the user to the number of elements in the pSurfaceFormats array, and on return the variable is overwritten with the number of structures actually written to pSurfaceFormats. If the value of pSurfaceFormatCount is less than the number of format tuples supported, at most pSurfaceFormatCount structures will be written. If pSurfaceFormatCount is smaller than the number of format tuples supported for the surface parameters described in pSurfaceInfo, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage
Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • pSurfaceInfo must be a valid pointer to a valid VkPhysicalDeviceSurfaceInfo2KHR structure

  • pSurfaceFormatCount must be a valid pointer to a uint32_t value

  • If the value referenced by pSurfaceFormatCount is not 0, and pSurfaceFormats is not NULL, pSurfaceFormats must be a valid pointer to an array of pSurfaceFormatCount VkSurfaceFormat2KHR structures

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

The VkSurfaceFormat2KHR structure is defined as:

// Provided by VK_KHR_get_surface_capabilities2
typedef struct VkSurfaceFormat2KHR {
    VkStructureType       sType;
    void*                 pNext;
    VkSurfaceFormatKHR    surfaceFormat;
} VkSurfaceFormat2KHR;

  • sType is the type of this structure.

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

  • surfaceFormat is a VkSurfaceFormatKHR structure describing a format-color space pair that is compatible with the specified surface.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SURFACE_FORMAT_2_KHR

  • pNext must be NULL

While the format of a presentable image refers to the encoding of each pixel, the colorSpace determines how the presentation engine interprets the pixel values. A color space in this document refers to a specific color space (defined by the chromaticities of its primaries and a white point in CIE Lab), and a transfer function that is applied before storing or transmitting color data in the given color space.

Possible values of VkSurfaceFormatKHR::colorSpace, specifying supported color spaces of a presentation engine, are:

// Provided by VK_KHR_surface
typedef enum VkColorSpaceKHR {
    VK_COLOR_SPACE_SRGB_NONLINEAR_KHR = 0,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT = 1000104001,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT = 1000104002,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT = 1000104003,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT = 1000104004,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_BT709_LINEAR_EXT = 1000104005,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_BT709_NONLINEAR_EXT = 1000104006,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_BT2020_LINEAR_EXT = 1000104007,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_HDR10_ST2084_EXT = 1000104008,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_DOLBYVISION_EXT = 1000104009,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_HDR10_HLG_EXT = 1000104010,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT = 1000104011,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT = 1000104012,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_PASS_THROUGH_EXT = 1000104013,
  // Provided by VK_EXT_swapchain_colorspace
    VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT = 1000104014,
  // Provided by VK_AMD_display_native_hdr
    VK_COLOR_SPACE_DISPLAY_NATIVE_AMD = 1000213000,
    VK_COLORSPACE_SRGB_NONLINEAR_KHR = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR,
    VK_COLOR_SPACE_DCI_P3_LINEAR_EXT = VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT,
} VkColorSpaceKHR;

  • VK_COLOR_SPACE_SRGB_NONLINEAR_KHR specifies support for the sRGB color space.

  • VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT specifies support for the Display-P3 color space to be displayed using an sRGB-like EOTF (defined below).

  • VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT specifies support for the extended sRGB color space to be displayed using a linear EOTF.

  • VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT specifies support for the extended sRGB color space to be displayed using an sRGB EOTF.

  • VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT specifies support for the Display-P3 color space to be displayed using a linear EOTF.

  • VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT specifies support for the DCI-P3 color space to be displayed using the DCI-P3 EOTF. Note that values in such an image are interpreted as XYZ encoded color data by the presentation engine.

  • VK_COLOR_SPACE_BT709_LINEAR_EXT specifies support for the BT709 color space to be displayed using a linear EOTF.

  • VK_COLOR_SPACE_BT709_NONLINEAR_EXT specifies support for the BT709 color space to be displayed using the SMPTE 170M EOTF.

  • VK_COLOR_SPACE_BT2020_LINEAR_EXT specifies support for the BT2020 color space to be displayed using a linear EOTF.

  • VK_COLOR_SPACE_HDR10_ST2084_EXT specifies support for the HDR10 (BT2020 color) space to be displayed using the SMPTE ST2084 Perceptual Quantizer (PQ) EOTF.

  • VK_COLOR_SPACE_DOLBYVISION_EXT specifies support for the Dolby Vision (BT2020 color space), proprietary encoding, to be displayed using the SMPTE ST2084 EOTF.

  • VK_COLOR_SPACE_HDR10_HLG_EXT specifies support for the HDR10 (BT2020 color space) to be displayed using the Hybrid Log Gamma (HLG) EOTF.

  • VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT specifies support for the AdobeRGB color space to be displayed using a linear EOTF.

  • VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT specifies support for the AdobeRGB color space to be displayed using the Gamma 2.2 EOTF.

  • VK_COLOR_SPACE_PASS_THROUGH_EXT specifies that color components are used “as is”. This is intended to allow applications to supply data for color spaces not described here.

  • VK_COLOR_SPACE_DISPLAY_NATIVE_AMD specifies support for the display’s native color space. This matches the color space expectations of AMD’s FreeSync2 standard, for displays supporting it.

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, VK_COLOR_SPACE_SRGB_NONLINEAR_KHR is used instead for consistency with Vulkan naming rules. The older enum is still available for backwards compatibility.
Note

In older versions of this extension VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT was misnamed VK_COLOR_SPACE_DCI_P3_LINEAR_EXT. This has been updated to indicate that it uses RGB color encoding, not XYZ. The old name is deprecated but is maintained for backwards compatibility.

The color components of non-linear color space swap chain images must have had the appropriate transfer function applied. The color space selected for the swap chain image will not affect the processing of data written into the image by the implementation. Vulkan requires that all implementations support the sRGB transfer function by use of an SRGB pixel format. Other transfer functions, such as SMPTE 170M or SMPTE2084, can be performed by the application shader. This extension defines enums for VkColorSpaceKHR that correspond to the following color spaces:

Table 44. Color Spaces and Attributes
Name Red Primary Green Primary Blue Primary White-point Transfer function

DCI-P3

1.000, 0.000

0.000, 1.000

0.000, 0.000

0.3333, 0.3333

DCI P3

Display-P3

0.680, 0.320

0.265, 0.690

0.150, 0.060

0.3127, 0.3290 (D65)

Display-P3

BT709

0.640, 0.330

0.300, 0.600

0.150, 0.060

0.3127, 0.3290 (D65)

ITU (SMPTE 170M)

sRGB

0.640, 0.330

0.300, 0.600

0.150, 0.060

0.3127, 0.3290 (D65)

sRGB

extended sRGB

0.640, 0.330

0.300, 0.600

0.150, 0.060

0.3127, 0.3290 (D65)

extended sRGB

HDR10_ST2084

0.708, 0.292

0.170, 0.797

0.131, 0.046

0.3127, 0.3290 (D65)

ST2084 PQ

DOLBYVISION

0.708, 0.292

0.170, 0.797

0.131, 0.046

0.3127, 0.3290 (D65)

ST2084 PQ

HDR10_HLG

0.708, 0.292

0.170, 0.797

0.131, 0.046

0.3127, 0.3290 (D65)

HLG

AdobeRGB

0.640, 0.330

0.210, 0.710

0.150, 0.060

0.3127, 0.3290 (D65)

AdobeRGB

The transfer functions are described in the “Transfer Functions” chapter of the Khronos Data Format Specification.

Except Display-P3 OETF, which is:

where L is the linear value of a color channel and E is the encoded value (as stored in the image in memory).

Note

For most uses, the sRGB OETF is equivalent.

32.5.3. Surface Presentation Mode Support

To query the supported presentation modes for a surface, call:

// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfacePresentModesKHR(
    VkPhysicalDevice                            physicalDevice,
    VkSurfaceKHR                                surface,
    uint32_t*                                   pPresentModeCount,
    VkPresentModeKHR*                           pPresentModes);

  • physicalDevice is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR.

  • surface is the surface that will be associated with the swapchain.

  • pPresentModeCount is a pointer to an integer related to the number of presentation modes available or queried, as described below.

  • pPresentModes is either NULL or a pointer to an array of VkPresentModeKHR values, indicating the supported presentation modes.

If pPresentModes is NULL, then the number of presentation modes supported for the given surface is returned in pPresentModeCount. Otherwise, pPresentModeCount must point to a variable set by the user to the number of elements in the pPresentModes array, and on return the variable is overwritten with the number of values actually written to pPresentModes. If the value of pPresentModeCount is less than the number of presentation modes supported, at most pPresentModeCount values will be written. If pPresentModeCount is smaller than the number of presentation modes supported for the given surface, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • surface must be a valid VkSurfaceKHR handle

  • pPresentModeCount must be a valid pointer to a uint32_t value

  • If the value referenced by pPresentModeCount is not 0, and pPresentModes is not NULL, pPresentModes must be a valid pointer to an array of pPresentModeCount VkPresentModeKHR values

  • Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

Alternatively, to query the supported presentation modes for a surface combined with select other fixed swapchain creation parameters, call:

// Provided by VK_EXT_full_screen_exclusive
VkResult vkGetPhysicalDeviceSurfacePresentModes2EXT(
    VkPhysicalDevice                            physicalDevice,
    const VkPhysicalDeviceSurfaceInfo2KHR*      pSurfaceInfo,
    uint32_t*                                   pPresentModeCount,
    VkPresentModeKHR*                           pPresentModes);

  • physicalDevice is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR.

  • pSurfaceInfo is a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR.

  • pPresentModeCount is a pointer to an integer related to the number of presentation modes available or queried, as described below.

  • pPresentModes is either NULL or a pointer to an array of VkPresentModeKHR values, indicating the supported presentation modes.

vkGetPhysicalDeviceSurfacePresentModes2EXT behaves similarly to vkGetPhysicalDeviceSurfacePresentModesKHR, with the ability to specify extended inputs via chained input structures.

Valid Usage (Implicit)

  • physicalDevice must be a valid VkPhysicalDevice handle

  • pSurfaceInfo must be a valid pointer to a valid VkPhysicalDeviceSurfaceInfo2KHR structure

  • pPresentModeCount must be a valid pointer to a uint32_t value

  • If the value referenced by pPresentModeCount is not 0, and pPresentModes is not NULL, pPresentModes must be a valid pointer to an array of pPresentModeCount VkPresentModeKHR values

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

Possible values of elements of the vkGetPhysicalDeviceSurfacePresentModesKHR::pPresentModes array, indicating the supported presentation modes for a surface, are:

// Provided by VK_KHR_surface
typedef enum VkPresentModeKHR {
    VK_PRESENT_MODE_IMMEDIATE_KHR = 0,
    VK_PRESENT_MODE_MAILBOX_KHR = 1,
    VK_PRESENT_MODE_FIFO_KHR = 2,
    VK_PRESENT_MODE_FIFO_RELAXED_KHR = 3,
  // Provided by VK_KHR_shared_presentable_image
    VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR = 1000111000,
  // Provided by VK_KHR_shared_presentable_image
    VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR = 1000111001,
} VkPresentModeKHR;

  • VK_PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately.

  • VK_PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for re-use by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.

  • VK_PRESENT_MODE_FIFO_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty. This is the only value of presentMode that is required to be supported.

  • VK_PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during or after each vertical blanking period in which the queue is non-empty.

  • VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing.

  • VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.

The supported VkImageUsageFlagBits 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:

Table 45. Presentable image usage queries
Presentation mode Image usage flags

VK_PRESENT_MODE_IMMEDIATE_KHR

VkSurfaceCapabilitiesKHR::supportedUsageFlags

VK_PRESENT_MODE_MAILBOX_KHR

VkSurfaceCapabilitiesKHR::supportedUsageFlags

VK_PRESENT_MODE_FIFO_KHR

VkSurfaceCapabilitiesKHR::supportedUsageFlags

VK_PRESENT_MODE_FIFO_RELAXED_KHR

VkSurfaceCapabilitiesKHR::supportedUsageFlags

VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR

VkSharedPresentSurfaceCapabilitiesKHR::sharedPresentSupportedUsageFlags

VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR

VkSharedPresentSurfaceCapabilitiesKHR::sharedPresentSupportedUsageFlags
Note

For reference, the mode indicated by VK_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 VK_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).

32.6. Full Screen Exclusive Control

Swapchains created with fullScreenExclusive set to VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT must acquire and release exclusive full-screen access explicitly, using the following commands.

To acquire exclusive full-screen access for a swapchain, call:

// Provided by VK_EXT_full_screen_exclusive
VkResult vkAcquireFullScreenExclusiveModeEXT(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain);

  • device is the device associated with swapchain.

  • swapchain is the swapchain to acquire exclusive full-screen access for.

Valid Usage

  • swapchain must not be in the retired state

  • swapchain must be a swapchain created with a VkSurfaceFullScreenExclusiveInfoEXT structure, with fullScreenExclusive set to VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT

  • swapchain must not currently have exclusive full-screen access

A return value of VK_SUCCESS indicates that the swapchain successfully acquired exclusive full-screen access. The swapchain will retain this exclusivity until either the application releases exclusive full-screen access with vkReleaseFullScreenExclusiveModeEXT, destroys the swapchain, or if any of the swapchain commands return VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT indicating that the mode was lost because of platform-specific changes.

If the swapchain was unable to acquire exclusive full-screen access to the display then VK_ERROR_INITIALIZATION_FAILED is returned. An application can attempt to acquire exclusive full-screen access again for the same swapchain even if this command fails, or if VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT has been returned by a swapchain command.

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • swapchain must be a valid VkSwapchainKHR handle

  • Both of device, and swapchain must have been created, allocated, or retrieved from the same VkInstance

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_SURFACE_LOST_KHR

To release exclusive full-screen access from a swapchain, call:

// Provided by VK_EXT_full_screen_exclusive
VkResult vkReleaseFullScreenExclusiveModeEXT(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain);

  • device is the device associated with swapchain.

  • swapchain is the swapchain to release exclusive full-screen access from.

Note

Applications will not be able to present to swapchain after this call until exclusive full-screen access is reacquired. This is usually useful to handle when an application is minimised or otherwise intends to stop presenting for a time.
Valid Usage

  • swapchain must not be in the retired state

  • swapchain must be a swapchain created with a VkSurfaceFullScreenExclusiveInfoEXT structure, with fullScreenExclusive set to VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT

32.7. Device Group Queries

A logical device that represents multiple physical devices may support presenting from images on more than one physical device, or combining images from multiple physical devices.

To query these capabilities, call:

// Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_surface
VkResult vkGetDeviceGroupPresentCapabilitiesKHR(
    VkDevice                                    device,
    VkDeviceGroupPresentCapabilitiesKHR*        pDeviceGroupPresentCapabilities);

  • device is the logical device.

  • pDeviceGroupPresentCapabilities is a pointer to a VkDeviceGroupPresentCapabilitiesKHR structure in which the device’s capabilities are returned.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

The VkDeviceGroupPresentCapabilitiesKHR structure is defined as:

// Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_surface
typedef struct VkDeviceGroupPresentCapabilitiesKHR {
    VkStructureType                     sType;
    const void*                         pNext;
    uint32_t                            presentMask[VK_MAX_DEVICE_GROUP_SIZE];
    VkDeviceGroupPresentModeFlagsKHR    modes;
} VkDeviceGroupPresentCapabilitiesKHR;

  • sType is the type of this structure.

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

  • presentMask is an array of VK_MAX_DEVICE_GROUP_SIZE uint32_t masks, where the mask at element i is non-zero if physical device i has a presentation engine, and where bit j is set in element i if physical device i can present swapchain images from physical device j. If element i is non-zero, then bit i must be set.

  • modes is a bitmask of VkDeviceGroupPresentModeFlagBitsKHR indicating which device group presentation modes are supported.

modes always has VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR set.

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

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

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR

  • pNext must be NULL

Bits which may be set in VkDeviceGroupPresentCapabilitiesKHR::modes to indicate which device group presentation modes are supported are:

// Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_surface
typedef enum VkDeviceGroupPresentModeFlagBitsKHR {
    VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR = 0x00000001,
    VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR = 0x00000002,
    VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR = 0x00000004,
    VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR = 0x00000008,
} VkDeviceGroupPresentModeFlagBitsKHR;

  • VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR specifies that any physical device with a presentation engine can present its own swapchain images.

  • VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR specifies that any physical device with a presentation engine can present swapchain images from any physical device in its presentMask.

  • VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR specifies that any physical device with a presentation engine can present the sum of swapchain images from any physical devices in its presentMask.

  • VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR specifies that multiple physical devices with a presentation engine can each present their own swapchain images.

// Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_surface
typedef VkFlags VkDeviceGroupPresentModeFlagsKHR;

VkDeviceGroupPresentModeFlagsKHR is a bitmask type for setting a mask of zero or more VkDeviceGroupPresentModeFlagBitsKHR.

Some surfaces may not be capable of using all the device group present modes.

To query the supported device group present modes for a particular surface, call:

// Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_surface
VkResult vkGetDeviceGroupSurfacePresentModesKHR(
    VkDevice                                    device,
    VkSurfaceKHR                                surface,
    VkDeviceGroupPresentModeFlagsKHR*           pModes);

  • device is the logical device.

  • surface is the surface.

  • pModes is a pointer to a VkDeviceGroupPresentModeFlagsKHR in which the supported device group present modes for the surface are returned.

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

Valid Usage (Implicit)
Host Synchronization

  • Host access to surface must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

Alternatively, to query the supported device group presentation modes for a surface combined with select other fixed swapchain creation parameters, call:

// Provided by VK_EXT_full_screen_exclusive with VK_KHR_device_group, VK_EXT_full_screen_exclusive with VK_VERSION_1_1
VkResult vkGetDeviceGroupSurfacePresentModes2EXT(
    VkDevice                                    device,
    const VkPhysicalDeviceSurfaceInfo2KHR*      pSurfaceInfo,
    VkDeviceGroupPresentModeFlagsKHR*           pModes);

vkGetDeviceGroupSurfacePresentModes2EXT behaves similarly to vkGetDeviceGroupSurfacePresentModesKHR, with the ability to specify extended inputs via chained input structures.

Valid Usage (Implicit)
Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

When using VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, the application may need to know which regions of the surface are used when presenting locally on each physical device. Presentation of swapchain images to this surface need only have valid contents in the regions returned by this command.

To query a set of rectangles used in presentation on the physical device, call:

// Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_surface
VkResult vkGetPhysicalDevicePresentRectanglesKHR(
    VkPhysicalDevice                            physicalDevice,
    VkSurfaceKHR                                surface,
    uint32_t*                                   pRectCount,
    VkRect2D*                                   pRects);

  • physicalDevice is the physical device.

  • surface is the surface.

  • pRectCount is a pointer to an integer related to the number of rectangles available or queried, as described below.

  • pRects is either NULL or a pointer to an array of VkRect2D structures.

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, VK_INCOMPLETE will be returned instead of VK_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 VkPhysicalDevice handle

  • surface must be a valid VkSurfaceKHR 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 VkRect2D structures

  • Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

  • Host access to surface must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

32.8. Display Timing Queries

Traditional game and real-time-animation applications frequently use VK_PRESENT_MODE_FIFO_KHR so that presentable images are updated during the vertical blanking period of a given refresh cycle (RC) of the presentation engine’s display. This avoids the visual anomaly known as tearing.

However, synchronizing the presentation of images with the RC does not prevent all forms of visual anomalies. Stuttering occurs when the geometry for each presentable image is not accurately positioned for when that image will be displayed. The geometry may appear to move too little some RCs, and too much for others. Sometimes the animation appears to freeze, when the same image is used for more than one RC.

In order to minimize stuttering, an application needs to correctly position their geometry for when the presentable image will be displayed to the user. To accomplish this, applications need various timing information about the presentation engine’s display. They need to know when presentable images were actually presented, and when they could have been presented. Applications also need to tell the presentation engine to display an image no sooner than a given time. This can allow the application’s animation to look smooth to the user, with no stuttering. The VK_GOOGLE_display_timing extension allows an application to satisfy these needs.

The presentation engine’s display typically refreshes the pixels that are displayed to the user on a periodic basis. The period may be fixed or variable. In many cases, the presentation engine is associated with fixed refresh rate (FRR) display technology, with a fixed refresh rate (RR, e.g. 60Hz). In some cases, the presentation engine is associated with variable refresh rate (VRR) display technology, where each refresh cycle (RC) can vary in length. This extension treats VRR displays as if they are FRR.

To query the duration of a refresh cycle (RC) for the presentation engine’s display, call:

// Provided by VK_GOOGLE_display_timing
VkResult vkGetRefreshCycleDurationGOOGLE(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    VkRefreshCycleDurationGOOGLE*               pDisplayTimingProperties);

  • device is the device associated with swapchain.

  • swapchain is the swapchain to obtain the refresh duration for.

  • pDisplayTimingProperties is a pointer to a VkRefreshCycleDurationGOOGLE structure.

Valid Usage (Implicit)
Host Synchronization

  • Host access to swapchain must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_SURFACE_LOST_KHR

The VkRefreshCycleDurationGOOGLE structure is defined as:

// Provided by VK_GOOGLE_display_timing
typedef struct VkRefreshCycleDurationGOOGLE {
    uint64_t    refreshDuration;
} VkRefreshCycleDurationGOOGLE;

  • refreshDuration is the number of nanoseconds from the start of one refresh cycle to the next.

Note

The rate at which an application renders and presents new images is known as the image present rate (IPR, aka frame rate). The inverse of IPR, or the duration between each image present, is the image present duration (IPD). In order to provide a smooth, stutter-free animation, an application will want its IPD to be a multiple of refreshDuration. For example, if a display has a 60Hz refresh rate, refreshDuration will be a value in nanoseconds that is approximately equal to 16.67ms. In such a case, an application will want an IPD of 16.67ms (1X multiplier of refreshDuration), or 33.33ms (2X multiplier of refreshDuration), or 50.0ms (3X multiplier of refreshDuration), etc.

In order to determine a target IPD for a display (i.e. a multiple of refreshDuration), an application needs to determine when its images are actually displayed. Let’s say that an application has an initial target IPD of 16.67ms (1X multiplier of refreshDuration). It will therefore position the geometry of a new image 16.67ms later than the previous image. Let’s say that this application is running on slower hardware, so that it actually takes 20ms to render each new image. This will create visual anomalies, because the images will not be displayed to the user every 16.67ms, nor every 20ms. In this case, it is better for the application to adjust its target IPD to 33.33ms (i.e. a 2X multiplier of refreshDuration), and tell the presentation engine to not present images any sooner than every 33.33ms. This will allow the geometry to be correctly positioned for each presentable image.

Adjustments to an application’s IPD may be needed because different views of an application’s geometry can take different amounts of time to render. For example, looking at the sky may take less time to render than looking at multiple, complex items in a room. In general, it is good to not frequently change IPD, as that can cause visual anomalies. Adjustments to a larger IPD because of late images should happen quickly, but adjustments to a smaller IPD should only happen if the actualPresentTime and earliestPresentTime members of the VkPastPresentationTimingGOOGLE structure are consistently different, and if presentMargin is consistently large, over multiple images.

The implementation will maintain a limited amount of history of timing information about previous presents. Because of the asynchronous nature of the presentation engine, the timing information for a given vkQueuePresentKHR command will become available some time later. These time values can be asynchronously queried, and will be returned if available. All time values are in nanoseconds, relative to a monotonically-increasing clock (e.g. CLOCK_MONOTONIC (see clock_gettime(2)) on Android and Linux).

To asynchronously query the presentation engine, for newly-available timing information about one or more previous presents to a given swapchain, call:

// Provided by VK_GOOGLE_display_timing
VkResult vkGetPastPresentationTimingGOOGLE(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    uint32_t*                                   pPresentationTimingCount,
    VkPastPresentationTimingGOOGLE*             pPresentationTimings);

  • device is the device associated with swapchain.

  • swapchain is the swapchain to obtain presentation timing information duration for.

  • pPresentationTimingCount is a pointer to an integer related to the number of VkPastPresentationTimingGOOGLE structures to query, as described below.

  • pPresentationTimings is either NULL or a pointer to an array of VkPastPresentationTimingGOOGLE structures.

If pPresentationTimings is NULL, then the number of newly-available timing records for the given swapchain is returned in pPresentationTimingCount. Otherwise, pPresentationTimingCount must point to a variable set by the user to the number of elements in the pPresentationTimings array, and on return the variable is overwritten with the number of structures actually written to pPresentationTimings. If the value of pPresentationTimingCount is less than the number of newly-available timing records, at most pPresentationTimingCount structures will be written. If pPresentationTimingCount is smaller than the number of newly-available timing records for the given swapchain, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • swapchain must be a valid VkSwapchainKHR handle

  • pPresentationTimingCount must be a valid pointer to a uint32_t value

  • If the value referenced by pPresentationTimingCount is not 0, and pPresentationTimings is not NULL, pPresentationTimings must be a valid pointer to an array of pPresentationTimingCount VkPastPresentationTimingGOOGLE structures

  • Both of device, and swapchain must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

  • Host access to swapchain must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_OUT_OF_DATE_KHR

  • VK_ERROR_SURFACE_LOST_KHR

The VkPastPresentationTimingGOOGLE structure is defined as:

// Provided by VK_GOOGLE_display_timing
typedef struct VkPastPresentationTimingGOOGLE {
    uint32_t    presentID;
    uint64_t    desiredPresentTime;
    uint64_t    actualPresentTime;
    uint64_t    earliestPresentTime;
    uint64_t    presentMargin;
} VkPastPresentationTimingGOOGLE;

  • presentID is an application-provided value that was given to a previous vkQueuePresentKHR command via VkPresentTimeGOOGLE::presentID (see below). It can be used to uniquely identify a previous present with the vkQueuePresentKHR command.

  • desiredPresentTime is an application-provided value that was given to a previous vkQueuePresentKHR command via VkPresentTimeGOOGLE::desiredPresentTime. If non-zero, it was used by the application to indicate that an image not be presented any sooner than desiredPresentTime.

  • actualPresentTime is the time when the image of the swapchain was actually displayed.

  • earliestPresentTime is the time when the image of the swapchain could have been displayed. This may differ from actualPresentTime if the application requested that the image be presented no sooner than VkPresentTimeGOOGLE::desiredPresentTime.

  • presentMargin is an indication of how early the vkQueuePresentKHR command was processed compared to how soon it needed to be processed, and still be presented at earliestPresentTime.

The results for a given swapchain and presentID are only returned once from vkGetPastPresentationTimingGOOGLE.

The application can use the VkPastPresentationTimingGOOGLE values to occasionally adjust its timing. For example, if actualPresentTime is later than expected (e.g. one refreshDuration late), the application may increase its target IPD to a higher multiple of refreshDuration (e.g. decrease its frame rate from 60Hz to 30Hz). If actualPresentTime and earliestPresentTime are consistently different, and if presentMargin is consistently large enough, the application may decrease its target IPD to a smaller multiple of refreshDuration (e.g. increase its frame rate from 30Hz to 60Hz). If actualPresentTime and earliestPresentTime are same, and if presentMargin is consistently high, the application may delay the start of its input-render-present loop in order to decrease the latency between user input and the corresponding present (always leaving some margin in case a new image takes longer to render than the previous image). An application that desires its target IPD to always be the same as refreshDuration, can also adjust features until actualPresentTime is never late and presentMargin is satisfactory.

The full VK_GOOGLE_display_timing extension semantics are described for swapchains created with VK_PRESENT_MODE_FIFO_KHR. For example, non-zero values of VkPresentTimeGOOGLE::desiredPresentTime must be honored, and vkGetPastPresentationTimingGOOGLE should return a VkPastPresentationTimingGOOGLE structure with valid values for all images presented with vkQueuePresentKHR. The semantics for other present modes are as follows:

  • VK_PRESENT_MODE_IMMEDIATE_KHR. The presentation engine may ignore non-zero values of VkPresentTimeGOOGLE::desiredPresentTime in favor of presenting immediately. The value of VkPastPresentationTimingGOOGLE::earliestPresentTime must be the same as VkPastPresentationTimingGOOGLE::actualPresentTime, which should be when the presentation engine displayed the image.

  • VK_PRESENT_MODE_MAILBOX_KHR. The intention of using this present mode with this extension is to handle cases where an image is presented late, and the next image is presented soon enough to replace it at the next vertical blanking period. For images that are displayed to the user, the value of VkPastPresentationTimingGOOGLE::actualPresentTime must be when the image was displayed. For images that are not displayed to the user, vkGetPastPresentationTimingGOOGLE may not return a VkPastPresentationTimingGOOGLE structure, or it may return a VkPastPresentationTimingGOOGLE structure with the value of zero for both VkPastPresentationTimingGOOGLE::actualPresentTime and VkPastPresentationTimingGOOGLE::earliestPresentTime. It is possible that an application can submit images with VkPresentTimeGOOGLE::desiredPresentTime values such that new images may not be displayed. For example, if VkPresentTimeGOOGLE::desiredPresentTime is far enough in the future that an image is not presented before vkQueuePresentKHR is called to present another image, the first image will not be displayed to the user. If the application continues to do that, the presentation may not display new images.

  • VK_PRESENT_MODE_FIFO_RELAXED_KHR. For images that are presented in time to be displayed at the next vertical blanking period, the semantics are identical as for VK_PRESENT_MODE_FIFO_RELAXED_KHR. For images that are presented late, and are displayed after the start of the vertical blanking period (i.e. with tearing), the values of VkPastPresentationTimingGOOGLE may be treated as if the image was displayed at the start of the vertical blanking period, or may be treated the same as for VK_PRESENT_MODE_IMMEDIATE_KHR.

32.9. WSI Swapchain

A swapchain object (a.k.a. swapchain) provides the ability to present rendering results to a surface. Swapchain objects are represented by VkSwapchainKHR handles:

// Provided by VK_KHR_swapchain
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSwapchainKHR)

A swapchain is an abstraction for an array of presentable images that are associated with a surface. The presentable images are represented by VkImage 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 vkAcquireNextImageKHR, and before it is presented by vkQueuePresentKHR. This includes transitioning the image layout and rendering commands.

An application can acquire use of a presentable image with vkAcquireNextImageKHR. 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 vkQueuePresentKHR, 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.

How this all works is described below.

If a swapchain is created with presentMode set to either VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, a single presentable image can be acquired, referred to as a shared presentable image. A shared presentable image may be concurrently accessed by the application and the presentation engine, without transitioning the image’s layout after it is initially presented.

  • With VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR, the presentation engine is only required to update to the latest contents of a shared presentable image after a present. The application must call vkQueuePresentKHR to guarantee an update. However, the presentation engine may update from it at any time.

  • With VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, the presentation engine will automatically present the latest contents of a shared presentable image during every refresh cycle. The application is only required to make one initial call to vkQueuePresentKHR, after which the presentation engine will update from it without any need for further present calls. The application can indicate the image contents have been updated by calling vkQueuePresentKHR, but this does not guarantee the timing of when updates will occur.

The presentation engine may access a shared presentable image at any time after it is first presented. To avoid tearing, an application should coordinate access with the presentation engine. This requires presentation engine timing information through platform-specific mechanisms and ensuring that color attachment writes are made available during the portion of the presentation engine’s refresh cycle they are intended for.

Note

The VK_KHR_shared_presentable_image extension does not provide functionality for determining the timing of the presentation engine’s refresh cycles.

In order to query a swapchain’s status when rendering to a shared presentable image, call:

// Provided by VK_KHR_shared_presentable_image
VkResult vkGetSwapchainStatusKHR(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain);

  • device is the device associated with swapchain.

  • swapchain is the swapchain to query.

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • swapchain must be a valid VkSwapchainKHR handle

  • Both of device, and swapchain must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

  • Host access to swapchain must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

  • VK_SUBOPTIMAL_KHR

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_OUT_OF_DATE_KHR

  • VK_ERROR_SURFACE_LOST_KHR

  • VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

The possible return values for vkGetSwapchainStatusKHR should be interpreted as follows:

  • VK_SUCCESS specifies the presentation engine is presenting the contents of the shared presentable image, as per the swapchain’s VkPresentModeKHR.

  • VK_SUBOPTIMAL_KHR the swapchain no longer matches the surface properties exactly, but the presentation engine is presenting the contents of the shared presentable image, as per the swapchain’s VkPresentModeKHR.

  • VK_ERROR_OUT_OF_DATE_KHR the surface has changed in such a way that it is no longer compatible with the swapchain.

  • VK_ERROR_SURFACE_LOST_KHR the surface is no longer available.

Note

The swapchain state may be cached by implementations, so applications should regularly call vkGetSwapchainStatusKHR when using a swapchain with VkPresentModeKHR set to VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR.

To create a swapchain, call:

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

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

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, VK_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)
Host Synchronization

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

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

Return Codes
Success

  • VK_SUCCESS

Failure

  • 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

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 the type of 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.

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 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. VK_TRUE value does not guarantee any clipping will occur, but allows more optimal 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.

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

Note

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, vkQueuePresentKHR may 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

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

  • 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

  • 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

  • minImageCount must be 1 if presentMode is either VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR

  • 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

  • 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 VkSurfaceCapabilitiesKHR structure returned by vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface

  • 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

  • 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

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

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

  • 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

  • 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

  • If the logical device was created with VkDeviceGroupDeviceCreateInfo::physicalDeviceCount equal to 1, flags must not contain VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR

  • If oldSwapchain is not VK_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 vkGetPhysicalDeviceImageFormatProperties

  • 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

  • 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

  • If flags dose 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

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

  • 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

Valid Usage (Implicit)

Bits which can be set in VkSwapchainCreateInfoKHR::flags, specifying parameters of swapchain creation, are:

// Provided by VK_KHR_swapchain
typedef enum VkSwapchainCreateFlagBitsKHR {
  // Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_swapchain
    VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR = 0x00000001,
  // Provided by VK_KHR_swapchain with VK_VERSION_1_1
    VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR = 0x00000002,
  // Provided by VK_KHR_swapchain_mutable_format
    VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR = 0x00000004,
} VkSwapchainCreateFlagBitsKHR;

  • VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR specifies that images created from the swapchain (i.e. with the swapchain member of VkImageSwapchainCreateInfoKHR set to this swapchain’s handle) must use VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT.

  • VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR specifies that images created from the swapchain are protected images.

  • VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR specifies that the images of the swapchain can be used to create a VkImageView with a different format than what the swapchain was created with. The list of allowed image view formats are specified by adding a VkImageFormatListCreateInfo structure to the pNext chain of VkSwapchainCreateInfoKHR. In addition, this flag also specifies that the swapchain can be created with usage flags that are not supported for the format the swapchain is created with but are supported for at least one of the allowed image view formats.

// Provided by VK_KHR_swapchain
typedef VkFlags VkSwapchainCreateFlagsKHR;

VkSwapchainCreateFlagsKHR is a bitmask type for setting a mask of zero or more VkSwapchainCreateFlagBitsKHR.

If the pNext chain of VkSwapchainCreateInfoKHR includes a VkDeviceGroupSwapchainCreateInfoKHR structure, then that structure includes a set of device group present modes that the swapchain can be used with.

The VkDeviceGroupSwapchainCreateInfoKHR structure is defined as:

// Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkDeviceGroupSwapchainCreateInfoKHR {
    VkStructureType                     sType;
    const void*                         pNext;
    VkDeviceGroupPresentModeFlagsKHR    modes;
} VkDeviceGroupSwapchainCreateInfoKHR;

  • sType is the type of this structure.

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

  • modes is a bitfield of modes that the swapchain can be used with.

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

Valid Usage (Implicit)

If the pNext chain of VkSwapchainCreateInfoKHR includes a VkSwapchainDisplayNativeHdrCreateInfoAMD structure, then that structure includes additional swapchain creation parameters specific to display native HDR support.

The VkSwapchainDisplayNativeHdrCreateInfoAMD structure is defined as:

// Provided by VK_AMD_display_native_hdr
typedef struct VkSwapchainDisplayNativeHdrCreateInfoAMD {
    VkStructureType    sType;
    const void*        pNext;
    VkBool32           localDimmingEnable;
} VkSwapchainDisplayNativeHdrCreateInfoAMD;

  • sType is the type of this structure.

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

  • localDimmingEnable specifies whether local dimming is enabled for the swapchain.

If the pNext chain of VkSwapchainCreateInfoKHR does not include this structure, the default value for localDimmingEnable is VK_TRUE, meaning local dimming is initially enabled for the swapchain.

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SWAPCHAIN_DISPLAY_NATIVE_HDR_CREATE_INFO_AMD

Valid Usage

The local dimming HDR setting may also be changed over the life of a swapchain by calling:

// Provided by VK_AMD_display_native_hdr
void vkSetLocalDimmingAMD(
    VkDevice                                    device,
    VkSwapchainKHR                              swapChain,
    VkBool32                                    localDimmingEnable);

  • device is the device associated with swapChain.

  • swapChain handle to enable local dimming.

  • localDimmingEnable specifies whether local dimming is enabled for the swapchain.

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • swapChain must be a valid VkSwapchainKHR handle

  • Both of device, and swapChain must have been created, allocated, or retrieved from the same VkInstance

Valid Usage

If the pNext chain of VkSwapchainCreateInfoKHR includes a VkSurfaceFullScreenExclusiveInfoEXT structure, then that structure specifies the application’s preferred full-screen presentation behavior. If this structure is not present, fullScreenExclusive is considered to be VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT.

To enable surface counters when creating a swapchain, add a VkSwapchainCounterCreateInfoEXT structure to the pNext chain of VkSwapchainCreateInfoKHR. VkSwapchainCounterCreateInfoEXT is defined as:

// Provided by VK_EXT_display_control
typedef struct VkSwapchainCounterCreateInfoEXT {
    VkStructureType             sType;
    const void*                 pNext;
    VkSurfaceCounterFlagsEXT    surfaceCounters;
} VkSwapchainCounterCreateInfoEXT;

  • sType is the type of this structure.

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

  • surfaceCounters is a bitmask of VkSurfaceCounterFlagBitsEXT specifying surface counters to enable for the swapchain.

Valid Usage
Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SWAPCHAIN_COUNTER_CREATE_INFO_EXT

  • surfaceCounters must be a valid combination of VkSurfaceCounterFlagBitsEXT values

The requested counters become active when the first presentation command for the associated swapchain is processed by the presentation engine. To query the value of an active counter, use:

// Provided by VK_EXT_display_control
VkResult vkGetSwapchainCounterEXT(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    VkSurfaceCounterFlagBitsEXT                 counter,
    uint64_t*                                   pCounterValue);

  • device is the VkDevice associated with swapchain.

  • swapchain is the swapchain from which to query the counter value.

  • counter is the counter to query.

  • pCounterValue will return the current value of the counter.

If a counter is not available because the swapchain is out of date, the implementation may return VK_ERROR_OUT_OF_DATE_KHR.

Valid Usage

  • One or more present commands on swapchain must have been processed by the presentation engine

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • swapchain must be a valid VkSwapchainKHR handle

  • counter must be a valid VkSurfaceCounterFlagBitsEXT value

  • pCounterValue must be a valid pointer to a uint64_t value

  • Both of device, and swapchain must have been created, allocated, or retrieved from the same VkInstance

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_OUT_OF_DATE_KHR

As mentioned above, if vkCreateSwapchainKHR succeeds, it will return a handle to a swapchain containing an array of at least 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 surface must not be destroyed until after the swapchain is destroyed.

If oldSwapchain is VK_NULL_HANDLE, and the native window referred to by 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 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 surface must not become associated with a non-Vulkan graphics API surface before all associated Vulkan swapchains have been destroyed.

Like core functions, several WSI functions, including vkCreateSwapchainKHR return VK_ERROR_DEVICE_LOST if the logical device was lost. See Lost Device. As with most core objects, VkSwapchainKHR is a child of the device and is affected by the lost state; it must be destroyed before destroying the VkDevice. However, VkSurfaceKHR is not a child of any VkDevice and is not otherwise 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.

Note

As mentioned in Lost Device, after a lost device event, the VkPhysicalDevice may also be lost. If other VkPhysicalDevice are available, they can be used together with the same VkSurfaceKHR to create the new VkSwapchainKHR, however the application must query the surface capabilities again, because they may differ on a per-physical device basis.

To destroy a swapchain object call:

// Provided by VK_KHR_swapchain
void vkDestroySwapchainKHR(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    const VkAllocationCallbacks*                pAllocator);

  • device is the VkDevice associated with swapchain.

  • swapchain is the swapchain to destroy.

  • pAllocator is the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation).

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 VkImage handles are destroyed, and must not be acquired or used any more by the application. The memory of each VkImage 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 VkSurfaceKHR, 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 VkAllocationCallbacks were provided when swapchain was created, a compatible set of callbacks must be provided here

  • If no VkAllocationCallbacks were provided when swapchain was created, pAllocator must be NULL

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

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

  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • Both of device, and swapchain that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization

  • Host access to swapchain must be externally synchronized

When the VK_KHR_display_swapchain extension is enabled, multiple swapchains that share presentable images are created by calling:

// Provided by VK_KHR_display_swapchain
VkResult vkCreateSharedSwapchainsKHR(
    VkDevice                                    device,
    uint32_t                                    swapchainCount,
    const VkSwapchainCreateInfoKHR*             pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkSwapchainKHR*                             pSwapchains);

  • device is the device to create the swapchains for.

  • swapchainCount is the number of swapchains to create.

  • pCreateInfos is a pointer to an array of VkSwapchainCreateInfoKHR structures specifying the parameters of the created swapchains.

  • pAllocator is the allocator used for host memory allocated for the swapchain objects when there is no more specific allocator available (see Memory Allocation).

  • pSwapchains is a pointer to an array of VkSwapchainKHR handles in which the created swapchain objects will be returned.

vkCreateSharedSwapchainsKHR is similar to vkCreateSwapchainKHR, except that it takes an array of VkSwapchainCreateInfoKHR structures, and returns an array of swapchain objects.

The swapchain creation parameters that affect the properties and number of presentable images must match between all the swapchains. If the displays used by any of the swapchains do not use the same presentable image layout or are incompatible in a way that prevents sharing images, swapchain creation will fail with the result code VK_ERROR_INCOMPATIBLE_DISPLAY_KHR. If any error occurs, no swapchains will be created. Images presented to multiple swapchains must be re-acquired from all of them before transitioning away from VK_IMAGE_LAYOUT_PRESENT_SRC_KHR. After destroying one or more of the swapchains, the remaining swapchains and the presentable images can continue to be used.

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • pCreateInfos must be a valid pointer to an array of swapchainCount valid VkSwapchainCreateInfoKHR structures

  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • pSwapchains must be a valid pointer to an array of swapchainCount VkSwapchainKHR handles

  • swapchainCount must be greater than 0

Host Synchronization

  • Host access to pCreateInfos[].surface must be externally synchronized

  • Host access to pCreateInfos[].oldSwapchain must be externally synchronized

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INCOMPATIBLE_DISPLAY_KHR

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_SURFACE_LOST_KHR

To obtain the array of presentable images associated with a swapchain, call:

// Provided by VK_KHR_swapchain
VkResult vkGetSwapchainImagesKHR(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    uint32_t*                                   pSwapchainImageCount,
    VkImage*                                    pSwapchainImages);

  • device is the device associated with swapchain.

  • swapchain is the swapchain to query.

  • pSwapchainImageCount is a pointer to an integer related to the number of presentable images available or queried, as described below.

  • pSwapchainImages is either NULL or a pointer to an array of VkImage handles.

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, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • swapchain must be a valid VkSwapchainKHR 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 VkImage handles

  • Both of device, and swapchain must have been created, allocated, or retrieved from the same VkInstance

Return Codes
Success

  • VK_SUCCESS

  • VK_INCOMPLETE

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

Note

By knowing all presentable images used in the swapchain, the application can create command buffers that reference these images prior to entering its main rendering loop.

Images returned by vkGetSwapchainImagesKHR are fully backed by memory before they are passed to the application. All presentable images are initially in the VK_IMAGE_LAYOUT_UNDEFINED layout, thus before using presentable images, the application must transition them to a valid layout for the intended use.

Further, the lifetime of presentable images is controlled by the implementation, so applications must not destroy a presentable image. See vkDestroySwapchainKHR for further details on the lifetime of presentable images.

Images can also be created by using vkCreateImage with VkImageSwapchainCreateInfoKHR and bound to swapchain memory using vkBindImageMemory2KHR with VkBindImageMemorySwapchainInfoKHR. These images can be used anywhere swapchain images are used, and are useful in logical devices with multiple physical devices to create peer memory bindings of swapchain memory. These images and bindings have no effect on what memory is presented. Unlike images retrieved from vkGetSwapchainImagesKHR, these images must be destroyed with vkDestroyImage.

To acquire an available presentable image to use, and retrieve the index of that image, call:

// Provided by VK_KHR_swapchain
VkResult vkAcquireNextImageKHR(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    uint64_t                                    timeout,
    VkSemaphore                                 semaphore,
    VkFence                                     fence,
    uint32_t*                                   pImageIndex);

  • device is the device associated with swapchain.

  • swapchain is the non-retired swapchain from which an image is being acquired.

  • timeout specifies how long the function waits, in nanoseconds, if no image is available.

  • semaphore is VK_NULL_HANDLE or a semaphore to signal.

  • fence is VK_NULL_HANDLE or a fence to signal.

  • pImageIndex is a pointer to a uint32_t in which the index of the next image to use (i.e. an index into the array of images returned by vkGetSwapchainImagesKHR) is returned.

Valid Usage

  • swapchain must not be in the retired state

  • If semaphore is not VK_NULL_HANDLE it must be unsignaled

  • If semaphore is not VK_NULL_HANDLE it must not have any uncompleted signal or wait operations pending

  • If fence is not VK_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 VK_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 VkSurfaceCapabilitiesKHR::minImageCount as returned by a call to vkGetPhysicalDeviceSurfaceCapabilities2KHR with the surface used to create swapchain, timeout must not be UINT64_MAX

  • semaphore must have a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • swapchain must be a valid VkSwapchainKHR handle

  • If semaphore is not VK_NULL_HANDLE, semaphore must be a valid VkSemaphore handle

  • If fence is not VK_NULL_HANDLE, fence must be a valid VkFence 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 VkInstance

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

  • VK_SUCCESS

  • VK_TIMEOUT

  • VK_NOT_READY

  • VK_SUBOPTIMAL_KHR

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_OUT_OF_DATE_KHR

  • VK_ERROR_SURFACE_LOST_KHR

  • VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

When successful, vkAcquireNextImageKHR acquires a presentable image from swapchain that an application can use, and sets pImageIndex to the index of that image within the swapchain. The presentation engine may not have finished reading from the image at the time it is acquired, so the application must use semaphore and/or fence to ensure that the image layout and contents are not modified until the presentation engine reads have completed. If semaphore is not VK_NULL_HANDLE, the application may assume that, once vkAcquireNextImageKHR returns, the semaphore signal operation referenced by semaphore has been submitted for execution. The order in which images are acquired is implementation-dependent, and may be different than the order the images were presented.

If timeout is zero, then vkAcquireNextImageKHR does not wait, and will either successfully acquire an image, or fail and return VK_NOT_READY if no image is available.

If the specified timeout period expires before an image is acquired, vkAcquireNextImageKHR returns VK_TIMEOUT. If timeout is UINT64_MAX, the timeout period is treated as infinite, and vkAcquireNextImageKHR will block until an image is acquired or an error occurs.

An image will eventually be acquired if the number of images that the application has currently acquired (but not yet presented) is less than or equal to the difference between the number of images in swapchain and the value of VkSurfaceCapabilitiesKHR::minImageCount. If the number of currently acquired images is greater than this, vkAcquireNextImageKHR should not be called; if it is, timeout must not be UINT64_MAX.

If an image is acquired successfully, vkAcquireNextImageKHR must either return VK_SUCCESS, or VK_SUBOPTIMAL_KHR if the swapchain no longer matches the surface properties exactly, but can still be used for presentation.

Note

This may happen, for example, if the platform surface has been resized but the platform is able to scale the presented images to the new size to produce valid surface updates. It is up to the application to decide whether it prefers to continue using the current swapchain in this state, or to re-create the swapchain to better match the platform surface properties.

If the swapchain images no longer match native surface properties, either VK_SUBOPTIMAL_KHR or VK_ERROR_OUT_OF_DATE_KHR must be returned. If VK_ERROR_OUT_OF_DATE_KHR is returned, no image is acquired and attempts to present previously acquired images to the swapchain will also fail with VK_ERROR_OUT_OF_DATE_KHR. Applications need to create a new swapchain for the surface to continue presenting if VK_ERROR_OUT_OF_DATE_KHR is returned.

If device loss occurs (see Lost Device) before the timeout has expired, vkAcquireNextImageKHR must return in finite time with either one of the allowed success codes, or VK_ERROR_DEVICE_LOST.

If semaphore is not VK_NULL_HANDLE, the semaphore must be unsignaled, with no signal or wait operations pending. It will become signaled when the application can use the image.

Note

Use of semaphore allows rendering operations to be recorded and submitted before the presentation engine has completed its use of the image.

If fence is not equal to VK_NULL_HANDLE, the fence must be unsignaled, with no signal operations pending. It will become signaled when the application can use the image.

Note

Applications should not rely on vkAcquireNextImageKHR blocking in order to meter their rendering speed. The implementation may return from this function immediately regardless of how many presentation requests are queued, and regardless of when queued presentation requests will complete relative to the call. Instead, applications can use fence to meter their frame generation work to match the presentation rate.

An application must wait until either the semaphore or fence is signaled before accessing the image’s data.

Note

When the presentable image will be accessed by some stage S, the recommended idiom for ensuring correct synchronization is:

  • The VkSubmitInfo used to submit the image layout transition for execution includes vkAcquireNextImageKHR::semaphore in its pWaitSemaphores member, with the corresponding element of pWaitDstStageMask including S.

  • The synchronization command that performs any necessary image layout transition includes S in both the srcStageMask and dstStageMask.

After a successful return, the image indicated by pImageIndex and its data will be unmodified compared to when it was presented.

Note

Exclusive ownership of presentable images corresponding to a swapchain created with VK_SHARING_MODE_EXCLUSIVE as defined in Resource Sharing is not altered by a call to vkAcquireNextImageKHR. That means upon the first acquisition from such a swapchain presentable images are not owned by any queue family, while at subsequent acquisitions the presentable images remain owned by the queue family the image was previously presented on.

The possible return values for vkAcquireNextImageKHR depend on the timeout provided:

  • VK_SUCCESS is returned if an image became available.

  • VK_ERROR_SURFACE_LOST_KHR if the surface becomes no longer available.

  • VK_NOT_READY is returned if timeout is zero and no image was available.

  • VK_TIMEOUT is returned if timeout is greater than zero and less than UINT64_MAX, and no image became available within the time allowed.

  • VK_SUBOPTIMAL_KHR is returned if an image became available, and the swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully.

Note

This may happen, for example, if the platform surface has been resized but the platform is able to scale the presented images to the new size to produce valid surface updates. It is up to the application to decide whether it prefers to continue using the current swapchain indefinitely or temporarily in this state, or to re-create the swapchain to better match the platform surface properties.

  • VK_ERROR_OUT_OF_DATE_KHR is returned if the surface has changed in such a way that it is no longer compatible with the swapchain, and further presentation requests using the swapchain will fail. Applications must query the new surface properties and recreate their swapchain if they wish to continue presenting to the surface.

If the native surface and presented image sizes no longer match, presentation may fail. If presentation does succeed, the mapping from the presented image to the native surface is implementation-defined. It is the application’s responsibility to detect surface size changes and react appropriately. If presentation fails because of a mismatch in the surface and presented image sizes, a VK_ERROR_OUT_OF_DATE_KHR error will be returned.

Note

For example, consider a 4x3 window/surface that gets resized to be 3x4 (taller than wider). On some window systems, the portion of the window/surface that was previously and still is visible (the 3x3 part) will contain the same contents as before, while the remaining parts of the window will have undefined contents. Other window systems may squash/stretch the image to fill the new window size without any undefined contents, or apply some other mapping.

To acquire an available presentable image to use, and retrieve the index of that image, call:

// Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_swapchain
VkResult vkAcquireNextImage2KHR(
    VkDevice                                    device,
    const VkAcquireNextImageInfoKHR*            pAcquireInfo,
    uint32_t*                                   pImageIndex);

  • device is the device associated with swapchain.

  • pAcquireInfo is a pointer to a VkAcquireNextImageInfoKHR structure containing parameters of the acquire.

  • pImageIndex is a pointer to a uint32_t that is set to the index of the next image to use.

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 VkSurfaceCapabilitiesKHR::minImageCount as returned by a call to vkGetPhysicalDeviceSurfaceCapabilities2KHR 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 VkDevice handle

  • pAcquireInfo must be a valid pointer to a valid VkAcquireNextImageInfoKHR structure

  • pImageIndex must be a valid pointer to a uint32_t value

Return Codes
Success

  • VK_SUCCESS

  • VK_TIMEOUT

  • VK_NOT_READY

  • VK_SUBOPTIMAL_KHR

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_OUT_OF_DATE_KHR

  • VK_ERROR_SURFACE_LOST_KHR

  • VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

The VkAcquireNextImageInfoKHR structure is defined as:

// Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkAcquireNextImageInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkSwapchainKHR     swapchain;
    uint64_t           timeout;
    VkSemaphore        semaphore;
    VkFence            fence;
    uint32_t           deviceMask;
} VkAcquireNextImageInfoKHR;

  • sType is the type of this structure.

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

  • swapchain is a non-retired swapchain from which an image is acquired.

  • timeout specifies how long the function waits, in nanoseconds, if no image is available.

  • semaphore is VK_NULL_HANDLE or a semaphore to signal.

  • fence is VK_NULL_HANDLE or a fence to signal.

  • deviceMask is a mask of physical devices for which the swapchain image will be ready to use when the semaphore or fence is signaled.

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

Note

vkAcquireNextImage2KHR 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 VK_NULL_HANDLE it must be unsignaled

  • If semaphore is not VK_NULL_HANDLE it must not have any uncompleted signal or wait operations pending

  • If fence is not VK_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 VK_NULL_HANDLE

  • deviceMask must be a valid device mask

  • deviceMask must not be zero

  • semaphore must have a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR

  • pNext must be NULL

  • swapchain must be a valid VkSwapchainKHR handle

  • If semaphore is not VK_NULL_HANDLE, semaphore must be a valid VkSemaphore handle

  • If fence is not VK_NULL_HANDLE, fence must be a valid VkFence 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 VkInstance

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

After queueing all rendering commands and transitioning the image to the correct layout, to queue an image for presentation, call:

// Provided by VK_KHR_swapchain
VkResult vkQueuePresentKHR(
    VkQueue                                     queue,
    const VkPresentInfoKHR*                     pPresentInfo);

  • queue is a queue that is capable of presentation to the target surface’s platform on the same device as the image’s swapchain.

  • pPresentInfo is a pointer to a VkPresentInfoKHR structure specifying parameters of the presentation.

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 vkGetPhysicalDeviceSurfaceSupportKHR

  • 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 VkSemaphoreType of VK_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 vkQueuePresentKHR 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 VkImage at coordinates (0,0) would appear at the upper left pixel of the platform surface (assuming VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, and the display standing the right way up).

If vkQueuePresentKHR fails to enqueue the corresponding set of queue operations, it may return VK_ERROR_OUT_OF_HOST_MEMORY or VK_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 vkQueuePresentKHR fails in such a way that the implementation is unable to make that guarantee, the implementation must return VK_ERROR_DEVICE_LOST.

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

If any swapchain member of pPresentInfo was created with VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, VK_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)
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
Command Buffer Levels Render Pass Scope Supported Queue Types Pipeline Type

-

-

Any

-
Return Codes
Success

  • VK_SUCCESS

  • VK_SUBOPTIMAL_KHR

Failure

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_OUT_OF_DATE_KHR

  • VK_ERROR_SURFACE_LOST_KHR

  • VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

The VkPresentInfoKHR structure is defined as:

// Provided by VK_KHR_swapchain
typedef struct VkPresentInfoKHR {
    VkStructureType          sType;
    const void*              pNext;
    uint32_t                 waitSemaphoreCount;
    const VkSemaphore*       pWaitSemaphores;
    uint32_t                 swapchainCount;
    const VkSwapchainKHR*    pSwapchains;
    const uint32_t*          pImageIndices;
    VkResult*                pResults;
} VkPresentInfoKHR;

  • sType is the type of this structure.

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

  • waitSemaphoreCount is the number of semaphores to wait for before issuing the present request. The number may be zero.

  • pWaitSemaphores is NULL or a pointer to an array of VkSemaphore objects with waitSemaphoreCount entries, and specifies the semaphores to wait for before issuing the present request.

  • swapchainCount is the number of swapchains being presented to by this command.

  • pSwapchains is a pointer to an array of VkSwapchainKHR objects with swapchainCount entries. A given swapchain must not appear in this list more than once.

  • pImageIndices is a pointer to an array of indices into the array of each swapchain’s presentable images, with swapchainCount entries. Each entry in this array identifies the image to present on the corresponding entry in the pSwapchains array.

  • pResults is a pointer to an array of VkResult typed elements with swapchainCount entries. Applications that do not need per-swapchain results can use NULL for pResults. If non-NULL, each entry in pResults will be set to the VkResult for presenting the swapchain corresponding to the same index in pSwapchains.

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

Note

When transitioning the image to VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or VK_IMAGE_LAYOUT_PRESENT_SRC_KHR, there is no need to delay subsequent processing, or perform any visibility operations (as vkQueuePresentKHR performs automatic visibility operations). To achieve this, the dstAccessMask member of the VkImageMemoryBarrier should be set to 0, and the dstStageMask parameter should be set to VK_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 VK_IMAGE_LAYOUT_PRESENT_SRC_KHR or VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR layout at the time the operation is executed on a VkDevice

  • All elements of the pWaitSemaphores must have a VkSemaphoreType of VK_SEMAPHORE_TYPE_BINARY

Valid Usage (Implicit)

  • sType must be VK_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 VkDeviceGroupPresentInfoKHR, VkDisplayPresentInfoKHR, VkPresentFrameTokenGGP, VkPresentRegionsKHR, or VkPresentTimesInfoGOOGLE

  • 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 VkSemaphore handles

  • pSwapchains must be a valid pointer to an array of swapchainCount valid VkSwapchainKHR 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 VkResult 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 VkInstance

When the VK_KHR_incremental_present extension is enabled, additional fields can be specified that allow an application to specify that only certain rectangular regions of the presentable images of a swapchain are changed. This is an optimization hint that a presentation engine may use to only update the region of a surface that is actually changing. The application still must ensure that all pixels of a presented image contain the desired values, in case the presentation engine ignores this hint. An application can provide this hint by adding a VkPresentRegionsKHR structure to the pNext chain of the VkPresentInfoKHR structure.

The VkPresentRegionsKHR structure is defined as:

// Provided by VK_KHR_incremental_present
typedef struct VkPresentRegionsKHR {
    VkStructureType              sType;
    const void*                  pNext;
    uint32_t                     swapchainCount;
    const VkPresentRegionKHR*    pRegions;
} VkPresentRegionsKHR;

  • sType is the type of this structure.

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

  • swapchainCount is the number of swapchains being presented to by this command.

  • pRegions is NULL or a pointer to an array of VkPresentRegionKHR elements with swapchainCount entries. If not NULL, each element of pRegions contains the region that has changed since the last present to the swapchain in the corresponding entry in the VkPresentInfoKHR::pSwapchains array.

Valid Usage

  • swapchainCount must be the same value as VkPresentInfoKHR::swapchainCount, where VkPresentInfoKHR is included in the pNext chain of this VkPresentRegionsKHR structure

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_PRESENT_REGIONS_KHR

  • If pRegions is not NULL, pRegions must be a valid pointer to an array of swapchainCount valid VkPresentRegionKHR structures

  • swapchainCount must be greater than 0

For a given image and swapchain, the region to present is specified by the VkPresentRegionKHR structure, which is defined as:

// Provided by VK_KHR_incremental_present
typedef struct VkPresentRegionKHR {
    uint32_t                 rectangleCount;
    const VkRectLayerKHR*    pRectangles;
} VkPresentRegionKHR;

  • rectangleCount is the number of rectangles in pRectangles, or zero if the entire image has changed and should be presented.

  • pRectangles is either NULL or a pointer to an array of VkRectLayerKHR structures. The VkRectLayerKHR structure is the framebuffer coordinates, plus layer, of a portion of a presentable image that has changed and must be presented. If non-NULL, each entry in pRectangles is a rectangle of the given image that has changed since the last image was presented to the given swapchain.

Valid Usage (Implicit)

  • If rectangleCount is not 0, and pRectangles is not NULL, pRectangles must be a valid pointer to an array of rectangleCount valid VkRectLayerKHR structures

The VkRectLayerKHR structure is defined as:

// Provided by VK_KHR_incremental_present
typedef struct VkRectLayerKHR {
    VkOffset2D    offset;
    VkExtent2D    extent;
    uint32_t      layer;
} VkRectLayerKHR;

  • offset is the origin of the rectangle, in pixels.

  • extent is the size of the rectangle, in pixels.

  • layer is the layer of the image. For images with only one layer, the value of layer must be 0.

Valid Usage

Some platforms allow the size of a surface to change, and then scale the pixels of the image to fit the surface. VkRectLayerKHR specifies pixels of the swapchain’s image(s), which will be constant for the life of the swapchain.

When the VK_KHR_display_swapchain extension is enabled additional fields can be specified when presenting an image to a swapchain by setting VkPresentInfoKHR::pNext to point to a VkDisplayPresentInfoKHR structure.

The VkDisplayPresentInfoKHR structure is defined as:

// Provided by VK_KHR_display_swapchain
typedef struct VkDisplayPresentInfoKHR {
    VkStructureType    sType;
    const void*        pNext;
    VkRect2D           srcRect;
    VkRect2D           dstRect;
    VkBool32           persistent;
} VkDisplayPresentInfoKHR;

  • sType is the type of this structure.

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

  • srcRect is a rectangular region of pixels to present. It must be a subset of the image being presented. If VkDisplayPresentInfoKHR is not specified, this region will be assumed to be the entire presentable image.

  • dstRect is a rectangular region within the visible region of the swapchain’s display mode. If VkDisplayPresentInfoKHR is not specified, this region will be assumed to be the entire visible region of the visible region of the swapchain’s mode. If the specified rectangle is a subset of the display mode’s visible region, content from display planes below the swapchain’s plane will be visible outside the rectangle. If there are no planes below the swapchain’s, the area outside the specified rectangle will be black. If portions of the specified rectangle are outside of the display’s visible region, pixels mapping only to those portions of the rectangle will be discarded.

  • persistent: If this is VK_TRUE, the display engine will enable buffered mode on displays that support it. This allows the display engine to stop sending content to the display until a new image is presented. The display will instead maintain a copy of the last presented image. This allows less power to be used, but may increase presentation latency. If VkDisplayPresentInfoKHR is not specified, persistent mode will not be used.

If the extent of the srcRect and dstRect are not equal, the presented pixels will be scaled accordingly.

Valid Usage

  • srcRect must specify a rectangular region that is a subset of the image being presented

  • dstRect must specify a rectangular region that is a subset of the visibleRegion parameter of the display mode the swapchain being presented uses

  • If the persistentContent member of the VkDisplayPropertiesKHR structure returned by vkGetPhysicalDeviceDisplayPropertiesKHR for the display the present operation targets then persistent must be VK_FALSE

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR

If the pNext chain of VkPresentInfoKHR includes a VkDeviceGroupPresentInfoKHR structure, then that structure includes an array of device masks and a device group present mode.

The VkDeviceGroupPresentInfoKHR structure is defined as:

// Provided by VK_KHR_swapchain with VK_VERSION_1_1, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkDeviceGroupPresentInfoKHR {
    VkStructureType                        sType;
    const void*                            pNext;
    uint32_t                               swapchainCount;
    const uint32_t*                        pDeviceMasks;
    VkDeviceGroupPresentModeFlagBitsKHR    mode;
} VkDeviceGroupPresentInfoKHR;

  • sType is the type of this structure.

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

  • swapchainCount is zero or the number of elements in pDeviceMasks.

  • pDeviceMasks is a pointer to an array of device masks, one for each element of VkPresentInfoKHR::pSwapchains.

  • mode is the device group present mode that will be used for this present.

If mode is VK_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 VkDeviceGroupPresentCapabilitiesKHR.

If mode is VK_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 VkDeviceGroupPresentCapabilitiesKHR::presentMask.

If mode is VK_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 VkDeviceGroupPresentCapabilitiesKHR::presentMask.

If mode is VK_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 VkDeviceGroupPresentCapabilitiesKHR.

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

Valid Usage

  • swapchainCount must equal 0 or VkPresentInfoKHR::swapchainCount

  • If mode is VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then each element of pDeviceMasks must have exactly one bit set, and the corresponding element of VkDeviceGroupPresentCapabilitiesKHR::presentMask must be non-zero

  • If mode is VK_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 VkDeviceGroupPresentCapabilitiesKHR::presentMask

  • If mode is VK_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 VkDeviceGroupPresentCapabilitiesKHR::presentMask

  • If mode is VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then for each bit set in each element of pDeviceMasks, the corresponding element of VkDeviceGroupPresentCapabilitiesKHR::presentMask must be non-zero

  • The value of each element of pDeviceMasks must be equal to the device mask passed in VkAcquireNextImageInfoKHR::deviceMask when the image index was last acquired

  • mode must have exactly one bit set, and that bit must have been included in VkDeviceGroupSwapchainCreateInfoKHR::modes

Valid Usage (Implicit)

  • sType must be VK_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 VkDeviceGroupPresentModeFlagBitsKHR value

When the VK_GOOGLE_display_timing extension is enabled, additional fields can be specified that allow an application to specify the earliest time that an image should be displayed. This allows an application to avoid stutter that is caused by an image being displayed earlier than planned. Such stuttering can occur with both fixed and variable-refresh-rate displays, because stuttering occurs when the geometry is not correctly positioned for when the image is displayed. An application can instruct the presentation engine that an image should not be displayed earlier than a specified time by adding a VkPresentTimesInfoGOOGLE structure to the pNext chain of the VkPresentInfoKHR structure.

The VkPresentTimesInfoGOOGLE structure is defined as:

// Provided by VK_GOOGLE_display_timing
typedef struct VkPresentTimesInfoGOOGLE {
    VkStructureType               sType;
    const void*                   pNext;
    uint32_t                      swapchainCount;
    const VkPresentTimeGOOGLE*    pTimes;
} VkPresentTimesInfoGOOGLE;

  • sType is the type of this structure.

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

  • swapchainCount is the number of swapchains being presented to by this command.

  • pTimes is NULL or a pointer to an array of VkPresentTimeGOOGLE elements with swapchainCount entries. If not NULL, each element of pTimes contains the earliest time to present the image corresponding to the entry in the VkPresentInfoKHR::pImageIndices array.

Valid Usage

  • swapchainCount must be the same value as VkPresentInfoKHR::swapchainCount, where VkPresentInfoKHR is included in the pNext chain of this VkPresentTimesInfoGOOGLE structure

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE

  • If pTimes is not NULL, pTimes must be a valid pointer to an array of swapchainCount VkPresentTimeGOOGLE structures

  • swapchainCount must be greater than 0

The VkPresentTimeGOOGLE structure is defined as:

// Provided by VK_GOOGLE_display_timing
typedef struct VkPresentTimeGOOGLE {
    uint32_t    presentID;
    uint64_t    desiredPresentTime;
} VkPresentTimeGOOGLE;

  • presentID is an application-provided identification value, that can be used with the results of vkGetPastPresentationTimingGOOGLE, in order to uniquely identify this present. In order to be useful to the application, it should be unique within some period of time that is meaningful to the application.

  • desiredPresentTime specifies that the image given should not be displayed to the user any earlier than this time. desiredPresentTime is a time in nanoseconds, relative to a monotonically-increasing clock (e.g. CLOCK_MONOTONIC (see clock_gettime(2)) on Android and Linux). A value of zero specifies that the presentation engine may display the image at any time. This is useful when the application desires to provide presentID, but does not need a specific desiredPresentTime.

When the VK_GGP_frame_token extension is enabled, a Google Games Platform frame token can be specified when presenting an image to a swapchain by adding a VkPresentFrameTokenGGP structure to the pNext chain of the VkPresentInfoKHR structure.

The VkPresentFrameTokenGGP structure is defined as:

// Provided by VK_GGP_frame_token
typedef struct VkPresentFrameTokenGGP {
    VkStructureType    sType;
    const void*        pNext;
    GgpFrameToken      frameToken;
} VkPresentFrameTokenGGP;

  • sType is the type of this structure.

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

  • frameToken is the Google Games Platform frame token.

Valid Usage

  • frameToken must be a valid GgpFrameToken

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_PRESENT_FRAME_TOKEN_GGP

vkQueuePresentKHR, releases the acquisition of the images referenced by imageIndices. The queue family corresponding to the queue vkQueuePresentKHR is executed on must have ownership of the presented images as defined in Resource Sharing. vkQueuePresentKHR does not alter the queue family ownership, but the presented images must not be used again before they have been reacquired using vkAcquireNextImageKHR.

The processing of the presentation happens in issue order with other queue operations, but semaphores have to be used to ensure that prior rendering and other commands in the specified queue complete before the presentation begins. The presentation command itself does not delay processing of subsequent commands on the queue, however, presentation requests sent to a particular queue are always performed in order. Exact presentation timing is controlled by the semantics of the presentation engine and native platform in use.

If an image is presented to a swapchain created from a display surface, the mode of the associated display will be updated, if necessary, to match the mode specified when creating the display surface. The mode switch and presentation of the specified image will be performed as one atomic operation.

The result codes VK_ERROR_OUT_OF_DATE_KHR and VK_SUBOPTIMAL_KHR have the same meaning when returned by vkQueuePresentKHR as they do when returned by vkAcquireNextImageKHR. If multiple swapchains are presented, the result code is determined applying the following rules in order:

  • If the device is lost, VK_ERROR_DEVICE_LOST is returned.

  • If any of the target surfaces are no longer available the error VK_ERROR_SURFACE_LOST_KHR is returned.

  • If any of the presents would have a result of VK_ERROR_OUT_OF_DATE_KHR if issued separately then VK_ERROR_OUT_OF_DATE_KHR is returned.

  • If any of the presents would have a result of VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT if issued separately then VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT is returned.

  • If any of the presents would have a result of VK_SUBOPTIMAL_KHR if issued separately then VK_SUBOPTIMAL_KHR is returned.

  • Otherwise VK_SUCCESS is returned.

Presentation is a read-only operation that will not affect the content of the presentable images. Upon reacquiring the image and transitioning it away from the VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout, the contents will be the same as they were prior to transitioning the image to the present source layout and presenting it. However, if a mechanism other than Vulkan is used to modify the platform window associated with the swapchain, the content of all presentable images in the swapchain becomes undefined.

Note

The application can continue to present any acquired images from a retired swapchain as long as the swapchain has not entered a state that causes vkQueuePresentKHR to return VK_ERROR_OUT_OF_DATE_KHR.

32.10. Hdr Metadata

To improve color reproduction of content it is useful to have information that can be used to better reproduce the colors as seen on the mastering display. That information can be provided to an implementation by calling vkSetHdrMetadataEXT. The metadata will be applied to the specified VkSwapchainKHR objects at the next vkQueuePresentKHR call using that VkSwapchainKHR object. The metadata will persist until a subsequent vkSetHdrMetadataEXT changes it. The definitions below are from the associated SMPTE 2086, CTA 861.3 and CIE 15:2004 specifications.

The definition of vkSetHdrMetadataEXT is:

// Provided by VK_EXT_hdr_metadata
void vkSetHdrMetadataEXT(
    VkDevice                                    device,
    uint32_t                                    swapchainCount,
    const VkSwapchainKHR*                       pSwapchains,
    const VkHdrMetadataEXT*                     pMetadata);

  • device is the logical device where the swapchain(s) were created.

  • swapchainCount is the number of swapchains included in pSwapchains.

  • pSwapchains is a pointer to an array of swapchainCount VkSwapchainKHR handles.

  • pMetadata is a pointer to an array of swapchainCount VkHdrMetadataEXT structures.

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • pSwapchains must be a valid pointer to an array of swapchainCount valid VkSwapchainKHR handles

  • pMetadata must be a valid pointer to an array of swapchainCount valid VkHdrMetadataEXT structures

  • swapchainCount must be greater than 0

  • Both of device, and the elements of pSwapchains must have been created, allocated, or retrieved from the same VkInstance

// Provided by VK_EXT_hdr_metadata
typedef struct VkXYColorEXT {
    float    x;
    float    y;
} VkXYColorEXT;

Chromaticity coordinates x and y are as specified in CIE 15:2004 “Calculation of chromaticity coordinates” (Section 7.3) and are limited to between 0 and 1 for real colors for the mastering display.

// Provided by VK_EXT_hdr_metadata
typedef struct VkHdrMetadataEXT {
    VkStructureType    sType;
    const void*        pNext;
    VkXYColorEXT       displayPrimaryRed;
    VkXYColorEXT       displayPrimaryGreen;
    VkXYColorEXT       displayPrimaryBlue;
    VkXYColorEXT       whitePoint;
    float              maxLuminance;
    float              minLuminance;
    float              maxContentLightLevel;
    float              maxFrameAverageLightLevel;
} VkHdrMetadataEXT;

  • sType is the type of this structure.

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

  • displayPrimaryRed is the mastering display’s red primary in chromaticity coordinates

  • displayPrimaryGreen is the mastering display’s green primary in chromaticity coordinates

  • displayPrimaryBlue is the mastering display’s blue primary in chromaticity coordinates

  • whitePoint is the mastering display’s white-point in chromaticity coordinates

  • maxLuminance is the maximum luminance of the mastering display in nits

  • minLuminance is the minimum luminance of the mastering display in nits

  • maxContentLightLevel is content’s maximum luminance in nits

  • maxFrameAverageLightLevel is the maximum frame average light level in nits

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_HDR_METADATA_EXT

  • pNext must be NULL

Note

The validity and use of this data is outside the scope of Vulkan.