To query the basic capabilities of a surface, needed in order to create a swapchain, call:
VkResult vkGetPhysicalDeviceSurfaceCapabilitiesKHR( VkPhysicalDevice physicalDevice, VkSurfaceKHR surface, VkSurfaceCapabilitiesKHR* pSurfaceCapabilities);
physicalDevice
is the physical device that will be associated with
the swapchain to be created, as described for
vkCreateSwapchainKHR
.
surface
is the surface that will be associated with the swapchain.
pSurfaceCapabilities
is a pointer to an instance of the
VkSurfaceCapabilitiesKHR
structure in which the capabilities are
returned.
The VkSurfaceCapabilitiesKHR
structure is defined as:
typedef struct VkSurfaceCapabilitiesKHR { uint32_t minImageCount; uint32_t maxImageCount; VkExtent2D currentExtent; VkExtent2D minImageExtent; VkExtent2D maxImageExtent; uint32_t maxImageArrayLayers; VkSurfaceTransformFlagsKHR supportedTransforms; VkSurfaceTransformFlagBitsKHR currentTransform; VkCompositeAlphaFlagsKHR supportedCompositeAlpha; VkImageUsageFlags supportedUsageFlags; } VkSurfaceCapabilitiesKHR;
minImageCount
is the minimum number of images the specified device
supports for a swapchain created for the surface.
maxImageCount
is the maximum number of images the specified device
supports for a swapchain created for the surface.
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 swapchain 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.
maxImageExtent
contains the largest valid swapchain extent for the
surface on the specified device.
maxImageArrayLayers
is the maximum number of layers swapchain
images can have for a swapchain created for this device and surface.
supportedTransforms
is a bitmask of
VkSurfaceTransformFlagBitsKHR
, describing the presentation
transforms supported for the surface on the specified device.
currentTransform
is a bitmask of
VkSurfaceTransformFlagBitsKHR
, describing 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.
Opaque composition can be achieved in any alpha compositing mode by
either using a swapchain image format that has no alpha component, or by
ensuring that all pixels in the swapchain 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 for the surface on the specified device.
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
must be included in the set
but implementations may support additional usages.
![]() | Note |
---|---|
Formulas such as min(N, |
The supportedTransforms
and currentTransform
members are of type
VkSurfaceTransformFlagBitsKHR
, which contains the following values:
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;
These values are described as follows:
VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR
: The image content is
presented without being transformed.
VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR
: The image content is
rotated 90 degrees clockwise.
VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR
: The image content is
rotated 180 degrees clockwise.
VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR
: The image content is
rotated 270 degrees clockwise.
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR
: The image content
is mirrored horizontally.
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR
: The
image content is mirrored horizontally, then rotated 90 degrees
clockwise.
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR
: The
image content is mirrored horizontally, then rotated 180 degrees
clockwise.
VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR
: The
image content is mirrored horizontally, then rotated 270 degrees
clockwise.
VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR
: The presentation transform
is not specified, and is instead determined by platform-specific
considerations and mechanisms outside Vulkan.
The supportedCompositeAlpha
member is of type
VkCompositeAlphaFlagBitsKHR
, which contains the following values:
typedef enum VkCompositeAlphaFlagBitsKHR { VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR = 0x00000001, VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR = 0x00000002, VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR = 0x00000004, VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR = 0x00000008, } VkCompositeAlphaFlagBitsKHR;
These values are described as follows:
VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR
: The alpha channel, if it
exists, of the images is ignored in the compositing process.
Instead, the image is treated as if it has a constant alpha of 1.0.
VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR
: The alpha channel, if
it exists, of the images is respected in the compositing process.
The non-alpha channels of the image are expected to already be
multiplied by the alpha channel by the application.
VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR
: The alpha channel, if
it exists, of the images is respected in the compositing process.
The non-alpha channels of the image are not expected to already be
multiplied by the alpha channel by the application; instead, the
compositor will multiply the non-alpha channels of the image by the
alpha channel during compositing.
VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR
: The way in which the
presentation engine treats the alpha channel in the images is unknown to
the Vulkan API.
Instead, the application is responsible for setting the composite alpha
blending mode using native window system commands.
If the application does not set the blending mode using native window
system commands, then a platform-specific default will be used.
To query the supported swapchain format-color space pairs for a surface, call:
VkResult vkGetPhysicalDeviceSurfaceFormatsKHR( VkPhysicalDevice physicalDevice, VkSurfaceKHR surface, uint32_t* pSurfaceFormatCount, VkSurfaceFormatKHR* pSurfaceFormats);
physicalDevice
is the physical device that will be associated with
the swapchain to be created, as described for
vkCreateSwapchainKHR
.
surface
is the surface that will be associated with the swapchain.
pSurfaceFormatCount
is a pointer to an integer related to the
number of format pairs available or queried, as described below.
pSurfaceFormats
is either NULL
or a pointer to an array of
VkSurfaceFormatKHR
structures.
If pSurfaceFormats
is NULL
, then the number of format pairs
supported for the given surface
is returned in
pSurfaceFormatCount
.
Otherwise, pSurfaceFormatCount
must point to a variable set by the
user to the number of elements in the pSurfaceFormats
array, and on
return the variable is overwritten with the number of structures actually
written to pSurfaceFormats
.
If the value of pSurfaceFormatCount
is less than the number of format
pairs supported, at most pSurfaceFormatCount
structures will be
written.
If pSurfaceFormatCount
is smaller than the number of format pairs
supported for the given surface
, VK_INCOMPLETE
will be returned
instead of VK_SUCCESS
to indicate that not all the available values
were returned.
The VkSurfaceFormatKHR
structure is defined as:
typedef struct VkSurfaceFormatKHR { VkFormat format; VkColorSpaceKHR colorSpace; } VkSurfaceFormatKHR;
format
is a VkFormat
that is compatible with the specified
surface.
colorSpace
is a presentation VkColorSpaceKHR
that is
compatible with the surface.
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 combination of color
model (i.e. RGB, YUV, HSL etc.), the actual color space (defined by the
chromaticities of its primaries and a white point in CIE Lab), and a
transfer function that is applied before storing or transmitting color data
in the given color space.
The VkColorSpaceKHR
is defined as follows:
typedef enum VkColorSpaceKHR { VK_COLOR_SPACE_SRGB_NONLINEAR_KHR = 0, } VkColorSpaceKHR;
VK_COLOR_SPACE_SRGB_NONLINEAR_KHR
: The presentation engine
supports the sRGB color space.
![]() | Note |
---|---|
If |
![]() | Note |
---|---|
In the initial release of the |
To query the supported presentation modes for a surface, call:
VkResult vkGetPhysicalDeviceSurfacePresentModesKHR( VkPhysicalDevice physicalDevice, VkSurfaceKHR surface, uint32_t* pPresentModeCount, VkPresentModeKHR* pPresentModes);
physicalDevice
is the physical device that will be associated with
the swapchain to be created, as described for
vkCreateSwapchainKHR
.
surface
is the surface that will be associated with the swapchain.
pPresentModeCount
is a pointer to an integer related to the number
of presentation modes available or queried, as described below.
pPresentModes
is either NULL
or a pointer to an array of
VkPresentModeKHR
structures.
If pPresentModes
is NULL
, then the number of presentation modes
supported for the given surface
is returned in
pPresentModeCount
.
Otherwise, pPresentModeCount
must point to a variable set by the user
to the number of elements in the pPresentModes
array, and on return
the variable is overwritten with the number of values actually written to
pPresentModes
.
If the value of pPresentModeCount
is less than the number of
presentation modes supported, at most pPresentModeCount
values will be
written.
If pPresentModeCount
is smaller than the number of presentation modes
supported for the given surface
, VK_INCOMPLETE
will be returned
instead of VK_SUCCESS
to indicate that not all the available values
were returned.
The definition of VkPresentModeKHR
is:
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, } VkPresentModeKHR;
VK_PRESENT_MODE_IMMEDIATE_KHR
: 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
: The presentation engine waits for the
next vertical blanking period to update the current image.
Tearing cannot be observed.
An internal single-entry queue is used to hold pending presentation
requests.
If the queue is full when a new presentation request is received, the
new request replaces the existing entry, and any images associated with
the prior entry become available for re-use by the application.
One request is removed from the queue and processed during each vertical
blanking period in which the queue is non-empty.
VK_PRESENT_MODE_FIFO_KHR
: The presentation engine waits for the
next vertical blanking period to update the current image.
Tearing cannot be observed.
An internal queue is used to hold pending presentation requests.
New requests are appended to the end of the queue, and one request is
removed from the beginning of the queue and processed during each
vertical blanking period in which the queue is non-empty.
This is the only value of presentMode
that is required to be
supported.
VK_PRESENT_MODE_FIFO_RELAXED_KHR
: 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.
![]() | Note |
---|---|
For reference, the mode indicated by |