Change log for March 25, 2016 Vulkan 1.0.7 spec update:

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

Github Issues:

  * Fix slink:VkSpecializationMapEntry example to avoid C/C++ strict
    aliasing issues (public issue 14).

  * Clarify the meaning of "matching" in flink:vkCmdBindDescriptorSets
    validity language (public issue 33).

  * Add stub reference pages so xrefs to not-yet-written pages don't
    generate 404 errors. However, the actual content of these pages
    still needs to be filled in as time allows (public issue 44, but
    does not close that issue out).

  * Remove incorrect validity statement for
    flink:vkGetImageSparseMemoryRequirements (public issue 85).

  * Reword the
    <<features-limits-bufferImageGranularity,bufferImageGranularity>>
    feature in terms of "aliasing", and clarify that it applies to
    bindings in the same memory object (public issue 90).

  * Clarify the relationship of the slink:VkPhysicalDeviceLimits
    pname:maxViewportDimensions and pname:viewportBoundsRange limits
    (public issue 92).

  * Specify sparse unbound texture replacement in the
    <<textures-texel-replacement,Texel Replacement>> section
    independently of robust buffer access language (public issue 100).

  * Add the <<fundamentals-architecture-model,Architecture Model>>
    section to explain architecture constraints Vulkan has chosen to
    accept in order to enable portable and performant code (public issue
    122).

  * State that an object must not be destroyed until *all* (not *any*)
    uses of that object have completed (public issue 123).

  * Minor editorial cleanup (public issues 129, 134, 146, 148).

  * Add validity language for layer and extension names to
    slink:VkDeviceCreateInfo matching that used for
    slink:VkInstanceCreateInfo (public issue 130).

  * Clean up terminology for the case when the bits set in one bitmask
    are a subset of the bits set in another bitmask (public issue 138).

  * Document that input attachments are UniformConstant not Input, in
    the <<interfaces-inputattachment,Fragment Input Attachment
    Interface>> section (public glslang bug 169).

