VulkanHub
Function Prototype

vkCmdBeginVideoCodingKHR

Begin video coding scope
primary
outside
outside
decode / encode
action / state

To begin a video coding scope, call:

void vkCmdBeginVideoCodingKHR(
    VkCommandBuffer commandBuffer,
    const VkVideoBeginCodingInfoKHR* pBeginInfo);
  • commandBuffer is the command buffer in which to record the command.
  • pBeginInfo is a pointer to a VkVideoBeginCodingInfoKHR structure specifying the parameters of the video coding scope, including the video session and video session parameters object to use.

After beginning a video coding scope, the video session object specified in pBeginInfo→videoSession is bound to the command buffer, and the command buffer is ready to record video coding operations. Similarly, if pBeginInfo→videoSessionParameters is not VK_NULL_HANDLE, it is also bound to the command buffer, and video coding operations can refer to the codec-specific parameters stored in it.

This command also establishes the set of bound reference picture resources that can be used as reconstructed pictures or reference pictures within the video coding scope. Each element of this set consists of a video picture resource and the DPB slot index associated with it, if there is one.

The set of bound reference picture resources is immutable within a video coding scope, however, the DPB slot index associated with any of the bound reference picture resources can change during the video coding scope in response to video coding operations.

The VkVideoReferenceSlotInfoKHR structures provided as the elements of pBeginInfo→pReferenceSlots are interpreted by this command as follows:

  • If slotIndex is non-negative and pPictureResource is not NULL, then the video picture resource defined by the VkVideoPictureResourceInfoKHR structure pointed to by pPictureResource is added to the set of bound reference picture resources and is associated with the DPB slot index specified in slotIndex.
  • If slotIndex is non-negative and pPictureResource is NULL, then the DPB slot with index slotIndex is deactivated by this command.
  • If slotIndex is negative and pPictureResource is not NULL, then the video picture resource defined by the VkVideoPictureResourceInfoKHR structure pointed to by pPictureResource is added to the set of bound reference picture resources without an associated DPB slot. Such a picture resource can be subsequently used as a reconstructed picture to associate it with a DPB slot.
  • If slotIndex is negative and pPictureResource is NULL, then the element is ignored.

It is possible for multiple bound reference picture resources to be associated with the same DPB slot index, or for a single bound reference picture to refer to multiple separate reference pictures. For example, in case of an H.264 decode profile with interlaced frame support a single DPB slot can refer to two separate pictures for the top and bottom fields. Depending on the picture layout used by the H.264 decode profile, the following special cases may arise:

  • If the picture layout is VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_INTERLEAVED_LINES_BIT_KHR, then the top and bottom field pictures are physically co-located in the same video picture resource with even scanlines corresponding to the top field and odd scanlines corresponding to the bottom field, respectively.
  • If the picture layout is VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_KHR, then the top and bottom field pictures are stored in separate video picture resources (in separate subregions of the same image layer, in separate layers of the same image, or in entirely separate images), hence two elements of VkVideoBeginCodingInfoKHR::pReferenceSlots can contain the same slotIndex but specify different video picture resources in their pPictureResource members.

All non-negative slotIndex values specified in the elements of pBeginInfo→pReferenceSlots must identify DPB slots of the video session that are in the active state at the time this command is executed on the device.

The application does not have to specify an entry in pBeginInfo→pReferenceSlots corresponding to all active DPB slots of the video session, but only for those which are intended to be used in the video coding scope. This way the application can avoid any potential runtime cost associated with binding the corresponding picture resources to the command buffer.

In case of a video encode session, the application is also responsible for providing information about the current rate control state configured for the video session by including an instance of the VkVideoEncodeRateControlInfoKHR structure in the pNext chain of pBeginInfo. If no VkVideoEncodeRateControlInfoKHR is included, then the presence of an empty VkVideoEncodeRateControlInfoKHR structure is implied which indicates that the current rate control mode is VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR. The specified state must match the effective rate control state configured for the video session at the time the recorded command is executed on the device.

Including an instance of the VkVideoEncodeRateControlInfoKHR structure in the pNext chain of pBeginInfo does not change the rate control state configured for the video session, but only specifies the expected rate control state configured at the time the recorded command is executed on the device which allows the implementation to have information about the configured rate control state at command buffer recording time. In order to change the current rate control state of a video session, the application has to issue an appropriate vkCmdControlVideoCodingKHR command as described in the Video Coding Control and Rate Control State sections.

Valid Usage

VUID-vkCmdBeginVideoCodingKHR-commandBuffer-07231

The VkCommandPool that commandBuffer was allocated from must support the video codec operation pBeginInfo→videoSession was created with, as returned by vkGetPhysicalDeviceQueueFamilyProperties2 in VkQueueFamilyVideoPropertiesKHR::videoCodecOperations

VUID-vkCmdBeginVideoCodingKHR-None-07232

There must be no active queries

VUID-vkCmdBeginVideoCodingKHR-commandBuffer-07233

