From 542718ca30aef2c3c5afbca41de6424bd37e1808 Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Mon, 18 Dec 2023 20:17:23 -0800 Subject: [PATCH] Change log for December 19, 2023 Vulkan 1.3.274 spec update: Github Issues * Remove incorrect `optional` attribute on slink:VkCudaLaunchInfoNV::pParams and pname:pExtras (public PR 2263). * Require identity swizzle for attachments in slink:VkRenderingInfo dynamic rendering VUs (public issue 2275). * Make slink:VkRenderPassStripeBeginInfoARM::pname:pStripeInfos `const` (public PR 2279). Internal Issues * Add a <> section to the introduction, to define "`ratified`" (as used in the extension appendix metadata) in terms useful for developers (internal issues 3472, 3709). * Allow fragment shader invocations to be merged for flat shaded primitives in the <> section (internal issue 3563). * Add alignment VUs to flink:vkCmdDrawIndirectByteCountEXT (internal issue 3674). * Fix etext:VK_*_CREATE_PROTECTED_BIT memory requirements reporting in the <> section (internal issue 3694). * Update common pipeline create info VUs for create flags (internal issue 3703). * Fix slink:VkRenderingInfo dynamic rendering VUs for slink:VkRenderingAttachmentInfo::pname:resolveImageView structures (internal issue 3711). * Minor changes to slink:VkGraphicsPipelinCreateInfo VUs to consistently allow pname:pMultisampleState to be optional (internal MR 6312). * Update flink:vkGetDescriptorEXT VUs for YCbCr ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER (internal MR 6318). * Specify alignment requirement VUs for slink:VkSparseMemoryBind pname:resourceOffset and pname:memoryOffset values (internal MR 6323). * Clarify slink:VkDescriptorSetLayoutBinding::pname:stageFlags VU (internal MR 6333). * Fix some slink:VkGraphicsPipelineCreateInfo VUs to read properly without some related extensions enabled in the build (internal MR 6335). * Fix code:OutputTriangles -> code:OutputTrianglesNV in the description of code:PrimitiveIndicesNV (internal MR 6338). * Add capture replay VUs to slink:VkAccelerationStructureCreateInfoKHR to ensure that the acceleration structure and buffer are identical and have the same addresses (internal MR 6351). New Extensions * VK_KHR_maintenance6 * Video Encode Extensions ** VK_KHR_video_encode_queue (was provisional KHR) ** VK_KHR_video_encode_h264 (promoted from provisional EXT) ** VK_KHR_video_encode_h265 (promoted from provisional EXT) ** VK_KHR_video_maintenance1 * VK_NV_per_stage_descriptor_set --- ChangeLog.adoc | 57 + Makefile | 2 +- antora/modules/ROOT/nav.adoc | 2 +- appendices/VK_KHR_maintenance6.adoc | 60 + appendices/VK_KHR_video_decode_h264.adoc | 5 +- appendices/VK_KHR_video_decode_h265.adoc | 5 +- appendices/VK_KHR_video_decode_queue.adoc | 9 +- ...264.adoc => VK_KHR_video_encode_h264.adoc} | 20 +- ...265.adoc => VK_KHR_video_encode_h265.adoc} | 26 +- appendices/VK_KHR_video_encode_queue.adoc | 27 +- appendices/VK_KHR_video_maintenance1.adoc | 45 + .../VK_NV_per_stage_descriptor_set.adoc | 46 + appendices/boilerplate.adoc | 8 +- .../present_barrier.adoc | 2 +- chapters/capabilities.adoc | 9 + ...iptor_buffer_embedded_samplers_common.adoc | 16 + .../bind_descriptor_sets_common.adoc | 60 + .../bind_index_buffer_common.adoc | 10 + .../commonvalidity/draw_indexed_common.adoc | 7 +- .../dynamic_pipeline_layout_common.adoc | 19 + .../pipeline_create_info_common.adoc | 8 + .../commonvalidity/push_constants_common.adoc | 27 + .../push_descriptor_set_common.adoc | 26 + ...h_descriptor_set_with_template_common.adoc | 35 + .../commonvalidity/query_begin_common.adoc | 10 +- .../set_descriptor_buffer_offsets_common.adoc | 44 + chapters/descriptorsets.adoc | 649 ++++-- chapters/drawing.adoc | 24 + chapters/features.adoc | 119 +- chapters/fragops.adoc | 6 + chapters/interfaces.adoc | 9 +- chapters/introduction.adoc | 27 + chapters/limits.adoc | 30 + chapters/pipelines.adoc | 50 +- chapters/primsrast.adoc | 10 +- chapters/queries.adoc | 39 +- chapters/renderpass.adoc | 72 + chapters/resources.adoc | 295 ++- chapters/sparsemem.adoc | 11 + .../decode.adoc} | 135 +- chapters/video/encode.adoc | 2010 +++++++++++++++++ .../h264_decode.adoc} | 128 +- chapters/video/h264_encode.adoc | 1598 +++++++++++++ chapters/video/h264_parameter_sets.adoc | 82 + .../h265_decode.adoc} | 287 +-- chapters/video/h265_encode.adoc | 1747 ++++++++++++++ chapters/video/h265_parameter_sets.adoc | 234 ++ chapters/video_encode_extensions.adoc | 738 ------ chapters/video_encode_h264_extensions.adoc | 755 ------- chapters/video_encode_h265_extensions.adoc | 857 ------- ...video_extensions.adoc => videocoding.adoc} | 920 ++++++-- images/h26x_closed_gop.svg | 922 ++++++++ images/h26x_layer_pattern_dyadic.svg | 3 + images/h26x_open_gop.svg | 3 + images/h26x_ref_pattern_dyadic.svg | 3 + images/h26x_ref_pattern_flat.svg | 3 + proposals/VK_KHR_maintenance6.adoc | 197 ++ proposals/VK_KHR_video_decode_h264.adoc | 52 +- proposals/VK_KHR_video_decode_h265.adoc | 55 +- proposals/VK_KHR_video_decode_queue.adoc | 71 +- proposals/VK_KHR_video_encode_h264.adoc | 817 +++++++ proposals/VK_KHR_video_encode_h265.adoc | 841 +++++++ proposals/VK_KHR_video_encode_queue.adoc | 1379 +++++++++++ proposals/VK_KHR_video_maintenance1.adoc | 200 ++ proposals/VK_KHR_video_queue.adoc | 10 +- scripts/genvk.py | 3 - scripts/xml_consistency.py | 4 +- vkspec.adoc | 4 +- xml/video.xml | 16 +- xml/vk.xml | 843 ++++--- 70 files changed, 13385 insertions(+), 3458 deletions(-) create mode 100644 appendices/VK_KHR_maintenance6.adoc rename appendices/{VK_EXT_video_encode_h264.adoc => VK_KHR_video_encode_h264.adoc} (93%) rename appendices/{VK_EXT_video_encode_h265.adoc => VK_KHR_video_encode_h265.adoc} (90%) create mode 100644 appendices/VK_KHR_video_maintenance1.adoc create mode 100644 appendices/VK_NV_per_stage_descriptor_set.adoc create mode 100644 chapters/commonvalidity/bind_descriptor_buffer_embedded_samplers_common.adoc create mode 100644 chapters/commonvalidity/bind_descriptor_sets_common.adoc create mode 100644 chapters/commonvalidity/dynamic_pipeline_layout_common.adoc create mode 100644 chapters/commonvalidity/push_constants_common.adoc create mode 100644 chapters/commonvalidity/push_descriptor_set_common.adoc create mode 100644 chapters/commonvalidity/push_descriptor_set_with_template_common.adoc create mode 100644 chapters/commonvalidity/set_descriptor_buffer_offsets_common.adoc rename chapters/{video_decode_extensions.adoc => video/decode.adoc} (86%) create mode 100644 chapters/video/encode.adoc rename chapters/{video_decode_h264_extensions.adoc => video/h264_decode.adoc} (87%) create mode 100644 chapters/video/h264_encode.adoc create mode 100644 chapters/video/h264_parameter_sets.adoc rename chapters/{video_decode_h265_extensions.adoc => video/h265_decode.adoc} (61%) create mode 100644 chapters/video/h265_encode.adoc create mode 100644 chapters/video/h265_parameter_sets.adoc delete mode 100644 chapters/video_encode_extensions.adoc delete mode 100644 chapters/video_encode_h264_extensions.adoc delete mode 100644 chapters/video_encode_h265_extensions.adoc rename chapters/{video_extensions.adoc => videocoding.adoc} (75%) create mode 100644 images/h26x_closed_gop.svg create mode 100644 images/h26x_layer_pattern_dyadic.svg create mode 100644 images/h26x_open_gop.svg create mode 100644 images/h26x_ref_pattern_dyadic.svg create mode 100644 images/h26x_ref_pattern_flat.svg create mode 100644 proposals/VK_KHR_maintenance6.adoc create mode 100644 proposals/VK_KHR_video_encode_h264.adoc create mode 100644 proposals/VK_KHR_video_encode_h265.adoc create mode 100644 proposals/VK_KHR_video_encode_queue.adoc create mode 100644 proposals/VK_KHR_video_maintenance1.adoc diff --git a/ChangeLog.adoc b/ChangeLog.adoc index 6aef5e5d7..b27950dd4 100644 --- a/ChangeLog.adoc +++ b/ChangeLog.adoc @@ -14,6 +14,63 @@ appears frequently in the change log. ----------------------------------------------------- +Change log for December 19, 2023 Vulkan 1.3.274 spec update: + +Github Issues + + * Remove incorrect `optional` attribute on + slink:VkCudaLaunchInfoNV::pParams and pname:pExtras (public PR 2263). + * Require identity swizzle for attachments in slink:VkRenderingInfo + dynamic rendering VUs (public issue 2275). + * Make slink:VkRenderPassStripeBeginInfoARM::pname:pStripeInfos `const` + (public PR 2279). + +Internal Issues + + * Add a <> section to the + introduction, to define "`ratified`" (as used in the extension appendix + metadata) in terms useful for developers (internal issues 3472, 3709). + * Allow fragment shader invocations to be merged for flat shaded + primitives in the <> section (internal + issue 3563). + * Add alignment VUs to flink:vkCmdDrawIndirectByteCountEXT (internal issue + 3674). + * Fix etext:VK_*_CREATE_PROTECTED_BIT memory requirements reporting in the + <> section (internal + issue 3694). + * Update common pipeline create info VUs for create flags (internal issue + 3703). + * Fix slink:VkRenderingInfo dynamic rendering VUs for + slink:VkRenderingAttachmentInfo::pname:resolveImageView structures + (internal issue 3711). + * Minor changes to slink:VkGraphicsPipelinCreateInfo VUs to consistently + allow pname:pMultisampleState to be optional (internal MR 6312). + * Update flink:vkGetDescriptorEXT VUs for YCbCr + ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER (internal MR 6318). + * Specify alignment requirement VUs for slink:VkSparseMemoryBind + pname:resourceOffset and pname:memoryOffset values (internal MR 6323). + * Clarify slink:VkDescriptorSetLayoutBinding::pname:stageFlags VU + (internal MR 6333). + * Fix some slink:VkGraphicsPipelineCreateInfo VUs to read properly without + some related extensions enabled in the build (internal MR 6335). + * Fix code:OutputTriangles -> code:OutputTrianglesNV in the description of + code:PrimitiveIndicesNV (internal MR 6338). + * Add capture replay VUs to slink:VkAccelerationStructureCreateInfoKHR to + ensure that the acceleration structure and buffer are identical and have + the same addresses (internal MR 6351). + +New Extensions + + * VK_KHR_maintenance6 + * Video Encode Extensions + ** VK_KHR_video_encode_queue (was provisional KHR) + ** VK_KHR_video_encode_h264 (promoted from provisional EXT) + ** VK_KHR_video_encode_h265 (promoted from provisional EXT) + ** VK_KHR_video_maintenance1 + * VK_NV_per_stage_descriptor_set + +----------------------------------------------------- + Change log for December 8, 2023 Vulkan 1.3.273 spec update: Github Issues diff --git a/Makefile b/Makefile index dfcb2d8f1..8ad08e1c3 100644 --- a/Makefile +++ b/Makefile @@ -136,7 +136,7 @@ VERBOSE = # ADOCOPTS options for asciidoc->HTML5 output NOTEOPTS = -a editing-notes -a implementation-guide -PATCHVERSION = 273 +PATCHVERSION = 274 BASEOPTS = ifneq (,$(findstring VKSC_VERSION_1_0,$(VERSIONS))) diff --git a/antora/modules/ROOT/nav.adoc b/antora/modules/ROOT/nav.adoc index 64e25f23e..3ab40edc1 100644 --- a/antora/modules/ROOT/nav.adoc +++ b/antora/modules/ROOT/nav.adoc @@ -48,7 +48,7 @@ ifeval::["{test}"=="0"] * xref:chapters/raytraversal.adoc[] * xref:chapters/raytracing.adoc[] * xref:chapters/VK_NV_memory_decompression.adoc[] -* xref:chapters/video_extensions.adoc[] +* xref:chapters/videocoding.adoc[] * xref:chapters/VK_NV_optical_flow/optical_flow.adoc[] * xref:chapters/executiongraphs.adoc[] * xref:chapters/VK_NV_low_latency2/low_latency2.adoc[] diff --git a/appendices/VK_KHR_maintenance6.adoc b/appendices/VK_KHR_maintenance6.adoc new file mode 100644 index 000000000..96283432b --- /dev/null +++ b/appendices/VK_KHR_maintenance6.adoc @@ -0,0 +1,60 @@ +// Copyright 2023 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_KHR_maintenance6.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2023-08-03 + +*Interactions and External Dependencies*:: + - Interacts with `apiext:VK_EXT_robustness2` + +*Contributors*:: + - Jon Leech, Khronos + - Stu Smith, AMD + - Mike Blumenkrantz, Valve + - Ralph Potter, Samsung + - James Fitzpatrick, Imagination Technologies + - Piers Daniell, NVIDIA + - Daniel Story, Nintendo + +=== Description + +apiext:VK_KHR_maintenance6 adds a collection of minor features, none of +which would warrant an entire extension of their own. + +The new features are as follows: + + * slink:VkBindMemoryStatusKHR may be included in the pname:pNext chain of + slink:VkBindBufferMemoryInfo and slink:VkBindImageMemoryInfo, allowing + applications to identify individual resources for which memory binding + failed during calls to flink:vkBindBufferMemory2 and + flink:vkBindImageMemory2. + * A new property pname:fragmentShadingRateClampCombinerInputs to indicate + if an implementation clamps the inputs to fragment shading rate combiner + operations. + * dlink:VK_NULL_HANDLE is allowed to be used when binding an index buffer, + instead of a valid slink:VkBuffer handle. + When the <> feature is + enabled, every index fetched results in a value of zero. + * A new property pname:maxCombinedImageSamplerDescriptorCount to indicate + the maximum number of descriptors needed for any of the + <> supported by the implementation. + * A new property pname:blockTexelViewCompatibleMultipleLayers indicating + whether ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT is allowed + to be used with pname:layerCount > 1 + * pname:pNext extensible *2 versions of all descriptor binding commands. + +include::{generated}/interfaces/VK_KHR_maintenance6.adoc[] + +=== Issues + +None. + +=== Version History + + * Revision 1, 2023-08-01 (Jon Leech) + ** Initial revision diff --git a/appendices/VK_KHR_video_decode_h264.adoc b/appendices/VK_KHR_video_decode_h264.adoc index 1ab35ef4d..9c5deaf6a 100644 --- a/appendices/VK_KHR_video_decode_h264.adoc +++ b/appendices/VK_KHR_video_decode_h264.adoc @@ -7,7 +7,7 @@ include::{generated}/meta/{refprefix}VK_KHR_video_decode_h264.adoc[] === Other Extension Metadata *Last Modified Date*:: - 2022-09-29 + 2023-12-05 *IP Status*:: No known IP claims. *Contributors*:: @@ -75,3 +75,6 @@ include::{generated}/interfaces/VK_KHR_video_decode_h264.adoc[] * Revision 8, 2022-09-29 (Daniel Rakos) ** Change extension from `EXT` to `KHR` ** Extension is no longer provisional + * Revision 9, 2023-12-05 (Daniel Rakos) + ** Condition reference picture setup based on the value of + `StdVideoDecodeH264PictureInfo::flags.is_reference` diff --git a/appendices/VK_KHR_video_decode_h265.adoc b/appendices/VK_KHR_video_decode_h265.adoc index fd84d97c0..0eb65debe 100644 --- a/appendices/VK_KHR_video_decode_h265.adoc +++ b/appendices/VK_KHR_video_decode_h265.adoc @@ -7,7 +7,7 @@ include::{generated}/meta/{refprefix}VK_KHR_video_decode_h265.adoc[] === Other Extension Metadata *Last Modified Date*:: - 2022-11-14 + 2023-12-05 *IP Status*:: No known IP claims. *Contributors*:: @@ -65,3 +65,6 @@ include::{generated}/interfaces/VK_KHR_video_decode_h265.adoc[] * Revision 7, 2022-11-14 (Daniel Rakos) ** Change extension from `EXT` to `KHR` ** Extension is no longer provisional + * Revision 8, 2023-12-05 (Daniel Rakos) + ** Condition reference picture setup based on the value of + `StdVideoDecodeH265PictureInfo::flags.IsReference` diff --git a/appendices/VK_KHR_video_decode_queue.adoc b/appendices/VK_KHR_video_decode_queue.adoc index f3c370d60..9492769a2 100644 --- a/appendices/VK_KHR_video_decode_queue.adoc +++ b/appendices/VK_KHR_video_decode_queue.adoc @@ -7,7 +7,7 @@ include::{generated}/meta/{refprefix}VK_KHR_video_decode_queue.adoc[] === Other Extension Metadata *Last Modified Date*:: - 2022-09-29 + 2023-12-05 *IP Status*:: No known IP claims. *Contributors*:: @@ -61,3 +61,10 @@ include::{generated}/interfaces/VK_KHR_video_decode_queue.adoc[] ** Add VkVideoDecodeUsageInfoKHR structure and related flags * Revision 7, 2022-09-29 (Daniel Rakos) ** Extension is no longer provisional + * Revision 8, 2023-12-05 (Daniel Rakos) + ** Require the specification of a reconstructed picture in all cases, + except when the video session was created with no DPB slots to match + shipping implementations + ** Make DPB slot activation behavior codec-specific to continue allowing + application control over reference picture setup now that a + reconstructed picture is always mandatory diff --git a/appendices/VK_EXT_video_encode_h264.adoc b/appendices/VK_KHR_video_encode_h264.adoc similarity index 93% rename from appendices/VK_EXT_video_encode_h264.adoc rename to appendices/VK_KHR_video_encode_h264.adoc index e955c9a54..967d7f34e 100644 --- a/appendices/VK_EXT_video_encode_h264.adoc +++ b/appendices/VK_KHR_video_encode_h264.adoc @@ -2,12 +2,12 @@ // // SPDX-License-Identifier: CC-BY-4.0 -include::{generated}/meta/{refprefix}VK_EXT_video_encode_h264.adoc[] +include::{generated}/meta/{refprefix}VK_KHR_video_encode_h264.adoc[] === Other Extension Metadata *Last Modified Date*:: - 2023-07-19 + 2023-12-05 *IP Status*:: No known IP claims. *Contributors*:: @@ -22,6 +22,7 @@ include::{generated}/meta/{refprefix}VK_EXT_video_encode_h264.adoc[] - Yang Liu, AMD - Daniel Rakos, RasterGrid - Aidan Fabius, Core Avionics & Industrial Inc. + - Lynne Iribarren, Independent === Description @@ -29,7 +30,14 @@ This extension builds upon the `apiext:VK_KHR_video_encode_queue` extension by adding support for encoding elementary video stream sequences compliant with the H.264/AVC video compression standard. -include::{generated}/interfaces/VK_EXT_video_encode_h264.adoc[] +[NOTE] +.Note +==== +This extension was promoted to `KHR` from the provisional extension +`VK_EXT_video_encode_h264`. +==== + +include::{generated}/interfaces/VK_KHR_video_encode_h264.adoc[] === Version History @@ -166,3 +174,9 @@ include::{generated}/interfaces/VK_EXT_video_encode_h264.adoc[] ** Fixed optionality of the array members of `VkVideoEncodeH264SessionParametersAddInfoEXT` ** Fixed optionality of `VkVideoEncodeH264RateControlInfoEXT::flags` + * Revision 13, 2023-09-04 (Daniel Rakos) + ** Change extension from `EXT` to `KHR` + ** Extension is no longer provisional + * Revision 14, 2023-12-05 (Daniel Rakos) + ** Condition reference picture setup based on the value of + `StdVideoEncodeH264PictureInfo::flags.is_reference` diff --git a/appendices/VK_EXT_video_encode_h265.adoc b/appendices/VK_KHR_video_encode_h265.adoc similarity index 90% rename from appendices/VK_EXT_video_encode_h265.adoc rename to appendices/VK_KHR_video_encode_h265.adoc index ca43fe2b9..d0fbf3f8b 100644 --- a/appendices/VK_EXT_video_encode_h265.adoc +++ b/appendices/VK_KHR_video_encode_h265.adoc @@ -2,12 +2,12 @@ // // SPDX-License-Identifier: CC-BY-4.0 -include::{generated}/meta/{refprefix}VK_EXT_video_encode_h265.adoc[] +include::{generated}/meta/{refprefix}VK_KHR_video_encode_h265.adoc[] === Other Extension Metadata *Last Modified Date*:: - 2023-07-19 + 2023-12-05 *IP Status*:: No known IP claims. *Contributors*:: @@ -21,6 +21,7 @@ include::{generated}/meta/{refprefix}VK_EXT_video_encode_h265.adoc[] - Ravi Chaudhary, NVIDIA - Daniel Rakos, RasterGrid - Aidan Fabius, Core Avionics & Industrial Inc. + - Lynne Iribarren, Independent === Description @@ -28,7 +29,14 @@ This extension builds upon the `apiext:VK_KHR_video_encode_queue` extension by adding support for encoding elementary video stream sequences compliant with the H.265/HEVC video compression standard. -include::{generated}/interfaces/VK_EXT_video_encode_h265.adoc[] +[NOTE] +.Note +==== +This extension was promoted to `KHR` from the provisional extension +`VK_EXT_video_encode_h265`. +==== + +include::{generated}/interfaces/VK_KHR_video_encode_h265.adoc[] === Version History @@ -80,7 +88,7 @@ include::{generated}/interfaces/VK_EXT_video_encode_h265.adoc[] `VkVideoEncodeH265ReferenceListsInfoEXT` from `uint8_t` to `uint32_t` ** Changed the type of `VkVideoEncodeH265RateControlInfoEXT::subLayerCount` and - `VkVideoEncodeH264RateControlLayerInfoEXT::temporalId` from `uint8_t` + `VkVideoEncodeH265RateControlLayerInfoEXT::temporalId` from `uint8_t` to `uint32_t` ** Removed `VkVideoEncodeH265InputModeFlagsEXT` and `VkVideoEncodeH265OutputModeFlagsEXT` as we only support @@ -89,8 +97,8 @@ include::{generated}/interfaces/VK_EXT_video_encode_h265.adoc[] `pStdPictureInfo` ** Rename `pSliceSegmentHeaderStd` in `VkVideoEncodeH265NaluSliceSegmentInfoEXT` to `pStdSliceSegmentHeader` - ** Rename `pReferenceFinalLists` in `VkVideoEncodeH264VclFrameInfoEXT` and - `VkVideoEncodeH264NaluSliceInfoEXT` to `pStdReferenceFinalLists` + ** Rename `pReferenceFinalLists` in `VkVideoEncodeH265VclFrameInfoEXT` and + `VkVideoEncodeH265NaluSliceSegmentInfoEXT` to `pStdReferenceFinalLists` ** Removed the `slotIndex` member of `VkVideoEncodeH265DpbSlotInfoEXT` and changed it to be chained to `VkVideoReferenceSlotInfoKHR` ** Replaced `VkVideoEncodeH265ReferenceListsInfoEXT` with the new Video @@ -154,3 +162,9 @@ include::{generated}/interfaces/VK_EXT_video_encode_h265.adoc[] ** Fixed optionality of the array members of `VkVideoEncodeH265SessionParametersAddInfoEXT` ** Fixed optionality of `VkVideoEncodeH265RateControlInfoEXT::flags` + * Revision 13, 2023-09-04 (Daniel Rakos) + ** Change extension from `EXT` to `KHR` + ** Extension is no longer provisional + * Revision 14, 2023-12-05 (Daniel Rakos) + ** Condition reference picture setup based on the value of + `StdVideoEncodeH265PictureInfo::flags.is_reference` diff --git a/appendices/VK_KHR_video_encode_queue.adoc b/appendices/VK_KHR_video_encode_queue.adoc index 751783591..4dfa54466 100644 --- a/appendices/VK_KHR_video_encode_queue.adoc +++ b/appendices/VK_KHR_video_encode_queue.adoc @@ -7,7 +7,7 @@ include::{generated}/meta/{refprefix}VK_KHR_video_encode_queue.adoc[] === Other Extension Metadata *Last Modified Date*:: - 2023-07-19 + 2023-12-05 *IP Status*:: No known IP claims. *Contributors*:: @@ -25,6 +25,7 @@ include::{generated}/meta/{refprefix}VK_KHR_video_encode_queue.adoc[] - Daniel Rakos, RasterGrid - Ping Liu, Intel - Aidan Fabius, Core Avionics & Industrial Inc. + - Lynne Iribarren, Independent === Description @@ -42,21 +43,6 @@ compression standards. include::{generated}/interfaces/VK_KHR_video_encode_queue.adoc[] -=== Issues - -1) Why is there no `VK_PIPELINE_STAGE_VIDEO_ENCODE_BIT_KHR`? - -*RESOLVED*: This extension requires `VK_KHR_synchronization2` because the -new access flags introduced did not fit in the 32-bit enum -`VkAccessFlagBits`. -Accordingly, all new pipeline stage and access flags have been added to the -corresponding 64-bit enum and no new flags have been added to the legacy -32-bit enums. -While the new pipeline stage flag introduced uses bit #27 which would also -fit in the legacy `VkPipelineStageFlagBits` enum, there is no real benefit -to include it. -Instead the bit is marked reserved. - === Version History * Revision 1, 2018-07-23 (Ahmed Abdelkhalek) @@ -130,3 +116,12 @@ Instead the bit is marked reserved. ** Added `VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR` query result status code and the related capability flag `VK_VIDEO_ENCODE_CAPABILITY_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_DETECTION_BIT_KHR` + * Revision 11, 2023-09-04 (Daniel Rakos) + ** Extension is no longer provisional + * Revision 12, 2023-12-05 (Daniel Rakos) + ** Require the specification of a reconstructed picture in all cases, + except when the video session was created with no DPB slots to match + shipping implementations + ** Make DPB slot activation behavior codec-specific to continue allowing + application control over reference picture setup now that a + reconstructed picture is always mandatory diff --git a/appendices/VK_KHR_video_maintenance1.adoc b/appendices/VK_KHR_video_maintenance1.adoc new file mode 100644 index 000000000..557579afe --- /dev/null +++ b/appendices/VK_KHR_video_maintenance1.adoc @@ -0,0 +1,45 @@ +// Copyright 201232023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_KHR_video_maintenance1.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2023-07-27 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Ahmed Abdelkhalek, AMD + - Aidan Fabius, Core Avionics & Industrial Inc. + - Ping Liu, Intel + - Lynne Iribarren, Independent + - Srinath Kumarapuram, NVIDIA + - Tony Zlatinski, NVIDIA + - Daniel Rakos, RasterGrid + +=== Description + +`VK_KHR_video_maintenance1` adds a collection of minor video coding +features, none of which would warrant an entire extension of their own. + +The new features are as follows: + + * Allow creating buffers that can be used in video coding operations, + independent of the used video profile, using the new buffer creation + flag ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. + * Allow creating images that can be used as decode output or encode input + pictures, independent of the used video profile, using the new image + creation flag ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. + * Allow specifying queries used by video coding operations as part of the + video coding command parameters, instead of using begin/end query when + the video session is created using the new video session creation flag + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR. + +include::{generated}/interfaces/VK_KHR_video_maintenance1.adoc[] + +=== Version History + + * Revision 1, 2023-07-27 (Daniel Rakos) + ** internal revisions diff --git a/appendices/VK_NV_per_stage_descriptor_set.adoc b/appendices/VK_NV_per_stage_descriptor_set.adoc new file mode 100644 index 000000000..f86066a8c --- /dev/null +++ b/appendices/VK_NV_per_stage_descriptor_set.adoc @@ -0,0 +1,46 @@ +// Copyright 2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/{refprefix}VK_NV_per_stage_descriptor_set.adoc[] + +=== Other Extension Metadata + +*Last Modified Date*:: + 2023-10-16 +*IP Status*:: + No known IP claims. +*Contributors*:: + - Daniel Story, Nintendo + +=== Description + +This extension introduces a new descriptor set layout creation flag that +allows bindings in a descriptor set to be scoped to each shader stage. +This means that shaders bound at the same time may: use completely different +descriptor set layouts without any restrictions on compatibility, and that +the descriptor limits that would otherwise apply to the union of all stages +together instead apply to each stage individually. +It also means that descriptors shared by multiple stages must: be bound to +each stage or set of stages that use a unique descriptor set layout using +their specific per stage descriptor set layout(s). + +This extension also allows each of the new descriptor binding functions from +VK_KHR_maintenance6 to have their slink:VkPipelineLayout member be +optionally set to dlink:VK_NULL_HANDLE, in which case the pipeline layout +information is taken from a slink:VkPipelineLayoutCreateInfo structure in +the pname:pNext chain. +This enables descriptors to be directly bound using descriptor set layouts +without applications needing to create and manage slink:VkPipelineLayout +objects at command recording time. + +include::{generated}/interfaces/VK_NV_per_stage_descriptor_set.adoc[] + +=== Issues + +None + +=== Version History + + * Revision 1, 2023-10-16 (Piers Daniell) + ** Initial draft diff --git a/appendices/boilerplate.adoc b/appendices/boilerplate.adoc index 2469a13bd..417b6bf2e 100644 --- a/appendices/boilerplate.adoc +++ b/appendices/boilerplate.adoc @@ -442,11 +442,11 @@ associated with the externally-provided video compression standards. |==== | Video Std Header Name | Description | Header File | Related Extensions | `vulkan_video_codecs_common` | Codec-independent common definitions | `` | - -| `vulkan_video_codec_h264std` | ITU-T H.264 common definitions | `` | apiext:VK_KHR_video_decode_h264, apiext:VK_EXT_video_encode_h264 +| `vulkan_video_codec_h264std` | ITU-T H.264 common definitions | `` | apiext:VK_KHR_video_decode_h264, apiext:VK_KHR_video_encode_h264 | `vulkan_video_codec_h264std_decode` | ITU-T H.264 decode-specific definitions | `` | apiext:VK_KHR_video_decode_h264 -| `vulkan_video_codec_h264std_encode` | ITU-T H.264 encode-specific definitions | `` | apiext:VK_EXT_video_encode_h264 -| `vulkan_video_codec_h265std` | ITU-T H.265 common definitions | `` | apiext:VK_KHR_video_decode_h265, apiext:VK_EXT_video_encode_h265 +| `vulkan_video_codec_h264std_encode` | ITU-T H.264 encode-specific definitions | `` | apiext:VK_KHR_video_encode_h264 +| `vulkan_video_codec_h265std` | ITU-T H.265 common definitions | `` | apiext:VK_KHR_video_decode_h265, apiext:VK_KHR_video_encode_h265 | `vulkan_video_codec_h265std_decode` | ITU-T H.265 decode-specific definitions | `` | apiext:VK_KHR_video_decode_h265 -| `vulkan_video_codec_h265std_encode` | ITU-T H.265 encode-specific definitions | `` | apiext:VK_EXT_video_encode_h265 +| `vulkan_video_codec_h265std_encode` | ITU-T H.265 encode-specific definitions | `` | apiext:VK_KHR_video_encode_h265 |==== endif::VKSC_VERSION_1_0[] diff --git a/chapters/VK_NV_present_barrier/present_barrier.adoc b/chapters/VK_NV_present_barrier/present_barrier.adoc index aa9b13648..6bf712a7c 100644 --- a/chapters/VK_NV_present_barrier/present_barrier.adoc +++ b/chapters/VK_NV_present_barrier/present_barrier.adoc @@ -21,7 +21,7 @@ barrier, whether or not that queued request has executed. A given presentation request is added, when created by calling flink:vkQueuePresentKHR and specifying a swapchain using the present barrier, either to the oldest existing set of corresponding requests for -which there is no existing member associated with the request's swapcahin, +which there is no existing member associated with the request's swapchain, or to a new set of corresponding requests if no such set exists. A set of corresponding requests is said to be _full_ when it contains one diff --git a/chapters/capabilities.adoc b/chapters/capabilities.adoc index 019c773be..918527662 100644 --- a/chapters/capabilities.adoc +++ b/chapters/capabilities.adoc @@ -872,6 +872,15 @@ To create a descriptor pool that allows allocating four descriptor sets with this layout, pname:descriptorCount must be at least `24`. ==== +ifdef::VK_KHR_maintenance6[] +Instead of querying all the potential formats that the application might use +in the descriptor layout, the application can: use the +slink:VkPhysicalDeviceMaintenance6PropertiesKHR::pname:maxCombinedImageSamplerDescriptorCount +property to determine the maximum descriptor size that that will accommodate +any and all <> supported by the implementation. +endif::VK_KHR_maintenance6[] + endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] diff --git a/chapters/commonvalidity/bind_descriptor_buffer_embedded_samplers_common.adoc b/chapters/commonvalidity/bind_descriptor_buffer_embedded_samplers_common.adoc new file mode 100644 index 000000000..72bce78b8 --- /dev/null +++ b/chapters/commonvalidity/bind_descriptor_buffer_embedded_samplers_common.adoc @@ -0,0 +1,16 @@ +// Copyright 2020-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +// Common Valid Usage +// Common to vkCmdBindDescriptorBufferEmbeddedSamplers* commands + * [[VUID-{refpage}-set-08070]] + The slink:VkDescriptorSetLayout at index pname:set when pname:layout was + created must: have been created with the + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT + bit set + * [[VUID-{refpage}-set-08071]] + pname:set must: be less than or equal to + slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when + pname:layout was created +// Common Valid Usage diff --git a/chapters/commonvalidity/bind_descriptor_sets_common.adoc b/chapters/commonvalidity/bind_descriptor_sets_common.adoc new file mode 100644 index 000000000..98c3c0996 --- /dev/null +++ b/chapters/commonvalidity/bind_descriptor_sets_common.adoc @@ -0,0 +1,60 @@ +// Copyright 2020-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +// Common Valid Usage +// Common to vkCmdBindDescriptorSets* commands + * [[VUID-{refpage}-pDescriptorSets-00358]] + Each element of pname:pDescriptorSets must: have been allocated with a + sname:VkDescriptorSetLayout that matches (is the same as, or identically + defined as) the sname:VkDescriptorSetLayout at set _n_ in pname:layout, + where _n_ is the sum of pname:firstSet and the index into + pname:pDescriptorSets + * [[VUID-{refpage}-dynamicOffsetCount-00359]] + pname:dynamicOffsetCount must: be equal to the total number of dynamic + descriptors in pname:pDescriptorSets + * [[VUID-{refpage}-firstSet-00360]] + The sum of pname:firstSet and pname:descriptorSetCount must: be less + than or equal to slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount + provided when pname:layout was created + * [[VUID-{refpage}-pDynamicOffsets-01971]] + Each element of pname:pDynamicOffsets which corresponds to a descriptor + binding with type ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC must: + be a multiple of + sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment + * [[VUID-{refpage}-pDynamicOffsets-01972]] + Each element of pname:pDynamicOffsets which corresponds to a descriptor + binding with type ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC must: + be a multiple of + sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment + * [[VUID-{refpage}-pDescriptorSets-01979]] + For each dynamic uniform or storage buffer binding in + pname:pDescriptorSets, the sum of the <> and the range of the binding must: be less than or + equal to the size of the buffer + * [[VUID-{refpage}-pDescriptorSets-06715]] + For each dynamic uniform or storage buffer binding in + pname:pDescriptorSets, if the range was set with ename:VK_WHOLE_SIZE + then pname:pDynamicOffsets which corresponds to the descriptor binding + must: be 0 +ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] + * [[VUID-{refpage}-pDescriptorSets-04616]] + Each element of pname:pDescriptorSets must: not have been allocated from + a sname:VkDescriptorPool with the + ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT flag set +endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] + * [[VUID-{refpage}-pDescriptorSets-06563]] + {empty} +ifdef::VK_EXT_graphics_pipeline_library[] + If <> + is not enabled, each +endif::VK_EXT_graphics_pipeline_library[] +ifndef::VK_EXT_graphics_pipeline_library[Each] + element of pname:pDescriptorSets must: be a valid slink:VkDescriptorSet +ifdef::VK_EXT_descriptor_buffer[] + * [[VUID-{refpage}-pDescriptorSets-08010]] + Each element of pname:pDescriptorSets must: have been allocated with a + sname:VkDescriptorSetLayout which was not created with + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT +endif::VK_EXT_descriptor_buffer[] +// Common Valid Usage diff --git a/chapters/commonvalidity/bind_index_buffer_common.adoc b/chapters/commonvalidity/bind_index_buffer_common.adoc index 27cbe4eae..fce565eab 100644 --- a/chapters/commonvalidity/bind_index_buffer_common.adoc +++ b/chapters/commonvalidity/bind_index_buffer_common.adoc @@ -25,4 +25,14 @@ ifdef::VK_EXT_index_type_uint8[] <> feature must: be enabled endif::VK_EXT_index_type_uint8[] + * [[VUID-{refpage}-None-09493]] + {empty} +ifdef::VK_KHR_maintenance6+VK_EXT_robustness2[] + If <> is not enabled, +endif::VK_KHR_maintenance6+VK_EXT_robustness2[] + pname:buffer must: not be dlink:VK_NULL_HANDLE +ifdef::VK_KHR_maintenance6[] + * [[VUID-{refpage}-buffer-09494]] + If pname:buffer is dlink:VK_NULL_HANDLE, offset must: be zero +endif::VK_KHR_maintenance6[] // Common Valid Usage diff --git a/chapters/commonvalidity/draw_indexed_common.adoc b/chapters/commonvalidity/draw_indexed_common.adoc index c48720128..00e3c6f9f 100644 --- a/chapters/commonvalidity/draw_indexed_common.adoc +++ b/chapters/commonvalidity/draw_indexed_common.adoc @@ -5,7 +5,12 @@ // Common Valid Usage // Common to drawing commands that are indexed * [[VUID-{refpage}-None-07312]] - An index buffer must: be bound + {empty} +ifdef::VK_KHR_maintenance6+VK_EXT_robustness2[] + If <> is not enabled, a +endif::VK_KHR_maintenance6+VK_EXT_robustness2[] +ifndef::VK_KHR_maintenance6[A] + valid index buffer must: be bound * [[VUID-{refpage}-robustBufferAccess2-07825]] If <> is not enabled, [eq]#(code:indexSize {times} (pname:firstIndex {plus} diff --git a/chapters/commonvalidity/dynamic_pipeline_layout_common.adoc b/chapters/commonvalidity/dynamic_pipeline_layout_common.adoc new file mode 100644 index 000000000..25712609a --- /dev/null +++ b/chapters/commonvalidity/dynamic_pipeline_layout_common.adoc @@ -0,0 +1,19 @@ +// Copyright 2020-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +// Common Valid Usage +// Common to VK_KHR_maintenance6 bind and push descriptor structs + * [[VUID-{refpage}-None-09495]] + {empty} +ifdef::VK_NV_per_stage_descriptor_set[] + If the <> + feature is not enabled, +endif::VK_NV_per_stage_descriptor_set[] + pname:layout must: be a valid slink:VkPipelineLayout handle +ifdef::VK_NV_per_stage_descriptor_set[] + * [[VUID-{refpage}-layout-09496]] + If pname:layout is dlink:VK_NULL_HANDLE, the pname:pNext chain must: + include a valid slink:VkPipelineLayoutCreateInfo structure +endif::VK_NV_per_stage_descriptor_set[] +// Common Valid Usage diff --git a/chapters/commonvalidity/pipeline_create_info_common.adoc b/chapters/commonvalidity/pipeline_create_info_common.adoc index 8cb62284e..149c4f00e 100644 --- a/chapters/commonvalidity/pipeline_create_info_common.adoc +++ b/chapters/commonvalidity/pipeline_create_info_common.adoc @@ -5,6 +5,14 @@ // Common Valid Usage // common to all pipeline creations ifndef::VKSC_VERSION_1_0[] + * [[VUID-{refpage}-None-09497]] + {empty} +ifdef::VK_KHR_maintenance5[] + If the pname:pNext chain does not include a + slink:VkPipelineCreateFlags2CreateInfoKHR structure, +endif::VK_KHR_maintenance5[] + pname:flags: must be a valid combination of + elink:VkPipelineCreateFlagBits values * [[VUID-{refpage}-flags-07984]] If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must: diff --git a/chapters/commonvalidity/push_constants_common.adoc b/chapters/commonvalidity/push_constants_common.adoc new file mode 100644 index 000000000..44ef2cfe1 --- /dev/null +++ b/chapters/commonvalidity/push_constants_common.adoc @@ -0,0 +1,27 @@ +// Copyright 2020-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +// Common Valid Usage +// Common to vkCmdPushConstants* commands + * [[VUID-{refpage}-offset-01795]] + For each byte in the range specified by pname:offset and pname:size and + for each shader stage in pname:stageFlags, there must: be a push + constant range in pname:layout that includes that byte and that stage + * [[VUID-{refpage}-offset-01796]] + For each byte in the range specified by pname:offset and pname:size and + for each push constant range that overlaps that byte, pname:stageFlags + must: include all stages in that push constant range's + slink:VkPushConstantRange::pname:stageFlags + * [[VUID-{refpage}-offset-00368]] + pname:offset must: be a multiple of `4` + * [[VUID-{refpage}-size-00369]] + pname:size must: be a multiple of `4` + * [[VUID-{refpage}-offset-00370]] + pname:offset must: be less than + sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize + * [[VUID-{refpage}-size-00371]] + pname:size must: be less than or equal to + sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus + pname:offset +// Common Valid Usage diff --git a/chapters/commonvalidity/push_descriptor_set_common.adoc b/chapters/commonvalidity/push_descriptor_set_common.adoc new file mode 100644 index 000000000..e61d517a0 --- /dev/null +++ b/chapters/commonvalidity/push_descriptor_set_common.adoc @@ -0,0 +1,26 @@ +// Copyright 2020-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +// Common Valid Usage +// Common to vkCmdPushDescriptorSet* commands + * [[VUID-{refpage}-set-00364]] + pname:set must: be less than + slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when + pname:layout was created + * [[VUID-{refpage}-set-00365]] + pname:set must: be the unique set number in the pipeline layout that + uses a descriptor set layout that was created with + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR + * [[VUID-{refpage}-pDescriptorWrites-06494]] + For each element [eq]#i# where + pname:pDescriptorWrites[i].pname:descriptorType is + ename:VK_DESCRIPTOR_TYPE_SAMPLER, + ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, + ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, + ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or + ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, + pname:pDescriptorWrites[i].pname:pImageInfo must: be a valid pointer to + an array of pname:pDescriptorWrites[i].pname:descriptorCount valid + sname:VkDescriptorImageInfo structures +// Common Valid Usage diff --git a/chapters/commonvalidity/push_descriptor_set_with_template_common.adoc b/chapters/commonvalidity/push_descriptor_set_with_template_common.adoc new file mode 100644 index 000000000..8f03e7ad4 --- /dev/null +++ b/chapters/commonvalidity/push_descriptor_set_with_template_common.adoc @@ -0,0 +1,35 @@ +// Copyright 2020-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +// Common Valid Usage +// Common to vkCmdPushDescriptorSetWithTemplate* commands + * [[VUID-{refpage}-commandBuffer-00366]] + The pname:pipelineBindPoint specified during the creation of the + descriptor update template must: be supported by the + pname:commandBuffer's parent sname:VkCommandPool's queue family + * [[VUID-{refpage}-pData-01686]] + pname:pData must: be a valid pointer to a memory containing one or more + valid instances of slink:VkDescriptorImageInfo, + slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined + by pname:descriptorUpdateTemplate when it was created with + flink:vkCreateDescriptorUpdateTemplate + * [[VUID-{refpage}-layout-07993]] + pname:layout must: be compatible with the layout used to create + pname:descriptorUpdateTemplate + * [[VUID-{refpage}-descriptorUpdateTemplate-07994]] + pname:descriptorUpdateTemplate must: have been created with a + pname:templateType of + ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR + * [[VUID-{refpage}-set-07995]] + pname:set must: be the same value used to create + pname:descriptorUpdateTemplate + * [[VUID-{refpage}-set-07304]] + pname:set must: be less than + slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when + pname:layout was created + * [[VUID-{refpage}-set-07305]] + pname:set must: be the unique set number in the pipeline layout that + uses a descriptor set layout that was created with + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR +// Common Valid Usage diff --git a/chapters/commonvalidity/query_begin_common.adoc b/chapters/commonvalidity/query_begin_common.adoc index 405f0f91f..dae6288c6 100644 --- a/chapters/commonvalidity/query_begin_common.adoc +++ b/chapters/commonvalidity/query_begin_common.adoc @@ -76,6 +76,11 @@ ifdef::VK_KHR_video_queue[] * [[VUID-{refpage}-None-07127]] If there is a bound video session, then there must: be no <> queries +ifdef::VK_KHR_video_maintenance1[] + * [[VUID-{refpage}-None-08370]] + If there is a bound video session, then it must: not have been created + with ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR +endif::VK_KHR_video_maintenance1[] * [[VUID-{refpage}-queryType-07128]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR and there is a bound video @@ -86,11 +91,6 @@ ifdef::VK_KHR_video_queue[] session was created with endif::VK_KHR_video_queue[] ifdef::VK_KHR_video_encode_queue[] - * [[VUID-{refpage}-queryType-04862]] - If the pname:queryType used to create pname:queryPool was - ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, then the - sname:VkCommandPool that pname:commandBuffer was allocated from must: - support <> * [[VUID-{refpage}-queryType-07129]] If the pname:queryType used to create pname:queryPool was ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, then there must: be a diff --git a/chapters/commonvalidity/set_descriptor_buffer_offsets_common.adoc b/chapters/commonvalidity/set_descriptor_buffer_offsets_common.adoc new file mode 100644 index 000000000..c9cda6466 --- /dev/null +++ b/chapters/commonvalidity/set_descriptor_buffer_offsets_common.adoc @@ -0,0 +1,44 @@ +// Copyright 2020-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +// Common Valid Usage +// Common to vkCmdSetDescriptorBufferOffsets* commands + * [[VUID-{refpage}-pOffsets-08061]] + The offsets in pname:pOffsets must: be aligned to + slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:descriptorBufferOffsetAlignment + * [[VUID-{refpage}-pOffsets-08063]] + The offsets in pname:pOffsets must: be small enough such that any + descriptor binding referenced by pname:layout +ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] + without the ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT + flag +endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] + computes a valid address inside the underlying slink:VkBuffer + * [[VUID-{refpage}-pOffsets-08126]] + The offsets in pname:pOffsets must: be small enough such that any + location accessed by a shader as a sampler descriptor must: be within + slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxSamplerDescriptorBufferRange + of the sampler descriptor buffer binding + * [[VUID-{refpage}-pOffsets-08127]] + The offsets in pname:pOffsets must: be small enough such that any + location accessed by a shader as a resource descriptor must: be within + slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxResourceDescriptorBufferRange + of the resource descriptor buffer binding + * [[VUID-{refpage}-pBufferIndices-08064]] + Each element of pname:pBufferIndices must: be less than + slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxDescriptorBufferBindings + * [[VUID-{refpage}-pBufferIndices-08065]] + Each element of pname:pBufferIndices must: reference a valid descriptor + buffer binding set by a previous call to + flink:vkCmdBindDescriptorBuffersEXT in pname:commandBuffer + * [[VUID-{refpage}-firstSet-08066]] + The sum of pname:firstSet and pname:setCount must: be less than or equal + to slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when + pname:layout was created + * [[VUID-{refpage}-firstSet-09006]] + The slink:VkDescriptorSetLayout for each set from pname:firstSet to + [eq]#pname:firstSet {plus} pname:setCount# when pname:layout was created + must: have been created with the + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT bit set +// Common Valid Usage diff --git a/chapters/descriptorsets.adoc b/chapters/descriptorsets.adoc index 21f6ef963..8bf4d6797 100644 --- a/chapters/descriptorsets.adoc +++ b/chapters/descriptorsets.adoc @@ -597,7 +597,15 @@ endif::VK_KHR_push_descriptor[] .Valid Usage **** * [[VUID-VkDescriptorSetLayoutCreateInfo-binding-00279]] - The slink:VkDescriptorSetLayoutBinding::pname:binding members of the +ifdef::VK_NV_per_stage_descriptor_set[] + If the <> + feature is not enabled, or pname:flags does not contain + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PER_STAGE_BIT_NV, then the +endif::VK_NV_per_stage_descriptor_set[] +ifndef::VK_NV_per_stage_descriptor_set[] + The +endif::VK_NV_per_stage_descriptor_set[] + slink:VkDescriptorSetLayoutBinding::pname:binding members of the elements of the pname:pBindings array must: each have different values ifdef::VK_KHR_push_descriptor[] * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-00280]] @@ -710,6 +718,20 @@ ifdef::VK_VALVE_mutable_descriptor_type[] ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_HOST_ONLY_POOL_BIT_VALVE endif::VK_VALVE_mutable_descriptor_type[] endif::VK_EXT_descriptor_buffer[] +ifdef::VK_NV_per_stage_descriptor_set[] + * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-09463]] + If pname:flags contains + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PER_STAGE_BIT_NV, then + <> must: be + enabled + * [[VUID-VkDescriptorSetLayoutCreateInfo-flags-09464]] + If pname:flags contains + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PER_STAGE_BIT_NV, then there must: + not be any two elements of the pname:pBindings array with the same + slink:VkDescriptorSetLayoutBinding::pname:binding value and their + slink:VkDescriptorSetLayoutBinding::pname:stageFlags containing the same + bit +endif::VK_NV_per_stage_descriptor_set[] **** include::{generated}/validity/structs/VkDescriptorSetLayoutCreateInfo.adoc[] @@ -868,6 +890,11 @@ ifndef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] non-UpdateAfterBind limits. endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] +ifdef::VK_NV_per_stage_descriptor_set[] + * ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PER_STAGE_BIT_NV specifies that + binding numbers in descriptor sets using this layout may: represent + different resources and/or types of resources in each stage. +endif::VK_NV_per_stage_descriptor_set[] ifndef::VK_KHR_push_descriptor[] [NOTE] @@ -1004,9 +1031,10 @@ ifdef::VK_EXT_descriptor_buffer[] must: not be `NULL` endif::VK_EXT_descriptor_buffer[] endif::VK_VERSION_1_3,VK_EXT_inline_uniform_block[] - * [[VUID-VkDescriptorSetLayoutBinding-descriptorCount-00283]] - If pname:descriptorCount is not `0`, pname:stageFlags must: be a valid - combination of elink:VkShaderStageFlagBits values + * [[VUID-VkDescriptorSetLayoutBinding-descriptorCount-09465]] + If pname:descriptorCount is not `0`, pname:stageFlags must: be + ename:VK_SHADER_STAGE_ALL or a valid combination of other + elink:VkShaderStageFlagBits values * [[VUID-VkDescriptorSetLayoutBinding-descriptorType-01510]] If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT and pname:descriptorCount is not `0`, then pname:stageFlags must: be `0` or @@ -1029,6 +1057,17 @@ ifdef::VKSC_VERSION_1_0[] slink:VkDeviceObjectReservationCreateInfo::pname:descriptorSetLayoutBindingLimit provided when the device was created endif::VKSC_VERSION_1_0[] +ifdef::VK_NV_per_stage_descriptor_set[] + * [[VUID-VkDescriptorSetLayoutBinding-flags-09466]] + If slink:VkDescriptorSetLayoutCreateInfo::pname:flags contains + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PER_STAGE_BIT_NV, and + pname:descriptorCount is not `0`, then pname:stageFlags must: be a valid + combination of ename:VK_SHADER_STAGE_VERTEX_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, + ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, + ename:VK_SHADER_STAGE_GEOMETRY_BIT, ename:VK_SHADER_STAGE_FRAGMENT_BIT + and ename:VK_SHADER_STAGE_COMPUTE_BIT values +endif::VK_NV_per_stage_descriptor_set[] **** include::{generated}/validity/structs/VkDescriptorSetLayoutBinding.adoc[] @@ -2727,6 +2766,14 @@ image samplers of multi-planar formats, an application needs to account for non-trivial descriptor consumption when choosing the pname:descriptorCount value, as indicated by slink:VkSamplerYcbcrConversionImageFormatProperties::pname:combinedImageSamplerDescriptorCount. + +ifdef::VK_KHR_maintenance6[] +For simplicity the application can: use the +slink:VkPhysicalDeviceMaintenance6PropertiesKHR::pname:maxCombinedImageSamplerDescriptorCount +property, which is sized to accommodate any and all +<> supported by the implementation. +endif::VK_KHR_maintenance6[] ==== endif::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] @@ -2990,9 +3037,9 @@ ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] the pname:pNext chain, and sname:VkDescriptorSetVariableDescriptorCountAllocateInfo::pname:descriptorSetCount is not zero, then - slink:VkDescriptorSetVariableDescriptorCountAllocateInfo::pDescriptorCounts[i] + slink:VkDescriptorSetVariableDescriptorCountAllocateInfo::pname:pDescriptorCounts[i] must: be less than or equal to - slink:VkDescriptorSetLayoutBinding::descriptorCount for the + slink:VkDescriptorSetLayoutBinding::pname:descriptorCount for the corresponding binding used to create pname:pSetLayouts[i] endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] @@ -4782,6 +4829,8 @@ endif::VKSC_VERSION_1_0[] [open,refpage='vkCmdBindDescriptorSets',desc='Binds descriptor sets to a command buffer',type='protos'] -- +:refpage: vkCmdBindDescriptorSets + To bind one or more descriptor sets to a command buffer, call: include::{generated}/api/protos/vkCmdBindDescriptorSets.adoc[] @@ -4911,48 +4960,10 @@ descriptor set. .Valid Usage **** - * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-00358]] - Each element of pname:pDescriptorSets must: have been allocated with a - sname:VkDescriptorSetLayout that matches (is the same as, or identically - defined as) the sname:VkDescriptorSetLayout at set _n_ in pname:layout, - where _n_ is the sum of pname:firstSet and the index into - pname:pDescriptorSets - * [[VUID-vkCmdBindDescriptorSets-dynamicOffsetCount-00359]] - pname:dynamicOffsetCount must: be equal to the total number of dynamic - descriptors in pname:pDescriptorSets - * [[VUID-vkCmdBindDescriptorSets-firstSet-00360]] - The sum of pname:firstSet and pname:descriptorSetCount must: be less - than or equal to slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount - provided when pname:layout was created +include::{chapters}/commonvalidity/bind_descriptor_sets_common.adoc[] * [[VUID-vkCmdBindDescriptorSets-pipelineBindPoint-00361]] pname:pipelineBindPoint must: be supported by the pname:commandBuffer's parent sname:VkCommandPool's queue family - * [[VUID-vkCmdBindDescriptorSets-pDynamicOffsets-01971]] - Each element of pname:pDynamicOffsets which corresponds to a descriptor - binding with type ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC must: - be a multiple of - sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment - * [[VUID-vkCmdBindDescriptorSets-pDynamicOffsets-01972]] - Each element of pname:pDynamicOffsets which corresponds to a descriptor - binding with type ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC must: - be a multiple of - sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment - * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-01979]] - For each dynamic uniform or storage buffer binding in - pname:pDescriptorSets, the sum of the <> and the range of the binding must: be less than or - equal to the size of the buffer - * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-06715]] - For each dynamic uniform or storage buffer binding in - pname:pDescriptorSets, if the range was set with ename:VK_WHOLE_SIZE - then pname:pDynamicOffsets which corresponds to the descriptor binding - must: be 0 -ifdef::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] - * [[VUID-vkCmdBindDescriptorSets-pDescriptorSets-04616]] - Each element of pname:pDescriptorSets must: not have been allocated from - a sname:VkDescriptorPool with the - ename:VK_DESCRIPTOR_POOL_CREATE_HOST_ONLY_BIT_EXT flag set -endif::VK_EXT_mutable_descriptor_type,VK_VALVE_mutable_descriptor_type[] * [[VUID-vkCmdBindDescriptorSets-graphicsPipelineLibrary-06754]] ifdef::VK_EXT_graphics_pipeline_library[] If <> @@ -4965,6 +4976,82 @@ ifndef::VK_EXT_graphics_pipeline_library[Each] include::{generated}/validity/protos/vkCmdBindDescriptorSets.adoc[] -- +ifdef::VK_KHR_maintenance6[] +[open,refpage='vkCmdBindDescriptorSets2KHR',desc='Binds descriptor sets to a command buffer',type='protos'] +-- +Alternatively, to bind one or more descriptor sets to a command buffer, +call: + +include::{generated}/api/protos/vkCmdBindDescriptorSets2KHR.adoc[] + + * pname:commandBuffer is the command buffer that the descriptor sets will + be bound to. + * pname:pBindDescriptorSetsInfo is a pointer to a + sname:VkBindDescriptorSetsInfoKHR structure. + +.Valid Usage +**** + * [[VUID-vkCmdBindDescriptorSets2KHR-pBindDescriptorSetsInfo-09467]] + Each bit in pname:pBindDescriptorSetsInfo->stageFlags must: be a stage + supported by the pname:commandBuffer's parent sname:VkCommandPool's + queue family +**** + +include::{generated}/validity/protos/vkCmdBindDescriptorSets2KHR.adoc[] +-- + +[open,refpage='VkBindDescriptorSetsInfoKHR',desc='Structure specifying a descriptor set binding operation',type='structs'] +-- +:refpage: VkBindDescriptorSetsInfoKHR + +The sname:VkBindDescriptorSetsInfoKHR structure is defined as: + +include::{generated}/api/structs/VkBindDescriptorSetsInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:stageFlags is a bitmask of elink:VkShaderStageFlagBits specifying + the shader stages the descriptor sets will be bound to. + * pname:layout is a slink:VkPipelineLayout object used to program the + bindings. +ifdef::VK_NV_per_stage_descriptor_set[] + If the <> + feature is enabled, pname:layout can: be dlink:VK_NULL_HANDLE and the + layout must: be specified by chaining the + slink:VkPipelineLayoutCreateInfo structure off the pname:pNext +endif::VK_NV_per_stage_descriptor_set[] + * pname:firstSet is the set number of the first descriptor set to be + bound. + * pname:descriptorSetCount is the number of elements in the + pname:pDescriptorSets array. + * pname:pDescriptorSets is a pointer to an array of handles to + slink:VkDescriptorSet objects describing the descriptor sets to bind to. + * pname:dynamicOffsetCount is the number of dynamic offsets in the + pname:pDynamicOffsets array. + * pname:pDynamicOffsets is a pointer to an array of code:uint32_t values + specifying dynamic offsets. + +If pname:stageFlags specifies a subset of all stages corresponding to one or +more pipeline bind points, the binding operation still affects all stages +corresponding to the given pipeline bind point(s) as if the equivalent +original version of this command had been called with the same parameters. +For example, specifying a pname:stageFlags value of +ename:VK_SHADER_STAGE_VERTEX_BIT | ename:VK_SHADER_STAGE_FRAGMENT_BIT | +ename:VK_SHADER_STAGE_COMPUTE_BIT is equivalent to calling the original +version of this command once with ename:VK_PIPELINE_BIND_POINT_GRAPHICS and +once with ename:VK_PIPELINE_BIND_POINT_COMPUTE. + +.Valid Usage +**** +include::{chapters}/commonvalidity/bind_descriptor_sets_common.adoc[] +include::{chapters}/commonvalidity/dynamic_pipeline_layout_common.adoc[] +**** + +include::{generated}/validity/structs/VkBindDescriptorSetsInfoKHR.adoc[] +-- +endif::VK_KHR_maintenance6[] + ifdef::VK_KHR_push_descriptor[] [[descriptorsets-push-descriptors]] @@ -4972,6 +5059,8 @@ ifdef::VK_KHR_push_descriptor[] [open,refpage='vkCmdPushDescriptorSetKHR',desc='Pushes descriptor updates into a command buffer',type='protos'] -- +:refpage: vkCmdPushDescriptorSetKHR + In addition to allocating descriptor sets and binding them to a command buffer, an application can: record descriptor updates into the command buffer. @@ -5041,37 +5130,95 @@ pipeline layout. .Valid Usage **** +include::{chapters}/commonvalidity/push_descriptor_set_common.adoc[] * [[VUID-vkCmdPushDescriptorSetKHR-pipelineBindPoint-00363]] pname:pipelineBindPoint must: be supported by the pname:commandBuffer's parent sname:VkCommandPool's queue family - * [[VUID-vkCmdPushDescriptorSetKHR-set-00364]] - pname:set must: be less than - slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when - pname:layout was created - * [[VUID-vkCmdPushDescriptorSetKHR-set-00365]] - pname:set must: be the unique set number in the pipeline layout that - uses a descriptor set layout that was created with - ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR - * [[VUID-vkCmdPushDescriptorSetKHR-pDescriptorWrites-06494]] - For each element [eq]#i# where - pname:pDescriptorWrites[i].pname:descriptorType is - ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, - ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or - ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, - pname:pDescriptorWrites[i].pname:pImageInfo must: be a valid pointer to - an array of pname:pDescriptorWrites[i].pname:descriptorCount valid - sname:VkDescriptorImageInfo structures **** include::{generated}/validity/protos/vkCmdPushDescriptorSetKHR.adoc[] -- +ifdef::VK_KHR_maintenance6[] +[open,refpage='vkCmdPushDescriptorSet2KHR',desc='Pushes descriptor updates into a command buffer',type='protos'] +-- +Alternatively, to push descriptor updates into a command buffer, call: + +include::{generated}/api/protos/vkCmdPushDescriptorSet2KHR.adoc[] + + * pname:commandBuffer is the command buffer that the descriptors will be + recorded in. + * pname:pPushDescriptorSetInfo is a pointer to a + sname:VkPushDescriptorSetInfoKHR structure. + +.Valid Usage +**** + * [[VUID-vkCmdPushDescriptorSet2KHR-pPushDescriptorSetInfo-09468]] + Each bit in pname:pPushDescriptorSetInfo->stageFlags must: be a stage + supported by the pname:commandBuffer's parent sname:VkCommandPool's + queue family +**** + +include::{generated}/validity/protos/vkCmdPushDescriptorSet2KHR.adoc[] +-- + +[open,refpage='VkPushDescriptorSetInfoKHR',desc='Structure specifying a descriptor set push operation',type='structs'] +-- +:refpage: VkPushDescriptorSetInfoKHR + +The sname:VkPushDescriptorSetInfoKHR structure is defined as: + +include::{generated}/api/structs/VkPushDescriptorSetInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:stageFlags is a bitmask of elink:VkShaderStageFlagBits specifying + the shader stages that will use the descriptors. + * pname:layout is a slink:VkPipelineLayout object used to program the + bindings. +ifdef::VK_NV_per_stage_descriptor_set[] + If the <> + feature is enabled, pname:layout can: be dlink:VK_NULL_HANDLE and the + layout must: be specified by chaining slink:VkPipelineLayoutCreateInfo + structure off the pname:pNext +endif::VK_NV_per_stage_descriptor_set[] + * pname:set is the set number of the descriptor set in the pipeline layout + that will be updated. + * pname:descriptorWriteCount is the number of elements in the + pname:pDescriptorWrites array. + * pname:pDescriptorWrites is a pointer to an array of + slink:VkWriteDescriptorSet structures describing the descriptors to be + updated. + +If pname:stageFlags specifies a subset of all stages corresponding to one or +more pipeline bind points, the binding operation still affects all stages +corresponding to the given pipeline bind point(s) as if the equivalent +original version of this command had been called with the same parameters. +For example, specifying a pname:stageFlags value of +ename:VK_SHADER_STAGE_VERTEX_BIT | ename:VK_SHADER_STAGE_FRAGMENT_BIT | +ename:VK_SHADER_STAGE_COMPUTE_BIT is equivalent to calling the original +version of this command once with ename:VK_PIPELINE_BIND_POINT_GRAPHICS and +once with ename:VK_PIPELINE_BIND_POINT_COMPUTE. + +.Valid Usage +**** +include::{chapters}/commonvalidity/push_descriptor_set_common.adoc[] +include::{chapters}/commonvalidity/dynamic_pipeline_layout_common.adoc[] +**** + +include::{generated}/validity/structs/VkPushDescriptorSetInfoKHR.adoc[] +-- +endif::VK_KHR_maintenance6[] + ifdef::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] === Push Descriptor Updates With Descriptor Update Templates [open,refpage='vkCmdPushDescriptorSetWithTemplateKHR',desc='Pushes descriptor updates into a command buffer using a descriptor update template',type='protos'] -- +:refpage: vkCmdPushDescriptorSetWithTemplateKHR + It is also possible to use a descriptor update template to specify the push descriptors to update. To do so, call: @@ -5095,34 +5242,7 @@ include::{generated}/api/protos/vkCmdPushDescriptorSetWithTemplateKHR.adoc[] .Valid Usage **** - * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-commandBuffer-00366]] - The pname:pipelineBindPoint specified during the creation of the - descriptor update template must: be supported by the - pname:commandBuffer's parent sname:VkCommandPool's queue family - * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-pData-01686]] - pname:pData must: be a valid pointer to a memory containing one or more - valid instances of slink:VkDescriptorImageInfo, - slink:VkDescriptorBufferInfo, or slink:VkBufferView in a layout defined - by pname:descriptorUpdateTemplate when it was created with - flink:vkCreateDescriptorUpdateTemplate - * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-layout-07993]] - pname:layout must: be compatible with the layout used to create - pname:descriptorUpdateTemplate - * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-descriptorUpdateTemplate-07994]] - pname:descriptorUpdateTemplate must: have been created with a - pname:templateType of - ename:VK_DESCRIPTOR_UPDATE_TEMPLATE_TYPE_PUSH_DESCRIPTORS_KHR - * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-set-07995]] - pname:set must: be the same value used to create - pname:descriptorUpdateTemplate - * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-set-07304]] - pname:set must: be less than - slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when - pname:layout was created - * [[VUID-vkCmdPushDescriptorSetWithTemplateKHR-set-07305]] - pname:set must: be the unique set number in the pipeline layout that - uses a descriptor set layout that was created with - ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR +include::{chapters}/commonvalidity/push_descriptor_set_with_template_common.adoc[] **** include::{generated}/validity/protos/vkCmdPushDescriptorSetWithTemplateKHR.adoc[] @@ -5177,6 +5297,63 @@ AppDataStructure appData; vkCmdPushDescriptorSetWithTemplateKHR(myCmdBuffer, myDescriptorUpdateTemplate, myPipelineLayout, 0,&appData); ---- -- + +ifdef::VK_KHR_maintenance6[] +[open,refpage='vkCmdPushDescriptorSetWithTemplate2KHR',desc='Pushes descriptor updates into a command buffer using a descriptor update template',type='protos'] +-- +Alternatively, to use a descriptor update template to specify the push +descriptors to update, call: + +include::{generated}/api/protos/vkCmdPushDescriptorSetWithTemplate2KHR.adoc[] + + * pname:commandBuffer is the command buffer that the descriptors will be + recorded in. + * pname:pPushDescriptorSetWithTemplateInfo is a pointer to a + sname:VkPushDescriptorSetWithTemplateInfoKHR structure. + +include::{generated}/validity/protos/vkCmdPushDescriptorSetWithTemplate2KHR.adoc[] +-- + +[open,refpage='VkPushDescriptorSetWithTemplateInfoKHR',desc='Structure specifying a descriptor set push operation using a descriptor update template',type='structs'] +-- +:refpage: VkPushDescriptorSetWithTemplateInfoKHR + +The sname:VkPushDescriptorSetWithTemplateInfoKHR structure is defined as: + +include::{generated}/api/structs/VkPushDescriptorSetWithTemplateInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:descriptorUpdateTemplate is a descriptor update template defining + how to interpret the descriptor information in pname:pData. + * pname:layout is a slink:VkPipelineLayout object used to program the + bindings. + It must: be compatible with the layout used to create the + pname:descriptorUpdateTemplate handle. +ifdef::VK_NV_per_stage_descriptor_set[] + If the <> + feature is enabled, pname:layout can: be dlink:VK_NULL_HANDLE and the + layout must: be specified by chaining slink:VkPipelineLayoutCreateInfo + structure off the pname:pNext +endif::VK_NV_per_stage_descriptor_set[] + * pname:set is the set number of the descriptor set in the pipeline layout + that will be updated. + This must: be the same number used to create the + pname:descriptorUpdateTemplate handle. + * pname:pData is a pointer to memory containing descriptors for the + templated update. + +.Valid Usage +**** +include::{chapters}/commonvalidity/push_descriptor_set_with_template_common.adoc[] +include::{chapters}/commonvalidity/dynamic_pipeline_layout_common.adoc[] +**** + +include::{generated}/validity/structs/VkPushDescriptorSetWithTemplateInfoKHR.adoc[] +-- +endif::VK_KHR_maintenance6[] + endif::VK_VERSION_1_1,VK_KHR_descriptor_update_template[] endif::VK_KHR_push_descriptor[] @@ -5198,6 +5375,8 @@ pipelines that is expected to outperform memory-backed resource updates. [open,refpage='vkCmdPushConstants',desc='Update the values of push constants',type='protos'] -- +:refpage: vkCmdPushConstants + To update push constants, call: include::{generated}/api/protos/vkCmdPushConstants.adoc[] @@ -5245,31 +5424,65 @@ created on are ignored. .Valid Usage **** - * [[VUID-vkCmdPushConstants-offset-01795]] - For each byte in the range specified by pname:offset and pname:size and - for each shader stage in pname:stageFlags, there must: be a push - constant range in pname:layout that includes that byte and that stage - * [[VUID-vkCmdPushConstants-offset-01796]] - For each byte in the range specified by pname:offset and pname:size and - for each push constant range that overlaps that byte, pname:stageFlags - must: include all stages in that push constant range's - slink:VkPushConstantRange::pname:stageFlags - * [[VUID-vkCmdPushConstants-offset-00368]] - pname:offset must: be a multiple of `4` - * [[VUID-vkCmdPushConstants-size-00369]] - pname:size must: be a multiple of `4` - * [[VUID-vkCmdPushConstants-offset-00370]] - pname:offset must: be less than - sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize - * [[VUID-vkCmdPushConstants-size-00371]] - pname:size must: be less than or equal to - sname:VkPhysicalDeviceLimits::pname:maxPushConstantsSize minus - pname:offset +include::{chapters}/commonvalidity/push_constants_common.adoc[] **** include::{generated}/validity/protos/vkCmdPushConstants.adoc[] -- +ifdef::VK_KHR_maintenance6[] +[open,refpage='vkCmdPushConstants2KHR',desc='Update the values of push constants',type='protos'] +-- +Alternatively, to update push constants, call: + +include::{generated}/api/protos/vkCmdPushConstants2KHR.adoc[] + + * pname:commandBuffer is the command buffer in which the push constant + update will be recorded. + * pname:pPushConstantsInfo is a pointer to a sname:VkPushConstantsInfoKHR + structure. + +include::{generated}/validity/protos/vkCmdPushConstants2KHR.adoc[] +-- + +[open,refpage='VkPushConstantsInfoKHR',desc='Structure specifying a push constant update operation',type='structs'] +-- +:refpage: VkPushConstantsInfoKHR + +The sname::VkPushConstantsInfoKHR structure is defined as: + +include::{generated}/api/structs/VkPushConstantsInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:layout is the pipeline layout used to program the push constant + updates. +ifdef::VK_NV_per_stage_descriptor_set[] + If the <> + feature is enabled, pname:layout can: be dlink:VK_NULL_HANDLE and the + layout must: be specified by chaining slink:VkPipelineLayoutCreateInfo + structure off the pname:pNext +endif::VK_NV_per_stage_descriptor_set[] + * pname:stageFlags is a bitmask of elink:VkShaderStageFlagBits specifying + the shader stages that will use the push constants in the updated range. + * pname:offset is the start offset of the push constant range to update, + in units of bytes. + * pname:size is the size of the push constant range to update, in units of + bytes. + * pname:pValues is a pointer to an array of pname:size bytes containing + the new push constant values. + +.Valid Usage +**** +include::{chapters}/commonvalidity/push_constants_common.adoc[] +include::{chapters}/commonvalidity/dynamic_pipeline_layout_common.adoc[] +**** + +include::{generated}/validity/structs/VkPushConstantsInfoKHR.adoc[] +-- +endif::VK_KHR_maintenance6[] + ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] [[descriptorsets-physical-storage-buffer]] @@ -5648,6 +5861,12 @@ underlying slink:VkBuffer is referenced instead. The <> feature must: be enabled * [[VUID-vkGetDescriptorEXT-dataSize-08125]] +ifdef::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] + If pname:descriptorType is not + ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER or pname:pImageInfo has + a pname:imageView member that was not created with a + sname:VkSamplerYcbcrConversionInfo structure in its pname:pNext chain, +endif::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] pname:dataSize must: equal the size of a descriptor of type slink:VkDescriptorGetInfoEXT::pname:type determined by the value in slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT @@ -5658,6 +5877,17 @@ ifdef::VK_EXT_fragment_density_map[] ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER whose slink:VkSampler was created with ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT set endif::VK_EXT_fragment_density_map[] +ifdef::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] + * [[VUID-vkGetDescriptorEXT-descriptorType-09469]] + If pname:descriptorType is + ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER and pname:pImageInfo has + a pname:imageView member that was created with a + sname:VkSamplerYcbcrConversionInfo structure in its pname:pNext chain, + pname:dataSize must: equal the size of + slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:combinedImageSamplerDescriptorSize + times + slink:VkSamplerYcbcrConversionImageFormatProperties::pname:combinedImageSamplerDescriptorCount +endif::VK_VULKAN_1_1,VK_KHR_sampler_ycbcr_conversion[] * [[VUID-vkGetDescriptorEXT-pDescriptor-08016]] pname:pDescriptor must: be a valid pointer to an array of at least pname:dataSize bytes @@ -6171,6 +6401,8 @@ include::{generated}/validity/structs/VkDescriptorBufferBindingPushDescriptorBuf [open,refpage='vkCmdSetDescriptorBufferOffsetsEXT',desc='Setting descriptor buffer offsets in a command buffer',type='protos'] -- +:refpage: vkCmdSetDescriptorBufferOffsetsEXT + To set descriptor buffer offsets in a command buffer, call: include::{generated}/api/protos/vkCmdSetDescriptorBufferOffsetsEXT.adoc[] @@ -6271,56 +6503,98 @@ endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] .Valid Usage **** +include::{chapters}/commonvalidity/set_descriptor_buffer_offsets_common.adoc[] * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-None-08060]] The <> feature must: be enabled - * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pOffsets-08061]] - The offsets in pname:pOffsets must: be aligned to - slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:descriptorBufferOffsetAlignment - * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pOffsets-08063]] - The offsets in pname:pOffsets must: be small enough such that any - descriptor binding referenced by pname:layout -ifdef::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] - without the ename:VK_DESCRIPTOR_BINDING_VARIABLE_DESCRIPTOR_COUNT_BIT - flag -endif::VK_VERSION_1_2,VK_EXT_descriptor_indexing[] - computes a valid address inside the underlying slink:VkBuffer - * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pOffsets-08126]] - The offsets in pname:pOffsets must: be small enough such that any - location accessed by a shader as a sampler descriptor must: be within - slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxSamplerDescriptorBufferRange - of the sampler descriptor buffer binding - * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pOffsets-08127]] - The offsets in pname:pOffsets must: be small enough such that any - location accessed by a shader as a resource descriptor must: be within - slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxResourceDescriptorBufferRange - of the resource descriptor buffer binding - * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pBufferIndices-08064]] - Each element of pname:pBufferIndices must: be less than - slink:VkPhysicalDeviceDescriptorBufferPropertiesEXT::pname:maxDescriptorBufferBindings - * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pBufferIndices-08065]] - Each element of pname:pBufferIndices must: reference a valid descriptor - buffer binding set by a previous call to - flink:vkCmdBindDescriptorBuffersEXT in pname:commandBuffer - * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-firstSet-08066]] - The sum of pname:firstSet and pname:setCount must: be less than or equal - to slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when - pname:layout was created * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-pipelineBindPoint-08067]] pname:pipelineBindPoint must: be supported by the pname:commandBuffer's parent sname:VkCommandPool's queue family - * [[VUID-vkCmdSetDescriptorBufferOffsetsEXT-firstSet-09006]] - The slink:VkDescriptorSetLayout for each set from pname:firstSet to - [eq]#pname:firstSet {plus} pname:setCount# when pname:layout was created - must: have been created with the - ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_DESCRIPTOR_BUFFER_BIT_EXT bit set **** include::{generated}/validity/protos/vkCmdSetDescriptorBufferOffsetsEXT.adoc[] -- +ifdef::VK_KHR_maintenance6[] +[open,refpage='vkCmdSetDescriptorBufferOffsets2EXT',desc='Setting descriptor buffer offsets in a command buffer',type='protos'] +-- +Alternatively, to set descriptor buffer offsets in a command buffer, call: + +include::{generated}/api/protos/vkCmdSetDescriptorBufferOffsets2EXT.adoc[] + + * pname:commandBuffer is the command buffer in which the descriptor buffer + offsets will be set. + * pname:pSetDescriptorBufferOffsetsInfo is a pointer to a + sname:VkSetDescriptorBufferOffsetsInfoEXT structure. + +.Valid Usage +**** + * [[VUID-vkCmdSetDescriptorBufferOffsets2EXT-descriptorBuffer-09470]] + The <> feature must: + be enabled + * [[VUID-vkCmdSetDescriptorBufferOffsets2EXT-pSetDescriptorBufferOffsetsInfo-09471]] + Each bit in pname:pSetDescriptorBufferOffsetsInfo->stageFlags must: be a + stage supported by the pname:commandBuffer's parent + sname:VkCommandPool's queue family +**** + +include::{generated}/validity/protos/vkCmdSetDescriptorBufferOffsets2EXT.adoc[] +-- + +[open,refpage='VkSetDescriptorBufferOffsetsInfoEXT',desc='Structure specifying descriptor buffer offsets to set in a command buffer',type='structs'] +-- +:refpage: VkSetDescriptorBufferOffsetsInfoEXT + +The sname::VkSetDescriptorBufferOffsetsInfoEXT structure is defined as: + +include::{generated}/api/structs/VkSetDescriptorBufferOffsetsInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:stageFlags is a bitmask of elink:VkShaderStageFlagBits specifying + the shader stages the descriptor sets will be bound to + * pname:layout is a slink:VkPipelineLayout object used to program the + bindings. +ifdef::VK_NV_per_stage_descriptor_set[] + If the <> + feature is enabled, pname:layout can: be dlink:VK_NULL_HANDLE and the + layout must: be specified by chaining slink:VkPipelineLayoutCreateInfo + structure off the pname:pNext +endif::VK_NV_per_stage_descriptor_set[] + * pname:firstSet is the number of the first set to be bound. + * pname:setCount is the number of elements in the pname:pBufferIndices and + pname:pOffsets arrays. + * pname:pBufferIndices is a pointer to an array of indices into the + descriptor buffer binding points set by + flink:vkCmdBindDescriptorBuffersEXT. + * pname:pOffsets is a pointer to an array of basetype:VkDeviceSize offsets + to apply to the bound descriptor buffers. + +If pname:stageFlags specifies a subset of all stages corresponding to one or +more pipeline bind points, the binding operation still affects all stages +corresponding to the given pipeline bind point(s) as if the equivalent +original version of this command had been called with the same parameters. +For example, specifying a pname:stageFlags value of +ename:VK_SHADER_STAGE_VERTEX_BIT | ename:VK_SHADER_STAGE_FRAGMENT_BIT | +ename:VK_SHADER_STAGE_COMPUTE_BIT is equivalent to calling the original +version of this command once with ename:VK_PIPELINE_BIND_POINT_GRAPHICS and +once with ename:VK_PIPELINE_BIND_POINT_COMPUTE. + +.Valid Usage +**** +include::{chapters}/commonvalidity/set_descriptor_buffer_offsets_common.adoc[] +include::{chapters}/commonvalidity/dynamic_pipeline_layout_common.adoc[] +**** + +include::{generated}/validity/structs/VkSetDescriptorBufferOffsetsInfoEXT.adoc[] +-- +endif::VK_KHR_maintenance6[] + [open,refpage='vkCmdBindDescriptorBufferEmbeddedSamplersEXT',desc='Setting embedded immutable samplers offsets in a command buffer',type='protos'] -- +:refpage: vkCmdBindDescriptorBufferEmbeddedSamplersEXT + To bind an embedded immutable sampler set to a command buffer, call: include::{generated}/api/protos/vkCmdBindDescriptorBufferEmbeddedSamplersEXT.adoc[] @@ -6348,26 +6622,89 @@ Compatibility>>. .Valid Usage **** +include::{chapters}/commonvalidity/bind_descriptor_buffer_embedded_samplers_common.adoc[] * [[VUID-vkCmdBindDescriptorBufferEmbeddedSamplersEXT-None-08068]] The <> feature must: be enabled * [[VUID-vkCmdBindDescriptorBufferEmbeddedSamplersEXT-pipelineBindPoint-08069]] pname:pipelineBindPoint must: be supported by the pname:commandBuffer's parent sname:VkCommandPool's queue family - * [[VUID-vkCmdBindDescriptorBufferEmbeddedSamplersEXT-set-08070]] - The slink:VkDescriptorSetLayout at index pname:set when pname:layout was - created must: have been created with the - ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_EMBEDDED_IMMUTABLE_SAMPLERS_BIT_EXT - bit set - * [[VUID-vkCmdBindDescriptorBufferEmbeddedSamplersEXT-set-08071]] - pname:set must: be less than or equal to - slink:VkPipelineLayoutCreateInfo::pname:setLayoutCount provided when - pname:layout was created **** include::{generated}/validity/protos/vkCmdBindDescriptorBufferEmbeddedSamplersEXT.adoc[] -- +ifdef::VK_KHR_maintenance6[] +[open,refpage='vkCmdBindDescriptorBufferEmbeddedSamplers2EXT',desc='Setting embedded immutable samplers offsets in a command buffer',type='protos'] +-- +Alternatively, to bind an embedded immutable sampler set to a command +buffer, call: + +include::{generated}/api/protos/vkCmdBindDescriptorBufferEmbeddedSamplers2EXT.adoc[] + + * pname:commandBuffer is the command buffer that the embedded immutable + samplers will be bound to. + * pname:pBindDescriptorBufferEmbeddedSamplersInfo is a pointer to a + sname:VkBindDescriptorBufferEmbeddedSamplersInfoEXT structure. + +.Valid Usage +**** + * [[VUID-vkCmdBindDescriptorBufferEmbeddedSamplers2EXT-descriptorBuffer-09472]] + The <> feature must: + be enabled + * [[VUID-vkCmdBindDescriptorBufferEmbeddedSamplers2EXT-pBindDescriptorBufferEmbeddedSamplersInfo-09473]] + Each bit in pname:pBindDescriptorBufferEmbeddedSamplersInfo->stageFlags + must: be a stage supported by the pname:commandBuffer's parent + sname:VkCommandPool's queue family +**** + +include::{generated}/validity/protos/vkCmdBindDescriptorBufferEmbeddedSamplers2EXT.adoc[] +-- + +[open,refpage='VkBindDescriptorBufferEmbeddedSamplersInfoEXT',desc='Structure specifying embedded immutable sampler offsets to set in a command buffer',type='structs'] +-- +:refpage: VkBindDescriptorBufferEmbeddedSamplersInfoEXT + +The sname::VkBindDescriptorBufferEmbeddedSamplersInfoEXT structure is +defined as: + +include::{generated}/api/structs/VkBindDescriptorBufferEmbeddedSamplersInfoEXT.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:stageFlags is a bitmask of elink:VkShaderStageFlagBits specifying + the shader stages that will use the embedded immutable samplers. + * pname:layout is a slink:VkPipelineLayout object used to program the + bindings. +ifdef::VK_NV_per_stage_descriptor_set[] + If the <> + feature is enabled, pname:layout can: be dlink:VK_NULL_HANDLE and the + layout must: be specified by chaining slink:VkPipelineLayoutCreateInfo + structure off the pname:pNext +endif::VK_NV_per_stage_descriptor_set[] + * pname:set is the number of the set to be bound. + +If pname:stageFlags specifies a subset of all stages corresponding to one or +more pipeline bind points, the binding operation still affects all stages +corresponding to the given pipeline bind point(s) as if the equivalent +original version of this command had been called with the same parameters. +For example, specifying a pname:stageFlags value of +ename:VK_SHADER_STAGE_VERTEX_BIT | ename:VK_SHADER_STAGE_FRAGMENT_BIT | +ename:VK_SHADER_STAGE_COMPUTE_BIT is equivalent to calling the original +version of this command once with ename:VK_PIPELINE_BIND_POINT_GRAPHICS and +once with ename:VK_PIPELINE_BIND_POINT_COMPUTE. + +.Valid Usage +**** +include::{chapters}/commonvalidity/bind_descriptor_buffer_embedded_samplers_common.adoc[] +include::{chapters}/commonvalidity/dynamic_pipeline_layout_common.adoc[] +**** + +include::{generated}/validity/structs/VkBindDescriptorBufferEmbeddedSamplersInfoEXT.adoc[] +-- +endif::VK_KHR_maintenance6[] + [[descriptorbuffers-updates]] === Updating Descriptor Buffers diff --git a/chapters/drawing.adoc b/chapters/drawing.adoc index d6d2ca728..0b1e70b3a 100644 --- a/chapters/drawing.adoc +++ b/chapters/drawing.adoc @@ -867,6 +867,16 @@ include::{generated}/api/protos/vkCmdBindIndexBuffer.adoc[] * pname:indexType is a elink:VkIndexType value specifying the size of the indices. +ifdef::VK_KHR_maintenance6[] +If the <> feature is enabled, +pname:buffer can: be dlink:VK_NULL_HANDLE. +ifdef::VK_EXT_robustness2[] +If pname::buffer is dlink:VK_NULL_HANDLE and the <> feature is enabled, every index fetched results in a +value of zero. +endif::VK_EXT_robustness2[] +endif::VK_KHR_maintenance6[] + .Valid Usage **** include::{chapters}/commonvalidity/bind_index_buffer_common.adoc[] @@ -898,6 +908,16 @@ pname:offset. If pname:size is ename:VK_WHOLE_SIZE then the bound size is from pname:offset to the end of the pname:buffer. +ifdef::VK_KHR_maintenance6[] +If the <> feature is enabled, +pname:buffer can: be dlink:VK_NULL_HANDLE. +ifdef::VK_EXT_robustness2[] +If pname::buffer is dlink:VK_NULL_HANDLE and the <> feature is enabled, every index fetched results in a +value of zero. +endif::VK_EXT_robustness2[] +endif::VK_KHR_maintenance6[] + .Valid Usage **** include::{chapters}/commonvalidity/bind_index_buffer_common.adoc[] @@ -1594,6 +1614,10 @@ include::{chapters}/commonvalidity/draw_instance_common.adoc[] ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set * [[VUID-vkCmdDrawIndirectByteCountEXT-counterBufferOffset-04568]] pname:counterBufferOffset must: be a multiple of `4` + * [[VUID-vkCmdDrawIndirectByteCountEXT-counterOffset-09474]] + pname:counterOffset must: be a multiple of `4` + * [[VUID-vkCmdDrawIndirectByteCountEXT-vertexStride-09475]] + pname:vertexStride must: be a multiple of `4` ifdef::VK_VERSION_1_1[] * [[VUID-vkCmdDrawIndirectByteCountEXT-commandBuffer-02646]] pname:commandBuffer must: not be a protected command buffer diff --git a/chapters/features.adoc b/chapters/features.adoc index 03df0222d..cd63d9852 100644 --- a/chapters/features.adoc +++ b/chapters/features.adoc @@ -4149,6 +4149,35 @@ include::{generated}/validity/structs/VkPhysicalDeviceRayTracingMaintenance1Feat -- endif::VK_KHR_ray_tracing_maintenance1[] +ifdef::VK_KHR_video_maintenance1[] +[open,refpage='VkPhysicalDeviceVideoMaintenance1FeaturesKHR',desc='Structure describing the video maintenance features that can be supported by an implementation',type='structs'] +-- +The sname:VkPhysicalDeviceVideoMaintenance1FeaturesKHR structure is defined +as: + +include::{generated}/api/structs/VkPhysicalDeviceVideoMaintenance1FeaturesKHR.adoc[] + +This structure describes the following features: + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[features-videoMaintenance1]] pname:videoMaintenance1 indicates that + the implementation supports the following: + ** The new buffer creation flag + ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. + ** The new image creation flag + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. + ** The new video session creation flag + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR. + +:refpage: VkPhysicalDeviceVideoMaintenance1FeaturesKHR +include::{chapters}/features.adoc[tag=features] + +include::{generated}/validity/structs/VkPhysicalDeviceVideoMaintenance1FeaturesKHR.adoc[] +-- +endif::VK_KHR_video_maintenance1[] + ifdef::VK_EXT_extended_dynamic_state[] [open,refpage='VkPhysicalDeviceExtendedDynamicStateFeaturesEXT',desc='Structure describing what extended dynamic state can be used',type='structs'] -- @@ -5969,6 +5998,46 @@ include::{generated}/validity/structs/VkPhysicalDeviceMaintenance5FeaturesKHR.ad -- endif::VK_KHR_maintenance5[] +ifdef::VK_KHR_maintenance6[] +[open,refpage='VkPhysicalDeviceMaintenance6FeaturesKHR',desc='Structure describing whether the implementation supports maintenance6 functionality',type='structs',alias='VkPhysicalDeviceMaintenance6FeaturesKHR'] +-- +The sname:VkPhysicalDeviceMaintenance6FeaturesKHR structure is defined as: + +include::{generated}/api/structs/VkPhysicalDeviceMaintenance6FeaturesKHR.adoc[] + +This structure describes the following feature: + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[features-maintenance6]] pname:maintenance6 indicates that the + implementation supports the following: + ** dlink:VK_NULL_HANDLE can: be used when binding an index buffer + ** slink:VkBindMemoryStatusKHR can: be included in the pname:pNext chain + of the slink:VkBindBufferMemoryInfo and slink:VkBindImageMemoryInfo + structures, enabling applications to retrieve elink:VkResult values for + individual memory binding operations. + ** slink:VkPhysicalDeviceMaintenance6PropertiesKHR::pname:blockTexelViewCompatibleMultipleLayers + property to indicate that the implementation supports creating image + views with ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT where + the pname:layerCount member of pname:subresourceRange is greater than + `1`. + ** slink:VkPhysicalDeviceMaintenance6PropertiesKHR::pname:maxCombinedImageSamplerDescriptorCount + property which indicates the maximum descriptor size required for any + <> supported by the implementation. + ** A + slink:VkPhysicalDeviceMaintenance6PropertiesKHR::pname:fragmentShadingRateClampCombinerInputs + property which indicates whether the implementation clamps the inputs + to fragment shading rate combiner operations. + +:refpage: VkPhysicalDeviceMaintenance6FeaturesKHR +include::{chapters}/features.adoc[tag=features] + +include::{generated}/validity/structs/VkPhysicalDeviceMaintenance6FeaturesKHR.adoc[] +-- +endif::VK_KHR_maintenance6[] + ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] [open,refpage='VkPhysicalDeviceDynamicRenderingFeatures',desc='Structure indicating support for dynamic render pass instances',type='structs',alias='VkPhysicalDeviceDynamicRenderingFeaturesKHR'] -- @@ -7043,7 +7112,7 @@ include::{generated}/api/structs/VkPhysicalDeviceClusterCullingShaderVrsFeatures structure. * [[features-clusterShadingRate]] pname:clusterShadingRate specifies whether per-cluster shading rates is supported. - + include::{generated}/validity/structs/VkPhysicalDeviceClusterCullingShaderVrsFeaturesHUAWEI.adoc[] -- @@ -7158,6 +7227,42 @@ include::{generated}/validity/structs/VkPhysicalDeviceDescriptorPoolOverallocati -- endif::VK_NV_descriptor_pool_overallocation[] +ifdef::VK_NV_per_stage_descriptor_set[] +[open,refpage='VkPhysicalDevicePerStageDescriptorSetFeaturesNV',desc='Structure describing feature to allow descriptor set layout bindings to be per-stage',type='structs'] +-- +The sname:VkPhysicalDevicePerStageDescriptorSetFeaturesNV structure is +defined as: + +include::{generated}/api/structs/VkPhysicalDevicePerStageDescriptorSetFeaturesNV.adoc[] + +This structure describes the following feature: + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * [[features-perStageDescriptorSet]] pname:perStageDescriptorSet indicates + that the implementation allows the + ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PER_STAGE_BIT_NV descriptor set + layout creation flag to be used so the bindings are specified per-stage + rather than across all stages. + * [[features-dynamicPipelineLayout]] pname:dynamicPipelineLayout indicates + the implementation allows the pname:layout member of + slink:VkBindDescriptorSetsInfoKHR, slink:VkPushConstantsInfoKHR, + slink:VkPushDescriptorSetInfoKHR, + slink:VkPushDescriptorSetWithTemplateInfoKHR, + slink:VkSetDescriptorBufferOffsetsInfoEXT and + slink:VkBindDescriptorBufferEmbeddedSamplersInfoEXT to be + dlink:VK_NULL_HANDLE and slink:VkPipelineLayoutCreateInfo can: be + chained off those structures' pname:pNext instead. + +:refpage: VkPhysicalDevicePerStageDescriptorSetFeaturesNV +include::{chapters}/features.adoc[tag=features] + +include::{generated}/validity/structs/VkPhysicalDevicePerStageDescriptorSetFeaturesNV.adoc[] + +-- +endif::VK_NV_per_stage_descriptor_set[] + ifdef::VK_NV_cuda_kernel_launch[] [open,refpage='VkPhysicalDeviceCudaKernelLaunchFeaturesNV',desc='Structure describing whether cuda kernel launch is supported by the implementation',type='structs'] -- @@ -7756,6 +7861,10 @@ ifdef::VK_KHR_maintenance5[] * <>, if the `apiext:VK_KHR_maintenance5` extension is supported. endif::VK_KHR_maintenance5[] +ifdef::VK_KHR_maintenance6[] + * <>, if the + `apiext:VK_KHR_maintenance6` extension is supported. +endif::VK_KHR_maintenance6[] ifdef::VK_EXT_image_2d_view_of_3d[] * <>, if the `apiext:VK_EXT_image_2d_view_of_3d` extension is supported. @@ -7844,6 +7953,10 @@ ifdef::VK_KHR_ray_tracing_maintenance1[] * <>, if the `apiext:VK_KHR_ray_tracing_maintenance1` extension is supported. endif::VK_KHR_ray_tracing_maintenance1[] +ifdef::VK_KHR_video_maintenance1[] + * <>, if the + `apiext:VK_KHR_video_maintenance1` extension is supported. +endif::VK_KHR_video_maintenance1[] ifdef::VK_EXT_color_write_enable[] * <>, if the `apiext:VK_EXT_color_write_enable` extension is supported. @@ -8119,6 +8232,10 @@ ifdef::VK_ARM_render_pass_striped[] * <>, if the `apiext:VK_ARM_render_pass_striped` extension is supported. endif::VK_ARM_render_pass_striped[] +ifdef::VK_NV_per_stage_descriptor_set[] + * <>, if the + `apiext:VK_NV_per_stage_descriptor_set` extension is supported. +endif::VK_NV_per_stage_descriptor_set[] All other features defined in the Specification are optional:. diff --git a/chapters/fragops.adoc b/chapters/fragops.adoc index 5d53c53b6..ca176ff6e 100644 --- a/chapters/fragops.adoc +++ b/chapters/fragops.adoc @@ -765,6 +765,12 @@ For fragment shaders invoked by fragments, the following rules apply: storage resources). ** Any other <> discards the fragment, and the shader does not write to any storage resources. + ** If a fragment shader statically computes the same values for different + framebuffer locations, and does not write to any storage resources, + multiple fragments may: be shaded by one fragment shader invocation. + This may: affect + ename:VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT + results, but must: otherwise not be visible behavior to applications. * Otherwise, at least one fragment shader must: be executed. ** If <> is enabled and multiple invocations per fragment are required:, additional invocations must: be diff --git a/chapters/interfaces.adoc b/chapters/interfaces.adoc index 3c45b51af..7ebf0df25 100644 --- a/chapters/interfaces.adoc +++ b/chapters/interfaces.adoc @@ -3655,8 +3655,8 @@ Decorating a variable with the code:PrimitiveIndicesNV decoration will make that variable contain the output array of vertex index values. Depending on the output primitive type declared using the execution mode, the indices are split into groups of one (code:OutputPoints), two -(code:OutputLinesNV), or three (code:OutputTriangles) indices and each group -generates a primitive. +(code:OutputLinesNV), or three (code:OutputTrianglesNV) indices and each +group generates a primitive. .Valid Usage **** @@ -5335,8 +5335,9 @@ code:ShaderIndexAMDX:: Decorating a variable with the code:ShaderIndexAMDX built-in decoration will make that variable contain the index of the shader specified when it was -compiled, either via slink:VkPipelineShaderStageNodeCreateInfoAMDX::index or -by the code:ShaderIndexAMDX execution mode. +compiled, either via +slink:VkPipelineShaderStageNodeCreateInfoAMDX::pname:index or by the +code:ShaderIndexAMDX execution mode. .Valid Usage **** diff --git a/chapters/introduction.adoc b/chapters/introduction.adoc index 0dbc611b8..051b5c431 100644 --- a/chapters/introduction.adoc +++ b/chapters/introduction.adoc @@ -69,6 +69,33 @@ corresponding XML Registry. ==== +[[introduction-ratified]] +=== Ratification + +_Ratification_ of a Vulkan core version or extension is a status conferred +by vote of the Khronos Board of Promoters, bringing that core version or +extension under the umbrella of the Khronos IP Policy. + +All Vulkan core versions and `KHR` extensions (including provisional +specifications) are ratified, as are some multi-vendor `EXT` extensions. +Ratification status of extensions is described in the <> appendix. + +[NOTE] +.Note +==== +Ratification status is primarily of interest to IHVs developing GPU hardware +and Vulkan implementations + +For developers, ratification does not necessarily mean that an extension is +"`better`"; has a more stable API; or is more widely supported than +alternative ways of achieving that functionality. + +Interactions between ratified and non-ratified extensions are not themselves +ratified. +==== + + [[introduction-informative-language]] === Informative Language diff --git a/chapters/limits.adoc b/chapters/limits.adoc index 06d50928d..d539a8795 100644 --- a/chapters/limits.adoc +++ b/chapters/limits.adoc @@ -1739,6 +1739,36 @@ include::{generated}/validity/structs/VkPhysicalDeviceMaintenance5PropertiesKHR. -- endif::VK_KHR_maintenance5[] +ifdef::VK_KHR_maintenance6[] +[open,refpage='VkPhysicalDeviceMaintenance6PropertiesKHR',desc='Structure describing various implementation-defined properties introduced with VK_KHR_maintenance6',type='structs',alias='VkPhysicalDeviceMaintenance6PropertiesKHR'] +-- +The sname:VkPhysicalDeviceMaintenance6PropertiesKHR structure is defined as: + +include::{generated}/api/structs/VkPhysicalDeviceMaintenance6PropertiesKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:blockTexelViewCompatibleMultipleLayers is a boolean value + indicating that an implementation supports creating image views with + ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT where the + pname:layerCount member of pname:subresourceRange is greater than `1`. + * pname:maxCombinedImageSamplerDescriptorCount is the maximum number of + combined image sampler descriptors that the implementation uses to + access any of the <> supported by the + implementation. + * pname:fragmentShadingRateClampCombinerInputs is a boolean value + indicating that an implementation clamps the inputs to + <>. + +:refpage: VkPhysicalDeviceMaintenance6PropertiesKHR +include::{chapters}/limits.adoc[tag=limits_desc] + +include::{generated}/validity/structs/VkPhysicalDeviceMaintenance6PropertiesKHR.adoc[] +-- +endif::VK_KHR_maintenance6[] + ifdef::VK_NV_mesh_shader[] [open,refpage='VkPhysicalDeviceMeshShaderPropertiesNV',desc='Structure describing mesh shading properties',type='structs'] -- diff --git a/chapters/pipelines.adoc b/chapters/pipelines.adoc index 1f9ed6aaf..76fc1bb0c 100644 --- a/chapters/pipelines.adoc +++ b/chapters/pipelines.adoc @@ -2113,7 +2113,7 @@ endif::VK_EXT_extended_dynamic_state3[] pname:pMultisampleState must: be a valid pointer to a valid slink:VkPipelineMultisampleStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-pMultisampleState-09027]] - If pname:pMultisampleState is not `NULL` is must: be a valid pointer to + If pname:pMultisampleState is not `NULL` it must: be a valid pointer to a valid slink:VkPipelineMultisampleStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-alphaToCoverageEnable-08891]] If the pipeline is being created with @@ -2127,10 +2127,10 @@ endif::VK_EXT_extended_dynamic_state3[] * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-09028]] If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being created with <>, and pname:subpass uses a depth/stencil attachment, and + shader state>>, and pname:subpass uses a depth/stencil attachment, ifdef::VK_EXT_extended_dynamic_state3[] - the `apiext:VK_EXT_extended_dynamic_state3` extension is not enabled or, - any of the ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE, + and the `apiext:VK_EXT_extended_dynamic_state3` extension is not enabled + or, any of the ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE, ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE, ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP, ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE, @@ -3430,12 +3430,14 @@ endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] pre-rasterization shader state>> or <>, pname:stageCount must: be greater than `0` +ifdef::VK_KHR_pipeline_library[] * [[VUID-VkGraphicsPipelineCreateInfo-graphicsPipelineLibrary-06606]] ifdef::VK_EXT_graphics_pipeline_library[] If the <> feature is not enabled, endif::VK_EXT_graphics_pipeline_library[] pname:flags must: not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR +endif::VK_KHR_pipeline_library[] ifdef::VK_EXT_graphics_pipeline_library[] * [[VUID-VkGraphicsPipelineCreateInfo-flags-06608]] If the pipeline defines, or includes as libraries, all the state subsets @@ -3703,7 +3705,6 @@ ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] libraries, the value of slink:VkPipelineRenderingCreateInfo::pname:viewMask set by each library must: be identical -endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] * [[VUID-VkGraphicsPipelineCreateInfo-pLibraries-06628]] If one element of slink:VkPipelineLibraryCreateInfoKHR::pname:pLibraries includes at least one of and no more than two of @@ -3714,25 +3715,34 @@ endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] slink:VkPipelineLibraryCreateInfoKHR::pname:pLibraries includes one of the other flags, the pname:renderPass objects used to create each library must: be compatible or all equal to dlink:VK_NULL_HANDLE - * [[VUID-VkGraphicsPipelineCreateInfo-pMultisampleState-06629]] - If the pipeline requires <> pname:pMultisampleState must: be `NULL` or a - valid pointer to a valid slink:VkPipelineMultisampleStateCreateInfo - structure * [[VUID-VkGraphicsPipelineCreateInfo-renderpass-06631]] - If the pipeline requires <> -ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] - and pname:renderpass is not dlink:VK_NULL_HANDLE, then -endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] - pname:pMultisampleState must: not be `NULL` -ifdef::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] + If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline requires + <>, +ifdef::VK_EXT_extended_dynamic_state3[] + and the `apiext:VK_EXT_extended_dynamic_state3` extension is not enabled + or any of the ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT, + ename:VK_DYNAMIC_STATE_SAMPLE_MASK_EXT, or + ename:VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT dynamic states is + not set, or <> is enabled on the device + and ename:VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT is not set, +endif::VK_EXT_extended_dynamic_state3[] + then pname:pMultisampleState must: be a valid pointer to a valid + slink:VkPipelineMultisampleStateCreateInfo structure * [[VUID-VkGraphicsPipelineCreateInfo-Input-06632]] If the pipeline requires <> with a fragment shader that either enables <> or decorates any variable in - the code:Input storage class with code:Sample, then - pname:pMultisampleState must: not be `NULL` + the code:Input storage class with code:Sample, +ifdef::VK_EXT_extended_dynamic_state3[] + and the `apiext:VK_EXT_extended_dynamic_state3` extension is not enabled + or any of the ename:VK_DYNAMIC_STATE_RASTERIZATION_SAMPLES_EXT, + ename:VK_DYNAMIC_STATE_SAMPLE_MASK_EXT, or + ename:VK_DYNAMIC_STATE_ALPHA_TO_COVERAGE_ENABLE_EXT dynamic states is + not set, or <> is enabled on the device + and ename:VK_DYNAMIC_STATE_ALPHA_TO_ONE_ENABLE_EXT is not set, +endif::VK_EXT_extended_dynamic_state3[] + then pname:pMultisampleState must: be a valid pointer to a valid + slink:VkPipelineMultisampleStateCreateInfo structure endif::VK_VERSION_1_3,VK_KHR_dynamic_rendering[] * [[VUID-VkGraphicsPipelineCreateInfo-flags-06633]] If slink:VkGraphicsPipelineLibraryCreateInfoEXT::pname:flags includes @@ -5148,7 +5158,7 @@ endif::VK_EXT_depth_bias_control[] the pname:depthBiasConstantFactor, pname:depthBiasClamp and pname:depthBiasSlopeFactor states in slink:VkPipelineRasterizationStateCreateInfo will be ignored and must: - be set dynamically with either flink:vkCmdSetDepthBias + be set dynamically with flink:vkCmdSetDepthBias ifdef::VK_EXT_depth_bias_control[or flink:vkCmdSetDepthBias2EXT] before any draws are performed with <>. diff --git a/chapters/primsrast.adoc b/chapters/primsrast.adoc index f51283c9f..3995e1bcf 100644 --- a/chapters/primsrast.adoc +++ b/chapters/primsrast.adoc @@ -1436,8 +1436,14 @@ rate, reported via the <>. Implementations should: clamp the inputs to the combiner operations -[eq]#A~xy~# and [eq]#B~xy~#, and must: clamp the result of the second -combiner operation. +[eq]#A~xy~# and [eq]#B~xy~#, and must: +ifdef::VK_KHR_maintenance6[] +do so if +sname:VkPhysicalDeviceMaintenance6PropertiesKHR::pname:fragmentShadingRateClampCombinerInputs +is set to ename:VK_TRUE. +All implementations must: +endif::VK_KHR_maintenance6[] +clamp the result of the second combiner operation. A fragment shading rate [eq]#R~xy~# representing any of [eq]#A~xy~#, [eq]#B~xy~# or [eq]#C~xy~# is clamped as follows. diff --git a/chapters/queries.adoc b/chapters/queries.adoc index 8230f09bb..c95e97384 100644 --- a/chapters/queries.adoc +++ b/chapters/queries.adoc @@ -1108,6 +1108,11 @@ unsuccessfully. elink:VkQueryResultStatusKHR defines specific meaning for values returned here, though implementations are free to return other values. + +If the status value written is negative, indicating that the operations +within the query completed unsuccessfully, then all other results written by +this command are undefined: unless otherwise specified for any of the +results of the used query type. endif::VK_KHR_video_queue[] [NOTE] @@ -1301,11 +1306,11 @@ Specific status codes that can: be returned from a query are: include::{generated}/api/enums/VkQueryResultStatusKHR.adoc[] - * ename:VK_QUERY_RESULT_STATUS_NOT_READY_KHR specifies that the query + * ename:VK_QUERY_RESULT_STATUS_NOT_READY_KHR indicates that the query result is not yet available. - * ename:VK_QUERY_RESULT_STATUS_ERROR_KHR specifies that operations did not + * ename:VK_QUERY_RESULT_STATUS_ERROR_KHR indicates that operations did not complete successfully. - * ename:VK_QUERY_RESULT_STATUS_COMPLETE_KHR specifies that operations + * ename:VK_QUERY_RESULT_STATUS_COMPLETE_KHR indicates that operations completed successfully and the query result is available. ifdef::VK_KHR_video_encode_queue[] * ename:VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR @@ -1370,6 +1375,11 @@ unsuccessfully. elink:VkQueryResultStatusKHR defines specific meaning for values returned here, though implementations are free to return other values. + +If the status value written is negative, indicating that the operations +within the query completed unsuccessfully, then all other results written by +this command are undefined: unless otherwise specified for any of the +results of the used query type. endif::VK_KHR_video_queue[] Results for any available query written by this command are final and @@ -2182,6 +2192,12 @@ include::{generated}/api/enums/VkVideoEncodeFeedbackFlagBitsKHR.adoc[] buffer specified in slink:VkVideoEncodeInfoKHR::pname:dstBuffer relative to the offset specified in slink:VkVideoEncodeInfoKHR::pname:dstBufferOffset. + For the first video encode operation issued by any + <>, this value will always + be zero, meaning that bitstream data is always written to the buffer + specified in slink:VkVideoEncodeInfoKHR::pname:dstBuffer starting from + the offset specified in + slink:VkVideoEncodeInfoKHR::pname:dstBufferOffset. * ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR specifies that queries managed by the pool will capture the number of bytes written by the video encode operation to the bitstream buffer specified @@ -2189,14 +2205,27 @@ include::{generated}/api/enums/VkVideoEncodeFeedbackFlagBitsKHR.adoc[] * ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR specifies that queries managed by the pool will capture a boolean value indicating that the data written to the bitstream buffer specified in - slink:VkVideoEncodeInfoKHR::pname:dstBuffer contains overridden - parameters. + slink:VkVideoEncodeInfoKHR::pname:dstBuffer contains + <>. When retrieving the results of video encode feedback queries, the values corresponding to each enabled video encode feedback are written in the order of the bits defined above, followed by an optional value indicating availability or result status if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT or ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR is specified, respectively. + +If the result status of a video encode feedback query is negative, then the +results of all enabled video encode feedback values will be undefined:. + +[NOTE] +.Note +==== +Thus it is recommended that applications always specify +ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR when retrieving the results of +video encode feedback queries and ignore such undefined: video encode +feedback values for any <> completed +video encode operations. +==== -- [open,refpage='VkVideoEncodeFeedbackFlagsKHR',desc='Bitmask of VkVideoEncodeFeedbackFlagBitsKHR',type='flags'] diff --git a/chapters/renderpass.adoc b/chapters/renderpass.adoc index 303b15f71..6d981dadd 100644 --- a/chapters/renderpass.adoc +++ b/chapters/renderpass.adoc @@ -271,6 +271,17 @@ endif::VK_VERSION_1_1,VK_KHR_device_group[] of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, that pname:imageView must: have been created with ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT + * [[VUID-VkRenderingInfo-colorAttachmentCount-09476]] + If pname:colorAttachmentCount is not `0` and there is an element of + pname:pColorAttachments with +ifdef::VK_ANDROID_external_format_resolve[] + either its pname:resolveMode member set to + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, or +endif::VK_ANDROID_external_format_resolve[] + its pname:imageView member not dlink:VK_NULL_HANDLE, and its + pname:resolveMode member not set to ename:VK_RESOLVE_MODE_NONE, the + pname:resolveImageView member of that element of pname:pColorAttachments + must: have been created with ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT * [[VUID-VkRenderingInfo-pDepthAttachment-06547]] If pname:pDepthAttachment is not `NULL` and pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, @@ -281,6 +292,11 @@ endif::VK_VERSION_1_1,VK_KHR_device_group[] pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, pname:pDepthAttachment->imageView must: have been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT + * [[VUID-VkRenderingInfo-pDepthAttachment-09477]] + If pname:pDepthAttachment is not `NULL` and + pname:pDepthAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, + pname:pDepthAttachment->resolveImageView must: have been created with + ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-VkRenderingInfo-pStencilAttachment-06548]] If pname:pStencilAttachment is not `NULL` and pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, @@ -292,6 +308,11 @@ endif::VK_VERSION_1_1,VK_KHR_device_group[] pname:pStencilAttachment->imageView must: have been created with a stencil usage including ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT + * [[VUID-VkRenderingInfo-pStencilAttachment-09478]] + If pname:pStencilAttachment is not `NULL` and + pname:pStencilAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, + pname:pStencilAttachment->resolveImageView must: have been created with + ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT * [[VUID-VkRenderingInfo-colorAttachmentCount-06090]] If pname:colorAttachmentCount is not `0` and the pname:imageView member of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, @@ -647,6 +668,57 @@ ifdef::VK_ARM_render_pass_striped[] slink:VkRenderPassStripeInfoARM::pname:pStripeInfos must: cover the pname:renderArea endif::VK_ARM_render_pass_striped[] + * [[VUID-VkRenderingInfo-colorAttachmentCount-09479]] + If pname:colorAttachmentCount is not `0` and the pname:imageView member + of an element of pname:pColorAttachments is not dlink:VK_NULL_HANDLE, + that pname:imageView must: have been created with the identity swizzle + * [[VUID-VkRenderingInfo-colorAttachmentCount-09480]] + If pname:colorAttachmentCount is not `0`, and there is an element of + pname:pColorAttachments with +ifdef::VK_ANDROID_external_format_resolve[] + either its pname:resolveMode member set to + ename:VK_RESOLVE_MODE_EXTERNAL_FORMAT_DOWNSAMPLE_ANDROID, or +endif::VK_ANDROID_external_format_resolve[] + its pname:imageView member not set to dlink:VK_NULL_HANDLE and its + pname:resolveMode member not set to ename:VK_RESOLVE_MODE_NONE, the + pname:resolveImageView member of that element of pname:pColorAttachments + must: have been created with the identity swizzle + * [[VUID-VkRenderingInfo-pDepthAttachment-09481]] + If pname:pDepthAttachment is not `NULL` and + pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, + pname:pDepthAttachment->imageView must: have been created with the + identity swizzle + * [[VUID-VkRenderingInfo-pDepthAttachment-09482]] + If pname:pDepthAttachment is not `NULL`, + pname:pDepthAttachment->imageView is not dlink:VK_NULL_HANDLE, and + pname:pDepthAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, + pname:pDepthAttachment->resolveImageView must: have been created with + the identity swizzle + * [[VUID-VkRenderingInfo-pStencilAttachment-09483]] + If pname:pStencilAttachment is not `NULL` and + pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, + pname:pStencilAttachment->imageView must: have been created with the + identity swizzle + * [[VUID-VkRenderingInfo-pStencilAttachment-09484]] + If pname:pStencilAttachment is not `NULL`, + pname:pStencilAttachment->imageView is not dlink:VK_NULL_HANDLE, and + pname:pStencilAttachment->resolveMode is not ename:VK_RESOLVE_MODE_NONE, + pname:pStencilAttachment->resolveImageView must: have been created with + the identity swizzle +ifdef::VK_KHR_fragment_shading_rate[] + * [[VUID-VkRenderingInfo-imageView-09485]] + If the pname:imageView member of a + slink:VkRenderingFragmentShadingRateAttachmentInfoKHR structure included + in the pname:pNext chain is not dlink:VK_NULL_HANDLE, it must: have been + created with the identity swizzle +endif::VK_KHR_fragment_shading_rate[] +ifdef::VK_EXT_fragment_density_map[] + * [[VUID-VkRenderingInfo-imageView-09486]] + If the pname:imageView member of a + slink:VkRenderingFragmentDensityMapAttachmentInfoEXT structure included + in the pname:pNext chain is not dlink:VK_NULL_HANDLE, it must: have been + created with the identity swizzle +endif::VK_EXT_fragment_density_map[] **** include::{generated}/validity/structs/VkRenderingInfo.adoc[] diff --git a/chapters/resources.adoc b/chapters/resources.adoc index 225e2447e..c645745a7 100644 --- a/chapters/resources.adoc +++ b/chapters/resources.adoc @@ -250,21 +250,37 @@ endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[ ifdef::VK_KHR_video_decode_queue[] * [[VUID-VkBufferCreateInfo-usage-04813]] If pname:usage includes ename:VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR - or ename:VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR, then the pname:pNext - chain must: include a slink:VkVideoProfileListInfoKHR structure with - pname:profileCount greater than `0` and pname:pProfiles including at - least one slink:VkVideoProfileInfoKHR structure with a - pname:videoCodecOperation member specifying a decode operation + or ename:VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR, +ifdef::VK_KHR_video_maintenance1[] + and pname:flags does not include + ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, +endif::VK_KHR_video_maintenance1[] + then the pname:pNext chain must: include a + slink:VkVideoProfileListInfoKHR structure with pname:profileCount + greater than `0` and pname:pProfiles including at least one + slink:VkVideoProfileInfoKHR structure with a pname:videoCodecOperation + member specifying a decode operation endif::VK_KHR_video_decode_queue[] ifdef::VK_KHR_video_encode_queue[] * [[VUID-VkBufferCreateInfo-usage-04814]] If pname:usage includes ename:VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR - or ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR, then the pname:pNext - chain must: include a slink:VkVideoProfileListInfoKHR structure with - pname:profileCount greater than `0` and pname:pProfiles including at - least one slink:VkVideoProfileInfoKHR structure with a - pname:videoCodecOperation member specifying an encode operation + or ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR, +ifdef::VK_KHR_video_maintenance1[] + and pname:flags does not include + ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, +endif::VK_KHR_video_maintenance1[] + then the pname:pNext chain must: include a + slink:VkVideoProfileListInfoKHR structure with pname:profileCount + greater than `0` and pname:pProfiles including at least one + slink:VkVideoProfileInfoKHR structure with a pname:videoCodecOperation + member specifying an encode operation endif::VK_KHR_video_encode_queue[] +ifdef::VK_KHR_video_maintenance1[] + * [[VUID-VkBufferCreateInfo-flags-08325]] + If pname:flags includes + ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then + <> must: be enabled +endif::VK_KHR_video_maintenance1[] ifdef::VK_VERSION_1_3,VK_KHR_maintenance4[] * [[VUID-VkBufferCreateInfo-size-06409]] pname:size must: be less than or equal to @@ -700,6 +716,12 @@ ifdef::VK_EXT_descriptor_buffer[] capturing and replaying (e.g. for trace capture and replay), see slink:VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail. endif::VK_EXT_descriptor_buffer[] +ifdef::VK_KHR_video_maintenance1[] + * ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR specifies that + the buffer can: be used in <> + without having to specify at buffer creation time the set of video + profiles the buffer will be used with. +endif::VK_KHR_video_maintenance1[] See <> and <> for details of the sparse memory @@ -2275,22 +2297,53 @@ ifdef::VK_KHR_video_decode_queue[] * [[VUID-VkImageCreateInfo-usage-04815]] If pname:usage includes ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, or - ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the pname:pNext - chain must: include a slink:VkVideoProfileListInfoKHR structure with - pname:profileCount greater than `0` and pname:pProfiles including at - least one slink:VkVideoProfileInfoKHR structure with a - pname:videoCodecOperation member specifying a decode operation + ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, +ifdef::VK_KHR_video_maintenance1[] + and pname:flags does not include + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, +endif::VK_KHR_video_maintenance1[] + then the pname:pNext chain must: include a + slink:VkVideoProfileListInfoKHR structure with pname:profileCount + greater than `0` and pname:pProfiles including at least one + slink:VkVideoProfileInfoKHR structure with a pname:videoCodecOperation + member specifying a decode operation endif::VK_KHR_video_decode_queue[] ifdef::VK_KHR_video_encode_queue[] * [[VUID-VkImageCreateInfo-usage-04816]] If pname:usage includes ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, or - ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the pname:pNext - chain must: include a slink:VkVideoProfileListInfoKHR structure with - pname:profileCount greater than `0` and pname:pProfiles including at - least one slink:VkVideoProfileInfoKHR structure with a - pname:videoCodecOperation member specifying an encode operation + ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, +ifdef::VK_KHR_video_maintenance1[] + and pname:flags does not include + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, +endif::VK_KHR_video_maintenance1[] + then the pname:pNext chain must: include a + slink:VkVideoProfileListInfoKHR structure with pname:profileCount + greater than `0` and pname:pProfiles including at least one + slink:VkVideoProfileInfoKHR structure with a pname:videoCodecOperation + member specifying an encode operation +endif::VK_KHR_video_encode_queue[] +ifdef::VK_KHR_video_maintenance1[] + * [[VUID-VkImageCreateInfo-flags-08328]] + If pname:flags includes + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then + <> must: be enabled +ifdef::VK_KHR_video_decode_queue[] + * [[VUID-VkImageCreateInfo-flags-08329]] + If pname:flags includes + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and pname:usage + does not include ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, then + pname:usage must: not include + ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR +endif::VK_KHR_video_decode_queue[] +ifdef::VK_KHR_video_encode_queue[] + * [[VUID-VkImageCreateInfo-flags-08331]] + If pname:flags includes + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then + pname:usage must: not include + ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR endif::VK_KHR_video_encode_queue[] +endif::VK_KHR_video_maintenance1[] ifdef::VK_KHR_video_queue[] * [[VUID-VkImageCreateInfo-pNext-06811]] If the pname:pNext chain includes a slink:VkVideoProfileListInfoKHR @@ -3367,6 +3420,51 @@ ifdef::VK_EXT_multisampled_render_to_single_sampled[] <> endif::VK_EXT_multisampled_render_to_single_sampled[] +ifdef::VK_KHR_video_maintenance1[] + * ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR specifies that + the image can: be used in <> + without having to specify at image creation time the set of video + profiles the image will be used with, except for images used only as + <> pictures, as long as the image is otherwise + <> with the video profile in + question. ++ +[NOTE] +.Note +==== +This enables exchanging video picture data without additional copies or +conversions when used as: + +ifdef::VK_KHR_video_decode_queue[] + * <>, indifferent of the + video profile used to produce them. +endif::VK_KHR_video_decode_queue[] +ifdef::VK_KHR_video_encode_queue[] + * <>, indifferent of the video + profile used to consume them. +endif::VK_KHR_video_encode_queue[] + +ifdef::VK_KHR_video_decode_queue[] +This includes images created with both +ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR and +ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, which is necessary to use the +same video picture as the <> +and <> in a video decode +operation on implementations supporting +ename:VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR. +endif::VK_KHR_video_decode_queue[] + +However, images with only DPB usage remain tied to the video profiles the +image was created with, as the data layout of such DPB-only images may: be +implementation- and codec-dependent. + +If an application would like to share or reuse the device memory backing +such images (e.g. for the purposes of temporal aliasing), then it should: +create separate image objects for each video profile and bind them to the +same underlying device memory range, similar to how memory resources can: be +shared across separate video sessions or any other memory-backed resource. +==== +endif::VK_KHR_video_maintenance1[] See <> and <> for more @@ -4788,6 +4886,46 @@ endif::VK_NV_linear_color_attachment[] ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then the image view's <> must: contain ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT +ifdef::VK_KHR_video_maintenance1[] +ifdef::VK_KHR_video_decode_queue[] + * [[VUID-VkImageViewCreateInfo-image-08333]] + If pname:image was created with + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and pname:usage + contains ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, then the image + view's <> must: + contain ename:VK_FORMAT_FEATURE_VIDEO_DECODE_OUTPUT_BIT_KHR + * [[VUID-VkImageViewCreateInfo-image-08334]] + If pname:image was created with + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and pname:usage + contains ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the image + view's <> must: + contain ename:VK_FORMAT_FEATURE_VIDEO_DECODE_DPB_BIT_KHR + * [[VUID-VkImageViewCreateInfo-image-08335]] + If pname:image was created with + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then + pname:usage must: not include + ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR +endif::VK_KHR_video_decode_queue[] +ifdef::VK_KHR_video_encode_queue[] + * [[VUID-VkImageViewCreateInfo-image-08336]] + If pname:image was created with + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and pname:usage + contains ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, then the image + view's <> must: + contain ename:VK_FORMAT_FEATURE_VIDEO_ENCODE_INPUT_BIT_KHR + * [[VUID-VkImageViewCreateInfo-image-08337]] + If pname:image was created with + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR and pname:usage + contains ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the image + view's <> must: + contain ename:VK_FORMAT_FEATURE_VIDEO_ENCODE_DPB_BIT_KHR + * [[VUID-VkImageViewCreateInfo-image-08338]] + If pname:image was created with + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, then + pname:usage must: not include + ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR +endif::VK_KHR_video_encode_queue[] +endif::VK_KHR_video_maintenance1[] * [[VUID-VkImageViewCreateInfo-usage-08932]] If pname:usage contains ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, ifdef::VK_ANDROID_external_format_resolve[] @@ -4969,8 +5107,18 @@ ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] * [[VUID-VkImageViewCreateInfo-image-07072]] If pname:image was created with the ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and - pname:format is a non-compressed format, the pname:levelCount and - pname:layerCount members of pname:subresourceRange must: both be `1` + pname:format is a non-compressed format, the pname:levelCount member of + pname:subresourceRange must: be `1` + * [[VUID-VkImageViewCreateInfo-image-09487]] + If pname:image was created with the + ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, +ifdef::VK_KHR_maintenance6[] + the + sname:VkPhysicalDeviceMaintenance6PropertiesKHR::pname:blockTexelViewCompatibleMultipleLayers + property is not set to ename:VK_TRUE, +endif::VK_KHR_maintenance6[] + and pname:format is a non-compressed format, then the pname:layerCount + member of pname:subresourceRange must: be `1` endif::VK_VERSION_1_1,VK_KHR_maintenance2[] ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] * [[VUID-VkImageViewCreateInfo-pNext-01585]] @@ -6447,14 +6595,7 @@ include::{generated}/api/structs/VkAccelerationStructureCreateInfoKHR.adoc[] * pname:deviceAddress is the device address requested for the acceleration structure if the <> feature is being used. - -If pname:deviceAddress is zero, no specific address is requested. - -If pname:deviceAddress is not zero, pname:deviceAddress must: be an address -retrieved from an identically created acceleration structure on the same -implementation. -The acceleration structure must: also be placed on an identically created -pname:buffer and at the same pname:offset. + If pname:deviceAddress is zero, no specific address is requested. Applications should: avoid creating acceleration structures with application-provided addresses and implementation-provided addresses in the @@ -6525,6 +6666,22 @@ endif::VK_NV_ray_tracing_motion_blur[] * [[VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-03612]] If pname:deviceAddress is not zero, pname:createFlags must: include ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR + * [[VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09488]] + If pname:deviceAddress is not zero, it must: have been retrieved from an + identically created acceleration structure, except for pname:buffer and + pname:deviceAddress + * [[VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09489]] + If pname:deviceAddress is not zero, pname:buffer must: have been created + identically to the pname:buffer used to create the acceleration + structure from which pname:deviceAddress was retrieved, except for + slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress + * [[VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-09490]] + If pname:deviceAddress is not zero, pname:buffer must: have been created + with a + slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress + that was retrieved from flink:vkGetBufferOpaqueCaptureAddress for the + pname:buffer that was used to create the acceleration structure from + which pname:deviceAddress was retrieved * [[VUID-VkAccelerationStructureCreateInfoKHR-createFlags-03613]] If pname:createFlags includes ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR, @@ -8037,11 +8194,13 @@ flink:vkGetBufferMemoryRequirements and flink:vkGetImageMemoryRequirements: * The pname:memoryTypeBits member always contains at least one bit set. * If pname:buffer is a sname:VkBuffer not created with the - ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT bit set, or if pname:image is - <> image, then the pname:memoryTypeBits - member always contains at least one bit set corresponding to a - sname:VkMemoryType with a pname:propertyFlags that has both the - ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit and the + ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT or + ename:VK_BUFFER_CREATE_PROTECTED_BIT bits set, or if pname:image is a + <> image that was not created with the + ename:VK_IMAGE_CREATE_PROTECTED_BIT bit set, then the + pname:memoryTypeBits member always contains at least one bit set + corresponding to a sname:VkMemoryType with a pname:propertyFlags that + has both the ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit and the ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit set. In other words, mappable coherent memory can: always be attached to these objects. @@ -8730,12 +8889,28 @@ endif::VK_KHR_bind_memory2[] On some implementations, it may: be more efficient to batch memory bindings into a single command. +ifdef::VK_KHR_maintenance6[] +If the <> feature is enabled, +this command must: attempt to perform all of the memory binding operations +described by pname:pBindInfos, and must: not early exit on the first +failure. +endif::VK_KHR_maintenance6[] + +If any of the memory binding operations described by pname:pBindInfos fail, +the elink:VkResult returned by this command must: be the return value of any +one of the memory binding operations which did not return ename:VK_SUCCESS. + [NOTE] .Note ==== -If fname:vkBindBufferMemory2 fails, and pname:bindInfoCount was greater than -one, then the buffers referenced by pname:pBindInfos will be in an -indeterminate state, and must not be used. +If the fname:vkBindBufferMemory2 command failed, +ifdef::VK_KHR_maintenance6[] +slink:VkBindMemoryStatusKHR structures were not included in the pname:pNext +chains of each element of pname:pBindInfos, +endif::VK_KHR_maintenance6[] +and pname:bindInfoCount was greater than one, then the buffers referenced by +pname:pBindInfos will be in an indeterminate state, and must not be used. + Applications should destroy these buffers. ==== @@ -8844,6 +9019,28 @@ In other words, by default each physical device attaches to instance zero. include::{generated}/validity/structs/VkBindBufferMemoryDeviceGroupInfo.adoc[] -- endif::VK_VERSION_1_1,VK_KHR_device_group[] + +ifdef::VK_KHR_maintenance6[] +[open,refpage='VkBindMemoryStatusKHR',desc='Structure specifying where to return memory binding status',type='structs'] +-- +The sname:VkBindMemoryStatusKHR structure is defined as: + +include::{generated}/api/structs/VkBindMemoryStatusKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:pResult is a pointer to a ename:VkResult value. + +If the pname:pNext chain of slink:VkBindBufferMemoryInfo or +slink:VkBindImageMemoryInfo includes a sname:VkBindMemoryStatusKHR +structure, then the sname:VkBindMemoryStatusKHR::pname:pResult will be +populated with a value describing the result of the corresponding memory +binding operation. + +include::{generated}/validity/structs/VkBindMemoryStatusKHR.adoc[] +-- +endif::VK_KHR_maintenance6[] endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] [open,refpage='vkBindImageMemory',desc='Bind device memory to an image object',type='protos'] @@ -8946,12 +9143,28 @@ endif::VK_KHR_bind_memory2[] On some implementations, it may: be more efficient to batch memory bindings into a single command. +ifdef::VK_KHR_maintenance6[] +If the <> feature is enabled, +this command must: attempt to perform all of the memory binding operations +described by pname:pBindInfos, and must: not early exit on the first +failure. +endif::VK_KHR_maintenance6[] + +If any of the memory binding operations described by pname:pBindInfos fail, +the elink:VkResult returned by this command must: be the return value of any +one of the memory binding operations which did not return ename:VK_SUCCESS. + [NOTE] .Note ==== -If fname:vkBindImageMemory2 fails, and pname:bindInfoCount was greater than -one, then the images referenced by pname:pBindInfos will be in an -indeterminate state, and must not be used. +If the fname:vkBindImageMemory2 command failed, +ifdef::VK_KHR_maintenance6[] +slink:VkBindMemoryStatusKHR structures were not included in the pname:pNext +chains of each element of pname:pBindInfos, +endif::VK_KHR_maintenance6[] +and pname:bindInfoCount was greater than one, then the images referenced by +pname:pBindInfos will be in an indeterminate state, and must not be used. + Applications should destroy these images. ==== diff --git a/chapters/sparsemem.adoc b/chapters/sparsemem.adoc index 02af1bc78..2105a83cb 100644 --- a/chapters/sparsemem.adoc +++ b/chapters/sparsemem.adoc @@ -1448,6 +1448,17 @@ the binding range must: be within the range If pname:memory is not dlink:VK_NULL_HANDLE, pname:memory and pname:memoryOffset must: match the memory requirements of the resource, as described in section <> + * [[VUID-VkSparseMemoryBind-resourceOffset-09491]] + If the resource being bound is a sname:VkBuffer, pname:resourceOffset + and pname:memoryOffset must: be an integer multiple of the + pname:alignment of the slink:VkMemoryRequirements structure returned + from a call to flink:vkGetBufferMemoryRequirements with the buffer + resource + * [[VUID-VkSparseMemoryBind-resourceOffset-09492]] + If the resource being bound is a sname:VkImage, pname:resourceOffset and + pname:memoryOffset must: be an integer multiple of the pname:alignment + of the slink:VkMemoryRequirements structure returned from a call to + flink:vkGetImageMemoryRequirements with the image resource * [[VUID-VkSparseMemoryBind-memory-01097]] If pname:memory is not dlink:VK_NULL_HANDLE, pname:memory must: not have been created with a memory type that reports diff --git a/chapters/video_decode_extensions.adoc b/chapters/video/decode.adoc similarity index 86% rename from chapters/video_decode_extensions.adoc rename to chapters/video/decode.adoc index ff8e47b25..01487c7c6 100644 --- a/chapters/video_decode_extensions.adoc +++ b/chapters/video/decode.adoc @@ -11,7 +11,7 @@ buffer and zero or more reference pictures, and produce a _decode output picture_ and an optional <>. [NOTE] -.Note: +.Note ==== Such decode output pictures can be shared with the <>, and can also be used @@ -38,7 +38,7 @@ ename:VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR stage: ename:VK_ACCESS_2_VIDEO_DECODE_WRITE_BIT_KHR. The image subresource of each <> accessed by the video coding operation is specified using a +resource>> accessed by the video decode operation is specified using a corresponding slink:VkVideoPictureResourceInfoKHR structure. Each such image subresource must: be in the appropriate image layout as follows: @@ -61,9 +61,10 @@ follows: A video decode operation may: complete unsuccessfully. In this case the <> will have undefined: contents. -Similarly, if a <> is -specified, it will also have undefined: contents, and the activated DPB slot -will have an <>. +Similarly, if <> is requested, +the <> will also have +undefined: contents, and the activated DPB slot will have an +<>. [[decode-codec-specific-semantics]] @@ -80,6 +81,7 @@ The following aspects of video decode operations are codec-specific: * The construction and interpretation of information related to the <> and the generation of picture data to the corresponding image subregion. + * The decision on <>. * The construction and interpretation of information related to the optional <> and the generation of picture data to the corresponding image subregion. @@ -114,15 +116,21 @@ ename:VK_PIPELINE_STAGE_2_VIDEO_DECODE_BIT_KHR stage: applying any prediction data read from the <> in the process; 3. Writes the decoded picture data to the <>, and to the <>, if one is specified and is different from the decode output - picture, according to the <>; - 4. When <> is provided, the requested <> is - <> with the specified picture and the DPB - slot index is associated with the corresponding - <>. + output picture>>, and optionally to the <>, if one is specified and is different from the + decode output picture, according to the + <>; + 4. If <> is requested, the + <> specified in the + <> + is <> with the + <>. + +When <> +is provided, the specified <> index is associated with +the corresponding <>, indifferent of whether <> is requested. === Capabilities @@ -172,7 +180,7 @@ ename:VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR. Accordingly, applications should: handle both cases to maximize portability. [NOTE] -.Note: +.Note ==== If both ename:VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR and ename:VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR are @@ -217,6 +225,15 @@ After calling this command, the Currently each call to this command results in the issue of a single video decode operation. +ifdef::VK_KHR_video_maintenance1[] +If the bound video session was created with +ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR and the pname:pNext +chain of pname:pDecodeInfo includes a slink:VkVideoInlineQueryInfoKHR +structure with its pname:queryPool member specifying a valid +sname:VkQueryPool handle, then this command will execute a query for each +video decode operation issued by it. +endif::VK_KHR_video_maintenance1[] + [[decode-active-reference-picture-info]] Active Reference Picture Information:: @@ -253,11 +270,39 @@ of the following: <> to by the <> used as the reconstructed picture. - * The <> index to <> with the - reconstructed picture. + * The <> index to use for picture reconstruction. * The codec-specific reference information related to the reconstructed picture. +[[decode-ref-pic-setup]] +Specifying a valid slink:VkVideoReferenceSlotInfoKHR structure in +pname:pDecodeInfo->pSetupReferenceSlot is always required, unless the video +session was created with slink:VkVideoSessionCreateInfoKHR::pname:maxDpbSlot +equal to zero. +However, the DPB slot identified by +pname:pDecodeInfo->pSetupReferenceSlot->slotIndex is only +<> with the <> specified in +pname:pDecodeInfo->pSetupReferenceSlot->pPictureResource if reference +picture setup is requested according to the +<>. + +If reconstructed picture information is specified, and +pname:pDecodeInfo->pSetupReferenceSlot->pPictureResource refers to a +<> different than that of +the <>, but reference picture +setup is not requested, the contents of the <> corresponding to the reconstructed picture will be +undefined: after the video decode operation. + +[NOTE] +.Note +==== +Some implementations may always output the reconstructed picture or use it +as temporary storage during the video decode operation even when the +reconstructed picture is not marked for future reference. +==== + [[decode-output-picture-info]] Decode Output Picture Information:: @@ -386,6 +431,8 @@ endif::VK_KHR_video_decode_h264[] .Valid Usage **** + * [[VUID-vkCmdDecodeVideoKHR-None-08249]] + The bound video session must: have been created with a decode operation * [[VUID-vkCmdDecodeVideoKHR-None-07011]] The bound video session must: not be in <> state at the time the command is executed on the device @@ -396,6 +443,50 @@ endif::VK_KHR_video_decode_h264[] be less than or equal to the <> corresponding to the query type of that query plus one +ifdef::VK_KHR_video_maintenance1[] + * [[VUID-vkCmdDecodeVideoKHR-pNext-08365]] + If the bound video session was created with + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, and the + pname:pNext chain of pname:pDecodeInfo includes a + slink:VkVideoInlineQueryInfoKHR structure with its pname:queryPool + member specifying a valid sname:VkQueryPool handle, then + slink:VkVideoInlineQueryInfoKHR::queryCount must: equal ename:opCount + * [[VUID-vkCmdDecodeVideoKHR-pNext-08366]] + If the bound video session was created with + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, and the + pname:pNext chain of pname:pDecodeInfo includes a + slink:VkVideoInlineQueryInfoKHR structure with its pname:queryPool + member specifying a valid sname:VkQueryPool handle, then all the queries + used by the command, as specified by the slink:VkVideoInlineQueryInfoKHR + structure, must: be _unavailable_ + * [[VUID-vkCmdDecodeVideoKHR-queryType-08367]] + If the bound video session was created with + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, then the + pname:queryType used to create the pname:queryPool specified in the + slink:VkVideoInlineQueryInfoKHR structure included in the pname:pNext + chain of pname:pDecodeInfo must: be + ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR + * [[VUID-vkCmdDecodeVideoKHR-queryPool-08368]] + If the bound video session was created with + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, then the + pname:queryPool specified in the slink:VkVideoInlineQueryInfoKHR + structure included in the pname:pNext chain of pname:pDecodeInfo must: + have been created with a slink:VkVideoProfileInfoKHR structure included + in the pname:pNext chain of slink:VkQueryPoolCreateInfo identical to the + one specified in slink:VkVideoSessionCreateInfoKHR::pname:pVideoProfile + the bound video session was created with + * [[VUID-vkCmdDecodeVideoKHR-queryType-08369]] + If the bound video session was created with + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, and the + pname:queryType used to create the pname:queryPool specified in the + slink:VkVideoInlineQueryInfoKHR structure included in the pname:pNext + chain of pname:pDecodeInfo is + ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR, then the sname:VkCommandPool + that pname:commandBuffer was allocated from must: have been created with + a queue family index that supports <>, as indicated by + slink:VkQueueFamilyQueryResultStatusPropertiesKHR::pname:queryResultStatusSupport +endif::VK_KHR_video_maintenance1[] * [[VUID-vkCmdDecodeVideoKHR-pDecodeInfo-07135]] pname:pDecodeInfo->srcBuffer must: be <> with the video profile the bound video session was created @@ -464,6 +555,10 @@ endif::VK_KHR_video_decode_h264[] <> is not supported, then pname:pDecodeInfo->dstPictureResource.imageViewBinding must: have been created from a protected image + * [[VUID-vkCmdDecodeVideoKHR-pDecodeInfo-08376]] + pname:pDecodeInfo->pSetupReferenceSlot must: not be `NULL` unless the + bound video session was created with + slink:VkVideoSessionCreateInfoKHR::pname:maxDpbSlots equal to zero * [[VUID-vkCmdDecodeVideoKHR-pDecodeInfo-07170]] If pname:pDecodeInfo->pSetupReferenceSlot is not `NULL`, then pname:pDecodeInfo->pSetupReferenceSlot->slotIndex must: be less than the @@ -750,10 +845,8 @@ include::{generated}/api/structs/VkVideoDecodeInfoKHR.adoc[] * pname:dstPictureResource is the video picture resource to use as the <>. * pname:pSetupReferenceSlot is `NULL` or a pointer to a - slink:VkVideoReferenceSlotInfoKHR structure describing the DPB slot to - <> and the video picture resource to use as - the <> to activate the DPB - slot with. + slink:VkVideoReferenceSlotInfoKHR structure specifying the + <>. * pname:referenceSlotCount is the number of elements in the pname:pReferenceSlots array. * pname:pReferenceSlots is `NULL` or a pointer to an array of diff --git a/chapters/video/encode.adoc b/chapters/video/encode.adoc new file mode 100644 index 000000000..9bf0f09a1 --- /dev/null +++ b/chapters/video/encode.adoc @@ -0,0 +1,2010 @@ +// Copyright 2018-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +[[video-encode-operations]] +== Video Encode Operations + +[[encode-input-picture]] +Video encode operations consume an _encode input picture_ and zero or more +reference pictures, and produce compressed video data to a video bitstream +buffer and an optional <>. + +[NOTE] +.Note +==== +Such encode input pictures can be used +ifdef::VK_KHR_video_decode_queue[] +as the <> of video decode operations, +endif::VK_KHR_video_decode_queue[] +with graphics or compute operations, +ifdef::VK_KHR_surface[] +or with <> APIs, +endif::VK_KHR_surface[] +depending on the capabilities of the implementation. +==== + +Video encode operations may: access the following resources in the +ename:VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR stage: + + * The image subregions corresponding to the source + <> and + <> with + access ename:VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR. + * The destination video bitstream buffer range and the optional + <> with access + ename:VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR. + +The image subresource of each <> accessed by the video encode operation is specified using a +corresponding slink:VkVideoPictureResourceInfoKHR structure. +Each such image subresource must: be in the appropriate image layout as +follows: + + * If the image subresource is used in the video encode operation as an + <>, then it must: be in the + ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR layout. + * If the image subresource is used in the video encode operation as a + <> or <>, then it must: be in the + ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR layout. + +[[encode-unsuccessful]] +A video encode operation may: complete unsuccessfully. +In this case the target video bitstream buffer will have undefined: +contents. +Similarly, if <> is requested, +the <> will also have +undefined: contents, and the activated DPB slot will have an +<>. + +If a video encode operation completes successfully and the codec-specific +parameters provided by the application adhere to the syntactic and semantic +requirements defined in the corresponding video compression standard, then +the target video bitstream buffer will contain compressed video data after +the execution of the video encode operation according to the respective +<>. + + +[[encode-codec-specific-semantics]] +=== Codec-Specific Semantics + +The following aspects of video encode operations are codec-specific: + + * The compressed video data written to the target video bitstream buffer + range. + * The construction and interpretation of the list of + <> and + the interpretation of the picture data referred to by the corresponding + image subregions. + * The construction and interpretation of information related to the + <> and the + interpretation of the picture data referred to by the corresponding + image subregion. + * The decision on <>. + * The construction and interpretation of information related to the + optional <> and + the generation of picture data to the corresponding image subregion. + * Certain aspects of <>. + +These codec-specific behaviors are defined for each video codec operation +separately. + +ifdef::VK_KHR_video_encode_h264[] + * If the used video codec operation is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the + codec-specific aspects of the video encoding process are performed as + defined in the <> section. +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * If the used video codec operation is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the + codec-specific aspects of the video encoding process are performed as + defined in the <> section. +endif::VK_KHR_video_encode_h265[] + + +[[encode-overrides]] +==== Video Encode Parameter Overrides + +Implementations supporting video encode operations for any particular video +codec operation often support only a subset of the available encoding tools +defined by the corresponding video compression standards. +Accordingly, certain implementation-dependent limitations may: apply to +codec-specific parameters provided through the structures defined in the +Video Std headers corresponding to the used video codec operation. + +Exposing all of these restrictions on particular codec-specific parameter +values or combinations thereof in the form of application-queryable +capabilities is impractical, hence this specification allows implementations +to _override_ the value of any of the codec-specific parameters, unless +otherwise specified, as long as all of the following conditions are met: + + * If the application-provided codec-specific parameters adhere to the + syntactic and semantic requirements and rules defined by the used video + compression standard, and thus would be usable to produce a video + bitstream compliant with that standard, then the codec-specific + parameters resulting from the process of implementation overrides must: + also adhere to the same requirements and rules, and any video bitstream + produced using the overridden parameters must: also be compliant. + * The overridden codec-specific parameter values must: not have an impact + on the codec-independent behaviors defined for video encode operations. + * The implementation must: not override any codec-specific parameters + specified to a command that may: cause application-provided + codec-specific parameters specified to subsequent commands to no longer + adhere to the semantic requirements and rules defined by the used video + compression standard, unless the implementation also overrides those + parameters to adhere to any such requirements and rules. + * The overridden codec-specific parameter values must: not have an impact + on the codec-specific picture data access semantics. + * The overridden codec-specific parameter values may: change the contents + of the codec-specific bitstream elements produced by video encode + operations or otherwise retrieved by the application (e.g. using the + flink:vkGetEncodedVideoSessionParametersKHR command) but must: still + adhere to the codec-specific semantics defined for that video codec + operation, including, but not limited to, the number, type, and order of + the encoded codec-specific bitstream elements. + +Besides codec-specific parameter overrides performed for +implementation-dependent reasons, applications can: enable the +implementation to apply additional <> that may: improve the efficiency or performance of video +encoding operations. +However, implementations must: meet the conditions listed above even in case +of such optimizing overrides. + +[NOTE] +.Note +==== +Unless the application opts in for optimizing overrides, implementations are +not expected to override any of the codec-specific parameters, except when +such overrides are necessary for the correct operation of video encoder +implementation due to limitations to the available encoding tools on that +implementation. +==== + + +[[encode-operation-steps]] +=== Video Encode Operation Steps + +Each video encode operation performs the following steps in the +ename:VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR stage: + + 1. Reads the input picture data from the <>; + 2. Determine derived encoding quality parameters according to the + <> and the + current <> state; + 3. Compresses the input picture data according to the + <>, applying + any prediction data read from the <> and rate control restrictions in the process; + 4. Writes the encoded bitstream data to the destination video bitstream + buffer range; + 5. Performs picture reconstruction of the encoded video data according to + the <>, + applying any prediction data read from the <> in the process, if a + <> is specified and + <> is requested; + 6. If <> is requested, the + <> specified in the + <> + is <> with the + <>; + 7. Writes the reconstructed picture data to the <>, if one is specified, according to the + <>. + +When <> +is provided, the specified <> index is associated with +the corresponding <>, indifferent of whether <> is requested. + +=== Capabilities + +[open,refpage='VkVideoEncodeCapabilitiesKHR',desc='Structure describing general video encode capabilities for a video profile',type='structs'] +-- +When calling flink:vkGetPhysicalDeviceVideoCapabilitiesKHR with +pname:pVideoProfile->videoCodecOperation specifying an encode operation, the +slink:VkVideoEncodeCapabilitiesKHR structure must: be included in the +pname:pNext chain of the slink:VkVideoCapabilitiesKHR structure to retrieve +capabilities specific to video encoding. + +The sname:VkVideoEncodeCapabilitiesKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeCapabilitiesKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:flags is a bitmask of elink:VkVideoEncodeCapabilityFlagBitsKHR + describing supported encoding features. + * pname:rateControlModes is a bitmask of + elink:VkVideoEncodeRateControlModeFlagBitsKHR indicating supported + <>. + * pname:maxRateControlLayers indicates the maximum number of + <> supported. + * pname:maxBitrate indicates the maximum supported bitrate. + * pname:maxQualityLevels indicates the number of discrete + <> supported. + Implementations must: support at least one quality level. + * pname:encodeInputPictureGranularity indicates the granularity at which + <> data is encoded and may: + indicate a texel granularity up to the size of the codec-specific coding + block size. + This capability does not impose any valid usage constraints on the + application, however, depending on the contents of the encode input + picture, it may: have effects on the encoded bitstream, as described in + more detail below. + * pname:supportedEncodeFeedbackFlags is a bitmask of + elink:VkVideoEncodeFeedbackFlagBitsKHR values specifying the supported + flags for <>. + +Implementations must: include support for at least +ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR and +ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR in +pname:supportedEncodeFeedbackFlags. + +pname:encodeInputPictureGranularity provides information about the way +<> data is used as input to video +encode operations. +In particular, some implementations may: not be able to limit the set of +texels used to encode the output video bitstream to the image subregion +specified in the slink:VkVideoPictureResourceInfoKHR structure corresponding +to the encode input picture (i.e. to the resolution of the image data to +encode specified in its pname:codedExtent member). + +[NOTE] +.Note +==== +For example, the application requests the coded extent to be 1920x1080, but +the implementation is only able to source the encode input picture data at +the granularity of the codec-specific coding block size which is 16x16 +pixels (or as otherwise indicated in pname:encodeInputPictureGranularity). +In this example, the content is horizontally aligned with the coding block +size, but not vertically aligned with it. +Thus encoding of the last row of coding blocks will be impacted by the +contents of the input image at texel rows 1080 to 1087 (the latter being the +next row which is vertically aligned with the coding block size, assuming a +zero-based texel row index). +==== + +If pname:codedExtent rounded up to the next integer multiple of +pname:encodeInputPictureGranularity is greater than the extent of the image +subresource specified for the <>, +then the texel values corresponding to texel coordinates outside of the +bounds of the image subresource may: be undefined:. +However, implementations should: use well-defined default values for such +texels in order to maximize the encoding efficiency for the last coding +block row/column, and/or to ensure consistent encoding results across +repeated encoding of the same input content. +Nonetheless, the values used for such texels must: not have an effect on +whether the video encode operation produces a compliant bitstream, and must: +not have any other effects on the encoded picture data beyond what may: +otherwise result from using these texel values as input to any compression +algorithm, as defined in the used video compression standard. + +[NOTE] +.Note +==== +While not required, it is generally a good practice for applications to make +sure that the image subresource used for the encode input picture has an +extent that is an integer multiple of the codec-specific coding block size +(or at least pname:encodeInputPictureGranularity) and that this padding area +is filled with known values in order to improve encoding efficiency, +portability, and reproducibility. +==== + +include::{generated}/validity/structs/VkVideoEncodeCapabilitiesKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeCapabilityFlagBitsKHR',desc='Video encode capability flags',type='enums'] +-- +Bits which may: be set in slink:VkVideoEncodeCapabilitiesKHR::pname:flags, +indicating the encoding tools supported, are: + +include::{generated}/api/enums/VkVideoEncodeCapabilityFlagBitsKHR.adoc[] + + * ename:VK_VIDEO_ENCODE_CAPABILITY_PRECEDING_EXTERNALLY_ENCODED_BYTES_BIT_KHR + indicates that the implementation supports the use of + slink:VkVideoEncodeInfoKHR::pname:precedingExternallyEncodedBytes. + * ename:VK_VIDEO_ENCODE_CAPABILITY_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_DETECTION_BIT_KHR + indicates that the implementation is able to detect and report when the + destination video bitstream buffer range provided by the application is + not sufficiently large to fit the encoded bitstream data produced by a + video encode operation by reporting the + ename:VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR + <>. ++ +[NOTE] +.Note +==== +Some implementations may: not be able to reliably detect insufficient +bitstream buffer range conditions in all situations. +Such implementations will not report support for the +ename:VK_VIDEO_ENCODE_CAPABILITY_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_DETECTION_BIT_KHR +encode capability flag for the video profile, but may: still report the +ename:VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR query +result status code in certain cases. +Applications should: always check for the specific query result status code +ename:VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR even +when this encode capability flag is not supported by the implementation for +the video profile in question. +However, applications must: not assume that a different negative query +result status code indicating an unsuccessful completion of a video encode +operation is not the result of an insufficient bitstream buffer condition +unless this encode capability flag is supported. +==== +-- + +[open,refpage='VkVideoEncodeCapabilityFlagsKHR',desc='Bitmask of VkVideoEncodeCapabilityFlagBitsKHR',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeCapabilityFlagsKHR.adoc[] + +tname:VkVideoEncodeCapabilityFlagsKHR is a bitmask type for setting a mask +of zero or more elink:VkVideoEncodeCapabilityFlagBitsKHR. +-- + + +[[encode-quality-level]] +=== Video Encode Quality Levels + +Implementations can: support more than one video encode quality levels for a +video encode profile, which control the number and type of +implementation-specific encoding tools and algorithms utilized in the +encoding process. + +[NOTE] +.Note +==== +Generally, using higher video encode quality levels may: produce higher +quality video streams at the cost of additional processing time. +However, as the final quality of an encoded picture depends on the contents +of the <>, the contents of the +<>, the codec-specific +encode parameters, and the particular implementation-specific tools used +corresponding to the individual video encode quality levels, there are no +guarantees that using a higher video encode quality level will always +produce a higher quality encoded picture for any given set of inputs. +==== + +[open,refpage='vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR',desc='Query video encode quality level properties',type='protos'] +-- +To query properties for a specific video encode quality level supported by a +video encode profile, call: + +include::{generated}/api/protos/vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR.adoc[] + + * pname:physicalDevice is the physical device to query the video encode + quality level properties for. + * pname:pQualityLevelInfo is a pointer to a + slink:VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR structure + specifying the video encode profile and quality level to query + properties for. + * pname:pQualityLevelProperties is a pointer to a + slink:VkVideoEncodeQualityLevelPropertiesKHR structure in which the + properties are returned. + +.Valid Usage +**** +ifdef::VK_KHR_video_encode_h264[] + * [[VUID-vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR-pQualityLevelInfo-08257]] + If pname:pQualityLevelInfo->pVideoProfile->videoCodecOperation is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the pname:pNext + chain of pname:pQualityLevelProperties must: include a + slink:VkVideoEncodeH264QualityLevelPropertiesKHR structure +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * [[VUID-vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR-pQualityLevelInfo-08258]] + If pname:pQualityLevelInfo->pVideoProfile->videoCodecOperation is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the pname:pNext + chain of pname:pQualityLevelProperties must: include a + slink:VkVideoEncodeH265QualityLevelPropertiesKHR structure +endif::VK_KHR_video_encode_h265[] +**** + +include::{generated}/validity/protos/vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR.adoc[] +-- + + +[open,refpage='VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR',desc='Structure describing the video encode profile and quality level to query properties for',type='structs'] +-- +The sname:VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR structure is +defined as: + +include::{generated}/api/structs/VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:pVideoProfile is a pointer to a slink:VkVideoProfileInfoKHR + structure specifying the video profile to query the video encode quality + level properties for. + * pname:qualityLevel is the video encode quality level to query properties + for. + +.Valid Usage +**** + * [[VUID-VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR-pVideoProfile-08259]] + pname:pVideoProfile must: be a <> + * [[VUID-VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR-pVideoProfile-08260]] + pname:pVideoProfile->videoCodecOperation must: specify an encode + operation + * [[VUID-VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR-qualityLevel-08261]] + pname:qualityLevel must: be less than + slink:VkVideoEncodeCapabilitiesKHR::pname:maxQualityLevels, as returned + by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile + specified in pname:pVideoProfile +**** + +include::{generated}/validity/structs/VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR.adoc[] +-- + + +[open,refpage='VkVideoEncodeQualityLevelPropertiesKHR',desc='Structure describing the video encode quality level properties',type='structs'] +-- +The sname:VkVideoEncodeQualityLevelPropertiesKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeQualityLevelPropertiesKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:preferredRateControlMode is a + elink:VkVideoEncodeRateControlModeFlagBitsKHR value indicating the + preferred <> to use with + the video encode quality level. + * pname:preferredRateControlLayerCount indicates the preferred number of + <> to use with the video + encode quality level. + +include::{generated}/validity/structs/VkVideoEncodeQualityLevelPropertiesKHR.adoc[] +-- + + +[open,refpage='VkVideoEncodeQualityLevelInfoKHR',desc='Structure specifying used video encode quality level',type='structs'] +-- +The sname:VkVideoEncodeQualityLevelInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeQualityLevelInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:qualityLevel is the used video encode quality level. + +This structure can: be specified in the following places: + + * In the pname:pNext chain of slink:VkVideoSessionParametersCreateInfoKHR + to specify the video encode quality level to use for a video session + parameters object created for a video encode session. + If no instance of this structure is included in the pname:pNext chain of + slink:VkVideoSessionParametersCreateInfoKHR, then the video session + parameters object is created with a video encode quality level of zero. + * In the pname:pNext chain of slink:VkVideoCodingControlInfoKHR to change + the video encode quality level state of the bound video session. + +.Valid Usage +**** + * [[VUID-VkVideoEncodeQualityLevelInfoKHR-qualityLevel-08311]] + pname:qualityLevel must: be less than + slink:VkVideoEncodeCapabilitiesKHR::pname:maxQualityLevels, as returned + by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile +**** + +include::{generated}/validity/structs/VkVideoEncodeQualityLevelInfoKHR.adoc[] +-- + + +=== Retrieving Encoded Session Parameters + +Any codec-specific parameters stored in video session parameters objects +may: need to be separately encoded and included in the final video bitstream +data, depending on the used video compression standard. +In such cases the application must: call the +flink:vkGetEncodedVideoSessionParametersKHR command to retrieve the encoded +parameter data from the used video session parameters object in order to be +able to produce a compliant video bitstream. + +[NOTE] +.Note +==== +This is needed because implementations may: have changed some of the +codec-specific parameters stored in the video session parameters object, as +defined in the <> +section. +In addition, the flink:vkGetEncodedVideoSessionParametersKHR command enables +the application to retrieve the encoded parameter data without having to +encode these codec-specific parameters manually. +==== + +[open,refpage='vkGetEncodedVideoSessionParametersKHR',desc='Get encoded parameter sets from a video session parameters object',type='protos'] +-- +Encoded parameter data can: be retrieved from a video session parameters +object created with a video encode operation using the command: + +include::{generated}/api/protos/vkGetEncodedVideoSessionParametersKHR.adoc[] + + * pname:device is the logical device that owns the video session + parameters object. + * pname:pVideoSessionParametersInfo is a pointer to a + slink:VkVideoEncodeSessionParametersGetInfoKHR structure specifying the + parameters of the encoded parameter data to retrieve. + * pname:pFeedbackInfo is either `NULL` or a pointer to a + slink:VkVideoEncodeSessionParametersFeedbackInfoKHR structure in which + feedback about the requested parameter data is returned. + * pname:pDataSize is a pointer to a code:size_t value related to the + amount of encode parameter data returned, as described below. + * pname:pData is either `NULL` or a pointer to a buffer to write the + encoded parameter data to. + +If pname:pData is `NULL`, then the size of the encoded parameter data, in +bytes, that can: be retrieved is returned in pname:pDataSize. +Otherwise, pname:pDataSize must: point to a variable set by the application +to the size of the buffer, in bytes, pointed to by pname:pData, and on +return the variable is overwritten with the number of bytes actually written +to pname:pData. +If pname:pDataSize is less than the size of the encoded parameter data that +can: be retrieved, then no data will be written to pname:pData, zero will be +written to pname:pDataSize, and ename:VK_INCOMPLETE will be returned instead +of ename:VK_SUCCESS, to indicate that no encoded parameter data was +returned. + +If pname:pFeedbackInfo is not `NULL` then the members of the +slink:VkVideoEncodeSessionParametersFeedbackInfoKHR structure and any +additional structures included in its pname:pNext chain that are applicable +to the video session parameters object specified in +pname:pVideoSessionParametersInfo::pname:videoSessionParameters will be +filled with feedback about the requested parameter data on all successful +calls to this command. + +[NOTE] +.Note +==== +This includes the cases when pname:pData is `NULL` or when +ename:VK_INCOMPLETE is returned by the command, and enables the application +to determine whether the implementation <> any of +the requested video session parameters without actually needing to retrieve +the encoded parameter data itself. +==== + +.Valid Usage +**** + * [[VUID-vkGetEncodedVideoSessionParametersKHR-pVideoSessionParametersInfo-08359]] + pname:pVideoSessionParametersInfo->videoSessionParameters must: have + been created with an encode operation +ifdef::VK_KHR_video_encode_h264[] + * [[VUID-vkGetEncodedVideoSessionParametersKHR-pVideoSessionParametersInfo-08262]] + If pname:pVideoSessionParametersInfo->videoSessionParameters was created + with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the pname:pNext + chain of pname:pVideoSessionParametersInfo must: include a + slink:VkVideoEncodeH264SessionParametersGetInfoKHR structure + * [[VUID-vkGetEncodedVideoSessionParametersKHR-pVideoSessionParametersInfo-08263]] + If pname:pVideoSessionParametersInfo->videoSessionParameters was created + with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then for the + slink:VkVideoEncodeH264SessionParametersGetInfoKHR structure included in + the pname:pNext chain of pname:pVideoSessionParametersInfo, if its + pname:writeStdSPS member is ename:VK_TRUE, then + pname:pVideoSessionParametersInfo->videoSessionParameters must: contain + a code:StdVideoH264SequenceParameterSet entry with + pname:seq_parameter_set_id matching + slink:VkVideoEncodeH264SessionParametersGetInfoKHR::pname:stdSPSId + * [[VUID-vkGetEncodedVideoSessionParametersKHR-pVideoSessionParametersInfo-08264]] + If pname:pVideoSessionParametersInfo->videoSessionParameters was created + with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then for the + slink:VkVideoEncodeH264SessionParametersGetInfoKHR structure included in + the pname:pNext chain of pname:pVideoSessionParametersInfo, if its + pname:writeStdPPS member is ename:VK_TRUE, then + pname:pVideoSessionParametersInfo->videoSessionParameters must: contain + a code:StdVideoH264PictureParameterSet entry with + pname:seq_parameter_set_id and pname:pic_parameter_set_id matching + slink:VkVideoEncodeH264SessionParametersGetInfoKHR::pname:stdSPSId and + slink:VkVideoEncodeH264SessionParametersGetInfoKHR::pname:stdPPSId, + respectively +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * [[VUID-vkGetEncodedVideoSessionParametersKHR-pVideoSessionParametersInfo-08265]] + If pname:pVideoSessionParametersInfo->videoSessionParameters was created + with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the pname:pNext + chain of pname:pVideoSessionParametersInfo must: include a + slink:VkVideoEncodeH265SessionParametersGetInfoKHR structure + * [[VUID-vkGetEncodedVideoSessionParametersKHR-pVideoSessionParametersInfo-08266]] + If pname:pVideoSessionParametersInfo->videoSessionParameters was created + with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then for the + slink:VkVideoEncodeH265SessionParametersGetInfoKHR structure included in + the pname:pNext chain of pname:pVideoSessionParametersInfo, if its + pname:writeStdVPS member is ename:VK_TRUE, then + pname:pVideoSessionParametersInfo->videoSessionParameters must: contain + a code:StdVideoH265VideoParameterSet entry with + pname:vps_video_parameter_set_id matching + slink:VkVideoEncodeH265SessionParametersGetInfoKHR::pname:stdVPSId + * [[VUID-vkGetEncodedVideoSessionParametersKHR-pVideoSessionParametersInfo-08267]] + If pname:pVideoSessionParametersInfo->videoSessionParameters was created + with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then for the + slink:VkVideoEncodeH265SessionParametersGetInfoKHR structure included in + the pname:pNext chain of pname:pVideoSessionParametersInfo, if its + pname:writeStdSPS member is ename:VK_TRUE, then + pname:pVideoSessionParametersInfo->videoSessionParameters must: contain + a code:StdVideoH265SequenceParameterSet entry with + pname:sps_video_parameter_set_id and pname:sps_seq_parameter_set_id + matching + slink:VkVideoEncodeH265SessionParametersGetInfoKHR::pname:stdVPSId and + slink:VkVideoEncodeH265SessionParametersGetInfoKHR::pname:stdSPSId, + respectively + * [[VUID-vkGetEncodedVideoSessionParametersKHR-pVideoSessionParametersInfo-08268]] + If pname:pVideoSessionParametersInfo->videoSessionParameters was created + with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then for the + slink:VkVideoEncodeH265SessionParametersGetInfoKHR structure included in + the pname:pNext chain of pname:pVideoSessionParametersInfo, if its + pname:writeStdPPS member is ename:VK_TRUE, then + pname:pVideoSessionParametersInfo->videoSessionParameters must: contain + a code:StdVideoH265PictureParameterSet entry with + pname:sps_video_parameter_set_id, pname:pps_seq_parameter_set_id, and + pname:pps_pic_parameter_set_id matching + slink:VkVideoEncodeH265SessionParametersGetInfoKHR::pname:stdVPSId, + slink:VkVideoEncodeH265SessionParametersGetInfoKHR::pname:stdSPSId, and + slink:VkVideoEncodeH265SessionParametersGetInfoKHR::pname:stdPPSId, + respectively +endif::VK_KHR_video_encode_h265[] +**** + +include::{generated}/validity/protos/vkGetEncodedVideoSessionParametersKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeSessionParametersGetInfoKHR',desc='Structure specifying parameters for retrieving encoded video session parameter data',type='structs'] +-- +The sname:VkVideoEncodeSessionParametersGetInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeSessionParametersGetInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:videoSessionParameters is the slink:VkVideoSessionParametersKHR + object to retrieve encoded parameter data from. + +Depending on the used video encode operation, additional codec-specific +structures may: need to be included in the pname:pNext chain of this +structure to identify the specific video session parameters to retrieve +encoded parameter data for, as described in the corresponding sections. + +include::{generated}/validity/structs/VkVideoEncodeSessionParametersGetInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeSessionParametersFeedbackInfoKHR',desc='Structure providing feedback about the requested video session parameters',type='structs'] +-- +The sname:VkVideoEncodeSessionParametersFeedbackInfoKHR structure is defined +as: + +include::{generated}/api/structs/VkVideoEncodeSessionParametersFeedbackInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:hasOverrides indicates whether any of the requested parameter data + were <> by the implementation. + +Depending on the used video encode operation, additional codec-specific +structures can: be be included in the pname:pNext chain of this structure to +capture codec-specific feedback information about the requested parameter +data, as described in the corresponding sections. + +include::{generated}/validity/structs/VkVideoEncodeSessionParametersFeedbackInfoKHR.adoc[] +-- + + +[[video-encode-commands]] +=== Video Encode Commands + +[open,refpage='vkCmdEncodeVideoKHR',desc='Launch video encode operations',type='protos'] +-- +To launch video encode operations, call: + +include::{generated}/api/protos/vkCmdEncodeVideoKHR.adoc[] + + * pname:commandBuffer is the command buffer in which to record the + command. + * pname:pEncodeInfo is a pointer to a slink:VkVideoEncodeInfoKHR structure + specifying the parameters of the video encode operations. + +Each call issues one or more video encode operations. +The implicit parameter pname:opCount corresponds to the number of video +encode operations issued by the command. +After calling this command, the +<> of each +<> query is incremented by pname:opCount. + +Currently each call to this command results in the issue of a single video +encode operation. + +ifdef::VK_KHR_video_maintenance1[] +If the bound video session was created with +ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR and the pname:pNext +chain of pname:pEncodeInfo includes a slink:VkVideoInlineQueryInfoKHR +structure with its pname:queryPool member specifying a valid +sname:VkQueryPool handle, then this command will execute a query for each +video encode operation issued by it. +endif::VK_KHR_video_maintenance1[] + +[[encode-active-reference-picture-info]] +Active Reference Picture Information:: + +The list of <> used by +a video encode operation is a list of image subregions used as the source of +<> data and related parameters, and is +derived from the slink:VkVideoReferenceSlotInfoKHR structures provided as +the elements of the pname:pEncodeInfo->pReferenceSlots array. +For each element of pname:pEncodeInfo->pReferenceSlots, one or more elements +are added to the active reference picture list, as defined by the +<>. +Each element of this list contains the following information: + + * The image subregion within the image subresource + <> to by the + <> used as the reference + picture. + * The <> index the reference picture is associated + with. + * The codec-specific reference information related to the reference + picture. + +[[encode-reconstructed-picture-info]] +Reconstructed Picture Information:: + +Information related to the optional <> used by a video encode operation is derived from the +slink:VkVideoReferenceSlotInfoKHR structure pointed to by +pname:pEncodeInfo->pSetupReferenceSlot, if not `NULL`, as defined by the +<>, and consists +of the following: + + * The image subregion within the image subresource + <> to by the + <> used as the + reconstructed picture. + * The <> index to use for picture reconstruction. + * The codec-specific reference information related to the reconstructed + picture. + +[[encode-ref-pic-setup]] +Specifying a valid slink:VkVideoReferenceSlotInfoKHR structure in +pname:pEncodeInfo->pSetupReferenceSlot is always required, unless the video +session was created with slink:VkVideoSessionCreateInfoKHR::pname:maxDpbSlot +equal to zero. +However, the DPB slot identified by +pname:pEncodeInfo->pSetupReferenceSlot->slotIndex is only +<> with the <> specified in +pname:pEncodeInfo->pSetupReferenceSlot->pPictureResource if reference +picture setup is requested according to the +<>. + +If reconstructed picture information is specified, but reference picture +setup is not requested, according to the codec-specific semantics, the +contents of the <> +corresponding to the reconstructed picture will be undefined: after the +video encode operation. + +[NOTE] +.Note +==== +Some implementations may always output the reconstructed picture or use it +as temporary storage during the video encode operation even when the +reconstructed picture is not marked for future reference. +==== + +[[encode-input-picture-info]] +Encode Input Picture Information:: + +Information related to the <> +used by a video encode operation is derived from +pname:pEncodeInfo->srcPictureResource and any codec-specific parameters +provided in the pname:pEncodeInfo->pNext chain, as defined by the +<>, and consists +of the following: + + * The image subregion within the image subresource + <> to by the + <> used as the encode + input picture. + * The codec-specific picture information related to the encoded picture. + +Several limiting values are defined below that are referenced by the +relevant valid usage statements of this command. + + * Let `uint32_t activeReferencePictureCount` be the size of the list of + active reference pictures used by the video encode operation. + Unless otherwise defined, pname:activeReferencePictureCount is set to + the value of pname:pEncodeInfo->referenceSlotCount. + * Let `VkOffset2D codedOffsetGranularity` be the minimum alignment + requirement for the coded offset of video picture resources. + Unless otherwise defined, the value of the pname:x and pname:y members + of pname:codedOffsetGranularity are `0`. + * Let `uint32_t dpbFrameUseCount[]` be an array of size pname:maxDpbSlots, + where pname:maxDpbSlots is the + slink:VkVideoSessionCreateInfoKHR::pname:maxDpbSlots the bound video + session was created with, with each element indicating the number of + times a frame associated with the corresponding DPB slot index is + referred to by the video coding operation. + Let the initial value of each element of the array be `0`. + ** If pname:pEncodeInfo->pSetupReferenceSlot is not `NULL`, then + `dpbFrameUseCount[i]` is incremented by one, where pname:i equals + pname:pEncodeInfo->pSetupReferenceSlot->slotIndex. + ** For each element of pname:pEncodeInfo->pReferenceSlots, + `dpbFrameUseCount[i]` is incremented by one, where pname:i equals the + pname:slotIndex member of the corresponding element. + * Let `VkExtent2D maxCodingBlockSize` be the maximum codec-specific coding + block size that may: be used by the video encode operation. +ifdef::VK_KHR_video_encode_h264[] + ** If the bound video session object was created with an + <>, then let + pname:maxCodingBlockSize be equal to the size of an H.264 macroblock, + i.e. `{16,16}`. +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + ** If the bound video session object was created with an + <>, then let + pname:maxCodingBlockSize be equal to the maximum H.265 coding block + size that may: be used by the video encode operation derived as the + maximum of the CTB sizes corresponding to the + elink:VkVideoEncodeH265CtbSizeFlagBitsKHR bits set in + slink:VkVideoEncodeH265CapabilitiesKHR::pname:ctbSizes, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the + bound video session was created with. +endif::VK_KHR_video_encode_h265[] + ** Otherwise, pname:maxCodingBlockSize is undefined:. + * If pname:maxCodingBlockSize is defined, then let `VkExtent2D + minCodingBlockExtent` be the coded extent of the + <> expressed in terms of + codec-specific coding blocks, assuming the maximum size of such coding + blocks, as defined by pname:maxCodingBlockSize, calculated from the + value of the pname:codedExtent member of + pname:pEncodeInfo->srcPictureResource as follows: + ** [eq]#pname:minCodingBlockExtent.width = (pname:codedExtent.width + + pname:maxCodingBlockSize.width - 1) / pname:maxCodingBlockSize.width# + ** [eq]#pname:minCodingBlockExtent.height = (pname:codedExtent.height + + pname:maxCodingBlockSize.height - 1) / pname:maxCodingBlockSize.height# +ifdef::VK_KHR_video_encode_h264[] + * If the bound video session object was created with an + <>, then: + ** Let `StdVideoH264PictureType h264PictureType` be the picture type of + the encoded picture set to the value of + pname:pStdPictureInfo->primary_pic_type specified in the + slink:VkVideoEncodeH264PictureInfoKHR structure included in the + pname:pEncodeInfo->pNext chain. + ** Let `StdVideoH264PictureType h264L0PictureTypes[]` and + `StdVideoH264PictureType h264L1PictureTypes[]` be the picture types of + the reference pictures in the L0 and L1 reference lists, respectively. + If pname:pStdPictureInfo->pRefLists specified in the + slink:VkVideoEncodeH264PictureInfoKHR structure included in the + pname:pEncodeInfo->pNext chain is not `NULL`, then for each reference + index specified in the elements of the + pname:pStdPictureInfo->pRefLists->RefPicList0 and + pname:pStdPictureInfo->pRefLists->RefPicList1 arrays, if the reference + index is not code:STD_VIDEO_H264_NO_REFERENCE_PICTURE, + pname:pStdReferenceInfo->primary_pic_type is added to + pname:h264L0PictureTypes or pname:h264L1PictureTypes, respectively, + where pname:pStdReferenceInfo is the member of the + slink:VkVideoEncodeH264DpbSlotInfoKHR structure included in the + pname:pNext chain of the element of pname:pEncodeInfo->pReferenceSlots + for which pname:slotIndex equals the reference index in question. +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * If the bound video session object was created with an + <>, then: + ** Let `StdVideoH265PictureType h265PictureType` be the picture type of + the encoded picture set to the value of pname:pStdPictureInfo->pic_type + specified in the slink:VkVideoEncodeH265PictureInfoKHR structure + included in the pname:pEncodeInfo->pNext chain. + ** Let `StdVideoH265PictureType h265L0PictureTypes[]` and + `StdVideoH265PictureType h265L1PictureTypes[]` be the picture types of + the reference pictures in the L0 and L1 reference lists, respectively. + If pname:pStdPictureInfo->pRefLists specified in the + slink:VkVideoEncodeH265PictureInfoKHR structure included in the + pname:pEncodeInfo->pNext chain is not `NULL`, then for each reference + index specified in the elements of the + pname:pStdPictureInfo->pRefLists->RefPicList0 and + pname:pStdPictureInfo->pRefLists->RefPicList1 arrays, if the reference + index is not code:STD_VIDEO_H265_NO_REFERENCE_PICTURE, + pname:pStdReferenceInfo->pic_type is added to pname:h265L0PictureTypes + or pname:h265L1PictureTypes, respectively, where + pname:pStdReferenceInfo is the member of the + slink:VkVideoEncodeH265DpbSlotInfoKHR structure included in the + pname:pNext chain of the element of pname:pEncodeInfo->pReferenceSlots + for which pname:slotIndex equals the reference index in question. +endif::VK_KHR_video_encode_h265[] + +.Valid Usage +**** + * [[VUID-vkCmdEncodeVideoKHR-None-08250]] + The bound video session must: have been created with an encode operation + * [[VUID-vkCmdEncodeVideoKHR-None-07012]] + The bound video session must: not be in <> state at the time the command is executed on the device + * [[VUID-vkCmdEncodeVideoKHR-None-08318]] + The bound video session parameters object must: have been created with + the currently set <> + for the bound video session at the time the command is executed on the + device + * [[VUID-vkCmdEncodeVideoKHR-opCount-07174]] + For each <> query, the + <> + corresponding to the query type of that query plus pname:opCount must: + be less than or equal to the + <> corresponding to the query type of that query plus one +ifdef::VK_KHR_video_maintenance1[] + * [[VUID-vkCmdEncodeVideoKHR-pNext-08360]] + If the bound video session was created with + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, and the + pname:pNext chain of pname:pEncodeInfo includes a + slink:VkVideoInlineQueryInfoKHR structure with its pname:queryPool + member specifying a valid sname:VkQueryPool handle, then + slink:VkVideoInlineQueryInfoKHR::queryCount must: equal ename:opCount + * [[VUID-vkCmdEncodeVideoKHR-pNext-08361]] + If the bound video session was created with + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, and the + pname:pNext chain of pname:pEncodeInfo includes a + slink:VkVideoInlineQueryInfoKHR structure with its pname:queryPool + member specifying a valid sname:VkQueryPool handle, then all the queries + used by the command, as specified by the slink:VkVideoInlineQueryInfoKHR + structure, must: be _unavailable_ + * [[VUID-vkCmdEncodeVideoKHR-queryType-08362]] + If the bound video session was created with + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, then the + pname:queryType used to create the pname:queryPool specified in the + slink:VkVideoInlineQueryInfoKHR structure included in the pname:pNext + chain of pname:pEncodeInfo must: be + ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR or + ename:VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR + * [[VUID-vkCmdEncodeVideoKHR-queryPool-08363]] + If the bound video session was created with + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, then the + pname:queryPool specified in the slink:VkVideoInlineQueryInfoKHR + structure included in the pname:pNext chain of pname:pEncodeInfo must: + have been created with a slink:VkVideoProfileInfoKHR structure included + in the pname:pNext chain of slink:VkQueryPoolCreateInfo identical to the + one specified in slink:VkVideoSessionCreateInfoKHR::pname:pVideoProfile + the bound video session was created with + * [[VUID-vkCmdEncodeVideoKHR-queryType-08364]] + If the bound video session was created with + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, and the + pname:queryType used to create the pname:queryPool specified in the + slink:VkVideoInlineQueryInfoKHR structure included in the pname:pNext + chain of pname:pEncodeInfo is + ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR, then the sname:VkCommandPool + that pname:commandBuffer was allocated from must: have been created with + a queue family index that supports <>, as indicated by + slink:VkQueueFamilyQueryResultStatusPropertiesKHR::pname:queryResultStatusSupport +endif::VK_KHR_video_maintenance1[] + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08201]] + pname:pEncodeInfo->dstBuffer must: be <> with the video profile the bound video session was created + with + * [[VUID-vkCmdEncodeVideoKHR-commandBuffer-08202]] + If pname:commandBuffer is an unprotected command buffer and + <> is not supported, + then pname:pEncodeInfo->dstBuffer must: not be a protected buffer + * [[VUID-vkCmdEncodeVideoKHR-commandBuffer-08203]] + If pname:commandBuffer is a protected command buffer and + <> is not supported, + then pname:pEncodeInfo->dstBuffer must: be a protected buffer + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08204]] + pname:pEncodeInfo->dstBufferOffset must: be an integer multiple of + slink:VkVideoCapabilitiesKHR::pname:minBitstreamBufferOffsetAlignment, + as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the + video profile the bound video session was created with + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08205]] + pname:pEncodeInfo->dstBufferRange must: be an integer multiple of + slink:VkVideoCapabilitiesKHR::pname:minBitstreamBufferSizeAlignment, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile the bound video session was created with + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08206]] + pname:pEncodeInfo->srcPictureResource.imageViewBinding must: be + <> with the video profile the + bound video session was created with + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08207]] + The format of pname:pEncodeInfo->srcPictureResource.imageViewBinding + must: match the slink:VkVideoSessionCreateInfoKHR::pname:pictureFormat + the bound video session was created with + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08208]] + pname:pEncodeInfo->srcPictureResource.codedOffset must: be an integer + multiple of pname:codedOffsetGranularity + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08209]] + pname:pEncodeInfo->srcPictureResource.codedExtent must: be between + pname:minCodedExtent and pname:maxCodedExtent, inclusive, the bound + video session was created with + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08210]] + pname:pEncodeInfo->srcPictureResource.imageViewBinding must: have been + created with ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR + * [[VUID-vkCmdEncodeVideoKHR-commandBuffer-08211]] + If pname:commandBuffer is an unprotected command buffer and + <> is not supported, + then pname:pEncodeInfo->srcPictureResource.imageViewBinding must: not + have been created from a protected image + * [[VUID-vkCmdEncodeVideoKHR-commandBuffer-08212]] + If pname:commandBuffer is a protected command buffer and + <> is not supported, + then pname:pEncodeInfo->srcPictureResource.imageViewBinding must: have + been created from a protected image + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08377]] + pname:pEncodeInfo->pSetupReferenceSlot must: not be `NULL` unless the + bound video session was created with + slink:VkVideoSessionCreateInfoKHR::pname:maxDpbSlots equal to zero + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08213]] + If pname:pEncodeInfo->pSetupReferenceSlot is not `NULL`, then + pname:pEncodeInfo->pSetupReferenceSlot->slotIndex must: be less than the + slink:VkVideoSessionCreateInfoKHR::pname:maxDpbSlots specified when the + bound video session was created + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08214]] + If pname:pEncodeInfo->pSetupReferenceSlot is not `NULL`, then + pname:pEncodeInfo->pSetupReferenceSlot->pPictureResource->codedOffset + must: be an integer multiple of pname:codedOffsetGranularity + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08215]] + If pname:pEncodeInfo->pSetupReferenceSlot is not `NULL`, then + pname:pEncodeInfo->pSetupReferenceSlot->pPictureResource must: + <> one of the + <> + * [[VUID-vkCmdEncodeVideoKHR-activeReferencePictureCount-08216]] + pname:activeReferencePictureCount must: be less than or equal to the + slink:VkVideoSessionCreateInfoKHR::pname:maxActiveReferencePictures + specified when the bound video session was created + * [[VUID-vkCmdEncodeVideoKHR-slotIndex-08217]] + The pname:slotIndex member of each element of + pname:pEncodeInfo->pReferenceSlots must: be less than the + slink:VkVideoSessionCreateInfoKHR::pname:maxDpbSlots specified when the + bound video session was created + * [[VUID-vkCmdEncodeVideoKHR-codedOffset-08218]] + The pname:codedOffset member of the slink:VkVideoPictureResourceInfoKHR + structure pointed to by the pname:pPictureResource member of each + element of pname:pEncodeInfo->pReferenceSlots must: be an integer + multiple of pname:codedOffsetGranularity + * [[VUID-vkCmdEncodeVideoKHR-pPictureResource-08219]] + The pname:pPictureResource member of each element of + pname:pEncodeInfo->pReferenceSlots must: + <> one of the + <> + associated with the DPB slot index specified in the pname:slotIndex + member of that element + * [[VUID-vkCmdEncodeVideoKHR-pPictureResource-08220]] + Each video picture resource corresponding to the pname:pPictureResource + member specified in the elements of pname:pEncodeInfo->pReferenceSlots + must: be <> within + pname:pEncodeInfo->pReferenceSlots + * [[VUID-vkCmdEncodeVideoKHR-dpbFrameUseCount-08221]] + All elements of pname:dpbFrameUseCount must: be less than or equal to + `1` + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08222]] + The image subresource <> to + by pname:pEncodeInfo->srcPictureResource must: be in the + ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR layout at the time the video + encode operation is executed on the device + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08223]] + If pname:pEncodeInfo->pSetupReferenceSlot is not `NULL`, then the image + subresource <> to by + pname:pEncodeInfo->pSetupReferenceSlot->pPictureResource must: be in the + ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR layout at the time the video + encode operation is executed on the device + * [[VUID-vkCmdEncodeVideoKHR-pPictureResource-08224]] + The image subresource <> to + by the pname:pPictureResource member of each element of + pname:pEncodeInfo->pReferenceSlots must: be in the + ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR layout at the time the video + encode operation is executed on the device +ifdef::VK_KHR_video_encode_h264[] + * [[VUID-vkCmdEncodeVideoKHR-pNext-08225]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the pname:pNext + chain of pname:pEncodeInfo must: include a + slink:VkVideoEncodeH264PictureInfoKHR structure + * [[VUID-vkCmdEncodeVideoKHR-StdVideoH264SequenceParameterSet-08226]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the bound video + session parameters object must: contain a + code:StdVideoH264SequenceParameterSet entry with + pname:seq_parameter_set_id matching + code:StdVideoEncodeH264PictureInfo::pname:seq_parameter_set_id that is + provided in the pname:pStdPictureInfo member of the + slink:VkVideoEncodeH264PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-StdVideoH264PictureParameterSet-08227]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the bound video + session parameters object must: contain a + code:StdVideoH264PictureParameterSet entry with + pname:seq_parameter_set_id and pname:pic_parameter_set_id matching + code:StdVideoEncodeH264PictureInfo::pname:seq_parameter_set_id and + code:StdVideoEncodeH264PictureInfo::pname:pic_parameter_set_id, + respectively, that are provided in the pname:pStdPictureInfo member of + the slink:VkVideoEncodeH264PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08228]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and + pname:pEncodeInfo->pSetupReferenceSlot is not `NULL`, then the + pname:pNext chain of pname:pEncodeInfo->pSetupReferenceSlot must: + include a slink:VkVideoEncodeH264DpbSlotInfoKHR structure + * [[VUID-vkCmdEncodeVideoKHR-pNext-08229]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the pname:pNext + chain of each element of pname:pEncodeInfo->pReferenceSlots must: + include a slink:VkVideoEncodeH264DpbSlotInfoKHR structure + * [[VUID-vkCmdEncodeVideoKHR-constantQp-08269]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and the current + <> is not + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then + slink:VkVideoEncodeH264NaluSliceInfoKHR::pname:constantQp must: be zero + for each element of the pname:pNaluSliceEntries member of the + slink:VkVideoEncodeH264PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-constantQp-08270]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and the current + <> is + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then + slink:VkVideoEncodeH264NaluSliceInfoKHR::pname:constantQp must: be + between slink:VkVideoEncodeH264CapabilitiesKHR::pname:minQp and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:maxQp, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the + bound video session was created with, for each element of the + pname:pNaluSliceEntries member of the + slink:VkVideoEncodeH264PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-constantQp-08271]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags does not include + ename:VK_VIDEO_ENCODE_H264_CAPABILITY_PER_SLICE_CONSTANT_QP_BIT_KHR, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile the bound video session was created with, then + slink:VkVideoEncodeH264NaluSliceInfoKHR::pname:constantQp must: have the + same value for each element of the pname:pNaluSliceEntries member of the + slink:VkVideoEncodeH264PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-naluSliceEntryCount-08302]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the + pname:naluSliceEntryCount member of the + slink:VkVideoEncodeH264PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo must: be less than or equal to + pname:minCodingBlockExtent.width multiplied by + pname:minCodingBlockExtent.height + * [[VUID-vkCmdEncodeVideoKHR-naluSliceEntryCount-08312]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags does not include + ename:VK_VIDEO_ENCODE_H264_CAPABILITY_ROW_UNALIGNED_SLICE_BIT_KHR, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile the bound video session was created with, then the + pname:naluSliceEntryCount member of the + slink:VkVideoEncodeH264PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo must: be less than or equal to + pname:minCodingBlockExtent.height + * [[VUID-vkCmdEncodeVideoKHR-pNext-08352]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, the pname:pNext + chain of pname:pEncodeInfo includes a + slink:VkVideoEncodeH264PictureInfoKHR structure, and + pname:pEncodeInfo->referenceSlotCount is greater than zero, then + slink:VkVideoEncodeH264PictureInfoKHR::pname:pStdPictureInfo->pRefLists + must: not be `NULL` + * [[VUID-vkCmdEncodeVideoKHR-pNext-08339]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, the pname:pNext + chain of pname:pEncodeInfo includes a + slink:VkVideoEncodeH264PictureInfoKHR structure, and + slink:VkVideoEncodeH264PictureInfoKHR::pname:pStdPictureInfo->pRefLists + is not `NULL`, then each element of the code:RefPicList0 and + code:RefPicList1 array members of the + code:StdVideoEncodeH264ReferenceListsInfo structure pointed to by + slink:VkVideoEncodeH264PictureInfoKHR::pname:pStdPictureInfo->pRefLists + must: either be code:STD_VIDEO_H264_NO_REFERENCE_PICTURE or must: equal + the pname:slotIndex member of one of the elements of + pname:pEncodeInfo->pReferenceSlots + * [[VUID-vkCmdEncodeVideoKHR-pNext-08353]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, the pname:pNext + chain of pname:pEncodeInfo includes a + slink:VkVideoEncodeH264PictureInfoKHR structure, and + pname:pEncodeInfo->referenceSlotCount is greater than zero, then the + pname:slotIndex member of each element of + pname:pEncodeInfo->pReferenceSlots must: equal one of the elements of + the code:RefPicList0 or code:RefPicList1 array members of the + code:StdVideoEncodeH264ReferenceListsInfo structure pointed to by + slink:VkVideoEncodeH264PictureInfoKHR::pname:pStdPictureInfo->pRefLists + * [[VUID-vkCmdEncodeVideoKHR-maxPPictureL0ReferenceCount-08340]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:maxPPictureL0ReferenceCount + is zero, as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR + for the video profile the bound video session was created with, then + pname:h264PictureType and each element of pname:h264L0PictureTypes and + pname:h264L1PictureTypes must: not be code:STD_VIDEO_H264_PICTURE_TYPE_P + * [[VUID-vkCmdEncodeVideoKHR-maxBPictureL0ReferenceCount-08341]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:maxBPictureL0ReferenceCount + and slink:VkVideoEncodeH264CapabilitiesKHR::pname:maxL1ReferenceCount + are both zero, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the + bound video session was created with, then pname:h264PictureType and + each element of pname:h264L0PictureTypes and pname:h264L1PictureTypes + must: not be code:STD_VIDEO_H264_PICTURE_TYPE_B + * [[VUID-vkCmdEncodeVideoKHR-flags-08342]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags does not include + ename:VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_KHR, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile the bound video session was created with, then each element of + pname:h264L0PictureTypes must: not be code:STD_VIDEO_H264_PICTURE_TYPE_B + * [[VUID-vkCmdEncodeVideoKHR-flags-08343]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags does not include + ename:VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_KHR, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile the bound video session was created with, then each element of + pname:h264L1PictureTypes must: not be code:STD_VIDEO_H264_PICTURE_TYPE_B +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * [[VUID-vkCmdEncodeVideoKHR-pNext-08230]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the pname:pNext + chain of pname:pEncodeInfo must: include a + slink:VkVideoEncodeH265PictureInfoKHR structure + * [[VUID-vkCmdEncodeVideoKHR-StdVideoH265VideoParameterSet-08231]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the bound video + session parameters object must: contain a + code:StdVideoH265VideoParameterSet entry with + pname:vps_video_parameter_set_id matching + code:StdVideoEncodeH265PictureInfo::pname:sps_video_parameter_set_id + that is provided in the pname:pStdPictureInfo member of the + slink:VkVideoEncodeH265PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-StdVideoH265SequenceParameterSet-08232]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the bound video + session parameters object must: contain a + code:StdVideoH265SequenceParameterSet entry with + pname:sps_video_parameter_set_id and pname:sps_seq_parameter_set_id + matching + code:StdVideoEncodeH265PictureInfo::pname:sps_video_parameter_set_id and + code:StdVideoEncodeH265PictureInfo::pname:pps_seq_parameter_set_id, + respectively, that are provided in the pname:pStdPictureInfo member of + the slink:VkVideoEncodeH265PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-StdVideoH265PictureParameterSet-08233]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the bound video + session parameters object must: contain a + code:StdVideoH265PictureParameterSet entry with + pname:sps_video_parameter_set_id, pname:pps_seq_parameter_set_id, and + pname:pps_pic_parameter_set_id matching + code:StdVideoEncodeH265PictureInfo::pname:sps_video_parameter_set_id, + code:StdVideoEncodeH265PictureInfo::pname:pps_seq_parameter_set_id, and + code:StdVideoEncodeH265PictureInfo::pname:pps_pic_parameter_set_id, + respectively, that are provided in the pname:pStdPictureInfo member of + the slink:VkVideoEncodeH265PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-pEncodeInfo-08234]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and + pname:pEncodeInfo->pSetupReferenceSlot is not `NULL`, then the + pname:pNext chain of pname:pEncodeInfo->pSetupReferenceSlot must: + include a slink:VkVideoEncodeH265DpbSlotInfoKHR structure + * [[VUID-vkCmdEncodeVideoKHR-pNext-08235]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the pname:pNext + chain of each element of pname:pEncodeInfo->pReferenceSlots must: + include a slink:VkVideoEncodeH265DpbSlotInfoKHR structure + * [[VUID-vkCmdEncodeVideoKHR-constantQp-08272]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and the current + <> is not + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then + slink:VkVideoEncodeH265NaluSliceSegmentInfoKHR::pname:constantQp must: + be zero for each element of the pname:pNaluSliceSegmentEntries member of + the slink:VkVideoEncodeH265PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-constantQp-08273]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and the current + <> is + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then + slink:VkVideoEncodeH265NaluSliceSegmentInfoKHR::pname:constantQp must: + be between slink:VkVideoEncodeH265CapabilitiesKHR::pname:minQp and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxQp, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the + bound video session was created with, for each element of the + pname:pNaluSliceSegmentEntries member of the + slink:VkVideoEncodeH265PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-constantQp-08274]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_PER_SLICE_SEGMENT_CONSTANT_QP_BIT_KHR, + as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the + video profile the bound video session was created with, then + slink:VkVideoEncodeH265NaluSliceSegmentInfoKHR::pname:constantQp must: + have the same value for each element of the + pname:pNaluSliceSegmentEntries member of the + slink:VkVideoEncodeH264PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo + * [[VUID-vkCmdEncodeVideoKHR-naluSliceSegmentEntryCount-08307]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the + pname:naluSliceSegmentEntryCount member of the + slink:VkVideoEncodeH265PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo must: be less than or equal to + pname:minCodingBlockExtent.width multiplied by + pname:minCodingBlockExtent.height + * [[VUID-vkCmdEncodeVideoKHR-naluSliceSegmentEntryCount-08313]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_ROW_UNALIGNED_SLICE_SEGMENT_BIT_KHR, + as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the + video profile the bound video session was created with, then the + pname:naluSliceSegmentEntryCount member of the + slink:VkVideoEncodeH265PictureInfoKHR structure included in the + pname:pNext chain of pname:pEncodeInfo must: be less than or equal to + pname:minCodingBlockExtent.height + * [[VUID-vkCmdEncodeVideoKHR-pNext-08354]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, the pname:pNext + chain of pname:pEncodeInfo includes a + slink:VkVideoEncodeH265PictureInfoKHR structure, and + pname:pEncodeInfo->referenceSlotCount is greater than zero, then + slink:VkVideoEncodeH265PictureInfoKHR::pname:pStdPictureInfo->pRefLists + must: not be `NULL` + * [[VUID-vkCmdEncodeVideoKHR-pNext-08344]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, the pname:pNext + chain of pname:pEncodeInfo includes a + slink:VkVideoEncodeH265PictureInfoKHR structure, and + slink:VkVideoEncodeH265PictureInfoKHR::pname:pStdPictureInfo->pRefLists + is not `NULL`, then each element of the code:RefPicList0 and + code:RefPicList1 array members of the + code:StdVideoEncodeH265ReferenceListsInfo structure pointed to by + slink:VkVideoEncodeH265PictureInfoKHR::pname:pStdPictureInfo->pRefLists + must: either be code:STD_VIDEO_H265_NO_REFERENCE_PICTURE or must: equal + the pname:slotIndex member of one of the elements of + pname:pEncodeInfo->pReferenceSlots + * [[VUID-vkCmdEncodeVideoKHR-pNext-08355]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, the pname:pNext + chain of pname:pEncodeInfo includes a + slink:VkVideoEncodeH265PictureInfoKHR structure, and + pname:pEncodeInfo->referenceSlotCount is greater than zero, then the + pname:slotIndex member of each element of + pname:pEncodeInfo->pReferenceSlots must: equal one of the elements of + the code:RefPicList0 or code:RefPicList1 array members of the + code:StdVideoEncodeH265ReferenceListsInfo structure pointed to by + slink:VkVideoEncodeH265PictureInfoKHR::pname:pStdPictureInfo->pRefLists + * [[VUID-vkCmdEncodeVideoKHR-maxPPictureL0ReferenceCount-08345]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxPPictureL0ReferenceCount + is zero, as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR + for the video profile the bound video session was created with, then + pname:h265PictureType and each element of pname:h265L0PictureTypes and + pname:h265L1PictureTypes must: not be code:STD_VIDEO_H265_PICTURE_TYPE_P + * [[VUID-vkCmdEncodeVideoKHR-maxBPictureL0ReferenceCount-08346]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxBPictureL0ReferenceCount + and slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxL1ReferenceCount + are both zero, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the + bound video session was created with, then pname:h265PictureType and + each element of pname:h265L0PictureTypes and pname:h265L1PictureTypes + must: not be code:STD_VIDEO_H265_PICTURE_TYPE_B + * [[VUID-vkCmdEncodeVideoKHR-flags-08347]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_KHR, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile the bound video session was created with, then each element of + pname:h265L0PictureTypes must: not be code:STD_VIDEO_H264_PICTURE_TYPE_B + * [[VUID-vkCmdEncodeVideoKHR-flags-08348]] + If the bound video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_KHR, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile the bound video session was created with, then each element of + pname:h265L1PictureTypes must: not be code:STD_VIDEO_H265_PICTURE_TYPE_B +endif::VK_KHR_video_encode_h265[] +**** + +include::{generated}/validity/protos/vkCmdEncodeVideoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeInfoKHR',desc='Structure specifying video encode parameters',type='structs'] +-- +The sname:VkVideoEncodeInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is a pointer to a structure extending this structure. + * pname:flags is reserved for future use. + * pname:dstBuffer is the destination video bitstream buffer to write the + encoded bitstream to. + * pname:dstBufferOffset is the starting offset in bytes from the start of + pname:dstBuffer to write the encoded bitstream to. + * pname:dstBufferRange is the maximum bitstream size in bytes that can: be + written to pname:dstBuffer, starting from pname:dstBufferOffset. + * pname:srcPictureResource is the video picture resource to use as the + <>. + * pname:pSetupReferenceSlot is `NULL` or a pointer to a + slink:VkVideoReferenceSlotInfoKHR structure specifying the + <>. + * pname:referenceSlotCount is the number of elements in the + pname:pReferenceSlots array. + * pname:pReferenceSlots is `NULL` or a pointer to an array of + slink:VkVideoReferenceSlotInfoKHR structures describing the DPB slots + and corresponding <> resources to + use in this video encode operation (the set of + <>). + * pname:precedingExternallyEncodedBytes is the number of bytes externally + encoded by the application to the video bitstream and is used to update + the internal state of the implementation's <> algorithm to account for the bitrate budget consumed by these + externally encoded bytes. + +.Valid Usage +**** + * [[VUID-VkVideoEncodeInfoKHR-dstBuffer-08236]] + pname:dstBuffer must: have been created with + ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR set + * [[VUID-VkVideoEncodeInfoKHR-dstBufferOffset-08237]] + pname:dstBufferOffset must: be less than the size of pname:dstBuffer + * [[VUID-VkVideoEncodeInfoKHR-dstBufferRange-08238]] + pname:dstBufferRange must: be less than or equal to the size of + pname:dstBuffer minus pname:dstBufferOffset + * [[VUID-VkVideoEncodeInfoKHR-pSetupReferenceSlot-08239]] + If pname:pSetupReferenceSlot is not `NULL`, then its pname:slotIndex + member must: not be negative + * [[VUID-VkVideoEncodeInfoKHR-pSetupReferenceSlot-08240]] + If pname:pSetupReferenceSlot is not `NULL`, then its + pname:pPictureResource must: not be `NULL` + * [[VUID-VkVideoEncodeInfoKHR-slotIndex-08241]] + The pname:slotIndex member of each element of pname:pReferenceSlots + must: not be negative + * [[VUID-VkVideoEncodeInfoKHR-pPictureResource-08242]] + The pname:pPictureResource member of each element of + pname:pReferenceSlots must: not be `NULL` +**** + +include::{generated}/validity/structs/VkVideoEncodeInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeFlagsKHR',desc='Reserved for future use',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeFlagsKHR.adoc[] + +tlink:VkVideoEncodeFlagsKHR is a bitmask type for setting a mask, but is +currently reserved for future use. +-- + + +[[encode-rate-control]] +== Video Encode Rate Control + +The size of the encoded bitstream data produced by video encode operations +is a function of the following set of constraints: + + * The capabilities of the compression algorithms defined and employed by + the used video compression standard; + * Restrictions imposed by the selected <> + according to the rules defined by the used video compression standard; + * Further restrictions imposed by the <> supported by the implementation for the selected + <>; + * The image data in the <> and + the set of <> (as + these affect the effectiveness of the compression algorithms employed by + the video encode operations); + * The set of codec-specific and codec-independent encoding parameters + provided by the application. + +These also inherently define the set of decoder capabilities required for +reconstructing and processing the picture data in the encoded bitstream. + +[[encode-bitrate]] +Video coding uses _bitrate_ as the quantitative metric associated with +encoded bitstream data size which expresses the rate at which video +bitstream data can: be transferred or processed, measured in number of bits +per second. +This bitrate is both a function of the encoded bitstream data size of the +encoded pictures as well as the _frame rate_ used by the video sequence. + +Rate control algorithms are used by video encode operations to enable +adjusting encoding parameters to achieve a target bitrate, or otherwise +directly or indirectly control the bitrate of the generated video bitstream +data. +These algorithms are usually not defined by the used video compression +standard, although some video compression standards do provide non-normative +guidelines for implementations. + +Accordingly, this specification does not mandate implementations to produce +identical encoded bitstream data outputs in response to video encode +operations, however, it does define a set of codec-independent and +codec-specific parameters that enable the application to control the +behavior of the rate control algorithms supported by the implementation. +Some of these parameters guarantee certain implementation behavior while +others provide guidance for implementations to apply various rate control +heuristics. + +[NOTE] +.Note +==== +Applications need to make sure that they configure rate control parameters +appropriately and that they follow the promises made to the implementation +through parameters providing guidance for the implementation's rate control +algorithms and heuristics in order to be able to get the desired rate +control behavior and to be able to hit the set bitrate targets. +In addition, the behavior of rate control may also differ across +implementations even if the capabilities of the used video profile match +between those implementations. +This may happen due to implementations applying different rate control +algorithms or heuristics internally, and thus even the same set of guidance +parameter values may have different effects on the rate control behavior +across implementations. +==== + + +[[encode-rate-control-modes]] +=== Rate Control Modes + +After a video session is reset to the <>, the default behavior and parameters of video encode rate control +are entirely implementation-dependent and the application cannot: affect the +bitrate or quality parameters of the encoded bitstream data produced by +video encode operations unless the application changes the rate control +configuration of the video session, as described in the +<> section. + +For each supported <>, the implementation may: +expose a set of _rate control modes_ that are available for use by the +application when encoding bitstreams targeting that video profile. +These modes allow using different rate control algorithms that fall into one +of the following two categories: + + 1. Per-operation rate control + 2. Stream-level rate control + +In case of _per-operation rate control_, the bitrate of the generated video +bitstream data is indirectly controlled by quality, size, or other encoding +parameters specified by the application for each individual video encode +operation. + +In case of _stream-level rate control_, the application can: directly +specify target bitrates besides other encoding parameters to control the +behavior of the rate control algorithm used by the implementation across +multiple video encode operations. + +[open,refpage='VkVideoEncodeRateControlModeFlagBitsKHR',desc='Video encode rate control modes',type='enums'] +-- +The rate control modes are defined with the following enums: + +include::{generated}/api/enums/VkVideoEncodeRateControlModeFlagBitsKHR.adoc[] + + * ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR specifies the use of + implementation-specific rate control. + * ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR specifies that + rate control is disabled and the application will specify per-operation + rate control parameters controlling the encoding quality. + In this mode implementations will encode pictures independently of the + output bitrate of prior video encode operations. +ifdef::VK_KHR_video_encode_h264[] + ** When using an <>, + implementations will use the QP value specified in + slink:VkVideoEncodeH264NaluSliceInfoKHR::pname:constantQp to control + the quality of the encoded picture. +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + ** When using an <>, + implementations will use the QP value specified in + slink:VkVideoEncodeH265NaluSliceSegmentInfoKHR::pname:constantQp to + control the quality of the encoded picture. +endif::VK_KHR_video_encode_h265[] + * ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR specifies the use of + constant bitrate (CBR) rate control mode. + In this mode the implementation will attempt to produce the encoded + bitstream at a constant bitrate while conforming to the constraints of + other rate control parameters. + * ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR specifies the use of + variable bitrate (VBR) rate control mode. + In this mode the implementation will produce the encoded bitstream at a + variable bitrate according to the constraints of other rate control + parameters. +-- + +[open,refpage='VkVideoEncodeRateControlModeFlagsKHR',desc='Bitmask of VkVideoEncodeRateControlModeFlagBitsKHR', type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeRateControlModeFlagsKHR.adoc[] + +tname:VkVideoEncodeRateControlModeFlagsKHR is a bitmask type for setting a +mask of zero or more elink:VkVideoEncodeRateControlModeFlagBitsKHR. +-- + + +[[encode-leaky-bucket-model]] +=== Leaky Bucket Model + +Video encoding implementations use the _leaky bucket model_ for stream-level +rate control. +The leaky bucket is a concept referring to the interface between the video +encoder and the consumer (for example, a network connection), where the +video encoder produces encoded bitstream data corresponding to the encoded +pictures and adds them in the leaky bucket while its content are drained by +the consumer. + +Analogously, a similar leaky bucket is considered to exist at the input +interface of a video decoder, into which encoded bitstream data is +continuously added and is subsequently consumed by the video decoder. +It is desirable to avoid overflowing or underflowing this leaky bucked +because: + + * In case of an underflow, the video decoder will be unable to consume + encoded bitstream data in order to decode pictures (and optionally + display them). + * In case of an overflow, the leaky bucket will be unable to accommodate + more encoded bitstream data and such data may: need to be thrown away, + leading to the loss of the corresponding encoded pictures. + +These requirements can: be satisfied by imposing various constraints on the +encoder-side leaky bucket to avoid its overflow or underflow, depending on +the used rate control algorithm and codec parameters. +However, enumerating these constraints is outside the scope of this +specification. + +The term _virtual buffer_ is often used as an alternative to refer to the +leaky bucket. + +This virtual buffer model is defined by the following parameters: + + * The bitrate (`R`) at which the encoded bitstream is expected to be + processed. + * The size (`B`) of the virtual buffer. + * The initial occupancy (`F`) of the virtual buffer. + +In this model the virtual buffer is used to smooth out fluctuations in the +bitrate of the encoded bitstream over time without experiencing buffer +overflow or underflow, as long as the bitrate of the encoded stream does not +diverge from the target bitrate for extended periods of time. + +This buffering may: inherently impose a processing delay, as the goal of the +model is to enable decoders maintain a consistent processing rate of an +encoded bitstream with varying data rate. + +The initial or start-up delay (`D`) is computed as: + + {empty}:: [eq]#`D` = `F` / `R`# + +[NOTE] +.Note +==== +Applications need to configure the virtual buffer with sufficient size to +avoid or minimize buffer overflows and underflows while also keeping it +small enough to meet their latency goals. +==== + + +[[encode-rate-control-layers]] +=== Rate Control Layers + +Some video compression standards and <> allow +associating encoded pictures with specific _video coding layers_. +The name, identification, and semantics associated with such video coding +layers are defined by the corresponding video compression standards. + +Analogously, stream-level rate control can: be configured to use one or more +_rate control layers_: + + * When a single rate control layer is configured, it is applied to all + encoded pictures, regardless of the picture's video coding layer. + In this case the distribution of the available bitrate budget across + video coding layers is implementation-dependent. + * When multiple rate control layers are configured, each rate control + layer is applied to the corresponding video coding layer, i.e. only + across encoded pictures pertaining to the corresponding video coding + layer. + +Individual rate control layers are identified using _layer indices_ between +zero and `N-1`, where `N` is the number of active rate control layers. + +Rate control layers are only applicable when using +<>. + + +[[encode-rate-control-state]] +=== Rate Control State + +Rate control state is maintained by the implementation in the +<> objects and its parameters are specified +using an instance of the sname:VkVideoEncodeRateControlInfoKHR structure. +The complete rate control state of a video session is defined by the +following set of parameters: + + * The values of the members of the slink:VkVideoEncodeRateControlInfoKHR + structure used to configure the rate control state. + * The values of the members of any + slink:VkVideoEncodeRateControlLayerInfoKHR structures specified in + slink:VkVideoEncodeRateControlInfoKHR::pname:pLayers used to configure + the state of individual <>. +ifdef::VK_KHR_video_encode_h264[] + * If the video session was created with an <>: + ** The values of the members of the + slink:VkVideoEncodeH264RateControlInfoKHR structure, if one is + specified in the pname:pNext chain of the + slink:VkVideoEncodeRateControlInfoKHR used to configure the rate + control state. + ** The values of the members of any + slink:VkVideoEncodeH264RateControlLayerInfoKHR structures included in + the pname:pNext chain of a slink:VkVideoEncodeRateControlLayerInfoKHR + structure used to configure the state of a rate control layer. +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * If the video session was created with an <>: + ** The values of the members of the + slink:VkVideoEncodeH265RateControlInfoKHR structure, if one is + specified in the pname:pNext chain of the + slink:VkVideoEncodeRateControlInfoKHR used to configure the rate + control state. + ** The values of the members of any + slink:VkVideoEncodeH265RateControlLayerInfoKHR structures included in + the pname:pNext chain of a slink:VkVideoEncodeRateControlLayerInfoKHR + structure used to configure the state of a rate control layer. +endif::VK_KHR_video_encode_h265[] + +[[encode-rate-control-state-matching]] +Two rate control states match if all the parameters listed above match +between them. + +[open,refpage='VkVideoEncodeRateControlInfoKHR',desc='Structure to set encode stream rate control parameters',type='structs'] +-- +The sname:VkVideoEncodeRateControlInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeRateControlInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:flags is reserved for future use. + * pname:rateControlMode is a elink:VkVideoEncodeRateControlModeFlagBitsKHR + value specifying the <>. + * pname:layerCount specifies the number of <> to use. + * pname:pLayers is a pointer to an array of pname:layerCount + slink:VkVideoEncodeRateControlLayerInfoKHR structures, each specifying + the rate control configuration of the corresponding rate control layer. + * pname:virtualBufferSizeInMs is the size in milliseconds of the virtual + buffer used by the implementation's rate control algorithm for the + <>, with respect to the + average bitrate of the stream calculated by summing the values of the + pname:averageBitrate members of the elements of the pname:pLayers array. + * pname:initialVirtualBufferSizeInMs is the initial occupancy in + milliseconds of the virtual buffer used by the implementation's rate + control algorithm for the <>. + +If pname:layerCount is zero then the values of pname:virtualBufferSizeInMs +and pname:initialVirtualBufferSizeInMs are ignored. + +This structure can: be specified in the following places: + + * In the pname:pNext chain of slink:VkVideoBeginCodingInfoKHR to specify + the current rate control state expected to be configured when beginning + a <>. + * In the pname:pNext chain of slink:VkVideoCodingControlInfoKHR to change + the rate control configuration of the bound video session. + +Including this structure in the pname:pNext chain of +slink:VkVideoCodingControlInfoKHR and including +ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR in +slink:VkVideoCodingControlInfoKHR::pname:flags enables updating the rate +control configuration of the bound video session. +This replaces the entire rate control configuration of the bound video +session and may: reset the state of all enabled rate control layers to an +initial state according to the codec-specific rate control semantics defined +in the corresponding sections listed below. + +When pname:layerCount is greater than one, multiple +<> are configured, and each +rate control layer is applied to the corresponding video coding layer +identified by the index of the corresponding element of pname:pLayer. + +ifdef::VK_KHR_video_encode_h264[] + * If the video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then this index + specifies the H.264 temporal layer ID of the video coding layer the rate + control layer is applied to. +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * If the video session was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then this index + specifies the H.265 temporal ID of the video coding layer the rate + control layer is applied to. +endif::VK_KHR_video_encode_h265[] + +Additional structures providing codec-specific rate control parameters can: +be included in the pname:pNext chain of sname:VkVideoCodingControlInfoKHR +depending on the <> the bound video session +was created. +For further details see: + + * <> +ifdef::VK_KHR_video_encode_h264[] + * <> +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * <> +endif::VK_KHR_video_encode_h265[] + +The new rate control configuration takes effect when the corresponding +flink:vkCmdControlVideoCodingKHR is executed on the device, and only impacts +video encode operations that follow in execution order. + +.Valid Usage +**** + * [[VUID-VkVideoEncodeRateControlInfoKHR-rateControlMode-08248]] + If pname:rateControlMode is + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR or + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, then + pname:layerCount must: be `0` + * [[VUID-VkVideoEncodeRateControlInfoKHR-rateControlMode-08275]] + If pname:rateControlMode is + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR or + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR, then + pname:layerCount must: be greater than `0` + * [[VUID-VkVideoEncodeRateControlInfoKHR-rateControlMode-08244]] + If pname:rateControlMode is not + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR, then it must: + specify one of the bits included in + slink:VkVideoEncodeCapabilitiesKHR::pname:rateControlModes, as returned + by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile + * [[VUID-VkVideoEncodeRateControlInfoKHR-layerCount-08245]] + pname:layerCount member must: be less than or equal to + slink:VkVideoEncodeCapabilitiesKHR::pname:maxRateControlLayers, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used + video profile + * [[VUID-VkVideoEncodeRateControlInfoKHR-pLayers-08276]] + For each element of pname:pLayers, its pname:averageBitrate member must: + be between `1` and slink:VkVideoEncodeCapabilitiesKHR::pname:maxBitrate, + as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the + used video profile + * [[VUID-VkVideoEncodeRateControlInfoKHR-pLayers-08277]] + For each element of pname:pLayers, its pname:maxBitrate member must: be + between `1` and slink:VkVideoEncodeCapabilitiesKHR::pname:maxBitrate, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used + video profile + * [[VUID-VkVideoEncodeRateControlInfoKHR-rateControlMode-08356]] + If pname:rateControlMode is + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR, then for each + element of pname:pLayers, its pname:averageBitrate member must: equal + its pname:maxBitrate member + * [[VUID-VkVideoEncodeRateControlInfoKHR-rateControlMode-08278]] + If pname:rateControlMode is + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR, then for each + element of pname:pLayers, its pname:averageBitrate member must: be less + than or equal to its pname:maxBitrate member + * [[VUID-VkVideoEncodeRateControlInfoKHR-layerCount-08357]] + If pname:layerCount is not zero, then pname:virtualBufferSizeInMs must: + be greater than zero + * [[VUID-VkVideoEncodeRateControlInfoKHR-layerCount-08358]] + If pname:layerCount is not zero, then pname:initialVirtualBufferSizeInMs + must: be less than pname:virtualBufferSizeInMs +ifdef::VK_KHR_video_encode_h264[] + * [[VUID-VkVideoEncodeRateControlInfoKHR-videoCodecOperation-07022]] + If the pname:videoCodecOperation of the used video profile is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, the pname:pNext + chain this structure is included in also includes an instance of the + slink:VkVideoEncodeH264RateControlInfoKHR structure, and + pname:layerCount is greater than `1`, then pname:layerCount must: equal + slink:VkVideoEncodeH264RateControlInfoKHR::pname:temporalLayerCount +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * [[VUID-VkVideoEncodeRateControlInfoKHR-videoCodecOperation-07025]] + If the pname:videoCodecOperation of the used video profile is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, the pname:pNext + chain this structure is included in also includes an instance of the + slink:VkVideoEncodeH265RateControlInfoKHR structure, and + pname:layerCount is greater than `1`, then pname:layerCount must: equal + slink:VkVideoEncodeH265RateControlInfoKHR::pname:subLayerCount +endif::VK_KHR_video_encode_h265[] +**** + +include::{generated}/validity/structs/VkVideoEncodeRateControlInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeRateControlFlagsKHR',desc='Reserved for future use',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeRateControlFlagsKHR.adoc[] + +tname:VkVideoEncodeRateControlFlagsKHR is a bitmask type for setting a mask, +but currently reserved for future use. +-- + + +==== Rate Control Layer State + +The configuration of individual rate control layers is specified using an +instance of the sname:VkVideoEncodeRateControlLayerInfoKHR structure. + +[open,refpage='VkVideoEncodeRateControlLayerInfoKHR',desc='Structure to set encode per-layer rate control parameters',type='structs'] +-- +The sname:VkVideoEncodeRateControlLayerInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeRateControlLayerInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is a pointer to a structure extending this structure. + * pname:averageBitrate is the average <> to be + targeted by the implementation's rate control algorithm. + * pname:maxBitrate is the peak <> to be targeted + by the implementation's rate control algorithm. + * pname:frameRateNumerator is the numerator of the frame rate assumed by + the implementation's rate control algorithm. + * pname:frameRateDenominator is the denominator of the frame rate assumed + by the implementation's rate control algorithm. + +[NOTE] +.Note +==== +The ability of the implementation's rate control algorithm to be able to +match the requested average and/or peak bitrates may: be limited by the set +of other codec-independent and codec-specific rate control parameters +specified by the application, the input content, as well as the application +conforming to the rate control guidance provided to the implementation, as +described <>. +==== + +Additional structures providing codec-specific rate control parameters can: +be included in the pname:pNext chain of +sname:VkVideoEncodeRateControlLayerInfoKHR depending on the +<> the bound video session was created with. +For further details see: + + * <> +ifdef::VK_KHR_video_encode_h264[] + * <> +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * <> +endif::VK_KHR_video_encode_h265[] + +.Valid Usage +**** + * [[VUID-VkVideoEncodeRateControlLayerInfoKHR-frameRateNumerator-08350]] + pname:frameRateNumerator must: be greater than zero + * [[VUID-VkVideoEncodeRateControlLayerInfoKHR-frameRateDenominator-08351]] + pname:frameRateDenominator must: be greater than zero +**** + +include::{generated}/validity/structs/VkVideoEncodeRateControlLayerInfoKHR.adoc[] +-- diff --git a/chapters/video_decode_h264_extensions.adoc b/chapters/video/h264_decode.adoc similarity index 87% rename from chapters/video_decode_h264_extensions.adoc rename to chapters/video/h264_decode.adoc index b80b1ce6d..730fd6980 100644 --- a/chapters/video_decode_h264_extensions.adoc +++ b/chapters/video/h264_decode.adoc @@ -46,6 +46,9 @@ section 8 of the <> as follows: reconstructed picture>> is accessed as defined in the <> section. + * The decision on <> is made + according to the parameters specified in the + <>. If the parameters and the bitstream adhere to the syntactic and semantic requirements defined in the corresponding sections of the <_` identifies H.264 level `.` as defined in section A.3 of the <_` identifying the H.264 level - `.` as defined in section A.3 of the <>; - * if code:flags.seq_scaling_matrix_present_flag is set, then the - code:StdVideoH264ScalingLists structure pointed to by code:pScalingLists - is interpreted as follows: - ** code:scaling_list_present_mask is a bitmask where bit index [eq]#i# - corresponds to `seq_scaling_list_present_flag[i]` as defined in section - 7.4.2.1 of the <>; - ** code:use_default_scaling_matrix_mask is a bitmask where bit index - [eq]#i# corresponds to `UseDefaultScalingMatrix4x4Flag[i]`, when [eq]#i - < 6#, or corresponds to `UseDefaultScalingMatrix8x8Flag[i-6]`, - otherwise, as defined in section 7.3.2.1 of the <>; - ** code:ScalingList4x4 and code:ScalingList8x8 correspond to the - identically named syntax elements defined in section 7.3.2.1 of the - <>; - * if code:flags.vui_parameters_present_flag is set, then - code:pSequenceParameterSetVui is a pointer to a - code:StdVideoH264SequenceParameterSetVui structure that is interpreted - as follows: - ** code:reserved1 is used only for padding purposes and is otherwise - ignored; - ** if code:flags.nal_hrd_parameters_present_flag or - code:flags.vcl_hrd_parameters_present_flag is set, then the - code:StdVideoH264HrdParameters structure pointed to by - code:pHrdParameters is interpreted as follows: - *** code:reserved1 is used only for padding purposes and is otherwise - ignored; - *** all other members of code:StdVideoH264HrdParameters are interpreted as - defined in section E.2.2 of the <>; - ** all other members of code:StdVideoH264SequenceParameterSetVui are - interpreted as defined in section E.2.1 of the <>; - * all other members of code:StdVideoH264SequenceParameterSet are - interpreted as defined in section 7.4.2.1 of the <>. - -[[decode-h264-pps]] -H.264 Picture Parameter Sets (PPS):: - -Represented by code:StdVideoH264PictureParameterSet structures and -interpreted as follows: - - * the pair constructed from code:seq_parameter_set_id and - code:pic_parameter_set_id is used as the key of the PPS entry; - * if code:flags.pic_scaling_matrix_present_flag is set, then the - code:StdVideoH264ScalingLists structure pointed to by code:pScalingLists - is interpreted as follows: - ** code:scaling_list_present_mask is a bitmask where bit index [eq]#i# - corresponds to `pic_scaling_list_present_flag[i]` as defined in section - 7.4.2.2 of the <>; - ** code:use_default_scaling_matrix_mask is a bitmask where bit index - [eq]#i# corresponds to `UseDefaultScalingMatrix4x4Flag[i]`, when [eq]#i - < 6#, or corresponds to `UseDefaultScalingMatrix8x8Flag[i-6]`, - otherwise, as defined in section 7.3.2.2 of the <>; - ** code:ScalingList4x4 and code:ScalingList8x8 correspond to the - identically named syntax elements defined in section 7.3.2.2 of the - <>; - * all other members of code:StdVideoH264PictureParameterSet are - interpreted as defined in section 7.4.2.2 of the <>. +:operationType: decode +include::{chapters}/video/h264_parameter_sets.adoc[] [open,refpage='VkVideoDecodeH264SessionParametersCreateInfoKHR',desc='Structure specifies H.264 decoder parameter set information',type='structs'] -- @@ -497,6 +428,19 @@ by pname:pStdPictureInfo are interpreted as follows: * all other members are interpreted as defined in section 7.4.3 of the <>. +[[decode-h264-ref-pic-setup]] +Reference picture setup is controlled by the value of +code:StdVideoDecodeH264PictureInfo::pname:flags.is_reference. +If it is set and a <> is specified, then the latter is used as the target of picture +reconstruction to <> the <> +specified in pname:pDecodeInfo->pSetupReferenceSlot->slotIndex. +If code:StdVideoDecodeH264PictureInfo::pname:flags.is_reference is not set, +but a <> is +specified, then the corresponding picture reference associated with the +<> is invalidated, as described in the +<> section. + Active Parameter Sets:: The members of the code:StdVideoDecodeH264PictureInfo structure pointed to @@ -612,7 +556,8 @@ is defined as follows: * The image subregion used is determined according to the <> section. - * The reconstructed picture is used to <> the + * If <> is requested, then + the reconstructed picture is used to <> the <> with the index specified in slink:VkVideoDecodeInfoKHR::pname:pSetupReferenceSlot->slotIndex. * The reconstructed picture is associated with the @@ -657,3 +602,34 @@ slink:VkQueueFamilyVideoPropertiesKHR::pname:videoCodecOperations. | Video Std Header Name | Version | `vulkan_video_codec_h264std_decode` | 1.0.0 |==== + +ifdef::VK_KHR_video_maintenance1[] +.Required Video Capabilities +[width="100%",cols="<35,<14,<11",options="header"] +|==== +| Video Capability | Requirement | Requirement Type^1^ +| **slink:VkVideoCapabilitiesKHR** | | +| pname:flags | - | min +| pname:minBitstreamBufferOffsetAlignment | 4096 | max +| pname:minBitstreamBufferSizeAlignment | 4096 | max +| pname:pictureAccessGranularity | (64,64) | max +| pname:minCodedExtent | - | max +| pname:maxCodedExtent | - | min +| pname:maxDpbSlots | 0 | min +| pname:maxActiveReferencePictures | 0 | min +| **slink:VkVideoDecodeCapabilitiesKHR** | | +| pname:flags | ename:VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR or + ename:VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR | min +| **slink:VkVideoDecodeH264CapabilitiesKHR** | | +| pname:maxLevelIdc | code:STD_VIDEO_H264_LEVEL_IDC_1_0 | min +| pname:fieldOffsetGranularity | (0,0) except for profiles using ename:VK_VIDEO_DECODE_H264_PICTURE_LAYOUT_INTERLACED_SEPARATE_PLANES_BIT_KHR | implementation-dependent +|==== + +1:: + The *Requirement Type* column specifies the requirement is either the + minimum value all implementations must: support, the maximum value all + implementations must: support, or the exact value all implementations + must: support. + For bitmasks a minimum value is the least bits all implementations must: + set, but they may: have additional bits set beyond this minimum. +endif::VK_KHR_video_maintenance1[] diff --git a/chapters/video/h264_encode.adoc b/chapters/video/h264_encode.adoc new file mode 100644 index 000000000..6b8a15d40 --- /dev/null +++ b/chapters/video/h264_encode.adoc @@ -0,0 +1,1598 @@ +// Copyright 2018-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +[[encode-h264]] +== H.264 Encode Operations + +Video encode operations using an <> can: be used to encode elementary video stream sequences compliant +to the <>. + +[NOTE] +.Note +==== +Refer to the <> for information on how the Khronos +Intellectual Property Rights Policy relates to normative references to +external materials not created by Khronos. +==== + +This process is performed according to the <> with the codec-specific semantics defined in +section 8 of the <> as follows: + + * Syntax elements, derived values, and other parameters are applied from + the following structures: + ** The code:StdVideoH264SequenceParameterSet structure corresponding to + the <> specifying the + <>. + ** The code:StdVideoH264PictureParameterSet structure corresponding to the + <> specifying the <>. + ** The code:StdVideoEncodeH264PictureInfo structure specifying the + <>. + ** The code:StdVideoEncodeH264SliceHeader structures specifying the + <> for + each encoded H.264 slice. + ** The code:StdVideoEncodeH264ReferenceInfo structures specifying the + <> + corresponding to the optional <> and any <>. + * The encoded bitstream data is written to the destination video bitstream + buffer range as defined in the + <> section. + * Picture data in the <> + corresponding to the used <>, <>, and + optional <> is accessed as + defined in the <> section. + * The decision on <> is made + according to the parameters specified in the + <>. + +If the parameters adhere to the syntactic and semantic requirements defined +in the corresponding sections of the <>, as described above, and the <> +associated with the <> +all refer to <>, then the video +encode operation will complete successfully. +Otherwise, the video encode operation may: complete +<>. + + +[[encode-h264-overrides]] +=== H.264 Encode Parameter Overrides + +Implementations may: override, unless otherwise specified, any of the H.264 +encode parameters specified in the following Video Std structures: + + * code:StdVideoH264SequenceParameterSet + * code:StdVideoH264PictureParameterSet + * code:StdVideoEncodeH264PictureInfo + * code:StdVideoEncodeH264SliceHeader + * code:StdVideoEncodeH264ReferenceInfo + +All such H.264 encode parameter overrides must: fulfill the conditions +defined in the <> +section. + +In addition, implementations must: not override any of the following H.264 +encode parameters: + + * code:StdVideoEncodeH264PictureInfo::code:primary_pic_type + * code:StdVideoEncodeH264SliceHeader::code:slice_type + +In case of H.264 encode parameters stored in +<> objects, +applications need to use the flink:vkGetEncodedVideoSessionParametersKHR +command to determine whether any implementation overrides happened. +If the query indicates that implementation overrides were applied, then the +application needs to retrieve and use the encoded H.264 parameter sets in +the bitstream in order to be able to produce a compliant H.264 video +bitstream using the H.264 encode parameters stored in the video session +parameters object. + +In case of any H.264 encode parameters stored in the encoded bitstream +produced by video encode operations, if the implementation supports the +ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR +<> flag, the +application can: use such queries to retrieve feedback about whether any +implementation overrides have been applied to those H.264 encode parameters. + + +[[encode-h264-bitstream-data-access]] +=== H.264 Encode Bitstream Data Access + +Each video encode operation writes one or more VCL NAL units comprising of +slice headers and data of the encoded picture, in the format defined in +sections 7.3.3 and 7.3.4, according to the semantics defined in sections +7.4.3 and 7.4.4 of the <>, +respectively. +The number of VCL NAL units written is specified by +slink:VkVideoEncodeH264PictureInfoKHR::pname:naluSliceEntryCount. + +In addition, if +slink:VkVideoEncodeH264PictureInfoKHR::pname:generatePrefixNalu is set to +ename:VK_TRUE for the video encode operation, then an additional prefix NAL +unit is written before each VCL NAL unit corresponding to individual slices +in the format defined in section 7.3.2.12, according to the semantics +defined in section 7.4.2.12 of the <>, +respectively. + + +[[encode-h264-picture-data-access]] +=== H.264 Encode Picture Data Access + +Accesses to image data within a video picture resource happen at the +granularity indicated by +slink:VkVideoCapabilitiesKHR::pname:pictureAccessGranularity, as returned by +flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used <>. +Accordingly, the complete image subregion of a <>, <>, or +<> accessed by video coding +operations using an <> is defined +as the set of texels within the coordinate range: + + {empty}:: [eq]#([0,pname:endX),[0,pname:endY))# + +Where: + + * [eq]#pname:endX# equals [eq]#pname:codedExtent.width# rounded up to the + nearest integer multiple of pname:pictureAccessGranularity.width and + clamped to the width of the image subresource + <> to by the corresponding + slink:VkVideoPictureResourceInfoKHR structure; + * [eq]#endY# equals [eq]#pname:codedExtent.height# rounded up to the + nearest integer multiple of pname:pictureAccessGranularity.height and + clamped to the height of the image subresource + <> to by the corresponding + slink:VkVideoPictureResourceInfoKHR structure; + +Where pname:codedExtent is the member of the +slink:VkVideoPictureResourceInfoKHR structure corresponding to the picture. + +In case of video encode operations using an <>, any access to a picture at the coordinates +[eq]#(pname:x,pname:y)#, as defined by the <>, is an access to the image subresource +<> to by the corresponding +slink:VkVideoPictureResourceInfoKHR structure at the texel coordinates +[eq]#(pname:x,pname:y)#. + +Implementations may: choose not to access some or all texels within +particular <> available to a video +encode operation (e.g. due to <> restricting the effective set of used reference pictures, or if +the encoding algorithm chooses not to use certain subregions of the +reference picture data for sample prediction). + + +[[encode-h264-frame-picture-slice]] +=== H.264 Frame, Picture, and Slice + +H.264 pictures are partitioned into slices, as defined in section 6.3 of the +<>. + +Video encode operations using an <> can: encode slices of different types, as defined in section 7.4.3 +of the <>, by specifying the +corresponding enumeration constant value in +code:StdVideoEncodeH264SliceHeader::code:slice_type in the +<> from the +Video Std enumeration type code:StdVideoH264SliceType: + + * [[encode-h264-p-slice]] code:STD_VIDEO_H264_SLICE_TYPE_P indicates that + the slice is a _P slice_ as defined in section 3.109 of the + <>. + * [[encode-h264-b-slice]] code:STD_VIDEO_H264_SLICE_TYPE_B indicates that + the slice is a _B slice_ as defined in section 3.9 of the + <>. + * [[encode-h264-i-slice]] code:STD_VIDEO_H264_SLICE_TYPE_I indicates that + the slice is an _I slice_ as defined in section 3.66 of the + <>. + +Pictures constructed from such slices can: be of different types, as defined +in section 7.4.2.4 of the <>. +Video encode operations using an <> can: encode pictures of a specific type by specifying the +corresponding enumeration constant value in +code:StdVideoEncodeH264PictureInfo::code:primary_pic_type in the +<> from the Video Std +enumeration type code:StdVideoH264PictureType: + + * [[encode-h264-p-pic]] code:STD_VIDEO_H264_PICTURE_TYPE_P indicates that + the picture is a _P picture_. + A frame consisting of a P picture is also referred to as a _P frame_. + * [[encode-h264-b-pic]] code:STD_VIDEO_H264_PICTURE_TYPE_B indicates that + the picture is a _B picture_. + A frame consisting of a B picture is also referred to as a _B frame_. + * [[encode-h264-i-pic]] code:STD_VIDEO_H264_PICTURE_TYPE_I indicates that + the picture is an _I picture_. + A frame consisting of an I picture is also referred to as an _I frame_. + * [[encode-h264-idr-pic]] code:STD_VIDEO_H264_PICTURE_TYPE_IDR indicates + that the picture is a special type of I picture called an _IDR picture_ + as defined in section 3.69 of the <>. + A frame consisting of an IDR picture is also referred to as an _IDR + frame_. + + +[[encode-h264-profile]] +=== H.264 Encode Profile + +[open,refpage='VkVideoEncodeH264ProfileInfoKHR',desc='Structure specifying H.264 encode-specific video profile parameters',type='structs'] +-- +A video profile supporting H.264 video encode operations is specified by +setting slink:VkVideoProfileInfoKHR::pname:videoCodecOperation to +ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and adding a +sname:VkVideoEncodeH264ProfileInfoKHR structure to the +slink:VkVideoProfileInfoKHR::pname:pNext chain. + +The sname:VkVideoEncodeH264ProfileInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264ProfileInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying 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, as defined in section A.2 of the + <>. + +include::{generated}/validity/structs/VkVideoEncodeH264ProfileInfoKHR.adoc[] +-- + + +=== H.264 Encode Capabilities + +[open,refpage='VkVideoEncodeH264CapabilitiesKHR',desc='Structure describing H.264 encode capabilities',type='structs'] +-- +When calling flink:vkGetPhysicalDeviceVideoCapabilitiesKHR to query the +capabilities for an <>, the +slink:VkVideoCapabilitiesKHR::pname:pNext chain must: include a +sname:VkVideoEncodeH264CapabilitiesKHR structure that will be filled with +the profile-specific capabilities. + +The sname:VkVideoEncodeH264CapabilitiesKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264CapabilitiesKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:flags is a bitmask of elink:VkVideoEncodeH264CapabilityFlagBitsKHR + indicating supported H.264 encoding capabilities. + * pname:maxLevelIdc is a code:StdVideoH264LevelIdc value indicating the + maximum H.264 level supported by the profile, where enum constant + `STD_VIDEO_H264_LEVEL_IDC__` identifies H.264 level + `.` as defined in section A.3 of the <>. + * pname:maxSliceCount indicates the maximum number of slices that can: be + encoded for a single picture. + Further restrictions may: apply to the number of slices that can: be + encoded for a single picture depending on other capabilities and + codec-specific rules. + * pname:maxPPictureL0ReferenceCount indicates the maximum number of + reference pictures the implementation supports in the reference list L0 + for <>. ++ +[NOTE] +.Note +==== +As implementations may: <> the reference lists, +pname:maxPPictureL0ReferenceCount does not limit the number of elements that +the application can: specify in the L0 reference list for P pictures. +However, if pname:maxPPictureL0ReferenceCount is zero, then the use of P +pictures is not allowed. +==== + * pname:maxBPictureL0ReferenceCount indicates the maximum number of + reference pictures the implementation supports in the reference list L0 + for <>. + * pname:maxL1ReferenceCount indicates the maximum number of reference + pictures the implementation supports in the reference list L1 if + encoding of <> is supported. ++ +[NOTE] +.Note +==== +As implementations may: <> the reference lists, +pname:maxBPictureL0ReferenceCount and pname:maxL1ReferenceCount does not +limit the number of elements that the application can: specify in the L0 and +L1 reference lists for B pictures. +However, if pname:maxBPictureL0ReferenceCount and pname:maxL1ReferenceCount +are both zero, then the use of B pictures is not allowed. +==== + * pname:maxTemporalLayerCount indicates the maximum number of H.264 + temporal layers supported by the implementation. + * pname:expectDyadicTemporalLayerPattern indicates that the + implementation's rate control algorithms expect the application to use a + <> when + encoding multiple temporal layers. + * pname:minQp indicates the minimum QP value supported. + * pname:maxQp indicates the maximum QP value supported. + * pname:prefersGopRemainingFrames indicates that the implementation's rate + control algorithm prefers the application to specify the number of + frames of each type <> in + the current <> when beginning a + <>. + * pname:requiresGopRemainingFrames indicates that the implementation's + rate control algorithm requires the application to specify the number of + frames of each type <> in + the current <> when beginning a + <>. + * pname:stdSyntaxFlags is a bitmask of + elink:VkVideoEncodeH264StdFlagBitsKHR indicating capabilities related to + H.264 syntax elements. + +include::{generated}/validity/structs/VkVideoEncodeH264CapabilitiesKHR.adoc[] +-- + + +[open,refpage='VkVideoEncodeH264CapabilityFlagBitsKHR',desc='H.264 encode capability flags',type='enums'] +-- +Bits which may: be set in +slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags, indicating the H.264 +encoding capabilities supported, are: + +include::{generated}/api/enums/VkVideoEncodeH264CapabilityFlagBitsKHR.adoc[] + + * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_HRD_COMPLIANCE_BIT_KHR indicates + whether the implementation may: be able to generate HRD compliant + bitstreams if any of the code:nal_hrd_parameters_present_flag or + code:vcl_hrd_parameters_present_flag members of + code:StdVideoH264SpsVuiFlags are set to `1` in the + <>. + * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_KHR + indicates that if code:StdVideoH264PpsFlags::code:weighted_pred_flag is + set to `1` or + code:StdVideoH264PictureParameterSet::code:weighted_bipred_idc is set to + code:STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICIT in the + <> when encoding a + <> or <>, + respectively, then the implementation is able to internally decide + syntax for code:pred_weight_table, as defined in section 7.4.3.2 of the + <>, and the application is not + required: to provide a weight table in the + <>. + * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_ROW_UNALIGNED_SLICE_BIT_KHR + indicates that each slice in a frame with multiple slices may begin or + finish at any offset in a macroblock row. + If not supported, all slices in the frame must: begin at the start of a + macroblock row (and hence each slice must: finish at the end of a + macroblock row). + * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_KHR + indicates that when a frame is encoded with multiple slices, the + implementation allows encoding each slice with a different + code:StdVideoEncodeH264SliceHeader::code:slice_type specified in the + <>. + If not supported, all slices of the frame must: be encoded with the same + code:slice_type which corresponds to the picture type of the frame. + * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_KHR + indicates support for using a <> as L0 + reference, as specified in + code:StdVideoEncodeH264ReferenceListsInfo::code:RefPicList0 in the + <>. + * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_KHR + indicates support for using a <> as L1 + reference, as specified in + code:StdVideoEncodeH264ReferenceListsInfo::code:RefPicList1 in the + <>. + * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHR + indicates support for specifying different QP values in the members of + slink:VkVideoEncodeH264QpKHR. + * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_PER_SLICE_CONSTANT_QP_BIT_KHR + indicates support for specifying different constant QP values for each + slice. + * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_GENERATE_PREFIX_NALU_BIT_KHR + indicates support for generating prefix NAL units by setting + slink:VkVideoEncodeH264PictureInfoKHR::pname:generatePrefixNalu to + ename:VK_TRUE. +-- + +[open,refpage='VkVideoEncodeH264CapabilityFlagsKHR',desc='Bitmask of VkVideoEncodeH264CapabilityFlagBitsKHR',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeH264CapabilityFlagsKHR.adoc[] + +tname:VkVideoEncodeH264CapabilityFlagsKHR is a bitmask type for setting a +mask of zero or more elink:VkVideoEncodeH264CapabilityFlagBitsKHR. +-- + +[open,refpage='VkVideoEncodeH264StdFlagBitsKHR',desc='Video encode H.264 syntax capability flags',type='enums'] +-- +Bits which may: be set in +slink:VkVideoEncodeH264CapabilitiesKHR::pname:stdSyntaxFlags, indicating the +capabilities related to the H.264 syntax elements, are: + +include::{generated}/api/enums/VkVideoEncodeH264StdFlagBitsKHR.adoc[] + + * ename:VK_VIDEO_ENCODE_H264_STD_SEPARATE_COLOR_PLANE_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH264SpsFlags::code:separate_colour_plane_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H264_STD_QPPRIME_Y_ZERO_TRANSFORM_BYPASS_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH264SpsFlags::code:qpprime_y_zero_transform_bypass_flag in + the <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H264_STD_SCALING_MATRIX_PRESENT_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided values for + code:StdVideoH264SpsFlags::code:seq_scaling_matrix_present_flag in the + <> and + code:StdVideoH264PpsFlags::code:pic_scaling_matrix_present_flag in the + <> when any of those values are `1`. + * ename:VK_VIDEO_ENCODE_H264_STD_CHROMA_QP_INDEX_OFFSET_BIT_KHR indicates + whether the implementation supports using the the application-provided + value for + code:StdVideoH264PictureParameterSet::code:chroma_qp_index_offset in the + <> when that value is non-zero. + * ename:VK_VIDEO_ENCODE_H264_STD_SECOND_CHROMA_QP_INDEX_OFFSET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH264PictureParameterSet::code:second_chroma_qp_index_offset + in the <> when that value is non-zero. + * ename:VK_VIDEO_ENCODE_H264_STD_PIC_INIT_QP_MINUS26_BIT_KHR indicates + whether the implementation supports using the application-provided value + for code:StdVideoH264PictureParameterSet::code:pic_init_qp_minus26 in + the <> when that value is non-zero. + * ename:VK_VIDEO_ENCODE_H264_STD_WEIGHTED_PRED_FLAG_SET_BIT_KHR indicates + whether the implementation supports using the application-provided value + for code:StdVideoH264PpsFlags::code:weighted_pred_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H264_STD_WEIGHTED_BIPRED_IDC_EXPLICIT_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH264PictureParameterSet::code:weighted_bipred_idc in the + <> when that value is + code:STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICIT. + * ename:VK_VIDEO_ENCODE_H264_STD_WEIGHTED_BIPRED_IDC_IMPLICIT_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH264PictureParameterSet::code:weighted_bipred_idc in the + <> when that value is + code:STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_IMPLICIT. + * ename:VK_VIDEO_ENCODE_H264_STD_TRANSFORM_8X8_MODE_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH264PpsFlags::code:transform_8x8_mode_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H264_STD_DIRECT_SPATIAL_MV_PRED_FLAG_UNSET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoEncodeH264SliceHeaderFlags::code:direct_spatial_mv_pred_flag + in the <> + when that value is `0`. + * ename:VK_VIDEO_ENCODE_H264_STD_ENTROPY_CODING_MODE_FLAG_UNSET_BIT_KHR + indicates whether the implementation supports CAVLC entropy coding, as + defined in section 9.2 of the <>, + and thus supports using the application-provided value for + code:StdVideoH264PpsFlags::code:entropy_coding_mode_flag in the + <> when that value is `0`. + * ename:VK_VIDEO_ENCODE_H264_STD_ENTROPY_CODING_MODE_FLAG_SET_BIT_KHR + indicates whether the implementation supports CABAC entropy coding, as + defined in section 9.3 of the <>, + and thus supports using the application-provided value for + code:StdVideoH264PpsFlags::code:entropy_coding_mode_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H264_STD_DIRECT_8X8_INFERENCE_FLAG_UNSET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH264SpsFlags::code:direct_8x8_inference_flag in the + <> when that value is `0`. + * ename:VK_VIDEO_ENCODE_H264_STD_CONSTRAINED_INTRA_PRED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH264PpsFlags::code:constrained_intra_pred_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_DISABLED_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoEncodeH264SliceHeader::code:disable_deblocking_filter_idc + in the <> + when that value is + code:STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_DISABLED. + * ename:VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_ENABLED_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoEncodeH264SliceHeader::code:disable_deblocking_filter_idc + in the <> + when that value is + code:STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_ENABLED. + * ename:VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_PARTIAL_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoEncodeH264SliceHeader::code:disable_deblocking_filter_idc + in the <> + when that value is + code:STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_PARTIAL. + * ename:VK_VIDEO_ENCODE_H264_STD_SLICE_QP_DELTA_BIT_KHR indicates whether + the implementation supports using the application-provided value for + code:StdVideoEncodeH264SliceHeader::code:slice_qp_delta in the + <> when + that value is identical across the slices of the encoded frame. + * ename:VK_VIDEO_ENCODE_H264_STD_DIFFERENT_SLICE_QP_DELTA_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoEncodeH264SliceHeader::code:slice_qp_delta in the + <> when + that value is different across the slices of the encoded frame. + +These capability flags provide information to the application about specific +H.264 syntax element values that the implementation supports without having +to <> them and do not otherwise restrict the +values that the application can: specify for any of the mentioned H.264 +syntax elements. +-- + +[open,refpage='VkVideoEncodeH264StdFlagsKHR',desc='Bitmask of VkVideoEncodeH264StdFlagBitsKHR',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeH264StdFlagsKHR.adoc[] + +tname:VkVideoEncodeH264StdFlagsKHR is a bitmask type for setting a mask of +zero or more elink:VkVideoEncodeH264StdFlagBitsKHR. +-- + + +=== H.264 Encode Quality Level Properties + +[open,refpage='VkVideoEncodeH264QualityLevelPropertiesKHR',desc='Structure describing the H.264 encode quality level properties',type='structs'] +-- +When calling flink:vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR +with pname:pVideoProfile->videoCodecOperation specified as +ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, the +slink:VkVideoEncodeH264QualityLevelPropertiesKHR structure must: be included +in the pname:pNext chain of the slink:VkVideoEncodeQualityLevelPropertiesKHR +structure to retrieve additional video encode quality level properties +specific to H.264 encoding. + +The slink:VkVideoEncodeH264QualityLevelPropertiesKHR structure is defined +as: + +include::{generated}/api/structs/VkVideoEncodeH264QualityLevelPropertiesKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:preferredRateControlFlags is a bitmask of + elink:VkVideoEncodeH264RateControlFlagBitsKHR values indicating the + preferred flags to use for + slink:VkVideoEncodeH264RateControlInfoKHR::pname:flags. + * pname:preferredGopFrameCount indicates the preferred value to use for + slink:VkVideoEncodeH264RateControlInfoKHR::pname:gopFrameCount. + * pname:preferredIdrPeriod indicates the preferred value to use for + slink:VkVideoEncodeH264RateControlInfoKHR::pname:idrPeriod. + * pname:preferredConsecutiveBFrameCount indicates the preferred value to + use for + slink:VkVideoEncodeH264RateControlInfoKHR::pname:consecutiveBFrameCount. + * pname:preferredTemporalLayerCount indicates the preferred value to use + for slink:VkVideoEncodeH264RateControlInfoKHR::pname:temporalLayerCount. + * pname:preferredConstantQp indicates the preferred values to use for + slink:VkVideoEncodeH264NaluSliceInfoKHR::pname:constantQp for each + picture type when using <> + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. + * pname:preferredMaxL0ReferenceCount indicates the preferred maximum + number of reference pictures to use in the reference list L0. + * pname:preferredMaxL1ReferenceCount indicates the preferred maximum + number of reference pictures to use in the reference list L1. + * pname:preferredStdEntropyCodingModeFlag indicates the preferred value to + use for code:entropy_coding_mode_flag in code:StdVideoH264PpsFlags. + +include::{generated}/validity/structs/VkVideoEncodeH264QualityLevelPropertiesKHR.adoc[] +-- + + +=== H.264 Encode Session + +Additional parameters can be specified when creating a video session with an +H.264 encode profile by including an instance of the +slink:VkVideoEncodeH264SessionCreateInfoKHR structure in the pname:pNext +chain of slink:VkVideoSessionCreateInfoKHR. + +[open,refpage='VkVideoEncodeH264SessionCreateInfoKHR',desc='Structure specifies H.264 encode session parameters',type='structs'] +-- +The sname:VkVideoEncodeH264SessionCreateInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264SessionCreateInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:useMaxLevelIdc indicates whether the value of pname:maxLevelIdc + should be used by the implementation. + When it is set to ename:VK_FALSE, the implementation ignores the value + of pname:maxLevelIdc and uses the value of + slink:VkVideoEncodeH264CapabilitiesKHR::pname:maxLevelIdc, as reported + by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile. + * pname:maxLevelIdc is a code:StdVideoH264LevelIdc value specifying the + upper bound on the H.264 level for the video bitstreams produced by the + created video session, where enum constant + `STD_VIDEO_H264_LEVEL_IDC__` identifies H.264 level + `.` as defined in section A.3 of the <>. + +include::{generated}/validity/structs/VkVideoEncodeH264SessionCreateInfoKHR.adoc[] +-- + + +[[encode-h264-parameter-sets]] +=== H.264 Encode Parameter Sets + +<> objects created with +the video codec operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR +can: contain the following types of parameters: + +:operationType: encode +include::{chapters}/video/h264_parameter_sets.adoc[] + +Implementations may: override any of these parameters according to the +semantics defined in the <> section before storing the resulting H.264 parameter sets into +the video session parameters object. +Applications need to use the flink:vkGetEncodedVideoSessionParametersKHR +command to determine whether any implementation overrides happened and to +retrieve the encoded H.264 parameter sets in order to be able to produce a +compliant H.264 video bitstream. + +Such H.264 parameter set overrides may: also have cascading effects on the +implementation overrides applied to the encoded bitstream produced by video +encode operations. +If the implementation supports the +ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR +<> flag, then the +application can: use such queries to retrieve feedback about whether any +implementation overrides have been applied to the encoded bitstream. + +[open,refpage='VkVideoEncodeH264SessionParametersCreateInfoKHR',desc='Structure specifies H.264 encoder parameter set information',type='structs'] +-- +When a <> object is +created with the codec operation +ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, the +slink:VkVideoSessionParametersCreateInfoKHR::pname:pNext chain must: include +a sname:VkVideoEncodeH264SessionParametersCreateInfoKHR structure specifying +the capacity and initial contents of the object. + +The sname:VkVideoEncodeH264SessionParametersCreateInfoKHR structure is +defined as: + +include::{generated}/api/structs/VkVideoEncodeH264SessionParametersCreateInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:maxStdSPSCount is the maximum number of <> entries the created sname:VkVideoSessionParametersKHR can: + contain. + * pname:maxStdPPSCount is the maximum number of <> entries the created sname:VkVideoSessionParametersKHR can: + contain. + * pname:pParametersAddInfo is `NULL` or a pointer to a + slink:VkVideoEncodeH264SessionParametersAddInfoKHR structure specifying + H.264 parameters to add upon object creation. + +include::{generated}/validity/structs/VkVideoEncodeH264SessionParametersCreateInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH264SessionParametersAddInfoKHR',desc='Structure specifies H.264 encoder parameter set information',type='structs'] +-- +The sname:VkVideoEncodeH264SessionParametersAddInfoKHR structure is defined +as: + +include::{generated}/api/structs/VkVideoEncodeH264SessionParametersAddInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:stdSPSCount is the number of elements in the pname:pStdSPSs array. + * pname:pStdSPSs is a pointer to an array of + code:StdVideoH264SequenceParameterSet structures describing the + <> entries to add. + * pname:stdPPSCount is the number of elements in the pname:pStdPPSs array. + * pname:pStdPPSs is a pointer to an array of + code:StdVideoH264PictureParameterSet structures describing the + <> entries to add. + +This structure can: be specified in the following places: + + * In the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH264SessionParametersCreateInfoKHR structure + specified in the pname:pNext chain of + slink:VkVideoSessionParametersCreateInfoKHR used to create a + <> object. + In this case, if the video codec operation the video session parameters + object is created with is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then it defines the + set of initial parameters to add to the created object (see + <>). + * In the pname:pNext chain of slink:VkVideoSessionParametersUpdateInfoKHR. + In this case, if the video codec operation the + <> object to be + updated was created with is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then it defines the + set of parameters to add to it (see + <>). + +.Valid Usage +**** + * [[VUID-VkVideoEncodeH264SessionParametersAddInfoKHR-None-04837]] + The pname:seq_parameter_set_id member of each + code:StdVideoH264SequenceParameterSet structure specified in the + elements of pname:pStdSPSs must: be unique within pname:pStdSPSs + * [[VUID-VkVideoEncodeH264SessionParametersAddInfoKHR-None-04838]] + The pair constructed from the pname:seq_parameter_set_id and + pname:pic_parameter_set_id members of each + code:StdVideoH264PictureParameterSet structure specified in the elements + of pname:pStdPPSs must: be unique within pname:pStdPPSs +**** + +include::{generated}/validity/structs/VkVideoEncodeH264SessionParametersAddInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH264SessionParametersGetInfoKHR',desc='Structure specifying parameters for retrieving encoded H.264 parameter set data',type='structs'] +-- +The sname:VkVideoEncodeH264SessionParametersGetInfoKHR structure is defined +as: + +include::{generated}/api/structs/VkVideoEncodeH264SessionParametersGetInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:writeStdSPS indicates whether the encoded <> identified by pname:stdSPSId is requested to be + retrieved. + * pname:writeStdPPS indicates whether the encoded <> identified by the pair constructed from + pname:stdSPSId and pname:stdPPSId is requested to be retrieved. + * pname:stdSPSId specifies the H.264 sequence parameter set ID used to + identify the retrieved H.264 sequence and/or picture parameter set(s). + * pname:stdPPSId specifies the H.264 picture parameter set ID used to + identify the retrieved H.264 picture parameter set when + pname:writeStdPPS is set to ename:VK_TRUE. + +When this structure is specified in the pname:pNext chain of the +slink:VkVideoEncodeSessionParametersGetInfoKHR structure passed to +flink:vkGetEncodedVideoSessionParametersKHR, the command will write encoded +parameter data to the output buffer in the following order: + + . The <> identified by + pname:stdSPSId, if pname:writeStdSPS is set to ename:VK_TRUE. + . The <> identified by the + pair constructed from pname:stdSPSId and pname:stdPPSId, if + pname:writeStdPPS is set to ename:VK_TRUE. + +.Valid Usage +**** + * [[VUID-VkVideoEncodeH264SessionParametersGetInfoKHR-writeStdSPS-08279]] + At least one of pname:writeStdSPS and pname:writeStdPPS must: be set to + ename:VK_TRUE +**** + +include::{generated}/validity/structs/VkVideoEncodeH264SessionParametersGetInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH264SessionParametersFeedbackInfoKHR',desc='Structure providing feedback about the requested H.264 video session parameters',type='structs'] +-- +The sname:VkVideoEncodeH264SessionParametersFeedbackInfoKHR structure is +defined as: + +include::{generated}/api/structs/VkVideoEncodeH264SessionParametersFeedbackInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:hasStdSPSOverrides indicates whether any of the parameters of the + requested <>, if one was + requested via + slink:VkVideoEncodeH264SessionParametersGetInfoKHR::pname:writeStdSPS, + were <> by the implementation. + * pname:hasStdPPSOverrides indicates whether any of the parameters of the + requested <>, if one was + requested via + slink:VkVideoEncodeH264SessionParametersGetInfoKHR::pname:writeStdPPS, + were <> by the implementation. + +include::{generated}/validity/structs/VkVideoEncodeH264SessionParametersFeedbackInfoKHR.adoc[] +-- + +=== H.264 Encoding Parameters + +[open,refpage='VkVideoEncodeH264PictureInfoKHR',desc='Structure specifies H.264 encode frame parameters',type='structs'] +-- +The slink:VkVideoEncodeH264PictureInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264PictureInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:naluSliceEntryCount is the number of elements in + pname:pNaluSliceEntries. + * pname:pNaluSliceEntries is a pointer to an array of + pname:naluSliceEntryCount slink:VkVideoEncodeH264NaluSliceInfoKHR + structures specifying the parameters of the individual H.264 slices to + encode for the input picture. + * pname:pStdPictureInfo is a pointer to a + code:StdVideoEncodeH264PictureInfo structure specifying + <>. + * pname:generatePrefixNalu controls whether prefix NALUs are generated + before slice NALUs into the target bitstream, as defined in sections + 7.3.2.12 and 7.4.2.12 of the <>. + +This structure is specified in the pname:pNext chain of the +slink:VkVideoEncodeInfoKHR structure passed to flink:vkCmdEncodeVideoKHR to +specify the codec-specific picture information for an <>. + +[[encode-h264-input-picture-info]] +Encode Input Picture Information:: + +When this structure is specified in the pname:pNext chain of the +slink:VkVideoEncodeInfoKHR structure passed to flink:vkCmdEncodeVideoKHR, +the information related to the <> is defined as follows: + + * The image subregion used is determined according to the + <> + section. + * The encode input picture is associated with the + <> provided in + pname:pStdPictureInfo. + +[[encode-h264-picture-info]] +Std Picture Information:: + +The members of the code:StdVideoEncodeH264PictureInfo structure pointed to +by pname:pStdPictureInfo are interpreted as follows: + + * code:flags.reserved and code:reserved1 are used only for padding + purposes and are otherwise ignored; + * code:flags.IdrPicFlag as defined in section 7.4.1 of the <>; + * code:flags.is_reference as defined in section 3.136 of the <>; + * code:seq_parameter_set_id and code:pic_parameter_set_id are used to + identify the active parameter sets, as described below; + * code:primary_pic_type as defined in section 7.4.2 of the <>; + * code:PicOrderCnt as defined in section 8.2 of the <>; + * code:temporal_id as defined in section G.7.4.1.1 of the <>; + * if code:pRefLists is not `NULL`, then it is a pointer to a + code:StdVideoEncodeH264ReferenceListsInfo structure that is interpreted + as follows: + ** code:flags.reserved is used only for padding purposes and is otherwise + ignored; + ** code:ref_pic_list_modification_flag_l0 and + code:ref_pic_list_modification_flag_l1 as defined in section 7.4.3.1 of + the <>; + ** code:num_ref_idx_l0_active_minus1 and code:num_ref_idx_l1_active_minus1 + as defined in section 7.4.3 of the <>; + ** code:RefPicList0 and code:RefPicList1 as defined in section 8.2.4 of + the <> where each element of + these arrays either identifies an + <> using + its <> index or contains the value + code:STD_VIDEO_H264_NO_REFERENCE_PICTURE to indicate "`no reference + picture`"; + ** if code:refList0ModOpCount is not zero, then + code:pRefList0ModOperations is a pointer to an array of + code:refList0ModOpCount number of + code:StdVideoEncodeH264RefListModEntry structures specifying the + modification parameters for the reference list L0 as defined in section + 7.4.3.1 of the <>; + ** if code:refList1ModOpCount is not zero, then + code:pRefList1ModOperations is a pointer to an array of + code:refList1ModOpCount number of + code:StdVideoEncodeH264RefListModEntry structures specifying the + modification parameters for the reference list L1 as defined in section + 7.4.3.1 of the <>; + ** if code:refPicMarkingOpCount is not zero, then + code:refPicMarkingOperations is a pointer to an array of + code:refPicMarkingOpCount number of + code:StdVideoEncodeH264RefPicMarkingEntry structures specifying the + reference picture marking parameters as defined in section 7.4.3.3 of + the <>; + * all other members are interpreted as defined in section 7.4.3 of the + <>. + +[[encode-h264-ref-pic-setup]] +Reference picture setup is controlled by the value of +code:StdVideoEncodeH264PictureInfo::pname:flags.is_reference. +If it is set and a <> is specified, then the latter is used as the target of picture +reconstruction to <> the <> +specified in pname:pEncodeInfo->pSetupReferenceSlot->slotIndex. +If code:StdVideoEncodeH264PictureInfo::pname:flags.is_reference is not set, +but a <> is +specified, then the corresponding picture reference associated with the +<> is invalidated, as described in the +<> section. + +Active Parameter Sets:: + +The members of the code:StdVideoEncodeH264PictureInfo structure pointed to +by pname:pStdPictureInfo are used to select the active parameter sets to use +from the bound video session parameters object, as follows: + + * [[encode-h264-active-sps]] The _active SPS_ is the + <> identified by the key specified in + code:StdVideoEncodeH264PictureInfo::code:seq_parameter_set_id. + * [[encode-h264-active-pps]] The _active PPS_ is the + <> identified by the key specified by the pair + constructed from + code:StdVideoEncodeH264PictureInfo::code:seq_parameter_set_id and + code:StdVideoEncodeH264PictureInfo::code:pic_parameter_set_id. + +[[encode-h264-weighted-pred]] +H.264 encoding uses _explicit weighted sample prediction_ for a slice, as +defined in section 8.4.2.3 of the <>, +if any of the following conditions are true for the active +<> and the pname:pStdSliceHeader member of the +corresponding element of pname:pNaluSliceEntries: + + * pname:pStdSliceHeader->slice_type is code:STD_VIDEO_H264_SLICE_TYPE_P + and code:weighted_pred_flag is enabled in the active PPS. + * pname:pStdSliceHeader->slice_type is code:STD_VIDEO_H264_SLICE_TYPE_B + and code:weighted_bipred_idc in the active PPS equals + code:STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICIT. + +.Valid Usage +**** + * [[VUID-VkVideoEncodeH264PictureInfoKHR-naluSliceEntryCount-08301]] + pname:naluSliceEntryCount must: be between `1` and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:maxSliceCount, inclusive, + as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the + used video profile + * [[VUID-VkVideoEncodeH264PictureInfoKHR-flags-08304]] + If slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H264_CAPABILITY_GENERATE_PREFIX_NALU_BIT_KHR, then + pname:generatePrefixNalu must: be ename:VK_FALSE + * [[VUID-VkVideoEncodeH264PictureInfoKHR-flags-08314]] + If slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H264_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_KHR + and the slice corresponding to any element of pname:pNaluSliceEntries + uses <>, + then + slink:VkVideoEncodeH264NaluSliceInfoKHR::pname:pStdSliceHeader->pWeightTable + must: not be `NULL` for that element of pname:pNaluSliceEntries + * [[VUID-VkVideoEncodeH264PictureInfoKHR-flags-08315]] + If slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_KHR, then + slink:VkVideoEncodeH264NaluSliceInfoKHR::pname:pStdSliceHeader->slice_type + must: be identical for all elements of pname:pNaluSliceEntries +**** + +include::{generated}/validity/structs/VkVideoEncodeH264PictureInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH264NaluSliceInfoKHR',desc='Structure specifies H.264 encode slice NALU parameters',type='structs'] +-- +The slink:VkVideoEncodeH264NaluSliceInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264NaluSliceInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:constantQp is the QP to use for the slice if the current + <> configured for the video + session is ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. + * pname:pStdSliceHeader is a pointer to a + code:StdVideoEncodeH264SliceHeader structure specifying + <> for + the slice. + +[[encode-h264-slice-header-params]] +Std Slice Header Parameters:: + +The members of the code:StdVideoEncodeH264SliceHeader structure pointed to +by pname:pStdSliceHeader are interpreted as follows: + + * code:flags.reserved and code:reserved1 are used only for padding + purposes and are otherwise ignored; + * if pname:pWeightTable is not `NULL`, then it is a pointer to a + code:StdVideoEncodeH264WeightTable that is interpreted as follows: + ** code:flags.reserved is used only for padding purposes and is otherwise + ignored; + ** all other members of code:StdVideoEncodeH264WeightTable are interpreted + as defined in section 7.4.3.2 of the <>; + * all other members are interpreted as defined in section 7.4.3 of the + <>. + +include::{generated}/validity/structs/VkVideoEncodeH264NaluSliceInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH264DpbSlotInfoKHR',desc='Structure specifies H.264 encode DPB picture information',type='structs'] +-- +The slink:VkVideoEncodeH264DpbSlotInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264DpbSlotInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:pStdReferenceInfo is a pointer to a + code:StdVideoEncodeH264ReferenceInfo structure specifying + <>. + +This structure is specified in the pname:pNext chain of +slink:VkVideoEncodeInfoKHR::pname:pSetupReferenceSlot, if not `NULL`, and +the pname:pNext chain of the elements of +slink:VkVideoEncodeInfoKHR::pname:pReferenceSlots to specify the +codec-specific reference picture information for an <>. + +[[encode-h264-active-reference-picture-info]] +Active Reference Picture Information:: + +When this structure is specified in the pname:pNext chain of the elements of +slink:VkVideoEncodeInfoKHR::pname:pReferenceSlots, one element is added to +the list of <> used by the video encode operation for each element of +slink:VkVideoEncodeInfoKHR::pname:pReferenceSlots as follows: + + * The image subregion used is determined according to the + <> + section. + * The reference picture is associated with the <> index + specified in the pname:slotIndex member of the corresponding element of + slink:VkVideoEncodeInfoKHR::pname:pReferenceSlots. + * The reference picture is associated with the + <> provided in + pname:pStdReferenceInfo. + +[[encode-h264-reconstructed-picture-info]] +Reconstructed Picture Information:: + +When this structure is specified in the pname:pNext chain of +slink:VkVideoEncodeInfoKHR::pname:pSetupReferenceSlot, the information +related to the <> +is defined as follows: + + * The image subregion used is determined according to the + <> + section. + * If <> is requested, + then the reconstructed picture is used to <> + the <> with the index specified in + slink:VkVideoEncodeInfoKHR::pname:pSetupReferenceSlot->slotIndex. + * The reconstructed picture is associated with the + <> provided in + pname:pStdReferenceInfo. + +[[encode-h264-reference-info]] +Std Reference Information:: + +The members of the code:StdVideoEncodeH264ReferenceInfo structure pointed to +by pname:pStdReferenceInfo are interpreted as follows: + + * code:flags.reserved is used only for padding purposes and is otherwise + ignored; + * code:flags.used_for_long_term_reference is used to indicate whether the + picture is marked as "`used for long-term reference`" as defined in + section 8.2.5.1 of the <>; + * code:primary_pic_type as defined in section 7.4.2 of the <>; + * code:long_term_pic_num and code:long_term_frame_idx as defined in + section 7.4.3 of the <>; + * code:temporal_id as defined in section G.7.4.1.1 of the <>; + * all other members are interpreted as defined in section 8.2 of the + <>. + +include::{generated}/validity/structs/VkVideoEncodeH264DpbSlotInfoKHR.adoc[] +-- + + +[[encode-h264-rate-control]] +=== H.264 Encode Rate Control + +[[encode-h264-gop]] +==== Group of Pictures + +In case of H.264 encoding it is common practice to follow a regular pattern +of different picture types in display order when encoding subsequent frames. +This pattern is referred to as the _group of pictures_ (GOP). + +[[encode-h264-regular-gop]] +A regular GOP is defined by the following parameters: + + * The number of frames in the GOP; + * The number of consecutive B frames between I and/or P frames in display + order. + +GOPs are further classified as _open_ and _closed_ GOPs. + +Frame types in an open GOP follow each other in display order according to +the following algorithm: + + 1. The first frame is always an I frame. + 2. This is followed by a number of consecutive B frames, as defined above. + 3. If the number of frames in the GOP is not reached yet, then the next + frame is a P frame and the algorithm continues from step 2. + +[[encode-h264-open-gop]] +image::{images}/h26x_open_gop.svg[align="center",title="H.264 open GOP",opts="{imageopts}"] + +[[encode-h264-idr-period]] +In case of a closed GOP, an <> is used at a +certain period. + +[[encode-h264-closed-gop]] +image::{images}/h26x_closed_gop.svg[align="center",title="H.264 closed GOP",opts="{imageopts}"] + +It is also typical for H.264 encoding to use specific reference picture +usage patterns across the frames of the GOP. +The two most common reference patterns used are as follows: + +[[encode-h264-ref-pattern-flat]] +Flat Reference Pattern:: + + * Each P frame uses the last non-B frame, in display order, as reference. + * Each B frame uses the last non-B frame, in display order, as its + backward reference, and uses the next non-B frame, in display order, as + its forward reference. + +image::{images}/h26x_ref_pattern_flat.svg[align="center",title="H.264 flat reference pattern",opts="{imageopts}"] + +[[encode-h264-ref-pattern-dyadic]] +Dyadic Reference Pattern:: + + * Each P frame uses the last non-B frame, in display order, as reference. + * The following algorithm is applied to the sequence of consecutive B + frames between I and/or P frames in display order: + + . The B frame in the middle of this sequence uses the frame preceding the + sequence as its backward reference, and uses the frame following the + sequence as its forward reference. + . The algorithm is executed recursively for the following frame sequences: + ** The B frames of the original sequence preceding the frame in the + middle, if any. + ** The B frames of the original sequence following the frame in the + middle, if any. + +image::{images}/h26x_ref_pattern_dyadic.svg[align="center",title="H.264 dyadic reference pattern",opts="{imageopts}"] + +The application can: provide guidance to the implementation's rate control +algorithm about the structure of the GOP used by the application. +Any such guidance about the GOP and its structure does not mandate that +specific GOP structure to be used by the application, as the picture type of +individual encoded pictures is still application-controlled, however, any +deviation from the provided guidance may: result in undesired rate control +behavior including, but not limited, to the implementation not being able to +conform to the expected average or target bitrates, or other rate control +parameters specified by the application. + +When an H.264 encode session is used to encode multiple temporal layers, it +is also common practice to follow a regular pattern for the H.264 temporal +ID for the encoded pictures in display order when encoding subsequent +frames. +This pattern is referred to as the _temporal GOP_. +The most common temporal layer pattern used is as follows: + +[[encode-h264-layer-pattern-dyadic]] +Dyadic Temporal Layer Pattern:: + + * The number of frames in the temporal GOP is [eq]#2^n-1^#, where [eq]#n# + is the number of temporal layers. + * The [eq]#i#^th^ frame in the temporal GOP uses temporal ID [eq]#t#, if + and only if the index of the least significant bit set in [eq]#i# equals + [eq]#n-t-1#, except for the first frame, which is the only frame in the + temporal GOP using temporal ID zero. + * The [eq]#i#^th^ frame in the temporal GOP uses the [eq]#r#^th^ frame as + reference, where [eq]#r# is calculated from [eq]#i# by clearing the + least significant bit set in it, except for the first frame in the + temporal GOP, which uses the first frame of the previous temporal GOP, + if any, as reference. + +image::{images}/h26x_layer_pattern_dyadic.svg[align="center",title="H.264 dyadic temporal layer pattern",opts="{imageopts}"] + +[NOTE] +.Note +==== +Multi-layer rate control and multi-layer coding are typically used for +streaming cases where low latency is expected, hence B pictures with forward +prediction are usually not used. +==== + +[open,refpage='VkVideoEncodeH264RateControlInfoKHR',desc='Structure describing H.264 stream rate control parameters',type='structs'] +-- +The sname:VkVideoEncodeH264RateControlInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264RateControlInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:flags is a bitmask of + elink:VkVideoEncodeH264RateControlFlagBitsKHR specifying H.264 rate + control flags. + * pname:gopFrameCount is the number of frames within a <> intended to be used by the application. + If it is set to 0, the rate control algorithm may: assume an + implementation-dependent GOP length. + If it is set to code:UINT32_MAX, the GOP length is treated as infinite. + * pname:idrPeriod is the interval, in terms of number of frames, between + two <> (see <>). + If it is set to 0, the rate control algorithm may: assume an + implementation-dependent IDR period. + If it is set to code:UINT32_MAX, the IDR period is treated as infinite. + * pname:consecutiveBFrameCount is the number of consecutive B frames + between I and/or P frames within the <>. + * pname:temporalLayerCount specifies the number of H.264 temporal layers + that the application intends to use. + +When an instance of this structure is included in the pname:pNext chain of +the slink:VkVideoCodingControlInfoKHR structure passed to the +flink:vkCmdControlVideoCodingKHR command, and +slink:VkVideoCodingControlInfoKHR::pname:flags includes +ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, the parameters in +this structure are used as guidance for the implementation's rate control +algorithm (see <>). + +If pname:flags includes +ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR, then +the rate control state is reset to an initial state to meet HRD compliance +requirements. +Otherwise the new rate control state may: be applied without a reset +depending on the implementation and the specified rate control parameters. + +[NOTE] +.Note +==== +It would be possible to infer the picture type to be used when encoding a +frame, on the basis of the values provided for pname:consecutiveBFrameCount, +pname:idrPeriod, and pname:gopFrameCount, but this inferred picture type +will not be used by implementations to override the picture type provided to +the video encode operation. +==== + +.Valid Usage +**** + * [[VUID-VkVideoEncodeH264RateControlInfoKHR-flags-08280]] + If slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H264_CAPABILITY_HRD_COMPLIANCE_BIT_KHR, then + pname:flags must: not contain + ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR + * [[VUID-VkVideoEncodeH264RateControlInfoKHR-flags-08281]] + If pname:flags contains + ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR + or + ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR, + then it must: also contain + ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REGULAR_GOP_BIT_KHR + * [[VUID-VkVideoEncodeH264RateControlInfoKHR-flags-08282]] + If pname:flags contains + ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR, + then it must: not also contain + ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR + * [[VUID-VkVideoEncodeH264RateControlInfoKHR-flags-08283]] + If pname:flags contains + ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REGULAR_GOP_BIT_KHR, then + pname:gopFrameCount must: be greater than `0` + * [[VUID-VkVideoEncodeH264RateControlInfoKHR-idrPeriod-08284]] + If pname:idrPeriod is not `0`, then it must: be greater than or equal to + pname:gopFrameCount + * [[VUID-VkVideoEncodeH264RateControlInfoKHR-consecutiveBFrameCount-08285]] + If pname:consecutiveBFrameCount is not `0`, then it must: be less than + pname:gopFrameCount +**** + +include::{generated}/validity/structs/VkVideoEncodeH264RateControlInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH264RateControlFlagBitsKHR',desc='H.264 encode rate control bits',type='enums'] +-- +Bits which can: be set in +slink:VkVideoEncodeH264RateControlInfoKHR::pname:flags, specifying H.264 +rate control flags, are: + +include::{generated}/api/enums/VkVideoEncodeH264RateControlFlagBitsKHR.adoc[] + + * ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR + specifies that rate control should: attempt to produce an HRD compliant + bitstream, as defined in annex C of the <>. + * ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REGULAR_GOP_BIT_KHR specifies + that the application intends to use a <> according to the parameters specified in the + pname:gopFrameCount, pname:idrPeriod, and pname:consecutiveBFrameCount + members of the slink:VkVideoEncodeH264RateControlInfoKHR structure. + * ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR + specifies that the application intends to follow a + <> in the GOP. + * ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR + specifies that the application intends to follow a + <> in the GOP. + * ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_TEMPORAL_LAYER_PATTERN_DYADIC_BIT_KHR + specifies that the application intends to follow a + <>. +-- + + +[open,refpage='VkVideoEncodeH264RateControlFlagsKHR',desc='Bitmask specifying H.264 encode rate control flags',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeH264RateControlFlagsKHR.adoc[] + +tname:VkVideoEncodeH264RateControlFlagsKHR is a bitmask type for setting a +mask of zero or more elink:VkVideoEncodeH264RateControlFlagBitsKHR. +-- + + +[[encode-h264-rate-control-layer]] +==== Rate Control Layers + +[open,refpage='VkVideoEncodeH264RateControlLayerInfoKHR',desc='Structure describing H.264 per-layer rate control parameters',type='structs'] +-- +The sname:VkVideoEncodeH264RateControlLayerInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264RateControlLayerInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:useMinQp indicates whether the QP values determined by rate + control will be clamped to the lower bounds on the QP values specified + in pname:minQp. + * pname:minQp specifies the lower bounds on the QP values, for each + picture type, that the implementation's rate control algorithm will use + when pname:useMinQp is set to ename:VK_TRUE. + * pname:useMaxQp indicates whether the QP values determined by rate + control will be clamped to the upper bounds on the QP values specified + in pname:maxQp. + * pname:maxQp specifies the upper bounds on the QP values, for each + picture type, that the implementation's rate control algorithm will use + when pname:useMaxQp is set to ename:VK_TRUE. + * pname:useMaxFrameSize indicates whether the implementation's rate + control algorithm should: use the values specified in pname:maxFrameSize + as the upper bounds on the encoded frame size for each picture type. + * pname:maxFrameSize specifies the upper bounds on the encoded frame size, + for each picture type, when pname:useMaxFrameSize is set to + ename:VK_TRUE. + +When used, the values in pname:minQp and pname:maxQp guarantee that the +effective QP values used by the implementation will respect those lower and +upper bounds, respectively. +However, limiting the range of QP values that the implementation is able to +use will also limit the capabilities of the implementation's rate control +algorithm to comply to other constraints. +In particular, the implementation may: not be able to comply to the +following: + + * The average and/or peak <> values to be used for + the encoded bitstream specified in the pname:averageBitrate and + pname:maxBitrate members of the + slink:VkVideoEncodeRateControlLayerInfoKHR structure. + * The upper bounds on the encoded frame size, for each picture type, + specified in the pname:maxFrameSize member of + sname:VkVideoEncodeH264RateControlLayerInfoKHR. + +[NOTE] +.Note +==== +In general, applications need to configure rate control parameters +appropriately in order to be able to get the desired rate control behavior, +as described in the <> +section. +==== + +When an instance of this structure is included in the pname:pNext chain of a +slink:VkVideoEncodeRateControlLayerInfoKHR structure specified in one of the +elements of the pname:pLayers array member of the +slink:VkVideoEncodeRateControlInfoKHR structure passed to the +flink:vkCmdControlVideoCodingKHR command, +slink:VkVideoCodingControlInfoKHR::pname:flags includes +ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, and the bound +video session was created with the video codec operation +ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, it specifies the +H.264-specific rate control parameters of the rate control layer +corresponding to that element of pname:pLayers. + +.Valid Usage +**** + * [[VUID-VkVideoEncodeH264RateControlLayerInfoKHR-useMinQp-08286]] + If pname:useMinQp is ename:VK_TRUE, then the pname:qpI, pname:qpP, and + pname:qpB members of pname:minQp must: all be between + slink:VkVideoEncodeH264CapabilitiesKHR::pname:minQp and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:maxQp, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile + * [[VUID-VkVideoEncodeH264RateControlLayerInfoKHR-useMaxQp-08287]] + If pname:useMaxQp is ename:VK_TRUE, then the pname:qpI, pname:qpP, and + pname:qpB members of pname:maxQp must: all be between + slink:VkVideoEncodeH264CapabilitiesKHR::pname:minQp and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:maxQp, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile + * [[VUID-VkVideoEncodeH264RateControlLayerInfoKHR-useMinQp-08288]] + If pname:useMinQp is ename:VK_TRUE and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H264_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHR, + then the pname:qpI, pname:qpP, and pname:qpB members of pname:minQp + must: all specify the same value + * [[VUID-VkVideoEncodeH264RateControlLayerInfoKHR-useMaxQp-08289]] + If pname:useMaxQp is ename:VK_TRUE and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H264_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHR, + then the pname:qpI, pname:qpP, and pname:qpB members of pname:maxQp + must: all specify the same value + * [[VUID-VkVideoEncodeH264RateControlLayerInfoKHR-useMinQp-08374]] + If pname:useMinQp and pname:useMaxQp are both ename:VK_TRUE, then the + pname:qpI, pname:qpP, and pname:qpB members of pname:minQp must: all be + less than or equal to the respective members of pname:maxQp +**** + +include::{generated}/validity/structs/VkVideoEncodeH264RateControlLayerInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH264QpKHR',desc='Structure describing H.264 QP values per picture type',type='structs'] +-- +The sname:VkVideoEncodeH264QpKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264QpKHR.adoc[] + + * pname:qpI is the QP to be used for <>. + * pname:qpP is the QP to be used for <>. + * pname:qpB is the QP to be used for <>. + +include::{generated}/validity/structs/VkVideoEncodeH264QpKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH264FrameSizeKHR',desc='Structure describing frame size values per H.264 picture type',type='structs'] +-- +The sname:VkVideoEncodeH264FrameSizeKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264FrameSizeKHR.adoc[] + + * pname:frameISize is the size in bytes to be used for + <>. + * pname:framePSize is the size in bytes to be used for + <>. + * pname:frameBSize is the size in bytes to be used for + <>. + +include::{generated}/validity/structs/VkVideoEncodeH264FrameSizeKHR.adoc[] +-- + + +[[encode-h264-gop-remaining-frames]] +==== GOP Remaining Frames + +Besides session level rate control configuration, the application can: +specify the number of frames per frame type remaining in the +<>. + +[open,refpage='VkVideoEncodeH264GopRemainingFrameInfoKHR',desc='Structure specifying H.264 encode rate control GOP remaining frame counts',type='structs'] +-- +The sname:VkVideoEncodeH264GopRemainingFrameInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH264GopRemainingFrameInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:useGopRemainingFrames indicates whether the implementation's rate + control algorithm should: use the values specified in + pname:gopRemainingI, pname:gopRemainingP, and pname:gopRemainingB. + If pname:useGopRemainingFrames is ename:VK_FALSE, then the values of + pname:gopRemainingI, pname:gopRemainingP, and pname:gopRemainingB are + ignored. + * pname:gopRemainingI specifies the number of <> the implementation's rate control algorithm should: assume to + be remaining in the <> prior to executing the video + encode operation. + * pname:gopRemainingP specifies the number of <> the implementation's rate control algorithm should: assume to + be remaining in the <> prior to executing the video + encode operation. + * pname:gopRemainingB specifies the number of <> the implementation's rate control algorithm should: assume to + be remaining in the <> prior to executing the video + encode operation. + +Setting pname:useGopRemainingFrames to ename:VK_TRUE and including this +structure in the pname:pNext chain of slink:VkVideoBeginCodingInfoKHR is +only mandatory if the +slink:VkVideoEncodeH264CapabilitiesKHR::pname:requiresGopRemainingFrames +reported for the used <> is ename:VK_TRUE. +However, implementations may: use these remaining frame counts, when +specified, even when it is not required. +In particular, when the application does not use a +<>, these values may: provide +additional guidance for the implementation's rate control algorithm. + +The slink:VkVideoEncodeH264CapabilitiesKHR::pname:prefersGopRemainingFrames +capability is also used to indicate that the implementation's rate control +algorithm may: operate more accurately if the application specifies the +remaining frame counts using this structure. + +As with other rate control guidance values, if the effective order and +number of frames encoded by the application are not in line with the +remaining frame counts specified in this structure at any given point, then +the behavior of the implementation's rate control algorithm may: deviate +from the one expected by the application. + +include::{generated}/validity/structs/VkVideoEncodeH264GopRemainingFrameInfoKHR.adoc[] +-- + + +[[encode-h264-requirements]] +=== H.264 Encode Requirements + +This section described the required: H.264 encoding capabilities for +physical devices that have at least one queue family that supports the video +codec operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, as +returned by flink:vkGetPhysicalDeviceQueueFamilyProperties2 in +slink:VkQueueFamilyVideoPropertiesKHR::pname:videoCodecOperations. + +.Required <> +[options="header"] +|==== +| Video Std Header Name | Version +| `vulkan_video_codec_h264std_encode` | 1.0.0 +|==== + +.Required Video Capabilities +[width="100%",cols="<35,<14,<11",options="header"] +|==== +| Video Capability | Requirement | Requirement Type^1^ +| **slink:VkVideoCapabilitiesKHR** | | +| pname:flags | - | min +| pname:minBitstreamBufferOffsetAlignment | 4096 | max +| pname:minBitstreamBufferSizeAlignment | 4096 | max +| pname:pictureAccessGranularity | (64,64) | max +| pname:minCodedExtent | - | max +| pname:maxCodedExtent | - | min +| pname:maxDpbSlots | 0 | min +| pname:maxActiveReferencePictures | 0 | min +| **slink:VkVideoEncodeCapabilitiesKHR** | | +| pname:flags | - | min +| pname:rateControlModes | - | min +| pname:maxBitrate | 64000 | min +| pname:maxQualityLevels | 1 | min +| pname:encodeInputPictureGranularity | (64,64) | max +| pname:supportedEncodeFeedbackFlags | ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR + + ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR | min +| **slink:VkVideoEncodeH264CapabilitiesKHR** | | +| pname:flags | - | min +| pname:maxLevelIdc | code:STD_VIDEO_H264_LEVEL_IDC_1_0 | min +| pname:maxSliceCount | 1 | min +| pname:maxPPictureL0ReferenceCount | 0 | min +| pname:maxBPictureL0ReferenceCount | 0 | min +| pname:maxL1ReferenceCount | 0 | min +| pname:maxTemporalLayerCount | 1 | min +| pname:expectDyadicTemporalLayerPattern | - | implementation-dependent +| pname:minQp | - | max +| pname:maxQp | - | min +| pname:prefersGopRemainingFrames | - | implementation-dependent +| pname:requiresGopRemainingFrames | - | implementation-dependent +| pname:stdSyntaxFlags | - | min +|==== + +1:: + The *Requirement Type* column specifies the requirement is either the + minimum value all implementations must: support, the maximum value all + implementations must: support, or the exact value all implementations + must: support. + For bitmasks a minimum value is the least bits all implementations must: + set, but they may: have additional bits set beyond this minimum. diff --git a/chapters/video/h264_parameter_sets.adoc b/chapters/video/h264_parameter_sets.adoc new file mode 100644 index 000000000..8a159f9c5 --- /dev/null +++ b/chapters/video/h264_parameter_sets.adoc @@ -0,0 +1,82 @@ +// Copyright 2020-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 +// Common H.264 Parameter Set descriptions +// "operationType" attribute specifies whether this is included in the encode or decode section + +[[{operationType}-h264-sps]] + +H.264 Sequence Parameter Sets (SPS):: + +Represented by code:StdVideoH264SequenceParameterSet structures and +interpreted as follows: + + * code:reserved1 and code:reserved2 are used only for padding purposes and + are otherwise ignored; + * code:seq_parameter_set_id is used as the key of the SPS entry; + * code:level_idc is one of the enum constants + `STD_VIDEO_H264_LEVEL_IDC__` identifying the H.264 level + `.` as defined in section A.3 of the <>; + * if code:flags.seq_scaling_matrix_present_flag is set, then the + code:StdVideoH264ScalingLists structure pointed to by code:pScalingLists + is interpreted as follows: + ** code:scaling_list_present_mask is a bitmask where bit index [eq]#i# + corresponds to `seq_scaling_list_present_flag[i]` as defined in section + 7.4.2.1 of the <>; + ** code:use_default_scaling_matrix_mask is a bitmask where bit index + [eq]#i# corresponds to `UseDefaultScalingMatrix4x4Flag[i]`, when [eq]#i + < 6#, or corresponds to `UseDefaultScalingMatrix8x8Flag[i-6]`, + otherwise, as defined in section 7.3.2.1 of the <>; + ** code:ScalingList4x4 and code:ScalingList8x8 correspond to the + identically named syntax elements defined in section 7.3.2.1 of the + <>; + * if code:flags.vui_parameters_present_flag is set, then + code:pSequenceParameterSetVui is a pointer to a + code:StdVideoH264SequenceParameterSetVui structure that is interpreted + as follows: + ** code:reserved1 is used only for padding purposes and is otherwise + ignored; + ** if code:flags.nal_hrd_parameters_present_flag or + code:flags.vcl_hrd_parameters_present_flag is set, then the + code:StdVideoH264HrdParameters structure pointed to by + code:pHrdParameters is interpreted as follows: + *** code:reserved1 is used only for padding purposes and is otherwise + ignored; + *** all other members of code:StdVideoH264HrdParameters are interpreted as + defined in section E.2.2 of the <>; + ** all other members of code:StdVideoH264SequenceParameterSetVui are + interpreted as defined in section E.2.1 of the <>; + * all other members of code:StdVideoH264SequenceParameterSet are + interpreted as defined in section 7.4.2.1 of the <>. + +[[{operationType}-h264-pps]] + +H.264 Picture Parameter Sets (PPS):: + +Represented by code:StdVideoH264PictureParameterSet structures and +interpreted as follows: + + * the pair constructed from code:seq_parameter_set_id and + code:pic_parameter_set_id is used as the key of the PPS entry; + * if code:flags.pic_scaling_matrix_present_flag is set, then the + code:StdVideoH264ScalingLists structure pointed to by code:pScalingLists + is interpreted as follows: + ** code:scaling_list_present_mask is a bitmask where bit index [eq]#i# + corresponds to `pic_scaling_list_present_flag[i]` as defined in section + 7.4.2.2 of the <>; + ** code:use_default_scaling_matrix_mask is a bitmask where bit index + [eq]#i# corresponds to `UseDefaultScalingMatrix4x4Flag[i]`, when [eq]#i + < 6#, or corresponds to `UseDefaultScalingMatrix8x8Flag[i-6]`, + otherwise, as defined in section 7.3.2.2 of the <>; + ** code:ScalingList4x4 and code:ScalingList8x8 correspond to the + identically named syntax elements defined in section 7.3.2.2 of the + <>; + * all other members of code:StdVideoH264PictureParameterSet are + interpreted as defined in section 7.4.2.2 of the <>. diff --git a/chapters/video_decode_h265_extensions.adoc b/chapters/video/h265_decode.adoc similarity index 61% rename from chapters/video_decode_h265_extensions.adoc rename to chapters/video/h265_decode.adoc index 1eb4ffb6c..cd195435e 100644 --- a/chapters/video_decode_h265_extensions.adoc +++ b/chapters/video/h265_decode.adoc @@ -49,6 +49,9 @@ section 8 of <>: reconstructed picture>> is accessed as defined in the <> section. + * The decision on <> is made + according to the parameters specified in the + <>. If the parameters and the bitstream adhere to the syntactic and semantic requirements defined in the corresponding sections of the <>. include::{generated}/validity/structs/VkVideoDecodeH265ProfileInfoKHR.adoc[] @@ -160,7 +163,7 @@ include::{generated}/api/structs/VkVideoDecodeH265CapabilitiesKHR.adoc[] * pname:sType is a elink:VkStructureType value identifying this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. - * pname:maxLevelIdc is a code:StdVideoH265LevelIdc value specifying the + * pname:maxLevelIdc is a code:StdVideoH265LevelIdc value indicating the maximum H.265 level supported by the profile, where enum constant `STD_VIDEO_H265_LEVEL_IDC__` identifies H.265 level `.` as defined in section A.4 of the <>; - * the code:StdVideoH265HrdParameters structure pointed to by - code:pHrdParameters is interpreted as follows: - ** code:reserved is used only for padding purposes and is otherwise - ignored; - ** code:flags.fixed_pic_rate_general_flag is a bitmask where bit index - [eq]#i# corresponds to `fixed_pic_rate_general_flag[i]` as defined in - section E.3.2 of the <>; - ** code:flags.fixed_pic_rate_within_cvs_flag is a bitmask where bit index - [eq]#i# corresponds to `fixed_pic_rate_within_cvs_flag[i]` as defined - in section E.3.2 of the <>; - ** code:flags.low_delay_hrd_flag is a bitmask where bit index [eq]#i# - corresponds to `low_delay_hrd_flag[i]` as defined in section E.3.2 of - the <>; - ** if code:flags.nal_hrd_parameters_present_flag is set, then - code:pSubLayerHrdParametersNal is a pointer to an array of - [eq]#code:vps_max_sub_layers_minus1 + 1# number of - code:StdVideoH265SubLayerHrdParameters structures where - code:vps_max_sub_layers_minus1 is the corresponding member of the - encompassing code:StdVideoH265VideoParameterSet structure and each - element is interpreted as follows: - *** code:cbr_flag is a bitmask where bit index [eq]#i# corresponds to - `cbr_flag[i]` as defined in section E.3.3 of the <>; - *** all other members of the code:StdVideoH265SubLayerHrdParameters - structure are interpreted as defined in section E.3.3 of the - <>; - ** if code:flags.vcl_hrd_parameters_present_flag is set, then - code:pSubLayerHrdParametersVcl is a pointer to an array of - [eq]#code:vps_max_sub_layers_minus1 + 1# number of - code:StdVideoH265SubLayerHrdParameters structures where - code:vps_max_sub_layers_minus1 is the corresponding member of the - encompassing code:StdVideoH265VideoParameterSet structure and each - element is interpreted as follows: - *** code:cbr_flag is a bitmask where bit index [eq]#i# corresponds to - `cbr_flag[i]` as defined in section E.3.3 of the <>; - *** all other members of the code:StdVideoH265SubLayerHrdParameters - structure are interpreted as defined in section E.3.3 of the - <>; - ** all other members of code:StdVideoH265HrdParameters are interpreted as - defined in section E.3.2 of the <>; - * the code:StdVideoH265ProfileTierLevel structure pointed to by - code:pProfileTierLevel are interpreted as follows: - ** code:general_level_idc is one of the enum constants - `STD_VIDEO_H265_LEVEL_IDC__` identifying the H.265 level - `.` as defined in section A.4 of the <>; - ** all other members of code:StdVideoH265ProfileTierLevel are interpreted - as defined in section 7.4.4 of the <>; - * all other members of code:StdVideoH265VideoParameterSet are interpreted - as defined in section 7.4.3.1 of the <>. - -[[decode-h265-sps]] -H.265 Sequence Parameter Sets (SPS):: - -Represented by code:StdVideoH265SequenceParameterSet structures and -interpreted as follows: - - * code:reserved1 and code:reserved2 are used only for padding purposes and - are otherwise ignored; - * the pair constructed from code:sps_video_parameter_set_id and - code:sps_seq_parameter_set_id is used as the key of the SPS entry; - * the code:StdVideoH265ProfileTierLevel structure pointed to by - code:pProfileTierLevel are interpreted as follows: - ** code:general_level_idc is one of the enum constants - `STD_VIDEO_H265_LEVEL_IDC__` identifying the H.265 level - `.` as defined in section A.4 of the <>; - ** all other members of code:StdVideoH265ProfileTierLevel are interpreted - as defined in section 7.4.4 of the <>; - * the code:max_latency_increase_plus1, code:max_dec_pic_buffering_minus1, - and code:max_num_reorder_pics members of the - code:StdVideoH265DecPicBufMgr structure pointed to by code:pDecPicBufMgr - correspond to `sps_max_latency_increase_plus1`, - `sps_max_dec_pic_buffering_minus1`, and `sps_max_num_reorder_pics`, - respectively, as defined in section 7.4.3.2 of the <>; - * if code:flags.sps_scaling_list_data_present_flag is set, then the - code:StdVideoH265ScalingLists structure pointed to by code:pScalingLists - is interpreted as follows: - ** code:ScalingList4x4, code:ScalingList8x8, code:ScalingList16x16, and - code:ScalingList32x32 correspond to `ScalingList[0]`, `ScalingList[1]`, - `ScalingList[2]`, and `ScalingList[3]`, respectively, as defined in - section 7.3.4 of the <>; - ** code:ScalingListDCCoef16x16 and code:ScalingListDCCoef32x32 correspond - to `scaling_list_dc_coef_minus8[0]` and - `scaling_list_dc_coef_minus8[1]`, respectively, as defined in section - 7.3.4 of the <>; - * code:pShortTermRefPicSet is a pointer to an array of - code:num_short_term_ref_pic_sets number of - code:StdVideoH265ShortTermRefPicSet structures where each element is - interpreted as follows: - ** code:reserved1, code:reserved2, and code:reserved3 are used only for - padding purposes and are otherwise ignored; - ** code:used_by_curr_pic_flag is a bitmask where bit index [eq]#i# - corresponds to `used_by_curr_pic_flag[i]` as defined in section 7.4.8 - of the <>; - ** code:use_delta_flag is a bitmask where bit index [eq]#i# corresponds to - `use_delta_flag[i]` as defined in section 7.4.8 of the <>; - ** code:used_by_curr_pic_s0_flag is a bitmask where bit index [eq]#i# - corresponds to `used_by_curr_pic_s0_flag[i]` as defined in section - 7.4.8 of the <>; - ** code:used_by_curr_pic_s1_flag is a bitmask where bit index [eq]#i# - corresponds to `used_by_curr_pic_s1_flag[i]` as defined in section - 7.4.8 of the <>; - ** all other members of code:StdVideoH265ShortTermRefPicSet are - interpreted as defined in section 7.4.8 of the <>; - * if code:flags.long_term_ref_pics_present_flag is set then the - code:StdVideoH265LongTermRefPicsSps structure pointed to by - code:pLongTermRefPicsSps is interpreted as follows: - ** code:used_by_curr_pic_lt_sps_flag is a bitmask where bit index [eq]#i# - corresponds to `used_by_curr_pic_lt_sps_flag[i]` as defined in section - 7.4.3.2 of the <>; - ** all other members of code:StdVideoH265LongTermRefPicsSps are - interpreted as defined in section 7.4.3.2 of the <>; - * if code:flags.vui_parameters_present_flag is set, then the - code:StdVideoH265SequenceParameterSetVui structure pointed to by - code:pSequenceParameterSetVui is interpreted as follows: - ** code:reserved1, code:reserved2, and code:reserved3 are used only for - padding purposes and are otherwise ignored; - ** the code:StdVideoH265HrdParameters structure pointed to by - code:pHrdParameters is interpreted as follows: - *** code:flags.fixed_pic_rate_general_flag is a bitmask where bit index - [eq]#i# corresponds to `fixed_pic_rate_general_flag[i]` as defined in - section E.3.2 of the <>; - *** code:flags.fixed_pic_rate_within_cvs_flag is a bitmask where bit index - [eq]#i# corresponds to `fixed_pic_rate_within_cvs_flag[i]` as defined - in section E.3.2 of the <>; - *** code:flags.low_delay_hrd_flag is a bitmask where bit index [eq]#i# - corresponds to `low_delay_hrd_flag[i]` as defined in section E.3.2 of - the <>; - *** if code:flags.nal_hrd_parameters_present_flag is set, then - code:pSubLayerHrdParametersNal is a pointer to an array of - [eq]#code:sps_max_sub_layers_minus1 + 1# number of - code:StdVideoH265SubLayerHrdParameters structures where - code:sps_max_sub_layers_minus1 is the corresponding member of the - encompassing code:StdVideoH265SequenceParameterSet structure and each - element is interpreted as follows: - **** code:cbr_flag is a bitmask where bit index [eq]#i# corresponds to - `cbr_flag[i]` as defined in section E.3.3 of the <>; - **** all other members of the code:StdVideoH265SubLayerHrdParameters - structure are interpreted as defined in section E.3.3 of the - <>; - *** if code:flags.vcl_hrd_parameters_present_flag is set, then - code:pSubLayerHrdParametersVcl is a pointer to an array of - [eq]#code:sps_max_sub_layers_minus1 + 1# number of - code:StdVideoH265SubLayerHrdParameters structures where - code:sps_max_sub_layers_minus1 is the corresponding member of the - encompassing code:StdVideoH265SequenceParameterSet structure and each - element is interpreted as follows: - **** code:cbr_flag is a bitmask where bit index [eq]#i# corresponds to - `cbr_flag[i]` as defined in section E.3.3 of the <>; - **** all other members of the code:StdVideoH265SubLayerHrdParameters - structure are interpreted as defined in section E.3.3 of the - <>; - *** all other members of code:StdVideoH265HrdParameters are interpreted as - defined in section E.3.2 of the <>; - ** all other members of code:pSequenceParameterSetVui are interpreted as - defined in section E.3.1 of the <>; - * if code:flags.sps_palette_predictor_initializer_present_flag is set, - then the code:PredictorPaletteEntries member of the - code:StdVideoH265PredictorPaletteEntries structure pointed to by - code:pPredictorPaletteEntries is interpreted as defined in section - 7.4.9.13 of the <>; - * all other members of code:StdVideoH265SequenceParameterSet are - interpreted as defined in section 7.4.3.1 of the <>. - -[[decode-h265-pps]] -H.265 Picture Parameter Sets (PPS):: - -Represented by code:StdVideoH265PictureParameterSet structures and -interpreted as follows: - - * code:reserved1, code:reserved2, and code:reserved3 are used only for - padding purposes and are otherwise ignored; - * the triplet constructed from code:sps_video_parameter_set_id, - code:pps_seq_parameter_set_id, and code:pps_pic_parameter_set_id is used - as the key of the PPS entry; - * if code:flags.pps_scaling_list_data_present_flag is set, then the - code:StdVideoH265ScalingLists structure pointed to by code:pScalingLists - is interpreted as follows: - ** code:ScalingList4x4, code:ScalingList8x8, code:ScalingList16x16, and - code:ScalingList32x32 correspond to `ScalingList[0]`, `ScalingList[1]`, - `ScalingList[2]`, and `ScalingList[3]`, respectively, as defined in - section 7.3.4 of the <>; - ** code:ScalingListDCCoef16x16 and code:ScalingListDCCoef32x32 correspond - to `scaling_list_dc_coef_minus8[0]` and - `scaling_list_dc_coef_minus8[1]`, respectively, as defined in section - 7.3.4 of the <>; - * if code:flags.pps_palette_predictor_initializer_present_flag is set, - then the code:PredictorPaletteEntries member of the - code:StdVideoH265PredictorPaletteEntries structure pointed to by - code:pPredictorPaletteEntries is interpreted as defined in section - 7.4.9.13 of the <>; - * all other members of code:StdVideoH265PictureParameterSet are - interpreted as defined in section 7.4.3.3 of the <>. +:operationType: decode +include::{chapters}/video/h265_parameter_sets.adoc[] [open,refpage='VkVideoDecodeH265SessionParametersCreateInfoKHR',desc='Structure specifies H.265 decoder parameter set information',type='structs'] -- @@ -575,11 +355,25 @@ by pname:pStdPictureInfo are interpreted as follows: <> where each element of these arrays either identifies an <> using - its <> index or contains the value 0xFF to indicate - "no reference picture"; + its <> index or contains the value + code:STD_VIDEO_H265_NO_REFERENCE_PICTURE to indicate "`no reference + picture`"; * all other members are interpreted as defined in section 8.3.2 of the <>. +[[decode-h265-ref-pic-setup]] +Reference picture setup is controlled by the value of +code:StdVideoDecodeH265PictureInfo::pname:flags.IsReference. +If it is set and a <> is specified, then the latter is used as the target of picture +reconstruction to <> the corresponding +<>. +If code:StdVideoDecodeH265PictureInfo::pname:flags.IsReference is not set, +but a <> is +specified, then the corresponding picture reference associated with the +<> is invalidated, as described in the +<> section. + Active Parameter Sets:: The members of the code:StdVideoDecodeH265PictureInfo structure pointed to @@ -655,8 +449,9 @@ is defined as follows: * The image subregion used is determined according to the <> section. - * The reconstructed picture is used to <> the - <> with the index specified in + * If <> is requested, + then the reconstructed picture is used to <> + the <> with the index specified in slink:VkVideoDecodeInfoKHR::pname:pSetupReferenceSlot->slotIndex. * The reconstructed picture is associated with the <> provided in @@ -696,3 +491,33 @@ slink:VkQueueFamilyVideoPropertiesKHR::pname:videoCodecOperations. | Video Std Header Name | Version | `vulkan_video_codec_h265std_decode` | 1.0.0 |==== + +ifdef::VK_KHR_video_maintenance1[] +.Required Video Capabilities +[width="100%",cols="<35,<14,<11",options="header"] +|==== +| Video Capability | Requirement | Requirement Type^1^ +| **slink:VkVideoCapabilitiesKHR** | | +| pname:flags | - | min +| pname:minBitstreamBufferOffsetAlignment | 4096 | max +| pname:minBitstreamBufferSizeAlignment | 4096 | max +| pname:pictureAccessGranularity | (64,64) | max +| pname:minCodedExtent | - | max +| pname:maxCodedExtent | - | min +| pname:maxDpbSlots | 0 | min +| pname:maxActiveReferencePictures | 0 | min +| **slink:VkVideoDecodeCapabilitiesKHR** | | +| pname:flags | ename:VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_COINCIDE_BIT_KHR or + ename:VK_VIDEO_DECODE_CAPABILITY_DPB_AND_OUTPUT_DISTINCT_BIT_KHR | min +| **slink:VkVideoDecodeH265CapabilitiesKHR** | | +| pname:maxLevelIdc | code:STD_VIDEO_H265_LEVEL_IDC_1_0 | min +|==== + +1:: + The *Requirement Type* column specifies the requirement is either the + minimum value all implementations must: support, the maximum value all + implementations must: support, or the exact value all implementations + must: support. + For bitmasks a minimum value is the least bits all implementations must: + set, but they may: have additional bits set beyond this minimum. +endif::VK_KHR_video_maintenance1[] diff --git a/chapters/video/h265_encode.adoc b/chapters/video/h265_encode.adoc new file mode 100644 index 000000000..e15a4ae3f --- /dev/null +++ b/chapters/video/h265_encode.adoc @@ -0,0 +1,1747 @@ +// Copyright 2018-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + +[[encode-h265]] +== H.265 Encode Operations + +Video encode operations using an <> can: be used to encode elementary video stream sequences compliant +to the <>. + +[NOTE] +.Note +==== +Refer to the <> for information on how the Khronos +Intellectual Property Rights Policy relates to normative references to +external materials not created by Khronos. +==== + +This process is performed according to the <> with the codec-specific semantics defined in +section 8 of the <> as follows: + + * Syntax elements, derived values, and other parameters are applied from + the following structures: + ** The code:StdVideoH265VideoParameterSet structure corresponding to the + <> specifying the <>. + ** The code:StdVideoH265SequenceParameterSet structure corresponding to + the <> specifying the + <>. + ** The code:StdVideoH265PictureParameterSet structure corresponding to the + <> specifying the <>. + ** The code:StdVideoEncodeH265PictureInfo structure specifying the + <>. + ** The code:StdVideoEncodeH265SliceSegmentHeader structures specifying the + <> for each encoded H.265 slice segment. + ** The code:StdVideoEncodeH265ReferenceInfo structures specifying the + <> + corresponding to the optional <> and any <>. + * The encoded bitstream data is written to the destination video bitstream + buffer range as defined in the + <> section. + * Picture data in the <> + corresponding to the used <>, <>, and + optional <> is accessed as + defined in the <> section. + * The decision on <> is made + according to the parameters specified in the + <>. + +If the parameters adhere to the syntactic and semantic requirements defined +in the corresponding sections of the <>, as described above, and the <> +associated with the <> +all refer to <>, then the video +encode operation will complete successfully. +Otherwise, the video encode operation may: complete +<>. + + +[[encode-h265-overrides]] +=== H.265 Encode Parameter Overrides + +Implementations may: override, unless otherwise specified, any of the H.265 +encode parameters specified in the following Video Std structures: + + * code:StdVideoH265VideoParameterSet + * code:StdVideoH265SequenceParameterSet + * code:StdVideoH265PictureParameterSet + * code:StdVideoEncodeH265PictureInfo + * code:StdVideoEncodeH265SliceSegmentHeader + * code:StdVideoEncodeH265ReferenceInfo + +All such H.265 encode parameter overrides must: fulfill the conditions +defined in the <> +section. + +In addition, implementations must: not override any of the following H.265 +encode parameters: + + * code:StdVideoEncodeH265PictureInfo::code:pic_type + * code:StdVideoEncodeH265SliceSegmentHeader::code:slice_type + +In case of H.265 encode parameters stored in +<> objects, +applications need to use the flink:vkGetEncodedVideoSessionParametersKHR +command to determine whether any implementation overrides happened. +If the query indicates that implementation overrides were applied, then the +application needs to retrieve and use the encoded H.265 parameter sets in +the bitstream in order to be able to produce a compliant H.265 video +bitstream using the H.265 encode parameters stored in the video session +parameters object. + +In case of any H.265 encode parameters stored in the encoded bitstream +produced by video encode operations, if the implementation supports the +ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR +<> flag, the +application can: use such queries to retrieve feedback about whether any +implementation overrides have been applied to those H.265 encode parameters. + + +[[encode-h265-bitstream-data-access]] +=== H.265 Encode Bitstream Data Access + +Each video encode operation writes one or more VCL NAL units comprising of +slice segment headers and data of the encoded picture, in the format defined +in sections 7.3.6 and 7.3.8, according to the semantics defined in sections +7.4.7 and 7.4.9 of the <>, +respectively. +The number of VCL NAL units written is specified by +slink:VkVideoEncodeH265PictureInfoKHR::pname:naluSliceSegmentEntryCount. + + +[[encode-h265-picture-data-access]] +=== H.265 Encode Picture Data Access + +Accesses to image data within a video picture resource happen at the +granularity indicated by +slink:VkVideoCapabilitiesKHR::pname:pictureAccessGranularity, as returned by +flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used <>. +Accordingly, the complete image subregion of a <>, <>, or +<> accessed by video coding +operations using an <> is defined +as the set of texels within the coordinate range: + + {empty}:: [eq]#([0,pname:endX),[0,pname:endY))# + +Where: + + * [eq]#pname:endX# equals [eq]#pname:codedExtent.width# rounded up to the + nearest integer multiple of pname:pictureAccessGranularity.width and + clamped to the width of the image subresource + <> to by the corresponding + slink:VkVideoPictureResourceInfoKHR structure; + * [eq]#endY# equals [eq]#pname:codedExtent.height# rounded up to the + nearest integer multiple of pname:pictureAccessGranularity.height and + clamped to the height of the image subresource + <> to by the corresponding + slink:VkVideoPictureResourceInfoKHR structure; + +Where pname:codedExtent is the member of the +slink:VkVideoPictureResourceInfoKHR structure corresponding to the picture. + +In case of video encode operations using an <>, any access to a picture at the coordinates +[eq]#(pname:x,pname:y)#, as defined by the <>, is an access to the image subresource +<> to by the corresponding +slink:VkVideoPictureResourceInfoKHR structure at the texel coordinates +[eq]#(pname:x,pname:y)#. + +Implementations may: choose not to access some or all texels within +particular <> available to a video +encode operation (e.g. due to <> restricting the effective set of used reference pictures, or if +the encoding algorithm chooses not to use certain subregions of the +reference picture data for sample prediction). + + +[[encode-h265-frame-picture-slice-type]] +=== H.265 Frame, Picture, Slice Segments, and Tiles + +H.265 pictures consist of one or more slices, slice segments, and tiles, as +defined in section 6.3.1 of the <>. + +Video encode operations using an <> can: encode slice segments of different types, as defined in +section 7.4.7.1 of the <>, by +specifying the corresponding enumeration constant value in +code:StdVideoEncodeH265SliceSegmentHeader::code:slice_type in the +<> from the Video Std enumeration type code:StdVideoH265SliceType: + + * [[encode-h265-b-slice]] code:STD_VIDEO_H265_SLICE_TYPE_B indicates that + the slice segment is part of a _B slice_ as defined in section 3.12 of + the <>. + * [[encode-h265-p-slice]] code:STD_VIDEO_H265_SLICE_TYPE_P indicates that + the slice segment is part of a _P slice_ as defined in section 3.111 of + the <>. + * [[encode-h265-i-slice]] code:STD_VIDEO_H265_SLICE_TYPE_I indicates that + the slice segment is part of an _I slice_ as defined in section 3.74 of + the <>. + +Pictures constructed from such slice segments can: be of different types, as +defined in section 7.4.3.5 of the <>. +Video encode operations using an <> can: encode pictures of a specific type by specifying the +corresponding enumeration constant value in +code:StdVideoEncodeH265PictureInfo::code:pic_type in the +<> from the Video Std +enumeration type code:StdVideoH265PictureType: + + * [[encode-h265-p-pic]] code:STD_VIDEO_H265_PICTURE_TYPE_P indicates that + the picture is a _P picture_. + A frame consisting of a P picture is also referred to as a _P frame_. + * [[encode-h265-b-pic]] code:STD_VIDEO_H265_PICTURE_TYPE_B indicates that + the picture is a _B picture_. + A frame consisting of a B picture is also referred to as a _B frame_. + * [[encode-h265-i-pic]] code:STD_VIDEO_H265_PICTURE_TYPE_I indicates that + the picture is an _I picture_. + A frame consisting of an I picture is also referred to as an _I frame_. + * [[encode-h265-idr-pic]] code:STD_VIDEO_H265_PICTURE_TYPE_IDR indicates + that the picture is a special type of I picture called an _IDR picture_ + as defined in section 3.67 of the <>. + A frame consisting of an IDR picture is also referred to as an _IDR + frame_. + + +[[encode-h265-profile]] +=== H.265 Encode Profile + +[open,refpage='VkVideoEncodeH265ProfileInfoKHR',desc='Structure specifying H.265 encode-specific video profile parameters',type='structs'] +-- +A video profile supporting H.265 video encode operations is specified by +setting slink:VkVideoProfileInfoKHR::pname:videoCodecOperation to +ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and adding a +sname:VkVideoEncodeH265ProfileInfoKHR structure to the +slink:VkVideoProfileInfoKHR::pname:pNext chain. + +The sname:VkVideoEncodeH265ProfileInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265ProfileInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying 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, as defined in section A.3 of the + <>. + +include::{generated}/validity/structs/VkVideoEncodeH265ProfileInfoKHR.adoc[] +-- + + +=== H.265 Encode Capabilities + +[open,refpage='VkVideoEncodeH265CapabilitiesKHR',desc='Structure describing H.265 encode capabilities',type='structs'] +-- +When calling flink:vkGetPhysicalDeviceVideoCapabilitiesKHR to query the +capabilities for an <>, the +slink:VkVideoCapabilitiesKHR::pname:pNext chain must: include a +sname:VkVideoEncodeH265CapabilitiesKHR structure that will be filled with +the profile-specific capabilities. + +The sname:VkVideoEncodeH265CapabilitiesKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265CapabilitiesKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:flags is a bitmask of elink:VkVideoEncodeH265CapabilityFlagBitsKHR + indicating supported H.265 encoding capabilities. + * pname:maxLevelIdc is a code:StdVideoH265LevelIdc value indicating the + maximum H.265 level supported by the profile, where enum constant + `STD_VIDEO_H265_LEVEL_IDC__` identifies H.265 level + `.` as defined in section A.4 of the <>. + * pname:maxSliceSegmentCount indicates the maximum number of slice + segments that can: be encoded for a single picture. + Further restrictions may: apply to the number of slice segments that + can: be encoded for a single picture depending on other capabilities and + codec-specific rules. + * pname:maxTiles indicates the maximum number of H.265 tile columns and + rows, as defined in sections 3.175 and 3.176 of the <> that can: be encoded for a single picture. + Further restrictions may: apply to the number of H.265 tiles that can: + be encoded for a single picture depending on other capabilities and + codec-specific rules. + * pname:ctbSizes is a bitmask of elink:VkVideoEncodeH265CtbSizeFlagBitsKHR + describing the supported CTB sizes. + * pname:transformBlockSizes is a bitmask of + elink:VkVideoEncodeH265TransformBlockSizeFlagBitsKHR describing the + supported transform block sizes. + * pname:maxPPictureL0ReferenceCount indicates the maximum number of + reference pictures the implementation supports in the reference list L0 + for <>. ++ +[NOTE] +.Note +==== +As implementations may: <> the reference lists, +pname:maxPPictureL0ReferenceCount does not limit the number of elements that +the application can: specify in the L0 reference list for P pictures. +However, if pname:maxPPictureL0ReferenceCount is zero, then the use of P +pictures is not allowed. +In case of H.265 encoding, backward-only predictive pictures can: be encoded +even if P pictures are not supported, as the <> supports _generalized P & B frames_ (also known as low delay +B frames) whereas B frames can: refer to past frames through both the L0 and +L1 reference lists. +==== + * pname:maxBPictureL0ReferenceCount indicates the maximum number of + reference pictures the implementation supports in the reference list L0 + for <>. + * pname:maxL1ReferenceCount indicates the maximum number of reference + pictures the implementation supports in the reference list L1 if + encoding of <> is supported. ++ +[NOTE] +.Note +==== +As implementations may: <> the reference lists, +pname:maxBPictureL0ReferenceCount and pname:maxL1ReferenceCount does not +limit the number of elements that the application can: specify in the L0 and +L1 reference lists for B pictures. +However, if pname:maxBPictureL0ReferenceCount and pname:maxL1ReferenceCount +are both zero, then the use of B pictures is not allowed. +==== + * pname:maxSubLayerCount indicates the maximum number of H.265 sub-layers + supported by the implementation. + * pname:expectDyadicTemporalSubLayerPattern indicates that the + implementation's rate control algorithms expect the application to use a + <> + when encoding multiple temporal sub-layers. + * pname:minQp indicates the minimum QP value supported. + * pname:maxQp indicates the maximum QP value supported. + * pname:prefersGopRemainingFrames indicates that the implementation's rate + control algorithm prefers the application to specify the number of + frames of each type <> in + the current <> when beginning a + <>. + * pname:requiresGopRemainingFrames indicates that the implementation's + rate control algorithm requires the application to specify the number of + frames of each type <> in + the current <> when beginning a + <>. + * pname:stdSyntaxFlags is a bitmask of + elink:VkVideoEncodeH265StdFlagBitsKHR indicating capabilities related to + H.265 syntax elements. + +include::{generated}/validity/structs/VkVideoEncodeH265CapabilitiesKHR.adoc[] +-- + + +[open,refpage='VkVideoEncodeH265CapabilityFlagBitsKHR',desc='Video encode H.265 capability flags',type='enums'] +-- +Bits which may: be set in +slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags, indicating the H.265 +encoding capabilities supported, are: + +include::{generated}/api/enums/VkVideoEncodeH265CapabilityFlagBitsKHR.adoc[] + + * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_HRD_COMPLIANCE_BIT_KHR indicates + if the implementation may: be able to generate HRD compliant bitstreams + if any of the code:nal_hrd_parameters_present_flag, + code:vcl_hrd_parameters_present_flag, or + code:sub_pic_hrd_params_present_flag members of + code:StdVideoH265HrdFlags are set to `1` in the HRD parameters of the + <> or <>, or if + code:StdVideoH265SpsVuiFlags::code:vui_hrd_parameters_present_flag is + set to `1` in the <>. + * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_KHR + indicates that if the code:weighted_pred_flag or the + code:weighted_bipred_flag member of code:StdVideoH265PpsFlags is set to + `1` in the <> when encoding a + <> or <>, + respectively, then the implementation is able to internally decide + syntax for code:pred_weight_table, as defined in section 7.4.7.3 of the + <>, and the application is not + required: to provide a weight table in the + <>. + * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_ROW_UNALIGNED_SLICE_SEGMENT_BIT_KHR + indicates that each slice segment in a frame with a single or multiple + tiles per slice may begin or finish at any offset in a CTB row. + If not supported, all slice segments in such a frame must: begin at the + start of a CTB row (and hence each slice segment must: finish at the end + of a CTB row). + Also indicates that each slice segment in a frame with multiple slices + per tile may begin or finish at any offset within the enclosing tile's + CTB row. + If not supported, slice segments in such a frame must: begin at the + start of the enclosing tile's CTB row (and hence each slice segment + must: finish at the end of the enclosing tile's CTB row). + * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_SLICE_SEGMENT_TYPE_BIT_KHR + indicates that when a frame is encoded with multiple slice segments, the + implementation allows encoding each slice segment with a different + code:StdVideoEncodeH265SliceSegmentHeader::code:slice_type specified in + the <>. + If not supported, all slice segments of the frame must: be encoded with + the same code:slice_type which corresponds to the picture type of the + frame. + * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_KHR + indicates support for using a <> as L0 + reference, as specified in + code:StdVideoEncodeH265ReferenceListsInfo::code:RefPicList0 in the + <>. + * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_KHR + indicates support for using a <> as L1 + reference, as specified in + code:StdVideoEncodeH265ReferenceListsInfo::code:RefPicList1 in the + <>. + * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHR + indicates support for specifying different QP values in the members of + slink:VkVideoEncodeH265QpKHR. + * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_PER_SLICE_SEGMENT_CONSTANT_QP_BIT_KHR + indicates support for specifying different constant QP values for each + slice segment. + * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_TILES_PER_SLICE_SEGMENT_BIT_KHR + indicates if encoding multiple tiles per slice segment, as defined in + section 6.3.1 of the <>, is + supported. + If this capability flag is not present, then the implementation is only + able to encode a single tile for each slice segment. + * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_SLICE_SEGMENTS_PER_TILE_BIT_KHR + indicates if encoding multiple slice segments per tile, as defined in + section 6.3.1 of the <>, is + supported. + If this capability flag is not present, then the implementation is only + able to encode a single slice segment for each tile. +-- + +[open,refpage='VkVideoEncodeH265CapabilityFlagsKHR',desc='Bitmask of VkVideoEncodeH265CapabilityFlagBitsKHR',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeH265CapabilityFlagsKHR.adoc[] + +tname:VkVideoEncodeH265CapabilityFlagsKHR is a bitmask type for setting a +mask of zero or more elink:VkVideoEncodeH265CapabilityFlagBitsKHR. +-- + +[open,refpage='VkVideoEncodeH265StdFlagBitsKHR',desc='Video encode H.265 syntax capability flags',type='enums'] +-- +Bits which may: be set in +slink:VkVideoEncodeH265CapabilitiesKHR::pname:stdSyntaxFlags, indicating the +capabilities related to the H.265 syntax elements, are: + +include::{generated}/api/enums/VkVideoEncodeH265StdFlagBitsKHR.adoc[] + + * ename:VK_VIDEO_ENCODE_H265_STD_SEPARATE_COLOR_PLANE_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265SpsFlags::code:separate_colour_plane_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_SAMPLE_ADAPTIVE_OFFSET_ENABLED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265SpsFlags::code:sample_adaptive_offset_enabled_flag in + the <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_SCALING_LIST_DATA_PRESENT_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for the code:scaling_list_enabled_flag and + code:sps_scaling_list_data_present_flag members of + code:StdVideoH265SpsFlags in the <>, and the + application-provided value for + code:StdVideoH265PpsFlags::code:pps_scaling_list_data_present_flag in + the <> when those values are `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_PCM_ENABLED_FLAG_SET_BIT_KHR indicates + whether the implementation supports using the application-provided value + for code:StdVideoH265SpsFlags::code:pcm_enable_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_SPS_TEMPORAL_MVP_ENABLED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265SpsFlags::code:sps_temporal_mvp_enabled_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_INIT_QP_MINUS26_BIT_KHR indicates whether + the implementation supports using the application-provided value for + code:StdVideoH265PictureParameterSet::code:init_qp_minus26 in the + <> when that value is non-zero. + * ename:VK_VIDEO_ENCODE_H265_STD_WEIGHTED_PRED_FLAG_SET_BIT_KHR indicates + whether the implementation supports using the application-provided value + for code:StdVideoH265PpsFlags::code:weighted_pred_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_WEIGHTED_BIPRED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PpsFlags::code:weighted_bipred_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_LOG2_PARALLEL_MERGE_LEVEL_MINUS2_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PictureParameterSet::code:log2_parallel_merge_level_minus2 + in the <> when that value is non-zero. + * ename:VK_VIDEO_ENCODE_H265_STD_SIGN_DATA_HIDING_ENABLED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PpsFlags::code:sign_data_hiding_enabled_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_TRANSFORM_SKIP_ENABLED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PpsFlags::code:transform_skip_enabled_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_TRANSFORM_SKIP_ENABLED_FLAG_UNSET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PpsFlags::code:transform_skip_enabled_flag in the + <> when that value is `0`. + * ename:VK_VIDEO_ENCODE_H265_STD_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PpsFlags::code:pps_slice_chroma_qp_offsets_present_flag + in the <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_TRANSQUANT_BYPASS_ENABLED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PpsFlags::code:transquant_bypass_enabled_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_CONSTRAINED_INTRA_PRED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PpsFlags::code:constrained_intra_pred_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_ENTROPY_CODING_SYNC_ENABLED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PpsFlags::code:entropy_coding_sync_enabled_flag in the + <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_DEBLOCKING_FILTER_OVERRIDE_ENABLED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PpsFlags::code:deblocking_filter_override_enabled_flag + in the <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_DEPENDENT_SLICE_SEGMENTS_ENABLED_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoH265PpsFlags::code:dependent_slice_segments_enabled_flag in + the <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_DEPENDENT_SLICE_SEGMENT_FLAG_SET_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoEncodeH265SliceSegmentHeader::code:dependent_slice_segment_flag + in the <> when that value is `1`. + * ename:VK_VIDEO_ENCODE_H265_STD_SLICE_QP_DELTA_BIT_KHR indicates whether + the implementation supports using the application-provided value for + code:StdVideoEncodeH265SliceSegmentHeader::code:slice_qp_delta in the + <> when that value is identical across the slice segments of + the encoded frame. + * ename:VK_VIDEO_ENCODE_H265_STD_DIFFERENT_SLICE_QP_DELTA_BIT_KHR + indicates whether the implementation supports using the + application-provided value for + code:StdVideoEncodeH265SliceSegmentHeader::code:slice_qp_delta in the + <> when that value is different across the slice segments of + the encoded frame. + +These capability flags provide information to the application about specific +H.265 syntax element values that the implementation supports without having +to <> them and do not otherwise restrict the +values that the application can: specify for any of the mentioned H.265 +syntax elements. +-- + +[open,refpage='VkVideoEncodeH265StdFlagsKHR',desc='Bitmask of VkVideoEncodeH265StdFlagBitsKHR',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeH265StdFlagsKHR.adoc[] + +tname:VkVideoEncodeH265StdFlagsKHR is a bitmask type for setting a mask of +zero or more elink:VkVideoEncodeH265StdFlagBitsKHR. +-- + +[open,refpage='VkVideoEncodeH265CtbSizeFlagBitsKHR',desc='Supported CTB sizes for H.265 video encode',type='enums'] +-- +Bits which may: be set in +slink:VkVideoEncodeH265CapabilitiesKHR::pname:ctbSizes, indicating the CTB +sizes supported by the implementation, are: + +include::{generated}/api/enums/VkVideoEncodeH265CtbSizeFlagBitsKHR.adoc[] + + * ename:VK_VIDEO_ENCODE_H265_CTB_SIZE_16_BIT_KHR specifies that a CTB size + of 16x16 is supported. + * ename:VK_VIDEO_ENCODE_H265_CTB_SIZE_32_BIT_KHR specifies that a CTB size + of 32x32 is supported. + * ename:VK_VIDEO_ENCODE_H265_CTB_SIZE_64_BIT_KHR specifies that a CTB size + of 64x64 is supported. +-- + +[open,refpage='VkVideoEncodeH265CtbSizeFlagsKHR',desc='Bitmask of VkVideoEncodeH265CtbSizeFlagBitsKHR',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeH265CtbSizeFlagsKHR.adoc[] + +tname:VkVideoEncodeH265CtbSizeFlagsKHR is a bitmask type for setting a mask +of zero or more elink:VkVideoEncodeH265CtbSizeFlagBitsKHR. + +Implementations must: support at least one of +ename:VkVideoEncodeH265CtbSizeFlagBitsKHR. +-- + +[open,refpage='VkVideoEncodeH265TransformBlockSizeFlagBitsKHR',desc='Supported transform block sizes for H.265 video encode',type='enums'] +-- +Bits which may: be set in +slink:VkVideoEncodeH265CapabilitiesKHR::pname:transformBlockSizes, +indicating the transform block sizes supported by the implementation, are: + +include::{generated}/api/enums/VkVideoEncodeH265TransformBlockSizeFlagBitsKHR.adoc[] + + * ename:VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_4_BIT_KHR specifies that + a transform block size of 4x4 is supported. + * ename:VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_8_BIT_KHR specifies that + a transform block size of 8x8 is supported. + * ename:VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_16_BIT_KHR specifies + that a transform block size of 16x16 is supported. + * ename:VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_32_BIT_KHR specifies + that a transform block size of 32x32 is supported. +-- + +[open,refpage='VkVideoEncodeH265TransformBlockSizeFlagsKHR',desc='Bitmask of VkVideoEncodeH265TransformBlockSizeFlagBitsKHR',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeH265TransformBlockSizeFlagsKHR.adoc[] + +tname:VkVideoEncodeH265TransformBlockSizeFlagsKHR is a bitmask type for +setting a mask of zero or more +elink:VkVideoEncodeH265TransformBlockSizeFlagBitsKHR. + +Implementations must: support at least one of +ename:VkVideoEncodeH265TransformBlockSizeFlagBitsKHR. +-- + + +=== H.265 Encode Quality Level Properties + +[open,refpage='VkVideoEncodeH265QualityLevelPropertiesKHR',desc='Structure describing the H.265 encode quality level properties',type='structs'] +-- +When calling flink:vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR +with pname:pVideoProfile->videoCodecOperation specified as +ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, the +slink:VkVideoEncodeH265QualityLevelPropertiesKHR structure must: be included +in the pname:pNext chain of the slink:VkVideoEncodeQualityLevelPropertiesKHR +structure to retrieve additional video encode quality level properties +specific to H.265 encoding. + +The slink:VkVideoEncodeH265QualityLevelPropertiesKHR structure is defined +as: + +include::{generated}/api/structs/VkVideoEncodeH265QualityLevelPropertiesKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:preferredRateControlFlags is a bitmask of + elink:VkVideoEncodeH265RateControlFlagBitsKHR values indicating the + preferred flags to use for + slink:VkVideoEncodeH265RateControlInfoKHR::pname:flags. + * pname:preferredGopFrameCount indicates the preferred value to use for + slink:VkVideoEncodeH265RateControlInfoKHR::pname:gopFrameCount. + * pname:preferredIdrPeriod indicates the preferred value to use for + slink:VkVideoEncodeH265RateControlInfoKHR::pname:idrPeriod. + * pname:preferredConsecutiveBFrameCount indicates the preferred value to + use for + slink:VkVideoEncodeH265RateControlInfoKHR::pname:consecutiveBFrameCount. + * pname:preferredSubLayerCount indicates the preferred value to use for + slink:VkVideoEncodeH265RateControlInfoKHR::pname:subLayerCount. + * pname:preferredConstantQp indicates the preferred values to use for + slink:VkVideoEncodeH265NaluSliceSegmentInfoKHR::pname:constantQp for + each picture type when using <> ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. + * pname:preferredMaxL0ReferenceCount indicates the preferred maximum + number of reference pictures to use in the reference list L0. + * pname:preferredMaxL1ReferenceCount indicates the preferred maximum + number of reference pictures to use in the reference list L1. + +include::{generated}/validity/structs/VkVideoEncodeH265QualityLevelPropertiesKHR.adoc[] +-- + + +=== H.265 Encode Session + +Additional parameters can be specified when creating a video session with an +H.265 encode profile by including an instance of the +slink:VkVideoEncodeH265SessionCreateInfoKHR structure in the pname:pNext +chain of slink:VkVideoSessionCreateInfoKHR. + +[open,refpage='VkVideoEncodeH265SessionCreateInfoKHR',desc='Structure specifies H.265 encode session parameters',type='structs'] +-- +The sname:VkVideoEncodeH265SessionCreateInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265SessionCreateInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:useMaxLevelIdc indicates whether the value of pname:maxLevelIdc + should be used by the implementation. + When it is set to ename:VK_FALSE, the implementation ignores the value + of pname:maxLevelIdc and uses the value of + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxLevelIdc, as reported + by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile. + * pname:maxLevelIdc is a code:StdVideoH265LevelIdc value specifying the + upper bound on the H.265 level for the video bitstreams produced by the + created video session, where enum constant + `STD_VIDEO_H265_LEVEL_IDC__` identifies H.265 level + `.` as defined in section A.4 of the <>. + +include::{generated}/validity/structs/VkVideoEncodeH265SessionCreateInfoKHR.adoc[] +-- + + +[[encode-h265-parameter-sets]] +=== H.265 Encode Parameter Sets + +<> objects created with +the video codec operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR +can: contain the following types of parameters: + +:operationType: encode +include::{chapters}/video/h265_parameter_sets.adoc[] + +Implementations may: override any of these parameters according to the +semantics defined in the <> section before storing the resulting H.265 parameter sets into +the video session parameters object. +Applications need to use the flink:vkGetEncodedVideoSessionParametersKHR +command to determine whether any implementation overrides happened and to +retrieve the encoded H.265 parameter sets in order to be able to produce a +compliant H.265 video bitstream. + +Such H.265 parameter set overrides may: also have cascading effects on the +implementation overrides applied to the encoded bitstream produced by video +encode operations. +If the implementation supports the +ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR +<> flag, then the +application can: use such queries to retrieve feedback about whether any +implementation overrides have been applied to the encoded bitstream. + +[open,refpage='VkVideoEncodeH265SessionParametersCreateInfoKHR',desc='Structure specifies H.265 encoder parameter set information',type='structs'] +-- +When a <> object is +created with the codec operation +ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, the +slink:VkVideoSessionParametersCreateInfoKHR::pname:pNext chain must: include +a sname:VkVideoEncodeH265SessionParametersCreateInfoKHR structure specifying +the capacity and initial contents of the object. + +The sname:VkVideoEncodeH265SessionParametersCreateInfoKHR structure is +defined as: + +include::{generated}/api/structs/VkVideoEncodeH265SessionParametersCreateInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:maxStdVPSCount is the maximum number of <> entries the created sname:VkVideoSessionParametersKHR can: + contain. + * pname:maxStdSPSCount is the maximum number of <> entries the created sname:VkVideoSessionParametersKHR can: + contain. + * pname:maxStdPPSCount is the maximum number of <> entries the created sname:VkVideoSessionParametersKHR can: + contain. + * pname:pParametersAddInfo is `NULL` or a pointer to a + slink:VkVideoEncodeH265SessionParametersAddInfoKHR structure specifying + H.265 parameters to add upon object creation. + +include::{generated}/validity/structs/VkVideoEncodeH265SessionParametersCreateInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH265SessionParametersAddInfoKHR',desc='Structure specifies H.265 encoder parameter set information',type='structs'] +-- +The sname:VkVideoEncodeH265SessionParametersAddInfoKHR structure is defined +as: + +include::{generated}/api/structs/VkVideoEncodeH265SessionParametersAddInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:stdVPSCount is the number of elements in the pname:pStdVPSs array. + * pname:pStdVPSs is a pointer to an array of + code:StdVideoH265VideoParameterSet structures describing the + <> entries to add. + * pname:stdSPSCount is the number of elements in the pname:pStdSPSs array. + * pname:pStdSPSs is a pointer to an array of + code:StdVideoH265SequenceParameterSet structures describing the + <> entries to add. + * pname:stdPPSCount is the number of elements in the pname:pStdPPSs array. + * pname:pStdPPSs is a pointer to an array of + code:StdVideoH265PictureParameterSet structures describing the + <> entries to add. + +This structure can: be specified in the following places: + + * In the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure + specified in the pname:pNext chain of + slink:VkVideoSessionParametersCreateInfoKHR used to create a + <> object. + In this case, if the video codec operation the video session parameters + object is created with is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then it defines the + set of initial parameters to add to the created object (see + <>). + * In the pname:pNext chain of slink:VkVideoSessionParametersUpdateInfoKHR. + In this case, if the video codec operation the + <> object to be + updated was created with is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then it defines the + set of parameters to add to it (see + <>). + +include::{generated}/validity/structs/VkVideoEncodeH265SessionParametersAddInfoKHR.adoc[] + +.Valid Usage +**** + * [[VUID-VkVideoEncodeH265SessionParametersAddInfoKHR-None-06438]] + The pname:vps_video_parameter_set_id member of each + code:StdVideoH265VideoParameterSet structure specified in the elements + of pname:pStdVPSs must: be unique within pname:pStdVPSs + * [[VUID-VkVideoEncodeH265SessionParametersAddInfoKHR-None-06439]] + The pair constructed from the pname:sps_video_parameter_set_id and + pname:sps_seq_parameter_set_id members of each + code:StdVideoH265SequenceParameterSet structure specified in the + elements of pname:pStdSPSs must: be unique within pname:pStdSPSs + * [[VUID-VkVideoEncodeH265SessionParametersAddInfoKHR-None-06440]] + The triplet constructed from the pname:sps_video_parameter_set_id, + pname:pps_seq_parameter_set_id, and pname:pps_pic_parameter_set_id + members of each code:StdVideoH265PictureParameterSet structure specified + in the elements of pname:pStdPPSs must: be unique within pname:pStdPPSs +**** +-- + +[open,refpage='VkVideoEncodeH265SessionParametersGetInfoKHR',desc='Structure specifying parameters for retrieving encoded H.265 parameter set data',type='structs'] +-- +The sname:VkVideoEncodeH265SessionParametersGetInfoKHR structure is defined +as: + +include::{generated}/api/structs/VkVideoEncodeH265SessionParametersGetInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:writeStdVPS indicates whether the encoded <> identified by pname:stdVPSId is requested to be + retrieved. + * pname:writeStdSPS indicates whether the encoded <> identified by the pair constructed from + pname:stdVPSId and pname:stdSPSId is requested to be retrieved. + * pname:writeStdPPS indicates whether the encoded <> identified by the triplet constructed from + pname:stdVPSId, pname:stdSPSId, and pname:stdPPSId is requested to be + retrieved. + * pname:stdVPSId specifies the H.265 video parameter set ID used to + identify the retrieved H.265 video, sequence, and/or picture parameter + set(s). + * pname:stdSPSId specifies the H.265 sequence parameter set ID used to + identify the retrieved H.265 sequence and/or picture parameter set(s) + when pname:writeStdSPS and/or pname:writeStdPPS is set to ename:VK_TRUE. + * pname:stdPPSId specifies the H.265 picture parameter set ID used to + identify the retrieved H.265 picture parameter set when + pname:writeStdPPS is set to ename:VK_TRUE. + +When this structure is specified in the pname:pNext chain of the +slink:VkVideoEncodeSessionParametersGetInfoKHR structure passed to +flink:vkGetEncodedVideoSessionParametersKHR, the command will write encoded +parameter data to the output buffer in the following order: + + . The <> identified by + pname:stdVPSId, if pname:writeStdVPS is set to ename:VK_TRUE. + . The <> identified by the + pair constructed from pname:stdVPSId and pname:stdSPSId, if + pname:writeStdSPS is set to ename:VK_TRUE. + . The <> identified by the + triplet constructed from pname:stdVPSId, pname:stdSPSId, and + pname:stdPPSId, if pname:writeStdPPS is set to ename:VK_TRUE. + +.Valid Usage +**** + * [[VUID-VkVideoEncodeH265SessionParametersGetInfoKHR-writeStdVPS-08290]] + At least one of pname:writeStdVPS, pname:writeStdSPS, and + pname:writeStdPPS must: be set to ename:VK_TRUE +**** + +include::{generated}/validity/structs/VkVideoEncodeH265SessionParametersGetInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH265SessionParametersFeedbackInfoKHR',desc='Structure providing feedback about the requested H.265 video session parameters',type='structs'] +-- +The sname:VkVideoEncodeH265SessionParametersFeedbackInfoKHR structure is +defined as: + +include::{generated}/api/structs/VkVideoEncodeH265SessionParametersFeedbackInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:hasStdVPSOverrides indicates whether any of the parameters of the + requested <>, if one was + requested via + slink:VkVideoEncodeH265SessionParametersGetInfoKHR::pname:writeStdVPS, + were <> by the implementation. + * pname:hasStdSPSOverrides indicates whether any of the parameters of the + requested <>, if one was + requested via + slink:VkVideoEncodeH265SessionParametersGetInfoKHR::pname:writeStdSPS, + were <> by the implementation. + * pname:hasStdPPSOverrides indicates whether any of the parameters of the + requested <>, if one was + requested via + slink:VkVideoEncodeH265SessionParametersGetInfoKHR::pname:writeStdPPS, + were <> by the implementation. + +include::{generated}/validity/structs/VkVideoEncodeH265SessionParametersFeedbackInfoKHR.adoc[] +-- + +=== H.265 Encoding Parameters + +[open,refpage='VkVideoEncodeH265PictureInfoKHR',desc='Structure specifies H.265 encode frame parameters',type='structs'] +-- +The slink:VkVideoEncodeH265PictureInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265PictureInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:naluSliceSegmentEntryCount is the number of elements in + pname:pNaluSliceSegmentEntries. + * pname:pNaluSliceSegmentEntries is a pointer to an array of + pname:naluSliceSegmentEntryCount + slink:VkVideoEncodeH265NaluSliceSegmentInfoKHR structures specifying the + parameters of the individual H.265 slice segments to encode for the + input picture. + * pname:pStdPictureInfo is a pointer to a + code:StdVideoEncodeH265PictureInfo structure specifying + <>. + +This structure is specified in the pname:pNext chain of the +slink:VkVideoEncodeInfoKHR structure passed to flink:vkCmdEncodeVideoKHR to +specify the codec-specific picture information for an <>. + +[[encode-h265-input-picture-info]] +Encode Input Picture Information:: + +When this structure is specified in the pname:pNext chain of the +slink:VkVideoEncodeInfoKHR structure passed to flink:vkCmdEncodeVideoKHR, +the information related to the <> is defined as follows: + + * The image subregion used is determined according to the + <> + section. + * The encode input picture is associated with the + <> provided in + pname:pStdPictureInfo. + +[[encode-h265-picture-info]] +Std Picture Information:: + +The members of the code:StdVideoEncodeH265PictureInfo structure pointed to +by pname:pStdPictureInfo are interpreted as follows: + + * code:flags.reserved and code:reserved1 are used only for padding + purposes and are otherwise ignored; + * code:flags.is_reference as defined in section 3.132 of the <>; + * code:flags.IrapPicFlag as defined in section 3.73 of the <>; + * code:flags.used_for_long_term_reference is used to indicate whether the + picture is marked as "`used for long-term reference`" as defined in + section 8.3.2 of the <>; + * code:flags.discardable_flag and code:cross_layer_bla_flag as defined in + section F.7.4.7.1 of the <>; + * code:pic_type as defined in section 7.4.3.5 of the <>; + * code:sps_video_parameter_set_id, code:pps_seq_parameter_set_id, and + code:pps_pic_parameter_set_id are used to identify the active parameter + sets, as described below; + * code:PicOrderCntVal as defined in section 8.3.1 of the + <>; + * code:TemporalId as defined in section 7.4.2.2 of the <>; + * if code:pRefLists is not `NULL`, then it is a pointer to a + code:StdVideoEncodeH265ReferenceListsInfo structure that is interpreted + as follows: + ** code:flags.reserved is used only for padding purposes and is otherwise + ignored; + ** code:ref_pic_list_modification_flag_l0 and + code:ref_pic_list_modification_flag_l1 as defined in section 7.4.7.2 of + the <>; + ** code:num_ref_idx_l0_active_minus1 and code:num_ref_idx_l1_active_minus1 + as defined in section 7.4.7.1 of the <>; + ** code:RefPicList0 and code:RefPicList1 as defined in section 8.3.4 of + the <> where each element of + these arrays either identifies an + <> using + its <> index or contains the value + code:STD_VIDEO_H265_NO_REFERENCE_PICTURE to indicate "`no reference + picture`"; + ** code:list_entry_l0 and code:list_entry_l1 as defined in section 7.4.7.2 + of the <>; + * if code:flags.short_term_ref_pic_set_sps_flag is set, then the + code:StdVideoH265ShortTermRefPicSet structure pointed to by + code:pShortTermRefPicSet is interpreted as defined for the elements of + the code:pShortTermRefPicSet array specified in <>. + * if code:flags.long_term_ref_pics_present_flag is set in the + <>, then the + code:StdVideoEncodeH265LongTermRefPics structure pointed to by + code:pLongTermRefPics is interpreted as follows: + ** code:used_by_curr_pic_lt_flag is a bitmask where bit index [eq]#i# + corresponds to `used_by_curr_pic_lt_flag[i]` as defined in section + 7.4.7.1 of the <>; + ** all other members of code:StdVideoEncodeH265LongTermRefPics are + interpreted as defined in section 7.4.7.1 of the <>; + * all other members are interpreted as defined in section 7.4.7.1 of the + <>. + +[[encode-h265-ref-pic-setup]] +Reference picture setup is controlled by the value of +code:StdVideoEncodeH265PictureInfo::pname:flags.is_reference. +If it is set and a <> is specified, then the latter is used as the target of picture +reconstruction to <> the <> +specified in pname:pEncodeInfo->pSetupReferenceSlot->slotIndex. +If code:StdVideoEncodeH265PictureInfo::pname:flags.is_reference is not set, +but a <> is +specified, then the corresponding picture reference associated with the +<> is invalidated, as described in the +<> section. + +Active Parameter Sets:: + +The members of the code:StdVideoEncodeH265PictureInfo structure pointed to +by pname:pStdPictureInfo are used to select the active parameter sets to use +from the bound video session parameters object, as follows: + + * [[encode-h265-active-vps]] The _active VPS_ is the + <> identified by the key specified in + code:StdVideoEncodeH265PictureInfo::code:sps_video_parameter_set_id. + * [[encode-h265-active-sps]] The _active SPS_ is the + <> identified by the key specified by the pair + constructed from + code:StdVideoEncodeH265PictureInfo::code:sps_video_parameter_set_id and + code:StdVideoEncodeH265PictureInfo::code:pps_seq_parameter_set_id. + * [[encode-h265-active-pps]] The _active PPS_ is the + <> identified by the key specified by the triplet + constructed from + code:StdVideoEncodeH265PictureInfo::code:sps_video_parameter_set_id, + code:StdVideoEncodeH265PictureInfo::code:pps_seq_parameter_set_id, and + code:StdVideoEncodeH265PictureInfo::code:pps_pic_parameter_set_id. + +[[encode-h265-weighted-pred]] +H.265 encoding uses _explicit weighted sample prediction_ for a slice +segment, as defined in section 8.5.3.3.4 of the <>, if any of the following conditions are true for the active +<> and the pname:pStdSliceSegmentHeader member of the +corresponding element of pname:pNaluSliceSegmentEntries: + + * pname:pStdSliceSegmentHeader->slice_type is + code:STD_VIDEO_H265_SLICE_TYPE_P and code:weighted_pred_flag is enabled + in the active PPS. + * pname:pStdSliceSegmentHeader->slice_type is + code:STD_VIDEO_H265_SLICE_TYPE_B and code:weighted_bipred_flag is + enabled in the active PPS. + +[[encode-h265-tile-count]] +The number of H.265 tiles, as defined in section 3.174 of the <>, is derived from the +code:num_tile_columns_minus1 and code:num_tile_rows_minus1 members of the +active <> as follows: + + {empty}:: [eq]#(code:num_tile_columns_minus1 {plus} 1) {times} + (code:num_tile_rows_minus1 {plus} 1)# + +.Valid Usage +**** + * [[VUID-VkVideoEncodeH265PictureInfoKHR-naluSliceSegmentEntryCount-08306]] + pname:naluSliceSegmentEntryCount must: be between `1` and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxSliceSegmentCount, + inclusive, as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR + for the used video profile + * [[VUID-VkVideoEncodeH265PictureInfoKHR-flags-08323]] + If slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_TILES_PER_SLICE_SEGMENT_BIT_KHR, + then pname:naluSliceSegmentEntryCount must: be greater than or equal to + the <> + * [[VUID-VkVideoEncodeH265PictureInfoKHR-flags-08324]] + If slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_SLICE_SEGMENTS_PER_TILE_BIT_KHR, + then pname:naluSliceSegmentEntryCount must: be less than or equal to the + <> + * [[VUID-VkVideoEncodeH265PictureInfoKHR-flags-08316]] + If slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_KHR + and the slice segment corresponding to any element of + pname:pNaluSliceSegmentEntries uses <>, then + slink:VkVideoEncodeH265NaluSliceSegmentInfoKHR::pname:pStdSliceSegmentHeader->pWeightTable + must: not be `NULL` for that element of pname:pNaluSliceSegmentEntries + * [[VUID-VkVideoEncodeH265PictureInfoKHR-flags-08317]] + If slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_SLICE_SEGMENT_TYPE_BIT_KHR, + then + slink:VkVideoEncodeH265NaluSliceSegmentInfoKHR::pname:pStdSliceSegmentHeader->slice_type + must: be identical for all elements of pname:pNaluSliceSegmentEntries +**** + +include::{generated}/validity/structs/VkVideoEncodeH265PictureInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH265NaluSliceSegmentInfoKHR',desc='Structure specifies H.265 encode slice segment NALU parameters',type='structs'] +-- +The slink:VkVideoEncodeH265NaluSliceSegmentInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265NaluSliceSegmentInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:constantQp is the QP to use for the slice segment if the current + <> configured for the video + session is ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. + * pname:pStdSliceSegmentHeader is a pointer to a + code:StdVideoEncodeH265SliceSegmentHeader structure specifying + <> for the slice segment. + +[[encode-h265-slice-segment-header-params]] +Std Slice Segment Header Parameters:: + +The members of the code:StdVideoEncodeH265SliceSegmentHeader structure +pointed to by pname:pStdSliceSegmentHeader are interpreted as follows: + + * code:flags.reserved and code:reserved1 are used only for padding + purposes and are otherwise ignored; + * if pname:pWeightTable is not `NULL`, then it is a pointer to a + code:StdVideoEncodeH265WeightTable that is interpreted as follows: + ** code:flags.luma_weight_l0_flag, code:flags.chroma_weight_l0_flag, + code:flags.luma_weight_l1_flag, and code:flags.chroma_weight_l1_flag + are bitmasks where bit index [eq]#i# corresponds to + `luma_weight_l0_flag[i]`, `chroma_weight_l0_flag[i]`, + `luma_weight_l1_flag[i]`, and `chroma_weight_l1_flag[i]`, respectively, + as defined in section 7.4.7.3 of the <>; + ** all other members of code:StdVideoEncodeH265WeightTable are interpreted + as defined in section 7.4.7.3 of the <>; + * all other members are interpreted as defined in section 7.4.7.1 of the + <>. + +include::{generated}/validity/structs/VkVideoEncodeH265NaluSliceSegmentInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH265DpbSlotInfoKHR',desc='Structure specifies H.265 encode DPB picture information',type='structs'] +-- +The slink:VkVideoEncodeH265DpbSlotInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265DpbSlotInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:pStdReferenceInfo is a pointer to a + code:StdVideoEncodeH265ReferenceInfo structure specifying + <>. + +This structure is specified in the pname:pNext chain of +slink:VkVideoEncodeInfoKHR::pname:pSetupReferenceSlot, if not `NULL`, and +the pname:pNext chain of the elements of +slink:VkVideoEncodeInfoKHR::pname:pReferenceSlots to specify the +codec-specific reference picture information for an <>. + +[[encode-h265-active-reference-picture-info]] +Active Reference Picture Information:: + +When this structure is specified in the pname:pNext chain of the elements of +slink:VkVideoEncodeInfoKHR::pname:pReferenceSlots, one element is added to +the list of <> used by the video encode operation for each element of +slink:VkVideoEncodeInfoKHR::pname:pReferenceSlots as follows: + + * The image subregion used is determined according to the + <> + section. + * The reference picture is associated with the <> index + specified in the pname:slotIndex member of the corresponding element of + slink:VkVideoEncodeInfoKHR::pname:pReferenceSlots. + * The reference picture is associated with the + <> provided in + pname:pStdReferenceInfo. + +[[encode-h265-reconstructed-picture-info]] +Reconstructed Picture Information:: + +When this structure is specified in the pname:pNext chain of +slink:VkVideoEncodeInfoKHR::pname:pSetupReferenceSlot, the information +related to the <> +is defined as follows: + + * The image subregion used is determined according to the + <> + section. + * If <> is requested, + then the reconstructed picture is used to <> + the <> with the index specified in + slink:VkVideoEncodeInfoKHR::pname:pSetupReferenceSlot->slotIndex. + * The reconstructed picture is associated with the + <> provided in + pname:pStdReferenceInfo. + +[[encode-h265-reference-info]] +Std Reference Information:: + +The members of the code:StdVideoEncodeH265ReferenceInfo structure pointed to +by pname:pStdReferenceInfo are interpreted as follows: + + * code:flags.reserved is used only for padding purposes and is otherwise + ignored; + * code:flags.used_for_long_term_reference is used to indicate whether the + picture is marked as "`used for long-term reference`" as defined in + section 8.3.2 of the <>; + * code:flags.unused_for_reference is used to indicate whether the picture + is marked as "`unused for reference`" as defined in section 8.3.2 of the + <>; + * code:pic_type as defined in section 7.4.3.5 of the <>; + * code:PicOrderCntVal as defined in section 8.3.1 of the + <>; + * code:TemporalId as defined in section 7.4.2.2 of the <>. + +include::{generated}/validity/structs/VkVideoEncodeH265DpbSlotInfoKHR.adoc[] +-- + + +[[encode-h265-rate-control]] +=== H.265 Encode Rate Control + +[[encode-h265-gop]] +==== Group of Pictures + +In case of H.265 encoding it is common practice to follow a regular pattern +of different picture types in display order when encoding subsequent frames. +This pattern is referred to as the _group of pictures_ (GOP). + +[[encode-h265-regular-gop]] +A regular GOP is defined by the following parameters: + + * The number of frames in the GOP; + * The number of consecutive B frames between I and/or P frames in display + order. + +GOPs are further classified as _open_ and _closed_ GOPs. + +Frame types in an open GOP follow each other in display order according to +the following algorithm: + + 1. The first frame is always an I frame. + 2. This is followed by a number of consecutive B frames, as defined above. + 3. If the number of frames in the GOP is not reached yet, then the next + frame is a P frame and the algorithm continues from step 2. + +[[encode-h265-open-gop]] +image::{images}/h26x_open_gop.svg[align="center",title="H.265 open GOP",opts="{imageopts}"] + +[[encode-h265-idr-period]] +In case of a closed GOP, an <> is used at a +certain period. + +[[encode-h265-closed-gop]] +image::{images}/h26x_closed_gop.svg[align="center",title="H.265 closed GOP",opts="{imageopts}"] + +It is also typical for H.265 encoding to use specific reference picture +usage patterns across the frames of the GOP. +The two most common reference patterns used are as follows: + +[[encode-h265-ref-pattern-flat]] +Flat Reference Pattern:: + + * Each P frame uses the last non-B frame, in display order, as reference. + * Each B frame uses the last non-B frame, in display order, as its + backward reference, and uses the next non-B frame, in display order, as + its forward reference. + +image::{images}/h26x_ref_pattern_flat.svg[align="center",title="H.265 flat reference pattern",opts="{imageopts}"] + +[[encode-h265-ref-pattern-dyadic]] +Dyadic Reference Pattern:: + + * Each P frame uses the last non-B frame, in display order, as reference. + * The following algorithm is applied to the sequence of consecutive B + frames between I and/or P frames in display order: + + . The B frame in the middle of this sequence uses the frame preceding the + sequence as its backward reference, and uses the frame following the + sequence as its forward reference. + . The algorithm is executed recursively for the following frame sequences: + ** The B frames of the original sequence preceding the frame in the + middle, if any. + ** The B frames of the original sequence following the frame in the + middle, if any. + +image::{images}/h26x_ref_pattern_dyadic.svg[align="center",title="H.265 dyadic reference pattern",opts="{imageopts}"] + +The application can: provide guidance to the implementation's rate control +algorithm about the structure of the GOP used by the application. +Any such guidance about the GOP and its structure does not mandate that +specific GOP structure to be used by the application, as the picture type of +individual encoded pictures is still application-controlled, however, any +deviation from the provided guidance may: result in undesired rate control +behavior including, but not limited, to the implementation not being able to +conform to the expected average or target bitrates, or other rate control +parameters specified by the application. + +When an H.265 encode session is used to encode multiple temporal sub-layers, +it is also common practice to follow a regular pattern for the H.265 +temporal ID for the encoded pictures in display order when encoding +subsequent frames. +This pattern is referred to as the _temporal GOP_. +The most common temporal layer pattern used is as follows: + +[[encode-h265-layer-pattern-dyadic]] +Dyadic Temporal Sub-Layer Pattern:: + + * The number of frames in the temporal GOP is [eq]#2^n-1^#, where [eq]#n# + is the number of temporal sub-layers. + * The [eq]#i#^th^ frame in the temporal GOP uses temporal ID [eq]#t#, if + and only if the index of the least significant bit set in [eq]#i# equals + [eq]#n-t-1#, except for the first frame, which is the only frame in the + temporal GOP using temporal ID zero. + * The [eq]#i#^th^ frame in the temporal GOP uses the [eq]#r#^th^ frame as + reference, where [eq]#r# is calculated from [eq]#i# by clearing the + least significant bit set in it, except for the first frame in the + temporal GOP, which uses the first frame of the previous temporal GOP, + if any, as reference. + +image::{images}/h26x_layer_pattern_dyadic.svg[align="center",title="H.265 dyadic temporal sub-layer pattern",opts="{imageopts}"] + +[NOTE] +.Note +==== +Multi-layer rate control and multi-layer coding are typically used for +streaming cases where low latency is expected, hence B pictures with forward +prediction are usually not used. +==== + +[open,refpage='VkVideoEncodeH265RateControlInfoKHR',desc='Structure describing H.265 stream rate control parameters',type='structs'] +-- +The sname:VkVideoEncodeH265RateControlInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265RateControlInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:flags is a bitmask of + elink:VkVideoEncodeH265RateControlFlagBitsKHR specifying H.265 rate + control flags. + * pname:gopFrameCount is the number of frames within a <> intended to be used by the application. + If it is set to 0, the rate control algorithm may: assume an + implementation-dependent GOP length. + If it is set to code:UINT32_MAX, the GOP length is treated as infinite. + * pname:idrPeriod is the interval, in terms of number of frames, between + two <> (see <>). + If it is set to 0, the rate control algorithm may: assume an + implementation-dependent IDR period. + If it is set to code:UINT32_MAX, the IDR period is treated as infinite. + * pname:consecutiveBFrameCount is the number of consecutive B frames + between I and/or P frames within the <>. + * pname:temporalLayerCount specifies the number of H.265 sub-layers that + the application intends to use. + +When an instance of this structure is included in the pname:pNext chain of +the slink:VkVideoCodingControlInfoKHR structure passed to the +flink:vkCmdControlVideoCodingKHR command, and +slink:VkVideoCodingControlInfoKHR::pname:flags includes +ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, the parameters in +this structure are used as guidance for the implementation's rate control +algorithm (see <>). + +If pname:flags includes +ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR, then +the rate control state is reset to an initial state to meet HRD compliance +requirements. +Otherwise the new rate control state may: be applied without a reset +depending on the implementation and the specified rate control parameters. + +[NOTE] +.Note +==== +It would be possible to infer the picture type to be used when encoding a +frame, on the basis of the values provided for pname:consecutiveBFrameCount, +pname:idrPeriod, and pname:gopFrameCount, but this inferred picture type +will not be used by implementations to override the picture type provided to +the video encode operation. +==== + +.Valid Usage +**** + * [[VUID-VkVideoEncodeH265RateControlInfoKHR-flags-08291]] + If slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_HRD_COMPLIANCE_BIT_KHR, then + pname:flags must: not contain + ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR + * [[VUID-VkVideoEncodeH265RateControlInfoKHR-flags-08292]] + If pname:flags contains + ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR + or + ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR, + then it must: also contain + ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REGULAR_GOP_BIT_KHR + * [[VUID-VkVideoEncodeH265RateControlInfoKHR-flags-08293]] + If pname:flags contains + ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR, + then it must: not also contain + ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR + * [[VUID-VkVideoEncodeH265RateControlInfoKHR-flags-08294]] + If pname:flags contains + ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REGULAR_GOP_BIT_KHR, then + pname:gopFrameCount must: be greater than `0` + * [[VUID-VkVideoEncodeH265RateControlInfoKHR-idrPeriod-08295]] + If pname:idrPeriod is not `0`, then it must: be greater than or equal to + pname:gopFrameCount + * [[VUID-VkVideoEncodeH265RateControlInfoKHR-consecutiveBFrameCount-08296]] + If pname:consecutiveBFrameCount is not `0`, then it must: be less than + pname:gopFrameCount +**** + +include::{generated}/validity/structs/VkVideoEncodeH265RateControlInfoKHR.adoc[] +-- + + +[open,refpage='VkVideoEncodeH265RateControlFlagBitsKHR',desc='H.265 encode rate control bits',type='enums'] +-- +Bits which can: be set in +slink:VkVideoEncodeH265RateControlInfoKHR::pname:flags, specifying H.265 +rate control flags, are: + +include::{generated}/api/enums/VkVideoEncodeH265RateControlFlagBitsKHR.adoc[] + + * ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR + specifies that rate control should: attempt to produce an HRD compliant + bitstream, as defined in annex C of the <>. + * ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REGULAR_GOP_BIT_KHR specifies + that the application intends to use a <> according to the parameters specified in the + pname:gopFrameCount, pname:idrPeriod, and pname:consecutiveBFrameCount + members of the slink:VkVideoEncodeH265RateControlInfoKHR structure. + * ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR + specifies that the application intends to follow a + <> in the GOP. + * ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR + specifies that the application intends to follow a + <> in the GOP. + * ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_TEMPORAL_SUB_LAYER_PATTERN_DYADIC_BIT_KHR + specifies that the application intends to follow a + <>. +-- + + +[open,refpage='VkVideoEncodeH265RateControlFlagsKHR',desc='Bitmask specifying H.265 encode rate control flags',type='flags'] +-- +include::{generated}/api/flags/VkVideoEncodeH265RateControlFlagsKHR.adoc[] + +tname:VkVideoEncodeH265RateControlFlagsKHR is a bitmask type for setting a +mask of zero or more elink:VkVideoEncodeH265RateControlFlagBitsKHR. +-- + + +[[encode-h265-rate-control-layer]] +==== Rate Control Layers + +[open,refpage='VkVideoEncodeH265RateControlLayerInfoKHR',desc='Structure describing H.265 per-layer rate control parameters',type='structs'] +-- +The sname:VkVideoEncodeH265RateControlLayerInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265RateControlLayerInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:useMinQp indicates whether the QP values determined by rate + control will be clamped to the lower bounds on the QP values specified + in pname:minQp. + * pname:minQp specifies the lower bounds on the QP values, for each + picture type, that the implementation's rate control algorithm will use + when pname:useMinQp is set to ename:VK_TRUE. + * pname:useMaxQp indicates whether the QP values determined by rate + control will be clamped to the upper bounds on the QP values specified + in pname:maxQp. + * pname:maxQp specifies the upper bounds on the QP values, for each + picture type, that the implementation's rate control algorithm will use + when pname:useMaxQp is set to ename:VK_TRUE. + * pname:useMaxFrameSize indicates whether the implementation's rate + control algorithm should: use the values specified in pname:maxFrameSize + as the upper bounds on the encoded frame size for each picture type. + * pname:maxFrameSize specifies the upper bounds on the encoded frame size, + for each picture type, when pname:useMaxFrameSize is set to + ename:VK_TRUE. + +When used, the values in pname:minQp and pname:maxQp guarantee that the +effective QP values used by the implementation will respect those lower and +upper bounds, respectively. +However, limiting the range of QP values that the implementation is able to +use will also limit the capabilities of the implementation's rate control +algorithm to comply to other constraints. +In particular, the implementation may: not be able to comply to the +following: + + * The average and/or peak <> values to be used for + the encoded bitstream specified in the pname:averageBitrate and + pname:maxBitrate members of the + slink:VkVideoEncodeRateControlLayerInfoKHR structure. + * The upper bounds on the encoded frame size, for each picture type, + specified in the pname:maxFrameSize member of + sname:VkVideoEncodeH265RateControlLayerInfoKHR. + +[NOTE] +.Note +==== +In general, applications need to configure rate control parameters +appropriately in order to be able to get the desired rate control behavior, +as described in the <> +section. +==== + +When an instance of this structure is included in the pname:pNext chain of a +slink:VkVideoEncodeRateControlLayerInfoKHR structure specified in one of the +elements of the pname:pLayers array member of the +slink:VkVideoEncodeRateControlInfoKHR structure passed to the +flink:vkCmdControlVideoCodingKHR command, +slink:VkVideoCodingControlInfoKHR::pname:flags includes +ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, and the bound +video session was created with the video codec operation +ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, it specifies the +H.265-specific rate control parameters of the rate control layer +corresponding to that element of pname:pLayers. + +.Valid Usage +**** + * [[VUID-VkVideoEncodeH265RateControlLayerInfoKHR-useMinQp-08297]] + If pname:useMinQp is ename:VK_TRUE, then the pname:qpI, pname:qpP, and + pname:qpB members of pname:minQp must: all be between + slink:VkVideoEncodeH265CapabilitiesKHR::pname:minQp and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxQp, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile + * [[VUID-VkVideoEncodeH265RateControlLayerInfoKHR-useMaxQp-08298]] + If pname:useMaxQp is ename:VK_TRUE, then the pname:qpI, pname:qpP, and + pname:qpB members of pname:maxQp must: all be between + slink:VkVideoEncodeH265CapabilitiesKHR::pname:minQp and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxQp, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video profile + * [[VUID-VkVideoEncodeH265RateControlLayerInfoKHR-useMinQp-08299]] + If pname:useMinQp is ename:VK_TRUE and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHR, + then the pname:qpI, pname:qpP, and pname:qpB members of pname:minQp + must: all specify the same value + * [[VUID-VkVideoEncodeH265RateControlLayerInfoKHR-useMaxQp-08300]] + If pname:useMaxQp is ename:VK_TRUE and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:flags, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the used video + profile, does not include + ename:VK_VIDEO_ENCODE_H265_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHR, + then the pname:qpI, pname:qpP, and pname:qpB members of pname:maxQp + must: all specify the same value + * [[VUID-VkVideoEncodeH265RateControlLayerInfoKHR-useMinQp-08375]] + If pname:useMinQp and pname:useMaxQp are both ename:VK_TRUE, then the + pname:qpI, pname:qpP, and pname:qpB members of pname:minQp must: all be + less than or equal to the respective members of pname:maxQp +**** + +include::{generated}/validity/structs/VkVideoEncodeH265RateControlLayerInfoKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH265QpKHR',desc='Structure describing H.265 QP values per picture type',type='structs'] +-- +The sname:VkVideoEncodeH265QpKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265QpKHR.adoc[] + + * pname:qpI is the QP to be used for <>. + * pname:qpP is the QP to be used for <>. + * pname:qpB is the QP to be used for <>. + +include::{generated}/validity/structs/VkVideoEncodeH265QpKHR.adoc[] +-- + +[open,refpage='VkVideoEncodeH265FrameSizeKHR',desc='Structure describing frame size values per H.265 picture type',type='structs'] +-- +The sname:VkVideoEncodeH265FrameSizeKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265FrameSizeKHR.adoc[] + + * pname:frameISize is the size in bytes to be used for + <>. + * pname:framePSize is the size in bytes to be used for + <>. + * pname:frameBSize is the size in bytes to be used for + <>. + +include::{generated}/validity/structs/VkVideoEncodeH265FrameSizeKHR.adoc[] +-- + + +[[encode-h265-gop-remaining-frames]] +==== GOP Remaining Frames + +Besides session level rate control configuration, the application can: +specify the number of frames per frame type remaining in the +<>. + +[open,refpage='VkVideoEncodeH265GopRemainingFrameInfoKHR',desc='Structure specifying H.265 encode rate control GOP remaining frame counts',type='structs'] +-- +The sname:VkVideoEncodeH265GopRemainingFrameInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoEncodeH265GopRemainingFrameInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:useGopRemainingFrames indicates whether the implementation's rate + control algorithm should: use the values specified in + pname:gopRemainingI, pname:gopRemainingP, and pname:gopRemainingB. + If pname:useGopRemainingFrames is ename:VK_FALSE, then the values of + pname:gopRemainingI, pname:gopRemainingP, and pname:gopRemainingB are + ignored. + * pname:gopRemainingI specifies the number of <> the implementation's rate control algorithm should: assume to + be remaining in the <> prior to executing the video + encode operation. + * pname:gopRemainingP specifies the number of <> the implementation's rate control algorithm should: assume to + be remaining in the <> prior to executing the video + encode operation. + * pname:gopRemainingB specifies the number of <> the implementation's rate control algorithm should: assume to + be remaining in the <> prior to executing the video + encode operation. + +Setting pname:useGopRemainingFrames to ename:VK_TRUE and including this +structure in the pname:pNext chain of slink:VkVideoBeginCodingInfoKHR is +only mandatory if the +slink:VkVideoEncodeH265CapabilitiesKHR::pname:requiresGopRemainingFrames +reported for the used <> is ename:VK_TRUE. +However, implementations may: use these remaining frame counts, when +specified, even when it is not required. +In particular, when the application does not use a +<>, these values may: provide +additional guidance for the implementation's rate control algorithm. + +The slink:VkVideoEncodeH265CapabilitiesKHR::pname:prefersGopRemainingFrames +capability is also used to indicate that the implementation's rate control +algorithm may: operate more accurately if the application specifies the +remaining frame counts using this structure. + +As with other rate control guidance values, if the effective order and +number of frames encoded by the application are not in line with the +remaining frame counts specified in this structure at any given point, then +the behavior of the implementation's rate control algorithm may: deviate +from the one expected by the application. + +include::{generated}/validity/structs/VkVideoEncodeH265GopRemainingFrameInfoKHR.adoc[] +-- + + +[[encode-h265-requirements]] +=== H.265 Encode Requirements + +This section described the required: H.265 encoding capabilities for +physical devices that have at least one queue family that supports the video +codec operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, as +returned by flink:vkGetPhysicalDeviceQueueFamilyProperties2 in +slink:VkQueueFamilyVideoPropertiesKHR::pname:videoCodecOperations. + +.Required <> +[options="header"] +|==== +| Video Std Header Name | Version +| `vulkan_video_codec_h265std_encode` | 1.0.0 +|==== + +.Required Video Capabilities +[width="100%",cols="<35,<14,<11",options="header"] +|==== +| Video Capability | Requirement | Requirement Type^1^ +| **slink:VkVideoCapabilitiesKHR** | | +| pname:flags | - | min +| pname:minBitstreamBufferOffsetAlignment | 4096 | max +| pname:minBitstreamBufferSizeAlignment | 4096 | max +| pname:pictureAccessGranularity | (64,64) | max +| pname:minCodedExtent | - | max +| pname:maxCodedExtent | - | min +| pname:maxDpbSlots | 0 | min +| pname:maxActiveReferencePictures | 0 | min +| **slink:VkVideoEncodeCapabilitiesKHR** | | +| pname:flags | - | min +| pname:rateControlModes | - | min +| pname:maxBitrate | 128000 | min +| pname:maxQualityLevels | 1 | min +| pname:encodeInputPictureGranularity | (64,64) | max +| pname:supportedEncodeFeedbackFlags | ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR + + ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR | min +| **slink:VkVideoEncodeH265CapabilitiesKHR** | | +| pname:flags | - | min +| pname:maxLevelIdc | code:STD_VIDEO_H265_LEVEL_IDC_1_0 | min +| pname:maxSliceSegmentCount | 1 | min +| pname:maxTiles | (1,1) | min +| pname:ctbSizes | at least one bit set | implementation-dependent +| pname:transformBlockSizes | at least one bit set | implementation-dependent +| pname:maxPPictureL0ReferenceCount | 0 | min +| pname:maxBPictureL0ReferenceCount | 0 | min +| pname:maxL1ReferenceCount | 0 | min +| pname:maxSubLayerCount | 1 | min +| pname:expectDyadicTemporalSubLayerPattern | - | implementation-dependent +| pname:minQp | - | max +| pname:maxQp | - | min +| pname:prefersGopRemainingFrames | - | implementation-dependent +| pname:requiresGopRemainingFrames | - | implementation-dependent +| pname:stdSyntaxFlags | - | min +|==== + +1:: + The *Requirement Type* column specifies the requirement is either the + minimum value all implementations must: support, the maximum value all + implementations must: support, or the exact value all implementations + must: support. + For bitmasks a minimum value is the least bits all implementations must: + set, but they may: have additional bits set beyond this minimum. diff --git a/chapters/video/h265_parameter_sets.adoc b/chapters/video/h265_parameter_sets.adoc new file mode 100644 index 000000000..ae1faaed9 --- /dev/null +++ b/chapters/video/h265_parameter_sets.adoc @@ -0,0 +1,234 @@ +// Copyright 2020-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 +// Common H.265 Parameter Set descriptions +// "operationType" attribute specifies whether this is included in the encode or decode section + +[[{operationType}-h265-vps]] + +H.265 Video Parameter Sets (VPS):: + +Represented by code:StdVideoH265VideoParameterSet structures and interpreted +as follows: + + * code:reserved1, code:reserved2, and code:reserved3 are used only for + padding purposes and are otherwise ignored; + * code:vps_video_parameter_set_id is used as the key of the VPS entry; + * the code:max_latency_increase_plus1, code:max_dec_pic_buffering_minus1, + and code:max_num_reorder_pics members of the + code:StdVideoH265DecPicBufMgr structure pointed to by code:pDecPicBufMgr + correspond to `vps_max_latency_increase_plus1`, + `vps_max_dec_pic_buffering_minus1`, and `vps_max_num_reorder_pics`, + respectively, as defined in section 7.4.3.1 of the <>; + * the code:StdVideoH265HrdParameters structure pointed to by + code:pHrdParameters is interpreted as follows: + ** code:reserved is used only for padding purposes and is otherwise + ignored; + ** code:flags.fixed_pic_rate_general_flag is a bitmask where bit index + [eq]#i# corresponds to `fixed_pic_rate_general_flag[i]` as defined in + section E.3.2 of the <>; + ** code:flags.fixed_pic_rate_within_cvs_flag is a bitmask where bit index + [eq]#i# corresponds to `fixed_pic_rate_within_cvs_flag[i]` as defined + in section E.3.2 of the <>; + ** code:flags.low_delay_hrd_flag is a bitmask where bit index [eq]#i# + corresponds to `low_delay_hrd_flag[i]` as defined in section E.3.2 of + the <>; + ** if code:flags.nal_hrd_parameters_present_flag is set, then + code:pSubLayerHrdParametersNal is a pointer to an array of + [eq]#code:vps_max_sub_layers_minus1 + 1# number of + code:StdVideoH265SubLayerHrdParameters structures where + code:vps_max_sub_layers_minus1 is the corresponding member of the + encompassing code:StdVideoH265VideoParameterSet structure and each + element is interpreted as follows: + *** code:cbr_flag is a bitmask where bit index [eq]#i# corresponds to + `cbr_flag[i]` as defined in section E.3.3 of the <>; + *** all other members of the code:StdVideoH265SubLayerHrdParameters + structure are interpreted as defined in section E.3.3 of the + <>; + ** if code:flags.vcl_hrd_parameters_present_flag is set, then + code:pSubLayerHrdParametersVcl is a pointer to an array of + [eq]#code:vps_max_sub_layers_minus1 + 1# number of + code:StdVideoH265SubLayerHrdParameters structures where + code:vps_max_sub_layers_minus1 is the corresponding member of the + encompassing code:StdVideoH265VideoParameterSet structure and each + element is interpreted as follows: + *** code:cbr_flag is a bitmask where bit index [eq]#i# corresponds to + `cbr_flag[i]` as defined in section E.3.3 of the <>; + *** all other members of the code:StdVideoH265SubLayerHrdParameters + structure are interpreted as defined in section E.3.3 of the + <>; + ** all other members of code:StdVideoH265HrdParameters are interpreted as + defined in section E.3.2 of the <>; + * the code:StdVideoH265ProfileTierLevel structure pointed to by + code:pProfileTierLevel are interpreted as follows: + ** code:general_level_idc is one of the enum constants + `STD_VIDEO_H265_LEVEL_IDC__` identifying the H.265 level + `.` as defined in section A.4 of the <>; + ** all other members of code:StdVideoH265ProfileTierLevel are interpreted + as defined in section 7.4.4 of the <>; + * all other members of code:StdVideoH265VideoParameterSet are interpreted + as defined in section 7.4.3.1 of the <>. + +[[{operationType}-h265-sps]] + +H.265 Sequence Parameter Sets (SPS):: + +Represented by code:StdVideoH265SequenceParameterSet structures and +interpreted as follows: + + * code:reserved1 and code:reserved2 are used only for padding purposes and + are otherwise ignored; + * the pair constructed from code:sps_video_parameter_set_id and + code:sps_seq_parameter_set_id is used as the key of the SPS entry; + * the code:StdVideoH265ProfileTierLevel structure pointed to by + code:pProfileTierLevel are interpreted as follows: + ** code:general_level_idc is one of the enum constants + `STD_VIDEO_H265_LEVEL_IDC__` identifying the H.265 level + `.` as defined in section A.4 of the <>; + ** all other members of code:StdVideoH265ProfileTierLevel are interpreted + as defined in section 7.4.4 of the <>; + * the code:max_latency_increase_plus1, code:max_dec_pic_buffering_minus1, + and code:max_num_reorder_pics members of the + code:StdVideoH265DecPicBufMgr structure pointed to by code:pDecPicBufMgr + correspond to `sps_max_latency_increase_plus1`, + `sps_max_dec_pic_buffering_minus1`, and `sps_max_num_reorder_pics`, + respectively, as defined in section 7.4.3.2 of the <>; + * if code:flags.sps_scaling_list_data_present_flag is set, then the + code:StdVideoH265ScalingLists structure pointed to by code:pScalingLists + is interpreted as follows: + ** code:ScalingList4x4, code:ScalingList8x8, code:ScalingList16x16, and + code:ScalingList32x32 correspond to `ScalingList[0]`, `ScalingList[1]`, + `ScalingList[2]`, and `ScalingList[3]`, respectively, as defined in + section 7.3.4 of the <>; + ** code:ScalingListDCCoef16x16 and code:ScalingListDCCoef32x32 correspond + to `scaling_list_dc_coef_minus8[0]` and + `scaling_list_dc_coef_minus8[1]`, respectively, as defined in section + 7.3.4 of the <>; + * code:pShortTermRefPicSet is a pointer to an array of + code:num_short_term_ref_pic_sets number of + code:StdVideoH265ShortTermRefPicSet structures where each element is + interpreted as follows: + ** code:reserved1, code:reserved2, and code:reserved3 are used only for + padding purposes and are otherwise ignored; + ** code:used_by_curr_pic_flag is a bitmask where bit index [eq]#i# + corresponds to `used_by_curr_pic_flag[i]` as defined in section 7.4.8 + of the <>; + ** code:use_delta_flag is a bitmask where bit index [eq]#i# corresponds to + `use_delta_flag[i]` as defined in section 7.4.8 of the <>; + ** code:used_by_curr_pic_s0_flag is a bitmask where bit index [eq]#i# + corresponds to `used_by_curr_pic_s0_flag[i]` as defined in section + 7.4.8 of the <>; + ** code:used_by_curr_pic_s1_flag is a bitmask where bit index [eq]#i# + corresponds to `used_by_curr_pic_s1_flag[i]` as defined in section + 7.4.8 of the <>; + ** all other members of code:StdVideoH265ShortTermRefPicSet are + interpreted as defined in section 7.4.8 of the <>; + * if code:flags.long_term_ref_pics_present_flag is set then the + code:StdVideoH265LongTermRefPicsSps structure pointed to by + code:pLongTermRefPicsSps is interpreted as follows: + ** code:used_by_curr_pic_lt_sps_flag is a bitmask where bit index [eq]#i# + corresponds to `used_by_curr_pic_lt_sps_flag[i]` as defined in section + 7.4.3.2 of the <>; + ** all other members of code:StdVideoH265LongTermRefPicsSps are + interpreted as defined in section 7.4.3.2 of the <>; + * if code:flags.vui_parameters_present_flag is set, then the + code:StdVideoH265SequenceParameterSetVui structure pointed to by + code:pSequenceParameterSetVui is interpreted as follows: + ** code:reserved1, code:reserved2, and code:reserved3 are used only for + padding purposes and are otherwise ignored; + ** the code:StdVideoH265HrdParameters structure pointed to by + code:pHrdParameters is interpreted as follows: + *** code:flags.fixed_pic_rate_general_flag is a bitmask where bit index + [eq]#i# corresponds to `fixed_pic_rate_general_flag[i]` as defined in + section E.3.2 of the <>; + *** code:flags.fixed_pic_rate_within_cvs_flag is a bitmask where bit index + [eq]#i# corresponds to `fixed_pic_rate_within_cvs_flag[i]` as defined + in section E.3.2 of the <>; + *** code:flags.low_delay_hrd_flag is a bitmask where bit index [eq]#i# + corresponds to `low_delay_hrd_flag[i]` as defined in section E.3.2 of + the <>; + *** if code:flags.nal_hrd_parameters_present_flag is set, then + code:pSubLayerHrdParametersNal is a pointer to an array of + [eq]#code:sps_max_sub_layers_minus1 + 1# number of + code:StdVideoH265SubLayerHrdParameters structures where + code:sps_max_sub_layers_minus1 is the corresponding member of the + encompassing code:StdVideoH265SequenceParameterSet structure and each + element is interpreted as follows: + **** code:cbr_flag is a bitmask where bit index [eq]#i# corresponds to + `cbr_flag[i]` as defined in section E.3.3 of the <>; + **** all other members of the code:StdVideoH265SubLayerHrdParameters + structure are interpreted as defined in section E.3.3 of the + <>; + *** if code:flags.vcl_hrd_parameters_present_flag is set, then + code:pSubLayerHrdParametersVcl is a pointer to an array of + [eq]#code:sps_max_sub_layers_minus1 + 1# number of + code:StdVideoH265SubLayerHrdParameters structures where + code:sps_max_sub_layers_minus1 is the corresponding member of the + encompassing code:StdVideoH265SequenceParameterSet structure and each + element is interpreted as follows: + **** code:cbr_flag is a bitmask where bit index [eq]#i# corresponds to + `cbr_flag[i]` as defined in section E.3.3 of the <>; + **** all other members of the code:StdVideoH265SubLayerHrdParameters + structure are interpreted as defined in section E.3.3 of the + <>; + *** all other members of code:StdVideoH265HrdParameters are interpreted as + defined in section E.3.2 of the <>; + ** all other members of code:pSequenceParameterSetVui are interpreted as + defined in section E.3.1 of the <>; + * if code:flags.sps_palette_predictor_initializer_present_flag is set, + then the code:PredictorPaletteEntries member of the + code:StdVideoH265PredictorPaletteEntries structure pointed to by + code:pPredictorPaletteEntries is interpreted as defined in section + 7.4.9.13 of the <>; + * all other members of code:StdVideoH265SequenceParameterSet are + interpreted as defined in section 7.4.3.1 of the <>. + +[[{operationType}-h265-pps]] + +H.265 Picture Parameter Sets (PPS):: + +Represented by code:StdVideoH265PictureParameterSet structures and +interpreted as follows: + + * code:reserved1, code:reserved2, and code:reserved3 are used only for + padding purposes and are otherwise ignored; + * the triplet constructed from code:sps_video_parameter_set_id, + code:pps_seq_parameter_set_id, and code:pps_pic_parameter_set_id is used + as the key of the PPS entry; + * if code:flags.pps_scaling_list_data_present_flag is set, then the + code:StdVideoH265ScalingLists structure pointed to by code:pScalingLists + is interpreted as follows: + ** code:ScalingList4x4, code:ScalingList8x8, code:ScalingList16x16, and + code:ScalingList32x32 correspond to `ScalingList[0]`, `ScalingList[1]`, + `ScalingList[2]`, and `ScalingList[3]`, respectively, as defined in + section 7.3.4 of the <>; + ** code:ScalingListDCCoef16x16 and code:ScalingListDCCoef32x32 correspond + to `scaling_list_dc_coef_minus8[0]` and + `scaling_list_dc_coef_minus8[1]`, respectively, as defined in section + 7.3.4 of the <>; + * if code:flags.pps_palette_predictor_initializer_present_flag is set, + then the code:PredictorPaletteEntries member of the + code:StdVideoH265PredictorPaletteEntries structure pointed to by + code:pPredictorPaletteEntries is interpreted as defined in section + 7.4.9.13 of the <>; + * all other members of code:StdVideoH265PictureParameterSet are + interpreted as defined in section 7.4.3.3 of the <>. diff --git a/chapters/video_encode_extensions.adoc b/chapters/video_encode_extensions.adoc deleted file mode 100644 index 77c8f03ea..000000000 --- a/chapters/video_encode_extensions.adoc +++ /dev/null @@ -1,738 +0,0 @@ -// Copyright 2018-2023 The Khronos Group Inc. -// -// SPDX-License-Identifier: CC-BY-4.0 - -[[video-encode-operations]] -== Video Encode Operations - -Before the application can start recording Vulkan command buffers for the -Video Encode Operations, it must: do the following, beforehand: - - . Ensure that the implementation can encode the Video Content by querying - the supported codec operations and profiles using - flink:vkGetPhysicalDeviceQueueFamilyProperties2. - . By using flink:vkGetPhysicalDeviceVideoFormatPropertiesKHR and providing - one or more video profiles, choose the Vulkan formats supported by the - implementation. - The formats for <> and - <> pictures must: be queried and chosen - separately. - Refer to the section on <>. - . Before creating an image to be used as a video picture resource, obtain - the supported image creation parameters by querying with - flink:vkGetPhysicalDeviceFormatProperties2 and - flink:vkGetPhysicalDeviceImageFormatProperties2 using one of the - reported formats and adding slink:VkVideoProfileListInfoKHR to the - pname:pNext chain of slink:VkFormatProperties2. - When querying the parameters with - flink:vkGetPhysicalDeviceImageFormatProperties2 for images targeting - <> and <> - pictures, the slink:VkPhysicalDeviceImageFormatInfo2::pname:usage field - should contain ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR and - ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, respectively. - . Create none, some, or all of the required <> for the - <> and <> - pictures. - More Video Picture Resources can: be created at some later point if - needed while processing the content to be encoded. - Also, if the size of the picture to be encoded is expected to change, - the images can: be created based on the maximum expected content size. - . Create the <> to be used for video encode - operations. - Before creating the Encode Video Session, the encode capabilities - should: be queried with flink:vkGetPhysicalDeviceVideoCapabilitiesKHR to - obtain the limits of the parameters allowed by the implementation for a - particular codec profile. - . Bind memory resources with the encode video session by calling - flink:vkBindVideoSessionMemoryKHR. - The video session cannot: be used until memory resources are allocated - and bound to it. - In order to determine the required memory sizes and heap types of the - device memory allocations, flink:vkGetVideoSessionMemoryRequirementsKHR - should: be called. - . Create one or more <> for use across command buffer recording operations, if - required by the codec extension in use. - These objects must: be created against a <> - with the parameters required by the codec. - Each <> created - is a child object of the associated <> - and cannot: be bound in the command buffer with any other - <>. - - -The recording of Video Encode Commands against a Vulkan Command Buffer -consists of the following sequence: - - . flink:vkCmdBeginVideoCodingKHR starts the recording of one or more Video - Encode operations in the command buffer. - For each Video Encode Command operation, a Video Session must: be bound - to the command buffer within this command. - This command establishes a Vulkan Video Encode Context that consists of - the bound Video Session Object, Session Parameters Object, and the - required Video Picture Resources. - The established Video Encode Context is in effect until the - flink:vkCmdEndVideoCodingKHR command is recorded. - If more Video Encode operations are to be required after the - flink:vkCmdEndVideoCodingKHR command, another Video Encode Context can: - be started with the flink:vkCmdBeginVideoCodingKHR command. - . flink:vkCmdEncodeVideoKHR specifies one or more frames to be encoded. - The slink:VkVideoEncodeInfoKHR parameters, and the codec extension - structures chained to this, specify the details of the encode operation. - . flink:vkCmdControlVideoCodingKHR records operations against the encoded - data, encoding device, or the Video Session state. - . flink:vkCmdEndVideoCodingKHR signals the end of the recording of the - Vulkan Video Encode Context, as established by - flink:vkCmdBeginVideoCodingKHR. - -In addition to the above, the following commands can: be recorded between -flink:vkCmdBeginVideoCodingKHR and flink:vkCmdEndVideoCodingKHR: - - * Query operations - * Global Memory Barriers - * Buffer Memory Barriers - * Image Memory Barriers (these must: be used to transition the Video - Picture Resources to the proper - ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR and - ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR layouts). - * Pipeline Barriers - * Events - * Timestamps - * Device Groups (device mask) - -The following Video Encode related commands must: be recorded *outside* the -Vulkan Video Encode Context established with the -flink:vkCmdBeginVideoCodingKHR and flink:vkCmdEndVideoCodingKHR commands: - - * Sparse Memory Binding - * Copy Commands - * Clear Commands - - -[[encode-input-picture]] -=== Encode Input Picture - -The primary source of input pixels for the video encoding process is the -_Encode Input Picture_, represented by a slink:VkImageView. -It may: also be a direct target of -ifdef::VK_KHR_video_decode_queue[] -video decode, -endif::VK_KHR_video_decode_queue[] -graphics, or compute operations -ifdef::VK_KHR_surface[] -, or with <> APIs -endif::VK_KHR_surface[] -. - - -=== Capabilities - -[open,refpage='VkVideoEncodeCapabilitiesKHR',desc='Structure specifying encode capabilities',type='structs'] --- -When calling flink:vkGetPhysicalDeviceVideoCapabilitiesKHR with -pname:pVideoProfile->videoCodecOperation specified as one of the encode -operation bits, the slink:VkVideoEncodeCapabilitiesKHR structure must: be -included in the pname:pNext chain of the slink:VkVideoCapabilitiesKHR -structure to retrieve capabilities specific to video encoding. - -The sname:VkVideoEncodeCapabilitiesKHR structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeCapabilitiesKHR.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:flags is a bitmask of elink:VkVideoEncodeCapabilityFlagBitsKHR - describing supported encoding features. - * pname:rateControlModes is a bitmask of - elink:VkVideoEncodeRateControlModeFlagBitsKHR indicating supported rate - control modes. - * pname:maxRateControlLayers indicates the maximum number of rate control - layers supported. - * pname:maxBitrate indicates the maximum supported bitrate. - * pname:maxQualityLevels indicates the number of discrete video encode - quality levels supported. - Implementations must: report at least 1. - * pname:encodeInputPictureGranularity indicates the granularity at which - <> data is encoded. - * pname:supportedEncodeFeedbackFlags is a bitmask of - elink:VkVideoEncodeFeedbackFlagBitsKHR values specifying the supported - flags for <>. - -Implementations must: include support for at least -ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR and -ename:VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR in -pname:supportedEncodeFeedbackFlags. - -The input content and encode resolution (specified in -slink:VkVideoEncodeInfoKHR::pname:codedExtent) may not be aligned with the -codec-specific coding block size. -For example, the input content may be 1920x1080 and the coding block size -may be 16x16 pixel blocks. -In this example, the content is horizontally aligned with the coding block -size, but not vertically aligned with the coding block size. -Encoding of the last row of blocks may be impacted by contents of the input -image in pixel rows 1081 to 1088 (the next vertical alignment with the -coding block size). -In general, to ensure efficient encoding for the last row/column of blocks, -and/or to ensure consistent encoding results between repeated encoding of -the same input content, these extra pixel rows/columns should be filled to -known values up to the coding block size alignment before encoding -operations are performed. -Some implementations support performing auto-fill of unaligned pixels beyond -a specific alignment for the purposes of encoding, which is reported in -pname:encodeInputPictureGranularity. -For example, if an implementation reports 1x1 in -pname:encodeInputPictureGranularity, then the implementation will perform -auto-fill for any unaligned pixels beyond the encode resolution up to the -next coding block size. -For a coding block size of 16x16, if the implementation reports 16x16 in -pname:encodeInputPictureGranularity, then it is the application's -responsibility to fill any unaligned pixels, if desired. -When the application does not fill these unaligned pixels, there may: be an -impact on the encoding efficiency but there will be no effect on the -validity of the generated bitstream. -If the implementation reports 8x8 in pname:encodeInputPictureGranularity, -then for the 1920x1080 example, since the content is aligned to 8 pixels -vertically, the implementation will auto-fill pixel rows 1081 to 1088 (up to -the 16x16 coding block size in the example). -The auto-fill value(s) are implementation-specific. -The auto-fill value(s) are not written to the input image memory, but are -used as part of the encoding operation on the input image. - -include::{generated}/validity/structs/VkVideoEncodeCapabilitiesKHR.adoc[] --- - -[open,refpage='VkVideoEncodeCapabilityFlagsKHR',desc='Bitmask of VkVideoEncodeCapabilityFlagBitsKHR',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeCapabilityFlagsKHR.adoc[] - -tname:VkVideoEncodeCapabilityFlagsKHR is a bitmask type for setting a mask -of zero or more elink:VkVideoEncodeCapabilityFlagBitsKHR. --- - -[open,refpage='VkVideoEncodeCapabilityFlagBitsKHR',desc='Video encode capability flags',type='enums'] --- -Bits which may: be set in slink:VkVideoEncodeCapabilitiesKHR::pname:flags, -indicating the encoding tools supported, are: - -include::{generated}/api/enums/VkVideoEncodeCapabilityFlagBitsKHR.adoc[] - - * ename:VK_VIDEO_ENCODE_CAPABILITY_PRECEDING_EXTERNALLY_ENCODED_BYTES_BIT_KHR - indicates that the implementation supports the use of - slink:VkVideoEncodeInfoKHR::pname:precedingExternallyEncodedBytes. - * ename:VK_VIDEO_ENCODE_CAPABILITY_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_DETECTION_BIT_KHR - indicates that the implementation is able to detect and report when the - destination video bitstream buffer range provided by the application is - not sufficiently large to fit the encoded bitstream data produced by a - video encode operation by reporting the - ename:VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR - <>. -+ -[NOTE] -.Note -==== -Some implementations may: not be able to reliably detect insufficient -bitstream buffer range conditions in all situations. -Such implementations will not report support for the -ename:VK_VIDEO_ENCODE_CAPABILITY_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_DETECTION_BIT_KHR -encode capability flag for the video profile, but may: still report the -ename:VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR query -result status code in certain cases. -Applications should: always check for the specific query result status code -ename:VK_QUERY_RESULT_STATUS_INSUFFICIENT_BITSTREAM_BUFFER_RANGE_KHR even -when this encode capability flag is not supported by the implementation for -the video profile in question. -However, applications must: not assume that a different negative query -result status code indicating an unsuccessful completion of a video encode -operation is not the result of an insufficient bitstream buffer condition -unless this encode capability flag is supported. -==== --- - - -=== Video Encode Quality Levels - -[open,refpage='vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR',desc='Query video encode quality level properties',type='protos'] --- -To query properties for a specific video encode quality level supported by a -video encode profile, call: - -include::{generated}/api/protos/vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR.adoc[] - - * pname:physicalDevice is the physical device to query the video encode - quality level properties for. - * pname:pQualityLevelInfo is a pointer to a - slink:VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR structure - specifying the video encode profile and quality level to query - properties for. - * pname:pQualityLevelProperties is a pointer to a - slink:VkVideoEncodeQualityLevelPropertiesKHR structure in which the - properties are returned. - -include::{generated}/validity/protos/vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR.adoc[] --- - - -[open,refpage='VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR',desc='Structure describing the video encode profile and quality level to query properties for',type='structs'] --- -The sname:VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR structure is -defined as: - -include::{generated}/api/structs/VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:pVideoProfile is a pointer to a slink:VkVideoProfileInfoKHR - structure specifying the video profile to query the video encode quality - level properties for. - * pname:qualityLevel is the video encode quality level to query properties - for. - -include::{generated}/validity/structs/VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR.adoc[] --- - - -[open,refpage='VkVideoEncodeQualityLevelPropertiesKHR',desc='Structure describing the video encode quality level properties',type='structs'] --- -The sname:VkVideoEncodeQualityLevelPropertiesKHR structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeQualityLevelPropertiesKHR.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:preferredRateControlMode is a - elink:VkVideoEncodeRateControlModeFlagBitsKHR value indicating the - preferred rate control mode to use with the video encode quality level. - * pname:preferredRateControlLayerCount indicates the preferred number of - rate control layers to use with the quality level. - -include::{generated}/validity/structs/VkVideoEncodeQualityLevelPropertiesKHR.adoc[] --- - - -[open,refpage='VkVideoEncodeQualityLevelInfoKHR',desc='Structure specifying used video encode quality level',type='structs'] --- -The sname:VkVideoEncodeQualityLevelInfoKHR structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeQualityLevelInfoKHR.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:qualityLevel is the used video encode quality level. - -This structure can: be specified in the following places: - - * In the pname:pNext chain of slink:VkVideoSessionParametersCreateInfoKHR - to specify the video encode quality level to use for a video session - parameters object created for a video encode session. - If no instance of this structure is included in the pname:pNext chain of - slink:VkVideoSessionParametersCreateInfoKHR, then the video session - parameters object is created with a video encode quality level of zero. - * In the pname:pNext chain of slink:VkVideoCodingControlInfoKHR to change - the video encode quality level state of the bound video session. - -include::{generated}/validity/structs/VkVideoEncodeQualityLevelInfoKHR.adoc[] --- - - -=== Retrieving Encoded Session Parameters - -Any codec-specific parameters stored in video session parameters objects -may: need to be separately encoded and included in the final video bitstream -data, depending on the used video compression standard. -In such cases the application must: call the -flink:vkGetEncodedVideoSessionParametersKHR command to retrieve the encoded -parameter data from the used video session parameters object in order to be -able to produce a compliant video bitstream. - -[open,refpage='vkGetEncodedVideoSessionParametersKHR',desc='Get encoded parameter sets from a video session parameters object',type='protos'] --- -Encoded parameter data can: be retrieved from a video session parameters -object created with a video encode operation using the command: - -include::{generated}/api/protos/vkGetEncodedVideoSessionParametersKHR.adoc[] - - * pname:device is the logical device that owns the video session - parameters object. - * pname:pVideoSessionParametersInfo is a pointer to a - slink:VkVideoEncodeSessionParametersGetInfoKHR structure specifying the - parameters of the encoded parameter data to retrieve. - * pname:pFeedbackInfo is either `NULL` or a pointer to a - slink:VkVideoEncodeSessionParametersFeedbackInfoKHR structure in which - feedback about the requested parameter data is returned. - * pname:pDataSize is a pointer to a code:size_t value related to the - amount of encode parameter data returned, as described below. - * pname:pData is either `NULL` or a pointer to a buffer to write the - encoded parameter data to. - -If pname:pData is `NULL`, then the size of the encoded parameter data, in -bytes, that can: be retrieved is returned in pname:pDataSize. -Otherwise, pname:pDataSize must: point to a variable set by the application -to the size of the buffer, in bytes, pointed to by pname:pData, and on -return the variable is overwritten with the number of bytes actually written -to pname:pData. -If pname:pDataSize is less than the size of the encoded parameter data that -can: be retrieved, then no data will be written to pname:pData, zero will be -written to pname:pDataSize, and ename:VK_INCOMPLETE will be returned instead -of ename:VK_SUCCESS, to indicate that no encoded parameter data was -returned. - -If pname:pFeedbackInfo is not `NULL` then the members of the -slink:VkVideoEncodeSessionParametersFeedbackInfoKHR structure and any -additional structures included in its pname:pNext chain that are applicable -to the video session parameters object specified in -pname:pVideoSessionParametersInfo::pname:videoSessionParameters will be -filled with feedback about the requested parameter data on all successful -calls to this command. - -[NOTE] -.Note: -==== -This includes the cases when pname:pData is `NULL` or when -ename:VK_INCOMPLETE is returned by the command, and enables the application -to determine whether the implementation overrode any of the requested video -session parameters without actually needing to retrieve the encoded -parameter data itself. -==== - -include::{generated}/validity/protos/vkGetEncodedVideoSessionParametersKHR.adoc[] --- - -[open,refpage='VkVideoEncodeSessionParametersGetInfoKHR',desc='Structure specifying parameters for retrieving encoded video session parameter data',type='structs'] --- -The sname:VkVideoEncodeSessionParametersGetInfoKHR structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeSessionParametersGetInfoKHR.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:videoSessionParameters is the slink:VkVideoSessionParametersKHR - object to retrieve encoded parameter data from. - -Depending on the used video encode operation, additional codec-specific -structures may: need to be included in the pname:pNext chain of this -structure to identify the specific video session parameters to retrieve -encoded parameter data for, as described in the corresponding sections. - -include::{generated}/validity/structs/VkVideoEncodeSessionParametersGetInfoKHR.adoc[] --- - -[open,refpage='VkVideoEncodeSessionParametersFeedbackInfoKHR',desc='Structure providing feedback about the requested video session parameters',type='structs'] --- -The sname:VkVideoEncodeSessionParametersFeedbackInfoKHR structure is defined -as: - -include::{generated}/api/structs/VkVideoEncodeSessionParametersFeedbackInfoKHR.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:hasOverrides indicates whether any of the requested parameter data - were overridden by the implementation. - -Depending on the used video encode operation, additional codec-specific -structures may: need to be included in the pname:pNext chain of this -structure to capture feedback information about the requested parameter -data, as described in the corresponding sections. - -include::{generated}/validity/structs/VkVideoEncodeSessionParametersFeedbackInfoKHR.adoc[] --- - - -=== Video Encode Commands - -[open,refpage='vkCmdEncodeVideoKHR',desc='Encode operation for bitstream generation',type='protos'] --- -To launch video encode operations, call: - -include::{generated}/api/protos/vkCmdEncodeVideoKHR.adoc[] - - * pname:commandBuffer is the command buffer to be filled with this - function for encoding to generate a bitstream. - * pname:pEncodeInfo is a pointer to a slink:VkVideoEncodeInfoKHR - structure. - -Each call issues one or more video encode operations. -The implicit parameter pname:opCount corresponds to the number of video -encode operations issued by the command. -After calling this command, the -<> of each -<> query is incremented by pname:opCount. - -Currently each call to this command results in the issue of a single video -encode operation. - -.Valid Usage -**** - * [[VUID-vkCmdEncodeVideoKHR-opCount-07174]] - For each <> query, the - <> - corresponding to the query type of that query plus pname:opCount must: - be less than or equal to the - <> corresponding to the query type of that query plus one -**** - -include::{generated}/validity/protos/vkCmdEncodeVideoKHR.adoc[] --- - -[open,refpage='VkVideoEncodeInfoKHR',desc='Structure to chain codec-specific structures to',type='structs'] --- -The sname:VkVideoEncodeInfoKHR structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeInfoKHR.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is a pointer to a structure extending this structure. - A codec-specific extension structure must: be chained to specify what - bitstream unit to generate with this encode operation. - * pname:flags is reserved for future use. - * pname:dstBuffer is the destination video bitstream buffer to write the - encoded bitstream to. - * pname:dstBufferOffset is the starting offset in bytes from the start of - pname:dstBuffer to write the encoded bitstream to. - pname:dstBufferOffset's value must: be aligned to - slink:VkVideoCapabilitiesKHR::pname:minBitstreamBufferOffsetAlignment, - as reported by the implementation. - * pname:dstBufferRange is the maximum size in bytes of the encoded - bitstream written to pname:dstBuffer, starting from - pname:dstBufferOffset. - pname:dstBufferRange's value must: be aligned to - slink:VkVideoCapabilitiesKHR::pname:minBitstreamBufferSizeAlignment, as - reported by the implementation. - * pname:srcPictureResource is the Picture Resource of the - <> to be encoded by the operation. - * pname:pSetupReferenceSlot is a pointer to a - slink:VkVideoReferenceSlotInfoKHR structure used for generating a - reconstructed reference slot and Picture Resource. - pname:pSetupReferenceSlot->slotIndex specifies the slot index number to - use as a target for producing the Reconstructed (DPB) data. - pname:pSetupReferenceSlot must: be one of the entries provided in - slink:VkVideoBeginCodingInfoKHR via the pname:pReferenceSlots within the - flink:vkCmdBeginVideoCodingKHR command that established the Vulkan Video - Encode Context for this command. - * pname:referenceSlotCount is the number of Reconstructed Reference - Pictures that will be used when this encoding operation is executing. - * pname:pReferenceSlots is `NULL` or a pointer to an array of - slink:VkVideoReferenceSlotInfoKHR structures that will be used when this - encoding operation is executing. - Each entry in pname:pReferenceSlots must: be one of the entries provided - in slink:VkVideoBeginCodingInfoKHR via the pname:pReferenceSlots within - the flink:vkCmdBeginVideoCodingKHR command that established the Vulkan - Video Encode Context for this command. - * pname:precedingExternallyEncodedBytes is the number of bytes externally - encoded for insertion in the active video encode session overall - bitstream prior to the bitstream that will be generated by the - implementation for this instance of sname:VkVideoEncodeInfoKHR. - The value provided is used to update the implementation's rate control - algorithm for the rate control layer this instance of - sname:VkVideoEncodeInfoKHR belongs to, by accounting for the bitrate - budget consumed by these externally encoded bytes. - See slink:VkVideoEncodeRateControlInfoKHR for additional information - about encode rate control. - -The coded size of the encode operation is specified in pname:codedExtent of -pname:srcPictureResource. - -Multiple flink:vkCmdEncodeVideoKHR commands may: be recorded within a Vulkan -Video Encode Context. -The execution of each flink:vkCmdEncodeVideoKHR command will result in -generating codec-specific bitstream units. -These bitstream units are generated consecutively into the bitstream buffer -specified in pname:dstBuffer of a sname:VkVideoEncodeInfoKHR structure -within the flink:vkCmdBeginVideoCodingKHR command. -The produced bitstream is the sum of all these bitstream units, including -any padding between the bitstream units. -Any bitstream padding must: be filled with data compliant to the codec -standard so as not to cause any syntax errors during decoding of the -bitstream units with the padding included. -The range of the bitstream buffer written can: be queried via -<>. - -.Valid Usage -**** - * [[VUID-VkVideoEncodeInfoKHR-None-07012]] - The bound video session must: not be in <> state at the time the command is executed on the device -**** - -include::{generated}/validity/structs/VkVideoEncodeInfoKHR.adoc[] --- - -[open,refpage='VkVideoEncodeFlagsKHR',desc='Reserved for future use',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeFlagsKHR.adoc[] - -tlink:VkVideoEncodeFlagsKHR is a bitmask type for setting a mask, but is -currently reserved for future use. --- - -[open,refpage='VkVideoEncodeRateControlInfoKHR',desc='Structure to set encode stream rate control parameters',type='structs'] --- -The sname:VkVideoEncodeRateControlInfoKHR structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeRateControlInfoKHR.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:flags is reserved for future use. - * pname:rateControlMode is a elink:VkVideoEncodeRateControlModeFlagBitsKHR - value specifying the encode stream rate control mode. - * pname:layerCount specifies the number of rate control layers in the - video encode stream. - * pname:pLayers is a pointer to an array of - slink:VkVideoEncodeRateControlLayerInfoKHR structures specifying the - rate control configurations of pname:layerCount rate control layers. - * pname:virtualBufferSizeInMs is the leaky bucket model virtual buffer - size in milliseconds, with respect to peak bitrate. - Valid when rate control mode is - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR or - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR. - For example, virtual buffer size is (pname:virtualBufferSizeInMs {times} - pname:maxBitrate / 1000). - * pname:initialVirtualBufferSizeInMs is the initial occupancy in - milliseconds of the virtual buffer in the leaky bucket model. - Valid when rate control mode is - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR or - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR. - -Including this structure in the pname:pNext chain of -slink:VkVideoCodingControlInfoKHR and including -ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR in -slink:VkVideoCodingControlInfoKHR::pname:flags will define stream rate -control settings for video encoding. - -Additional structures providing codec-specific rate control parameters may: -need to be included in the pname:pNext chain of -sname:VkVideoCodingControlInfoKHR depending on the codec profile the bound -video session was created with and the parameters specified in -sname:VkVideoEncodeRateControlInfoKHR (see <>). - -To ensure that the video session is properly initialized with stream-level -rate control settings, the application must: call -flink:vkCmdControlVideoCodingKHR with stream-level rate control settings at -least once in execution order before the first flink:vkCmdEncodeVideoKHR -command that is executed after video session reset. -If not provided, default implementation-specific stream rate control -settings will be used. - -Stream rate control settings can: also be re-initialized during an active -video encoding session. -The re-initialization takes effect whenever the -sname:VkVideoEncodeRateControlInfoKHR structure is included in the -pname:pNext chain of the slink:VkVideoCodingControlInfoKHR structure in the -call to flink:vkCmdControlVideoCodingKHR, and only impacts -flink:vkCmdEncodeVideoKHR operations that follow in execution order. - -include::{generated}/validity/structs/VkVideoEncodeRateControlInfoKHR.adoc[] --- - -[open,refpage='VkVideoEncodeRateControlFlagsKHR',desc='Reserved for future use',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeRateControlFlagsKHR.adoc[] - -tname:VkVideoEncodeRateControlFlagsKHR is a bitmask type for setting a mask, -but currently reserved for future use. --- - -[open,refpage='VkVideoEncodeRateControlModeFlagBitsKHR',desc='Video encode rate control modes',type='enums'] --- -The rate control modes are defined with the following enums: - -include::{generated}/api/enums/VkVideoEncodeRateControlModeFlagBitsKHR.adoc[] - - * ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR specifies the use of - implementation-specific rate control. - * ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR specifies that - rate control is disabled and any quality control parameters for the - encoding are provided on a per-picture basis. - In this mode implementations will encode pictures independently of the - output bitrate of prior video encode operations. -ifdef::VK_EXT_video_encode_h264[] - When using an H.264 encode profile, implementations will use the QP - values specified in the slink:VkVideoEncodeH264RateControlInfoEXT - structure for the encoded picture. -endif::VK_EXT_video_encode_h264[] -ifdef::VK_EXT_video_encode_h265[] - When using an H.265 encode profile, implementations will use the QP - values specified in the slink:VkVideoEncodeH265RateControlInfoEXT - structure for the encoded picture. -endif::VK_EXT_video_encode_h265[] - * ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR specifies the use of - constant bitrate rate control mode. - * ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR specifies the use of - variable bitrate rate control mode. --- - -[open,refpage='VkVideoEncodeRateControlModeFlagsKHR',desc='Bitmask of VkVideoEncodeRateControlModeFlagBitsKHR', type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeRateControlModeFlagsKHR.adoc[] - -tname:VkVideoEncodeRateControlModeFlagsKHR is a bitmask type for setting a -mask of zero or more elink:VkVideoEncodeRateControlModeFlagBitsKHR. --- - -[open,refpage='VkVideoEncodeRateControlLayerInfoKHR',desc='Structure to set encode per-layer rate control parameters',type='structs'] --- -The sname:VkVideoEncodeRateControlLayerInfoKHR structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeRateControlLayerInfoKHR.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is a pointer to a structure extending this structure. - * pname:averageBitrate is the average bitrate in bits/second. - Valid when rate control mode is - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR or - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR. - * pname:maxBitrate is the peak bitrate in bits/second. - Valid when rate control mode is - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR. - * pname:frameRateNumerator is the numerator of the frame rate. - Valid when rate control mode is - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR or - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR. - * pname:frameRateDenominator is the denominator of the frame rate. - Valid when rate control mode is - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR or - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR. - -A codec-specific structure specifying additional per-layer rate control -settings must: be chained to sname:VkVideoEncodeRateControlLayerInfoKHR. -If multiple rate control layers are enabled -(slink:VkVideoEncodeRateControlInfoKHR::pname:layerCount is greater than 1), -then the chained codec-specific extension structure also identifies the -specific video coding layer its parent -sname:VkVideoEncodeRateControlLayerInfoKHR applies to. -If multiple rate control layers are enabled, the number of rate control -layers must: match the number of video coding layers. -The specification for an encode codec-specific extension would describe how -multiple video coding layers are enabled for the corresponding codec. - -Per-layer rate control settings for all enabled rate control layers must: be -initialized or re-initialized whenever stream rate control settings are -provided via slink:VkVideoEncodeRateControlInfoKHR. -This is done by specifying settings for all enabled rate control layers in -slink:VkVideoEncodeRateControlInfoKHR::pname:pLayers. - -It is possible for an application to enable multiple video coding layers -(via codec-specific extensions to encoding operations) while only enabling a -single layer of rate control for the entire video stream. -To achieve this, pname:layerCount in slink:VkVideoEncodeRateControlInfoKHR -must: be set to 1, and the single sname:VkVideoEncodeRateControlLayerInfoKHR -provided in pname:pLayers would apply to all encoded segments of the video -stream, regardless of which codec-defined video coding layer they belong to. -In this case, the implementation decides bitrate distribution across video -coding layers (if applicable to the specified stream rate control mode). - -include::{generated}/validity/structs/VkVideoEncodeRateControlLayerInfoKHR.adoc[] --- - diff --git a/chapters/video_encode_h264_extensions.adoc b/chapters/video_encode_h264_extensions.adoc deleted file mode 100644 index eb81e9734..000000000 --- a/chapters/video_encode_h264_extensions.adoc +++ /dev/null @@ -1,755 +0,0 @@ -// Copyright 2018-2023 The Khronos Group Inc. -// -// SPDX-License-Identifier: CC-BY-4.0 - -[[encode-h264]] -== Encode H.264 - -The `apiext:VK_EXT_video_encode_h264` extension adds H.264 codec specific -structures/types needed to support H.264 encoding. -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 https://www.itu.int/rec/T-REC-H.264. - -[NOTE] -.Note -==== -Refer to the <> for information on how the Khronos -Intellectual Property Rights Policy relates to normative references to -external materials not created by Khronos. -==== - - -=== H.264 Encode Profile - -[open,refpage='VkVideoEncodeH264ProfileInfoEXT',desc='Structure specifying H.264 encode profile',type='structs'] --- -The sname:VkVideoEncodeH264ProfileInfoEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH264ProfileInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying 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. - -An H.264 encode profile is specified by including a -sname:VkVideoEncodeH264ProfileInfoEXT structure in the pname:pNext chain of -the slink:VkVideoProfileInfoKHR structure when -slink:VkVideoProfileInfoKHR::pname:videoCodecOperation is -ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT. - -include::{generated}/validity/structs/VkVideoEncodeH264ProfileInfoEXT.adoc[] --- - - -=== Capabilities - -[open,refpage='VkVideoEncodeH264CapabilitiesEXT',desc='Structure specifying H.264 encode capabilities',type='structs'] --- -When calling flink:vkGetPhysicalDeviceVideoCapabilitiesKHR with -pname:pVideoProfile->videoCodecOperation specified as -ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT, the -slink:VkVideoEncodeH264CapabilitiesEXT structure must: be included in the -pname:pNext chain of the slink:VkVideoCapabilitiesKHR structure to retrieve -more capabilities specific to H.264 video encoding. - -The slink:VkVideoEncodeH264CapabilitiesEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH264CapabilitiesEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:flags is a bitmask of elink:VkVideoEncodeH264CapabilityFlagBitsEXT - indicating supported H.264 encoding capabilities. - * pname:maxLevelIdc is a code:StdVideoH264LevelIdc value indicating the - maximum H.264 level supported. - * pname:maxSliceCount indicates the maximum number of slices that can: be - encoded for a single picture. - Further restrictions may: apply to the number of slices that can: be - encoded for a single picture depending on other capabilities and - codec-specific rules. - * pname:maxPPictureL0ReferenceCount indicates the maximum number of - reference pictures the implementation supports in the reference list L0 - for P pictures. - * pname:maxBPictureL0ReferenceCount indicates the maximum number of - reference pictures the implementation supports in the reference list L0 - for B pictures. - The reported value is `0` if encoding of B pictures is not supported. - * pname:maxL1ReferenceCount reports the maximum number of reference - pictures the implementation supports in the reference list L1 if - encoding of B pictures is supported. - The reported value is `0` if encoding of B pictures is not supported. - * pname:maxTemporalLayerCount indicates the maximum number of H.264 - temporal layers supported by the implementation. - * pname:expectDyadicTemporalLayerPattern indicates that the - implementation's rate control algorithms expect the application to use a - dyadic temporal layer pattern when encoding multiple temporal layers. - * pname:minQp indicates the minimum QP value supported. - * pname:maxQp indicates the maximum QP value supported. - * pname:prefersGopRemainingFrames indicates that the implementation's rate - control algorithm prefers the application to specify the number of - frames of each type remaining in the current group of pictures. - * pname:requiresGopRemainingFrames indicates that the implementation's - rate control algorithm requires the application to specify the number of - frames of each type remaining in the current group of pictures. - * pname:stdSyntaxFlags is a bitmask of - elink:VkVideoEncodeH264StdFlagBitsEXT indicating capabilities related to - H.264 syntax elements. - -When flink:vkGetPhysicalDeviceVideoCapabilitiesKHR is called to query the -capabilities with parameter pname:videoCodecOperation specified as -ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT, a -sname:VkVideoEncodeH264CapabilitiesEXT structure can: be chained to -slink:VkVideoCapabilitiesKHR to retrieve H.264 extension specific -capabilities. - -include::{generated}/validity/structs/VkVideoEncodeH264CapabilitiesEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH264CapabilityFlagBitsEXT',desc='Video encode H.264 capability flags',type='enums'] --- -Bits which may: be set in -slink:VkVideoEncodeH264CapabilitiesEXT::pname:flags, indicating the -supported H.264 encoding capabilities, are: - -include::{generated}/api/enums/VkVideoEncodeH264CapabilityFlagBitsEXT.adoc[] - - * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_HRD_COMPLIANCE_BIT_EXT indicates - if the implementation guarantees generating a HRD compliant bitstream if - code:nal_hrd_parameters_present_flag or - code:vcl_hrd_parameters_present_flag are enabled in - code:StdVideoH264SpsVuiFlags. - * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_EXT - indicates that when code:weighted_pred_flag is enabled or - code:STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICIT from - code:StdVideoH264WeightedBipredIdc is used, the implementation is able - to internally decide syntax for code:pred_weight_table. - * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_ROW_UNALIGNED_SLICE_BIT_EXT - indicates that each slice in a frame with multiple slices may begin or - finish at any offset in a macroblock row. - If not supported, all slices in the frame must: begin at the start of a - macroblock row (and hence each slice must: finish at the end of a - macroblock row). - * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_EXT - indicates that when a frame is encoded with multiple slices, the - implementation allows encoding each slice with a different - code:StdVideoEncodeH264SliceHeader::code:slice_type. - If not supported, all slices of the frame must: be encoded with the same - code:slice_type which corresponds to the picture type of the frame. - For example, all slices of a P-frame would be encoded as P-slices. - * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_EXT - indicates support for using a B frame as L0 reference. - * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_EXT - indicates support for using a B frame as L1 reference. - * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_EXT - indicates support for specifying different QP values in the members of - slink:VkVideoEncodeH264QpEXT. - * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_PER_SLICE_CONSTANT_QP_BIT_EXT - indicates support for specifying different constant QP values for each - slice. - * ename:VK_VIDEO_ENCODE_H264_CAPABILITY_GENERATE_PREFIX_NALU_BIT_EXT - indicates support for generating prefix NALUs by setting - slink:VkVideoEncodeH264PictureInfoEXT::pname:generatePrefixNalu to - ename:VK_TRUE. --- - -[open,refpage='VkVideoEncodeH264CapabilityFlagsEXT',desc='Bitmask of VkVideoEncodeH264CapabilityFlagBitsEXT',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeH264CapabilityFlagsEXT.adoc[] - -tname:VkVideoEncodeH264CapabilityFlagsEXT is a bitmask type for setting a -mask of zero or more elink:VkVideoEncodeH264CapabilityFlagBitsEXT. --- - -[open,refpage='VkVideoEncodeH264StdFlagBitsEXT',desc='Video encode H.264 syntax capability flags',type='enums'] --- -Bits which may: be set in -slink:VkVideoEncodeH264CapabilitiesEXT::pname:stdSyntaxFlags, indicating the -capabilities related to the H.264 syntax elements, are: - -include::{generated}/api/enums/VkVideoEncodeH264StdFlagBitsEXT.adoc[] - - * ename:VK_VIDEO_ENCODE_H264_STD_SEPARATE_COLOR_PLANE_FLAG_SET_BIT_EXT - indicates if enabling code:separate_colour_plane_flag in - code:StdVideoH264SpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_QPPRIME_Y_ZERO_TRANSFORM_BYPASS_FLAG_SET_BIT_EXT - indicates if enabling code:qpprime_y_zero_transform_bypass_flag in - code:StdVideoH264SpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_SCALING_MATRIX_PRESENT_FLAG_SET_BIT_EXT - indicates if enabling code:seq_scaling_matrix_present_flag in - code:StdVideoH264SpsFlags or code:pic_scaling_matrix_present_flag in - code:StdVideoH264PpsFlags are supported. - * ename:VK_VIDEO_ENCODE_H264_STD_CHROMA_QP_INDEX_OFFSET_BIT_EXT indicates - if setting non-zero code:chroma_qp_index_offset in - code:StdVideoH264PictureParameterSet is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_SECOND_CHROMA_QP_INDEX_OFFSET_BIT_EXT - indicates if setting non-zero code:second_chroma_qp_index_offset in - code:StdVideoH264PictureParameterSet is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_PIC_INIT_QP_MINUS26_BIT_EXT indicates if - setting non-zero code:pic_init_qp_minus26 in - code:StdVideoH264PictureParameterSet is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_WEIGHTED_PRED_FLAG_SET_BIT_EXT indicates - if enabling code:weighted_pred_flag in code:StdVideoH264PpsFlags is - supported. - * ename:VK_VIDEO_ENCODE_H264_STD_WEIGHTED_BIPRED_IDC_EXPLICIT_BIT_EXT - indicates if using code:STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_EXPLICIT from - code:StdVideoH264WeightedBipredIdc is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_WEIGHTED_BIPRED_IDC_IMPLICIT_BIT_EXT - indicates if using code:STD_VIDEO_H264_WEIGHTED_BIPRED_IDC_IMPLICIT from - code:StdVideoH264WeightedBipredIdc is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_TRANSFORM_8X8_MODE_FLAG_SET_BIT_EXT - indicates if enabling code:transform_8x8_mode_flag in - code:StdVideoH264PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_DIRECT_SPATIAL_MV_PRED_FLAG_UNSET_BIT_EXT - indicates if disabling - code:StdVideoEncodeH264SliceHeaderFlags::code:direct_spatial_mv_pred_flag - is supported when it is present in the slice header. - * ename:VK_VIDEO_ENCODE_H264_STD_ENTROPY_CODING_MODE_FLAG_UNSET_BIT_EXT - indicates if CAVLC entropy coding is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_ENTROPY_CODING_MODE_FLAG_SET_BIT_EXT - indicates if CABAC entropy coding is supported. - An implementation must: support at least one entropy coding mode. - * ename:VK_VIDEO_ENCODE_H264_STD_DIRECT_8X8_INFERENCE_FLAG_UNSET_BIT_EXT - indicates if disabling code:direct_8x8_inference_flag in - code:StdVideoH264SpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_CONSTRAINED_INTRA_PRED_FLAG_SET_BIT_EXT - indicates if enabling code:constrained_intra_pred_flag in - code:StdVideoH264PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_DISABLED_BIT_EXT - indicates if using - code:STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_DISABLED from - StdVideoH264DisableDeblockingFilterIdc is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_ENABLED_BIT_EXT - indicates if using - code:STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_ENABLED from - StdVideoH264DisableDeblockingFilterIdc is supported. - * ename:VK_VIDEO_ENCODE_H264_STD_DEBLOCKING_FILTER_PARTIAL_BIT_EXT - indicates if using - code:STD_VIDEO_H264_DISABLE_DEBLOCKING_FILTER_IDC_PARTIAL from - StdVideoH264DisableDeblockingFilterIdc is supported. - An implementation must: support at least one deblocking filter mode. - * ename:VK_VIDEO_ENCODE_H264_STD_SLICE_QP_DELTA_BIT_EXT indicates whether - the implementation supports using the application-provided value for - code:StdVideoEncodeH264SliceHeader::code:slice_qp_delta when that value - is identical across the slices of the encoded frame. - * ename:VK_VIDEO_ENCODE_H264_STD_DIFFERENT_SLICE_QP_DELTA_BIT_EXT - indicates whether the implementation supports using the - application-provided value for - code:StdVideoEncodeH264SliceHeader::code:slice_qp_delta when that value - is different across the slices of the encoded frame. --- - -[open,refpage='VkVideoEncodeH264StdFlagsEXT',desc='Bitmask of VkVideoEncodeH264StdFlagBitsEXT',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeH264StdFlagsEXT.adoc[] - -tname:VkVideoEncodeH264StdFlagsEXT is a bitmask type for setting a mask of -zero or more elink:VkVideoEncodeH264StdFlagBitsEXT. --- - - -=== H.264 Encode Quality Level Properties - -[open,refpage='VkVideoEncodeH264QualityLevelPropertiesEXT',desc='Structure describing the H.264 encode quality level properties',type='structs'] --- -When calling flink:vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR -with pname:pVideoProfile->videoCodecOperation specified as -ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT, the -slink:VkVideoEncodeH264QualityLevelPropertiesEXT structure can: be included -in the pname:pNext chain of the slink:VkVideoEncodeQualityLevelPropertiesKHR -structure to retrieve additional video encode quality level properties -specific to H.264 encoding. - -The slink:VkVideoEncodeH264QualityLevelPropertiesEXT structure is defined -as: - -include::{generated}/api/structs/VkVideoEncodeH264QualityLevelPropertiesEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:preferredRateControlFlags is a bitmask of - elink:VkVideoEncodeH264RateControlFlagBitsEXT values indicating the - preferred flags to use for - slink:VkVideoEncodeH264RateControlInfoEXT::pname:flags. - * pname:preferredGopFrameCount indicates the preferred value to use for - slink:VkVideoEncodeH264RateControlInfoEXT::pname:gopFrameCount. - * pname:preferredIdrPeriod indicates the preferred value to use for - slink:VkVideoEncodeH264RateControlInfoEXT::pname:idrPeriod. - * pname:preferredConsecutiveBFrameCount indicates the preferred value to - use for - slink:VkVideoEncodeH264RateControlInfoEXT::pname:consecutiveBFrameCount. - * pname:preferredTemporalLayerCount indicates the preferred value to use - for slink:VkVideoEncodeH264RateControlInfoEXT::pname:temporalLayerCount. - * pname:preferredConstantQp indicates the preferred values to use for - slink:VkVideoEncodeH264NaluSliceInfoEXT::pname:constantQp for each - picture type when using rate control mode - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. - * pname:preferredMaxL0ReferenceCount indicates the preferred maximum - number of reference pictures to use in the reference list L0. - * pname:preferredMaxL1ReferenceCount indicates the preferred maximum - number of reference pictures to use in the reference list L1. - * pname:preferredStdEntropyCodingModeFlag indicates the preferred value to - use for code:entropy_coding_mode_flag in code:StdVideoH264PpsFlags. - -include::{generated}/validity/structs/VkVideoEncodeH264QualityLevelPropertiesEXT.adoc[] --- - - -=== H.264 Encode Session - -Additional parameters can be specified when creating a video session with an -H.264 encode profile by including an instance of the -slink:VkVideoEncodeH264SessionCreateInfoEXT structure in the pname:pNext -chain of slink:VkVideoSessionCreateInfoKHR. - -[open,refpage='VkVideoEncodeH264SessionCreateInfoEXT',desc='Structure specifies H.264 encode session parameters',type='structs'] --- -The sname:VkVideoEncodeH264SessionCreateInfoEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH264SessionCreateInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:useMaxLevelIdc indicates whether the value of pname:maxLevelIdc - should be used by the implementation. - When it is set to ename:VK_FALSE, the implementation ignores the value - of pname:maxLevelIdc and uses the value of - slink:VkVideoEncodeH264CapabilitiesEXT::pname:maxLevelIdc, as reported - by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile. - * pname:maxLevelIdc provides the upper bound on the H.264 level for the - video bitstreams produced by the created video session. - -include::{generated}/validity/structs/VkVideoEncodeH264SessionCreateInfoEXT.adoc[] --- - - -=== Encoder Parameter Sets - -To reduce parameter traffic during encoding, the encoder parameter set -object supports storing H.264 SPS/PPS parameter sets that may: be later -referenced during encoding. - -[open,refpage='VkVideoEncodeH264SessionParametersCreateInfoEXT',desc='Structure specifies H.264 encoder parameter set information',type='structs'] --- -The slink:VkVideoEncodeH264SessionParametersCreateInfoEXT structure is -defined as: - -include::{generated}/api/structs/VkVideoEncodeH264SessionParametersCreateInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:maxStdSPSCount is the maximum number of SPS parameters that the - sname:VkVideoSessionParametersKHR can contain. - * pname:maxStdPPSCount is the maximum number of PPS parameters that the - sname:VkVideoSessionParametersKHR can contain. - * pname:pParametersAddInfo is `NULL` or a pointer to a - sname:VkVideoEncodeH264SessionParametersAddInfoEXT structure specifying - H.264 parameters to add upon object creation. - -include::{generated}/validity/structs/VkVideoEncodeH264SessionParametersCreateInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH264SessionParametersAddInfoEXT',desc='Structure specifies H.264 encoder parameter set information',type='structs'] --- -The sname:VkVideoEncodeH264SessionParametersAddInfoEXT structure is defined -as: - -include::{generated}/api/structs/VkVideoEncodeH264SessionParametersAddInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:stdSPSCount is the number of SPS elements in the pname:pStdSPSs. - Its value must: be less than or equal to the value of - pname:maxStdSPSCount. - * pname:pStdSPSs 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:stdPPSCount is the number of PPS provided in pname:pStdPPSs. - Its value must: be less than or equal to the value of - pname:maxStdPPSCount. - * pname:pStdPPSs 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-VkVideoEncodeH264SessionParametersAddInfoEXT-stdSPSCount-04837]] - The values of pname:stdSPSCount and pname:stdPPSCount must: be less than - or equal to the values of pname:maxStdSPSCount and pname:maxStdPPSCount, - respectively - * [[VUID-VkVideoEncodeH264SessionParametersAddInfoEXT-maxStdSPSCount-04838]] - When the pname:maxStdSPSCount number of parameters of type - StdVideoH264SequenceParameterSet 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-VkVideoEncodeH264SessionParametersAddInfoEXT-maxStdPPSCount-04839]] - When the pname:maxStdPPSCount number of parameters of type - StdVideoH264PictureParameterSet 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-VkVideoEncodeH264SessionParametersAddInfoEXT-None-04840]] - 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-VkVideoEncodeH264SessionParametersAddInfoEXT-None-04841]] - Parameter entries that already exist in Video Session Parameters object - with a particular SPS-PPS IDs cannot: be replaced nor updated - * [[VUID-VkVideoEncodeH264SessionParametersAddInfoEXT-None-04842]] - 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-VkVideoEncodeH264SessionParametersAddInfoEXT-None-04843]] - SPS/PPS parameters must: comply with the limits specified in - slink:VkVideoSessionCreateInfoKHR during Video Session creation -**** - -include::{generated}/validity/structs/VkVideoEncodeH264SessionParametersAddInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH264SessionParametersGetInfoEXT',desc='Structure specifying parameters for retrieving encoded H.264 parameter set data',type='structs'] --- -The sname:VkVideoEncodeH264SessionParametersGetInfoEXT structure is defined -as: - -include::{generated}/api/structs/VkVideoEncodeH264SessionParametersGetInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:writeStdSPS indicates whether the encoded H.264 sequence parameter - set identified by pname:stdSPSId is requested to be retrieved. - * pname:writeStdPPS indicates whether the encoded H.264 picture parameter - set identified by the pair constructed from pname:stdSPSId and - pname:stdPPSId is requested to be retrieved. - * pname:stdSPSId specifies the H.264 sequence parameter set ID used to - identify the retrieved H.264 sequence and/or picture parameter set(s). - * pname:stdPPSId specifies the H.264 picture parameter set ID used to - identify the retrieved H.264 picture parameter set when - pname:writeStdPPS is set to ename:VK_TRUE. - -When this structure is specified in the pname:pNext chain of the -slink:VkVideoEncodeSessionParametersGetInfoKHR structure passed to -flink:vkGetEncodedVideoSessionParametersKHR, the command will write encoded -parameter data to the output buffer in the following order: - - . The H.264 sequence parameter set identified by pname:stdSPSId, if - pname:writeStdSPS is set to ename:VK_TRUE. - . The H.264 picture parameter set identified by the pair constructed from - pname:stdSPSId and pname:stdPPSId, if pname:writeStdPPS is set to - ename:VK_TRUE. - -include::{generated}/validity/structs/VkVideoEncodeH264SessionParametersGetInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH264SessionParametersFeedbackInfoEXT',desc='Structure providing feedback about the requested H.264 video session parameters',type='structs'] --- -The sname:VkVideoEncodeH264SessionParametersFeedbackInfoEXT structure is -defined as: - -include::{generated}/api/structs/VkVideoEncodeH264SessionParametersFeedbackInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:hasStdSPSOverrides indicates whether any of the parameters of the - requested H.264 sequence parameter set, if one was requested via - slink:VkVideoEncodeH264SessionParametersGetInfoEXT::pname:writeStdSPS, - were overridden by the implementation. - * pname:hasStdPPSOverrides indicates whether any of the parameters of the - requested H.264 picture parameter set, if one was requested via - slink:VkVideoEncodeH264SessionParametersGetInfoEXT::pname:writeStdPPS, - were overridden by the implementation. - -include::{generated}/validity/structs/VkVideoEncodeH264SessionParametersFeedbackInfoEXT.adoc[] --- - - -=== Frame Encoding - -In order to encode a frame, add a slink:VkVideoEncodeH264PictureInfoEXT -structure to the pname:pNext chain of the slink:VkVideoEncodeInfoKHR -structure passed to the flink:vkCmdEncodeVideoKHR command. - -[open,refpage='VkVideoEncodeH264PictureInfoEXT',desc='Structure specifies H.264 encode frame parameters',type='structs'] --- -The slink:VkVideoEncodeH264PictureInfoEXT structure representing a frame -encode operation is defined as: - -include::{generated}/api/structs/VkVideoEncodeH264PictureInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:naluSliceEntryCount is the number of slice NALUs in the frame. - * pname:pNaluSliceEntries is a pointer to an array of - pname:naluSliceEntryCount slink:VkVideoEncodeH264NaluSliceInfoEXT - structures specifying the division of the current picture into slices - and the properties of these slices. - This is an ordered sequence; the NALUs are generated consecutively in - slink:VkVideoEncodeInfoKHR::pname:dstBuffer in the same order as in this - array. - * pname:pStdPictureInfo is a pointer to a - code:StdVideoEncodeH264PictureInfo structure specifying the syntax and - other codec-specific information from the H.264 specification associated - with this picture. - The information provided must: reflect the decoded picture marking - operations that are applicable to this frame. - * pname:generatePrefixNalu controls whether prefix NALUs are generated - before slice NALUs into the target bitstream. - -include::{generated}/validity/structs/VkVideoEncodeH264PictureInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH264NaluSliceInfoEXT',desc='Structure specifies H.264 encode slice NALU parameters',type='structs'] --- -The slink:VkVideoEncodeH264NaluSliceInfoEXT structure representing a slice -is defined as: - -include::{generated}/api/structs/VkVideoEncodeH264NaluSliceInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:constantQp is the QP to use for the slice if the current rate - control mode configured for the video session is - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. - * pname:pStdSliceHeader is a pointer to a - code:StdVideoEncodeH264SliceHeader structure specifying the slice header - for the current slice. - -include::{generated}/validity/structs/VkVideoEncodeH264NaluSliceInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH264DpbSlotInfoEXT',desc='Structure specifies H.264 encode DPB picture information',type='structs'] --- -The slink:VkVideoEncodeH264DpbSlotInfoEXT structure, representing a -reconstructed picture that is being used as a reference picture, is defined -as: - -include::{generated}/api/structs/VkVideoEncodeH264DpbSlotInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:pStdReferenceInfo is a pointer to a - code:StdVideoEncodeH264ReferenceInfo structure specifying the syntax and - other codec-specific information from the H.264 specification associated - with this reference picture. - -include::{generated}/validity/structs/VkVideoEncodeH264DpbSlotInfoEXT.adoc[] --- - - -=== Rate Control - -[open,refpage='VkVideoEncodeH264RateControlInfoEXT',desc='Structure describing H.264 stream rate control parameters',type='structs'] --- -The sname:VkVideoEncodeH264RateControlInfoEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH264RateControlInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:flags is a bitmask of - elink:VkVideoEncodeH264RateControlFlagBitsEXT specifying H.264 rate - control flags. - * pname:gopFrameCount is the number of frames contained within the group - of pictures (GOP), starting from an intra frame and until the next intra - frame. - If it is set to 0, the implementation chooses a suitable value. - If it is set to code:UINT32_MAX, the GOP length is treated as infinite. - * pname:idrPeriod is the interval, in terms of number of frames, between - two IDR frames. - If it is set to 0, the implementation chooses a suitable value. - If it is set to code:UINT32_MAX, the IDR period is treated as infinite. - * pname:consecutiveBFrameCount is the number of consecutive B-frames - between I- and/or P-frames within the GOP. - * pname:temporalLayerCount specifies the number of temporal layers enabled - in the stream. - -In order to provide H.264-specific stream rate control parameters, add a -sname:VkVideoEncodeH264RateControlInfoEXT structure to the pname:pNext chain -of the slink:VkVideoEncodeRateControlInfoKHR structure in the pname:pNext -chain of the slink:VkVideoCodingControlInfoKHR structure passed to the -flink:vkCmdControlVideoCodingKHR command. - -The parameters from this structure act as a guidance for implementations to -apply various rate control heuristics. - -It is possible to infer the picture type to be used when encoding a frame, -on the basis of the values provided for pname:consecutiveBFrameCount, -pname:idrPeriod, and pname:gopFrameCount, but this inferred picture type -will not be used by implementations to override the picture type provided in -flink:vkCmdEncodeVideoKHR. -Additionally, it is not required for the video session to be reset if the -inferred picture type does not match the actual picture type. - -include::{generated}/validity/structs/VkVideoEncodeH264RateControlInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH264RateControlFlagBitsEXT',desc='H.264 encode rate control bits',type='enums'] --- -Bits which can: be set in -slink:VkVideoEncodeH264RateControlInfoEXT::pname:flags, specifying H.264 -rate control flags, are: - -include::{generated}/api/enums/VkVideoEncodeH264RateControlFlagBitsEXT.adoc[] - - * ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_EXT - specifies that rate control should: attempt to produce an HRD compliant - bitstream. - * ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REGULAR_GOP_BIT_EXT specifies - that the application intends to use a regular GOP structure according to - the parameters specified in the pname:gopFrameCount, pname:idrPeriod, - and pname:consecutiveBFrameCount members of the - slink:VkVideoEncodeH264RateControlInfoEXT structure. - * ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_EXT - specifies that the application intends to follow a flat reference - pattern. - * ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_EXT - specifies that the application intends to follow a dyadic reference - pattern. - * ename:VK_VIDEO_ENCODE_H264_RATE_CONTROL_TEMPORAL_LAYER_PATTERN_DYADIC_BIT_EXT - specifies that the application intends to follow a dyadic temporal layer - pattern. --- - - -[open,refpage='VkVideoEncodeH264RateControlFlagsEXT',desc='Bitmask specifying H.264 encode rate control flags',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeH264RateControlFlagsEXT.adoc[] - -tname:VkVideoEncodeH264RateControlFlagsEXT is a bitmask type for setting a -mask of zero or more elink:VkVideoEncodeH264RateControlFlagBitsEXT. --- - - -[open,refpage='VkVideoEncodeH264RateControlLayerInfoEXT',desc='Structure describing H.264 per-layer rate control parameters',type='structs'] --- -The sname:VkVideoEncodeH264RateControlLayerInfoEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH264RateControlLayerInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:useMinQp indicates whether the values within pname:minQp should be - used by the implementation. - When it is set to ename:VK_FALSE, the implementation ignores the values - in pname:minQp and chooses suitable values. - * pname:minQp provides the lower bound on the QP values for each picture - type, to be used in rate control calculations. - * pname:useMaxQp indicates whether the values within pname:maxQp should be - used by the implementation. - When it is set to ename:VK_FALSE, the implementation ignores the values - in pname:maxQp and chooses suitable values. - * pname:maxQp provides the upper bound on the QP values for each picture - type, to be used in rate control calculations. - * pname:useMaxFrameSize indicates whether the values within - pname:maxFrameSize should be used by the implementation. - * pname:maxFrameSize provides the upper bound on the encoded frame size - for each picture type. - The implementation does not guarantee the encoded frame sizes will be - within the specified limits, however these limits may: be used as a - guide in rate control calculations. - If enabled and not set properly, the pname:maxQp limit may prevent the - implementation from respecting the pname:maxFrameSize limit. - -H.264-specific per-layer rate control parameters must: be specified by -adding a sname:VkVideoEncodeH264RateControlLayerInfoEXT structure to the -pname:pNext chain of each slink:VkVideoEncodeRateControlLayerInfoKHR -structure in a call to flink:vkCmdControlVideoCodingKHR command, when the -command buffer context has an active video encode H.264 session. - -include::{generated}/validity/structs/VkVideoEncodeH264RateControlLayerInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH264QpEXT',desc='Structure describing H.264 QP values per picture type',type='structs'] --- -The sname:VkVideoEncodeH264QpEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH264QpEXT.adoc[] - - * pname:qpI is the QP to be used for I-frames. - * pname:qpP is the QP to be used for P-frames. - * pname:qpB is the QP to be used for B-frames. - -include::{generated}/validity/structs/VkVideoEncodeH264QpEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH264FrameSizeEXT',desc='Structure describing frame size values per H.264 picture type',type='structs'] --- -The sname:VkVideoEncodeH264FrameSizeEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH264FrameSizeEXT.adoc[] - - * pname:frameISize is the size in bytes to be used for I-frames. - * pname:framePSize is the size in bytes to be used for P-frames. - * pname:frameBSize is the size in bytes to be used for B-frames. - -include::{generated}/validity/structs/VkVideoEncodeH264FrameSizeEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH264GopRemainingFrameInfoEXT',desc='Structure specifying H.264 encode rate control GOP remaining frame counts',type='structs'] --- -The sname:VkVideoEncodeH264GopRemainingFrameInfoEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH264GopRemainingFrameInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:useGopRemainingFrames indicates whether the implementation's rate - control algorithm should: use the values specified in - pname:gopRemainingI, pname:gopRemainingP, and pname:gopRemainingB. - If pname:useGopRemainingFrames is ename:VK_FALSE, then the values of - pname:gopRemainingI, pname:gopRemainingP, and pname:gopRemainingB are - ignored. - * pname:gopRemainingI specifies the number of I-frames the - implementation's rate control algorithm should: assume to be remaining - in the GOP prior to executing the video encode operation. - * pname:gopRemainingP specifies the number of P-frames the - implementation's rate control algorithm should: assume to be remaining - in the GOP prior to executing the video encode operation. - * pname:gopRemainingB specifies the number of B-frames the - implementation's rate control algorithm should: assume to be remaining - in the GOP prior to executing the video encode operation. - -Setting pname:useGopRemainingFrames to ename:VK_TRUE and including this -structure in the pname:pNext chain of slink:VkVideoEncodeInfoKHR is only -mandatory if the -slink:VkVideoEncodeH264CapabilitiesEXT::pname:requiresGopRemainingFrames -reported for the used <> is ename:VK_TRUE. -However, implementations may: use these remaining frame counts, when -specified, even when it is not required. -In particular, when the application does not use a regular GOP structure, -these values may: provide additional guidance for the implementation's rate -control algorithm. - -The slink:VkVideoEncodeH264CapabilitiesEXT::pname:prefersGopRemainingFrames -capability is also used to indicate that the implementation's rate control -algorithm may: operate more accurately if the application specifies the -remaining frame counts using this structure. - -As with other rate control guidance values, if the effective order and -number of frames encoded by the application are not in line with the -remaining frame counts specified in this structure at any given point, then -the behavior of the implementation's rate control algorithm may: deviate -from the one expected by the application. - -include::{generated}/validity/structs/VkVideoEncodeH264GopRemainingFrameInfoEXT.adoc[] --- diff --git a/chapters/video_encode_h265_extensions.adoc b/chapters/video_encode_h265_extensions.adoc deleted file mode 100644 index 1802994fc..000000000 --- a/chapters/video_encode_h265_extensions.adoc +++ /dev/null @@ -1,857 +0,0 @@ -// Copyright 2018-2023 The Khronos Group Inc. -// -// SPDX-License-Identifier: CC-BY-4.0 - -[[encode-h265]] -== Encode H.265 - -The `apiext:VK_EXT_video_encode_h265` extension adds H.265 codec-specific -structures/types needed to support H.265 video encoding. -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 https://www.itu.int/rec/T-REC-H.265. - -[NOTE] -.Note -==== -Refer to the <> for information on how the Khronos -Intellectual Property Rights Policy relates to normative references to -external materials not created by Khronos. -==== - - -=== H.265 Encode Profile - -An H.265 encode profile is specified by including the -slink:VkVideoEncodeH265ProfileInfoEXT structure in the pname:pNext chain of -the slink:VkVideoProfileInfoKHR structure when -slink:VkVideoProfileInfoKHR::pname:videoCodecOperation is -ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT. - -[open,refpage='VkVideoEncodeH265ProfileInfoEXT',desc='Structure specifying H.265 encode profile',type='structs'] --- -The sname:VkVideoEncodeH265ProfileInfoEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH265ProfileInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying 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/VkVideoEncodeH265ProfileInfoEXT.adoc[] --- - - -=== Capabilities - -[open,refpage='VkVideoEncodeH265CapabilitiesEXT',desc='Structure specifying H.265 encode capabilities',type='structs'] --- -When calling flink:vkGetPhysicalDeviceVideoCapabilitiesKHR with -pname:pVideoProfile->videoCodecOperation specified as -ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT, the -slink:VkVideoEncodeH265CapabilitiesEXT structure must: be included in the -pname:pNext chain of the slink:VkVideoCapabilitiesKHR structure to retrieve -more capabilities specific to H.265 video encoding. - -The sname:VkVideoEncodeH265CapabilitiesEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH265CapabilitiesEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:flags is a bitmask of elink:VkVideoEncodeH265CapabilityFlagBitsEXT - indicating supported H.265 encoding capabilities. - * pname:maxLevelIdc is a code:StdVideoH265LevelIdc value indicating the - maximum H.265 level supported. - * pname:maxSliceSegmentCount indicates the maximum number of slice - segments that can: be encoded for a single picture. - Further restrictions may: apply to the number of slice segments that - can: be encoded for a single picture depending on other capabilities and - codec-specific rules. - * pname:maxTiles indicates the maximum number of H.265 tile columns and - rows that can: be encoded for a single picture. - Further restrictions may: apply to the number of H.265 tiles that can: - be encoded for a single picture depending on other capabilities and - codec-specific rules. - * pname:ctbSizes is a bitmask of elink:VkVideoEncodeH265CtbSizeFlagBitsEXT - describing the supported CTB sizes. - * pname:transformBlockSizes is a bitmask of - elink:VkVideoEncodeH265TransformBlockSizeFlagBitsEXT describing the - supported transform block sizes. - * pname:maxPPictureL0ReferenceCount indicates the maximum number of - reference pictures the implementation supports in the reference list L0 - for P pictures. - * pname:maxBPictureL0ReferenceCount indicates the maximum number of - reference pictures the implementation supports in the reference list L0 - for B pictures. - The reported value is `0` if encoding of B pictures is not supported. - * pname:maxL1ReferenceCount indicates the maximum number of reference - pictures the implementation supports in the reference list L1 if - encoding of B pictures is supported. - The reported value is `0` if encoding of B pictures is not supported. - * pname:maxSubLayerCount indicates the maximum number of H.265 sub-layers - supported by the implementation. - * pname:expectDyadicTemporalSubLayerPattern indicates that the - implementation's rate control algorithms expect the application to use a - dyadic temporal sub-layer pattern when encoding multiple temporal - sub-layers. - * pname:minQp indicates the minimum QP value supported. - * pname:maxQp indicates the maximum QP value supported. - * pname:prefersGopRemainingFrames indicates that the implementation's rate - control algorithm prefers the application to specify the number of - frames of each type remaining in the current group of pictures. - * pname:requiresGopRemainingFrames indicates that the implementation's - rate control algorithm requires the application to specify the number of - frames of each type remaining in the current group of pictures. - * pname:stdSyntaxFlags is a bitmask of - elink:VkVideoEncodeH265StdFlagBitsEXT indicating capabilities related to - H.265 syntax elements. - -include::{generated}/validity/structs/VkVideoEncodeH265CapabilitiesEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH265CapabilityFlagBitsEXT',desc='Video encode H.265 capability flags',type='enums'] --- -Bits which may: be set in -slink:VkVideoEncodeH265CapabilitiesEXT::pname:flags indicating the supported -H.265 encoding capabilities, are: - -include::{generated}/api/enums/VkVideoEncodeH265CapabilityFlagBitsEXT.adoc[] - - * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_HRD_COMPLIANCE_BIT_EXT indicates - if the implementation guarantees generating a HRD compliant bitstream if - code:nal_hrd_parameters_present_flag, - code:vcl_hrd_parameters_present_flag, or - code:sub_pic_hrd_params_present_flag are enabled in - code:StdVideoH265HrdFlags, or code:vui_hrd_parameters_present_flag is - enabled in code:StdVideoH265SpsVuiFlags. - * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_EXT - indicates that when code:weighted_pred_flag or code:weighted_bipred_flag - in code:StdVideoH265PpsFlags are enabled, the implementation is able to - internally decide syntax for code:pred_weight_table. - * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_ROW_UNALIGNED_SLICE_SEGMENT_BIT_EXT - indicates that each slice segment in a frame with a single or multiple - tiles per slice may begin or finish at any offset in a CTB row. - If not supported, all slice segments in such a frame must: begin at the - start of a CTB row (and hence each slice segment must: finish at the end - of a CTB row). - Also indicates that each slice segment in a frame with multiple slices - per tile may begin or finish at any offset within the enclosing tile's - CTB row. - If not supported, slice segments in such a frame must: begin at the - start of the enclosing tile's CTB row (and hence each slice segment - must: finish at the end of the enclosing tile's CTB row). - * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_SLICE_SEGMENT_TYPE_BIT_EXT - indicates that when a frame is encoded with multiple slice segments, the - implementation allows encoding each slice segment with a different - code:StdVideoEncodeH265SliceSegmentHeader::code:slice_type. - If not supported, all slice segments of the frame must: be encoded with - the same code:slice_type which corresponds to the picture type of the - frame. - For example, all slice segments of a P-frame would be encoded as - P-slices. - * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_EXT - indicates support for using a B frame as L0 reference. - * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_EXT - indicates support for using a B frame as L1 reference. - * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_EXT - indicates support for specifying different QP values in the members of - slink:VkVideoEncodeH265QpEXT. - * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_PER_SLICE_SEGMENT_CONSTANT_QP_BIT_EXT - indicates support for specifying different constant QP values for each - slice segment. - * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_TILES_PER_SLICE_SEGMENT_BIT_EXT - indicates if encoding multiple tiles per slice segment is supported. - If not set, the implementation is only able to encode a single tile for - each slice segment. - * ename:VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_SLICE_SEGMENTS_PER_TILE_BIT_EXT - indicates if encoding multiple slice segments per tile is supported. - If not set, the implementation is only able to encode a single slice - segment for each tile. --- - -[open,refpage='VkVideoEncodeH265CapabilityFlagsEXT',desc='Bitmask of VkVideoEncodeH265CapabilityFlagBitsEXT',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeH265CapabilityFlagsEXT.adoc[] - -tname:VkVideoEncodeH265CapabilityFlagsEXT is a bitmask type for setting a -mask of zero or more elink:VkVideoEncodeH265CapabilityFlagBitsEXT. --- - -[open,refpage='VkVideoEncodeH265StdFlagBitsEXT',desc='Video encode H.265 syntax capability flags',type='enums'] --- -Bits which may: be set in -slink:VkVideoEncodeH265CapabilitiesEXT::pname:stdSyntaxFlags, indicating the -capabilities related to the H.265 syntax elements, are: - -include::{generated}/api/enums/VkVideoEncodeH265StdFlagBitsEXT.adoc[] - - * ename:VK_VIDEO_ENCODE_H265_STD_SEPARATE_COLOR_PLANE_FLAG_SET_BIT_EXT - indicates if enabling code:separate_colour_plane_flag in - code:StdVideoH265SpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_SAMPLE_ADAPTIVE_OFFSET_ENABLED_FLAG_SET_BIT_EXT - indicates if enabling code:sample_adaptive_offset_enabled_flag in - code:StdVideoH265SpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_SCALING_LIST_DATA_PRESENT_FLAG_SET_BIT_EXT - indicates if enabling code:scaling_list_enabled_flag and - code:sps_scaling_list_data_present_flag in code:StdVideoH265SpsFlags, or - enabling code:pps_scaling_list_data_present_flag in - code:StdVideoH265PpsFlags are supported. - * ename:VK_VIDEO_ENCODE_H265_STD_PCM_ENABLED_FLAG_SET_BIT_EXT indicates if - enabling code:pcm_enable_flag in code:StdVideoH265SpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_SPS_TEMPORAL_MVP_ENABLED_FLAG_SET_BIT_EXT - indicates if enabling code:sps_temporal_mvp_enabled_flag in - code:StdVideoH265SpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_INIT_QP_MINUS26_BIT_EXT indicates if - setting non-zero code:init_qp_minus26 in - code:StdVideoH265PictureParameterSet is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_WEIGHTED_PRED_FLAG_SET_BIT_EXT indicates - if enabling code:weighted_pred_flag in code:StdVideoH265PpsFlags is - supported. - * ename:VK_VIDEO_ENCODE_H265_STD_WEIGHTED_BIPRED_FLAG_SET_BIT_EXT - indicates if enabling code:weighted_bipred_flag in - code:StdVideoH265PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_LOG2_PARALLEL_MERGE_LEVEL_MINUS2_BIT_EXT - indicates if setting non-zero value for - code:log2_parallel_merge_level_minus2 in - code:StdVideoH265PictureParameterSet is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_SIGN_DATA_HIDING_ENABLED_FLAG_SET_BIT_EXT - indicates if enabling code:sign_data_hiding_enabled_flag in - code:StdVideoH265PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_TRANSFORM_SKIP_ENABLED_FLAG_SET_BIT_EXT - indicates if enabling code:transform_skip_enabled_flag in - code:StdVideoH265PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_TRANSFORM_SKIP_ENABLED_FLAG_UNSET_BIT_EXT - indicates if disabling code:transform_skip_enabled_flag in - code:StdVideoH265PpsFlags is supported. - Implementations must: report at least one of - ename:VK_VIDEO_ENCODE_H265_STD_TRANSFORM_SKIP_ENABLED_FLAG_SET_BIT_EXT - and - ename:VK_VIDEO_ENCODE_H265_STD_TRANSFORM_SKIP_ENABLED_FLAG_UNSET_BIT_EXT - as supported. - * ename:VK_VIDEO_ENCODE_H265_STD_PPS_SLICE_CHROMA_QP_OFFSETS_PRESENT_FLAG_SET_BIT_EXT - indicates if enabling code:pps_slice_chroma_qp_offsets_present_flag in - code:StdVideoH265PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_TRANSQUANT_BYPASS_ENABLED_FLAG_SET_BIT_EXT - indicates if enabling code:transquant_bypass_enabled_flag in - code:StdVideoH265PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_CONSTRAINED_INTRA_PRED_FLAG_SET_BIT_EXT - indicates if enabling code:constrained_intra_pred_flag in - code:StdVideoH265PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_ENTROPY_CODING_SYNC_ENABLED_FLAG_SET_BIT_EXT - indicates if enabling code:entropy_coding_sync_enabled_flag in - code:StdVideoH265PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_DEBLOCKING_FILTER_OVERRIDE_ENABLED_FLAG_SET_BIT_EXT - indicates if enabling code:deblocking_filter_override_enabled_flag in - code:StdVideoH265PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_DEPENDENT_SLICE_SEGMENTS_ENABLED_FLAG_SET_BIT_EXT - indicates if enabling code:dependent_slice_segments_enabled_flag in - code:StdVideoH265PpsFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_DEPENDENT_SLICE_SEGMENT_FLAG_SET_BIT_EXT - indicates if enabling code:dependent_slice_segment_flag in - code:StdVideoEncodeH265SliceHeaderFlags is supported. - * ename:VK_VIDEO_ENCODE_H265_STD_SLICE_QP_DELTA_BIT_EXT indicates whether - the implementation supports using the application-provided value for - code:StdVideoEncodeH265SliceSegmentHeader::code:slice_qp_delta when that - value is identical across the slice segments of the encoded frame. - * ename:VK_VIDEO_ENCODE_H265_STD_DIFFERENT_SLICE_QP_DELTA_BIT_EXT - indicates whether the implementation supports using the - application-provided value for - code:StdVideoEncodeH265SliceSegmentHeader::code:slice_qp_delta when that - value is different across the slice segments of the encoded frame. --- - -[open,refpage='VkVideoEncodeH265StdFlagsEXT',desc='Bitmask of VkVideoEncodeH265StdFlagBitsEXT',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeH265StdFlagsEXT.adoc[] - -tname:VkVideoEncodeH265StdFlagsEXT is a bitmask type for setting a mask of -zero or more elink:VkVideoEncodeH265StdFlagBitsEXT. --- - -[open,refpage='VkVideoEncodeH265CtbSizeFlagsEXT',desc='Bitmask of VkVideoEncodeH265CtbSizeFlagBitsEXT',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeH265CtbSizeFlagsEXT.adoc[] - -tname:VkVideoEncodeH265CtbSizeFlagsEXT is a bitmask type for setting a mask -of zero or more elink:VkVideoEncodeH265CtbSizeFlagBitsEXT. -Implementations must: set at least one of -ename:VkVideoEncodeH265CtbSizeFlagBitsEXT. --- - -[open,refpage='VkVideoEncodeH265CtbSizeFlagBitsEXT',desc='Supported CTB sizes for H.265 video encode',type='enums'] --- -Bits which may: be set in -slink:VkVideoEncodeH265CapabilitiesEXT::pname:ctbSizes, indicating the CTB -sizes supported by the implementation, are: - -include::{generated}/api/enums/VkVideoEncodeH265CtbSizeFlagBitsEXT.adoc[] - - * ename:VK_VIDEO_ENCODE_H265_CTB_SIZE_16_BIT_EXT specifies that a CTB size - of 16x16 is supported. - * ename:VK_VIDEO_ENCODE_H265_CTB_SIZE_32_BIT_EXT specifies that a CTB size - of 32x32 is supported. - * ename:VK_VIDEO_ENCODE_H265_CTB_SIZE_64_BIT_EXT specifies that a CTB size - of 64x64 is supported. --- - -[open,refpage='VkVideoEncodeH265TransformBlockSizeFlagsEXT',desc='Bitmask of VkVideoEncodeH265TransformBlockSizeFlagBitsEXT',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeH265TransformBlockSizeFlagsEXT.adoc[] - -tname:VkVideoEncodeH265TransformBlockSizeFlagsEXT is a bitmask type for -setting a mask of zero or more -elink:VkVideoEncodeH265TransformBlockSizeFlagBitsEXT. -Implementations must: set at least one of -ename:VkVideoEncodeH265TransformBlockSizeFlagBitsEXT. --- - -[open,refpage='VkVideoEncodeH265TransformBlockSizeFlagBitsEXT',desc='Supported transform block sizes for H.265 video encode',type='enums'] --- -Bits which may: be set in -slink:VkVideoEncodeH265CapabilitiesEXT::pname:transformBlockSizes, -indicating the transform block sizes supported by the implementation, are: - -include::{generated}/api/enums/VkVideoEncodeH265TransformBlockSizeFlagBitsEXT.adoc[] - - * ename:VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_4_BIT_EXT specifies that - a transform block size of 4x4 is supported. - * ename:VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_8_BIT_EXT specifies that - a transform block size of 8x8 is supported. - * ename:VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_16_BIT_EXT specifies - that a transform block size of 16x16 is supported. - * ename:VK_VIDEO_ENCODE_H265_TRANSFORM_BLOCK_SIZE_32_BIT_EXT specifies - that a transform block size of 32x32 is supported. --- - - -=== H.265 Encode Quality Level Properties - -[open,refpage='VkVideoEncodeH265QualityLevelPropertiesEXT',desc='Structure describing the H.265 encode quality level properties',type='structs'] --- -When calling flink:vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR -with pname:pVideoProfile->videoCodecOperation specified as -ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT, the -slink:VkVideoEncodeH265QualityLevelPropertiesEXT structure can: be included -in the pname:pNext chain of the slink:VkVideoEncodeQualityLevelPropertiesKHR -structure to retrieve additional video encode quality level properties -specific to H.265 encoding. - -The slink:VkVideoEncodeH265QualityLevelPropertiesEXT structure is defined -as: - -include::{generated}/api/structs/VkVideoEncodeH265QualityLevelPropertiesEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:preferredRateControlFlags is a bitmask of - elink:VkVideoEncodeH265RateControlFlagBitsEXT values indicating the - preferred flags to use for - slink:VkVideoEncodeH265RateControlInfoEXT::pname:flags. - * pname:preferredGopFrameCount indicates the preferred value to use for - slink:VkVideoEncodeH265RateControlInfoEXT::pname:gopFrameCount. - * pname:preferredIdrPeriod indicates the preferred value to use for - slink:VkVideoEncodeH265RateControlInfoEXT::pname:idrPeriod. - * pname:preferredConsecutiveBFrameCount indicates the preferred value to - use for - slink:VkVideoEncodeH265RateControlInfoEXT::pname:consecutiveBFrameCount. - * pname:preferredSubLayerCount indicates the preferred value to use for - slink:VkVideoEncodeH265RateControlInfoEXT::pname:subLayerCount. - * pname:preferredConstantQp indicates the preferred values to use for - slink:VkVideoEncodeH265NaluSliceSegmentInfoEXT::pname:constantQp for - each picture type when using rate control mode - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. - * pname:preferredMaxL0ReferenceCount indicates the preferred maximum - number of reference pictures to use in the reference list L0. - * pname:preferredMaxL1ReferenceCount indicates the preferred maximum - number of reference pictures to use in the reference list L1. - -include::{generated}/validity/structs/VkVideoEncodeH265QualityLevelPropertiesEXT.adoc[] --- - - -=== H.265 Encode Session - -Additional parameters can be specified when creating a video session with an -H.265 encode profile by including an instance of the -slink:VkVideoEncodeH265SessionCreateInfoEXT structure in the pname:pNext -chain of slink:VkVideoSessionCreateInfoKHR. - -[open,refpage='VkVideoEncodeH265SessionCreateInfoEXT',desc='Structure specifies H.265 encode session parameters',type='structs'] --- -The sname:VkVideoEncodeH265SessionCreateInfoEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH265SessionCreateInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:useMaxLevelIdc indicates whether the value of pname:maxLevelIdc - should be used by the implementation. - When it is set to ename:VK_FALSE, the implementation ignores the value - of pname:maxLevelIdc and uses the value of - slink:VkVideoEncodeH265CapabilitiesEXT::pname:maxLevelIdc, as reported - by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile. - * pname:maxLevelIdc provides the upper bound on the H.265 level for the - video bitstreams produced by the created video session. - -include::{generated}/validity/structs/VkVideoEncodeH265SessionCreateInfoEXT.adoc[] --- - - -=== Encoder H.265 Video Session Parameters Object - -When creating a Video Session Parameters object, add a -slink:VkVideoEncodeH265SessionParametersCreateInfoEXT structure to the -pname:pNext chain of the slink:VkVideoSessionParametersCreateInfoKHR -structure passed to flink:vkCreateVideoSessionParametersKHR in order to -specify the H.265-specific video encoder session parameters. - -[open,refpage='VkVideoEncodeH265SessionParametersCreateInfoEXT',desc='Structure specifies H.265 encoder parameter set info',type='structs'] --- -The sname:VkVideoEncodeH265SessionParametersCreateInfoEXT structure is -defined as: - -include::{generated}/api/structs/VkVideoEncodeH265SessionParametersCreateInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:maxStdVPSCount is the maximum number of entries of type - code:StdVideoH265VideoParameterSet within - sname:VkVideoSessionParametersKHR. - * pname:maxStdSPSCount is the maximum number of entries of type - code:StdVideoH265SequenceParameterSet within - sname:VkVideoSessionParametersKHR. - * pname:maxStdPPSCount is the maximum number of entries of type - code:StdVideoH265PictureParameterSet within - sname:VkVideoSessionParametersKHR. - * pname:pParametersAddInfo is `NULL` or a pointer to a - slink:VkVideoEncodeH265SessionParametersAddInfoEXT structure specifying - the video session parameters to add upon creation of this object. - -When a slink:VkVideoSessionParametersKHR object contains -pname:maxStdVPSCount code:StdVideoH265VideoParameterSet entries, no -additional code:StdVideoH265VideoParameterSet entries can be added to it, -and ename:VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made -to add these entries. -When a slink:VkVideoSessionParametersKHR object contains -pname:maxStdSPSCount code:StdVideoH265SequenceParameterSet entries, no -additional code:StdVideoH265SequenceParameterSet entries can be added to it, -and ename:VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made -to add these entries. -When a slink:VkVideoSessionParametersKHR object contains -pname:maxStdPPSCount code:StdVideoH265PictureParameterSet entries, no -additional code:StdVideoH265PictureParameterSet entries can be added to it, -and ename:VK_ERROR_TOO_MANY_OBJECTS will be returned if an attempt is made -to add these entries. - -include::{generated}/validity/structs/VkVideoEncodeH265SessionParametersCreateInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH265SessionParametersAddInfoEXT',desc='Structure specifies H.265 encoder parameter set info',type='structs'] --- -The sname:VkVideoEncodeH265SessionParametersAddInfoEXT structure is defined -as: - -include::{generated}/api/structs/VkVideoEncodeH265SessionParametersAddInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:stdVPSCount is the number of VPS elements in pname:pStdVPSs. - * pname:pStdVPSs is a pointer to an array of pname:stdVPSCount - code:StdVideoH265VideoParameterSet structures representing H.265 video - parameter sets. - * pname:stdSPSCount is the number of SPS elements in pname:pStdSPSs. - * pname:pStdSPSs is a pointer to an array of pname:stdSPSCount - code:StdVideoH265SequenceParameterSet structures representing H.265 - sequence parameter sets. - * pname:stdPPSCount is the number of PPS elements in pname:pStdPPSs. - * pname:pStdPPSs is a pointer to an array of pname:stdPPSCount - code:StdVideoH265PictureParameterSet structures representing H.265 - picture parameter sets. - -include::{generated}/validity/structs/VkVideoEncodeH265SessionParametersAddInfoEXT.adoc[] - -.Valid Usage -**** - * [[VUID-VkVideoEncodeH265SessionParametersAddInfoEXT-stdVPSCount-06438]] - The values of pname:stdVPSCount, pname:stdSPSCount and pname:stdPPSCount - must: be less than or equal to the values of - slink:VkVideoEncodeH265SessionParametersCreateInfoEXT::pname:maxStdVPSCount, - slink:VkVideoEncodeH265SessionParametersCreateInfoEXT:pname:maxStdSPSCount, - and - slink:VkVideoEncodeH265SessionParametersCreateInfoEXT:pname:maxStdPPSCount, - respectively - * [[VUID-VkVideoEncodeH265SessionParametersAddInfoEXT-pStdVPSs-06439]] - Each code:StdVideoH265VideoParameterSet entry in pname:pStdVPSs must: - have a unique H.265 VPS ID - * [[VUID-VkVideoEncodeH265SessionParametersAddInfoEXT-pStdSPSs-06440]] - Each code:StdVideoH265SequenceParameterSet entry in pname:pStdSPSs must: - have a unique H.265 VPS-SPS ID pair - * [[VUID-VkVideoEncodeH265SessionParametersAddInfoEXT-pStdPPSs-06441]] - Each code:StdVideoH265PictureParameterSet entry in pname:pStdPPSs must: - have a unique H.265 VPS-SPS-PPS ID tuple - * [[VUID-VkVideoEncodeH265SessionParametersAddInfoEXT-None-06442]] - 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-VkVideoEncodeH265SessionParametersAddInfoEXT-None-06443]] - Parameter entries that already exist in Video Session Parameters object - with a particular VPS-SPS-PPS IDs must: not be replaced nor updated - * [[VUID-VkVideoEncodeH265SessionParametersAddInfoEXT-None-06444]] - 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-VkVideoEncodeH265SessionParametersAddInfoEXT-None-06445]] - VPS/SPS/PPS parameters must: comply with the limits specified in - slink:VkVideoSessionCreateInfoKHR during Video Session creation -**** --- - -[open,refpage='VkVideoEncodeH265SessionParametersGetInfoEXT',desc='Structure specifying parameters for retrieving encoded H.265 parameter set data',type='structs'] --- -The sname:VkVideoEncodeH265SessionParametersGetInfoEXT structure is defined -as: - -include::{generated}/api/structs/VkVideoEncodeH265SessionParametersGetInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:writeStdVPS indicates whether the encoded H.265 video parameter - set identified by pname:stdVPSId is requested to be retrieved. - * pname:writeStdSPS indicates whether the encoded H.265 sequence parameter - set identified by the pair constructed from pname:stdVPSId and - pname:stdSPSId is requested to be retrieved. - * pname:writeStdPPS indicates whether the encoded H.265 picture parameter - set identified by the triplet constructed from pname:stdVPSId, - pname:stdSPSId, and pname:stdPPSId is requested to be retrieved. - * pname:stdVPSId specifies the H.265 video parameter set ID used to - identify the retrieved H.265 video, sequence, and/or picture parameter - set(s). - * pname:stdSPSId specifies the H.265 sequence parameter set ID used to - identify the retrieved H.265 sequence and/or picture parameter set(s) - when pname:writeStdSPS and/or pname:writeStdPPS is set to ename:VK_TRUE. - * pname:stdPPSId specifies the H.265 picture parameter set ID used to - identify the retrieved H.265 picture parameter set when - pname:writeStdPPS is set to ename:VK_TRUE. - -When this structure is specified in the pname:pNext chain of the -slink:VkVideoEncodeSessionParametersGetInfoKHR structure passed to -flink:vkGetEncodedVideoSessionParametersKHR, the command will write encoded -parameter data to the output buffer in the following order: - - . The H.265 video parameter set identified by pname:stdVPSId, if - pname:writeStdVPS is set to ename:VK_TRUE. - . The H.265 sequence parameter set identified by the pair constructed from - pname:stdVPSId and pname:stdSPSId, if pname:writeStdSPS is set to - ename:VK_TRUE. - . The H.265 picture parameter set identified by the triplet constructed - from pname:stdVPSId, pname:stdSPSId, and pname:stdPPSId, if - pname:writeStdPPS is set to ename:VK_TRUE. - -include::{generated}/validity/structs/VkVideoEncodeH265SessionParametersGetInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH265SessionParametersFeedbackInfoEXT',desc='Structure providing feedback about the requested H.265 video session parameters',type='structs'] --- -The sname:VkVideoEncodeH265SessionParametersFeedbackInfoEXT structure is -defined as: - -include::{generated}/api/structs/VkVideoEncodeH265SessionParametersFeedbackInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:hasStdVPSOverrides indicates whether any of the parameters of the - requested H.265 video parameter set, if one was requested via - slink:VkVideoEncodeH265SessionParametersGetInfoEXT::pname:writeStdVPS, - were overridden by the implementation. - * pname:hasStdSPSOverrides indicates whether any of the parameters of the - requested H.265 sequence parameter set, if one was requested via - slink:VkVideoEncodeH265SessionParametersGetInfoEXT::pname:writeStdSPS, - were overridden by the implementation. - * pname:hasStdPPSOverrides indicates whether any of the parameters of the - requested H.265 picture parameter set, if one was requested via - slink:VkVideoEncodeH265SessionParametersGetInfoEXT::pname:writeStdPPS, - were overridden by the implementation. - -include::{generated}/validity/structs/VkVideoEncodeH265SessionParametersFeedbackInfoEXT.adoc[] --- - - -=== Frame Encoding - -In order to encode a frame, add a slink:VkVideoEncodeH265PictureInfoEXT -structure to the pname:pNext chain of the slink:VkVideoEncodeInfoKHR -structure passed to the flink:vkCmdEncodeVideoKHR command. - -[open,refpage='VkVideoEncodeH265PictureInfoEXT',desc='Structure specifies H.265 encode frame parameters',type='structs'] --- -The slink:VkVideoEncodeH265PictureInfoEXT structure representing a frame -encode operation is defined as: - -include::{generated}/api/structs/VkVideoEncodeH265PictureInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:naluSliceSegmentEntryCount is the number of slice segment NALUs in - the frame. - * pname:pNaluSliceSegmentEntries is a pointer to an array of - slink:VkVideoEncodeH265NaluSliceSegmentInfoEXT structures specifying the - division of the current picture into slice segments and the properties - of these slice segments. - * pname:pStdPictureInfo is a pointer to a - code:StdVideoEncodeH265PictureInfo structure specifying the syntax and - other codec-specific information from the H.265 specification, - associated with this picture. - -include::{generated}/validity/structs/VkVideoEncodeH265PictureInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH265NaluSliceSegmentInfoEXT',desc='Structure specifies H.265 encode slice segment NALU parameters',type='structs'] --- -The slink:VkVideoEncodeH265NaluSliceSegmentInfoEXT structure representing a -slice segment is defined as: - -include::{generated}/api/structs/VkVideoEncodeH265NaluSliceSegmentInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:constantQp is the QP to use for the slice segment if the current - rate control mode configured for the video session is - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR. - * pname:pStdSliceSegmentHeader is a pointer to a - code:StdVideoEncodeH265SliceSegmentHeader structure specifying the slice - segment header for the current slice segment. - -include::{generated}/validity/structs/VkVideoEncodeH265NaluSliceSegmentInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH265DpbSlotInfoEXT',desc='Structure specifies H.265 encode decoded pic info',type='structs'] --- -The slink:VkVideoEncodeH265DpbSlotInfoEXT structure, representing a -reconstructed picture that is being used as a reference picture, is defined -as: - -include::{generated}/api/structs/VkVideoEncodeH265DpbSlotInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:pStdReferenceInfo is a pointer to a - code:StdVideoEncodeH265ReferenceInfo structure specifying the syntax and - other codec-specific information from the H.265 specification, - associated with this reference picture. - -include::{generated}/validity/structs/VkVideoEncodeH265DpbSlotInfoEXT.adoc[] --- - - -=== Rate Control - -[open,refpage='VkVideoEncodeH265RateControlInfoEXT',desc='Structure describing H.265 stream rate control parameters',type='structs'] --- -The sname:VkVideoEncodeH265RateControlInfoEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH265RateControlInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:flags is a bitmask of - elink:VkVideoEncodeH265RateControlFlagBitsEXT specifying H.265 rate - control flags. - * pname:gopFrameCount is the number of frames contained within the group - of pictures (GOP), starting from an intra frame and until the next intra - frame. - If it is set to 0, the implementation chooses a suitable value. - If it is set to code:UINT32_MAX, the GOP length is treated as infinite. - * pname:idrPeriod is the interval, in terms of number of frames, between - two IDR frames. - If it is set to 0, the implementation chooses a suitable value. - If it is set to code:UINT32_MAX, the IDR period is treated as infinite. - * pname:consecutiveBFrameCount is the number of consecutive B-frames - between I- and/or P-frames within the GOP. - * pname:subLayerCount specifies the number of sub layers enabled in the - stream. - -In order to provide H.265-specific stream rate control parameters, add a -sname:VkVideoEncodeH265RateControlInfoEXT structure to the pname:pNext chain -of the slink:VkVideoEncodeRateControlInfoKHR structure in the pname:pNext -chain of the slink:VkVideoCodingControlInfoKHR structure passed to the -flink:vkCmdControlVideoCodingKHR command. - -The parameters from this structure act as a guidance for implementations to -apply various rate control heuristics. - -It is possible to infer the picture type to be used when encoding a frame, -on the basis of the values provided for pname:consecutiveBFrameCount, -pname:idrPeriod, and pname:gopFrameCount, but this inferred picture type -will not be used by implementations to override the picture type provided in -flink:vkCmdEncodeVideoKHR. -Additionally, it is not required for the video session to be reset if the -inferred picture type does not match the actual picture type. - -include::{generated}/validity/structs/VkVideoEncodeH265RateControlInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH265RateControlFlagBitsEXT',desc='H.265 encode rate control bits',type='enums'] --- -Bits which can: be set in -slink:VkVideoEncodeH265RateControlInfoEXT::pname:flags, specifying H.265 -rate control flags, are: - -include::{generated}/api/enums/VkVideoEncodeH265RateControlFlagBitsEXT.adoc[] - - * ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_EXT - specifies that rate control should: attempt to produce an HRD compliant - bitstream. - * ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REGULAR_GOP_BIT_EXT specifies - that the application intends to use a regular GOP structure according to - the parameters specified in the pname:gopFrameCount, pname:idrPeriod, - and pname:consecutiveBFrameCount members of the - slink:VkVideoEncodeH265RateControlInfoEXT structure. - * ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_EXT - specifies that the application intends to follow a flat reference - pattern. - * ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_EXT - specifies that the application intends to follow a dyadic reference - pattern. - * ename:VK_VIDEO_ENCODE_H265_RATE_CONTROL_TEMPORAL_SUB_LAYER_PATTERN_DYADIC_BIT_EXT - specifies that the application intends to follow a dyadic temporal - sub-layer pattern. --- - - -[open,refpage='VkVideoEncodeH265RateControlFlagsEXT',desc='Bitmask specifying H.265 encode rate control flags',type='flags'] --- -include::{generated}/api/flags/VkVideoEncodeH265RateControlFlagsEXT.adoc[] - -tname:VkVideoEncodeH265RateControlFlagsEXT is a bitmask type for setting a -mask of zero or more elink:VkVideoEncodeH265RateControlFlagBitsEXT. --- - -[open,refpage='VkVideoEncodeH265RateControlLayerInfoEXT',desc='Structure describing H.265 per-layer rate control parameters',type='structs'] --- -The sname:VkVideoEncodeH265RateControlLayerInfoEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH265RateControlLayerInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:useMinQp indicates whether the values within pname:minQp should be - used by the implementation. - When it is set to ename:VK_FALSE, the implementation ignores the values - in pname:minQp and chooses suitable values. - * pname:minQp provides the lower bound on the QP values for each picture - type, to be used in rate control calculations. - * pname:useMaxQp indicates whether the values within pname:maxQp should be - used by the implementation. - When it is set to ename:VK_FALSE, the implementation ignores the values - in pname:maxQp and chooses suitable values. - * pname:maxQp provides the upper bound on the QP values for each picture - type, to be used in rate control calculations. - * pname:useMaxFrameSize indicates whether the values within - pname:maxFrameSize should be used by the implementation. - * pname:maxFrameSize provides the upper bound on the encoded frame size - for each picture type. - The implementation does not guarantee the encoded frame sizes will be - within the specified limits, however these limits may: be used as a - guide in rate control calculations. - If enabled and not set properly, the pname:maxQp limit may prevent the - implementation from respecting the pname:maxFrameSize limit. - -H.265-specific per-layer rate control parameters must: be specified by -adding a sname:VkVideoEncodeH265RateControlLayerInfoEXT structure to the -pname:pNext chain of each slink:VkVideoEncodeRateControlLayerInfoKHR -structure in a call to flink:vkCmdControlVideoCodingKHR command, when the -command buffer context has an active video encode H.265 session. - -include::{generated}/validity/structs/VkVideoEncodeH265RateControlLayerInfoEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH265QpEXT',desc='Structure describing H.265 QP values per picture type',type='structs'] --- -The sname:VkVideoEncodeH265QpEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH265QpEXT.adoc[] - - * pname:qpI is the QP to be used for I-frames. - * pname:qpP is the QP to be used for P-frames. - * pname:qpB is the QP to be used for B-frames. - -include::{generated}/validity/structs/VkVideoEncodeH265QpEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH265FrameSizeEXT',desc='Structure describing frame size values per H.265 picture type',type='structs'] --- -The sname:VkVideoEncodeH265FrameSizeEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH265FrameSizeEXT.adoc[] - - * pname:frameISize is the size in bytes to be used for I-frames. - * pname:framePSize is the size in bytes to be used for P-frames. - * pname:frameBSize is the size in bytes to be used for B-frames. - -include::{generated}/validity/structs/VkVideoEncodeH265FrameSizeEXT.adoc[] --- - -[open,refpage='VkVideoEncodeH265GopRemainingFrameInfoEXT',desc='Structure specifying H.265 encode rate control GOP remaining frame counts',type='structs'] --- -The sname:VkVideoEncodeH265GopRemainingFrameInfoEXT structure is defined as: - -include::{generated}/api/structs/VkVideoEncodeH265GopRemainingFrameInfoEXT.adoc[] - - * pname:sType is a elink:VkStructureType value identifying this structure. - * pname:pNext is `NULL` or a pointer to a structure extending this - structure. - * pname:useGopRemainingFrames indicates whether the implementation's rate - control algorithm should: use the values specified in - pname:gopRemainingI, pname:gopRemainingP, and pname:gopRemainingB. - If pname:useGopRemainingFrames is ename:VK_FALSE, then the values of - pname:gopRemainingI, pname:gopRemainingP, and pname:gopRemainingB are - ignored. - * pname:gopRemainingI specifies the number of I-frames the - implementation's rate control algorithm should: assume to be remaining - in the GOP prior to executing the video encode operation. - * pname:gopRemainingP specifies the number of P-frames the - implementation's rate control algorithm should: assume to be remaining - in the GOP prior to executing the video encode operation. - * pname:gopRemainingB specifies the number of B-frames the - implementation's rate control algorithm should: assume to be remaining - in the GOP prior to executing the video encode operation. - -Setting pname:useGopRemainingFrames to ename:VK_TRUE and including this -structure in the pname:pNext chain of slink:VkVideoEncodeInfoKHR is only -mandatory if the -slink:VkVideoEncodeH265CapabilitiesEXT::pname:requiresGopRemainingFrames -reported for the used <> is ename:VK_TRUE. -However, implementations may: use these remaining frame counts, when -specified, even when it is not required. -In particular, when the application does not use a regular GOP structure, -these values may: provide additional guidance for the implementation's rate -control algorithm. - -The slink:VkVideoEncodeH265CapabilitiesEXT::pname:prefersGopRemainingFrames -capability is also used to indicate that the implementation's rate control -algorithm may: operate more accurately if the application specifies the -remaining frame counts using this structure. - -As with other rate control guidance values, if the effective order and -number of frames encoded by the application are not in line with the -remaining frame counts specified in this structure at any given point, then -the behavior of the implementation's rate control algorithm may: deviate -from the one expected by the application. - -include::{generated}/validity/structs/VkVideoEncodeH265GopRemainingFrameInfoEXT.adoc[] --- diff --git a/chapters/video_extensions.adoc b/chapters/videocoding.adoc similarity index 75% rename from chapters/video_extensions.adoc rename to chapters/videocoding.adoc index 9739c1daf..e6b6f73e2 100644 --- a/chapters/video_extensions.adoc +++ b/chapters/videocoding.adoc @@ -195,11 +195,30 @@ Initially, all DPB slots managed by a <> are in _inactive_ state. A DPB slot can: be _activated_ by using it as the target of picture -reconstruction within a video coding operation, changing its state to -_active_. +reconstruction in a video coding operation with the reconstructed picture +requested to be set up as a reference picture, according to the +codec-specific semantics, changing its state to _active_ and associating it +with a _picture reference_ to the <>. -As part of the picture reconstruction, the implementation may: also generate +Some video coding standards allow multiple picture references to be +associated with a single DPB slot. +In this case the state of the individual picture references can: be +independently updated. + +ifdef::VK_KHR_video_decode_h264[] +[NOTE] +.Note +==== +As an example, H.264 decoding allows associating a separate top field and +bottom field picture with the same DPB slot. +==== +endif::VK_KHR_video_decode_h264[] + +As part of reference picture setup, the implementation may: also generate <>. +Such reference picture metadata is specific to each picture reference +associated with the DPB slot. If such a video coding operation completes successfully, the activated DPB slot will have a _valid picture reference_ and the <> associated with the DPB slot. +If an already active DPB slot is used as the target of picture +reconstruction in a video coding operation, but the decoded picture is not +requested to be set up as a reference picture, according to the +codec-specific semantics, no reference picture setup happens and the +corresponding picture reference and <> is invalidated within the DPB slot. +If the DPB slot no longer has any associated picture references after such +an operation, the DPB slot is implicitly deactivated. + +ifdef::VK_KHR_video_decode_h264[] +If an already active DPB slot is used as the target of picture +reconstruction when decoding a field picture that is not marked as +reference, then the behavior is as follows: + + * If the DPB slot is currently associated with a frame, then the DPB slot + is deactivated. + * If the DPB slot is not currently associated with a top field picture and + the decoded picture is a top field picture, or if the DPB slot is not + currently associated with a bottom field picture and the decoded picture + is a bottom field picture, then the other field picture association of + the DPB slot, if any, is not disturbed. + * If the DPB slot is currently associated with a top field picture and the + decoded picture is a top field picture, or if the DPB slot is currently + associated with a bottom field picture and the decoded picture is a + bottom field picture, then that picture association is invalidated, + without disturbing the other field picture association, if any. + If the DPB slot no longer has any associated picture references after + such an operation, the DPB slot is implicitly deactivated. +endif::VK_KHR_video_decode_h264[] + A DPB slot can: be activated with a new frame even if it is already active. In this case all previous associations of the DPB slots with <> are replaced with an association with the <> used to activate it. + ifdef::VK_KHR_video_decode_h264[] If an already active DPB slot is activated with a reconstructed field picture, then the behavior is as follows: @@ -350,18 +400,18 @@ ifdef::VK_KHR_video_decode_h265[] ename:VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, then the pname:pNext chain must: include a slink:VkVideoDecodeH265ProfileInfoKHR structure endif::VK_KHR_video_decode_h265[] -ifdef::VK_EXT_video_encode_h264[] +ifdef::VK_KHR_video_encode_h264[] * [[VUID-VkVideoProfileInfoKHR-videoCodecOperation-07181]] If pname:videoCodecOperation is - ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT, then the pname:pNext - chain must: include a slink:VkVideoEncodeH264ProfileInfoEXT structure -endif::VK_EXT_video_encode_h264[] -ifdef::VK_EXT_video_encode_h265[] + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the pname:pNext + chain must: include a slink:VkVideoEncodeH264ProfileInfoKHR structure +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] * [[VUID-VkVideoProfileInfoKHR-videoCodecOperation-07182]] If pname:videoCodecOperation is - ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT, then the pname:pNext - chain must: include a slink:VkVideoEncodeH265ProfileInfoEXT structure -endif::VK_EXT_video_encode_h265[] + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the pname:pNext + chain must: include a slink:VkVideoEncodeH265ProfileInfoKHR structure +endif::VK_KHR_video_encode_h265[] **** include::{generated}/validity/structs/VkVideoProfileInfoKHR.adoc[] @@ -379,20 +429,20 @@ include::{generated}/api/enums/VkVideoCodecOperationFlagBitsKHR.adoc[] video codec operations. ifdef::VK_KHR_video_decode_h264[] * ename:VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR specifies support for - H.264 video decode operations. + <>. endif::VK_KHR_video_decode_h264[] ifdef::VK_KHR_video_decode_h265[] * ename:VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR specifies support for - H.265 video decode operations. + <>. endif::VK_KHR_video_decode_h265[] -ifdef::VK_EXT_video_encode_h264[] - * ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT specifies support for - H.264 video encode operations. -endif::VK_EXT_video_encode_h264[] -ifdef::VK_EXT_video_encode_h265[] - * ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT specifies support for - H.265 video encode operations. -endif::VK_EXT_video_encode_h265[] +ifdef::VK_KHR_video_encode_h264[] + * ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR specifies support for + <>. +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR specifies support for + <>. +endif::VK_KHR_video_encode_h265[] -- [open,refpage='VkVideoCodecOperationFlagsKHR',desc='Bitmask of VkVideoCodecOperationFlagBitsKHR',type='flags'] @@ -658,7 +708,7 @@ include::{generated}/api/structs/VkVideoProfileListInfoKHR.adoc[] structures. [NOTE] -.Note: +.Note ==== Video transcoding is an example of a use case that necessitates the specification of multiple profiles in various contexts. @@ -736,20 +786,20 @@ ifdef::VK_KHR_video_encode_queue[] operation, then the pname:pNext chain of pname:pCapabilities must: include a slink:VkVideoEncodeCapabilitiesKHR structure endif::VK_KHR_video_encode_queue[] -ifdef::VK_EXT_video_encode_h264[] +ifdef::VK_KHR_video_encode_h264[] * [[VUID-vkGetPhysicalDeviceVideoCapabilitiesKHR-pVideoProfile-07187]] If pname:pVideoProfile->videoCodecOperation is - ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT, then the pname:pNext + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the pname:pNext chain of pname:pCapabilities must: include a - slink:VkVideoEncodeH264CapabilitiesEXT structure -endif::VK_EXT_video_encode_h264[] -ifdef::VK_EXT_video_encode_h265[] + slink:VkVideoEncodeH264CapabilitiesKHR structure +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] * [[VUID-vkGetPhysicalDeviceVideoCapabilitiesKHR-pVideoProfile-07188]] If pname:pVideoProfile->videoCodecOperation is - ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT, then the pname:pNext + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the pname:pNext chain of pname:pCapabilities must: include a - slink:VkVideoEncodeH265CapabilitiesEXT structure -endif::VK_EXT_video_encode_h265[] + slink:VkVideoEncodeH265CapabilitiesKHR structure +endif::VK_KHR_video_encode_h265[] **** include::{generated}/validity/protos/vkGetPhysicalDeviceVideoCapabilitiesKHR.adoc[] @@ -788,7 +838,7 @@ include::{generated}/api/structs/VkVideoCapabilitiesKHR.adoc[] ifdef::VK_KHR_video_decode_queue[] [NOTE] -.Note: +.Note ==== It is common for video compression standards to allow using all reference pictures associated with active DPB slots as active reference pictures, @@ -811,10 +861,10 @@ Bits which can: be set in slink:VkVideoCapabilitiesKHR::pname:flags are: include::{generated}/api/enums/VkVideoCapabilityFlagBitsKHR.adoc[] - * ename:VK_VIDEO_CAPABILITY_PROTECTED_CONTENT_BIT_KHR specifies that video + * ename:VK_VIDEO_CAPABILITY_PROTECTED_CONTENT_BIT_KHR indicates that video sessions support producing and consuming protected content. * [[separate-reference-images]] - ename:VK_VIDEO_CAPABILITY_SEPARATE_REFERENCE_IMAGES_BIT_KHR specifies + ename:VK_VIDEO_CAPABILITY_SEPARATE_REFERENCE_IMAGES_BIT_KHR indicates that the <> associated with the <> of a video session can: be backed by separate sname:VkImage objects. @@ -939,7 +989,7 @@ slink:VkVideoFormatPropertiesKHR structure returned will include additional image usage flags indicating that. [NOTE] -.Note: +.Note ==== For most use cases, only decode or encode related usage flags are going to be specified. @@ -1091,6 +1141,12 @@ include::{generated}/validity/structs/VkVideoFormatPropertiesKHR.adoc[] Video sessions are objects that represent and maintain the state needed to perform video decode or encode operations using a specific video profile. +ifdef::VK_KHR_video_encode_queue[] +In case of video encode profiles this includes the current +<> configuration and the currently set +<>. +endif::VK_KHR_video_encode_queue[] + Video sessions are represented by sname:VkVideoSessionKHR handles: include::{generated}/api/handles/VkVideoSessionKHR.adoc[] @@ -1246,6 +1302,12 @@ endif::VK_KHR_video_encode_queue[] by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile specified by pname:pVideoProfile, then pname:flags must: not include ename:VK_VIDEO_SESSION_CREATE_PROTECTED_CONTENT_BIT_KHR +ifdef::VK_KHR_video_maintenance1[] + * [[VUID-VkVideoSessionCreateInfoKHR-flags-08371]] + If pname:flags includes + ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, then + <> must: be enabled +endif::VK_KHR_video_maintenance1[] * [[VUID-VkVideoSessionCreateInfoKHR-pVideoProfile-04845]] pname:pVideoProfile must: be a <> @@ -1333,6 +1395,28 @@ endif::VK_KHR_video_encode_queue[] slink:VkVideoCapabilitiesKHR::pname:stdHeaderVersion.specVersion, as returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile specified by pname:pVideoProfile +ifdef::VK_KHR_video_encode_h264[] + * [[VUID-VkVideoSessionCreateInfoKHR-pVideoProfile-08251]] + If pname:pVideoProfile->videoCodecOperation is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and the pname:pNext + chain of this structure includes a + slink:VkVideoEncodeH264SessionCreateInfoKHR structure, then its + pname:maxLevelIdc member must: be less than or equal to + slink:VkVideoEncodeH264CapabilitiesKHR::pname:maxLevelIdc, as returned + by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile + specified in pname:pVideoProfile +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * [[VUID-VkVideoSessionCreateInfoKHR-pVideoProfile-08252]] + If pname:pVideoProfile->videoCodecOperation is + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and the pname:pNext + chain of this structure includes a + slink:VkVideoEncodeH265SessionCreateInfoKHR structure, then its + pname:maxLevelIdc member must: be less than or equal to + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxLevelIdc, as returned + by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile + specified in pname:pVideoProfile +endif::VK_KHR_video_encode_h265[] **** include::{generated}/validity/structs/VkVideoSessionCreateInfoKHR.adoc[] @@ -1348,13 +1432,33 @@ include::{generated}/api/enums/VkVideoSessionCreateFlagBitsKHR.adoc[] * ename:VK_VIDEO_SESSION_CREATE_PROTECTED_CONTENT_BIT_KHR specifies that the video session uses protected video content. ifdef::VK_KHR_video_encode_queue[] - * ename:VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHR - specifies that the implementation is allowed to override video session - parameters and other codec-specific encoding parameters to optimize - video encode operations based on the specific use case defined by the - <> and the used video encode quality - level. + * [[encode-optimizing-overrides]] + ename:VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHR + specifies that the implementation is allowed to + <> video session parameters and other + codec-specific encoding parameters to optimize video encode operations + based on the use case information specified in the + <> and the used + <>. ++ +[NOTE] +.Note +==== +Not specifying +ename:VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHR +does not guarantee that the implementation will not do any codec-specific +parameter overrides, as certain overrides are necessary for the correct +operation of the video encoder implementation due to limitations to the +available encoding tools on that implementation. +This flag, however, enables the implementation to apply further optimizing +overrides. +==== endif::VK_KHR_video_encode_queue[] +ifdef::VK_KHR_video_maintenance1[] + * ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR specifies that + queries within video coding scopes using the created video session are + <> with video coding operations. +endif::VK_KHR_video_maintenance1[] -- [open,refpage='VkVideoSessionCreateFlagsKHR',desc='Bitmask of VkVideoSessionCreateFlagBitsKHR',type='flags'] @@ -1584,6 +1688,12 @@ ifdef::VK_KHR_video_encode_queue[] * ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR endif::VK_KHR_video_encode_queue[] +ifdef::VK_KHR_video_maintenance1[] +A slink:VkBuffer is also compatible with a video profile if it was created +with slink:VkBufferCreateInfo::pname:flags including +ename:VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. +endif::VK_KHR_video_maintenance1[] + A slink:VkImage is compatible with a video profile if it was created with the slink:VkImageCreateInfo::pname:pNext chain including a slink:VkVideoProfileListInfoKHR structure with its pname:pProfiles member @@ -1602,6 +1712,52 @@ ifdef::VK_KHR_video_encode_queue[] * ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR endif::VK_KHR_video_encode_queue[] +ifdef::VK_KHR_video_maintenance1[] +A slink:VkImage is also compatible with a video profile if all of the +following conditions are true for the slink:VkImageCreateInfo structure the +image was created with: + + * slink:VkImageCreateInfo::pname:flags included + ename:VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR. + * The list of slink:VkVideoFormatPropertiesKHR structures, obtained by + calling flink:vkGetPhysicalDeviceVideoFormatPropertiesKHR with + slink:VkPhysicalDeviceVideoFormatInfoKHR::pname:imageUsage equal to the + slink:VkImageCreateInfo::pname:usage the image was created with and the + slink:VkPhysicalDeviceVideoFormatInfoKHR::pname:pNext chain including a + slink:VkVideoProfileListInfoKHR structure with its pname:pProfiles + member containing a single array element specifying the + slink:VkVideoProfileInfoKHR structure chain describing the video profile + in question, contains an element for which all of the following + conditions are true with respect to the slink:VkImageCreateInfo + structure the image was created with: + ** slink:VkImageCreateInfo::pname:format equals + slink:VkVideoFormatPropertiesKHR::pname:format. + ** slink:VkImageCreateInfo::pname:flags only contains bits also set in + slink:VkVideoFormatPropertiesKHR::pname:imageCreateFlags. + ** slink:VkImageCreateInfo::pname:imageType equals + slink:VkVideoFormatPropertiesKHR::pname:imageType. + ** slink:VkImageCreateInfo::pname:tiling equals + slink:VkVideoFormatPropertiesKHR::pname:imageTiling. + ** slink:VkImageCreateInfo::pname:usage only contains bits also set in + slink:VkVideoFormatPropertiesKHR::pname:imageUsageFlags. + +[NOTE] +.Note +==== +While some of these rules allow creating buffer or image resources that may: +be compatible with any video profile, applications should: still prefer to +include the specific video profiles the buffer or image resource is expected +to be used with (through a slink:VkVideoProfileListInfoKHR structure +included in the pname:pNext chain of the corresponding create info +structure) whenever the information about the complete set of video profiles +is available at resource creation time, to enable the implementation to +optimize the created resource for the specific use case. +In the absence of that information, the implementation may: have to make +conservative decisions about the memory requirements or representation of +the resource. +==== +endif::VK_KHR_video_maintenance1[] + A slink:VkImageView is compatible with a video profile if the slink:VkImage it was created from is also compatible with that video profile. @@ -1664,6 +1820,27 @@ ifdef::VK_KHR_video_decode_h265[] in the <> section. endif::VK_KHR_video_decode_h265[] +ifdef::VK_KHR_video_encode_h264[] + * For ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR these are defined + in the <> + section. +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * For ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR these are defined + in the <> + section. +endif::VK_KHR_video_encode_h265[] + +ifdef::VK_KHR_video_encode_queue[] +Video session parameters objects created with an encode operation are +further specialized based on the <> the video session parameters are used with, as implementations may: +apply different sets of <> depending +on the used quality level. +This enables implementations to store the potentially optimized set of +parameters in these objects, further limiting the necessary processing +required while recording video encode operations into command buffers. +endif::VK_KHR_video_encode_queue[] [open,refpage='VkVideoSessionParametersKHR',desc='Opaque handle to a video session parameters object',type='handles'] @@ -1698,6 +1875,18 @@ include::{generated}/api/protos/vkCreateVideoSessionParametersKHR.adoc[] The resulting video session parameters object is said to be created with the video codec operation pname:pCreateInfo->videoSession was created with. +ifdef::VK_KHR_video_encode_queue[] +Video session parameters objects created with an encode operation are always +created with respect to a <>. +By default, the created video session parameters objects are created with +quality level zero, unless otherwise specified by including a +slink:VkVideoEncodeQualityLevelInfoKHR structure in the +pname:pCreateInfo->pNext chain, in which case the video session parameters +object is created with the quality level specified in +slink:VkVideoEncodeQualityLevelInfoKHR::pname:qualityLevel. +endif::VK_KHR_video_encode_queue[] + If pname:pCreateInfo->videoSessionParametersTemplate is not dname:VK_NULL_HANDLE, then it will be used as a template for constructing the new video session parameters object. @@ -1706,6 +1895,26 @@ creation parameters provided in the pname: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. +ifdef::VK_KHR_video_encode_queue[] +For video session parameters objects created with an encode operation, the +template object specified in +pname:pCreateInfo->videoSessionParametersTemplate must: have been created +with the same <> as the +newly created object. + +[NOTE] +.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 +<>) may: no longer be available in +them for the purposes of constructing the derived object. +==== +endif::VK_KHR_video_encode_queue[] + ifdef::VK_KHR_video_decode_h264[] If pname:pCreateInfo->videoSession was created with the video codec operation ename:VK_VIDEO_CODEC_OPERATION_DECODE_H264_BIT_KHR, then the @@ -1785,6 +1994,85 @@ sets of parameter entries: pname:pps_seq_parameter_set_id, and pname:pps_pic_parameter_set_id. endif::VK_KHR_video_decode_h265[] +ifdef::VK_KHR_video_encode_h264[] +If pname:pCreateInfo->videoSession was created with the video codec +operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the +created video session parameters object will initially contain the following +sets of parameter entries: + + * code:StdVideoH264SequenceParameterSet structures representing + <> entries, as follows: + ** If the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH264SessionParametersCreateInfoKHR structure + provided in the pname:pCreateInfo->pNext chain is not `NULL`, then the + set of code:StdVideoH264SequenceParameterSet entries specified in + pname:pParametersAddInfo->pStdSPSs are added first; + ** If pname:pCreateInfo->videoSessionParametersTemplate is not + dname:VK_NULL_HANDLE, then each code: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 pname:seq_parameter_set_id. + * code:StdVideoH264PictureParameterSet structures representing + <> entries, as follows: + ** If the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH264SessionParametersCreateInfoKHR structure + provided in the pname:pCreateInfo->pNext chain is not `NULL`, then the + set of code:StdVideoH264PictureParameterSet entries specified in + pname:pParametersAddInfo->pStdPPSs are added first; + ** If pname:pCreateInfo->videoSessionParametersTemplate is not + dname:VK_NULL_HANDLE, then each code: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 pname:seq_parameter_set_id and + pname:pic_parameter_set_id. +endif::VK_KHR_video_encode_h264[] + +ifdef::VK_KHR_video_encode_h265[] +If pname:pCreateInfo->videoSession was created with the video codec +operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the +created video session parameters object will initially contain the following +sets of parameter entries: + + * code:StdVideoH265VideoParameterSet structures representing + <> entries, as follows: + ** If the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure + provided in the pname:pCreateInfo->pNext chain is not `NULL`, then the + set of code:StdVideoH265VideoParameterSet entries specified in + pname:pParametersAddInfo->pStdVPSs are added first; + ** If pname:pCreateInfo->videoSessionParametersTemplate is not + dname:VK_NULL_HANDLE, then each code: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 pname:vps_video_parameter_set_id. + * code:StdVideoH265SequenceParameterSet structures representing + <> entries, as follows: + ** If the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure + provided in the pname:pCreateInfo->pNext chain is not `NULL`, then the + set of code:StdVideoH265SequenceParameterSet entries specified in + pname:pParametersAddInfo->pStdSPSs are added first; + ** If pname:pCreateInfo->videoSessionParametersTemplate is not + dname:VK_NULL_HANDLE, then each code: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 pname:sps_video_parameter_set_id and + pname:sps_seq_parameter_set_id. + * code:StdVideoH265PictureParameterSet structures representing + <> entries, as follows: + ** If the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure + provided in the pname:pCreateInfo->pNext chain is not `NULL`, then the + set of code:StdVideoH265PictureParameterSet entries specified in + pname:pParametersAddInfo->pStdPPSs are added first; + ** If pname:pCreateInfo->videoSessionParametersTemplate is not + dname:VK_NULL_HANDLE, then each code: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 pname:sps_video_parameter_set_id, + pname:pps_seq_parameter_set_id, and pname:pps_pic_parameter_set_id. +endif::VK_KHR_video_encode_h265[] + ifdef::VK_KHR_video_encode_queue[] In case of video session parameters objects created with a video encode operation, implementations may: return the @@ -1904,12 +2192,107 @@ ifdef::VK_KHR_video_decode_h265[] pname:pps_pic_parameter_set_id not matching any of the entries already in pname:ppsAddList is added to pname:ppsAddList. endif::VK_KHR_video_decode_h265[] +ifdef::VK_KHR_video_encode_queue[] + * If pname:videoSession was created with an encode operation, then let + `uint32_t qualityLevel` be the <> of the created video session parameters object, defined + as follows: + ** If the pname:pNext chain of this structure includes a + slink:VkVideoEncodeQualityLevelInfoKHR structure, then + pname:qualityLevel is equal to + slink:VkVideoEncodeQualityLevelInfoKHR::pname:qualityLevel. + ** Otherwise pname:qualityLevel is `0` +endif::VK_KHR_video_encode_queue[] +ifdef::VK_KHR_video_encode_h264[] + * If pname:videoSession was created with the codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then let + `StdVideoH264SequenceParameterSet spsAddList[]` be the list of + <> entries to add to the created video + session parameters object, defined as follows: + ** If the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH264SessionParametersCreateInfoKHR structure + provided in the pname:pNext chain is not `NULL`, then the set of + code:StdVideoH264SequenceParameterSet entries specified in + pname:pParametersAddInfo->pStdSPSs are added to pname:spsAddList; + ** If pname:videoSessionParametersTemplate is not dname:VK_NULL_HANDLE, + then each code:StdVideoH264SequenceParameterSet entry stored in it with + pname:seq_parameter_set_id not matching any of the entries already in + pname:spsAddList is added to pname:spsAddList. + * If pname:videoSession was created with the codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then let + `StdVideoH264PictureParameterSet ppsAddList[]` be the list of + <> entries to add to the created video + session parameters object, defined as follows: + ** If the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH264SessionParametersCreateInfoKHR structure + provided in the pname:pNext chain is not `NULL`, then the set of + code:StdVideoH264PictureParameterSet entries specified in + pname:pParametersAddInfo->pStdPPSs are added to pname:ppsAddList; + ** If pname:videoSessionParametersTemplate is not dname:VK_NULL_HANDLE, + then each code:StdVideoH264PictureParameterSet entry stored in it with + pname:seq_parameter_set_id or pname:pic_parameter_set_id not matching + any of the entries already in pname:ppsAddList is added to + pname:ppsAddList. +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * If pname:videoSession was created with the codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then let + `StdVideoH265VideoParameterSet vpsAddList[]` be the list of + <> entries to add to the created video + session parameters object, defined as follows: + ** If the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure + provided in the pname:pNext chain is not `NULL`, then the set of + code:StdVideoH265VideoParameterSet entries specified in + pname:pParametersAddInfo->pStdVPSs are added to pname:vpsAddList; + ** If pname:videoSessionParametersTemplate is not dname:VK_NULL_HANDLE, + then each code:StdVideoH265VideoParameterSet entry stored in it with + pname:vps_video_parameter_set_id not matching any of the entries + already in pname:vpsAddList is added to pname:vpsAddList. + * If pname:videoSession was created with the codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then let + `StdVideoH265SequenceParameterSet spsAddList[]` be the list of + <> entries to add to the created video + session parameters object, defined as follows: + ** If the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure + provided in the pname:pNext chain is not `NULL`, then the set of + code:StdVideoH265SequenceParameterSet entries specified in + pname:pParametersAddInfo->pStdSPSs are added to pname:spsAddList; + ** If pname:videoSessionParametersTemplate is not dname:VK_NULL_HANDLE, + then each code:StdVideoH265SequenceParameterSet entry stored in it with + pname:sps_video_parameter_set_id or pname:sps_seq_parameter_set_id not + matching any of the entries already in pname:spsAddList is added to + pname:spsAddList. + * If pname:videoSession was created with the codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then let + `StdVideoH265PictureParameterSet ppsAddList[]` be the list of + <> entries to add to the created video + session parameters object, defined as follows: + ** If the pname:pParametersAddInfo member of the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure + provided in the pname:pNext chain is not `NULL`, then the set of + code:StdVideoH265PictureParameterSet entries specified in + pname:pParametersAddInfo->pStdPPSs are added to pname:ppsAddList; + ** If pname:videoSessionParametersTemplate is not dname:VK_NULL_HANDLE, + then each code:StdVideoH265PictureParameterSet entry stored in it with + pname:sps_video_parameter_set_id, pname:pps_seq_parameter_set_id, or + pname:pps_pic_parameter_set_id not matching any of the entries already + in pname:ppsAddList is added to pname:ppsAddList. +endif::VK_KHR_video_encode_h265[] .Valid Usage **** * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSessionParametersTemplate-04855]] - If pname:videoSessionParametersTemplate represents a valid handle, it + If pname:videoSessionParametersTemplate is not dname:VK_NULL_HANDLE, it must: have been created against pname:videoSession +ifdef::VK_KHR_video_encode_queue[] + * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSessionParametersTemplate-08310]] + If pname:videoSessionParametersTemplate is not dname:VK_NULL_HANDLE and + pname:videoSession was created with an encode operation, then + pname:qualityLevel must: equal the <> level pname:videoSessionParametersTemplate was created with +endif::VK_KHR_video_encode_queue[] ifdef::VK_KHR_video_decode_h264[] * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSession-07203]] If pname:videoSession was created with the video codec operation @@ -1959,20 +2342,71 @@ ifdef::VK_KHR_video_decode_h265[] slink:VkVideoDecodeH265SessionParametersCreateInfoKHR structure included in the pname:pNext chain endif::VK_KHR_video_decode_h265[] -ifdef::VK_EXT_video_encode_h264[] +ifdef::VK_KHR_video_encode_h264[] * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSession-07210]] If pname:videoSession was created with the video codec operation - ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT, then the pname:pNext + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the pname:pNext chain must: include a - slink:VkVideoEncodeH264SessionParametersCreateInfoEXT structure -endif::VK_EXT_video_encode_h264[] -ifdef::VK_EXT_video_encode_h265[] + slink:VkVideoEncodeH264SessionParametersCreateInfoKHR structure + * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSession-04839]] + If pname:videoSession was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the number of + elements of pname:spsAddList must: be less than or equal to the + pname:maxStdSPSCount specified in the + slink:VkVideoEncodeH264SessionParametersCreateInfoKHR structure included + in the pname:pNext chain + * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSession-04840]] + If pname:videoSession was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the number of + elements of pname:ppsAddList must: be less than or equal to the + pname:maxStdPPSCount specified in the + slink:VkVideoEncodeH264SessionParametersCreateInfoKHR structure included + in the pname:pNext chain +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSession-07211]] If pname:videoSession was created with the video codec operation - ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT, then the pname:pNext + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the pname:pNext chain must: include a - slink:VkVideoEncodeH265SessionParametersCreateInfoEXT structure -endif::VK_EXT_video_encode_h265[] + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure + * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSession-04841]] + If pname:videoSession was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the number of + elements of pname:vpsAddList must: be less than or equal to the + pname:maxStdVPSCount specified in the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure included + in the pname:pNext chain + * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSession-04842]] + If pname:videoSession was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the number of + elements of pname:spsAddList must: be less than or equal to the + pname:maxStdSPSCount specified in the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure included + in the pname:pNext chain + * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSession-04843]] + If pname:videoSession was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the number of + elements of pname:ppsAddList must: be less than or equal to the + pname:maxStdPPSCount specified in the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR structure included + in the pname:pNext chain + * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSession-08319]] + If pname:videoSession was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then + code:num_tile_columns_minus1 must: be less than + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxTiles.width, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile pname:videoSession was created with, for each element of + pname:ppsAddList + * [[VUID-VkVideoSessionParametersCreateInfoKHR-videoSession-08320]] + If pname:videoSession was created with the video codec operation + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then + code:num_tile_rows_minus1 must: be less than + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxTiles.height, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile pname:videoSession was created with, for each element of + pname:ppsAddList +endif::VK_KHR_video_encode_h265[] **** include::{generated}/validity/structs/VkVideoSessionParametersCreateInfoKHR.adoc[] @@ -2045,7 +2479,7 @@ pname:videoSessionParameters is changed to the value specified in pname:pUpdateInfo->updateSequenceCount. [NOTE] -.Note: +.Note ==== As each update issued to a video session parameters object needs to specify the next available update sequence count value, concurrent updates of the @@ -2086,6 +2520,36 @@ pname:videoSessionParameters: slink:VkVideoDecodeH265SessionParametersAddInfoKHR::pname:pStdPPSs. endif::VK_KHR_video_decode_h265[] +ifdef::VK_KHR_video_encode_h264[] +If pname:videoSessionParameters was created with the video codec operation +ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and the +pname:pUpdateInfo->pNext chain includes a +slink:VkVideoEncodeH264SessionParametersAddInfoKHR structure, then this +command adds the following parameter entries to +pname:videoSessionParameters: + + * The <> entries specified in + slink:VkVideoEncodeH264SessionParametersAddInfoKHR::pname:pStdSPSs. + * The <> entries specified in + slink:VkVideoEncodeH264SessionParametersAddInfoKHR::pname:pStdPPSs. +endif::VK_KHR_video_encode_h264[] + +ifdef::VK_KHR_video_encode_h265[] +If pname:videoSessionParameters was created with the video codec operation +ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and the +pname:pUpdateInfo->pNext chain includes a +slink:VkVideoEncodeH265SessionParametersAddInfoKHR structure, then this +command adds the following parameter entries to +pname:videoSessionParameters: + + * The <> entries specified in + slink:VkVideoEncodeH265SessionParametersAddInfoKHR::pname:pStdVPSs. + * The <> entries specified in + slink:VkVideoEncodeH265SessionParametersAddInfoKHR::pname:pStdSPSs. + * The <> entries specified in + slink:VkVideoEncodeH265SessionParametersAddInfoKHR::pname:pStdPPSs. +endif::VK_KHR_video_encode_h265[] + ifdef::VK_KHR_video_encode_queue[] In case of video session parameters objects created with a video encode operation, implementations may: return the @@ -2209,58 +2673,123 @@ ifdef::VK_KHR_video_decode_h265[] slink:VkVideoDecodeH265SessionParametersCreateInfoKHR::pname:maxStdPPSCount pname:videoSessionParameters was created with endif::VK_KHR_video_decode_h265[] -ifdef::VK_EXT_video_encode_h264[] +ifdef::VK_KHR_video_encode_h264[] * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-07226]] If pname:videoSessionParameters was created with the video codec - operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT and the + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and the pname:pNext chain of pname:pUpdateInfo includes a - slink:VkVideoEncodeH264SessionParametersAddInfoEXT structure, then + slink:VkVideoEncodeH264SessionParametersAddInfoKHR structure, then pname:videoSessionParameters must: not already contain a code:StdVideoH264SequenceParameterSet entry with pname:seq_parameter_set_id matching any of the elements of - slink:VkVideoEncodeH264SessionParametersAddInfoEXT::pname:pStdSPSs + slink:VkVideoEncodeH264SessionParametersAddInfoKHR::pname:pStdSPSs + * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-06441]] + If pname:videoSessionParameters was created with the video codec + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the + number of code:StdVideoH264SequenceParameterSet entries already stored + in it plus the value of the pname:stdSPSCount member of the + slink:VkVideoEncodeH264SessionParametersAddInfoKHR structure included in + the pname:pUpdateInfo->pNext chain must: be less than or equal to the + slink:VkVideoEncodeH264SessionParametersCreateInfoKHR::pname:maxStdSPSCount + pname:videoSessionParameters was created with * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-07227]] If pname:videoSessionParameters was created with the video codec - operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT and the + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR and the pname:pNext chain of pname:pUpdateInfo includes a - slink:VkVideoEncodeH264SessionParametersAddInfoEXT structure, then + slink:VkVideoEncodeH264SessionParametersAddInfoKHR structure, then pname:videoSessionParameters must: not already contain a code:StdVideoH264PictureParameterSet entry with both pname:seq_parameter_set_id and pname:pic_parameter_set_id matching any of the elements of - slink:VkVideoEncodeH264SessionParametersAddInfoEXT::pname:pStdPPSs -endif::VK_EXT_video_encode_h264[] -ifdef::VK_EXT_video_encode_h265[] + slink:VkVideoEncodeH264SessionParametersAddInfoKHR::pname:pStdPPSs + * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-06442]] + If pname:videoSessionParameters was created with the video codec + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then the + number of code:StdVideoH264PictureParameterSet entries already stored in + it plus the value of the pname:stdPPSCount member of the + slink:VkVideoEncodeH264SessionParametersAddInfoKHR structure included in + the pname:pUpdateInfo->pNext chain must: be less than or equal to the + slink:VkVideoEncodeH264SessionParametersCreateInfoKHR::pname:maxStdPPSCount + pname:videoSessionParameters was created with +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-07228]] If pname:videoSessionParameters was created with the video codec - operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT and the + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and the pname:pNext chain of pname:pUpdateInfo includes a - slink:VkVideoEncodeH265SessionParametersAddInfoEXT structure, then + slink:VkVideoEncodeH265SessionParametersAddInfoKHR structure, then pname:videoSessionParameters must: not already contain a code:StdVideoH265VideoParameterSet entry with pname:vps_video_parameter_set_id matching any of the elements of - slink:VkVideoEncodeH265SessionParametersAddInfoEXT::pname:pStdVPSs + slink:VkVideoEncodeH265SessionParametersAddInfoKHR::pname:pStdVPSs + * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-06443]] + If pname:videoSessionParameters was created with the video codec + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the + number of code:StdVideoH265VideoParameterSet entries already stored in + it plus the value of the pname:stdVPSCount member of the + slink:VkVideoEncodeH265SessionParametersAddInfoKHR structure included in + the pname:pUpdateInfo->pNext chain must: be less than or equal to the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR::pname:maxStdVPSCount + pname:videoSessionParameters was created with * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-07229]] If pname:videoSessionParameters was created with the video codec - operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT and the + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and the pname:pNext chain of pname:pUpdateInfo includes a - slink:VkVideoEncodeH265SessionParametersAddInfoEXT structure, then + slink:VkVideoEncodeH265SessionParametersAddInfoKHR structure, then pname:videoSessionParameters must: not already contain a code:StdVideoH265SequenceParameterSet entry with both pname:sps_video_parameter_set_id and pname:sps_seq_parameter_set_id matching any of the elements of - slink:VkVideoEncodeH265SessionParametersAddInfoEXT::pname:pStdSPSs + slink:VkVideoEncodeH265SessionParametersAddInfoKHR::pname:pStdSPSs + * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-06444]] + If pname:videoSessionParameters was created with the video codec + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the + number of code:StdVideoH265SequenceParameterSet entries already stored + in it plus the value of the pname:stdSPSCount member of the + slink:VkVideoEncodeH265SessionParametersAddInfoKHR structure included in + the pname:pUpdateInfo->pNext chain must: be less than or equal to the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR::pname:maxStdSPSCount + pname:videoSessionParameters was created with * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-07230]] If pname:videoSessionParameters was created with the video codec - operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT and the + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and the pname:pNext chain of pname:pUpdateInfo includes a - slink:VkVideoEncodeH265SessionParametersAddInfoEXT structure, then + slink:VkVideoEncodeH265SessionParametersAddInfoKHR structure, then pname:videoSessionParameters must: not already contain a code:StdVideoH265PictureParameterSet entry with pname:sps_video_parameter_set_id, pname:pps_seq_parameter_set_id, and pname:pps_pic_parameter_set_id all matching any of the elements of - slink:VkVideoEncodeH265SessionParametersAddInfoEXT::pname:pStdPPSs -endif::VK_EXT_video_encode_h265[] + slink:VkVideoEncodeH265SessionParametersAddInfoKHR::pname:pStdPPSs + * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-06445]] + If pname:videoSessionParameters was created with the video codec + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then the + number of code:StdVideoH265PictureParameterSet entries already stored in + it plus the value of the pname:stdPPSCount member of the + slink:VkVideoEncodeH265SessionParametersAddInfoKHR structure included in + the pname:pUpdateInfo->pNext chain must: be less than or equal to the + slink:VkVideoEncodeH265SessionParametersCreateInfoKHR::pname:maxStdPPSCount + pname:videoSessionParameters was created with + * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-08321]] + If pname:videoSessionParameters was created with the video codec + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and the + pname:pNext chain of pname:pUpdateInfo includes a + slink:VkVideoEncodeH265SessionParametersAddInfoKHR structure, then + code:num_tile_columns_minus1 must: be less than + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxTiles.width, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile pname:videoSessionParameters was created with, for each element + of slink:VkVideoEncodeH265SessionParametersAddInfoKHR::pname:pStdPPSs + * [[VUID-vkUpdateVideoSessionParametersKHR-videoSessionParameters-08322]] + If pname:videoSessionParameters was created with the video codec + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR and the + pname:pNext chain of pname:pUpdateInfo includes a + slink:VkVideoEncodeH265SessionParametersAddInfoKHR structure, then + code:num_tile_rows_minus1 must: be less than + slink:VkVideoEncodeH265CapabilitiesKHR::pname:maxTiles.height, as + returned by flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video + profile pname:videoSessionParameters was created with, for each element + of slink:VkVideoEncodeH265SessionParametersAddInfoKHR::pname:pStdPPSs +endif::VK_KHR_video_encode_h265[] **** include::{generated}/validity/protos/vkUpdateVideoSessionParametersKHR.adoc[] @@ -2346,7 +2875,7 @@ follows: ifdef::VK_KHR_video_decode_h264[] [NOTE] -.Note: +.Note ==== It is possible for multiple bound reference picture resources to be associated with the same DPB slot index, or for a single bound reference @@ -2381,7 +2910,7 @@ session that are in the <> at the time this command is executed on the device. [NOTE] -.Note: +.Note ==== The application does not have to specify an entry in pname:pBeginInfo->pReferenceSlots corresponding to all active DPB slots of @@ -2391,6 +2920,36 @@ This way the application can avoid any potential runtime cost associated with binding the corresponding picture resources to the command buffer. ==== +ifdef::VK_KHR_video_encode_queue[] +In case of a video encode session, the application is also responsible for +providing information about the current <> configured for the video session by including an instance of +the slink:VkVideoEncodeRateControlInfoKHR structure in the pname:pNext chain +of pname:pBeginInfo. +If no slink:VkVideoEncodeRateControlInfoKHR is included, then the presence +of an empty slink:VkVideoEncodeRateControlInfoKHR structure is implied which +indicates that the current <> +is ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR. +The specified state must: <> the +effective rate control state configured for the video session at the time +the recorded command is executed on the device. + +[NOTE] +.Note +==== +Including an instance of the slink:VkVideoEncodeRateControlInfoKHR structure +in the pname:pNext chain of pname:pBeginInfo does not change the rate +control state configured for the video session, but only specifies the +expected rate control state configured at the time the recorded command is +executed on the device which allows the implementation to have information +about the configured rate control state at command buffer recording time. +In order to change the current rate control state of a video session, the +application has to issue an appropriate flink:vkCmdControlVideoCodingKHR +command as described in the <> +and <> sections. +==== +endif::VK_KHR_video_encode_queue[] + .Valid Usage **** * [[VUID-vkCmdBeginVideoCodingKHR-commandBuffer-07231]] @@ -2439,6 +2998,52 @@ with binding the corresponding picture resources to the command buffer. video picture resources currently associated with the DPB slot index of pname:pBeginInfo->videoSession specified by pname:slotIndex at the time the command is executed on the device +ifdef::VK_KHR_video_encode_queue[] + * [[VUID-vkCmdBeginVideoCodingKHR-pBeginInfo-08253]] + If pname:pBeginInfo->videoSession was created with a video encode + operation and the pname:pNext chain of pname:pBeginInfo does not include + an instance of the slink:VkVideoEncodeRateControlInfoKHR structure, then + the <> configured for + pname:pBeginInfo->videoSession at the time the command is executed on + the device must: be ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR + * [[VUID-vkCmdBeginVideoCodingKHR-pBeginInfo-08254]] + If pname:pBeginInfo->videoSession was created with a video encode + operation and the pname:pNext chain of pname:pBeginInfo includes an + instance of the slink:VkVideoEncodeRateControlInfoKHR structure, then it + must: <> the rate control + state configured for pname:pBeginInfo->videoSession at the time the + command is executed on the device +endif::VK_KHR_video_encode_queue[] +ifdef::VK_KHR_video_encode_h264[] + * [[VUID-vkCmdBeginVideoCodingKHR-pBeginInfo-08255]] + If pname:pBeginInfo->videoSession was created with the video codec + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, the + current <> is not + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR or + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, and + slink:VkVideoEncodeH264CapabilitiesKHR::pname:requiresGopRemainingFrames + is ename:VK_TRUE, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the + pname:pBeginInfo->videoSession was created with, then the pname:pNext + chain of pname:pBeginInfo must: include an instance of the + slink:VkVideoEncodeH264GopRemainingFrameInfoKHR with its + pname:useGopRemainingFrames member set to ename:VK_TRUE +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] + * [[VUID-vkCmdBeginVideoCodingKHR-pBeginInfo-08256]] + If pname:pBeginInfo->videoSession was created with the video codec + operation ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, the + current <> is not + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR or + ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, and + slink:VkVideoEncodeH265CapabilitiesKHR::pname:requiresGopRemainingFrames + is ename:VK_TRUE, as returned by + flink:vkGetPhysicalDeviceVideoCapabilitiesKHR for the video profile the + pname:pBeginInfo->videoSession was created with, then the pname:pNext + chain of pname:pBeginInfo must: include an instance of the + slink:VkVideoEncodeH265GopRemainingFrameInfoKHR with its + pname:useGopRemainingFrames member set to ename:VK_TRUE +endif::VK_KHR_video_encode_h265[] **** include::{generated}/validity/protos/vkCmdBeginVideoCodingKHR.adoc[] @@ -2561,18 +3166,18 @@ ifdef::VK_KHR_video_decode_h265[] ename:VK_VIDEO_CODEC_OPERATION_DECODE_H265_BIT_KHR, then pname:videoSessionParameters must: not be dname:VK_NULL_HANDLE endif::VK_KHR_video_decode_h265[] -ifdef::VK_EXT_video_encode_h264[] +ifdef::VK_KHR_video_encode_h264[] * [[VUID-VkVideoBeginCodingInfoKHR-videoSession-07249]] If pname:videoSession was created with the video codec operation - ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT, then + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, then pname:videoSessionParameters must: not be dname:VK_NULL_HANDLE -endif::VK_EXT_video_encode_h264[] -ifdef::VK_EXT_video_encode_h265[] +endif::VK_KHR_video_encode_h264[] +ifdef::VK_KHR_video_encode_h265[] * [[VUID-VkVideoBeginCodingInfoKHR-videoSession-07250]] If pname:videoSession was created with the video codec operation - ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT, then + ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, then pname:videoSessionParameters must: not be dname:VK_NULL_HANDLE -endif::VK_EXT_video_encode_h265[] +endif::VK_KHR_video_encode_h265[] * [[VUID-VkVideoBeginCodingInfoKHR-videoSessionParameters-04857]] If pname:videoSessionParameters is not dname:VK_NULL_HANDLE, it must: have been created with pname:videoSession specified in @@ -2688,9 +3293,9 @@ Correspondingly, any DPB slot index associated with the removed. ifdef::VK_KHR_video_encode_queue[] -For encode sessions, the reset operation returns rate control configuration -to implementation default settings and sets the video encode quality level -to zero. +For encode sessions, the reset operation returns <> configuration to implementation default settings and sets the +<> to zero. endif::VK_KHR_video_encode_queue[] After video coding operations are performed using a video session, the reset @@ -2699,6 +3304,22 @@ state as after the reset of a newly created video session. This can: be used, for example, when different video sequences are needed to be processed with the same video session object. +ifdef::VK_KHR_video_encode_queue[] +If pname:pCodingControlInfo->flags includes +ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, then the command +replaces the <> configuration maintained +by the video session with the configuration specified in the +slink:VkVideoEncodeRateControlInfoKHR structure included in the +pname:pCodingControlInfo->pNext chain. + +If pname:pCodingControlInfo->flags includes +ename:VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR, then the command +changes the current <> to +the value specified in the pname:qualityLevel member of the +slink:VkVideoEncodeQualityLevelInfoKHR structure included in the +pname:pCodingControlInfo->pNext chain. +endif::VK_KHR_video_encode_queue[] + .Valid Usage **** * [[VUID-vkCmdControlVideoCodingKHR-flags-07017]] @@ -2706,6 +3327,13 @@ be processed with the same video session object. ename:VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR, then the bound video session must: not be in <> state at the time the command is executed on the device +ifdef::VK_KHR_video_encode_queue[] + * [[VUID-vkCmdControlVideoCodingKHR-pCodingControlInfo-08243]] + If the bound video session was not created with an encode operation, + then pname:pCodingControlInfo->pNext must: not include + ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR or + ename:VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR +endif::VK_KHR_video_encode_queue[] **** include::{generated}/validity/protos/vkCmdControlVideoCodingKHR.adoc[] @@ -2731,46 +3359,12 @@ ifdef::VK_KHR_video_encode_queue[] ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, then the pname:pNext chain must: include a slink:VkVideoEncodeRateControlInfoKHR structure -endif::VK_KHR_video_encode_queue[] -ifdef::VK_EXT_video_encode_h264[] - * [[VUID-VkVideoCodingControlInfoKHR-flags-07021]] + * [[VUID-VkVideoCodingControlInfoKHR-flags-08349]] If pname:flags includes - ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, the - pname:rateControlMode member of slink:VkVideoEncodeRateControlInfoKHR - included in the pname:pNext chain is not - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR or - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, and the bound - video session was created with the video codec operation - ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_EXT, then the pname:pNext - chain must: include a slink:VkVideoEncodeH264RateControlInfoEXT - structure - * [[VUID-VkVideoCodingControlInfoKHR-pNext-07022]] - If the pname:pNext chain includes a - slink:VkVideoEncodeRateControlInfoKHR, and - slink:VkVideoEncodeRateControlInfoKHR::pname:layerCount is greater than - `1`, then - slink:VkVideoEncodeH264RateControlInfoEXT::pname:temporalLayerCount - must: be equal to pname:layerCount -endif::VK_EXT_video_encode_h264[] -ifdef::VK_EXT_video_encode_h265[] - * [[VUID-VkVideoCodingControlInfoKHR-flags-07024]] - If pname:flags includes - ename:VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR, the - pname:rateControlMode member of slink:VkVideoEncodeRateControlInfoKHR - included in the pname:pNext chain is not - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR or - ename:VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR, and the bound - video session was created with the video codec operation - ename:VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_EXT, then the pname:pNext - chain must: include a slink:VkVideoEncodeH265RateControlInfoEXT + ename:VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR, then the + pname:pNext chain must: include a slink:VkVideoEncodeQualityLevelInfoKHR structure - * [[VUID-VkVideoCodingControlInfoKHR-pNext-07025]] - If the pname:pNext chain includes a - slink:VkVideoEncodeRateControlInfoKHR, and - slink:VkVideoEncodeRateControlInfoKHR::pname:layerCount is greater than - `1`, then slink:VkVideoEncodeH265RateControlInfoEXT::pname:subLayerCount - must: be equal to pname:layerCount -endif::VK_EXT_video_encode_h265[] +endif::VK_KHR_video_encode_queue[] **** include::{generated}/validity/structs/VkVideoCodingControlInfoKHR.adoc[] @@ -2805,26 +3399,96 @@ zero or more elink:VkVideoCodingControlFlagBitsKHR. -- +ifdef::VK_KHR_video_maintenance1[] +[[video-inline-queries]] +== Inline Queries + +If a video session was created with +ename:VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, beginning queries +using commands such as flink:vkCmdBeginQuery within a video coding scope is +not allowed. +Instead, queries are executed inline by including an instance of the +slink:VkVideoInlineQueryInfoKHR structure in the pname:pNext chain of the +parameters of one of the video coding commands, with its pname:queryPool +member set to a valid sname:VkQueryPool handle. + +[open,refpage='VkVideoInlineQueryInfoKHR',desc='Structure specifying inline query information for video coding commands',type='structs'] +-- +The sname:VkVideoInlineQueryInfoKHR structure is defined as: + +include::{generated}/api/structs/VkVideoInlineQueryInfoKHR.adoc[] + + * pname:sType is a elink:VkStructureType value identifying this structure. + * pname:pNext is `NULL` or a pointer to a structure extending this + structure. + * pname:queryPool is dname:VK_NULL_HANDLE or a valid handle to a + slink:VkQueryPool object that will manage the results of the queries. + * pname:firstQuery is the query index within the query pool that will + contain the query results for the first video coding operation. + The query results of subsequent video coding operations will be + contained by subsequent query indices. + * pname:queryCount is the number of queries to execute. ++ +[NOTE] +.Note +==== +In practice, if pname:queryPool is not dname:VK_NULL_HANDLE, then +pname:queryCount will always have to match the number of video coding +operations issued by the video coding command this structure is specified +to, meaning that using inline queries in a video coding command will always +execute a query for each issued video coding operation. +==== + +This structure can: be included in the pname:pNext chain of the input +parameter structure of video coding commands. + +ifdef::VK_KHR_video_decode_queue[] + * In the pname:pNext chain of the pname:pDecodeInfo parameter of the + flink:vkCmdDecodeVideoKHR command to execute a query for each video + decode operation issued by the command. +endif::VK_KHR_video_decode_queue[] +ifdef::VK_KHR_video_encode_queue[] + * In the pname:pNext chain of the pname:pEncodeInfo parameter of the + flink:vkCmdEncodeVideoKHR command to execute a query for each video + encode operation issued by the command. +endif::VK_KHR_video_encode_queue[] + +.Valid Usage +**** + * [[VUID-VkVideoInlineQueryInfoKHR-queryPool-08372]] + If pname:queryPool is not dname:VK_NULL_HANDLE, then pname:firstQuery + must: be less than the number of queries in pname:queryPool + * [[VUID-VkVideoInlineQueryInfoKHR-queryPool-08373]] + If pname:queryPool is not dname:VK_NULL_HANDLE, then the sum of + pname:firstQuery and pname:queryCount must: be less than or equal to the + number of queries in pname:queryPool +**** + +include::{generated}/validity/structs/VkVideoInlineQueryInfoKHR.adoc[] +-- +endif::VK_KHR_video_maintenance1[] + + ifdef::VK_KHR_video_decode_queue[] -include::{chapters}/video_decode_extensions.adoc[] +include::{chapters}/video/decode.adoc[] endif::VK_KHR_video_decode_queue[] ifdef::VK_KHR_video_decode_h264[] -include::{chapters}/video_decode_h264_extensions.adoc[] +include::{chapters}/video/h264_decode.adoc[] endif::VK_KHR_video_decode_h264[] ifdef::VK_KHR_video_decode_h265[] -include::{chapters}/video_decode_h265_extensions.adoc[] +include::{chapters}/video/h265_decode.adoc[] endif::VK_KHR_video_decode_h265[] ifdef::VK_KHR_video_encode_queue[] -include::{chapters}/video_encode_extensions.adoc[] +include::{chapters}/video/encode.adoc[] endif::VK_KHR_video_encode_queue[] -ifdef::VK_EXT_video_encode_h264[] -include::{chapters}/video_encode_h264_extensions.adoc[] -endif::VK_EXT_video_encode_h264[] +ifdef::VK_KHR_video_encode_h264[] +include::{chapters}/video/h264_encode.adoc[] +endif::VK_KHR_video_encode_h264[] -ifdef::VK_EXT_video_encode_h265[] -include::{chapters}/video_encode_h265_extensions.adoc[] -endif::VK_EXT_video_encode_h265[] +ifdef::VK_KHR_video_encode_h265[] +include::{chapters}/video/h265_encode.adoc[] +endif::VK_KHR_video_encode_h265[] diff --git a/images/h26x_closed_gop.svg b/images/h26x_closed_gop.svg new file mode 100644 index 000000000..f82e6cf6d --- /dev/null +++ b/images/h26x_closed_gop.svg @@ -0,0 +1,922 @@ + + + + + + + + + + + + + + + + + + GOP frame count + + + + GOP frame count + + + + + + + + + + + IDR period + + + + IDR period + + + + + + + + + B + + + + B + + + + + + + + + ... + + + + ... + + + + + + + + + B + + + + B + + + + + + + + + IDR + + + + IDR + + + + + + + + + B + + + + B + + + + + + + + + B + + + + B + + + + + + + + + P + + + + P + + + + + + + + + B + + + + B + + + + + + + + + B + + + + B + + + + + + + + + B + + + + B + + + + + + + + + P + + + + P + + + + + + + + + B + + + + B + + + + + + + + + B + + + + B + + + + + + + + + IDR + + + + IDR + + + + + + + + + B + + + + B + + + + + + + + + ... + + + + ... + + + + + + + + + I + + + + I + + + + + + + + + B + + + + B + + + + + + + Text is not SVG - cannot display + + + diff --git a/images/h26x_layer_pattern_dyadic.svg b/images/h26x_layer_pattern_dyadic.svg new file mode 100644 index 000000000..b53386492 --- /dev/null +++ b/images/h26x_layer_pattern_dyadic.svg @@ -0,0 +1,3 @@ + + +
0
0
1
1
2
2
3
3
Temporal Layer
Temporal Layer
0
0
1
1
2
2
3
3
4
4
5
5
6
6
7
7
Temporal GOP Index
Temporal GOP Index
0
0
1
1
2
2
3
3
4
4
5
5
6
6
7
7Text is not SVG - cannot display \ No newline at end of file diff --git a/images/h26x_open_gop.svg b/images/h26x_open_gop.svg new file mode 100644 index 000000000..ef8c0051f --- /dev/null +++ b/images/h26x_open_gop.svg @@ -0,0 +1,3 @@ + + +
B
B
...
...
B
B
I
I
B
B
B
B
B
B
P
P
B
B
B
B
B
B
P
P
B
B
B
B
I
I
B
B
B
B
...
...
GOP frame count
GOP frame count
consecutive B-frame count
consecutive B-frame countText is not SVG - cannot display \ No newline at end of file diff --git a/images/h26x_ref_pattern_dyadic.svg b/images/h26x_ref_pattern_dyadic.svg new file mode 100644 index 000000000..2dffa7408 --- /dev/null +++ b/images/h26x_ref_pattern_dyadic.svg @@ -0,0 +1,3 @@ + + +
B
B
...
...
B
B
I
I
B
B
B
B
B
B
P
P
B
B
B
B
B
B
P
P
B
B
B
B
I
I
B
B
B
B
...
...Text is not SVG - cannot display \ No newline at end of file diff --git a/images/h26x_ref_pattern_flat.svg b/images/h26x_ref_pattern_flat.svg new file mode 100644 index 000000000..08d15f14d --- /dev/null +++ b/images/h26x_ref_pattern_flat.svg @@ -0,0 +1,3 @@ + + +
B
B
...
...
B
B
I
I
B
B
B
B
B
B
P
P
B
B
B
B
B
B
P
P
B
B
B
B
I
I
B
B
B
B
...
...Text is not SVG - cannot display \ No newline at end of file diff --git a/proposals/VK_KHR_maintenance6.adoc b/proposals/VK_KHR_maintenance6.adoc new file mode 100644 index 000000000..13de9d99f --- /dev/null +++ b/proposals/VK_KHR_maintenance6.adoc @@ -0,0 +1,197 @@ +// Copyright 2023 The Khronos Group Inc. +// SPDX-License-Identifier: CC-BY-4.0 + += Proposal Template +:toc: left +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ +:sectnums: + +This proposal details and addresses the issues solved by the `VK_KHR_maintenance6` extension. + +== Problem Statement + +Over time, a collection of minor features, none of which would warrant an +entire extension of their own, requires the creation of a maintenance +extension. + +The following is a list of issues considered in this proposal: + + * `vkBindBufferMemory2` and `vkBindImageMemory2` accept arrays of memory + binding parameters, but the commands only return a single `VkResult` value. + This makes it impossible to identify which specific memory binding operation + failed, and leaves resources in an indeterminate, unusable state. + * Add a property to describe if an implementation clamps the inputs to + fragment shading rate combiner operations. + * There are some use cases where an index buffer must be bound, even if it is + not used, and the specification currently forbids the use of + `VK_NULL_HANDLE`. + * Need a `maxCombinedImageSamplerDescriptorCount` value, for cases where + you need to create a descriptor set layout, but do not know which + formats which will be used (and therefore cannot query it). + * Creating image views with ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT + and multiple layers is supported by all modern hardware, so this should be exposed + by the API. + * `pNext` extensible *2 versions of all descriptor binding commands. + +== Proposal + +=== New features + +The following features are exposed: + +[source,c] +---- +typedef struct VkPhysicalDeviceMaintenance6FeaturesKHR { + VkStructureType sType; + void* pNext; + VkBool32 maintenance6; +} VkPhysicalDeviceMaintenance6FeaturesKHR; +---- + + * The `maintenance6` feature indicates support for the `VK_KHR_maintenance6` extension. + +=== New properties + +The following device properties are exposed: + +[source,c] +---- +typedef struct VkPhysicalDeviceMaintenance6PropertiesKHR { + VkStructureType sType; + void* pNext; + VkBool32 blockTexelViewCompatibleMultipleLayers; + uint32_t maxCombinedImageSamplerDescriptorCount; + VkBool32 fragmentShadingRateClampCombinerInputs; +} VkPhysicalDeviceMaintenance6PropertiesKHR; +---- + + * The `blockTexelViewCompatibleMultipleLayers` property indicates whether a `VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT` + can be used with a `layerCount` of greater than `1`. + * The `maxCombinedImageSamplerDescriptorCount` property indicates the maximum number of descriptors needed for any of the multi-planar formats + supported by the implementation that require `YCbCr` conversion . + * The `fragmentShadingRateClampCombinerInputs` property indicates if an implementation clamps the inputs to fragment shading rate combiner operations. + +=== New binding status structure + +[source,c] +---- +typedef struct VkBindMemoryStatusKHR { + VkStructureType sType; + const void* pNext; + VkResult* pResult; +} VkBindMemoryStatusKHR; +---- + +The `VkBindMemoryStatusKHR` structure can be included in the `pNext` chain of `VkBindBufferMemoryInfo` and +`VkBindImageMemoryInfo`, allowing applications to retrieve `VkResult` values for individual memory binding operations. + +=== New index buffer binding functionality + +`VK_NULL_HANDLE` can now be used in index buffer binding functions, in place +of a valid `VkBuffer` handle. When the `nullDescriptor` feature is enabled, +every index fetched results in a value of zero. + + +=== New functions + +The following new functions are added in order to support future extensibility: + +[source,c] +---- +typedef struct VkBindDescriptorSetsInfoKHR { + VkStructureType sType; + const void* pNext; + VkShaderStageFlags stageFlags; + VkPipelineLayout layout; + uint32_t firstSet; + uint32_t descriptorSetCount; + const VkDescriptorSet* pDescriptorSets; + uint32_t dynamicOffsetCount; + const uint32_t* pDynamicOffsets; +} VkBindDescriptorSetsInfoKHR; + +typedef struct VkPushConstantsInfoKHR { + VkStructureType sType; + const void* pNext; + VkPipelineLayout layout; + VkShaderStageFlags stageFlags; + uint32_t offset; + uint32_t size; + const void* pValues; +} VkPushConstantsInfoKHR; + +typedef struct VkPushDescriptorSetInfoKHR { + VkStructureType sType; + const void* pNext; + VkShaderStageFlags stageFlags; + VkPipelineLayout layout; + uint32_t set; + uint32_t descriptorWriteCount; + const VkWriteDescriptorSet* pDescriptorWrites; +} VkPushDescriptorSetInfoKHR; + +typedef struct VkPushDescriptorSetWithTemplateInfoKHR { + VkStructureType sType; + const void* pNext; + VkDescriptorUpdateTemplate descriptorUpdateTemplate; + VkPipelineLayout layout; + uint32_t set; + const void* pData; +} VkPushDescriptorSetWithTemplateInfoKHR; + +typedef struct VkSetDescriptorBufferOffsetsInfoEXT { + VkStructureType sType; + const void* pNext; + VkShaderStageFlags stageFlags; + VkPipelineLayout layout; + uint32_t firstSet; + uint32_t setCount; + const uint32_t* pBufferIndices; + const VkDeviceSize* pOffsets; +} VkSetDescriptorBufferOffsetsInfoEXT; + +typedef struct VkBindDescriptorBufferEmbeddedSamplersInfoEXT { + VkStructureType sType; + const void* pNext; + VkShaderStageFlags stageFlags; + VkPipelineLayout layout; + uint32_t set; +} VkBindDescriptorBufferEmbeddedSamplersInfoEXT; + +void vkCmdBindDescriptorSets2KHR( + VkCommandBuffer commandBuffer, + const VkBindDescriptorSetsInfoKHR* pBindDescriptorSetsInfo); + +void vkCmdPushConstants2KHR( + VkCommandBuffer commandBuffer, + const VkPushConstantsInfoKHR* pPushConstantsInfo); + +void vkCmdPushDescriptorSet2KHR( + VkCommandBuffer commandBuffer, + const VkPushDescriptorSetInfoKHR* pPushDescriptorSetInfo); + +void vkCmdPushDescriptorSetWithTemplate2KHR( + VkCommandBuffer commandBuffer, + const VkPushDescriptorSetWithTemplateInfoKHR* pPushDescriptorSetWithTemplateInfo); + +void vkCmdSetDescriptorBufferOffsets2EXT( + VkCommandBuffer commandBuffer, + const VkSetDescriptorBufferOffsetsInfoEXT* pSetDescriptorBufferOffsetsInfo); + +void vkCmdBindDescriptorBufferEmbeddedSamplers2EXT( + VkCommandBuffer commandBuffer, + const VkBindDescriptorBufferEmbeddedSamplersInfoEXT* pBindDescriptorBufferEmbeddedSamplersInfo); +---- + +The parameters of the structures are identical to the arguments of the +existing functions, except that `VkPipelineBindPoint` is replaced with +`VkShaderStageFlagBits`. + +== Issues + +None. + + +== Further Functionality + +None. diff --git a/proposals/VK_KHR_video_decode_h264.adoc b/proposals/VK_KHR_video_decode_h264.adoc index ab3480b6a..71bac044f 100644 --- a/proposals/VK_KHR_video_decode_h264.adoc +++ b/proposals/VK_KHR_video_decode_h264.adoc @@ -352,7 +352,7 @@ vkUpdateVideoSessionParametersKHR(device, &videoSessionParams, &updateInfo); ---- -=== Record H.264 decode operation (without reconstructed picture setup or reference pictures) +=== Record H.264 decode operation (video session without DPB slots) [source,c] ---- @@ -374,6 +374,10 @@ VkVideoDecodeInfoKHR decodeInfo = { .sType = VK_STRUCTURE_TYPE_VIDEO_DECODE_INFO_KHR, .pNext = &decodeH264PictureInfo, ... + // reconstructed picture is not needed if video session was created without DPB slots + .pSetupReferenceSlot = NULL, + .referenceSlotCount = 0, + .pReferenceSlots = NULL }; vkCmdDecodeVideoKHR(commandBuffer, &decodeInfo); @@ -382,7 +386,7 @@ vkCmdEndVideoCodingKHR(commandBuffer, ...); ---- -=== Record H.264 decode operation with reconstructed picture setup +=== Record H.264 decode operation with optional reference picture setup [source,c] ---- @@ -404,8 +408,26 @@ VkVideoReferenceSlotInfoKHR setupSlotInfo = { ... }; +StdVideoDecodeH264PictureInfo stdPictureInfo = {}; +// parse and populate picture info from frame header data +... +if (stdPictureInfo.flags.is_reference) { + // reconstructed picture will be used for reference picture setup and DPB slot activation +} else { + // reconstructed picture and slot may only be used by implementations as transient resource +} + +VkVideoDecodeH264PictureInfoKHR decodeH264PictureInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PICTURE_INFO_KHR, + .pNext = NULL, + .pStdPictureInfo = &stdPictureInfo, + .sliceCount = ... // number of slices + .pSliceOffsets = ... // array of slice offsets relative to the bitstream buffer range +}; + VkVideoDecodeInfoKHR decodeInfo = { .sType = VK_STRUCTURE_TYPE_VIDEO_DECODE_INFO_KHR, + .pNext = &decodeH264PictureInfo, ... .pSetupReferenceSlot = &setupSlotInfo, ... @@ -456,8 +478,27 @@ VkVideoReferenceSlotInfoKHR referenceSlotInfo[] = { ... }; + +StdVideoDecodeH264PictureInfo stdPictureInfo = {}; +// parse and populate picture info from frame header data +... +if (stdPictureInfo.flags.is_reference) { + // reconstructed picture will be used for reference picture setup and DPB slot activation +} else { + // reconstructed picture and slot may only be used by implementations as transient resource +} + +VkVideoDecodeH264PictureInfoKHR decodeH264PictureInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_DECODE_H264_PICTURE_INFO_KHR, + .pNext = NULL, + .pStdPictureInfo = &stdPictureInfo, + .sliceCount = ... // number of slices + .pSliceOffsets = ... // array of slice offsets relative to the bitstream buffer range +}; + VkVideoDecodeInfoKHR decodeInfo = { .sType = VK_STRUCTURE_TYPE_VIDEO_DECODE_INFO_KHR, + .pNext = &decodeH264PictureInfo, ... .referenceSlotCount = sizeof(referenceSlotInfo) / sizeof(referenceSlotInfo[0]), .pReferenceSlots = &referenceSlotInfo[0] @@ -527,6 +568,13 @@ Not as part of this extension, but future extensions can add support for that. W For historical reasons, the `StdVideoH264Level` type is defined with ordinal enum constant values, which does not match the decimal encoding used by the H.264/AVC video compression standard specification. All APIs defined by this extension and the used video std headers accept and report H.264 levels using the enum constants `STD_VIDEO_H264_LEVEL_.`, not the decimal encoding used within raw H.264/AVC bitstreams. +=== RESOLVED: How is reference picture setup requested for H.264 decode operations? + +As specifying a reconstructed picture DPB slot and resource is always required per the latest revision of the video extensions, additional codec syntax controls whether reference picture setup is requested and, in response, the DPB slot is activated with the reconstructed picture. + +For H.264 decode, reference picture setup is requested and the DPB slot specified for the reconstructed picture is activated with the picture if and only if the `StdVideoDecodeH264PictureInfo::flags.is_reference` flag is set. + + == Further Functionality Future extensions can further extend the capabilities provided here, e.g. exposing support to decode H.264 Multiview content. diff --git a/proposals/VK_KHR_video_decode_h265.adoc b/proposals/VK_KHR_video_decode_h265.adoc index 21ac86330..3f913b7ec 100644 --- a/proposals/VK_KHR_video_decode_h265.adoc +++ b/proposals/VK_KHR_video_decode_h265.adoc @@ -172,7 +172,7 @@ typedef struct VkVideoDecodeH265DpbSlotInfoKHR { It is the application's responsibility to specify video bitstream buffer data and codec-specific parameters that are compliant to the rules defined by the H.265/HEVC video compression standard. While it is not illegal, from the API usage's point of view, to specify non-compliant inputs, they may cause the video decode operation to complete unsuccessfully and will cause the output pictures (decode output and reconstructed pictures) to have undefined contents after the execution of the operation. -For more information about how to parse individual H.265 bitstream syntax elements, calculate derived values, and, in general, how to interpret these parameters, please refer to the corresponding sections of the https://www.itu.int/rec/T-REC-H.265-202108-I/[ITU-T H.265 Specification]. +For more information about how to parse individual H.265 bitstream syntax elements, calculate derived values, and, in general, how to interpret these parameters, please refer to the corresponding sections of the https://www.itu.int/rec/T-REC-H.265-202108-S/[ITU-T H.265 Specification]. == Examples @@ -324,7 +324,7 @@ vkUpdateVideoSessionParametersKHR(device, &videoSessionParams, &updateInfo); ---- -=== Record H.265 decode operation (without reconstructed picture setup or reference pictures) +=== Record H.265 decode operation (video session without DPB slots) [source,c] ---- @@ -346,6 +346,10 @@ VkVideoDecodeInfoKHR decodeInfo = { .sType = VK_STRUCTURE_TYPE_VIDEO_DECODE_INFO_KHR, .pNext = &decodeH265PictureInfo, ... + // reconstructed picture is not needed if video session was created without DPB slots + .pSetupReferenceSlot = NULL, + .referenceSlotCount = 0, + .pReferenceSlots = NULL }; vkCmdDecodeVideoKHR(commandBuffer, &decodeInfo); @@ -354,7 +358,7 @@ vkCmdEndVideoCodingKHR(commandBuffer, ...); ---- -=== Record H.265 decode operation with reconstructed picture setup +=== Record H.265 decode operation with optional reference picture setup [source,c] ---- @@ -376,8 +380,27 @@ VkVideoReferenceSlotInfoKHR setupSlotInfo = { ... }; + +StdVideoDecodeH265PictureInfo stdPictureInfo = {}; +// parse and populate picture info from frame header data +... +if (stdPictureInfo.flags.IsReference) { + // reconstructed picture will be used for reference picture setup and DPB slot activation +} else { + // reconstructed picture and slot may only be used by implementations as transient resource +} + +VkVideoDecodeH265PictureInfoKHR decodeH265PictureInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PICTURE_INFO_KHR, + .pNext = NULL, + .pStdPictureInfo = &stdPictureInfo, + .sliceSegmentCount = ... // number of slice segments + .pSliceSegmentOffsets = ... // array of slice segment offsets relative to the bitstream buffer range +}; + VkVideoDecodeInfoKHR decodeInfo = { .sType = VK_STRUCTURE_TYPE_VIDEO_DECODE_INFO_KHR, + .pNext = &decodeH265PictureInfo, ... .pSetupReferenceSlot = &setupSlotInfo, ... @@ -428,8 +451,27 @@ VkVideoReferenceSlotInfoKHR referenceSlotInfo[] = { ... }; + +StdVideoDecodeH265PictureInfo stdPictureInfo = {}; +// parse and populate picture info from frame header data +... +if (stdPictureInfo.flags.IsReference) { + // reconstructed picture will be used for reference picture setup and DPB slot activation +} else { + // reconstructed picture and slot may only be used by implementations as transient resource +} + +VkVideoDecodeH265PictureInfoKHR decodeH265PictureInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_DECODE_H265_PICTURE_INFO_KHR, + .pNext = NULL, + .pStdPictureInfo = &stdPictureInfo, + .sliceSegmentCount = ... // number of slice segments + .pSliceSegmentOffsets = ... // array of slice segment offsets relative to the bitstream buffer range +}; + VkVideoDecodeInfoKHR decodeInfo = { .sType = VK_STRUCTURE_TYPE_VIDEO_DECODE_INFO_KHR, + .pNext = &decodeH265PictureInfo, ... .referenceSlotCount = sizeof(referenceSlotInfo) / sizeof(referenceSlotInfo[0]), .pReferenceSlots = &referenceSlotInfo[0] @@ -487,6 +529,13 @@ It is thus not recommended for applications to statically allocate for the worst For historical reasons, the `StdVideoH265Level` type is defined with ordinal enum constant values, which does not match the decimal encoding used by the H.265/HEVC video compression standard specification. All APIs defined by this extension and the used video std headers accept and report H.265 levels using the enum constants `STD_VIDEO_H265_LEVEL_.`, not the decimal encoding used within raw H.265/HEVC bitstreams. +=== RESOLVED: How is reference picture setup requested for H.265 decode operations? + +As specifying a reconstructed picture DPB slot and resource is always required per the latest revision of the video extensions, additional codec syntax controls whether reference picture setup is requested and, in response, the DPB slot is activated with the reconstructed picture. + +For H.265 decode, reference picture setup is requested and the DPB slot specified for the reconstructed picture is activated with the picture if and only if the `StdVideoDecodeH265PictureInfo::flags.IsReference` flag is set. + + == Further Functionality Future extensions can further extend the capabilities provided here, e.g. exposing support to decode H.265 Multiview content. diff --git a/proposals/VK_KHR_video_decode_queue.adoc b/proposals/VK_KHR_video_decode_queue.adoc index 750ec0fa9..3f08f8b1b 100644 --- a/proposals/VK_KHR_video_decode_queue.adoc +++ b/proposals/VK_KHR_video_decode_queue.adoc @@ -18,7 +18,7 @@ Integrating video decode operations into Vulkan applications enable a wide set o It is also not uncommon for Vulkan capable devices to feature dedicated hardware acceleration for video decompression. -The goal of this proposal is to enable these use cases, allow exposing the underlying hardware capabilities, and provide tight integration with other functionalities of the Vulkan API. +The goal of this proposal is to enable these use cases, expose the underlying hardware capabilities, and provide tight integration with other functionalities of the Vulkan API. == Solution Space @@ -102,7 +102,7 @@ This extension also introduces the following new image usage flags: * `VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR` allows using the image as a decode output picture * `VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR` allows using the image as a decode DPB picture (reconstructed/reference picture) -Specifying these usage flags alone is not sufficient to create a buffer or image that is compatible to be used with a video session created against any particular video profile. In fact, when specifying any of these usage flags at resource creation time, the application has to include a `VkVideoProfileListInfoKHR` structure in the `pNext` chain of the corresponding create info structure that includes a video decode profile. The created resources will be compatible only with that single video decode profile (and any additional video encode profiles that may have been specified in the list). +Specifying these usage flags alone is not sufficient to create a buffer or image that is compatible with a video session created against any particular video profile. In fact, when specifying any of these usage flags at resource creation time, the application has to include a `VkVideoProfileListInfoKHR` structure in the `pNext` chain of the corresponding create info structure with `VkVideoProfileListInfoKHR::pProfiles` including a video decode profile. The created resources will be compatible only with that single video decode profile (and any additional video encode profiles that may have been specified in the list). === New Format Feature Flags @@ -170,9 +170,20 @@ The image subresource backing the decode output picture has to be in the new `VK === Reconstructed Picture -`pSetupReferenceSlot` is an optional parameter specifying the video picture resource to use as the reconstructed picture and the DPB slot index to activate with it. Content-wise, a reconstructed picture is generally identical to the decode output picture, but unlike the latter, the reconstructed picture can be used as a reference picture in future video decode operations, hence it is a picture that is part of the DPB. +`pSetupReferenceSlot` is an optional parameter specifying the video picture resource and DPB slot index to use for the reconstructed picture. Implementations use the reconstructed picture for one of the following purposes: -When a non-`NULL` `pSetupReferenceSlot` is specified, the DPB slot identified by its `slotIndex` member is activated with the video picture resource specified by its `pPictureResource` member. Hence this parameter can be used to add new reference pictures to the DPB, and change the association between DPB slot indices and video picture resources. That also implies that the application has to specify a video picture resource in `pSetupReferenceSlot->pPictureResource` that was included in the set of bound reference picture resources specified when the video coding scope was started (in one of the elements of `VkVideoBeginCodingInfoKHR::pReferenceSlots`). No similar requirement exists for the decode output picture specified by `dstPictureResource` which can refer to any video picture resource. + 1. When the decoded picture is requested to be set up as a reference, according to the codec-specific semantics, the video decode operation will output the raw decoding results to this picture and activate the reconstructed picture's DPB slot with it in order to enable using the picture as a reference picture in future video decode operations. Content-wise, this picture is generally identical to the decode output picture unless the decode output picture contains any sort of post-processing (e.g. film grain). + 2. When the decoded picture is not requested to be set up as a reference, implementations may use the reconstructed picture's resource and/or DPB slot for intermediate data required by the decoding process. + +Accordingly, `pSetupReferenceSlot` must never be `NULL`, except when the video session was created without any DPB slots. + +[NOTE] +.Note +==== +The original version of this extension only required the specification of the reconstructed picture information (i.e. a non-`NULL` `pSetupReferenceSlot`) when the application intended to set up a reference picture by activating a DPB slot. Consequently, the presence of reconstructed picture information always implied DPB slot activation. This was changed in revision 8 of the extension, and whether DPB slot activation happens is now subject to codec-specific semantics. More details on this change are discussed in the corresponding issue in this proposal document. +==== + +In summary, for decoded pictures requested to be set up as a reference, this parameter can be used to add new reference pictures to the DPB, and change the association between DPB slot indices and video picture resources. That also implies that the application has to specify a video picture resource in `pSetupReferenceSlot->pPictureResource` that was included in the set of bound reference picture resources specified when the video coding scope was started (in one of the elements of `VkVideoBeginCodingInfoKHR::pReferenceSlots`). No similar requirement exists for the decode output picture specified by `dstPictureResource` which can refer to any video picture resource. The application has to create the image view specified in `pSetupReferenceSlot->pPictureResource->imageViewBinding` with the new `VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR` usage flag, and must also include the used video session's video profile in the `VkVideoProfileListInfoKHR` structure specified at image creation time. @@ -188,8 +199,14 @@ Support for the individual modes is indicated by the `VK_VIDEO_DECODE_CAPABILITY Generally speaking, the application has to create the following images in order to decode a video stream: - * One or more images that will contain the reference pictures associated with the DPB. - * An additional image usable as the decode output picture (if not all decoded pictures are expected to be stored in the DPB). + * One or more images usable as reconstructed pictures, some of which will contain the reference pictures associated with the DPB. + * Optionally, an additional image usable as the decode output picture when the reconstructed picture has to be _distinct_ or when using video sessions without any DPB slots. + +[NOTE] +.Note +==== +In practice, applications will typically allocate more than one decode output pictures for buffering purposes and/or to minimize synchronization overhead resulting from having to prevent write-after-write hazards across subsequent video decode operations targeting the same decode output picture resource. Some applications may also allocate more resources for reference pictures than the number of DPB slots for similar reasons. +==== The application should always create the image(s) backing the DPB with the `VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR` usage flag. If only the _coincide_ mode is supported for reconstructed pictures, then the DPB image(s) that may be used as a reconstructed picture in a video decode operation have to also include the `VK_IMAGE_USAGE_VIDEO_DECODE_DST_KHR` usage flag to allow them to be used as coinciding decode output and reconstructed pictures. @@ -197,10 +214,10 @@ The image backing the decode output picture should always be created with the `V The DPB image(s) are expected to be in the `VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR` layout while in use by video decode operations, while the decode output image is expected to be in the `VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR` layout. -Now we have two cases to consider: +Here we have two cases to consider: - 1. When a reconstructed picture needs to be specified (as the picture is expected to be used as a reference picture later on); and - 2. When one is not needed (`pSetupReferenceSlot = NULL`) + 1. When a reconstructed picture is specified; and + 2. When one is not needed (as the video session was created without any DPB slots) In case of (2), the application can use the image created for the decode output picture in `dstPictureResource`, indifferent of whether the _distinct_ or _coincide_ mode is used. @@ -218,11 +235,11 @@ If the video profile in use requires additional codec-specific parameters for th If the video session allows, reference pictures can be specified in the `pReferenceSlots` array to provide predictions of the values of samples of the decoded picture. -Each entry in the `pReferenceSlots` array adds one or more pictures, currently associated with the DPB slot specified in the element's `slotIndex` member and stored in the video picture specified in the element's `pPictureResource` member, to the list of active reference pictures to use in the video decode operation. +Each entry in the `pReferenceSlots` array adds one or more pictures, currently associated with the DPB slot specified in the element's `slotIndex` member and stored in the video picture resource specified in the element's `pPictureResource` member, to the list of active reference pictures to use in the video decode operation. The application has to make sure to specify each video picture resource used as a reference picture in a video decode operation, beforehand, in the set of bound reference picture resources specified when the video coding scope was started (in one of the elements of `VkVideoBeginCodingInfoKHR::pReferenceSlots`). -The application has to create the image view specified in `pPictureResource->imageViewBinding` of the elements of `pReferenceSlots` with the new `VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR`` usage flag, and must also include the used video session’s video profile in the `VkVideoProfileListInfoKHR` structure specified at image creation time. +The application has to create the image view specified in `pPictureResource->imageViewBinding` of the elements of `pReferenceSlots` with the new `VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR` usage flag, and must also include the used video session’s video profile in the `VkVideoProfileListInfoKHR` structure specified at image creation time. The image subresources backing the reference pictures have to be in the new `VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR` layout at the time the video decode operation is executed. @@ -270,8 +287,7 @@ Before the application can start recording command buffers with video decode ope . Construct the `VkVideoProfileInfoKHR` structure describing the entire video profile, including the video codec operation, chroma subsampling, bit depths, and any other usage or codec-specific parameters. . Ensure that the specific video profile is supported by the implementation using the `vkGetPhysicalDeviceVideoCapabilitiesKHR` command and retrieve the general, decode-specific, and codec-specific capabilities at the same time. . Query the list of supported image/picture format properties supported for the video profile using the `vkGetPhysicalDeviceVideoFormatPropertiesKHR` structure, and select a suitable format for the DPB and decode output pictures. - . Create an image corresponding to the decode output picture with the appropriate usage flags and video profile list, as described earlier, and bind suitable device memory to the image. Also create an image view with the appropriate usage flags to use in the video decode operations. - . If needed, create one or more images corresponding to the DPB pictures with the appropriate usage flags and video profile list, as described earlier, and bind suitable device memory to them. Also create any image views with the appropriate usage flags to use in the video decode operations. + . If needed, create one or more images corresponding to the decode output picture(s) and/or DPB picture(s) with the appropriate usage flags and video profile list, as described earlier, and bind suitable device memory to them. Also create any image views with the appropriate usage flags to use in the video decode operations. . Create a buffer with the `VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR` usage flag and the video profile list, to use as the source video bitstream buffer. If the buffer is expected to be populated using the CPU, consider binding compatible host-visible device memory to the buffer. . If result status queries are needed and supported (as determined earlier), create a query pool with the `VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR` query type and the used video decode profile. . Create the video session using the video decode profile and appropriate parameters within the capabilities supported by the profile, as determined earlier. Bind suitable device memory to each memory binding index of the video session. @@ -563,7 +579,7 @@ vkCreateImageView(device, &imageViewCreateInfo, NULL, &dpbImageView); ---- -=== Record decode operation (without reconstructed picture setup or reference pictures) +=== Record decode operation (video session without DPB slots) [source,c] ---- @@ -597,7 +613,7 @@ vkCmdEndVideoCodingKHR(commandBuffer, ...); ---- -=== Record decode operation with reconstructed picture setup (DISTINCT mode) +=== Record decode operation with reconstructed picture information (DISTINCT mode) [source,c] ---- @@ -625,7 +641,8 @@ VkVideoPictureResourceInfoKHR reconstructedPictureResource = { VkVideoReferenceSlotInfoKHR setupSlotInfo = { .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, .pNext = ... // pointer to codec-specific reconstructed picture information structure - .slotIndex = ... // DPB slot index to activate with the reconstructed picture + .slotIndex = ... // DPB slot index to use with the reconstructed picture + // (optionally activated per the codec-specific semantics) .pPictureResource = &reconstructedPictureResource }; @@ -644,7 +661,7 @@ vkCmdEndVideoCodingKHR(commandBuffer, ...); ---- -=== Record decode operation with reconstructed picture setup (COINCIDE mode) +=== Record decode operation with reconstructed picture information (COINCIDE mode) [source,c] ---- @@ -663,7 +680,8 @@ VkVideoPictureResourceInfoKHR reconstructedPictureResource = { VkVideoReferenceSlotInfoKHR setupSlotInfo = { .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, .pNext = ... // pointer to codec-specific reconstructed picture information structure - .slotIndex = ... // DPB slot index to activate with the reconstructed picture + .slotIndex = ... // DPB slot index to use with the reconstructed picture + // (optionally activated per the codec-specific semantics) .pPictureResource = &reconstructedPictureResource }; @@ -790,6 +808,23 @@ There are no specific behavioral effects associated with any of the video decode However, just like any other additional video profile information included in the `pNext` chain of `VkVideoProfileInfoKHR` structures, they are part of the video profile definition, hence whenever matching video profiles have to be provided to an API call, let that be queries or resource creation structures, the application must provide identical video decode usage hint values. This also applies if the application does not include the `VkVideoDecodeUsageInfoKHR` structure, which is treated equivalently to specifying the structure with `videoUsageHints` equal to `VK_VIDEO_DECODE_USAGE_DEFAULT_KHR` (or zero), per the usual conventions of Vulkan. +=== RESOLVED: When is it mandatory to specify reconstructed picture information in `VkVideoDecodeInfoKHR::pSetupReferenceSlot`? + +In the original version of this extension, specifying a non-`NULL` `pSetupReferenceSlot` parameter was only required for activating DPB slots with reference pictures, but no shipping implementation actually supported specifying `NULL` for `pSetupReferenceSlot`. In the end, some implementations turned out to require a reconstructed picture resource and/or DPB slot, even when the decoded picture is not expected to be used as a reference picture by future video decode operations, so this extension has been changed with revision 8 as follows: + + 1. Specifying reconstructed picture information (i.e. a non-`NULL` `pSetupReferenceSlot`) is made mandatory for all cases except when the video session was created with no DPB slots + 2. Reference picture setup (and, inherently, DPB slot activation) was changed to be subject to codec-specific behavior, meaning that specifying a non-`NULL` `pSetupReferenceSlot` will only trigger reference picture setup if the appropriate codec-specific parameters or semantics indicate so (typically in the form of marking the decoded picture as reference) + +(2) was necessary in order to avoid unnecessary DPB slot activation and the cost of populating the reconstructed picture resource when it is distinct from the decode output and the reconstructed picture is not intended to be used as a reference picture by future video decode operations. However, as some implementations may use the reconstructed picture resource and/or DPB slot as transient storage during the decoding process, if a non-`NULL` `pSetupReferenceSlot` is specified but no reference picture setup is requested, then the contents of the reconstructed picture resource become undefined and some of the picture references associated with the reconstructed picture's DPB slot may get invalidated. + +While this change breaks backward-compatibility, no implementation actually supported the removed behavior, thus it should not have any effect on shipping applications. + + +=== RESOLVED: Does always requiring the specification of reconstructed picture information in `VkVideoDecodeInfoKHR::pSetupReferenceSlot` have any undesired performance consequences? + +There may be performance implications when using _distinct_ mode, i.e. using a reconstructed picture resource that is distinct from the decode output picture. As discussed in the previous issue, the explicit codec-specific opt-in for reference picture setup allows implementations to avoid consuming twice as much memory bandwidth to also write out the reconstructed picture when it is otherwise not needed. However, as it is implementation-specific whether the reconstructed picture is written to, even when no reference picture setup takes place, the reconstructed picture becomes a shared resource that the application has to synchronize in order to avoid write-after-write hazards. Accordingly, depending on the implementation, there may be some performance implications to always requiring the specification of reconstructed picture information. + + == Further Functionality This extension is meant to provide only common video decode functionality, thus support for individual video decode profiles using specific video compression standards is left for extensions layered on top of the infrastructure provided here. diff --git a/proposals/VK_KHR_video_encode_h264.adoc b/proposals/VK_KHR_video_encode_h264.adoc new file mode 100644 index 000000000..caf4c9505 --- /dev/null +++ b/proposals/VK_KHR_video_encode_h264.adoc @@ -0,0 +1,817 @@ +// Copyright 2021-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_KHR_video_encode_h264 +:toc: left +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ +:sectnums: + +This document outlines a proposal to enable performing H.264/AVC video encode operations in Vulkan. + +== Problem Statement + +The `VK_KHR_video_queue` extension introduces support for video coding operations and the `VK_KHR_video_encode_queue` extension further extends this with APIs specific to video encoding. + +The goal of this proposal is to build upon this infrastructure to introduce support for encoding elementary video stream sequences compliant with the H.264/AVC video compression standard. + + +== Solution Space + +As the `VK_KHR_video_queue` and `VK_KHR_video_encode_queue` extensions already laid down the architecture for how codec-specific video encode extensions need to be designed, this extension only needs to define the APIs to provide the necessary codec-specific parameters at various points during the use of the codec-independent APIs. In particular: + + * APIs allowing to specify H.264 sequence and picture parameter sets (SPS, PPS) to be stored in video session parameters objects + * APIs allowing to specify H.264 information specific to the encoded picture, including references to previously stored SPS and PPS entries + * APIs allowing to specify H.264 reference picture information specific to the active reference pictures and optional reconstructed picture used in video encode operations + +Codec-specific encoding parameters are specified by the application through custom definitions provided by a video std header dedicated to H.264 video encoding. + +This proposal uses the common H.264 definitions first utilized by the `VK_KHR_video_decode_h264` extension and augments it with another video std header specific to H.264 encoding. Thus this extension uses the following video std headers: + + * `vulkan_video_codec_h264std` - containing common definitions for all H.264 video coding operations + * `vulkan_video_codec_h264std_encode` - containing definitions specific to H.264 video encoding operations + +These headers can be included as follows: + +[source,c] +---- +#include +#include +---- + + +== Proposal + +=== Video Std Headers + +This extension uses the new `vulkan_video_codec_h264std_encode` video std header. Implementations must always support at least version 1.0.0 of this video std header. + + +=== H.264 Encode Profiles + +This extension introduces the new video codec operation `VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR`. This flag can be used to check whether a particular queue family supports encoding H.264/AVC content, as returned in `VkQueueFamilyVideoPropertiesKHR`. + +An H.264 encode profile can be defined through a `VkVideoProfileInfoKHR` structure using this new video codec operation and by including the following new codec-specific profile information structure in the `pNext` chain: + +[source,c] +---- +typedef struct VkVideoEncodeH264ProfileInfoKHR { + VkStructureType sType; + const void* pNext; + StdVideoH264ProfileIdc stdProfileIdc; +} VkVideoEncodeH264ProfileInfoKHR; +---- + +`stdProfileIdc` specifies the H.264 profile indicator. + + +=== H.264 Encode Capabilities + +Applications need to include the following new structure in the `pNext` chain of `VkVideoCapabilitiesKHR` when calling the `vkGetPhysicalDeviceVideoCapabilitiesKHR` command to retrieve the capabilities specific to H.264 video encoding: + +[source,c] +---- +typedef struct VkVideoEncodeH264CapabilitiesKHR { + VkStructureType sType; + void* pNext; + VkVideoEncodeH264CapabilityFlagsKHR flags; + StdVideoH264LevelIdc maxLevelIdc; + uint32_t maxSliceCount; + uint32_t maxPPictureL0ReferenceCount; + uint32_t maxBPictureL0ReferenceCount; + uint32_t maxL1ReferenceCount; + uint32_t maxTemporalLayerCount; + VkBool32 expectDyadicTemporalLayerPattern; + int32_t minQp; + int32_t maxQp; + VkBool32 prefersGopRemainingFrames; + VkBool32 requiresGopRemainingFrames; + VkVideoEncodeH264StdFlagsKHR stdSyntaxFlags; +} VkVideoEncodeH264CapabilitiesKHR; +---- + +`flags` indicates support for various H.264 encoding capabilities: + + * `VK_VIDEO_ENCODE_H264_CAPABILITY_HRD_COMPLIANCE_BIT_KHR` - support for generating HRD compliant bitstreams when the related HRD parameters are present + * `VK_VIDEO_ENCODE_H264_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_KHR` - support for generating the weight tables used by the encoding process, when necessary, instead of the application having to provide them + * `VK_VIDEO_ENCODE_H264_CAPABILITY_ROW_UNALIGNED_SLICE_BIT_KHR` - support for slices that do not start/finish at macroblock row boundaries + * `VK_VIDEO_ENCODE_H264_CAPABILITY_DIFFERENT_SLICE_TYPE_BIT_KHR` - support for different slice types within a frame + * `VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_KHR` - support for including B pictures in the L0 reference list + * `VK_VIDEO_ENCODE_H264_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_KHR` - support for including B pictures in the L1 reference list + * `VK_VIDEO_ENCODE_H264_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHR` - support for using different min/max QP values for each picture type when rate control is enabled + * `VK_VIDEO_ENCODE_H264_CAPABILITY_PER_SLICE_CONSTANT_QP_BIT_KHR` - support for using different constant QP values for each slice of a frame when rate control is disabled + * `VK_VIDEO_ENCODE_H264_CAPABILITY_GENERATE_PREFIX_NALU_BIT_KHR` - support for generating prefix NAL units + +`maxLevelIdc` indicates the maximum supported H.264 level indicator. + +`maxSliceCount` indicates the implementation's upper bound on the number of H.264 slices that an encoded frame can contain, although the actual maximum may be smaller for a given frame depending on its dimensions and some of the capability flags described earlier. + +`maxPPictureL0ReferenceCount`, `maxBPictureL0ReferenceCount`, and `maxL1ReferenceCount` indicate the maximum number of reference frames that the encoded frames can refer to through the L0 and L1 reference lists depending on the type of the picture (P or B), respectively. These capabilities do not restrict the number of references the application can include in the L0 and L1 reference lists as, in practice, implementations may restrict the effective number of used references based on the encoded content and/or the capabilities of the encoder implementation. However, they do indirectly indicate whether encoding P or B pictures are supported. In particular: + + * If `maxPPictureL0ReferenceCount` is zero, then encoding P pictures is not supported by the implementation + * If both `maxBPictureL0ReferenceCount` and `maxL1ReferenceCount` are zero, then encoding B pictures is not supported by the implementation + +`maxTemporalLayerCount` indicates the number of supported H.264 temporal layers, while `expectDyadicTemporalLayerPattern` indicates whether the multi-layer rate control algorithm of the implementation (if support is indicated by `VkVideoEncodeCapabilitiesKHR::maxRateControlLayers` being greater than one for the given H.264 encode profile) expects the application to use a dyadic temporal layer pattern for accurate operation. + +`minQp` and `maxQp` indicate the supported range of QP values that can be used in the rate control configurations or as the constant QP to be used when rate control is disabled. + +`prefersGopRemainingFrames` and `requiresGopRemainingFrames` indicate whether the implementation prefers or requires, respectively, that the application track the remaining number of frames (for each type) in the current GOP (group of pictures), as some implementations may need this information for the accurate operation of their rate control algorithm. + +`stdSyntaxFlags` contains a set of flags that provide information to the application about which video std parameters or parameter values are supported to be used directly as specified by the application. These flags do not restrict what video std parameter values the application can specify, rather, they provide guarantees about respecting those. + + +=== H.264 Encode Parameter Sets + +The use of video session parameters objects is mandatory when encoding H.264 video streams. Applications need to include the following new structure in the `pNext` chain of `VkVideoSessionParametersCreateInfoKHR` when creating video session parameters objects for H.264 encode use, to specify the parameter set capacity of the created objects: + +[source,c] +---- +typedef struct VkVideoEncodeH264SessionParametersCreateInfoKHR { + VkStructureType sType; + const void* pNext; + uint32_t maxStdSPSCount; + uint32_t maxStdPPSCount; + const VkVideoEncodeH264SessionParametersAddInfoKHR* pParametersAddInfo; +} VkVideoEncodeH264SessionParametersCreateInfoKHR; +---- + +The optional `pParametersAddInfo` member also allows specifying an initial set of parameter sets to add to the created object: + +[source,c] +---- +typedef struct VkVideoEncodeH264SessionParametersAddInfoKHR { + VkStructureType sType; + const void* pNext; + uint32_t stdSPSCount; + const StdVideoH264SequenceParameterSet* pStdSPSs; + uint32_t stdPPSCount; + const StdVideoH264PictureParameterSet* pStdPPSs; +} VkVideoEncodeH264SessionParametersAddInfoKHR; +---- + +This structure can also be included in the `pNext` chain of `VkVideoSessionParametersUpdateInfoKHR` used in video session parameters update operations to add further parameter sets to an object after its creation. + +Individual parameter sets are stored using parameter set IDs as their keys, specifically: + + * H.264 SPS entries are identified using a `seq_parameter_set_id` value + * H.264 PPS entries are identified using a pair of `seq_parameter_set_id` and `pic_parameter_set_id` values + +The H.264/AVC video compression standard always requires an SPS and PPS, hence the application has to add an instance of each parameter set to the used parameters object before being able to record video encode operations. + +Furthermore, the H.264/AVC video compression standard also allows modifying existing parameter sets, but as parameters already stored in video session parameters objects cannot be changed in Vulkan, the application has to create new parameters objects in such cases, as described in the proposal for `VK_KHR_video_queue`. + +As implementations can override parameters in the SPS and PPS entries stored in video session parameters objects, as described in the proposal for `VK_KHR_video_encode_queue`, this proposal introduces additional structures specific to H.264 encode to be used with the `vkGetEncodedVideoSessionParametersKHR` command. + +First, the following new structure has to be included in the `pNext` chain of `VkVideoEncodeSessionParametersGetInfoKHR` to identify the H.264 parameter sets that the command is expected to return feedback information or encoded parameter set data for: + +[source,c] +---- +typedef struct VkVideoEncodeH264SessionParametersGetInfoKHR { + VkStructureType sType; + const void* pNext; + VkBool32 writeStdSPS; + VkBool32 writeStdPPS; + uint32_t stdSPSId; + uint32_t stdPPSId; +} VkVideoEncodeH264SessionParametersGetInfoKHR; +---- + +`writeStdSPS` and `writeStdPPS` specify whether SPS or PPS feedback/bitstream data is requested. Both can be requested, if needed. + +`stdSPSId` and `stdPPSId` are used to identify the SPS and/or PPS to request data for, the latter being relevant only for PPS queries. + +When requesting feedback using the `vkGetEncodedVideoSessionParametersKHR` command, the following new structure can be included in the `pNext` chain of `VkVideoEncodeSessionParametersFeedbackInfoKHR`: + +[source,c] +---- +typedef struct VkVideoEncodeH264SessionParametersFeedbackInfoKHR { + VkStructureType sType; + void* pNext; + VkBool32 hasStdSPSOverrides; + VkBool32 hasStdPPSOverrides; +} VkVideoEncodeH264SessionParametersFeedbackInfoKHR; +---- + +The resulting values of `hasStdSPSOverrides` and `hasStdPPSOverrides` indicate whether overrides were applied to the SPS and/or PPS, respectively, if the corresponding `writeStd` field was set in the input parameters. + +When requesting encoded bitstream data using the `vkGetEncodedVideoSessionParametersKHR` command, the output host data buffer will be filled with the encoded bitstream of the requested H.264 parameter sets. + +As described in great detail in the proposal for the `VK_KHR_video_encode_queue` extension, the application may have the option to encode the parameters otherwise stored in video session parameters object on its own. However, this may not result in a compliant bitstream if the implementation applied overrides to SPS or PPS parameters, thus it is generally recommended for applications to use the encoded parameter set data retrieved using the `vkGetEncodedVideoSessionParametersKHR` command. + + +=== H.264 Encoding Parameters + +Encode parameters specific to H.264 need to be provided by the application through the `pNext` chain of `VkVideoEncodeInfoKHR`, using the following new structure: + +[source,c] +---- +typedef struct VkVideoEncodeH264PictureInfoKHR { + VkStructureType sType; + const void* pNext; + uint32_t naluSliceEntryCount; + const VkVideoEncodeH264NaluSliceInfoKHR* pNaluSliceEntries; + const StdVideoEncodeH264PictureInfo* pStdPictureInfo; + VkBool32 generatePrefixNalu; +} VkVideoEncodeH264PictureInfoKHR; +---- + +`naluSliceEntryCount` specifies the number of slices to encode for the frame and the elements of the `pNaluSliceEntries` array provide additional information for each slice, as described later. + +`pStdPictureInfo` points to the codec-specific encode parameters defined in the `vulkan_video_codec_h264std_encode` video std header. + +The active SPS and PPS (sourced from the bound video session parameters object) are identified by the `seq_parameter_set_id` and `pic_parameter_set_id` parameters. + +The structure pointed to by `pStdPictureInfo->pRefLists` specifies the codec-specific parameters related to the reference lists. In particular, it specifies the DPB slots corresponding to the elements of the L0 and L1 reference lists, as well as the reference picture marking and reference list modification operations. + +If the `VK_VIDEO_ENCODE_H264_CAPABILITY_GENERATE_PREFIX_NALU_BIT_KHR` capability flag is supported, `generatePrefixNalu` can be set to `VK_TRUE` to request the generation of prefix NAL units before each encoded slice. + +The parameters of individual slices are provided through instances of the following new structure: + +[source,c] +---- +typedef struct VkVideoEncodeH264NaluSliceInfoKHR { + VkStructureType sType; + const void* pNext; + int32_t constantQp; + const StdVideoEncodeH264SliceHeader* pStdSliceHeader; +} VkVideoEncodeH264NaluSliceInfoKHR; +---- + +`constantQp` specifies the constant QP value to use for the slice when rate control is disabled. + +`pStdSliceHeader` points to the codec-specific encode parameters to use in the slice header. + +Picture information specific to H.264 for the active reference pictures and the optional reconstructed picture need to be provided by the application through the `pNext` chain of corresponding elements of `VkVideoEncodeInfoKHR::pReferenceSlots` and the `pNext` chain of `VkVideoEncodeInfoKHR::pSetupReferenceSlot`, respectively, using the following new structure: + +[source,c] +---- +typedef struct VkVideoEncodeH264DpbSlotInfoKHR { + VkStructureType sType; + const void* pNext; + const StdVideoEncodeH264ReferenceInfo* pStdReferenceInfo; +} VkVideoEncodeH264DpbSlotInfoKHR; +---- + +`pStdReferenceInfo` points to the codec-specific reference picture parameters defined in the `vulkan_video_codec_h264std_encode` video std header. + +It is the application's responsibility to specify codec-specific parameters that are compliant to the rules defined by the H.264/AVC video compression standard. While it is not illegal, from the API usage's point of view, to specify non-compliant inputs, they may cause the video encode operation to complete unsuccessfully and will cause the output bitstream and the reconstructed picture, if one is specified, to have undefined contents after the execution of the operation. + +Implementations may override some of these parameters in order to conform to any restrictions of the encoder implementation, but that will not affect the overall operation of the encoding. The application has the option to also opt-in for additional optimizing overrides that can result in better performance or efficiency tailored to the usage scenario by creating the video session with the new `VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHR` flag. + +For more information about individual H.264 bitstream syntax elements, derived values, and, in general, how to interpret these parameters, please refer to the corresponding sections of the https://www.itu.int/rec/T-REC-H.264-202108-I/[ITU-T H.264 Specification]. + + +=== H.264 Reference Lists + +In order to populate the L0 and L1 reference lists used to encode predictive pictures, the application has to set the corresponding elements of the `RefPicList0` and `RefPicList1` array members of the structure pointed to by `VkVideoEncodeH264PictureInfoKHR::pStdPictureInfo->pRefLists` to the DPB slot indices of the reference pictures, while all unused elements of `RefPicList0` and `RefPicList1` have to be set to `STD_VIDEO_H264_NO_REFERENCE_PICTURE`. As usual, the reference picture resources are specified by including them in the list of active reference pictures according to the codec-independent semantics defined by the `VK_KHR_video_encode_queue` extension. + +In all cases the set of DPB slot indices referenced by the L0 and L1 reference lists and the list of active reference pictures specified in `VkVideoEncodeInfoKHR::pReferenceSlots` must match, but the order in which the active reference pictures are included in the `pReferenceSlots` array does not matter. + + +=== H.264 Rate Control + +This proposal adds a set of optional rate control parameters specific to H.264 encoding that provide additional guidance to the implementation's rate control algorithm. + +When rate control is not disabled and not set to implementation-default behavior, the application can include the following new structure in the `pNext` chain of `VkVideoEncodeRateControlInfoKHR`: + +[source,c] +---- +typedef struct VkVideoEncodeH264RateControlInfoKHR { + VkStructureType sType; + const void* pNext; + VkVideoEncodeH264RateControlFlagsKHR flags; + uint32_t gopFrameCount; + uint32_t idrPeriod; + uint32_t consecutiveBFrameCount; + uint32_t temporalLayerCount; +} VkVideoEncodeH264RateControlInfoKHR; +---- + +`flags` can include one or more of the following flags: + + * `VK_VIDEO_ENCODE_H264_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR` can be used to indicate that the application would like the implementation's rate control algorithm to attempt to produce an HRD compliant bitstream when possible + * `VK_VIDEO_ENCODE_H264_RATE_CONTROL_REGULAR_GOP_BIT_KHR` can be used to indicate that the application intends to use a regular GOP structure according to the parameters specified in `gopFrameCount`, `idrPeriod`, and `consecutiveBFrameCount` + * `VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR` can be used to indicate that the application intends to follow a flat reference pattern in the GOP where each P frame uses the last non-B frame as reference, and each B frame uses the last and next non-B frame as forward and backward references, respectively + * `VK_VIDEO_ENCODE_H264_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR` can be used to indicate that the application intends to follow a dyadic reference pattern + * `VK_VIDEO_ENCODE_H264_RATE_CONTROL_TEMPORAL_LAYER_PATTERN_DYADIC_BIT_KHR` can be used to indicate that the application intends to follow a dyadic temporal layer pattern when using multiple temporal layers + +`gopFrameCount`, `idrPeriod`, and `consecutiveBFrameCount` specify the GOP size, IDR period, and the number of consecutive B frames between non-B frames, respectively, that define the typical structure of the GOP the implementation's rate control algorithm should expect. If `VK_VIDEO_ENCODE_H264_RATE_CONTROL_REGULAR_GOP_BIT_KHR` is also specified in `flags`, the implementation will expect all GOPs to follow this structure, while otherwise it may assume that the application will diverge from these values from time to time. If any of these values are zero, then the implementation's rate control algorithm will not make any assumptions about the corresponding parameter of the GOP structure. + +`temporalLayerCount` indicates the number of H.264 temporal layers that the application intends to use and it is expected to match the number of rate control layers when multi-layer rate control is used. + +The following new structure can be included in the `pNext` chain of `VkVideoEncodeRateControlLayerInfoKHR` to specify additional per-rate-control-layer guidance parameters specific to H.264 encode: + +[source,c] +---- +typedef struct VkVideoEncodeH264RateControlLayerInfoKHR { + VkStructureType sType; + const void* pNext; + VkBool32 useMinQp; + VkVideoEncodeH264QpKHR minQp; + VkBool32 useMaxQp; + VkVideoEncodeH264QpKHR maxQp; + VkBool32 useMaxFrameSize; + VkVideoEncodeH264FrameSizeKHR maxFrameSize; +} VkVideoEncodeH264RateControlLayerInfoKHR; +---- + +When `useMinQp` is set to `VK_TRUE`, `minQp` specifies the lower bound on the QP values, for each picture type, that the implementation's rate control algorithm should use. Similarly, when `useMaxQp` is set to `VK_TRUE`, `maxQp` specifies the upper bound on the QP values. + +When `useMaxFrameSize` is set to `VK_TRUE`, `maxFrameSize` specifies the maximum frame size in bytes, for each picture type, that the implementation's rate control algorithm should target. + +Some implementations may benefit from or require additional guidance on the remaining number of frames in the currently encoded GOP, as indicated by the `prefersGopRemainingFrames` and `requiresGopRemainingFrames` capabilities, respectively. This may be the case either due to the implementation not being able to track the current position of the encoded stream within the GOP, or because the implementation may be able to use this information to better react to dynamic changes to the GOP structure. This proposal solves this by introducing the following new structure that can be included in the `pNext` chain of `VkVideoBeginCodingInfoKHR`: + +[source,c] +---- +typedef struct VkVideoEncodeH264GopRemainingFrameInfoKHR { + VkStructureType sType; + const void* pNext; + VkBool32 useGopRemainingFrames; + uint32_t gopRemainingI; + uint32_t gopRemainingP; + uint32_t gopRemainingB; +} VkVideoEncodeH264GopRemainingFrameInfoKHR; +---- + +When `useGopRemainingFrames` is set to `VK_TRUE`, the implementation's rate control algorithm may use the values specified in `gopRemainingI`, `gopRemainingP`, and `gopRemainingB` as a guidance on the number of remaining frames of the corresponding type in the currently encoded GOP. + + +== Examples + +=== Select queue family with H.264 encode support + +[source,c] +---- +uint32_t queueFamilyIndex; +uint32_t queueFamilyCount; + +vkGetPhysicalDeviceQueueFamilyProperties2(physicalDevice, &queueFamilyCount, NULL); + +VkQueueFamilyProperties2* props = calloc(queueFamilyCount, + sizeof(VkQueueFamilyProperties2)); +VkQueueFamilyVideoPropertiesKHR* videoProps = calloc(queueFamilyCount, + sizeof(VkQueueFamilyVideoPropertiesKHR)); + +for (queueFamilyIndex = 0; queueFamilyIndex < queueFamilyCount; ++queueFamilyIndex) { + props[queueFamilyIndex].sType = VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2; + props[queueFamilyIndex].pNext = &videoProps[queueFamilyIndex]; + + videoProps[queueFamilyIndex].sType = VK_STRUCTURE_TYPE_QUEUE_FAMILY_VIDEO_PROPERTIES_KHR; +} + +vkGetPhysicalDeviceQueueFamilyProperties2(physicalDevice, &queueFamilyCount, props); + +for (queueFamilyIndex = 0; queueFamilyIndex < queueFamilyCount; ++queueFamilyIndex) { + if ((props[queueFamilyIndex].queueFamilyProperties.queueFlags & VK_QUEUE_VIDEO_ENCODE_BIT_KHR) != 0 && + (videoProps[queueFamilyIndex].videoCodecOperations & VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR) != 0) { + break; + } +} + +if (queueFamilyIndex < queueFamilyCount) { + // Found appropriate queue family + ... +} else { + // Did not find a queue family with the needed capabilities + ... +} +---- + + +=== Check support and query the capabilities for an H.264 encode profile + +[source,c] +---- +VkResult result; + +VkVideoEncodeH264ProfileInfoKHR encodeH264ProfileInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PROFILE_INFO_KHR, + .pNext = NULL, + .stdProfileIdc = STD_VIDEO_H264_PROFILE_IDC_BASELINE +}; + +VkVideoProfileInfoKHR profileInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PROFILE_INFO_KHR, + .pNext = &encodeH264ProfileInfo, + .videoCodecOperation = VK_VIDEO_CODEC_OPERATION_ENCODE_H264_BIT_KHR, + .chromaSubsampling = VK_VIDEO_CHROMA_SUBSAMPLING_420_BIT_KHR, + .lumaBitDepth = VK_VIDEO_COMPONENT_BIT_DEPTH_8_BIT_KHR, + .chromaBitDepth = VK_VIDEO_COMPONENT_BIT_DEPTH_8_BIT_KHR +}; + +VkVideoEncodeH264CapabilitiesKHR encodeH264Capabilities = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_CAPABILITIES_KHR, + .pNext = NULL, +}; + +VkVideoEncodeCapabilitiesKHR encodeCapabilities = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_CAPABILITIES_KHR, + .pNext = &encodeH264Capabilities +} + +VkVideoCapabilitiesKHR capabilities = { + .sType = VK_STRUCTURE_TYPE_VIDEO_CAPABILITIES_KHR, + .pNext = &encodeCapabilities +}; + +result = vkGetPhysicalDeviceVideoCapabilitiesKHR(physicalDevice, &profileInfo, &capabilities); + +if (result == VK_SUCCESS) { + // Profile is supported, check additional capabilities + ... +} else { + // Profile is not supported, result provides additional information about why + ... +} +---- + +=== Create and update H.264 video session parameters objects + +[source,c] +---- +VkVideoSessionParametersKHR videoSessionParams = VK_NULL_HANDLE; + +VkVideoEncodeH264SessionParametersCreateInfoKHR encodeH264CreateInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_CREATE_INFO_KHR, + .pNext = NULL, + .maxStdSPSCount = ... // SPS capacity + .maxStdPPSCount = ... // PPS capacity + .pParametersAddInfo = ... // parameters to add at creation time or NULL +}; + +VkVideoSessionParametersCreateInfoKHR createInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_CREATE_INFO_KHR, + .pNext = &encodeH264CreateInfo, + .flags = 0, + .videoSessionParametersTemplate = ... // template to use or VK_NULL_HANDLE + .videoSession = videoSession +}; + +vkCreateVideoSessionParametersKHR(device, &createInfo, NULL, &videoSessionParams); + +... + +StdVideoH264SequenceParameterSet sps = {}; +// parse and populate SPS parameters +... + +StdVideoH264PictureParameterSet pps = {}; +// parse and populate PPS parameters +... + +VkVideoEncodeH264SessionParametersAddInfoKHR encodeH264AddInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_SESSION_PARAMETERS_ADD_INFO_KHR, + .pNext = NULL, + .stdSPSCount = 1, + .pStdSPSs = &sps, + .stdPPSCount = 1, + .pStdPPSs = &pps +}; + +VkVideoSessionParametersUpdateInfoKHR updateInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_UPDATE_INFO_KHR, + .pNext = &encodeH264AddInfo, + .updateSequenceCount = 1 // incremented for each subsequent update +}; + +vkUpdateVideoSessionParametersKHR(device, &videoSessionParams, &updateInfo); +---- + + +=== Record H.264 encode operation producing an I frame that is also set up as a reference + +[source,c] +---- +// Bound reference resource list provided has to include reconstructed picture resource +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +StdVideoEncodeH264ReferenceInfo stdReferenceInfo = {}; +// Populate H.264 reference picture info for the reconstructed picture +stdReferenceInfo.primary_pic_type = STD_VIDEO_H264_PICTURE_TYPE_I; +... + +VkVideoEncodeH264DpbSlotInfoKHR encodeH264DpbSlotInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_DPB_SLOT_INFO_KHR, + .pNext = NULL, + .pStdReferenceInfo = &stdReferenceInfo +}; + +VkVideoReferenceSlotInfoKHR setupSlotInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = &encodeH264DpbSlotInfo + ... +}; + +StdVideoEncodeH264ReferenceListsInfo stdRefListInfo = {}; +// No references are used so just initialize the RefPicLists +for (uint32_t i = 0; i < STD_VIDEO_H264_MAX_NUM_LIST_REF; ++i) { + stdRefListInfo.RefPicList0[i] = STD_VIDEO_H264_NO_REFERENCE_PICTURE; + stdRefListInfo.RefPicList1[i] = STD_VIDEO_H264_NO_REFERENCE_PICTURE; +} +// Populate H.264 reference list modification/marking ops and other parameters +... + +StdVideoEncodeH264PictureInfo stdPictureInfo = {}; +// Populate H.264 picture info for the encode input picture +... +// Make sure that the reconstructed picture is requested to be set up as reference +stdPictureInfo.flags.is_reference = 1; +... +stdPictureInfo.primary_pic_type = STD_VIDEO_H264_PICTURE_TYPE_I; +... +stdPictureInfo.pRefLists = &stdRefListInfo; + +VkVideoEncodeH264PictureInfoKHR encodeH264PictureInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PICTURE_INFO_KHR, + .pNext = NULL, + .naluSliceEntryCount = ... // number of slices to encode + .pNaluSliceEntries = ... // pointer to the array of slice parameters + .pStdPictureInfo = &stdPictureInfo +}; + +VkVideoEncodeInfoKHR encodeInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR, + .pNext = &encodeH264PictureInfo, + ... + .pSetupReferenceSlot = &setupSlotInfo, + ... +}; + +vkCmdEncodeVideoKHR(commandBuffer, &encodeInfo); + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Record H.264 encode operation producing a P frame with a single backward reference + +[source,c] +---- +// Bound reference resource list provided has to include the used reference picture resource +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +StdVideoEncodeH264ReferenceInfo stdBackwardReferenceInfo = {}; +// Populate H.264 reference picture info for the backward referenced picture +... + +VkVideoEncodeH264DpbSlotInfoKHR encodeH264DpbSlotInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_DPB_SLOT_INFO_KHR, + .pNext = NULL, + .pStdReferenceInfo = &stdBackwardReferenceInfo +}; + +VkVideoReferenceSlotInfoKHR referenceSlotInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = &encodeH264DpbSlotInfo, + .slotIndex = ... // DPB slot index of the backward reference picture + ... +}; + +StdVideoEncodeH264ReferenceListsInfo stdRefListInfo = {}; +// Initialize the RefPicLists and add the backward reference to the L0 list +for (uint32_t i = 0; i < STD_VIDEO_H264_MAX_NUM_LIST_REF; ++i) { + stdRefListInfo.RefPicList0[i] = STD_VIDEO_H264_NO_REFERENCE_PICTURE; + stdRefListInfo.RefPicList1[i] = STD_VIDEO_H264_NO_REFERENCE_PICTURE; +} +stdRefListInfo.RefPicList0[0] = ... // DPB slot index of the backward reference picture +// Populate H.264 reference list modification/marking ops and other parameters +... + +StdVideoEncodeH264PictureInfo stdPictureInfo = {}; +// Populate H.264 picture info for the encode input picture +... +stdPictureInfo.primary_pic_type = STD_VIDEO_H264_PICTURE_TYPE_P; +... +stdPictureInfo.pRefLists = &stdRefListInfo; + +VkVideoEncodeH264PictureInfoKHR encodeH264PictureInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PICTURE_INFO_KHR, + .pNext = NULL, + .naluSliceEntryCount = ... // number of slices to encode + .pNaluSliceEntries = ... // pointer to the array of slice parameters + .pStdPictureInfo = &stdPictureInfo +}; + +VkVideoEncodeInfoKHR encodeInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR, + .pNext = &encodeH264PictureInfo, + ... + .referenceSlotCount = 1, + .pReferenceSlots = &referenceSlotInfo +}; + +vkCmdEncodeVideoKHR(commandBuffer, &encodeInfo); + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Record H.264 encode operation producing a B frame with a forward and a backward reference + +[source,c] +---- +// Bound reference resource list provided has to include the used reference picture resources +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +StdVideoEncodeH264ReferenceInfo stdBackwardReferenceInfo = {}; +// Populate H.264 reference picture info for the backward referenced picture +... + +StdVideoEncodeH264ReferenceInfo stdForwardReferenceInfo = {}; +// Populate H.264 reference picture info for the forward referenced picture +... + +VkVideoEncodeH264DpbSlotInfoKHR encodeH264DpbSlotInfo[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_DPB_SLOT_INFO_KHR, + .pNext = NULL, + .pStdReferenceInfo = &stdBackwardReferenceInfo + }, + { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_DPB_SLOT_INFO_KHR, + .pNext = NULL, + .pStdReferenceInfo = &stdForwardReferenceInfo + } +}; + +VkVideoReferenceSlotInfoKHR referenceSlotInfo[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = &encodeH264DpbSlotInfo[0], + .slotIndex = ... // DPB slot index of the backward reference picture + ... + }, + { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = &encodeH264DpbSlotInfo[1], + .slotIndex = ... // DPB slot index of the forward reference picture + ... + } +}; + +StdVideoEncodeH264ReferenceListsInfo stdRefListInfo = {}; +// Initialize the RefPicLists, add the backward reference to the L0 list, +// and add the forward reference to the L1 list +for (uint32_t i = 0; i < STD_VIDEO_H264_MAX_NUM_LIST_REF; ++i) { + stdRefListInfo.RefPicList0[i] = STD_VIDEO_H264_NO_REFERENCE_PICTURE; + stdRefListInfo.RefPicList1[i] = STD_VIDEO_H264_NO_REFERENCE_PICTURE; +} +stdRefListInfo.RefPicList0[0] = ... // DPB slot index of the backward reference picture +stdRefListInfo.RefPicList1[0] = ... // DPB slot index of the forward reference picture +// Populate H.264 reference list modification/marking ops and other parameters +... + +StdVideoEncodeH264PictureInfo stdPictureInfo = {}; +// Populate H.264 picture info for the encode input picture +... +stdPictureInfo.primary_pic_type = STD_VIDEO_H264_PICTURE_TYPE_B; +... +stdPictureInfo.pRefLists = &stdRefListInfo; + +VkVideoEncodeH264PictureInfoKHR encodeH264PictureInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_PICTURE_INFO_KHR, + .pNext = NULL, + .naluSliceEntryCount = ... // number of slices to encode + .pNaluSliceEntries = ... // pointer to the array of slice parameters + .pStdPictureInfo = &stdPictureInfo +}; + +VkVideoEncodeInfoKHR encodeInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR, + .pNext = &encodeH264PictureInfo, + ... + .referenceSlotCount = sizeof(referenceSlotInfo) / sizeof(referenceSlotInfo[0]), + .pReferenceSlots = &referenceSlotInfo[0] +}; + +vkCmdEncodeVideoKHR(commandBuffer, &encodeInfo); + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Change the rate control configuration of an H.264 encode session with optional H.264 controls + +[source,c] +---- +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +// Include the optional H.264 rate control layer information +// In this example we restrict the QP range to be used by the implementation +VkVideoEncodeH264RateControlLayerInfoKHR rateControlLayersH264[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_LAYER_INFO_KHR, + .pNext = NULL, + .useMinQp = VK_TRUE, + .minQp = { /* min I frame QP */, /* min P frame QP */, /* min B frame QP */ }, + .useMaxQp = VK_TRUE, + .minQp = { /* max I frame QP */, /* max P frame QP */, /* max B frame QP */ }, + .useMaxFrameSize = VK_FALSE, + .maxFrameSize = { 0, 0, 0 } + }, + ... +}; + +VkVideoEncodeRateControlLayerInfoKHR rateControlLayers[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_LAYER_INFO_KHR, + .pNext = &rateControlLayersH264[0], + ... + }, + ... +}; + +// Include the optional H.264 global rate control information +VkVideoEncodeH264RateControlInfoKHR rateControlInfoH264 = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H264_RATE_CONTROL_INFO_KHR, + .pNext = NULL, + .flags = VK_VIDEO_ENCODE_H264_RATE_CONTROL_REGULAR_GOP_BIT_KHR // Indicate the use of a regular GOP structure... + | VK_VIDEO_ENCODE_H264_RATE_CONTROL_TEMPORAL_LAYER_PATTERN_DYADIC_BIT_KHR, // ... and a dyadic temporal layer pattern + // Indicate a GOP structure of the form IBBBPBBBPBBBI with an IDR frame at the beginning of every 10th GOP + .gopFrameCount = 12, + .idrPeriod = 120, + .consecutiveBFrameCount = 3, + // This example uses multiple temporal layers with per layer rate control + .temporalLayerCount = sizeof(rateControlLayers) / sizeof(rateControlLayers[0]) +}; + +VkVideoEncodeRateControlInfoKHR rateControlInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_INFO_KHR, + .pNext = &rateControlInfoH264, + ... + .layerCount = sizeof(rateControlLayers) / sizeof(rateControlLayers[0]), + .pLayers = rateControlLayers, + ... +}; + +// Change the rate control configuration for the video session +VkVideoCodingControlInfoKHR controlInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_CODING_CONTROL_INFO_KHR, + .pNext = &rateControlInfo, + .flags = VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR +}; + +vkCmdControlVideoCodingKHR(commandBuffer, &controlInfo); + +... + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +== Issues + +=== RESOLVED: In what form should codec-specific parameters be provided? + +In the form of structures defined by the `vulkan_video_codec_h264std_encode` and `vulkan_video_codec_h264std` video std headers. Applications are responsible to populate the structures defined by the video std headers. It is also the application's responsibility to maintain and manage these data structures, as needed, to be able to provide them as inputs to video encode operations where needed. + + +=== RESOLVED: Why the `vulkan_video_codec_h264std` video std header does not have a version number? + +The `vulkan_video_codec_h264std` video std header was introduced to share common definitions used in both H.264/AVC video decoding and video encoding, as the two functionalities were designed in parallel. However, as no video coding extension uses this video std header directly, only as a dependency of the video std header specific to the particular video coding operation, no separate versioning scheme was deemed necessary. + + +=== RESOLVED: What are the requirements for the codec-specific input parameters? + +It is legal from an API usage perspective for the application to provide any values for the codec-specific input parameters (parameter sets, picture information, etc.). However, if the input data does not conform to the requirements of the H.264/AVC video compression standard, then video encode operations may complete unsuccessfully and, in general, the outputs produced by the video encode operation will have undefined contents. + +In addition, certain commands may return the `VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR` error if any of the specified codec-specific parameters do not adhere to the syntactic or semantic requirements of the H.264/AVC video compression standard or if values derived from parameters according to the rules defined by the H.264/AVC video compression standard do not adhere to the capabilities of the H.264/AVC video compression standard or the implementation. In particular, in this extension the following commands may return this error code: + + * `vkCreateVideoSessionParametersKHR` or `vkUpdateVideoSessionParametersKHR` - if the specified parameter sets are invalid according to these rules + * `vkEndCommandBuffer` - if the codec-specific picture information provided to video encode operations are invalid according to these rules + +Generating errors in the cases above, however, is not required so applications should not rely on receiving an error code for the purposes of verifying the correctness of the used codec-specific parameters. + + +=== RESOLVED: Are interlaced frames supported? + +No. Encoding interlaced H.264 content does not seem like an important use case to support. + + +=== RESOLVED: Do we want to allow the application to specify separate reference lists for each slice? + +Not in this extension. While the H.264/AVC video compression standard seems to support this, such flexibility is not exposed here for the sake of simplicity. If the need arises to support per slice reference lists operations, a layered extension can introduce the necessary APIs to enable it. + + +=== RESOLVED: Are prefix NAL units generated by the implementation when multiple temporal layers are used? + +Only when the `VK_VIDEO_ENCODE_H264_CAPABILITY_GENERATE_PREFIX_NALU_BIT_KHR` capability flag is supported by the implementation and the application explicitly requests the generation of prefix NAL units using the `generatePrefixNalu` parameter. + +If an application intends to use multiple temporal layers on an implementation that does not support the generation of prefix NALU units, then the application is responsible for inserting those into the final bitstream. + + +=== RESOLVED: What codec-specific parameters are guaranteed to not be overridden by implementations? + +This proposal only requires that implementations do not override the `primary_pic_type` and `slice_type` parameters, as the used picture and slice types are fundamental to the general operation of H.264 encoding. In addition, bits set in the `stdSyntaxFlags` capability provide additional guarantees about other Video Std parameters that the implementation will use without overriding them. No further restrictions are included in this extension regarding codec-specific parameter overrides, however, future extensions may include capability flags providing additional guarantees based on the needs of the users of the API. + + +=== RESOLVED: How is reference picture setup requested for H.264 encode operations? + +As specifying a reconstructed picture DPB slot and resource is always required per the latest revision of the video extensions, additional codec syntax controls whether reference picture setup is requested and, in response, the DPB slot is activated with the reconstructed picture. + +For H.264 encode, reference picture setup is requested and the DPB slot specified for the reconstructed picture is activated with the picture if and only if the `StdVideoEncodeH264PictureInfo::flags.is_reference` flag is set. + + +== Further Functionality + +Future extensions can further extend the capabilities provided here, e.g. exposing support for encode modes allowing per-slice input and/or output. diff --git a/proposals/VK_KHR_video_encode_h265.adoc b/proposals/VK_KHR_video_encode_h265.adoc new file mode 100644 index 000000000..5c68f07fa --- /dev/null +++ b/proposals/VK_KHR_video_encode_h265.adoc @@ -0,0 +1,841 @@ +// Copyright 2021-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_KHR_video_encode_h265 +:toc: left +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ +:sectnums: + +This document outlines a proposal to enable performing H.265/HEVC video encode operations in Vulkan. + +== Problem Statement + +The `VK_KHR_video_queue` extension introduces support for video coding operations and the `VK_KHR_video_encode_queue` extension further extends this with APIs specific to video encoding. + +The goal of this proposal is to build upon this infrastructure to introduce support for encoding elementary video stream sequences compliant with the H.265/HEVC video compression standard. + + +== Solution Space + +As the `VK_KHR_video_queue` and `VK_KHR_video_encode_queue` extensions already laid down the architecture for how codec-specific video encode extensions need to be designed, this extension only needs to define the APIs to provide the necessary codec-specific parameters at various points during the use of the codec-independent APIs. In particular: + + * APIs allowing to specify H.265 video, sequence, and picture parameter sets (VPS, SPS, PPS) to be stored in video session parameters objects + * APIs allowing to specify H.265 information specific to the encoded picture, including references to previously stored VPS, SPS, and PPS entries + * APIs allowing to specify H.265 reference picture information specific to the active reference pictures and optional reconstructed picture used in video encode operations + +Codec-specific encoding parameters are specified by the application through custom definitions provided by a video std header dedicated to H.265 video encoding. + +This proposal uses the common H.265 definitions first utilized by the `VK_KHR_video_decode_h265` extension and augments it with another video std header specific to H.265 encoding. Thus this extension uses the following video std headers: + + * `vulkan_video_codec_h265std` - containing common definitions for all H.265 video coding operations + * `vulkan_video_codec_h265std_encode` - containing definitions specific to H.265 video encoding operations + +These headers can be included as follows: + +[source,c] +---- +#include +#include +---- + + +== Proposal + +=== Video Std Headers + +This extension uses the new `vulkan_video_codec_h265std_encode` video std header. Implementations must always support at least version 1.0.0 of this video std header. + + +=== H.265 Encode Profiles + +This extension introduces the new video codec operation `VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR`. This flag can be used to check whether a particular queue family supports encoding H.265/HEVC content, as returned in `VkQueueFamilyVideoPropertiesKHR`. + +An H.265 encode profile can be defined through a `VkVideoProfileInfoKHR` structure using this new video codec operation and by including the following new codec-specific profile information structure in the `pNext` chain: + +[source,c] +---- +typedef struct VkVideoEncodeH265ProfileInfoKHR { + VkStructureType sType; + const void* pNext; + StdVideoH265ProfileIdc stdProfileIdc; +} VkVideoEncodeH265ProfileInfoKHR; +---- + +`stdProfileIdc` specifies the H.265 profile indicator. + + +=== H.265 Encode Capabilities + +Applications need to include the following new structure in the `pNext` chain of `VkVideoCapabilitiesKHR` when calling the `vkGetPhysicalDeviceVideoCapabilitiesKHR` command to retrieve the capabilities specific to H.265 video encoding: + +[source,c] +---- +typedef struct VkVideoEncodeH265CapabilitiesKHR { + VkStructureType sType; + void* pNext; + VkVideoEncodeH265CapabilityFlagsKHR flags; + StdVideoH265LevelIdc maxLevelIdc; + uint32_t maxSliceSegmentCount; + VkExtent2D maxTiles; + VkVideoEncodeH265CtbSizeFlagsKHR ctbSizes; + VkVideoEncodeH265TransformBlockSizeFlagsKHR transformBlockSizes; + uint32_t maxPPictureL0ReferenceCount; + uint32_t maxBPictureL0ReferenceCount; + uint32_t maxL1ReferenceCount; + uint32_t maxSubLayerCount; + VkBool32 expectDyadicTemporalSubLayerPattern; + int32_t minQp; + int32_t maxQp; + VkBool32 prefersGopRemainingFrames; + VkBool32 requiresGopRemainingFrames; + VkVideoEncodeH265StdFlagsKHR stdSyntaxFlags; +} VkVideoEncodeH265CapabilitiesKHR; +---- + +`flags` indicates support for various H.265 encoding capabilities: + + * `VK_VIDEO_ENCODE_H265_CAPABILITY_HRD_COMPLIANCE_BIT_KHR` - support for generating HRD compliant bitstreams when the related HRD parameters are present + * `VK_VIDEO_ENCODE_H265_CAPABILITY_PREDICTION_WEIGHT_TABLE_GENERATED_BIT_KHR` - support for generating the weight tables used by the encoding process, when necessary, instead of the application having to provide them + * `VK_VIDEO_ENCODE_H265_CAPABILITY_ROW_UNALIGNED_SLICE_SEGMENT_BIT_KHR` - support for slice segments that do not start/finish at CTB row boundaries + * `VK_VIDEO_ENCODE_H265_CAPABILITY_DIFFERENT_SLICE_SEGMENT_TYPE_BIT_KHR` - support for different slice segment types within a frame + * `VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L0_LIST_BIT_KHR` - support for including B pictures in the L0 reference list + * `VK_VIDEO_ENCODE_H265_CAPABILITY_B_FRAME_IN_L1_LIST_BIT_KHR` - support for including B pictures in the L1 reference list + * `VK_VIDEO_ENCODE_H265_CAPABILITY_PER_PICTURE_TYPE_MIN_MAX_QP_BIT_KHR` - support for using different min/max QP values for each picture type when rate control is enabled + * `VK_VIDEO_ENCODE_H265_CAPABILITY_PER_SLICE_SEGMENT_CONSTANT_QP_BIT_KHR` - support for using different constant QP values for each slice segment of a frame when rate control is disabled + * `VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_TILES_PER_SLICE_SEGMENT_BIT_KHR` - support for encoding multiple tiles per slice segment + * `VK_VIDEO_ENCODE_H265_CAPABILITY_MULTIPLE_SLICE_SEGMENTS_PER_TILE_BIT_KHR` - support for encoding multiple slice segments per tile + +`maxLevelIdc` indicates the maximum supported H.265 level indicator. + +`maxSliceSegmentCount` indicates the implementation's upper bound on the number of H.265 slice segments that an encoded frame can contain, although the actual maximum may be smaller for a given frame depending on its dimensions and some of the capability flags described earlier. + +The fields of `maxTiles` indicate the maximum number of H.265 tile columns and rows, respectively. + +`ctbSizes` and `transformBlockSizes` are bitmasks that indicate the set of CTB and transform block sizes supported by the implementation, respectively. + +`maxPPictureL0ReferenceCount`, `maxBPictureL0ReferenceCount`, and `maxL1ReferenceCount` indicate the maximum number of reference frames that the encoded frames can refer to through the L0 and L1 reference lists depending on the type of the picture (P or B), respectively. These capabilities do not restrict the number of references the application can include in the L0 and L1 reference lists as, in practice, implementations may restrict the effective number of used references based on the encoded content and/or the capabilities of the encoder implementation. However, they do indirectly indicate whether encoding P or B pictures are supported. In particular: + + * If `maxPPictureL0ReferenceCount` is zero, then encoding P pictures is not supported by the implementation + * If both `maxBPictureL0ReferenceCount` and `maxL1ReferenceCount` are zero, then encoding B pictures is not supported by the implementation + +The H.265/HEVC video compression standard supports so called generalized B pictures (also known as low delay B pictures) that use both L0 and L1 references referring to only past frames. This can make the use of P pictures moot. Hence, certain implementations may only advertise support for encoding B pictures (but not P pictures). This, however, should not limit applications in encoding backward-reference-only frames. + +`maxSubLayerCount` indicates the number of supported H.265 sub-layers, while `expectDyadicTemporalSubLayerPattern` indicates whether the multi-layer rate control algorithm of the implementation (if support is indicated by `VkVideoEncodeCapabilitiesKHR::maxRateControlLayers` being greater than one for the given H.265 encode profile) expects the application to use a dyadic temporal sub-layer pattern for accurate operation. + +`minQp` and `maxQp` indicate the supported range of QP values that can be used in the rate control configurations or as the constant QP to be used when rate control is disabled. + +`prefersGopRemainingFrames` and `requiresGopRemainingFrames` indicate whether the implementation prefers or requires, respectively, that the application tracks the remaining number of frames (for each type) in the current GOP (group of pictures), as some implementations may need this information for the accurate operation of their rate control algorithm. + +`stdSyntaxFlags` contains a set of flags that provide information to the application about which video std parameters or parameter values are supported to be used directly as specified by the application. These flags do not restrict what video std parameter values the application can specify, rather, they provide guarantees about respecting those. + + +=== H.265 Encode Parameter Sets + +The use of video session parameters objects is mandatory when encoding H.265 video streams. Applications need to include the following new structure in the `pNext` chain of `VkVideoSessionParametersCreateInfoKHR` when creating video session parameters objects for H.265 encode use, to specify the parameter set capacity of the created objects: + +[source,c] +---- +typedef struct VkVideoEncodeH265SessionParametersCreateInfoKHR { + VkStructureType sType; + const void* pNext; + uint32_t maxStdVPSCount; + uint32_t maxStdSPSCount; + uint32_t maxStdPPSCount; + const VkVideoEncodeH265SessionParametersAddInfoKHR* pParametersAddInfo; +} VkVideoEncodeH265SessionParametersCreateInfoKHR; +---- + +The optional `pParametersAddInfo` member also allows specifying an initial set of parameter sets to add to the created object: + +[source,c] +---- +typedef struct VkVideoEncodeH265SessionParametersAddInfoKHR { + VkStructureType sType; + const void* pNext; + uint32_t stdVPSCount; + const StdVideoH265VideoParameterSet* pStdVPSs; + uint32_t stdSPSCount; + const StdVideoH265SequenceParameterSet* pStdSPSs; + uint32_t stdPPSCount; + const StdVideoH265PictureParameterSet* pStdPPSs; +} VkVideoEncodeH265SessionParametersAddInfoKHR; +---- + +This structure can also be included in the `pNext` chain of `VkVideoSessionParametersUpdateInfoKHR` used in video session parameters update operations to add further parameter sets to an object after its creation. + +Individual parameter sets are stored using parameter set IDs as their keys, specifically: + + * H.265 VPS entries are identified using a `vps_video_parameter_set_id` value + * H.265 SPS entries are identified using a pair of `sps_video_parameter_set_id` and `sps_seq_parameter_set_id` values + * H.265 PPS entries are identified using a triplet of `sps_video_parameter_set_id`, `pps_seq_parameter_set_id`, and `pps_pic_parameter_set_id` values + +Please note the inclusion of the VPS ID in the PPS key. This is needed because a PPS is not uniquely identified by its ID and the ID of the parent SPS, as multiple SPS entries may exist with the same ID that have different parent VPS IDs. In order to ensure the uniqueness of keys, all APIs referring to a PPS in this proposal also take the parent VPS ID of the SPS the PPS in question belongs to, to specify the full hierarchy of IDs. + +The H.265/HEVC video compression standard always requires a VPS, SPS, and PPS, hence the application has to add an instance of each parameter set to the used parameters object before being able to record video encode operations. + +Furthermore, the H.265/HEVC video compression standard also allows modifying existing parameter sets, but as parameters already stored in video session parameters objects cannot be changed in Vulkan, the application has to create new parameters objects in such cases, as described in the proposal for `VK_KHR_video_queue`. + +As implementations can override parameters in the VPS, SPS, and PPS entries stored in video session parameters objects, as described in the proposal for `VK_KHR_video_encode_queue`, this proposal introduces additional structures specific to H.265 encode to be used with the `vkGetEncodedVideoSessionParametersKHR` command. + +First, the following new structure has to be included in the `pNext` chain of `VkVideoEncodeSessionParametersGetInfoKHR` to identify the H.265 parameter sets that the command is expected to return feedback information or encoded parameter set data for: + +[source,c] +---- +typedef struct VkVideoEncodeH265SessionParametersGetInfoKHR { + VkStructureType sType; + const void* pNext; + VkBool32 writeStdVPS; + VkBool32 writeStdSPS; + VkBool32 writeStdPPS; + uint32_t stdVPSId; + uint32_t stdSPSId; + uint32_t stdPPSId; +} VkVideoEncodeH265SessionParametersGetInfoKHR; +---- + +`writeStdVPS`, `writeStdSPS`, and `writeStdPPS` specify whether VPS, SPS, or PPS feedback/bitstream data is requested. Any combination can be requested, if needed. + +`stdVPSId`, `stdSPSId`, and `stdPPSId` are used to identify the VPS, SPS, and/or PPS to request data for. Naturally, `stdPPSId` is only relevant for PPS queries, and `stdSPSId` is only relevant for SPS and/or PPS queries. + +When requesting feedback using the `vkGetEncodedVideoSessionParametersKHR` command, the following new structure can be included in the `pNext` chain of `VkVideoEncodeSessionParametersFeedbackInfoKHR`: + +[source,c] +---- +typedef struct VkVideoEncodeH265SessionParametersFeedbackInfoKHR { + VkStructureType sType; + void* pNext; + VkBool32 hasStdVPSOverrides; + VkBool32 hasStdSPSOverrides; + VkBool32 hasStdPPSOverrides; +} VkVideoEncodeH265SessionParametersFeedbackInfoKHR; +---- + +The resulting values of `hasStdVPSOverrides`, `hasStdSPSOverrides`, and `hasStdPPSOverrides` indicate whether overrides were applied to the VPS, SPS, and/or PPS, respectively, if the corresponding `writeStd` field was set in the input parameters. + +When requesting encoded bitstream data using the `vkGetEncodedVideoSessionParametersKHR` command, the output host data buffer will be filled with the encoded bitstream of the requested H.265 parameter sets. + +As described in great detail in the proposal for the `VK_KHR_video_encode_queue` extension, the application may have the option to encode the parameters otherwise stored in video session parameters object on its own. However, this may not result in a compliant bitstream if the implementation applied overrides to VPS, SPS, or PPS parameters, thus it is generally recommended for applications to use the encoded parameter set data retrieved using the `vkGetEncodedVideoSessionParametersKHR` command. + + +=== H.265 Encoding Parameters + +Encode parameters specific to H.265 need to be provided by the application through the `pNext` chain of `VkVideoEncodeInfoKHR`, using the following new structure: + +[source,c] +---- +typedef struct VkVideoEncodeH265PictureInfoKHR { + VkStructureType sType; + const void* pNext; + uint32_t naluSliceSegmentEntryCount; + const VkVideoEncodeH265NaluSliceSegmentInfoKHR* pNaluSliceSegmentEntries; + const StdVideoEncodeH265PictureInfo* pStdPictureInfo; +} VkVideoEncodeH265PictureInfoKHR; +---- + +`naluSliceSegmentEntryCount` specifies the number of slice segments to encode for the frame and the elements of the `pNaluSliceSegmentEntries` array provide additional information for each slice segment, as described later. + +`pStdPictureInfo` points to the codec-specific encode parameters defined in the `vulkan_video_codec_h265std_encode` video std header. + +The active VPS, SPS, and PPS (sourced from the bound video session parameters object) are identified by the `sps_video_parameter_set_id`, `pps_seq_parameter_set_id`, and `pps_pic_parameter_set_id` parameters. + +The structure pointed to by `pStdPictureInfo->pRefLists` specifies the codec-specific parameters related to the reference lists. In particular, it specifies the DPB slots corresponding to the elements of the L0 and L1 reference lists, as well as reference list modification information. + +The parameters of individual slice segments are provided through instances of the following new structure: + +[source,c] +---- +typedef struct VkVideoEncodeH265NaluSliceSegmentInfoKHR { + VkStructureType sType; + const void* pNext; + int32_t constantQp; + const StdVideoEncodeH265SliceSegmentHeader* pStdSliceSegmentHeader; +} VkVideoEncodeH265NaluSliceSegmentInfoKHR; +---- + +`constantQp` specifies the constant QP value to use for the slice when rate control is disabled. + +`pStdSliceSegmentHeader` points to the codec-specific encode parameters to use in the slice segment header. + +Picture information specific to H.265 for the active reference pictures and the optional reconstructed picture need to be provided by the application through the `pNext` chain of corresponding elements of `VkVideoEncodeInfoKHR::pReferenceSlots` and the `pNext` chain of `VkVideoEncodeInfoKHR::pSetupReferenceSlot`, respectively, using the following new structure: + +[source,c] +---- +typedef struct VkVideoEncodeH265DpbSlotInfoKHR { + VkStructureType sType; + const void* pNext; + const StdVideoEncodeH265ReferenceInfo* pStdReferenceInfo; +} VkVideoEncodeH265DpbSlotInfoKHR; +---- + +`pStdReferenceInfo` points to the codec-specific reference picture parameters defined in the `vulkan_video_codec_h265std_encode` video std header. + +It is the application's responsibility to specify codec-specific parameters that are compliant to the rules defined by the H.265/HEVC video compression standard. While it is not illegal, from the API usage's point of view, to specify non-compliant inputs, they may cause the video encode operation to complete unsuccessfully and will cause the output bitstream and the reconstructed picture, if one is specified, to have undefined contents after the execution of the operation. + +Implementations may override some of these parameters in order to conform to any restrictions of the encoder implementation, but that will not affect the overall operation of the encoding. The application has the option to also opt-in for additional optimizing overrides that can result in better performance or efficiency tailored to the usage scenario by creating the video session with the new `VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHR` flag. + +For more information about individual H.265 bitstream syntax elements, calculate derived values, and, in general, how to interpret these parameters, please refer to the corresponding sections of the https://www.itu.int/rec/T-REC-H.265-202108-S/[ITU-T H.265 Specification]. + + +=== H.265 Reference Lists + +In order to populate the L0 and L1 reference lists used to encode predictive pictures, the application has to set the corresponding elements of the `RefPicList0` and `RefPicList1` array members of the structure pointed to by `VkVideoEncodeH265PictureInfoKHR::pStdPictureInfo->pRefLists` to the DPB slot indices of the reference pictures, while all unused elements of `RefPicList0` and `RefPicList1` have to be set to `STD_VIDEO_H265_NO_REFERENCE_PICTURE`. As usual, the reference picture resources are specified by including them in the list of active reference pictures according to the codec-independent semantics defined by the `VK_KHR_video_encode_queue` extension. + +In all cases the set of DPB slot indices referenced by the L0 and L1 reference lists and the list of active reference pictures specified in `VkVideoEncodeInfoKHR::pReferenceSlots` must match, but the order in which the active reference pictures are included in the `pReferenceSlots` array does not matter. + + +=== H.265 Rate Control + +This proposal adds a set of optional rate control parameters specific to H.265 encoding that provide additional guidance to the implementation's rate control algorithm. + +When rate control is not disabled and not set to implementation-default behavior, the application can include the following new structure in the `pNext` chain of `VkVideoEncodeRateControlInfoKHR`: + +[source,c] +---- +typedef struct VkVideoEncodeH265RateControlInfoKHR { + VkStructureType sType; + const void* pNext; + VkVideoEncodeH265RateControlFlagsKHR flags; + uint32_t gopFrameCount; + uint32_t idrPeriod; + uint32_t consecutiveBFrameCount; + uint32_t subLayerCount; +} VkVideoEncodeH265RateControlInfoKHR; +---- + +`flags` can include one or more of the following flags: + + * `VK_VIDEO_ENCODE_H265_RATE_CONTROL_ATTEMPT_HRD_COMPLIANCE_BIT_KHR` can be used to indicate that the application would like the implementation's rate control algorithm to attempt to produce an HRD compliant bitstream when possible + * `VK_VIDEO_ENCODE_H265_RATE_CONTROL_REGULAR_GOP_BIT_KHR` can be used to indicate that the application intends to use a regular GOP structure according to the parameters specified in `gopFrameCount`, `idrPeriod`, and `consecutiveBFrameCount` + * `VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_FLAT_BIT_KHR` can be used to indicate that the application intends to follow a flat reference pattern in the GOP where each P frame uses the last non-B frame as reference, and each B frame uses the last and next non-B frame as forward and backward references, respectively + * `VK_VIDEO_ENCODE_H265_RATE_CONTROL_REFERENCE_PATTERN_DYADIC_BIT_KHR` can be used to indicate that the application intends to follow a dyadic reference pattern + * `VK_VIDEO_ENCODE_H265_RATE_CONTROL_TEMPORAL_SUB_LAYER_PATTERN_DYADIC_BIT_KHR` can be used to indicate that the application intends to follow a dyadic temporal sub-layer pattern when using multiple temporal sub-layers + +`gopFrameCount`, `idrPeriod`, and `consecutiveBFrameCount` specify the GOP size, IDR period, and the number of consecutive B frames between non-B frames, respectively, that define the typical structure of the GOP the implementation's rate control algorithm should expect. If `VK_VIDEO_ENCODE_H265_RATE_CONTROL_REGULAR_GOP_BIT_KHR` is also specified in `flags`, the implementation will expect all GOPs to follow this structure, while otherwise it may assume that the application will diverge from these values from time to time. If any of these values are zero, then the implementation's rate control algorithm will not make any assumptions about the corresponding parameter of the GOP structure. + +`subLayerCount` indicates the number of H.265 temporal sub-layers that the application intends to use and it is expected to match the number of rate control layers when multi-layer rate control is used. + +The following new structure can be included in the `pNext` chain of `VkVideoEncodeRateControlLayerInfoKHR` to specify additional per-rate-control-layer guidance parameters specific to H.265 encode: + +[source,c] +---- +typedef struct VkVideoEncodeH265RateControlLayerInfoKHR { + VkStructureType sType; + const void* pNext; + VkBool32 useMinQp; + VkVideoEncodeH265QpKHR minQp; + VkBool32 useMaxQp; + VkVideoEncodeH265QpKHR maxQp; + VkBool32 useMaxFrameSize; + VkVideoEncodeH265FrameSizeKHR maxFrameSize; +} VkVideoEncodeH265RateControlLayerInfoKHR; +---- + +When `useMinQp` is set to `VK_TRUE`, `minQp` specifies the lower bound on the QP values, for each picture type, that the implementation's rate control algorithm should use. Similarly, when `useMaxQp` is set to `VK_TRUE`, `maxQp` specifies the upper bound on the QP values. + +When `useMaxFrameSize` is set to `VK_TRUE`, `maxFrameSize` specifies the maximum frame size in bytes, for each picture type, that the implementation's rate control algorithm should target. + +Some implementations may benefit from or require additional guidance on the remaining number of frames in the currently encoded GOP, as indicated by the `prefersGopRemainingFrames` and `requiresGopRemainingFrames` capabilities, respectively. This may be the case either due to the implementation not being able to track the current position of the encoded stream within the GOP, or because the implementation may be able to use this information to better react to dynamic changes to the GOP structure. This proposal solves this by introducing the following new structure that can be included in the `pNext` chain of `VkVideoBeginCodingInfoKHR`: + +[source,c] +---- +typedef struct VkVideoEncodeH265GopRemainingFrameInfoKHR { + VkStructureType sType; + const void* pNext; + VkBool32 useGopRemainingFrames; + uint32_t gopRemainingI; + uint32_t gopRemainingP; + uint32_t gopRemainingB; +} VkVideoEncodeH265GopRemainingFrameInfoKHR; +---- + +When `useGopRemainingFrames` is set to `VK_TRUE`, the implementation's rate control algorithm may use the values specified in `gopRemainingI`, `gopRemainingP`, and `gopRemainingB` as a guidance on the number of remaining frames of the corresponding type in the currently encoded GOP. + + +== Examples + +=== Select queue family with H.265 encode support + +[source,c] +---- +uint32_t queueFamilyIndex; +uint32_t queueFamilyCount; + +vkGetPhysicalDeviceQueueFamilyProperties2(physicalDevice, &queueFamilyCount, NULL); + +VkQueueFamilyProperties2* props = calloc(queueFamilyCount, + sizeof(VkQueueFamilyProperties2)); +VkQueueFamilyVideoPropertiesKHR* videoProps = calloc(queueFamilyCount, + sizeof(VkQueueFamilyVideoPropertiesKHR)); + +for (queueFamilyIndex = 0; queueFamilyIndex < queueFamilyCount; ++queueFamilyIndex) { + props[queueFamilyIndex].sType = VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2; + props[queueFamilyIndex].pNext = &videoProps[queueFamilyIndex]; + + videoProps[queueFamilyIndex].sType = VK_STRUCTURE_TYPE_QUEUE_FAMILY_VIDEO_PROPERTIES_KHR; +} + +vkGetPhysicalDeviceQueueFamilyProperties2(physicalDevice, &queueFamilyCount, props); + +for (queueFamilyIndex = 0; queueFamilyIndex < queueFamilyCount; ++queueFamilyIndex) { + if ((props[queueFamilyIndex].queueFamilyProperties.queueFlags & VK_QUEUE_VIDEO_ENCODE_BIT_KHR) != 0 && + (videoProps[queueFamilyIndex].videoCodecOperations & VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR) != 0) { + break; + } +} + +if (queueFamilyIndex < queueFamilyCount) { + // Found appropriate queue family + ... +} else { + // Did not find a queue family with the needed capabilities + ... +} +---- + + +=== Check support and query the capabilities for an H.265 encode profile + +[source,c] +---- +VkResult result; + +VkVideoEncodeH265ProfileInfoKHR encodeH265ProfileInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PROFILE_INFO_KHR, + .pNext = NULL, + .stdProfileIdc = STD_VIDEO_H265_PROFILE_IDC_MAIN +}; + +VkVideoProfileInfoKHR profileInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PROFILE_INFO_KHR, + .pNext = &encodeH265ProfileInfo, + .videoCodecOperation = VK_VIDEO_CODEC_OPERATION_ENCODE_H265_BIT_KHR, + .chromaSubsampling = VK_VIDEO_CHROMA_SUBSAMPLING_420_BIT_KHR, + .lumaBitDepth = VK_VIDEO_COMPONENT_BIT_DEPTH_8_BIT_KHR, + .chromaBitDepth = VK_VIDEO_COMPONENT_BIT_DEPTH_8_BIT_KHR +}; + +VkVideoEncodeH265CapabilitiesKHR encodeH265Capabilities = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_CAPABILITIES_KHR, + .pNext = NULL, +}; + +VkVideoEncodeCapabilitiesKHR encodeCapabilities = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_CAPABILITIES_KHR, + .pNext = &encodeH265Capabilities +} + +VkVideoCapabilitiesKHR capabilities = { + .sType = VK_STRUCTURE_TYPE_VIDEO_CAPABILITIES_KHR, + .pNext = &encodeCapabilities +}; + +result = vkGetPhysicalDeviceVideoCapabilitiesKHR(physicalDevice, &profileInfo, &capabilities); + +if (result == VK_SUCCESS) { + // Profile is supported, check additional capabilities + ... +} else { + // Profile is not supported, result provides additional information about why + ... +} +---- + +=== Create and update H.265 video session parameters objects + +[source,c] +---- +VkVideoSessionParametersKHR videoSessionParams = VK_NULL_HANDLE; + +VkVideoEncodeH265SessionParametersCreateInfoKHR encodeH265CreateInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_CREATE_INFO_KHR, + .pNext = NULL, + .maxStdVPSCount = ... // VPS capacity + .maxStdSPSCount = ... // SPS capacity + .maxStdPPSCount = ... // PPS capacity + .pParametersAddInfo = ... // parameters to add at creation time or NULL +}; + +VkVideoSessionParametersCreateInfoKHR createInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_CREATE_INFO_KHR, + .pNext = &encodeH265CreateInfo, + .flags = 0, + .videoSessionParametersTemplate = ... // template to use or VK_NULL_HANDLE + .videoSession = videoSession +}; + +vkCreateVideoSessionParametersKHR(device, &createInfo, NULL, &videoSessionParams); + +... + +StdVideoH265VideoParameterSet vps = {}; +// parse and populate VPS parameters +... + +StdVideoH265SequenceParameterSet sps = {}; +// parse and populate SPS parameters +... + +StdVideoH265PictureParameterSet pps = {}; +// parse and populate PPS parameters +... + +VkVideoEncodeH265SessionParametersAddInfoKHR encodeH265AddInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_SESSION_PARAMETERS_ADD_INFO_KHR, + .pNext = NULL, + .stdVPSCount = 1, + .pStdVPSs = &vps, + .stdSPSCount = 1, + .pStdSPSs = &sps, + .stdPPSCount = 1, + .pStdPPSs = &pps +}; + +VkVideoSessionParametersUpdateInfoKHR updateInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_UPDATE_INFO_KHR, + .pNext = &encodeH265AddInfo, + .updateSequenceCount = 1 // incremented for each subsequent update +}; + +vkUpdateVideoSessionParametersKHR(device, &videoSessionParams, &updateInfo); +---- + + +=== Record H.265 encode operation producing an I frame that is also set up as a reference + +[source,c] +---- +// Bound reference resource list provided has to include reconstructed picture resource +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +StdVideoEncodeH265ReferenceInfo stdReferenceInfo = {}; +// Populate H.265 reference picture info for the reconstructed picture +stdReferenceInfo.pic_type = STD_VIDEO_H265_PICTURE_TYPE_I; +... + +VkVideoEncodeH265DpbSlotInfoKHR encodeH265DpbSlotInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_DPB_SLOT_INFO_KHR, + .pNext = NULL, + .pStdReferenceInfo = &stdReferenceInfo +}; + +VkVideoReferenceSlotInfoKHR setupSlotInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = &encodeH265DpbSlotInfo + ... +}; + +StdVideoEncodeH265ReferenceListsInfo stdRefListInfo = {}; +// No references are used so just initialize the RefPicLists +for (uint32_t i = 0; i < STD_VIDEO_H265_MAX_NUM_LIST_REF; ++i) { + stdRefListInfo.RefPicList0[i] = STD_VIDEO_H265_NO_REFERENCE_PICTURE; + stdRefListInfo.RefPicList1[i] = STD_VIDEO_H265_NO_REFERENCE_PICTURE; +} +// Populate other H.265 reference list parameters +... + +StdVideoEncodeH265PictureInfo stdPictureInfo = {}; +// Populate H.265 picture info for the encode input picture +... +// Make sure that the reconstructed picture is requested to be set up as reference +stdPictureInfo.flags.is_reference = 1; +... +stdPictureInfo.pic_type = STD_VIDEO_H265_PICTURE_TYPE_I; +... +stdPictureInfo.pRefLists = &stdRefListInfo; +... + +VkVideoEncodeH265PictureInfoKHR encodeH265PictureInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PICTURE_INFO_KHR, + .pNext = NULL, + .naluSliceSegmentEntryCount = ... // number of slice segments to encode + .pNaluSliceSegmentEntries = ... // pointer to the array of slice segment parameters + .pStdPictureInfo = &stdPictureInfo +}; + +VkVideoEncodeInfoKHR encodeInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR, + .pNext = &encodeH265PictureInfo, + ... + .pSetupReferenceSlot = &setupSlotInfo, + ... +}; + +vkCmdEncodeVideoKHR(commandBuffer, &encodeInfo); + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Record H.265 encode operation producing a P frame with a single backward reference + +[source,c] +---- +// Bound reference resource list provided has to include the used reference picture resource +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +StdVideoEncodeH265ReferenceInfo stdBackwardReferenceInfo = {}; +// Populate H.265 reference picture info for the backward referenced picture +... + +VkVideoEncodeH265DpbSlotInfoKHR encodeH265DpbSlotInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_DPB_SLOT_INFO_KHR, + .pNext = NULL, + .pStdReferenceInfo = &stdBackwardReferenceInfo +}; + +VkVideoReferenceSlotInfoKHR referenceSlotInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = &encodeH265DpbSlotInfo, + .slotIndex = ... // DPB slot index of the backward reference picture + ... +}; + +StdVideoEncodeH265ReferenceListsInfo stdRefListInfo = {}; +// Initialize the RefPicLists and add the backward reference to the L0 list +for (uint32_t i = 0; i < STD_VIDEO_H265_MAX_NUM_LIST_REF; ++i) { + stdRefListInfo.RefPicList0[i] = STD_VIDEO_H265_NO_REFERENCE_PICTURE; + stdRefListInfo.RefPicList1[i] = STD_VIDEO_H265_NO_REFERENCE_PICTURE; +} +stdRefListInfo.RefPicList0[0] = ... // DPB slot index of the backward reference picture +// Populate other H.265 reference list parameters +... + +StdVideoEncodeH265PictureInfo stdPictureInfo = {}; +// Populate H.265 picture info for the encode input picture +... +stdPictureInfo.pic_type = STD_VIDEO_H265_PICTURE_TYPE_P; +... +stdPictureInfo.pRefLists = &stdRefListInfo; +... + +VkVideoEncodeH265PictureInfoKHR encodeH265PictureInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PICTURE_INFO_KHR, + .pNext = NULL, + .naluSliceSegmentEntryCount = ... // number of slice segments to encode + .pNaluSliceSegmentEntries = ... // pointer to the array of slice segment parameters + .pStdPictureInfo = &stdPictureInfo +}; + +VkVideoEncodeInfoKHR encodeInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR, + .pNext = &encodeH265PictureInfo, + ... + .referenceSlotCount = 1, + .pReferenceSlots = &referenceSlotInfo +}; + +vkCmdEncodeVideoKHR(commandBuffer, &encodeInfo); + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Record H.265 encode operation producing a B frame with a forward and a backward reference + +[source,c] +---- +// Bound reference resource list provided has to include the used reference picture resources +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +StdVideoEncodeH265ReferenceInfo stdBackwardReferenceInfo = {}; +// Populate H.265 reference picture info for the backward referenced picture +... + +StdVideoEncodeH265ReferenceInfo stdForwardReferenceInfo = {}; +// Populate H.265 reference picture info for the forward referenced picture +... + +VkVideoEncodeH265DpbSlotInfoKHR encodeH265DpbSlotInfo[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_DPB_SLOT_INFO_KHR, + .pNext = NULL, + .pStdReferenceInfo = &stdBackwardReferenceInfo + }, + { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_DPB_SLOT_INFO_KHR, + .pNext = NULL, + .pStdReferenceInfo = &stdForwardReferenceInfo + } +}; + +VkVideoReferenceSlotInfoKHR referenceSlotInfo[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = &encodeH265DpbSlotInfo[0], + .slotIndex = ... // DPB slot index of the backward reference picture + ... + }, + { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = &encodeH265DpbSlotInfo[1], + .slotIndex = ... // DPB slot index of the forward reference picture + ... + } +}; + +StdVideoEncodeH265ReferenceListsInfo stdRefListInfo = {}; +// Initialize the RefPicLists, add the backward reference to the L0 list, +// and add the forward reference to the L1 list +for (uint32_t i = 0; i < STD_VIDEO_H265_MAX_NUM_LIST_REF; ++i) { + stdRefListInfo.RefPicList0[i] = STD_VIDEO_H265_NO_REFERENCE_PICTURE; + stdRefListInfo.RefPicList1[i] = STD_VIDEO_H265_NO_REFERENCE_PICTURE; +} +stdRefListInfo.RefPicList0[0] = ... // DPB slot index of the backward reference picture +stdRefListInfo.RefPicList1[0] = ... // DPB slot index of the forward reference picture +// Populate other H.265 reference list parameters +... + +StdVideoEncodeH265PictureInfo stdPictureInfo = {}; +// Populate H.265 picture info for the encode input picture +... +stdPictureInfo.pic_type = STD_VIDEO_H265_PICTURE_TYPE_B; +... +stdPictureInfo.pRefLists = &stdRefListInfo; +... + +VkVideoEncodeH265PictureInfoKHR encodeH265PictureInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_PICTURE_INFO_KHR, + .pNext = NULL, + .naluSliceSegmentEntryCount = ... // number of slice segments to encode + .pNaluSliceSegmentEntries = ... // pointer to the array of slice segment parameters + .pStdPictureInfo = &stdPictureInfo +}; + +VkVideoEncodeInfoKHR encodeInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR, + .pNext = &encodeH265PictureInfo, + ... + .referenceSlotCount = sizeof(referenceSlotInfo) / sizeof(referenceSlotInfo[0]), + .pReferenceSlots = &referenceSlotInfo[0] +}; + +vkCmdEncodeVideoKHR(commandBuffer, &encodeInfo); + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Change the rate control configuration of an H.265 encode session with optional H.265 controls + +[source,c] +---- +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +// Include the optional H.265 rate control layer information +// In this example we restrict the QP range to be used by the implementation +VkVideoEncodeH265RateControlLayerInfoKHR rateControlLayersH265[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_LAYER_INFO_KHR, + .pNext = NULL, + .useMinQp = VK_TRUE, + .minQp = { /* min I frame QP */, /* min P frame QP */, /* min B frame QP */ }, + .useMaxQp = VK_TRUE, + .minQp = { /* max I frame QP */, /* max P frame QP */, /* max B frame QP */ }, + .useMaxFrameSize = VK_FALSE, + .maxFrameSize = { 0, 0, 0 } + }, + ... +}; + +VkVideoEncodeRateControlLayerInfoKHR rateControlLayers[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_LAYER_INFO_KHR, + .pNext = &rateControlLayersH265[0], + ... + }, + ... +}; + +// Include the optional H.265 global rate control information +VkVideoEncodeH265RateControlInfoKHR rateControlInfoH265 = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_H265_RATE_CONTROL_INFO_KHR, + .pNext = NULL, + .flags = VK_VIDEO_ENCODE_H265_RATE_CONTROL_REGULAR_GOP_BIT_KHR // Indicate the use of a regular GOP structure... + | VK_VIDEO_ENCODE_H265_RATE_CONTROL_TEMPORAL_SUB_LAYER_PATTERN_DYADIC_BIT_KHR, // ... and a dyadic temporal sub-layer pattern + // Indicate a GOP structure of the form IBBBPBBBPBBBI with an IDR frame at the beginning of every 10th GOP + .gopFrameCount = 12, + .idrPeriod = 120, + .consecutiveBFrameCount = 3, + // This example uses multiple temporal sub-layers with per layer rate control + .subLayerCount = sizeof(rateControlLayers) / sizeof(rateControlLayers[0]) +}; + +VkVideoEncodeRateControlInfoKHR rateControlInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_INFO_KHR, + .pNext = &rateControlInfoH265, + ... + .layerCount = sizeof(rateControlLayers) / sizeof(rateControlLayers[0]), + .pLayers = rateControlLayers, + ... +}; + +// Change the rate control configuration for the video session +VkVideoCodingControlInfoKHR controlInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_CODING_CONTROL_INFO_KHR, + .pNext = &rateControlInfo, + .flags = VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR +}; + +vkCmdControlVideoCodingKHR(commandBuffer, &controlInfo); + +... + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +== Issues + +=== RESOLVED: In what form should codec-specific parameters be provided? + +In the form of structures defined by the `vulkan_video_codec_h265std_encode` and `vulkan_video_codec_h265std` video std headers. Applications are responsible to populate the structures defined by the video std headers. It is also the application's responsibility to maintain and manage these data structures, as needed, to be able to provide them as inputs to video encode operations where needed. + + +=== RESOLVED: Why the `vulkan_video_codec_h265std` video std header does not have a version number? + +The `vulkan_video_codec_h265std` video std header was introduced to share common definitions used in both H.265/HEVC video decoding and video encoding, as the two functionalities were designed in parallel. However, as no video coding extension uses this video std header directly, only as a dependency of the video std header specific to the particular video coding operation, no separate versioning scheme was deemed necessary. + + +=== RESOLVED: What are the requirements for the codec-specific input parameters? + +It is legal from an API usage perspective for the application to provide any values for the codec-specific input parameters (parameter sets, picture information, etc.). However, if the input data does not conform to the requirements of the H.265/HEVC video compression standard, then video encode operations may complete unsuccessfully and, in general, the outputs produced by the video encode operation will have undefined contents. + +In addition, certain commands may return the `VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR` error if any of the specified codec-specific parameters do not adhere to the syntactic or semantic requirements of the H.265/HEVC video compression standard or if values derived from parameters according to the rules defined by the H.265/HEVC video compression standard do not adhere to the capabilities of the H.265/HEVC video compression standard or the implementation. In particular, in this extension the following commands may return this error code: + + * `vkCreateVideoSessionParametersKHR` or `vkUpdateVideoSessionParametersKHR` - if the specified parameter sets are invalid according to these rules + * `vkEndCommandBuffer` - if the codec-specific picture information provided to video encode operations are invalid according to these rules + +Generating errors in the cases above, however, is not required so applications should not rely on receiving an error code for the purposes of verifying the correctness of the used codec-specific parameters. + + +=== RESOLVED: Do we want to allow the application to specify separate reference lists for each slice segment? + +Not in this extension. While the H.265/HEVC video compression standard seems to support this, such flexibility is not exposed here for the sake of simplicity. If the need arises to support per slice segment reference lists, a layered extension can introduce the necessary APIs to enable it. + + +=== RESOLVED: Are generalized P and B frames (aka low delay B frames) supported? + +Yes, in fact, some implementations do not support encoding P frames but do support encoding B frames with backward-only references. In order to maximize portability, applications should check for B frame support and use low delay B frames to encode frames with backward-only references even when P frame support is not available on a given implementation. + + +=== RESOLVED: What codec-specific parameters are guaranteed to not be overridden by implementations? + +This proposal only requires that implementations do not override the `pic_type` and `slice_type` parameters, as the used picture and slice types are fundamental to the general operation of H.265 encoding. In addition, bits set in the `stdSyntaxFlags` capability provide additional guarantees about other Video Std parameters that the implementation will use without overriding them. No further restrictions are included in this extension regarding codec-specific parameter overrides, however, future extensions may include capability flags providing additional guarantees based on the needs of the users of the API. + + +=== RESOLVED: Can implementations override the values of `pic_width_in_luma_samples` and/or `pic_height_in_luma_samples`? + +Yes. Implementations may have limitations on the size of the coding blocks they can produce within CTBs amongst other implementation-specific alignment limitations which may require overriding the values of `pic_width_in_luma_samples` and/or `pic_height_in_luma_samples`. This can be safely done without affecting the effective coded extent of the encoded frames by making corresponding adjustments to the values of `conf_win_right_offset` and/or `conf_win_bottom_offset`. Allowing implementations to perform such codec-specific parameter overrides enables better portability and avoids the need for application developers having to navigate an unnecessarily complex set of capabilities that would otherwise be necessary to account for the quirks of individual hardware implementations. + + +=== RESOLVED: How is reference picture setup requested for H.265 encode operations? + +As specifying a reconstructed picture DPB slot and resource is always required per the latest revision of the video extensions, additional codec syntax controls whether reference picture setup is requested and, in response, the DPB slot is activated with the reconstructed picture. + +For H.265 encode, reference picture setup is requested and the DPB slot specified for the reconstructed picture is activated with the picture if and only if the `StdVideoEncodeH265PictureInfo::flags.is_reference` flag is set. + + +== Further Functionality + +Future extensions can further extend the capabilities provided here, e.g. exposing support for encode modes allowing per-slice-segment input and/or output. diff --git a/proposals/VK_KHR_video_encode_queue.adoc b/proposals/VK_KHR_video_encode_queue.adoc new file mode 100644 index 000000000..1d00d7b9c --- /dev/null +++ b/proposals/VK_KHR_video_encode_queue.adoc @@ -0,0 +1,1379 @@ +// Copyright 2021-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_KHR_video_encode_queue +:toc: left +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ +:sectnums: + +This document outlines a proposal to enable performing video encode operations in Vulkan. + +== Problem Statement + +Integrating video encode operations into Vulkan applications enables a wide set of new usage scenarios including, but not limited to, the following examples: + + * Recording the output of rendering operations + * Efficiently transferring rendering results over network (video conferencing, game streaming, etc.) + +It is also not uncommon for Vulkan capable devices to feature dedicated hardware acceleration for video compression. + +The goal of this proposal is to enable these use cases, expose the underlying hardware capabilities, and provide tight integration with other functionalities of the Vulkan API. + + +== Solution Space + +The following options have been considered: + + 1. Rely on external sharing capabilities to interact with existing video encode APIs + 2. Add new dedicated APIs to Vulkan specific to video encoding + 3. Build upon a common set of APIs that enable video coding operations in general + +As discussed in the proposal for the `VK_KHR_video_queue` extension, reusing a common, shared infrastructure across all video coding functionalities that leverage existing Vulkan capabilities was preferred, hence this extension follows option 3. + +Further sub-options were considered whether a common set of APIs could be used to enable video encoding in general, upon which codec-specific extensions can be built. As the possibility of API reuse is similarly possible within the domain of video encoding as it is for video coding in general, this proposal follows the same principle to extend `VK_KHR_video_queue` with codec-independent video encoding capabilities. + + +== Proposal + +=== Video Encode Queues + +While `VK_KHR_video_queue` already includes support for a more fine grained query to determine the set of supported video codec operations for a given queue family, this extension introduces an explicit queue flag called `VK_QUEUE_VIDEO_ENCODE_BIT_KHR` to indicate support for video encoding. + +Applications can use this flag bit to identify video encode capable queue families in general, if needed, before querying more details about the individual video codec operations supported through the use of the `VkQueueFamilyVideoPropertiesKHR` structure. It also indicates support for the set of command buffer commands available on video encode queues, which include the following: + + * Pipeline barrier and event handling commands used for synchronization + * Basic query commands to begin, end, and reset queries + * Timestamp write commands + * Generic video coding commands + * The new video encode command introduced by this extension + +For the full list of individual commands supported by video encode queues, and whether any command is supported inside/outside of video coding scopes, refer to the manual page of the corresponding command. + + +=== Video Encode Profiles + +Video encode profiles are defined using a `VkVideoProfileInfoKHR` structure that specifies a `videoCodecOperation` value identifying a video encode operation. This extension does not introduce any video encode operation flags, as that is left to the codec-specific encode extensions. + +On the other hand, this extension allows the application to specify usage information specific to video encoding by chaining the following new structure to `VkVideoProfileInfoKHR`: + +[source,c] +---- +typedef struct VkVideoEncodeUsageInfoKHR { + VkStructureType sType; + const void* pNext; + VkVideoEncodeUsageFlagsKHR videoUsageHints; + VkVideoEncodeContentFlagsKHR videoContentHints; + VkVideoEncodeTuningModeKHR tuningMode; +} VkVideoEncodeUsageInfoKHR; +---- + +This structure contains two hints specific to the encoding use case and the content to be encoded, respectively, as well as a tuning mode. + +The usage hint flags introduced by this extension are as follows: + + * `VK_VIDEO_ENCODE_USAGE_TRANSCODING_BIT_KHR` should be used in video transcoding use cases + * `VK_VIDEO_ENCODE_USAGE_STREAMING_BIT_KHR` should be used when encoding video content streamed over network + * `VK_VIDEO_ENCODE_USAGE_RECORDING_BIT_KHR` should be used in real-time recording but offline consumption use cases + * `VK_VIDEO_ENCODE_USAGE_CONFERENCING_BIT_KHR` should be used for video conferencing use cases + +The content hint flags introduced are as follows: + + * `VK_VIDEO_ENCODE_CONTENT_CAMERA_BIT_KHR` should be used when encoding images captured using a camera + * `VK_VIDEO_ENCODE_CONTENT_DESKTOP_BIT_KHR` should be used when encoding desktop screen captures + * `VK_VIDEO_ENCODE_CONTENT_RENDERED_BIT_KHR` should be used when encoding rendered (e.g. game) content + +These usage hints do not provide any restrictions or guarantees, so any combination of flags can be used, but they allow the application to better communicate the intended use case scenario so that implementations can make appropriate choices based on it. + +Logically, however, it is part of the video profile definition, so capabilities may vary across video encode profiles that only differ in terms of video encode usage hints, and it also affects video profile compatibility between resources and video sessions, so the same `VkVideoEncodeUsageInfoKHR` structure has to be included everywhere where the specific video encode profile is used. The contemporary extension `VK_KHR_video_maintenance1`, however, does allow creating buffer and image resources that are compatible with multiple video profiles when they are created with the `VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR` or `VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR` flags, respectively, introduced by that extension. + +Unlike the hints, `tuningMode` is an explicit mode setting parameter that has functional implications and is expected to limit encoding capabilities to fit the usage scenario. The following tuning mode values are introduced by this extension: + + * `VK_VIDEO_ENCODE_TUNING_MODE_DEFAULT_KHR` is the default tuning mode + * `VK_VIDEO_ENCODE_TUNING_MODE_HIGH_QUALITY_KHR` tunes encoding for high quality and will likely impose latency and performance compromises + * `VK_VIDEO_ENCODE_TUNING_MODE_LOW_LATENCY_KHR` tunes encoding for low latency and will likely impose quality compromises for better performance + * `VK_VIDEO_ENCODE_TUNING_MODE_ULTRA_LOW_LATENCY_KHR` tunes encoding for ultra-low latency with further quality compromises for maximum performance + * `VK_VIDEO_ENCODE_TUNING_MODE_LOSSLESS_KHR` tunes encoding to produce lossless output. + +In practice, not all codecs and profiles will support every tuning mode. The new query command `vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR`, as described later, may also return different recommended configuration parameters based on the tuning mode specified in the video profile in order to further aid application developers in choosing the most suitable settings for the encoding scenario at hand. + + +=== New Pipeline Stage and Access Flags + +This extension also introduces a new pipeline stage identified by the `VK_PIPELINE_STAGE_2_VIDEO_ENCODE_BIT_KHR` flag to enable synchronizing video encode operations with respect to other Vulkan operations. + +In addition, two new access flags are introduced to indicate reads and writes, respectively, performed by the video encode pipeline stage: + + * `VK_ACCESS_2_VIDEO_ENCODE_READ_BIT_KHR` + * `VK_ACCESS_2_VIDEO_ENCODE_WRITE_BIT_KHR` + +As these flags did no longer fit into the legacy 32-bit enums, this extension requires the `VK_KHR_synchronization2` extension and relies on the 64-bit versions of the pipeline stage and access mask flags to handle synchronization specific to video encode operations. + + +=== New Buffer and Image Usage Flags + +This extension introduces the following new buffer usage flags: + + * `VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR` is reserved for future use + * `VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR` allows using the buffer as a video bitstream buffer in video encode operations + +This extension also introduces the following new image usage flags: + + * `VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR` allows using the image as an encode input picture + * `VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR` is reserved for future use + * `VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR` allows using the image as an encode DPB picture (reconstructed/reference picture) + +Specifying these usage flags alone is not sufficient to create a buffer or image that is compatible with a video session created against any particular video profile. In fact, when specifying any of these usage flags at resource creation time, the application has to include a `VkVideoProfileListInfoKHR` structure in the `pNext` chain of the corresponding create info structure with `VkVideoProfileListInfoKHR::pProfiles` including a video encode profile. The created resources will be compatible only with the included video encode profiles (and a video encode profile, if one is also specified in the list). + + +=== New Format Feature Flags + +To indicate which formats are compatible with video encode usage, the following new format feature flags are introduced: + + * `VK_FORMAT_FEATURE_VIDEO_ENCODE_INPUT_BIT_KHR` indicates support for encode input picture usage + * `VK_FORMAT_FEATURE_VIDEO_ENCODE_DPB_BIT_KHR` indicates support for encode DPB picture usage + +The presence of the format flags alone, as returned by the various format queries, is not sufficient to indicate that an image with that format is usable with video encoding using any particular video encode profile. Actual compatibility with a specific video encode profile has to be verified using the `vkGetPhysicalDeviceVideoFormatPropertiesKHR` command. + + +=== Basic Operation + +Video encode operations can be recorded into command buffers allocated from command pools created against queue families that support the `VK_QUEUE_VIDEO_ENCODE_BIT_KHR` flag. + +Recording video encode operations happens through the use of the following new command: + +[source,c] +---- +VKAPI_ATTR void VKAPI_CALL vkCmdEncodeVideoKHR( + VkCommandBuffer commandBuffer, + const VkVideoEncodeInfoKHR* pEncodeInfo); +---- + +The common, codec-independent parameters of the video encode operation are provided using the following new structure: + +[source,c] +---- +typedef struct VkVideoEncodeInfoKHR { + VkStructureType sType; + const void* pNext; + VkVideoEncodeFlagsKHR flags; + VkBuffer dstBuffer; + VkDeviceSize dstBufferOffset; + VkDeviceSize dstBufferRange; + VkVideoPictureResourceInfoKHR srcPictureResource; + const VkVideoReferenceSlotInfoKHR* pSetupReferenceSlot; + uint32_t referenceSlotCount; + const VkVideoReferenceSlotInfoKHR* pReferenceSlots; + uint32_t precedingExternallyEncodedBytes; +} VkVideoEncodeInfoKHR; +---- + +Executing such a video encode operation results in the compression of a single picture (unless otherwise defined by layered extensions), and, if there is an active `VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR` query, the status of the video encode operation is recorded into the active query slot. + +In addition to `VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR` queries, applications can use the new `VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR` queries to retrieve additional feedback about the encoded picture including the offset and size of the bitstream written to the specified video bitstream buffer range, as discussed later. + +If the encode operation requires additional codec-specific parameters, then such parameters are provided in the `pNext` chain of the structure above. Whether such codec-specific information is necessary, and what it may contain is up to the codec-specific extensions. + +`dstBuffer`, `dstBufferOffset`, and `dstBufferRange` provide information about the target video bitstream buffer range. The video encode operation writes the compressed picture data to this buffer range. + +The application has to create the video bitstream buffer with the new `VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR` usage flag, and must also include the used video session's video profile in the `VkVideoProfileListInfoKHR` structure specified at buffer creation time. + +The data written to the video bitstream buffer range depends on the specific video codec used, as defined by corresponding codec-specific extensions built upon this proposal. + +The `srcPictureResource`, `pSetupReferenceSlot`, and `pReferenceSlots` members specify the encode input picture, reconstructed picture, and reference pictures, respectively, used by the video encode operation, as discussed in later sections of this proposal. + +The `precedingExternallyEncodedBytes` member specifies the number of bytes externally encoded into the bitstream by the application. This value is used to update the implementation's rate control algorithm for the rate control layer this encode operation belongs to, by accounting for the bitrate budget consumed by these externally encoded bytes. This parameter is respected by the implementation only if the `VK_VIDEO_ENCODE_CAPABILITY_PRECEDING_EXTERNALLY_ENCODED_BYTES_BIT_KHR` capability is supported. + + +=== Encode Input Picture + +`srcPictureResource` defines the parameters of the video picture resource to use as the encode input picture. The video encode operation reads the picture data to compress from this video picture resource. As such it is a mandatory parameter of the operation. + +The application has to create the image view specified in `srcPictureResource.imageViewBinding` with the new `VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR` usage flag, and must also include the used video session's video profile in the `VkVideoProfileListInfoKHR` structure specified at image creation time. + +The image subresource backing the encode input picture has to be in the new `VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR` layout at the time the video encode operation is executed. + + +=== Reconstructed Picture + +`pSetupReferenceSlot` is an optional parameter specifying the video picture resource and DPB slot index to use for the reconstructed picture. Implementations use the reconstructed picture for one of the following purposes: + + 1. When the encoded picture is requested to be set up as a reference, according to the codec-specific semantics, the video encode operation will perform picture reconstruction, output the results to this picture, and activate the reconstructed picture's DPB slot with the picture in order to enable using the picture as a reference picture in future video encode operations. + 2. When the encoded picture is not requested to be set up as a reference, implementations may use the reconstructed picture's resource and/or DPB slot for intermediate data required by the encoding process. + +Accordingly, `pSetupReferenceSlot` must never be `NULL`, except when the video session was created without any DPB slots. + +[NOTE] +.Note +==== +The original version of this extension only required the specification of the reconstructed picture information (i.e. a non-`NULL` `pSetupReferenceSlot`) when the application intended to set up a reference picture by activating a DPB slot. Consequently, the presence of reconstructed picture information always implied DPB slot activation. This was changed in revision 12 of the extension, and whether DPB slot activation happens is now subject to codec-specific semantics. More details on this change are discussed in the corresponding issue in this proposal document. +==== + +In summary, for encoded pictures requested to be set up as reference, this parameter can be used to add new reference pictures to the DPB, and change the association between DPB slot indices and video picture resources. That also implies that the application has to specify a video picture resource in `pSetupReferenceSlot->pPictureResource` that was included in the set of bound reference picture resources specified when the video coding scope was started (in one of the elements of `VkVideoBeginCodingInfoKHR::pReferenceSlots`). No similar requirement exists for the encode input picture specified by `srcPictureResource` which can refer to any video picture resource. + +The application has to create the image view specified in `pSetupReferenceSlot->pPictureResource->imageViewBinding` with the new `VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR` usage flag, and must also include the used video session's video profile in the `VkVideoProfileListInfoKHR` structure specified at image creation time. + +The image subresource backing the reconstructed picture has to be in the new `VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR` layout at the time the video encode operation is executed. + +If the video profile in use requires additional codec-specific parameters for the reconstructed picture, then such parameters are provided in the `pNext` chain of `pSetupReferenceSlot`. Whether such codec-specific reconstructed picture information is necessary, and what it may contain is up to the codec-specific extensions. + + +=== Reference Pictures + +If the video session allows, reference pictures can be specified in the `pReferenceSlots` array to provide predictions of the values of samples of the encoded picture. + +Each entry in the `pReferenceSlots` array adds one or more pictures, currently associated with the DPB slot specified in the element's `slotIndex` member and stored in the video picture resource specified in the element's `pPictureResource` member, to the list of active reference pictures to use in the video encode operation. + +The application has to make sure to specify each video picture resource used as a reference picture in a video encode operation, beforehand, in the set of bound reference picture resources specified when the video coding scope was started (in one of the elements of `VkVideoBeginCodingInfoKHR::pReferenceSlots`). + +The application has to create the image view specified in `pPictureResource->imageViewBinding` of the elements of `pReferenceSlots` with the new `VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR` usage flag, and must also include the used video session’s video profile in the `VkVideoProfileListInfoKHR` structure specified at image creation time. + +The image subresources backing the reference pictures have to be in the new `VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR` layout at the time the video encode operation is executed. + +Typically the number of elements in `pReferenceSlots` equals the number of reference pictures added, but in certain cases (depending on the used video codec and video profile) there may be multiple pictures in the same DPB slot resource. + +If the video profile in use requires additional codec-specific parameters for the reference pictures, then such parameters are provided in the `pNext` chain of the elements of `pReferenceSlots`. Whether such codec-specific reference picture information is necessary, and what it may contain is up to the codec-specific extensions. + + +=== Video Encode Parameter Overrides + +Encoder implementations usually only support a subset of the available encoding tools defined by the corresponding video compression standards. This may prevent some implementation from being able to respect certain codec-specific parameters, or specific parameter values. + +Enumerating exhaustively all of these constraints and potentially defining application queryable capabilities corresponding to those is not practical, as it would potentially require separate capabilities for almost every single codec-specific parameter, parameter value, and combinations of those, as usually there are complicated interactions between those codec-specific parameters. Instead, this proposal approaches this problem from the other direction. + +Instead of defining capabilities for each of these constraints, implementations are allowed to override codec-specific parameter values or combinations thereof, so that the resulting overridden codec-specific parameters now comply to the constraints of the target implementation. This has multiple benefits: + + * Enables the video encode APIs to be supported on a much wider set of hardware implementations, as the codec-specific extensions layered on top of this extension would not have codec-specific requirements that assume implementations to support certain, potentially not universally available, encoding tools + * Enables implementations to expose all of the encoding tools they support for a particular video compression standard, which typically is not possible in other video APIs as, without overrides, implementations may not be able to expose a large set of their encoding tools just because they do not comply to the exact wording of the capabilities defined by that API + * Enables writing portable applications without getting lost in myriads of capabilities + +Allowing implementations to override codec-specific parameters does not mean, however, that implementations can do any overrides they wish. The base parameter override mechanism is reserved to deal with implementation limitations only. Thus, by default, implementations are expected to override codec-specific parameters only if it is absolutely paramount for the correct functioning of their encoder hardware. + +In certain cases, applications may want to allow the implementation to make its own choices about the certain codec-specific parameters that are not driven by implementation constraints, but rather aim to allow the implementation to choose parameters and encoding tools that better fit the usage scenario described by the video profile and other parameters, like the encode quality level, than the one the application specified. This proposal introduces a new video session creation flag called `VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHR` that enables the application to opt in to such optimization overrides. + +There are certain rules that implementations need to follow in all cases where they may apply codec-specific parameter overrides. In particular: + + * Certain codec-specific parameters are defined by layered codec-specific extensions to be always respected, and thus cannot be overridden, which is generally expected to be the case for all parameters that may affect the overall behavior of video encoding, or any bitstream elements that are not encoded in any fashion by the implementation, so that applications still have the necessary freedom to encode such auxiliary bitstream elements the way they wish + * In a similar vein, implementation overrides cannot affect the compliance of the generated bitstream to the video compression standard + +The details of these rules can be found in the specification language of this extension, and any layered extension built upon it. + +In general, there are two categories of codec-specific parameters to which implementation overrides may be applied: + + 1. Codec-specific parameters stored in video session parameters objects, if any + 2. Codec-specific parameters provided to video encode commands + +Both of these codec-specific parameter categories may have an effect on the video bitstream data produced by video encode operations. However, parameters falling into the first category are particularly important as it is common for applications to encode the codec-specific parameters stored in video session parameters on their own. + +In order to enable the application to deal with parameter overrides applied to video session parameters, this proposal introduces the following new command: + +[source,c] +---- +VKAPI_ATTR VkResult VKAPI_CALL vkGetEncodedVideoSessionParametersKHR( + VkDevice device, + const VkVideoEncodeSessionParametersGetInfoKHR* pVideoSessionParametersInfo, + VkVideoEncodeSessionParametersFeedbackInfoKHR* pFeedbackInfo, + size_t* pDataSize, + void* pData); +---- + +The main input to this command is the video session parameters object in question, with layered extensions adding additional chainable structures to provide additional codec-specific input parameters: + +[source,c] +---- +typedef struct VkVideoEncodeSessionParametersGetInfoKHR { + VkStructureType sType; + const void* pNext; + VkVideoSessionParametersKHR videoSessionParameters; +} VkVideoEncodeSessionParametersGetInfoKHR; +---- + +This command has multiple purposes. + +First, by providing a non-`NULL` `pFeedbackInfo` parameter, the application can get feedback about whether the implementation applied any parameter overrides to the video session parameters in question through the following output structure: + +[source,c] +---- +typedef struct VkVideoEncodeSessionParametersFeedbackInfoKHR { + VkStructureType sType; + void* pNext; + VkBool32 hasOverrides; +} VkVideoEncodeSessionParametersFeedbackInfoKHR; +---- + +The `hasOverrides` member will be set to `VK_TRUE` if implementation overrides were applied, and layered extensions may provide additional chainable output structures that return further (typically codec-specific) information about the applied overrides. + +When this feedback indicates that implementation overrides were applied, the application needs to retrieve the encoded video session parameters containing the overrides in order to be able to produce a compliant bitstream. This can be done in the usual fashion by providing a non-`NULL` `pDataSize` parameter to retrieve the size of the encoded parameter data, and then calling the command again with a non-`NULL` `pData` pointer to retrieve the data. + +The application can choose to use the `vkGetEncodedVideoSessionParametersKHR` command to encode the video session parameters even if the implementation did not override any of the parameters, but in this case it can also choose to encode the respective bitstream elements on its own. + +It is worth calling out though that if the application does not use this command to determine whether video session parameter overrides happened or does not use the encoded parameters retrievable using this command when video session parameter overrides happened, but rather just encodes the respective bitstream elements with its own choice of codec-specific parameters, then it risks the resulting video bitstream to end up being non-compliant to the video compression standard. + + +=== Capabilities + +Querying capabilities specific to video encoding happens through the query mechanisms introduced by the `VK_KHR_video_queue` extension. + +Support for individual video encode operations can be retrieved for each queue family using the `VkQueueFamilyVideoPropertiesKHR` structure, as discussed earlier. + +The application can also use the `vkGetPhysicalDeviceVideoCapabilitiesKHR` command to query the capabilities of a specific video encode profile. In case of video encode profiles, the following new structure has to be included in the `pNext` chain of the `VkVideoCapabilitiesKHR` structure used to retrieve the general video encode capabilities: + +[source,c] +---- +typedef struct VkVideoEncodeCapabilitiesKHR { + VkStructureType sType; + void* pNext; + VkVideoEncodeCapabilityFlagsKHR flags; + VkVideoEncodeRateControlModeFlagsKHR rateControlModes; + uint32_t maxRateControlLayers; + uint64_t maxBitrate; + uint32_t maxQualityLevels; + VkExtent2D encodeInputPictureGranularity; + VkVideoEncodeFeedbackFlagsKHR supportedEncodeFeedbackFlags; +} VkVideoEncodeCapabilitiesKHR; +---- + +This structure contains a new encode-specific `flags` member that indicates support for various video encode capabilities, like the support for the `precedingExternallyEncodedBytes` parameter discussed before. + +The `rateControlModes` and `maxRateControlLayers` members provide information about the supported rate control modes and maximum number of rate control layers that can be used in a video session, as discussed later. + +The `maxBitrate` member provides information about the maximum bitrate supported for the video profile. + +The `maxQualityLevels` member specifies the number of different video encode quality level values supported by the video encode profile in question which are identified with numbers in the range `0..maxQualityLevels`. The number and implementation effect of the quality levels is expected to vary across video encode profiles, even in video encode profiles using the same video codec operation (e.g. due to the use of different tuning modes), as discussed later. + +The `encodeInputPictureGranularity` member indicates the granularity at which data from the encode input picture is used for encoding individual codec-specific coding blocks. If this capability is not `{1,1}`, then it is recommend for applications to initialize the data in the encode input picture at this granularity, as the encoder will use data in such padding texels during the encoding, which may affect the quality and efficiency of the encoding. + +The `supportedEncodeFeedbackFlags` member indicates the set of supported encode feedback flags for the `VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR` queries described later. + +The `vkGetPhysicalDeviceVideoFormatPropertiesKHR` command can be used to query the supported image/picture formats for a given set of video profiles, as described in the `VK_KHR_video_queue` extension. + +In particular, if the application would like to query the list of format properties supported for encode input pictures, then it should include the new `VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR` usage flag in `VkPhysicalDeviceVideoFormatInfoKHR::imageUsage`. + +Similarly, to query the list of format properties supported for encode DPB pictures (reconstructed/reference pictures), then it should include the new `VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR` usage flag in `VkPhysicalDeviceVideoFormatInfoKHR::imageUsage`. + + +=== Video Encode Quality Levels + +This proposal introduces the concept of video encode quality levels, which can be thought of as encoder presets that control the number and type of implementation-specific encoding tools and algorithms utilized in the encoding process. Implementations can expose support for one or more such video encode quality levels for each video profile. By default, video encode quality level index zero is used, unless otherwise specified. + +Generally, using higher video encode quality levels may produce higher quality video streams at the cost of additional processing time. However, as the final quality of an encoded picture depends on the contents of the encode input picture, the contents of the active reference pictures, the codec-specific encode parameters, and the particular implementation-specific tools used corresponding to the individual video encode quality levels, there are no guarantees that using a higher video encode quality level will always produce a higher quality encoded picture for any given set of inputs. + +The chosen quality level may also affect the optimization overrides applied by implementations when using the `VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHR` flag, and thus codec-specific parameters stored in video session parameters may be affected by the used video encode quality level. As such, video session parameters objects are always created with respect to a specific video encode quality level. The application can choose to create a video session parameters object with a video encode quality level index different than the default quality level of zero by including the following new structure in the `pNext` chain of `VkVideoSessionParametersCreateInfoKHR`: + +[source,c] +---- +typedef struct VkVideoEncodeQualityLevelInfoKHR { + VkStructureType sType; + const void* pNext; + uint32_t qualityLevel; +} VkVideoEncodeQualityLevelInfoKHR; +---- + +Where `qualityLevel` specifies the used video encode quality level. + +Video sessions created against a video encode profile allow changing the used video encode quality level dynamically. After creation, the video session is configured with the default quality level of zero, which then can be changed by including the new `VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR` flag in the `flags` member of the `VkVideoCodingControlInfoKHR` structure passed to the `vkCmdControlVideoCodingKHR` command and including an instance of the `VkVideoEncodeQualityLevelInfoKHR` structure in the `VkVideoCodingControlInfoKHR::pNext` chain specifying the new quality level to set for the video session. + +If video session parameters objects are used by a particular video encode command, then the video encode quality the parameters object was created with has to match the currently configured quality level for the bound video session. + +Implementations may have certain recommendations for encoding parameters and configuration (e.g. for rate control) specific to each supported video encode quality level. These recommendations and other quality level related properties can be queried for a specific video encode profile using the following new command: + +[source,c] +---- +VKAPI_ATTR VkResult VKAPI_CALL vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR( + VkPhysicalDevice physicalDevice, + const VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR* pQualityLevelInfo, + VkVideoEncodeQualityLevelPropertiesKHR* pQualityLevelProperties); +---- + +The input to the command is a structure that specifies the video encode profile and quality level to query properties for: + +[source,c] +---- +typedef struct VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR { + VkStructureType sType; + const void* pNext; + const VkVideoProfileInfoKHR* pVideoProfile; + uint32_t qualityLevel; +} VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR; +---- + +This proposal allows retrieving the following codec-independent quality level properties: + +[source,c] +---- +typedef struct VkVideoEncodeQualityLevelPropertiesKHR { + VkStructureType sType; + void* pNext; + VkVideoEncodeRateControlModeFlagBitsKHR preferredRateControlMode; + uint32_t preferredRateControlLayerCount; +} VkVideoEncodeQualityLevelPropertiesKHR; +---- + +Layered extensions may add additional (typically codec-specific) property structures that can be chained to the base output structure defined above. + + +=== Video Encode Feedback Queries + +The new `VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR` query type works similarly to pipeline statistics from the perspective of being able to report multiple distinct values about the video encode operations they collect feedback about. When creating a query pool with this type the following new structure specifies the selected feedback values: + +[source,c] +---- +typedef struct VkQueryPoolVideoEncodeFeedbackCreateInfoKHR { + VkStructureType sType; + const void* pNext; + VkVideoEncodeFeedbackFlagsKHR encodeFeedbackFlags; +} VkQueryPoolVideoEncodeFeedbackCreateInfoKHR; +---- + +This extension adds support for the following video encode feedback flags: + + * `VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR` requests capturing the offset relative to `dstBufferOffset` where the bitstream data corresponding to the video encode operation is written to + * `VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR` requests capturing the number of bytes written by the video encode operation to the bitstream buffer + * `VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR` requests capturing information about whether the implementation overrode any codec-specific parameters in the generated bitstream data with respect to the parameter values supplied by the application + +All implementations are expected to support `VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR` and `VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR`, but `VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR` is optional, as not all implementations may be able to provide feedback about overrides performed on the encoded bitstream data. + +The reported offset for `VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR` is currently defined to be always zero until otherwise defined by any layered extension. + + +=== Video Encode Rate Control + +A key aspect of video encoding is to control the size of the encoded bitstream. This happens through the application of rate control. Rate control settings consist of codec-independent and codec-specific parameters hence this extension only includes the common parameters. + +The following rate control modes are introduced by this extension: + + * `VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR` for disabling rate control + * `VK_VIDEO_ENCODE_RATE_CONTROL_MODE_CBR_BIT_KHR` for constant bitrate (CBR) rate control + * `VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR` for variable bitrate (VBR) rate control + +In addition, the `VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR` constant is used to set rate control configuration to implementation-dependent default settings. This is the initial rate control mode that is set for newly created video sessions which leaves rate control entirely in the implementation's control. + +Certain codecs define a concept typically referred to as _video coding layers_. The semantics of these layers are defined by the corresponding video compression standards. However, some implementations allow certain configuration parameters of rate control to be specified separately for each such video coding layer, thus this proposal introduces the concept of rate control layers which enable the application to explicitly control these parameters on a per layer basis. + +When a single rate control layer is configured, it is applied to all encoded pictures. In contrast, when multiple rate control layers are configured, then each rate control layer is applied only to encoded pictures targeting a specific video coding layer. + +After a video session is reset using `VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR`, its rate control settings are initialized to implementation-specific defaults. Applications can change these by calling `vkCmdControlVideoCodingKHR` and specifying the `VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR` flag. When this flag is present, the following new structure chained to the `pNext` chain of `VkVideoCodingControlInfoKHR` specifies the rate control configuration: + +[source,c] +---- +typedef struct VkVideoEncodeRateControlInfoKHR { + VkStructureType sType; + const void* pNext; + VkVideoEncodeRateControlFlagsKHR flags; + VkVideoEncodeRateControlModeFlagBitsKHR rateControlMode; + uint32_t layerCount; + const VkVideoEncodeRateControlLayerInfoKHR* pLayers; + uint32_t virtualBufferSizeInMs; + uint32_t initialVirtualBufferSizeInMs; +} VkVideoEncodeRateControlInfoKHR; +---- + +`rateControlMode` specifies the rate control mode to set. + +`layerCount` specifies the number of rate control layers to use from this point, and `pLayers` specifies the configuration of each layer. Rate control layers can only be specified when rate control is not disabled or is not set to the implementation-specific defaults. + +`virtualBufferSizeInMs` and `initialVirtualBufferSizeInMs` specify the size and initial occupancy, respectively, in milliseconds of the leaky bucket model virtual buffer. + +The `VkVideoEncodeRateControlLayerInfoKHR` structure is defined as follows: + +[source,c] +---- +typedef struct VkVideoEncodeRateControlLayerInfoKHR { + VkStructureType sType; + const void* pNext; + uint64_t averageBitrate; + uint64_t maxBitrate; + uint32_t frameRateNumerator; + uint32_t frameRateDenominator; +} VkVideoEncodeRateControlLayerInfoKHR; +---- + +`averageBitrate` and `maxBitrate` specify the target and peak bitrate that the rate control layer should use in bits/second. In case of CBR mode the two values have to match. + +`frameRateNumerator` and `frameRateDenominator` specify the numerator and denominator of the frame rate used by the video sequence. + +The exact behavior of rate control is implementation-specific but it is typically constrained by the video compression standard corresponding to the used video profile. Implementations are expected to implement rate control as follows: + + * In case of CBR mode the bitrate should stay as close to the specified `averageBitrate` as possible within the virtual buffer window. + * In case of VBR mode the bitrate should not exceed the value of `maxBitrate` while also trying to get close to the target bitrate specified by `averageBitrate` within the virtual buffer window. + +Codec-specific video encode extensions can include both global and per-layer codec-specific rate control configurations by chaining codec-specific parameters to the `VkVideoEncodeRateControlInfoKHR` and `VkVideoEncodeRateControlLayerInfoKHR` structures, respectively. + +Some implementations do not track the current rate control configuration as part of the device state maintained in the video session object, but the current rate control configuration may affect the device commands recorded in response to video encode operations. In order to enable implementations to have access to the current rate control configuration when recording video encoding commands into command buffers, this proposal requires the current rate control configuration to be also specified when calling `vkCmdBeginVideoCodingKHR` by including the `VkVideoEncodeRateControlInfoKHR` structure describing it in the `pNext` chain of the `pBeginCodingInfo` parameter. When this information is not included, it is assumed that the currently expected rate control configuration is the default one, i.e. the implementation-specific rate control mode indicated by `VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR`. + +It is important to note that specifying the rate control configuration when calling `vkCmdBeginVideoCodingKHR` does not change the current rate control configuration. For that the `vkCmdControlVideoCodingKHR` command must be used with the `VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR` flag, as discussed earlier. The rate control configuration specified to `vkCmdBeginVideoCodingKHR` serves only to make the information about the current rate control state available to implementations during command recording and is expected to always match the effective current rate control state at the time the command is executed on the device. + + +=== Usage Summary + +To summarize the usage of the video encoding features introduced by this extension, let us take a look at a typical usage scenario when using this extension to encode a video stream. + +Before the application can start recording command buffers with video encode operations, it has to do the following: + + . Ensure that the implementation can encode the video content by first querying the video codec operations supported by each queue family using the `vkGetPhysicalDeviceQueueFamilyProperties2` command and the `VkQueueFamilyVideoPropertiesKHR` output structure. + . If needed, the application has to also retrieve the `VkQueueFamilyQueryResultStatusPropertiesKHR` output structure for the queue family to check support for `VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR` queries. + . Construct the `VkVideoProfileInfoKHR` structure describing the entire video profile, including the video codec operation, chroma subsampling, bit depths, and any other usage or codec-specific parameters. + . Ensure that the specific video profile is supported by the implementation using the `vkGetPhysicalDeviceVideoCapabilitiesKHR` command and retrieve the general, encode-specific, and codec-specific capabilities at the same time. + . Query the list of supported image/picture format properties supported for the video profile using the `vkGetPhysicalDeviceVideoFormatPropertiesKHR` structure, and select a suitable format for the DPB and encode input pictures. + . Create an image corresponding to the encode input picture with the appropriate usage flags and video profile list, as described earlier, and bind suitable device memory to the image. Also create an image view with the appropriate usage flags to use in the video encode operations. + . If needed, create one or more images corresponding to the DPB pictures with the appropriate usage flags and video profile list, as described earlier, and bind suitable device memory to them. Also create any image views with the appropriate usage flags to use in the video encode operations. + . Create a buffer with the `VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR` usage flag and the video profile list, to use as the destination video bitstream buffer. If the buffer is expected to be consumed using the CPU, consider binding compatible host-visible device memory to the buffer. + . If result status or video encode feedback queries are needed and supported (as determined earlier), create a query pool with the corresponding query type and the used video encode profile. + . Create the video session using the video encode profile and appropriate parameters within the capabilities supported by the profile, as determined earlier. Bind suitable device memory to each memory binding index of the video session. + . If needed, create a video session parameters object for the video session. + +Recording video encode operations into command buffers typically consists of the following sequence: + + . Start a video coding scope with the created video session (and parameters) object using the `vkCmdBeginVideoCodingKHR` command. Make sure to include all video picture resources in `VkVideoBeginCodingInfoKHR::pReferenceSlots` that may be used as reconstructed or reference pictures within the video coding scope, and ensure that the DPB slots specified for each reflect the current DPB slot association for the resource. + . If this is the first video coding scope the video session is used in, reset the video session to the initial state by recording a `vkCmdControlVideoCodingKHR` command with the `VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR` flag. + . If needed, also update the rate control state or the used video encode quality level for the video session by recording a + `vkCmdControlVideoCodingKHR` command with the `VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR` and/or `VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR` flags (can be done in the same command that resets the video session, if needed). + . If needed, start a result status or video coding feedback query using `vkCmdBeginQuery`. Reset the query using `vkCmdResetQueryPool`, beforehand, as needed. + . Issue a video encode operation using the `vkCmdEncodeVideoKHR` command with appropriate parameters, as discussed earlier. + . If needed, end the started query using `vkCmdEndQuery`. + . Record any further control or encode operations into the video coding scope, as needed. + . End the video coding scope using the `vkCmdEndVideoCodingKHR` command. + +Video profiles that require the use of video session parameters objects may also require the application to encode the stored codec-specific parameters separately into the final bitstream. Applications are expected to encode these parameters according to the following steps: + + . If the application wants to encode such parameters on its own, when possible, it should first call the `vkGetEncodedVideoSessionParametersKHR` command with a non-NULL `pFeedbackInfo` parameter to retrieve information about whether the implementation applied any overrides to the codec-specific parameters in question. + . If the results of the previous step indicate that no implementation overrides were applied, then the application can choose to encode the codec-specific parameters in question on its own and ignore the rest of the steps listed here + . Otherwise, the application has to retrieve the encoded codec-specific parameters by calling the `vkGetEncodedVideoSessionParametersKHR` command twice: first, to retrieve the size, second to retrieve the data of the encoded codec-specific parameters in question, as discussed earlier. + + +== Examples + +=== Select queue family with video encode support for a given video codec operation + +[source,c] +---- +VkVideoCodecOperationFlagBitsKHR neededVideoEncodeOp = ... +uint32_t queueFamilyIndex; +uint32_t queueFamilyCount; + +vkGetPhysicalDeviceQueueFamilyProperties2(physicalDevice, &queueFamilyCount, NULL); + +VkQueueFamilyProperties2* props = calloc(queueFamilyCount, + sizeof(VkQueueFamilyProperties2)); +VkQueueFamilyVideoPropertiesKHR* videoProps = calloc(queueFamilyCount, + sizeof(VkQueueFamilyVideoPropertiesKHR)); + +for (queueFamilyIndex = 0; queueFamilyIndex < queueFamilyCount; ++queueFamilyIndex) { + props[queueFamilyIndex].sType = VK_STRUCTURE_TYPE_QUEUE_FAMILY_PROPERTIES_2; + props[queueFamilyIndex].pNext = &videoProps[queueFamilyIndex]; + + videoProps[queueFamilyIndex].sType = VK_STRUCTURE_TYPE_QUEUE_FAMILY_VIDEO_PROPERTIES_KHR; +} + +vkGetPhysicalDeviceQueueFamilyProperties2(physicalDevice, &queueFamilyCount, props); + +for (queueFamilyIndex = 0; queueFamilyIndex < queueFamilyCount; ++queueFamilyIndex) { + if ((props[queueFamilyIndex].queueFamilyProperties.queueFlags & VK_QUEUE_VIDEO_ENCODE_BIT_KHR) != 0 && + (videoProps[queueFamilyIndex].videoCodecOperations & neededVideoEncodeOp) != 0) { + break; + } +} + +if (queueFamilyIndex < queueFamilyCount) { + // Found appropriate queue family + ... +} else { + // Did not find a queue family with the needed capabilities + ... +} +---- + + +=== Check support and query the capabilities for a video encode profile + +[source,c] +---- +VkResult result; + +// We also include the optional encode usage information here +VkVideoEncodeUsageInfoKHR profileUsageInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_USAGE_INFO_KHR, + .pNext = ... // pointer to codec-specific profile structure + .videoUsageHints = VK_VIDEO_ENCODE_USAGE_DEFAULT_KHR, + .videoContentHints = VK_VIDEO_ENCODE_CONTENT_DEFAULT_KHR, + .tuningMode = VK_VIDEO_ENCODE_TUNING_MODE_DEFAULT_KHR +}; + +VkVideoProfileInfoKHR profileInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PROFILE_INFO_KHR, + .pNext = &profileUsageInfo, + .videoCodecOperation = ... // used video encode operation + .chromaSubsampling = VK_VIDEO_CHROMA_SUBSAMPLING_420_BIT_KHR, + .lumaBitDepth = VK_VIDEO_COMPONENT_BIT_DEPTH_8_BIT_KHR, + .chromaBitDepth = VK_VIDEO_COMPONENT_BIT_DEPTH_8_BIT_KHR +}; + +VkVideoEncodeCapabilitiesKHR encodeCapabilities = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_CAPABILITIES_KHR, + .pNext = ... // pointer to codec-specific capability structure +} + +VkVideoCapabilitiesKHR capabilities = { + .sType = VK_STRUCTURE_TYPE_VIDEO_CAPABILITIES_KHR, + .pNext = &encodeCapabilities +}; + +result = vkGetPhysicalDeviceVideoCapabilitiesKHR(physicalDevice, &profileInfo, &capabilities); + +if (result == VK_SUCCESS) { + // Profile is supported, check additional capabilities + ... +} else { + // Profile is not supported, result provides additional information about why + ... +} +---- + + +=== Select encode input and DPB formats supported by the video encode profile + +[source,c] +---- +VkVideoProfileInfoKHR profileInfo = { + ... +}; + +VkVideoProfileListInfoKHR profileListInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PROFILE_LIST_INFO_KHR, + .pNext = NULL, + .profileCount = 1, + .pProfiles = &profileInfo +}; + +VkPhysicalDeviceVideoFormatInfoKHR formatInfo = { + .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_FORMAT_INFO_KHR, + .pNext = &profileListInfo +}; + +VkVideoFormatPropertiesKHR* formatProps = NULL; + +// First query encode input formats +formatInfo.imageUsage = VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR; + +vkGetPhysicalDeviceVideoFormatPropertiesKHR(physicalDevice, &formatInfo, &formatCount, NULL); +formatProps = calloc(formatCount, sizeof(VkVideoFormatPropertiesKHR)); +for (uint32_t i = 0; i < formatCount; ++i) { + formatProps.sType = VK_STRUCTURE_TYPE_VIDEO_FORMAT_PROPERTIES_KHR; +} +vkGetPhysicalDeviceVideoFormatPropertiesKHR(physicalDevice, &formatInfo, &formatCount, formatProps); + +for (uint32_t i = 0; i < formatCount; ++i) { + // Select encode input format and image creation capabilities best suited for the use case + ... +} +free(formatProps); + +// Then query DPB formats +formatInfo.imageUsage = VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR; + +vkGetPhysicalDeviceVideoFormatPropertiesKHR(physicalDevice, &formatInfo, &formatCount, NULL); +formatProps = calloc(formatCount, sizeof(VkVideoFormatPropertiesKHR)); +for (uint32_t i = 0; i < formatCount; ++i) { + formatProps.sType = VK_STRUCTURE_TYPE_VIDEO_FORMAT_PROPERTIES_KHR; +} +vkGetPhysicalDeviceVideoFormatPropertiesKHR(physicalDevice, &formatInfo, &formatCount, formatProps); + +for (uint32_t i = 0; i < formatCount; ++i) { + // Select DPB format and image creation capabilities best suited for the use case + ... +} +free(formatProps); +---- + + +=== Create bitstream buffer + +[source,c] +---- +VkBuffer bitstreamBuffer = VK_NULL_HANDLE; + +VkVideoProfileListInfoKHR profileListInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PROFILE_LIST_INFO_KHR, + .pNext = NULL, + .profileCount = ... // number of video profiles to use the bitstream buffer with + .pProfiles = ... // pointer to an array of video profile information structure chains +}; + +VkBufferCreateInfo createInfo = { + .sType = VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO, + .pNext = &profileListInfo, + ... + .usage = VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR | ... // any other usages that may be needed + ... +}; + +vkCreateBuffer(device, &createInfo, NULL, &bitstreamBuffer); +---- + + +=== Create encode input image and image view + +[source,c] +---- +VkImage inputImage = VK_NULL_HANDLE; +VkImageView inputImageView = VK_NULL_HANDLE; + +VkVideoProfileListInfoKHR profileListInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PROFILE_LIST_INFO_KHR, + .pNext = NULL, + .profileCount = ... // number of video profiles to use the encode input image with + .pProfiles = ... // pointer to an array of video profile information structure chains +}; + +VkImageCreateInfo imageCreateInfo = { + .sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO, + .pNext = &profileListInfo, + ... + .usage = VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR | ... // any other usages that may be needed + ... +}; + +vkCreateImage(device, &imageCreateInfo, NULL, &inputImage); + +VkImageViewUsageCreateInfo imageViewUsageInfo = { + .sType = VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO, + .pNext = NULL, + .usage = VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR +}; + +VkImageViewCreateInfo imageViewCreateInfo = { + .sType = VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO, + .pNext = &imageViewUsageInfo, + .flags = 0, + .image = inputImage, + .viewType = ... // image view type (only 2D or 2D_ARRAY is supported) + ... // other image view creation parameters +}; + +vkCreateImageView(device, &imageViewCreateInfo, NULL, &inputImageView); +---- + + +=== Create DPB image and image view + +[source,c] +---- +// NOTE: This example creates a single image and image view that is used to back all DPB pictures +// but, depending on the support of the VK_VIDEO_CAPABILITY_SEPARATE_REFERENCE_IMAGES_BIT_KHR +// capability flag, the application can choose to create separate images for each DPB slot or +// picture + +VkImage dpbImage = VK_NULL_HANDLE; +VkImageView dpbImageView = VK_NULL_HANDLE; + +VkVideoProfileListInfoKHR profileListInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PROFILE_LIST_INFO_KHR, + .pNext = NULL, + .profileCount = ... // number of video profiles to use the encode DPB image with + .pProfiles = ... // pointer to an array of video profile information structure chains +}; + +VkImageCreateInfo imageCreateInfo = { + .sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO, + .pNext = &profileListInfo, + ... + .usage = VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR | ... // any other usages that may be needed + ... + .arrayLayers = // typically equal to the DPB slot count +}; + +vkCreateImage(device, &imageCreateInfo, NULL, &dpbImage); + +VkImageViewUsageCreateInfo imageViewUsageInfo = { + .sType = VK_STRUCTURE_TYPE_IMAGE_VIEW_USAGE_CREATE_INFO, + .pNext = NULL, + .usage = VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR +}; + +VkImageViewCreateInfo imageViewCreateInfo = { + .sType = VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO, + .pNext = &imageViewUsageInfo, + .flags = 0, + .image = dpbImage, + .viewType = ... // image view type (only 2D or 2D_ARRAY is supported) + ... // other image view creation parameters +}; + +vkCreateImageView(device, &imageViewCreateInfo, NULL, &dpbImageView); +---- + + +=== Create and use video encode feedback query pool with a video session + +[source,c] +---- +VkQueryPool queryPool = VK_NULL_HANDLE; + +VkVideoProfileInfoKHR profileInfo = { + ... +}; + +// We will capture both bitstream offset and bitstream bytes written in the feedback +VkVideoEncodeFeedbackFlags capturedEncodeFeedbackValues = + VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BUFFER_OFFSET_BIT_KHR | + VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_BYTES_WRITTEN_BIT_KHR; + +// NOTE: Only the encode feedback values listed above are required to be supported by all +// video encode implementations. So if the application intends to use other encode +// feedback values like VK_VIDEO_ENCODE_FEEDBACK_BITSTREAM_HAS_OVERRIDES_BIT_KHR, then +// it must first check support for it as indicated by the supportedEncodeFeedbackFlags +// capability for the video encode profile in question. + +VkQueryPoolVideoEncodeFeedbackCreateInfoKHR feedbackInfo = { + .sType = VK_STRUCTURE_TYPE_QUERY_POOL_VIDEO_ENCODE_FEEDBACK_CREATE_INFO_KHR, + .pNext = &profileInfo, + .encodeFeedbackFlags = capturedEncodeFeedbackValues +}; + +VkQueryPoolCreateInfo createInfo = { + .sType = VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO, + .pNext = &feedbackInfo, + .flags = 0, + .queryType = VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, + ... +}; + +vkCreateQueryPool(device, &createInfo, NULL, &queryPool); + +... +vkBeginCommandBuffer(commandBuffer, ...); +... +vkCmdBeginVideoCodingKHR(commandBuffer, ...); +... +vkCmdBeginQuery(commandBuffer, queryPool, 0, 0); +// Issue video encode operation +... +vkCmdEndQuery(commandBuffer, queryPool, 0); +... +vkCmdEndVideoCodingKHR(commandBuffer, ...); +... +vkEndCommandBuffer(commandBuffer); +... + +// We retrieve the captured feedback values as well as the status +struct { + uint32_t bitstreamBufferOffset; + uint32_t bitstreamBytesWritten; + VkQueryResultStatusKHR status; +} results; +vkGetQueryPoolResults(device, queryPool, 0, 1, + sizeof(results), &results, sizeof(results), + VK_QUERY_RESULT_WITH_STATUS_BIT_KHR); + +if (results.status == VK_QUERY_RESULT_STATUS_NOT_READY_KHR /* 0 */) { + // Query result not ready yet + ... +} else if (results.status > 0) { + // Video encode operation was successful, we can use bitstream feedback data + ... +} else if (results.status < 0) { + // Video encode operation was unsuccessful, feedback data is undefined + ... +} + +---- + + +=== Record encode operation (video session without DPB slots) + +[source,c] +---- +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +VkVideoPictureResourceInfoKHR encodeInputPictureResource = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PICTURE_RESOURCE_INFO_KHR, + .pNext = NULL, + .codedOffset = ... // offset within the image subresource (typically { 0, 0 }) + .codedExtent = ... // extent of encoded picture (typically the video frame size) + .baseArrayLayer = 0, + .imageViewBinding = inputImageView +}; + +VkVideoEncodeInfoKHR encodeInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR, + .pNext = ... // pointer to codec-specific picture information structure + .flags = 0, + .dstBuffer = bitstreamBuffer, + .dstBufferOffset = ... // offset where the encoded bitstream is written + .dstBufferRange = ... // maximum size in bytes of the written bitstream data + .srcPictureResource = encodeInputPictureResource, + .pSetupReferenceSlot = NULL, + .referenceSlotCount = 0, + .pReferenceSlots = NULL, + .precedingExternallyEncodedBytes = ... +}; + +vkCmdEncodeVideoKHR(commandBuffer, &encodeInfo); + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Record encode operation with reconstructed picture information + +[source,c] +---- +// Bound reference resource list provided has to include reconstructed picture resource +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +VkVideoPictureResourceInfoKHR encodeInputPictureResource = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PICTURE_RESOURCE_INFO_KHR, + .pNext = NULL, + .codedOffset = ... // offset within the image subresource (typically { 0, 0 }) + .codedExtent = ... // extent of encoded picture (typically the video frame size) + .baseArrayLayer = 0, + .imageViewBinding = inputImageView +}; + +VkVideoPictureResourceInfoKHR reconstructedPictureResource = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PICTURE_RESOURCE_INFO_KHR, + .pNext = NULL, + .codedOffset = ... // offset within the image subresource (typically { 0, 0 }) + .codedExtent = ... // extent of reconstructed picture (typically the video frame size) + .baseArrayLayer = ... // layer to use for setup picture in DPB + .imageViewBinding = dpbImageView +}; + +VkVideoReferenceSlotInfoKHR setupSlotInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = ... // pointer to codec-specific reconstructed picture information structure + .slotIndex = ... // DPB slot index to use with the reconstructed picture + // (optionally activated per the codec-specific semantics) + .pPictureResource = &reconstructedPictureResource +}; + +VkVideoEncodeInfoKHR encodeInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR, + .pNext = ... // pointer to codec-specific picture information structure + ... + .srcPictureResource = encodeInputPictureResource, + .pSetupReferenceSlot = &setupSlotInfo, + ... +}; + +vkCmdEncodeVideoKHR(commandBuffer, &encodeInfo); + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Record encode operation with reference picture list + +[source,c] +---- +// Bound reference resource list provided has to include all used reference picture resources +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +VkVideoPictureResourceInfoKHR referencePictureResources[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_PICTURE_RESOURCE_INFO_KHR, + .pNext = NULL, + .codedOffset = ... // offset within the image subresource (typically { 0, 0 }) + .codedExtent = ... // extent of reference picture (typically the video frame size) + .baseArrayLayer = ... // layer of first reference picture resource + .imageViewBinding = dpbImageView + }, + { + .sType = VK_STRUCTURE_TYPE_VIDEO_PICTURE_RESOURCE_INFO_KHR, + .pNext = NULL, + .codedOffset = ... // offset within the image subresource (typically { 0, 0 }) + .codedExtent = ... // extent of reference picture (typically the video frame size) + .baseArrayLayer = ... // layer of second reference picture resource + .imageViewBinding = dpbImageView + }, + ... +}; +// NOTE: Individual resources do not have to refer to the same image view, e.g. if different +// image views are created for each picture resource, or if the +// VK_VIDEO_CAPABILITY_SEPARATE_REFERENCE_IMAGES_BIT_KHR capability is supported and the +// application created separate images for the reference pictures. + +VkVideoReferenceSlotInfoKHR referenceSlotInfo[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = ... // pointer to codec-specific reference picture information structure + .slotIndex = ... // DPB slot index of the first reference picture + .pPictureResource = &referencePictureResource[0] + }, + { + .sType = VK_STRUCTURE_TYPE_VIDEO_REFERENCE_SLOT_INFO_KHR, + .pNext = ... // pointer to codec-specific reference picture information structure + .slotIndex = ... // DPB slot index of the second reference picture + .pPictureResource = &referencePictureResource[1] + }, + ... +}; + +VkVideoEncodeInfoKHR encodeInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_INFO_KHR, + .pNext = ... // pointer to codec-specific picture information structure + ... + .referenceSlotCount = sizeof(referenceSlotInfo) / sizeof(referenceSlotInfo[0]), + .pReferenceSlots = &referenceSlotInfo[0] +}; + +vkCmdEncodeVideoKHR(commandBuffer, &encodeInfo); + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Encode codec-specific parameters stored in video session parameters objects + +[source,c] +---- +VkVideoEncodeSessionParametersGetInfoKHR getInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_PARAMETERS_GET_INFO_KHR, + .pNext = ... // pointer to any codec-specific parameters, if needed + .videoSessionParameters = // video session parameters object to query +}; + +// VK_TRUE, if application prefers to encode the stored codec-specific parameters +// itself, if possible, VK_FALSE otherwise +VkBool32 preferApplicationParameterEncode = ...; + +VkBool32 parametersContainOverrides = VK_FALSE; + +if (preferApplicationParameterEncode) { + VkVideoEncodeSessionParametersFeedbackInfoKHR feedbackInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_SESSION_PARAMETERS_FEEDBACK_INFO_KHR, + .pNext = ... // pointer to any codec-specific feedback info, if needed + .hasOverrides = VK_FALSE; + }; + + vkGetEncodedVideoSessionParametersKHR(device, &getInfo, &feedbackInfo, NULL, NULL); + + parametersContainOverrides = feedbackInfo.hasOverrides; +} + +if (preferApplicationParameterEncode && !parametersContainOverrides) { + // Encode codec-specific parameters manually + ... +} else { + // Retrieve encoded codec-specific parameters from implementation + size_t dataSize = 0; + vkGetEncodedVideoSessionParametersKHR(device, &getInfo, NULL, &dataSize, NULL); + + // Pointer to CPU buffer with at least dataSize number of bytes of storage + // (allocate it on demand or use an existing pool used for bitstream storage) + void* data = ...; + vkGetEncodedVideoSessionParametersKHR(device, &getInfo, NULL, &dataSize, data); +} +---- + + +=== Change the rate control configuration of a video encode session + +[source,c] +---- +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +VkVideoEncodeRateControlLayerInfoKHR rateControlLayers[] = { + { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_LAYER_INFO_KHR, + .pNext = ... // pointer to optional codec-specific rate control layer configuration + .averageBitrate = 2000000, // 2 Mbps target bitrate + .maxBitrate = 5000000, // 5 Mbps peak bitrate + .frameRateNumerator = 30000, // 29.97 fps numerator + .frameRateDenominator = 1001 // 29.97 fps denominator + }, + ... +}; + +VkVideoEncodeRateControlInfoKHR rateControlInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_INFO_KHR, + .pNext = ... // pointer to optional codec-specific rate control configuration + .flags = 0, + .rateControlMode = VK_VIDEO_ENCODE_RATE_CONTROL_MODE_VBR_BIT_KHR, // variable bitrate mode + .layerCount = sizeof(rateControlLayers) / sizeof(rateControlLayers[0]), + .pLayers = rateControlLayers, + .virtualBufferSizeInMs = 2000, // virtual buffer size is 2 seconds + .initialVirtualBufferSizeInMs = 0 +}; + +// Change the rate control configuration for the video session +VkVideoCodingControlInfoKHR controlInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_CODING_CONTROL_INFO_KHR, + .pNext = &rateControlInfo, + .flags = VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR +}; + +vkCmdControlVideoCodingKHR(commandBuffer, &controlInfo); + +... + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Change the video encode quality level used by a video encode session + +[source,c] +---- +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +VkVideoEncodeQualityLevelInfoKHR qualityLevelInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR, + .pNext = NULL, + .qualityLevel = ... // the new quality level to set +}; + +VkVideoCodingControlInfoKHR controlInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_CODING_CONTROL_INFO_KHR, + .pNext = &qualityLevelInfo, + .flags = VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR +}; + +vkCmdControlVideoCodingKHR(commandBuffer, &controlInfo); + +... + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +=== Initialize a video encode session with a specific quality level and corresponding recommended rate control settings + +[source,c] +---- +// Construct the video encode profile with appropriate usage scenario information +// We also include the optional encode usage information here +VkVideoEncodeUsageInfoKHR profileUsageInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_USAGE_INFO_KHR, + .pNext = ... // pointer to codec-specific profile structure + .videoUsageHints = ... // usage hints + .videoContentHints = ... // content hints + .tuningMode = ... // tuning mode +}; + +VkVideoProfileInfoKHR profileInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_PROFILE_INFO_KHR, + .pNext = &profileUsageInfo, + ... +}; + +// Query the video encode profile capabilities to determine maxQualityLevels +VkVideoEncodeCapabilitiesKHR encodeCapabilities = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_CAPABILITIES_KHR, + .pNext = ... // pointer to codec-specific capability structure +} + +VkVideoCapabilitiesKHR capabilities = { + .sType = VK_STRUCTURE_TYPE_VIDEO_CAPABILITIES_KHR, + .pNext = &encodeCapabilities +}; + +result = vkGetPhysicalDeviceVideoCapabilitiesKHR(physicalDevice, &profileInfo, &capabilities); + +// Select a quality level to use between 0 and maxQualityLevels-1 +uint32_t selectedQualityLevel = selectQualityLevelFrom(0, encodeCapabilities.maxQualityLevels - 1); + +// Query recommended settings for the selected video encode quality level +VkPhysicalDeviceVideoEncodeQualityLevelInfoKHR qualityLevelInfo = { + .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR, + .pNext = NULL, + .pVideoProfile = &profileInfo, + .qualityLevel = selectedQualityLevel +}; + +VkVideoEncodeQualityLevelPropertiesKHR qualityLevelProps = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_PROPERTIES_KHR, + .pNext = ... // pointer to any codec-specific parameters, if needed +}; + +result = vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR(physicalDevice, &qualityLevelInfo, &qualityLevelProps); + +... + +// Video session parameters are always created with respect to the used +// video encode quality level, so create one accordingly +VkVideoEncodeQualityLevelInfoKHR paramsQualityLevelInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR, + .pNext = ... // pointer to codec-specific parameters creation information + .qualityLevel = selectedQualityLevel +}; + +VkVideoSessionParametersCreateInfoKHR paramsCreateInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_SESSION_PARAMETERS_CREATE_INFO_KHR, + .pNext = ¶msQualityLevelInfo, + ... +}; + +VkVideoSessionParametersKHR params = VK_NULL_HANDLE; +result = vkCreateVideoSessionParametersKHR(device, ¶msCreateInfo, NULL, ¶ms); + +... + +vkCmdBeginVideoCodingKHR(commandBuffer, ...); + +// Initialize the video session, set the quality level, and the +// recommended rate control configuration +// NOTE: The application can choose other rate control settings as the +// quality level properties only indicate preference, not a requirement + +// Include rate control information +VkVideoEncodeRateControlInfoKHR rateControlInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_RATE_CONTROL_INFO_KHR, + .pNext = ... // pointer to optional codec-specific rate control configuration + .flags = 0, + .rateControlMode = qualityLevelProps.preferredRateControlMode, + .layerCount = qualityLevelProps.preferredRateControlLayerCount, + ... +}; + +// Include quality level information +VkVideoEncodeQualityLevelInfoKHR qualityLevelInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_ENCODE_QUALITY_LEVEL_INFO_KHR, + .pNext = &rateControlInfo, + .qualityLevel = selectedQualityLevel +}; + +// Include all of the RESET, ENCODE_QUALITY_LEVEL, and RATE_CONTROL bits +// because in this example we do an initialization followed by an immediate +// update to the quality level and rate control states +VkVideoCodingControlInfoKHR controlInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_CODING_CONTROL_INFO_KHR, + .pNext = &qualityLevelInfo, + .flags = VK_VIDEO_CODING_CONTROL_RESET_BIT_KHR + | VK_VIDEO_CODING_CONTROL_ENCODE_QUALITY_LEVEL_BIT_KHR + | VK_VIDEO_CODING_CONTROL_ENCODE_RATE_CONTROL_BIT_KHR +}; + +vkCmdControlVideoCodingKHR(commandBuffer, &controlInfo); + +... + +vkCmdEndVideoCodingKHR(commandBuffer, ...); +---- + + +== Issues + +=== RESOLVED: Why is there no `VK_PIPELINE_STAGE_VIDEO_ENCODE_BIT_KHR`? + +This extension requires the `VK_KHR_synchronization2` extension because the new access flags introduced did not fit in the 32-bit enum `VkAccessFlagBits`. Accordingly, all new pipeline stage and access flags have been added to the corresponding 64-bit enums and no new flags have been added to the legacy 32-bit enums. While the new pipeline stage flag introduced uses bit #27 which would also fit in the legacy `VkPipelineStageFlagBits` enum, there is no real benefit to include it. Instead the bit is marked reserved. + + +=== RESOLVED: How can layered codec-specific encode extensions enable applications to provide the necessary codec-specific picture information, parameter sets, etc. that may be needed to perform the video coding operations? + +There are multiple points where codec-specific picture information can be provided to a video encode operation. This extension suggests the following convention: + + * Codec-specific encode parameters are expected to be provided in the `pNext` chain of `VkVideoEncodeInfoKHR`. + * Codec-specific reconstructed picture information is expected to be provided in the `pNext` chain of `VkVideoEncodeInfoKHR::pSetupReferenceSlot`. + * Codec-specific reference picture information is expected to be provided in the `pNext` chain of the elements of the `VkVideoEncodeInfoKHR::pReferenceSlots` array. + + +=== RESOLVED: Can `vkCmdVideoEncodeKHR` only encode frames? What about field encoding, slice encoding, etc.? + +This extension does not define the types of pictures or sub-picture content that can be encoded by a `vkCmdVideoEncodeKHR` command. It is expected that the codec-specific encode extensions built upon this extension define the types of pictures that can be encoded. Furthermore, both codec-specific and codec-independent extensions can expand the set of capabilities introduced here to enable more advanced use cases, as needed. + + +=== RESOLVED: What is the effect of the flags provided in `VkVideoEncodeUsageInfoKHR::videoUsageHints` and `VkVideoEncodeUsageInfoKHR::videoContentHints`? + +There are no specific behavioral effects associated with any of the video encode usage and content hints, so the application can specify any combination of these flags. They are included to enable the application to better communicate the intended use case scenario to the implementation. + +However, just like any other additional video profile information included in the `pNext` chain of `VkVideoProfileInfoKHR` structures, they are part of the video profile definition, hence whenever matching video profiles have to be provided to an API call, be that queries or resource creation structures, the application must provide identical video encode usage and content hint values. This also applies if the application does not include the `VkVideoEncodeUsageInfoKHR` structure, which is treated equivalently to specifying the structure with `videoUsageHints`, `videoContentHints`, and `tuningMode` equal to `VK_VIDEO_ENCODE_USAGE_DEFAULT_KHR`, `VK_VIDEO_ENCODE_CONTENT_DEFAULT_KHR`, and `VK_VIDEO_ENCODE_TUNING_MODE_DEFAULT_KHR` (or zero), respectively, per the usual conventions of Vulkan. + + +=== RESOLVED: What is the effect of the tuning mode provided in `VkVideoEncodeUsageInfoKHR::tuningMode`? + +Unlike the other fields in `VkVideoEncodeUsageInfoKHR`, the tuning mode affects the behavior of video session objects created using them. Different tuning modes may put the hardware in a different mode of operation tuned for the particular use case with significantly different capabilities, as well as quality and performance characteristics. + + +=== RESOLVED: How should we expose video encoding feedback values (e.g. encoded bitstream size)? + +Through a new query type. We follow the model of pipeline statistics queries to enable adding additional feedback values to the query thus this extension introduces a new `VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR` query type with the ability to get feedback about the offset and size of the bitstream data produced by video encode operations (amongst other feedback values). We expect that in the future video decode operations will need to support similar feedback values thus a similar query type for video decode operations can be introduced by another extension. + + +=== RESOLVED: Do result status queries need to be used in conjunction with video encode feedback queries? + +No, in fact only a single query can ever be active within a video coding scope, hence executing a result status query as well as a video encode feedback query for the same video encode operation is not possible. Though it is also not needed, as all query types allow returning a result status, just like availability status. Thus, in practice, result status queries are only needed to be used when no other query type is supported in the particular context, and in case of video encoding applications are expected to only use video encode feedback queries within a video coding scope. + + +=== RESOLVED: Why is there a need to allow implementations to override codec-specific parameters? + +As described in the corresponding section earlier, encoder implementations usually only support a subset of the available encoding tools defined by the corresponding video compression standards and enumerating exhaustively all of these constraints would be impractical and could result in a combinatorial explosion of codec-specific capabilities. Instead, this proposal allows implementations to override any codec-specific parameter values or combinations thereof, so that the resulting parameters comply to the constraints of the target implementation. + +Some other video encode APIs do not support implementation overrides, but the drawback of that choice is that implementations may not be able to expose a potentially large set of their encoding tools just because they do not comply to the exact wording of the capabilities defined by these APIs, so this proposal chose to maximize the exposed capabilities instead. + +Such minimal and necessary implementation overrides are expected to be applied only when they are absolutely paramount for the correct functioning of the underlying encoder hardware. Additional, optimizing overrides can be, however, explicitly enabled by the application using the `VK_VIDEO_SESSION_CREATE_ALLOW_ENCODE_PARAMETER_OPTIMIZATIONS_BIT_KHR` video session creation flag. + + +=== RESOLVED: Can the application disable all implementation overrides? + +No. Without the ability to override codec-specific parameters, as necessitated by the constraints of the target implementation, the implementation may not be able to guarantee that the generated bitstreams will be compliant to the video compression standard in question. + +Accordingly, if the API would allow the application to disable all implementation overrides, that would, for all practical purposes, be equivalent to a flag enabling undefined behavior from the perspective of video compression standard compliance. + +For the same reason, if the application chooses to encode codec-specific parameters stored in video session parameters object on its own, indifferent of whether the implementation had to apply overrides to those, as reported by `vkGetEncodedVideoSessionParametersKHR`, it risks the final bitstream to be non-compliant. + +Applications seeking to only accept bitstreams produced exactly according to the codec-specific parameters they requested can choose to treat the presence of any overrides as an encoding error. + + +=== RESOLVED: Can implementations override any codec-specific parameter? + +No. First, there are a set of rules that implementations have to comply to when applying any parameter overrides, as defined in detail in the specification. In addition, codec-specific extensions layered on top of this proposal can define their own restrictions about what parameters can implementations override. In practice, it is expected that certain codec-specific parameters that affect the overall behavior of the encoder and that could have an impact on any additional bitstream elements that need to be encoded by the application will never be overridden by the implementation, and thus will be excluded from the set of overridable parameters in the corresponding codec-specific extension. + +Over time, it is expected that the set of these guarantees will grow (e.g. by exposing additional capabilities) according to the needs of encoder applications. + + +=== RESOLVED: Do all implementations have to implement the same rate control algorithms corresponding to the rate control modes defined by this proposal? + +No. While the high-level rate control modes (CBR and VBR) defined by this proposal are fairly universal, each rate control mode can be implemented in many different ways while still complying to the fundamental model of the mode itself. In practice, the rate control algorithms employed by implementations significantly differ. + +Accordingly, this proposal does not try to describe any specific rate control algorithm for any of the rate control modes introduced, rather it provides a high-level description of the modes and the underlying leaky bucket model used by them. + +The only case where the effects of rate control are defined exactly is when rate control is disabled (using `VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DISABLED_BIT_KHR`), where implementations must encode the pictures exactly per the application-specified codec-specific quantization parameters. + + +=== RESOLVED: Do rate control implementations guarantee to respect the average/max bitrates, or frame sizes configured for the video session? + +Unfortunately, implementations cannot provide hard guarantees about always respecting these rate control parameters, as the ability to conform to these is affected by the input content, the encoder tools of the video compression standard or the implementation, including the contents of future pictures, which implementations cannot make predictions about. + +However, for all practical purposes, these rate control parameters are expected to be respected when the application chooses them in a way that is in line with the encoded content and the characteristics of the used video compression standard. + + +=== RESOLVED: Are video session parameters objects dependent on the used video encode quality level? + +Some implementations may support different hardware modes that are enabled in response to the used video encode quality level. This may also have an effect on the constraints related to the available encoding tools and as such may also affect the necessary codec-specific parameter overrides the implementation has to apply. As video session parameters objects are expected to store the already overridden codec-specific parameters typically in an encoded or otherwise optimized format, using a video session parameters object with any video encode quality level would require implementations to also store the original parameters in order to be able to re-encode them according to the needs of the target video encode quality level, which would partially defeat the purpose of video session parameters object. + +Instead, this proposal defines video session parameters objects to be created with respect to a specific video encode quality level (when using a video encode profile) and applications have to make sure that they use a compatible video session parameters object in their encode commands according to the current quality level state of the video session. + +In practice, this should not have any effect on most encoder applications, as usually they use a single video encode quality level throughout the lifetime of the video session, so the additional complexity resulting from this specialization will only affect advanced applications that may need to operate using different video encode quality levels within a single video stream. + + +=== RESOLVED: Are video encode quality levels and rate control mutually exclusive? + +No, they are completely orthogonal, as they control different aspects of the encoder, and they are both always in effect all the time. There is always a currently active video encode quality level and rate control state, which default to quality level zero and implementation-specific rate control state, respectively, when the video encode session is initialized. The used video encode quality level and the rate control settings can be updated subsequently, potentially independently, or together with initialization per the application's needs. The only relation between video encode quality levels and rate control is that the application can query for each video encode profile and video encode quality level the implementation recommended settings (using `vkGetPhysicalDeviceVideoEncodeQualityLevelPropertiesKHR`) that are best suited for the selected quality level and the usage scenario information included in the video encode profile. These include recommendations on the rate control mode to use amongst other codec-independent and codec-specific suggestions. Nonetheless, these are only recommendations and the application can diverge from these if deemed necessary. + + +=== RESOLVED: Does specifying `VkVideoEncodeRateControlInfoKHR` in the `pNext` chain of the `pBeginCodingInfo` parameter of `vkCmdBeginVideoCodingKHR` change the current rate control configuration? + +No. The rate control information specified to `vkCmdBeginVideoCodingKHR` does not change the state of the video session, it is only expected to specify the current rate control configuration (previously already set through the execution of an appropriate `vkCmdControlVideoCodingKHR` command). This information is needed by some implementations in order to be aware of the current rate control configuration of the video session while recording commands, as some of the rate control state may affect the recorded device commands. When this information is not specified, the implementation will assume that the current rate control mode is set to `VK_VIDEO_ENCODE_RATE_CONTROL_MODE_DEFAULT_KHR`. + +The validation layers are expected to detect at command buffer submission time if there is any mismatch between the expected rate control configuration specified to the `vkCmdBeginVideoCodingKHR` command and the actual rate control configuration of the video session at the time the video coding scope is started on the device timeline. If these two sets of state do not match, then the behavior of the implementations is undefined and may result in any sort of misbehavior permitted by the Vulkan specification when valid usage conditions are not met. Accordingly, applications have to make sure to track and specify the expected rate control configuration at the beginning of every video coding scope performing video encode operations in order to attain correct encoder behavior. + + +=== RESOLVED: When is it mandatory to specify reconstructed picture information in `VkVideoEncodeInfoKHR::pSetupReferenceSlot`? + +In line with the `VK_KHR_video_decode_queue` extension, due to foreseeable implementation limitations that may require the presence of a reconstructed picture resource and/or DPB slot for encoding, revision 12 of this extension changed the requirements on reconstructed picture information as follows: + + 1. Specifying reconstructed picture information (i.e. a non-`NULL` `pSetupReferenceSlot`) is made mandatory for all cases except when the video session was created with no DPB slots + 2. Reference picture setup (and, inherently, DPB slot activation) was changed to be subject to codec-specific behavior, meaning that specifying a non-`NULL` `pSetupReferenceSlot` will only trigger reference picture setup if the appropriate codec-specific parameters or semantics indicate so (typically in the form of marking the encoded picture as reference) + +As some implementations may use the reconstructed picture resource and/or DPB slot as transient storage during the decoding process, if a non-`NULL` `pSetupReferenceSlot` is specified but no reference picture setup is requested, then the contents of the reconstructed picture resource become undefined and some of the picture references associated with the reconstructed picture's DPB slot may get invalidated. + + +== Further Functionality + +This extension is meant to provide only common video encode functionality, thus support for individual video encode profiles using specific video compression standards is left for extensions layered on top of the infrastructure provided here. + +Currently the following layered extensions are available: + + * `VK_KHR_video_encode_h264` - adds support for encoding H.264/AVC video sequences + * `VK_KHR_video_encode_h265` - adds support for encoding H.265/HEVC video sequences diff --git a/proposals/VK_KHR_video_maintenance1.adoc b/proposals/VK_KHR_video_maintenance1.adoc new file mode 100644 index 000000000..2e8b34e0f --- /dev/null +++ b/proposals/VK_KHR_video_maintenance1.adoc @@ -0,0 +1,200 @@ +// Copyright 2023-2023 The Khronos Group Inc. +// +// SPDX-License-Identifier: CC-BY-4.0 + += VK_KHR_video_maintenance1 +:toc: left +:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ +:sectnums: + +This proposal details and addresses the issues solved by the `VK_KHR_video_maintenance1` extension. + +== Problem Statement + +Over time, a collection of minor features, none of which would warrant an entire extension of their own, and some of which have been identified after the final version of the first set of video coding extensions were released, justified the creation of a video maintenance extension: + +The following is a list of issues considered in this proposal: + + * Relax the requirement for the application having to specify video profiles when creating buffer or image resources with video usage + * Simplify how queries work in video coding + + +== Solution Space + +=== Relaxed video profile compatibility + +For buffers and images used in video coding, it is currently required that applications have to specify all video profiles which these resources will be used with. In case of video decoding, this requirement is not too limiting. However, in transcoding use cases it is very common for the application to not have a full list up-front of all possible video encode profiles the resources will be intended to be used with which may limit the application's ability to reuse the decode output picture resources directly as the encode input picture resources. + +The motivation behind requiring the specification of all video profiles the created resources are planned to be used with is that knowing that information up-front enables implementations to use the optimal representation option when multiple choices may be available. In particular, image resources may be optimized both from memory usage and memory layout perspective specifically for that explicit list of video profiles, while not having that information available may result in representations that require worst case memory storage that may also suffer from suboptimal access performance. + +The following two main options have been considered to address this issue: + + 1. Allow opting in to exclude certain subsets of video profile parameters from the video profile compatibility criteria + 2. Allow creating resources in an entirely video profile independent fashion + +Option 1 is problematic, because one would either have to draw an arbitrary line between parameters affecting the video profile compatibility criteria vs those which do not, or there would be a need to introduce multiple options and complex compatibility rules to allow more flexibility. + +In practice, most of the benefits of knowing the video profiles up-front are only important for DPB images, which are not expected to be shared between video sessions using different video profiles anyway, hence this extension follows option 2 with the restriction that image resources with only DPB video usage cannot be created as video profile independent resources. + +Nonetheless, while this extension enables creating video profile independent buffers with video usage, and creating video profile independent images with video decode output or video encode input usage, applications that do know the set of video profiles up-front should still prefer specifying those instead of creating video profile independent resources, as that may still provide some performance or memory usage benefits on certain implementations. + +=== Simplified video queries + +Currently, queries performed in video coding scopes use the same scoped `vkCmdBegin/EndQuery` commands, as the ones used in the vast majority of the cases across the Vulkan API, with the notable exception timestamp queries and some ray tracing related queries. + +This poses some problems in the context of video coding for the following reasons: + + * Query slots are consumed and query results are produced on a per video coding operation basis. While a scoped query is a good fit for queries that collect statistics over multiple commands (like occlusion queries and pipeline statistics queries), scoped queries are not a good fit for video coding operations as they allow for command sequences that are invalid (like recording multiple video coding operations within the scope of a query) or simply useless (like recording a `vkCmdBegin/EndQuery` command pair without issuing any video coding operations in between) + * This would only get more complicated if future video coding functionality would introduce the ability to issue multiple video coding operations through the recording of a single video coding command, and thus would need to consume more than a single query slot, as there are no variants of the `vkCmdBegin/EndQuery` commands that allow running more than one query within a scope (excluding the awkward corner case of query behavior with multiview rendering) + * In addition, as in practice the scope of video queries will only ever span a single video coding command, the additional overhead of calling the `vkCmdBegin/EndQuery` commands before/after the video coding command which the query will apply to is simply wasteful + +The straightforward answer to these problems is to provide the query information directly to the video coding command it applies to. Considering that some ray tracing related queries already follow this model, such an API change would not create a new precedence either. + +The following options have been considered to define the interaction between `vkCmdBegin/EndQuery`-style scoped queries and the newly introduced inline queries: + + 1. Only allow inline queries when the features of this extension are enabled + 2. Allow mixing scoped queries and inline queries + 3. Make the use of scoped queries and inline queries mutually exclusive within a video coding scope + 4. Make the use of scoped queries and inline queries mutually exclusive on a per video session basis + +The problem with option 1 is that it could cause backward-compatibility issues for any legacy content that may automatically enable all features available on the implementation. + +Option 2 is the most flexible, but it would add a lot of unnecessary complexity to implementations. + +Between option 3 and 4, the only difference is the granularity at which the application has to choose between the use of scoped queries and inline queries. However, as in practice it is highly unlikely for an application to mix the two forms of queries, option 4 is preferred due to its simplicity. + +Going forward, applications should prefer to use inline queries, when available, as support for using scoped video queries is unlikely to be extended to be compatible with any future video coding functionalities that may require the use of multiple query slots. + + +== Proposal + +Items introduced by this extension are: + +=== Video profile independent buffer creation + +The new `VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR` buffer creation flag enables creating buffers that can be used in video coding operations, independent of the used video profile. + +=== Video profile independent image creation + +The new `VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR` image creation flag enables creating images (except for DPB-only video usage) that can be used in video coding operations, independent of the used video profile. + +=== Inline video queries + +When creating a video session with the new `VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR` flag, instead of using the `vkCmdBegin/EndQuery` commands, applications can issue queries inline with the video coding commands themselves by chaining the following new structure to the `pNext` chain of the corresponding video coding command's input parameter structure (e.g. to `VkVideoDecodeInfoKHR` or `VkVideoEncodeInfoKHR`): + +[source,c] +---- +typedef struct VkVideoInlineQueryInfoKHR { + VkStructureType sType; + const void* pNext; + VkQueryPool queryPool; + uint32_t firstQuery; + uint32_t queryCount; +} VkVideoInlineQueryInfoKHR; +---- + +== Examples + +=== Create video profile independent bitstream buffer + +[source,c] +---- +VkBuffer buffer = VK_NULL_HANDLE; + +VkBufferCreateInfo createInfo = { + .sType = VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO, + .pNext = NULL, // No need to specify video profile list + .flags = VK_BUFFER_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, + ... // buffer creation parameters including one or more video-specific usage flags +}; + +vkCreateBuffer(device, &createInfo, NULL, &buffer); +---- + + +=== Create video profile independent image backing video picture resources + +[source,c] +---- +VkImage image = VK_NULL_HANDLE; + +VkImageCreateInfo imageCreateInfo = { + .sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO, + .pNext = NULL, // No need to specify video profile list + .flags = VK_IMAGE_CREATE_VIDEO_PROFILE_INDEPENDENT_BIT_KHR, + ... // image creation parameters including one or more video-specific usage flags + // NOTE: usage must not contain DPB use as the only video-specific usage flag +}; + +vkCreateImage(device, &imageCreateInfo, NULL, &image); +---- + + +=== Using inline queries with a video session + +[source,c] +---- +// Create video session with inline query support +VkVideoSessionKHR videoSession = VK_NULL_HANDLE; + +VkVideoSessionCreateInfoKHR createInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_SESSION_CREATE_INFO_KHR, + .pNext = NULL, + .queueFamilyIndex = ... // index of queue family that supports the video codec operation + .flags = VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR, // opt-in to use inline queries + ... +}; + +vkCreateVideoSessionKHR(device, &createInfo, NULL, &videoSession); + +// Create query pool as usual +VkQueryPool queryPool = VK_NULL_HANDLE; + +VkVideoProfileInfoKHR profileInfo = { + ... +}; + +VkQueryPoolCreateInfo createInfo = { + .sType = VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO, + .pNext = &profileInfo, + ... +}; + +vkCreateQueryPool(device, &createInfo, NULL, &queryPool); + +... +vkBeginCommandBuffer(commandBuffer, ...); +... +vkCmdBeginVideoCodingKHR(commandBuffer, ...); +... + +// Execute single query inline with a video codec operation +VkVideoInlineQueryInfoKHR inlineQueryInfo = { + .sType = VK_STRUCTURE_TYPE_VIDEO_INLINE_QUERY_INFO_KHR, + .pNext = NULL, + .queryPool = queryPool, + .firstQuery = 0, + .queryCount = 1 +}; + +// Include inlineQueryInfo in the pNext chain of the video codec command parameters +// (e.g. VkVideoDecodeInfoKHR or VkVideoEncodeInfoKHR). + +// Issue video coding operation + +... +vkCmdEndVideoCodingKHR(commandBuffer, ...); +... +vkEndCommandBuffer(commandBuffer); +... +---- + + +== Issues + +None. + + +== Further Functionality + +None. diff --git a/proposals/VK_KHR_video_queue.adoc b/proposals/VK_KHR_video_queue.adoc index 2fd4e9a56..77b946655 100644 --- a/proposals/VK_KHR_video_queue.adoc +++ b/proposals/VK_KHR_video_queue.adoc @@ -21,7 +21,7 @@ Integrating video coding operations into Vulkan applications enable a wide set o It is also not uncommon for Vulkan capable devices to feature dedicated hardware acceleration for video compression and decompression. -The goal of this proposal is to enable these use cases, allow exposing the underlying hardware capabilities, and provide tight integration with other functionalities of the Vulkan API. +The goal of this proposal is to enable these use cases, expose the underlying hardware capabilities, and provide tight integration with other functionalities of the Vulkan API. == Solution Space @@ -729,7 +729,7 @@ VkVideoSessionCreateInfoKHR createInfo = { .pStdHeaderVersion = ... // pointer to the video std header information (typically the same as reported in the capabilities) }; -vkCreateVideoSession(device, &createInfo, NULL, &videoSession); +vkCreateVideoSessionKHR(device, &createInfo, NULL, &videoSession); ---- @@ -1069,6 +1069,6 @@ Currently the following layered extensions are available: * `VK_KHR_video_decode_queue` - adds general support for video decode operations * `VK_KHR_video_decode_h264` - adds support for decoding H.264/AVC video sequences * `VK_KHR_video_decode_h265` - adds support for decoding H.265/HEVC video sequences - * `VK_KHR_video_encode_queue` (provisional) - adds general support for video encode operations - * `VK_EXT_video_encode_h264` (provisional) - adds support for encoding H.264/AVC video sequences - * `VK_EXT_video_encode_h265` (provisional) - adds support for encoding H.265/HEVC video sequences + * `VK_KHR_video_encode_queue` - adds general support for video encode operations + * `VK_KHR_video_encode_h264` - adds support for encoding H.264/AVC video sequences + * `VK_KHR_video_encode_h265` - adds support for encoding H.265/HEVC video sequences diff --git a/scripts/genvk.py b/scripts/genvk.py index 676c78c4f..c1e9da65b 100755 --- a/scripts/genvk.py +++ b/scripts/genvk.py @@ -413,9 +413,6 @@ def makeGenOpts(args): # the extension blocks. betaRequireExtensions = [ 'VK_KHR_portability_subset', - 'VK_KHR_video_encode_queue', - 'VK_EXT_video_encode_h264', - 'VK_EXT_video_encode_h265', 'VK_NV_displacement_micromap', 'VK_AMDX_shader_enqueue', ] diff --git a/scripts/xml_consistency.py b/scripts/xml_consistency.py index 889bc9a85..e52f5e4f8 100755 --- a/scripts/xml_consistency.py +++ b/scripts/xml_consistency.py @@ -35,8 +35,8 @@ 'VK_EXT_shader_image_atomic_int64', 'VK_KHR_video_decode_h264', 'VK_KHR_video_decode_h265', - 'VK_EXT_video_encode_h264', - 'VK_EXT_video_encode_h265', + 'VK_KHR_video_encode_h264', + 'VK_KHR_video_encode_h265', 'VK_KHR_external_fence_win32', 'VK_KHR_external_memory_win32', 'VK_KHR_external_semaphore_win32', diff --git a/vkspec.adoc b/vkspec.adoc index cb5b3acf6..c19ae54a9 100644 --- a/vkspec.adoc +++ b/vkspec.adoc @@ -181,9 +181,9 @@ ifdef::VK_NV_memory_decompression[] include::{chapters}/VK_NV_memory_decompression.adoc[] endif::VK_NV_memory_decompression[] -// Vulkan Video extensions +// Video Coding ifdef::VK_KHR_video_queue[] -include::{chapters}/video_extensions.adoc[] +include::{chapters}/videocoding.adoc[] endif::VK_KHR_video_queue[] ifdef::VK_NV_optical_flow[] diff --git a/xml/video.xml b/xml/video.xml index a7e66dbe8..cf5d318da 100644 --- a/xml/video.xml +++ b/xml/video.xml @@ -38,16 +38,16 @@ The current public version of video.xml is maintained in the default branch #define VK_STD_VULKAN_VIDEO_CODEC_H264_DECODE_API_VERSION_1_0_0 VK_MAKE_VIDEO_STD_VERSION(1, 0, 0) - // Vulkan 0.9 provisional Vulkan video H.264 encode std specification version number -#define VK_STD_VULKAN_VIDEO_CODEC_H264_ENCODE_API_VERSION_0_9_11 VK_MAKE_VIDEO_STD_VERSION(0, 9, 11) + +#define VK_STD_VULKAN_VIDEO_CODEC_H264_ENCODE_API_VERSION_1_0_0 VK_MAKE_VIDEO_STD_VERSION(1, 0, 0) #define VK_STD_VULKAN_VIDEO_CODEC_H265_DECODE_API_VERSION_1_0_0 VK_MAKE_VIDEO_STD_VERSION(1, 0, 0) - // Vulkan 0.9 provisional Vulkan video H.265 encode std specification version number -#define VK_STD_VULKAN_VIDEO_CODEC_H265_ENCODE_API_VERSION_0_9_12 VK_MAKE_VIDEO_STD_VERSION(0, 9, 12) + +#define VK_STD_VULKAN_VIDEO_CODEC_H265_ENCODE_API_VERSION_1_0_0 VK_MAKE_VIDEO_STD_VERSION(1, 0, 0) @@ -1104,8 +1104,8 @@ The current public version of video.xml is maintained in the default branch - - + + @@ -1197,8 +1197,8 @@ The current public version of video.xml is maintained in the default branch - - + + diff --git a/xml/vk.xml b/xml/vk.xml index e6e4f33ff..d19aba5d8 100644 --- a/xml/vk.xml +++ b/xml/vk.xml @@ -175,7 +175,7 @@ branch of the member gitlab server. #define VKSC_API_VERSION_1_0 VK_MAKE_API_VERSION(VKSC_API_VARIANT, 1, 0, 0)// Patch version should always be set to 0 // Version of this file -#define VK_HEADER_VERSION 273 +#define VK_HEADER_VERSION 274 // Complete version of this file #define VK_HEADER_VERSION_COMPLETE VK_MAKE_API_VERSION(0, 1, 3, VK_HEADER_VERSION) // Version of this file @@ -513,16 +513,16 @@ typedef void* MTLSharedEvent_id; typedef VkFlags VkVideoComponentBitDepthFlagsKHR; Video Encode H.264 extension - typedef VkFlags VkVideoEncodeH264CapabilityFlagsEXT; - typedef VkFlags VkVideoEncodeH264StdFlagsEXT; - typedef VkFlags VkVideoEncodeH264RateControlFlagsEXT; + typedef VkFlags VkVideoEncodeH264CapabilityFlagsKHR; + typedef VkFlags VkVideoEncodeH264StdFlagsKHR; + typedef VkFlags VkVideoEncodeH264RateControlFlagsKHR; Video Encode H.265 extension - typedef VkFlags VkVideoEncodeH265CapabilityFlagsEXT; - typedef VkFlags VkVideoEncodeH265StdFlagsEXT; - typedef VkFlags VkVideoEncodeH265RateControlFlagsEXT; - typedef VkFlags VkVideoEncodeH265CtbSizeFlagsEXT; - typedef VkFlags VkVideoEncodeH265TransformBlockSizeFlagsEXT; + typedef VkFlags VkVideoEncodeH265CapabilityFlagsKHR; + typedef VkFlags VkVideoEncodeH265StdFlagsKHR; + typedef VkFlags VkVideoEncodeH265RateControlFlagsKHR; + typedef VkFlags VkVideoEncodeH265CtbSizeFlagsKHR; + typedef VkFlags VkVideoEncodeH265TransformBlockSizeFlagsKHR; Types which can be void pointers or class pointers, selected at compile time VK_DEFINE_HANDLE(VkInstance) @@ -907,16 +907,16 @@ typedef void* MTLSharedEvent_id; Video H.264 Encode extensions - - - + + + Video H.265 Encode extensions - - - - - + + + + + The PFN_vk*Function types are used by VkAllocationCallbacks below typedef void (VKAPI_PTR *PFN_vkInternalAllocationNotification)( @@ -1596,7 +1596,7 @@ typedef void* MTLSharedEvent_id; VkStructureType sType const void* pNext - VkPipelineCreateFlags flagsPipeline creation flags + VkPipelineCreateFlags flagsPipeline creation flags uint32_t stageCount const VkPipelineShaderStageCreateInfo* pStagesOne entry for each active shader stage const VkPipelineShaderStageCreateInfo* pStagesOne entry for each active shader stage @@ -1660,7 +1660,7 @@ typedef void* MTLSharedEvent_id; uint32_t offsetStart of the range, in bytes uint32_t sizeSize of the range, in bytes - + VkStructureType sType const void* pNext VkPipelineLayoutCreateFlags flags @@ -3718,6 +3718,18 @@ typedef void* MTLSharedEvent_id; VkBool32 nonStrictSinglePixelWideLinesUseParallelogram VkBool32 nonStrictWideLinesUseParallelogram + + VkStructureType sType + void* pNext + VkBool32 maintenance6 + + + VkStructureType sType + void* pNext + VkBool32 blockTexelViewCompatibleMultipleLayers + uint32_t maxCombinedImageSamplerDescriptorCount + VkBool32 fragmentShadingRateClampCombinerInputs + VkStructureType sType const void* pNext @@ -6020,11 +6032,11 @@ typedef void* MTLSharedEvent_id; VkStructureType sType void*pNext VkBool32 clustercullingShader - VkBool32 multiviewClusterCullingShader + VkBool32 multiviewClusterCullingShader - VkStructureType sType - void*pNext + VkStructureType sType + void*pNext VkBool32 clusterShadingRate @@ -6706,6 +6718,18 @@ typedef void* MTLSharedEvent_id; const VkVideoReferenceSlotInfoKHR* pSetupReferenceSlot uint32_t referenceSlotCount const VkVideoReferenceSlotInfoKHR* pReferenceSlots + + + VkStructureType sType + void* pNext + VkBool32 videoMaintenance1 + + + VkStructureType sType + const void* pNext + VkQueryPool queryPool + uint32_t firstQuery + uint32_t queryCount Video Decode Codec Standard specific structures #include "vk_video/vulkan_video_codec_h264std.h" @@ -6889,7 +6913,7 @@ typedef void* MTLSharedEvent_id; VkStructureType sType const void* pNext - VkVideoCodingControlFlagsKHR flags + VkVideoCodingControlFlagsKHR flags VkStructureType sType @@ -6962,10 +6986,10 @@ typedef void* MTLSharedEvent_id; VkExtent2D encodeInputPictureGranularity VkVideoEncodeFeedbackFlagsKHR supportedEncodeFeedbackFlags - - VkStructureType sType + + VkStructureType sType void* pNext - VkVideoEncodeH264CapabilityFlagsEXT flags + VkVideoEncodeH264CapabilityFlagsKHR flags StdVideoH264LevelIdc maxLevelIdc uint32_t maxSliceCount uint32_t maxPPictureL0ReferenceCount @@ -6977,17 +7001,17 @@ typedef void* MTLSharedEvent_id; int32_t maxQp VkBool32 prefersGopRemainingFrames VkBool32 requiresGopRemainingFrames - VkVideoEncodeH264StdFlagsEXT stdSyntaxFlags + VkVideoEncodeH264StdFlagsKHR stdSyntaxFlags - - VkStructureType sType + + VkStructureType sType void* pNext - VkVideoEncodeH264RateControlFlagsEXT preferredRateControlFlags + VkVideoEncodeH264RateControlFlagsKHR preferredRateControlFlags uint32_t preferredGopFrameCount uint32_t preferredIdrPeriod uint32_t preferredConsecutiveBFrameCount uint32_t preferredTemporalLayerCount - VkVideoEncodeH264QpEXT preferredConstantQp + VkVideoEncodeH264QpKHR preferredConstantQp uint32_t preferredMaxL0ReferenceCount uint32_t preferredMaxL1ReferenceCount VkBool32 preferredStdEntropyCodingModeFlag @@ -7003,111 +7027,111 @@ typedef void* MTLSharedEvent_id; - - VkStructureType sType + + VkStructureType sType const void* pNext VkBool32 useMaxLevelIdc StdVideoH264LevelIdc maxLevelIdc - - VkStructureType sType + + VkStructureType sType const void* pNext uint32_t stdSPSCount const StdVideoH264SequenceParameterSet* pStdSPSs uint32_t stdPPSCount const StdVideoH264PictureParameterSet* pStdPPSsList of Picture Parameters associated with the spsStd, above - - VkStructureType sType + + VkStructureType sType const void* pNext uint32_t maxStdSPSCount uint32_t maxStdPPSCount - const VkVideoEncodeH264SessionParametersAddInfoEXT* pParametersAddInfo + const VkVideoEncodeH264SessionParametersAddInfoKHR* pParametersAddInfo - - VkStructureType sType + + VkStructureType sType const void* pNext VkBool32 writeStdSPS VkBool32 writeStdPPS uint32_t stdSPSId uint32_t stdPPSId - - VkStructureType sType + + VkStructureType sType void* pNext VkBool32 hasStdSPSOverrides VkBool32 hasStdPPSOverrides - - VkStructureType sType + + VkStructureType sType const void* pNext const StdVideoEncodeH264ReferenceInfo* pStdReferenceInfo - - VkStructureType sType + + VkStructureType sType const void* pNext uint32_t naluSliceEntryCount - const VkVideoEncodeH264NaluSliceInfoEXT* pNaluSliceEntries + const VkVideoEncodeH264NaluSliceInfoKHR* pNaluSliceEntries const StdVideoEncodeH264PictureInfo* pStdPictureInfo VkBool32 generatePrefixNalu - - VkStructureType sType + + VkStructureType sType const void* pNext StdVideoH264ProfileIdc stdProfileIdc - - VkStructureType sType + + VkStructureType sType const void* pNext int32_t constantQp const StdVideoEncodeH264SliceHeader* pStdSliceHeader - - VkStructureType sType + + VkStructureType sType const void* pNext - VkVideoEncodeH264RateControlFlagsEXT flags + VkVideoEncodeH264RateControlFlagsKHR flags uint32_t gopFrameCount uint32_t idrPeriod uint32_t consecutiveBFrameCount uint32_t temporalLayerCount - + int32_t qpI int32_t qpP int32_t qpB - + uint32_t frameISize uint32_t framePSize uint32_t frameBSize - - VkStructureType sType + + VkStructureType sType const void* pNext VkBool32 useGopRemainingFrames uint32_t gopRemainingI uint32_t gopRemainingP uint32_t gopRemainingB - - VkStructureType sType + + VkStructureType sType const void* pNext VkBool32 useMinQp - VkVideoEncodeH264QpEXT minQp + VkVideoEncodeH264QpKHR minQp VkBool32 useMaxQp - VkVideoEncodeH264QpEXT maxQp + VkVideoEncodeH264QpKHR maxQp VkBool32 useMaxFrameSize - VkVideoEncodeH264FrameSizeEXT maxFrameSize + VkVideoEncodeH264FrameSizeKHR maxFrameSize - - VkStructureType sType + + VkStructureType sType void* pNext - VkVideoEncodeH265CapabilityFlagsEXT flags + VkVideoEncodeH265CapabilityFlagsKHR flags StdVideoH265LevelIdc maxLevelIdc uint32_t maxSliceSegmentCount VkExtent2D maxTiles - VkVideoEncodeH265CtbSizeFlagsEXT ctbSizes - VkVideoEncodeH265TransformBlockSizeFlagsEXT transformBlockSizes + VkVideoEncodeH265CtbSizeFlagsKHR ctbSizes + VkVideoEncodeH265TransformBlockSizeFlagsKHR transformBlockSizes uint32_t maxPPictureL0ReferenceCount uint32_t maxBPictureL0ReferenceCount uint32_t maxL1ReferenceCount @@ -7117,17 +7141,17 @@ typedef void* MTLSharedEvent_id; int32_t maxQp VkBool32 prefersGopRemainingFrames VkBool32 requiresGopRemainingFrames - VkVideoEncodeH265StdFlagsEXT stdSyntaxFlags + VkVideoEncodeH265StdFlagsKHR stdSyntaxFlags - - VkStructureType sType + + VkStructureType sType void* pNext - VkVideoEncodeH265RateControlFlagsEXT preferredRateControlFlags + VkVideoEncodeH265RateControlFlagsKHR preferredRateControlFlags uint32_t preferredGopFrameCount uint32_t preferredIdrPeriod uint32_t preferredConsecutiveBFrameCount uint32_t preferredSubLayerCount - VkVideoEncodeH265QpEXT preferredConstantQp + VkVideoEncodeH265QpKHR preferredConstantQp uint32_t preferredMaxL0ReferenceCount uint32_t preferredMaxL1ReferenceCount @@ -7140,14 +7164,14 @@ typedef void* MTLSharedEvent_id; - - VkStructureType sType + + VkStructureType sType const void* pNext VkBool32 useMaxLevelIdc StdVideoH265LevelIdc maxLevelIdc - - VkStructureType sType + + VkStructureType sType const void* pNext uint32_t stdVPSCount const StdVideoH265VideoParameterSet* pStdVPSs @@ -7156,16 +7180,16 @@ typedef void* MTLSharedEvent_id; uint32_t stdPPSCount const StdVideoH265PictureParameterSet* pStdPPSsList of Picture Parameters associated with the spsStd, above - - VkStructureType sType + + VkStructureType sType const void* pNext uint32_t maxStdVPSCount uint32_t maxStdSPSCount uint32_t maxStdPPSCount - const VkVideoEncodeH265SessionParametersAddInfoEXT* pParametersAddInfo + const VkVideoEncodeH265SessionParametersAddInfoKHR* pParametersAddInfo - - VkStructureType sType + + VkStructureType sType const void* pNext VkBool32 writeStdVPS VkBool32 writeStdSPS @@ -7174,70 +7198,70 @@ typedef void* MTLSharedEvent_id; uint32_t stdSPSId uint32_t stdPPSId - - VkStructureType sType + + VkStructureType sType void* pNext VkBool32 hasStdVPSOverrides VkBool32 hasStdSPSOverrides VkBool32 hasStdPPSOverrides - - VkStructureType sType + + VkStructureType sType const void* pNext uint32_t naluSliceSegmentEntryCount - const VkVideoEncodeH265NaluSliceSegmentInfoEXT* pNaluSliceSegmentEntries + const VkVideoEncodeH265NaluSliceSegmentInfoKHR* pNaluSliceSegmentEntries const StdVideoEncodeH265PictureInfo* pStdPictureInfo - - VkStructureType sType + + VkStructureType sType const void* pNext int32_t constantQp const StdVideoEncodeH265SliceSegmentHeader* pStdSliceSegmentHeader - - VkStructureType sType + + VkStructureType sType const void* pNext - VkVideoEncodeH265RateControlFlagsEXT flags + VkVideoEncodeH265RateControlFlagsKHR flags uint32_t gopFrameCount uint32_t idrPeriod uint32_t consecutiveBFrameCount uint32_t subLayerCount - + int32_t qpI int32_t qpP int32_t qpB - + uint32_t frameISize uint32_t framePSize uint32_t frameBSize - - VkStructureType sType + + VkStructureType sType const void* pNext VkBool32 useGopRemainingFrames uint32_t gopRemainingI uint32_t gopRemainingP uint32_t gopRemainingB - - VkStructureType sType + + VkStructureType sType const void* pNext VkBool32 useMinQp - VkVideoEncodeH265QpEXT minQp + VkVideoEncodeH265QpKHR minQp VkBool32 useMaxQp - VkVideoEncodeH265QpEXT maxQp + VkVideoEncodeH265QpKHR maxQp VkBool32 useMaxFrameSize - VkVideoEncodeH265FrameSizeEXT maxFrameSize + VkVideoEncodeH265FrameSizeKHR maxFrameSize - - VkStructureType sType + + VkStructureType sType const void* pNext StdVideoH265ProfileIdc stdProfileIdc - - VkStructureType sType + + VkStructureType sType const void* pNext const StdVideoEncodeH265ReferenceInfo* pStdReferenceInfo @@ -8704,6 +8728,65 @@ typedef void* MTLSharedEvent_id; VkDeviceOrHostAddressConstAMDX infos uint64_t stride + + VkStructureType sType + const void* pNext + VkResult* pResult + + + VkStructureType sType + const void* pNext + VkShaderStageFlags stageFlags + VkPipelineLayout layout + uint32_t firstSet + uint32_t descriptorSetCount + const VkDescriptorSet* pDescriptorSets + uint32_t dynamicOffsetCount + const uint32_t* pDynamicOffsets + + + VkStructureType sType + const void* pNext + VkPipelineLayout layout + VkShaderStageFlags stageFlags + uint32_t offset + uint32_t size + const void* pValues + + + VkStructureType sType + const void* pNext + VkShaderStageFlags stageFlags + VkPipelineLayout layout + uint32_t set + uint32_t descriptorWriteCount + const VkWriteDescriptorSet* pDescriptorWrites + + + VkStructureType sType + const void* pNext + VkDescriptorUpdateTemplate descriptorUpdateTemplate + VkPipelineLayout layout + uint32_t set + const void* pData + + + VkStructureType sType + const void* pNext + VkShaderStageFlags stageFlags + VkPipelineLayout layout + uint32_t firstSet + uint32_t setCount + const uint32_t* pBufferIndices + const VkDeviceSize* pOffsets + + + VkStructureType sType + const void* pNext + VkShaderStageFlags stageFlags + VkPipelineLayout layout + uint32_t set + VkStructureType sType void* pNext @@ -8761,6 +8844,12 @@ typedef void* MTLSharedEvent_id; void* pNext VkLayeredDriverUnderlyingApiMSFT underlyingAPI + + VkStructureType sType + void* pNext + VkBool32 perStageDescriptorSet + VkBool32 dynamicPipelineLayout + VkStructureType sType void* pNext @@ -10653,45 +10742,45 @@ typedef void* MTLSharedEvent_id; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -10769,58 +10858,58 @@ typedef void* MTLSharedEvent_id; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -11790,7 +11879,7 @@ typedef void* MTLSharedEvent_id; void vkCmdBindIndexBuffer VkCommandBuffer commandBuffer - VkBuffer buffer + VkBuffer buffer VkDeviceSize offset VkIndexType indexType @@ -14004,7 +14093,7 @@ typedef void* MTLSharedEvent_id; void vkCmdBindIndexBuffer2KHR VkCommandBuffer commandBuffer - VkBuffer buffer + VkBuffer buffer VkDeviceSize offset VkDeviceSize size VkIndexType indexType @@ -15082,6 +15171,36 @@ typedef void* MTLSharedEvent_id; VkDeviceAddress scratch VkDeviceAddress countInfo + + void vkCmdBindDescriptorSets2KHR + VkCommandBuffer commandBuffer + const VkBindDescriptorSetsInfoKHR* pBindDescriptorSetsInfo + + + void vkCmdPushConstants2KHR + VkCommandBuffer commandBuffer + const VkPushConstantsInfoKHR* pPushConstantsInfo + + + void vkCmdPushDescriptorSet2KHR + VkCommandBuffer commandBuffer + const VkPushDescriptorSetInfoKHR* pPushDescriptorSetInfo + + + void vkCmdPushDescriptorSetWithTemplate2KHR + VkCommandBuffer commandBuffer + const VkPushDescriptorSetWithTemplateInfoKHR* pPushDescriptorSetWithTemplateInfo + + + void vkCmdSetDescriptorBufferOffsets2EXT + VkCommandBuffer commandBuffer + const VkSetDescriptorBufferOffsetsInfoEXT* pSetDescriptorBufferOffsetsInfo + + + void vkCmdBindDescriptorBufferEmbeddedSamplers2EXT + VkCommandBuffer commandBuffer + const VkBindDescriptorBufferEmbeddedSamplersInfoEXT* pBindDescriptorBufferEmbeddedSamplersInfo + VkResult vkSetLatencySleepModeNV VkDevice device @@ -16947,7 +17066,7 @@ typedef void* MTLSharedEvent_id; - + @@ -17124,101 +17243,101 @@ typedef void* MTLSharedEvent_id; - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + - + @@ -19391,7 +19510,7 @@ typedef void* MTLSharedEvent_id; - + @@ -20759,43 +20878,43 @@ typedef void* MTLSharedEvent_id; - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + @@ -20833,8 +20952,8 @@ typedef void* MTLSharedEvent_id; - - + + @@ -22176,16 +22295,16 @@ typedef void* MTLSharedEvent_id; - - + + - - + + @@ -23077,6 +23196,7 @@ typedef void* MTLSharedEvent_id; + @@ -23522,19 +23642,26 @@ typedef void* MTLSharedEvent_id; - + - - - - + + + + + + + + + - + - - - + + + + + @@ -23757,10 +23884,42 @@ typedef void* MTLSharedEvent_id; - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -23821,6 +23980,12 @@ typedef void* MTLSharedEvent_id; + + + + + +