Change log for June 17, 2016 Vulkan 1.0.17 spec update:

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

Github Issues:

  * Update description of vertex shader reuse in
    <<shaders-vertex-execution>> (public issue 106).
  * Simplify validity language around pname:ppEnabledExtensionNames and
    pname:ppEnabledLayerNames (in the <<initialization-instances>> and
    <<devsandqueues-device-creation>> sections) (public issue 214).
  * Add missing validity rule to flink:vkCmdBeginRenderPass requiring
    compatibility between slink:VkAttachmentDescription pname:initalLayout
    members and the corresponding attached framebuffer images (public issue
    233).
  * Fix Unicode arrows appearing in output instead of relational operators
    (public issue 239).
  * Correctly describe the required number of elements for
    code:TessLevelInner and code:TessLevelOuter arrays in the
    <<interfaces-builtin-variables,Built-In Variables>> section as two and
    four, respectively, instead of the other way around, and refer to this
    section from the <<tessellation,Tessellation>> chapter (public issue
    246).

Internal Issues:

  * Document deprecation of ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR in the
    VK_KHR_surface extension branch, and of
    ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT in the
    VK_EXT_debug_report branch (internal issue 328).
  * Added language to define what a valid usage statement is and should be,
    with a note about some apparent weirdnesses this might entail (internal
    issue 357).

Other Commits:

  * Added missing ename:VK_ERROR_DEVICE_LOST error to
    flink:vkQueueBindSparse.

ChangeLog.txt

@@ -752,3 +752,46 @@ Other Commits:
     header / validation layer / include autogeneration from XML,
     reducing platform dependencies.
 
+-----------------------------------------------------
+
+Change log for June 17, 2016 Vulkan 1.0.17 spec update:
+
+  * Bump API patch number and header version number to 17 for this
+    update.
+
+Github Issues:
+
+  * Update description of vertex shader reuse in
+    <<shaders-vertex-execution>> (public issue 106).
+  * Simplify validity language around pname:ppEnabledExtensionNames and
+    pname:ppEnabledLayerNames (in the <<initialization-instances>> and
+    <<devsandqueues-device-creation>> sections) (public issue 214).
+  * Add missing validity rule to flink:vkCmdBeginRenderPass requiring
+    compatibility between slink:VkAttachmentDescription pname:initalLayout
+    members and the corresponding attached framebuffer images (public issue
+    233).
+  * Fix Unicode arrows appearing in output instead of relational operators
+    (public issue 239).
+  * Correctly describe the required number of elements for
+    code:TessLevelInner and code:TessLevelOuter arrays in the
+    <<interfaces-builtin-variables,Built-In Variables>> section as two and
+    four, respectively, instead of the other way around, and refer to this
+    section from the <<tessellation,Tessellation>> chapter (public issue
+    246).
+
+Internal Issues:
+
+  * Document deprecation of ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR in the
+    VK_KHR_surface extension branch, and of
+    ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT in the
+    VK_EXT_debug_report branch (internal issue 328).
+  * Added language to define what a valid usage statement is and should be,
+    with a note about some apparent weirdnesses this might entail (internal
+    issue 357).
+
+Other Commits:
+
+  * Added missing ename:VK_ERROR_DEVICE_LOST error to
+    flink:vkQueueBindSparse.
+
+

doc/specs/vulkan/Makefile

@@ -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.16
+SPECREVISION = 1.0.17
 SPECREMARK =
 
 # Spec targets

doc/specs/vulkan/chapters/fundamentals.txt

@@ -543,6 +543,40 @@ validation layers by default.
 [[fundamentals-validusage]]
 === Valid Usage
 
+Valid usage defines a set of conditions which must: be met in order to achieve
+well-defined run-time behavior in an application. These conditions depend only
+on Vulkan state, and the parameters or objects whose usage is constrained by
+the condition.
+
+Some valid usage conditions have dependencies on run-time limits or feature
+availability. It is possible to validate these conditions against Vulkan's
+minimum supported values for these limits and features, or some subset of
+other known values.
+
+Valid usage conditions do not cover conditions where well-defined behavior
+(including returning an error code) exists.
+
+Valid usage conditions should: apply to the command or structure where
+complete information about the condition would be known during execution of
+an application. This is such that a validation layer or linter can: be
+written directly against these statements at the point they are specified.
+
+[NOTE]
+.Note
+====
+This does lead to some non-obvious places for valid usage statements. For
+instance, the valid values for a structure might depend on a separate value
+in the calling command. In this case, the structure itself will not
+reference this valid usage as it is impossible to determine validity from
+the structure that it is invalid - instead this valid usage would be
+attached to the calling command.
+
+Another example is draw state - the state setters are independent, and can
+cause a legitimately invalid state configuration between draw calls; so the
+valid usage statements are attached to the place where all state needs to be
+valid - at the draw command.
+====
+
 Certain usage rules apply to all commands in the API unless explicitly
 denoted differently for a command. These rules are as follows.
 

doc/specs/vulkan/chapters/initialization.txt

