vkCmdDecodeVideoKHR(3)

Name

vkCmdDecodeVideoKHR - Launch a video decode operation

C Specification

To launch video decode operations, call:

// Provided by VK_KHR_video_decode_queue
void vkCmdDecodeVideoKHR(
    VkCommandBuffer                             commandBuffer,
    const VkVideoDecodeInfoKHR*                 pDecodeInfo);

Parameters

  • commandBuffer is the command buffer in which to record the command.

  • pDecodeInfo is a pointer to a VkVideoDecodeInfoKHR structure specifying the parameters of the video decode operations.

Description

Each call issues one or more video decode operations. The implicit parameter opCount corresponds to the number of video decode operations issued by the command. After calling this command, the active query index of each active query is incremented by opCount.

Currently each call to this command results in the issue of a single video decode operation.

If the bound video session was created with VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR and the pNext chain of pDecodeInfo includes a VkVideoInlineQueryInfoKHR structure with its queryPool member specifying a valid VkQueryPool handle, then this command will execute a query for each video decode operation issued by it.

Active Reference Picture Information

The list of active reference pictures used by a video decode operation is a list of image subregions used as the source of reference picture data and related parameters, and is derived from the VkVideoReferenceSlotInfoKHR structures provided as the elements of the pDecodeInfo->pReferenceSlots array. For each element of pDecodeInfo->pReferenceSlots, one or more elements are added to the active reference picture list, as defined by the codec-specific semantics. Each element of this list contains the following information:

  • The image subregion within the image subresource referred to by the video picture resource used as the reference picture.

  • The DPB slot index the reference picture is associated with.

  • The codec-specific reference information related to the reference picture.

Reconstructed Picture Information

Information related to the optional reconstructed picture used by a video decode operation is derived from the VkVideoReferenceSlotInfoKHR structure pointed to by pDecodeInfo->pSetupReferenceSlot, if not NULL, as defined by the codec-specific semantics, and consists of the following:

  • The image subregion within the image subresource referred to by the video picture resource used as the reconstructed picture.

  • The DPB slot index to use for picture reconstruction.

  • The codec-specific reference information related to the reconstructed picture.

Specifying a valid VkVideoReferenceSlotInfoKHR structure in pDecodeInfo->pSetupReferenceSlot is always required, unless the video session was created with VkVideoSessionCreateInfoKHR::maxDpbSlots equal to zero. However, the DPB slot identified by pDecodeInfo->pSetupReferenceSlot→slotIndex is only activated with the reconstructed picture specified in pDecodeInfo->pSetupReferenceSlot→pPictureResource if reference picture setup is requested according to the codec-specific semantics.

If reconstructed picture information is specified, and pDecodeInfo->pSetupReferenceSlot→pPictureResource refers to a video picture resource different than that of the decode output picture, but reference picture setup is not requested, the contents of the video picture resource corresponding to the reconstructed picture will be undefined after the video decode operation.

Some implementations may always output the reconstructed picture or use it as temporary storage during the video decode operation even when the reconstructed picture is not marked for future reference.
Decode Output Picture Information

Information related to the decode output picture used by a video decode operation is derived from pDecodeInfo->dstPictureResource and any codec-specific parameters provided in the pDecodeInfo->pNext chain, as defined by the codec-specific semantics, and consists of the following:

  • The image subregion within the image subresource referred to by the video picture resource used as the decode output picture.

  • The codec-specific picture information related to the decode output picture.

