Change log for May 27, 2016 Vulkan 1.0.15 spec update:

* Bump API patch number and header version number to 15 for this update. Github Issues: * Fixed the <<glossary,Glossary>> entry for Fragment Input Attachment Interface to specify code:UniformConstant storage class (public issue 156). * Disallow lazily allocated memory for buffers in the description of slink:VkMemoryRequirements::pname:memoryTypeBits (public issue 196). * Add numbered figure captions (public issue 219). * Fix output variable names in the <<fundamentals-fpfixedconv,Conversion from Floating-Point to Normalized Fixed-Point>> section and related minor normative language and markup cleanup (public issue 220). Internal Issues: * Fix reference to nonexistent etext:VK_IMAGE_LAYOUT_TRANSFER_{SRC,DST}BIT to the actual etext:VK_IMAGE_LAYOUT{SRC,DST}_OPTIMAL (internal issue 296). * Update the <<sparsememory-sparse-memory-aliasing,Sparse Resource Implementation Guidelines>> to refer to the correct feature names (internal issue 305).
KhronosGroup · May 27, 2016 · 36ce3ba · 36ce3ba
1 parent b3d4802
commit 36ce3ba
Show file tree

Hide file tree

Showing 13 changed files with 121 additions and 50 deletions.
diff --git a/ChangeLog.txt b/ChangeLog.txt
@@ -666,3 +666,31 @@ Other Commits:
   * Fix the names of decorations listed in the
     <<interfaces-builtin-variables,Built-in Variables>> section such
     that they match the SPIR-V specification.
+
+-----------------------------------------------------
+
+Change log for May 27, 2016 Vulkan 1.0.15 spec update:
+
+  * Bump API patch number and header version number to 15 for this
+    update.
+
+Github Issues:
+
+  * Fixed the <<glossary,Glossary>> entry for Fragment Input Attachment
+    Interface to specify code:UniformConstant storage class (public issue
+    156).
+  * Disallow lazily allocated memory for buffers in the description of
+    slink:VkMemoryRequirements::pname:memoryTypeBits (public issue 196).
+  * Add numbered figure captions (public issue 219).
+  * Fix output variable names in the <<fundamentals-fpfixedconv,Conversion
+    from Floating-Point to Normalized Fixed-Point>> section and related
+    minor normative language and markup cleanup (public issue 220).
+
+Internal Issues:
+
+  * Fix reference to nonexistent etext:VK_IMAGE_LAYOUT_TRANSFER_{SRC,DST}BIT
+    to the actual etext:VK_IMAGE_LAYOUT{SRC,DST}_OPTIMAL (internal issue
+    296).
+  * Update the <<sparsememory-sparse-memory-aliasing,Sparse Resource
+    Implementation Guidelines>> to refer to the correct feature names
+    (internal issue 305).
diff --git a/doc/specs/vulkan/Makefile b/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.14
+SPECREVISION = 1.0.15
 SPECREMARK =
 
 # Spec targets

diff --git a/doc/specs/vulkan/appendices/glossary.txt b/doc/specs/vulkan/appendices/glossary.txt
@@ -286,7 +286,7 @@ Flatshading::
     value unaltered.
 
 Fragment Input Attachment Interface::
-    A fragment shader entry point's variables with code:Input storage class
+    A fragment shader entry point's variables with code:UniformConstant storage class
     and a decoration of code:InputAttachmentIndex, which receive values from
     input attachments.
 

diff --git a/doc/specs/vulkan/chapters/drawing.txt b/doc/specs/vulkan/chapters/drawing.txt
@@ -100,8 +100,7 @@ triangles changes as shown in the figure, so that all triangle faces have
 the same orientation.
 
 [[fig-triangles]]
-.Triangle strips, fans, and lists
-image:images/triangles.{svgpdf}["Triangle strips, fans, and lists",{fullimagewidth}]
+image::images/triangles.{svgpdf}[align="center",title="Triangle strips, fans, and lists",{fullimagewidth}]
 
 ifdef::editing-notes[]
 [NOTE]
@@ -160,8 +159,7 @@ latexmath:[$4 i+1$]st and latexmath:[$4 i+2$]nd vertices, respectively, as
 shown in figure <<fig-lineadj>>.
 
 [[fig-lineadj]]
