// Copyright 2018-2021 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[decode-h265]]
== Video Decode of HEVC (ITU-T H.265)

This extension adds H.265 codec specific structures needed for decode
session to execute decode jobs which include H.265 sequence header, picture
parameter header and quantization matrix etc.
Unless otherwise noted, all references to the H.265 specification are to the
2013 edition published by the ITU-T, dated April 2013.
This specification is available at http://www.itu.int/rec/T-REC-H.265.


=== H.265 decode profile

A H.265 decode profile is specified using slink:VkVideoDecodeH265ProfileEXT
chained to slink:VkVideoProfileKHR when the codec-operation in
slink:VkVideoProfileKHR is
ename:VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_EXT.

[open,refpage='VkVideoDecodeH265ProfileEXT',desc='Structure specifying H.265 decode profile',type='structs']
--
The slink:VkVideoDecodeH265ProfileEXT structure is defined as:

include::{generated}/api/structs/VkVideoDecodeH265ProfileEXT.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:stdProfileIdc is a code:StdVideoH265ProfileIdc value specifying
    the H.265 codec profile IDC.

include::{generated}/validity/structs/VkVideoDecodeH265ProfileEXT.txt[]
--


=== Selecting an H.265 Profile

When using flink:vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for the input pname:pVideoProfile with
pname:videoCodecOperation specified as
ename:VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_EXT, the instance of
slink:VkVideoDecodeH265ProfileEXT structure must: be chained to
slink:VkVideoProfileKHR to select a H.265 decode profile.
If supported, the implementation returns the capabilities associated with
the specified H.265 decode profile.
The requirement is similar when querying supported image formats using
flink:vkGetPhysicalDeviceVideoFormatPropertiesKHR.

A supported H.265 decode profile must: be selected when creating a video
session by chaining slink:VkVideoDecodeH265ProfileEXT to the
slink:VkVideoProfileKHR field of slink:VkVideoSessionCreateInfoKHR.


=== Capabilities

[open,refpage='VkVideoDecodeH265CapabilitiesEXT',desc='Structure specifies H.265 decode capabilities parameters when decoding a frame',type='structs']
--
When uses flink:vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for the parameter pname:videoCodecOperation specified as
ename:VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_EXT,
slink:VkVideoDecodeH265CapabilitiesEXT structure can: be chained to
slink:VkVideoCapabilitiesKHR to get this H.265 extension specific
capabilities.

The slink:VkVideoDecodeH265CapabilitiesEXT structure is defined as:

include::{generated}/api/structs/VkVideoDecodeH265CapabilitiesEXT.txt[]
  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:maxLevel is the maximum H.265 level supported by the device.
  * pname:stdExtensionVersion is a slink:VkExtensionProperties structure
    specifying the H.265 extension name and version supported by this
    implementation.

include::{generated}/validity/structs/VkVideoDecodeH265CapabilitiesEXT.txt[]
--


=== Create Infomation

[open,refpage='VkVideoDecodeH265SessionCreateInfoEXT',desc='Structure specifies H.265 decode session creation parameters',type='structs']
--
The instance of slink:VkVideoDecodeH265SessionCreateInfoEXT structure can:
be chained to slink:VkVideoSessionCreateInfoKHR when the function
flink:vkCreateVideoSessionKHR is called to create a video session for H.265
decode operations.

The slink:VkVideoDecodeH265SessionCreateInfoEXT structure is defined as:

include::{generated}/api/structs/VkVideoDecodeH265SessionCreateInfoEXT.txt[]
  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use.
  * pname:pStdExtensionVersion is a pointer to a slink:VkExtensionProperties
    structure specifying H.265 codec extensions.

include::{generated}/validity/structs/VkVideoDecodeH265SessionCreateInfoEXT.txt[]
--


=== Decoder Parameter Sets

To reduce parameter traffic during decoding, the decoder parameter set
object supports storing H.265 SPS/PPS parameter sets that may be later
referenced during decoding.

[open,refpage='VkVideoDecodeH265SessionParametersCreateInfoEXT',desc='Structure specifies H.265 decoder parameter set information',type='structs']
--
An instance of sname:VkVideoDecodeH265SessionParametersCreateInfoEXT holding
one H.265 SPS and at least one H.265 PPS paramater set must: be chained to
sname:VkVideoSessionParametersCreateInfoKHR when calling
fname:vkCreateVideoSessionParametersKHR to store these parameter set(s) with
the decoder parameter set object for later reference.
The provided H.265 SPS/PPS parameters must: be within the limits specified
during decoder creation for the decoder specified in
sname:VkVideoSessionParametersCreateInfoKHR.

The sname:VkVideoDecodeH265SessionParametersCreateInfoEXT structure is
defined as:

include::{generated}/api/structs/VkVideoDecodeH265SessionParametersCreateInfoEXT.txt[]
  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:maxSpsStdCount is the maximum number of SPS parameters that the
    sname:VkVideoSessionParametersKHR can contain.
  * pname:maxPpsStdCount is the maximum number of PPS parameters that the
    sname:VkVideoSessionParametersKHR can contain.
  * pname:pParametersAddInfo is `NULL` or a pointer to a
    slink:VkVideoDecodeH265SessionParametersAddInfoEXT structure specifying
    H.265 parameters to add upon object creation.

