Change log for April 1, 2016 Vulkan 1.0.8 spec update:

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

Github Issues:

  * Specify in the validity language for flink:vkBeginCommandBuffer that
    pname:commandBuffer mustnot: currently be pending execution (public
    issue 96).
  * Describe depth comparison using the correct temporary variable names
    in the <<textures-depth-compare-operation,Depth Compare Operation>>
    section (public issue 100).
  * Clarify the order of descriptor update operations in the
    flink:vkUpdateDescriptorSets command (public issue 115).
  * Specify in the VK_KHR_swapchain extension that
    flink:vkAcquireNextImageKHR's pname:semaphore and pname:fence
    parameters cannot both be sname:VK_NULL_HANDLE (partly addresses,
    but does not fully close, public issue 117 / internal issue 246).
  * Change reference to the "lifetime" of a Vulkan command to
    "duration", and define the "duration" term (public issue 135).
  * Added valid usage language for slink:VkImageLayout to require both
    pname:height and pname:depth to be 1 for 1D images and pname:depth
    to be 1 for 2D images (public issue 137).
  * Fix SPIR-V example code in the
    <<descriptorsets-inputattachment,Input Attachment>> section to
    properly decorate the code:InputAttachmentIndex (public issue 139).
  * Fix reference to nonexistent pname:imageInfo in the description of
    flink:VkWriteDescriptorSet to refer to pname:pImageInfo (public
    issue 140).

