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

[[decode-h264]]
== Video Decode of AVC (ITU-T H.264)

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


=== H.264 decode profile

A H.264 decode profile is specified using slink:VkVideoDecodeH264ProfileEXT
chained to slink:VkVideoProfileKHR when the codec-operation in
slink:VkVideoProfileKHR is
ename:VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_EXT.

[open,refpage='VkVideoDecodeH264ProfileEXT',desc='Structure specifying H.264 decode profile',type='structs']
--
The sname:VkVideoDecodeH264ProfileEXT structure is defined as:

include::{generated}/api/structs/VkVideoDecodeH264ProfileEXT.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:StdVideoH264ProfileIdc value specifying
    the H.264 codec profile IDC
  * pname:pictureLayout is a bitmask of
    elink:VkVideoDecodeH264PictureLayoutFlagBitsEXT specifying the layout of
    the decoded picture's contents depending on the nature (progressive vs.
    interlaced) of the input content.

[NOTE]
.Note
====
When passing sname:VkVideoDecodeH264ProfileEXT to
flink:vkCreateVideoSessionKHR in the pname:pNext chain of
slink:VkVideoSessionCreateInfoKHR, requests for a pname:pictureLayout not
supported by the implementation will result in failure of the command.
====

.Valid Usage
****
  * [[VUID-VkVideoDecodeH264ProfileEXT-pNext-06259]]
    If the slink:VkVideoDecodeH264ProfileEXT structure is included in the
    pname:pNext chain of the slink:VkVideoCapabilitiesKHR structure passed
    to flink:vkGetPhysicalDeviceVideoCapabilitiesKHR, the value in
    pname:pictureLayout is treated as a bitmask of requested picture
    layouts.
    It is always valid to use the value
    ename:VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_PROGRESSIVE_EXT as the
    implementation is guaranteed to support decoding of progressive content.
  * [[VUID-VkVideoDecodeH264ProfileEXT-pNext-06260]]
    If the slink:VkVideoDecodeH264ProfileEXT structure is included in the
    pname:pNext chain of the slink:VkVideoSessionCreateInfoKHR structure
    passed to flink:vkCreateVideoSessionKHR, the value in
    pname:pictureLayout must: be exactly one of
    ename:VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_PROGRESSIVE_EXT,
    ename:VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_INTERLEAVED_LINES_BIT_EXT
    or
    ename:VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_EXT.
****

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

[open,refpage='VkVideoDecodeH264PictureLayoutFlagsEXT',desc='Bitmask of VkVideoDecodeH264PictureLayoutFlagBitsEXT',type='flags']
--
include::{generated}/api/flags/VkVideoDecodeH264PictureLayoutFlagsEXT.txt[]

tname:VkVideoDecodeH264PictureLayoutFlagsEXT is a bitmask type for setting a
mask of zero or more elink:VkVideoDecodeH264PictureLayoutFlagBitsEXT.
--

[open,refpage='VkVideoDecodeH264PictureLayoutFlagBitsEXT',desc='H.264 video decode picture layout flags',type='enums']
--
The H.264 video decode picture layout flags are defined with the following
enum:

include::{generated}/api/enums/VkVideoDecodeH264PictureLayoutFlagBitsEXT.txt[]

  * ename:VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_PROGRESSIVE_EXT specifies
    support for progressive content.
    This flag has the value `0`.
  * ename:VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_INTERLEAVED_LINES_BIT_EXT
    specifies support for or use of a picture layout for interlaced content
    where all lines belonging to the first field are decoded to the
    even-numbered lines within the picture resource, and all lines belonging
    to the second field are decoded to the odd-numbered lines within the
    picture resource.
  * ename:VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_EXT
    specifies support for or use of a picture layout for interlaced content
    where all lines belonging to the first field are grouped together in a
    single plane, followed by another plane containing all lines belonging
    to the second field.
--


=== Selecting a H.264 decode 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_H264_BIT_EXT, a
slink:VkVideoDecodeH264ProfileEXT structure must: be chained to
slink:VkVideoProfileKHR to select a H.264 decode profile.
If supported, the implementation returns the capabilities associated with
the specified H.264 decode profile.
The requirement is similar when querying supported image formats using
flink:vkGetPhysicalDeviceVideoFormatPropertiesKHR.

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


=== Capabilities

[open,refpage='VkVideoDecodeH264CapabilitiesEXT',desc='Structure specifying H.264 decode capabilities',type='structs']
--
When using flink:vkGetPhysicalDeviceVideoCapabilitiesKHR to query the
capabilities for the input pname:pVideoProfile with
pname:videoCodecOperation specified as
ename:VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_EXT, a
slink:VkVideoDecodeH264CapabilitiesEXT structure must: be chained to
slink:VkVideoCapabilitiesKHR to get this H.264 decode profile specific
capabilities.

The slink:VkVideoDecodeH264CapabilitiesEXT structure is defined as:

include::{generated}/api/structs/VkVideoDecodeH264CapabilitiesEXT.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.264 level supported by the device.
  * pname:fieldOffsetGranularity - if Interlaced Video Content is suported,
    the maximum field offset granularity supported for the picture resource.
  * pname:stdExtensionVersion is a slink:VkExtensionProperties structure
    specifying the H.264 extension name and version supported by this
    implementation.

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


