vkCmdControlVideoCodingKHR(3)

C Specification

To apply dynamic controls to the currently bound video session object, call:

// Provided by VK_KHR_video_queue
void vkCmdControlVideoCodingKHR(
    VkCommandBuffer                             commandBuffer,
    const VkVideoCodingControlInfoKHR*          pCodingControlInfo);

Parameters

commandBuffer is the command buffer in which to record the command.
pCodingControlInfo is a pointer to a VkVideoCodingControlInfoKHR structure specifying the control parameters.

Description

The control parameters provided in this call are applied to the video session at the time the command executes on the device and are in effect until a subsequent call to this command with the same video session bound changes the corresponding control parameters.

A newly created video session must be reset before performing video coding operations using it by including VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR in pCodingControlInfo->flags. The reset operation also returns all DPB slots of the video session to the inactive state. Correspondingly, any DPB slot index associated with the bound reference picture resources is removed.

For encode sessions, the reset operation returns rate control configuration to implementation default settings and sets the video encode quality level to zero.

After video coding operations are performed using a video session, the reset operation can be used to return the video session to the same initial state as after the reset of a newly created video session. This can be used, for example, when different video sequences are needed to be processed with the same video session object.

If pCodingControlInfo->flags includes VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, then the command replaces the rate control configuration maintained by the video session with the configuration specified in the VkVideoEncodeRateControlInfoKHR structure included in the pCodingControlInfo->pNext chain.

If pCodingControlInfo->flags includes VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR, then the command changes the current video encode quality level to the value specified in the qualityLevel member of the VkVideoEncodeQualityLevelInfoKHR structure included in the pCodingControlInfo->pNext chain.

Valid Usage

VUID-vkCmdControlVideoCodingKHR-flags-07017
If pCodingControlInfo->flags does not include VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR, then the bound video session must not be in uninitialized state at the time the command is executed on the device
VUID-vkCmdControlVideoCodingKHR-pCodingControlInfo-08243
If the bound video session was not created with an encode operation, then pCodingControlInfo->flags must not include VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR or VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR

Valid Usage (Implicit)

VUID-vkCmdControlVideoCodingKHR-commandBuffer-parameter
commandBuffer must be a valid VkCommandBuffer handle
VUID-vkCmdControlVideoCodingKHR-pCodingControlInfo-parameter
pCodingControlInfo must be a valid pointer to a valid VkVideoCodingControlInfoKHR structure
VUID-vkCmdControlVideoCodingKHR-commandBuffer-recording
commandBuffer must be in the recording state
VUID-vkCmdControlVideoCodingKHR-commandBuffer-cmdpool
The VkCommandPool that commandBuffer was allocated from must support decode, or encode operations
VUID-vkCmdControlVideoCodingKHR-renderpass
This command must only be called outside of a render pass instance
VUID-vkCmdControlVideoCodingKHR-videocoding
This command must only be called inside of a video coding scope
VUID-vkCmdControlVideoCodingKHR-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