Change log for August 5, 2016 Vulkan 1.0.23 spec update:

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

Github Issues:

  * Add explicit valid value attributes to pname:sType members in vk.xml
    (public issue 34).
  * Clarify usage of flink:vkGetInstanceProcAddr and
    flink:vkGetDeviceProcAddr (public issue 225).
  * Fix a copy-and-paste error in the description of
    pname:pSwapchainImageCount saying that it was the count of ``format
    pairs'' instead of ``swapchain images'' (public issue 292).
  * flink:vkCmdExecuteCommandBuffers requires all command buffers to be
    allocated from command pools created for the same queue family (public
    issue 296).
  * Remove bogus +optional+ attribute for
    flink:vkEnumerateDeviceLayerProperties::pname:physicalDevice from vk.xml
    (public issue 301).
  * Clean up the <<resources-image-views-compatibility,image and image view
    compatibility table>> reference and contents. Use full enumerant names.
    Refer to pname:layerCount in the ``view parameters'' column instead of
    pname:arrayLayers. Require N >= 1 for the cube array subview row, not
    just arrayLayers >= 6 N (public issue 304).
  * Modify description of <<resources-memory-aliasing,memory aliasing>> to
    be consistent with the description of
    <<resources-bufferimagegranularity,buffer image granularity>> (public
    issue 307).

Internal Issues:

  * Describe remaining +vk_platform.h+ macros in the <<boilerplate,API
    Boilerplate>> appendix (internal issue 6).
  * Clarify
    <<features-features-robustBufferAccess,pname:robustBufferAccess>>
    feature behavior; what memory can be accessed, how bounds checking is
    performed, and allowing for vectorization (internal issue 332).
  * Document markup for automatic extraction of reference pages from the
    spec sources in the style guide (internal issue 395).
  * Allow flink:vkCreateDisplayModeKHR to return
    ename:VK_ERROR_INITIALIZAION_FAILED_KHR if the user requests mode
    parameters that the specified display does not support (internal issue
    411).
  * Remove atomic counters (atomic_uint style) from KHR_vulkan_glsl, and
    more clearly remove the subroutine keyword alongside it (internal issue
    421).
  * Clarify behavior of flink:vkCmdBindDescriptorSets for descriptor sets
    not contained in the layout (internal issue 427).

Other Commits:

  * Change the order in which members of sname:VkAttachmentDescription and
    sname:VkPipelineInputAssemblyStateCreateInfo are described to match
    their order in the structures.

doc/specs/misc/GL_KHR_vulkan_glsl.txt

@@ -33,8 +33,8 @@ Status
 
 Version
 
-    Last Modified Date: 20-Jul-2016
-    Revision: 31
+    Last Modified Date: 1-Aug-2016
+    Revision: 32
 
 Number
 
@@ -62,7 +62,7 @@ Overview
     The following features are removed:
         * default uniforms (uniform variables not inside a uniform block),
           except for opaque types
-        * atomic-counter bindings: atomic counters form a one-dimensional space
+        * atomic-counters (those based on atomic_uint)
         * subroutines
         * shared and packed block layouts
         * the already deprecated texturing functions (e.g., texture2D())
@@ -219,7 +219,7 @@ Overview
 
     The constant_id can only be applied to a scalar *int*, a scalar *float*
     or a scalar *bool*.
-    
+
     Only basic operators and constructors can be applied to a specialization
     constant and still result in a specialization constant:
 
@@ -324,7 +324,7 @@ Overview
       in / out variable            -> Input/Output, possibly with block (below)
       in / out block...            -> Input/Output, with Block decoration
       buffer  blockN { ... } ...;  -> Uniform, with BufferBlock decoration
-      ... uniform atomic_uint ...  -> AtomicCounter
+      N/A                          -> AtomicCounter
       shared                       -> Workgroup
       <normal global>              -> Private
 
@@ -417,7 +417,7 @@ Overview
     Mapping of layouts
 
       std140/std430  ->  explicit offsets/strides on struct
-      shared/packed  ->  not allowed 
+      shared/packed  ->  not allowed
       <default>      ->  not shared, but std140 or std430
 
       max_vertices   ->  OutputVertices
@@ -426,13 +426,13 @@ Overview
 
       %     -> OpUMod/OpSMod
       mod() -> OpFMod
-      NA    -> OpSRem/OpFRem
+      N/A   -> OpSRem/OpFRem
 
       atomicExchange()      -> OpAtomicExchange
       imageAtomicExchange() -> OpAtomicExchange
       atomicCompSwap()      -> OpAtomicCompareExchange
       imageAtomicCompSwap() -> OpAtomicCompareExchange
-      NA                    -> OpAtomicCompareExchangeWeak
+      N/A                   -> OpAtomicCompareExchangeWeak
 
 Changes to Chapter 1 of the OpenGL Shading Language Specification
 
