C Specification

To launch video encode operations, call:

// Provided by VK_KHR_video_encode_queue
void vkCmdEncodeVideoKHR(
    VkCommandBuffer                             commandBuffer,
    const VkVideoEncodeInfoKHR*                 pEncodeInfo);

Parameters

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

  • pEncodeInfo is a pointer to a VkVideoEncodeInfoKHR structure specifying the parameters of the video encode operations.

Description

Each call issues one or more video encode operations. The implicit parameter opCount corresponds to the number of video encode 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 encode operation.

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

Active Reference Picture Information

The list of active reference pictures used by a video encode 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 pEncodeInfo->pReferenceSlots array. For each element of pEncodeInfo->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 encode operation is derived from the VkVideoReferenceSlotInfoKHR structure pointed to by pEncodeInfo->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 pEncodeInfo->pSetupReferenceSlot is always required, unless the video session was created with VkVideoSessionCreateInfoKHR::maxDpbSlots equal to zero. However, the DPB slot identified by pEncodeInfo->pSetupReferenceSlot->slotIndex is only activated with the reconstructed picture specified in pEncodeInfo->pSetupReferenceSlot->pPictureResource if reference picture setup is requested according to the codec-specific semantics.

If reconstructed picture information is specified, but reference picture setup is not requested, according to the codec-specific semantics, the contents of the video picture resource corresponding to the reconstructed picture will be undefined after the video encode operation.

Note

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