=== Create Information

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

The slink:VkVideoDecodeH264SessionCreateInfoEXT structure is defined as:

include::{generated}/api/structs/VkVideoDecodeH264SessionCreateInfoEXT.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 the H.264 codec extensions defined in
    code:StdVideoH264Extensions.

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

[open,refpage='VkVideoDecodeH264CreateFlagsEXT',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkVideoDecodeH264CreateFlagsEXT.txt[]

tname:VkVideoDecodeH264CreateFlagsEXT is a bitmask type for setting a mask,
but is currently reserved for future use.
--


=== Decoder Parameter Sets

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

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

The slink:VkVideoDecodeH264SessionParametersCreateInfoEXT structure is
defined as:

include::{generated}/api/structs/VkVideoDecodeH264SessionParametersCreateInfoEXT.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:VkVideoDecodeH264SessionParametersAddInfoEXT structure specifying
    H.264 parameters to add upon object creation.

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

[open,refpage='VkVideoDecodeH264SessionParametersAddInfoEXT',desc='Structure specifies H.264 decoder parameter set information',type='structs']
--
include::{generated}/api/structs/VkVideoDecodeH264SessionParametersAddInfoEXT.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 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:StdVideoH264SequenceParameterSet structures representing H.264
    sequence parameter sets.
    Each element of the array must: have a unique H.264 SPS ID.
  * 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:StdVideoH264PictureParameterSet structures representing H.264
    picture parameter sets.
    Each element of the array must: have a unique H.264 SPS-PPS ID pair.

.Valid Usage
****
  * [[VUID-VkVideoDecodeH264SessionParametersAddInfoEXT-spsStdCount-04822]]
    The values of pname:spsStdCount and pname:ppsStdCount must: be less than
    or equal to the values of pname:maxSpsStdCount and pname:maxPpsStdCount,
    respectively
  * [[VUID-VkVideoDecodeH264SessionParametersAddInfoEXT-maxSpsStdCount-04823]]
    When the pname:maxSpsStdCount number of parameters of type
    StdVideoH264SequenceParameterSet in the Video Session Parameters object
    is reached, no additional parameters of that type can be added to this
    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-VkVideoDecodeH264SessionParametersAddInfoEXT-maxPpsStdCount-04824]]
    When the pname:maxPpsStdCount number of parameters of type
    StdVideoH264PictureParameterSet in the Video Session Parameters object
    is reached, no additional parameters of that type can be added to this
    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-VkVideoDecodeH264SessionParametersAddInfoEXT-None-04825]]
    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, SPS-PPS IDs
  * [[VUID-VkVideoDecodeH264SessionParametersAddInfoEXT-None-04826]]
    Parameter entries that already exist in Video Session Parameters object
    with a particular SPS-PPS IDs cannot: be replaced nor updated
  * [[VUID-VkVideoDecodeH264SessionParametersAddInfoEXT-None-04827]]
    When creating a new object using a Video Session Parameters as a
    template, the array's parameters with the same SPS-PPS IDs as the ones
    from the template take precedence
  * [[VUID-VkVideoDecodeH264SessionParametersAddInfoEXT-None-04828]]
    SPS/PPS parameters must: comply with the limits specified in
    slink:VkVideoSessionCreateInfoKHR during Video Session creation
****

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


=== Picture Decoding

To decode a picture, the structure slink:VkVideoDecodeH264PictureInfoEXT
may: be chained to slink:VkVideoDecodeInfoKHR when calling
flink:vkCmdDecodeVideoKHR.

[open,refpage='VkVideoDecodeH264PictureInfoEXT',desc='Structure specifies H.264 decode picture parameters when decoding a picture',type='structs']
--
The structure slink:VkVideoDecodeH264PictureInfoEXT representing a picture
decode operation is defined as:

include::{generated}/api/structs/VkVideoDecodeH264PictureInfoEXT.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:StdVideoDecodeH264PictureInfo structure specifying the codec
    standard specific picture information from the H.264 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/VkVideoDecodeH264PictureInfoEXT.txt[]
--

[open,refpage='VkVideoDecodeH264DpbSlotInfoEXT',desc='Structure specifies H.264 decode DPB picture information',type='structs']
--
The slink:VkVideoDecodeH264DpbSlotInfoEXT structure correlates a DPB Slot
index with codec-specific information and is defined as:

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

  * pname:sType is the type of this structure.
  * pname:pStdReferenceInfo is a pointer to a
    code:StdVideoDecodeH264ReferenceInfo structure specifying the codec
    standard specific picture reference information from the H.264
    specification.

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

[open,refpage='VkVideoDecodeH264MvcEXT',desc='Structure specifies parameters of mvc views',type='structs']
--
The slink:VkVideoDecodeH264MvcEXT structure is defined as:

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

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:pStdMvc is a pointer to a code:StdVideoDecodeH264Mvc structure
    specifying H.264 codec specification information for MVC.

When the content type is H.264 MVC, a slink:VkVideoDecodeH264MvcEXT
structure must: be chained to slink:VkVideoDecodeH264PictureInfoEXT.

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