@@ -139,7 +139,10 @@ include::../validity/structs/VkInstanceCreateInfo.txt[]
 fname:vkCreateInstance creates the instance, then enables and initializes
 global layers and extensions requested by the application. If an extension
 is provided by a layer, both the layer and extension must: be specified at
-fname:vkCreateInstance time.
+fname:vkCreateInstance time. If a specified layer cannot be found, no
+sname:VkInstance will be created and the function will return
+ename:VK_ERROR_LAYER_NOT_PRESENT. Likewise, if a specified extension cannot be found
+the call will return ename:VK_ERROR_EXTENSION_NOT_PRESENT.
 
 The pname:pApplicationInfo member of slink:VkInstanceCreateInfo can: point
 to an instance of sname:VkApplicationInfo.
@@ -165,7 +168,7 @@ include::../structs/VkApplicationInfo.txt[]
     <<fundamentals-versionnum,API Version Numbers and Semantics>> section.
     If pname:apiVersion is 0 the implementation must: ignore it, otherwise
     if the implementation does not support the requested pname:apiVersion it
-    must: return VK_ERROR_INCOMPATIBLE_DRIVER. The patch version number
+    must: return ename:VK_ERROR_INCOMPATIBLE_DRIVER. The patch version number
     specified in pname:apiVersion is ignored when creating an instance
     object. Only the major and minor versions of the instance must: match
     those requested in pname:apiVersion.

doc/specs/vulkan/chapters/interfaces.txt

@@ -1112,32 +1112,32 @@ code:TessLevelOuter::
 
 The code:TessLevelOuter decoration is used in tessellation control
 shaders to decorate an output variable to contain the outer tessellation
-factor for the resulting patch. This value is used by the tessellator
+factors for the resulting patch. These values are used by the tessellator
 to control primitive tessellation and can: be read by
 tessellation evaluation shaders. When applied to an input variable in a
-tessellation evaluation shader, the shader can: read the value written by
+tessellation evaluation shader, the shader can: read the values written by
 the tessellation control shader.
 +
 The code:TessLevelOuter decoration must: be used only within
 tessellation control and evaluation shaders.
 +
-code:TessLevelOuter must: be declared as an array of size two,
+code:TessLevelOuter must: be declared as an array of size four,
 containing 32-bit floating-point values.
 
 code:TessLevelInner::
 
 The code:TessLevelInner decoration is used in tessellation control
 shaders to decorate an output variable to contain the inner tessellation
-factor for the resulting patch. This value is used by the tessellator to
+factors for the resulting patch. These values are used by the tessellator to
 control primitive tessellation and can: be read by
 tessellation evaluation shaders. When applied to an input variable in a
-tessellation evaluation shader, the shader can: read the value written by
+tessellation evaluation shader, the shader can: read the values written by
 the tessellation control shader.
 +
 The code:TessLevelInner decoration must: be used only within
 tessellation control and evaluation shaders.
 +
-code:TessLevelInner must: be declared as an array of size four,
+code:TessLevelInner must: be declared as an array of size two,
 containing 32-bit floating-point values.
 
 code:VertexIndex::

doc/specs/vulkan/chapters/shaders.txt

@@ -212,20 +212,21 @@ the vertex and instance for which it has been invoked. Input variables
 declared in the vertex shader are filled by the implementation with the
 values of vertex attributes associated with the invocation being executed.
 
-If a vertex is a part of more than one input primitive, for example
-by including the same index value multiple times in an index buffer, the
-vertex shader may: be invoked only once and the results shared amongst the
-resulting primitives. This is known as _vertex reuse_.
-
-ifdef::implementation-guide[]
-.Implementor's Note
-****
-If a vertex is repeated in a draw command (i.e. the same index is repeated
-in an indexed draw), the shader may: be executed anywhere from one to the
-number of repetitions times for that vertex, depending on the
-implementation's ability to reuse shader results.
-****
-endif::implementation-guide[]
+If the same vertex is specified multiple times in a draw command (e.g.
+by including the same index value multiple times in an index buffer) the
+implementation may: reuse the results of vertex shading if it can statically
+determine that the vertex shader invocations will produce identical results.
+
+[NOTE]
+.Note
+==================
+It is implementation-dependent when and if results of vertex shading are
+reused, and thus how many times the vertex shader will be executed. This
+is true also if the vertex shader contains stores or atomic operations
+(see <<features-features-vertexPipelineStoresAndAtomics,
+pname:vertexPipelineStoresAndAtomics>>).
+==================
+
 
 
 [[shaders-tessellation-control]]

doc/specs/vulkan/chapters/tessellation.txt

@@ -22,8 +22,11 @@ If a pipeline includes both tessellation shaders (control and evaluation),
 the tessellator consumes each input patch (after vertex shading) and
 produces a new set of independent primitives (points, lines, or triangles).
 These primitives are logically produced by subdividing a geometric primitive