Internal Issues:

  * Add max enum values to "flag bits" enums (internal issue flutter#136).

  * Clarify language around the various uses of the term "block" in the
    <<appendix-compressedtex-bc,Block Compressed Image Formats>> section
    (internal issue flutter#202).

  * Removed "expand" dependency from <enums> groups in vk.xml and added
    auto-generation code in the scripts to infer it instead, to ensure
    consistency. This caused renaming of sname:VkColorSpaceKHR and
    sname:VkPresentModeKHR etext:BEGIN_RANGE (etc.) tokens, but those
    tokens are metadata, not part of the API, and the Vulkan WG is OK
    with this change. This change adds ranges to two additional enums
    that were missing them due to not defining the "expand" attribute
    (internal issue 217).

  * Tweak makefile to generate ref page nroff (.3) files in the right
    output directory, working around an a2x limitation (internal issue
    223).

Other Commits:

  * Add validity requirements for flink:vkCmdCopyQueryPoolResults
    pname:dstBuffer parameter.

  * Fix ref page build to generate .3 targets in the right output
    directory.

Author: oddhack

ChangeLog.txt

@@ -273,3 +273,89 @@ Other Commits:
 
   * Update GL_KHR_vulkan_glsl so push_constants do not have descriptor
     sets.
+
+-----------------------------------------------------
+
+Change log for March 25, 2016 Vulkan 1.0.7 spec update:
+
+  * Bump API patch number and header version number to 7 for this
+    update.
+
+Github Issues:
+
+  * Fix slink:VkSpecializationMapEntry example to avoid C/C++ strict
+    aliasing issues (public issue 14).
+
+  * Clarify the meaning of "matching" in flink:vkCmdBindDescriptorSets
+    validity language (public issue 33).
+
+  * Add stub reference pages so xrefs to not-yet-written pages don't
+    generate 404 errors. However, the actual content of these pages
+    still needs to be filled in as time allows (public issue 44, but
+    does not close that issue out).
+
+  * Remove incorrect validity statement for
+    flink:vkGetImageSparseMemoryRequirements (public issue 85).
+
+  * Reword the
+    <<features-limits-bufferImageGranularity,bufferImageGranularity>>
+    feature in terms of "aliasing", and clarify that it applies to
+    bindings in the same memory object (public issue 90).
+
+  * Clarify the relationship of the slink:VkPhysicalDeviceLimits
+    pname:maxViewportDimensions and pname:viewportBoundsRange limits
+    (public issue 92).
+
+  * Specify sparse unbound texture replacement in the
+    <<textures-texel-replacement,Texel Replacement>> section
+    independently of robust buffer access language (public issue 100).
+
+  * Add the <<fundamentals-architecture-model,Architecture Model>>
+    section to explain architecture constraints Vulkan has chosen to
+    accept in order to enable portable and performant code (public issue
+    122).
+
+  * State that an object must not be destroyed until *all* (not *any*)
+    uses of that object have completed (public issue 123).
+
+  * Minor editorial cleanup (public issues 129, 134, 146, 148).
+
+  * Add validity language for layer and extension names to
+    slink:VkDeviceCreateInfo matching that used for
+    slink:VkInstanceCreateInfo (public issue 130).
+
+  * Clean up terminology for the case when the bits set in one bitmask
+    are a subset of the bits set in another bitmask (public issue 138).
+
+  * Document that input attachments are UniformConstant not Input, in
+    the <<interfaces-inputattachment,Fragment Input Attachment
+    Interface>> section (public glslang bug 169).
+
+Internal Issues:
+
+  * Add max enum values to "flag bits" enums (internal issue #136).
+
+  * Clarify language around the various uses of the term "block" in the
+    <<appendix-compressedtex-bc,Block Compressed Image Formats>> section
+    (internal issue #202).
+
+  * Removed "expand" dependency from <enums> groups in vk.xml and added
+    auto-generation code in the scripts to infer it instead, to ensure
+    consistency. This caused renaming of sname:VkColorSpaceKHR and
+    sname:VkPresentModeKHR etext:BEGIN_RANGE (etc.) tokens, but those
+    tokens are metadata, not part of the API, and the Vulkan WG is OK
+    with this change. This change adds ranges to two additional enums
+    that were missing them due to not defining the "expand" attribute
+    (internal issue 217).
+
+  * Tweak makefile to generate ref page nroff (.3) files in the right
+    output directory, working around an a2x limitation (internal issue
+    223).
+
+Other Commits:
+
+  * Add validity requirements for flink:vkCmdCopyQueryPoolResults
+    pname:dstBuffer parameter.
+
+  * Fix ref page build to generate .3 targets in the right output
+    directory.

doc/specs/vulkan/Makefile

@@ -44,7 +44,7 @@ ECHO:=echo
 # XHTMLDIR - 'xhtml' target
 # PDFDIR - 'pdf' target
 # CHECKDIR - 'allchecks' target
-OUTDIR :=../../../out/core
+OUTDIR :=../../../out/1.0
 HTMLDIR := $(OUTDIR)/html
 XHTMLDIR := $(OUTDIR)/xhtml
 PDFDIR := $(OUTDIR)/pdf
@@ -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.6
+SPECREVISION = 1.0.7
 SPECREMARK =
 
 # Spec targets

doc/specs/vulkan/appendices/compressedtex.txt

@@ -24,7 +24,7 @@ Format Specification.
 <<<
 
 [[appendix-compressedtex-bc]]
-== Block Compressed Image Formats
+== Block-Compressed Image Formats
 
 .Mapping of {apiname} BC formats to descriptions
 [width="90%",options="header",cols="5,4"]
@@ -86,7 +86,7 @@ chapter of the Khronos Data Format Specification.
 .Mapping of {apiname} ASTC formats to descriptions
 [width="75%",options="header",cols="63%,15%,22%"]
 |==============================
-| VkFormat ^| Block size ^| sRGB-encoded
+| VkFormat ^| Compressed texel block dimensions ^| sRGB-encoded
 | ename:VK_FORMAT_ASTC_4x4_UNORM_BLOCK    ^|latexmath:[$4\times 4$] ^|No
 | ename:VK_FORMAT_ASTC_4x4_SRGB_BLOCK     ^|latexmath:[$4\times 4$] ^|Yes
 | ename:VK_FORMAT_ASTC_5x4_UNORM_BLOCK    ^|latexmath:[$5\times 4$] ^|No

doc/specs/vulkan/appendices/extensions.txt

@@ -415,14 +415,14 @@ The information needed to add new values to the XML are as follows:
     positive, if not specified.
 
 Implicit is the registered number of an extension, which is used to create a
-block of unused values offset against a global extension base value.
-Individual enumerant values are calculated as offsets in that block. Values
+range of unused values offset against a global extension base value.
+Individual enumerant values are calculated as offsets in that range. Values
 are calculated as follows:
 
   * base_value = 1000000000
-  * block_size = 1000
+  * range_size = 1000
   * enum_offset(extension_number,offset) = base_value +
-    (extension_number - 1) × block_size + offset
+    (extension_number - 1) × range_size + offset
   * Positive values: enum_offset(extension_number,offset)
   * Negative values: -enum_offset(extension_number,offset)
 

doc/specs/vulkan/appendices/glossary.txt

@@ -139,6 +139,14 @@ Compatible Queues::
     Queues within a queue family. Compatible queues have identical
     properties.
 
+Compressed Texel Block::
+    An element of an image having a block-compressed format, comprising a
+    rectangular block of texel values that are encoded as a single value in
+    memory. Compressed texel blocks of a particular block-compressed format
+    have a corresponding width, height, and depth that define the dimensions
+    of these elements in units of texels, and a size in bytes of the encoding
+    in memory.
+
 Cull Distance::
     A built-in output from vertex processing stages that defines a cull
     half-space where the primitive is rejected if all vertices have a
@@ -435,8 +443,8 @@ Memory Type::
 
 Mip Tail Region::
     The set of mipmap levels of a sparse residency texture that are too
-    small to fill a block, and that must all be bound to memory collectively
-    and opaquely.
+    small to fill a sparse block, and that must all be bound to memory
+    collectively and opaquely.
 
 Non-Dispatchable Handle::
     A handle of an integer handle type. Handle values may: not be unique,
@@ -607,6 +615,18 @@ Shader Stage::
 Side Effect::
     A store to memory or atomic operation on memory from a shader invocation.
 
+Sparse Block::
+    An element of a sparse resource that can be independently bound to memory.
+    Sparse blocks of a particular sparse resource have a corresponding size
+    in bytes that they use in the bound memory.
+
+Sparse Image Block::
+    A sparse block in a sparse partially-resident image. In addition to the
+    sparse block size in bytes, sparse image blocks have a corresponding
+    width, height, and depth that define the dimensions of these elements
+    in units of texels or compressed texel blocks, the latter being used in
+    case of sparse images having a block-compressed format.
+
 Sparse Unbound Texel::
     A texel read from a region of a sparse texture that does not have
     memory bound to it.

doc/specs/vulkan/chapters/copies.txt

@@ -28,7 +28,8 @@ Some rules for valid operation are common to all copy commands:
   * Copy regions must: be non-empty.
   * Regions must: not extend outside the bounds of the buffer or image
     level, except that regions of compressed images can: extend as far as
-    the dimension of the image level rounded up to a complete block.
+    the dimension of the image level rounded up to a complete compressed
+    texel block.
   * Source image subresources must: be in either the
     ename:VK_IMAGE_LAYOUT_GENERAL or
     ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL layout. Destination image
@@ -154,51 +155,57 @@ destination. pname:layerCount layers are copied to the destination image.
 The formats of pname:srcImage and pname:dstImage must: be compatible.
 Formats are considered compatible if their texel size in bytes is the same
 between both formats. For example, ename:VK_FORMAT_R8G8B8A8_UNORM is
-compatible with ename:VK_FORMAT_R32_UINT because because both texels are 4
+compatible with ename:VK_FORMAT_R32_UINT because both texels are 4
 bytes in size. Depth/stencil formats must: match exactly.
 
 fname:vkCmdCopyImage allows copying between size-compatible compressed
 and uncompressed internal formats. Formats are size-compatible if the texel
-size of the uncompressed format is equal to the block size in bytes of the
-compressed format. Such a copy does not perform on-the-fly compression or
-decompression. When copying from an uncompressed format to a compressed
-format, each texel of uncompressed data becomes a single block of compressed
-data. When copying from a compressed format to an uncompressed format, a
-block of compressed data becomes a single texel of uncompressed data. Thus,
-for example, it is legal to copy between a 128-bit uncompressed format and a
-compressed format which uses 8-bit/texel 4x4 blocks, or between a 64-bit
-uncompressed format and a compressed format which uses 4-bit/texel 4x4
-blocks.
+size of the uncompressed format is equal to the compressed texel block size in
+bytes of the compressed format. Such a copy does not perform on-the-fly
+compression or decompression. When copying from an uncompressed format to a
+compressed format, each texel of uncompressed data of the source image is
+copied as a raw value to the corresponding compressed texel block of the
+destination image. When copying from a compressed format to an uncompressed
+format, each compressed texel block of the source image is copied as a raw
+value to the corresponding texel of uncompressed data in the destination
+image. Thus, for example, it is legal to copy between a 128-bit uncompressed
+format and a compressed format which has a 128-bit sized compressed texel
+block representing 4x4 texels (using 8 bits per texel), or between a 64-bit
+uncompressed format and a compressed format which has a 64-bit sized
+compressed texel block representing 4x4 texels (using 4 bits per texel).
 
 When copying between compressed and uncompressed formats the pname:extent
 members represent the texel dimensions of the source image and not the
 destination. When copying from a compressed image to an uncompressed image
 the image texel dimensions written to the uncompressed image will be source
-extent divided by the block size. When copying from an uncompressed image to
-a compressed image the image texel dimensions written to the compressed
-image will be the source extent multiplied by the block size. In both cases
-the number of bytes read and the number of bytes written will be identical.
+extent divided by the compressed texel block dimensions. When copying from an
+uncompressed image to a compressed image the image texel dimensions written
+to the compressed image will be the source extent multiplied by the
+compressed texel block dimensions. In both cases the number of bytes read and
+the number of bytes written will be identical.
 
 Copying to or from block-compressed images is typically done in multiples of
-the block. For this reason the pname:extent must: be a multiple of the
-block dimension. There is one exception to this rule which is required: to
-handle compressed images created with dimensions that are not a multiple
-of the block dimensions. If the pname:srcImage is compressed and if
-pname:extent.width is not a multiple of the block width then
-(pname:extent.width + pname:srcOffset.x) must: equal the subresource width,
-if pname:extent.height is not a multiple of the block height then
-(pname:extent.height + pname:srcOffset.y) must: equal
-the subresource height and if pname:extent.depth is not a multiple of the
-block depth then (pname:extent.depth + pname:srcOffset.z) must: equal
-the subresource depth. Similarily if the pname:dstImage is compressed and
-if pname:extent.width is not a multiple of the block width then
-(pname:extent.width + pname:dstOffset.x) must: equal the subresource width,
-if pname:extent.height is not a multiple of the block height then
-(pname:extent.height + pname:dstOffset.y) must: equal
-the subresource height and if pname:extent.depth is not a multiple of the
-block depth then (pname:extent.depth + pname:dstOffset.z) must: equal
-the subresource depth. This allows the last block of the image in each
-non-multiple dimension to be included as a source or target of the copy.
+the compressed texel block. For this reason the pname:extent must: be a
+multiple of the compressed texel block dimension. There is one exception to
+this rule which is required: to handle compressed images created with
+dimensions that are not a multiple of the compressed texel block dimensions.
+If the pname:srcImage is compressed and if pname:extent.width is not a
+multiple of the compressed texel block width then (pname:extent.width +
+pname:srcOffset.x) must: equal the subresource width, if pname:extent.height
+is not a multiple of the compressed texel block height then
+(pname:extent.height + pname:srcOffset.y) must: equal the subresource height
+and if pname:extent.depth is not a multiple of the compressed texel block
+depth then (pname:extent.depth + pname:srcOffset.z) must: equal the
+subresource depth. Similarily if the pname:dstImage is compressed and if
+pname:extent.width is not a multiple of the compressed texel block width then
+(pname:extent.width + pname:dstOffset.x) must: equal the subresource width, if
+pname:extent.height is not a multiple of the compressed texel block height
+then (pname:extent.height + pname:dstOffset.y) must: equal the subresource
+height and if pname:extent.depth is not a multiple of the compressed texel
+block depth then (pname:extent.depth + pname:dstOffset.z) must: equal the
+subresource depth. This allows the last compressed texel block of the image
+in each non-multiple dimension to be included as a source or destination of
+the copy.
 
 fname:vkCmdCopyImage can: be used to copy image data between multisample
 images, but both images must: have the same number of samples.
@@ -330,8 +337,8 @@ buffer memory. Instead, pname:bufferOffset can: be used to
 select the starting address in buffer memory.
 
 For block-compression formats, all parameters are still specified in texels
-rather than blocks, but the addressing math operates on whole blocks.
-Pseudocode for compressed copy addressing is:
+rather than compressed texel blocks, but the addressing math operates on
+whole compressed texel blocks. Pseudocode for compressed copy addressing is:
 
 [source,c]
 ---------------------------------------------------
@@ -343,28 +350,30 @@ imageHeight = region->bufferImageHeight;
 if (imageHeight == 0)
     imageHeight = region->imageExtent.height;
 
-blockSizeInBytes = <block size taken from the src/dstImage>;
-rowLength /= blockWidth;
-imageHeight /= blockHeight;
+compressedTexelBlockSizeInBytes = <compressed texel block size taken from the src/dstImage>;
+rowLength /= compressedTexelBlockWidth;
+imageHeight /= compressedTexelBlockHeight;
 
-address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * blockSizeInBytes;
+address of (x,y,z) = region->bufferOffset + (((z * imageHeight) + y) * rowLength + x) * compressedTexelBlockSizeInBytes;
 
-where x,y,z range from (0,0,0) to region->imageExtent.{width/blockWidth,height/blockHeight,depth/blockDepth}.
+where x,y,z range from (0,0,0) to region->imageExtent.{width/compressedTexelBlockWidth,height/compressedTexelBlockHeight,depth/compressedTexelBlockDepth}.
 ---------------------------------------------------
 
 Copying to or from block-compressed images is typically done in multiples of
-the block. For this reason the pname:imageExtent must: be a multiple of the
-block dimension. There is one exception to this rule which is required: to
-handle compressed images created with dimensions that are not a multiple of
-the block dimensions. If pname:imageExtent.width is not a multiple of the
-block width then (pname:imageExtent.width + pname:imageOffset.x) must: equal
-the subresource width, if pname:imageExtent.height is not a multiple of the
-block height then (pname:imageExtent.height + pname:imageOffset.y) must:
-equal the subresource height and if pname:imageExtent.depth is not a
-multiple of the block depth then (pname:imageExtent.depth +
-pname:imageOffset.z) must: equal the subresource depth. This allows the last
-block of the image in each non-multiple dimension to be included as a source
-or target of the copy.
+the compressed texel block. For this reason the pname:imageExtent must: be a
+multiple of the compressed texel block dimension. There is one exception to
+this rule which is required: to handle compressed images created with
+dimensions that are not a multiple of the compressed texel block dimensions.
+If pname:imageExtent.width is not a multiple of the compressed texel block
+width then (pname:imageExtent.width + pname:imageOffset.x) must: equal the
+subresource width, if pname:imageExtent.height is not a multiple of the
+compressed texel block height then (pname:imageExtent.height +
+pname:imageOffset.y) must: equal the subresource height and if
+pname:imageExtent.depth is not a multiple of the compressed texel block depth
+then (pname:imageExtent.depth + pname:imageOffset.z) must: equal the
+subresource depth. This allows the last compressed texel block of the image
+in each non-multiple dimension to be included as a source or destination of
+the copy.
 
 
 [[copies-imagescaling]]

doc/specs/vulkan/chapters/devsandqueues.txt

@@ -220,8 +220,9 @@ include::../validity/structs/VkQueueFamilyProperties.txt[]
 
 For further details see <<devsandqueues-queues,Queues>>.
 
-The value returned in pname:minImageTransferGranularity has a unit of blocks
-for images having a block compressed format, and a unit of texels otherwise.
+The value returned in pname:minImageTransferGranularity has a unit of
+compressed texel blocks for images having a block-compressed format, and a
+unit of texels otherwise.
 
 Possible values of pname:minImageTransferGranularity are:
 
@@ -257,8 +258,9 @@ Possible values of pname:minImageTransferGranularity are:
      equal the depth of the image subresource corresponding to the
      parameter.
   ** If the format of the image corresponding to the parameters is one of
-     the block compressed formats then for the purposes of the above
-     calculations the granularity must: be scaled up by the block size.
+     the block-compressed formats then for the purposes of the above
+     calculations the granularity must: be scaled up by the compressed
+     texel block dimensions.
 
 Queues supporting graphics and/or compute operations must: report
 latexmath:[$(1,1,1)$] in pname:minImageTransferGranularity, meaning that