vkCmdBeginVideoCodingKHR(3)

# vkCmdBeginVideoCodingKHR(3) Manual Page

## Name

vkCmdBeginVideoCodingKHR - Begin video coding scope

Loading… please wait.

## 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-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0