Change log for July 12, 2024 Vulkan 1.3.290 spec update:

  * Explicitly state that PackHalf2x16 rounding is implementation-dependent
    <<spirvenv-op-prec, Precision of Individual Operations>> section (public
    issue 1825).
  * Update `asciidoctor-spec` Docker build image to one based on ruby:3.3.3
    to reduce the number of reported CVEs on the image and update toolchain
    components (public MR 2073, internal MR 6754).
  * Fix display/encoding statements and interchanged concepts of EOTF and
    OETF for the VK_EXT_swapchain_colorspace extension (partially addresses
    public issue 2312).
  * Fix <<copies-buffers-images-addressing, copy buffer <-> image
    equations>> and corresponding common validity statements for block image
    formats (public issues 2377 and 2378).
  * Clarify that the query LOD is relative to the base level in the
    <<textures-queries, Image Query Instructions>> section (public issues
    2383).

Internal Issues

  * Improve cross-referencing links in refpages, primarily by adding
    crosslinks for all corresponding VkFlags* / VkFlagBits* types (internal
    issue 861).
  * Clarify VUs for OpCooperativeMatrixMulAdd (internal issue 3708).
  * Add CI check for consistency of Vk*Flags and corresponding Vk*FlagBits
    type names and sizes (internal issue 3716).
  * Add CI check to prevent custom macro use in proposal documents (internal
    issue 3919).
  * Remove references to "`reference monitor`" in the VK_EXT_hdr_metadata
    extension and replace with "`display used to optimize the content`"
    (internal MR 6566).
  * Add new <<fundamentals-commandsyntax-array-results, Array Results>>
    section summarizing behavior of commands which query arrays (internal MR
    6685).
  * Fix incorrect description of
    VkDisplaySurfaceCreateInfoKHR::VkDisplayPlaneAlphaFlagBitsKHR in
    `vk.xml` (internal MR 6704).
  * Add additional terminology checks to CI (internal MR 6747).
  * Fix VkFramebufferCreateInfo VU 04587 (internal MR 6756).
  * Remove redundant VU 08921 (internal MR 6766).
  * Fix a/an typos (internal MR 6773).

.github/workflows/CI.yml

@@ -21,8 +21,8 @@ jobs:
     runs-on: ubuntu-latest
     # We now refer to the container by its SHA instead of the name, to prevent
     # caching problems when updating the image.
-    # container: khronosgroup/docker-images:asciidoctor-spec
-    container: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed
+    # container: khronosgroup/docker-images:asciidoctor-spec.20240702
+    container: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f
 
     steps:
       - uses: actions/checkout@v4
@@ -32,12 +32,12 @@ jobs:
   terminology-check:
     name: Run various checker scripts on the spec and XML sources
     runs-on: ubuntu-latest
-    container: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed
+    container: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f
 
     steps:
       - uses: actions/checkout@v4
       - name: Internal self-test of the check_spec_links script
-        run: py.test-3 test*.py
+        run: pytest test*.py
         working-directory: scripts
       - name: Generate a summary of problems for CI logs (if any)
         run: |
@@ -48,7 +48,7 @@ jobs:
   spec-core:
     name: Build the core-only spec, to try and catch ifdef errors in extension markup
     runs-on: ubuntu-latest
-    container: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed
+    container: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f
 
     steps:
       - uses: actions/checkout@v4
@@ -57,7 +57,7 @@ jobs:
   spec-generate:
     name: Build the vulkan specification and generate any associated files (such as vulkan.h)
     runs-on: ubuntu-latest
-    container: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed
+    container: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f
 
     steps:
       - uses: actions/checkout@v4
@@ -185,7 +185,7 @@ jobs:
   cts-framework-tests:
     name: Run Vulkan CTS framework tests to validate against XML changes
     runs-on: ubuntu-latest
-    container: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed
+    container: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f
     continue-on-error: true
 
     steps:

.gitlab-ci.yml