-.Lines with adjacency
-image:images/lineadj.{svgpdf}["Lines with adjacency",{fullimagewidth}]
+image::images/lineadj.{svgpdf}[align="center",title="Lines with adjacency",{fullimagewidth}]
 
 ifdef::editing-notes[]
 [NOTE]
@@ -215,8 +213,7 @@ latexmath:[$6 i+4$]th to the latexmath:[$6 i$]th vertices, respectively, as
 shown in figure <<fig-triadj>>.
 
 [[fig-triadj]]
-.Triangles with adjacency
-image:images/triadj.{svgpdf}["Triangles with adjacency",{fullimagewidth}]
+image::images/triadj.{svgpdf}[align="center",title="Triangles with adjacency",{fullimagewidth}]
 
 ifdef::editing-notes[]
 [NOTE]
@@ -284,8 +281,7 @@ both the first vertex and first triangle are numbered latexmath:[$0$].
 endif::editing-notes[]
 
 [[fig-tstripadj]]
-.Triangle strips with adjacency
-image:images/tstripadj.{svgpdf}["Triangle strips with adjacency",width="{svgpdf@pdf:400:800}"]
+image::images/tstripadj.{svgpdf}[align="center",title="Triangle strips with adjacency",width="{svgpdf@pdf:400:800}"]
 
 ifdef::editing-notes[]
 [NOTE]

diff --git a/doc/specs/vulkan/chapters/fundamentals.txt b/doc/specs/vulkan/chapters/fundamentals.txt
@@ -898,7 +898,7 @@ latexmath:[$f$] is performed using
 
 [latexmath]
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-\[ f = \max \left\{ {c \over {2^{b-1} - 1}}, -1.0 \right\} \]
+\[ f = \max( {c \over {2^{b-1} - 1}}, -1.0 ) \]
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 Only the range latexmath:[$[-2^{b-1}+1,2^{b-1}-1\]$] is used to represent
@@ -909,10 +909,7 @@ latexmath:[$1.0$]. Note that while zero is exactly expressible in this
 representation, one value (latexmath:[$-128$] in the example) is outside the
 representable range, and must: be clamped before use. This equation is used
 everywhere that signed normalized fixed-point values are converted to
-floating-point, including for all signed normalized fixed-point parameters
-in Vulkan commands, such as vertex attribute values, as well as for
-specifying texture or framebuffer values using signed normalized
-fixed-point.
+floating-point.
 
 
 [[fundamentals-fpfixedconv]]