@@ -442,7 +442,7 @@ Changes to Chapter 1 of the OpenGL Shading Language Specification
 
     Add a paragraph: "The Vulkan API will specify the Vulkan entry points used
     to manipulate SPIR-V shaders.  Independent offline tool chains will compile
-    GLSL down to the SPIR-V intermediate language. Vulkan use is not enabled 
+    GLSL down to the SPIR-V intermediate language. Vulkan use is not enabled
     with a #extension, #version, or a profile.  Instead, use of GLSL for Vulkan
     is determined by offline tool-chain use. See the documentation of such
     tools to see how to request generation of SPIR-V for Vulkan."
@@ -480,7 +480,7 @@ Changes to Chapter 3 of the OpenGL Shading Language Specification
         textureCube      texture2DRect    texture1DArray
         texture2DArray   textureBuffer    texture2DMS
         texture2DMSArray textureCubeArray
-        
+
         itexture1D        itexture2D       itexture3D
         itextureCube      itexture2DRect   itexture1DArray
         itexture2DArray   itextureBuffer
@@ -497,10 +497,17 @@ Changes to Chapter 3 of the OpenGL Shading Language Specification
         subpassInput      isubpassInput     usubpassInput
         subpassInputMS    isubpassInputMS   usubpassInputMS
 
+    Move the following keywords in section 3.6 Keywords to the reserved
+    section:
+
+        atomic_uint
+        subroutine
+
 Changes to Chapter 4 of the OpenGL Shading Language Specification
 
-    Add into the tables in section 4.1, interleaved with the existing types,
-    using the existing descriptions (when not supplied below):
+    Add into the tables in section 4.1 Basic Types, interleaved with the
+    existing types, using the existing descriptions (when not supplied
+    below):
 
         Floating-Point Opaque Types
 
@@ -555,6 +562,10 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification
             usubpassInputMS   | a handle for accessing a multi-sampled unsigned
                               | integer subpass input
 
+    Remove the entry from the table in section 4.1 Basic Types:
+
+        atomic_uint
+
     Add a new category in this section
 
       "Sampler Opaque Types
@@ -590,7 +601,7 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification
         and unsigned integer data types. Textures can be combined with a
         variable of type *sampler* or *samplerShadow* to create a sampler type
         (e.g., sampler2D, or sampler2DShadow). This is done with a constructor,
-        e.g., sampler2D(texture2D, sampler) or 
+        e.g., sampler2D(texture2D, sampler) or
         sampler2DShadow(texture2D, samplerShadow),
         and is described in more detail in section 5.4 "Constructors"."
 
@@ -608,11 +619,7 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification
         "Subpass input types are only available in fragment shaders.  It is a
         compile-time error to use them in any other stage."
 
-    Add to section 4.1.7.3 Atomic Counters:
-
-       "It is an error to declare an atomic type with a different precision or
-       to specify the default precision for an atomic type to be lowp or
-       mediump."
+    Remove the section 4.1.7.3 Atomic Counters
 
     Change section 4.3.3 Constant Expressions:
 
@@ -723,14 +730,14 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification
       returned for the lowerleft-most pixel in a window. The origin can be
       changed by redeclaring gl_FragCoord with the
       origin_upper_left identifier."
-    
+
     To
 
       "The gl_FragCoord built-in variable assumes an upper-left origin for
       window coordinates ... For example, the (x, y) location (0.5, 0.5) is
       returned for the upper-left-most pixel in a window. The origin can be
       explicitly set by redeclaring gl_FragCoord with the origin_upper_left
-      identifier.  It is a compile-time error to change it to 
+      identifier.  It is a compile-time error to change it to
       origin_lower_left."
 
     Add to the end of section 4.4.3 Uniform Variable Layout Qualifiers:
@@ -765,6 +772,9 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification
       "It is a compile-time error for either the /set/ or /binding/ value
       to exceed a front-end-configuration supplied maximum value."
 
+    Remove mention of subroutine throughout section 4.4 Layout Qualifiers,
+    including removal of section 4.4.4 Subroutine Function Layout Qualifiers.
+
     Change section 4.4.6 Opaque-Uniform Layout Qualifiers:
 
       Change
@@ -779,6 +789,8 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification
       takes just the provided binding number.  The next consecutive binding
       number is available for a different object."
 
+    Remove section 4.4.6.1 Atomic Counter Layout Qualifiers
+
     Add a new subsection at the end of section 4.4:
 
       "4.4.x Specialization-Constant Qualifier
@@ -809,22 +821,22 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification
       "The built-in constant vector gl_WorkGroupSize can be specialized using
       the local_size_{xyz}_id qualifiers, to individually give the components
       an id. For example:
