## 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).