29. 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.
29.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, which contain 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.
29.2. WSI Surface
Native platform surface or window objects are abstracted by surface objects,
which are represented by VkSurfaceKHR
handles:
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 struct that contains the
platform-specific information about the surface.
This will be described in the documentation for the loader-ICD interface,
and in the |
29.2.1. Android Platform
To create a VkSurfaceKHR
object for an Android native window, call:
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 an instance of theVkAndroidSurfaceCreateInfoKHR
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
points 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 |
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).
The VkAndroidSurfaceCreateInfoKHR
structure is defined as:
typedef struct VkAndroidSurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkAndroidSurfaceCreateFlagsKHR flags;
struct ANativeWindow* window;
} VkAndroidSurfaceCreateInfoKHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
flags
is reserved for future use. -
window
is a pointer to the ANativeWindow to associate the surface with.
To remove an unnecessary compile-time dependency, an incomplete type definition of ANativeWindow is provided in the Vulkan headers:
struct ANativeWindow;
The actual ANativeWindow type is defined in Android NDK headers.
29.2.2. Wayland Platform
To create a VkSurfaceKHR
object for a Wayland surface, call:
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 an instance of the 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
points to a VkSurfaceKHR handle in which the created surface object is returned.
The VkWaylandSurfaceCreateInfoKHR
structure is defined as:
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
isNULL
or a pointer to an extension-specific structure. -
flags
is reserved for future use. -
display
andsurface
are pointers to the Waylandwl_display
andwl_surface
to associate the surface with.
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.
29.2.3. Win32 Platform
To create a VkSurfaceKHR
object for a Win32 window, call:
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 an instance of theVkWin32SurfaceCreateInfoKHR
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
points to a VkSurfaceKHR handle in which the created surface object is returned.
The VkWin32SurfaceCreateInfoKHR
structure is defined as:
typedef struct VkWin32SurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkWin32SurfaceCreateFlagsKHR flags;
HINSTANCE hinstance;
HWND hwnd;
} VkWin32SurfaceCreateInfoKHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
flags
is reserved for future use. -
hinstance
andhwnd
are the Win32HINSTANCE
andHWND
for the window to associate the surface with.
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 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. |
29.2.4. XCB Platform
To create a VkSurfaceKHR
object for an X11 window, using the XCB
client-side library, call:
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 an instance of theVkXcbSurfaceCreateInfoKHR
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
points to a VkSurfaceKHR handle in which the created surface object is returned.
The VkXcbSurfaceCreateInfoKHR
structure is defined as:
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
isNULL
or a pointer to an extension-specific structure. -
flags
is reserved for future use. -
connection
is a pointer to anxcb_connection_t
to the X server. -
window
is thexcb_window_t
for the X11 window to associate the surface with.
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 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.
29.2.5. Xlib Platform
To create a VkSurfaceKHR
object for an X11 window, using the Xlib
client-side library, call:
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 an instance of theVkXlibSurfaceCreateInfoKHR
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
points to a VkSurfaceKHR handle in which the created surface object is returned.
The VkXlibSurfaceCreateInfoKHR
structure is defined as:
typedef struct VkXlibSurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkXlibSurfaceCreateFlagsKHR flags;
Display* dpy;
Window window;
} VkXlibSurfaceCreateInfoKHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
flags
is reserved for future use. -
dpy
is a pointer to an XlibDisplay
connection to the X server. -
window
is an XlibWindow
to associate the surface with.
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 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.
29.2.6. 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:
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.
29.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.
29.3.1. Display Enumeration
Displays are represented by VkDisplayKHR
handles:
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:
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 eitherNULL
or a pointer to an array ofVkDisplayPropertiesKHR
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.
The VkDisplayPropertiesKHR
structure is defined as:
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 string containing the name of the display. Generally, this will be the name provided by the display’s EDID. It can beNULL
if no suitable name is available. If notNULL
, the memory it points to must remain accessible as long asdisplay
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 isVK_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:
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 eitherNULL
or a pointer to an array ofVkDisplayProperties2KHR
structures.
vkGetPhysicalDeviceDisplayProperties2KHR
behaves similarly to
vkGetPhysicalDeviceDisplayPropertiesKHR, with the ability to return
extended information via chained output structures.
The VkDisplayProperties2KHR
structure is defined as:
typedef struct VkDisplayProperties2KHR {
VkStructureType sType;
void* pNext;
VkDisplayPropertiesKHR displayProperties;
} VkDisplayProperties2KHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
displayProperties
is an instance of the VkDisplayPropertiesKHR structure.
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:
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 eitherNULL
or a pointer to an array ofVkDisplayPlanePropertiesKHR
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.
The VkDisplayPlanePropertiesKHR
structure is defined as:
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 byvkGetPhysicalDeviceDisplayPlanePropertiesKHR
inpPropertyCount
.
To query the properties of a device’s display planes, call:
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 eitherNULL
or a pointer to an array ofVkDisplayPlaneProperties2KHR
structures.
vkGetPhysicalDeviceDisplayPlaneProperties2KHR
behaves similarly to
vkGetPhysicalDeviceDisplayPlanePropertiesKHR, with the ability to
return extended information via chained output structures.
The VkDisplayPlaneProperties2KHR
structure is defined as:
typedef struct VkDisplayPlaneProperties2KHR {
VkStructureType sType;
void* pNext;
VkDisplayPlanePropertiesKHR displayPlaneProperties;
} VkDisplayPlaneProperties2KHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
displayPlaneProperties
is an instance of the VkDisplayPlanePropertiesKHR structure.
To determine which displays a plane is usable with, call
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 eitherNULL
or a pointer to an array ofVkDisplayKHR
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.
Additional properties of displays are queried using specialized query functions.
Display Modes
Display modes are represented by VkDisplayModeKHR
handles:
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:
VkResult vkGetDisplayModePropertiesKHR(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display,
uint32_t* pPropertyCount,
VkDisplayModePropertiesKHR* pProperties);
-
physicalDevice
is the physical device associated withdisplay
. -
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 eitherNULL
or a pointer to an array ofVkDisplayModePropertiesKHR
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.
The VkDisplayModePropertiesKHR
structure is defined as:
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 withdisplayMode
.
To query the properties of a device’s built-in display modes, call:
VkResult vkGetDisplayModeProperties2KHR(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display,
uint32_t* pPropertyCount,
VkDisplayModeProperties2KHR* pProperties);
-
physicalDevice
is the physical device associated withdisplay
. -
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 eitherNULL
or a pointer to an array ofVkDisplayModeProperties2KHR
structures.
vkGetDisplayModeProperties2KHR
behaves similarly to
vkGetDisplayModePropertiesKHR, with the ability to return extended
information via chained output structures.
The VkDisplayModeProperties2KHR
structure is defined as:
typedef struct VkDisplayModeProperties2KHR {
VkStructureType sType;
void* pNext;
VkDisplayModePropertiesKHR displayModeProperties;
} VkDisplayModeProperties2KHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
displayModeProperties
is an instance of the VkDisplayModePropertiesKHR structure.
The VkDisplayModeParametersKHR
structure is defined as:
typedef struct VkDisplayModeParametersKHR {
VkExtent2D visibleRegion;
uint32_t refreshRate;
} VkDisplayModeParametersKHR;
-
visibleRegion
is the 2D extents of the visible region. -
refreshRate
is auint32_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 |
Additional modes may also be created by calling:
VkResult vkCreateDisplayModeKHR(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display,
const VkDisplayModeCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkDisplayModeKHR* pMode);
-
physicalDevice
is the physical device associated withdisplay
. -
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.
The VkDisplayModeCreateInfoKHR
structure is defined as:
typedef struct VkDisplayModeCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkDisplayModeCreateFlagsKHR flags;
VkDisplayModeParametersKHR parameters;
} VkDisplayModeCreateInfoKHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific 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 returnVK_ERROR_INITIALIZATION_FAILED
.
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:
VkResult vkGetDisplayPlaneCapabilitiesKHR(
VkPhysicalDevice physicalDevice,
VkDisplayModeKHR mode,
uint32_t planeIndex,
VkDisplayPlaneCapabilitiesKHR* pCapabilities);
-
physicalDevice
is the physical device associated withdisplay
-
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.
The VkDisplayPlaneCapabilitiesKHR
structure is defined as:
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. Thex
andy
components ofmaxSrcPosition
must each be greater than or equal to thex
andy
components ofminSrcPosition
, 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
andmaxDstPosition
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.
Vendors may still fail presentation requests that specify unsupported
combinations.
To query the capabilities of a given mode and plane combination, call:
VkResult vkGetDisplayPlaneCapabilities2KHR(
VkPhysicalDevice physicalDevice,
const VkDisplayPlaneInfo2KHR* pDisplayPlaneInfo,
VkDisplayPlaneCapabilities2KHR* pCapabilities);
-
physicalDevice
is the physical device associated withpDisplayPlaneInfo
. -
pDisplayPlaneInfo
is a pointer to an instance of the 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.
The VkDisplayPlaneInfo2KHR
structure is defined as:
typedef struct VkDisplayPlaneInfo2KHR {
VkStructureType sType;
const void* pNext;
VkDisplayModeKHR mode;
uint32_t planeIndex;
} VkDisplayPlaneInfo2KHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific 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.
The VkDisplayPlaneCapabilities2KHR
structure is defined as:
typedef struct VkDisplayPlaneCapabilities2KHR {
VkStructureType sType;
void* pNext;
VkDisplayPlaneCapabilitiesKHR capabilities;
} VkDisplayPlaneCapabilities2KHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
capabilities
is an instance of the VkDisplayPlaneCapabilitiesKHR structure.
29.3.2. 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:
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 an instance of the 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
points to a VkSurfaceKHR handle in which the created surface is returned.
The VkDisplaySurfaceCreateInfoKHR
structure is defined as:
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
isNULL
or a pointer to an extension-specific 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 ifalphaMode
is notVK_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. |
Possible values of VkDisplaySurfaceCreateInfoKHR::alphaMode
,
specifying the type of alpha blending to use on a display, are:
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 toVK_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.
typedef VkFlags VkDisplayPlaneAlphaFlagsKHR;
VkDisplayPlaneAlphaFlagsKHR
is a bitmask type for setting a mask of
zero or more VkDisplayPlaneAlphaFlagBitsKHR.
29.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:
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 aVkBool32
, which is set toVK_TRUE
to indicate support, andVK_FALSE
otherwise.
29.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.
29.4.2. Wayland Platform
To determine whether a queue family of a physical device supports presentation to a Wayland compositor, call:
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 thewl_display
associated with a Wayland compositor.
This platform-specific function can be called prior to creating a surface.
29.4.3. Win32 Platform
To determine whether a queue family of a physical device supports presentation to the Microsoft Windows desktop, call:
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.
29.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:
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 anxcb_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.
29.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:
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 XlibDisplay
connection to the server. -
visualId
is an X11 visual (VisualID
).
This platform-specific function can be called prior to creating a surface.
29.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. Capabilities that correspond to image creation parameters are not independent of each other: combinations of parameters that are not supported as reported by vkGetPhysicalDeviceImageFormatProperties are not supported by the surface on that physical device, even if the capabilities taken individually are supported as part of some other parameter combinations.
To query the basic capabilities of a surface, needed in order to create a swapchain, call:
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 an instance of the VkSurfaceCapabilitiesKHR structure in which the capabilities are returned.
The VkSurfaceCapabilitiesKHR
structure is defined as:
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 tominImageCount
. 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. Thewidth
andheight
of the extent will each be less than or equal to the correspondingwidth
andheight
ofcurrentExtent
, unlesscurrentExtent
has the special value described above. -
maxImageExtent
contains the largest valid swapchain extent for the surface on the specified device. Thewidth
andheight
of the extent will each be greater than or equal to the correspondingwidth
andheight
ofminImageExtent
. Thewidth
andheight
of the extent will each be greater than or equal to the correspondingwidth
andheight
ofcurrentExtent
, unlesscurrentExtent
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 toVK_PRESENT_MODE_IMMEDIATE_KHR
,VK_PRESENT_MODE_MAILBOX_KHR
,VK_PRESENT_MODE_FIFO_KHR
orVK_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
|
Note
Formulas such as min(N, |
To query the basic capabilities of a surface defined by the core or extensions, call:
VkResult vkGetPhysicalDeviceSurfaceCapabilities2KHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceSurfaceInfo2KHR* pSurfaceInfo,
VkSurfaceCapabilities2KHR* pSurfaceCapabilities);
-
physicalDevice
is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
pSurfaceInfo
points to an instance of the VkPhysicalDeviceSurfaceInfo2KHR structure, describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR. -
pSurfaceCapabilities
points to an instance of the VkSurfaceCapabilities2KHR structure in which the capabilities are returned.
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.
The VkPhysicalDeviceSurfaceInfo2KHR
structure is defined as:
typedef struct VkPhysicalDeviceSurfaceInfo2KHR {
VkStructureType sType;
const void* pNext;
VkSurfaceKHR surface;
} VkPhysicalDeviceSurfaceInfo2KHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific 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.
The VkSurfaceCapabilities2KHR
structure is defined as:
typedef struct VkSurfaceCapabilities2KHR {
VkStructureType sType;
void* pNext;
VkSurfaceCapabilitiesKHR surfaceCapabilities;
} VkSurfaceCapabilities2KHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
surfaceCapabilities
is a structure of type VkSurfaceCapabilitiesKHR describing the capabilities of the specified surface.
The VkSharedPresentSurfaceCapabilitiesKHR
structure is defined as:
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific 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 toVK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
orVK_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.
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:
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.
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:
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.
typedef VkFlags VkCompositeAlphaFlagsKHR;
VkCompositeAlphaFlagsKHR
is a bitmask type for setting a mask of zero
or more VkCompositeAlphaFlagBitsKHR.
To query the supported swapchain format-color space pairs for a surface, call:
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 eitherNULL
or a pointer to an array ofVkSurfaceFormatKHR
structures.
If pSurfaceFormats
is NULL
, then the number of format pairs
supported for the given surface
is returned in
pSurfaceFormatCount
.
The number of format pairs supported will be greater than or equal to 1.
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 VkSurfaceFormatKHR
structure is defined as:
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:
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
points to an instance of the 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 eitherNULL
or a pointer to an array of VkSurfaceFormat2KHR structures.
If pSurfaceFormats
is NULL
, then the number of format tuples
supported for the given surface
is returned in
pSurfaceFormatCount
.
The number of format tuples supported will be greater than or equal to 1.
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.
The VkSurfaceFormat2KHR
structure is defined as:
typedef struct VkSurfaceFormat2KHR {
VkStructureType sType;
void* pNext;
VkSurfaceFormatKHR surfaceFormat;
} VkSurfaceFormat2KHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
surfaceFormat
is an instance of VkSurfaceFormatKHR describing a format-color space pair that is compatible with the specified surface.
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:
typedef enum VkColorSpaceKHR {
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR = 0,
VK_COLORSPACE_SRGB_NONLINEAR_KHR = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR,
} VkColorSpaceKHR;
-
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR
specifies support for the sRGB color space.
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.
Note
If |
Note
In the initial release of the |
To query the supported presentation modes for a surface, call:
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 eitherNULL
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.
Possible values of elements of the
vkGetPhysicalDeviceSurfacePresentModesKHR::pPresentModes
array,
indicating the supported presentation modes for a surface, are:
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,
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR = 1000111000,
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 ofpresentMode
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:
Presentation mode | Image usage flags |
---|---|
|
VkSurfaceCapabilitiesKHR:: |
|
VkSurfaceCapabilitiesKHR:: |
|
VkSurfaceCapabilitiesKHR:: |
|
VkSurfaceCapabilitiesKHR:: |
|
VkSharedPresentSurfaceCapabilitiesKHR:: |
|
VkSharedPresentSurfaceCapabilitiesKHR:: |
Note
For reference, the mode indicated by |
29.6. 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:
VkResult vkGetDeviceGroupPresentCapabilitiesKHR(
VkDevice device,
VkDeviceGroupPresentCapabilitiesKHR* pDeviceGroupPresentCapabilities);
-
device
is the logical device. -
pDeviceGroupPresentCapabilities
is a pointer to a structure of type VkDeviceGroupPresentCapabilitiesKHR that is filled with the logical device’s capabilities.
The VkDeviceGroupPresentCapabilitiesKHR
structure is defined as:
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
isNULL
or a pointer to an extension-specific structure. -
presentMask
is an array of 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
.
Bits which may be set in
VkDeviceGroupPresentCapabilitiesKHR::modes
to indicate which
device group presentation modes are supported are:
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 itspresentMask
. -
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 itspresentMask
. -
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.
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:
VkResult vkGetDeviceGroupSurfacePresentModesKHR(
VkDevice device,
VkSurfaceKHR surface,
VkDeviceGroupPresentModeFlagsKHR* pModes);
-
device
is the logical device. -
surface
is the surface. -
pModes
is a pointer to a value of type VkDeviceGroupPresentModeFlagsKHR that is filled with the supported device group present modes for the surface.
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.
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:
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 eitherNULL
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.
29.7. 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:
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 callvkQueuePresentKHR
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 tovkQueuePresentKHR
, 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 callingvkQueuePresentKHR
, 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 |
In order to query a swapchain’s status when rendering to a shared presentable image, call:
VkResult vkGetSwapchainStatusKHR(
VkDevice device,
VkSwapchainKHR swapchain);
-
device
is the device associated withswapchain
. -
swapchain
is the swapchain to query.
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 |
To create a swapchain, call:
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 an instance of the 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.
The VkSwapchainCreateInfoKHR
structure is defined as:
typedef struct VkSwapchainCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkSwapchainCreateFlagsKHR flags;
VkSurfaceKHR surface;
uint32_t minImageCount;
VkFormat imageFormat;
VkColorSpaceKHR imageColorSpace;
VkExtent2D imageExtent;
uint32_t imageArrayLayers;
VkImageUsageFlags imageUsage;
VkSharingMode imageSharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t* pQueueFamilyIndices;
VkSurfaceTransformFlagBitsKHR preTransform;
VkCompositeAlphaFlagBitsKHR compositeAlpha;
VkPresentModeKHR presentMode;
VkBool32 clipped;
VkSwapchainKHR oldSwapchain;
} VkSwapchainCreateInfoKHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific 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 withsurface
. -
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’scurrentExtent
as returned byvkGetPhysicalDeviceSurfaceCapabilitiesKHR
.
Note
On some platforms, it is normal that |
-
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 whenimageSharingMode
isVK_SHARING_MODE_CONCURRENT
. -
pQueueFamilyIndices
is an array of queue family indices having access to the images(s) of the swapchain whenimageSharingMode
isVK_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 thecurrentTransform
value returned byvkGetPhysicalDeviceSurfaceCapabilitiesKHR
, 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. Pixel 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 |
-
oldSwapchain
is VK_NULL_HANDLE, or the existing non-retired swapchain currently associated withsurface
. Providing a validoldSwapchain
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
After The application can continue to use a shared presentable image obtained
from |
Bits which can be set in VkSwapchainCreateInfoKHR::flags
,
specifying parameters of swapchain creation, are:
typedef enum VkSwapchainCreateFlagBitsKHR {
VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR = 0x00000001,
VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR = 0x00000002,
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 theswapchain
member of VkImageSwapchainCreateInfoKHR set to this swapchain’s handle) must useVK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
. -
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
specifies that the images of the swapchain can be used to create aVkImageView
with a different format than what the swapchain was created with. The list of allowed image view formats are specified by chaining an instance of the VkImageFormatListCreateInfoKHR structure to thepNext
chain ofVkSwapchainCreateInfoKHR
. 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.
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:
typedef struct VkDeviceGroupSwapchainCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkDeviceGroupPresentModeFlagsKHR modes;
} VkDeviceGroupSwapchainCreateInfoKHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific 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
.
As mentioned above, if vkCreateSwapchainKHR
succeeds, it will return a
handle to a swapchain that contains 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 |
---|---|
|
all other bits are unset |
|
|
|
|
|
|
|
1 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
To destroy a swapchain object call:
void vkDestroySwapchainKHR(
VkDevice device,
VkSwapchainKHR swapchain,
const VkAllocationCallbacks* pAllocator);
-
device
is the VkDevice associated withswapchain
. -
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.
To obtain the array of presentable images associated with a swapchain, call:
VkResult vkGetSwapchainImagesKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint32_t* pSwapchainImageCount,
VkImage* pSwapchainImages);
-
device
is the device associated withswapchain
. -
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 eitherNULL
or a pointer to an array ofVkImage
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.
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. |
The implementation will have already allocated and bound the memory backing
the VkImage
objects returned by vkGetSwapchainImagesKHR
.
The memory for each image will not alias with the memory for other images or
with any VkDeviceMemory
object.
As such, performing any operation affecting the binding of memory to a
presentable image results in undefined behavior.
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 destroying a presentable image with vkDestroyImage results in undefined behavior. 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:
VkResult vkAcquireNextImageKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint64_t timeout,
VkSemaphore semaphore,
VkFence fence,
uint32_t* pImageIndex);
-
device
is the device associated withswapchain
. -
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 auint32_t
that is set to the index of the next image to use (i.e. an index into the array of images returned byvkGetSwapchainImagesKHR
).
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.
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 |
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 |
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:
|
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 |
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 iftimeout
is zero and no image was available. -
VK_TIMEOUT
is returned iftimeout
is greater than zero and less thanUINT64_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:
VkResult vkAcquireNextImage2KHR(
VkDevice device,
const VkAcquireNextImageInfoKHR* pAcquireInfo,
uint32_t* pImageIndex);
-
device
is the device associated withswapchain
. -
pAcquireInfo
is a pointer to a structure of type VkAcquireNextImageInfoKHR containing parameters of the acquire. -
pImageIndex
is a pointer to auint32_t
that is set to the index of the next image to use.
The VkAcquireNextImageInfoKHR
structure is defined as:
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
isNULL
or a pointer to an extension-specific 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 |
After queueing all rendering commands and transitioning the image to the correct layout, to queue an image for presentation, call:
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 an instance of the VkPresentInfoKHR structure specifying the 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. |
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.
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
or
VK_ERROR_SURFACE_LOST_KHR
, the set of queue operations are still
considered to be enqueued and thus any semaphore to be waited on gets
unsignaled when the corresponding queue operation is complete.
The VkPresentInfoKHR
structure is defined as:
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
isNULL
or a pointer to an extension-specific structure. -
waitSemaphoreCount
is the number of semaphores to wait for before issuing the present request. The number may be zero. -
pWaitSemaphores
, if notNULL
, is an array of VkSemaphore objects withwaitSemaphoreCount
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 an array of VkSwapchainKHR objects withswapchainCount
entries. A given swapchain must not appear in this list more than once. -
pImageIndices
is an array of indices into the array of each swapchain’s presentable images, withswapchainCount
entries. Each entry in this array identifies the image to present on the corresponding entry in thepSwapchains
array. -
pResults
is an array of VkResult typed elements withswapchainCount
entries. Applications that do not need per-swapchain results can useNULL
forpResults
. If non-NULL
, each entry inpResults
will be set to the VkResult for presenting the swapchain corresponding to the same index inpSwapchains
.
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
|
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 including the
VkPresentRegionsKHR
structure in the pNext
chain of the
VkPresentInfoKHR
structure.
The VkPresentRegionsKHR
structure is defined as:
typedef struct VkPresentRegionsKHR {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const VkPresentRegionKHR* pRegions;
} VkPresentRegionsKHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
swapchainCount
is the number of swapchains being presented to by this command. -
pRegions
isNULL
or a pointer to an array ofVkPresentRegionKHR
elements withswapchainCount
entries. If notNULL
, each element ofpRegions
contains the region that has changed since the last present to the swapchain in the corresponding entry in theVkPresentInfoKHR
::pSwapchains
array.
For a given image and swapchain, the region to present is specified by the
VkPresentRegionKHR
structure, which is defined as:
typedef struct VkPresentRegionKHR {
uint32_t rectangleCount;
const VkRectLayerKHR* pRectangles;
} VkPresentRegionKHR;
-
rectangleCount
is the number of rectangles inpRectangles
, or zero if the entire image has changed and should be presented. -
pRectangles
is eitherNULL
or a pointer to an array ofVkRectLayerKHR
structures. TheVkRectLayerKHR
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 inpRectangles
is a rectangle of the given image that has changed since the last image was presented to the given swapchain.
The VkRectLayerKHR
structure is defined as:
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 oflayer
must be 0.
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 an instance of the
VkDisplayPresentInfoKHR structure.
The VkDisplayPresentInfoKHR
structure is defined as:
typedef struct VkDisplayPresentInfoKHR {
VkStructureType sType;
const void* pNext;
VkRect2D srcRect;
VkRect2D dstRect;
VkBool32 persistent;
} VkDisplayPresentInfoKHR;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to an extension-specific structure. -
srcRect
is a rectangular region of pixels to present. It must be a subset of the image being presented. IfVkDisplayPresentInfoKHR
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. IfVkDisplayPresentInfoKHR
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 isVK_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. IfVkDisplayPresentInfoKHR
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.
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:
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
isNULL
or a pointer to an extension-specific structure. -
swapchainCount
is zero or the number of elements inpDeviceMasks
. -
pDeviceMasks
is 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
.
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 thenVK_ERROR_OUT_OF_DATE_KHR
is returned. -
If any of the presents would have a result of
VK_SUBOPTIMAL_KHR
if issued separately thenVK_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 |