vkCreateVideoSessionParametersKHR(3)

# vkCreateVideoSessionParametersKHR(3) Manual Page

## Name

vkCreateVideoSessionParametersKHR - Creates video session parameters object

Loading… please wait.

## C Specification

To create a video session parameters object, call:

    // Provided by VK_KHR_video_queue
    VkResult vkCreateVideoSessionParametersKHR(
        VkDevice                                    device,
        const VkVideoSessionParametersCreateInfoKHR* pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkVideoSessionParametersKHR*                pVideoSessionParameters);

## Parameters

- `device` is the logical device that creates the video session parameters object.

- `pCreateInfo` is a pointer to VkVideoSessionParametersCreateInfoKHR structure containing parameters to be used to create the video session parameters object.

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

- `pVideoSessionParameters` is a pointer to a VkVideoSessionParametersKHR handle in which the resulting video session parameters object is returned.

## Description

The resulting video session parameters object is said to be created with the video codec operation `pCreateInfo->videoSession` was created with.

Video session parameters objects created with an encode operation are always created with respect to a video encode quality level. By default, the created video session parameters objects are created with quality level zero, unless otherwise specified by including a VkVideoEncodeQualityLevelInfoKHR structure in the `pCreateInfo->pNext` chain, in which case the video session parameters object is created with the quality level specified in VkVideoEncodeQualityLevelInfoKHR::`qualityLevel`.

If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then it will be used as a template for constructing the new video session parameters object. This happens by first adding any parameters according to the additional creation parameters provided in the `pCreateInfo->pNext` chain, followed by adding any parameters from the template object that have a key that does not match the key of any of the already added parameters.

For video session parameters objects created with an encode operation, the template object specified in `pCreateInfo->videoSessionParametersTemplate` must have been created with the same video encode quality level as the newly created object.

| Note This means that codec-specific parameters stored in video session parameters objects can only be reused across different video encode quality levels by re-specifying them, as previously created video session parameters against other quality levels cannot be used as template because the original codec-specific parameters (before the implementation may have applied parameter overrides) may no longer be available in them for the purposes of constructing the derived object.

If `pCreateInfo->videoSession` was created with the video codec operation `VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR`, then the created video session parameters object will initially contain the following sets of parameter entries:

- `StdVideoH264SequenceParameterSet` structures representing H.264 SPS entries, as follows:

  - If the `pParametersAddInfo` member of the VkVideoDecodeH264SessionParametersCreateInfoKHR structure provided in the `pCreateInfo->pNext` chain is not `NULL`, then the set of `StdVideoH264SequenceParameterSet` entries specified in `pParametersAddInfo->pStdSPSs` are added first;

  - If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then each `StdVideoH264SequenceParameterSet` entry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the same `seq_parameter_set_id`.

- `StdVideoH264PictureParameterSet` structures representing H.264 PPS entries, as follows:

  - If the `pParametersAddInfo` member of the VkVideoDecodeH264SessionParametersCreateInfoKHR structure provided in the `pCreateInfo->pNext` chain is not `NULL`, then the set of `StdVideoH264PictureParameterSet` entries specified in `pParametersAddInfo->pStdPPSs` are added first;

  - If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then each `StdVideoH264PictureParameterSet` entry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the same `seq_parameter_set_id` and `pic_parameter_set_id`.

If `pCreateInfo->videoSession` was created with the video codec operation `VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR`, then the created video session parameters object will initially contain the following sets of parameter entries:

- `StdVideoH265VideoParameterSet` structures representing H.265 VPS entries, as follows:

  - If the `pParametersAddInfo` member of the VkVideoDecodeH265SessionParametersCreateInfoKHR structure provided in the `pCreateInfo->pNext` chain is not `NULL`, then the set of `StdVideoH265VideoParameterSet` entries specified in `pParametersAddInfo->pStdVPSs` are added first;

  - If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then each `StdVideoH265VideoParameterSet` entry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the same `vps_video_parameter_set_id`.

- `StdVideoH265SequenceParameterSet` structures representing H.265 SPS entries, as follows:

  - If the `pParametersAddInfo` member of the VkVideoDecodeH265SessionParametersCreateInfoKHR structure provided in the `pCreateInfo->pNext` chain is not `NULL`, then the set of `StdVideoH265SequenceParameterSet` entries specified in `pParametersAddInfo->pStdSPSs` are added first;

  - If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then each `StdVideoH265SequenceParameterSet` entry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the same `sps_video_parameter_set_id` and `sps_seq_parameter_set_id`.