include::{generated}/validity/structs/VkVideoDecodeH265SessionParametersCreateInfoEXT.txt[]
--

[open,refpage='VkVideoDecodeH265SessionParametersAddInfoEXT',desc='Structure specifies H.265 decoder parameter set information',type='structs']
--
include::{generated}/api/structs/VkVideoDecodeH265SessionParametersAddInfoEXT.txt[]
  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:spsStdCount is the number of SPS elements in the pname:pSpsStd.
    Its value must: be less than or equal to the value of
    pname:maxSpsStdCount.
  * pname:pSpsStd is a pointer to an array of
    code:StdVideoH265SequenceParameterSet structures representing H.265
    sequence parameter sets.
    Each element of the array must: have a unique H.265 VPS-SPS ID pair.
  * pname:ppsStdCount is the number of PPS provided in pname:pPpsStd.
    Its value must: be less than or equal to the value of
    pname:maxPpsStdCount.
  * pname:pPpsStd is a pointer to an array of
    code:StdVideoH265PictureParameterSet structures representing H.265
    picture parameter sets.
    Each element of the array entry must: have a unique H.265 VPS-SPS-PPS ID
    tuple.

.Valid Usage
****
  * [[VUID-VkVideoDecodeH265SessionParametersAddInfoEXT-vpsStdCount-04829]]
    The values of pname:vpsStdCount, pname:spsStdCount and pname:ppsStdCount
    must: be less than or equal to the values of pname:maxVpsStdCount,
    pname:maxSpsStdCount and pname:maxPpsStdCount, respectively.
  * [[VUID-VkVideoDecodeH265SessionParametersAddInfoEXT-maxVpsStdCount-04830]]
    When the pname:maxVpsStdCount number of parameters of type
    StdVideoH265VideoParameterSet in the Video Session Parameters object is
    reached, no additional parameters of that type can be added to the
    object.
    ename:VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made
    to add additional data to this object at this point.
  * [[VUID-VkVideoDecodeH265SessionParametersAddInfoEXT-maxSpsStdCount-04831]]
    When the pname:maxSpsStdCount number of parameters of type
    StdVideoH265SequenceParameterSet in the Video Session Parameters object
    is reached, no additional parameters of that type can be added to the
    object.
    ename:VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made
    to add additional data to this object at this point.
  * [[VUID-VkVideoDecodeH265SessionParametersAddInfoEXT-maxPpsStdCount-04832]]
    When the pname:maxPpsStdCount number of parameters of type
    StdVideoH265PictureParameterSet in the Video Session Parameters object
    is reached, no additional parameters of that type can be added to the
    object.
    ename:VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made
    to add additional data to this object at this point.
  * [[VUID-VkVideoDecodeH265SessionParametersAddInfoEXT-None-04833]]
    Each entry to be added must: have a unique, to the rest of the parameter
    array entries and the existing parameters in the Video Session
    Parameters Object that is being updated, VPS-SPS-PPS IDs.
  * [[VUID-VkVideoDecodeH265SessionParametersAddInfoEXT-None-04834]]
    Parameter entries that already exist in Video Session Parameters object
    with a particular VPS-SPS-PPS IDs cannot: be replaced nor updated.
  * [[VUID-VkVideoDecodeH265SessionParametersAddInfoEXT-None-04835]]
    When creating a new object using a Video Session Parameters as a
    template, the array's parameters with the same VPS-SPS-PPS IDs as the
    ones from the template take precedence.
  * [[VUID-VkVideoDecodeH265SessionParametersAddInfoEXT-None-04836]]
    VPS/SPS/PPS parameters must: comply with the limits specified in
    slink:VkVideoSessionCreateInfoKHR during Video Session creation.
****

include::{generated}/validity/structs/VkVideoDecodeH265SessionParametersAddInfoEXT.txt[]
--


=== Picture Parameters

[open,refpage='VkVideoDecodeH265PictureInfoEXT',desc='Structure specifies H.265 picture information when decoding a frame',type='structs']
--
The slink:VkVideoDecodeH265PictureInfoEXT structure is defined as:

include::{generated}/api/structs/VkVideoDecodeH265PictureInfoEXT.txt[]
  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:pStdPictureInfo is a pointer to a
    code:StdVideoDecodeH265PictureInfo structure specifying codec standard
    specific picture information from the H.265 specification.
  * pname:slicesCount is the number of slices in this picture.
  * pname:pSlicesDataOffsets is a pointer to an array of pname:slicesCount
    offsets indicating the start offset of each slice within the bitstream
    buffer.

include::{generated}/validity/structs/VkVideoDecodeH265PictureInfoEXT.txt[]
--

[open,refpage='VkVideoDecodeH265DpbSlotInfoEXT',desc='Structure specifies H.265 DPB information when decoding a frame',type='structs']
--
The slink:VkVideoDecodeH265DpbSlotInfoEXT structure is defined as:

include::{generated}/api/structs/VkVideoDecodeH265DpbSlotInfoEXT.txt[]
  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:pStdReferenceInfo is a pointer to a
    code:StdVideoDecodeH265ReferenceInfo structure specifying the codec
    standard specific picture reference information from the H.264
    specification.

include::{generated}/validity/structs/VkVideoDecodeH265DpbSlotInfoEXT.txt[]
--

