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_DECODE_AV1_BIT_KHR, then the created video session parameters object will contain a single AV1 sequence header represented by a StdVideoAV1SequenceHeader structure specified through the pStdSequenceHeader member of the VkVideoDecodeAV1SessionParametersCreateInfoKHR structure provided in the pCreateInfo->pNext chain. As such video session parameters objects can only contain a single AV1 sequence header, it is not possible to use a previously created object as a template or subsequently update the created video session parameters object.

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

SPDX-License-Identifier: CC-BY-4.0