- `StdVideoH265PictureParameterSet` structures representing H.265 PPS entries, as follows:

  - If the `pParametersAddInfo` member of the VkVideoDecodeH265SessionParametersCreateInfoKHR structure provided in the `pCreateInfo->pNext` chain is not `NULL`, then the set of `StdVideoH265PictureParameterSet` entries specified in `pParametersAddInfo->pStdPPSs` are added first;

  - If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then each `StdVideoH265PictureParameterSet` entry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the same `sps_video_parameter_set_id`, `pps_seq_parameter_set_id`, and `pps_pic_parameter_set_id`.

If `pCreateInfo->videoSession` was created with the video codec operation `VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR`, then the created video session parameters object will initially contain the following sets of parameter entries:

- `StdVideoH264SequenceParameterSet` structures representing H.264 SPS entries, as follows:

  - If the `pParametersAddInfo` member of the VkVideoEncodeH264SessionParametersCreateInfoKHR structure provided in the `pCreateInfo->pNext` chain is not `NULL`, then the set of `StdVideoH264SequenceParameterSet` entries specified in `pParametersAddInfo->pStdSPSs` are added first;

  - If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then each `StdVideoH264SequenceParameterSet` entry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the same `seq_parameter_set_id`.

- `StdVideoH264PictureParameterSet` structures representing H.264 PPS entries, as follows:

  - If the `pParametersAddInfo` member of the VkVideoEncodeH264SessionParametersCreateInfoKHR structure provided in the `pCreateInfo->pNext` chain is not `NULL`, then the set of `StdVideoH264PictureParameterSet` entries specified in `pParametersAddInfo->pStdPPSs` are added first;

  - If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then each `StdVideoH264PictureParameterSet` entry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the same `seq_parameter_set_id` and `pic_parameter_set_id`.

If `pCreateInfo->videoSession` was created with the video codec operation `VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR`, then the created video session parameters object will initially contain the following sets of parameter entries:

- `StdVideoH265VideoParameterSet` structures representing H.265 VPS entries, as follows:

  - If the `pParametersAddInfo` member of the VkVideoEncodeH265SessionParametersCreateInfoKHR structure provided in the `pCreateInfo->pNext` chain is not `NULL`, then the set of `StdVideoH265VideoParameterSet` entries specified in `pParametersAddInfo->pStdVPSs` are added first;

  - If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then each `StdVideoH265VideoParameterSet` entry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the same `vps_video_parameter_set_id`.

- `StdVideoH265SequenceParameterSet` structures representing H.265 SPS entries, as follows:

  - If the `pParametersAddInfo` member of the VkVideoEncodeH265SessionParametersCreateInfoKHR structure provided in the `pCreateInfo->pNext` chain is not `NULL`, then the set of `StdVideoH265SequenceParameterSet` entries specified in `pParametersAddInfo->pStdSPSs` are added first;

  - If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then each `StdVideoH265SequenceParameterSet` entry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the same `sps_video_parameter_set_id` and `sps_seq_parameter_set_id`.

- `StdVideoH265PictureParameterSet` structures representing H.265 PPS entries, as follows:

  - If the `pParametersAddInfo` member of the VkVideoEncodeH265SessionParametersCreateInfoKHR structure provided in the `pCreateInfo->pNext` chain is not `NULL`, then the set of `StdVideoH265PictureParameterSet` entries specified in `pParametersAddInfo->pStdPPSs` are added first;

  - If `pCreateInfo->videoSessionParametersTemplate` is not `VK_NULL_HANDLE`, then each `StdVideoH265PictureParameterSet` entry stored in it is copied to the created video session parameters object if the created object does not already contain such an entry with the same `sps_video_parameter_set_id`, `pps_seq_parameter_set_id`, and `pps_pic_parameter_set_id`.

In case of video session parameters 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-vkCreateVideoSessionParametersKHR-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkCreateVideoSessionParametersKHR-pCreateInfo-parameter
  `pCreateInfo` must be a valid pointer to a valid VkVideoSessionParametersCreateInfoKHR structure

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

- VUID-vkCreateVideoSessionParametersKHR-pVideoSessionParameters-parameter
  `pVideoSessionParameters` must be a valid pointer to a VkVideoSessionParametersKHR 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_INVALID_VIDEO_STD_PARAMETERS_KHR`

## See Also

VK_KHR_video_queue, VkAllocationCallbacks, VkDevice, VkVideoSessionParametersCreateInfoKHR, VkVideoSessionParametersKHR

## 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