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.
WSI Platform
A platform is an abstraction for a window system, OS, etc. Some examples include MS Windows, Android, and Wayland. The Vulkan API may be integrated in a unique manner for each platform.
The Vulkan API does not define any type of platform object. Platform-specific WSI extensions are defined, each containing platform-specific functions for using WSI. Use of these extensions is guarded by preprocessor symbols as defined in the Window System-Specific Header Control appendix.
In order for an application to be compiled to use WSI with a given platform, it must either:
-
#define
the appropriate preprocessor symbol prior to including thevulkan.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.
WSI Surface
Native platform surface or window objects are abstracted by surface objects,
which are represented by VkSurfaceKHR
handles:
// Provided by VK_KHR_surface
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR)
The VK_KHR_surface
extension declares the VkSurfaceKHR
object, and provides a function for destroying VkSurfaceKHR
objects.
Separate platform-specific extensions each provide a function for creating a
VkSurfaceKHR
object for the respective platform.
From the application’s perspective this is an opaque handle, just like the
handles of other Vulkan objects.
Android Platform
To create a VkSurfaceKHR
object for an Android native window, call:
// Provided by VK_KHR_android_surface
VkResult vkCreateAndroidSurfaceKHR(
VkInstance instance,
const VkAndroidSurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance to associate the surface with. -
pCreateInfo
is a pointer to aVkAndroidSurfaceCreateInfoKHR
structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
During the lifetime of a surface created using a particular
ANativeWindow
handle any attempts to create another surface for the
same ANativeWindow
and any attempts to connect to the same
ANativeWindow
through other platform mechanisms will fail.
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:
// Provided by VK_KHR_android_surface
typedef struct VkAndroidSurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkAndroidSurfaceCreateFlagsKHR flags;
struct ANativeWindow* window;
} VkAndroidSurfaceCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
window
is a pointer to theANativeWindow
to associate the surface with.
To remove an unnecessary compile time dependency, an incomplete type
definition of ANativeWindow
is provided in the Vulkan headers:
// Provided by VK_KHR_android_surface
struct ANativeWindow;
The actual ANativeWindow
type is defined in Android NDK headers.
// Provided by VK_KHR_android_surface
typedef VkFlags VkAndroidSurfaceCreateFlagsKHR;
VkAndroidSurfaceCreateFlagsKHR
is a bitmask type for setting a mask,
but is currently reserved for future use.
Wayland Platform
To create a VkSurfaceKHR
object for a Wayland surface, call:
// Provided by VK_KHR_wayland_surface
VkResult vkCreateWaylandSurfaceKHR(
VkInstance instance,
const VkWaylandSurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance to associate the surface with. -
pCreateInfo
is a pointer to a VkWaylandSurfaceCreateInfoKHR structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkWaylandSurfaceCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_wayland_surface
typedef struct VkWaylandSurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkWaylandSurfaceCreateFlagsKHR flags;
struct wl_display* display;
struct wl_surface* surface;
} VkWaylandSurfaceCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this 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
The wl_surface.attach
, wl_surface.damage
, and
wl_surface.commit
requests 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.
// Provided by VK_KHR_wayland_surface
typedef VkFlags VkWaylandSurfaceCreateFlagsKHR;
VkWaylandSurfaceCreateFlagsKHR
is a bitmask type for setting a mask,
but is currently reserved for future use.
Win32 Platform
To create a VkSurfaceKHR
object for a Win32 window, call:
// Provided by VK_KHR_win32_surface
VkResult vkCreateWin32SurfaceKHR(
VkInstance instance,
const VkWin32SurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance to associate the surface with. -
pCreateInfo
is a pointer to aVkWin32SurfaceCreateInfoKHR
structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
Some Vulkan functions may call the SendMessage
system API when
interacting with a VkSurfaceKHR
through a VkSwapchainKHR
.
In a multithreaded environment, calling SendMessage
from a thread that is
not the thread associated with pCreateInfo->hwnd
will block until the
application has processed the window message.
Thus, applications should either call these Vulkan functions on the message
pump thread, or make sure their message pump is actively running.
Failing to do so may result in deadlocks.
The functions subject to this requirement are:
The VkWin32SurfaceCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_win32_surface
typedef struct VkWin32SurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkWin32SurfaceCreateFlagsKHR flags;
HINSTANCE hinstance;
HWND hwnd;
} VkWin32SurfaceCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
hinstance
is the Win32HINSTANCE
for the window to associate the surface with. -
hwnd
is the Win32HWND
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.
Due to above restrictions,
unless VkSwapchainPresentScalingCreateInfoEXT is used to specify
handling of disparities between surface and swapchain dimensions,
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. |
// Provided by VK_KHR_win32_surface
typedef VkFlags VkWin32SurfaceCreateFlagsKHR;
VkWin32SurfaceCreateFlagsKHR
is a bitmask type for setting a mask, but
is currently reserved for future use.
XCB Platform
To create a VkSurfaceKHR
object for an X11 window, using the XCB
client-side library, call:
// Provided by VK_KHR_xcb_surface
VkResult vkCreateXcbSurfaceKHR(
VkInstance instance,
const VkXcbSurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance to associate the surface with. -
pCreateInfo
is a pointer to aVkXcbSurfaceCreateInfoKHR
structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkXcbSurfaceCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_xcb_surface
typedef struct VkXcbSurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkXcbSurfaceCreateFlagsKHR flags;
xcb_connection_t* connection;
xcb_window_t window;
} VkXcbSurfaceCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this 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.
Due to above restrictions,
unless VkSwapchainPresentScalingCreateInfoEXT is used to specify
handling of disparities between surface and swapchain dimensions,
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.
// Provided by VK_KHR_xcb_surface
typedef VkFlags VkXcbSurfaceCreateFlagsKHR;
VkXcbSurfaceCreateFlagsKHR
is a bitmask type for setting a mask, but
is currently reserved for future use.
Xlib Platform
To create a VkSurfaceKHR
object for an X11 window, using the Xlib
client-side library, call:
// Provided by VK_KHR_xlib_surface
VkResult vkCreateXlibSurfaceKHR(
VkInstance instance,
const VkXlibSurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance to associate the surface with. -
pCreateInfo
is a pointer to aVkXlibSurfaceCreateInfoKHR
structure containing the parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkXlibSurfaceCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_xlib_surface
typedef struct VkXlibSurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkXlibSurfaceCreateFlagsKHR flags;
Display* dpy;
Window window;
} VkXlibSurfaceCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this 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.
Due to above restrictions,
unless VkSwapchainPresentScalingCreateInfoEXT is used to specify
handling of disparities between surface and swapchain dimensions,
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.
// Provided by VK_KHR_xlib_surface
typedef VkFlags VkXlibSurfaceCreateFlagsKHR;
VkXlibSurfaceCreateFlagsKHR
is a bitmask type for setting a mask, but
is currently reserved for future use.
DirectFB Platform
To create a VkSurfaceKHR
object for a DirectFB surface, call:
// Provided by VK_EXT_directfb_surface
VkResult vkCreateDirectFBSurfaceEXT(
VkInstance instance,
const VkDirectFBSurfaceCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance to associate the surface with. -
pCreateInfo
is a pointer to aVkDirectFBSurfaceCreateInfoEXT
structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkDirectFBSurfaceCreateInfoEXT
structure is defined as:
// Provided by VK_EXT_directfb_surface
typedef struct VkDirectFBSurfaceCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkDirectFBSurfaceCreateFlagsEXT flags;
IDirectFB* dfb;
IDirectFBSurface* surface;
} VkDirectFBSurfaceCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
dfb
is a pointer to theIDirectFB
main interface of DirectFB. -
surface
is a pointer to aIDirectFBSurface
surface interface.
With DirectFB, minImageExtent
, maxImageExtent
, and
currentExtent
must always equal the surface size.
// Provided by VK_EXT_directfb_surface
typedef VkFlags VkDirectFBSurfaceCreateFlagsEXT;
VkDirectFBSurfaceCreateFlagsEXT
is a bitmask type for setting a mask,
but is currently reserved for future use.
Fuchsia Platform
To create a VkSurfaceKHR
object for a Fuchsia ImagePipe, call:
// Provided by VK_FUCHSIA_imagepipe_surface
VkResult vkCreateImagePipeSurfaceFUCHSIA(
VkInstance instance,
const VkImagePipeSurfaceCreateInfoFUCHSIA* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance to associate with the surface. -
pCreateInfo
is a pointer to a VkImagePipeSurfaceCreateInfoFUCHSIA structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkImagePipeSurfaceCreateInfoFUCHSIA
structure is defined as:
// Provided by VK_FUCHSIA_imagepipe_surface
typedef struct VkImagePipeSurfaceCreateInfoFUCHSIA {
VkStructureType sType;
const void* pNext;
VkImagePipeSurfaceCreateFlagsFUCHSIA flags;
zx_handle_t imagePipeHandle;
} VkImagePipeSurfaceCreateInfoFUCHSIA;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
imagePipeHandle
is azx_handle_t
referring to the ImagePipe to associate with the surface.
On Fuchsia, the surface currentExtent
is the special value
(0xFFFFFFFF, 0xFFFFFFFF), indicating that the surface size will be
determined by the extent of a swapchain targeting the surface.
// Provided by VK_FUCHSIA_imagepipe_surface
typedef VkFlags VkImagePipeSurfaceCreateFlagsFUCHSIA;
VkImagePipeSurfaceCreateFlagsFUCHSIA
is a bitmask type for setting a
mask, but is currently reserved for future use.
Google Games Platform
To create a VkSurfaceKHR
object for a Google Games Platform stream
descriptor, call:
// Provided by VK_GGP_stream_descriptor_surface
VkResult vkCreateStreamDescriptorSurfaceGGP(
VkInstance instance,
const VkStreamDescriptorSurfaceCreateInfoGGP* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance to associate with the surface. -
pCreateInfo
is a pointer to aVkStreamDescriptorSurfaceCreateInfoGGP
structure containing parameters that affect the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkStreamDescriptorSurfaceCreateInfoGGP
structure is defined as:
// Provided by VK_GGP_stream_descriptor_surface
typedef struct VkStreamDescriptorSurfaceCreateInfoGGP {
VkStructureType sType;
const void* pNext;
VkStreamDescriptorSurfaceCreateFlagsGGP flags;
GgpStreamDescriptor streamDescriptor;
} VkStreamDescriptorSurfaceCreateInfoGGP;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
streamDescriptor
is aGgpStreamDescriptor
referring to the GGP stream descriptor to associate with the surface.
On Google Games Platform, the surface extents are dynamic.
The minImageExtent
will never be greater than 1080p and the
maxImageExtent
will never be less than 1080p.
The currentExtent
will reflect the current optimal resolution.
Applications are expected to choose an appropriate size for the swapchain’s
imageExtent
, within the bounds of the surface.
Using the surface’s currentExtent
will offer the best performance and
quality.
When a swapchain’s imageExtent
does not match the surface’s
currentExtent
, the presentable images are scaled to the surface’s
dimensions during presentation if possible and VK_SUBOPTIMAL_KHR
is
returned, otherwise presentation fails with VK_ERROR_OUT_OF_DATE_KHR
.
// Provided by VK_GGP_stream_descriptor_surface
typedef VkFlags VkStreamDescriptorSurfaceCreateFlagsGGP;
VkStreamDescriptorSurfaceCreateFlagsGGP
is a bitmask type for setting
a mask, but is currently reserved for future use.
iOS Platform
To create a VkSurfaceKHR
object for an iOS UIView
or
CAMetalLayer
, call:
// Provided by VK_MVK_ios_surface
VkResult vkCreateIOSSurfaceMVK(
VkInstance instance,
const VkIOSSurfaceCreateInfoMVK* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance with which to associate the surface. -
pCreateInfo
is a pointer to a VkIOSSurfaceCreateInfoMVK structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The |
The VkIOSSurfaceCreateInfoMVK structure is defined as:
// Provided by VK_MVK_ios_surface
typedef struct VkIOSSurfaceCreateInfoMVK {
VkStructureType sType;
const void* pNext;
VkIOSSurfaceCreateFlagsMVK flags;
const void* pView;
} VkIOSSurfaceCreateInfoMVK;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
pView
is a reference to either aCAMetalLayer
object or aUIView
object.
// Provided by VK_MVK_ios_surface
typedef VkFlags VkIOSSurfaceCreateFlagsMVK;
VkIOSSurfaceCreateFlagsMVK
is a bitmask type for setting a mask, but
is currently reserved for future use.
macOS Platform
To create a VkSurfaceKHR
object for a macOS NSView
or
CAMetalLayer
, call:
// Provided by VK_MVK_macos_surface
VkResult vkCreateMacOSSurfaceMVK(
VkInstance instance,
const VkMacOSSurfaceCreateInfoMVK* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance with which to associate the surface. -
pCreateInfo
is a pointer to a VkMacOSSurfaceCreateInfoMVK structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The |
The VkMacOSSurfaceCreateInfoMVK structure is defined as:
// Provided by VK_MVK_macos_surface
typedef struct VkMacOSSurfaceCreateInfoMVK {
VkStructureType sType;
const void* pNext;
VkMacOSSurfaceCreateFlagsMVK flags;
const void* pView;
} VkMacOSSurfaceCreateInfoMVK;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
pView
is a reference to either aCAMetalLayer
object or anNSView
object.
// Provided by VK_MVK_macos_surface
typedef VkFlags VkMacOSSurfaceCreateFlagsMVK;
VkMacOSSurfaceCreateFlagsMVK
is a bitmask type for setting a mask, but
is currently reserved for future use.
VI Platform
To create a VkSurfaceKHR
object for an nn
::vi
::Layer
,
query the layer’s native handle using
nn
::vi
::GetNativeWindow
, and then call:
// Provided by VK_NN_vi_surface
VkResult vkCreateViSurfaceNN(
VkInstance instance,
const VkViSurfaceCreateInfoNN* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance with which to associate the surface. -
pCreateInfo
is a pointer to aVkViSurfaceCreateInfoNN
structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
During the lifetime of a surface created using a particular
nn
::vi
::NativeWindowHandle
, applications must not attempt to
create another surface for the same nn
::vi
::Layer
or attempt
to connect to the same nn
::vi
::Layer
through other platform
mechanisms.
If the native window is created with a specified size, currentExtent
will reflect that size.
In this case, applications should use the same size for the swapchain’s
imageExtent
.
Otherwise, the currentExtent
will have the special value
(0xFFFFFFFF, 0xFFFFFFFF), indicating that applications are expected to
choose an appropriate size for the swapchain’s imageExtent
(e.g., by
matching the result of a call to
nn
::vi
::GetDisplayResolution
).
The VkViSurfaceCreateInfoNN
structure is defined as:
// Provided by VK_NN_vi_surface
typedef struct VkViSurfaceCreateInfoNN {
VkStructureType sType;
const void* pNext;
VkViSurfaceCreateFlagsNN flags;
void* window;
} VkViSurfaceCreateInfoNN;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
window
is thenn
::vi
::NativeWindowHandle
for thenn
::vi
::Layer
with which to associate the surface.
// Provided by VK_NN_vi_surface
typedef VkFlags VkViSurfaceCreateFlagsNN;
VkViSurfaceCreateFlagsNN
is a bitmask type for setting a mask, but is
currently reserved for future use.
Metal Platform
To create a VkSurfaceKHR
object for a CAMetalLayer
, call:
// Provided by VK_EXT_metal_surface
VkResult vkCreateMetalSurfaceEXT(
VkInstance instance,
const VkMetalSurfaceCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance with which to associate the surface. -
pCreateInfo
is a pointer to a VkMetalSurfaceCreateInfoEXT structure specifying parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to aVkSurfaceKHR
handle in which the created surface object is returned.
The VkMetalSurfaceCreateInfoEXT structure is defined as:
// Provided by VK_EXT_metal_surface
typedef struct VkMetalSurfaceCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkMetalSurfaceCreateFlagsEXT flags;
const CAMetalLayer* pLayer;
} VkMetalSurfaceCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
pLayer
is a reference to aCAMetalLayer
object representing a renderable surface.
To remove an unnecessary compile time dependency, an incomplete type
definition of CAMetalLayer
is provided in the Vulkan headers:
// Provided by VK_EXT_metal_surface
#ifdef __OBJC__
@class CAMetalLayer;
#else
typedef void CAMetalLayer;
#endif
The actual CAMetalLayer
type is defined in the QuartzCore
framework.
// Provided by VK_EXT_metal_surface
typedef VkFlags VkMetalSurfaceCreateFlagsEXT;
VkMetalSurfaceCreateFlagsEXT
is a bitmask type for setting a mask, but
is currently reserved for future use.
QNX Screen Platform
To create a VkSurfaceKHR
object for a QNX Screen surface, call:
// Provided by VK_QNX_screen_surface
VkResult vkCreateScreenSurfaceQNX(
VkInstance instance,
const VkScreenSurfaceCreateInfoQNX* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance to associate the surface with. -
pCreateInfo
is a pointer to a VkScreenSurfaceCreateInfoQNX structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface object is returned.
The VkScreenSurfaceCreateInfoQNX
structure is defined as:
// Provided by VK_QNX_screen_surface
typedef struct VkScreenSurfaceCreateInfoQNX {
VkStructureType sType;
const void* pNext;
VkScreenSurfaceCreateFlagsQNX flags;
struct _screen_context* context;
struct _screen_window* window;
} VkScreenSurfaceCreateInfoQNX;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
context
andwindow
are QNX Screencontext
andwindow
to associate the surface with.
// Provided by VK_QNX_screen_surface
typedef VkFlags VkScreenSurfaceCreateFlagsQNX;
VkScreenSurfaceCreateFlagsQNX
is a bitmask type for setting a mask,
but is currently reserved for future use.
Platform-Independent Information
Once created, VkSurfaceKHR
objects can be used in this and other
extensions, in particular the VK_KHR_swapchain
extension.
Several WSI functions return VK_ERROR_SURFACE_LOST_KHR
if the surface
becomes no longer available.
After such an error, the surface (and any child swapchain, if one exists)
should be destroyed, as there is no way to restore them to a not-lost
state.
Applications may attempt to create a new VkSurfaceKHR
using the same
native platform window object, but whether such re-creation will succeed is
platform-dependent and may depend on the reason the surface became
unavailable.
A lost surface does not otherwise cause devices to be
lost.
To destroy a VkSurfaceKHR
object, call:
// Provided by VK_KHR_surface
void vkDestroySurfaceKHR(
VkInstance instance,
VkSurfaceKHR surface,
const VkAllocationCallbacks* pAllocator);
-
instance
is the instance used to create the surface. -
surface
is the surface to destroy. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).
Destroying a VkSurfaceKHR
merely severs the connection between Vulkan
and the native surface, and does not imply destroying the native surface,
closing a window, or similar behavior.
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.
Display Enumeration
Displays are represented by VkDisplayKHR
handles:
// Provided by VK_KHR_display
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDisplayKHR)
Various functions are provided for enumerating the available display devices present on a Vulkan physical device. To query information about the available displays, call:
// Provided by VK_KHR_display
VkResult vkGetPhysicalDeviceDisplayPropertiesKHR(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkDisplayPropertiesKHR* pProperties);
-
physicalDevice
is a physical device. -
pPropertyCount
is a pointer to an integer related to the number of display devices available or queried, as described below. -
pProperties
is eitherNULL
or a pointer to an array of VkDisplayPropertiesKHR structures.
If pProperties
is NULL
, then the number of display devices available
for physicalDevice
is returned in pPropertyCount
.
Otherwise, pPropertyCount
must point to a variable set by the
application 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, and VK_INCOMPLETE
will be returned instead of
VK_SUCCESS
, to indicate that not all the available properties were
returned.
The VkDisplayPropertiesKHR
structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplayPropertiesKHR {
VkDisplayKHR display;
const char* displayName;
VkExtent2D physicalDimensions;
VkExtent2D physicalResolution;
VkSurfaceTransformFlagsKHR supportedTransforms;
VkBool32 planeReorderPossible;
VkBool32 persistentContent;
} VkDisplayPropertiesKHR;
-
display
is a handle that is used to refer to the display described here. This handle will be valid for the lifetime of the Vulkan instance. -
displayName
isNULL
or a pointer to a null-terminated UTF-8 string containing the name of the display. Generally, this will be the name provided by the display’s EDID. IfNULL
, no suitable name is available. If notNULL
, the string pointed to must remain accessible and unmodified 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.
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.
Persistent presents may have higher latency, and may use less power when the screen content is updated infrequently, or when only a portion of the screen needs to be updated in most frames. |
To query information about the available displays, call:
// Provided by VK_KHR_get_display_properties2
VkResult vkGetPhysicalDeviceDisplayProperties2KHR(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkDisplayProperties2KHR* pProperties);
-
physicalDevice
is a physical device. -
pPropertyCount
is a pointer to an integer related to the number of display devices available or queried, as described below. -
pProperties
is 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:
// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayProperties2KHR {
VkStructureType sType;
void* pNext;
VkDisplayPropertiesKHR displayProperties;
} VkDisplayProperties2KHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
displayProperties
is a VkDisplayPropertiesKHR structure.
Acquiring and Releasing Displays
On some platforms, access to displays is limited to a single process or native driver instance. On such platforms, some or all of the displays may not be available to Vulkan if they are already in use by a native windowing system or other application.
To acquire permission to directly access a display in Vulkan from an X11 server, call:
// Provided by VK_EXT_acquire_xlib_display
VkResult vkAcquireXlibDisplayEXT(
VkPhysicalDevice physicalDevice,
Display* dpy,
VkDisplayKHR display);
-
physicalDevice
The physical device the display is on. -
dpy
A connection to the X11 server that currently ownsdisplay
. -
display
The display the caller wishes to control in Vulkan.
All permissions necessary to control the display are granted to the Vulkan
instance associated with physicalDevice
until the display is released
or the X11 connection specified by dpy
is terminated.
Permission to access the display may be temporarily revoked during periods
when the X11 server from which control was acquired itself loses access to
display
.
During such periods, operations which require access to the display must
fail with an appropriate error code.
If the X11 server associated with dpy
does not own display
, or
if permission to access it has already been acquired by another entity, the
call must return the error code VK_ERROR_INITIALIZATION_FAILED
.
One example of when an X11 server loses access to a display is when it loses ownership of its virtual terminal. |
When acquiring displays from an X11 server, an application may also wish to
enumerate and identify them using a native handle rather than a
VkDisplayKHR
handle.
To determine the VkDisplayKHR
handle corresponding to an X11 RandR
Output, call:
// Provided by VK_EXT_acquire_xlib_display
VkResult vkGetRandROutputDisplayEXT(
VkPhysicalDevice physicalDevice,
Display* dpy,
RROutput rrOutput,
VkDisplayKHR* pDisplay);
-
physicalDevice
The physical device to query the display handle on. -
dpy
A connection to the X11 server from whichrrOutput
was queried. -
rrOutput
An X11 RandR output ID. -
pDisplay
The corresponding VkDisplayKHR handle will be returned here.
If there is no VkDisplayKHR corresponding to rrOutput
on
physicalDevice
, VK_NULL_HANDLE must be returned in
pDisplay
.
To acquire permission to directly access a display in Vulkan on Windows 10, call:
// Provided by VK_NV_acquire_winrt_display
VkResult vkAcquireWinrtDisplayNV(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display);
-
physicalDevice
The physical device the display is on. -
display
The display the caller wishes to control in Vulkan.
All permissions necessary to control the display are granted to the Vulkan
instance associated with physicalDevice
until the display is released
or the application is terminated.
Permission to access the display may be revoked by events that cause
Windows 10 itself to lose access to display
.
If this has happened, operations which require access to the display must
fail with an appropriate error code.
If permission to access display
has already been acquired by another
entity, the call must return the error code
VK_ERROR_INITIALIZATION_FAILED
.
The Vulkan instance acquires control of a “winrt::Windows::Devices::Display::Core::DisplayTarget” by performing an operation equivalent to “winrt::Windows::Devices::Display::Core::DisplayManager.TryAcquireTarget()” on the “DisplayTarget”. |
One example of when Windows 10 loses access to a display is when the display is hot-unplugged. |
One example of when a display has already been acquired by another entity is when the Windows desktop compositor (DWM) is in control of the display. Beginning with Windows 10 version 2004 it is possible to cause DWM to release a display by using the “Advanced display settings” sub-page of the “Display settings” control panel. vkAcquireWinrtDisplayNV does not itself cause DWM to release a display; this action must be performed outside of Vulkan. |
When acquiring displays on Windows 10, an application may also wish to
enumerate and identify them using a native handle rather than a
VkDisplayKHR
handle.
To determine the VkDisplayKHR
handle corresponding to a
“winrt::Windows::Devices::Display::Core::DisplayTarget”,
call:
// Provided by VK_NV_acquire_winrt_display
VkResult vkGetWinrtDisplayNV(
VkPhysicalDevice physicalDevice,
uint32_t deviceRelativeId,
VkDisplayKHR* pDisplay);
-
physicalDevice
The physical device on which to query the display handle. -
deviceRelativeId
The value of the “AdapterRelativeId” property of a “DisplayTarget” that is enumerated by a “DisplayAdapter” with an “Id” property matching thedeviceLUID
property of a VkPhysicalDeviceIDProperties forphysicalDevice
. -
pDisplay
The corresponding VkDisplayKHR handle will be returned here.
If there is no VkDisplayKHR corresponding to deviceRelativeId
on
physicalDevice
, VK_NULL_HANDLE must be returned in
pDisplay
.
To acquire permission to directly a display in Vulkan from the Direct Rendering Manager (DRM) interface, call:
// Provided by VK_EXT_acquire_drm_display
VkResult vkAcquireDrmDisplayEXT(
VkPhysicalDevice physicalDevice,
int32_t drmFd,
VkDisplayKHR display);
-
physicalDevice
The physical device the display is on. -
drmFd
DRM primary file descriptor. -
display
The display the caller wishes Vulkan to control.
All permissions necessary to control the display are granted to the Vulkan
instance associated with the provided physicalDevice
until the display
is either released or the connector is unplugged.
The provided drmFd
must correspond to the one owned by the
physicalDevice
.
If not, the error code VK_ERROR_UNKNOWN
must be returned.
The DRM FD must have DRM master permissions.
If any error is encountered during the acquisition of the display, the call
must return the error code VK_ERROR_INITIALIZATION_FAILED
.
The provided DRM fd should not be closed before the display is released, attempting to do it may result in undefined behavior.
Before acquiring a display from the DRM interface, the caller may want to
select a specific VkDisplayKHR
handle by identifying it using a
connectorId
.
To do so, call:
// Provided by VK_EXT_acquire_drm_display
VkResult vkGetDrmDisplayEXT(
VkPhysicalDevice physicalDevice,
int32_t drmFd,
uint32_t connectorId,
VkDisplayKHR* display);
-
physicalDevice
The physical device to query the display from. -
drmFd
DRM primary file descriptor. -
connectorId
Identifier of the specified DRM connector. -
display
The corresponding VkDisplayKHR handle will be returned here.
If there is no VkDisplayKHR corresponding to the connectorId
on
the physicalDevice
, the returning display
must be set to
VK_NULL_HANDLE.
The provided drmFd
must correspond to the one owned by the
physicalDevice
.
If not, the error code VK_ERROR_UNKNOWN
must be returned.
Master permissions are not required, because the file descriptor is just
used for information gathering purposes.
The given connectorId
must be a resource owned by the provided
drmFd
.
If not, the error code VK_ERROR_UNKNOWN
must be returned.
If any error is encountered during the identification of the display, the
call must return the error code VK_ERROR_INITIALIZATION_FAILED
.
To release a previously acquired display, call:
// Provided by VK_EXT_direct_mode_display
VkResult vkReleaseDisplayEXT(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display);
-
physicalDevice
The physical device the display is on. -
display
The display to release control of.
Display Planes
Images are presented to individual planes on a display. Devices must support at least one plane on each display. Planes can be stacked and blended to composite multiple images on one display. Devices may support only a fixed stacking order and fixed mapping between planes and displays, or they may allow arbitrary application-specified stacking orders and mappings between planes and displays. To query the properties of device display planes, call:
// Provided by VK_KHR_display
VkResult vkGetPhysicalDeviceDisplayPlanePropertiesKHR(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkDisplayPlanePropertiesKHR* pProperties);
-
physicalDevice
is a physical device. -
pPropertyCount
is a pointer to an integer related to the number of display planes available or queried, as described below. -
pProperties
is 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
application 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:
// Provided by VK_KHR_display
typedef struct VkDisplayPlanePropertiesKHR {
VkDisplayKHR currentDisplay;
uint32_t currentStackIndex;
} VkDisplayPlanePropertiesKHR;
-
currentDisplay
is the handle of the display the plane is currently associated with. If the plane is not currently attached to any displays, this will be VK_NULL_HANDLE. -
currentStackIndex
is the current z-order of the plane. This will be between 0 and the value returned byvkGetPhysicalDeviceDisplayPlanePropertiesKHR
inpPropertyCount
.
To query the properties of a device’s display planes, call:
// Provided by VK_KHR_get_display_properties2
VkResult vkGetPhysicalDeviceDisplayPlaneProperties2KHR(
VkPhysicalDevice physicalDevice,
uint32_t* pPropertyCount,
VkDisplayPlaneProperties2KHR* pProperties);
-
physicalDevice
is a physical device. -
pPropertyCount
is a pointer to an integer related to the number of display planes available or queried, as described below. -
pProperties
is 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:
// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayPlaneProperties2KHR {
VkStructureType sType;
void* pNext;
VkDisplayPlanePropertiesKHR displayPlaneProperties;
} VkDisplayPlaneProperties2KHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
displayPlaneProperties
is a VkDisplayPlanePropertiesKHR structure.
To determine which displays a plane is usable with, call
// Provided by VK_KHR_display
VkResult vkGetDisplayPlaneSupportedDisplaysKHR(
VkPhysicalDevice physicalDevice,
uint32_t planeIndex,
uint32_t* pDisplayCount,
VkDisplayKHR* pDisplays);
-
physicalDevice
is a physical device. -
planeIndex
is the plane which the application wishes to use, and must be in the range [0, physical device plane count - 1]. -
pDisplayCount
is a pointer to an integer related to the number of displays available or queried, as described below. -
pDisplays
is 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
application 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 usable
display-plane pairs for physicalDevice
, at most pDisplayCount
handles will be written, and VK_INCOMPLETE
will be returned instead of
VK_SUCCESS
, to indicate that not all the available pairs were
returned.
Additional properties of displays are queried using specialized query functions.
Display Modes
Display modes are represented by VkDisplayModeKHR
handles:
// Provided by VK_KHR_display
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkDisplayModeKHR)
Each display has one or more supported modes associated with it by default. These built-in modes are queried by calling:
// Provided by VK_KHR_display
VkResult vkGetDisplayModePropertiesKHR(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display,
uint32_t* pPropertyCount,
VkDisplayModePropertiesKHR* pProperties);
-
physicalDevice
is the physical device associated 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
application 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, and VK_INCOMPLETE
will be returned instead of
VK_SUCCESS
, to indicate that not all the available display modes were
returned.
The VkDisplayModePropertiesKHR
structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplayModePropertiesKHR {
VkDisplayModeKHR displayMode;
VkDisplayModeParametersKHR parameters;
} VkDisplayModePropertiesKHR;
-
displayMode
is a handle to the display mode described in this structure. This handle will be valid for the lifetime of the Vulkan instance. -
parameters
is a VkDisplayModeParametersKHR structure describing the display parameters associated withdisplayMode
.
// Provided by VK_KHR_display
typedef VkFlags VkDisplayModeCreateFlagsKHR;
VkDisplayModeCreateFlagsKHR
is a bitmask type for setting a mask, but
is currently reserved for future use.
To query the properties of a device’s built-in display modes, call:
// Provided by VK_KHR_get_display_properties2
VkResult vkGetDisplayModeProperties2KHR(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display,
uint32_t* pPropertyCount,
VkDisplayModeProperties2KHR* pProperties);
-
physicalDevice
is the physical device associated 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:
// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayModeProperties2KHR {
VkStructureType sType;
void* pNext;
VkDisplayModePropertiesKHR displayModeProperties;
} VkDisplayModeProperties2KHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
displayModeProperties
is a VkDisplayModePropertiesKHR structure.
The VkDisplayModeParametersKHR
structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplayModeParametersKHR {
VkExtent2D visibleRegion;
uint32_t refreshRate;
} VkDisplayModeParametersKHR;
-
visibleRegion
is the 2D extents of the visible region. -
refreshRate
is auint32_t
that is the number of times the display is refreshed each second multiplied by 1000.
For example, a 60Hz display mode would report a |
Additional modes may also be created by calling:
// Provided by VK_KHR_display
VkResult vkCreateDisplayModeKHR(
VkPhysicalDevice physicalDevice,
VkDisplayKHR display,
const VkDisplayModeCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkDisplayModeKHR* pMode);
-
physicalDevice
is the physical device associated withdisplay
. -
display
is the display to create an additional mode for. -
pCreateInfo
is a pointer to 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
is a pointer to a VkDisplayModeKHR handle in which the mode created is returned.
The VkDisplayModeCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplayModeCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkDisplayModeCreateFlagsKHR flags;
VkDisplayModeParametersKHR parameters;
} VkDisplayModeCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use, and must be zero. -
parameters
is a VkDisplayModeParametersKHR structure describing the display parameters to use in creating the new mode. If the parameters are not compatible with the specified display, the implementation must 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:
// Provided by VK_KHR_display
VkResult vkGetDisplayPlaneCapabilitiesKHR(
VkPhysicalDevice physicalDevice,
VkDisplayModeKHR mode,
uint32_t planeIndex,
VkDisplayPlaneCapabilitiesKHR* pCapabilities);
-
physicalDevice
is the physical device associated with the display specified bymode
-
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:
// Provided by VK_KHR_display
typedef struct VkDisplayPlaneCapabilitiesKHR {
VkDisplayPlaneAlphaFlagsKHR supportedAlpha;
VkOffset2D minSrcPosition;
VkOffset2D maxSrcPosition;
VkExtent2D minSrcExtent;
VkExtent2D maxSrcExtent;
VkOffset2D minDstPosition;
VkOffset2D maxDstPosition;
VkExtent2D minDstExtent;
VkExtent2D maxDstExtent;
} VkDisplayPlaneCapabilitiesKHR;
-
supportedAlpha
is a bitmask of VkDisplayPlaneAlphaFlagBitsKHR describing the supported alpha blending modes. -
minSrcPosition
is the minimum source rectangle offset supported by this plane using the specified mode. -
maxSrcPosition
is the maximum source rectangle offset supported by this plane using the specified mode. 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 which 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 which 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
.
The value supportedAlpha
must contain at least one valid
VkDisplayPlaneAlphaFlagBitsKHR bit.
These values indicate the limits of the implementation’s individual fields.
Not all combinations of values within the offset and extent ranges returned
in VkDisplayPlaneCapabilitiesKHR
are guaranteed to be supported.
Presentation requests specifying unsupported combinations may fail.
To query the capabilities of a given mode and plane combination, call:
// Provided by VK_KHR_get_display_properties2
VkResult vkGetDisplayPlaneCapabilities2KHR(
VkPhysicalDevice physicalDevice,
const VkDisplayPlaneInfo2KHR* pDisplayPlaneInfo,
VkDisplayPlaneCapabilities2KHR* pCapabilities);
-
physicalDevice
is the physical device associated withpDisplayPlaneInfo
. -
pDisplayPlaneInfo
is a pointer to a VkDisplayPlaneInfo2KHR structure describing the plane and mode. -
pCapabilities
is a pointer to a VkDisplayPlaneCapabilities2KHR structure in which the capabilities are returned.
vkGetDisplayPlaneCapabilities2KHR
behaves similarly to
vkGetDisplayPlaneCapabilitiesKHR, with the ability to specify extended
inputs via chained input structures, and to return extended information via
chained output structures.
The VkDisplayPlaneInfo2KHR
structure is defined as:
// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayPlaneInfo2KHR {
VkStructureType sType;
const void* pNext;
VkDisplayModeKHR mode;
uint32_t planeIndex;
} VkDisplayPlaneInfo2KHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
mode
is the display mode the application intends to program when using the specified plane.
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:
// Provided by VK_KHR_get_display_properties2
typedef struct VkDisplayPlaneCapabilities2KHR {
VkStructureType sType;
void* pNext;
VkDisplayPlaneCapabilitiesKHR capabilities;
} VkDisplayPlaneCapabilities2KHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
capabilities
is a VkDisplayPlaneCapabilitiesKHR structure.
Display Control
To set the power state of a display, call:
// Provided by VK_EXT_display_control
VkResult vkDisplayPowerControlEXT(
VkDevice device,
VkDisplayKHR display,
const VkDisplayPowerInfoEXT* pDisplayPowerInfo);
-
device
is a logical device associated withdisplay
. -
display
is the display whose power state is modified. -
pDisplayPowerInfo
is a pointer to a VkDisplayPowerInfoEXT structure specifying the new power state ofdisplay
.
The VkDisplayPowerInfoEXT
structure is defined as:
// Provided by VK_EXT_display_control
typedef struct VkDisplayPowerInfoEXT {
VkStructureType sType;
const void* pNext;
VkDisplayPowerStateEXT powerState;
} VkDisplayPowerInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
powerState
is a VkDisplayPowerStateEXT value specifying the new power state of the display.
Possible values of VkDisplayPowerInfoEXT::powerState
, specifying
the new power state of a display, are:
// Provided by VK_EXT_display_control
typedef enum VkDisplayPowerStateEXT {
VK_DISPLAY_POWER_STATE_OFF_EXT = 0,
VK_DISPLAY_POWER_STATE_SUSPEND_EXT = 1,
VK_DISPLAY_POWER_STATE_ON_EXT = 2,
} VkDisplayPowerStateEXT;
-
VK_DISPLAY_POWER_STATE_OFF_EXT
specifies that the display is powered down. -
VK_DISPLAY_POWER_STATE_SUSPEND_EXT
specifies that the display is put into a low power mode, from which it may be able to transition back toVK_DISPLAY_POWER_STATE_ON_EXT
more quickly than if it were inVK_DISPLAY_POWER_STATE_OFF_EXT
. This state may be the same asVK_DISPLAY_POWER_STATE_OFF_EXT
. -
VK_DISPLAY_POWER_STATE_ON_EXT
specifies that the display is powered on.
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
object for a display plane, call:
// Provided by VK_KHR_display
VkResult vkCreateDisplayPlaneSurfaceKHR(
VkInstance instance,
const VkDisplaySurfaceCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance corresponding to the physical device the targeted display is on. -
pCreateInfo
is a pointer to a VkDisplaySurfaceCreateInfoKHR structure specifying which mode, plane, and other parameters to use, as described below. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to a VkSurfaceKHR handle in which the created surface is returned.
The VkDisplaySurfaceCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_display
typedef struct VkDisplaySurfaceCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkDisplaySurfaceCreateFlagsKHR flags;
VkDisplayModeKHR displayMode;
uint32_t planeIndex;
uint32_t planeStackIndex;
VkSurfaceTransformFlagBitsKHR transform;
float globalAlpha;
VkDisplayPlaneAlphaFlagBitsKHR alphaMode;
VkExtent2D imageExtent;
} VkDisplaySurfaceCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use, and must be zero. -
displayMode
is a VkDisplayModeKHR handle specifying the mode to use when displaying this surface. -
planeIndex
is the plane on which this surface appears. -
planeStackIndex
is the z-order of the plane. -
transform
is a VkSurfaceTransformFlagBitsKHR value specifying the transformation to apply to images as part of the scanout operation. -
globalAlpha
is the global alpha value. This value is ignored ifalphaMode
is notVK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR
. -
alphaMode
is a VkDisplayPlaneAlphaFlagBitsKHR value specifying the type of alpha blending to use. -
imageExtent
is the size of the presentable images to use with the surface.
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. |
// Provided by VK_KHR_display
typedef VkFlags VkDisplaySurfaceCreateFlagsKHR;
VkDisplaySurfaceCreateFlagsKHR
is a bitmask type for setting a mask,
but is currently reserved for future use.
Bits which can be set in
VkDisplaySurfaceCreateInfoKHR::alphaMode
, specifying the type of
alpha blending to use on a display, are:
// Provided by VK_KHR_display
typedef enum VkDisplayPlaneAlphaFlagBitsKHR {
VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR = 0x00000001,
VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR = 0x00000002,
VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR = 0x00000004,
VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_PREMULTIPLIED_BIT_KHR = 0x00000008,
} VkDisplayPlaneAlphaFlagBitsKHR;
-
VK_DISPLAY_PLANE_ALPHA_OPAQUE_BIT_KHR
specifies that the source image will be treated as opaque. -
VK_DISPLAY_PLANE_ALPHA_GLOBAL_BIT_KHR
specifies that a global alpha value must be specified that will be applied to all pixels in the source image. -
VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR
specifies that the alpha value will be determined by the alpha component 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 components. -
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 components.
// Provided by VK_KHR_display
typedef VkFlags VkDisplayPlaneAlphaFlagsKHR;
VkDisplayPlaneAlphaFlagsKHR
is a bitmask type for setting a mask of
zero or more VkDisplayPlaneAlphaFlagBitsKHR.
Presenting to Headless Surfaces
Vulkan rendering can be presented to a headless surface, where the presentation operation is a no-op producing no externally-visible result.
Because there is no real presentation target, the headless presentation engine may be extended to impose an arbitrary or customizable set of restrictions and features. This makes it a useful portable test target for applications targeting a wide range of presentation engines where the actual target presentation engines might be scarce, unavailable or otherwise undesirable or inconvenient to use for general Vulkan application development. The usual surface query mechanisms must be used to determine the actual restrictions and features of the implementation. |
To create a headless VkSurfaceKHR
object, call:
// Provided by VK_EXT_headless_surface
VkResult vkCreateHeadlessSurfaceEXT(
VkInstance instance,
const VkHeadlessSurfaceCreateInfoEXT* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSurfaceKHR* pSurface);
-
instance
is the instance to associate the surface with. -
pCreateInfo
is a pointer to a VkHeadlessSurfaceCreateInfoEXT structure containing parameters affecting the creation of the surface object. -
pAllocator
is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation). -
pSurface
is a pointer to aVkSurfaceKHR
handle in which the created surface object is returned.
The VkHeadlessSurfaceCreateInfoEXT
structure is defined as:
// Provided by VK_EXT_headless_surface
typedef struct VkHeadlessSurfaceCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkHeadlessSurfaceCreateFlagsEXT flags;
} VkHeadlessSurfaceCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use.
For headless surfaces, currentExtent
is the reserved value
(0xFFFFFFFF, 0xFFFFFFFF).
Whatever the application sets a swapchain’s imageExtent
to will be the
size of the surface, after the first image is presented.
// Provided by VK_EXT_headless_surface
typedef VkFlags VkHeadlessSurfaceCreateFlagsEXT;
VkHeadlessSurfaceCreateFlagsEXT
is a bitmask type for setting a mask,
but is currently reserved for future use.
Querying for WSI Support
Not all physical devices will include WSI support. Within a physical device, not all queue families will support presentation. WSI support and compatibility can be determined in a platform-neutral manner (which determines support for presentation to a particular surface object) and additionally may be determined in platform-specific manners (which determine support for presentation on the specified physical device but do not guarantee support for presentation to a particular surface object).
To determine whether a queue family of a physical device supports presentation to a given surface, call:
// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfaceSupportKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
VkSurfaceKHR surface,
VkBool32* pSupported);
-
physicalDevice
is the physical device. -
queueFamilyIndex
is the queue family. -
surface
is the surface. -
pSupported
is a pointer to aVkBool32
, which is set toVK_TRUE
to indicate support, andVK_FALSE
otherwise.
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.
Wayland Platform
To determine whether a queue family of a physical device supports presentation to a Wayland compositor, call:
// Provided by VK_KHR_wayland_surface
VkBool32 vkGetPhysicalDeviceWaylandPresentationSupportKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
struct wl_display* display);
-
physicalDevice
is the physical device. -
queueFamilyIndex
is the queue family index. -
display
is a pointer to thewl_display
associated with a Wayland compositor.
This platform-specific function can be called prior to creating a surface.
Win32 Platform
To determine whether a queue family of a physical device supports presentation to the Microsoft Windows desktop, call:
// Provided by VK_KHR_win32_surface
VkBool32 vkGetPhysicalDeviceWin32PresentationSupportKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex);
-
physicalDevice
is the physical device. -
queueFamilyIndex
is the queue family index.
This platform-specific function can be called prior to creating a surface.
XCB Platform
To determine whether a queue family of a physical device supports presentation to an X11 server, using the XCB client-side library, call:
// Provided by VK_KHR_xcb_surface
VkBool32 vkGetPhysicalDeviceXcbPresentationSupportKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
xcb_connection_t* connection,
xcb_visualid_t visual_id);
-
physicalDevice
is the physical device. -
queueFamilyIndex
is the queue family index. -
connection
is a pointer to 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.
Xlib Platform
To determine whether a queue family of a physical device supports presentation to an X11 server, using the Xlib client-side library, call:
// Provided by VK_KHR_xlib_surface
VkBool32 vkGetPhysicalDeviceXlibPresentationSupportKHR(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
Display* dpy,
VisualID visualID);
-
physicalDevice
is the physical device. -
queueFamilyIndex
is the queue family index. -
dpy
is a pointer to an XlibDisplay
connection to the server. -
visualId
is an X11 visual (VisualID
).
This platform-specific function can be called prior to creating a surface.
DirectFB Platform
To determine whether a queue family of a physical device supports presentation with DirectFB library, call:
// Provided by VK_EXT_directfb_surface
VkBool32 vkGetPhysicalDeviceDirectFBPresentationSupportEXT(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
IDirectFB* dfb);
-
physicalDevice
is the physical device. -
queueFamilyIndex
is the queue family index. -
dfb
is a pointer to theIDirectFB
main interface of DirectFB.
This platform-specific function can be called prior to creating a surface.
Fuchsia Platform
On Fuchsia, all physical devices and queue families must be capable of presentation with any ImagePipe. As a result there is no Fuchsia-specific query for these capabilities.
Google Games Platform
On Google Games Platform, all physical devices and queue families with the
VK_QUEUE_GRAPHICS_BIT
or VK_QUEUE_COMPUTE_BIT
capabilities must
be capable of presentation with any Google Games Platform stream descriptor.
As a result, there is no query specific to Google Games Platform for these
capabilities.
iOS Platform
On iOS, all physical devices and queue families must be capable of presentation with any layer. As a result there is no iOS-specific query for these capabilities.
macOS Platform
On macOS, all physical devices and queue families must be capable of presentation with any layer. As a result there is no macOS-specific query for these capabilities.
VI Platform
On VI, all physical devices and queue families must be capable of presentation with any layer. As a result there is no VI-specific query for these capabilities.
QNX Screen Platform
To determine whether a queue family of a physical device supports presentation to a QNX Screen compositor, call:
// Provided by VK_QNX_screen_surface
VkBool32 vkGetPhysicalDeviceScreenPresentationSupportQNX(
VkPhysicalDevice physicalDevice,
uint32_t queueFamilyIndex,
struct _screen_window* window);
-
physicalDevice
is the physical device. -
queueFamilyIndex
is the queue family index. -
window
is the QNX Screenwindow
object.
This platform-specific function can be called prior to creating a surface.
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.
In addition to the surface capabilities as obtained by surface queries below, swapchain images are also subject to ordinary image creation limits as reported by vkGetPhysicalDeviceImageFormatProperties. As an application is instructed by the appropriate Valid Usage sections, both the surface capabilities and the image creation limits have to be satisfied whenever swapchain images are created. |
Surface Capabilities
To query the basic capabilities of a surface, needed in order to create a swapchain, call:
// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfaceCapabilitiesKHR(
VkPhysicalDevice physicalDevice,
VkSurfaceKHR surface,
VkSurfaceCapabilitiesKHR* pSurfaceCapabilities);
-
physicalDevice
is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
surface
is the surface that will be associated with the swapchain. -
pSurfaceCapabilities
is a pointer to a VkSurfaceCapabilitiesKHR structure in which the capabilities are returned.
The VkSurfaceCapabilitiesKHR
structure is defined as:
// Provided by VK_KHR_surface
typedef struct VkSurfaceCapabilitiesKHR {
uint32_t minImageCount;
uint32_t maxImageCount;
VkExtent2D currentExtent;
VkExtent2D minImageExtent;
VkExtent2D maxImageExtent;
uint32_t maxImageArrayLayers;
VkSurfaceTransformFlagsKHR supportedTransforms;
VkSurfaceTransformFlagBitsKHR currentTransform;
VkCompositeAlphaFlagsKHR supportedCompositeAlpha;
VkImageUsageFlags supportedUsageFlags;
} VkSurfaceCapabilitiesKHR;
-
minImageCount
is the minimum number of images the specified device supports for a swapchain created for the surface, and will be at least one. -
maxImageCount
is the maximum number of images the specified device supports for a swapchain created for the surface, and will be either 0, or greater than or equal 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_FIFO_LATEST_READY_EXT
,VK_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. Implementations may support additional usages.
Supported usage flags of a presentable image when using
|
Formulas such as min(N, |
To query the basic capabilities of a surface defined by the core or extensions, call:
// Provided by VK_KHR_get_surface_capabilities2
VkResult vkGetPhysicalDeviceSurfaceCapabilities2KHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceSurfaceInfo2KHR* pSurfaceInfo,
VkSurfaceCapabilities2KHR* pSurfaceCapabilities);
-
physicalDevice
is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
pSurfaceInfo
is a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR. -
pSurfaceCapabilities
is a pointer to a 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:
// Provided by VK_KHR_get_surface_capabilities2
typedef struct VkPhysicalDeviceSurfaceInfo2KHR {
VkStructureType sType;
const void* pNext;
VkSurfaceKHR surface;
} VkPhysicalDeviceSurfaceInfo2KHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
surface
is the surface that will be associated with the swapchain.
The members of VkPhysicalDeviceSurfaceInfo2KHR
correspond to the
arguments to vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with
sType
and pNext
added for extensibility.
Additional capabilities of a surface may be available to swapchains created
with different full-screen exclusive settings - particularly if exclusive
full-screen access is application controlled.
These additional capabilities can be queried by adding a
VkSurfaceFullScreenExclusiveInfoEXT structure to the pNext
chain
of this structure when used to query surface properties.
Additionally, for Win32 surfaces with application controlled exclusive
full-screen access, chaining a
VkSurfaceFullScreenExclusiveWin32InfoEXT structure may also report
additional surface capabilities.
These additional capabilities only apply to swapchains created with the same
parameters included in the pNext
chain of
VkSwapchainCreateInfoKHR.
If the pNext
chain of VkSwapchainCreateInfoKHR includes a
VkSurfaceFullScreenExclusiveInfoEXT
structure, then that structure
specifies the application’s preferred full-screen transition behavior.
The VkSurfaceFullScreenExclusiveInfoEXT
structure is defined as:
// Provided by VK_EXT_full_screen_exclusive
typedef struct VkSurfaceFullScreenExclusiveInfoEXT {
VkStructureType sType;
void* pNext;
VkFullScreenExclusiveEXT fullScreenExclusive;
} VkSurfaceFullScreenExclusiveInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
fullScreenExclusive
is a VkFullScreenExclusiveEXT value specifying the preferred full-screen transition behavior.
If this structure is not present, fullScreenExclusive
is considered to
be VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT
.
Possible values of
VkSurfaceFullScreenExclusiveInfoEXT
::fullScreenExclusive
are:
// Provided by VK_EXT_full_screen_exclusive
typedef enum VkFullScreenExclusiveEXT {
VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT = 0,
VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT = 1,
VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT = 2,
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT = 3,
} VkFullScreenExclusiveEXT;
-
VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT
indicates the implementation should determine the appropriate full-screen method by whatever means it deems appropriate. -
VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT
indicates the implementation may use full-screen exclusive mechanisms when available. Such mechanisms may result in better performance and/or the availability of different presentation capabilities, but may require a more disruptive transition during swapchain initialization, first presentation and/or destruction. -
VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT
indicates the implementation should avoid using full-screen mechanisms which rely on disruptive transitions. -
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT
indicates the application will manage full-screen exclusive mode by using the vkAcquireFullScreenExclusiveModeEXT and vkReleaseFullScreenExclusiveModeEXT commands.
The VkSurfaceFullScreenExclusiveWin32InfoEXT
structure is defined as:
// Provided by VK_KHR_win32_surface with VK_EXT_full_screen_exclusive
typedef struct VkSurfaceFullScreenExclusiveWin32InfoEXT {
VkStructureType sType;
const void* pNext;
HMONITOR hmonitor;
} VkSurfaceFullScreenExclusiveWin32InfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
hmonitor
is the Win32HMONITOR
handle identifying the display to create the surface with.
If |
It is the responsibility of the application to change the display settings of the targeted Win32 display using the appropriate platform APIs. Such changes may alter the surface capabilities reported for the created surface. |
The VkSurfaceCapabilities2KHR
structure is defined as:
// Provided by VK_KHR_get_surface_capabilities2
typedef struct VkSurfaceCapabilities2KHR {
VkStructureType sType;
void* pNext;
VkSurfaceCapabilitiesKHR surfaceCapabilities;
} VkSurfaceCapabilities2KHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
surfaceCapabilities
is a VkSurfaceCapabilitiesKHR structure describing the capabilities of the specified surface.
If the VK_GOOGLE_surfaceless_query
extension is enabled and
VkPhysicalDeviceSurfaceInfo2KHR::surface
in the
vkGetPhysicalDeviceSurfaceCapabilities2KHR call is
VK_NULL_HANDLE, the values returned in minImageCount
,
maxImageCount
, currentExtent
, and currentTransform
will
not reflect that of any surface and will instead be as such:
-
minImageCount
andmaxImageCount
will be 0xFFFFFFFF -
currentExtent
will be (0xFFFFFFFF, 0xFFFFFFFF) -
currentTransform
will beVK_SURFACE_TRANSFORM_INHERIT_BIT_KHR
An application queries if a protected VkSurfaceKHR is displayable on a
specific windowing system using VkSurfaceProtectedCapabilitiesKHR
,
which can be passed in pNext
parameter of
VkSurfaceCapabilities2KHR
.
The VkSurfaceProtectedCapabilitiesKHR
structure is defined as:
// Provided by VK_KHR_surface_protected_capabilities
typedef struct VkSurfaceProtectedCapabilitiesKHR {
VkStructureType sType;
const void* pNext;
VkBool32 supportsProtected;
} VkSurfaceProtectedCapabilitiesKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
supportsProtected
specifies whether a protected swapchain created from VkPhysicalDeviceSurfaceInfo2KHR::surface
for a particular windowing system can be displayed on screen or not. IfsupportsProtected
isVK_TRUE
, then creation of swapchains with theVK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR
flag set must be supported forsurface
.
If the VK_GOOGLE_surfaceless_query
extension is enabled, the value
returned in supportsProtected
will be identical for every valid
surface created on this physical device, and so in the
vkGetPhysicalDeviceSurfaceCapabilities2KHR call,
VkPhysicalDeviceSurfaceInfo2KHR::surface
can be
VK_NULL_HANDLE.
In that case, the contents of
VkSurfaceCapabilities2KHR::surfaceCapabilities
as well as any
other struct chained to it will be undefined.
The VkSurfacePresentScalingCapabilitiesEXT
structure is defined as:
// Provided by VK_EXT_surface_maintenance1
typedef struct VkSurfacePresentScalingCapabilitiesEXT {
VkStructureType sType;
void* pNext;
VkPresentScalingFlagsEXT supportedPresentScaling;
VkPresentGravityFlagsEXT supportedPresentGravityX;
VkPresentGravityFlagsEXT supportedPresentGravityY;
VkExtent2D minScaledImageExtent;
VkExtent2D maxScaledImageExtent;
} VkSurfacePresentScalingCapabilitiesEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
supportedPresentScaling
is a bitmask of VkPresentScalingFlagBitsEXT representing the scaling methods supported by the surface, or0
if application-defined scaling is not supported. -
supportedPresentGravityX
is a bitmask of VkPresentGravityFlagBitsEXT representing the X-axis pixel gravity supported by the surface, or0
if Vulkan-defined pixel gravity is not supported for the X axis. -
supportedPresentGravityY
is a bitmask of VkPresentGravityFlagBitsEXT representing the Y-axis pixel gravity supported by the surface, or0
if Vulkan-defined pixel gravity is not supported for the Y axis. -
minScaledImageExtent
contains the smallest valid swapchain extent for the surface on the specified device when one of the scaling methods specified insupportedPresentScaling
is used, or the special value (0xFFFFFFFF, 0xFFFFFFFF) indicating that the surface size will be determined by the extent of a swapchain targeting the surface. Thewidth
andheight
of the extent will each be smaller than or equal to the correspondingwidth
andheight
of VkSurfaceCapabilitiesKHR::minImageExtent
. -
maxScaledImageExtent
contains the largest valid swapchain extent for the surface on the specified device when one of the scaling methods specified insupportedPresentScaling
is used, or the special value described above forminScaledImageExtent
. Thewidth
andheight
of the extent will each be greater than or equal to the correspondingwidth
andheight
of VkSurfaceCapabilitiesKHR::maxImageExtent
.
Before creating a swapchain whose scaling mode can be specified through the
use of VkSwapchainPresentScalingCreateInfoEXT, obtain the set of
supported scaling modes by including a VkSurfacePresentModeEXT
structure in the pNext
chain of VkPhysicalDeviceSurfaceInfo2KHR
when calling vkGetPhysicalDeviceSurfaceCapabilities2KHR.
The implementation must return the same values in
VkSurfacePresentScalingCapabilitiesEXT
for any of the compatible
present modes as obtained through
VkSurfacePresentModeCompatibilityEXT.
Bits which may be set in
VkSurfacePresentScalingCapabilitiesEXT::supportedPresentScaling
,
specifying scaling modes supported by the surface, are:
// Provided by VK_EXT_surface_maintenance1
typedef enum VkPresentScalingFlagBitsEXT {
VK_PRESENT_SCALING_ONE_TO_ONE_BIT_EXT = 0x00000001,
VK_PRESENT_SCALING_ASPECT_RATIO_STRETCH_BIT_EXT = 0x00000002,
VK_PRESENT_SCALING_STRETCH_BIT_EXT = 0x00000004,
} VkPresentScalingFlagBitsEXT;
-
VK_PRESENT_SCALING_ONE_TO_ONE_BIT_EXT
specifies that no scaling occurs, and pixels in the swapchain image are mapped to one and only one pixel in the surface. The mapping between pixels is defined by the chosen presentation gravity. -
VK_PRESENT_SCALING_ASPECT_RATIO_STRETCH_BIT_EXT
specifies that the swapchain image will be minified or magnified such that at least one of the resulting width or height is equal to the corresponding surface dimension, and the other resulting dimension is less than or equal to the corresponding surface dimension, with the aspect ratio of the resulting image being identical to that of the original swapchain image. -
VK_PRESENT_SCALING_STRETCH_BIT_EXT
specifies that the swapchain image will be minified or magnified such that the resulting image dimensions are equal to those of the surface.
// Provided by VK_EXT_surface_maintenance1
typedef VkFlags VkPresentScalingFlagsEXT;
VkPresentScalingFlagsEXT
is a bitmask type for setting a mask of zero
or more VkPresentScalingFlagBitsEXT.
Bits which may be set in the
VkSurfacePresentScalingCapabilitiesEXT::supportedPresentGravityX
or supportedPresentGravityY
fields, specifying the gravity of
presented pixels supported by the surface, are:
// Provided by VK_EXT_surface_maintenance1
typedef enum VkPresentGravityFlagBitsEXT {
VK_PRESENT_GRAVITY_MIN_BIT_EXT = 0x00000001,
VK_PRESENT_GRAVITY_MAX_BIT_EXT = 0x00000002,
VK_PRESENT_GRAVITY_CENTERED_BIT_EXT = 0x00000004,
} VkPresentGravityFlagBitsEXT;
-
VK_PRESENT_GRAVITY_MIN_BIT_EXT
means that the pixels will gravitate towards the top or left side of the surface. -
VK_PRESENT_GRAVITY_MAX_BIT_EXT
means that the pixels will gravitate towards the bottom or right side of the surface. -
VK_PRESENT_GRAVITY_CENTERED_BIT_EXT
means that the pixels will be centered in the surface.
If the value in VkSurfaceCapabilitiesKHR::currentTransform
is
not VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
, it is
implementation-defined whether the gravity configuration applies to the
presented image before or after transformation.
// Provided by VK_EXT_surface_maintenance1
typedef VkFlags VkPresentGravityFlagsEXT;
VkPresentGravityFlagsEXT
is a bitmask type for setting a mask of zero
or more VkPresentGravityFlagBitsEXT.
The VkSurfacePresentModeEXT
structure is defined as:
// Provided by VK_EXT_surface_maintenance1
typedef struct VkSurfacePresentModeEXT {
VkStructureType sType;
void* pNext;
VkPresentModeKHR presentMode;
} VkSurfacePresentModeEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
presentMode
is the presentation mode the swapchain will use.
If the VkSurfacePresentModeEXT
structure is included in the
pNext
chain of VkPhysicalDeviceSurfaceInfo2KHR, the values
returned in VkSurfaceCapabilitiesKHR::minImageCount
,
VkSurfaceCapabilitiesKHR::maxImageCount
,
VkSurfacePresentScalingCapabilitiesEXT::minScaledImageExtent
,
and VkSurfacePresentScalingCapabilitiesEXT::maxScaledImageExtent
are valid only for the specified presentMode
.
If presentMode
is VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
or
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
, the per-present mode
image counts must both be one.
The per-present mode image counts may be less-than or greater-than the
image counts returned when VkSurfacePresentModeEXT
is not provided.
If VkSwapchainPresentModesCreateInfoEXT is provided to swapchain
creation, the requirements for forward progress may be less strict.
For example, a FIFO swapchain might only require 2 images to guarantee
forward progress, but a MAILBOX one might require 4.
Without the per-present image counts, such an implementation would have to
return 4 in VkSurfaceCapabilitiesKHR:: VkSwapchainPresentModesCreateInfoEXT is required for the specification to be backwards compatible with applications that do not know about, or make use of this feature. |
The VkSurfacePresentModeCompatibilityEXT
structure is defined as:
// Provided by VK_EXT_surface_maintenance1
typedef struct VkSurfacePresentModeCompatibilityEXT {
VkStructureType sType;
void* pNext;
uint32_t presentModeCount;
VkPresentModeKHR* pPresentModes;
} VkSurfacePresentModeCompatibilityEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
presentModeCount
is an integer related to the number of present modes available or queried, as described below. -
pPresentModes
is a pointer to an array of VkPresentModeKHR in which present modes compatible with a given present mode are returned.
If pPresentModes
is NULL
, then the number of present modes that are
compatible with the one specified in VkSurfacePresentModeEXT is
returned in presentModeCount
.
Otherwise, presentModeCount
must point to a variable set by the
application 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 presentModeCount
is less than the number of compatible
present modes that are supported, at most presentModeCount
values will
be written to pPresentModes
.
The implementation must include the present mode passed to
VkSurfacePresentModeEXT in pPresentModes
, unless
presentModeCount
is zero.
Before creating a swapchain whose present modes can be modified through the
use of VkSwapchainPresentModesCreateInfoEXT, obtain the set of present
modes compatible with a given initial present mode by including a
VkSurfacePresentModeEXT structure in the pNext
chain of
VkPhysicalDeviceSurfaceInfo2KHR when calling
vkGetPhysicalDeviceSurfaceCapabilities2KHR.
The VkSharedPresentSurfaceCapabilitiesKHR
structure is defined as:
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
sharedPresentSupportedUsageFlags
is a bitmask of VkImageUsageFlagBits representing the ways the application can use the shared presentable image from a swapchain created with VkPresentModeKHR set 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.
The VkDisplayNativeHdrSurfaceCapabilitiesAMD
structure is defined as:
// Provided by VK_AMD_display_native_hdr
typedef struct VkDisplayNativeHdrSurfaceCapabilitiesAMD {
VkStructureType sType;
void* pNext;
VkBool32 localDimmingSupport;
} VkDisplayNativeHdrSurfaceCapabilitiesAMD;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
localDimmingSupport
specifies whether the surface supports local dimming. If this isVK_TRUE
, VkSwapchainDisplayNativeHdrCreateInfoAMD can be used to explicitly enable or disable local dimming for the surface. Local dimming may also be overridden by vkSetLocalDimmingAMD during the lifetime of the swapchain.
The VkSurfaceCapabilitiesFullScreenExclusiveEXT
structure is defined
as:
// Provided by VK_EXT_full_screen_exclusive
typedef struct VkSurfaceCapabilitiesFullScreenExclusiveEXT {
VkStructureType sType;
void* pNext;
VkBool32 fullScreenExclusiveSupported;
} VkSurfaceCapabilitiesFullScreenExclusiveEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
fullScreenExclusiveControlSupported
is a boolean describing whether the surface is able to make use of exclusive full-screen access.
This structure can be included in the pNext
chain of
VkSurfaceCapabilities2KHR to determine support for exclusive
full-screen access.
If fullScreenExclusiveSupported
is VK_FALSE
, it indicates that
exclusive full-screen access is not obtainable for this surface.
Applications must not attempt to create swapchains with
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT
set if
fullScreenExclusiveSupported
is VK_FALSE
.
The VkSurfaceCapabilitiesPresentBarrierNV
structure is defined as:
// Provided by VK_NV_present_barrier
typedef struct VkSurfaceCapabilitiesPresentBarrierNV {
VkStructureType sType;
void* pNext;
VkBool32 presentBarrierSupported;
} VkSurfaceCapabilitiesPresentBarrierNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
presentBarrierSupported
is a boolean describing whether the surface is able to make use of the present barrier feature.
This structure can be included in the pNext
chain of
VkSurfaceCapabilities2KHR to determine support for present barrier
access.
If presentBarrierSupported
is VK_FALSE
, it indicates that the
present barrier feature is not obtainable for this surface.
To query the basic capabilities of a surface, needed in order to create a swapchain, call:
// Provided by VK_EXT_display_surface_counter
VkResult vkGetPhysicalDeviceSurfaceCapabilities2EXT(
VkPhysicalDevice physicalDevice,
VkSurfaceKHR surface,
VkSurfaceCapabilities2EXT* pSurfaceCapabilities);
-
physicalDevice
is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
surface
is the surface that will be associated with the swapchain. -
pSurfaceCapabilities
is a pointer to a VkSurfaceCapabilities2EXT structure in which the capabilities are returned.
vkGetPhysicalDeviceSurfaceCapabilities2EXT
behaves similarly to
vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to return
extended information by adding extending structures to the pNext
chain
of its pSurfaceCapabilities
parameter.
The VkSurfaceCapabilities2EXT
structure is defined as:
// Provided by VK_EXT_display_surface_counter
typedef struct VkSurfaceCapabilities2EXT {
VkStructureType sType;
void* pNext;
uint32_t minImageCount;
uint32_t maxImageCount;
VkExtent2D currentExtent;
VkExtent2D minImageExtent;
VkExtent2D maxImageExtent;
uint32_t maxImageArrayLayers;
VkSurfaceTransformFlagsKHR supportedTransforms;
VkSurfaceTransformFlagBitsKHR currentTransform;
VkCompositeAlphaFlagsKHR supportedCompositeAlpha;
VkImageUsageFlags supportedUsageFlags;
VkSurfaceCounterFlagsEXT supportedSurfaceCounters;
} VkSurfaceCapabilities2EXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
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_FIFO_LATEST_READY_EXT
,VK_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. Implementations may support additional usages. -
supportedSurfaceCounters
is a bitmask of VkSurfaceCounterFlagBitsEXT indicating the supported surface counter types.
Bits which can be set in
VkSurfaceCapabilities2EXT::supportedSurfaceCounters
, indicating
supported surface counter types, are:
// Provided by VK_EXT_display_surface_counter
typedef enum VkSurfaceCounterFlagBitsEXT {
VK_SURFACE_COUNTER_VBLANK_BIT_EXT = 0x00000001,
// VK_SURFACE_COUNTER_VBLANK_EXT is a deprecated alias
VK_SURFACE_COUNTER_VBLANK_EXT = VK_SURFACE_COUNTER_VBLANK_BIT_EXT,
} VkSurfaceCounterFlagBitsEXT;
-
VK_SURFACE_COUNTER_VBLANK_BIT_EXT
specifies a counter incrementing once every time a vertical blanking period occurs on the display associated with the surface.
// Provided by VK_EXT_display_surface_counter
typedef VkFlags VkSurfaceCounterFlagsEXT;
VkSurfaceCounterFlagsEXT
is a bitmask type for setting a mask of zero
or more VkSurfaceCounterFlagBitsEXT.
Bits which may be set in
VkSurfaceCapabilitiesKHR::supportedTransforms
indicating the
presentation transforms supported for the surface on the specified device,
and possible values of
VkSurfaceCapabilitiesKHR::currentTransform
indicating the
surface’s current transform relative to the presentation engine’s natural
orientation, are:
// Provided by VK_KHR_surface
typedef enum VkSurfaceTransformFlagBitsKHR {
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR = 0x00000001,
VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR = 0x00000002,
VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR = 0x00000004,
VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR = 0x00000008,
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR = 0x00000010,
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR = 0x00000020,
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR = 0x00000040,
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR = 0x00000080,
VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR = 0x00000100,
} VkSurfaceTransformFlagBitsKHR;
-
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
specifies that image content is presented without being transformed. -
VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
specifies that image content is rotated 90 degrees clockwise. -
VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
specifies that image content is rotated 180 degrees clockwise. -
VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
specifies that image content is rotated 270 degrees clockwise. -
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR
specifies that image content is mirrored horizontally. -
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR
specifies that image content is mirrored horizontally, then rotated 90 degrees clockwise. -
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR
specifies that image content is mirrored horizontally, then rotated 180 degrees clockwise. -
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR
specifies that image content is mirrored horizontally, then rotated 270 degrees clockwise. -
VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR
specifies that the presentation transform is not specified, and is instead determined by platform-specific considerations and mechanisms outside Vulkan.
// Provided by VK_KHR_display
typedef VkFlags VkSurfaceTransformFlagsKHR;
VkSurfaceTransformFlagsKHR
is a bitmask type for setting a mask of
zero or more VkSurfaceTransformFlagBitsKHR.
The supportedCompositeAlpha
member is of type
VkCompositeAlphaFlagBitsKHR, containing the following values:
// Provided by VK_KHR_surface
typedef enum VkCompositeAlphaFlagBitsKHR {
VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR = 0x00000001,
VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR = 0x00000002,
VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR = 0x00000004,
VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR = 0x00000008,
} VkCompositeAlphaFlagBitsKHR;
These values are described as follows:
-
VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR
: The alpha component, 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 component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are expected to already be multiplied by the alpha component by the application. -
VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR
: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are not expected to already be multiplied by the alpha component by the application; instead, the compositor will multiply the non-alpha components of the image by the alpha component during compositing. -
VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR
: The way in which the presentation engine treats the alpha component in the images is unknown to the Vulkan API. Instead, the application is responsible for setting the composite alpha blending mode using native window system commands. If the application does not set the blending mode using native window system commands, then a platform-specific default will be used.
// Provided by VK_KHR_surface
typedef VkFlags VkCompositeAlphaFlagsKHR;
VkCompositeAlphaFlagsKHR
is a bitmask type for setting a mask of zero
or more VkCompositeAlphaFlagBitsKHR.
Surface Format Support
To query the supported swapchain format-color space pairs for a surface, call:
// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfaceFormatsKHR(
VkPhysicalDevice physicalDevice,
VkSurfaceKHR surface,
uint32_t* pSurfaceFormatCount,
VkSurfaceFormatKHR* pSurfaceFormats);
-
physicalDevice
is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
surface
is the surface that will be associated with the swapchain. -
pSurfaceFormatCount
is a pointer to an integer related to the number of format pairs available or queried, as described below. -
pSurfaceFormats
is 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
.
Otherwise, pSurfaceFormatCount
must point to a variable set by the
application 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, and VK_INCOMPLETE
will be returned instead of
VK_SUCCESS
, to indicate that not all the available format pairs were
returned.
The number of format pairs supported must be greater than or equal to 1.
pSurfaceFormats
must not contain an entry whose value for
format
is VK_FORMAT_UNDEFINED
.
If pSurfaceFormats
includes an entry whose value for colorSpace
is VK_COLOR_SPACE_SRGB_NONLINEAR_KHR
and whose value for format
is a UNORM (or SRGB) format and the corresponding SRGB (or UNORM) format is
a color renderable format for VK_IMAGE_TILING_OPTIMAL
, then
pSurfaceFormats
must also contain an entry with the same value for
colorSpace
and format
equal to the corresponding SRGB (or UNORM)
format.
If the VK_GOOGLE_surfaceless_query
extension is enabled, the values
returned in pSurfaceFormats
will be identical for every valid surface
created on this physical device, and so surface
can be
VK_NULL_HANDLE.
The VkSurfaceFormatKHR
structure is defined as:
// Provided by VK_KHR_surface
typedef struct VkSurfaceFormatKHR {
VkFormat format;
VkColorSpaceKHR colorSpace;
} VkSurfaceFormatKHR;
-
format
is a VkFormat that is compatible with the specified surface. -
colorSpace
is a presentation VkColorSpaceKHR that is compatible with the surface.
To query the supported swapchain format tuples for a surface, call:
// Provided by VK_KHR_get_surface_capabilities2
VkResult vkGetPhysicalDeviceSurfaceFormats2KHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceSurfaceInfo2KHR* pSurfaceInfo,
uint32_t* pSurfaceFormatCount,
VkSurfaceFormat2KHR* pSurfaceFormats);
-
physicalDevice
is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
pSurfaceInfo
is a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR. -
pSurfaceFormatCount
is a pointer to an integer related to the number of format tuples available or queried, as described below. -
pSurfaceFormats
is eitherNULL
or a pointer to an array of VkSurfaceFormat2KHR structures.
vkGetPhysicalDeviceSurfaceFormats2KHR behaves similarly to
vkGetPhysicalDeviceSurfaceFormatsKHR, with the ability to be extended
via pNext
chains.
If pSurfaceFormats
is NULL
, then the number of format tuples
supported for the given surface
is returned in
pSurfaceFormatCount
.
Otherwise, pSurfaceFormatCount
must point to a variable set by the
application 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, and 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:
// Provided by VK_KHR_get_surface_capabilities2
typedef struct VkSurfaceFormat2KHR {
VkStructureType sType;
void* pNext;
VkSurfaceFormatKHR surfaceFormat;
} VkSurfaceFormat2KHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
surfaceFormat
is a VkSurfaceFormatKHR structure describing a format-color space pair that is compatible with the specified surface.
If the imageCompressionControlSwapchain
feature is supported and a
VkImageCompressionPropertiesEXT structure is included in the
pNext
chain of this structure, then it will be filled with the
compression properties that are supported for the surfaceFormat
.
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
transfer functions indicating the mapping between the image data and the
colorimetry with respect to the given color space.
Possible values of VkSurfaceFormatKHR::colorSpace
, specifying
the color spaces that a presentation engine can accept, are:
// Provided by VK_KHR_surface
typedef enum VkColorSpaceKHR {
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR = 0,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT = 1000104001,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT = 1000104002,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT = 1000104003,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT = 1000104004,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_BT709_LINEAR_EXT = 1000104005,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_BT709_NONLINEAR_EXT = 1000104006,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_BT2020_LINEAR_EXT = 1000104007,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_HDR10_ST2084_EXT = 1000104008,
// Provided by VK_EXT_swapchain_colorspace
// VK_COLOR_SPACE_DOLBYVISION_EXT is deprecated, but no reason was given in the API XML
VK_COLOR_SPACE_DOLBYVISION_EXT = 1000104009,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_HDR10_HLG_EXT = 1000104010,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT = 1000104011,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT = 1000104012,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_PASS_THROUGH_EXT = 1000104013,
// Provided by VK_EXT_swapchain_colorspace
VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT = 1000104014,
// Provided by VK_AMD_display_native_hdr
VK_COLOR_SPACE_DISPLAY_NATIVE_AMD = 1000213000,
// VK_COLORSPACE_SRGB_NONLINEAR_KHR is a deprecated alias
VK_COLORSPACE_SRGB_NONLINEAR_KHR = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR,
// Provided by VK_EXT_swapchain_colorspace
// VK_COLOR_SPACE_DCI_P3_LINEAR_EXT is a deprecated alias
VK_COLOR_SPACE_DCI_P3_LINEAR_EXT = VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT,
} VkColorSpaceKHR;
-
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR
specifies support for the images in sRGB color space, encoded according to the sRGB specification. -
VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT
specifies support for the images in Display-P3 color space, encoded using a Display-P3 transfer function. -
VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT
specifies support for the images in extended sRGB color space, encoded using a linear transfer function. -
VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT
specifies support for the images in extended sRGB color space, encoded according to the scRGB specification. -
VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT
specifies support for the images in Display-P3 color space, encoded using a linear transfer function. -
VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT
specifies support for the images in DCI-P3 color space, encoded according to the DCI-P3 specification. Note that values in such an image are interpreted as XYZ encoded color data by the presentation engine. -
VK_COLOR_SPACE_BT709_LINEAR_EXT
specifies support for the images in BT709 color space, encoded using a linear transfer function. -
VK_COLOR_SPACE_BT709_NONLINEAR_EXT
specifies support for the images in BT709 color space, encoded according to the BT709 specification. -
VK_COLOR_SPACE_BT2020_LINEAR_EXT
specifies support for the images in BT2020 color space, encoded using a linear transfer function. -
VK_COLOR_SPACE_HDR10_ST2084_EXT
specifies support for the images in HDR10 (BT2020) color space, encoded according to SMPTE ST2084 Perceptual Quantizer (PQ) specification. -
VK_COLOR_SPACE_HDR10_HLG_EXT
specifies support for the images in HDR10 (BT2020) color space, encoded according to the Hybrid Log Gamma (HLG) specification. -
VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT
specifies support for images in Adobe RGB color space, encoded using a linear transfer function. -
VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT
specifies support for the images in Adobe RGB color space, encoded according to the Adobe RGB specification (approximately Gamma 2.2). -
VK_COLOR_SPACE_PASS_THROUGH_EXT
specifies that color components are used “as is”. This is intended to allow applications to supply data for color spaces not described here. -
VK_COLOR_SPACE_DISPLAY_NATIVE_AMD
specifies support for the display’s native color space. This matches the color space expectations of AMD’s FreeSync2 standard, for displays supporting it.
In the initial release of the |
In older versions of this extension
|
In older versions of the |
Note
For a traditional “Linear” or non-gamma transfer function color space use
|
The presentation engine interprets the pixel values of the R, G, and B components as having been encoded using an appropriate transfer function. Applications should ensure that the appropriate transfer function has been applied. Textures Output Format Conversion requires that all implementations implicitly apply the sRGB EOTF-1 on R, G, and B components when shaders write to an sRGB pixel format image, which is useful for sRGB color spaces. For sRGB color spaces with other pixel formats, or other non-linear color spaces, applications can apply the transfer function explicitly in a shader. The A channel is always interpreted as linearly encoded.
This extension defines enums for VkColorSpaceKHR that correspond to the following color spaces:
Name | Red Primary | Green Primary | Blue Primary | White-point | Transfer function |
---|---|---|---|---|---|
DCI-P3 |
1.000, 0.000 |
0.000, 1.000 |
0.000, 0.000 |
0.3333, 0.3333 |
DCI P3 |
Display-P3 |
0.680, 0.320 |
0.265, 0.690 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
Display-P3 |
BT709 |
0.640, 0.330 |
0.300, 0.600 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
BT709 |
sRGB |
0.640, 0.330 |
0.300, 0.600 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
sRGB |
extended sRGB |
0.640, 0.330 |
0.300, 0.600 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
scRGB |
HDR10_ST2084 |
0.708, 0.292 |
0.170, 0.797 |
0.131, 0.046 |
0.3127, 0.3290 (D65) |
ST2084 PQ |
HDR10_HLG |
0.708, 0.292 |
0.170, 0.797 |
0.131, 0.046 |
0.3127, 0.3290 (D65) |
HLG |
Adobe RGB |
0.640, 0.330 |
0.210, 0.710 |
0.150, 0.060 |
0.3127, 0.3290 (D65) |
Adobe RGB |
The transfer functions are described in the “Transfer Functions” chapter of the Khronos Data Format Specification.
Except Display-P3 OETF, which is:
where L is the linear value of a color component and E is the encoded value (as stored in the image in memory).
For most uses, the sRGB OETF is equivalent. |
Surface Presentation Mode Support
To query the supported presentation modes for a surface, call:
// Provided by VK_KHR_surface
VkResult vkGetPhysicalDeviceSurfacePresentModesKHR(
VkPhysicalDevice physicalDevice,
VkSurfaceKHR surface,
uint32_t* pPresentModeCount,
VkPresentModeKHR* pPresentModes);
-
physicalDevice
is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
surface
is the surface that will be associated with the swapchain. -
pPresentModeCount
is a pointer to an integer related to the number of presentation modes available or queried, as described below. -
pPresentModes
is 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
application 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, and VK_INCOMPLETE
will be returned instead of
VK_SUCCESS
, to indicate that not all the available modes were
returned.
If the VK_GOOGLE_surfaceless_query
extension is enabled and
surface
is VK_NULL_HANDLE, the values returned in
pPresentModes
will only indicate support for
VK_PRESENT_MODE_FIFO_KHR
,
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
, and
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
.
To query support for any other present mode, a valid handle must be
provided in surface
.
Alternatively, to query the supported presentation modes for a surface combined with select other fixed swapchain creation parameters, call:
// Provided by VK_EXT_full_screen_exclusive
VkResult vkGetPhysicalDeviceSurfacePresentModes2EXT(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceSurfaceInfo2KHR* pSurfaceInfo,
uint32_t* pPresentModeCount,
VkPresentModeKHR* pPresentModes);
-
physicalDevice
is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR. -
pSurfaceInfo
is a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR. -
pPresentModeCount
is a pointer to an integer related to the number of presentation modes available or queried, as described below. -
pPresentModes
is eitherNULL
or a pointer to an array of VkPresentModeKHR values, indicating the supported presentation modes.
vkGetPhysicalDeviceSurfacePresentModes2EXT
behaves similarly to
vkGetPhysicalDeviceSurfacePresentModesKHR, with the ability to specify
extended inputs via chained input structures.
Possible values of elements of the
vkGetPhysicalDeviceSurfacePresentModesKHR::pPresentModes
array,
indicating the supported presentation modes for a surface, are:
// Provided by VK_KHR_surface
typedef enum VkPresentModeKHR {
VK_PRESENT_MODE_IMMEDIATE_KHR = 0,
VK_PRESENT_MODE_MAILBOX_KHR = 1,
VK_PRESENT_MODE_FIFO_KHR = 2,
VK_PRESENT_MODE_FIFO_RELAXED_KHR = 3,
// Provided by VK_KHR_shared_presentable_image
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR = 1000111000,
// Provided by VK_KHR_shared_presentable_image
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR = 1000111001,
// Provided by VK_EXT_present_mode_fifo_latest_ready
VK_PRESENT_MODE_FIFO_LATEST_READY_EXT = 1000361000,
} 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 reuse 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_FIFO_LATEST_READY_EXT
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. At each vertical blanking period, the presentation engine dequeues all successive requests that are ready to be presented from the beginning of the queue. If usingVK_GOOGLE_display_timing
to provide a target present time, the presentation engine will check the specified time for each image. If the target present time is less-than or equal-to the current time, the presentation engine will dequeue the image and check the next one. The image of the last dequeued request will be presented. The other dequeued requests will be dropped. -
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:: |
|
VkSurfaceCapabilitiesKHR:: |
|
VkSharedPresentSurfaceCapabilitiesKHR:: |
|
VkSharedPresentSurfaceCapabilitiesKHR:: |
For reference, the mode indicated by |
Full Screen Exclusive Control
Swapchains created with fullScreenExclusive
set to
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT
must acquire and
release exclusive full-screen access explicitly, using the following
commands.
To acquire exclusive full-screen access for a swapchain, call:
// Provided by VK_EXT_full_screen_exclusive
VkResult vkAcquireFullScreenExclusiveModeEXT(
VkDevice device,
VkSwapchainKHR swapchain);
-
device
is the device associated withswapchain
. -
swapchain
is the swapchain to acquire exclusive full-screen access for.
A return value of VK_SUCCESS
indicates that the swapchain
successfully acquired exclusive full-screen access.
The swapchain will retain this exclusivity until either the application
releases exclusive full-screen access with
vkReleaseFullScreenExclusiveModeEXT, destroys the swapchain, or if any
of the swapchain commands return
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
indicating that the mode
was lost because of platform-specific changes.
If the swapchain was unable to acquire exclusive full-screen access to the
display then VK_ERROR_INITIALIZATION_FAILED
is returned.
An application can attempt to acquire exclusive full-screen access again
for the same swapchain even if this command fails, or if
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
has been returned by a
swapchain command.
To release exclusive full-screen access from a swapchain, call:
// Provided by VK_EXT_full_screen_exclusive
VkResult vkReleaseFullScreenExclusiveModeEXT(
VkDevice device,
VkSwapchainKHR swapchain);
-
device
is the device associated withswapchain
. -
swapchain
is the swapchain to release exclusive full-screen access from.
Applications will not be able to present to |
Device Group Queries
A logical device that represents multiple physical devices may support presenting from images on more than one physical device, or combining images from multiple physical devices.
To query these capabilities, call:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
VkResult vkGetDeviceGroupPresentCapabilitiesKHR(
VkDevice device,
VkDeviceGroupPresentCapabilitiesKHR* pDeviceGroupPresentCapabilities);
-
device
is the logical device. -
pDeviceGroupPresentCapabilities
is a pointer to a VkDeviceGroupPresentCapabilitiesKHR structure in which the device’s capabilities are returned.
The VkDeviceGroupPresentCapabilitiesKHR
structure is defined as:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
typedef struct VkDeviceGroupPresentCapabilitiesKHR {
VkStructureType sType;
void* pNext;
uint32_t presentMask[VK_MAX_DEVICE_GROUP_SIZE];
VkDeviceGroupPresentModeFlagsKHR modes;
} VkDeviceGroupPresentCapabilitiesKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
presentMask
is an array ofVK_MAX_DEVICE_GROUP_SIZE
uint32_t
masks, where the mask at element i is non-zero if physical device i has a presentation engine, and where bit j is set in element i if physical device i can present swapchain images from physical device j. If element i is non-zero, then bit i must be set. -
modes
is a bitmask of VkDeviceGroupPresentModeFlagBitsKHR indicating which device group presentation modes are supported.
modes
always has VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR
set.
The present mode flags are also used when presenting an image, in
VkDeviceGroupPresentInfoKHR::mode
.
If a device group only includes a single physical device, then modes
must equal VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR
.
Bits which may be set in
VkDeviceGroupPresentCapabilitiesKHR::modes
, indicating which
device group presentation modes are supported, are:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
typedef enum VkDeviceGroupPresentModeFlagBitsKHR {
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR = 0x00000001,
VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR = 0x00000002,
VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR = 0x00000004,
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR = 0x00000008,
} VkDeviceGroupPresentModeFlagBitsKHR;
-
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR
specifies that any physical device with a presentation engine can present its own swapchain images. -
VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR
specifies that any physical device with a presentation engine can present swapchain images from any physical device in 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.
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
typedef VkFlags VkDeviceGroupPresentModeFlagsKHR;
VkDeviceGroupPresentModeFlagsKHR
is a bitmask type for setting a mask
of zero or more VkDeviceGroupPresentModeFlagBitsKHR.
Some surfaces may not be capable of using all the device group present modes.
To query the supported device group present modes for a particular surface, call:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
VkResult vkGetDeviceGroupSurfacePresentModesKHR(
VkDevice device,
VkSurfaceKHR surface,
VkDeviceGroupPresentModeFlagsKHR* pModes);
-
device
is the logical device. -
surface
is the surface. -
pModes
is a pointer to a VkDeviceGroupPresentModeFlagsKHR in which the supported device group present modes for the surface are returned.
The modes returned by this command are not invariant, and may change in response to the surface being moved, resized, or occluded. These modes must be a subset of the modes returned by vkGetDeviceGroupPresentCapabilitiesKHR.
Alternatively, to query the supported device group presentation modes for a surface combined with select other fixed swapchain creation parameters, call:
// Provided by VK_EXT_full_screen_exclusive with VK_KHR_device_group or VK_VERSION_1_1
VkResult vkGetDeviceGroupSurfacePresentModes2EXT(
VkDevice device,
const VkPhysicalDeviceSurfaceInfo2KHR* pSurfaceInfo,
VkDeviceGroupPresentModeFlagsKHR* pModes);
-
device
is the logical device. -
pSurfaceInfo
is a pointer to a VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface and other fixed parameters that would be consumed by vkCreateSwapchainKHR. -
pModes
is a pointer to a VkDeviceGroupPresentModeFlagsKHR in which the supported device group present modes for the surface are returned.
vkGetDeviceGroupSurfacePresentModes2EXT
behaves similarly to
vkGetDeviceGroupSurfacePresentModesKHR, with the ability to specify
extended inputs via chained input structures.
When using VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR
,
the application may need to know which regions of the surface are used when
presenting locally on each physical device.
Presentation of swapchain images to this surface need only have valid
contents in the regions returned by this command.
To query a set of rectangles used in presentation on the physical device, call:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_surface
VkResult vkGetPhysicalDevicePresentRectanglesKHR(
VkPhysicalDevice physicalDevice,
VkSurfaceKHR surface,
uint32_t* pRectCount,
VkRect2D* pRects);
-
physicalDevice
is the physical device. -
surface
is the surface. -
pRectCount
is a pointer to an integer related to the number of rectangles available or queried, as described below. -
pRects
is 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 application
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, and VK_INCOMPLETE
will be returned instead of VK_SUCCESS
, to indicate that not all the
available rectangles 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.
Display Timing Queries
Traditional game and real-time-animation applications frequently use
VK_PRESENT_MODE_FIFO_KHR
so that presentable images are updated during
the vertical blanking period of a given refresh cycle (RC) of the
presentation engine’s display.
This avoids the visual anomaly known as tearing.
However, synchronizing the presentation of images with the RC does not prevent all forms of visual anomalies. Stuttering occurs when the geometry for each presentable image is not accurately positioned for when that image will be displayed. The geometry may appear to move too little some RCs, and too much for others. Sometimes the animation appears to freeze, when the same image is used for more than one RC.
In order to minimize stuttering, an application needs to correctly position
their geometry for when the presentable image will be displayed to the user.
To accomplish this, applications need various timing information about the
presentation engine’s display.
They need to know when presentable images were actually presented, and when
they could have been presented.
Applications also need to tell the presentation engine to display an image
no sooner than a given time.
This can allow the application’s animation to look smooth to the user, with
no stuttering.
The VK_GOOGLE_display_timing
extension allows an application to
satisfy these needs.
The presentation engine’s display typically refreshes the pixels that are displayed to the user on a periodic basis. The period may be fixed or variable. In many cases, the presentation engine is associated with fixed refresh rate (FRR) display technology, with a fixed refresh rate (RR, e.g. 60Hz). In some cases, the presentation engine is associated with variable refresh rate (VRR) display technology, where each refresh cycle (RC) can vary in length. This extension treats VRR displays as if they are FRR.
To query the duration of a refresh cycle (RC) for the presentation engine’s display, call:
// Provided by VK_GOOGLE_display_timing
VkResult vkGetRefreshCycleDurationGOOGLE(
VkDevice device,
VkSwapchainKHR swapchain,
VkRefreshCycleDurationGOOGLE* pDisplayTimingProperties);
-
device
is the device associated withswapchain
. -
swapchain
is the swapchain to obtain the refresh duration for. -
pDisplayTimingProperties
is a pointer to aVkRefreshCycleDurationGOOGLE
structure.
The VkRefreshCycleDurationGOOGLE
structure is defined as:
// Provided by VK_GOOGLE_display_timing
typedef struct VkRefreshCycleDurationGOOGLE {
uint64_t refreshDuration;
} VkRefreshCycleDurationGOOGLE;
-
refreshDuration
is the number of nanoseconds from the start of one refresh cycle to the next.
The rate at which an application renders and presents new images is known as
the image present rate (IPR, aka frame rate).
The inverse of IPR, or the duration between each image present, is the image
present duration (IPD).
In order to provide a smooth, stutter-free animation, an application will
want its IPD to be a multiple of In order to determine a target IPD for a display (i.e. a multiple of
Adjustments to an application’s IPD may be needed because different views of
an application’s geometry can take different amounts of time to render.
For example, looking at the sky may take less time to render than looking at
multiple, complex items in a room.
In general, it is good to not frequently change IPD, as that can cause
visual anomalies.
Adjustments to a larger IPD because of late images should happen quickly,
but adjustments to a smaller IPD should only happen if the
|
The implementation will maintain a limited amount of history of timing
information about previous presents.
Because of the asynchronous nature of the presentation engine, the timing
information for a given vkQueuePresentKHR command will become
available some time later.
These time values can be asynchronously queried, and will be returned if
available.
All time values are in nanoseconds, relative to a monotonically-increasing
clock (e.g. CLOCK_MONOTONIC
(see clock_gettime(2)) on Android and Linux).
To asynchronously query the presentation engine, for newly-available timing information about one or more previous presents to a given swapchain, call:
// Provided by VK_GOOGLE_display_timing
VkResult vkGetPastPresentationTimingGOOGLE(
VkDevice device,
VkSwapchainKHR swapchain,
uint32_t* pPresentationTimingCount,
VkPastPresentationTimingGOOGLE* pPresentationTimings);
-
device
is the device associated withswapchain
. -
swapchain
is the swapchain to obtain presentation timing information duration for. -
pPresentationTimingCount
is a pointer to an integer related to the number ofVkPastPresentationTimingGOOGLE
structures to query, as described below. -
pPresentationTimings
is eitherNULL
or a pointer to an array ofVkPastPresentationTimingGOOGLE
structures.
If pPresentationTimings
is NULL
, then the number of newly-available
timing records for the given swapchain
is returned in
pPresentationTimingCount
.
Otherwise, pPresentationTimingCount
must point to a variable set by
the user to the number of elements in the pPresentationTimings
array,
and on return the variable is overwritten with the number of structures
actually written to pPresentationTimings
.
If the value of pPresentationTimingCount
is less than the number of
newly-available timing records, at most pPresentationTimingCount
structures will be written, and VK_INCOMPLETE
will be returned instead
of VK_SUCCESS
, to indicate that not all the available timing records
were returned.
The VkPastPresentationTimingGOOGLE
structure is defined as:
// Provided by VK_GOOGLE_display_timing
typedef struct VkPastPresentationTimingGOOGLE {
uint32_t presentID;
uint64_t desiredPresentTime;
uint64_t actualPresentTime;
uint64_t earliestPresentTime;
uint64_t presentMargin;
} VkPastPresentationTimingGOOGLE;
-
presentID
is an application-provided value that was given to a previousvkQueuePresentKHR
command via VkPresentTimeGOOGLE::presentID
(see below). It can be used to uniquely identify a previous present with the vkQueuePresentKHR command. -
desiredPresentTime
is an application-provided value that was given to a previous vkQueuePresentKHR command via VkPresentTimeGOOGLE::desiredPresentTime
. If non-zero, it was used by the application to indicate that an image not be presented any sooner thandesiredPresentTime
. -
actualPresentTime
is the time when the image of theswapchain
was actually displayed. -
earliestPresentTime
is the time when the image of theswapchain
could have been displayed. This may differ fromactualPresentTime
if the application requested that the image be presented no sooner than VkPresentTimeGOOGLE::desiredPresentTime
. -
presentMargin
is an indication of how early thevkQueuePresentKHR
command was processed compared to how soon it needed to be processed, and still be presented atearliestPresentTime
.
The results for a given swapchain
and presentID
are only
returned once from vkGetPastPresentationTimingGOOGLE
.
The application can use the VkPastPresentationTimingGOOGLE
values to
occasionally adjust its timing.
For example, if actualPresentTime
is later than expected (e.g. one
refreshDuration
late), the application may increase its target IPD to
a higher multiple of refreshDuration
(e.g. decrease its frame rate
from 60Hz to 30Hz).
If actualPresentTime
and earliestPresentTime
are consistently
different, and if presentMargin
is consistently large enough, the
application may decrease its target IPD to a smaller multiple of
refreshDuration
(e.g. increase its frame rate from 30Hz to 60Hz).
If actualPresentTime
and earliestPresentTime
are same, and if
presentMargin
is consistently high, the application may delay the
start of its input-render-present loop in order to decrease the latency
between user input and the corresponding present (always leaving some margin
in case a new image takes longer to render than the previous image).
An application that desires its target IPD to always be the same as
refreshDuration
, can also adjust features until
actualPresentTime
is never late and presentMargin
is
satisfactory.
The full VK_GOOGLE_display_timing
extension semantics are described
for swapchains created with VK_PRESENT_MODE_FIFO_KHR
.
For example, non-zero values of
VkPresentTimeGOOGLE
::desiredPresentTime
must be honored, and
vkGetPastPresentationTimingGOOGLE
should return a
VkPastPresentationTimingGOOGLE
structure with valid values for all
images presented with vkQueuePresentKHR
.
The semantics for other present modes are as follows:
-
VK_PRESENT_MODE_IMMEDIATE_KHR
. The presentation engine may ignore non-zero values ofVkPresentTimeGOOGLE
::desiredPresentTime
in favor of presenting immediately. The value ofVkPastPresentationTimingGOOGLE
::earliestPresentTime
must be the same asVkPastPresentationTimingGOOGLE
::actualPresentTime
, which should be when the presentation engine displayed the image. -
VK_PRESENT_MODE_MAILBOX_KHR
. The intention of using this present mode with this extension is to handle cases where an image is presented late, and the next image is presented soon enough to replace it at the next vertical blanking period. For images that are displayed to the user, the value ofVkPastPresentationTimingGOOGLE
::actualPresentTime
must be when the image was displayed. For images that are not displayed to the user,vkGetPastPresentationTimingGOOGLE
may not return aVkPastPresentationTimingGOOGLE
structure, or it may return aVkPastPresentationTimingGOOGLE
structure with the value of zero for bothVkPastPresentationTimingGOOGLE
::actualPresentTime
andVkPastPresentationTimingGOOGLE
::earliestPresentTime
. It is possible that an application can submit images withVkPresentTimeGOOGLE
::desiredPresentTime
values such that new images may not be displayed. For example, ifVkPresentTimeGOOGLE
::desiredPresentTime
is far enough in the future that an image is not presented beforevkQueuePresentKHR
is called to present another image, the first image will not be displayed to the user. If the application continues to do that, the presentation may not display new images. -
VK_PRESENT_MODE_FIFO_RELAXED_KHR
. For images that are presented in time to be displayed at the next vertical blanking period, the semantics are identical as forVK_PRESENT_MODE_FIFO_KHR
. For images that are presented late, and are displayed after the start of the vertical blanking period (i.e. with tearing), the values ofVkPastPresentationTimingGOOGLE
may be treated as if the image was displayed at the start of the vertical blanking period, or may be treated the same as forVK_PRESENT_MODE_IMMEDIATE_KHR
.
Present Wait
Applications wanting to control the pacing of the application by monitoring when presentation processes have completed to limit the number of outstanding images queued for presentation, need to have a method of being signaled during the presentation process.
Using
the VK_GOOGLE_display_timing
extension
applications can discover when images were presented, but only
asynchronously.
Providing a mechanism which allows applications to block, waiting for a specific step of the presentation process to complete allows them to control the amount of outstanding work (and hence the potential lag in responding to user input or changes in the rendering environment).
The VK_KHR_present_wait
extension allows applications to tell the
presentation engine at the vkQueuePresentKHR call that it plans on
waiting for presentation by passing a VkPresentIdKHR structure.
The presentId
passed in that structure may then be passed to a future
vkWaitForPresentKHR call to cause the application to block until that
presentation is finished.
WSI Swapchain
A swapchain object (a.k.a.
swapchain) provides the ability to present rendering results to a surface.
Swapchain objects are represented by VkSwapchainKHR
handles:
// Provided by VK_KHR_swapchain
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSwapchainKHR)
A swapchain is an abstraction for an array of presentable images that are
associated with a surface.
The presentable images are represented by VkImage
objects created by
the platform.
One image (which can be an array image for multiview/stereoscopic-3D
surfaces) is displayed at a time, but multiple images can be queued for
presentation.
An application renders to the image, and then queues the image for
presentation to the surface.
A native window cannot be associated with more than one non-retired swapchain at a time. Further, swapchains cannot be created for native windows that have a non-Vulkan graphics API surface associated with them.
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 released 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 application can also release the acquisition of the image through vkReleaseSwapchainImagesEXT, if the image is not in use by the device, and skip the present operation.
The presentation engine controls the order in which presentable images are acquired for use by the application.
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.
The |
In order to query a swapchain’s status when rendering to a shared presentable image, call:
// Provided by VK_KHR_shared_presentable_image
VkResult vkGetSwapchainStatusKHR(
VkDevice device,
VkSwapchainKHR swapchain);
-
device
is the device associated 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.
The swapchain state may be cached by implementations, so applications
should regularly call |
To create a swapchain, call:
// Provided by VK_KHR_swapchain
VkResult vkCreateSwapchainKHR(
VkDevice device,
const VkSwapchainCreateInfoKHR* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkSwapchainKHR* pSwapchain);
-
device
is the device to create the swapchain for. -
pCreateInfo
is a pointer to a VkSwapchainCreateInfoKHR structure specifying the parameters of the created swapchain. -
pAllocator
is the allocator used for host memory allocated for the swapchain object when there is no more specific allocator available (see Memory Allocation). -
pSwapchain
is a pointer to a VkSwapchainKHR handle in which the created swapchain object will be returned.
As mentioned above, if vkCreateSwapchainKHR
succeeds, it will return a
handle to a swapchain containing an array of at least
pCreateInfo->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 pCreateInfo->surface
must not be destroyed until after the
swapchain is destroyed.
If oldSwapchain
is VK_NULL_HANDLE, and
the native window referred to by pCreateInfo->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 pCreateInfo->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 pCreateInfo->surface
must not become
associated with a non-Vulkan graphics API surface before all associated
Vulkan swapchains have been destroyed.
vkCreateSwapchainKHR
will return VK_ERROR_DEVICE_LOST
if the
logical device was lost.
The VkSwapchainKHR
is a child of the device
, and must be
destroyed before the device
.
However, VkSurfaceKHR
is not a child of any VkDevice
and is not
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.
If the oldSwapchain
parameter of pCreateInfo
is a valid
swapchain, which has exclusive full-screen access, that access is released
from pCreateInfo->oldSwapchain
.
If the command succeeds in this case, the newly created swapchain will
automatically acquire exclusive full-screen access from
pCreateInfo->oldSwapchain
.
This implicit transfer is intended to avoid exiting and entering full-screen exclusive mode, which may otherwise cause unwanted visual updates to the display. |
In some cases, swapchain creation may fail if exclusive full-screen mode is
requested for application control, but for some implementation-specific
reason exclusive full-screen access is unavailable for the particular
combination of parameters provided.
If this occurs, VK_ERROR_INITIALIZATION_FAILED
will be returned.
In particular, it will fail if the |
If the pNext
chain of VkSwapchainCreateInfoKHR includes a
VkSwapchainPresentBarrierCreateInfoNV structure, then that structure
includes additional swapchain creation parameters specific to the present
barrier.
Swapchain creation may fail if the state of the current system restricts
the usage of the present barrier feature
VkSurfaceCapabilitiesPresentBarrierNV, or a swapchain itself does not
satisfy all the required conditions.
In this scenario VK_ERROR_INITIALIZATION_FAILED
is returned.
When the VkSurfaceKHR in VkSwapchainCreateInfoKHR is a display
surface, then the VkDisplayModeKHR in display surface’s
VkDisplaySurfaceCreateInfoKHR is associated with a particular
VkDisplayKHR.
Swapchain creation may fail if that VkDisplayKHR is not acquired by
the application.
In this scenario VK_ERROR_INITIALIZATION_FAILED
is returned.
The VkSwapchainCreateInfoKHR
structure is defined as:
// Provided by VK_KHR_swapchain
typedef struct VkSwapchainCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkSwapchainCreateFlagsKHR flags;
VkSurfaceKHR surface;
uint32_t minImageCount;
VkFormat imageFormat;
VkColorSpaceKHR imageColorSpace;
VkExtent2D imageExtent;
uint32_t imageArrayLayers;
VkImageUsageFlags imageUsage;
VkSharingMode imageSharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t* pQueueFamilyIndices;
VkSurfaceTransformFlagBitsKHR preTransform;
VkCompositeAlphaFlagBitsKHR compositeAlpha;
VkPresentModeKHR presentMode;
VkBool32 clipped;
VkSwapchainKHR oldSwapchain;
} VkSwapchainCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkSwapchainCreateFlagBitsKHR indicating parameters of the swapchain creation. -
surface
is the surface onto which the swapchain will present images. If the creation succeeds, the swapchain becomes associated 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
.On some platforms, it is normal that
maxImageExtent
may become(0, 0)
, for example when the window is minimized. In such a case, it is not possible to create a swapchain due to the Valid Usage requirements , unless scaling is selected through VkSwapchainPresentScalingCreateInfoEXT, if supported . -
imageArrayLayers
is the number of views in a multiview/stereo surface. For non-stereoscopic-3D applications, this value is 1. -
imageUsage
is a bitmask of VkImageUsageFlagBits describing the intended usage of the (acquired) swapchain images. -
imageSharingMode
is the sharing mode used for the image(s) of the swapchain. -
queueFamilyIndexCount
is the number of queue families having access to the image(s) of the swapchain whenimageSharingMode
isVK_SHARING_MODE_CONCURRENT
. -
pQueueFamilyIndices
is a pointer to 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. Fragment shaders may not execute for these pixels, and thus any side effects they would have had will not occur. SettingVK_TRUE
does not guarantee any clipping will occur, but allows more efficient 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.Applications should set this value to
VK_TRUE
if they do not expect to read back the content of presentable images before presenting them or after reacquiring them, and if their fragment shaders do not have any side effects that require them to run for all pixels in the presentable image.
-
-
oldSwapchain
is VK_NULL_HANDLE, or the existing non-retired swapchain currently associated 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
.
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:
// Provided by VK_KHR_swapchain
typedef enum VkSwapchainCreateFlagBitsKHR {
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR = 0x00000001,
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain
VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR = 0x00000002,
// Provided by VK_KHR_swapchain_mutable_format
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR = 0x00000004,
// Provided by VK_EXT_swapchain_maintenance1
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT = 0x00000008,
} 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_PROTECTED_BIT_KHR
specifies that images created from the swapchain are protected images. -
VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
specifies that the images of the swapchain can be used to create aVkImageView
with a different format than what the swapchain was created with. The list of allowed image view formats is specified by adding a VkImageFormatListCreateInfo structure to thepNext
chain of VkSwapchainCreateInfoKHR. In addition, this flag also specifies that the swapchain can be created with usage flags that are not supported for the format the swapchain is created with but are supported for at least one of the allowed image view formats. -
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT
specifies that the implementation may defer allocation of memory associated with each swapchain image until its index is to be returned from vkAcquireNextImageKHR or vkAcquireNextImage2KHR for the first time.
// Provided by VK_KHR_swapchain
typedef VkFlags VkSwapchainCreateFlagsKHR;
VkSwapchainCreateFlagsKHR
is a bitmask type for setting a mask of zero
or more VkSwapchainCreateFlagBitsKHR.
If the pNext
chain of VkSwapchainCreateInfoKHR includes a
VkDeviceGroupSwapchainCreateInfoKHR
structure, then that structure
includes a set of device group present modes that the swapchain can be used
with.
The VkDeviceGroupSwapchainCreateInfoKHR
structure is defined as:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkDeviceGroupSwapchainCreateInfoKHR {
VkStructureType sType;
const void* pNext;
VkDeviceGroupPresentModeFlagsKHR modes;
} VkDeviceGroupSwapchainCreateInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
modes
is a bitfield of modes that the swapchain can be used with.
If this structure is not present, modes
is considered to be
VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR
.
If the pNext
chain of VkSwapchainCreateInfoKHR includes a
VkSwapchainDisplayNativeHdrCreateInfoAMD
structure, then that
structure includes additional swapchain creation parameters specific to
display native HDR support.
The VkSwapchainDisplayNativeHdrCreateInfoAMD
structure is defined as:
// Provided by VK_AMD_display_native_hdr
typedef struct VkSwapchainDisplayNativeHdrCreateInfoAMD {
VkStructureType sType;
const void* pNext;
VkBool32 localDimmingEnable;
} VkSwapchainDisplayNativeHdrCreateInfoAMD;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
localDimmingEnable
specifies whether local dimming is enabled for the swapchain.
If the pNext
chain of VkSwapchainCreateInfoKHR does not include
this structure, the default value for localDimmingEnable
is
VK_TRUE
, meaning local dimming is initially enabled for the swapchain.
The local dimming HDR setting may also be changed over the life of a swapchain by calling:
// Provided by VK_AMD_display_native_hdr
void vkSetLocalDimmingAMD(
VkDevice device,
VkSwapchainKHR swapChain,
VkBool32 localDimmingEnable);
-
device
is the device associated withswapChain
. -
swapChain
handle to enable local dimming. -
localDimmingEnable
specifies whether local dimming is enabled for the swapchain.
If the pNext
chain of VkSwapchainCreateInfoKHR includes a
VkSurfaceFullScreenExclusiveInfoEXT structure, then that structure
specifies the application’s preferred full-screen presentation behavior.
If this structure is not present, fullScreenExclusive
is considered to
be VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT
.
To enable surface counters when creating a swapchain, add a
VkSwapchainCounterCreateInfoEXT
structure to the pNext
chain of
VkSwapchainCreateInfoKHR.
VkSwapchainCounterCreateInfoEXT
is defined as:
// Provided by VK_EXT_display_control
typedef struct VkSwapchainCounterCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkSurfaceCounterFlagsEXT surfaceCounters;
} VkSwapchainCounterCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
surfaceCounters
is a bitmask of VkSurfaceCounterFlagBitsEXT specifying surface counters to enable for the swapchain.
The requested counters become active when the first presentation command for the associated swapchain is processed by the presentation engine. To query the value of an active counter, use:
// Provided by VK_EXT_display_control
VkResult vkGetSwapchainCounterEXT(
VkDevice device,
VkSwapchainKHR swapchain,
VkSurfaceCounterFlagBitsEXT counter,
uint64_t* pCounterValue);
-
device
is the VkDevice associated withswapchain
. -
swapchain
is the swapchain from which to query the counter value. -
counter
is a VkSurfaceCounterFlagBitsEXT value specifying the counter to query. -
pCounterValue
will return the current value of the counter.
If a counter is not available because the swapchain is out of date, the
implementation may return VK_ERROR_OUT_OF_DATE_KHR
.
To specify compression properties for the swapchain images in this
swapchain, add a VkImageCompressionControlEXT structure to the
pNext
chain of the VkSwapchainCreateInfoKHR structure.
Applications can modify the presentation mode used by the swapchain on a
per-presentation basis.
However, all presentation modes the application intends to use with the
swapchain must be specified at swapchain creation time.
To specify more than one presentation mode when creating a swapchain,
include the VkSwapchainPresentModesCreateInfoEXT
structure in the
pNext
chain of the VkSwapchainCreateInfoKHR structure.
The VkSwapchainPresentModesCreateInfoEXT
structure is defined as:
// Provided by VK_EXT_swapchain_maintenance1
typedef struct VkSwapchainPresentModesCreateInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t presentModeCount;
const VkPresentModeKHR* pPresentModes;
} VkSwapchainPresentModesCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
presentModeCount
is the number of presentation modes provided. -
pPresentModes
is a list of presentation modes withpresentModeCount
entries
When an application presents a swapchain image with dimensions different than those of the target surface, different behavior is possible on different platforms per their respective specifications:
-
Presentation fails and
VK_ERROR_OUT_OF_DATE_KHR
is returned -
Scaling is done and
VK_SUCCESS
orVK_SUBOPTIMAL_KHR
is returned -
Unspecified scaling using an arbitrary combination of stretching, centering and/or clipping.
Applications can define specific behavior when creating a swapchain by
including the VkSwapchainPresentScalingCreateInfoEXT
structure in the
pNext
chain of the VkSwapchainCreateInfoKHR structure.
The VkSwapchainPresentScalingCreateInfoEXT
structure is defined as:
// Provided by VK_EXT_swapchain_maintenance1
typedef struct VkSwapchainPresentScalingCreateInfoEXT {
VkStructureType sType;
const void* pNext;
VkPresentScalingFlagsEXT scalingBehavior;
VkPresentGravityFlagsEXT presentGravityX;
VkPresentGravityFlagsEXT presentGravityY;
} VkSwapchainPresentScalingCreateInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
scalingBehavior
is0
or the scaling method to use when the dimensions of the surface and swapchain images differ. -
presentGravityX
is0
or the x-axis direction in which swapchain image pixels gravitate relative to the surface whenscalingBehavior
does not result in a one-to-one pixel mapping between the scaled swapchain image and the surface. -
presentGravityY
is0
or the y-axis direction in which swapchain image pixels gravitate relative to the surface whenscalingBehavior
does not result in a one-to-one pixel mapping between the scaled swapchain image and the surface.
If scalingBehavior
is 0
, the result of presenting a swapchain image
with dimensions that do not match the surface dimensions is implementation
and platform-dependent.
If presentGravityX
or presentGravityY
are 0
, the presentation
gravity must match that defined by the native platform surface on platforms
which define surface gravity.
To destroy a swapchain object call:
// Provided by VK_KHR_swapchain
void vkDestroySwapchainKHR(
VkDevice device,
VkSwapchainKHR swapchain,
const VkAllocationCallbacks* pAllocator);
-
device
is the VkDevice associated 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.
If swapchain
has exclusive full-screen access, it is released before
the swapchain is destroyed.
To obtain the array of presentable images associated with a swapchain, call:
// Provided by VK_KHR_swapchain
VkResult vkGetSwapchainImagesKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint32_t* pSwapchainImageCount,
VkImage* pSwapchainImages);
-
device
is the device associated 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
application 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, and VK_INCOMPLETE
will be returned instead
of VK_SUCCESS
, to indicate that not all the available presentable
images were returned.
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.
However, command buffers are not allowed to reference presentable images
created with |
Images returned by vkGetSwapchainImagesKHR are fully backed by memory
before they are passed to the application, as if they are each bound
completely and contiguously to a single VkDeviceMemory
object
, unless the swapchain is created with the
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT
flag
.
All presentable images are initially in the VK_IMAGE_LAYOUT_UNDEFINED
layout, thus before using presentable images, the application must
transition them to a valid layout for the intended use.
Further, the lifetime of presentable images is controlled by the implementation, so applications must not destroy a presentable image. See vkDestroySwapchainKHR for further details on the lifetime of presentable images.
Images can also be created by using vkCreateImage with
VkImageSwapchainCreateInfoKHR and bound to swapchain memory using
vkBindImageMemory2 with VkBindImageMemorySwapchainInfoKHR.
These images can be used anywhere swapchain images are used, and are useful
in logical devices with multiple physical devices to create peer memory
bindings of swapchain memory.
These images and bindings have no effect on what memory is presented.
Unlike images retrieved from vkGetSwapchainImagesKHR
, these images
must be destroyed with vkDestroyImage.
To acquire an available presentable image to use, and retrieve the index of that image, call:
// Provided by VK_KHR_swapchain
VkResult vkAcquireNextImageKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint64_t timeout,
VkSemaphore semaphore,
VkFence fence,
uint32_t* pImageIndex);
-
device
is the device associated 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
in which the index of the next image to use (i.e. an index into the array of images returned byvkGetSwapchainImagesKHR
) is returned.
If the swapchain
has been created with the
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT
flag, the image
whose index is returned in pImageIndex
will be fully backed by memory
before this call returns to the application, as if it is bound completely
and contiguously to a single VkDeviceMemory
object.
If an image is acquired successfully, vkAcquireNextImageKHR
must
either return VK_SUCCESS
or VK_SUBOPTIMAL_KHR
.
The implementation may return VK_SUBOPTIMAL_KHR
if the swapchain no
longer matches the surface properties exactly, but can still be used for
presentation.
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.
Once vkAcquireNextImageKHR
successfully acquires an image, the
semaphore signal operation referenced by semaphore
, if not
VK_NULL_HANDLE, and the fence signal operation referenced by
fence
, if not VK_NULL_HANDLE, are submitted for execution.
If vkAcquireNextImageKHR
does not successfully acquire an image,
semaphore
and fence
are unaffected.
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.
Let S be the number of images in swapchain
.
If swapchain
is created with
VkSwapchainPresentModesCreateInfoEXT, let M be the maximum of
the values in VkSurfaceCapabilitiesKHR::minImageCount
when
queried with each present mode in
VkSwapchainPresentModesCreateInfoEXT::pPresentModes
in
VkSurfacePresentModeEXT.
Otherwise, let M be the value of
VkSurfaceCapabilitiesKHR::minImageCount
without a
VkSurfacePresentModeEXT as part of the query input.
vkAcquireNextImageKHR
should not be called if the number of images
that the application has currently acquired is greater than S-M.
If vkAcquireNextImageKHR
is called when the number of images that the
application has currently acquired is less than or equal to S-M,
vkAcquireNextImageKHR
must return in finite time with an allowed
VkResult
code.
Returning a result in finite time guarantees that the implementation cannot
deadlock an application, or suspend its execution indefinitely with correct
API usage.
Acquiring too many images at once may block indefinitely, which is covered
by valid usage when attempting to use |
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.
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.
Applications should not rely on |
An application must wait until either the semaphore
or fence
is
signaled before accessing the image’s data.
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.
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
is returned 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.
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
unless the swapchain is created with a non-zero value in
VkSwapchainPresentScalingCreateInfoEXT::scalingBehavior
.
If presentation does succeed, the mapping from the presented image to the
native surface is
defined by the VkSwapchainPresentScalingCreateInfoEXT structure if
provided.
Otherwise it 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.
For example, consider a 4x3 window/surface that gets resized to be 3x4 (taller than wider). On some window systems, the portion of the window/surface that was previously and still is visible (the 3x3 part) will contain the same contents as before, while the remaining parts of the window will have undefined contents. Other window systems may squash/stretch the image to fill the new window size without any undefined contents, or apply some other mapping. |
To acquire an available presentable image to use, and retrieve the index of that image, call:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
VkResult vkAcquireNextImage2KHR(
VkDevice device,
const VkAcquireNextImageInfoKHR* pAcquireInfo,
uint32_t* pImageIndex);
-
device
is the device associated withswapchain
. -
pAcquireInfo
is a pointer to a VkAcquireNextImageInfoKHR structure containing parameters of the acquire. -
pImageIndex
is a pointer to auint32_t
that is set to the index of the next image to use.
If the swapchain
has been created with the
VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT
flag, the image
whose index is returned in pImageIndex
will be fully backed by memory
before this call returns to the application.
The VkAcquireNextImageInfoKHR
structure is defined as:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkAcquireNextImageInfoKHR {
VkStructureType sType;
const void* pNext;
VkSwapchainKHR swapchain;
uint64_t timeout;
VkSemaphore semaphore;
VkFence fence;
uint32_t deviceMask;
} VkAcquireNextImageInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
swapchain
is a non-retired swapchain from which an image is acquired. -
timeout
specifies how long the function waits, in nanoseconds, if no image is available. -
semaphore
is VK_NULL_HANDLE or a semaphore to signal. -
fence
is VK_NULL_HANDLE or a fence to signal. -
deviceMask
is a mask of physical devices for which the swapchain image will be ready to use when the semaphore or fence is signaled.
If vkAcquireNextImageKHR is used, the device mask is considered to include all physical devices in the logical device.
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:
// Provided by VK_KHR_swapchain
VkResult vkQueuePresentKHR(
VkQueue queue,
const VkPresentInfoKHR* pPresentInfo);
-
queue
is a queue that is capable of presentation to the target surface’s platform on the same device as the image’s swapchain. -
pPresentInfo
is a pointer to a VkPresentInfoKHR structure specifying parameters of the presentation.
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. |
The origin of the native orientation of the surface coordinate system is not
specified in the Vulkan specification; it depends on the platform.
For most platforms the origin is by default upper-left, meaning the pixel of
the presented VkImage at coordinates (0,0) would appear at the
upper left pixel of the platform surface (assuming
|
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 any swapchain
member of pPresentInfo
was created with
VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT
,
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
will be returned if that
swapchain does not have exclusive full-screen access, possibly for
implementation-specific reasons outside of the application’s control.
If multiple swapchains are presented, the result code is determined by
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_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
if issued separately thenVK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
is returned. -
If any of the presents would have a result of
VK_SUBOPTIMAL_KHR
if issued separately thenVK_SUBOPTIMAL_KHR
is returned. -
Otherwise
VK_SUCCESS
is returned.
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.
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.
Calls to vkQueuePresentKHR
may block, but must return in finite
time.
The processing of the presentation happens in issue order with other queue
operations, but semaphores must 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.
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
,
VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT
,
or VK_ERROR_SURFACE_LOST_KHR
, the set of queue operations are still
considered to be enqueued and thus any semaphore wait operation specified in
VkPresentInfoKHR will execute when the corresponding queue operation
is complete.
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 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 |
The VkPresentInfoKHR
structure is defined as:
// Provided by VK_KHR_swapchain
typedef struct VkPresentInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t waitSemaphoreCount;
const VkSemaphore* pWaitSemaphores;
uint32_t swapchainCount;
const VkSwapchainKHR* pSwapchains;
const uint32_t* pImageIndices;
VkResult* pResults;
} VkPresentInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
waitSemaphoreCount
is the number of semaphores to wait for before issuing the present request. The number may be zero. -
pWaitSemaphores
isNULL
or a pointer to 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 a pointer to an array of VkSwapchainKHR objects withswapchainCount
entries. -
pImageIndices
is a pointer to 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 a pointer to 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.
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 adding a VkPresentRegionsKHR
structure to the pNext
chain of the VkPresentInfoKHR
structure.
The VkPresentRegionsKHR
structure is defined as:
// Provided by VK_KHR_incremental_present
typedef struct VkPresentRegionsKHR {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const VkPresentRegionKHR* pRegions;
} VkPresentRegionsKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this 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:
// Provided by VK_KHR_incremental_present
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 rectangles must be specified relative to VkSurfaceCapabilitiesKHR::currentTransform
, regardless of the swapchain’spreTransform
. The presentation engine will apply thepreTransform
transformation to the rectangles, along with any further transformation it applies to the image content.
The VkRectLayerKHR
structure is defined as:
// Provided by VK_KHR_incremental_present
typedef struct VkRectLayerKHR {
VkOffset2D offset;
VkExtent2D extent;
uint32_t layer;
} VkRectLayerKHR;
-
offset
is the origin of the rectangle, in pixels. -
extent
is the size of the rectangle, in pixels. -
layer
is the layer of the image. For images with only one layer, the value 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 a
VkDisplayPresentInfoKHR structure.
The VkDisplayPresentInfoKHR
structure is defined as:
// Provided by VK_KHR_display_swapchain
typedef struct VkDisplayPresentInfoKHR {
VkStructureType sType;
const void* pNext;
VkRect2D srcRect;
VkRect2D dstRect;
VkBool32 persistent;
} VkDisplayPresentInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
srcRect
is a rectangular region of pixels to present. It must be a subset of the image being presented. 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 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:
// Provided by VK_VERSION_1_1 with VK_KHR_swapchain, VK_KHR_device_group with VK_KHR_swapchain
typedef struct VkDeviceGroupPresentInfoKHR {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const uint32_t* pDeviceMasks;
VkDeviceGroupPresentModeFlagBitsKHR mode;
} VkDeviceGroupPresentInfoKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
swapchainCount
is zero or the number of elements inpDeviceMasks
. -
pDeviceMasks
is a pointer to an array of device masks, one for each element of VkPresentInfoKHR::pSwapchains
. -
mode
is a VkDeviceGroupPresentModeFlagBitsKHR value specifying 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
.
When the VK_GOOGLE_display_timing
extension is enabled, additional
fields can be specified that allow an application to specify the earliest
time that an image should be displayed.
This allows an application to avoid stutter that is caused by an image being
displayed earlier than planned.
Such stuttering can occur with both fixed and variable-refresh-rate
displays, because stuttering occurs when the geometry is not correctly
positioned for when the image is displayed.
An application can instruct the presentation engine that an image should
not be displayed earlier than a specified time by adding a
VkPresentTimesInfoGOOGLE
structure to the pNext
chain of the
VkPresentInfoKHR
structure.
The VkPresentTimesInfoGOOGLE
structure is defined as:
// Provided by VK_GOOGLE_display_timing
typedef struct VkPresentTimesInfoGOOGLE {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const VkPresentTimeGOOGLE* pTimes;
} VkPresentTimesInfoGOOGLE;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
swapchainCount
is the number of swapchains being presented to by this command. -
pTimes
isNULL
or a pointer to an array ofVkPresentTimeGOOGLE
elements withswapchainCount
entries. If notNULL
, each element ofpTimes
contains the earliest time to present the image corresponding to the entry in theVkPresentInfoKHR
::pImageIndices
array.
The VkPresentTimeGOOGLE
structure is defined as:
// Provided by VK_GOOGLE_display_timing
typedef struct VkPresentTimeGOOGLE {
uint32_t presentID;
uint64_t desiredPresentTime;
} VkPresentTimeGOOGLE;
-
presentID
is an application-provided identification value, that can be used with the results of vkGetPastPresentationTimingGOOGLE, in order to uniquely identify this present. In order to be useful to the application, it should be unique within some period of time that is meaningful to the application. -
desiredPresentTime
specifies that the image given should not be displayed to the user any earlier than this time.desiredPresentTime
is a time in nanoseconds, relative to a monotonically-increasing clock (e.g.CLOCK_MONOTONIC
(see clock_gettime(2)) on Android and Linux). A value of zero specifies that the presentation engine may display the image at any time. This is useful when the application desires to providepresentID
, but does not need a specificdesiredPresentTime
.
The VkPresentIdKHR
structure is defined as:
// Provided by VK_KHR_present_id
typedef struct VkPresentIdKHR {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const uint64_t* pPresentIds;
} VkPresentIdKHR;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
swapchainCount
is the number of swapchains being presented to thevkQueuePresentKHR
command. -
pPresentIds
isNULL
or a pointer to an array ofuint64_t
withswapchainCount
entries. If notNULL
, each non-zero value inpPresentIds
specifies the present id to be associated with the presentation of the swapchain with the same index in the vkQueuePresentKHR call.
For applications to be able to reference specific presentation events queued
by a call to vkQueuePresentKHR
, an identifier needs to be associated
with them.
When the presentId
feature is enabled,
applications can include the VkPresentIdKHR
structure in the
pNext
chain of the VkPresentInfoKHR structure to supply
identifiers.
Each VkSwapchainKHR
has a presentId associated with it.
This value is initially set to zero when the VkSwapchainKHR
is
created.
When a VkPresentIdKHR
structure with a non-NULL pPresentIds
is
included in the pNext
chain of a VkPresentInfoKHR structure,
each pSwapchains
entry has a presentId associated in the
pPresentIds
array at the same index as the swapchain in the
pSwapchains
array.
If this presentId is non-zero, then the application can later use this
value to refer to that image presentation.
A value of zero indicates that this presentation has no associated
presentId.
A non-zero presentId must be greater than any non-zero presentId passed
previously by the application for the same swapchain.
There is no requirement for any precise timing relationship between the presentation of the image to the user and the update of the presentId value, but implementations should make this as close as possible to the presentation of the first pixel in the new image to the user.
When the presentWait
feature is enabled, an
application can wait for an image to be presented to the user by first
specifying a presentId for the target presentation by adding a
VkPresentIdKHR
structure to the pNext
chain of the
VkPresentInfoKHR structure and then waiting for that presentation to
complete by calling:
// Provided by VK_KHR_present_wait
VkResult vkWaitForPresentKHR(
VkDevice device,
VkSwapchainKHR swapchain,
uint64_t presentId,
uint64_t timeout);
-
device
is the device associated withswapchain
. -
swapchain
is the non-retired swapchain on which an image was queued for presentation. -
presentId
is the presentation presentId to wait for. -
timeout
is the timeout period in units of nanoseconds.timeout
is adjusted to the closest value allowed by the implementation-dependent timeout accuracy, which may be substantially longer than one nanosecond, and may be longer than the requested period.
vkWaitForPresentKHR
waits for the presentId associated with
swapchain
to be increased in value so that it is at least equal to
presentId
.
For VK_PRESENT_MODE_MAILBOX_KHR
(or other present mode where images
may be replaced in the presentation queue) any wait of this type associated
with such an image must be signaled no later than a wait associated with
the replacing image would be signaled.
When the presentation has completed, the presentId associated with the
related pSwapchains
entry will be increased in value so that it is at
least equal to the value provided in the VkPresentIdKHR
structure.
There is no requirement for any precise timing relationship between the presentation of the image to the user and the update of the presentId value, but implementations should make this as close as possible to the presentation of the first pixel in the next image being presented to the user.
The call to vkWaitForPresentKHR
will block until either the presentId
associated with swapchain
is greater than or equal to presentId
,
or timeout
nanoseconds passes.
When the swapchain becomes OUT_OF_DATE, the call will either return
VK_SUCCESS
(if the image was delivered to the presentation engine and
may have been presented to the user) or will return early with status
VK_ERROR_OUT_OF_DATE_KHR
(if the image was not presented to the user).
As an exception to the normal rules for objects which are externally
synchronized, the swapchain
passed to vkWaitForPresentKHR
may
be simultaneously used by other threads in calls to functions other than
vkDestroySwapchainKHR.
Access to the swapchain data associated with this extension must be atomic
within the implementation.
When the VK_GGP_frame_token
extension is enabled, a Google Games
Platform frame token can be specified when presenting an image to a
swapchain by adding a VkPresentFrameTokenGGP
structure to the
pNext
chain of the VkPresentInfoKHR
structure.
The VkPresentFrameTokenGGP
structure is defined as:
// Provided by VK_GGP_frame_token
typedef struct VkPresentFrameTokenGGP {
VkStructureType sType;
const void* pNext;
GgpFrameToken frameToken;
} VkPresentFrameTokenGGP;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
frameToken
is the Google Games Platform frame token.
The VkSwapchainPresentModeInfoEXT
structure is defined as:
// Provided by VK_EXT_swapchain_maintenance1
typedef struct VkSwapchainPresentModeInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const VkPresentModeKHR* pPresentModes;
} VkSwapchainPresentModeInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
swapchainCount
is the number of swapchains being presented to by this command. -
pPresentModes
is a list of presentation modes withswapchainCount
entries.
If the pNext
chain of VkPresentInfoKHR includes a
VkSwapchainPresentModeInfoEXT
structure, then that structure defines
the presentation modes used for the current and subsequent presentation
operations.
When the application changes present modes with VkSwapchainPresentModeInfoEXT, images that have already been queued for presentation will continue to be presented according to the previous present mode. The current image being queued for presentation and subsequent images will be presented according to the new present mode. The behavior during the transition between the two modes is defined as follows.
-
Transition from
VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
toVK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
: the presentation engine updates the shared presentable image according to the behavior ofVK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
. -
Transition from
VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
toVK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
: the presentation engine may update the shared presentable image or defer that to its regular refresh cycle, according to the behavior ofVK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
. -
Transition between
VK_PRESENT_MODE_FIFO_KHR
andVK_PRESENT_MODE_FIFO_RELAXED_KHR
: Images continue to be appended to the same FIFO queue, and the behavior with respect to waiting for vertical blanking period will follow the new mode for current and subsequent images. -
Transition from
VK_PRESENT_MODE_IMMEDIATE_KHR
toVK_PRESENT_MODE_FIFO_KHR
orVK_PRESENT_MODE_FIFO_RELAXED_KHR
orVK_PRESENT_MODE_FIFO_LATEST_READY_EXT
: As all prior present requests in theVK_PRESENT_MODE_IMMEDIATE_KHR
mode are applied immediately, there are no outstanding present operations in this mode, and current and subsequent images are appended to the FIFO queue and presented according to the new mode. -
Transition from
VK_PRESENT_MODE_MAILBOX_KHR
toVK_PRESENT_MODE_FIFO_KHR
orVK_PRESENT_MODE_FIFO_RELAXED_KHR
orVK_PRESENT_MODE_FIFO_LATEST_READY_EXT
: Presentation in FIFO modes require waiting for the next vertical blanking period, withVK_PRESENT_MODE_MAILBOX_KHR
allowing the pending present operation to be replaced by a new one. In this case, the current present operation will replace the pending present operation and is applied according to the new mode. -
Transition from
VK_PRESENT_MODE_FIFO_KHR
orVK_PRESENT_MODE_FIFO_RELAXED_KHR
orVK_PRESENT_MODE_FIFO_LATEST_READY_EXT
toVK_PRESENT_MODE_IMMEDIATE_KHR
orVK_PRESENT_MODE_MAILBOX_KHR
: If the FIFO queue is empty, presentation is done according to the behavior of the new mode. If there are present operations in the FIFO queue, once the last present operation is performed based on the respective vertical blanking period, the current and subsequent updates are applied according to the new mode. -
Transition between
VK_PRESENT_MODE_FIFO_KHR
orVK_PRESENT_MODE_FIFO_RELAXED_KHR
, andVK_PRESENT_MODE_FIFO_LATEST_READY_EXT
: Images continue to be appended to the same FIFO queue, and the behavior with respect to waiting for vertical blanking period and dequeuing requests will follow the new mode for current and subsequent images. -
The behavior during transition between any other present modes, if possible, is implementation defined.
The VkSwapchainPresentFenceInfoEXT
structure is defined as:
// Provided by VK_EXT_swapchain_maintenance1
typedef struct VkSwapchainPresentFenceInfoEXT {
VkStructureType sType;
const void* pNext;
uint32_t swapchainCount;
const VkFence* pFences;
} VkSwapchainPresentFenceInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
swapchainCount
is the number of swapchains being presented to by this command. -
pFences
is a list of fences withswapchainCount
entries. Each entry must be VK_NULL_HANDLE or the handle of a fence to signal when the relevant operations on the associated swapchain have completed.
The set of queue operations defined by queuing an image for presentation, as well as operations performed by the presentation engine access the payloads of objects associated with the presentation operation. The associated objects include:
-
The swapchain image, its implicitly bound memory, and any other resources bound to that memory.
-
The wait semaphores specified when queuing the image for presentation.
The application can provide a fence that the implementation will signal when all such queue operations have completed and the presentation engine has taken a reference to the payload of any objects it accesses as part of the present operation. For all binary wait semaphores imported by the presentation engine using the equivalent of reference transference, as described in Importing Semaphore Payloads, this fence must not signal until all such semaphore payloads have been reset by the presentation engine.
The application can destroy the wait semaphores associated with a given presentation operation when at least one of the associated fences is signaled, and can destroy the swapchain when the fences associated with all past presentation requests referring to that swapchain have signaled.
Fences associated with presentations to the same swapchain on the same VkQueue must be signaled in the same order as the present operations.
To specify a fence for each swapchain in a present operation, include the
VkSwapchainPresentFenceInfoEXT
structure in the pNext
chain of
the VkPresentInfoKHR structure.
To release images previously acquired through vkAcquireNextImage2KHR or vkAcquireNextImageKHR, call:
// Provided by VK_EXT_swapchain_maintenance1
VkResult vkReleaseSwapchainImagesEXT(
VkDevice device,
const VkReleaseSwapchainImagesInfoEXT* pReleaseInfo);
-
device
is the device associated with VkReleaseSwapchainImagesInfoEXT::swapchain
. -
pReleaseInfo
is a pointer to a VkReleaseSwapchainImagesInfoEXT structure containing parameters of the release.
Only images that are not in use by the device can be released.
Releasing images is a read-only operation that will not affect the content of the released images. Upon reacquiring the image, the image contents and its layout will be the same as they were prior to releasing 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.
This functionality is useful during swapchain recreation, where acquired images from the old swapchain can be released instead of presented. |
The VkReleaseSwapchainImagesInfoEXT
structure is defined as:
// Provided by VK_EXT_swapchain_maintenance1
typedef struct VkReleaseSwapchainImagesInfoEXT {
VkStructureType sType;
const void* pNext;
VkSwapchainKHR swapchain;
uint32_t imageIndexCount;
const uint32_t* pImageIndices;
} VkReleaseSwapchainImagesInfoEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
swapchain
is a swapchain to which images are being released. -
imageIndexCount
is the number of image indices to be released. -
pImageIndices
is a pointer to an array of indices into the array ofswapchain
’s presentable images, withimageIndexCount
entries.
HDR Metadata
This section describes how to improve color reproduction of content to better reproduce colors as seen on the display used to originally optimize the content.
To provide HDR metadata to an implementation, call:
// Provided by VK_EXT_hdr_metadata
void vkSetHdrMetadataEXT(
VkDevice device,
uint32_t swapchainCount,
const VkSwapchainKHR* pSwapchains,
const VkHdrMetadataEXT* pMetadata);
-
device
is the logical device where the swapchain(s) were created. -
swapchainCount
is the number of swapchains included inpSwapchains
. -
pSwapchains
is a pointer to an array ofswapchainCount
VkSwapchainKHR handles. -
pMetadata
is a pointer to an array ofswapchainCount
VkHdrMetadataEXT structures.
The metadata will be applied to the specified VkSwapchainKHR objects
at the next vkQueuePresentKHR call using that VkSwapchainKHR
object.
The metadata will persist until a subsequent vkSetHdrMetadataEXT
changes it.
The VkHdrMetadataEXT
structure is defined as:
// Provided by VK_EXT_hdr_metadata
typedef struct VkHdrMetadataEXT {
VkStructureType sType;
const void* pNext;
VkXYColorEXT displayPrimaryRed;
VkXYColorEXT displayPrimaryGreen;
VkXYColorEXT displayPrimaryBlue;
VkXYColorEXT whitePoint;
float maxLuminance;
float minLuminance;
float maxContentLightLevel;
float maxFrameAverageLightLevel;
} VkHdrMetadataEXT;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
displayPrimaryRed
is a VkXYColorEXT structure specifying the red primary of the display used to optimize the content -
displayPrimaryGreen
is a VkXYColorEXT structure specifying the green primary of the display used to optimize the content -
displayPrimaryBlue
is a VkXYColorEXT structure specifying the blue primary of the display used to optimize the content -
whitePoint
is a VkXYColorEXT structure specifying the white-point of the display used to optimize the content -
maxLuminance
is the maximum luminance of the display used to optimize the content in nits -
minLuminance
is the minimum luminance of the display used to optimize the content in nits -
maxContentLightLevel
is the value in nits of the desired luminance for the brightest pixels in the displayed image. -
maxFrameAverageLightLevel
is the value in nits of the average luminance of the frame which has the brightest average luminance anywhere in the content.
If any of the above values are unknown, they can be set to 0.
The meta-data provided here is intended to be used as defined in the SMPTE 2086, CTA 861.3 and CIE 15:2004 specifications. The validity and use of this data is outside the scope of Vulkan. |
The VkXYColorEXT
structure is defined as:
// Provided by VK_EXT_hdr_metadata
typedef struct VkXYColorEXT {
float x;
float y;
} VkXYColorEXT;
-
x
is the x chromaticity coordinate. -
y
is the y chromaticity coordinate.
Chromaticity coordinates are as specified in CIE 15:2004 “Calculation of chromaticity coordinates” (Section 7.3) and are limited to between 0 and 1 for real colors.
Lag Control
Some implementations support extensions to reduce display latency and control the swapchain present interval, as described in the remainder of this section.
Anti-Lag
The VK_AMD_anti_lag extension lowers latency between receiving input and displaying on the screen. It adds a command to indicate when input is being processed for a frame, and when that frame’s images are presented.
To lower latency, call:
// Provided by VK_AMD_anti_lag
void vkAntiLagUpdateAMD(
VkDevice device,
const VkAntiLagDataAMD* pData);
-
device
is the logical device -
pData
is a pointer to a VkAntiLagDataAMD structure containing latency reduction parameters.
This command should be executed immediately before the application processes
user input.
If pData
is not NULL
and
VkAntiLagDataAMD::presentationInfo
is not NULL
, this command
should be executed again before vkQueuePresentKHR, with
pPresentationInfo
set to matching values.
The VkAntiLagDataAMD
structure is defined as:
// Provided by VK_AMD_anti_lag
typedef struct VkAntiLagDataAMD {
VkStructureType sType;
const void* pNext;
VkAntiLagModeAMD mode;
uint32_t maxFPS;
const VkAntiLagPresentationInfoAMD* pPresentationInfo;
} VkAntiLagDataAMD;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
mode
is a VkAntiLagModeAMD value specifying the anti-lag status. -
maxFPS
is the framerate limit, in frames per second, used by the application. This limit will be imposed if anti-lag is enabled. If the application tries to render faster, the framerate will be reduced to match this limit. A value of 0 will disable the limit. -
pPresentationInfo
is a pointer to a VkAntiLagPresentationInfoAMD structure containing information about the application stage.
This structure specifies anti-lag parameters.
Possible values of VkAntiLagDataAMD::mode
, specifying the
anti-lag status, are:
// Provided by VK_AMD_anti_lag
typedef enum VkAntiLagModeAMD {
VK_ANTI_LAG_MODE_DRIVER_CONTROL_AMD = 0,
VK_ANTI_LAG_MODE_ON_AMD = 1,
VK_ANTI_LAG_MODE_OFF_AMD = 2,
} VkAntiLagModeAMD;
-
VK_ANTI_LAG_MODE_DRIVER_CONTROL_AMD
specifies that anti-lag will be enabled or disabled depending on driver settings. -
VK_ANTI_LAG_MODE_ON_AMD
specifies that anti-lag will be enabled. -
VK_ANTI_LAG_MODE_OFF_AMD
specifies that anti-lag will be disabled.
The VkAntiLagPresentationInfoAMD
structure is defined as:
// Provided by VK_AMD_anti_lag
typedef struct VkAntiLagPresentationInfoAMD {
VkStructureType sType;
void* pNext;
VkAntiLagStageAMD stage;
uint64_t frameIndex;
} VkAntiLagPresentationInfoAMD;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
stage
is a VkAntiLagStageAMD value specifying the current application stage. -
frameIndex
is set just before the application processes input data (VK_ANTI_LAG_STAGE_INPUT_AMD
). The sameframeIndex
value should be set before the frame with current input data will be presented by vkQueuePresentKHR (VK_ANTI_LAG_STAGE_PRESENT_AMD
). This should be done for each frame.
This structure specifies information about the presentation stage for which anti-lag parameters are being set.
Possible values of VkAntiLagPresentationInfoAMD::stage
,
specifying the current application stage, are:
// Provided by VK_AMD_anti_lag
typedef enum VkAntiLagStageAMD {
VK_ANTI_LAG_STAGE_INPUT_AMD = 0,
VK_ANTI_LAG_STAGE_PRESENT_AMD = 1,
} VkAntiLagStageAMD;
-
VK_ANTI_LAG_STAGE_INPUT_AMD
specifies the stage before processing input. -
VK_ANTI_LAG_STAGE_PRESENT_AMD
specifies the stage before vkQueuePresentKHR.
Latency Reduction
To enable or disable low latency mode on a swapchain, call:
// Provided by VK_NV_low_latency2
VkResult vkSetLatencySleepModeNV(
VkDevice device,
VkSwapchainKHR swapchain,
const VkLatencySleepModeInfoNV* pSleepModeInfo);
-
device
is the device associated withswapchain
. -
swapchain
is the swapchain to enable or disable low latency mode on. -
pSleepModeInfo
isNULL
or a pointer to a VkLatencySleepModeInfoNV structure specifying the parameters of the latency sleep mode.
If pSleepModeInfo
is NULL
, vkSetLatencySleepModeNV
will
disable low latency mode, low latency boost, and set the minimum present
interval previously specified by VkLatencySleepModeInfoNV to zero on
swapchain
.
As an exception to the normal rules for objects which are externally
synchronized, the swapchain passed to vkSetLatencySleepModeNV
may be
simultaneously used by other threads in calls to functions other than
vkDestroySwapchainKHR.
Access to the swapchain data associated with this extension must be atomic
within the implementation.
The VkLatencySleepModeInfoNV
structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkLatencySleepModeInfoNV {
VkStructureType sType;
const void* pNext;
VkBool32 lowLatencyMode;
VkBool32 lowLatencyBoost;
uint32_t minimumIntervalUs;
} VkLatencySleepModeInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
lowLatencyMode
is the toggle to enable or disable low latency mode. -
lowLatencyBoost
allows an application to hint to the GPU to increase performance to provide additional latency savings at a cost of increased power consumption. -
minimumIntervalUs
is the microseconds between vkQueuePresentKHR calls for a given swapchain that vkLatencySleepNV will enforce.
If lowLatencyMode
is set to VK_FALSE
, lowLatencyBoost
will
still hint to the GPU to increase its power state and vkLatencySleepNV
will still enforce minimumIntervalUs
between vkQueuePresentKHR
calls.
To provide the synchronization primitive used to delay host CPU work for lower latency rendering, call:
// Provided by VK_NV_low_latency2
VkResult vkLatencySleepNV(
VkDevice device,
VkSwapchainKHR swapchain,
const VkLatencySleepInfoNV* pSleepInfo);
-
device
is the device associated withswapchain
. -
swapchain
is the swapchain to delay associated CPU work based on VkLatencySubmissionPresentIdNV submissions. -
pSleepInfo
is a pointer to a VkLatencySleepInfoNV structure specifying the parameters of the latency sleep.
vkLatencySleepNV
returns immediately.
Applications should use vkWaitSemaphores with
pSleepInfo->signalSemaphore
to delay host CPU work.
CPU work refers to application work done before presenting which includes
but is not limited to: input sampling, simulation, command buffer recording,
command buffer submission, and present submission.
It is recommended to call this function before input sampling.
When using this function, it should be called exactly once between
presents.
The VkLatencySleepInfoNV
structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkLatencySleepInfoNV {
VkStructureType sType;
const void* pNext;
VkSemaphore signalSemaphore;
uint64_t value;
} VkLatencySleepInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
signalSemaphore
is a semaphore that is signaled to indicate that the application should resume input sampling work. -
value
is the value thatsignalSemaphore
is set to for resuming sampling work.
An application can provide timestamps at various stages of its frame generation work by calling:
// Provided by VK_NV_low_latency2
void vkSetLatencyMarkerNV(
VkDevice device,
VkSwapchainKHR swapchain,
const VkSetLatencyMarkerInfoNV* pLatencyMarkerInfo);
-
device
is the device associated withswapchain
. -
swapchain
is the swapchain to capture timestamps on. -
pSetLatencyMarkerInfo
is a pointer to a VkSetLatencyMarkerInfoNV structure specifying the parameters of the marker to set.
At the beginning and end of simulation and render threads and beginning and
end of vkQueuePresentKHR calls, vkSetLatencyMarkerNV
can be
called to provide timestamps for the application’s reference.
These timestamps are returned with a call to vkGetLatencyTimingsNV
alongside driver provided timestamps at various points of interest with
regards to latency within the application.
As an exception to the normal rules for objects which are externally
synchronized, the swapchain passed to vkSetLatencyMarkerNV
may be
simultaneously used by other threads in calls to functions other than
vkDestroySwapchainKHR.
Access to the swapchain data associated with this extension must be atomic
within the implementation.
The VkSetLatencyMarkerInfoNV
structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkSetLatencyMarkerInfoNV {
VkStructureType sType;
const void* pNext;
uint64_t presentID;
VkLatencyMarkerNV marker;
} VkSetLatencyMarkerInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
presentID
is an application provided value that is used to associate the timestamp with avkQueuePresentKHR
command using VkPresentIdKHR::pPresentIds
for a given present. -
marker
is the type of timestamp to be recorded.
The VkLatencyMarkerNV enum is defined as:
// Provided by VK_NV_low_latency2
typedef enum VkLatencyMarkerNV {
VK_LATENCY_MARKER_SIMULATION_START_NV = 0,
VK_LATENCY_MARKER_SIMULATION_END_NV = 1,
VK_LATENCY_MARKER_RENDERSUBMIT_START_NV = 2,
VK_LATENCY_MARKER_RENDERSUBMIT_END_NV = 3,
VK_LATENCY_MARKER_PRESENT_START_NV = 4,
VK_LATENCY_MARKER_PRESENT_END_NV = 5,
VK_LATENCY_MARKER_INPUT_SAMPLE_NV = 6,
VK_LATENCY_MARKER_TRIGGER_FLASH_NV = 7,
VK_LATENCY_MARKER_OUT_OF_BAND_RENDERSUBMIT_START_NV = 8,
VK_LATENCY_MARKER_OUT_OF_BAND_RENDERSUBMIT_END_NV = 9,
VK_LATENCY_MARKER_OUT_OF_BAND_PRESENT_START_NV = 10,
VK_LATENCY_MARKER_OUT_OF_BAND_PRESENT_END_NV = 11,
} VkLatencyMarkerNV;
The members of the VkLatencyMarkerNV are used as arguments for vkSetLatencyMarkerNV in the use cases described below:
-
VK_LATENCY_MARKER_SIMULATION_START_NV
should be called at the start of the simulation execution each frame, but after the call tovkLatencySleepNV
. -
VK_LATENCY_MARKER_SIMULATION_END_NV
should be called at the end of the simulation execution each frame. -
VK_LATENCY_MARKER_RENDERSUBMIT_START_NV
should be called at the beginning of the render submission execution each frame. This should be wherever Vulkan API calls are made and must not span into asynchronous rendering. -
VK_LATENCY_MARKER_RENDERSUBMIT_END_NV
should be called at the end of the render submission execution each frame. -
VK_LATENCY_MARKER_PRESENT_START_NV
should be called just beforevkQueuePresentKHR
. -
VK_LATENCY_MARKER_PRESENT_END_NV
should be called whenvkQueuePresentKHR
returns. -
VK_LATENCY_MARKER_INPUT_SAMPLE_NV
should be called just before the application gathers input data. -
VK_LATENCY_MARKER_TRIGGER_FLASH_NV
should be called anywhere betweenVK_LATENCY_MARKER_SIMULATION_START_NV
andVK_LATENCY_MARKER_SIMULATION_END_NV
whenever a left mouse click occurs.
To get an array containing the newest collected latency data, call:
// Provided by VK_NV_low_latency2
void vkGetLatencyTimingsNV(
VkDevice device,
VkSwapchainKHR swapchain,
VkGetLatencyMarkerInfoNV* pLatencyMarkerInfo);
-
device
is the device associated withswapchain
. -
swapchain
is the swapchain to return data from. -
pGetLatencyMarkerInfo
is a pointer to a VkGetLatencyMarkerInfoNV structure specifying the parameters for returning latency information.
The timings returned by vkGetLatencyTimingsNV
contain the timestamps
requested from vkSetLatencyMarkerNV and additional
implementation-specific markers defined in
VkLatencyTimingsFrameReportNV.
The VkGetLatencyMarkerInfoNV
structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkGetLatencyMarkerInfoNV {
VkStructureType sType;
const void* pNext;
uint32_t timingCount;
VkLatencyTimingsFrameReportNV* pTimings;
} VkGetLatencyMarkerInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
is eitherNULL
or a pointer to a structure extending this structure. -
timingCount
is an integer related to the number of previous frames of latency data available or queried, as described below. -
pTimings
is eitherNULL
or a pointer to an array of VkLatencyTimingsFrameReportNV structures.
If pTimings
is NULL
then the maximum number of queryable frame data
is returned in timingCount
.
Otherwise, timingCount
must be set by the application to the number
of elements in the pTimings
array, and on return the variable is
overwritten with the number of values actually written to pTimings
.
The elements of pTimings
are arranged in the order they were requested
in, with the oldest data in the first entry.
The VkLatencyTimingsFrameReportNV structure describes latency data returned by vkGetLatencyTimingsNV
// Provided by VK_NV_low_latency2
typedef struct VkLatencyTimingsFrameReportNV {
VkStructureType sType;
const void* pNext;
uint64_t presentID;
uint64_t inputSampleTimeUs;
uint64_t simStartTimeUs;
uint64_t simEndTimeUs;
uint64_t renderSubmitStartTimeUs;
uint64_t renderSubmitEndTimeUs;
uint64_t presentStartTimeUs;
uint64_t presentEndTimeUs;
uint64_t driverStartTimeUs;
uint64_t driverEndTimeUs;
uint64_t osRenderQueueStartTimeUs;
uint64_t osRenderQueueEndTimeUs;
uint64_t gpuRenderStartTimeUs;
uint64_t gpuRenderEndTimeUs;
} VkLatencyTimingsFrameReportNV;
The members of the VkLatencyTimingsFrameReportNV structure describe the following:
-
presentID
is the application provided value that is used to associate the timestamp with avkQueuePresentKHR
command using VkPresentIdKHR::pPresentIds
for a given present. -
simStartTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_SIMULATION_START_NV
. -
simEndTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_SIMULATION_END_NV
-
renderStartTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_RENDERSUBMIT_START_NV
. -
renderEndTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_RENDERSUBMIT_END_NV
. -
presentStartTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_PRESENT_START_NV
. -
presentEndTimeUs
is the timestamp written whenvkSetLatencyMarkerNV
is called with theVkLatencyMarkerNV
enumVK_LATENCY_MARKER_PRESENT_END_NV
. -
driverStartTimeUs
is the timestamp written when the firstvkQueueSubmit
for the frame is called. -
driverEndTimeUs
is the timestamp written when the finalvkQueueSubmit
hands off from the Vulkan Driver. -
osRenderQueueStartTimeUs
is the timestamp written when the finalvkQueueSubmit
hands off from the Vulkan Driver. -
osRenderQueueEndTimeUs
is the timestamp written when the first submission reaches the GPU. -
gpuRenderStartTimeUs
is the timestamp written when the first submission reaches the GPU. -
gpuRenderEndTimeUs
is the timestamp written when the final submission finishes on the GPU for the frame.
The VkLatencySubmissionPresentIdNV structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkLatencySubmissionPresentIdNV {
VkStructureType sType;
const void* pNext;
uint64_t presentID;
} VkLatencySubmissionPresentIdNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
presentID
is used to associate thevkQueueSubmit
with the presentId used for a givenvkQueuePresentKHR
via VkPresentIdKHR::pPresentIds
.
For any submission to be tracked with low latency mode pacing, it needs to
be associated with other submissions in a given present.
To associate a submission with presentID
for low latency mode, the
pNext
chain of vkQueueSubmit must include a
VkLatencySubmissionPresentIdNV
structure.
An application can mark a queue as Out of Band to indicate that all
vkQueueSubmit
calls on this queue are ignored for latency evaluation
by calling:
// Provided by VK_NV_low_latency2
void vkQueueNotifyOutOfBandNV(
VkQueue queue,
const VkOutOfBandQueueTypeInfoNV* pQueueTypeInfo);
-
queue
is the VkQueue to be marked as out of band. -
pQueueTypeInfo
is a pointer to a VkOutOfBandQueueTypeInfoNV structure specifying the queue type.
The VkOutOfBandQueueTypeInfoNV structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkOutOfBandQueueTypeInfoNV {
VkStructureType sType;
const void* pNext;
VkOutOfBandQueueTypeNV queueType;
} VkOutOfBandQueueTypeInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
queueType
describes the usage of the queue to be marked as out of band.
The VkOutOfBandQueueTypeNV enum is defined as:
// Provided by VK_NV_low_latency2
typedef enum VkOutOfBandQueueTypeNV {
VK_OUT_OF_BAND_QUEUE_TYPE_RENDER_NV = 0,
VK_OUT_OF_BAND_QUEUE_TYPE_PRESENT_NV = 1,
} VkOutOfBandQueueTypeNV;
The members of the VkOutOfBandQueueTypeNV are used to describe the queue type in VkOutOfBandQueueTypeInfoNV as described below:
-
VK_OUT_OF_BAND_QUEUE_TYPE_RENDER_NV
indicates that work will be submitted to this queue. -
VK_OUT_OF_BAND_QUEUE_TYPE_PRESENT_NV
indicates that this queue will be presented from.
To allow low latency mode to be used by a swapchain, add a
VkSwapchainLatencyCreateInfoNV
structure to the pNext
chain of
VkSwapchainCreateInfoKHR.
The VkSwapchainLatencyCreateInfoNV
structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkSwapchainLatencyCreateInfoNV {
VkStructureType sType;
const void* pNext;
VkBool32 latencyModeEnable;
} VkSwapchainLatencyCreateInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
lowLatencyModeEnable
indicates if the swapchain created will utilize low latency mode.
The VkLatencySurfaceCapabilitiesNV
structure is defined as:
// Provided by VK_NV_low_latency2
typedef struct VkLatencySurfaceCapabilitiesNV {
VkStructureType sType;
const void* pNext;
uint32_t presentModeCount;
VkPresentModeKHR* pPresentModes;
} VkLatencySurfaceCapabilitiesNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
presentModeCount
is the number of presentation modes provided. -
pPresentModes
is list of presentation modes optimized for use with low latency mode withpresentModeCount
entries.
If pPresentModes
is NULL
, then the number of present modes that are
optimized for use with low latency mode returned in presentModeCount
.
Otherwise, presentModeCount
must be set by the application 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 presentModeCount
is less than the number of optimized
present modes, at most presentModeCount
values will be written to
pPresentModes
.
Present Barrier
The VK_NV_present_barrier
extension allows applications to
synchronize corresponding presentation requests across multiple swapchains
using the present barrier.
A swapchain is said to be using the present barrier if the swapchain is
created by adding a VkSwapchainPresentBarrierCreateInfoNV structure to
the pNext
chain of the VkSwapchainCreateInfoKHR structure, and
setting
VkSwapchainPresentBarrierCreateInfoNV::presentBarrierEnable
to
true.
A set of corresponding presentation requests is defined as exactly one queued presentation request associated with each swapchain using the present barrier, whether or not that queued request has executed. A given presentation request is added, when created by calling vkQueuePresentKHR and specifying a swapchain using the present barrier, either to the oldest existing set of corresponding requests for which there is no existing member associated with the request’s swapchain, or to a new set of corresponding requests if no such set exists.
A set of corresponding requests is said to be full when it contains one request from each swapchain using the present barrier. Queued presentation of an image to a swapchain using the present barrier is deferred by the implementation until the set of corresponding requests is full, and the visibility operations associated with all requests in that set, as described by vkQueuePresentKHR, have completed.
Additionally, the set of swapchains using the present barrier can be in the same process, or different processes running under the same operating system. And if the required synchronization hardware is connected and correctly configured, this extension also supports applications to synchronize corresponding presentation requests using the present barrier across distributed systems. However, the configuration mechanism of the required hardware is outside the scope of the Vulkan specification and this extension.
The VkSwapchainPresentBarrierCreateInfoNV structure is defined as:
// Provided by VK_NV_present_barrier
typedef struct VkSwapchainPresentBarrierCreateInfoNV {
VkStructureType sType;
void* pNext;
VkBool32 presentBarrierEnable;
} VkSwapchainPresentBarrierCreateInfoNV;
-
sType
is a VkStructureType value identifying this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
presentBarrierEnable
is a boolean value indicating a request for using the present barrier.
If the pNext
chain of VkSwapchainCreateInfoKHR does not include
this structure, the default value for presentBarrierEnable
is
VK_FALSE
, meaning the swapchain does not request to use the present
barrier.
Additionally, when recreating a swapchain that was using the present
barrier, and the pNext
chain of VkSwapchainCreateInfoKHR does
not include this structure, it means the swapchain will stop using the
present barrier.