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.

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

See Also

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

SPDX-License-Identifier: CC-BY-4.0