Change log for June 10, 2016 Vulkan 1.0.16 spec update:

  * Bump API patch number and header version number to 16 for this
    update.

Github Issues:

  * Clarify that integer border values are meant to be 0/1, and that
    integer texture lookups are sign-extended in the
    <<textures-format-conversion,Format Conversion>> and
    <<textures-texel-replacement,Texel Replacement>> sections (public
    issue 52).
  * Add logic to generate spec boilerplate without using the 'git'
    command-line client, needed when building from a tarball or another
    source of the Vulkan tree rather than a cloned git repo. Remove
    boilerplate as part of 'clean' target (public issue 195).
  * Document that color writes and clears to unused attachments have no
    effect for slink:VkClearAttachment and
    elink:VkColorComponentFlagBits (public issue 198).
  * Fixed flink:vkCmdExecuteCommands validity statement for
    sname:VkCommandBufferInheritanceInfo::pname:framebuffer. If used, it
    must match the framebuffer in the current renderpass instance
    (public issue 226).
  * Added valid usage language to require for all functions that set
    dynamic state that the currently bound graphics pipeline has the
    corresponding dynamic state enabled (public issue 235).

Internal Issues:

  * Clarify for flink:vkEnumerateInstanceExtensionProperties, in the
    <<extended-functionality-instance-extensions-and-devices, Instance
    Extensions and Device Extensions>> section, and in the
    <<glossary,Glossary>> section when functionality should be exposed
    as an instance extension, as a device extension, or as both
    (internal issue 109).
  * Place WorkgroupSize in alphabetical order in the
    <<interfaces-builtin-variables,Built-in Variables>> section
    (internal issue 323).
  * Corrects valid usage in vkEndRenderPass to only affect primary
    render passes, as secondaries may be entirely within a render pass,
    and should be able to be ended (previous language disallowed that)
    (internal issue 338).
  * Fix relational operator from <= to >= in the
    <<features-extentperimagetype,Allowed Extent Values>> section
    (internal issue 343).
  * Disallow recursion under SPIR-V entry points in the
    <<spirvenv-module-validation,Validation Rules within a Module>>
    section (internal SPIR-V issue 37).

Other Commits:

  * Use standard Python ElementTree package instead of lxml.etree in
    header / validation layer / include autogeneration from XML,
    reducing platform dependencies.

ChangeLog.txt

@@ -694,3 +694,61 @@ Internal Issues:
   * Update the <<sparsememory-sparse-memory-aliasing,Sparse Resource
     Implementation Guidelines>> to refer to the correct feature names
     (internal issue 305).
+
+-----------------------------------------------------
+
+Change log for June 10, 2016 Vulkan 1.0.16 spec update:
+
+  * Bump API patch number and header version number to 16 for this
+    update.
+
+Github Issues:
+
+  * Clarify that integer border values are meant to be 0/1, and that
+    integer texture lookups are sign-extended in the
+    <<textures-format-conversion,Format Conversion>> and
+    <<textures-texel-replacement,Texel Replacement>> sections (public
+    issue 52).
+  * Add logic to generate spec boilerplate without using the 'git'
+    command-line client, needed when building from a tarball or another
+    source of the Vulkan tree rather than a cloned git repo. Remove
+    boilerplate as part of 'clean' target (public issue 195).
+  * Document that color writes and clears to unused attachments have no
+    effect for slink:VkClearAttachment and
+    elink:VkColorComponentFlagBits (public issue 198).
+  * Fixed flink:vkCmdExecuteCommands validity statement for
+    sname:VkCommandBufferInheritanceInfo::pname:framebuffer. If used, it
+    must match the framebuffer in the current renderpass instance
+    (public issue 226).
+  * Added valid usage language to require for all functions that set
+    dynamic state that the currently bound graphics pipeline has the
+    corresponding dynamic state enabled (public issue 235).
+
+Internal Issues:
+
+  * Clarify for flink:vkEnumerateInstanceExtensionProperties, in the
+    <<extended-functionality-instance-extensions-and-devices, Instance
+    Extensions and Device Extensions>> section, and in the
+    <<glossary,Glossary>> section when functionality should be exposed
+    as an instance extension, as a device extension, or as both
+    (internal issue 109).
+  * Place WorkgroupSize in alphabetical order in the
+    <<interfaces-builtin-variables,Built-in Variables>> section
+    (internal issue 323).
+  * Corrects valid usage in vkEndRenderPass to only affect primary
+    render passes, as secondaries may be entirely within a render pass,
+    and should be able to be ended (previous language disallowed that)
+    (internal issue 338).
+  * Fix relational operator from <= to >= in the
+    <<features-extentperimagetype,Allowed Extent Values>> section
+    (internal issue 343).
+  * Disallow recursion under SPIR-V entry points in the
+    <<spirvenv-module-validation,Validation Rules within a Module>>
+    section (internal SPIR-V issue 37).
+
+Other Commits:
+
+  * Use standard Python ElementTree package instead of lxml.etree in
+    header / validation layer / include autogeneration from XML,
+    reducing platform dependencies.
+

