vkGetPhysicalDeviceVideoFormatPropertiesKHR

To enumerate the supported output, input and DPB image formats and corresponding capabilities for a specific video profile, call:

VkResult vkGetPhysicalDeviceVideoFormatPropertiesKHR(
    VkPhysicalDevice physicalDevice,
    const VkPhysicalDeviceVideoFormatInfoKHR* pVideoFormatInfo,
    uint32_t* pVideoFormatPropertyCount,
    VkVideoFormatPropertiesKHR* pVideoFormatProperties);

• physicalDevice is the physical device from which to query the video format properties.
• pVideoFormatInfo is a pointer to a VkPhysicalDeviceVideoFormatInfoKHR structure specifying the usage and video profiles for which supported image formats and capabilities are returned.
• pVideoFormatPropertyCount is a pointer to an integer related to the number of video format properties available or queried, as described below.
• pVideoFormatProperties is a pointer to an array of VkVideoFormatPropertiesKHR structures in which supported image formats and capabilities are returned.

If pVideoFormatProperties is NULL, then the number of video format properties supported for the given physicalDevice is returned in pVideoFormatPropertyCount. Otherwise, pVideoFormatPropertyCount must point to a variable set by the application to the number of elements in the pVideoFormatProperties array, and on return the variable is overwritten with the number of values actually written to pVideoFormatProperties. If the value of pVideoFormatPropertyCount is less than the number of video format properties supported, at most pVideoFormatPropertyCount values will be written to pVideoFormatProperties, and VK_INCOMPLETE will be returned instead of VK_SUCCESS, to indicate that not all the available values were returned.

Video format properties are always queried with respect to a specific set of video profiles. These are specified by chaining the VkVideoProfileListInfoKHR structure to pVideoFormatInfo.

For most use cases, the images are used by a single video session and a single video profile is provided. For a use case such as video transcoding, where a decode session output image can be used as encode input in one or more encode sessions, multiple video profiles corresponding to the video sessions that will share the image must be provided.

If any of the video profiles specified via VkVideoProfileListInfoKHR::pProfiles are not supported, then this command returns one of the video-profile-specific error codes. Furthermore, if VkPhysicalDeviceVideoFormatInfoKHR::imageUsage includes any image usage flags not supported by the specified video profiles, then this command returns VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.

This command also returns VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR if VkPhysicalDeviceVideoFormatInfoKHR::imageUsage does not include the appropriate flags as dictated by the decode capability flags returned in VkVideoDecodeCapabilitiesKHR::flags for any of the profiles specified in the VkVideoProfileListInfoKHR structure provided in the pNext chain of pVideoFormatInfo.

If the decode capability flags include VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR but not VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR, then in order to query video format properties for decode DPB and output usage, VkPhysicalDeviceVideoFormatInfoKHR::imageUsage must include both VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR and VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR. Otherwise, the call will fail with VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.

If the decode capability flags include VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR but not VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR, then in order to query video format properties for decode DPB usage, VkPhysicalDeviceVideoFormatInfoKHR::imageUsage must include VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, but not VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR. Otherwise, the call will fail with VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR. Similarly, to query video format properties for decode output usage, VkPhysicalDeviceVideoFormatInfoKHR::imageUsage must include VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, but not VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR. Otherwise, the call will fail with VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR.

The imageUsage member of the VkPhysicalDeviceVideoFormatInfoKHR structure specifies the expected video usage flags that the returned video formats must support. Correspondingly, the imageUsageFlags member of each VkVideoFormatPropertiesKHR structure returned will contain at least the same set of image usage flags.

If the implementation supports using video input, output, or DPB images of a particular format in operations other than video decode/encode then the imageUsageFlags member of the corresponding VkVideoFormatPropertiesKHR structure returned will include additional image usage flags indicating that.

Multiple VkVideoFormatPropertiesKHR entries may be returned with the same format member with different componentMapping, imageType, or imageTiling values, as described later.

In addition, a different set of VkVideoFormatPropertiesKHR entries may be returned depending on the imageUsage member of the VkPhysicalDeviceVideoFormatInfoKHR structure, even for the same set of video profiles, for example, based on whether encode input, encode DPB, decode output, and/or decode DPB usage is requested.

The application can select the parameters returned in the VkVideoFormatPropertiesKHR entries and use compatible parameters when creating the input, output, and DPB images. The implementation will report all image creation and usage flags that are valid for images used with the requested video profiles but applications should create images only with those that are necessary for the particular use case.

Before creating an image, the application can obtain the complete set of supported image format features by calling vkGetPhysicalDeviceImageFormatProperties2 using parameters derived from the members of one of the reported VkVideoFormatPropertiesKHR entries and adding the same VkVideoProfileListInfoKHR structure to the pNext chain of VkPhysicalDeviceImageFormatInfo2.

The following applies to all VkVideoFormatPropertiesKHR entries returned by vkGetPhysicalDeviceVideoFormatPropertiesKHR:

• vkGetPhysicalDeviceFormatProperties2 must succeed when called with VkVideoFormatPropertiesKHR::format
• If VkVideoFormatPropertiesKHR::imageTiling is VK_IMAGE_TILING_OPTIMAL, then the optimalTilingFeatures returned by vkGetPhysicalDeviceFormatProperties2 must include all format features required by the image usage flags reported in VkVideoFormatPropertiesKHR::imageUsageFlags for the format, as indicated in the Format Feature Dependent Usage Flags section.
• If VkVideoFormatPropertiesKHR::imageTiling is VK_IMAGE_TILING_LINEAR, then the linearTilingFeatures returned by vkGetPhysicalDeviceFormatProperties2 must include all format features required by the image usage flags reported in VkVideoFormatPropertiesKHR::imageUsageFlags for the format, as indicated in the Format Feature Dependent Usage Flags section.
• vkGetPhysicalDeviceImageFormatProperties2 must succeed when called with a VkPhysicalDeviceImageFormatInfo2 structure containing the following information:
  • The pNext chain including the same VkVideoProfileListInfoKHR structure used to call vkGetPhysicalDeviceVideoFormatPropertiesKHR.
  • format set to the value of VkVideoFormatPropertiesKHR::format.
  • type set to the value of VkVideoFormatPropertiesKHR::imageType.
  • tiling set to the value of VkVideoFormatPropertiesKHR::imageTiling.
  • usage set to the value of VkVideoFormatPropertiesKHR::imageUsageFlags.
  • flags set to the value of VkVideoFormatPropertiesKHR::imageCreateFlags.

The componentMapping member of VkVideoFormatPropertiesKHR defines the ordering of the Y′C_BC_R color channels from the perspective of the video codec operations specified in VkVideoProfileListInfoKHR. For example, if the implementation produces video decode output with the format VK_FORMAT_G8_B8R8_2PLANE_420_UNORM where the blue and red chrominance channels are swapped then the componentMapping member of the corresponding VkVideoFormatPropertiesKHR structure will have the following member values:

components.r = VK_COMPONENT_SWIZZLE_B;        // Cb component
components.g = VK_COMPONENT_SWIZZLE_IDENTITY; // Y component
components.b = VK_COMPONENT_SWIZZLE_R;        // Cr component
components.a = VK_COMPONENT_SWIZZLE_IDENTITY; // unused, defaults to 1.0