## 29.5. Surface Queries

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, maxImageCount) are not correct, since maxImageCount may be zero.

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 pSurfaceFormats includes just one entry, whose value for format is VK_FORMAT_UNDEFINED, surface has no preferred format. In this case, the application can use any valid VkFormat value.
Note In the initial release of the VK_KHR_surface and VK_KHR_swapchain extensions, the token VK_COLORSPACE_SRGB_NONLINEAR_KHR was used. Starting in the May 13, 2016 updates to the extension branches, matching release 1.0.13 of the core API specification, VK_COLOR_SPACE_SRGB_NONLINEAR_KHR is used instead for consistency with Vulkan naming rules. The older enum is still available for backwards compatibility.

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 VK_PRESENT_MODE_FIFO_KHR is equivalent to the behavior of {wgl|glX|egl}SwapBuffers with a swap interval of 1, while the mode indicated by VK_PRESENT_MODE_FIFO_RELAXED_KHR is equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval of -1 (from the {WGL|GLX}_EXT_swap_control_tear extensions).