Change log for April 16, 2020 Vulkan 1.2.138 spec update:

  * Update release number to 138 for this update.

Github Issues:

  * Use correctly tagged normative term macros in various places (public
    pull request 1217).
  * Fix C arrow markup in parameter descriptions (public pull request 1222).

Internal Issues:

  * Add language to the <<features-requirements, Feature Requirements>>
    section, the <<versions, Core Revisions>> appendix, and the applicable
    extensions to require major feature bits if the corresponding extension
    is supported (internal issue 1961).
  * Allow slink:VkAccelerationStructureCreateInfoKHR::pname:maxGeometryCount
    = 0, and clarify that exactly one of pname:compactedSize and
    pname:maxGeometryCount must: be zero. (internal issue 2079).
  * Add `allowduplicate` attribute to XML `type` tags to enable future
    structures which can allow multiple copies of a structure in their
    pname:pNext chain (internal issue 2090).
  * Add the glossary term "`format features`", and make minor clarifications
    to uses of this term in several places in the <<resources, Resource
    Creation>> chapter and the
    <<resources-sampler-ycbcr-conversion-format-features, Sampler Ycbcr
    Conversion Format Features>> section (internal merge request 3727).
  * Add a constraint to the <<memory-external-android-hardware-buffer,
    Android Hardware Buffer>> section requiring that bound slink:VkImage or
    slink:VkBuffer objects be created with the
    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
    flag set, and corresponding valid usage statements to
    flink:vkBindBufferMemory, slink:VkBindBufferMemoryInfo,
    flink:vkBindImageMemory, and slink:VkBindImageMemoryInfo (internal merge
    request 3732).
  * Fix pname:memoryTypes ordering description for device coherent memory
    (ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD) in the
    <<memory-device-bitmask-list>> section (internal merge request 3738).
  * Replace code:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT with
    code:AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER in the
    <<memory-external-android-hardware-buffer-usage, AHardwareBuffer Usage
    Equivalence>> table, and add
    ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT flag for this case
    (internal merge request 3741).
  * Add more references to `NV` and `KHR` ray tracing pipelines in
    discussions of creating pipelines, or generalize text so they need not
    all be mentioned by name (internal merge request 3743).
  * Allow *ShaderCallKHR* memory scope in ray tracing shaders, in the
    <<spirvenv-module-validation, Validation Rules within a Module>>
    appendix (internal merge request 3744).
  * Use Khronos Dockerhub image for spec builds in internal CI (internal
    merge request 3748).
  * Add the `<<VK_KHR_dedicated_allocation>>` extension as a dependency of
    `<<VK_ANDROID_external_memory_android_hardware_buffer>>` (internal merge
    request 3751).

.gitlab-ci.yml

@@ -1,23 +1,18 @@
 # Gitlab CI file for vulkan spec and header generation
 
-image: ruby:2.7
+# All stages use the same Docker image, so there are no prerequisites
+image: khronosgroup/docker-images:vulkan-docs
 
 # Build the vulkan specification and generate any associated files (such as vulkan.h)
 spec-generate:
   stage: build
   before_script:
-    # Add Node.js to the apt registry
-    - curl -sL https://deb.nodesource.com/setup_12.x | bash -
-    - apt-get update -qq
-    - apt-get install -y -qq --no-install-recommends bash bison build-essential cmake flex fonts-lyx clang gcc ghostscript git gosu g++ jing libavalon-framework-java libbatik-java libcairo2-dev libffi-dev libgdk-pixbuf2.0-dev libpango1.0-dev libreadline-dev libxml2-dev nodejs pdftk poppler-utils python3 python3-pytest python3-termcolor tcsh
-    - apt-get clean
-    - gem install asciidoctor asciidoctor-diagram asciidoctor-mathematical asciidoctor-pdf coderay json-schema i18n
-    - npm install -g escape-string-regexp he [email protected]
+    # Nothing, all prerequisites are in the Docker image
   script:
     - NODE_PATH="/usr/lib/node_modules"
     - export NODE_PATH
     # Internal self-test of the check_spec_links script
