Change log for July 19, 2024 Vulkan 1.3.291 spec update:

GitHub Issues * Remove stale dangling video Std* type references from vk.xml (public issue 2388). * Update NOTE block markup so asciidoctor outputs match Antora outputs (public issue 2392). * Fix incorrect registry schema doc information regarding XML type tags (public issue 2394). Internal Issues * Add comments in generated headers and interface includes for APIs with XML 'deprecated' attributes, describing why they're deprecated (internal issue 2897). * Clarify language about OpFDiv(x,0) generating infinity and relocate to the <<spirvenv-precision-core-table>> Precision of core SPIR-V Instructions>> table (internal issue 3902). * Update the <<memory-external-android-hardware-buffer-external-formats, Android Hardware Buffer External Formats>> section to address confusion about content preservation and input attachments with external format resolves (internal issue 3931). * Fix dynamic state interaction in common draw dispatch VU 08608 (internal issue 3935). * Refactor SPIR-V precisions to reduce duplication by introducing the term _bit-preserving operations_. Add additional bit-preserving operations in <<spirvenv-precision-operation, Precision and Operation of SPIR-V Instructions>>, and move OpTranspose into the bit-preserving operations section of that list (internal issue 3902). * Update test build expectations, and add a spec-toolchain step to CI invoking the test build (internal MR 6632). * Correct use of normative must: in several places that had accumulated (internal MR 6750). * Update VkImageCreateInfo VU 06722 and add new VU to fix mutable image creation for planar images to match up with imageview VUs (internal MR 6774). * Remove unhelpful (because unobserveable) additional notes about float precision in <<spirvenv-precision-operation, Precision and Operation of SPIR-V Instructions>> (internal MR 6778). * Add video codec and capabilities metadata to the XML (internal MR 6787). * Refactor the VK_AMD_anti_lag and VK_NV_low_latency2 extensions from very short standalone chapters into the WSI chapter (internal MR 6792) New Extensions * VK_AMD_anti_lag
KhronosGroup · Jul 19, 2024 · 4b01c38 · 4b01c38
1 parent 043260d
commit 4b01c38
Show file tree

Hide file tree

Showing 154 changed files with 1,408 additions and 1,197 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -45,6 +45,15 @@ jobs:
           scripts/check_spec_links.py --html=gen/out/checks/problems.html > /dev/null || true
           make CHECK_XREFS= allchecks
 
+  spec-toolchain:
+    name: Build a test spec and check against expectation, to make sure the spec toolchain works as expected
+    runs-on: ubuntu-latest
+    container: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f
+
+    steps:
+      - uses: actions/checkout@v4
+      - run: ./testBuild
+
   spec-core:
     name: Build the core-only spec, to try and catch ifdef errors in extension markup
     runs-on: ubuntu-latest

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -50,6 +50,14 @@ spec_version_check:
     - test -z "$CI_COMMIT_BRANCH" || scripts/testSpecVersion.py -branch $CI_COMMIT_BRANCH
   allow_failure: false
 
+# Build a test spec and check against expectation, to make sure the spec toolchain works as expected
+spec-toolchain:
+  stage: build
+  before_script:
+    # Nothing, all prerequisites are in the Docker image
+  script:
+    - ./testBuild
+
 # Build the vulkan specification and generate any associated files (such as vulkan.h)
 spec-generate:
   stage: build
@@ -83,7 +91,7 @@ spec-generate:
     # Check consistency of internal xrefs and anchors in the HTML output
     - make check-xrefs
     # Build headers, for use by all later stages
-    - ( cd xml && make validate install test )
+    - ( cd xml && make validate install test vtest )
   artifacts:
     when: always
     paths:

diff --git a/BUILD.adoc b/BUILD.adoc
@@ -68,15 +68,13 @@ toolchain installed, you can just invoke the same `make` commands from the
 repository root.
 
 [NOTE]
