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 bitfield of
VkSurfaceTransformFlagBitsKHR
, describing the presentation
transforms supported for the surface on the specified device.
currentTransform
is a bitfield of
VkSurfaceTransformFlagBitsKHR
, describing the surface’s current
transform relative to the presentation engine’s natural orientation.
supportedCompositeAlpha
is a bitfield 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 bitfield 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.
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-colorspace 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 the presentation engine interprets the pixel values. A
colorspace in this document refers to a specific combination of color model
(i.e. RGB, YUV, HSL etc.), the actual colorspace (defined by the
chromaticities of its primaries and a whitepoint in CIE Lab), and a transfer
function that is applied before storing or transmitting color data in the
given colorspace.
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 colorspace.
![]() | Note |
---|---|
If |
![]() | Note |
---|---|
In the initial release of the VK_KHR_surface and VK_KHR_swapchain
extensions, the token |
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 occassionally be late, and
present a new image just after the 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 |