-    - ( cd scripts && py.test-3 test*.py && echo "${NODE_PATH}" )
+    - ( cd scripts && py.test-3 test*.py )
     - mkdir -p out/checks
     - scripts/check_spec_links.py --html=out/checks/problems.html > /dev/null || true
     # Breaking the build if # of errors increases. We should manually ratchet ignore_count down as errors get fixed.
@@ -26,8 +21,8 @@ spec-generate:
     # errors" but simpler than the alternatives (running against master,
     # diff, etc)
     - scripts/check_spec_links.py -Werror --ignore_count 0
-    # Build the actual spec
-    - ./makeAllExts QUIET= -j${nproc} -Otarget validusage html styleguide registry manhtmlpages
+    # Build the actual spec, and other common targets
+    - ./makeAllExts QUIET= -j${nproc} -Otarget manhtmlpages validusage styleguide registry html  > out/ERRS.QUIET=.all  2>&1
     # Build headers, for use by all later stages
     - ( cd xml && make validate test install )
   artifacts:
@@ -36,15 +31,14 @@ spec-generate:
       - include/
       - src/
       - out/
-    expire_in: 1 month
+      - gen/meta/
+    expire_in: 1 week
 
 # Generate the vulkan C++ header (vulkan.hpp)
 hpp-generate:
   stage: build
   before_script:
     - SPEC_DIR="${PWD}"
-    - apt-get update -qq
-    - apt-get install -y -qq --no-install-recommends cmake git g++
     - cd /tmp
     - rm -rf Vulkan-Hpp
     - git clone https://github.com/KhronosGroup/Vulkan-Hpp.git
@@ -66,22 +60,21 @@ hpp-generate:
   artifacts:
     paths:
       - Vulkan-Hpp/vulkan/
-    expire_in: 1 month
+    expire_in: 1 week
   allow_failure: true
 
 # Compile a simple test program that uses vulkan.h
 # The fake platform headers in tests/ allow compiling with all Vulkan
 # platforms at once.
 h-compile:
-    stage: test
-    dependencies:
-      - spec-generate
-    before_script:
-      - apt-get update -qq
-      - apt-get install -y -qq gcc clang
-    script:
-      - gcc -c -std=c11 -Iinclude -Itests -Wall -Wextra -Werror tests/htest.c
-      - clang -c -std=c11 -Iinclude -Itests -Wall -Wextra -Werror tests/htest.c
+  stage: test
+  dependencies:
+    - spec-generate
+  before_script:
+  # Nothing, all prerequisites are in the Docker image
+  script:
+    - gcc -c -std=c11 -Iinclude -Itests -Wall -Wextra -Werror tests/htest.c
+    - clang -c -std=c11 -Iinclude -Itests -Wall -Wextra -Werror tests/htest.c
 
 # Compile a simple test program that uses vulkan.hpp
 hpp-compile:
@@ -90,8 +83,7 @@ hpp-compile:
     - spec-generate
     - hpp-generate
   before_script:
-    - apt-get update -qq
-    - apt-get install -y -qq g++ clang
+    # Nothing, all prerequisites are in the Docker image
   script:
     - g++ -c -std=c++11 -Iinclude -IVulkan-Hpp -Wall -Wextra -Werror tests/hpptest.cpp
     - clang++ -c -std=c++11 -Iinclude -IVulkan-Hpp -Wall -Wextra -Werror tests/hpptest.cpp

ChangeLog.txt

@@ -8,6 +8,64 @@ public pull requests that have been accepted.
 
 -----------------------------------------------------
 