doc/specs/vulkan/Makefile

@@ -91,7 +91,7 @@ DBLATEXOPTS := $(KEEP) -V -T db2latex -I. -I images -I images/icons -s $(DBLATEX
 A2XDBLATEXOPTS := --dblatex-opts='$(DBLATEXOPTS)'
 
 # Misc. files to clean up (see 'checkinc' target below)
-DIRT :=
+DIRT = $(SPECVERSION)
 
 .PHONY: directories
 
@@ -125,7 +125,7 @@ INCLUDES := $(wildcard protos/*.txt structs/*.txt flags/*.txt enums/*.txt funcpo
 COMMONDOCS := $(CHAPTERS) $(INCLUDES)
 # A generated included file with the spec version, date, and git commit
 SPECVERSION = specversion.txt
-SPECREVISION = 1.0.15
+SPECREVISION = 1.0.16
 SPECREMARK =
 
 # Spec targets
@@ -173,19 +173,27 @@ $(PDFDIR):
 	$(QUIET)if test ! -d $(PDFDIR) ; then $(MKDIR) $(PDFDIR) ; fi
 
 # Generate Asciidoc attributes for spec version / date
+GITHEAD := ../../../.git/logs/HEAD
+ifeq ($(wildcard $(GITHEAD)),)
+# If GITHEAD does not exist, don't include branch info.
+$(SPECVERSION):
+	$(QUIET)echo ":revnumber: $(SPECREVISION)" > $@
+	$(QUIET)echo ":revdate: " `date` >> $@
+	$(QUIET)echo ":revremark: Git branch information not available" >> $@
+else
 # Could use `git log -1 --format="%cd"` to get branch commit date
 # This used to be a dependency in the spec html/chunked/pdf targets,
 # but that's likely to lead to merge conflicts. Just regenerate
 # when pushing a new spec for review to the sandbox.
 # The dependency on HEAD is per the suggestion in
 # http://neugierig.org/software/blog/2014/11/binary-revisions.html
-GITHEAD := ../../../.git/logs/HEAD
 $(SPECVERSION): $(GITHEAD)
 	$(QUIET)echo ":revnumber: $(SPECREVISION)" > $@
 	$(QUIET)echo ":revdate: " `date` >> $@
 	$(QUIET)echo ":revremark: $(SPECREMARK) from git branch:" \
 	    `git symbolic-ref --short HEAD` \
 	    "commit:" `git log -1 --format="%H"` >> $@
+endif
 
 styleguide: $(OUTDIR)/styleguide.html
 

doc/specs/vulkan/appendices/glossary.txt

@@ -210,6 +210,11 @@ Device Memory::
     Memory accessible to the device. Represented by a sname:VkDeviceMemory
     object.
 
+Device-Level Object::
+    Logical device objects and their child objects For example,
+    sname:VkDevice, sname:VkQueue, and sname:VkCommandBuffer objects are
+    device-level objects.
+
 Device-Local Memory::
     Memory that is connected to the device, and may: be more performant for
     device access than host-local memory.
@@ -406,6 +411,11 @@ Instance::
     connection to the implementation. Represented by a sname:VkInstance
     object.
 
+Instance-Level Object::
+    High-level Vulkan objects, which are not logical devices, nor children
+    of logical devices.  For example, sname:VkInstance and
+    sname:VkPhysicalDevice objects are instance-level objects.
+
 Internal Synchronization::
     A type of synchronization required of the implementation, where
     parameters not defined to be externally synchronized may: require

doc/specs/vulkan/appendices/spirvenv.txt

@@ -92,6 +92,7 @@ A SPIR-V module passed to flink:vkCreateShaderModule must: conform to the
 following rules:
 
   * Every entry point must: have no return value and accept no arguments.
+  * Recursion: The static function-call graph for an entry point must not contain cycles.
   * The *Logical* addressing model must: be selected.
   * *Scope* for execution must: be limited to:
   ** *Workgroup*

doc/specs/vulkan/chapters/clears.txt

@@ -120,20 +120,24 @@ include::../structs/VkClearAttachment.txt[]
     ename:VK_IMAGE_ASPECT_COLOR_BIT for color attachments,
     ename:VK_IMAGE_ASPECT_DEPTH_BIT for depth/stencil attachments with a
     depth component, and ename:VK_IMAGE_ASPECT_STENCIL_BIT for depth/stencil
-    attachments with a stencil component.
+    attachments with a stencil component. If the subpass's depth/stencil
+    attachment is ename:VK_ATTACHMENT_UNUSED, then the clear has no effect.
   * pname:colorAttachment is only meaningful if
     ename:VK_IMAGE_ASPECT_COLOR_BIT is set in pname:aspectMask, in which
     case it is an index to the pname:pColorAttachments array in the
     slink:VkSubpassDescription structure of the current subpass which
-    selects the color attachment to clear.
+    selects the color attachment to clear. If pname:colorAttachment is
+    ename:VK_ATTACHMENT_UNUSED or is greater than or equal to
+    sname:VkSubpassDescription::pname:colorAttachmentCount, then the clear has
+    no effect.
   * pname:clearValue is the color or depth/stencil value to clear the
     attachment to, as described in <<clears-values,Clear Values>> below.
 
 No memory barriers are needed between fname:vkCmdClearAttachments and
 preceding or subsequent draw or attachment clear commands in the same
 subpass.
 
-The fname:vkCmdClearAttachments commands is not affected by the bound
+The fname:vkCmdClearAttachments command is not affected by the bound
 pipeline state.
 
 Attachments can: also be cleared at the beginning of a render pass instance

doc/specs/vulkan/chapters/extensions.txt

@@ -189,6 +189,10 @@ To enable an instance extension, the name of the extension should be added to
 the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo when
 creating a sname:VkInstance.
 
+Enabling an extension does not change behavior of functionality exposed by
+the core Vulkan API or any other extension, other than making valid the use
+of the commands, enums and structures defined by that extension.
+
 To query the extensions available to a given physical device, call:
 
 include::../protos/vkEnumerateDeviceExtensionProperties.txt[]
@@ -231,3 +235,69 @@ include::../structs/VkExtensionProperties.txt[]
     incremented with backward compatible changes.
 
 include::../validity/structs/VkExtensionProperties.txt[]
+
+[[extended-functionality-instance-extensions-and-devices]]
+=== Instance Extensions and Device Extensions
+
+Because an instance extension can affect the operation of an instance and
+any of its child objects, the decision to expose functionality as an instance
+extension or as a device extension is not always clear.
+This section provides some guidelines and rules for when to expose new
+functionality as an instance extension, device extension, or both.
+
+The decision is influenced by whether extension functionality affects
+instance-level objects (e.g. instances and physical devices) and commands,
+or device-level objects (e.g. logical devices, queues, and command buffers)
+and commands, or both.
+
+In some cases, the decision is clear:
+
+* Functionality that is restricted to the instance-level must: be
+implemented as an instance extension.
+* Functionality that is restricted to the device-level must: be
+implemented as an device extension.
+
+In other cases, the decision is not so clear:
+
+* Global functionality that affects the entire Vulkan API, including
+instance and device-level objects and commands, should: be an instance
+extension.
+* Device-level functionality that contains physical-device queries, can: be
+implemented as an instance extension.
+If some part of an instance extension's functionality might not be available
+on all physical devices, the extension should: provide a query to determine
+which physical devices provide the functionality.
+* For a set of global functionality that provides new instance-level and
+device-level commands, and can: be enabled for a subset of devices, it is
+recommended that the functionality be partitioned across two extensions--one
+for the instance-level functionality, and one for the device-specific
+functionality.
+In this latter case, it is generally recommended that the two extensions have
+unique names.
+
+Examples of instance extensions include:
+
+* Logging of debug messages by any enabled layers for all Vulkan commands.
+* Functionality creating new objects which are direct children of an instance.
+* Functionality creating new objects which are direct children of a
+physical device and intended to work with any logical device created
+from the physical device.
+* Functionality adding new instance-level Vulkan commands that do not affect
+any device-level commands.
+
+[NOTE]
+.Note
+====
+Instance extensions generally require support in the Vulkan loader.
+This is especially true for commands that are dispatched from
+instances and physical devices.
+Additional information about supporting instance-level commands may be found
+in the "Vulkan Loader Specification and Architecture Overview" document,
+which may be found at the following web page:
+
+* https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/sdk-1.0.13/loader/LoaderAndLayerInterface.md
+
+Please see the "Architectural overview of layers and loader" section for
+information about how both instance-level and device-level commands are
+supported and dispatched.
+====

doc/specs/vulkan/chapters/features.txt

@@ -3737,24 +3737,24 @@ pname:format, pname:type, and pname:tiling.
 
 For ename:VK_IMAGE_TYPE_1D:
 
-  * pname:maxExtent.width >=
+  * pname:maxExtent.width <=
     slink:VkPhysicalDeviceLimits::pname:maxImageDimension1D
   * pname:maxExtent.height = 1
   * pname:maxExtent.depth = 1
 
 For ename:VK_IMAGE_TYPE_2D:
 
-  * pname:maxExtent.width >=
+  * pname:maxExtent.width <=
     slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D
-  * pname:maxExtent.height >=
+  * pname:maxExtent.height <=
     slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D
   * pname:maxExtent.depth = 1
 
 For ename:VK_IMAGE_TYPE_3D:
 
-  * pname:maxExtent.width >=
+  * pname:maxExtent.width <=
     slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D
-  * pname:maxExtent.height >=
+  * pname:maxExtent.height <=
     slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D
-  * pname:maxExtent.depth >=
+  * pname:maxExtent.depth <=
     slink:VkPhysicalDeviceLimits::pname:maxImageDimension3D

doc/specs/vulkan/chapters/framebuffer.txt

@@ -300,6 +300,10 @@ the resulting latexmath:[$c_s$] values for R, G and B are unmodified. The
 value of A is never sRGB encoded. That is, the alpha component is always
 stored in memory as linear.
 
+If the framebuffer color attachment is ename:VK_ATTACHMENT_UNUSED, no writes
+are performed through that attachment. Framebuffer color attachments greater
+than or equal to sname:VkSubpassDescription::pname:colorAttachmentCount
+perform no writes.
 
 [[framebuffer-logicop]]
 == Logical Operations

doc/specs/vulkan/chapters/interfaces.txt

@@ -927,22 +927,6 @@ The code:NumWorkgroups decoration must: be used only within compute shaders.
 code:NumWorkgroups must: be declared as a three-component vector of 32-bit
 integers.
 
-code:WorkgroupSize::
-
-The code:WorkgroupSize decoration can: be applied to declare an object
-representing the dimensions of a local workgroup in a compute shader. If this
-is done, it must: be applied to a code:uvec3 specialization constant or a
-code:uvec3 constant.
-+
-If a specialization constant or a constant is decorated with the
-code:WorkgroupSize decoration, this must: take precedence over any execution
-mode set for code:LocalSize.
-+
-The code:WorkgroupSize decoration must: be used only within compute shaders.
-+
-code:WorkgroupSize must: be declared as a three-component vector of 32-bit
-integers.
-
 code:PatchVertices::
 
 An input variable decorated with code:PatchVertices in the tessellation
@@ -1208,3 +1192,19 @@ The code:WorkgroupId decoration must: be used only within compute shaders.
 +
 code:WorkgroupId must: be declared as a three-component vector of 32-bit
 integers.
+
+code:WorkgroupSize::
+
+The code:WorkgroupSize decoration can: be applied to declare an object
+representing the dimensions of a local workgroup in a compute shader. If this
+is done, it must: be applied to a code:uvec3 specialization constant or a
+code:uvec3 constant.
++
+If a specialization constant or a constant is decorated with the
+code:WorkgroupSize decoration, this must: take precedence over any execution
+mode set for code:LocalSize.
++
+The code:WorkgroupSize decoration must: be used only within compute shaders.
++
+code:WorkgroupSize must: be declared as a three-component vector of 32-bit
+integers.

doc/specs/vulkan/chapters/shaders.txt

@@ -53,7 +53,7 @@ include::../protos/vkCreateShaderModule.txt[]
   * pname:pAllocator controls host memory allocation as described in the
     <<memory-allocation, Memory Allocation>> chapter.
   * pname:pShaderModule points to a sname:VkShaderModule handle in which the
-    resulting render pass object is returned.
+    resulting shader module object is returned.
 
 include::../validity/protos/vkCreateShaderModule.txt[]
 

doc/specs/vulkan/chapters/textures.txt

@@ -527,7 +527,8 @@ elink:VkFormat), using the appropriate equations in
 <<fundamentals-fp11,Unsigned 11-Bit Floating-Point Numbers>>,
 <<fundamentals-fp10,Unsigned 10-Bit Floating-Point Numbers>>,
 <<fundamentals-fixedconv,Fixed-Point Data Conversion>>, and
-<<textures-sexp-RGB,Shared Exponent to RGB>>.
+<<textures-sexp-RGB,Shared Exponent to RGB>>. Signed integer components
+smaller than 32 bits are sign-extended.
 
 If the image format is sRGB, the color components are first converted as if
 they are UNORM, and then sRGB to linear conversion is applied to the R, G,
@@ -565,6 +566,15 @@ pname:borderColor of the sampler. The border color is:
 | ename:VK_BORDER_COLOR_INT_OPAQUE_WHITE        | latexmath:[$B = (1, 1, 1, 1)$]
 |====
 
+[NOTE]
+.Note
+====
+The names etext:TRANSPARENT_BLACK, etext:OPAQUE_BLACK, and etext:OPAQUE_WHITE
+are meant to describe which components are zeros and ones in the vocabulary of
+compositing, and are not meant to imply that the numerical value of
+etext:WHITE is a saturating value for integers.
+====
+
 This is substituted for the texel value by replacing the number of components
 in the image format
 

doc/specs/vulkan/validity/protos/vkCmdExecuteCommands.txt

@@ -23,7 +23,7 @@ endif::doctype-manpage[]
 * If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with the ename:VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT
 * If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:subpass set to the index of the subpass which the given command buffer will be executed in
 * If fname:vkCmdExecuteCommands is being called within a render pass instance, any given element of pname:pCommandBuffers must: have been recorded with a render pass that is compatible with the current render pass - see <<renderpass-compatibility>>
-* If fname:vkCmdExecuteCommands is being called within a render pass instance, and any given element of pname:pCommandBuffers was recorded with sname:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to sname:VK_NULL_HANDLE, that sname:VkFramebuffer must: be compatible with the sname:VkFramebuffer used in the current render pass instance
+* If fname:vkCmdExecuteCommands is being called within a render pass instance, and any given element of pname:pCommandBuffers was recorded with sname:VkCommandBufferInheritanceInfo::pname:framebuffer not equal to sname:VK_NULL_HANDLE, that sname:VkFramebuffer must: match the sname:VkFramebuffer used in the current render pass instance
 * If the <<features-features-inheritedQueries,inherited queries>> feature is not enabled, pname:commandBuffer mustnot: have any queries <<queries-operation-active,active>>
 * If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query <<queries-operation-active,active>>, then each element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:occlusionQueryEnable set to ename:VK_TRUE
 * If pname:commandBuffer has a ename:VK_QUERY_TYPE_OCCLUSION query <<queries-operation-active,active>>, then each element of pname:pCommandBuffers must: have been recorded with sname:VkCommandBufferInheritanceInfo::pname:queryFlags having all bits set that are set for the query

doc/specs/vulkan/validity/protos/vkCmdSetBlendConstants.txt

@@ -10,6 +10,7 @@ endif::doctype-manpage[]
 * pname:commandBuffer must: be a valid sname:VkCommandBuffer handle
 * pname:commandBuffer must: be in the recording state
 * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations
+* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS dynamic state enabled
 ifndef::doctype-manpage[]
 ********************************************************************************
 endif::doctype-manpage[]

doc/specs/vulkan/validity/protos/vkCmdSetDepthBias.txt

@@ -10,6 +10,7 @@ endif::doctype-manpage[]
 * pname:commandBuffer must: be a valid sname:VkCommandBuffer handle
 * pname:commandBuffer must: be in the recording state
 * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations
+* The currently bound graphics pipeline must: have been created with the ename:VK_DYNAMIC_STATE_DEPTH_BIAS dynamic state enabled
 * If the <<features-features-depthBiasClamp,depth bias clamping>> feature is not enabled, pname:depthBiasClamp must: be code:0.0
 ifndef::doctype-manpage[]
 ********************************************************************************