diff --git a/ChangeLog.txt b/ChangeLog.txt
index 1eeb5fc4..7ebc08e0 100644
--- a/ChangeLog.txt
+++ b/ChangeLog.txt
@@ -526,3 +526,117 @@ Other Commits:
on relevant script/XML/header files. This does not affect the
specification source copyright.
+-----------------------------------------------------
+
+Change log for April 29, 2016 Vulkan 1.0.12 spec update:
+
+ * Bump API patch number and header version number to 12 for this
+ update.
+
+Github Issues:
+
+ * Change valid usage statements intended to be "sub-points" to
+ be actual sub-points (public issue 66).
+ * Replace double negation in description of
+ slink:VkRenderPassBeginInfo::pname:pClearValues (based on public
+ merge 142).
+ * Cleanup minor typos in spec, ref pages and XML, including those
+ proposed in public pull requests 144, 150, 151, 167, 168, 181, and
+ 186.
+ * Use *strict subset* in describing the partial order of memory
+ property types for slink:VkMemoryType, and update the style guide
+ accordingly (public issue 190).
+ * Fix various "a image" -> "an image" typos (public issue 191).
+ * Note in the <> and
+ <> sections that
+ structures defined by extensions which may be passed in structure
+ chains using the ptext:pNext member must: include initial
+ ptext:sType and ptext:pNext members (public issue 192).
+
+Internal Issues:
+
+ * Remove duplicate language from the description of the pname:fence
+ parameter to flink:vkQueueSubmit and improve validity language
+ (internal issue 91).
+ * Added documentation for "optional" attribute to XML readme.tex/pdf
+ (internal issue 149).
+ * Clarify the host-side data validity rules and behavior of
+ flink:vkFlushMappedMemoryRanges and
+ flink:vkInvalidateMappedMemoryRanges (internal issue 266).
+
+Other Commits:
+
+ * Added clarification to flink:vkCmdFillBuffer regarding the use of
+ ename:VK_WHOLE_SIZE.
+ * Fixed and documented implementation of "validextensionstructs"
+ attribute. in XML processing scripts and readme.tex/pdf.
+ * Add missing validity statements to flink:vkResetEvent and
+ flink:vkCmdResetEvent.
+ * Fix validity for the
+ ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag.
+ Correct all the draw/dispatch commands to mention optimally tiled
+ images as well as linear tiled images, and say image VIEWS instead
+ of images. Add validity statement to flink:vkCmdBlitImage
+ * Replace the {apiname} macro with hardcoded "Vulkan", now that we've
+ committed to that name.
+ * Add the VK_AMD_rasterization_order extension to vk.xml.
+
+-----------------------------------------------------
+
+Change log for May 13, 2016 Vulkan 1.0.13 spec update:
+
+ * Bump API patch number and header version number to 13 for this
+ update.
+
+Github Issues:
+
+ * Improve the description of ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR in the
+ VK_KHR_surface extension (public issue 174).
+ * Clarify use of etext:*_SIMULTANEOUS_USE_BIT for secondary command
+ buffers (public issue 182).
+ * Fix typos in VK_KHR_wayland_surface extension where code:wl_device was
+ used instead of code:wl_display (public issue 193).
+ * Replaced {apiname} with ``Vulkan'' in XML validity statements (public
+ issue 199).
+ * Fix dead links for WSI handle types (public issue 200).
+ * Use "signaled" instead of "signalled" spelling everywhere (public issue
+ 201).
+ * Move readme.pdf target directory for XML schema documentation into the
+ target generation directory, instead of leaving it checked into the spec
+ source tree (public issue 203).
+ * Fix duplicate 'which which' typo in description of
+ elink:VkCommandPoolResetFlagBits (public issue 204).
+ * Move the <> section up one level, out of
+ the <> section
+ (public issue 209).
+
+Internal Issues:
+
+ * Clarify in the <> section that
+ implementations should not manage the size of pipeline cache (internal
+ issue 192).
+ * Deprecate the concept of device layers and associated commands (internal
+ issue 255).
+ * Remove ename:VK_INCOMPLETE from the list of possible result codes of
+ flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR (internal issue 314).
+ * Add missing std140/std430 rule: the base alignment of a member following
+ a structure is a multiple of the structure's base alignment (internal
+ issue 321).
+ * Fixes naming of the single elink:VkColorSpaceKHR enum from
+ ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR to
+ ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR in XML/header and the
+ VK_KHR_swapchain and VK_KHR_surface extensions to match the style of the
+ typename (space and color are two words, not one) (internal issue 322).
+ * Make it clear that code:LocalInvocationID should only be applied to an
+ input variable and normalize the language describing
+ code:LocalInvocationID to the language for other compute shader
+ variables in the <>
+ section, and add normative language (internal issue 323).
+ * Clarify in the <> section that
+ the result pointer may be modified for specific commands, even if a
+ runtime error is returned (internal issue 324).
+
+
+
+
+
diff --git a/doc/specs/vulkan/Makefile b/doc/specs/vulkan/Makefile
index b09702da..72358b13 100644
--- a/doc/specs/vulkan/Makefile
+++ b/doc/specs/vulkan/Makefile
@@ -26,7 +26,6 @@ allchecks: checkinc checklinks
# Note that the := assignments below are immediate, not deferred, and
# are therefore order-dependent in the Makefile
-APINAME=Vulkan
QUIET?=@
ASCIIDOC ?= asciidoc.py
A2X ?= a2x.py
@@ -44,7 +43,7 @@ ECHO:=echo
# XHTMLDIR - 'xhtml' target
# PDFDIR - 'pdf' target
# CHECKDIR - 'allchecks' target
-OUTDIR :=../../../out/1.0
+OUTDIR := ../../../out/1.0
HTMLDIR := $(OUTDIR)/html
XHTMLDIR := $(OUTDIR)/xhtml
PDFDIR := $(OUTDIR)/pdf
@@ -64,14 +63,14 @@ KEEP =
# asciidoc / a2x attributes to set.
# XMLLINT normally unset - to detect problems with intermediate files
# NOTEOPTS sets options controlling which NOTEs are generated
-# ATTRIBOPTS sets {apiname} to "Vulkan" and enables MathJax generation
+# ATTRIBOPTS sets the api revision and enables MathJax generation
# VKCONF contains Vulkan-specific Asciidoc macros
# ADOCOPTS options for asciidoc->HTML output
# ADOCPDFOPTS options for asciidoc->PDF output via dblatex (not using a2x)
# A2XOPTS options for a2x->{HTML,PDF} output
XMLLINT = --no-xmllint
NOTEOPTS = -a editing-notes -a implementation-guide
-ATTRIBOPTS = -a apiname=$(APINAME)@ -a apirevision="$(SPECREVISION)" -a mathjax
+ATTRIBOPTS = -a apirevision="$(SPECREVISION)" -a mathjax
VKCONF = config/vkspec.conf
ADOCOPTS = $(ATTRIBOPTS) $(NOTEOPTS) -f config/mathjax-asciidoc.conf \
-f $(VKCONF) $(VERBOSE)
@@ -126,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.11
+SPECREVISION = 1.0.13
SPECREMARK =
# Spec targets
diff --git a/doc/specs/vulkan/appendices/VK_KHR_sampler_mirror_clamp_to_edge.txt b/doc/specs/vulkan/appendices/VK_KHR_sampler_mirror_clamp_to_edge.txt
index 054334ba..3bc18fed 100644
--- a/doc/specs/vulkan/appendices/VK_KHR_sampler_mirror_clamp_to_edge.txt
+++ b/doc/specs/vulkan/appendices/VK_KHR_sampler_mirror_clamp_to_edge.txt
@@ -7,7 +7,7 @@
*Last Modified Date*:: 16/02/2016
*Revision*:: 1
*Dependencies*::
- - This extension is written against version 1.0. of the {apiname} API.
+ - This extension is written against version 1.0. of the Vulkan API.
*Contributors*::
- Tobias Hector, Imagination Technologies
*Contacts*::
diff --git a/doc/specs/vulkan/appendices/compressedtex.txt b/doc/specs/vulkan/appendices/compressedtex.txt
index f4c9d3eb..880fb9d2 100644
--- a/doc/specs/vulkan/appendices/compressedtex.txt
+++ b/doc/specs/vulkan/appendices/compressedtex.txt
@@ -26,7 +26,7 @@ Format Specification.
[[appendix-compressedtex-bc]]
== Block-Compressed Image Formats
-.Mapping of {apiname} BC formats to descriptions
+.Mapping of Vulkan BC formats to descriptions
[width="90%",options="header",cols="5,4"]
|==============================
| VkFormat | Data Format Specification description
@@ -59,7 +59,7 @@ Format Specification.
The following formats are described in the ``ETC2 Compressed Texture Image
Formats'' chapter of the Khronos Data Format Specification.
-.Mapping of {apiname} ETC formats to descriptions
+.Mapping of Vulkan ETC formats to descriptions
[options="header",cols="1,1"]
|==============================
| VkFormat | Data Format Specification description
@@ -83,7 +83,7 @@ Formats'' chapter of the Khronos Data Format Specification.
ASTC formats are described in the ``ASTC Compressed Texture Image Formats''
chapter of the Khronos Data Format Specification.
-.Mapping of {apiname} ASTC formats to descriptions
+.Mapping of Vulkan ASTC formats to descriptions
[width="75%",options="header",cols="63%,15%,22%"]
|==============================
| VkFormat ^| Compressed texel block dimensions ^| sRGB-encoded
diff --git a/doc/specs/vulkan/appendices/extensions.txt b/doc/specs/vulkan/appendices/extensions.txt
index f03c812c..f99c3f63 100644
--- a/doc/specs/vulkan/appendices/extensions.txt
+++ b/doc/specs/vulkan/appendices/extensions.txt
@@ -6,9 +6,9 @@
[[extensions]]
= Layers & Extensions
-Extensions to the {apiname} API can: be defined by authors, groups of
-authors, and the Khronos {apiname} Working Group. In order not to compromise
-the readability of the {apiname} Specification, the core Specification does
+Extensions to the Vulkan API can: be defined by authors, groups of
+authors, and the Khronos Vulkan Working Group. In order not to compromise
+the readability of the Vulkan Specification, the core Specification does
not incorporate most extensions. The online registry of extensions is
available at URL
@@ -41,7 +41,7 @@ several purposes:
* Provides a central repository for documentation and header changes
associated with extensions
-{apiname}'s design and general software development trends introduces two
+Vulkan's design and general software development trends introduces two
new paradigms that require rethinking the existing mechanisms:
* Layers, and with them a focus on a more open ecosystem where non-Khronos
@@ -63,7 +63,7 @@ Some general rules to simplify the specific rules below:
* All extensions must: be registered with Khronos.
* Extensions must: be strictly additive and backwards-compatible. That is,
extensions mustnot: remove existing functionality, or change existing
- default behaviors. A {apiname} implementation may: support any
+ default behaviors. A Vulkan implementation may: support any
combination of extensions, but applications written using only the core
API, or a subset of the supported extensions, must: continue to work in
such an implementation without changes in behavior.
@@ -78,8 +78,8 @@ Both extensions and layer names include a +VK_+ prefix. In addition, layers
add a +LAYER_+ prefix. Extension and layer names also contain an _author
prefix_ identifying the author of the extension/layer. This prefix is a
short, capitalized, registered string identifying an author, such as a
-Khronos member developing {apiname} implementations for their devices, or a
-non-Khronos developer creating {apiname} layers.
+Khronos member developing Vulkan implementations for their devices, or a
+non-Khronos developer creating Vulkan layers.
Some authors have platform communities they wish to distinguish between, and
can: register additional author prefixes for that purpose. For example,
@@ -98,7 +98,7 @@ only for layers.
will use the prefix +VK_KHR_+.
** The following author prefixes are reserved and mustnot: be used:
*** +VK+ - To avoid confusion with the top-level +VK_+ prefix.
- *** +VULKAN+ - To avoid confusion with the name of the {apiname} API.
+ *** +VULKAN+ - To avoid confusion with the name of the Vulkan API.
*** +LAYER+ - To avoid confusion with the higher-level ``LAYER'' prefix.
*** +KHRONOS+ - To avoid confusion with the Khronos organization.
** Multi-author extensions that have not been ratified by Khronos (those
@@ -143,7 +143,7 @@ browser.
== Extension Command, Type, and Token Naming Conventions
Extensions may: add new commands, types, and tokens, or collectively
-``objects'', to the {apiname} API. These objects are given globally unique
+``objects'', to the Vulkan API. These objects are given globally unique
names by appending the author prefix defined above for the extension name
according to the following templates.
@@ -184,10 +184,10 @@ enum VkSomeValuesGRPHX {
[[extensions-api-registry]]
-== The {apiname} Registry
+== The Vulkan Registry
-The canonical definition of the {apiname} APIs is kept in an XML file known
-as the *{apiname} registry*. The registry is kept in +src/spec/vk.xml+ in
+The canonical definition of the Vulkan APIs is kept in an XML file known
+as the *Vulkan registry*. The registry is kept in +src/spec/vk.xml+ in
the branch of the vulkan project containing the most recently released core
API specification. The registry contains reserved author prefixes, core and
extension interface definitions, definitions of individual commands and
@@ -202,7 +202,7 @@ documentation used in generating the API specification and reference pages.
== Registering an Author Prefix with Khronos
Previous Khronos APIs could only officially be modified by Khronos members.
-In an effort to build a more flexible platform, {apiname} allows non-Khronos
+In an effort to build a more flexible platform, Vulkan allows non-Khronos
developers to extend and modify the API via layers and extensions in the
same manner as Khronos members. However, extensions must: still be
registered with Khronos. A mechanism for non-members to register layers and
@@ -222,7 +222,7 @@ contact email address, respectively. The author prefix will be reserved only
once this merge request is accepted.
Please do not try to reserve author names which clearly belong to another
-existing company or software project which may: wish to develop {apiname}
+existing company or software project which may: wish to develop Vulkan
extensions or layers in the future, as a matter of courtesy and respect.
Khronos may: decline to register author names that are not requested in good
faith.
@@ -231,7 +231,7 @@ faith.
[[extensions-vendor-id]]
== Registering a Vendor ID with Khronos
-{apiname} implementers must report a valid vendor ID for their
+Vulkan implementers must report a valid vendor ID for their
implementation, as reported by
<>. If
there is no valid PCI vendor ID defined for the physical device,
@@ -251,7 +251,7 @@ available ID in the list of ++ tags. The vendor ID will be
reserved only once this merge request has been accepted.
Please do not try to reserve vendor IDs unless you are making a good faith
-effort to develop a {apiname} implementation and require one for that
+effort to develop a Vulkan implementation and require one for that
purpose.
@@ -264,7 +264,7 @@ registration is strongly recommended. Registration means:
* Adding the extension or layer name to the list in +vk.xml+ and appearing
on the Khronos registry website, which will link to associated
documentation hosted on Khronos.
- * For extensions which add to the {apiname} API, including definitions of
+ * For extensions which add to the Vulkan API, including definitions of
those additions to +vk.xml+.
Registration for Khronos members is handled by filing a merge request in the
@@ -298,7 +298,7 @@ extension number assignment prior to extension publication:
* Develop and test the extension using the registered extension number.
* Publish the extension to Khronos using the previously registered
extension number, by creating a branch of the repository with
- appropriate changes relative to the core {apiname} API branch.
+ appropriate changes relative to the core Vulkan API branch.
* Mark the extension as enabled, by proposing a merge to master changing
the +supported+ attribute value of the ++ to
+supported="vulkan"+. This should: be completely automated and under the
@@ -326,15 +326,15 @@ endif::editing-notes[]
== Documenting Extensions
-Extensions are documented as modifications to the {apiname} specification.
+Extensions are documented as modifications to the Vulkan specification.
These modifications will be on Git branches that are named with the
following syntax: +-+
For example, the VK_KHR_surface extension will be documented relative
-to version 1.0 of the {apiname} specification. As such, the branch name will
+to version 1.0 of the Vulkan specification. As such, the branch name will
be: +1.0-VK_KHR_surface+
-If the extension modifies an existing section of the {apiname}
+If the extension modifies an existing section of the Vulkan
specification, those modifications are made in-place. Since the changes are
on a branch, the core-only specification can: be easily produced. A
specification with an extension is created by merging in the extension's
@@ -347,7 +347,7 @@ higher-numbered extension should: take care to deal with any conflicts.
The WSI extensions were used to help pioneer what should: be done for
extensions. This includes the following:
- * All extensions should: add to the appendix of the {apiname}
+ * All extensions should: add to the appendix of the Vulkan
specification. This should: be modeled after what was done for the
+VK_KHR_surface+ extension, which contains some high-level information
about the extension (as well as code examples, and revision history) in
@@ -360,12 +360,12 @@ extensions. This includes the following:
multiple extensions' branches are merged in order to create the ``full''
branch specification.
* If there are any other places where 2 or more extensions will extend the
- {apiname} specification, it is best to put that content in a file, and
+ Vulkan specification, it is best to put that content in a file, and
use an +include+ statement to put that content into the spec. Again,
this +include+ line should: be put on the master branch in order to
avoid merge conflicts.
- * If an extension is more of an addition to the {apiname} specification,
- the extension should: add a chapter to the {apiname} specification.
+ * If an extension is more of an addition to the Vulkan specification,
+ the extension should: add a chapter to the Vulkan specification.
== Assigning Extension Token Values
@@ -443,7 +443,7 @@ all extensions must: define two additional tokens.
extension specification, and is incremented when significant changes
(bugfixes or added functionality) are made. Note that the revision of an
extension defined in +vulkan.h+ and the revision supported by the
- {apiname} implementation (the pname:specVersion field of the
+ Vulkan implementation (the pname:specVersion field of the
slink:VkExtensionProperties structure corresponding to the extension and
returned by one of the <>) may: differ. In such cases, only the functionality and
@@ -472,7 +472,7 @@ be included in the +vulkan.h+ header supplied by Khronos.
.Note
====
Application developers are encouraged to be careful when using +switch+
-statements with {apiname} API enums. This is because extensions can: add new
+statements with Vulkan API enums. This is because extensions can: add new
values to existing enums. The use of a +default:+ statement, within a
+switch+, may: avoid future compilation issues.
====
@@ -481,23 +481,23 @@ values to existing enums. The use of a +default:+ statement, within a
[[extension-function_prototypes]]
== Extension Function Prototypes
-Function pointer declarations and function prototypes for all core {apiname}
+Function pointer declarations and function prototypes for all core Vulkan
API commands are included in the +vulkan.h+ file. These come from the
-official XML specification of the {apiname} API hosted by Khronos.
+official XML specification of the Vulkan API hosted by Khronos.
Function pointer declarations are also included in the +vulkan.h+ file for
all commands defined by registered extensions. Function prototypes for
extensions may: be included in +vulkan.h+. Extension commands that are part
-of the {apiname} ABI must: be flagged in the XML. Function prototypes will
+of the Vulkan ABI must: be flagged in the XML. Function prototypes will
be included in +vulkan.h+ for all extension commands that are part of the
-{apiname} ABI.
+Vulkan ABI.
An extension can: be considered platform specific, in which case its
interfaces in +vulkan.h+ are protected by #ifdefs. This is orthogonal to
-whether an extension command is considered to be part of the {apiname} ABI.
+whether an extension command is considered to be part of the Vulkan ABI.
The initial set of WSI extension commands are considered to be part of the
-{apiname} ABI. Function prototypes for these WSI commands are included in
+Vulkan ABI. Function prototypes for these WSI commands are included in
the +vulkan.h+ provided by Khronos, though the platform-specific portions of
+vulkan.h+ are protected by #ifdefs.
@@ -505,7 +505,7 @@ the +vulkan.h+ provided by Khronos, though the platform-specific portions of
.Note
====
Based on feedback from implementers, Khronos expects that the Android,
-Linux, and Windows {apiname} SDKs will include our +vulkan.h+ and export
+Linux, and Windows Vulkan SDKs will include our +vulkan.h+ and export
the supported WSI functions for those platforms from their loader
libraries. Other implementations can: make different choices for their
headers and loader libraries, but are encouraged to be consistent with
@@ -518,8 +518,8 @@ these implementations.
flink:vkGetInstanceProcAddr and flink:vkGetDeviceProcAddr can: be used in
order to obtain function pointer addresses for core and extension commands
(per the description in <>). Different {apiname} API loaders can: choose to statically
-export functions for some or all of the core {apiname} API commands, and
+Pointers>>). Different Vulkan API loaders can: choose to statically
+export functions for some or all of the core Vulkan API commands, and
can: statically export functions for some or all extension commands. If a
loader statically exports a function, an application can: link against that
function without needing to call one of the ftext:vkGet*ProcAddr commands.
@@ -527,8 +527,8 @@ function without needing to call one of the ftext:vkGet*ProcAddr commands.
[NOTE]
.Note
====
-The Khronos-provided {apiname} API loader for Android, Linux, and Windows
-exports functions for all core {apiname} API and WSI extension commands. The
+The Khronos-provided Vulkan API loader for Android, Linux, and Windows
+exports functions for all core Vulkan API and WSI extension commands. The
WSI functions are considered special, because they are required for many
applications.
====
@@ -556,6 +556,7 @@ defined and locked down, it's safest to refer to the listed contact.
====
+[[extensions-interactions]]
== Extension Interactions
Extensions modifying the behavior of existing commands should: provide
@@ -563,7 +564,14 @@ additional parameters by using the pname:pNext field of an existing
structure, pointing to a new structure defined by the extension, as
described in the <> section. Extension
structures defined by multiple extensions affecting the same structure can
-be chained together in this fashion.
+be chained together in this fashion. Any structure which can: be chained
+in this fashion must: begin with the following two members:
+
+["source","{basebackend@docbook:c++:cpp}",title=""]
+------------------------------------------------------------------------------
+VkStructureType sType;
+const void* pNext;
+------------------------------------------------------------------------------
It is in principle possible for extensions to provide additional parameters
through alternate means, such as passing a handle parameter to a structure
diff --git a/doc/specs/vulkan/appendices/glossary.txt b/doc/specs/vulkan/appendices/glossary.txt
index 9c2123e5..63430b9f 100644
--- a/doc/specs/vulkan/appendices/glossary.txt
+++ b/doc/specs/vulkan/appendices/glossary.txt
@@ -216,7 +216,7 @@ Device-Local Memory::
Dispatchable Handle::
A handle of a pointer handle type which may: be used by layers as part
- of intercepting API commands. The first argument to each {apiname}
+ of intercepting API commands. The first argument to each Vulkan
command is a dispatchable handle type.
Dispatching Commands::
@@ -229,7 +229,7 @@ Drawing Commands::
flink:vkCmdDrawIndexedIndirect.
Duration (Command)::
- The _duration_ of a {apiname} command refers to the interval between
+ The _duration_ of a Vulkan command refers to the interval between
calling the command and its return to the caller.
Dynamic Storage Buffer::
@@ -245,7 +245,7 @@ Explicitly-Enabled Layer::
list in flink:vkCreateInstance or flink:vkCreateDevice.
Event::
- A synchronization primitive that is signalled when execution of previous
+ A synchronization primitive that is signaled when execution of previous
commands complete through a specified set of pipeline stages. Events can
be waited on by the device and polled by the host. Represented by a
sname:VkEvent object.
@@ -314,7 +314,7 @@ Global Workgroup::
A collection of local workgroups dispatched by a single dispatch command.
Handle::
- An opaque integer or pointer value used to refer to a {apiname} object.
+ An opaque integer or pointer value used to refer to a Vulkan object.
Each object type has a unique handle type.
Happen-after::
@@ -378,7 +378,7 @@ Immutable Sampler::
the layout, and cannot be changed.
Implicitly-Enabled Layer::
- A layer enabled by a loader-defined mechanism outside the {apiname} API,
+ A layer enabled by a loader-defined mechanism outside the Vulkan API,
rather than explicitly by the application during instance or device
creation.
@@ -402,7 +402,7 @@ Input Attachment::
view.
Instance::
- The top-level {apiname} object, which represents the application's
+ The top-level Vulkan object, which represents the application's
connection to the implementation. Represented by a sname:VkInstance
object.
@@ -427,7 +427,7 @@ Local Workgroup::
Logical Device::
An object that represents the application's interface to the physical
- device. The logical device is the parent of most {apiname} objects.
+ device. The logical device is the parent of most Vulkan objects.
Represented by a sname:VkDevice object.
Logical Operation::
@@ -802,7 +802,7 @@ A::
= Prefixes
Prefixes are used in the API to denote specific semantic meaning of
-{apiname} names, or as a label to avoid name clashes, and are explained
+Vulkan names, or as a label to avoid name clashes, and are explained
here:
VK/Vk/vk::
diff --git a/doc/specs/vulkan/appendices/invariance.txt b/doc/specs/vulkan/appendices/invariance.txt
index efcb0875..4656c409 100644
--- a/doc/specs/vulkan/appendices/invariance.txt
+++ b/doc/specs/vulkan/appendices/invariance.txt
@@ -4,8 +4,8 @@
[appendix]
= Invariance
-The {apiname} specification is not pixel exact. It therefore does not
-guarantee an exact match between images produced by different {apiname}
+The Vulkan specification is not pixel exact. It therefore does not
+guarantee an exact match between images produced by different Vulkan
implementations. However, the specification does specify exact matches, in
some cases, for images produced by the same implementation. The purpose of
this appendix is to identify and provide justification for those cases that
@@ -14,10 +14,10 @@ require exact matches.
== Repeatability
The obvious and most fundamental case is repeated issuance of a series of
-{apiname} commands. For any given {apiname} and framebuffer state vector,
-and for any {apiname} command, the resulting {apiname} and framebuffer state
+Vulkan commands. For any given Vulkan and framebuffer state vector,
+and for any Vulkan command, the resulting Vulkan and framebuffer state
must: be identical whenever the command is executed on that initial
-{apiname} and framebuffer state. This repeatability requirement doesn't
+Vulkan and framebuffer state. This repeatability requirement doesn't
apply when using shaders containing side effects (image and buffer variable
stores and atomic operations), because these memory operations are not
guaranteed to be processed in a defined order.
@@ -38,7 +38,7 @@ Additional invariance rules are desirable to ensure useful operation.
== Multi-pass Algorithms
Invariance is necessary for a whole set of useful multi-pass algorithms.
-Such algorithms render multiple times, each time with a different {apiname}
+Such algorithms render multiple times, each time with a different Vulkan
mode vector, to eventually produce a result in the framebuffer. Examples of
these algorithms include:
@@ -49,11 +49,11 @@ these algorithms include:
== Invariance Rules
-For a given instantiation of an {apiname} rendering context:
+For a given instantiation of an Vulkan rendering context:
-*Rule 1* _For any given {apiname} and framebuffer state vector, and for any
-given {apiname} command, the resulting {apiname} and framebuffer state must:
-be identical each time the command is executed on that initial {apiname} and
+*Rule 1* _For any given Vulkan and framebuffer state vector, and for any
+given Vulkan command, the resulting Vulkan and framebuffer state must:
+be identical each time the command is executed on that initial Vulkan and
framebuffer state._
*Rule 2* _Changes to the following state values have no side effects (the
@@ -89,7 +89,7 @@ sequence, are pixel identical._
when run multiple times with the same input. The wording ``the same shader''
means a program object that is populated with the same SPIR-V binary, which
is used to create pipelines, possibly multiple times, and which program
-object is then executed using the same {apiname} state vector. Invariance is
+object is then executed using the same Vulkan state vector. Invariance is
relaxed for shaders with side effects, such as performing stores or
atomics._
@@ -98,19 +98,19 @@ assign_ code:FragCoord.z _to_ code:FragDepth _are depth-invariant with
respect to each other, for those fragments where the assignment to_
code:FragDepth _actually is done._
-If a sequence of {apiname} commands specifies primitives to be rendered with
+If a sequence of Vulkan commands specifies primitives to be rendered with
shaders containing side effects (image and buffer variable stores and atomic
operations), invariance rules are relaxed. In particular, rule 1, corollary
2, and rule 4 do not apply in the presence of shader side effects.
-The following weaker versions of rules 1 and 4 apply to {apiname} commands
+The following weaker versions of rules 1 and 4 apply to Vulkan commands
involving shader side effects:
-*Rule 6* _For any given {apiname} and framebuffer state vector, and for any
-given {apiname} command, the contents of any framebuffer state not directly
+*Rule 6* _For any given Vulkan and framebuffer state vector, and for any
+given Vulkan command, the contents of any framebuffer state not directly
or indirectly affected by results of shader image or buffer variable stores
or atomic operations must: be identical each time the command is executed on
-that initial {apiname} and framebuffer state._
+that initial Vulkan and framebuffer state._
*Rule 7* _The same vertex or fragment shader will produce the same result
when run multiple times with the same input as long as:_
@@ -121,8 +121,8 @@ when run multiple times with the same input as long as:_
* _no shader invocation, or other operation performed to process the
sequence of commands, reads memory written to by an image store._
-When any sequence of {apiname} commands triggers shader invocations that
-perform image stores or atomic operations, and subsequent {apiname} commands
+When any sequence of Vulkan commands triggers shader invocations that
+perform image stores or atomic operations, and subsequent Vulkan commands
read the memory written by those shader invocations, these operations must:
be explicitly synchronized.
diff --git a/doc/specs/vulkan/appendices/spirvenv.txt b/doc/specs/vulkan/appendices/spirvenv.txt
index a931148d..01830247 100644
--- a/doc/specs/vulkan/appendices/spirvenv.txt
+++ b/doc/specs/vulkan/appendices/spirvenv.txt
@@ -3,16 +3,16 @@
[appendix]
[[spirvenv]]
-= {apiname} Environment for SPIR-V
+= Vulkan Environment for SPIR-V
-Shaders for {apiname} are defined by the <> as
+Shaders for Vulkan are defined by the <> as
well as the <>.
-This appendix defines additional SPIR-V requirements applying to {apiname}
+This appendix defines additional SPIR-V requirements applying to Vulkan
shaders.
== Required Versions and Formats
-A {apiname} 1.0 implementation must: support the 1.0 version of SPIR-V and
+A Vulkan 1.0 implementation must: support the 1.0 version of SPIR-V and
the 1.0 version of the SPIR-V Extended Instructions for GLSL.
A SPIR-V module passed into flink:vkCreateShaderModule is interpreted as
@@ -47,7 +47,7 @@ to that feature must: also be supported.
.SPIR-V Capabilities which are not required:, and corresponding feature names
[options="header"]
|====
-| SPIR-V OpCapability | {apiname} feature name
+| SPIR-V OpCapability | Vulkan feature name
| code:Geometry | <>
| code:Tessellation | <>
| code:Float64 | <>
@@ -81,7 +81,7 @@ following to flink:vkCreateShaderModule:
- any OpCapability not listed above,
- an unsupported capability, or
- - a capability which corresponds to a {apiname} feature which has not been
+ - a capability which corresponds to a Vulkan feature which has not been
enabled.
@@ -198,18 +198,18 @@ negative the result is undefined.
.Note
====
While the code:OpSRem and code:OpSMod instructions are supported by the
-{apiname} environment, they require non-negative values and thus do not
+Vulkan environment, they require non-negative values and thus do not
enable additional functionality beyond what code:OpUMod provides.
====
[[spirvenv-image-formats]]
-Compatibility Between SPIR-V Image Formats And {apiname} Formats
-----------------------------------------------------------------
+Compatibility Between SPIR-V Image Formats And Vulkan Formats
+-------------------------------------------------------------
[cols="2*", options="header"]
|===
-|SPIR-V Image Format |{apiname} Format
+|SPIR-V Image Format |Vulkan Format
|code:Rgba32f |ename:VK_FORMAT_R32G32B32A32_SFLOAT
|code:Rgba16f |ename:VK_FORMAT_R16G16B16A16_SFLOAT
|code:R32f |ename:VK_FORMAT_R32_SFLOAT
diff --git a/doc/specs/vulkan/buildRelease b/doc/specs/vulkan/buildRelease
index 9d62a8a0..33df0fed 100755
--- a/doc/specs/vulkan/buildRelease
+++ b/doc/specs/vulkan/buildRelease
@@ -33,8 +33,7 @@ git checkout master
echo "**** AUTOGENERATING HEADERS AND SPEC INCLUDE FILES ****"
cd $xml
-make clobber
-make full_install
+make OUTDIR=$outdir clobber full_install
echo "**** CLEANING SPEC ****"
cd $spec
diff --git a/doc/specs/vulkan/chapters/clears.txt b/doc/specs/vulkan/chapters/clears.txt
index b946f5f1..39ff7d81 100644
--- a/doc/specs/vulkan/chapters/clears.txt
+++ b/doc/specs/vulkan/chapters/clears.txt
@@ -221,7 +221,9 @@ include::../protos/vkCmdFillBuffer.txt[]
filling, and must: be a multiple of 4.
* pname:size is the number of bytes to fill, and must: be either a
multiple of 4, or ename:VK_WHOLE_SIZE to fill the range from
- pname:offset to the end of the buffer.
+ pname:offset to the end of the buffer. If ename:VK_WHOLE_SIZE is used
+ and the remaining size of the buffer is not a multiple of 4, then the
+ nearest smaller multiple is used.
* pname:data is the 4-byte word written repeatedly to the buffer to fill
pname:size bytes of data. The data word is written to memory according
to the host endianness.
diff --git a/doc/specs/vulkan/chapters/cmdbuffers.txt b/doc/specs/vulkan/chapters/cmdbuffers.txt
index cb4e7744..7e463bca 100644
--- a/doc/specs/vulkan/chapters/cmdbuffers.txt
+++ b/doc/specs/vulkan/chapters/cmdbuffers.txt
@@ -136,7 +136,7 @@ command buffers allocated from the command pool back to the command pool.
All command buffers that have been allocated from the command pool are put
in the initial state.
-pname:flags is a bitmask controlling the operation. Bits which which can: be
+pname:flags is a bitmask controlling the operation. Bits which can: be
set include:
include::../enums/VkCommandPoolResetFlagBits.txt[]
@@ -336,7 +336,8 @@ fname:vkCmdExecuteCommands) until the final time that primary buffer's
submission to a queue completes. If, after the primary buffer completes, the
secondary command buffer is recorded to execute on a different primary
buffer, the first primary buffer mustnot: be resubmitted until after it is
-reset with flink:vkResetCommandBuffer.
+reset with flink:vkResetCommandBuffer unless the secondary command buffer
+was recorded with ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT.
If ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT is not set on a
secondary command buffer, that command buffer mustnot: be used more than
@@ -400,25 +401,13 @@ include::../protos/vkQueueSubmit.txt[]
which describe the work to submit. All work described by pname:pSubmits
must: be submitted to the queue before the command returns.
* pname:fence is an optional handle to a fence. If pname:fence is not
- code:VK_NULL_HANDLE, the fence is signaled when execution of all
- sname:VkSubmitInfo::pname:pCommandBuffers members of pname:pSubmits is
- completed. If pname:submitCount is zero but pname:fence is not
- code:VK_NULL_HANDLE, the fence will still be submitted to the queue and
- will become signaled when all work previously submitted to the queue has
- completed.
-
-ifdef::editing-notes[]
-[NOTE]
-.editing-note
-====
-(Jon) The description of pname:fence here was added from the ref page
-because it was missing from the starting point of MR #1048, which is just
-about cleaning up the markup of command parameters. It needs to be resolved
-with the description far below of pname:fence, as noted by @jbolz, because
-they're not very similar and because most of the second description belongs
-in validity XML language.
-====
-endif::editing-notes[]
+ code:VK_NULL_HANDLE, the fence is signaled when execution of all command
+ buffers specified in the sname:VkSubmitInfo::pname:pCommandBuffers
+ members of pname:pSubmits is complete, providing certain
+ <>. If
+ pname:submitCount is zero but pname:fence is not code:VK_NULL_HANDLE,
+ the fence will still be submitted to the queue and will become signaled
+ when all work previously submitted to the queue has completed.
include::../validity/protos/vkQueueSubmit.txt[]
@@ -440,11 +429,11 @@ Each call to fname:vkQueueSubmit submits zero or more _batches_ of work to
the queue for execution. pname:submitCount is used to specify the number of
batches to submit. Each batch includes zero or more semaphores to wait upon,
and a corresponding set of stages that will wait for the semaphore to be
-signalled before executing any work, followed by a number of command buffers
+signaled before executing any work, followed by a number of command buffers
that will be executed, and finally, zero or more semaphores that will be
signaled after command buffer execution completes. Each batch is represented
as an instance of the slink:VkSubmitInfo structure stored in an array, the
-address of which is passed in pname:pSubmitInfo.
+address of which is passed in pname:pSubmits.
The sname:VkSubmitInfo structure is defined as:
@@ -473,13 +462,6 @@ include::../structs/VkSubmitInfo.txt[]
include::../validity/structs/VkSubmitInfo.txt[]
-If pname:fence is provided, it must: be in the unsignaled state (see
-<>) and a fence must: only be associated with
-a single submission until that submission completes, and the fence is
-subsequently reset. When all command buffers in pname:pCommandBuffers have
-completed execution, the status of pname:fence is set to signaled, providing
-certain <>.
-
[[commandbuffers-submission-progress]]
== Queue Forward Progress
diff --git a/doc/specs/vulkan/chapters/copies.txt b/doc/specs/vulkan/chapters/copies.txt
index 6fefdd6d..07a7506f 100644
--- a/doc/specs/vulkan/chapters/copies.txt
+++ b/doc/specs/vulkan/chapters/copies.txt
@@ -197,7 +197,7 @@ pname:extent.height is not a multiple of the compressed texel block height
then (pname:extent.height + pname:srcOffset.y) must: equal the image
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 image subresource depth. Similarily if the pname:dstImage is
+must: equal the image subresource depth. Similarly, 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 image subresource width, if pname:extent.height is not a multiple of the
diff --git a/doc/specs/vulkan/chapters/descriptorsets.txt b/doc/specs/vulkan/chapters/descriptorsets.txt
index 65ecdd4a..9fa9970b 100644
--- a/doc/specs/vulkan/chapters/descriptorsets.txt
+++ b/doc/specs/vulkan/chapters/descriptorsets.txt
@@ -79,7 +79,7 @@ layout (set=m, binding=n) uniform sampler2D variableNameArray[L];
== Descriptor Types
The following sections outline the various descriptor types supported by
-{apiname}. Each section defines a descriptor type, and each descriptor type
+Vulkan. Each section defines a descriptor type, and each descriptor type
has a manifestation in the shading language and SPIR-V as well as in
descriptor sets. There is mostly a one-to-one correspondence between
descriptor types and classes of opaque types in the shading language, where
@@ -1478,7 +1478,7 @@ include::../validity/protos/vkCmdBindDescriptorSets.txt[]
As described above in section <>, the pipeline layout defines shader push constants which are
-updated via {apiname} commands rather than via writes to memory or copy
+updated via Vulkan commands rather than via writes to memory or copy
commands.
[NOTE]
diff --git a/doc/specs/vulkan/chapters/devsandqueues.txt b/doc/specs/vulkan/chapters/devsandqueues.txt
index 4d40bc51..c9782367 100644
--- a/doc/specs/vulkan/chapters/devsandqueues.txt
+++ b/doc/specs/vulkan/chapters/devsandqueues.txt
@@ -4,10 +4,10 @@
[[devsandqueues]]
= Devices and Queues
-Once {apiname} is initialized, devices and queues are the primary objects
-used to interact with a {apiname} implementation.
+Once Vulkan is initialized, devices and queues are the primary objects
+used to interact with a Vulkan implementation.
-{apiname} separates the concept of _physical_ and _logical_ devices. A
+Vulkan separates the concept of _physical_ and _logical_ devices. A
physical device usually represents a single device in a system (perhaps made
up of several individual hardware devices working together), of which there
are a finite number. A logical device represents an application's view of
@@ -21,7 +21,7 @@ physical devices installed in the system, call:
include::../protos/vkEnumeratePhysicalDevices.txt[]
- * pname:instance is a handle to a {apiname} instance previously created
+ * pname:instance is a handle to a Vulkan instance previously created
with fname:vkCreateInstance.
* pname:pPhysicalDeviceCount is a pointer to an integer related to the
number of physical devices available or queried, as described below.
@@ -60,7 +60,7 @@ The sname:VkPhysicalDeviceProperties structure is defined as:
include::../structs/VkPhysicalDeviceProperties.txt[]
- * pname:apiVersion is the version of {apiname} supported by the device,
+ * pname:apiVersion is the version of Vulkan supported by the device,
encoded as described in the <> section.
* pname:driverVersion is the vendor-specified version of the driver.
@@ -279,7 +279,7 @@ device exposes a number of _queue families_ each having one or more
_queues_. All queues in a queue family support the same operations.
As described in <>, a {apiname} application will first query for all physical devices
+Devices>>, a Vulkan application will first query for all physical devices
in a system. Each physical device can: then be queried for its capabilities,
including its queue and queue family properties. Once an acceptable physical
device is identified, an application will create a corresponding logical
@@ -330,11 +330,9 @@ include::../structs/VkDeviceCreateInfo.txt[]
requested to be created along with the logical device. Refer to the
<> section below for
further details.
- * pname:enabledLayerCount is the number of device layers to enable.
- * pname:ppEnabledLayerNames is a pointer to an array of
- pname:enabledLayerCount null-terminated UTF-8 strings containing the
- names of layers to enable for the created device. See the
- <> section for further details.
+ * pname:enabledLayerCount is deprecated and ignored.
+ * pname:ppEnabledLayerNames is deprecated and ignored. See
+ <>.
* pname:enabledExtensionCount is the number of device extensions to
enable.
* pname:ppEnabledExtensionNames is a pointer to an array of
@@ -418,7 +416,7 @@ error is largely informational and intended only to inform the user that
their hardware has probably developed a fault or become physically
disconnected, and should: be investigated further. In many cases, physical
device loss may: cause other more serious issues such as the operating
-system crashing; in which case it may: not be reported via the {apiname}
+system crashing; in which case it may: not be reported via the Vulkan
API.
====
@@ -482,7 +480,7 @@ include::../validity/protos/vkDestroyDevice.txt[]
To ensure that no work is active on the device, flink:vkDeviceWaitIdle
can: be used to gate the destruction of the device. Prior to destroying a
-device, an application is responsible for destroying/freeing any {apiname}
+device, an application is responsible for destroying/freeing any Vulkan
objects that were created using that device as the first parameter of the
corresponding ftext:vkCreate* or ftext:vkAllocate* command.
@@ -581,7 +579,7 @@ include::../validity/protos/vkGetDeviceQueue.txt[]
[[devsandqueues-index]]
=== Queue Family Index
-The queue family index is used in multiple places in {apiname} in order to
+The queue family index is used in multiple places in Vulkan in order to
tie operations to a specific family of queues.
When retrieving a handle to the queue via fname:vkGetDeviceQueue, the queue
@@ -647,7 +645,7 @@ binding operations in the queue have completed.
include::../validity/protos/vkQueueWaitIdle.txt[]
-Synchronization between queues is done using {apiname} semaphores as
+Synchronization between queues is done using Vulkan semaphores as
described in the <>
chapter.
@@ -655,7 +653,7 @@ chapter.
[[devsandqueues-sparsebinding]]
=== Sparse Memory Binding
-In {apiname} it is possible to sparsely bind memory to buffers and
+In Vulkan it is possible to sparsely bind memory to buffers and
images as described in the <> chapter. Sparse
memory binding is a queue operation. A queue whose flags include the
ename:VK_QUEUE_SPARSE_BINDING_BIT must: be able to support the
diff --git a/doc/specs/vulkan/chapters/drawing.txt b/doc/specs/vulkan/chapters/drawing.txt
index 0abc6ea2..220b56e1 100644
--- a/doc/specs/vulkan/chapters/drawing.txt
+++ b/doc/specs/vulkan/chapters/drawing.txt
@@ -340,7 +340,7 @@ The order of vertices in such a primitive is significant during
<>.
-=== Programmable Primitive Shading
+== Programmable Primitive Shading
Once primitives are assembled, they proceed to the vertex shading stage of
the pipeline. If the draw includes multiple instances, then the set of
diff --git a/doc/specs/vulkan/chapters/extensions.txt b/doc/specs/vulkan/chapters/extensions.txt
index 9e564ab3..41e526d8 100644
--- a/doc/specs/vulkan/chapters/extensions.txt
+++ b/doc/specs/vulkan/chapters/extensions.txt
@@ -5,34 +5,40 @@
= Extended Functionality
Additional functionality may: be provided by layers or extensions. A layer
-cannot: add or modify {apiname} commands, while an extension may: do so.
+cannot: add or modify Vulkan commands, while an extension may: do so.
-There are two kinds of layers and extensions, instance and device. Instance
-layers and extensions are general purpose and do not depend on a specific
-device. Device layers and extensions operate on specific devices, and
-require a valid sname:VkDevice to be used. Instance extensions usually
-affect the operation of the API as a whole, whereas device layers and
-extensions tend to be hardware-specific. Examples of these might be:
+The set of layers to enable is specified when creating an instance, and those
+layers are able to intercept any Vulkan command dispatched to that instance
+or any of its child objects.
- * Whole API validation is an example of a good instance layer.
+Extensions can operate at either the instance or device scope. Enabled instance
+extensions are able to affect the operation of the instance and any of its
+child objects, while device extensions may: only be available on a subset of
+physical devices, must be individually enabled per-device, and only affect the
+operation of the devices where they are enabled.
+
+Examples of these might be:
+
+ * Whole API validation is an example of a layer.
* Debug capabilities might make a good instance extension.
* A layer that provides hardware-specific performance telemetry and
- analysis could be a device layer.
+ analysis could be a layer that is only active for devices created from
+ compatible physical devices.
* Functions to allow an application to use additional hardware features
beyond the core would be a good candidate for a device extension.
[[extended-functionality-layers]]
== Layers
-When a layer is enabled, it inserts itself into the call chain for {apiname}
+When a layer is enabled, it inserts itself into the call chain for Vulkan
commands the layer is interested in. A common use of layers is to validate
application behavior during development. For example, the implementation
-will not check that {apiname} enums used by the application fall within
+will not check that Vulkan enums used by the application fall within
allowed ranges. Instead, a validation layer would do those checks and flag
issues. This avoids a performance penalty during production use of the
application because those layers would not be enabled in production.
-To query the available instance layers, call:
+To query the available layers, call:
include::../protos/vkEnumerateInstanceLayerProperties.txt[]
@@ -43,38 +49,16 @@ include::../protos/vkEnumerateInstanceLayerProperties.txt[]
include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[]
-To enable a instance layer, the name of the layer should be added to the
-pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating
-a sname:VkInstance.
-
-To query the layers available to a given physical device, call:
-
-include::../protos/vkEnumerateDeviceLayerProperties.txt[]
-
- * pname:physicalDevice is the physical device that will be queried.
- * pname:pPropertyCount is a pointer to an integer related to the number of
- layer properties available or queried, as described below.
- * pname:pProperties is either `NULL` or a pointer to an array of
- slink:VkLayerProperties structures.
-
-include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
-
-To enable a device layer, the name of the layer should be added to the
-pname:ppEnabledLayerNames member of slink:VkDeviceCreateInfo when creating
-a sname:VkDevice.
-
-For both flink:vkEnumerateInstanceLayerProperties and
-flink:vkEnumerateDeviceLayerProperties, if pname:pProperties is `NULL`, then
-the number of layer properties available is returned in pname:pPropertyCount.
-Otherwise, pname:pPropertyCount must: point to a variable set by the user to
-the number of elements in the pname:pProperties array, and on return the
-variable is overwritten with the number of structures actually written to
-pname:pProperties. If pname:pPropertyCount is less than the
-number of layer properties available, at most pname:pPropertyCount
-structures will be written. If pname:pPropertyCount is smaller than the
-number of layers available, ename:VK_INCOMPLETE will be returned instead of
-ename:VK_SUCCESS, to indicate that not all the available layer properties
-were returned.
+If pname:pProperties is `NULL`, then the number of layer properties available
+is returned in pname:pPropertyCount. Otherwise, pname:pPropertyCount must:
+point to a variable set by the user to the number of elements in the
+pname:pProperties array, and on return the variable is overwritten with the
+number of structures actually written to pname:pProperties. If
+pname:pPropertyCount is less than the number of layer properties available, at
+most pname:pPropertyCount structures will be written. If pname:pPropertyCount
+is smaller than the number of layers available, ename:VK_INCOMPLETE will be
+returned instead of ename:VK_SUCCESS, to indicate that not all the available
+layer properties were returned.
The sname:VkLayerProperties structure is defined as:
@@ -82,10 +66,9 @@ include::../structs/VkLayerProperties.txt[]
* pname:layerName is a null-terminated UTF-8 string specifying the name of
the layer. Use this name in the pname:ppEnabledLayerNames array passed
- in the slink:VkInstanceCreateInfo and slink:VkDeviceCreateInfo
- structures passed to flink:vkCreateInstance and flink:vkCreateDevice,
- respectively, to enable this layer for an instance or device.
- * pname:specVersion is the {apiname} version the layer was written to,
+ in the slink:VkInstanceCreateInfo structure to enable this layer for an
+ instance.
+ * pname:specVersion is the Vulkan version the layer was written to,
encoded as described in the <> section.
* pname:implementationVersion is the version of this layer. It is an
@@ -95,20 +78,86 @@ include::../structs/VkLayerProperties.txt[]
include::../validity/structs/VkLayerProperties.txt[]
-Loader implementations may: provide mechanisms outside the {apiname} API for
+To enable a layer, the name of the layer should be added to the
+pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating
+a sname:VkInstance.
+
+Loader implementations may: provide mechanisms outside the Vulkan API for
enabling specific layers. Layers enabled through such a mechanism are
_implicitly enabled_, while layers enabled by including the layer name in
-the pname:ppEnabledLayerNames member of slink:VkDeviceCreateInfo are
+the pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo are
_explicitly enabled_. Except where otherwise specified, implicitly enabled
and explicitly enabled layers differ only in the way they are enabled.
Explicitly enabling a layer that is implicitly enabled has no additional
effect.
+[[extended-functionality-device-layer-deprecation]]
+=== Device Layer Deprecation
+
+Previous versions of this specification distinguished between instance and
+device layers. Instance layers were only able to intercept commands that
+operate on sname:VkInstance and sname:VkPhysicalDevice, except they were not
+able to intercept flink:vkCreateDevice. Device layers were enabled for
+individual devices when they were created, and could only intercept commands
+operating on that device or its child objects.
+
+Device-only layers are now deprecated, and this specification no longer
+distinguishes between instance and device layers. Layers are enabled during
+instance creation, and are able to intercept all commands operating on that
+instance or any of its child objects. At the time of deprecation there were no
+known device-only layers and no compelling reason to create one.
+
+In order to maintain compatibility with implementations released prior to
+device-layer deprecation, applications should: still enumerate and enable
+device layers. The behavior of fname:vkEnumerateDeviceLayerProperties and
+valid usage of the pname:ppEnabledLayerNames member of sname:VkDeviceCreateInfo
+maximizes compatibility with applications written to work with the previous
+requirements.
+
+Device layers can: be enumerated by calling:
+
+include::../protos/vkEnumerateDeviceLayerProperties.txt[]
+
+ * pname:pPropertyCount is a pointer to an integer related to the number of
+ layer properties available or queried.
+ * pname:pProperties is either `NULL` or a pointer to an array of
+ slink:VkLayerProperties structures.
+
+include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
+
+If pname:pProperties is `NULL`, then the number of layer properties available
+is returned in pname:pPropertyCount. Otherwise, pname:pPropertyCount must:
+point to a variable set by the user to the number of elements in the
+pname:pProperties array, and on return the variable is overwritten with the
+number of structures actually written to pname:pProperties. If
+pname:pPropertyCount is less than the number of layer properties available, at
+most pname:pPropertyCount structures will be written. If pname:pPropertyCount
+is smaller than the number of layers available, ename:VK_INCOMPLETE will be
+returned instead of ename:VK_SUCCESS, to indicate that not all the available
+layer properties were returned.
+
+The list of layers enumerated by fname:vkEnumerateDeviceLayerProperties must:
+be exactly the sequence of layers enabled for the instance. The members of
+sname:VkLayerProperties for each enumerated layer must: be the same as the
+properties when the layer was enumerated by
+fname:vkEnumerateInstanceLayerProperties.
+
+The pname:ppEnabledLayerNames and pname:enabledLayerCount members of
+sname:VkDeviceCreateInfo are deprecated and their values must: be ignored by
+implementations. However, for compatibility, only an empty list of layers or a
+list that exactly matches the sequence enabled at instance creation time are
+valid, and validation layers should: issue diagnostics for other cases.
+
+Regardless of the enabled layer list provided in sname:VkDeviceCreateInfo, the
+sequence of layers active for a device will be exactly the sequence of layers
+enabled when the parent instance was created.
+
+
[[extended-functionality-extensions]]
== Extensions
-Extensions may: define new {apiname} commands, structures, and enumerants.
+Extensions may: define new Vulkan commands, structures, and enumerants.
For compilation purposes, the interfaces defined by registered extensions,
including new structures and enumerants as well as function pointer types
for new commands, are defined in the Khronos-supplied +vulkan.h+ together
@@ -116,14 +165,14 @@ with the core API. However, commands defined by extensions may: not be
available for static linking - in which case function pointers to these
commands should: be queried at runtime as described in
<>. Extensions may: be provided by layers
-as well as by a {apiname} implementation.
+as well as by a Vulkan implementation.
To query the available instance extensions, call:
include::../protos/vkEnumerateInstanceExtensionProperties.txt[]
* pname:pLayerName is either `NULL` or a pointer to a null-terminated
- UTF-8 string naming the instance layer to retrieve extensions from.
+ UTF-8 string naming the layer to retrieve extensions from.
* pname:pPropertyCount is a pointer to an integer related to the number of
extension properties available or queried, as described below.
* pname:pProperties is either `NULL` or a pointer to an array of
@@ -131,12 +180,12 @@ include::../protos/vkEnumerateInstanceExtensionProperties.txt[]
include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[]
-When pLayerName parameter is NULL, only extensions provided by the {apiname}
+When pLayerName parameter is NULL, only extensions provided by the Vulkan
implementation or by implicitly enabled layers are returned.
When pname:pLayerName is the name of a layer, the instance extensions
provided by that layer are returned.
-To enable a instance extension, the name of the extension should be added to
+To enable an instance extension, the name of the extension should be added to
the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo when
creating a sname:VkInstance.
@@ -146,7 +195,7 @@ include::../protos/vkEnumerateDeviceExtensionProperties.txt[]
* pname:physicalDevice is the physical device that will be queried.
* pname:pLayerName is either `NULL` or a pointer to a null-terminated
- UTF-8 string naming the device layer to retrieve extensions from.
+ UTF-8 string naming the layer to retrieve extensions from.
* pname:pPropertyCount is a pointer to an integer related to the number of
extension properties available or queried, as described below.
* pname:pProperties is either `NULL` or a pointer to an array of
@@ -154,15 +203,11 @@ include::../protos/vkEnumerateDeviceExtensionProperties.txt[]
include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[]
-When pLayerName parameter is NULL, only extensions provided by the {apiname}
+When pLayerName parameter is NULL, only extensions provided by the Vulkan
implementation or by implicitly enabled layers are returned.
When pname:pLayerName is the name of a layer, the device extensions
provided by that layer are returned.
-To enable a device layer, the name of the layer should be added to the
-pname:ppEnabledExtensionNames member of slink:VkDeviceCreateInfo when
-creating a sname:VkDevice.
-
For both flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties, if pname:pProperties is `NULL`,
then the number of extensions properties available is returned in
diff --git a/doc/specs/vulkan/chapters/features.txt b/doc/specs/vulkan/chapters/features.txt
index 55e0968b..1f259769 100644
--- a/doc/specs/vulkan/chapters/features.txt
+++ b/doc/specs/vulkan/chapters/features.txt
@@ -4,7 +4,7 @@
[[features]]
= Features, Limits, and Formats
-{apiname} is designed to support a wide range of hardware and as such there
+Vulkan is designed to support a wide range of hardware and as such there
are a number of features, limits, and formats which are not supported on all
hardware. Features describe functionality that is not required: and which
must: be explicitly enabled. Limits describe implementation-dependent
@@ -20,7 +20,7 @@ by the implementation.
The features and limits are reported via basic structures (that is
slink:VkPhysicalDeviceFeatures and slink:VkPhysicalDeviceLimits).
It is expected that when new features or limits are added in a future
-{apiname} version, new structure(s) and entry point(s) will be added as
+Vulkan version, new structure(s) and entry point(s) will be added as
necessary to query these. New functionality added by
<> is not expected to
modify the core feature and limit structures.
@@ -30,7 +30,7 @@ modify the core feature and limit structures.
== Features
The Specification defines a set of fine-grained features that are not
-required:, but may: be supported by a {apiname} implementation. Support for
+required:, but may: be supported by a Vulkan implementation. Support for
features is reported and enabled on a per-feature basis. Features are
properties of the physical device.
@@ -565,7 +565,7 @@ include::../validity/structs/VkPhysicalDeviceFeatures.txt[]
[[features-features-requirements]]
=== Feature Requirements
-All {apiname} graphics implementations must: support the following features:
+All Vulkan graphics implementations must: support the following features:
* robustBufferAccess.
@@ -1233,7 +1233,7 @@ include::../validity/structs/VkPhysicalDeviceLimits.txt[]
[[features-limits-minmax]]
=== Limit Requirements
-The following table specifies the required minimum/maximum for all {apiname}
+The following table specifies the required minimum/maximum for all Vulkan
graphics implementations. Where a limit corresponds to a fine-grained
device feature which is optional:, the feature name is listed with two
required limits, one when the feature is supported and one when it is not
@@ -3097,11 +3097,16 @@ ename:VK_FORMAT_FEATURE_BLIT_DST_BIT::
fname:vkCmdBlitImage command.
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT::
- sname:VkImage can: be used with a sampler that has either of
+ If ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT is also set,
+ sname:VkImageView can: be used with a sampler that has either of
pname:magFilter or pname:minFilter set to ename:VK_FILTER_LINEAR,
- or pname:mipmapMode set to ename:VK_SAMPLER_MIPMAP_MODE_LINEAR. This bit
- must: only be exposed for formats that also support the
- ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT.
+ or pname:mipmapMode set to ename:VK_SAMPLER_MIPMAP_MODE_LINEAR.
+ If ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT is also set, sname:VkImage
+ can be used as the pname:srcImage to flink:vkCmdBlitImage
+ with a pname:filter of ename:VK_FILTER_LINEAR. This bit must: only be
+ exposed for formats that also support the
+ ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT or
+ ename:VK_FORMAT_FEATURE_BLIT_SRC_BIT.
+
If the format being queried is a depth/stencil format, this bit only indicates
that the depth aspect (not the stencil aspect) supports linear filtering,
diff --git a/doc/specs/vulkan/chapters/fragops.txt b/doc/specs/vulkan/chapters/fragops.txt
index 2b833451..710be615 100644
--- a/doc/specs/vulkan/chapters/fragops.txt
+++ b/doc/specs/vulkan/chapters/fragops.txt
@@ -432,7 +432,7 @@ include::../enums/VkCompareOp.txt[]
* ename:VK_COMPARE_OP_ALWAYS: the test always passes.
As described earlier, the pname:failOp, pname:passOp, and pname:depthFailOp
-members of pname:VkStencilOpState indicate what happens to the stored
+members of slink:VkStencilOpState indicate what happens to the stored
stencil value if this or certain subsequent tests fail or pass. Each enum is
of type elink:VkStencilOp, which is defined as:
diff --git a/doc/specs/vulkan/chapters/framebuffer.txt b/doc/specs/vulkan/chapters/framebuffer.txt
index fd2713b9..1ad5a5a6 100644
--- a/doc/specs/vulkan/chapters/framebuffer.txt
+++ b/doc/specs/vulkan/chapters/framebuffer.txt
@@ -326,7 +326,7 @@ include::../enums/VkLogicOp.txt[]
<<<
-The logical operations supported by {apiname} are summarized in the
+The logical operations supported by Vulkan are summarized in the
following table in which
* latexmath:[$\lnot$] is bitwise invert,
diff --git a/doc/specs/vulkan/chapters/fundamentals.txt b/doc/specs/vulkan/chapters/fundamentals.txt
index 15dfb32f..98d52896 100644
--- a/doc/specs/vulkan/chapters/fundamentals.txt
+++ b/doc/specs/vulkan/chapters/fundamentals.txt
@@ -4,7 +4,7 @@
[[fundamentals]]
= Fundamentals
-This chapter introduces fundamental concepts including the {apiname}
+This chapter introduces fundamental concepts including the Vulkan
architecture and execution model, API syntax, queues, pipeline
configurations, numeric representation, state and state queries, and the
different types of objects and shaders. It provides a framework for
@@ -55,9 +55,9 @@ external standards such as the Linux Standard Base.
[[fundamentals-execmodel]]
== Execution Model
-This section outlines the execution model of a {apiname} system.
+This section outlines the execution model of a Vulkan system.
-{apiname} exposes one or more _devices_,
+Vulkan exposes one or more _devices_,
each of which exposes one or more _queues_ which may: process work
asynchronously to one another. The set of queues supported by a device is
partitioned into _families_. Each family supports one or more types of
@@ -94,8 +94,8 @@ an implementation include:
On other architectures, there may: only be a single heap that can: be used
for any purpose.
-A {apiname} application controls a set of devices through the submission of
-command buffers which have recorded device commands issued via {apiname}
+A Vulkan application controls a set of devices through the submission of
+command buffers which have recorded device commands issued via Vulkan
library calls. The content of command buffers is specific to the underlying
hardware and is opaque to the application. Once constructed, a command
buffer can: be submitted once or many times to a queue for execution.
@@ -115,7 +115,7 @@ the responsibility of the application.
[[fundamentals-queueoperation]]
=== Queue Operation
-{apiname} queues provide an interface to the execution engines of a device.
+Vulkan queues provide an interface to the execution engines of a device.
Commands are recorded into command buffers ahead of execution time.
These command buffers are then submitted to queues for execution. Command
buffers submitted to a single queue are played back in the order they were
@@ -128,7 +128,7 @@ specified. Therefore, the application must: explicitly synchronize work
between queues when needed.
In order to control relative order of execution of work both within a queue
-and across multiple queues, {apiname} provides several synchronization
+and across multiple queues, Vulkan provides several synchronization
primitives, which include _semaphores_, _events_, _pipeline barriers_, and
_fences_. These are covered in depth in <>. In broad terms, semaphores are used to synchronize work
@@ -142,7 +142,7 @@ to synchronize work between the device and the host.
====
Implementations have significant freedom to overlap execution of work
submitted to a queue, and this is common due to deep pipelining and
-parallelism in {apiname} devices.
+parallelism in Vulkan devices.
====
Work is submitted to queues using queue submission commands that typically
@@ -246,8 +246,8 @@ command buffers to execute. This is covered in more detail in
[[fundamentals-objectmodel-overview]]
== Object Model
-The devices, queues, and other entities in {apiname} are represented by
-{apiname} objects. At the API level, all objects are referred to by handles.
+The devices, queues, and other entities in Vulkan are represented by
+Vulkan objects. At the API level, all objects are referred to by handles.
There are two classes of handles, dispatchable and non-dispatchable.
_Dispatchable_ handle types are a pointer to an opaque type. This pointer
may: be used by layers as part of intercepting API commands, and thus each
@@ -280,19 +280,19 @@ ftext:vkDestroy* and ftext:vkFree* commands, respectively.
Objects that are allocated (rather than created) take resources from an
existing pool object or memory heap, and when freed return resources to that
pool or heap. While object creation and destruction are generally expected
-to be low-frequency occurences during runtime, allocating and freeing
+to be low-frequency occurrences during runtime, allocating and freeing
objects can: occur at high frequency. Pool objects help accommodate improved
performance of the allocations and frees.
-It is an application's responsibility to track the lifetime of {apiname}
+It is an application's responsibility to track the lifetime of Vulkan
objects, and not to destroy them while they are still in use.
-Application-owned memory is immediately consumed by any {apiname} command it
+Application-owned memory is immediately consumed by any Vulkan command it
is passed into. The application can: alter or free this memory as soon as
the commands that consume it have returned.
The following object types are consumed when they are passed into a
-{apiname} command and not further accessed by the objects they are used to
+Vulkan command and not further accessed by the objects they are used to
create. They can: be destroyed at any time they are not in use by an API
command:
@@ -306,11 +306,11 @@ sets mustnot: be updated with flink:vkUpdateDescriptorSets after the
descriptor set layout has been destroyed. Otherwise, descriptor set layouts
can: be destroyed any time they are not in use by an API command.
-The application mustnot: destroy any other type of {apiname} object until
+The application mustnot: destroy any other type of Vulkan object until
all uses of that object by the device (such as via command buffer execution)
have completed.
-The following {apiname} objects can: be destroyed when no command buffers
+The following Vulkan objects can: be destroyed when no command buffers
using the object are executing:
* sname:VkEvent
@@ -328,7 +328,7 @@ using the object are executing:
* sname:VkDeviceMemory
* sname:VkDescriptorSet
-The following {apiname} objects can: be destroyed when work on the queue
+The following Vulkan objects can: be destroyed when work on the queue
that uses the object has been completed:
* sname:VkFence
@@ -354,7 +354,7 @@ sname:VkDescriptorPool objects are parents of sname:VkDescriptorSet objects.
sname:VkDevice objects are parents of many object types (all that take a
sname:VkDevice as a parameter to their creation).
-The following {apiname} objects have specific restrictions for when they
+The following Vulkan objects have specific restrictions for when they
can: be destroyed:
* sname:VkQueue objects cannot: be explicitly destroyed. Instead, they are
@@ -399,32 +399,32 @@ can: be destroyed:
[[fundamentals-commandsyntax]]
== Command Syntax and Duration
-The Specification describes {apiname} commands as functions or procedures
+The Specification describes Vulkan commands as functions or procedures
using C99 syntax. Language bindings for other languages such as C++ and
Javascript may: allow for stricter parameter passing, or object-oriented
interfaces.
-With few exceptions, {apiname} uses the standard C types for parameters (int
+With few exceptions, Vulkan uses the standard C types for parameters (int
types from stdint.h, etc). Exceptions to this are using basetype:VkResult
for return values, using basetype:VkBool32 for boolean values,
basetype:VkDeviceSize for sizes and offsets pertaining to device address
space, and basetype:VkFlags for passing bits or sets of bits of predefined
values.
-Commands that create {apiname} objects are of the form ftext:vkCreate* and
+Commands that create Vulkan objects are of the form ftext:vkCreate* and
take stext:Vk*CreateInfo structures with the parameters needed to create the
-object. These {apiname} objects are destroyed with commands of the form
+object. These Vulkan objects are destroyed with commands of the form
ftext:vkDestroy*.
-The last in-parameter to each command that creates or destroys a {apiname}
+The last in-parameter to each command that creates or destroys a Vulkan
object is pname:pAllocator. The pname:pAllocator parameter can: be set to a
non-`NULL` value such that allocations for the given object are delegated to
an application provided callback; refer to the <> chapter for further details.
-Commands that allocate {apiname} objects owned by pool objects are of the
+Commands that allocate Vulkan objects owned by pool objects are of the
form ftext:vkAllocate*, and take stext:Vk*AllocateInfo structures. These
-{apiname} objects are freed with commands of the form ftext:vkFree*.
+Vulkan objects are freed with commands of the form ftext:vkFree*.
These objects do not take allocators; if host memory is needed, they will
use the allocator that was specified when their parent pool was created.
@@ -438,21 +438,21 @@ 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 _duration_ of a Vulkan command refers to the interval between calling
the command and its return to the caller.
[[fundamentals-threadingbehavior]]
== Threading Behavior
-{apiname} is intended to provide scalable performance when used on multiple
+Vulkan is intended to provide scalable performance when used on multiple
host threads. All commands support being called concurrently from multiple
threads, but certain parameters, or components of parameters are defined to
be _externally synchronized_. This means that the caller must: guarantee
that no more than one thread is using such a parameter at a given time.
-More precisely, {apiname} commands use simple stores to update software
-structures representing {apiname} objects. A parameter declared as
+More precisely, Vulkan commands use simple stores to update software
+structures representing Vulkan objects. A parameter declared as
externally synchronized may: have its software
structures updated at any time during the host execution of the command. If
two commands operate on the same object and at least one of the commands
@@ -468,7 +468,7 @@ Memory barriers are particularly relevant on the ARM CPU architecture
which is more weakly ordered than many developers are accustomed to from
x86/x64 programming. Fortunately, most higher-level synchronization
primitives (like the pthread library) perform memory barriers as a part of
-mutual exclusion, so mutexing {apiname} objects via these primitives will
+mutual exclusion, so mutexing Vulkan objects via these primitives will
have the desired effect.
====
@@ -513,11 +513,11 @@ include::../hostsynctable/implicit.txt[]
[[fundamentals-errors]]
== Errors
-{apiname} is a layered API. The lowest layer is the core {apiname} layer, as
+Vulkan is a layered API. The lowest layer is the core Vulkan layer, as
defined by this Specification. The application can: use additional layers
above the core for debugging, validation, and other purposes.
-One of the core principles of {apiname} is that building and submitting
+One of the core principles of Vulkan is that building and submitting
command buffers should: be highly efficient. Thus error checking and
validation of state in the core layer is minimal, although more rigorous
validation can: be enabled through the use of layers.
@@ -602,18 +602,21 @@ ename:VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO.
The values ename:VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO and
ename:VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO are reserved for internal
-use by the loader, and don't have corresponding {apiname} structures in this
+use by the loader, and don't have corresponding Vulkan structures in this
specification.
Any parameter that is a structure containing a basetype:void* ptext:pNext
-member must: have a value of ptext:pNext that is either `NULL`, or points to a
-valid structure defined by an extension. If that extension is supported by
-the implementation, then it must: be enabled.
-Any component of the implementation (the loader, any enabled layers, and
-drivers) must: ignore extension structures with pname:sType values defined
-by extensions not supported by that component.
+member must: have a value of ptext:pNext that is either `NULL`, or points to
+a valid structure defined by an extension, containing ptext:sType and
+ptext:pNext members as described in the <> section. If that extension is supported by the
+implementation, then it must: be enabled. Any component of the
+implementation (the loader, any enabled layers, and drivers) must: skip
+over, without processing (other than reading the pname:sType and pname:pNext
+members) any chained structures with pname:sType values not defined by
+extensions supported by that component.
-Extension structures are not described in the base {apiname} specification,
+Extension structures are not described in the base Vulkan specification,
but either in layered specifications incorporating those extensions,
or in separate vendor-provided documents.
@@ -628,8 +631,8 @@ sections.
[[fundamentals-returncodes]]
=== Return Codes
-While the core {apiname} API is not designed to capture incorrect usage,
-some circumstances still require return codes. Commands in {apiname} return
+While the core Vulkan API is not designed to capture incorrect usage,
+some circumstances still require return codes. Commands in Vulkan return
their status via return codes that are in one of two categories:
* Successful completion codes are returned when a command needs to
@@ -639,7 +642,7 @@ their status via return codes that are in one of two categories:
failure that could only be detected at run time. All run time error
codes are negative values.
-All return codes in {apiname} are reported via basetype:VkResult return
+All return codes in Vulkan are reported via basetype:VkResult return
values. The possible codes are:
include::../enums/VkResult.txt[]
@@ -681,7 +684,7 @@ include::VK_KHR_swapchain/VkResultSuccessDescriptions_swapchain.txt[]
* ename:VK_ERROR_FEATURE_NOT_PRESENT
A requested feature is not supported.
* ename:VK_ERROR_INCOMPATIBLE_DRIVER
- The requested version of {apiname} is not supported by the driver or
+ The requested version of Vulkan is not supported by the driver or
is otherwise incompatible for implementation-specific reasons.
* ename:VK_ERROR_TOO_MANY_OBJECTS
Too many objects of the type have already been created.
@@ -692,9 +695,9 @@ include::VK_KHR_swapchain/VkResultErrorDescriptions_swapchain.txt[]
include::VK_KHR_display_swapchain/VkResultErrorDescriptions_display_swapchain.txt[]
If a command returns a run time error, it will leave any result pointers
-unmodified.
+unmodified, unless other behavior is explicitly defined in the specification.
-Out of memory errors do not damage any currently existing {apiname} objects.
+Out of memory errors do not damage any currently existing Vulkan objects.
Objects that have already been successfully created can: still be used by
the application.
@@ -711,7 +714,7 @@ Implementations normally perform computations in floating-point, and must:
meet the range and precision requirements defined under
``Floating-Point Computation'' below.
-These requirements only apply to computations performed in {apiname}
+These requirements only apply to computations performed in Vulkan
operations outside of shader execution, such as texture image
specification and sampling, and per-fragment operations. Range and
precision requirements during shader execution differ and are specified
@@ -720,7 +723,7 @@ Instructions>> section.
In some cases, the representation and/or precision of operations is
implicitly limited by the specified format of vertex or texel
-data consumed by {apiname}. Specific floating-point formats are
+data consumed by Vulkan. Specific floating-point formats are
described later in this section.
@@ -769,12 +772,12 @@ arithmetic operations such as latexmath:[$0 / 0$]. Implementations may:
support latexmath:[$Inf$]s and latexmath:[$NaN$]s in their floating-point
computations.
-Any representable floating-point value is legal as input to a {apiname}
+Any representable floating-point value is legal as input to a Vulkan
command that requires floating-point data. The result of providing a value
that is not a floating-point number to such a command is unspecified, but
-mustnot: lead to {apiname} interruption or termination. In <>
+mustnot: lead to Vulkan interruption or termination. In <>
arithmetic, for example, providing a negative zero or a denormalized number
-to an {apiname} command must: yield deterministic results, while providing a
+to an Vulkan command must: yield deterministic results, while providing a
latexmath:[$NaN$] or latexmath:[$Inf$] yields unspecified results.
@@ -786,11 +789,11 @@ latexmath:[$NaN$] or latexmath:[$Inf$] yields unspecified results.
section of the Khronos Data Format Specification.
Any representable 16-bit floating-point value is legal as input to a
-{apiname} command that accepts 16-bit floating-point data. The result of
+Vulkan command that accepts 16-bit floating-point data. The result of
providing a value that is not a floating-point number (such as
latexmath:[$Inf$] or latexmath:[$NaN$]) to such a command is
-unspecified, but mustnot: lead to {apiname} interruption or termination.
-Providing a denormalized number or negative zero to {apiname} must: yield
+unspecified, but mustnot: lead to Vulkan interruption or termination.
+Providing a denormalized number or negative zero to Vulkan must: yield
deterministic results.
@@ -814,11 +817,11 @@ converted to positive infinity; and both positive and negative
latexmath:[$NaN$] are converted to positive latexmath:[$NaN$].
Any representable unsigned 11-bit floating-point value is legal as input
-to a {apiname} command that accepts 11-bit floating-point data. The
+to a Vulkan command that accepts 11-bit floating-point data. The
result of providing a value that is not a floating-point number (such as
latexmath:[$Inf$] or latexmath:[$NaN$]) to such a command is
-unspecified, but mustnot: lead to {apiname} interruption or termination.
-Providing a denormalized number to {apiname} must: yield deterministic
+unspecified, but mustnot: lead to Vulkan interruption or termination.
+Providing a denormalized number to Vulkan must: yield deterministic
results.
@@ -842,11 +845,11 @@ converted to positive infinity; and both positive and negative
latexmath:[$NaN$] are converted to positive latexmath:[$NaN$].
Any representable unsigned 10-bit floating-point value is legal as input to
-a {apiname} command that accepts 10-bit floating-point data. The result of
+a Vulkan command that accepts 10-bit floating-point data. The result of
providing a value that is not a floating-point number (such as
latexmath:[$Inf$] or latexmath:[$NaN$]) to such a command is unspecified,
-but mustnot: lead to {apiname} interruption or termination. Providing a
-denormalized number to {apiname} must: yield deterministic results.
+but mustnot: lead to Vulkan interruption or termination. Providing a
+denormalized number to Vulkan must: yield deterministic results.
[[fundamentals-general]]
@@ -854,7 +857,7 @@ denormalized number to {apiname} must: yield deterministic results.
Some calculations require division. In such cases (including implied
divisions performed by vector normalization), division by zero produces an
-unspecified result but mustnot: lead to {apiname} interruption or
+unspecified result but mustnot: lead to Vulkan interruption or
termination.
@@ -911,7 +914,7 @@ 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 {apiname} commands, such as vertex attribute values, as well as for
+in Vulkan commands, such as vertex attribute values, as well as for
specifying texture or framebuffer values using signed normalized
fixed-point.
@@ -967,7 +970,7 @@ or framebuffer values using floating-point.
[[fundamentals-versionnum]]
== API Version Numbers and Semantics
-The {apiname} version number is used in several places in the API. In each
+The Vulkan version number is used in several places in the API. In each
such use, the API _major version number_, _minor version number_, and _patch
version number_ are packed into a 32-bit integer as follows:
@@ -975,7 +978,7 @@ version number_ are packed into a 32-bit integer as follows:
* The minor version number is a 10-bit integer packed into bits 21-12.
* The patch version number is a 12-bit integer packed into bits 11-0.
-Differences in any of the {apiname} version numbers indicates a change to
+Differences in any of the Vulkan version numbers indicates a change to
the API in some way, with each part of the version number indicating a
different scope of changes.
@@ -1005,7 +1008,7 @@ significant modification to an application in order for it to function.
[[fundamentals-common-objects]]
== Common Object Types
-Some types of {apiname} objects are used in many different structures and
+Some types of Vulkan objects are used in many different structures and
command parameters, and are described here. These types include _offsets_,
_extents_, and _rectangles_.
diff --git a/doc/specs/vulkan/chapters/fxvertex.txt b/doc/specs/vulkan/chapters/fxvertex.txt
index 651acab2..9fd3d8fb 100644
--- a/doc/specs/vulkan/chapters/fxvertex.txt
+++ b/doc/specs/vulkan/chapters/fxvertex.txt
@@ -6,7 +6,7 @@
Some implementations have specialized fixed-function hardware for fetching
and format-converting vertex input data from buffers, rather than performing
-the fetch as part of the vertex shader. {apiname} includes a vertex
+the fetch as part of the vertex shader. Vulkan includes a vertex
attribute fetch stage in the graphics pipeline in order to take advantage of
this.
diff --git a/doc/specs/vulkan/chapters/initialization.txt b/doc/specs/vulkan/chapters/initialization.txt
index 100a64d1..c9f5d396 100644
--- a/doc/specs/vulkan/chapters/initialization.txt
+++ b/doc/specs/vulkan/chapters/initialization.txt
@@ -4,14 +4,14 @@
[[initialization]]
= Initialization
-Before using {apiname}, an application must: initialize it by loading the
-{apiname} commands, and creating a sname:VkInstance object.
+Before using Vulkan, an application must: initialize it by loading the
+Vulkan commands, and creating a sname:VkInstance object.
[[initialization-functionpointers]]
== Command Function Pointers
-{apiname} commands are not necessarily exposed statically on a platform.
-Function pointers for all {apiname} commands can: be obtained with the
+Vulkan commands are not necessarily exposed statically on a platform.
+Function pointers for all Vulkan commands can: be obtained with the
command:
include::../protos/vkGetInstanceProcAddr.txt[]
@@ -27,8 +27,8 @@ specific manner. Typically, the loader library will export this command as a
function symbol, so applications can: link against the loader library, or
load it dynamically and look up the symbol using platform-specific APIs.
Loaders are encouraged to export function symbols for all other core
-{apiname} commands as well; if this is done, then applications that use only
-the core {apiname} commands have no need to use fname:vkGetInstanceProcAddr.
+Vulkan commands as well; if this is done, then applications that use only
+the core Vulkan commands have no need to use fname:vkGetInstanceProcAddr.
Function pointers to commands that don't operate on a specific instance can:
be obtained by using this command with pname:instance equal to `NULL`. The
@@ -43,7 +43,7 @@ commands that operate on pname:instance or a child of pname:instance can: be
obtained. The returned function pointer must: only be called with a
dispatchable object (the first parameter) that is a child of pname:instance.
-If pname:pName is not the name of a core {apiname} command, or is an
+If pname:pName is not the name of a core Vulkan command, or is an
extension command for any extension not supported by any available layer or
implementation, then fname:vkGetInstanceProcAddr will return `NULL`.
@@ -66,7 +66,7 @@ it.
====
endif::editing-notes[]
-In order to support systems with multiple {apiname} implementations
+In order to support systems with multiple Vulkan implementations
comprising heterogeneous collections of hardware and software, the function
pointers returned by fname:vkGetInstanceProcAddr may: point to dispatch
code, which calls a different real implementation for different
@@ -79,13 +79,13 @@ command:
include::../protos/vkGetDeviceProcAddr.txt[]
* pname:device is the logical device that provides the function pointer.
- * pname:pName is the name of any {apiname} command whose first parameter
+ * pname:pName is the name of any Vulkan command whose first parameter
is one of
** sname:VkDevice
** sname:VkQueue
** sname:VkCommandBuffer
-If pname:pName is not the name of one of these {apiname} commands, and is
+If pname:pName is not the name of one of these Vulkan commands, and is
not the name of an extension command belonging to an extension enabled for
pname:device, then fname:vkGetDeviceProcAddr will return `NULL`.
@@ -94,9 +94,9 @@ include::../validity/protos/vkGetDeviceProcAddr.txt[]
[[initialization-instances]]
== Instances
-There is no global state in {apiname} and all per-application state is
+There is no global state in Vulkan and all per-application state is
stored in a sname:VkInstance object. Creating a sname:VkInstance object
-initializes the {apiname} library and allows the application to pass
+initializes the Vulkan library and allows the application to pass
information about itself to the implementation.
To create an instance object, call:
@@ -160,7 +160,7 @@ include::../structs/VkApplicationInfo.txt[]
* pname:engineVersion is an unsigned integer variable containing the
developer-supplied version number of the engine used to create the
application.
- * pname:apiVersion is the version of the {apiname} API against which the
+ * pname:apiVersion is the version of the Vulkan API against which the
application expects to run, encoded as described in the
<> section.
If pname:apiVersion is 0 the implementation must: ignore it, otherwise
diff --git a/doc/specs/vulkan/chapters/interfaces.txt b/doc/specs/vulkan/chapters/interfaces.txt
index 1e09f03b..02fe23b0 100644
--- a/doc/specs/vulkan/chapters/interfaces.txt
+++ b/doc/specs/vulkan/chapters/interfaces.txt
@@ -643,6 +643,11 @@ out according to the following rules.
+
* Any code:ArrayStride or code:MatrixStride decoration must: be an integer
multiple of the base alignment of the array or matrix from above.
++
+ * The code:Offset Decoration of a member immediately following a structure or
+ an array must: be greater than or equal to the next multiple of the base
+ alignment of that structure or array.
+
[NOTE]
.Note
@@ -742,7 +747,7 @@ The z component of code:FragCoord is the interpolated depth value of the
primitive, and the w component is the interpolated
latexmath:[$\frac{1}{w}$].
+
-The code:FragCoord decoration is only supported in fragment shaders. The
+The code:FragCoord decoration must: be used only within fragment shaders. The
code:Centroid interpolation decoration is ignored on code:FragCoord.
+
code:FragCoord must: be declared as a four-component vector of 32-bit
@@ -760,7 +765,7 @@ is an execution path through the shader that does not set code:FragDepth,
then the fragment's depth value is undefined for executions of the shader
that take that path.
+
-The code:FragDepth decoration is only supported in fragment shaders.
+The code:FragDepth decoration must: be used only within fragment shaders.
+
code:FragDepth must: be declared as a scalar 32-bit floating-point value.
@@ -797,7 +802,8 @@ workgroup. The value in this variable is equal to the index of the local
workgroup multiplied by the size of the local workgroup plus
code:LocalInvocationID.
+
-The code:GlobalInvocationID decoration is only supported in compute shaders.
+The code:GlobalInvocationID decoration must: be used only within compute
+shaders.
+
code:GlobalInvocationID must: be declared as a three-component vector of
32-bit integers.
@@ -810,7 +816,8 @@ the shader that is produced to satisfy internal requirements such as the
generation of derivatives.
+
--
-The code:HelperInvocation decoration is only supported in fragment shaders.
+The code:HelperInvocation decoration must: be used only within fragment
+shaders.
code:HelperInvocation must: be declared as a scalar 32-bit integer.
@@ -877,26 +884,34 @@ vertices of a given primitive. When used in a fragment shader, an input
variable decorated with code:Layer contains the layer index of the primitive
that the fragment invocation belongs to.
+
-The code:Layer decoration is only supported in geometry and fragment
+The code:Layer decoration must: be used only within geometry and fragment
shaders.
+
code:Layer must: be declared as a scalar 32-bit integer.
code:LocalInvocationID::
-This variable contains the location of the current compute shader invocation
-within the local workgroup. The range of possible values for each component
-of LocalInvocationID range from zero through the size of the workgroup in that
-dimension minus one. If the size of the workgroup in a particular dimension is
-one, then LocalInvocationID in that dimension will be zero. That is, if the
-workgroup is effectively two-dimensional, then pname:LocalInvocationID.z will
-be zero, and if the workgroup is one-dimensional, then both
-pname:LocalInvocationID.y and pname:LocalInvocationID.z will be zero.
+The code:LocalInvocationID decoration can: be applied to a code:uvec3 input
+variable in a compute shader, in which case it will contain the location of the
+current compute shader invocation within the local workgroup. The possible
+values for each component of code:LocalInvocationID range from zero through to
+the size of the workgroup in that dimension minus one.
+
-The code:LocalInvocationID decoration is only supported in compute shaders.
+The code:LocalInvocationID decoration must: be used only within compute
+shaders.
+
-code:LocalInvocationID must: be declared as a three-component vector of
-32-bit integers.
+code:LocalInvocationID must: be declared as a three-component vector of 32-bit
+integers.
+
+[NOTE]
+.Note
+====
+If the size of the workgroup in a particular dimension is one, then the
+code:LocalInvocationID in that dimension will be zero. If the workgroup is
+effectively two-dimensional, then code:LocalInvocationID.z will be zero.
+If the workgroup is effectively one-dimensional, then both
+code:LocalInvocationID.y and code:LocalInvocationID.z will be zero.
+====
code:NumWorkGroups::
@@ -907,7 +922,7 @@ to. It reflects the values passed to a call to flink:vkCmdDispatch or
through the structure consumed by the execution of
flink:vkCmdDispatchIndirect.
+
-The code:NumWorkGroups decoration is only supported in compute shaders.
+The code:NumWorkGroups decoration must: be used only within compute shaders.
+
code:NumWorkGroups must: be declared as a three-component vector of 32-bit
integers.
@@ -923,7 +938,7 @@ If a specialization constant or a constant is decorated with the
code:WorkgroupSize decoration, this must: take precedence over any execution
mode set for code:LocalSize.
+
-The code:WorkgroupSize decoration is only supported in compute shaders.
+The code:WorkgroupSize decoration must: be used only within compute shaders.
+
code:WorkgroupSize must: be declared as a three-component vector of 32-bit
integers.
@@ -936,8 +951,8 @@ vertices in the input patch being processed by the shader. A single
tessellation control or evaluation shader can: read patches of differing
sizes, so the code:PatchVertices variable may: differ between patches.
+
-The code:PatchVertices decoration is only supported in tessellation control
-and evaluation shaders.
+The code:PatchVertices decoration must: be used only within tessellation
+control and evaluation shaders.
+
code:PatchVertices must: be declared as scalar 32-bit integer.
@@ -951,7 +966,7 @@ Point Rasterization>>. If the primitive the fragment shader invocation
belongs to is not a point, then code:PointCoord is undefined.
+
--
-The code:PointCoord decoration is only supported in fragment shaders.
+The code:PointCoord decoration must: be used only within fragment shaders.
code:PointCoord must: be declared as two-component vector of 32-bit
floating-point values.
@@ -1076,7 +1091,7 @@ shader entry point's interface does not include an output variable decorated
with code:SampleMask, the sample mask has no effect on the processing of a
fragment.
+
-The code:SampleMask decoration is only supported in fragment shaders.
+The code:SampleMask decoration must: be used only within fragment shaders.
+
code:SampleMask must: be declared as an array of 32-bit integers.
@@ -1089,7 +1104,7 @@ fragment shader entry point's interface includes an input variable decorated
with code:SamplePosition, per-sample shading is enabled for draws that use
that fragment shader.
+
-The code:SamplePosition decoration is only supported in fragment shaders.
+The code:SamplePosition decoration must: be used only within fragment shaders.
+
code:SamplePosition must: be declared as a two-component vector of
floating-point values.
@@ -1103,7 +1118,7 @@ and w are in the range latexmath:[$[0,1\]$] and vary linearly across the
primitive being subdivided. For the tessellation modes of code:Quads or
code:IsoLines, the third component is always zero.
+
-The code:TessellationCoord decoration is only available to tessellation
+The code:TessellationCoord decoration must: be used only within tessellation
evaluation shaders.
+
code:TessellationCoord must: be declared as three-component vector of 32-bit
@@ -1119,7 +1134,7 @@ tessellation evaluation shaders. When applied to an input variable in a
tessellation evaluation shader, the shader can: read the value written by
the tessellation control shader.
+
-The code:TessellationLevelOuter decoration is not available outside
+The code:TessellationLevelOuter decoration must: be used only within
tessellation control and evaluation shaders.
+
code:TessellationLevelOuter must: be declared as an array of size two,
@@ -1135,7 +1150,7 @@ tessellation evaluation shaders. When applied to an input variable in a
tessellation evaluation shader, the shader can: read the value written by
the tessellation control shader.
+
-The code:TessellationLevelInner decoration is not available outside
+The code:TessellationLevelInner decoration must: be used only within
tessellation control and evaluation shaders.
+
code:TessellationLevelInner must: be declared as an array of size four,
@@ -1156,8 +1171,7 @@ consumed by flink:vkCmdDrawIndexedIndirect.
+
code:VertexIndex starts at the same starting value for each instance.
+
-The code:VertexIndex decoration mustnot: be used in any shader stage other
-than vertex.
+The code:VertexIndex decoration must: be used only within vertex shaders.
+
code:VertexIndex must: be declared as a 32-bit integer.
@@ -1176,8 +1190,8 @@ in a fragment shader, an input variable decorated with code:ViewportIndex
contains the viewport index of the primitive that the fragment invocation
belongs to.
+
-The code:ViewportIndex decoration is only supported in geometry and fragment
-shaders.
+The code:ViewportIndex decoration must: be used only within geometry and
+fragment shaders.
+
code:ViewportIndex must: be declared as a 32-bit integer.
@@ -1190,7 +1204,7 @@ Each component ranges from zero to the values of the parameters passed into
flink:vkCmdDispatch or read from the sname:VkDispatchIndirectCommand
structure read through a call to flink:vkCmdDispatchIndirect.
+
-The code:WorkGroupID decoration is only supported in compute shaders.
+The code:WorkGroupID decoration must: be used only within compute shaders.
+
code:WorkGroupID must: be declared as a three-component vector of 32-bit
integers.
diff --git a/doc/specs/vulkan/chapters/introduction.txt b/doc/specs/vulkan/chapters/introduction.txt
index 3eb1031e..7fcac7cc 100644
--- a/doc/specs/vulkan/chapters/introduction.txt
+++ b/doc/specs/vulkan/chapters/introduction.txt
@@ -7,23 +7,23 @@
This chapter is Informative except for the sections on Terminology and
Normative References.
-This document, referred to as the ``{apiname} Specification'' or just the
-``Specification'' hereafter, describes the {apiname} graphics system: what
+This document, referred to as the ``Vulkan Specification'' or just the
+``Specification'' hereafter, describes the Vulkan graphics system: what
it is, how it acts, and what is required to implement it. We assume that the
reader has at least a rudimentary understanding of computer graphics. This
means familiarity with the essentials of computer graphics algorithms and
terminology as well as with modern GPUs (Graphic Processing Units).
The canonical version of the Specification is available in the official
-{apiname} Registry, located at URL
+Vulkan Registry, located at URL
http://www.khronos.org/registry/vulkan/
[[introduction-whatis]]
-== What is the {apiname} Graphics System?
+== What is the Vulkan Graphics System?
-{apiname} is an API (Application Programming Interface) for graphics and
+Vulkan is an API (Application Programming Interface) for graphics and
compute hardware. The API consists of many commands that
allow a programmer to specify shader programs, compute kernels, objects, and
operations involved in producing high-quality graphical images, specifically
@@ -31,18 +31,18 @@ color images of three-dimensional objects.
[[introduction-programmer]]
-=== The Programmer's View of {apiname}
+=== The Programmer's View of Vulkan
-To the programmer, {apiname} is a set of commands that allow the
+To the programmer, Vulkan is a set of commands that allow the
specification of _shader programs_ or _shaders_, _kernels_, data used by
-kernels or shaders, and state controlling aspects of {apiname} outside the
+kernels or shaders, and state controlling aspects of Vulkan outside the
scope of shaders. Typically, the data represents geometry in two or three
dimensions and texture images, while the shaders and kernels control the
processing of the data, rasterization of the geometry, and the lighting and
shading of _fragments_ generated by rasterization, resulting in the
rendering of geometry into the framebuffer.
-A typical {apiname} program begins with platform-specific calls to open a
+A typical Vulkan program begins with platform-specific calls to open a
window or otherwise prepare a display device onto which the program will
draw. Then, calls are made to open _queues_ to which _command buffers_ are
submitted. The command buffers contain lists of commands which will be
@@ -56,24 +56,24 @@ transfer the resulting image to a display device or window.
[[introduction-implementor]]
-=== The Implementor's View of {apiname}
+=== The Implementor's View of Vulkan
-To the implementor, {apiname} is a set of commands that allow the
+To the implementor, Vulkan is a set of commands that allow the
construction and submission of command buffers to a device. Modern devices
-accelerate virtually all {apiname} operations, storing data and framebuffer
+accelerate virtually all Vulkan operations, storing data and framebuffer
images in high-speed memory and executing shaders in dedicated GPU
processing resources.
The implementor's task is to provide a software library on the host which
-implements the {apiname} API, while mapping the work for each {apiname}
+implements the Vulkan API, while mapping the work for each Vulkan
command to the graphics hardware as appropriate for the capabilities of the
device.
[[introduction-ourview]]
-=== Our View of {apiname}
+=== Our View of Vulkan
-We view {apiname} as a pipeline having some programmable stages and some
+We view Vulkan as a pipeline having some programmable stages and some
state-driven fixed-function stages that are invoked by a set of specific
drawing operations. We expect this model to result in a specification that
satisfies the needs of both programmers and implementors. It does not,
@@ -86,7 +86,7 @@ efficient than the one specified.
[[introduction-bugs]]
== Filing Bug Reports
-Issues with and bug reports on the {apiname} Specification and the API
+Issues with and bug reports on the Vulkan Specification and the API
Registry can: be filed in the Khronos Vulkan Github repository, located at
URL
@@ -173,7 +173,7 @@ endif::editing-notes[]
== Normative References
Normative references are references to external documents or resources to
-which implementers of {apiname} must: comply.
+which implementers of Vulkan must: comply.
[[IEEE 754]]:: _IEEE Standard for Floating-Point Arithmetic_,
IEEE Std 754-2008,
diff --git a/doc/specs/vulkan/chapters/memory.txt b/doc/specs/vulkan/chapters/memory.txt
index 0ba4c388..cc8f7505 100644
--- a/doc/specs/vulkan/chapters/memory.txt
+++ b/doc/specs/vulkan/chapters/memory.txt
@@ -4,20 +4,20 @@
[[memory]]
= Memory Allocation
-{apiname} memory is broken up into two categories, _host memory_ and
+Vulkan memory is broken up into two categories, _host memory_ and
_device memory_.
[[memory-host]]
== Host Memory
-Host memory is memory needed by the {apiname} implementation for
+Host memory is memory needed by the Vulkan implementation for
non-device-visible storage. This storage may: be used for e.g. internal
software structures.
[[memory-allocation]]
-{apiname} provides applications the opportunity to perform host memory
-allocations on behalf of the {apiname} implementation. If this feature is
+Vulkan provides applications the opportunity to perform host memory
+allocations on behalf of the Vulkan implementation. If this feature is
not used, the implementation will perform its own memory allocations. Since
most memory allocations are off the critical path, this is not meant as a
performance feature. Rather, this can: be useful for certain embedded
@@ -31,7 +31,7 @@ include::../structs/VkAllocationCallbacks.txt[]
* pname:pUserData is a value to be interpreted by the implementation of
the callbacks. When any of the callbacks in sname:VkAllocationCallbacks
- are called, the {apiname} implementation will pass this value as the
+ are called, the Vulkan implementation will pass this value as the
first parameter to the callback. This value can: vary each time an
allocator is passed into a command, even when the same object takes an
allocator in multiple commands.
@@ -190,17 +190,17 @@ 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 duration of the {apiname} command.
+ the duration of the Vulkan command.
* ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT - The allocation is scoped to
- the lifetime of the {apiname} object that is being created or used.
+ the lifetime of the Vulkan object that is being created or used.
* ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE - The allocation is scoped to the
lifetime of a sname:VkPipelineCache object.
* ename:VK_SYSTEM_ALLOCATION_SCOPE_DEVICE - The allocation is scoped to
- the lifetime of the {apiname} device.
+ the lifetime of the Vulkan device.
* ename:VK_SYSTEM_ALLOCATION_SCOPE_INSTANCE - The allocation is scoped to
- the lifetime of the {apiname} instance.
+ the lifetime of the Vulkan instance.
-Most {apiname} commands operate on a single object, or there is a sole
+Most Vulkan commands operate on a single object, or there is a sole
object that is being created or manipulated. When an allocation uses a scope
of ename:VK_SYSTEM_ALLOCATION_SCOPE_OBJECT or
ename:VK_SYSTEM_ALLOCATION_SCOPE_CACHE, the allocation is scoped to the
@@ -292,7 +292,7 @@ If pname:pfnAllocation or pname:pfnReallocation fail, the implementation
may: fail object creation and/or generate an
ename:VK_ERROR_OUT_OF_HOST_MEMORY error, as appropriate.
-Allocation callbacks must: not call any {apiname} commands.
+Allocation callbacks must: not call any Vulkan commands.
The following sets of rules define when an implementation is permitted to
call the allocator callbacks.
@@ -493,8 +493,8 @@ The memory types are sorted according to a preorder which serves to aid
in easily selecting an appropriate memory type. Given two memory types X and
Y, the preorder defines latexmath:[$X \leq Y$] if:
- * the memory property bits set for X are a subset of the memory property
- bits set for Y. Or,
+ * the memory property bits set for X are a strict subset of the memory
+ property bits set for Y. Or,
* the memory property bits set for X are the same as the memory property
bits set for Y, and X uses a memory heap with greater or equal
performance (as determined in an implementation-specific manner).
@@ -539,7 +539,7 @@ accesses, as appropriate for the intended usage, and if such a memory type is
not present can: fallback to searching for a less optimal but guaranteed set of
properties such as "0" or "host-visible and coherent".
-A {apiname} device operates on data in device memory via memory objects that
+A Vulkan device operates on data in device memory via memory objects that
are represented in the API by a sname:VkDeviceMemory handle. Memory objects
are allocated by calling fname:vkAllocateMemory:
@@ -657,16 +657,6 @@ include::../validity/protos/vkMapMemory.txt[]
It is an application error to call fname:vkMapMemory on a memory object that
is already mapped.
-ifdef::editing-notes[]
-[NOTE]
-.editing-note
-====
-TODO (Tobias) - There's a circular section reference in this next section.
-The information is all covered by both places, but it seems a bit weird to
-have them reference each other. Not sure how to resolve it.
-====
-endif::editing-notes[]
-
[[memory-device-hostaccess-hazards]]
fname:vkMapMemory does not check whether the device memory is currently in
use before returning the host-accessible pointer. The application
@@ -696,35 +686,11 @@ familiar with all of the mechanisms described in the chapter on
to maintaining memory access ordering.
====
-Host-visible memory types that advertise the
-ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT property still require
-<> between host and
-device in order to be coherent, but do not require additional cache
-management operations (fname:vkFlushMappedMemoryRanges or
-fname:vkInvalidateMappedMemoryRanges) to achieve coherency. For host writes
-to be seen by subsequent command buffer operations, a pipeline barrier from
-a source of ename:VK_ACCESS_HOST_WRITE_BIT and
-ename:VK_PIPELINE_STAGE_HOST_BIT to a destination of the relevant device
-pipeline stages and access types must: be performed. Note that such a
-barrier is performed
-<> upon each
-command buffer submission, so an explicit barrier is only rarely needed
-(e.g. if a command buffer waits upon an event signaled by the host, where
-the host wrote some data after submission). For device writes to be seen by
-subsequent host reads, a pipeline barrier is required: to
-<>.
+Two commands are provided to enable applications to work with
+non-coherent memory allocations: fname:vkFlushMappedMemoryRanges and
+fname:vkInvalidateMappedMemoryRanges.
-In order to enable applications to work with non-coherent memory
-allocations, two entry points are provided. To flush host write caches, an
-application must: use fname:vkFlushMappedMemoryRanges, while
-fname:vkInvalidateMappedMemoryRanges allows invalidating host input caches
-so that device writes become visible to the host.
-fname:vkFlushMappedMemoryRanges must: be called after the host writes to
-non-coherent memory have completed and before command buffers that will read
-or write any of those memory locations are submitted to a queue. Similarly,
-fname:vkInvalidateMappedMemoryRanges must: be called after command buffers
-that execute and flush (via memory barriers) the device writes have
-completed, and before the host will read or write any of those locations.
+To flush ranges of non-coherent memory from the host caches, call:
include::../protos/vkFlushMappedMemoryRanges.txt[]
@@ -736,6 +702,13 @@ include::../protos/vkFlushMappedMemoryRanges.txt[]
include::../validity/protos/vkFlushMappedMemoryRanges.txt[]
+fname:vkFlushMappedMemoryRanges must: be used to guarantee that host writes to
+non-coherent memory are visible to the device. It must: be called after the host
+writes to non-coherent memory have completed and before command buffers that will
+read or write any of those memory locations are submitted to a queue.
+
+To invalidate ranges of non-coherent memory from the host caches, call:
+
include::../protos/vkInvalidateMappedMemoryRanges.txt[]
* pname:device is the logical device that owns the memory ranges.
@@ -770,8 +743,42 @@ fname:vkFlushMappedMemoryRanges and fname:vkInvalidateMappedMemoryRanges are
unnecessary and may: have performance cost.
====
+fname:vkInvalidateMappedMemoryRanges must: be used to guarantee that device writes to
+non-coherent memory are visible to the host. It must: be called after command buffers
+that execute and flush (via memory barriers) the device writes have completed, and
+before the host will read or write any of those locations. If a range of non-coherent
+memory is written by the host and then invalidated without first being flushed, its
+contents are undefined.
+
+ifdef::editing-notes[]
+[NOTE]
+.editing-note
+====
+TODO (Tobias) - There's a circular section reference between this next section
+and the <>. The
+information is all covered by both places, but it seems a bit weird to have them
+reference each other. Not sure how to resolve it.
+====
+endif::editing-notes[]
+
+Host-visible memory types that advertise the
+ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT property still require
+<> between host and device
+in order to be coherent, but do not require additional cache management
+operations to achieve coherency. For host writes to
+be seen by subsequent command buffer operations, a pipeline barrier from
+a source of ename:VK_ACCESS_HOST_WRITE_BIT and ename:VK_PIPELINE_STAGE_HOST_BIT
+to a destination of the relevant device pipeline stages and access types must:
+be performed. Note that such a barrier is performed
+<> upon each
+command buffer submission, so an explicit barrier is only rarely needed
+(e.g. if a command buffer waits upon an event signaled by the host, where
+the host wrote some data after submission). For device writes to be seen by
+subsequent host reads, a pipeline barrier is required: to
+<>.
+
Once host access to a memory object is no longer needed by the application,
-it can: be unmapped by calling :
+it can: be unmapped by calling:
include::../protos/vkUnmapMemory.txt[]
diff --git a/doc/specs/vulkan/chapters/pipelines.txt b/doc/specs/vulkan/chapters/pipelines.txt
index f6908236..f2b4a0ba 100644
--- a/doc/specs/vulkan/chapters/pipelines.txt
+++ b/doc/specs/vulkan/chapters/pipelines.txt
@@ -5,7 +5,7 @@
= Pipelines
The following <> shows a block diagram of
-the {apiname} pipelines. Some {apiname} commands specify geometric objects
+the Vulkan pipelines. Some Vulkan commands specify geometric objects
to be drawn or computational work to be performed, while others specify
state controlling how objects are handled by the various pipeline stages, or
control data transfer between memory organized as images and buffers.
@@ -46,8 +46,8 @@ The <> is a separate pipeline from the
graphics pipeline, which operates on one-, two-, or three-dimensional
workgroups which can: read from and write to buffer and image memory.
-This ordering is meant only as a tool for describing {apiname}, not as a
-strict rule of how {apiname} is implemented, and we present it only as a
+This ordering is meant only as a tool for describing Vulkan, not as a
+strict rule of how Vulkan is implemented, and we present it only as a
means to organize the various operations of the pipelines.
[[pipelines-block-diagram]]
@@ -98,7 +98,7 @@ include::../protos/vkCreateComputePipelines.txt[]
<> object, in which case use of that
cache is enabled for the duration of the command.
* pname:createInfoCount is the length of the pname:pCreateInfos and
- pname:Pipelines arrays.
+ pname:pPipelines arrays.
* pname:pCreateInfos is an array of sname:VkComputePipelineCreateInfo
structures.
* pname:pAllocator controls host memory allocation as described in the
@@ -183,7 +183,7 @@ include::../protos/vkCreateGraphicsPipelines.txt[]
<> object, in which case use of that
cache is enabled for the duration of the command.
* pname:createInfoCount is the length of the pname:pCreateInfos and
- pname:Pipelines arrays.
+ pname:pPipelines arrays.
* pname:pCreateInfos is an array of sname:VkGraphicsPipelineCreateInfo
structures.
* pname:pAllocator controls host memory allocation as described in the
@@ -493,8 +493,9 @@ pipelines is achieved by passing the same pipeline cache object when
creating multiple related pipelines. Reuse across runs of an application is
achieved by retrieving pipeline cache contents in one run of an application,
saving the contents, and using them to preinitialize a pipeline cache on a
-subsequent run. The contents and size of the pipeline cache objects are
-managed by the implementation. Applications can: control the amount of data
+subsequent run. The contents of the pipeline cache objects are
+managed by the implementation. Applications can: manage the host memory
+consumed by a pipeline cache object and control the amount of data
retrieved from a pipeline cache object.
Pipeline cache objects are created by calling:
@@ -511,6 +512,16 @@ include::../protos/vkCreatePipelineCache.txt[]
* pname:pPipelineCache is a pointer to a sname:VkPipelineCache handle in
which the resulting pipeline cache object is returned.
+[NOTE]
+.Note
+====
+Applications can: track and manage the total host memory size of a pipeline
+cache object using the pname:pAllocator. Applications can: limit the amount
+of data retrieved from a pipeline cache object in fname:vkGetPipeineCacheData.
+Implementations shouldnot: internally limit the total number of entries added to a
+pipeline cache object or the total host memory consumed.
+====
+
include::../validity/protos/vkCreatePipelineCache.txt[]
The sname:VkPipelineCacheCreateInfo structure is defined as:
diff --git a/doc/specs/vulkan/chapters/primsrast.txt b/doc/specs/vulkan/chapters/primsrast.txt
index 54a00b6a..36eb9d04 100644
--- a/doc/specs/vulkan/chapters/primsrast.txt
+++ b/doc/specs/vulkan/chapters/primsrast.txt
@@ -122,7 +122,7 @@ stage in the pipeline before rasterization.
[[primsrast-multisampling]]
== Multisampling
-Multisampling is a mechanism to antialias all {apiname} primitives: points,
+Multisampling is a mechanism to antialias all Vulkan primitives: points,
lines, and polygons. The technique is to sample all primitives multiple
times at each pixel. Each sample in each framebuffer attachment has storage
for a color, depth, and/or stencil value, such that per-fragment operations
@@ -131,7 +131,7 @@ _resolved_ to a single color (see <> and the <> chapter for more details on how
to resolve multisample images to non-multisample images).
-{apiname} defines rasterization rules for single-sample modes in a way that
+Vulkan defines rasterization rules for single-sample modes in a way that
is equivalent to a multisample mode with a single sample in the center of
each pixel.
diff --git a/doc/specs/vulkan/chapters/queries.txt b/doc/specs/vulkan/chapters/queries.txt
index a831f1f0..8921c430 100644
--- a/doc/specs/vulkan/chapters/queries.txt
+++ b/doc/specs/vulkan/chapters/queries.txt
@@ -5,7 +5,7 @@
= Queries
_Queries_ provide a mechanism to return information about the processing of
-a sequence of {apiname} commands. Query operations are asynchronous, and as
+a sequence of Vulkan commands. Query operations are asynchronous, and as
such, their results are not returned immediately. Instead, their results,
and their availability status, are stored in a <>. The state of these queries can: be read back on the host, or copied
@@ -246,7 +246,7 @@ These bits have the following meanings:
* ename:VK_QUERY_RESULT_64_BIT indicates the results will be written as an
array of 64-bit unsigned integer values. If this bit is not set, the
results will be written as an array of 32-bit unsigned integer values.
- * ename:VK_QUERY_RESULT_WAIT_BIT indicates that {apiname} will wait for
+ * ename:VK_QUERY_RESULT_WAIT_BIT indicates that Vulkan will wait for
each query's status to become available before retrieving its results.
* ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT indicates that the
availability status accompanies the results.
@@ -263,7 +263,7 @@ If ename:VK_QUERY_RESULT_64_BIT is not set and the result overflows a
ename:VK_QUERY_RESULT_64_BIT is set and the result overflows a 64-bit
value, the value may: either wrap or saturate.
-If ename:VK_QUERY_RESULT_WAIT_BIT is set, {apiname} will wait for each
+If ename:VK_QUERY_RESULT_WAIT_BIT is set, Vulkan will wait for each
query to be in the available state before retrieving the numerical
results for that query. In this case, fname:vkGetQueryPoolResults is
guaranteed to succeed and return ename:VK_SUCCESS if the queries
@@ -458,7 +458,7 @@ but still not be visible in a final image.
== Pipeline Statistics Queries
Pipeline statistics queries allow the application to sample a specified set
-of sname:VkPipeline counters. These counters are accumulated by {apiname}
+of sname:VkPipeline counters. These counters are accumulated by Vulkan
for a set of either draw or dispatch commands while a pipeline statistics
query is active. As such, pipeline statistics queries are available on
queue families supporting either graphics or compute operations. Further,
diff --git a/doc/specs/vulkan/chapters/renderpass.txt b/doc/specs/vulkan/chapters/renderpass.txt
index 6d50f16c..cea83b21 100644
--- a/doc/specs/vulkan/chapters/renderpass.txt
+++ b/doc/specs/vulkan/chapters/renderpass.txt
@@ -758,8 +758,8 @@ include::../structs/VkRenderPassBeginInfo.txt[]
* pname:pClearValues is an array of slink:VkClearValue structures that
contains clear values for each attachment, if the attachment uses a
pname:loadOp value of ename:VK_ATTACHMENT_LOAD_OP_CLEAR. The array is
- indexed by attachment number, with elements corresponding to uncleared
- attachments being unused.
+ indexed by attachment number. Only elements corresponding to cleared
+ attachments are used. Other elements of pname:pClearValues are ignored.
include::../validity/structs/VkRenderPassBeginInfo.txt[]
diff --git a/doc/specs/vulkan/chapters/resources.txt b/doc/specs/vulkan/chapters/resources.txt
index 5dae7823..712a8cdf 100644
--- a/doc/specs/vulkan/chapters/resources.txt
+++ b/doc/specs/vulkan/chapters/resources.txt
@@ -4,7 +4,7 @@
[[resources]]
= Resource Creation
-{apiname} supports two primary resource types: _buffers_ and _images_.
+Vulkan supports two primary resource types: _buffers_ and _images_.
Resources are views of memory with associated formatting and dimensionality.
Buffers are essentially unformatted arrays of bytes whereas images contain
format information, can: be multidimensional and may: have associated
@@ -449,7 +449,7 @@ pname:depthPitch is defined only for 3D images.
For color formats, the pname:aspectMask member of sname:VkImageSubresource
must: be ename:VK_IMAGE_ASPECT_COLOR_BIT. For depth/stencil formats,
-pname:aspect must: be either ename:VK_IMAGE_ASPECT_DEPTH_BIT or
+pname:aspectMask must: be either ename:VK_IMAGE_ASPECT_DEPTH_BIT or
ename:VK_IMAGE_ASPECT_STENCIL_BIT. On implementations that store depth and
stencil aspects separately, querying each of these image subresource layouts
will return a different pname:offset and pname:size representing the region
@@ -997,7 +997,7 @@ include::../protos/vkBindBufferMemory.txt[]
include::../validity/protos/vkBindBufferMemory.txt[]
-To attach memory to a image object, call:
+To attach memory to an image object, call:
include::../protos/vkBindImageMemory.txt[]
diff --git a/doc/specs/vulkan/chapters/samplers.txt b/doc/specs/vulkan/chapters/samplers.txt
index 3c7c1419..7dcc205a 100644
--- a/doc/specs/vulkan/chapters/samplers.txt
+++ b/doc/specs/vulkan/chapters/samplers.txt
@@ -109,7 +109,7 @@ include::../enums/VkBorderColor.txt[]
** The functions mustnot: use offsets.
[NOTE]
-.Mapping of OpenGL to {apiname} filter modes
+.Mapping of OpenGL to Vulkan filter modes
==================
pname:magFilter values of ename:VK_FILTER_NEAREST and ename:VK_FILTER_LINEAR
directly correspond to code:GL_NEAREST and code:GL_LINEAR magnification
@@ -120,7 +120,7 @@ ename:VK_FILTER_LINEAR and pname:mipmapMode of
ename:VK_SAMPLER_MIPMAP_MODE_NEAREST correspond to
code:GL_LINEAR_MIPMAP_NEAREST).
-There are no {apiname} filter modes that directly correspond to OpenGL
+There are no Vulkan filter modes that directly correspond to OpenGL
minification filters of code:GL_LINEAR or code:GL_NEAREST, but they can: be
emulated using ename:VK_SAMPLER_MIPMAP_MODE_NEAREST, pname:minLod = 0, and
pname:maxLod = 0.25, and using pname:minFilter = ename:VK_FILTER_LINEAR or
diff --git a/doc/specs/vulkan/chapters/shaders.txt b/doc/specs/vulkan/chapters/shaders.txt
index 70e29756..dc59d5d5 100644
--- a/doc/specs/vulkan/chapters/shaders.txt
+++ b/doc/specs/vulkan/chapters/shaders.txt
@@ -40,7 +40,7 @@ _Shader modules_ contain _shader code_ and one or more entry points. Shaders
are selected from a shader module by specifying an entry point as part of
<> creation. The stages of a pipeline can: use shaders
that come from different modules. The shader code defining a shader module
-must: be in the SPIR-V format, as described by the <> appendix.
A shader module is created by calling:
diff --git a/doc/specs/vulkan/chapters/sparsemem.txt b/doc/specs/vulkan/chapters/sparsemem.txt
index e8fa836b..39ef1bfc 100644
--- a/doc/specs/vulkan/chapters/sparsemem.txt
+++ b/doc/specs/vulkan/chapters/sparsemem.txt
@@ -5,7 +5,7 @@
= Sparse Resources
As documented in <>,
-sname:VkBuffer and sname:VkImage resources in {apiname} must: be bound
+sname:VkBuffer and sname:VkImage resources in Vulkan must: be bound
completely and contiguously to a single sname:VkDeviceMemory object.
This binding must: be done before the resource is used, and the
binding is immutable for the lifetime of the resource.
@@ -1027,7 +1027,7 @@ arrayMipTailOffset = imageMipTailOffset + arrayLayer * imageMipTailStride;
and the mip tail can: be bound with code:layerCount slink:VkSparseMemoryBind
structures, each using pname:size = pname:imageMipTailSize and
-pname:resourceOffset = pname:arrayMipTailOffset as defined above.
+pname:resourceOffset = ptext:arrayMipTailOffset as defined above.
Sparse memory binding is handled by the following APIs and related data
structures.
@@ -1167,7 +1167,7 @@ include::../structs/VkSparseImageMemoryBind.txt[]
* pname:extent is the size in texels of the region within the image
subresource to bind. The extent must: be a multiple of the sparse image
block dimensions, except when binding sparse image blocks along the edge
- of a image subresource it can: instead be such that any coordinate of
+ of an image subresource it can: instead be such that any coordinate of
latexmath:[$\mathit{offset} + \mathit{extent}$] equals the corresponding
dimensions of the image subresource.
* pname:memory is the sname:VkDeviceMemory object that the sparse image
diff --git a/doc/specs/vulkan/chapters/synchronization.txt b/doc/specs/vulkan/chapters/synchronization.txt
index 6f8f43bb..8f74e2df 100644
--- a/doc/specs/vulkan/chapters/synchronization.txt
+++ b/doc/specs/vulkan/chapters/synchronization.txt
@@ -5,17 +5,17 @@
= Synchronization and Cache Control
Synchronization of access to resources is primarily the responsibility of
-the application. In {apiname}, there are four forms of concurrency during
+the application. In Vulkan, there are four forms of concurrency during
execution: between the host and device, between the queues, between
queue submissions, and between commands within a command buffer.
-{apiname} provides the application with a set of
+Vulkan provides the application with a set of
synchronization primitives for these purposes. Further, memory caches and
other optimizations mean that the normal flow of command execution does not
guarantee that all memory transactions from a command are immediately
-visible to other agents with views into a given range of memory. {apiname}
+visible to other agents with views into a given range of memory. Vulkan
also provides barrier operations to ensure this type of synchronization.
-Four synchronization primitive types are exposed by {apiname}. These are:
+Four synchronization primitive types are exposed by Vulkan. These are:
* <>
* <>
@@ -225,7 +225,7 @@ include::../protos/vkDestroySemaphore.txt[]
include::../validity/protos/vkDestroySemaphore.txt[]
To signal a semaphore from a queue, include it in an element of the array
-of slink:VkSubmitInfo structures passed through the pname:pSubmitInfo
+of slink:VkSubmitInfo structures passed through the pname:pSubmits
parameter to a call to flink:vkQueueSubmit, or in an element of the array
of slink:VkBindSparseInfo structures passed through the pname:pBindInfo
parameter to a call to flink:vkQueueBindSparse.
@@ -297,7 +297,7 @@ 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.)
+is not defined in the core Vulkan specification.)
====
When a queue signals or waits upon a semaphore, certain
@@ -313,7 +313,7 @@ the host.
Events represent a fine-grained synchronization primitive that can: be used
to gauge progress through a sequence of commands executed on a queue by
-{apiname}. An event is initially in the unsignaled state. It can: be
+Vulkan. An event is initially in the unsignaled state. It can: be
signaled by a device, using commands inserted into the command buffer, or by
the host. It can: also be reset to the unsignaled state by a device or the
host. The host can: query the state of an event. A device can: wait for one
@@ -936,7 +936,7 @@ Enumeration>> and <>.
_Memory barriers_ express the two halves of a memory dependency between an
earlier set of memory accesses against a later set of memory accesses.
-{apiname} provides three types of memory barriers: global memory, buffer
+Vulkan provides three types of memory barriers: global memory, buffer
memory, and image memory.
@@ -1142,7 +1142,7 @@ include::../validity/structs/VkBufferMemoryBarrier.txt[]
The image memory barrier type is specified with an instance of the
sname:VkImageMemoryBarrier structure. This type of barrier only applies to
memory accesses involving a specific image subresource range of the
-specified image object. That is, a memory dependency formed from a image
+specified image object. That is, a memory dependency formed from an image
memory barrier is
<> to the
specified image subresources of the image. It is also used to perform a
diff --git a/doc/specs/vulkan/copyright.txt b/doc/specs/vulkan/copyright.txt
index 9d45fbb5..e2eea321 100644
--- a/doc/specs/vulkan/copyright.txt
+++ b/doc/specs/vulkan/copyright.txt
@@ -62,6 +62,6 @@ representatives be liable for any damages, whether direct, indirect, special or
consequential damages for lost revenues, lost profits, or otherwise, arising from or in
connection with these materials.
-Khronos and {apiname} are trademarks of The Khronos Group Inc. OpenCL is a trademark of
+Khronos and Vulkan are trademarks of The Khronos Group Inc. OpenCL is a trademark of
Apple Inc. and OpenGL is a registered trademark of Silicon Graphics International, both
used under license by Khronos.
diff --git a/doc/specs/vulkan/genRelease b/doc/specs/vulkan/genRelease
index 6341e815..535da30d 100755
--- a/doc/specs/vulkan/genRelease
+++ b/doc/specs/vulkan/genRelease
@@ -18,7 +18,9 @@ from datetime import *
# branch = branch or commit or tag name
# label = textual label to apply
# outdir = directory to generate specs in
-def buildRelease(branch,label,outdir,targets):
+# xmlTargets = targets to build in src/spec/
+# specTargets = targets to build in doc/specs/vulkan/
+def buildRelease(branch,label,outdir,xmlTargets,specTargets):
global root, xml, spec
print('echo Info: Generating branch=' + branch,
@@ -26,10 +28,6 @@ def buildRelease(branch,label,outdir,targets):
'outdir=' + outdir)
print('git checkout', branch)
- print('echo Info: Generating headers and spec include files')
- print('cd', xml)
- print('make clobber full_install')
-
print('echo Info: Cleaning spec in', outdir)
print('cd', spec)
print('rm -rf',
@@ -40,9 +38,15 @@ def buildRelease(branch,label,outdir,targets):
outdir + '/vkspec.html',
'specversion.txt')
+ print('echo Info: Generating headers and spec include files')
+ print('cd', xml)
+ print('make OUTDIR=' + outdir, xmlTargets)
+
print('echo Info: Generating spec')
+ print('cd', spec)
print('make specversion.txt')
- print('make -j 4 OUTDIR=' + outdir, ' NOTEOPTS="-a implementation-guide"', targets)
+ print('make -j 4 OUTDIR=' + outdir, ' NOTEOPTS="-a implementation-guide"',
+ specTargets)
print('rm', outdir + '/pdf/vkspec.xml')
# Main
@@ -68,11 +72,15 @@ wsibranch = '1.0-wsi_extensions'
now = datetime.today().strftime('%Y%m%d')
# Generate specs
-coretargets='xhtml pdf styleguide manhtml manpdf manhtmlpages'
-buildRelease(corebranch, corebranch, outdir + corebranch, coretargets)
+coreXmlTargets='clobber full_install pdf_install'
+coreSpecTargets='xhtml pdf styleguide manhtml manpdf manhtmlpages'
+buildRelease(corebranch, corebranch, outdir + corebranch,
+ coreXmlTargets, coreSpecTargets)
-wsitargets='xhtml pdf'
-buildRelease(wsibranch, wsibranch, outdir + wsibranch, wsitargets)
+wsiXmlTargets='clobber full_install'
+wsiSpecTargets='xhtml pdf'
+buildRelease(wsibranch, wsibranch, outdir + wsibranch,
+ wsiXmlTargets, wsiSpecTargets)
print('echo Info: post-generation cleanup')
@@ -80,8 +88,9 @@ print('git checkout ' + corebranch)
print('echo To tag the spec branches, execute these commands:')
print('echo git checkout', corebranch)
-print('echo git tag -a -m \\"Tag core API specification for', now, 'release\\"', 'v1.0-core-' + now)
+print('echo git tag -a -m \\"Tag core API specification for', now,
+ 'release\\"', 'v1.0-core-' + now)
print('echo git checkout', wsibranch)
-print('echo git tag -a -m \\"Tag core+WSI API specification for', now, 'release\\"', 'v1.0-core+wsi-' + now)
-print('echo git push --tags')
+print('echo git tag -a -m \\"Tag core+WSI API specification for', now,
+ 'release\\"', 'v1.0-core+wsi-' + now)
diff --git a/doc/specs/vulkan/man/vkAllocateCommandBuffers.txt b/doc/specs/vulkan/man/vkAllocateCommandBuffers.txt
index 3af458c9..948b2386 100644
--- a/doc/specs/vulkan/man/vkAllocateCommandBuffers.txt
+++ b/doc/specs/vulkan/man/vkAllocateCommandBuffers.txt
@@ -25,7 +25,7 @@ pname:pCommandBuffers::
Description
-----------
-fname::vkAllocateCommandBuffers allocates command buffers from an existing command pool. pname:pAllocateInfo
+fname:vkAllocateCommandBuffers allocates command buffers from an existing command pool. pname:pAllocateInfo
is a pointer to an instance of the slink:VkCommandBufferAllocateInfo structure which
describes the command buffer allocation. The definition of slink:VkCommandBufferAllocateInfo is:
diff --git a/doc/specs/vulkan/man/vkCmdCopyBuffer.txt b/doc/specs/vulkan/man/vkCmdCopyBuffer.txt
index 626ada51..e8ca4bf1 100644
--- a/doc/specs/vulkan/man/vkCmdCopyBuffer.txt
+++ b/doc/specs/vulkan/man/vkCmdCopyBuffer.txt
@@ -39,7 +39,7 @@ the slink:VkBufferCopy structure, whose definition is:
include::../structs/VkBufferCopy.txt[]
If any two or more regions within pname:pRegions overlap, the resulting data will be
-undefined. It is recomended, but not required, that the regions given in pname:pRegions
+undefined. It is recommended, but not required, that the regions given in pname:pRegions
start on multiples of four bytes and have a length which is a multiple of four bytes.
include::../validity/protos/vkCmdCopyBuffer.txt[]
diff --git a/doc/specs/vulkan/man/vkCmdResolveImage.txt b/doc/specs/vulkan/man/vkCmdResolveImage.txt
index 8bff87d7..261c065b 100644
--- a/doc/specs/vulkan/man/vkCmdResolveImage.txt
+++ b/doc/specs/vulkan/man/vkCmdResolveImage.txt
@@ -14,7 +14,7 @@ Parameters
----------
pname:commandBuffer::
- Ths command buffer into which the command is to be placed.
+ The command buffer into which the command is to be placed.
pname:srcImage::
The image that is the source of the resolve operation.
diff --git a/doc/specs/vulkan/man/vkCmdWaitEvents.txt b/doc/specs/vulkan/man/vkCmdWaitEvents.txt
index ca63b29c..827c78ba 100644
--- a/doc/specs/vulkan/man/vkCmdWaitEvents.txt
+++ b/doc/specs/vulkan/man/vkCmdWaitEvents.txt
@@ -43,13 +43,13 @@ Description
-----------
fname:vkCmdWaitEvents waits for a number of event objects to become
-signalled and inserts a set of memory barriers into the command buffer
+signaled and inserts a set of memory barriers into the command buffer
specified by pname:commandBuffer.
fname:vkCmdWaitEvents waits for each of the pname:eventCount event object
-specified by pname:pEvents to become signalled. The point at which each is
-signalled must have been specified in the command that caused the object to
-become signalled (either fname:vkSetEvent or fname:vkCmdSetEvent) and must
+specified by pname:pEvents to become signaled. The point at which each is
+signaled must have been specified in the command that caused the object to
+become signaled (either fname:vkSetEvent or fname:vkCmdSetEvent) and must
also have the corresponding bit set in pname:srcStageMask.
The pname:ppMemoryBarriers parameter is a pointer to an array of pname:memoryBarrierCount
diff --git a/doc/specs/vulkan/man/vkCreateBuffer.txt b/doc/specs/vulkan/man/vkCreateBuffer.txt
index 3374be4e..dec66c0b 100644
--- a/doc/specs/vulkan/man/vkCreateBuffer.txt
+++ b/doc/specs/vulkan/man/vkCreateBuffer.txt
@@ -20,7 +20,7 @@ pname:pCreateInfo::
Pointer to data structure containing information about the object to be created.
pname:pBuffer::
- Pointer to a variable to recieve a handle to the new buffer object.
+ Pointer to a variable to receive a handle to the new buffer object.
Description
-----------
diff --git a/doc/specs/vulkan/man/vkCreateComputePipelines.txt b/doc/specs/vulkan/man/vkCreateComputePipelines.txt
index 4b914d3a..fa6fdb6a 100644
--- a/doc/specs/vulkan/man/vkCreateComputePipelines.txt
+++ b/doc/specs/vulkan/man/vkCreateComputePipelines.txt
@@ -66,7 +66,7 @@ to fname:vkCreateComputePipelines.
The parameters pname:basePipelineHandle and pname:basePipelineIndex are ignored
unless pname:flags has the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT bit set. If
using the pname:basePipelineIndex parameter, the index must refer to a
-pname:pCreateInfos parameter pased to vkCreateComputePipelines that appeared
+pname:pCreateInfos parameter passed to vkCreateComputePipelines that appeared
earlier than the current sname:VkComputePipelineCreateInfo in the list. The
parameters pname:basePipelineHandle and pname:basePipelineIndex are mutually
exclusive. If you specify a valid pname:basePipelineHandle,
diff --git a/doc/specs/vulkan/man/vkCreateImageView.txt b/doc/specs/vulkan/man/vkCreateImageView.txt
index 33731b6d..facd64b4 100644
--- a/doc/specs/vulkan/man/vkCreateImageView.txt
+++ b/doc/specs/vulkan/man/vkCreateImageView.txt
@@ -25,7 +25,7 @@ pname:pView::
Description
-----------
-fname:vkCreateImageView creates a new view of a source image in a compatible format, alowing casting
+fname:vkCreateImageView creates a new view of a source image in a compatible format, allowing casting
of image data from one format to another. Image views may be bound into descriptor sets to allow them
to be accessed in shaders, or be bound as color attachments. pname:device specifies the device that
is to be used to create the new view. pname:pCreateInfo is a pointer to an instance of the
diff --git a/doc/specs/vulkan/man/vkCreatePipelineLayout.txt b/doc/specs/vulkan/man/vkCreatePipelineLayout.txt
index 3a6828f9..987e5380 100644
--- a/doc/specs/vulkan/man/vkCreatePipelineLayout.txt
+++ b/doc/specs/vulkan/man/vkCreatePipelineLayout.txt
@@ -20,7 +20,7 @@ pname:pCreateInfo::
A pointer to structure specifying the properties of the new pipeline layout.
pname:pPipelineLayout::
- Pointer to a variable to recieve a handle to the new pipeline layout object.
+ Pointer to a variable to receive a handle to the new pipeline layout object.
Description
-----------
diff --git a/doc/specs/vulkan/man/vkEnumeratePhysicalDevices.txt b/doc/specs/vulkan/man/vkEnumeratePhysicalDevices.txt
index f51f0136..17334512 100644
--- a/doc/specs/vulkan/man/vkEnumeratePhysicalDevices.txt
+++ b/doc/specs/vulkan/man/vkEnumeratePhysicalDevices.txt
@@ -41,7 +41,7 @@ If pname:pPhysicalDevices is not code:NULL, then pname:pPhysicalDeviceCount shou
to a variable that has been initialized with the size of the array pointed to by pname:pPhysicalDevices.
No more than this number of physical device handles will be written into the output array.
The actual number of device handles written into pname:pPhysicalDevices is then written into
-the variable pointed to pname:pPhysicalDevices.
+the variable pointed to by pname:pPhysicalDeviceCount.
include::../validity/protos/vkEnumeratePhysicalDevices.txt[]
diff --git a/doc/specs/vulkan/man/vkGetImageSubresourceLayout.txt b/doc/specs/vulkan/man/vkGetImageSubresourceLayout.txt
index 4e4e16ae..ad37fc16 100644
--- a/doc/specs/vulkan/man/vkGetImageSubresourceLayout.txt
+++ b/doc/specs/vulkan/man/vkGetImageSubresourceLayout.txt
@@ -30,7 +30,7 @@ Description
-----------
fname:vkGetImageSubresourceLayout returns information about the memory
-layout of a image subresource of an image. pname:device is a handle to the
+layout of an image subresource of an image. pname:device is a handle to the
device that owns pname:image, which is the image about which to retrieve
information. A description of the image subresource is passsed to the
command through an instance of the slink:VkImageSubresource structure, the
diff --git a/doc/specs/vulkan/man/vkGetInstanceProcAddr.txt b/doc/specs/vulkan/man/vkGetInstanceProcAddr.txt
index 8548f830..156e8cbe 100644
--- a/doc/specs/vulkan/man/vkGetInstanceProcAddr.txt
+++ b/doc/specs/vulkan/man/vkGetInstanceProcAddr.txt
@@ -30,7 +30,7 @@ different values of pname:instance.
If pname:instance is code:NULL, fname:vkGetInstanceProcAddr will return
non-code:NULL function pointers for the global commands
-fname::vkEnumerateInstanceExtensionProperties,
+fname:vkEnumerateInstanceExtensionProperties,
fname:vkEnumerateInstanceLayerProperties, and fname:vkCreateInstance. It will
return code:NULL for all other commands, since they may have different
implementations in different instances.
diff --git a/doc/specs/vulkan/man/vkGetPhysicalDeviceQueueFamilyProperties.txt b/doc/specs/vulkan/man/vkGetPhysicalDeviceQueueFamilyProperties.txt
index ad7e2bd7..9ccfabfd 100644
--- a/doc/specs/vulkan/man/vkGetPhysicalDeviceQueueFamilyProperties.txt
+++ b/doc/specs/vulkan/man/vkGetPhysicalDeviceQueueFamilyProperties.txt
@@ -73,8 +73,8 @@ operations such as binding graphics state and graphics pipelines and executing d
* If a queue's ptext:queueFlags member contains ename:VK_QUEUE_COMPUTE_BIT, then it supports compute
operations such as binding compute pipelines and executing compute dispatches.
-* If a queue's ptext:queueFlags member contains ename:VK_QUEUE_TRANSFER_BIT, then it supports transsfer
-operations, which include copying data an images.
+* If a queue's ptext:queueFlags member contains ename:VK_QUEUE_TRANSFER_BIT, then it supports transfer
+operations, which include copying data and images.
* If a queue's ptext:queueFlags member contains ename:VK_QUEUE_SPARSE_BINDING_BIT, then it supports
binding memory to sparse buffer and image resources.
diff --git a/doc/specs/vulkan/style/styleguide.txt b/doc/specs/vulkan/style/styleguide.txt
index 770d18aa..f4f324ee 100644
--- a/doc/specs/vulkan/style/styleguide.txt
+++ b/doc/specs/vulkan/style/styleguide.txt
@@ -583,6 +583,13 @@ See Gitlab issue #61.
====
+=== Terms to Use With Caution
+
+The term _subset_ is sometimes used to refer to a _strict subset_, and
+sometimes used to refer to a subset which may be equal to the entire set.
+This is particularly likely to come up when describing bitmasks. Make sure
+to use either _subset_ or _strict subset_ as appropriate.
+
=== Terms to Avoid
Don't describe anything in the documentation using vague or wishy-washy
@@ -634,6 +641,16 @@ write that it ``contains one or more bits''. A counter example is that it is oka
to write ``For non-stereoscopic-3D applications, this value is 1.''
+=== Use American Spelling Conventions
+
+In case of conflict, use American rather than British spelling
+conventions. For example:
+
+*Correct:* color, signaled.
+
+*Incorrect:* colour, signalled.
+
+
[[writingstyle-describing]]
== Describing Commands and Parameters
@@ -852,7 +869,7 @@ autogenerated from vk.xml, and included from the `../validity/` directories:
include::../validity/protos/vkCreateCommandPool.txt[]
====
-The sname:VkCommandPoolCreateInfo structure is defined as follows:
+The sname:VkCommandPoolCreateInfo structure is defined as:
include::../structs/VkCommandPoolCreateInfo.txt[]
@@ -956,6 +973,9 @@ for this structure:
= Revision History
+* 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.
* March 12, 2016 - Recommend against "the value of".
* February 26, 2016 - Replace use of the "maynot{cl}" macro with "may{cl} not".
* February 16, 2016 - Place asciidoc conversion post-release.
diff --git a/doc/specs/vulkan/validity/protos/vkCmdBlitImage.txt b/doc/specs/vulkan/validity/protos/vkCmdBlitImage.txt
index efdd9194..9726e9ce 100644
--- a/doc/specs/vulkan/validity/protos/vkCmdBlitImage.txt
+++ b/doc/specs/vulkan/validity/protos/vkCmdBlitImage.txt
@@ -35,6 +35,7 @@ endif::doctype-manpage[]
* If either of pname:srcImage or pname:dstImage was created with an unsigned integer elink:VkFormat, the other must: also have been created with an unsigned integer elink:VkFormat
* If either of pname:srcImage or pname:dstImage was created with a depth/stencil format, the other must: have exactly the same format
* If pname:srcImage was created with a depth/stencil format, pname:filter must: be ename:VK_FILTER_NEAREST
+* If pname:filter is ename:VK_FILTER_LINEAR, pname:srcImage must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkCmdClearColorImage.txt b/doc/specs/vulkan/validity/protos/vkCmdClearColorImage.txt
index ba5d69e1..6baaf8fa 100644
--- a/doc/specs/vulkan/validity/protos/vkCmdClearColorImage.txt
+++ b/doc/specs/vulkan/validity/protos/vkCmdClearColorImage.txt
@@ -20,7 +20,7 @@ endif::doctype-manpage[]
* pname:image must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
* pname:imageLayout must: specify the layout of the image subresource ranges of pname:image specified in pname:pRanges at the time this command is executed on a sname:VkDevice
* pname:imageLayout must: be either of ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL
-* The image range of any given element of pname:pRanges must: be a image subresource range that is contained within pname:image
+* The image range of any given element of pname:pRanges must: be an image subresource range that is contained within pname:image
* pname:image mustnot: have a compressed or depth/stencil format
ifndef::doctype-manpage[]
********************************************************************************
diff --git a/doc/specs/vulkan/validity/protos/vkCmdClearDepthStencilImage.txt b/doc/specs/vulkan/validity/protos/vkCmdClearDepthStencilImage.txt
index 1d635617..f08d7358 100644
--- a/doc/specs/vulkan/validity/protos/vkCmdClearDepthStencilImage.txt
+++ b/doc/specs/vulkan/validity/protos/vkCmdClearDepthStencilImage.txt
@@ -20,7 +20,7 @@ endif::doctype-manpage[]
* pname:image must: have been created with ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage flag
* pname:imageLayout must: specify the layout of the image subresource ranges of pname:image specified in pname:pRanges at the time this command is executed on a sname:VkDevice
* pname:imageLayout must: be either of ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL or ename:VK_IMAGE_LAYOUT_GENERAL
-* The image range of any given element of pname:pRanges must: be a image subresource range that is contained within pname:image
+* The image range of any given element of pname:pRanges must: be an image subresource range that is contained within pname:image
* pname:image must: have a depth/stencil format
ifndef::doctype-manpage[]
********************************************************************************
diff --git a/doc/specs/vulkan/validity/protos/vkCmdDispatch.txt b/doc/specs/vulkan/validity/protos/vkCmdDispatch.txt
index d91b3f33..9f394a3b 100644
--- a/doc/specs/vulkan/validity/protos/vkCmdDispatch.txt
+++ b/doc/specs/vulkan/validity/protos/vkCmdDispatch.txt
@@ -23,7 +23,7 @@ endif::doctype-manpage[]
* If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses unnormalized coordinates, it mustnot: be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions that includes a lod bias or any offset values, in any shader stage
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a uniform buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a storage buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
-* Any sname:VkImage being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties
+* Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkCmdDispatchIndirect.txt b/doc/specs/vulkan/validity/protos/vkCmdDispatchIndirect.txt
index 9af07848..15f3975a 100644
--- a/doc/specs/vulkan/validity/protos/vkCmdDispatchIndirect.txt
+++ b/doc/specs/vulkan/validity/protos/vkCmdDispatchIndirect.txt
@@ -25,7 +25,7 @@ endif::doctype-manpage[]
* If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE uses unnormalized coordinates, it mustnot: be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions that includes a lod bias or any offset values, in any shader stage
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a uniform buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE accesses a storage buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
-* Any sname:VkImage being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties
+* Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkCmdDraw.txt b/doc/specs/vulkan/validity/protos/vkCmdDraw.txt
index b0e12e44..4a8848b6 100644
--- a/doc/specs/vulkan/validity/protos/vkCmdDraw.txt
+++ b/doc/specs/vulkan/validity/protos/vkCmdDraw.txt
@@ -24,7 +24,7 @@ endif::doctype-manpage[]
* If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS uses unnormalized coordinates, it mustnot: be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions that includes a lod bias or any offset values, in any shader stage
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS accesses a uniform buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS accesses a storage buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
-* Any sname:VkImage being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties
+* Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkCmdDrawIndexed.txt b/doc/specs/vulkan/validity/protos/vkCmdDrawIndexed.txt
index 94aa5840..60071f8f 100644
--- a/doc/specs/vulkan/validity/protos/vkCmdDrawIndexed.txt
+++ b/doc/specs/vulkan/validity/protos/vkCmdDrawIndexed.txt
@@ -25,7 +25,7 @@ endif::doctype-manpage[]
* If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS uses unnormalized coordinates, it mustnot: be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions that includes a lod bias or any offset values, in any shader stage
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS accesses a uniform buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS accesses a storage buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
-* Any sname:VkImage being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties
+* Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkCmdDrawIndexedIndirect.txt b/doc/specs/vulkan/validity/protos/vkCmdDrawIndexedIndirect.txt
index 54d65d2d..1efbd99d 100644
--- a/doc/specs/vulkan/validity/protos/vkCmdDrawIndexedIndirect.txt
+++ b/doc/specs/vulkan/validity/protos/vkCmdDrawIndexedIndirect.txt
@@ -32,7 +32,7 @@ endif::doctype-manpage[]
* If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS uses unnormalized coordinates, it mustnot: be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions that includes a lod bias or any offset values, in any shader stage
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS accesses a uniform buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS accesses a storage buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
-* Any sname:VkImage being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties
+* Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkCmdDrawIndirect.txt b/doc/specs/vulkan/validity/protos/vkCmdDrawIndirect.txt
index 52ee2b89..a41ad304 100644
--- a/doc/specs/vulkan/validity/protos/vkCmdDrawIndirect.txt
+++ b/doc/specs/vulkan/validity/protos/vkCmdDrawIndirect.txt
@@ -32,7 +32,7 @@ endif::doctype-manpage[]
* If any sname:VkSampler object that is accessed from a shader by the sname:VkPipeline currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS uses unnormalized coordinates, it mustnot: be used with any of the SPIR-V `OpImageSample*` or `OpImageSparseSample*` instructions that includes a lod bias or any offset values, in any shader stage
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS accesses a uniform buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
* If the <> feature is not enabled, and any shader stage in the sname:VkPipeline object currently bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS accesses a storage buffer, it mustnot: access values outside of the range of that buffer specified in the currently bound descriptor set
-* Any sname:VkImage being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures returned by fname:vkGetPhysicalDeviceFormatProperties
+* Any sname:VkImageView being sampled with ename:VK_FILTER_LINEAR as a result of this command must: be of a format which supports linear filtering, as specified by the ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT flag in sname:VkFormatProperties::pname:linearTilingFeatures (for a linear image) or sname:VkFormatProperties::pname:optimalTilingFeatures(for an optimally tiled image) returned by fname:vkGetPhysicalDeviceFormatProperties
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkCmdResetEvent.txt b/doc/specs/vulkan/validity/protos/vkCmdResetEvent.txt
index 948aad98..711bf340 100644
--- a/doc/specs/vulkan/validity/protos/vkCmdResetEvent.txt
+++ b/doc/specs/vulkan/validity/protos/vkCmdResetEvent.txt
@@ -17,6 +17,7 @@ endif::doctype-manpage[]
* Each of pname:commandBuffer and pname:event must: have been created, allocated or retrieved from the same sname:VkDevice
* If the <> feature is not enabled, pname:stageMask mustnot: contain ename:VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT
* If the <> feature is not enabled, pname:stageMask mustnot: contain ename:VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or ename:VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT
+* When this command executes, pname:event mustnot: be waited on by a fname:vkCmdWaitEvents command that is currently executing
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkEnumerateDeviceExtensionProperties.txt b/doc/specs/vulkan/validity/protos/vkEnumerateDeviceExtensionProperties.txt
index f3ad2c1b..edb44cbc 100644
--- a/doc/specs/vulkan/validity/protos/vkEnumerateDeviceExtensionProperties.txt
+++ b/doc/specs/vulkan/validity/protos/vkEnumerateDeviceExtensionProperties.txt
@@ -11,7 +11,7 @@ endif::doctype-manpage[]
* If pname:pLayerName is not `NULL`, pname:pLayerName must: be a null-terminated string
* pname:pPropertyCount must: be a pointer to a basetype:uint32_t value
* If the value referenced by pname:pPropertyCount is not `0`, and pname:pProperties is not `NULL`, pname:pProperties must: be a pointer to an array of pname:pPropertyCount sname:VkExtensionProperties structures
-* If pname:pLayerName is not `NULL`, it must: be the name of a device layer returned by flink:vkEnumerateDeviceLayerProperties
+* If pname:pLayerName is not `NULL`, it must: be the name of a layer returned by flink:vkEnumerateDeviceLayerProperties
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkEnumerateInstanceExtensionProperties.txt b/doc/specs/vulkan/validity/protos/vkEnumerateInstanceExtensionProperties.txt
index 7a202b76..0b21ed71 100644
--- a/doc/specs/vulkan/validity/protos/vkEnumerateInstanceExtensionProperties.txt
+++ b/doc/specs/vulkan/validity/protos/vkEnumerateInstanceExtensionProperties.txt
@@ -10,7 +10,7 @@ endif::doctype-manpage[]
* If pname:pLayerName is not `NULL`, pname:pLayerName must: be a null-terminated string
* pname:pPropertyCount must: be a pointer to a basetype:uint32_t value
* If the value referenced by pname:pPropertyCount is not `0`, and pname:pProperties is not `NULL`, pname:pProperties must: be a pointer to an array of pname:pPropertyCount sname:VkExtensionProperties structures
-* If pname:pLayerName is not `NULL`, it must: be the name of an instance layer returned by flink:vkEnumerateInstanceLayerProperties
+* If pname:pLayerName is not `NULL`, it must: be the name of a layer returned by flink:vkEnumerateInstanceLayerProperties
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkQueueBindSparse.txt b/doc/specs/vulkan/validity/protos/vkQueueBindSparse.txt
index 6f820ecf..44672ff3 100644
--- a/doc/specs/vulkan/validity/protos/vkQueueBindSparse.txt
+++ b/doc/specs/vulkan/validity/protos/vkQueueBindSparse.txt
@@ -12,7 +12,7 @@ endif::doctype-manpage[]
* If pname:fence is not sname:VK_NULL_HANDLE, pname:fence must: be a valid sname:VkFence handle
* The pname:queue must: support sparse binding operations
* Each of pname:queue and pname:fence that are valid handles must: have been created, allocated or retrieved from the same sname:VkDevice
-* pname:fence must: be unsignalled
+* pname:fence must: be unsignaled
* pname:fence mustnot: be associated with any other queue command that has not yet completed execution on that queue
ifndef::doctype-manpage[]
********************************************************************************
diff --git a/doc/specs/vulkan/validity/protos/vkQueueSubmit.txt b/doc/specs/vulkan/validity/protos/vkQueueSubmit.txt
index cae39038..d29228fb 100644
--- a/doc/specs/vulkan/validity/protos/vkQueueSubmit.txt
+++ b/doc/specs/vulkan/validity/protos/vkQueueSubmit.txt
@@ -11,8 +11,8 @@ endif::doctype-manpage[]
* If pname:submitCount is not `0`, pname:pSubmits must: be a pointer to an array of pname:submitCount valid sname:VkSubmitInfo structures
* If pname:fence is not sname:VK_NULL_HANDLE, pname:fence must: be a valid sname:VkFence handle
* Each of pname:queue and pname:fence that are valid handles must: have been created, allocated or retrieved from the same sname:VkDevice
-* pname:fence must: be unsignalled
-* pname:fence mustnot: be associated with any other queue command that has not yet completed execution on that queue
+* If pname:fence is not sname:VK_NULL_HANDLE, pname:fence must: be unsignaled
+* If pname:fence is not sname:VK_NULL_HANDLE, pname:fence mustnot: be associated with any other queue command that has not yet completed execution on that queue
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/protos/vkResetEvent.txt b/doc/specs/vulkan/validity/protos/vkResetEvent.txt
index 856449b4..0a1bda1d 100644
--- a/doc/specs/vulkan/validity/protos/vkResetEvent.txt
+++ b/doc/specs/vulkan/validity/protos/vkResetEvent.txt
@@ -11,6 +11,7 @@ endif::doctype-manpage[]
* pname:event must: be a valid sname:VkEvent handle
* pname:event must: have been created, allocated or retrieved from pname:device
* Each of pname:device and pname:event must: have been created, allocated or retrieved from the same sname:VkPhysicalDevice
+* pname:event mustnot: be waited on by a fname:vkCmdWaitEvents command that is currently executing
ifndef::doctype-manpage[]
********************************************************************************
endif::doctype-manpage[]
diff --git a/doc/specs/vulkan/validity/structs/VkBufferImageCopy.txt b/doc/specs/vulkan/validity/structs/VkBufferImageCopy.txt
index 3a8df78b..bdfb59e4 100644
--- a/doc/specs/vulkan/validity/structs/VkBufferImageCopy.txt
+++ b/doc/specs/vulkan/validity/structs/VkBufferImageCopy.txt
@@ -16,13 +16,13 @@ endif::doctype-manpage[]
* pname:imageOffset.y and (imageExtent.height + pname:imageOffset.y) must: both be greater than or equal to `0` and less than or equal to the image subresource height
* pname:imageOffset.z and (imageExtent.depth + pname:imageOffset.z) must: both be greater than or equal to `0` and less than or equal to the image subresource depth
* If the calling command's sname:VkImage parameter is a compressed format image:
-* pname:bufferRowLength must: be a multiple of the compressed texel block width
-* pname:bufferImageHeight must: be a multiple of the compressed texel block height
-* all members of pname:imageOffset must: be a multiple of the corresponding dimensions of the compressed texel block
-* pname:bufferOffset must: be a multiple of the compressed texel block size in bytes
-* pname:imageExtent.width must: be a multiple of the compressed texel block width or (pname:imageExtent.width + pname:imageOffset.x) must: equal the image subresource width
-* pname:imageExtent.height must: be a multiple of the compressed texel block height or (pname:imageExtent.height + pname:imageOffset.y) must: equal the image subresource height
-* pname:imageExtent.depth must: be a multiple of the compressed texel block depth or (pname:imageExtent.depth + pname:imageOffset.z) must: equal the image subresource depth
+ ** pname:bufferRowLength must: be a multiple of the compressed texel block width
+ ** pname:bufferImageHeight must: be a multiple of the compressed texel block height
+ ** all members of pname:imageOffset must: be a multiple of the corresponding dimensions of the compressed texel block
+ ** pname:bufferOffset must: be a multiple of the compressed texel block size in bytes
+ ** pname:imageExtent.width must: be a multiple of the compressed texel block width or (pname:imageExtent.width + pname:imageOffset.x) must: equal the image subresource width
+ ** pname:imageExtent.height must: be a multiple of the compressed texel block height or (pname:imageExtent.height + pname:imageOffset.y) must: equal the image subresource height
+ ** pname:imageExtent.depth must: be a multiple of the compressed texel block depth or (pname:imageExtent.depth + pname:imageOffset.z) must: equal the image subresource depth
* pname:bufferOffset, pname:bufferRowLength, pname:bufferImageHeight and all members of pname:imageOffset and pname:imageExtent must: respect the image transfer granularity requirements of the queue family that it will be submitted against, as described in <>
* The pname:aspectMask member of pname:imageSubresource must: specify aspects present in the calling command's sname:VkImage parameter
* The pname:aspectMask member of pname:imageSubresource must: only have a single bit set
diff --git a/doc/specs/vulkan/validity/structs/VkBufferViewCreateInfo.txt b/doc/specs/vulkan/validity/structs/VkBufferViewCreateInfo.txt
index 9d9efb1d..adae18c6 100644
--- a/doc/specs/vulkan/validity/structs/VkBufferViewCreateInfo.txt
+++ b/doc/specs/vulkan/validity/structs/VkBufferViewCreateInfo.txt
@@ -15,10 +15,10 @@ endif::doctype-manpage[]
* pname:offset must: be less than the size of pname:buffer
* pname:offset must: be a multiple of sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment
* If pname:range is not equal to ename:VK_WHOLE_SIZE:
-* pname:range must: be greater than `0`
-* pname:range must: be a multiple of the element size of pname:format
-* pname:range divided by the size of an element of pname:format, must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxTexelBufferElements
-* the sum of pname:offset and pname:range must: be less than or equal to the size of pname:buffer
+ ** pname:range must: be greater than `0`
+ ** pname:range must: be a multiple of the element size of pname:format
+ ** pname:range divided by the size of an element of pname:format, must: be less than or equal to sname:VkPhysicalDeviceLimits::pname:maxTexelBufferElements
+ ** the sum of pname:offset and pname:range must: be less than or equal to the size of pname:buffer
* pname:buffer must: have been created with a pname:usage value containing at least one of ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT or ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT
* If pname:buffer was created with pname:usage containing ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, pname:format must: be supported for uniform texel buffers, as specified by the ename:VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT flag in sname:VkFormatProperties::pname:bufferFeatures returned by fname:vkGetPhysicalDeviceFormatProperties
* If pname:buffer was created with pname:usage containing ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:format must: be supported for storage texel buffers, as specified by the ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT flag in sname:VkFormatProperties::pname:bufferFeatures returned by fname:vkGetPhysicalDeviceFormatProperties
diff --git a/doc/specs/vulkan/validity/structs/VkDeviceCreateInfo.txt b/doc/specs/vulkan/validity/structs/VkDeviceCreateInfo.txt
index 2578a59b..e2e546a3 100644
--- a/doc/specs/vulkan/validity/structs/VkDeviceCreateInfo.txt
+++ b/doc/specs/vulkan/validity/structs/VkDeviceCreateInfo.txt
@@ -15,7 +15,7 @@ endif::doctype-manpage[]
* If pname:enabledExtensionCount is not `0`, pname:ppEnabledExtensionNames must: be a pointer to an array of pname:enabledExtensionCount null-terminated strings
* If pname:pEnabledFeatures is not `NULL`, pname:pEnabledFeatures must: be a pointer to a valid sname:VkPhysicalDeviceFeatures structure
* pname:queueCreateInfoCount must: be greater than `0`
-* Any given element of pname:ppEnabledLayerNames must: be the name of a layer present on the system, exactly matching a string returned in the sname:VkLayerProperties structure by fname:vkEnumerateDeviceLayerProperties
+* pname:ppEnabledLayerNames must: either be sname:NULL or contain the same sequence of layer names that was enabled when creating the parent instance
* Any given element of pname:ppEnabledExtensionNames must: be the name of an extension present on the system, exactly matching a string returned in the sname:VkExtensionProperties structure by fname:vkEnumerateDeviceExtensionProperties
* If an extension listed in pname:ppEnabledExtensionNames is provided as part of a layer, then both the layer and extension must: be enabled to enable that extension
* The pname:queueFamilyIndex member of any given element of pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos
diff --git a/doc/specs/vulkan/validity/structs/VkImageCopy.txt b/doc/specs/vulkan/validity/structs/VkImageCopy.txt
index 0254a1d7..fca2cdf4 100644
--- a/doc/specs/vulkan/validity/structs/VkImageCopy.txt
+++ b/doc/specs/vulkan/validity/structs/VkImageCopy.txt
@@ -21,15 +21,15 @@ endif::doctype-manpage[]
* pname:dstOffset.y and (pname:extent.height + pname:dstOffset.y) must: both be greater than or equal to `0` and less than or equal to the destination image subresource height
* pname:dstOffset.z and (pname:extent.depth + pname:dstOffset.z) must: both be greater than or equal to `0` and less than or equal to the destination image subresource depth
* If the calling command's pname:srcImage is a compressed format image:
-* all members of pname:srcOffset must: be a multiple of the corresponding dimensions of the compressed texel block
-* pname:extent.width must: be a multiple of the compressed texel block width or (pname:extent.width + pname:srcOffset.x) must: equal the source image subresource width
-* pname:extent.height must: be a multiple of the compressed texel block height or (pname:extent.height + pname:srcOffset.y) must: equal the source image subresource height
-* pname:extent.depth must: be a multiple of the compressed texel block depth or (pname:extent.depth + pname:srcOffset.z) must: equal the source image subresource depth
+ ** all members of pname:srcOffset must: be a multiple of the corresponding dimensions of the compressed texel block
+ ** pname:extent.width must: be a multiple of the compressed texel block width or (pname:extent.width + pname:srcOffset.x) must: equal the source image subresource width
+ ** pname:extent.height must: be a multiple of the compressed texel block height or (pname:extent.height + pname:srcOffset.y) must: equal the source image subresource height
+ ** pname:extent.depth must: be a multiple of the compressed texel block depth or (pname:extent.depth + pname:srcOffset.z) must: equal the source image subresource depth
* If the calling command's pname:dstImage is a compressed format image:
-* all members of pname:dstOffset must: be a multiple of the corresponding dimensions of the compressed texel block
-* pname:extent.width must: be a multiple of the compressed texel block width or (pname:extent.width + pname:dstOffset.x) must: equal the destination image subresource width
-* pname:extent.height must: be a multiple of the compressed texel block height or (pname:extent.height + pname:dstOffset.y) must: equal the destination image subresource height
-* pname:extent.depth must: be a multiple of the compressed texel block depth or (pname:extent.depth + pname:dstOffset.z) must: equal the destination image subresource depth
+ ** all members of pname:dstOffset must: be a multiple of the corresponding dimensions of the compressed texel block
+ ** pname:extent.width must: be a multiple of the compressed texel block width or (pname:extent.width + pname:dstOffset.x) must: equal the destination image subresource width
+ ** pname:extent.height must: be a multiple of the compressed texel block height or (pname:extent.height + pname:dstOffset.y) must: equal the destination image subresource height
+ ** pname:extent.depth must: be a multiple of the compressed texel block depth or (pname:extent.depth + pname:dstOffset.z) must: equal the destination image subresource depth
* pname:srcOffset, pname:dstOffset, and pname:extent must: respect the image transfer granularity requirements of the queue family that it will be submitted against, as described in <>
ifndef::doctype-manpage[]
********************************************************************************
diff --git a/doc/specs/vulkan/validity/structs/VkSubmitInfo.txt b/doc/specs/vulkan/validity/structs/VkSubmitInfo.txt
index 4a644444..39a81fa2 100644
--- a/doc/specs/vulkan/validity/structs/VkSubmitInfo.txt
+++ b/doc/specs/vulkan/validity/structs/VkSubmitInfo.txt
@@ -15,7 +15,7 @@ endif::doctype-manpage[]
* If pname:commandBufferCount is not `0`, pname:pCommandBuffers must: be a pointer to an array of pname:commandBufferCount valid sname:VkCommandBuffer handles
* If pname:signalSemaphoreCount is not `0`, pname:pSignalSemaphores must: be a pointer to an array of pname:signalSemaphoreCount valid sname:VkSemaphore handles
* Each of the elements of pname:pWaitSemaphores, the elements of pname:pCommandBuffers and the elements of pname:pSignalSemaphores that are valid handles must: have been created, allocated or retrieved from the same sname:VkDevice
-* Any given element of pname:pSignalSemaphores must: currently be unsignalled
+* Any given element of pname:pSignalSemaphores must: currently be unsignaled
* Any given element of pname:pCommandBuffers must: either have been recorded with the ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, or not currently be executing on the device
* Any given element of pname:pCommandBuffers must: be in the executable state
* If any given element of pname:pCommandBuffers contains commands that execute secondary command buffers, those secondary command buffers must: have been recorded with the ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, or not currently be executing on the device
diff --git a/doc/specs/vulkan/vkapi.py b/doc/specs/vulkan/vkapi.py
index 4b29f962..bb5800a9 100644
--- a/doc/specs/vulkan/vkapi.py
+++ b/doc/specs/vulkan/vkapi.py
@@ -113,7 +113,11 @@ consts['VK_STRUCTURE_TYPE_MIR_SURFACE_CREATE_INFO_KHR'] = 'VkStructureType'
consts['VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR'] = 'VkStructureType'
consts['VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR'] = 'VkStructureType'
consts['VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT'] = 'VkStructureType'
-enums['VkStructureType'] = ['VK_STRUCTURE_TYPE_APPLICATION_INFO', 'VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO', 'VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO', 'VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO', 'VK_STRUCTURE_TYPE_SUBMIT_INFO', 'VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO', 'VK_STRUCTURE_TYPE_MAPPED_MEMORY_RANGE', 'VK_STRUCTURE_TYPE_BIND_SPARSE_INFO', 'VK_STRUCTURE_TYPE_FENCE_CREATE_INFO', 'VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO', 'VK_STRUCTURE_TYPE_EVENT_CREATE_INFO', 'VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO', 'VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO', 'VK_STRUCTURE_TYPE_BUFFER_VIEW_CREATE_INFO', 'VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO', 'VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO', 'VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_CACHE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_INPUT_ASSEMBLY_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_DEPTH_STENCIL_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO', 'VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO', 'VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO', 'VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO', 'VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_CREATE_INFO', 'VK_STRUCTURE_TYPE_DESCRIPTOR_SET_ALLOCATE_INFO', 'VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET', 'VK_STRUCTURE_TYPE_COPY_DESCRIPTOR_SET', 'VK_STRUCTURE_TYPE_FRAMEBUFFER_CREATE_INFO', 'VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO', 'VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO', 'VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO', 'VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_INFO', 'VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO', 'VK_STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO', 'VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER', 'VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER', 'VK_STRUCTURE_TYPE_MEMORY_BARRIER', 'VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO', 'VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO', 'VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_PRESENT_INFO_KHR', 'VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR', 'VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_XCB_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_MIR_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT']
+consts['VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_RASTERIZATION_ORDER_AMD'] = 'VkStructureType'
+consts['VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT'] = 'VkStructureType'
+consts['VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT'] = 'VkStructureType'
+consts['VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT'] = 'VkStructureType'
+enums['VkStructureType'] = ['VK_STRUCTURE_TYPE_APPLICATION_INFO', 'VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO', 'VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO', 'VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO', 'VK_STRUCTURE_TYPE_SUBMIT_INFO', 'VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO', 'VK_STRUCTURE_TYPE_MAPPED_MEMORY_RANGE', 'VK_STRUCTURE_TYPE_BIND_SPARSE_INFO', 'VK_STRUCTURE_TYPE_FENCE_CREATE_INFO', 'VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO', 'VK_STRUCTURE_TYPE_EVENT_CREATE_INFO', 'VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO', 'VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO', 'VK_STRUCTURE_TYPE_BUFFER_VIEW_CREATE_INFO', 'VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO', 'VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO', 'VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_CACHE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_INPUT_ASSEMBLY_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_TESSELLATION_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_DEPTH_STENCIL_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO', 'VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO', 'VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO', 'VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO', 'VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO', 'VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO', 'VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_CREATE_INFO', 'VK_STRUCTURE_TYPE_DESCRIPTOR_SET_ALLOCATE_INFO', 'VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET', 'VK_STRUCTURE_TYPE_COPY_DESCRIPTOR_SET', 'VK_STRUCTURE_TYPE_FRAMEBUFFER_CREATE_INFO', 'VK_STRUCTURE_TYPE_RENDER_PASS_CREATE_INFO', 'VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO', 'VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO', 'VK_STRUCTURE_TYPE_COMMAND_BUFFER_INHERITANCE_INFO', 'VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO', 'VK_STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO', 'VK_STRUCTURE_TYPE_BUFFER_MEMORY_BARRIER', 'VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER', 'VK_STRUCTURE_TYPE_MEMORY_BARRIER', 'VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO', 'VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO', 'VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_PRESENT_INFO_KHR', 'VK_STRUCTURE_TYPE_DISPLAY_MODE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR', 'VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_XCB_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_WAYLAND_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_MIR_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_ANDROID_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR', 'VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT', 'VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_RASTERIZATION_ORDER_AMD', 'VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_NAME_INFO_EXT', 'VK_STRUCTURE_TYPE_DEBUG_MARKER_OBJECT_TAG_INFO_EXT', 'VK_STRUCTURE_TYPE_DEBUG_MARKER_MARKER_INFO_EXT']
# Unprocessed type: void
# Unprocessed type: uint32_t
# Unprocessed type: VkFlags category: basetype
@@ -988,7 +992,7 @@ protos['vkCmdCopyBuffer'] = ['commandBuffer', 'srcBuffer', 'dstBuffer', 'region
structs['VkImageSubresourceLayers'] = ['aspectMask', 'mipLevel', 'baseArrayLayer', 'layerCount']
structs['VkImageCopy'] = ['srcSubresource', 'srcOffset', 'dstSubresource', 'dstOffset', 'extent']
protos['vkCmdCopyImage'] = ['commandBuffer', 'srcImage', 'srcImageLayout', 'dstImage', 'dstImageLayout', 'regionCount', 'pRegions']
-structs['VkImageBlit'] = ['srcSubresource', 'srcOffsets[2]', 'dstSubresource', 'dstOffsets[2]']
+structs['VkImageBlit'] = ['srcSubresource', 'srcOffsets', 'dstSubresource', 'dstOffsets']
protos['vkCmdBlitImage'] = ['commandBuffer', 'srcImage', 'srcImageLayout', 'dstImage', 'dstImageLayout', 'regionCount', 'pRegions', 'filter']
structs['VkBufferImageCopy'] = ['bufferOffset', 'bufferRowLength', 'bufferImageHeight', 'imageSubresource', 'imageOffset', 'imageExtent']
protos['vkCmdCopyBufferToImage'] = ['commandBuffer', 'srcBuffer', 'dstImage', 'dstImageLayout', 'regionCount', 'pRegions']
diff --git a/doc/specs/vulkan/vkspec.txt b/doc/specs/vulkan/vkspec.txt
index 70d7dbc8..f4de8be6 100644
--- a/doc/specs/vulkan/vkspec.txt
+++ b/doc/specs/vulkan/vkspec.txt
@@ -3,7 +3,7 @@
include::specversion.txt[]
-= {apiname} {apirevision} - A Specification
+= Vulkan {apirevision} - A Specification
The Khronos Vulkan Working Group
:icons:
:toc2:
diff --git a/out/index.html b/out/index.html
index cfc7ba88..8c155c73 100644
--- a/out/index.html
+++ b/out/index.html
@@ -9,9 +9,11 @@
related documents. It is updated by hand periodically by Jon Leech.
- - The Vulkan Style Guide is a work
- in progress (but significantly complete) document, useful when
- writing and modifying Specification and reference page language.
+
- The Vulkan Style Guide is a work in
+ progress (but significantly complete) document, useful when writing
+ and modifying Specification and reference page language.
+ - The XML Registry README describes the
+ schema and some use cases for vk.xml.
- Core API Specifications
- The following targets are for internal use only and are probably
- not included in, or if included, not up to date in the sandbox
-
+ not included in, or if included, not up to date in the sandbox
+
diff --git a/src/spec/Makefile b/src/spec/Makefile
index b8f15fe4..8c999d14 100644
--- a/src/spec/Makefile
+++ b/src/spec/Makefile
@@ -19,6 +19,7 @@ PYTHON ?= python3
PYFILES = genheaders.py reg.py
GENOPTS =
GENHEADERS = genheaders.py $(GENOPTS)
+OUTDIR = ../../out/1.0
# Generate all outputs for Vulkan, including headers and (soon) Asciidoc
# frameworks. Targets:
@@ -39,7 +40,7 @@ DOCROOT = ../../doc/specs/vulkan
DOCPYSRC = $(DOCROOT)/vkapi.py
DOCVALIDITY = validity
DOCHOSTSYNCTABLE = hostsynctable
-XMLDOC = readme.pdf
+XMLDOC = $(OUTDIR)/readme.pdf
# Could add $(XMLDOC) to default, but that requires a LaTeX install.
# Could regenerate vk.json automatically but the generator script isn't
@@ -50,6 +51,8 @@ default install: $(HEADERS)
full_install: default $(DOCINCLUDES) $(DOCPYSRC) $(DOCVALIDITY) $(DOCHOSTSYNCTABLE)
+pdf_install: $(OUTDIR)/readme.pdf
+
################################################
# Python and XML files on which vulkan.h depends
@@ -97,12 +100,13 @@ vk.json: tojson.py vk.xml
################################################
# Documentation targets
-readme.pdf: readme.tex Makefile
+$(OUTDIR)/readme.pdf: readme.tex Makefile
touch readme.ind
pdflatex readme.tex
pdflatex readme.tex
makeindex readme.idx
pdflatex readme.tex
+ mv readme.pdf $@
################################################
@@ -128,6 +132,7 @@ clean:
# (installed header & asciidoc includes)
clobber: clean
-rm -f $(HEADERS) $(DOCINCLUDES)
+ -rm -f $(OUTDIR)/readme.pdf
-rm -f $(DOCROOT)/vkapi.py
-rm -f $(DOCROOT)/structs/*.txt $(DOCROOT)/protos/*.txt
-rm -f $(DOCROOT)/enums/*.txt $(DOCROOT)/flags/*.txt
diff --git a/src/spec/generator.py b/src/spec/generator.py
index 00a274be..c9b09b0a 100644
--- a/src/spec/generator.py
+++ b/src/spec/generator.py
@@ -1745,11 +1745,14 @@ class ValidityOutputGenerator(OutputGenerator):
asciidoc += self.makeParameterName(paramname.text)
validextensionstructs = param.attrib.get('validextensionstructs')
- if validextensionstructs is None:
- asciidoc += ' must: be `NULL`'
- else:
- extensionstructs = validextensionstructs.split(',')
- asciidoc += ' must: point to one of ' + extensionstructs[:-1].join(', ') + ' or ' + extensionstructs[-1] + 'if the extension that introduced them is enabled '
+ asciidoc += ' must: be `NULL`'
+ if validextensionstructs is not None:
+ extensionstructs = ['slink:' + x for x in validextensionstructs.split(',')]
+ asciidoc += ', or a pointer to a valid instance of '
+ if len(extensionstructs) == 1:
+ asciidoc += validextensionstructs
+ else:
+ asciidoc += (', ').join(extensionstructs[:-1]) + ' or ' + extensionstructs[-1]
asciidoc += '\n'
diff --git a/src/spec/readme.pdf b/src/spec/readme.pdf
deleted file mode 100644
index 1353273e..00000000
--- a/src/spec/readme.pdf
+++ /dev/null
@@ -1,4593 +0,0 @@
-%PDF-1.5
-%ÐÔÅØ
-1 0 obj
-<< /S /GoTo /D (section.1) >>
-endobj
-4 0 obj
-(1 Introduction)
-endobj
-5 0 obj
-<< /S /GoTo /D (subsection.1.1) >>
-endobj
-8 0 obj
-(1.1 Schema Choices)
-endobj
-9 0 obj
-<< /S /GoTo /D (section.2) >>
-endobj
-12 0 obj
-(2 Getting Started)
-endobj
-13 0 obj
-<< /S /GoTo /D (subsection.2.1) >>
-endobj
-16 0 obj
-(2.1 Header Generation Script - genvk.py)
-endobj
-17 0 obj
-<< /S /GoTo /D (subsection.2.2) >>
-endobj
-20 0 obj
-(2.2 Registry Processing Script - reg.py)
-endobj
-21 0 obj
-<< /S /GoTo /D (subsection.2.3) >>
-endobj
-24 0 obj
-(2.3 Output Generator Script - generator.py)
-endobj
-25 0 obj
-<< /S /GoTo /D (section.3) >>
-endobj
-28 0 obj
-(3 Vulkan Registry Schema)
-endobj
-29 0 obj
-<< /S /GoTo /D (subsection.3.1) >>
-endobj
-32 0 obj
-(3.1 Profiles)
-endobj
-33 0 obj
-<< /S /GoTo /D (subsection.3.2) >>
-endobj
-36 0 obj
-(3.2 API Names)
-endobj
-37 0 obj
-<< /S /GoTo /D (section.4) >>
-endobj
-40 0 obj
-(4 Registry Root \( tag\))
-endobj
-41 0 obj
-<< /S /GoTo /D (subsection.4.1) >>
-endobj
-44 0 obj
-(4.1 Attributes of tags)
-endobj
-45 0 obj
-<< /S /GoTo /D (subsection.4.2) >>
-endobj
-48 0 obj
-(4.2 Contents of tags)
-endobj
-49 0 obj
-<< /S /GoTo /D (section.5) >>
-endobj
-52 0 obj
-(5 Vendor IDs \( tag\))
-endobj
-53 0 obj
-<< /S /GoTo /D (subsection.5.1) >>
-endobj
-56 0 obj
-(5.1 Attributes of tags)
-endobj
-57 0 obj
-<< /S /GoTo /D (section.6) >>
-endobj
-60 0 obj
-(6 Author Prefixes \( tag\))
-endobj
-61 0 obj
-<< /S /GoTo /D (subsection.6.1) >>
-endobj
-64 0 obj
-(6.1 Attributes of tags)
-endobj
-65 0 obj
-<< /S /GoTo /D (section.7) >>
-endobj
-68 0 obj
-(7 API types \( tag\))
-endobj
-69 0 obj
-<< /S /GoTo /D (subsection.7.1) >>
-endobj
-72 0 obj
-(7.1 Attributes of tags)
-endobj
-73 0 obj
-<< /S /GoTo /D (subsection.7.2) >>
-endobj
-76 0 obj
-(7.2 Contents of tags)
-endobj
-77 0 obj
-<< /S /GoTo /D (subsubsection.7.2.1) >>
-endobj
-80 0 obj
-(7.2.1 Enumerated types - category "enum")
-endobj
-81 0 obj
-<< /S /GoTo /D (subsubsection.7.2.2) >>
-endobj
-84 0 obj
-(7.2.2 Structure types - category "struct" or "union")
-endobj
-85 0 obj
-<< /S /GoTo /D (section*.2) >>
-endobj
-88 0 obj
-(Structure member \(\) tags)
-endobj
-89 0 obj
-<< /S /GoTo /D (section*.3) >>
-endobj
-92 0 obj
-(Attributes of tags)
-endobj
-93 0 obj
-<< /S /GoTo /D (section*.4) >>
-endobj
-96 0 obj
-(Contents of tags)
-endobj
-97 0 obj
-<< /S /GoTo /D (section*.5) >>
-endobj
-100 0 obj
-(Validation \(\) tags)
-endobj
-101 0 obj
-<< /S /GoTo /D (section*.6) >>
-endobj
-104 0 obj
-(Contents of tags)
-endobj
-105 0 obj
-<< /S /GoTo /D (subsubsection.7.2.3) >>
-endobj
-108 0 obj
-(7.2.3 All other types)
-endobj
-109 0 obj
-<< /S /GoTo /D (subsection.7.3) >>
-endobj
-112 0 obj
-(7.3 Example of a tag)
-endobj
-113 0 obj
-<< /S /GoTo /D (section.8) >>
-endobj
-116 0 obj
-(8 Enumerant Blocks \( tag\))
-endobj
-117 0 obj
-<< /S /GoTo /D (subsection.8.1) >>
-endobj
-120 0 obj
-(8.1 Attributes of tags)
-endobj
-121 0 obj
-<< /S /GoTo /D (subsection.8.2) >>
-endobj
-124 0 obj
-(8.2 Contents of tags)
-endobj
-125 0 obj
-<< /S /GoTo /D (subsection.8.3) >>
-endobj
-128 0 obj
-(8.3 Example of tags)
-endobj
-129 0 obj
-<< /S /GoTo /D (section.9) >>
-endobj
-132 0 obj
-(9 Enumerants \( tag\))
-endobj
-133 0 obj
-<< /S /GoTo /D (subsection.9.1) >>
-endobj
-136 0 obj
-(9.1 Attributes of tags)
-endobj
-137 0 obj
-<< /S /GoTo /D (subsection.9.2) >>
-endobj
-140 0 obj
-(9.2 Contents of tags)
-endobj
-141 0 obj
-<< /S /GoTo /D (section.10) >>
-endobj
-144 0 obj
-(10 Unused Enumerants \( tag\))
-endobj
-145 0 obj
-<< /S /GoTo /D (subsection.10.1) >>
-endobj
-148 0 obj
-(10.1 Attributes of tags)
-endobj
-149 0 obj
-<< /S /GoTo /D (subsection.10.2) >>
-endobj
-152 0 obj
-(10.2 Contents of tags)
-endobj
-153 0 obj
-<< /S /GoTo /D (section.11) >>
-endobj
-156 0 obj
-(11 Command Blocks \( tag\))
-endobj
-157 0 obj
-<< /S /GoTo /D (subsection.11.1) >>
-endobj
-160 0 obj
-(11.1 Attributes of tags)
-endobj
-161 0 obj
-<< /S /GoTo /D (subsection.11.2) >>
-endobj
-164 0 obj
-(11.2 Contents of tags)
-endobj
-165 0 obj
-<< /S /GoTo /D (section.12) >>
-endobj
-168 0 obj
-(12 Commands \( tag\))
-endobj
-169 0 obj
-<< /S /GoTo /D (subsection.12.1) >>
-endobj
-172 0 obj
-(12.1 Attributes of tags)
-endobj
-173 0 obj
-<< /S /GoTo /D (subsection.12.2) >>
-endobj
-176 0 obj
-(12.2 Contents of tags)
-endobj
-177 0 obj
-<< /S /GoTo /D (subsection.12.3) >>
-endobj
-180 0 obj
-(12.3 Command prototype \( tags\))
-endobj
-181 0 obj
-<< /S /GoTo /D (subsubsection.12.3.1) >>
-endobj
-184 0 obj
-(12.3.1 Attributes of tags)
-endobj
-185 0 obj
-<< /S /GoTo /D (subsubsection.12.3.2) >>
-endobj
-188 0 obj
-(12.3.2 Contents of tags)
-endobj
-189 0 obj
-<< /S /GoTo /D (subsection.12.4) >>
-endobj
-192 0 obj
-(12.4 Command parameter \( tags\))
-endobj
-193 0 obj
-<< /S /GoTo /D (subsubsection.12.4.1) >>
-endobj
-196 0 obj
-(12.4.1 Attributes of tags)
-endobj
-197 0 obj
-<< /S /GoTo /D (subsubsection.12.4.2) >>
-endobj
-200 0 obj
-(12.4.2 Contents of tags)
-endobj
-201 0 obj
-<< /S /GoTo /D (subsection.12.5) >>
-endobj
-204 0 obj
-(12.5 Example of a tag)
-endobj
-205 0 obj
-<< /S /GoTo /D (subsection.12.6) >>
-endobj
-208 0 obj
-(12.6 Parameter validation \(\) tags)
-endobj
-209 0 obj
-<< /S /GoTo /D (section*.7) >>
-endobj
-212 0 obj
-(Contents of tags)
-endobj
-213 0 obj
-<< /S /GoTo /D (section.13) >>
-endobj
-216 0 obj
-(13 API Features / Versions \( tag\))
-endobj
-217 0 obj
-<< /S /GoTo /D (subsection.13.1) >>
-endobj
-220 0 obj
-(13.1 Attributes of tags)
-endobj
-221 0 obj
-<< /S /GoTo /D (subsection.13.2) >>
-endobj
-224 0 obj
-(13.2 Contents of tags)
-endobj
-225 0 obj
-<< /S /GoTo /D (subsection.13.3) >>
-endobj
-228 0 obj
-(13.3 Example of a tag)
-endobj
-229 0 obj
-<< /S /GoTo /D (section.14) >>
-endobj
-232 0 obj
-(14 Extension Blocks \( tag\))
-endobj
-233 0 obj
-<< /S /GoTo /D (subsection.14.1) >>
-endobj
-236 0 obj
-(14.1 Attributes of tags)
-endobj
-237 0 obj
-<< /S /GoTo /D (subsection.14.2) >>
-endobj
-240 0 obj
-(14.2 Contents of tags)
-endobj
-241 0 obj
-<< /S /GoTo /D (section.15) >>
-endobj
-244 0 obj
-(15 API Extensions \( tag\))
-endobj
-245 0 obj
-<< /S /GoTo /D (subsection.15.1) >>
-endobj
-248 0 obj
-(15.1 Attributes of tags)
-endobj
-249 0 obj
-<< /S /GoTo /D (subsection.15.2) >>
-endobj
-252 0 obj
-(15.2 Contents of tags)
-endobj
-253 0 obj
-<< /S /GoTo /D (subsection.15.3) >>
-endobj
-256 0 obj
-(15.3 Example of an tag)
-endobj
-257 0 obj
-<< /S /GoTo /D (section.16) >>
-endobj
-260 0 obj
-(16 Required and Removed Interfaces \( and tags\))
-endobj
-261 0 obj
-<< /S /GoTo /D (subsection.16.1) >>
-endobj
-264 0 obj
-(16.1 Attributes of and tags)
-endobj
-265 0 obj
-<< /S /GoTo /D (subsection.16.2) >>
-endobj
-268 0 obj
-(16.2 Contents of and tags)
-endobj
-269 0 obj
-<< /S /GoTo /D (subsection.16.3) >>
-endobj
-272 0 obj
-(16.3 Examples of Extension Enumerants)
-endobj
-273 0 obj
-<< /S /GoTo /D (appendix.A) >>
-endobj
-276 0 obj
-(A Examples / FAQ / How Do I?)
-endobj
-277 0 obj
-<< /S /GoTo /D (subsection.A.1) >>
-endobj
-280 0 obj
-(A.1 General Strategy)
-endobj
-281 0 obj
-<< /S /GoTo /D (subsection.A.2) >>
-endobj
-284 0 obj
-(A.2 API Feature Dependencies)
-endobj
-285 0 obj
-<< /S /GoTo /D (subsubsection.A.2.1) >>
-endobj
-288 0 obj
-(A.2.1 API Feature Walkthrough)
-endobj
-289 0 obj
-<< /S /GoTo /D (subsection.A.3) >>
-endobj
-292 0 obj
-(A.3 How To Add A Compile-Time Constant)
-endobj
-293 0 obj
-<< /S /GoTo /D (subsection.A.4) >>
-endobj
-296 0 obj
-(A.4 How To Add A Struct or Union Type)
-endobj
-297 0 obj
-<< /S /GoTo /D (subsection.A.5) >>
-endobj
-300 0 obj
-(A.5 How To Add An Enumerated Type)
-endobj
-301 0 obj
-<< /S /GoTo /D (subsection.A.6) >>
-endobj
-304 0 obj
-(A.6 How to Add A Command)
-endobj
-305 0 obj
-<< /S /GoTo /D (subsection.A.7) >>
-endobj
-308 0 obj
-(A.7 More Complicated API Representations)
-endobj
-309 0 obj
-<< /S /GoTo /D (subsection.A.8) >>
-endobj
-312 0 obj
-(A.8 More Complicated Output Formats And Other Languages)
-endobj
-313 0 obj
-<< /S /GoTo /D (subsection.A.9) >>
-endobj
-316 0 obj
-(A.9 Additional Semantic Tagging)
-endobj
-317 0 obj
-<< /S /GoTo /D (subsection.A.10) >>
-endobj
-320 0 obj
-(A.10 Stability of the XML Database and Schema)
-endobj
-321 0 obj
-<< /S /GoTo /D (appendix.B) >>
-endobj
-324 0 obj
-(B Change Log)
-endobj
-325 0 obj
-<< /S /GoTo /D [326 0 R /Fit] >>
-endobj
-348 0 obj <<
-/Length 1414
-/Filter /FlateDecode
->>
-stream
-xÚÝXmoÛ6þž_¡20Ñ|)q(d閥Ͷ"õŠí>(c±%C¢Òåßï(R²¬ÈyYÐ̓ßîî¹»‡Gcoéaïôh\ͱG"D ½Å•G±Px‚pÄ$õ™÷Ñ_¬Ô, ûoWUY”µýø0‹¸ß¬¯“Â~¿;³5#Ü_æµ®níÈUYÝÙó×âN䜶ÂCq{Q,‰þ¦tçŸ+•®Ì6/`áÀ:†¨Œìºó¤Öva³Í2ûA1sL甚w ¨#)Dk~HQÄe+ Ü|| †$©>´ö„“:…Lvøå3úY™6UE%÷3U§U~©Ü¤na†ñÌ0º3LZ˜ab3LÕéJm’ïfÃÜOŠÌŽn«2°°†B
Äj7y֊үˑa?ɲ\çe‘¬íL^€7‰²ÉeÙh»¶©óbiGþЩö53'¶Ê!`ðV;‰º´³KU¨
-\Öj‰÷LÀBü›“ª\é[3@ýòÊN€"ÛF×Æh¦éºÉZÌ¢»f¥’LUvèÆtmL6‰k?«õÚNw#µ2oŒ š›Ô·Ûn§oÖ§y^RÝ*˜0ÆrᣩMxš^^ضÅÎt†î6ß»£~½UinNI#Ìl‹«éTêJUªHÝ)Ûd©j48—6{[©E°§flÕhÖ·Ö‰!÷ÿüõÜvz…͇õ_(þ3£•²u™ºŒƒ6H µáÃ>¶Íå:Omÿ4׫æÒ¬*‡¶;»ž‚ô‹óÉ4{×^×{;NmΑ0©
‰)™ãŒ•ÖÛúûù|i ±Òr3…g$öÒ§¶×lçf’Zǯ˴ÞScÌ@#w²ÄˆD“F¯Ê*×àÆ]ŒÙ©´ÜÎökš3îvÞ%ÖÜqñ&É
¿Žõòb·Õm8ÐçLAõV3‚pÏÆ»E†,BÙ¹¬’"]!·ŽÂ=a®‰–µ!•)’hè[ÐÐn8)
DW÷;$œL…Ù >¥ pN 3p1ÆþY¡-ØY“¶n¶Î¬–Ϋ§GÞGÃóÙ]ìd€~lìíÒÙÙŠXÞ·Di!:Y•yjÓšú&e@•o¼â2
Á›¾w8€$Ž1¨óØ©ÒÚ‡ÁT'•á€Ã^ã± ~øT¯ÑÞk¿87ÒNí•‘wÅÁû–—l?p1O†ØÜE<\87×h{Û‡ýn!mdº…_Óø¤Ó ±X"Gc訃î.s¼«Jˆúzç¾(ŠDL¥–Óø…Pš1ù?à÷$ÅA ”o|#s0þÞ{ØU¶âG#Ä1D Ý=b`³ÿÄçà5æ
-J$"ß'æÈbwv—Ù0#&"c2RãäÁzò€xï+šªç—Áô_,ðÇŽIúWÞoɦÅòÅÜš_./¦îÐÐ¥Å~\”¥ãO öD‰¸g‘W•ÛýÃD™%LÕ¶N–p$9œa$Ʊ¸?ÃCb³ýØû;Öž³3
-¯B꾈°ž×ð=d[
¬€s9/"ÉàA#BèÏ.×úú$ ”Üä_#)ù7–pÑ#.F1£ûÇû‹_YwuŸ½®ïÍ9¥U_ѼºiwæY=™s1¢éÏ9NåȦ»9GQûn„vÊuV¼Ø”{d pxp±(ÂÊñÌü™hë]Élž§Ê”«ûC&Ž<'{´
†SáéÏø(ZF?.£ˆŽÊ ñìxݦB…Amɯ6TžFñ¿›ƒ‡€¬„WWßôÿg·ü´8úZèJ
-endstream
-endobj
-326 0 obj <<
-/Type /Page
-/Contents 348 0 R
-/Resources 347 0 R
-/MediaBox [0 0 612 792]
-/Parent 356 0 R
-/Annots [ 327 0 R 328 0 R 329 0 R 330 0 R 331 0 R 332 0 R 333 0 R 334 0 R 335 0 R 336 0 R 337 0 R 338 0 R 339 0 R 340 0 R 341 0 R 342 0 R 343 0 R ]
->> endobj
-327 0 obj <<
-/Type /Annot
-/Border[0 0 0]/H/I/C[0 1 1]
-/Rect [213.338 436.348 397.91 446.343]
-/Subtype/Link/A<>
->> endobj
-328 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 365.207 478.476 374.203]
-/A << /S /GoTo /D (section.1) >>
->> endobj
-329 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 353.252 478.476 362.178]
-/A << /S /GoTo /D (subsection.1.1) >>
->> endobj
-330 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 331.473 478.476 340.33]
-/A << /S /GoTo /D (section.2) >>
->> endobj
-331 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 319.379 478.476 328.305]
-/A << /S /GoTo /D (subsection.2.1) >>
->> endobj
-332 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 307.423 478.476 316.35]
-/A << /S /GoTo /D (subsection.2.2) >>
->> endobj
-333 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 295.468 478.476 304.395]
-/A << /S /GoTo /D (subsection.2.3) >>
->> endobj
-334 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 273.55 478.476 282.547]
-/A << /S /GoTo /D (section.3) >>
->> endobj
-335 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 261.595 478.476 270.522]
-/A << /S /GoTo /D (subsection.3.1) >>
->> endobj
-336 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 249.64 478.476 258.566]
-/A << /S /GoTo /D (subsection.3.2) >>
->> endobj
-337 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 227.722 478.476 236.718]
-/A << /S /GoTo /D (section.4) >>
->> endobj
-338 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 215.767 478.476 224.693]
-/A << /S /GoTo /D (subsection.4.1) >>
->> endobj
-339 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 203.877 478.476 212.599]
-/A << /S /GoTo /D (subsection.4.2) >>
->> endobj
-340 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 182.034 478.476 190.726]
-/A << /S /GoTo /D (section.5) >>
->> endobj
-341 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 170.004 478.476 178.726]
-/A << /S /GoTo /D (subsection.5.1) >>
->> endobj
-342 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 148.161 478.476 156.853]
-/A << /S /GoTo /D (section.6) >>
->> endobj
-343 0 obj <<
-/Type /Annot
-/Subtype /Link
-/Border[0 0 0]/H/I/C[1 0 0]
-/Rect [471.502 136.066 478.476 144.992]
-/A << /S /GoTo /D (subsection.6.1) >>
->> endobj
-349 0 obj <<
-/D [326 0 R /XYZ 132.768 705.06 null]
->> endobj
-350 0 obj <<
-/D [326 0 R /XYZ 133.768 667.198 null]
->> endobj
-354 0 obj <<
-/D [326 0 R /XYZ 133.768 406.542 null]
->> endobj
-347 0 obj <<
-/Font << /F40 351 0 R /F42 352 0 R /F44 353 0 R /F48 355 0 R >>
-/ProcSet [ /PDF /Text ]
->> endobj
-398 0 obj <<
-/Length 1388
-/Filter /FlateDecode
->>
-stream
-xÚåšMoÛF†ïþ