+Change log for April 16, 2020 Vulkan 1.2.138 spec update:
+
+  * Update release number to 138 for this update.
+
+Github Issues:
+
+  * Use correctly tagged normative term macros in various places (public
+    pull request 1217).
+  * Fix C arrow markup in parameter descriptions (public pull request 1222).
+
+Internal Issues:
+
+  * Add language to the <<features-requirements, Feature Requirements>>
+    section, the <<versions, Core Revisions>> appendix, and the applicable
+    extensions to require major feature bits if the corresponding extension
+    is supported (internal issue 1961).
+  * Allow slink:VkAccelerationStructureCreateInfoKHR::pname:maxGeometryCount
+    = 0, and clarify that exactly one of pname:compactedSize and
+    pname:maxGeometryCount must: be zero. (internal issue 2079).
+  * Add `allowduplicate` attribute to XML `type` tags to enable future
+    structures which can allow multiple copies of a structure in their
+    pname:pNext chain (internal issue 2090).
+  * Add the glossary term "`format features`", and make minor clarifications
+    to uses of this term in several places in the <<resources, Resource
+    Creation>> chapter and the
+    <<resources-sampler-ycbcr-conversion-format-features, Sampler Ycbcr
+    Conversion Format Features>> section (internal merge request 3727).
+  * Add a constraint to the <<memory-external-android-hardware-buffer,
+    Android Hardware Buffer>> section requiring that bound slink:VkImage or
+    slink:VkBuffer objects be created with the
+    ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
+    flag set, and corresponding valid usage statements to
+    flink:vkBindBufferMemory, slink:VkBindBufferMemoryInfo,
+    flink:vkBindImageMemory, and slink:VkBindImageMemoryInfo (internal merge
+    request 3732).
+  * Fix pname:memoryTypes ordering description for device coherent memory
+    (ename:VK_MEMORY_PROPERTY_DEVICE_UNCACHED_BIT_AMD) in the
+    <<memory-device-bitmask-list>> section (internal merge request 3738).
+  * Replace code:AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT with
+    code:AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER in the
+    <<memory-external-android-hardware-buffer-usage, AHardwareBuffer Usage
+    Equivalence>> table, and add
+    ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT flag for this case
+    (internal merge request 3741).
+  * Add more references to `NV` and `KHR` ray tracing pipelines in
+    discussions of creating pipelines, or generalize text so they need not
+    all be mentioned by name (internal merge request 3743).
+  * Allow *ShaderCallKHR* memory scope in ray tracing shaders, in the
+    <<spirvenv-module-validation, Validation Rules within a Module>>
+    appendix (internal merge request 3744).
+  * Use Khronos Dockerhub image for spec builds in internal CI (internal
+    merge request 3748).
+  * Add the `<<VK_KHR_dedicated_allocation>>` extension as a dependency of
+    `<<VK_ANDROID_external_memory_android_hardware_buffer>>` (internal merge
+    request 3751).
+
+-----------------------------------------------------
+
 Change log for April 06, 2020 Vulkan 1.2.137 spec update:
 
   * Update release number to 137 for this update.

Makefile

@@ -21,7 +21,7 @@
 # VK_VERSION_1_0). $(VERSIONS) is converted into asciidoc and generator
 # script arguments $(VERSIONATTRIBS) and $(VERSIONOPTIONS)
 #
-# To build the specification and reference pages with optional
+# To build the specification / reference pages (refpages) with optional
 # extensions included, set the $(EXTENSIONS) variable on the make
 # command line to a space-separated list of extension names.
 # $(EXTENSIONS) is converted into asciidoc and generator script
@@ -56,7 +56,7 @@ IMAGEOPTS = inline
 #  registry - HTML5 single-page XML Registry Schema documentation
 #  manhtml - HTML5 single-page reference guide - NOT SUPPORTED
 #  manpdf - PDF reference guide - NOT SUPPORTED
-#  manhtmlpages - HTML5 separate per-feature reference pages
+#  manhtmlpages - HTML5 separate per-feature refpages
 #  allchecks - Python sanity checker for script markup and macro use
 
 all: alldocs allchecks
