C Specification
To enumerate the supported video formats and corresponding capabilities for a specific video profile, call:
// Provided by VK_KHR_video_queue
VkResult vkGetPhysicalDeviceVideoFormatPropertiesKHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceVideoFormatInfoKHR* pVideoFormatInfo,
uint32_t* pVideoFormatPropertyCount,
VkVideoFormatPropertiesKHR* pVideoFormatProperties);
Parameters
-
physicalDeviceis the physical device from which to query the video format properties. -
pVideoFormatInfois a pointer to a VkPhysicalDeviceVideoFormatInfoKHR structure specifying the usage and video profiles for which supported image formats and capabilities are returned. -
pVideoFormatPropertyCountis a pointer to an integer related to the number of video format properties available or queried, as described below. -
pVideoFormatPropertiesis a pointer to an array of VkVideoFormatPropertiesKHR structures in which supported image formats and capabilities are returned.
Description
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 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.
|
Note
|
For most use cases, only decode or encode related usage flags are going to be specified. For a use case such as transcode, if the image were to be shared between decode and encode session(s), then both decode and encode related usage flags can be set. |
Multiple VkVideoFormatPropertiesKHR entries may be returned with the
same format member with different componentMapping,
imageType, or imageTiling values, as described later.
If VkPhysicalDeviceVideoFormatInfoKHR::imageUsage includes
VK_IMAGE_USAGE_VIDEO_ENCODE_QUANTIZATION_DELTA_MAP_BIT_KHR or
VK_IMAGE_USAGE_VIDEO_ENCODE_EMPHASIS_MAP_BIT_KHR, multiple
VkVideoFormatPropertiesKHR entries may be returned with the same
format, componentMapping, imageType, and imageTiling
member values, but different quantizationMapTexelSize returned in the
VkVideoFormatQuantizationMapPropertiesKHR structure, if one is
included in the VkVideoFormatPropertiesKHR::pNext chain, when
the queried quantization map type supports
multiple distinct quantization map
texel sizes.
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::imageTilingisVK_IMAGE_TILING_OPTIMAL, then theoptimalTilingFeaturesreturned by vkGetPhysicalDeviceFormatProperties2 must include all format features required by the image usage flags reported inVkVideoFormatPropertiesKHR::imageUsageFlagsfor the format, as indicated in the Format Feature Dependent Usage Flags section. -
If
VkVideoFormatPropertiesKHR::imageTilingisVK_IMAGE_TILING_LINEAR, then thelinearTilingFeaturesreturned by vkGetPhysicalDeviceFormatProperties2 must include all format features required by the image usage flags reported inVkVideoFormatPropertiesKHR::imageUsageFlagsfor 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
pNextchain including the same VkVideoProfileListInfoKHR structure used to callvkGetPhysicalDeviceVideoFormatPropertiesKHR. -
formatset to the value ofVkVideoFormatPropertiesKHR::format. -
typeset to the value ofVkVideoFormatPropertiesKHR::imageType. -
tilingset to the value ofVkVideoFormatPropertiesKHR::imageTiling. -
usageset to the value ofVkVideoFormatPropertiesKHR::imageUsageFlags. -
flagsset to the value ofVkVideoFormatPropertiesKHR::imageCreateFlags.
-
The componentMapping member of VkVideoFormatPropertiesKHR
defines the ordering of the Y′CBCR 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
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.