@@ -6,8 +6,8 @@
 # All stages use the same Docker image, so there are no prerequisites
 # Refer to the container by its SHA instead of the name, to prevent
 # caching problems when updating the image.
-# image: khronosgroup/docker-images:asciidoctor-spec
-image: khronosgroup/docker-images@sha256:91a1b62399f9804e17110e89d85d62e90bc8d2ad7b94a329bee87784158368a9
+# image: khronosgroup/docker-images:asciidoctor-spec.20240702
+image: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f
 
 # Specify which gitlab runner to use
 default:
@@ -31,7 +31,7 @@ terminology_check:
     # Nothing, all prerequisites are in the Docker image
   script:
     # Internal self-test of the check_spec_links script
-    - ( cd scripts && py.test-3 test*.py )
+    - ( cd scripts && pytest test*.py )
     - mkdir -p gen/out/checks
     # Generate a summary of problems for CI logs (if any)
     # Override CHECK_XREFS to avoid building a redundant HTML target at this stage

.reuse/dep5

@@ -2,7 +2,7 @@ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: Vulkan-Docs
 Source: https://github.com/KhronosGroup/Vulkan-Docs
 
-Files: images/*.svg config/chunkindex/custom.patch config/CI/contractions* config/CI/writing config/CI/txt-files-allowed config/*/docinfo-header.html build_tests/expectations/* build_tests/images/*.svg images/proposals/*.svg
+Files: images/*.svg config/chunkindex/custom.patch config/CI/* config/*/docinfo-header.html build_tests/expectations/* build_tests/images/*.svg images/proposals/*.svg
 Copyright: 2015-2024 The Khronos Group Inc.
 License: CC-BY-4.0
 

BUILD.adoc

@@ -426,7 +426,7 @@ image name. The SHA256 can be determined from
 
 which will print a line like
 
-    image: khronosgroup/docker-images@sha256:42123ba13792c4e809d037b69152c2230ad97fbf43b677338075ab9c928ab6ed
+    image: khronosgroup/docker-images@sha256:4aab96a03ef292439c9bd0f972adfa29cdf838d0909b1cb4ec2a6d7b2d14a37f
 
 Everything following `image: ` is the <imagename> to use. The first time you
 try to run a container with this <imagename>, as is done by the `runDocker`
@@ -520,7 +520,7 @@ https://github.com/KhronosGroup/Vulkan-Docs/pull/2286 for more.
   * 2017-01-06 - Replace MathJax with KaTeX.
   * 2016-08-25 - Update for the single-branch model.
   * 2016-07-10 - Update for current state of spec and ref page generation.
-  * 2015-11-11 - Add new can: etc.
+  * 2015-11-11 - Add new *can* etc.
     macros and DBLATEXPREFIX variable.
   * 2015-09-21 - Convert document to asciidoc and rename to README.md in the
     hope the gitlab browser will render it in some fashion.

ChangeLog.adoc

@@ -14,6 +14,50 @@ appears frequently in the change log.
 
 '''
 
+Change log for July 12, 2024 Vulkan 1.3.290 spec update:
+
+  * Explicitly state that PackHalf2x16 rounding is implementation-dependent
+    <<spirvenv-op-prec, Precision of Individual Operations>> section (public
+    issue 1825).
+  * Update `asciidoctor-spec` Docker build image to one based on ruby:3.3.3
+    to reduce the number of reported CVEs on the image and update toolchain
+    components (public MR 2073, internal MR 6754).
+  * Fix display/encoding statements and interchanged concepts of EOTF and
+    OETF for the VK_EXT_swapchain_colorspace extension (partially addresses
+    public issue 2312).
+  * Fix <<copies-buffers-images-addressing, copy buffer <-> image
+    equations>> and corresponding common validity statements for block image
+    formats (public issues 2377 and 2378).
+  * Clarify that the query LOD is relative to the base level in the
+    <<textures-queries, Image Query Instructions>> section (public issues
+    2383).
+
+Internal Issues
+
+  * Improve cross-referencing links in refpages, primarily by adding
+    crosslinks for all corresponding VkFlags* / VkFlagBits* types (internal
+    issue 861).
+  * Clarify VUs for OpCooperativeMatrixMulAdd (internal issue 3708).
+  * Add CI check for consistency of Vk*Flags and corresponding Vk*FlagBits
+    type names and sizes (internal issue 3716).
+  * Add CI check to prevent custom macro use in proposal documents (internal
+    issue 3919).
+  * Remove references to "`reference monitor`" in the VK_EXT_hdr_metadata
+    extension and replace with "`display used to optimize the content`"
+    (internal MR 6566).
+  * Add new <<fundamentals-commandsyntax-array-results, Array Results>>
+    section summarizing behavior of commands which query arrays (internal MR
+    6685).
+  * Fix incorrect description of
+    VkDisplaySurfaceCreateInfoKHR::VkDisplayPlaneAlphaFlagBitsKHR in
+    `vk.xml` (internal MR 6704).
+  * Add additional terminology checks to CI (internal MR 6747).
+  * Fix VkFramebufferCreateInfo VU 04587 (internal MR 6756).
+  * Remove redundant VU 08921 (internal MR 6766).
+  * Fix a/an typos (internal MR 6773).
+
+'''
+
 Change log for June 28, 2024 Vulkan 1.3.289 spec update:
 
 Internal Issues
@@ -3177,7 +3221,7 @@ Public Issues:
     elink:VK_COLOR_SPACE_PASS_THROUGH_EXT for a linear or non-gamma transfer
     function color space (public merge request 1729).
   * Fix clamp expression for d_{lo} in the
-    <<textures-level-of-detail-operation, Level-of-Detail Operation>>
+    <<textures-level-of-detail-operation, Level of Detail Operation>>
     section (partial fix for public issue 1836).
   * Update <<spirvenv-module-validation-standalone, Standalone SPIR-V
     Validation>> to add explicit valid usage statements for code:Uniform
@@ -8576,7 +8620,7 @@ GitHub Issues:
 Internal Issues:
 
   * Clarify range and precision of code:OpImageQueryLod in the discussion of
-    scale factor and level-of-detail operation in the
+    scale factor and LOD operation in the
     <<textures-normalized-operations, Normalized Texel Coordinate
     Operations>> section (internal issues 926, 1719).
   * Fix framebuffer layer valid usage statements for
@@ -10978,7 +11022,7 @@ Internal Issues:
   * Specify which storage classes can have an initializer in the
     <<spirvenv-module-validation, Validation Rules within a Module>> section
     (internal issue 1023).
-  * Use "LOD" consistently for "level-of-detail", to eliminate spelling
+  * Use "LOD" consistently for "level{nbsp} of detail", to eliminate spelling
     inconsistencies. The term is already standardized in the Glossary
     (internal issue 1027).
 
@@ -11024,7 +11068,7 @@ Internal Issues:
     <<synchronization-semaphores-importing, Importing Semaphore Payloads>>
     section (internal issue 820).
   * Update the <<textures-image-level-selection, Image Level(s) Selection>>
-    equations so that the parameters returned by the level-of-detail query
+    equations so that the parameters returned by the LOD query
     appear explicitly, also fixing the issue that linear filtering would
     select a level below the base level for magnification (internal issue
     926).
@@ -11453,7 +11497,7 @@ GitHub Issues:
 Internal Issues:
 
   * Fix tessellation domain to have an upper-left origin in the
-    <<img-tessellation-topology-ul, tessellation toplogy image>> and related
+    <<img-tessellation-topology-ul, tessellation topology image>> and related
     language. CTS and all implementations were already doing this, it was
     just a documentation bug that it was flipped to lower-left (internal
     issue 603).
@@ -12182,7 +12226,7 @@ Internal Issues:
     extensions (internal issue 448).
   * Add the +<<VK_EXT_shader_subgroup_vote>>+ and
     +<<VK_EXT_shader_subgroup_ballot>>+ extensions (internal issue 449).
-  * Update the texture level-of-detail equation in the
+  * Update the texture LOD equation in the
     <<textures-scale-factor,Scale Factor Operation>> section to better
     approximate the ellipse major and minor axes (internal issue 547).
   * Forbid non-explicitly allowed uses of interface decorations in the
@@ -13880,10 +13924,9 @@ GitHub Issues:
   * Remove redundant statement from the code:FragDepth description in
     the <<interfaces-builtin-variables,Built-In Variables>>
     section (public issue 47).
-  * Define the clamping of the
-    <<textures-level-of-detail-operation,bias added to the scale
-    factor>> by linking to the slink:VkPhysicalDevice feature
-    pname:maxSamplerLodBias (public issue 64).
+  * Define the clamping of the <<textures-level-of-detail-operation, bias
+    added to the scale factor>> by linking to the slink:VkPhysicalDevice
+    feature pname:maxSamplerLodBias (public issue 64).
   * Fix typo "optimal linear resources" and clarify the set of resources
     <<features-limits-bufferImageGranularity,the
     pname:bufferImageGranularity resource>> applies to (public issue

Makefile

@@ -82,6 +82,7 @@ allchecks: check-copyright-dates \
     check-links \
     check-consistency \
     check-undefined \
+    check-custom-macros \
     check-txtfiles \
     $(CHECK_XREFS)
 
@@ -138,7 +139,7 @@ VERBOSE =
 # ADOCOPTS options for asciidoc->HTML5 output
 
 NOTEOPTS     = -a editing-notes -a implementation-guide
-PATCHVERSION = 289
+PATCHVERSION = 290
 BASEOPTS     =
 
 ifneq (,$(findstring VKSC_VERSION_1_0,$(VERSIONS)))
@@ -437,7 +438,7 @@ reflow:
 # 'ci-allchecks' targets or individually.
 
 # Look for disallowed contractions
-CHECK_CONTRACTIONS = git grep -i -F -f $(ROOTDIR)/config/CI/contractions | egrep -v -E -f $(ROOTDIR)/config/CI/contractions-allowed
+CHECK_CONTRACTIONS = git grep -n -i -F -f $(ROOTDIR)/config/CI/contractions | egrep -v -E -f $(ROOTDIR)/config/CI/contractions-allowed
 check-contractions:
 	if test `$(CHECK_CONTRACTIONS) | wc -l` != 0 ; then \
 	    echo "Contractions found that are not allowed:" ; \
@@ -453,19 +454,21 @@ check-duplicates:
 	    exit 1 ; \
 	fi
 
-# Look for typos and suggest fixes
-CODESPELL = codespell --config $(ROOTDIR)/config/CI/codespellrc -S '*.js' -S './antora*/*' -S 'ERRS*,*.pdf,*.html'
+# Look for typos and unpreferred terms, and suggest fixes.
+# Harder to detect (e.g. case-sensitive) typos are handled in the
+# check-writing target below.
+CODESPELL = codespell --config $(ROOTDIR)/config/CI/codespellrc
 check-spelling:
 	if ! $(CODESPELL) > /dev/null ; then \