-.Note
 ====
 You can modify the `runDocker` script to change the `docker` command-line
 options, but it is important to always use the Docker image specified in
 that script, so you have the latest version of the spec toolchain.
 ====
 
 [NOTE]
-.Note
 ====
   * While it is possible to invoke `make` directly, this is rarely
     appropriate or useful.
@@ -270,7 +268,6 @@ of each section which links to the next difference section.
 The first diff section is `#difference1`.
 
 [NOTE]
-.Note
 ====
 This output is not without errors.
 It may instead result in visible `+++[.added]##content##+++` and
@@ -438,7 +435,6 @@ This image is used to build Specification output documents or other Makefile
 targets.
 
 [NOTE]
-.Note
 ====
 When we update the image on Dockerhub, it is to add new components or update
 versions of components used in the specification toolchain.
@@ -468,7 +464,6 @@ link:https://github.com/KhronosGroup/Vulkan-Docs/blob/v1.2.135/BUILD.adoc#depend
 version of BUILD.adoc in the v1.2.135 repository tag]
 
 [NOTE]
-.Note
 ====
 While you do not have to use our Docker image, we cannot support every
 possible build environment.

diff --git a/ChangeLog.adoc b/ChangeLog.adoc
@@ -14,6 +14,56 @@ appears frequently in the change log.
 
 '''
 
+Change log for July 19, 2024 Vulkan 1.3.291 spec update:
+
+GitHub Issues
+
+  * Remove stale dangling video Std* type references from vk.xml (public
+    issue 2388).
+  * Update NOTE block markup so asciidoctor outputs match Antora outputs
+    (public issue 2392).
+  * Fix incorrect registry schema doc information regarding XML type tags
+    (public issue 2394).
+
+Internal Issues
+
+  * Add comments in generated headers and interface includes for APIs with
+    XML 'deprecated' attributes, describing why they're deprecated (internal
+    issue 2897).
+  * Clarify language about OpFDiv(x,0) generating infinity and relocate to
+    the <<spirvenv-precision-core-table>> Precision of core SPIR-V
+    Instructions>> table (internal issue 3902).
+  * Update the <<memory-external-android-hardware-buffer-external-formats,
+    Android Hardware Buffer External Formats>> section to address confusion
+    about content preservation and input attachments with external format
+    resolves (internal issue 3931).
+  * Fix dynamic state interaction in common draw dispatch VU 08608 (internal
+    issue 3935).
+  * Refactor SPIR-V precisions to reduce duplication by introducing the term
+    _bit-preserving operations_. Add additional bit-preserving operations in
+    <<spirvenv-precision-operation, Precision and Operation of SPIR-V
+    Instructions>>, and move OpTranspose into the bit-preserving operations
+    section of that list (internal issue 3902).
+  * Update test build expectations, and add a spec-toolchain step to CI
+    invoking the test build (internal MR 6632).
+  * Correct use of normative must: in several places that had accumulated
+    (internal MR 6750).
+  * Update VkImageCreateInfo VU 06722 and add new VU to fix mutable image
+    creation for planar images to match up with imageview VUs (internal MR
+    6774).
+  * Remove unhelpful (because unobserveable) additional notes about float
+    precision in <<spirvenv-precision-operation, Precision and Operation of
+    SPIR-V Instructions>> (internal MR 6778).
+  * Add video codec and capabilities metadata to the XML (internal MR 6787).
+  * Refactor the VK_AMD_anti_lag and VK_NV_low_latency2 extensions from very
+    short standalone chapters into the WSI chapter (internal MR 6792)
+
+New Extensions
+
+  * VK_AMD_anti_lag
+
+'''
+
 Change log for July 12, 2024 Vulkan 1.3.290 spec update:
 
   * Explicitly state that PackHalf2x16 rounding is implementation-dependent

diff --git a/Makefile b/Makefile
@@ -139,7 +139,7 @@ VERBOSE =
 # ADOCOPTS options for asciidoc->HTML5 output
 
 NOTEOPTS     = -a editing-notes -a implementation-guide
