Change log for June 30, 2023 Vulkan 1.3.256 spec update:

Github Issues

  * Fix minor typos (public pull requests 2154 and 2157).
  * Fix XML `<format>` metadata for etext:VK_FORMAT_R64G64* and
    ename:VK_FORMAT_BC*_SNORM_BLOCK (public pull request 2156).

Internal Issues

  * Specify fragment stage when accessing color attachment via shader tile
    image reads for ename:VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT and
    ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT (internal merge request 5918).
  * Clarify in which stages subgroup control flags
    ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT
    and ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT, as
    well as their apiext:VK_EXT_shader_object variants, are allowed to be
    set (internal issue 3529).
  * Fix typo to pname:depth in flink:vkCmdBindInvocationMaskHUAWEI VUID
    04983 (internal merge request 5958).
  * Rename ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADING_HUAWEI to
    ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADER_HUAWEI (internal merge request
    5959).
  * Modify the VU extraction script to correctly handle content that is not
    plain text, such as nested bullets or blocks (internal merge request
    5964).
  * Add a NOTE to the <<pipelines-cache-header, Pipeline Cache Header>>
    section and move one related VU statement. Fix handling of queue types
    with dependencies in generator scripts (internal merge request 5965).
  * Remove explicit `optional="false"` syntax from the XML schema for
    command `param` and structure `member` tags (internal merge request
    5970).
  * Refactor README.adoc to move Vulkan and VulkanSC-specific language into
    READMEVK.adoc and READMESC.adoc, respectively (internal merge request
    5971).
  * Update registry schema document with a current example of `externsync`
    for arrays (internal merge request 5975).

Author: oddhack

ChangeLog.adoc

@@ -14,6 +14,46 @@ appears frequently in the change log.
 
 -----------------------------------------------------
 
+Change log for June 30, 2023 Vulkan 1.3.256 spec update:
+
+Github Issues
+
+  * Fix minor typos (public pull requests 2154 and 2157).
+  * Fix XML `<format>` metadata for etext:VK_FORMAT_R64G64* and
+    ename:VK_FORMAT_BC*_SNORM_BLOCK (public pull request 2156).
+
+Internal Issues
+
+  * Specify fragment stage when accessing color attachment via shader tile
+    image reads for ename:VK_ACCESS_2_COLOR_ATTACHMENT_READ_BIT and
+    ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT (internal merge request 5918).
+  * Clarify in which stages subgroup control flags
+    ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT
+    and ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT, as
+    well as their apiext:VK_EXT_shader_object variants, are allowed to be
+    set (internal issue 3529).
+  * Fix typo to pname:depth in flink:vkCmdBindInvocationMaskHUAWEI VUID
+    04983 (internal merge request 5958).
+  * Rename ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADING_HUAWEI to
+    ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADER_HUAWEI (internal merge request
+    5959).
+  * Modify the VU extraction script to correctly handle content that is not
+    plain text, such as nested bullets or blocks (internal merge request
+    5964).
+  * Add a NOTE to the <<pipelines-cache-header, Pipeline Cache Header>>
+    section and move one related VU statement. Fix handling of queue types
+    with dependencies in generator scripts (internal merge request 5965).
+  * Remove explicit `optional="false"` syntax from the XML schema for
+    command `param` and structure `member` tags (internal merge request
+    5970).
+  * Refactor README.adoc to move Vulkan and VulkanSC-specific language into
+    READMEVK.adoc and READMESC.adoc, respectively (internal merge request
+    5971).
+  * Update registry schema document with a current example of `externsync`
+    for arrays (internal merge request 5975).
+
+-----------------------------------------------------
+
 Change log for June 23, 2023 Vulkan 1.3.255 spec update:
 
 Github Issues

Makefile

@@ -115,7 +115,7 @@ VERBOSE =
 # ADOCOPTS options for asciidoc->HTML5 output
 
 NOTEOPTS     = -a editing-notes -a implementation-guide
-PATCHVERSION = 255
+PATCHVERSION = 256
 BASEOPTS     =
 
 ifneq (,$(findstring VKSC_VERSION_1_0,$(VERSIONS)))

README.adoc

@@ -5,65 +5,11 @@ ifdef::env-github[]
 :note-caption: :information_source:
 endif::[]
 