-	    echo "Found probable misspellings. Corrections can be added to config/CI/codespell-allowed:" ; \
+	    echo "Found probable misspellings. Corrections can be added to config/CI/codespell-allowed, or files excluded in config/CI/codespellrc if there is no other option:" ; \
 	    $(CODESPELL) ; \
 	    exit 1 ; \
 	fi
 
 # Look for old or unpreferred language in specification language.
 # This mostly helps when we make global changes that also need to be
 # made in outstanding extension branches for new text.
-CHECK_WRITING = git grep -E -f $(ROOTDIR)/config/CI/writing $(SPECDIR)/registry.adoc $(SPECDIR)/vkspec.adoc $(SPECDIR)/chapters $(SPECDIR)/appendices
+CHECK_WRITING = git grep -n -E -f $(ROOTDIR)/config/CI/writing $(SPECDIR)/registry.adoc $(SPECDIR)/vkspec.adoc $(SPECDIR)/chapters $(SPECDIR)/appendices
 check-writing:
 	if test `$(CHECK_WRITING) | wc -l` != 0 ; then \
 	    echo "Found old style writing. Please refer to the style guide or similar language in current main branch for fixes:" ; \
@@ -474,7 +477,7 @@ check-writing:
 	fi
 
 # Look for bullet list items not preceded by exactly two spaces, per styleguide