Several limiting values are defined below that are referenced by the relevant valid usage statements of this command.

  • Let uint32_t activeReferencePictureCount be the size of the list of active reference pictures used by the video decode operation. Unless otherwise defined, activeReferencePictureCount is set to the value of pDecodeInfo->referenceSlotCount.

    • If the bound video session was created with an H.264 decode profile, then let activeReferencePictureCount be the value of pDecodeInfo->referenceSlotCount plus the number of elements of the pDecodeInfo->pReferenceSlots array that have a VkVideoDecodeH264DpbSlotInfoKHR structure included in their pNext chain with both pStdReferenceInfo->flags.top_field_flag and pStdReferenceInfo->flags.bottom_field_flag set.

      This means that the elements of pDecodeInfo->pReferenceSlots that include both a top and bottom field reference are counted as two separate active reference pictures, as described in the active reference picture list construction rules for H.264 decode operations.

  • Let VkOffset2D codedOffsetGranularity be the minimum alignment requirement for the coded offset of video picture resources. Unless otherwise defined, the value of the x and y members of codedOffsetGranularity are 0.

  • Let uint32_t dpbFrameUseCount[] be an array of size maxDpbSlots, where maxDpbSlots is the VkVideoSessionCreateInfoKHR::maxDpbSlots the bound video session was created with, with each element indicating the number of times a frame associated with the corresponding DPB slot index is referred to by the video coding operation. Let the initial value of each element of the array be 0.

    • If pDecodeInfo->pSetupReferenceSlot is not NULL, then dpbFrameUseCount[i] is incremented by one, where i equals pDecodeInfo->pSetupReferenceSlot→slotIndex. If the bound video session object was created with an H.264 decode profile, then dpbFrameUseCount[i] is decremented by one if either pStdReferenceInfo->flags.top_field_flag or pStdReferenceInfo->flags.bottom_field_flag is set in the VkVideoDecodeH264DpbSlotInfoKHR structure in the pDecodeInfo->pSetupReferenceSlot→pNext chain.

    • For each element of pDecodeInfo->pReferenceSlots, dpbFrameUseCount[i] is incremented by one, where i equals the slotIndex member of the corresponding element. If the bound video session object was created with an H.264 decode profile, then dpbFrameUseCount[i] is decremented by one if either pStdReferenceInfo->flags.top_field_flag or pStdReferenceInfo->flags.bottom_field_flag is set in the VkVideoDecodeH264DpbSlotInfoKHR structure in the pNext chain of the corresponding element of pDecodeInfo->pReferenceSlots.

  • Let uint32_t dpbTopFieldUseCount[] and uint32_t dpbBottomFieldUseCount[] be arrays of size maxDpbSlots, where maxDpbSlots is the VkVideoSessionCreateInfoKHR::maxDpbSlots the bound video session was created with, with each element indicating the number of times the top field or the bottom field, respectively, associated with the corresponding DPB slot index is referred to by the video coding operation. Let the initial value of each element of the arrays be 0.

    • If the bound video session object was created with an H.264 decode profile and pDecodeInfo->pSetupReferenceSlot is not NULL, then perform the following:

      • If pStdReferenceInfo->flags.top_field_flag is set in the VkVideoDecodeH264DpbSlotInfoKHR structure in the pDecodeInfo->pSetupReferenceSlot→pNext chain, then dpbTopFieldUseCount[i] is incremented by one, where i equals pDecodeInfo->pSetupReferenceSlot→slotIndex.

      • If pStdReferenceInfo->flags.bottom_field_flag is set in the VkVideoDecodeH264DpbSlotInfoKHR structure in the pDecodeInfo->pSetupReferenceSlot→pNext chain, then dpbBottomFieldUseCount[i] is incremented by one, where i equals pDecodeInfo->pSetupReferenceSlot→slotIndex.

    • If the bound video session object was created with an H.264 decode profile, then perform the following for each element of pDecodeInfo->pReferenceSlots:

      • If pStdReferenceInfo->flags.top_field_flag is set in the VkVideoDecodeH264DpbSlotInfoKHR structure in the pNext chain of the element, then dpbTopFieldUseCount[i] is incremented by one, where i equals the slotIndex member of the element.

      • If pStdReferenceInfo->flags.bottom_field_flag is set in the VkVideoDecodeH264DpbSlotInfoKHR structure in the pNext chain of the element, then dpbBottomFieldUseCount[i] is incremented by one, where i equals the slotIndex member of the element.

Valid Usage
Valid Usage (Implicit)

  • VUID-vkCmdDecodeVideoKHR-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdDecodeVideoKHR-pDecodeInfo-parameter
    pDecodeInfo must be a valid pointer to a valid VkVideoDecodeInfoKHR structure

  • VUID-vkCmdDecodeVideoKHR-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdDecodeVideoKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_VIDEO_DECODE_BIT_KHR operations

  • VUID-vkCmdDecodeVideoKHR-renderpass
    This command must only be called outside of a render pass instance

  • VUID-vkCmdDecodeVideoKHR-suspended
    This command must not be called between suspended render pass instances

  • VUID-vkCmdDecodeVideoKHR-videocoding
    This command must only be called inside of a video coding scope

  • VUID-vkCmdDecodeVideoKHR-bufferlevel
    commandBuffer must be a primary VkCommandBuffer

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties
Command Buffer Levels Render Pass Scope Video Coding Scope Supported Queue Types Command Type

Primary

Outside

Inside

VK_QUEUE_VIDEO_DECODE_BIT_KHR

Action
Conditional Rendering

vkCmdDecodeVideoKHR is not affected by conditional rendering

See Also

VK_KHR_video_decode_queue, VkCommandBuffer, VkVideoDecodeInfoKHR

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.