-= Vulkan^(R)^ API Documentation Project
-
-The link:https://github.com/KhronosGroup/Vulkan-Docs[Vulkan-Docs]
-repository (or the equivalent internal Khronos tracking repository)
-contains sources for the formal documentation of the Vulkan
-API. This includes:
-
-[options="compact"]
-  * The Vulkan API Specification
-  * Specification of API extensions
-  * API reference ("`man`") pages
-  * The XML API Registry (also mirrored at
-    link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers])
-  * Vulkan header files (also mirrored at
-    link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers])
-  * Related tools and scripts.
-
-The authoritative public repository is located at
-link:https://github.com/KhronosGroup/Vulkan-Docs/[Vulkan-Docs].
-It hosts a public Issue tracker, and outside developers can file proposed
-changes (Pull Requests) against the Specification, subject to approval by
-Khronos.
-
-If in doubt where to submit your Issue, consult the
-link:https://github.com/KhronosGroup/Vulkan-Web-Registry/blob/main/Vulkan-Projects.adoc[Vulkan-Projects] list on the link:https://github.com/KhronosGroup/Vulkan-Web-Registry[Vulkan-Web-Registry]
-repository.
-
-The Vulkan-Docs repository also includes the sources for the Vulkan SC
-specification in order to simplify the long-term maintenance of the Vulkan SC
-specification. These are not considered normative. The formal sources for
-Vulkan SC can be found as detailed in link:READMESC.adoc[READMESC.adoc]
-
-== External Contributions
-
-Khronos welcomes feedback in GitHub Issues, and proposed changes in GitHub
-Pull Requests (PRs), but will not necessarily accept all such changes.
-
-Please keep your issues and pull requests focused on solving a single
-problem. Broader feedback that tries to solve multiple problems, or touches
-many parts of the Specification at once, is difficult for the Vulkan Working
-Group to review in a timely fashion.
-
-
-== Branch Structure
-
-The current Specification is maintained in the default branch (currently
-`main`) of the repository.
-From this branch it is possible to generate Specifications for any published
-version of Vulkan (1.3, 1.2, 1.1, and 1.0), and incorporating any desired set of
-extensions.
-Each published update is tagged in the form `1.3.*release*` where *release*
-is a constantly incrementing release number and `1.3` is the latest
-published version of the API.
-The last public spec update prior to Vulkan 1.3 is tagged `v1.2.???`.
-
-The last state of the default branch in Khronos' internal GitLab server,
-before 1.3 content was merged into it, is tagged `1.2-archive` (this tag is
-not in GitHub).
+= Vulkan^(R)^ and Vulkan^(R)^ SC API Documentation Project
 
+For Vulkan^(R)^ API specific documentation see link:READMEVK.adoc[READMEVK.adoc]
+
+For Vulkan^(R)^ SC API specific documentation see link:READMESC.adoc[READMESC.adoc]
 
 == Directory Structure
 