If commandBuffer is an unprotected command buffer and protectedNoFault is not supported, then pBeginInfo→videoSession must not have been created with VK_VIDEO_SESSION_CREATE_PROTECTED_CONTENT_BIT_KHR

VUID-vkCmdBeginVideoCodingKHR-commandBuffer-07234

If commandBuffer is a protected command buffer and protectedNoFault is not supported, then pBeginInfo→videoSession must have been created with VK_VIDEO_SESSION_CREATE_PROTECTED_CONTENT_BIT_KHR

VUID-vkCmdBeginVideoCodingKHR-commandBuffer-07235

If commandBuffer is an unprotected command buffer, protectedNoFault is not supported, and the pPictureResource member of any element of pBeginInfo→pReferenceSlots is not NULL, then pPictureResource→imageViewBinding for that element must not specify an image view created from a protected image

VUID-vkCmdBeginVideoCodingKHR-commandBuffer-07236

If commandBuffer is a protected command buffer protectedNoFault is not supported, and the pPictureResource member of any element of pBeginInfo→pReferenceSlots is not NULL, then pPictureResource→imageViewBinding for that element must specify an image view created from a protected image

VUID-vkCmdBeginVideoCodingKHR-slotIndex-07239

If the slotIndex member of any element of pBeginInfo→pReferenceSlots is not negative, then it must specify the index of a DPB slot that is in the active state in pBeginInfo→videoSession at the time the command is executed on the device

VUID-vkCmdBeginVideoCodingKHR-pPictureResource-07265

Each video picture resource specified by any non-NULL

pPictureResource member specified in the elements of pBeginInfo→pReferenceSlots for which slotIndex is not negative must match one of the video picture resources currently associated with the DPB slot index of pBeginInfo→videoSession specified by slotIndex at the time the command is executed on the device

VUID-vkCmdBeginVideoCodingKHR-pBeginInfo-08253

If pBeginInfo→videoSession was created with a video encode operation and the pNext chain of pBeginInfo does not include an instance of the VkVideoEncodeRateControlInfoKHR structure, then the rate control mode configured for pBeginInfo→videoSession at the time the command is executed on the device must be VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR

VUID-vkCmdBeginVideoCodingKHR-pBeginInfo-08254

If pBeginInfo→videoSession was created with a video encode operation and the pNext chain of pBeginInfo includes an instance of the VkVideoEncodeRateControlInfoKHR structure, then it must match the rate control state configured for pBeginInfo→videoSession at the time the command is executed on the device

VUID-vkCmdBeginVideoCodingKHR-pBeginInfo-08255

If pBeginInfo→videoSession was created with the video codec operation VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, the current rate control mode is not VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR or VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, and VkVideoEncodeH264CapabilitiesKHR::requiresGopRemainingFrames is VK_TRUE, as returned by vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the pBeginInfo→videoSession was created with, then the pNext chain of pBeginInfo must include an instance of the VkVideoEncodeH264GopRemainingFrameInfoKHR with its useGopRemainingFrames member set to VK_TRUE

VUID-vkCmdBeginVideoCodingKHR-pBeginInfo-08256

If pBeginInfo→videoSession was created with the video codec operation VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, the current rate control mode is not VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR or VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, and VkVideoEncodeH265CapabilitiesKHR::requiresGopRemainingFrames is VK_TRUE, as returned by vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the pBeginInfo→videoSession was created with, then the pNext chain of pBeginInfo must include an instance of the VkVideoEncodeH265GopRemainingFrameInfoKHR with its useGopRemainingFrames member set to VK_TRUE

VUID-vkCmdBeginVideoCodingKHR-pBeginInfo-10282

If pBeginInfo→videoSession was created with the video codec operation VK_VIDEO_CODEC_OPERATION_ENCODE_AV1_BIT_KHR, the current rate control mode is not VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR or VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, and VkVideoEncodeAV1CapabilitiesKHR::requiresGopRemainingFrames is VK_TRUE, as returned by vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the pBeginInfo→videoSession was created with, then the pNext chain of pBeginInfo must include an instance of the VkVideoEncodeAV1GopRemainingFrameInfoKHR with its useGopRemainingFrames member set to VK_TRUE

Valid Usage (Implicit)

VUID-vkCmdBeginVideoCodingKHR-commandBuffer-parameter

commandBuffer must be a valid VkCommandBuffer handle

VUID-vkCmdBeginVideoCodingKHR-pBeginInfo-parameter

pBeginInfo must be a valid pointer to a valid VkVideoBeginCodingInfoKHR structure

VUID-vkCmdBeginVideoCodingKHR-commandBuffer-recording

commandBuffer must be in the recording state

VUID-vkCmdBeginVideoCodingKHR-commandBuffer-cmdpool

The VkCommandPool that commandBuffer was allocated from must support decode, or encode operations

VUID-vkCmdBeginVideoCodingKHR-renderpass

This command must only be called outside of a render pass instance

VUID-vkCmdBeginVideoCodingKHR-videocoding

This command must only be called outside of a video coding scope

VUID-vkCmdBeginVideoCodingKHR-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 ::