C Specification

To create a video session object, call:

// Provided by VK_KHR_video_queue
VkResult vkCreateVideoSessionKHR(
    VkDevice                                    device,
    const VkVideoSessionCreateInfoKHR*          pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkVideoSessionKHR*                          pVideoSession);

Parameters

  • device is the logical device that creates the video session.

  • pCreateInfo is a pointer to a VkVideoSessionCreateInfoKHR structure containing parameters to be used to create the video session.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pVideoSession is a pointer to a VkVideoSessionKHR handle in which the resulting video session object is returned.

Description

The resulting video session object is said to be created with the video codec operation specified in pCreateInfo->pVideoProfile->videoCodecOperation.

The name and version of the codec-specific Video Std header to be used with the video session is specified by the VkExtensionProperties structure pointed to by pCreateInfo->pStdHeaderVersion. If a non-existent or unsupported Video Std header version is specified in pCreateInfo->pStdHeaderVersion->specVersion, then this command returns VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHR.

Video session objects are created in uninitialized state. In order to transition the video session into initial state, the application must issue a vkCmdControlVideoCodingKHR command with VkVideoCodingControlInfoKHR::flags including VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR.

Video session objects also maintain the state of the DPB. The number of DPB slots usable with the created video session is specified in pCreateInfo->maxDpbSlots, and each slot is initially in the inactive state.

Each DPB slot maintained by the created video session can refer to a reference picture representing a video frame.

In addition, if the videoCodecOperation member of the VkVideoProfileInfoKHR structure pointed to by pCreateInfo->pVideoProfile is VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR and the pictureLayout member of the VkVideoDecodeH264ProfileInfoKHR structure provided in the VkVideoProfileInfoKHR::pNext chain is not VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_PROGRESSIVE_KHR, then the created video session supports interlaced frames and each DPB slot maintained by the created video session can instead refer to separate top field and bottom field reference pictures that together can represent a full video frame. In this case, it is up to the application, driven by the video content, whether it associates any individual DPB slot with separate top and/or bottom field pictures or a single picture representing a full frame.

The created video session can be used to perform video coding operations using video frames up to the maximum size specified in pCreateInfo->maxCodedExtent. The minimum frame size allowed is implicitly derived from VkVideoCapabilitiesKHR::minCodedExtent, as returned by vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile specified by pCreateInfo->pVideoProfile. Accordingly, the created video session is said to be created with a minCodedExtent equal to that.

In case of video session objects created with a video encode operation, implementations may return the VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error if any of the specified Video Std parameters do not adhere to the syntactic or semantic requirements of the used video compression standard, or if values derived from parameters according to the rules defined by the used video compression standard do not adhere to the capabilities of the video compression standard or the implementation.

Note

Applications should not rely on the VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR error being returned by any command as a means to verify Video Std parameters, as implementations are not required to report the error in any specific set of cases.
Valid Usage (Implicit)

  • VUID-vkCreateVideoSessionKHR-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateVideoSessionKHR-pCreateInfo-parameter
    pCreateInfo must be a valid pointer to a valid VkVideoSessionCreateInfoKHR structure

  • VUID-vkCreateVideoSessionKHR-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateVideoSessionKHR-pVideoSession-parameter
    pVideoSession must be a valid pointer to a VkVideoSessionKHR handle

Return Codes
On success, this command returns

  • VK_SUCCESS

On failure, this command returns

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

  • VK_ERROR_VIDEO_STD_VERSION_NOT_SUPPORTED_KHR

  • VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR

See Also

VK_KHR_video_queue, VkAllocationCallbacks, VkDevice, VkVideoSessionCreateInfoKHR, VkVideoSessionKHR

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