-  
+
           layout(local_size_x_id = 18, local_size_z_id = 19) in;
 
       "This leaves gl_WorkGroupSize.y as a non-specialization constant, with
       gl_WorkGroupSize being a partially specialized vector.  Its x and z
       components can be later specialized using the ids 18 and 19.  These ids
       are declared independently from declaring the work-group size:
-  
+
         layout(local_size_x = 32, local_size_y = 32) in;   // size is (32,32,1)
         layout(local_size_x_id = 18) in;                   // constant_id for x
         layout(local_size_z_id = 19) in;                   // constant_id for z
-  
+
       "Existing rules for declaring local_size_x, local_size_y, and
       local_size_z are not changed by this extension. For the local-size ids,
       it is a compile-time error to provide different id values for the same
-      local-size id, or to provide them after any use.  Otherwise, order, 
+      local-size id, or to provide them after any use.  Otherwise, order,
       placement, number of statements, and replication do not cause errors.
 
       "Two arrays sized with specialization constants are the same type only if
@@ -871,7 +883,7 @@ Changes to Chapter 4 of the OpenGL Shading Language Specification
       in the implicit input_attachment_index consumed by array declarations.
 
       "It is a compile-time error if the value assigned to an
-      input_attachment_index is greater than or equal to 
+      input_attachment_index is greater than or equal to
       gl_MaxInputAttachments."
 
     Remove all mention of the 'shared' and 'packed' layout qualifiers.
@@ -1023,6 +1035,11 @@ Changes to Chapter 5 of the OpenGL Shading Language Specification
            * logical operations ( && , || , ^^ )
            * comparison ( == , != )
 
+Changes to Chapter 6 of the OpenGL Shading Language Specification
+
+    Remove mention of subroutine throughout, including removal of
+    section 6.1.2 Subroutines.
+
 Changes to Chapter 7 of the OpenGL Shading Language Specification
 
     Changes to section 7.1 Built-In Language Variables
@@ -1100,11 +1117,10 @@ Changes to Chapter 8 of the OpenGL Shading Language Specification
 
         - For prototypes that do specify a resulting precision qualifier,
           the specified precision qualifier is the precision qualification of
-          the result."      
+          the result."
 
     Add precision qualifiers to the following in desktop versions:
 
-
       genIType floatBitsToInt (highp genFType value)
       genUType floatBitsToUint(highp genFType value)
       genFType intBitsToFloat (highp genIType value)
@@ -1134,6 +1150,8 @@ Changes to Chapter 8 of the OpenGL Shading Language Specification
       void imulExtended(highp genIType x, highp genIType y,
                         out highp genIType msb, out highp genIType lsb)
 
+    Remove section 8.10 Atomic-Counter Functions
+
     Add a section
 
       "8.X Subpass Functions
@@ -1161,18 +1179,22 @@ Changes to the grammar
 
       | LEFT_BRACKET constant_expression RIGHT_BRACKET
 
-    to 
+    to
 
       | LEFT_BRACKET conditional_expression RIGHT_BRACKET
 
     and change
 
       | array_specifier LEFT_BRACKET constant_expression RIGHT_BRACKET
 
-    to 
+    to
 
       | array_specifier LEFT_BRACKET conditional_expression RIGHT_BRACKET
 
+    Remove the ATOMIC_UINT type_specifier_nonarray.
+
+    Remove all instances of the SUBROUTINE keyword.
+
 Issues
 
 1. Can we have specialization sizes in an array in a block?  That prevents
@@ -1286,6 +1308,7 @@ Revision History
 
     Rev.    Date         Author    Changes
     ----  -----------    -------  --------------------------------------------
+    32     1-Aug-2016    JohnK    Remove atomic_uint and more fully subroutine
     31    20-Jul-2016    JohnK    Have desktop versions respect mediump/lowp
     30    12-Apr-2016    JohnK    Restrict spec-const operations to non-float
     29     5-Apr-2016    JohnK    Clarify disallowance of spec-const arrays in

doc/specs/vulkan/Makefile

@@ -134,7 +134,7 @@ GENDEPENDS = api/timeMarker validity/timeMarker hostsynctable/timeMarker
 COMMONDOCS = $(CHAPTERS) $(GENINCLUDE) $(GENDEPENDS)
 # A generated included file with the spec version, date, and git commit
 SPECVERSION = specversion.txt
-SPECREVISION = 1.0.22
+SPECREVISION = 1.0.23
 SPECREMARK =
 
 # Spec targets

doc/specs/vulkan/api/defines/VK_HEADER_VERSION.txt

@@ -8,6 +8,6 @@ ifdef::doctype-manpage[]
 endif::doctype-manpage[]
 ------------------------------------------------------------------------------
 // Version of this file
-#define VK_HEADER_VERSION 22
+#define VK_HEADER_VERSION 23
 
 ------------------------------------------------------------------------------