@@ -926,15 +923,15 @@ then computing
 // Equation {glop:fund:convert:eqfloatuint}
 [latexmath]
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-\[ f' = \operatorname{convertFloatToUint} ( f \times ( 2^b - 1 ) , b ) \]
+\[ c = \operatorname{convertFloatToUint} ( f \times ( 2^b - 1 ) , b ) \]
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 where latexmath:[$\operatorname{convertFloatToUint}(r,b)$] returns one of
 the two unsigned binary integer values with exactly latexmath:[$b$] bits
-which are closest to the floating-point value latexmath:[$r$] (where
-rounding to nearest is preferred). If latexmath:[$r$] is equal to an
+which are closest to the floating-point value latexmath:[$r$].
+Implementations should: round to nearest. If latexmath:[$r$] is equal to an
 integer, then that integer value is returned. In particular, if
-latexmath:[$f$] is equal to 0.0 or 1.0, then latexmath:[$f'$] must: be
+latexmath:[$f$] is equal to 0.0 or 1.0, then latexmath:[$c$] must: be
 assigned 0 or latexmath:[$2^b-1$], respectively.
 
 The conversion from a floating-point value latexmath:[$f$] to the
@@ -945,22 +942,20 @@ then computing
 // Equation {glop:fund:convert:eqfloatsnorm}
 [latexmath]
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-\[ f' = \operatorname{convertFloatToInt} ( f \times ( 2^{b - 1} - 1 ) , b ) \]
+\[ c = \operatorname{convertFloatToInt} ( f \times ( 2^{b - 1} - 1 ) , b ) \]
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 where latexmath:[$\operatorname{convertFloatToInt}(r,b)$] returns one of the
 two signed two's-complement binary integer values with exactly
 latexmath:[$b$] bits which are closest to the floating-point value
-latexmath:[$r$] (where rounding to nearest is preferred). If latexmath:[$r$]
-is equal to an integer, then that integer value is returned. In particular,
-if latexmath:[$f$] is equal to -1.0, 0.0, or 1.0, then latexmath:[$f'$]
+latexmath:[$r$]. Implementations should: round to nearest. If latexmath:[$r$]
+is equal to an integer, then that integer value must: be returned. In particular,
+if latexmath:[$f$] is equal to -1.0, 0.0, or 1.0, then latexmath:[$c$]
 must: be assigned latexmath:[$-(2^{b-1}-1)$], 0, or latexmath:[$2^{b-1}-1$],
 respectively.
 
 This equation is used everywhere that floating-point values are converted to
-signed normalized fixed-point, including when querying floating-point state
-and returning integers, as well as for specifying signed normalized texture
-or framebuffer values using floating-point.
+signed normalized fixed-point.
 
 
 [[fundamentals-versionnum]]

diff --git a/doc/specs/vulkan/chapters/primsrast.txt b/doc/specs/vulkan/chapters/primsrast.txt
@@ -434,8 +434,7 @@ triangles where each pair of vertices at each end of the line has identical
 attributes.
 
 [[fig-non-strict-lines]]
-.Non strict lines
-image:images/non_strict_lines.{svgpdf}["Non strict lines",{fullimagewidth}]
+image::images/non_strict_lines.{svgpdf}[align="center",title="Non strict lines",{fullimagewidth}]
 
 
 [[primsrast-polygons]]
@@ -689,8 +688,8 @@ latexmath:[$m$] may: be approximated as
 [latexmath]
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 \begin{equation}
-m =  \max \left \{ \left |{\partial z_f \over \partial x_f} \right |,
-\left |{\partial z_f \over \partial y_f} \right | \right \}.
+m = \max( \left |{\partial z_f \over \partial x_f} \right |,
+\left |{\partial z_f \over \partial y_f} \right | ).
 \end{equation}
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 

diff --git a/doc/specs/vulkan/chapters/resources.txt b/doc/specs/vulkan/chapters/resources.txt
@@ -973,13 +973,27 @@ flink:vkGetImageMemoryRequirements:
     pname:flags member and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
     of the pname:usage member in the sname:VkImageCreateInfo structure
     passed to fname:vkCreateImage.
-  * The pname:memoryTypeBits member mustnot: refer to a sname:VkMemoryType
+  * If the memory requirements are for a sname:VkImage,
+    the pname:memoryTypeBits member mustnot: refer to a sname:VkMemoryType
     with a pname:propertyFlags that has the
     ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set if the
-    sname:VkImage does not have
+    flink:vkGetImageMemoryRequirements::pname:image did not have
     ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT bit set in the pname:usage
     member of the sname:VkImageCreateInfo structure passed to
     fname:vkCreateImage.
+  * If the memory requirements are for a sname:VkBuffer, the
+    pname:memoryTypeBits member mustnot: refer to a sname:VkMemoryType with
+    a pname:propertyFlags that has the
+    ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set.
++
+--
+[NOTE]
+.Note
+====
+The implication of this requirement is that lazily allocated memory is
+disallowed for buffers in all cases.
+====
+--
 
 To attach memory to a buffer object, call:
 

diff --git a/doc/specs/vulkan/chapters/sparsemem.txt b/doc/specs/vulkan/chapters/sparsemem.txt
@@ -67,7 +67,8 @@ feature enables specified in slink:VkPhysicalDeviceFeatures.
      accesses are considered safe, but reads will return undefined values.
   ** Requested via the ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT and
      ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT bits.
-  ** Support is advertised on a finer grain via the following features:
+  ** [[features-features-sparseResidency,Sparse residency support]] is
+     advertised on a finer grain via the following features:
 +
 --
   *** <<features-features-sparseResidencyBuffer,pname:sparseResidencyBuffer>>:
@@ -330,6 +331,7 @@ pixel size is the size of the compressed texel block (128-bit for etext:BC5)
 thus the dimensions of the standard sparse image block shapes apply in terms
 of compressed texel blocks.
 
+[NOTE]
 .Note
 ====
 For block-compressed formats, the dimensions of a sparse image block in terms
@@ -505,10 +507,11 @@ bind operation to set this. Without any other creation flags, no other
 constraints are relaxed compared to normal resources. All pages must: be
 bound to physical memory before the device accesses the resource.
 
-The pname:sparseResidency feature allows the sparse resource to be used even
+The <<features-features-sparseResidency,sparse residency>> features allow
+sparse resources to be used even
 when not all pages are bound to memory. Hardware that supports access to
 unbound pages without causing a fault may: support
-pname:sparseResidencyNonResidentStrict.
+pname:residencyNonResidentStrict.
 
 Not faulting on access to unbound pages is not enough to support
 pname:sparseResidencyNonResidentStrict. An implementation must: also

diff --git a/doc/specs/vulkan/chapters/tessellation.txt b/doc/specs/vulkan/chapters/tessellation.txt
@@ -68,9 +68,8 @@ position in a normalized parameter space, with parameter values in the range
 latexmath:[$[0,1\]$], as illustrated in figure
 <<img-tessellation-topology>>.
 
-[[img-tessellation-topology,Domain parameterization for tessellation primitive modes]]
-.Domain parameterization for tessellation primitive modes
-image:images/tessparam.{svgpdf}["Domain parameterization for tessellation primitive modes",{fullimagewidth}]
+[[img-tessellation-topology]]
+image::images/tessparam.{svgpdf}[align="center",title="Domain parameterization for tessellation primitive modes",{fullimagewidth}]
 
 For triangles, the vertex's position is a barycentric coordinate (u,v,w),
 where u + v + w = 1.0, and indicates the relative influence of the three
@@ -238,9 +237,8 @@ subdivision process repeats itself, using the generated triangle as an outer
 triangle. This subdivision process is illustrated in <<img-innertri,Inner
 Triangle Tessellation>>.
 
-[[img-innertri,Inner Triangle Tessellation]]
-.Inner Triangle Tessellation
-image:images/innertri.{svgpdf}["Inner Triangle Tessellation",{fullimagewidth}]
+[[img-innertri]]
+image::images/innertri.{svgpdf}[align="center",title="Inner Triangle Tessellation",{fullimagewidth}]
 
 // TODO: Add caption:
 //  Inner triangle tessellation with inner tessellation
@@ -340,9 +338,8 @@ latexmath:[$n$] is two, the inner rectangle is degenerate, and one or both
 of the rectangle's _edges_ consist of a single point. This subdivision is
 illustrated in Figure <<img-innerquad,Inner Quad Tessellation>>.
 
-[[img-innerquad,Inner Quad Tessellation]]
-.Inner Quad Tessellation
-image:images/innerquad.{svgpdf}["Inner Quad Tessellation",{fullimagewidth}]
+[[img-innerquad]]
+image::images/innerquad.{svgpdf}[align="center",title="Inner Quad Tessellation",{fullimagewidth}]
 
 // TODO: Add caption:
 //  Inner quad tessellation with inner tessellation

diff --git a/doc/specs/vulkan/style/styleguide.txt b/doc/specs/vulkan/style/styleguide.txt
@@ -236,6 +236,25 @@ the macros defined by asciidoc itself, additional macros are defined by the
 Specification and Reference Page configuration files.
 
 
+[[markup-samplesection-images]]
+=== Figures
+
+All figures (images) must be marked up as follows, to ensure there's an
+anchor and that the figure is given a caption which shows the figure number
+and is added to the list of figures:
+
+.Example Markup
+----
+[[fig-anchorname]]
+image::images/imagename.{svgpdf}[align="center",title="Figure caption",{fullimagewidth}]
+----
+
+There must be both .svg and .pdf versions of each figure checked into the
++images/+ directory, to support generating both HTML and PDF outputs. It is
+best to create images in Inkscape as SVG files and then use the conversion
+rule in +images/Makefile+ to generate PDF.
+
+
 === API Markup Macros
 
 These macros must: be used to tag command, structure, enumeration,
@@ -973,6 +992,8 @@ for this structure:
 
 = Revision History
 
+* May 22, 2016 - Add markup and image creation rules, after fixing missing
+  figure captions for public Github issue 219.
 * May 1, 2016 - Include feedback from public Github issues 120 and 190. Use
   consistent conventions for defining structures. Use American rather than
   British spelling conventions.

diff --git a/doc/specs/vulkan/validity/protos/vkCmdBeginRenderPass.txt b/doc/specs/vulkan/validity/protos/vkCmdBeginRenderPass.txt
@@ -17,8 +17,8 @@ endif::doctype-manpage[]
 * 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_BIT 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_BIT 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_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
 ifndef::doctype-manpage[]
 ********************************************************************************
 endif::doctype-manpage[]