-CHECK_BULLETS = git grep -E '^( |   +)[-*]+ ' $(SPECDIR)/chapters $(SPECDIR)/appendices $(SPECDIR)/style $(SPECDIR)/[a-z]*.adoc
+CHECK_BULLETS = git grep -n -E '^( |   +)[-*]+ ' $(SPECDIR)/chapters $(SPECDIR)/appendices $(SPECDIR)/style $(SPECDIR)/[a-z]*.adoc
 check-bullets:
 	if test `$(CHECK_BULLETS) | wc -l` != 0 ; then \
 	    echo "Bullet list item found not preceded by exactly two spaces:" ; \
@@ -508,10 +511,20 @@ check-links:
 check-consistency:
 	$(PYTHON) $(SCRIPTS)/xml_consistency.py
 
-# Looks for untagged use of 'undefined' in spec sources
+# Look for untagged use of 'undefined' in spec sources
 check-undefined:
 	$(SCRIPTS)/ci/check_undefined
 
+# Look for use of custom macros in the proposals and other
+# non-Specification document (except for the ChangeLog*.adoc) markup
+CHECK_CUSTOM_MACROS = git grep -n -E -f $(ROOTDIR)/config/CI/custom-macros [A-Z][A-Z]*.adoc proposals/
+check-custom-macros:
+	if test `$(CHECK_CUSTOM_MACROS) | wc -l` != 0 ; then \
+	    echo "Found use of specification macros in proposal or repository metadocumentation, where they are not allowed. Please use straight asciidoc markup like *must* for fixes:" ; \
+	    $(CHECK_CUSTOM_MACROS) ; \
+	    exit 1 ; \
+	fi
+
 # Look for '.txt' and '.asciidoc' files, which should almost all be .adoc now
 CHECK_TXTFILES = find . -name '*.txt' -o -name '*.asciidoc' | egrep -v -E -f $(ROOTDIR)/config/CI/txt-files-allowed
 check-txtfiles:
