vkCreateVideoSessionKHR(3)

# vkCreateVideoSessionKHR(3) Manual Page

## Name

vkCreateVideoSessionKHR - Creates a video session object

Loading… please wait.

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

SPDX-License-Identifier: CC-BY-4.0