doc/specs/vulkan/appendices/boilerplate.txt

@@ -225,3 +225,90 @@ handle. It may be passed to and returned from Vulkan commands only when
 include::../api/defines/VK_NULL_HANDLE.txt[]
 
 // refEnd VK_NULL_HANDLE
+
+
+[[boilerplate-platform-macros]]
+== Platform-Specific Macro Definitions in +vk_platform.h+
+
+In addition to the macros described for +vulkan.h+, platform-specific macros
+specified and used in the included +vk_platform.h+ file are described in
+this section. These macros are specifically used to control
+platform-dependent behavior and their exact definitions are under the
+control of specific platforms and Vulkan implementations.
+
+
+=== Platform-Specific Calling Conventions
+
+// @refBegin VKAPI_ATTR - Vulkan function attributes
+
+dname:VKAPI_ATTR is a macro placed before the return type in Vulkan API
+function declarations. If not empty, the interpretation of this macro
+depends on the platform and compiler in use, but normally controls calling
+conventions for C++11 and GCC/Clang-style compilers.
+
+// @refEnd VKAPI_ATTR VKAPI_CALL VKAPI_PTR
+
+// @refBegin VKAPI_CALL - Vulkan function calling conventions
+
+dname:VKAPI_CALL is a macro placed after the return type in Vulkan API
+function declarations. If not empty, the interpretation of this macro
+depends on the platform and compiler in use, but normally controls calling
+conventions for MSVC-style compilers.
+
+// @refEnd VKAPI_CALL VKAPI_ATTR VKAPI_PTR
+
+// @refBegin VKAPI_PTR - Vulkan function pointer calling conventions
+
+dname:VKAPI_PTR is a macro placed between the '(' and '*' in Vulkan API
+function pointer declarations. If not empty, the interpretation of this
+macro depends on the platform and compiler in use, and normally controls
+calling conventions. dname:VKAPI_PTR typically has the same definition as
+dname:VKAPI_ATTR or dname:VKAPI_CALL, depending on the compiler.
+
+// @refEnd VKAPI_PTR VKAPI_ATTR VKAPI_CALL
+
+
+=== Platform-Specific Header Control
+
+// @refBegin VK_NO_STDINT_H - control definition of +<stdint.h>+ types
+
+If the +VK_NO_STDINT_H+ macro is defined at compile time, it indicates that
+the system +<stdint.h>+ does not define some required integer types, and
++vk_platform.h+ will declare fallback definitions of those types. This is
+included for backwards compatibility with very old compilers, such as
+Microsoft Visual Studio version 2008 or before.
+
+// @refEnd VK_NO_STDINT_H
+
+
+=== Window System-Specific Header Control
+
+// @refBegin WSIheaders - control inclusion of window system interface extensions
+
+When using different window systems with Khronos extensions, header files
+for those window systems must: be included at compile time in order for the
+corresponding extension definitions to compile. The Vulkan header files
+cannot determine whether or not an external header is available at compile
+time, so applications must: include macros enabling those headers. If this is
+not done, the corresponding extension interfaces will not be defined and
+they will be unusable.
+
+The extensions, required compile-time symbols to enable them, and window
+systems they correspond to are defined in the
+<<boilerplate-wsi-header-table,following table>>.
+
+
+[[boilerplate-wsi-header-table]]
+.Window System Extensions and Required Compile-Time Symbol Definitions
+[options="header"]
+|====
+| Extension Name           | Required Compile-Time Symbol  | Window System Name
+| +VK_KHR_xlib_surface+    | +VK_USE_PLATFORM_XLIB_KHR+    | X11 Xlib library
+| +VK_KHR_xcb_surface+     | +VK_USE_PLATFORM_XCB_KHR+     | X11 Xcb library
+| +VK_KHR_wayland_surface+ | +VK_USE_PLATFORM_WAYLAND_KHR+ | Wayland
+| +VK_KHR_mir_surface+     | +VK_USE_PLATFORM_MIR_KHR+     | Mir
+| +VK_KHR_android_surface+ | +VK_USE_PLATFORM_ANDROID_KHR+ | Android Native
+| +VK_KHR_win32_surface+   | +VK_USE_PLATFORM_WIN32_KHR+   | Windows Win32
+|====
+
+// @refEnd WSIheaders

doc/specs/vulkan/appendices/extensions.txt

@@ -22,5 +22,5 @@ specific Vulkan extensions and layers, but rather specifies the processes by
 which extensions and layers are created. As of version 1.0.21 of the Vulkan
 Specification, this content has been migrated to the <<vulkan-styleguide,
 Vulkan Documentation and Extensions>>
-document. Authors creating extensions and layers must follow the mandatory
+document. Authors creating extensions and layers must: follow the mandatory
 procedures in that document.