C Specification

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);

Parameters

  • 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 either NULL or a pointer to an array of VkSurfaceFormat2KHR structures.

Description

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 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 tuples supported, at most pSurfaceFormatCount structures will be written. If pSurfaceFormatCount is smaller than the number of format tuples supported for the surface parameters described in pSurfaceInfo, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage
Valid Usage (Implicit)
  • physicalDevice must be a valid VkPhysicalDevice handle

  • pSurfaceInfo must be a valid pointer to a valid VkPhysicalDeviceSurfaceInfo2KHR structure

  • pSurfaceFormatCount must be a valid pointer to a uint32_t value

  • If the value referenced by pSurfaceFormatCount is not 0, and pSurfaceFormats is not NULL, pSurfaceFormats must be a valid pointer to an array of pSurfaceFormatCount VkSurfaceFormat2KHR structures

Return Codes
On success, this command returns
  • VK_SUCCESS

  • VK_INCOMPLETE

On failure, this command returns
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_SURFACE_LOST_KHR

See Also

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0