@@ -119,7 +119,7 @@ VERBOSE =
 # ADOCOPTS options for asciidoc->HTML5 output
 
 NOTEOPTS     = -a editing-notes -a implementation-guide
-PATCHVERSION = 137
+PATCHVERSION = 138
 ifneq (,$(findstring VK_VERSION_1_2,$(VERSIONS)))
 SPECREVISION = 1.2.$(PATCHVERSION)
 else
@@ -364,9 +364,9 @@ MANSECTION  := 3
 # These lists should be autogenerated
 
 # Ref page sources, split up by core API (CORE), KHR extensions (KHR), and
-# other extensions (VEN). This is a hacky approach to ref page generation
+# other extensions (VEN). This is a hacky approach to refpage generation
 # now that the single-branch model is in place, and there are outstanding
-# issues to resolve it. For now, always build all reference pages.
+# issues to resolve it. For now, always build all refpages.
 # Changing MANSOURCES to e.g. $(CORESOURCES) will restore older behavior.
 
 KHRSOURCES   = $(wildcard $(MANDIR)/*KHR.txt)
@@ -376,21 +376,21 @@ CORESOURCES  = $(filter-out $(KHRSOURCES) $(VENSOURCES),$(wildcard $(MANDIR)/[Vv
 MANSOURCES   = $(wildcard $(MANDIR)/[Vv][Kk]*.txt $(MANDIR)/PFN*.txt)
 MANCOPYRIGHT = $(MANDIR)/copyright-ccby.txt $(MANDIR)/footer.txt
 
-# Generation of ref page asciidoctor sources by extraction from the
+# Generation of refpage asciidoctor sources by extraction from the
 # specification.
 #
 # Should have a proper dependency causing the man page sources to be
 # generated by running genRef (once), but adding $(MANSOURCES) to the
 # targets causes genRef to run once/target.
 #
 # Should pass in $(EXTOPTIONS) to determine which pages to generate.
-# For now, all core and extension ref pages are extracted by genRef.py.
+# For now, all core and extension refpages are extracted by genRef.py.
 GENREF = $(SCRIPTS)/genRef.py
 LOGFILE = man/logfile
 man/apispec.txt: $(SPECFILES) $(GENREF) $(SCRIPTS)/reflib.py $(SCRIPTS)/vkapi.py
 	$(PYTHON) $(GENREF) -log $(LOGFILE) -extpath $(CURDIR)/appendices $(EXTOPTIONS) $(SPECFILES)
 
-# These targets are HTML5 ref pages
+# These targets are HTML5 refpages
 #
 # The recursive $(MAKE) is an apparently unavoidable hack, since the
 # actual list of man page sources isn't known until after
@@ -405,11 +405,13 @@ manhtmlpages: man/apispec.txt $(GENDEPENDS)
 	$(QUIET) echo $(ASCIIDOC) -b html5 $(ADOCOPTS) $(ADOCHTMLOPTS) $(ADOCREFOPTS) -d manpage -o REFPAGE.html REFPAGE.txt
 	$(MAKE) $(SUBMAKEOPTIONS) -e buildmanpages
 
+# Build the individual refpages, then the symbolic links from aliases
 MANHTMLDIR  = $(OUTDIR)/man/html
 MANHTML     = $(MANSOURCES:$(MANDIR)/%.txt=$(MANHTMLDIR)/%.html)
-buildmanpages: $(MANHTML) manaliases
+buildmanpages: $(MANHTML)
+	$(MAKE) $(SUBMAKEOPTIONS) -e manaliases
 
-# Asciidoctor options to build reference pages
+# Asciidoctor options to build refpages
 #
 # ADOCREFOPTS *must* be placed after ADOCOPTS in the command line, so
 # that it can override spec attribute values.
@@ -434,8 +436,8 @@ $(MANHTMLDIR)/%.html: $(MANDIR)/%.txt $(MANCOPYRIGHT) $(GENDEPENDS) katexinst
 	fi
 
 # The 'manhtml' and 'manpdf' targets are NO LONGER SUPPORTED by Khronos.
-# They generate HTML5 and PDF single-file versions of the ref pages.
-# The generated ref page sources are included by man/apispec.txt, and
+# They generate HTML5 and PDF single-file versions of the refpages.
+# The generated refpage sources are included by man/apispec.txt, and
 # are always generated along with man/apispec.txt. Therefore there's no
 # need for a recursive $(MAKE) or a $(MANHTML) dependency, unlike the
 # manhtmlpages target.

appendices/VK_KHR_buffer_device_address.txt

@@ -94,6 +94,8 @@ None
 
 All functionality in this extension is included in core Vulkan 1.2, with the
 KHR suffix omitted.
+However, if Vulkan 1.2 is supported and this extension is not, the
+code:bufferDeviceAddress capability is optional.
 The original type, enum and command names are still available as aliases of
 the core functionality.
 

appendices/VK_KHR_sampler_ycbcr_conversion.txt

@@ -123,6 +123,8 @@ bind memory to the planes of an image collectively or separately.
 
 All functionality in this extension is included in core Vulkan 1.1, with the
 KHR suffix omitted.
+However, if Vulkan 1.1 is supported and this extension is not, the
+code:samplerYcbcrConversion capability is optional.
 The original type, enum and command names are still available as aliases of
 the core functionality.
 

appendices/VK_KHR_shader_atomic_int64.txt

@@ -48,6 +48,8 @@ OpAtomicCompareExchange.
 
 All functionality in this extension is included in core Vulkan 1.2, with the
 KHR suffix omitted.
+However, if Vulkan 1.2 is supported and this extension is not, the
+code:shaderBufferInt64Atomics capability is optional.
 The original type, enum and command names are still available as aliases of
 the core functionality.
 

appendices/VK_KHR_shader_float16_int8.txt

@@ -56,6 +56,8 @@ output interfaces>> and therefore does not supersede the
 
 All functionality in this extension is included in core Vulkan 1.2, with the
 KHR suffix omitted.
+However, if Vulkan 1.2 is supported and this extension is not, both the
+code:shaderFloat16 and code:shaderInt8 capabilities are optional.
 The original type, enum and command names are still available as aliases of
 the core functionality.
 

appendices/VK_KHR_vulkan_memory_model.txt

@@ -55,6 +55,8 @@ change from version 2.
 
 All functionality in this extension is included in core Vulkan 1.2, with the
 KHR suffix omitted.
+However, if Vulkan 1.2 is supported and this extension is not, the
+code:vulkanMemoryModel capability is optional.
 The original type, enum and command names are still available as aliases of
 the core functionality.
 

appendices/glossary.txt

@@ -564,6 +564,11 @@ Flat Shading::
     primitive, and for interpolation of that attribute to return that single
     value unaltered.
 
+Format Features::
+    A set of features from elink:VkFormatFeatureFlagBits that a
+    elink:VkFormat is capable of using for various commands.
+    The list is determined by factors such as elink:VkImageTiling.
+
 Fragment::
     A rectangular framebuffer region with associated data produced by
     <<primsrast,rasterization>> and processed by <<fragops,fragment

appendices/spirvenv.txt

@@ -628,6 +628,12 @@ ifdef::VK_NV_mesh_shader[]
       task, mesh, and
 endif::VK_NV_mesh_shader[]
       compute execution model(s).
+ifdef::VK_KHR_ray_tracing[]
+  ** *ShaderCallKHR*
+  *** The *ShaderCallKHR* scope must: only be used in the ray generation,
+      intersection, closest hit, any-hit, miss, and callable execution
+      models.
+endif::VK_KHR_ray_tracing[]
 ifdef::VK_VERSION_1_1[]
   ** *Subgroup*
 endif::VK_VERSION_1_1[]
@@ -1112,8 +1118,8 @@ ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing[]
     any-hit, or closest hit shaders.
   * code:CallableDataKHR storage class must: only be used in ray generation,
     closest hit, miss, and callable shaders.
-  * code:IncomingCallableDataKHR storage class must: only be used in callable
-    shaders.
+  * code:IncomingCallableDataKHR storage class must: only be used in
+    callable shaders.
 endif::VK_NV_ray_tracing,VK_KHR_ray_tracing[]
 ifdef::VK_VERSION_1_2,VK_VERSION_1_1,VK_KHR_variable_pointers,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[]
   * The code:Base operand of code:OpPtrAccessChain must: point to one of the

appendices/versions.txt

@@ -89,6 +89,43 @@ slink:VkPhysicalDeviceVulkan12Features::pname:shaderOutputViewportIndex and
 slink:VkPhysicalDeviceVulkan12Features::pname:shaderOutputLayer when queried
 via flink:vkGetPhysicalDeviceFeatures2.
 
+=== Differences relative to `VK_KHR_buffer_device_address`
+
+If the `<<VK_KHR_buffer_device_address>>` extension is not supported,
+support for the <<features-bufferDeviceAddress,bufferDeviceAddress>> feature
+is optional.
+Support for this feature is defined by
+slink:VkPhysicalDeviceVulkan12Features::pname:bufferDeviceAddress when
+queried via flink:vkGetPhysicalDeviceFeatures2.
+
+=== Differences relative to `VK_KHR_shader_atomic_int64`
+
+If the `<<VK_KHR_shader_atomic_int64>>` extension is not supported, support
+for the <<features-shaderBufferInt64Atomics,shaderBufferInt64Atomics>>
+feature is optional.
+Support for this feature is defined by
+slink:VkPhysicalDeviceVulkan12Features::pname:shaderBufferInt64Atomics when
+queried via flink:vkGetPhysicalDeviceFeatures2.
+
+=== Differences relative to `VK_KHR_shader_float16_int8`
+
+If the `<<VK_KHR_shader_float16_int8>>` extension is not supported, support
+for at least one of <<features-shaderFloat16,shaderFloat16>> and
+<<features-shaderInt8,shaderInt8>> feature is optional.
+Support for these features are defined by
+slink:VkPhysicalDeviceVulkan12Features::pname:shaderFloat16 and
+slink:VkPhysicalDeviceVulkan12Features::pname:shaderInt8 when queried via
+flink:vkGetPhysicalDeviceFeatures2.
+
+=== Differences relative to `VK_KHR_vulkan_memory_model`
+
+If the `<<VK_KHR_vulkan_memory_model>>` extension is not supported, support
+for the <<features-vulkanMemoryModel,vulkanMemoryModel>> feature is
+optional.
+Support for this feature is defined by
+slink:VkPhysicalDeviceVulkan12Features::pname:vulkanMemoryModel when queried
+via flink:vkGetPhysicalDeviceFeatures2.
+
 === Additional Vulkan 1.2 Feature Support
 
 [[versions-1.2-new-features]]
@@ -260,6 +297,15 @@ operations>> with <<shaders-scope-subgroup, subgroup scope>>,
 <<memory-protected-memory, protected memory>>, and a new command to
 <<vkEnumerateInstanceVersion, enumerate the instance version>>.
 
+=== Differences relative to `VK_KHR_sampler_ycbcr_conversion`
+
+If the `<<VK_KHR_sampler_ycbcr_conversion>>` extension is not supported,
+support for the <<features-samplerYcbcrConversion,samplerYcbcrConversion>>
+feature is optional.
+Support for this feature is defined by
+slink:VkPhysicalDeviceVulkan11Features::pname:samplerYcbcrConversion when
+queried via flink:vkGetPhysicalDeviceFeatures2.
+
 === New Object Types
 
   * slink:VkDescriptorUpdateTemplate