-(rectangle or triangle) according to the per-patch tessellation levels
-written by the tessellation control shader. This subdivision is performed in
+(rectangle or triangle) according to the per-patch outer and inner
+tessellation levels written by the tessellation control shader. These levels
+are specified using the <<interfaces-builtin-variables,built-in variables>>
+code:TessLevelOuter and code:TessLevelInner, respectively.
+This subdivision is performed in
 an implementation-dependent manner. If no tessellation shaders are present
 in the pipeline, the tessellator is disabled and incoming primitives are
 passed through without modification.

doc/specs/vulkan/man/vkCreateDevice.txt

@@ -35,6 +35,33 @@ include::../structs/VkDeviceCreateInfo.txt[]
 
 include::../validity/protos/vkCreateDevice.txt[]
 
+  * pname:sType is the type of this structure.
+  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
+  * pname:flags is reserved for future use.
+  * pname:queueCreateInfoCount is the unsigned integer size of the
+    pname:pQueueCreateInfos array. Refer to the
+    <<devsandqueues-queue-creation,Queue Creation>> section below for
+    further details.
+  * pname:pQueueCreateInfos is a pointer to an array of
+    slink:VkDeviceQueueCreateInfo structures describing the queues that are
+    requested to be created along with the logical device. Refer to the
+    <<devsandqueues-queue-creation,Queue Creation>> section below for
+    further details.
+  * pname:enabledLayerCount is deprecated and ignored.
+  * pname:ppEnabledLayerNames is deprecated and ignored. See
+    <<extended-functionality-device-layer-deprecation,Device Layer Deprecation>>.
+  * pname:enabledExtensionCount is the number of device extensions to
+    enable.
+  * pname:ppEnabledExtensionNames is a pointer to an array of
+    pname:enabledExtensionCount null-terminated UTF-8 strings containing the
+    names of extensions to enable for the created device. See the
+    <<extended-functionality-extensions,Extensions>> section for further
+    details.
+  * pname:pEnabledFeatures is `NULL` or a pointer to a
+    slink:VkPhysicalDeviceFeatures structure that contains boolean
+    indicators of all the features to be enabled. Refer to the
+    <<features-features,Features>> section for further details.
+
 See Also
 --------
 

doc/specs/vulkan/man/vkCreateInstance.txt

@@ -42,13 +42,16 @@ The pname:enabledLayerNameCount member of sname:VkInstanceCreateInfo specifies t
 to enable, and pname:ppEnabledLayerNames is a pointer to an array of pname:enabledLayerNameCount
 code:NULL-terminated UTF-8 strings containing the names of layers
 that should be enabled globally. If pname:enabledLayerNameCount is zero, then pname:ppEnabledLayerNames
-is ignored and no global layers are enabled.
+is ignored and no global layers are enabled. If a layer cannot be found, the
+call will not create a sname:VkInstance and will return ename:VK_ERROR_LAYER_NOT_PRESENT.
 
 Similary, information about global extensions is specified in the pname:enabledExtensionNameCount and
 pname:ppEnabledExtensionNames members. pname:enabledExtensionNameCount specifies the number of global
 extensions to enable and pname:ppEnabledExtensionNames is a pointer to an array of pointers
 to code:NULL-terminated UTF-8 strings containing the extension names. If an extension is provided
-by a layer, both the layer and extension must be specified at fname:vkCreateInstance time.
+by a layer, both the layer and extension must be specified at
+fname:vkCreateInstance time. If a extension cannot be found, the call will not
+create a sname:VkInstance and will return ename:VK_ERROR_LAYER_NOT_PRESENT.
 
 If pname:enabledExtensionNameCount is zero then no extensions are enabled and pname:ppEnabledExtensionNames
 is ignored.

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

@@ -14,11 +14,12 @@ endif::doctype-manpage[]
 * The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics operations
 * This command must: only be called outside of a render pass instance
 * pname:commandBuffer must: be a primary sname:VkCommandBuffer
-* If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then the corresponding attachment image of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT set
-* If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set
-* If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_SAMPLED_BIT or ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set
-* If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set
-* If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set
+* If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT set
+* If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set
+* If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_SAMPLED_BIT or ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set
+* If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT set
+* If any of the pname:initialLayout or pname:finalLayout member of the sname:VkAttachmentDescription structures or the pname:layout member of the sname:VkAttachmentReference structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL then the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT set
+* If any of the pname:initialLayout members of the sname:VkAttachmentDescription structures specified when creating the render pass specified in the pname:renderPass member of pname:pRenderPassBegin is not one of ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED, then each such pname:initialLayout must: be equal to the current layout of the corresponding attachment image subresource of the framebuffer specified in the pname:framebuffer member of pname:pRenderPassBegin.
 ifndef::doctype-manpage[]
 ********************************************************************************
 endif::doctype-manpage[]

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

@@ -77,6 +77,7 @@ On failure, this command returns::
 endif::doctype-manpage[]
 * ename:VK_ERROR_OUT_OF_HOST_MEMORY
 * ename:VK_ERROR_OUT_OF_DEVICE_MEMORY
+* ename:VK_ERROR_DEVICE_LOST
 ifndef::doctype-manpage[]
 ********************************************************************************
 endif::doctype-manpage[]