C Specification
To enumerate the supported output, input and DPB image formats for a specific codec operation and video profile, call:
// Provided by VK_KHR_video_queue
VkResult vkGetPhysicalDeviceVideoFormatPropertiesKHR(
VkPhysicalDevice physicalDevice,
const VkPhysicalDeviceVideoFormatInfoKHR* pVideoFormatInfo,
uint32_t* pVideoFormatPropertyCount,
VkVideoFormatPropertiesKHR* pVideoFormatProperties);
Parameters
-
physicalDevice
is the physical device being queried. -
pVideoFormatInfo
is a pointer to a VkPhysicalDeviceVideoFormatInfoKHR structure specifying the codec and video profile for which information is 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 formats and image parameters 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 user 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.
If an implementation reports
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR
is
supported but
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR
is not
supported in VkVideoDecodeCapabilitiesKHR::flags
, then to query
for video format properties for decode DPB or output,
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage
must have both
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR
and
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR
set.
Otherwise, the call will fail with
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR
.
If an implementation reports
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR
is
supported but
VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR
is not
supported in VkVideoDecodeCapabilitiesKHR::flags
, then to query
for video format properties for decode DPB,
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage
must have
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR
set and
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR
not set.
Otherwise, the call will fail with
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR
.
Similarly, to query for video format properties for decode output,
VkPhysicalDeviceVideoFormatInfoKHR::imageUsage
must have
VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR
set and
VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR
not set.
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.
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. |
Video format properties are always queried with respect to a specific set of
video profiles, as defined by the VkVideoProfileKHR structure.
These are specified by chaining the VkVideoProfilesKHR 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 transcode, 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 profiles specified via
VkVideoProfilesKHR::pProfiles
are not supported, then
vkGetPhysicalDeviceVideoFormatPropertiesKHR
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 vkGetPhysicalDeviceVideoFormatPropertiesKHR
returns
VK_ERROR_IMAGE_USAGE_NOT_SUPPORTED_KHR
.
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 VkVideoProfilesKHR structure to the
pNext
chain of VkPhysicalDeviceImageFormatInfo2.
The componentMapping
member of VkVideoFormatPropertiesKHR
defines the ordering of the Y′CBCR color channels from the perspective of
the video codec operations specified in VkVideoProfilesKHR
.
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.