Internal Issues:

  * Link to the fixed-function vertex chapter from the drawing chapter
    (internal issue flutter#110)
  * Fix typo in slink:VkImageCreateInfo validity language:
    ptext:maxExtent.sampleCounts -> pname:sampleCounts (internal issue
    249).
  * Explain why the non-core token etext:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
    is used in the example in the
    <<synchronization-semaphores,Semaphores>> section (internal issue
    251).
  * Attempt to clarify in the VK_KHR_android_surface extension's
    <<platformQuerySupport_android,Android Platform Support>> section
    that there is no Android-specific WSI query, and why (internal issue
    252).

Other Commits:

  * Add missing language about ename:VK_INCOMPLETE being returned from
    array queries when the passed array is too short, in the
    VK_KHR_display, VK_KHR_swapchain, and VK_KHR_surface extensions.

Author: oddhack

ChangeLog.txt

@@ -359,3 +359,58 @@ Other Commits:
 
   * Fix ref page build to generate .3 targets in the right output
     directory.
+
+-----------------------------------------------------
+
+Change log for April 1, 2016 Vulkan 1.0.8 spec update:
+
+  * Bump API patch number and header version number to 8 for this
+    update.
+
+Github Issues:
+
+  * Specify in the validity language for flink:vkBeginCommandBuffer that
+    pname:commandBuffer mustnot: currently be pending execution (public
+    issue 96).
+  * Describe depth comparison using the correct temporary variable names
+    in the <<textures-depth-compare-operation,Depth Compare Operation>>
+    section (public issue 100).
+  * Clarify the order of descriptor update operations in the
+    flink:vkUpdateDescriptorSets command (public issue 115).
+  * Specify in the VK_KHR_swapchain extension that
+    flink:vkAcquireNextImageKHR's pname:semaphore and pname:fence
+    parameters cannot both be sname:VK_NULL_HANDLE (partly addresses,
+    but does not fully close, public issue 117 / internal issue 246).
+  * Change reference to the "lifetime" of a Vulkan command to
+    "duration", and define the "duration" term (public issue 135).
+  * Added valid usage language for slink:VkImageLayout to require both
+    pname:height and pname:depth to be 1 for 1D images and pname:depth
+    to be 1 for 2D images (public issue 137).
+  * Fix SPIR-V example code in the
+    <<descriptorsets-inputattachment,Input Attachment>> section to
+    properly decorate the code:InputAttachmentIndex (public issue 139).
+  * Fix reference to nonexistent pname:imageInfo in the description of
+    flink:VkWriteDescriptorSet to refer to pname:pImageInfo (public
+    issue 140).
+
+Internal Issues:
+
+  * Link to the fixed-function vertex chapter from the drawing chapter
+    (internal issue #110)
+  * Fix typo in slink:VkImageCreateInfo validity language:
+    ptext:maxExtent.sampleCounts -> pname:sampleCounts (internal issue
+    249).
+  * Explain why the non-core token etext:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
+    is used in the example in the
+    <<synchronization-semaphores,Semaphores>> section (internal issue
+    251).
+  * Attempt to clarify in the VK_KHR_android_surface extension's
+    <<platformQuerySupport_android,Android Platform Support>> section
+    that there is no Android-specific WSI query, and why (internal issue
+    252).
+
+Other Commits:
+
+  * Add missing language about ename:VK_INCOMPLETE being returned from
+    array queries when the passed array is too short, in the
+    VK_KHR_display, VK_KHR_swapchain, and VK_KHR_surface extensions.

doc/specs/vulkan/Makefile

@@ -126,7 +126,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.7
+SPECREVISION = 1.0.8
 SPECREMARK =
 
 # Spec targets

doc/specs/vulkan/appendices/glossary.txt

@@ -228,6 +228,10 @@ Drawing Commands::
     flink:vkCmdDraw, flink:vkCmdDrawIndexed, flink:vkCmdDrawIndirect, and
     flink:vkCmdDrawIndexedIndirect.
 
+Duration (Command)::
+    The _duration_ of a {apiname} command refers to the interval between
+    calling the command and its return to the caller.
+
 Dynamic Storage Buffer::
     A storage buffer whose offset is specified each time the storage buffer
     is bound to a command buffer via a descriptor set.

doc/specs/vulkan/chapters/descriptorsets.txt

@@ -514,6 +514,7 @@ layout (input_attachment_index=i, set=m, binding=n) uniform subpassInput myInput
                OpName %9 "myInputAttachment"
                OpDecorate %9 DescriptorSet m
                OpDecorate %9 Binding n
+               OpDecorate %9 InputAttachmentIndex i
           %2 = OpTypeVoid
           %3 = OpTypeFunction %2
           %6 = OpTypeFloat 32
@@ -1247,6 +1248,11 @@ include::../protos/vkUpdateDescriptorSets.txt[]
     slink:VkCopyDescriptorSet structures describing the descriptor sets to
     copy between.
 
+The operations described by pname:pDescriptorWrites are performed first,
+followed by the operations described by pname:pDescriptorCopies. Within
+each array, the operations are performed in the order they appear in the
+array.
+
 include::../validity/protos/vkUpdateDescriptorSets.txt[]
 
 Each element in the pname:pDescriptorWrites array describes an operation
@@ -1293,7 +1299,8 @@ ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER,
 ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC, or
 ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC, the pname:pBufferInfo array
 will be used to update the descriptors, and other arrays will be ignored.
-Each entry is of type sname:VkDescriptorBufferInfo and is defined as:
+Each element of pname:pBufferInfo is of type sname:VkDescriptorBufferInfo
+and is defined as:
 
 include::../structs/VkDescriptorBufferInfo.txt[]
 
@@ -1321,10 +1328,10 @@ If pname:descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLER,
 ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER,
 ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE,
 ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or
-ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the members in pname:pImageInfo
-array will be used to update the descriptors, and other arrays will be
-ignored. pname:imageInfo is of type sname:VkDescriptorImageInfo and is
-defined as:
+ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT, the elements of the
+pname:pImageInfo array will be used to update the descriptors, and other
+arrays will be ignored. Each element of pname:pImageInfo is of type
+sname:VkDescriptorImageInfo and is defined as:
 
 include::../structs/VkDescriptorImageInfo.txt[]
 

doc/specs/vulkan/chapters/drawing.txt

@@ -360,7 +360,10 @@ Drawing commands fall roughly into two categories:
 
   * Non-indexed drawing (fname:vkCmdDraw and fname:vkCmdDrawIndirect)
     commands present a sequential code:vertexIndex to the vertex shader. The
-    sequential index is generated automatically by the device.
+    sequential index is generated automatically by the device (see
+    <<fxvertex,Fixed-Function Vertex Processing>> for details on both
+    specifying the vertex attributes indexed by code:vertexIndex, as well as
+    binding vertex buffers containing those attributes to a command buffer).
   * Indexed drawing commands (fname:vkCmdDrawIndexed and
     fname:vkCmdDrawIndexedIndirect) read index values from an _index buffer_ and use
     this to compute the code:vertexIndex value for the vertex shader.

doc/specs/vulkan/chapters/fundamentals.txt

@@ -397,7 +397,7 @@ can: be destroyed:
 
 
 [[fundamentals-commandsyntax]]
-== Command Syntax
+== Command Syntax and Duration
 
 The Specification describes {apiname} commands as functions or procedures
 using C99 syntax. Language bindings for other languages such as C++ and
@@ -438,6 +438,9 @@ and/or outside a render pass, and in one or more of the supported queue
 types. These restrictions are documented together with the definition of
 each such command.
 
+The _duration_ of a {apiname} command refers to the interval between calling
+the command and its return to the caller.
+
 
 [[fundamentals-threadingbehavior]]
 == Threading Behavior

doc/specs/vulkan/chapters/memory.txt

@@ -160,7 +160,7 @@ parameter and takes a value of type elink:VkSystemAllocationScope:
 include::../enums/VkSystemAllocationScope.txt[]
 
   * ename:VK_SYSTEM_ALLOCATION_SCOPE_COMMAND - The allocation is scoped to
-    the lifetime of the {apiname} command.
+    the duration of the {apiname} command.
   * ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT - The allocation is scoped to
     the lifetime of the {apiname} object that is being created or used.
   * ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE - The allocation is scoped to the

doc/specs/vulkan/chapters/synchronization.txt

@@ -281,11 +281,11 @@ operation. For example, a sname:VkImageMemoryBarrier could use:
   * pname:dstStageMask = ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT
   * pname:dstAccessMask = ename:VK_ACCESS_COLOR_ATTACHMENT_READ_BIT |
     ename:VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT.
-  * pname:oldLayout = ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
+  * pname:oldLayout = etext:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
   * pname:newLayout = ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
 
-Alternately, pname:oldLayout can: be ename:VK_IMAGE_LAYOUT_UNDEFINED, if
-the image's contents need not be preserved.
+Alternately, pname:oldLayout can: be ename:VK_IMAGE_LAYOUT_UNDEFINED, if the
+image's contents need not be preserved.
 
 This barrier accomplishes a dependency chain between previous presentation
 operations and subsequent color attachment output operations, with the
@@ -296,6 +296,10 @@ semaphore wait stalls the
 ename:VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT stage, then there is a
 dependency from that same stage to itself with the layout transition
 performed in between.
+
+(The primary use case for this example is with the presentation extensions,
+thus the etext:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR token is used even though it
+is not defined in the core {apiname} specification.)
 ====
 
 When a queue signals or waits upon a semaphore, certain

doc/specs/vulkan/chapters/textures.txt

@@ -611,38 +611,39 @@ the value of the sparse unbound texel is undefined.
 [[textures-depth-compare-operation]]
 === Depth Compare Operation
 
-If the image view's format is depth and the operation is a code:Dref
-instruction, a depth comparison is performed. The initial value of the
-result latexmath:[$r$] is latexmath:[$0.0$], which is replaced with
-latexmath:[$1.0$] if the result of the compare operation is
-latexmath:[$true$]. The compare operation is selected by the pname:compareOp
+If the image view has a depth/stencil format, the depth component is
+selected by the pname:aspectMask, and the operation is a code:Dref
+instruction, a depth comparison is performed. The value of the
+result latexmath:[$D$] is latexmath:[$1.0$] if the result of the
+compare operation is latexmath:[$true$], and latexmath:[$0.0$]
+otherwise. The compare operation is selected by the pname:compareOp
 member of the sampler.
 
 [latexmath]
 +++++++++++++++++++
 \begin{align*}
-r & = 0.0 & \textrm{initial value} \\
-r & = 1.0
+D & = 1.0 &
   \begin{cases}
-    D_{ref} \leq D_{t} & \textrm{for LEQUAL}   \\
-    D_{ref} \geq D_{t} & \textrm{for GEQUAL}   \\
-    D_{ref} < D_{t}    & \textrm{for LESS}     \\
-    D_{ref} > D_{t}    & \textrm{for GREATER}  \\
-    D_{ref} = D_{t}    & \textrm{for EQUAL}    \\
-    D_{ref} \neq D_{t} & \textrm{for NOTEQUAL} \\
-    true               & \textrm{for ALWAYS}   \\
-    false              & \textrm{for NEVER}
-  \end{cases}
+    D_{ref} \leq D & \textrm{for LEQUAL}   \\
+    D_{ref} \geq D & \textrm{for GEQUAL}   \\
+    D_{ref} < D    & \textrm{for LESS}     \\
+    D_{ref} > D    & \textrm{for GREATER}  \\
+    D_{ref} = D    & \textrm{for EQUAL}    \\
+    D_{ref} \neq D & \textrm{for NOTEQUAL} \\
+    true           & \textrm{for ALWAYS}   \\
+    false          & \textrm{for NEVER}
+  \end{cases} \\
+D & = 0.0 & \textrm{otherwise}
 \end{align*}
 +++++++++++++++++++
 
-where:
+where, in the depth comparison:
 
 [latexmath]
 +++++++++++++++++++
 \begin{align*}
 & D_{ref} = shaderOp.D_{ref} & \textrm{(from optional SPIR-V operand)} \\
-& D_{t}                      & \textrm{texel depth value}
+& D                          & \textrm{texel depth value}
 \end{align*}
 +++++++++++++++++++
 

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

@@ -10,6 +10,7 @@ endif::doctype-manpage[]
 * pname:commandBuffer must: be a valid sname:VkCommandBuffer handle
 * pname:pBeginInfo must: be a pointer to a valid sname:VkCommandBufferBeginInfo structure
 * pname:commandBuffer mustnot: be in the recording state
+* pname:commandBuffer mustnot: currently be pending execution
 * If pname:commandBuffer was allocated from a sname:VkCommandPool which did not have the ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT flag set, pname:commandBuffer must: be in the initial state.
 * If pname:commandBuffer is a secondary command buffer, the pname:pInheritanceInfo member of pname:pBeginInfo must: be a valid sname:VkCommandBufferInheritanceInfo structure
 * If pname:commandBuffer is a secondary command buffer and either the pname:occlusionQueryEnable member of the pname:pInheritanceInfo member of pname:pBeginInfo is ename:VK_FALSE, or the precise occlusion queries feature is not enabled, the pname:queryFlags member of the pname:pInheritanceInfo member pname:pBeginInfo mustnot: contain ename:VK_QUERY_CONTROL_PRECISE_BIT

doc/specs/vulkan/validity/structs/VkImageCreateInfo.txt

@@ -29,10 +29,12 @@ endif::doctype-manpage[]
 * If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width and pname:extent.height must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxImageDimensionCube, or sname:VkImageFormatProperties::pname:maxExtent.width/height (as returned by fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, pname:type, pname:tiling, pname:usage and pname:flags equal to those in this structure) - whichever is higher
 * If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width and pname:extent.height must: be equal
 * If pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:extent.width, pname:extent.height and pname:extent.depth must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxImageDimension3D, or sname:VkImageFormatProperties::pname:maxExtent.width/height/depth (as returned by fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, pname:type, pname:tiling, pname:usage and pname:flags equal to those in this structure) - whichever is higher
+* If pname:imageType is ename:VK_IMAGE_TYPE_1D, both pname:extent.height and pname:extent.depth must: be `1`
+* If pname:imageType is ename:VK_IMAGE_TYPE_2D, pname:extent.depth must: be `1`
 * pname:mipLevels must: be less than or equal to latexmath:[$\lfloor\log_2(\max(\mathit{extent.width}, \mathit{extent.height}, \mathit{extent.depth}))\rfloor + 1$]
 * If any of pname:extent.width, pname:extent.height or pname:extent.depth are greater than the equivalently named members of sname:VkPhysicalDeviceLimits::pname:maxImageDimension3D, pname:mipLevels must: be less than or equal to sname:VkImageFormatProperties::pname:maxMipLevels (as returned by fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, pname:type, pname:tiling, pname:usage and pname:flags equal to those in this structure)
 * pname:arrayLayers must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxImageArrayLayers, or sname:VkImageFormatProperties::pname:maxArrayLayers (as returned by fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, pname:type, pname:tiling, pname:usage and pname:flags equal to those in this structure) - whichever is higher
-* pname:samples must: be a bit value that is set in sname:VkPhysicalDeviceLimits::pname:sampleCounts returned by flink:vkGetPhysicalDeviceProperties, or sname:VkImageFormatProperties::pname:maxExtent.sampleCounts returned by fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, pname:type, pname:tiling, pname:usage and pname:flags equal to those in this structure
+* pname:samples must: be a bit value that is set in sname:VkPhysicalDeviceLimits::pname:sampleCounts returned by flink:vkGetPhysicalDeviceProperties, or sname:VkImageFormatProperties::pname:sampleCounts returned by fname:vkGetPhysicalDeviceImageFormatProperties with pname:format, pname:type, pname:tiling, pname:usage and pname:flags equal to those in this structure
 * If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT or ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.width must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth
 * If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT or ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.height must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight
 * If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, pname:samples must: be a bit value that is set in sname:VkPhysicalDeviceLimits::pname:maxFramebufferColorSamples