-PATCHVERSION = 290
+PATCHVERSION = 291
 BASEOPTS     =
 
 ifneq (,$(findstring VKSC_VERSION_1_0,$(VERSIONS)))

diff --git a/antora/spec/modules/ROOT/nav.adoc b/antora/spec/modules/ROOT/nav.adoc
@@ -51,7 +51,6 @@ ifeval::["{test}"=="0"]
 * 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[]
 * xref:chapters/extensions.adoc[]
 * xref:chapters/features.adoc[]
 * xref:chapters/limits.adoc[]

diff --git a/appendices/VK_AMD_anti_lag.adoc b/appendices/VK_AMD_anti_lag.adoc
@@ -0,0 +1,33 @@
+// Copyright (c) 2024 Advanced Micro Devices, Inc.
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}VK_AMD_anti_lag.adoc[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2024-06-06
+*IP Status*::
+    No known IP claims.
+*Contributors*::
+  - Tobias Hector, AMD
+  - Stuart Smith, AMD
+  - Arkadiusz Sarwa, AMD
+
+=== Description
+
+This extension automatically paces the CPU to make sure it does not get too
+far ahead of the GPU, reducing the latency between inputs received and
+updates on the screen.
+Additionally, Anti-Lag+ offers applications the ability to inform the driver
+when input processing begins, in order to align the timing of display
+updates, enabling even lower latency between receiving input and displaying
+on the screen.
+
+include::{generated}/interfaces/VK_AMD_anti_lag.adoc[]
+
+=== Version History
+
+  * Revision 1, 2024-06-06 (Arkadiusz Sarw)
+  ** Initial version
diff --git a/appendices/VK_EXT_debug_report.adoc b/appendices/VK_EXT_debug_report.adoc
@@ -93,7 +93,6 @@ happens and the third will log warnings to stdout.
 ----
 
 [NOTE]
-.Note
 ====
 In the initial release of the `VK_EXT_debug_report` extension, the token
 ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT was used.
@@ -104,7 +103,6 @@ The older enum is still available for backwards compatibility.
 ====
 
 [NOTE]
-.Note
 ====
 In the initial release of the `VK_EXT_debug_report` extension, the token
 ename:VK_DEBUG_REPORT_OBJECT_TYPE_DEBUG_REPORT_EXT was used.

diff --git a/appendices/VK_EXT_layer_settings.adoc b/appendices/VK_EXT_layer_settings.adoc
@@ -86,7 +86,6 @@ vkCreateInstance(&inst_create_info, nullptr, &_instances);
 ----
 
 [NOTE]
-.Note
 ====
 The `apiext:VK_EXT_layer_settings` extension subsumes all the functionality
 provided in the `apiext:VK_EXT_validation_flags` extension and the

diff --git a/appendices/VK_EXT_load_store_op_none.adoc b/appendices/VK_EXT_load_store_op_none.adoc
@@ -38,7 +38,6 @@ functionality.
 include::{generated}/interfaces/VK_EXT_load_store_op_none.adoc[]
 
 [NOTE]
-.Note
 ====
 While ename:VK_ATTACHMENT_STORE_OP_NONE is part of Vulkan 1.3, this
 extension was not promoted to core either in whole or in part.

diff --git a/appendices/VK_EXT_shader_viewport_index_layer.adoc b/appendices/VK_EXT_shader_viewport_index_layer.adoc
@@ -43,7 +43,6 @@ Behavior of these variables is extended as described in the
 
 ifdef::VK_NV_viewport_array2[]
 [NOTE]
-.Note
 ====
 The code:ShaderViewportIndexLayerEXT capability is equivalent to the
 code:ShaderViewportIndexLayerNV capability added by

diff --git a/appendices/VK_GOOGLE_display_timing.adoc b/appendices/VK_GOOGLE_display_timing.adoc
@@ -43,7 +43,6 @@ include::{generated}/interfaces/VK_GOOGLE_display_timing.adoc[]
 === Examples
 
 [NOTE]
-.Note
 ====
 The example code for the this extension (like the `apiext:VK_KHR_surface`
 and `VK_GOOGLE_display_timing` extensions) is contained in the cube demo

diff --git a/appendices/VK_IMG_format_pvrtc.adoc b/appendices/VK_IMG_format_pvrtc.adoc
@@ -20,7 +20,6 @@ specific to Imagination Technologies PowerVR Texture compression format
 (called PVRTC).
 
 [NOTE]
-.Note
 ====
 As also noted in the <<data-format, Khronos Data Format Specification>>,
 PVRTC1 images must have dimensions that are a power of two.

diff --git a/appendices/VK_KHR_display.adoc b/appendices/VK_KHR_display.adoc
@@ -197,7 +197,6 @@ ifndef::VKSC_VERSION_1_0[]
 === Examples
 
 [NOTE]
-.Note
 ====
 The example code for the `VK_KHR_display` and
 `apiext:VK_KHR_display_swapchain` extensions was removed from the appendix

diff --git a/appendices/VK_KHR_display_swapchain.adoc b/appendices/VK_KHR_display_swapchain.adoc
@@ -73,7 +73,6 @@ ifndef::VKSC_VERSION_1_0[]
 === Examples
 
 [NOTE]
-.Note
 ====
 The example code for the `apiext:VK_KHR_display` and
 `VK_KHR_display_swapchain` extensions was removed from the appendix after

diff --git a/appendices/VK_KHR_load_store_op_none.adoc b/appendices/VK_KHR_load_store_op_none.adoc
@@ -22,7 +22,6 @@ the `apiext:VK_EXT_load_store_op_none` extension.
 include::{generated}/interfaces/VK_KHR_load_store_op_none.adoc[]
 
 [NOTE]
-.Note
 ====
 While ename:VK_ATTACHMENT_STORE_OP_NONE is part of Vulkan 1.3, this
 extension was not promoted to core either in whole or in part.

diff --git a/appendices/VK_KHR_surface.adoc b/appendices/VK_KHR_surface.adoc
@@ -43,7 +43,6 @@ ifndef::VKSC_VERSION_1_0[]
 === Examples
 
 [NOTE]
-.Note
 ====
 The example code for the `VK_KHR_surface` and `apiext:VK_KHR_swapchain`
 extensions was removed from the appendix after revision 1.0.29.

diff --git a/appendices/VK_KHR_swapchain.adoc b/appendices/VK_KHR_swapchain.adoc
@@ -411,7 +411,6 @@ ifndef::VKSC_VERSION_1_0[]
 === Examples
 
 [NOTE]
-.Note
 ====
 The example code for the `apiext:VK_KHR_surface` and `VK_KHR_swapchain`
 extensions was removed from the appendix after revision 1.0.29.

diff --git a/appendices/VK_KHR_video_decode_h264.adoc b/appendices/VK_KHR_video_decode_h264.adoc
@@ -28,7 +28,6 @@ by adding support for decoding elementary video stream sequences compliant
 with the H.264/AVC video compression standard.
 
 [NOTE]
-.Note
 ====
 This extension was promoted to `KHR` from the provisional extension
 `VK_EXT_video_decode_h264`.

diff --git a/appendices/VK_KHR_video_decode_h265.adoc b/appendices/VK_KHR_video_decode_h265.adoc
@@ -27,7 +27,6 @@ by adding support for decoding elementary video stream sequences compliant
 with the H.265/HEVC video compression standard.
 
 [NOTE]
-.Note
 ====
 This extension was promoted to `KHR` from the provisional extension
 `VK_EXT_video_decode_h265`.

diff --git a/appendices/VK_KHR_video_encode_h264.adoc b/appendices/VK_KHR_video_encode_h264.adoc
@@ -31,7 +31,6 @@ by adding support for encoding elementary video stream sequences compliant
 with the H.264/AVC video compression standard.
 
 [NOTE]
-.Note
 ====
 This extension was promoted to `KHR` from the provisional extension
 `VK_EXT_video_encode_h264`.

diff --git a/appendices/VK_KHR_video_encode_h265.adoc b/appendices/VK_KHR_video_encode_h265.adoc
@@ -30,7 +30,6 @@ by adding support for encoding elementary video stream sequences compliant
 with the H.265/HEVC video compression standard.
 
 [NOTE]
-.Note
 ====
 This extension was promoted to `KHR` from the provisional extension
 `VK_EXT_video_encode_h265`.

diff --git a/appendices/VK_KHR_vulkan_memory_model.adoc b/appendices/VK_KHR_vulkan_memory_model.adoc
@@ -29,7 +29,6 @@ memory accesses to the same memory locations performed by multiple shader
 invocations.
 
 [NOTE]
-.Note
 ====
 Version 3 of the spec added a member
 (pname:vulkanMemoryModelAvailabilityVisibilityChains) to

diff --git a/appendices/VK_NVX_binary_import.adoc b/appendices/VK_NVX_binary_import.adoc
@@ -18,7 +18,6 @@ This extension allows applications to import CuBIN binaries and execute
 them.
 
 [NOTE]
-.Note
 ====
 There is currently no specification language written for this extension.
 The links to APIs defined by the extension are to stubs that only include

diff --git a/appendices/VK_NV_optical_flow.adoc b/appendices/VK_NV_optical_flow.adoc
@@ -21,7 +21,6 @@ This extension allows applications to estimate 2D displacement of pixels
 between two frames.
 
 [NOTE]
-.Note
 ====
 This extension is designed to be used with upcoming NVIDIA Optical Flow SDK
 Version 5 which will be available on NVIDIA Developer webpage.

diff --git a/appendices/VK_NV_viewport_array2.adoc b/appendices/VK_NV_viewport_array2.adoc
@@ -53,7 +53,6 @@ specification.
 
 ifdef::VK_EXT_shader_viewport_index_layer[]
 [NOTE]
-.Note
 ====
 The code:ShaderViewportIndexLayerNV capability is equivalent to the
 code:ShaderViewportIndexLayerEXT capability added by

diff --git a/appendices/VK_QCOM_render_pass_store_ops.adoc b/appendices/VK_QCOM_render_pass_store_ops.adoc
@@ -30,7 +30,6 @@ rendering, the contents of the attachment will be undefined: inside the
 render area.
 
 [NOTE]
-.Note
 ====
 The elink:VkAttachmentStoreOp ename:VK_ATTACHMENT_STORE_OP_STORE may: force
 an implementation to assume that the attachment was written and force an

diff --git a/appendices/VK_SEC_amigo_profiling.adoc b/appendices/VK_SEC_amigo_profiling.adoc
@@ -27,7 +27,6 @@ It is documented solely for the benefit of tools and layer developers, who
 may need to manipulate pname:pNext chains that include these structures.
 
 [NOTE]
-.Note
 ====
 There is currently no specification language written for this extension.
 The links to APIs defined by the extension are to stubs that only include
@@ -36,7 +35,6 @@ statements.
 ====
 
 [NOTE]
-.Note
 ====
 This extension is only intended for use in specific embedded environments
 with known implementation details, and is therefore undocumented.

diff --git a/appendices/VK_VALVE_descriptor_set_host_mapping.adoc b/appendices/VK_VALVE_descriptor_set_host_mapping.adoc
@@ -22,7 +22,6 @@ Memory offsets and sizes for descriptors can: be queried from a
 slink:VkDescriptorSetLayout as well.
 
 [NOTE]
-.Note
 ====
 There is currently no specification language written for this extension.
 The links to APIs defined by the extension are to stubs that only include
@@ -31,7 +30,6 @@ statements.
 ====
 
 [NOTE]
-.Note
 ====
 This extension is only intended for use in specific embedded environments
 with known implementation details, and is therefore undocumented.