Information related to the encode input picture used by a video encode operation is derived from pEncodeInfo->srcPictureResource and any codec-specific parameters provided in the pEncodeInfo->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 encode input picture.

  • The codec-specific picture information related to the encoded 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 encode operation. Unless otherwise defined, activeReferencePictureCount is set to the value of pEncodeInfo->referenceSlotCount.

  • 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 pEncodeInfo->pSetupReferenceSlot is not NULL, then dpbFrameUseCount[i] is incremented by one, where i equals pEncodeInfo->pSetupReferenceSlot->slotIndex.

    • For each element of pEncodeInfo->pReferenceSlots, dpbFrameUseCount[i] is incremented by one, where i equals the slotIndex member of the corresponding element.

  • If there is a bound video session parameters object created with VK_VIDEO_SESSION_PARAMETERS_CREATE_QUANTIZATION_MAP_COMPATIBLE_BIT_KHR, then let VkExtent2D quantizationMapTexelSize be the quantization map texel size the bound video session parameters object was created with.

  • Let VkExtent2D maxCodingBlockSize be the maximum codec-specific coding block size that may be used by the video encode operation.

  • If maxCodingBlockSize is defined, then let VkExtent2D minCodingBlockExtent be the coded extent of the encode input picture expressed in terms of codec-specific coding blocks, assuming the maximum size of such coding blocks, as defined by maxCodingBlockSize, calculated from the value of the codedExtent member of pEncodeInfo->srcPictureResource as follows:

    • minCodingBlockExtent.width = (codedExtent.width
      maxCodingBlockSize.width - 1) / maxCodingBlockSize.width

    • minCodingBlockExtent.height = (codedExtent.height
      maxCodingBlockSize.height - 1) / maxCodingBlockSize.height

  • If the bound video session object was created with an H.264 encode profile, then:

    • Let StdVideoH264PictureType h264PictureType be the picture type of the encoded picture set to the value of pStdPictureInfo->primary_pic_type specified in the VkVideoEncodeH264PictureInfoKHR structure included in the pEncodeInfo->pNext chain.

    • Let StdVideoH264PictureType h264L0PictureTypes[] and StdVideoH264PictureType h264L1PictureTypes[] be the picture types of the reference pictures in the L0 and L1 reference lists, respectively. If pStdPictureInfo->pRefLists specified in the VkVideoEncodeH264PictureInfoKHR structure included in the pEncodeInfo->pNext chain is not NULL, then for each reference index specified in the elements of the pStdPictureInfo->pRefLists->RefPicList0 and pStdPictureInfo->pRefLists->RefPicList1 arrays, if the reference index is not STD_VIDEO_H264_NO_REFERENCE_PICTURE, pStdReferenceInfo->primary_pic_type is added to h264L0PictureTypes or h264L1PictureTypes, respectively, where pStdReferenceInfo is the member of the VkVideoEncodeH264DpbSlotInfoKHR structure included in the pNext chain of the element of pEncodeInfo->pReferenceSlots for which slotIndex equals the reference index in question.

  • If the bound video session was created with the video codec operation VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and with the intra refresh mode VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_PER_PICTURE_PARTITION_BIT_KHR, pEncodeInfo->flags includes VK_VIDEO_ENCODE_INTRA_REFRESH_BIT_KHR, and the pNext chain of pEncodeInfo includes a VkVideoEncodeIntraRefreshInfoKHR structure, then let uint32_t intraRefreshH264SliceIndex be the intra refresh index specified in VkVideoEncodeIntraRefreshInfoKHR::intraRefreshIndex. Otherwise intraRefreshH264SliceIndex is not defined.

  • If the bound video session object was created with an H.265 encode profile, then:

    • Let StdVideoH265PictureType h265PictureType be the picture type of the encoded picture set to the value of pStdPictureInfo->pic_type specified in the VkVideoEncodeH265PictureInfoKHR structure included in the pEncodeInfo->pNext chain.

    • Let StdVideoH265PictureType h265L0PictureTypes[] and StdVideoH265PictureType h265L1PictureTypes[] be the picture types of the reference pictures in the L0 and L1 reference lists, respectively. If pStdPictureInfo->pRefLists specified in the VkVideoEncodeH265PictureInfoKHR structure included in the pEncodeInfo->pNext chain is not NULL, then for each reference index specified in the elements of the pStdPictureInfo->pRefLists->RefPicList0 and pStdPictureInfo->pRefLists->RefPicList1 arrays, if the reference index is not STD_VIDEO_H265_NO_REFERENCE_PICTURE, pStdReferenceInfo->pic_type is added to h265L0PictureTypes or h265L1PictureTypes, respectively, where pStdReferenceInfo is the member of the VkVideoEncodeH265DpbSlotInfoKHR structure included in the pNext chain of the element of pEncodeInfo->pReferenceSlots for which slotIndex equals the reference index in question.

  • If the bound video session was created with the video codec operation VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and with the intra refresh mode VK_VIDEO_ENCODE_INTRA_REFRESH_MODE_PER_PICTURE_PARTITION_BIT_KHR, pEncodeInfo->flags includes VK_VIDEO_ENCODE_INTRA_REFRESH_BIT_KHR, and the pNext chain of pEncodeInfo includes a VkVideoEncodeIntraRefreshInfoKHR structure, then let uint32_t intraRefreshH265SliceSegmentIndex be the intra refresh index specified in VkVideoEncodeIntraRefreshInfoKHR::intraRefreshIndex. Otherwise intraRefreshH265SliceSegmentIndex is not defined.

  • If the bound video session object was created with an AV1 encode profile, then:

Valid Usage
Valid Usage (Implicit)

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

  • VUID-vkCmdEncodeVideoKHR-pEncodeInfo-parameter
    pEncodeInfo must be a valid pointer to a valid VkVideoEncodeInfoKHR structure

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

  • VUID-vkCmdEncodeVideoKHR-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support VK_QUEUE_VIDEO_ENCODE_BIT_KHR operations

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

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

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

  • VUID-vkCmdEncodeVideoKHR-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_ENCODE_BIT_KHR

Action
Conditional Rendering

vkCmdEncodeVideoKHR is not affected by conditional rendering

See Also

VK_KHR_video_encode_queue, VkCommandBuffer, VkVideoEncodeInfoKHR

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

SPDX-License-Identifier: CC-BY-4.0