@@ -72,12 +18,13 @@ The directory structure is as follows:
 ```
 README.adoc           This file
 READMESC.adoc         Readme for the Vulkan SC specification
+READMEVK.adoc         Readme for the Vulkan specification
 BUILD.adoc            Documents how to build the specifications and reference pages
 CONTRIBUTING.adoc     Requirements for external contributions to the repository
 COPYING.adoc          Copyright and licensing information
 CODE_OF_CONDUCT.adoc  Code of Conduct
 LICENSE.adoc          Summary of licenses used by files in the repository
-ChangeLog.adoc        Change log summary for each public spec update
+ChangeLog.adoc        Change log summary for each public Vulkan spec update
 ChangeLogSC.adoc      Change log summary for each public Vulkan SC spec update
 Makefile, make*       Makefile and helper build scripts (see BUILD.adoc)
 appendices/           Specification appendices

READMESC.adoc

@@ -62,55 +62,3 @@ is a constantly incrementing release number and `1.0` is the latest
 published version of the API.
 
 
-== Directory Structure
-
-The directory structure is as follows:
-
-```
-README.adoc           Readme for the Vulkan specification
-READMESC.adoc         This file
-BUILD.adoc            Documents how to build the specifications and reference pages
-CONTRIBUTING.adoc     Requirements for external contributions to the repository
-COPYING.adoc          Copyright and licensing information
-CODE_OF_CONDUCT.adoc  Code of Conduct
-LICENSE.adoc          Summary of licenses used by files in the repository
-ChangeLog.adoc        Change log summary for each public Vulkan spec update
-ChangeLogSC.adoc      Change log summary for each public Vulkan SC spec update
-Makefile, make*       Makefile and helper build scripts (see BUILD.adoc)
-appendices/           Specification appendices
-chapters/             Specification chapters
-proposals/            Design documents for extensions
-config/               Asciidoctor configuration, CSS, and index generator
-images/               Images (figures, diagrams, icons)
-gen/out/              Default directory for the generated documents
-scripts/              Helper scripts used in specification, header, and reference page generation
-style/                Sources for "styleguide" (Vulkan SC Documentation and Extensions: Procedures and Conventions)
-xml/                  XML API Registry (vk.xml)
-registry.adoc         Sources for documentation of the XML format
-```
-
-
-== Building the Specification and Reference Pages
-
-The document sources are marked up in Asciidoctor format, and we use
-`asciidoctor` and related toolchain components to generate output documents.
-See link:BUILD.adoc[BUILD.adoc] for more information on installing the
-toolchain and building the Specification.
-
-
-== Generating Headers and Related Files
-
-See link:xml/README.adoc[xml/README.adoc].
-
-The header files (`include/vulkan/vulkan*.h`) and many parts of the
-specification and reference page documents are generated from descriptions
-in the XML API Registry (link:xml/vk.xml[`xml/vk.xml`]).
-The generated files are not checked into the repository.
-If you change `vk.xml`, you can regenerate the headers by going into
-`xml/` and running:
-
-    $ make clean install
-
-The other generated files are built as required via dependencies in
-the top-level `Makefile`.
-

READMEVK.adoc

@@ -0,0 +1,67 @@
+// Copyright 2017-2023 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+ifdef::env-github[]
+:note-caption: :information_source:
+endif::[]
+
+= Vulkan^(R)^ API Documentation Project
+
+The link:https://github.com/KhronosGroup/Vulkan-Docs[Vulkan-Docs]
+repository (or the equivalent internal Khronos tracking repository)
+contains sources for the formal documentation of the Vulkan
+API. This includes:
+
+[options="compact"]
+  * The Vulkan API Specification
+  * Specification of API extensions
+  * API reference ("`man`") pages
+  * The XML API Registry (also mirrored at
+    link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers])
+  * Vulkan header files (also mirrored at
+    link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers])
+  * Related tools and scripts.
+
+The authoritative public repository is located at
+link:https://github.com/KhronosGroup/Vulkan-Docs/[Vulkan-Docs].
+It hosts a public Issue tracker, and outside developers can file proposed
+changes (Pull Requests) against the Specification, subject to approval by
+Khronos.
+
+If in doubt where to submit your Issue, consult the
+link:https://github.com/KhronosGroup/Vulkan-Web-Registry/blob/main/Vulkan-Projects.adoc[Vulkan-Projects] list on the link:https://github.com/KhronosGroup/Vulkan-Web-Registry[Vulkan-Web-Registry]
+repository.
+
+The Vulkan-Docs repository also includes the sources for the Vulkan SC
+specification in order to simplify the long-term maintenance of the Vulkan SC
+specification. These are not considered normative. The formal sources for
+Vulkan SC can be found as detailed in link:READMESC.adoc[READMESC.adoc]
+
+== External Contributions
+
+Khronos welcomes feedback in GitHub Issues, and proposed changes in GitHub
+Pull Requests (PRs), but will not necessarily accept all such changes.
+
+Please keep your issues and pull requests focused on solving a single
+problem. Broader feedback that tries to solve multiple problems, or touches
+many parts of the Specification at once, is difficult for the Vulkan Working
+Group to review in a timely fashion.
+
+
+== Branch Structure
+
+The current Specification is maintained in the default branch (currently
+`main`) of the repository.
+From this branch it is possible to generate Specifications for any published
+version of Vulkan (1.3, 1.2, 1.1, and 1.0), and incorporating any desired set of
+extensions.
+Each published update is tagged in the form `1.3.*release*` where *release*
+is a constantly incrementing release number and `1.3` is the latest
+published version of the API.
+The last public spec update prior to Vulkan 1.3 is tagged `v1.2.???`.
+
+The last state of the default branch in Khronos' internal GitLab server,
+before 1.3 content was merged into it, is tagged `1.2-archive` (this tag is
+not in GitHub).
+
+

appendices/VK_HUAWEI_subpass_shading.adoc

@@ -175,12 +175,12 @@ VkSubpassDescription2 subpasses[] = {
 VkMemoryBarrier2KHR fragmentToSubpassShading = {
   VK_STRUCTURE_TYPE_MEMORY_BARRIER_2_KHR, NULL,
   VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT_KHR, VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT|VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT,
-  VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI, VK_ACCESS_INPUT_ATTACHMENT_READ_BIT
+  VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_ACCESS_INPUT_ATTACHMENT_READ_BIT
 };
 
 VkMemoryBarrier2KHR subpassShadingToFragment = {
   VK_STRUCTURE_TYPE_MEMORY_BARRIER_2_KHR, NULL,
-  VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI, VK_ACCESS_SHADER_WRITE_BIT,
+  VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI, VK_ACCESS_SHADER_WRITE_BIT,
   VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT_KHR, VK_ACCESS_SHADER_READ_BIT
 };
 
@@ -254,6 +254,10 @@ vkCreateComputePipelines(device, pipelineCache, 1, &subpassShadingComputePipelin
 
 === Version History
 
+  * Revision 3, 2023-06-19 (Pan Gao)
+  ** Rename `VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI` to
+     `VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI` to better aligned with
+     naming of other pipeline stages
   * Revision 2, 2021-06-28 (Hueilong Wang)
   ** Change vkGetSubpassShadingMaxWorkgroupSizeHUAWEI to
      vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI to resolve issue

appendices/spirvenv.adoc

@@ -1127,60 +1127,60 @@ ifdef::VK_NV_cooperative_matrix[]
     slink:VkPhysicalDeviceCooperativeMatrixPropertiesNV::pname:cooperativeMatrixSupportedStages
 endif::VK_NV_cooperative_matrix[]
 ifdef::VK_KHR_cooperative_matrix[]
-  * [[VUID-{refpage}-OpTypeCooperativeMatrixKHR-]]
+  * [[VUID-{refpage}-OpTypeCooperativeMatrixKHR-08974]]
     For code:OpTypeCooperativeMatrixKHR, the component type, scope, number
     of rows, and number of columns must: match one of the matrices in any of
     the supported slink:VkCooperativeMatrixPropertiesKHR.
-  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-]]
+  * [[VUID-{refpage}-MSize-08975]]
     For code:OpCooperativeMatrixMulAddKHR, the type of code:A must: have
     slink:VkCooperativeMatrixPropertiesKHR::pname:MSize rows and
     slink:VkCooperativeMatrixPropertiesKHR::pname:KSize columns and have a
     component type that matches
     slink:VkCooperativeMatrixPropertiesKHR::pname:AType.
-  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-]]
+  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-08976]]
     For code:OpCooperativeMatrixMulAddKHR, when the component type of code:A
     is a signed integer type, the code:MatrixASignedComponents cooperative
     matrix operand must: be present.
-  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-]]
+  * [[VUID-{refpage}-KSize-08977]]
     For code:OpCooperativeMatrixMulAddKHR, the type of code:B must: have
     slink:VkCooperativeMatrixPropertiesKHR::pname:KSize rows and
     slink:VkCooperativeMatrixPropertiesKHR::pname:NSize columns and have a
     component type that matches
     slink:VkCooperativeMatrixPropertiesKHR::pname:BType.
-  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-]]
+  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-08978]]
     For code:OpCooperativeMatrixMulAddKHR, when the component type of code:B
     is a signed integer type, the code:MatrixBSignedComponents cooperative
     matrix operand must: be present.
-  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-]]
+  * [[VUID-{refpage}-MSize-08979]]
     For code:OpCooperativeMatrixMulAddKHR, the type of code:C must: have
     slink:VkCooperativeMatrixPropertiesKHR::pname:MSize rows and
     slink:VkCooperativeMatrixPropertiesKHR::pname:NSize columns and have a
     component type that matches
     slink:VkCooperativeMatrixPropertiesKHR::pname:CType.
-  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-]]
+  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-08980]]
     For code:OpCooperativeMatrixMulAddKHR, when the component type of code:C
     is a signed integer type, the code:MatrixCSignedComponents cooperative
     matrix operand must: be present.
-  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-]]
+  * [[VUID-{refpage}-MSize-08981]]
     For code:OpCooperativeMatrixMulAddKHR, the type of code:Result must:
     have slink:VkCooperativeMatrixPropertiesKHR::pname:MSize rows and
     slink:VkCooperativeMatrixPropertiesKHR::pname:NSize columns and have a
     component type that matches
     slink:VkCooperativeMatrixPropertiesKHR::pname:ResultType.
-  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-]]
+  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-08982]]
     For code:OpCooperativeMatrixMulAddKHR, when the component type of
     code:Result is a signed integer type, the
     code:MatrixResultSignedComponents cooperative matrix operand must: be
     present.
-  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-]]
+  * [[VUID-{refpage}-saturatingAccumulation-08983]]
     For code:OpCooperativeMatrixMulAddKHR, the code:SaturatingAccumulation
     cooperative matrix operand must: be present if and only if
     slink:VkCooperativeMatrixPropertiesKHR::pname:saturatingAccumulation is
     ename:VK_TRUE.
-  * [[VUID-{refpage}-OpCooperativeMatrixMulAddKHR-]]
+  * [[VUID-{refpage}-scope-08984]]
     For code:OpCooperativeMatrixMulAddKHR, the type of code:A, code:B,
     code:C, and code:Result must: all have a scope of pname:scope.
-  * [[VUID-{refpage}-OpTypeCooperativeMatrixKHR-]]
+  * [[VUID-{refpage}-cooperativeMatrixSupportedStages-08985]]
     code:OpTypeCooperativeMatrixKHR and code:OpCooperativeMatrix*
     instructions must: not be used in shader stages not included in
     slink:VkPhysicalDeviceCooperativeMatrixPropertiesKHR::pname:cooperativeMatrixSupportedStages.
@@ -1334,7 +1334,7 @@ ifdef::VK_EXT_mesh_shader[]
     pname:maxTaskPayloadAndSharedMemorySize>>
 endif::VK_EXT_mesh_shader[]
 ifdef::VK_KHR_cooperative_matrix[]
-  * [[VUID-{refpage}-OpCooperativeMatrixLoadKHR-]]
+  * [[VUID-{refpage}-OpCooperativeMatrixLoadKHR-08986]]
     For code:OpCooperativeMatrixLoadKHR and code:OpCooperativeMatrixStoreKHR
     instructions, the code:Pointer and code:Stride operands must: be aligned
     to at least the lesser of 16 bytes or the natural alignment of a row or

chapters/VK_KHR_swapchain/wsi.adoc

@@ -1643,8 +1643,8 @@ include::{chapters}/VK_EXT_swapchain_maintenance1/SwapchainPresentModeInfo.adoc[
 include::{chapters}/VK_EXT_swapchain_maintenance1/SwapchainPresentFenceInfo.adoc[]
 endif::VK_EXT_swapchain_maintenance1[]
 
-fname:vkQueuePresentKHR releases the acquisition of the images referenced
-by pname:imageIndices.
+fname:vkQueuePresentKHR releases the acquisition of the images referenced by
+pname:imageIndices.
 The queue family corresponding to the queue fname:vkQueuePresentKHR is
 executed on must: have ownership of the presented images as defined in
 <<resources-sharing,Resource Sharing>>.

chapters/commonvalidity/access_mask_2_common.adoc

@@ -29,7 +29,7 @@
     If pname:{accessMaskName} includes
     ename:VK_ACCESS_2_INPUT_ATTACHMENT_READ_BIT, pname:{stageMaskName} must:
     include ename:VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT,
-    ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADING_BIT_HUAWEI,
+    ename:VK_PIPELINE_STAGE_2_SUBPASS_SHADER_BIT_HUAWEI,
     ename:VK_PIPELINE_STAGE_2_ALL_GRAPHICS_BIT, or
     ename:VK_PIPELINE_STAGE_2_ALL_COMMANDS_BIT
   * [[VUID-{refpage}-{accessMaskName}-03904]]