C Specification

To begin a video coding scope, call:

// Provided by VK_KHR_video_queue
void vkCmdBeginVideoCodingKHR(
    VkCommandBuffer                             commandBuffer,
    const VkVideoBeginCodingInfoKHR*            pBeginInfo);

Parameters

  • 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.

Description

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.

Note

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.

Note

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.

Note

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

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

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

Primary

Outside

Outside

Decode
Encode

Action
State

See Also

VK_KHR_video_queue, VkCommandBuffer, VkVideoBeginCodingInfoKHR

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.

Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0