@@ -523,7 +536,7 @@ check-txtfiles:
 
 # Check for valid xrefs in the output html
 check-xrefs: $(HTMLDIR)/vkspec.html
-	$(SCRIPTS)/check_html_xrefs.py $(HTMLDIR)/vkspec.html
+	$(PYTHON) $(SCRIPTS)/check_html_xrefs.py $(HTMLDIR)/vkspec.html
 
 # Clean generated and output files
 

appendices/VK_EXT_device_address_binding_report.adoc

@@ -50,7 +50,7 @@ such as buffers and images?
 *RESOLVED*: The extension covers all Vulkan objects, and is not restricted
 to objects backed by VkDeviceMemory objects.
 
-3.) Should reallocation be identified explicitly, or as a unbind/bind pair?
+3.) Should reallocation be identified explicitly, or as an unbind/bind pair?
 
 *RESOLVED*: Reallocation should be represented as an unbind/bind pair.
 

appendices/VK_EXT_device_memory_report.adoc

@@ -148,7 +148,7 @@ like size and heap index reported?
 This fits in well with the callback infrastructure added in this extension,
 and implementation touches the same code and has the same overheads as the
 rest of the extension.
-It could help debugging things like getting an
+It could help debugging things like getting a
 ename:VK_ERROR_OUT_OF_HOST_MEMORY error when ending a command buffer.
 Right now the allocation failure could have happened anywhere during
 recording, and a callback would be really useful to understand where and