codegen/vulkan/vulkan-docs-next/registry.adoc - platform/hardware/google/gfxstream - Git at Google

 // Copyright 2013-2023 The Khronos Group Inc.
 //
 // SPDX-License-Identifier: CC-BY-4.0

 // Core versions and extensions to enable
 // Must be included before the header and attribs.adoc
 include::{generated}/specattribs.adoc[]

 = The Khronos^®^ Vulkan^®^ API Registry
 Jon Leech
 :data-uri:
 :icons: font
 :toc2:
 :toclevels: 3
 :numbered:
 :source-highlighter: rouge
 :rouge-style: github
 :doctype: book
 :imagewidth: 800
 :fullimagewidth: width="800"
 :attribute-missing: warn
 :cl: &#x3a;

 // Various special / math symbols. This is easier to edit with than Unicode.
 include::{config}/attribs.adoc[]

 :leveloffset: 1

 <<<<

 include::{config}/copyright-ccby.adoc[]

 <<<<

 [[introduction]]
 = Introduction

 This document describes the Khronos Vulkan API Registry schema, and provides
 some additional information about using the registry and scripts to generate
 a variety of outputs, including C header files as well as several types of
 asciidoc include files used in the Vulkan API specification and reference
 pages.
 The underlying XML files and scripts are located on the Khronos public
 GitHub server at URL

 https://github.com/KhronosGroup/Vulkan-Docs

 The authoritative copy of the Registry is maintained in the default branch,
 currently `main`.

 The registry uses an XML representation of the Vulkan API, together with a
 set of Python scripts to manipulate the registry once loaded.
 The scripts rely on the Python `etree` package to parse and operate on XML.
 An XML schema and validator target are included.

 The schema is based on, but not identical to that used for the previously
 published OpenGL, OpenGL ES and EGL API registries.
 It was extended to represent additional types and concepts not needed for
 those APIs, such as structure and enumerant types, as well as additional
 types of registered information specific to Vulkan.

 The Vulkan C header files generated from the registry are checked into a
 separate repository under

 https://github.com/KhronosGroup/Vulkan-Headers/


 == Schema Choices

 The XML schema is not pure XML all the way down.
 In particular, command return types/names and parameters, and structure
 members, are described in mixed-mode tag containing C declarations of the
 appropriate information, with some XML nodes annotating particular parts of
 the declaration such as its base type and name.
 This choice is based on prior experience with the SGI `.spec` file format
 used to describe OpenGL, and greatly eases human reading and writing the
 XML, and generating C-oriented output.
 The cost is that people writing output generators for other languages will
 have to include enough logic to parse the C declarations and extract the
 relevant information.

 People who do not find the supplied Python scripts to suit their needs are
 likely to write their own parsers, interpreters, and/or converters operating
 on the registry XML.
 We hope that we have provided enough information in this document, the RNC
 schema (`registry.rnc`), and comments in the Registry (`vk.xml`) itself to
 enable such projects.
 If not and you need clarifications; if you have other problems using the
 registry; or if you have proposed changes and enhancements, then please file
 issues on Khronos' public GitHub project at

 https://github.com/KhronosGroup/Vulkan-Docs/issues

 Please tag your issues with `[Registry]` in the subject line to help us
 categorize them.


 [[introduction-normative]]
 == Normative References

 Normative references are references to external documents or resources to
 which documentation authors must comply.

 [[vulkan-styleguide]] Jon Leech and Tobias Hector.
 _Vulkan Documentation and Extensions: Procedures and Conventions_ (February
 26, 2023).
 https://registry.khronos.org/vulkan/specs/1.3/styleguide.html .

 [[vulkan-spec]] Khronos Vulkan Working Group.
 _Vulkan 1.3.242 - A Specification_ (February 26, 2023).
 https://registry.khronos.org/vulkan/ .


 [[starting]]
 = Getting Started

 See
 https://gitlab.khronos.org/vulkan/vulkan/blob/main/xml/README.adoc[`xml/README.adoc`]
 in the `Vulkan-Docs` repository for information on required toolchain
 components such as Python 3, pass:[g++], and GNU make.

 Once you have the right tools installed, perform the following steps:

   * Check out the `Vulkan-Docs` repository linked above from Khronos GitHub
     (there are instructions at the link)
   * `cd` to the root directory in your checked-out repo
   * Switch to the default branch (`main`).
   * Invoke `make clean ; make install ; make test`

 This should regenerate `vulkan_core.h` and a variety of platform-specific
 headers, install them in `../include/vulkan/`, and verify that the headers
 build properly.
 If you build at the latest repository tag, the resulting headers should be
 identical to the latest versions in the
 link:https://github.com/KhronosGroup/Vulkan-Headers/[Vulkan-Headers
 repository].

 The `install` target also generates source code for a simple extension
 loader library in `../src/ext_loader/`.

 Other Makefile targets in `xml/` include:

   * `validate` - validate `vk.xml` against the XML schema.
     Recommended if you are making nontrivial changes.
   * The asciidoc includes used by the <<vulkan-spec, Vulkan API
     Specification>> and Reference Pages are built using the 'make generated'
     target in the parent directory Makefile, although they use the scripts
     and XML in this directory.
     These files are generated dynamically when building the specs, since
     their contents depend on the exact set of extensions the Specification
     is being built to include.

 If you just want to modify the API, changing `vk.xml` and running `make`
 should be all that is needed.
 See <<examples>> for some examples of modifying the XML.

 If you want to use the registry for reasons other than generating the header
 file, extension loader, and asciidoc includes, or to generate headers for
 languages other than C, start with the Makefile rules and the files
 `vk.xml` and scripts `genvk.py`, `reg.py`, and `generator.py`.
 The scripts are described below and are all located in the `scripts`
 directory under the repository root.

 == Header Generation Script - `genvk.py`

 When generating header files using the `genvk.py` script, an API name and
 profile name are required, as shown in the Makefile examples.
 Additionally, specific API versions and extensions can be required or
 excluded.
 Based on this information, the generator script extracts the relevant
 interfaces and creates a C-language header file for them.
 `genvk.py` contains predefined generator options for the current
 <<vulkan-spec, Vulkan API Specification>> release.

 The generator script is intended to be generalizable to other languages by
 writing new generator classes.
 Such generators would have to rewrite the C types and definitions in the XML
 to something appropriate to their language.


 == Registry Processing Script - `reg.py`

 XML processing is done in `reg.py`, which contains several objects and
 methods for loading registries and extracting interfaces and extensions for
 use in header generation.
 There is some internal documentation in the form of comments, although
 nothing more extensive exists yet.


 == Output Generator Script - `generator.py`

 Once the registry is loaded, the `COutputGenerator` class defined in
 `generator.py` is used to create a header file.
 The `DocOutputGenerator` class is used to create the asciidoc include files.
 Output generators for other purposes can be added as needed.
 There are a variety of output generators included:

   * `cgenerator.py` - generate C header file
   * `docgenerator.py` - generate asciidoc includes for APIs
   * `hostsyncgenerator.py` - generate host sync table includes for APIs
   * `validitygenerator.py` - generate validity language includes
   * `pygenerator.py` - generate a Python dictionary-based encoding of
     portions of the registry, used during spec generation
   * `extensionStubSource.py` - generate a simple C extension loader.


 [[schema]]
 = Vulkan Registry Schema

 The format of the Vulkan registry is a top level tag:registry tag containing
 tag:types, tag:enums, tag:commands, tag:feature, and tag:extension tags
 describing the different elements of an API, as explained below.
 This description corresponds to a formal Relax NG schema file,
 `registry.rnc`, against which the XML registry files can be validated.

 At present the only registry in this schema is the core Vulkan API registry,
 `vk.xml`.


 [[schema:profile]]
 == Profiles

 Types and enumerants can have different definitions depending on the API
 profile requested.
 This capability is not used in the current Vulkan API but may be in the
 future.
 Features and extensions can include some elements conditionally depending on
 the API profile requested.


 [[schema:apiname]]
 == API Names

 Specific API versions features and extensions can be tagged as belonging to
 to classes of features with the use of _API names_.
 This is intended to allow multiple closely-related API specifications in the
 same family - such as desktop and mobile specifications - to share the same
 XML.
 An API name is an arbitrary alphanumeric string, although it should be
 chosen to match the corresponding API.
 For example, Vulkan and OpenXR use `vulkan` and `openxr` as their API names,
 respectively.

 The attr:api attribute of the tag:feature tag and the attr:supported
 attribute of the tag:extensions tag must be comma-separated lists of one or
 more API names, all of which match that feature or extension.
 When generating headers and other artifacts from the XML, an API name may be
 specified to the processing scripts, causing the selection of only those
 features and extensions whose API names match the specified name.

 Several other tags for defining types and groups of types also support
 attr:api attributes.
 If present, the attribute value must be a comma-separated list of one or
 more API names.
 This allows specializing a definition for different, closely related APIs.


 [[schema:root]]
 = Registry Root (tag:registry Tag)

 A tag:registry contains the entire definition of one or more related APIs.

 == Attributes of tag:registry Tags

 None.

 == Contents of tag:registry Tags

 Zero or more of each of the following tags, normally in this order (although
 order should not be important):

   * tag:comment - Contains arbitrary text, such as a copyright statement.
   * <<tag-platforms,tag:platforms>> - defines platform names corresponding
     to platform-specific <<tag-extension,API extensions>>.
   * <<tag-tags,tag:tags>> - defines author IDs used for extensions and
     layers.
     Author IDs are described in detail in the "`Layers & Extensions`"
     section of the "`Vulkan Documentation and Extensions: Procedures and
     Conventions`" document.
   * <<tag-types,tag:types>> - defines API types.
     Usually only one tag is used.
   * <<tag-enums,tag:enums>> - defines API token names and values.
     Usually multiple tags are used.
     Related groups may be tagged as an enumerated type corresponding to a
     tag:type tag, and resulting in a C `enum` declaration.
     This ability is heavily used in the Vulkan API.
   * <<tag-commands,tag:commands>> - defines API commands (functions).
     Usually only one tag is used.
   * <<tag-feature,tag:feature>> - defines API feature interfaces (API
     versions, more or less).
     One tag per feature set.
   * <<tag-extensions,tag:extensions>> - defines API extension interfaces.
     Usually only one tag is used, wrapping many extensions.
   * <<tag-formats,tag:formats>> - defines properties of image formats.
     Only one tag is used, wrapping all the formats.
   * <<tag-spirvextensions,tag:spirvextensions>> - defines relationship
     between SPIR-V extensions and API interfaces which enable each
     extension.
     Only one tag is used, wrapping all the SPIR-V extensions.
   * <<tag-spirvcapabilities,tag:spirvcapabilities>> - defines relationship
     between SPIR-V capabilities and API interfaces which enable each
     capability.
     Only one tag is used, wrapping all the SPIR-V capabilities.
   * <<tag-sync,tag:sync>> - Defines sync objects
   * <<tag-syncstage,tag::syncstage>> - Defines all Pipeline Stages
   * <<tag-syncaccess,tag::syncaccess>> - Defines all Access Types
   * <<tag-syncpipeline,tag::syncpipeline>> - Defines Pipeline's logical ordering


 [[tag-comment]]
 === Comment Tags (tag:comment Tag)

 A tag:comment tag contains an arbitrary string, and is unused.
 Comment tags may appear in multiple places in the schema, as described
 below.
 Comment tags are removed by output generators if they would otherwise appear
 in generated headers, asciidoc include files, etc.


 [[tag-platforms]]
 = Platform Name Blocks (tag:platforms Tag)

 A tag:platforms contains descriptions of platform IDs for platforms
 supported by window system-specific extensions to Vulkan.

 == Attributes of tag:platforms Tags

   * attr:comment - optional.
     Arbitrary string (unused).

 == Contents of tag:platforms Tags

 Zero or more tag:platform tags, in arbitrary order (though they are
 typically ordered by sorting on the platform name).


 [[tag-platform]]
 = Platform Names (tag:platform Tag)

 A tag:platform tag describes a single platform name.

 == Attributes of tag:platform Tags

   * attr:name - required.
     The platform name.
     This must be a short alphanumeric string corresponding to the platform
     name, valid as part of a C99 identifier.
     Lower-case is preferred.
     In some cases, it may be desirable to distinguish a subset of platform
     functionality from the entire platform.
     In these cases, the platform name should begin with the entire platform
     name, followed by `_` and the subset name.
 +
 --
 [NOTE]
 .Note
 ====
 For example,

 `name="xlib"`

 is used for the X Window System, Xlib client library platform.

 `name="xlib_xrandr"`

 is used for the XRandR functionality within the `xlib` platform.
 ====
 --
   * attr:protect - required.
     This must be a C99 preprocessor token beginning with `VK_USE_PLATFORM_`
     followed by the platform name, converted to upper case, followed by `_`
     and the extension suffix of the corresponding window system-specific
     extension supporting the platform.
 +
 --
 [NOTE]
 .Note
 ====
 For example,

 `protect="VK_USE_PLATFORM_XLIB_XRANDR_EXT"`

 is used for the `xlib_xrandr` platform name.
 ====
 --
   * attr:comment - optional.
     Arbitrary string (unused).

 == Contents of tag:platform Tags

 No contents are allowed.
 All information is contained in the attributes.


 [[tag-tags]]
 = Author ID Blocks (tag:tags Tag)

 A tag:tags tag contains tag:authorid tags describing reserved author IDs
 used by extension and layer authors.

 == Attributes of tag:tags Tags

   * attr:comment - optional.
     Arbitrary string (unused).

 == Contents of tag:tags Tags

 Zero or more tag:tag tags, in arbitrary order (though they are typically
 ordered by sorting on the author ID).


 [[tag-tag]]
 = Author IDs (tag:tag Tag)

 A tag:tag tag contains information defining a single author ID.

 == Attributes of tag:tag Tags

   * attr:name - required.
     The author ID, as registered with Khronos.
     A short, upper-case string, usually an abbreviation of an author,
     project or company name.
   * attr:author - required.
     The author name, such as a full company or project name.
   * attr:contact - required.
     The contact who registered or is currently responsible for extensions
     and layers using the ID, including sufficient contact information to
     reach the contact such as individual name together with email address,
     GitHub username, or other contact information.

 == Contents of tag:tag Tags

 No contents are allowed.
 All information is contained in the attributes.


 [[tag-types]]
 = API Type Blocks (tag:types Tag)

 A tag:types tag contains definitions of derived types used in the API.

 == Attributes of tag:types Tags

   * attr:comment - optional.
     Arbitrary string (unused).

 == Contents of tag:types Tags

 Zero or more tag:type and tag:comment tags, in arbitrary order (though they
 are typically ordered by putting dependencies of other types earlier in the
 list).
 The tag:comment tags are used mostly to indicate grouping of related types.


 [[tag-type]]
 = API Type (tag:type Tag)

 A tag:type tag contains information which can be used to generate C code
 corresponding to the type.
 In many cases, this is simply legal C code, with attributes or embedded tags
 denoting the type name and other types used in defining this type.
 In some cases, additional attribute and embedded type information is used to
 generate more complicated C types.

 == Attributes of tag:type Tags

   * attr:requires - optional.
     Another type name this type requires to complete its definition.
   * attr:name - optional.
     Name of this type (if not defined in the tag body).
   * attr:alias - optional.
     Another type name which this type is an alias of.
     Must match the name of another tag:type element.
     This is typically used when promoting a type defined by an extension to
     a new core version of the API.
     The old extension type is still defined, but as an alias of the new
     type.
   * attr:api - optional comma-separated list of <<schema:apiname, API names>>
     for which this definition is specialized, so that different APIs may
     have different definitions for the same type.
     This definition is only used if the requested API name matches the
     attribute.
     May be used to address subtle incompatibilities.
   * attr:category - optional.
     A string which indicates that this type contains a more complex
     structured definition.
     At present the only accepted categories are `basetype`, `bitmask`,
     `define`, `enum`, `funcpointer`, `group`, `handle`, `include`, `struct`,
     and `union`, as described below.
   * attr:comment - optional.
     Arbitrary string (unused).
   * attr:deprecated - optional.
     Indicates that this type has been deprecated.
     Possible values are:
   ** `"true"` - deprecated, but no explanation given.
   ** `"aliased"` - an old name not following Vulkan conventions.
      The equivalent alias following Vulkan conventions should be used
      instead.
   * attr:parent - only applicable if `"category"` is `handle`.
     Notes another type with the `handle` category that acts as a parent
     object for this type.
   * attr:returnedonly - only applicable if `"category"` is `struct` or
     `union`.
     Notes that this struct/union is going to be filled in by the API, rather
     than an application filling it out and passing it to the API.
   * attr:structextends only applicable if category is `struct` or `union`.
     This is a comma-separated list of structures whose `pNext` can include
     this type.
     This should usually only list the top-level structure that is extended,
     for all possible extending structures.
     This will generate a validity statement on the top level structure that
     validates the entire chain in one go, rather than each extending
     structure repeating the list of valid structs.
     There is no need to set the attr:noautovalidity attribute on the `pNext`
     members of extending structures.
   * attr:allowduplicate - only applicable if attr:category is `"struct"`.
     If `"true"`, then structures whose `pNext` chains include this structure
     may include more than one instance of it.
   * attr:objtypeenum - only applicable at present if attr:category is
     `"handle"`.
     Specifies the name of a `VkObjectType` enumerant which corresponds to
     this type.
     The enumerant must be defined.

 == Contents of tag:type Tags

 The valid contents depend on the attr:category attribute.

 === Enumerated Types - attr:category `"enum"`

 If the attr:category tag has the value `enum`, the type is a C enumeration.
 The body of the tag is ignored in this case.
 The value of the attr:name attribute must be provided and must match the
 attr:name attribute of a <<tag-enums,tag:enums>> tag.
 The enumerant values defined within the tag:enums tag are used to generate a
 C `enum` type declaration.

 === Structure Types - attr:category `"struct"` or `"union"`

 If the attr:category tag has the values `struct` or `union`, the type is a C
 structure or union, respectively.
 In this case, the attr:name attribute must be provided, and the contents of
 the tag:type tag are a series of tag:member tags defining the members of the
 aggregate type, in order, interleaved with any number of tag:comment tags.

 ==== Structure Member (tag:member) Tags

 The tag:member tag defines the type and name of a structure or union member.

 ==== Attributes of tag:member Tags

   * attr:api - optional <<schema:apiname, API names>> for which this
     definition is specialized, so that different APIs may have different
     definitions for the same type.
     This definition is only used if the requested API name matches the
     attribute.
     May be used to address subtle incompatibilities.
   * attr:values - only valid on the `sType` member of a struct.
     This is a comma-separated list of enumerant values that are valid for
     the structure type; usually there is only a single value.
   * attr:len - if the member is an array, len may be one or more of the
     following things, separated by commas (one for each array indirection):
     another member of that struct; `"null-terminated"` for a string; `"1"`
     to indicate it is just a pointer (used for nested pointers); or an
     equation in math markup for incorporation in the specification (a LaTeX
     math expression delimited by `latexmath:[` and `]`.
     The only variables in the equation should be the names of members of the
     structure.
   * attr:altlen - if the attr:len attribute is specified, and contains a
     `latexmath:` equation, this attribute should be specified with an
     equivalent equation using only C builtin operators, C math library
     function names, and variables as allowed for attr:len.
     It must be a valid C99 expression whose result is equal to attr:len for
     all possible inputs.
     It is a comma separated list that has size equal to only the `latexmath`
     item count in attr:len list.
     This attribute is intended to support consumers of the XML who need to
     generate validation code from the allowed length.
   * attr:deprecated - optional.
     Indicates that this member has been deprecated.
     Possible values are:
   ** `"true"` - deprecated, but no explanation given.
   ** `"ignored"` - functionality described by this member no longer
      operates.
   * attr:externsync - denotes that the member should be externally
     synchronized when accessed by Vulkan
   * attr:optional - optional.
     A value of `"true"` specifies that this member can be omitted by
     providing `NULL` (for pointers), `VK_NULL_HANDLE` (for handles), or 0
     (for other scalar types).
     If not present, the value is assumed to be `"false"` (the member must
     not be omitted).
     If the member is a pointer to one of those types, multiple values may be
     provided, separated by commas - one for each pointer indirection.
     Structure members with name `pNext` must always be specified with
     `optional="true"`, since there is no requirement that any member of a
     `pNext` chain have a following member in the chain.
 +
 --
 [NOTE]
 .Note
 ====
 While the attr:optional attribute can be used for scalar types such as
 integers, it does not affect the output generators included with the
 <<vulkan-spec, Vulkan API Specification>>.
 In this case, the attribute serves only as an indicator to human readers of
 the XML.

 Explicitly specifying `optional="false"` is not supported, but
 `optional="false,true"` is supported for a pointer type.
 ====
 --
   * attr:selector - optional.
     If the member is a union, attr:selector identifies another member of the
     struct that is used to select which of that union's members are valid.
   * attr:selection - optional.
     For a member of a union, attr:selection identifies a value of the
     attr:selector that indicates this member is valid.
   * attr:noautovalidity - prevents automatic validity language being
     generated for the tagged item.
     Only suppresses item-specific validity - parenting issues etc.
     are still captured.
     It must also be used for structures that have no implicit validity when
     such structure has explicit validity.
   * attr:limittype - only applicable for members of
     `VkFormatProperties`, `VkFormatProperties2`,
     `VkPhysicalDeviceProperties`, `VkPhysicalDeviceProperties2`,
     `VkPhysicalDeviceLimits`, `VkQueueFamilyProperties`,
     `VkQueueFamilyProperties2`, `VkSparseImageFormatProperties`,
     `VkSparseImageFormatProperties2`, and structures extending or members of
     any of those structures.
     Specifies the type of a device limit.
     This type describes how a value might be compared with the value of a
     member in order to check whether it fits the limit.
     Valid values:
   ** `"min"` and `"max"` denote minimum and maximum limits.
      They may also apply to arrays and `VkExtent*D`.
   ** `"pot"` denotes a value that has to be a power of two value.
      They may also apply to arrays and `VkExtent*D`.
   ** `"mul"` denotes a value that must be an integer multiple of this limit.
      They may also apply to arrays and `VkExtent*D`.
   ** `"bits"` corresponds to the bits precision of an implementation.
   ** `"bitmask"` corresponds to bitmasks and `VkBool32`, where set bits
      indicate the presence of a capability
   ** `"range"` specifies a [min, max] range
   ** `"struct"` means that the member's fields should be compared.
   ** `"exact"` specifies a limit that must be a specific value.
   ** `"noauto"` limits cannot be trivially compared.
      This is the default value, if unspecified.
   * attr:objecttype - only applicable for members which are `uint64_t`
     values representing a Vulkan object handle.
     Specifies the name of another member which must be a `VkObjectType` or
     `VkDebugReportObjectTypeEXT` value specifying the type of object the
     handle refers to.
   * attr:stride - if the member is an array, stride specifies the name of
     another member containing the byte stride between consecutive elements
     in the array. Is assumed tightly packed if omitted.


 ==== Contents of tag:member Tags

 The text elements of a tag:member tag, with all other tags removed, is a
 legal C declaration of a struct or union member.
 In addition it may contain several semantic tags:

   * The tag:type tag is optional.
     It contains text which is a valid type name found in another tag:type
     tag, and indicates that this type must be previously defined for the
     definition of the command to succeed.
     Builtin C types should not be wrapped in tag:type tags.
   * The tag:name tag is required, and contains the struct/union member name
     being described.
   * The tag:enum tag is optional.
     It contains text which is a valid enumerant name found in another
     tag:type tag, and indicates that this enumerant must be previously
     defined for the definition of the command to succeed.
     Typically this is used to semantically tag static array lengths.
   * The tag:comment tag is optional.
     It contains an arbitrary string (unused).


 === All Other Types

 If the attr:category attribute is one of `basetype`, `bitmask`, `define`,
 `funcpointer`, `group`, `handle` or `include`, or is not specified, tag:type
 contains text which is legal C code for a type declaration.
 It may also contain embedded tags:

   * tag:type - nested type tags contain other type names which are required
     by the definition of this type.
   * tag:apientry/ - insert a platform calling convention macro here during
     header generation, used mostly for function pointer types.
   * tag:name - contains the name of this type (if not defined in the tag
     attributes).
   * tag:bitvalues - contains the name of the enumeration defining flag
     values for a `bitmask` type.
     Ignored for other types.

 There is no restriction on which sorts of definitions may be made in a given
 category, although the contents of tags with attr:category `enum`, `struct`
 or `union` are interpreted specially as described above.

 However, when generating the header, types within each category are grouped
 together, and categories are generated in the order given by the following
 list.
 Therefore, types in a category should correspond to the intended purpose
 given for that category.
 If this recommendation is not followed, it is possible that the resulting
 header file will not compile due to out-of-order type dependencies.
 The intended purpose of each category is:

   * `include` (`#include`) directives)
   * `define` (macro `#define` directives)
   * `basetype` (built-in C language types; scalar API typedefs, such as the
     definition of `VkFlags`; and types defined by external APIs, such as an
     underlying OS or window system
   * `handle` (invocations of macros defining scalar types such as
     `VkInstance`)
   * `enum` (enumeration types and `#define` for constant values)
   * `group` (currently unused)
   * `bitmask` (enumeration types whose members are bitmasks)
   * `funcpointer` (function pointer typedefs)
   * `struct` and `union` together (struct and union types)


 [[tag-types:example]]
 == Example of a tag:types Tag

 [source,xml]
 --------------------------------------
 <types>
     <type name="stddef">#include &lt;stddef.h&gt;</type>
     <type requires="stddef">typedef ptrdiff_t <name>VKlongint</name>;</type>
     <type name="VkEnum" category="enum"/>
     <type category="struct" name="VkStruct">
         <member><type>VkEnum</type> <name>srcEnum</name></member>
         <member><type>VkEnum</type> <name>dstEnum</name></member>
     </type>
 </types>

 <enums name="VkEnum" type="enum">
     <enum value="0" name="VK_ENUM_ZERO"/>
     <enum value="42" name="VK_ENUM_FORTY_TWO"/>
 </enums>
 --------------------------------------

 The `VkStruct` type is defined to require the types `VkEnum` and `VKlongint`
 as well.
 If `VkStruct` is in turn required by a command or another type during header
 generation, it will result in the following declarations:

 [source,c]
 --------------------------------------
 #include <stddef.h>
 typedef ptrdiff_t VKlongint.

 typedef enum {
     VK_ENUM_ZERO = 0,
     VK_ENUM_FORTY_TWO = 42
 } VkEnum;

 typedef struct {
     VkEnum    dstEnum;
     VkLongint dstVal;
 } VkStruct;
 --------------------------------------

 Note that the angle brackets around `stddef.h` are represented as XML
 entities in the registry.
 This could also be done using a CDATA block but unless there are many
 characters requiring special representation in XML, using entities is
 preferred.


 [[tag-enums]]
 = Enumerant Blocks (tag:enums Tag)

 The tag:enums tags contain individual tag:enum tags describing each of the
 token names used in the API.
 In some cases these correspond to a C `enum`, and in some cases they are
 simply compile time constants (e.g. `#define`).

 [NOTE]
 .Note
 ====
 It would make more sense to call these `const` or `define` tags.
 This is a historical hangover from the OpenGL XML format which this schema
 was based on.
 ====


 == Attributes of tag:enums Tags

   * attr:name - optional.
     String naming the C `enum` type whose members are defined by this enum
     group.
     If present, this attribute should match the attr:name attribute of a
     corresponding tag:type tag.
   * attr:type - optional.
     String describing the data type of the values of this group of enums.
     At present the only accepted categories are `enum` and `bitmask`, as
     described below.
   * attr:comment - optional.
     Arbitrary string (unused).
   * attr:bitwidth - optional.
     Bit width required for the generated enum value type.
     If omitted, a default value of 32 is used.

 == Contents of tag:enums Tags

 Each tag:enums block contains zero or more tag:enum, tag:unused, and
 tag:comment tags, in arbitrary order (although they are typically ordered by
 sorting on enumerant values, to improve human readability).

 == Example of tag:enums Tags

 <<tag-types:example,An example>> showing a tag with attribute
 attr:type`="enum"` is given above.
 The following example is for non-enumerated tokens.

 [source,xml]
 --------------------------------------
 <enums>
     <enum value="256" name="VK_MAX_EXTENSION_NAME"/>
     <enum value="MAX_FLOAT"  name="VK_LOD_CLAMP_NONE"/>
 </enums>
 --------------------------------------

 When processed into a C header, and assuming all these tokens were required,
 this results in

 [source,c]
 --------------------------------------
 #define VK_MAX_EXTENSION_NAME   256
 #define VK_LOD_CLAMP_NONE       MAX_FLOAT
 --------------------------------------


 [[tag-enum]]
 = Enumerants (tag:enum Tag)

 Each tag:enum tag defines a single Vulkan (or other API) token.

 == Attributes of tag:enum Tags

   * attr:value is a numeric value in the form of a legal C expression when
     evaluated at compile time in the generated header files.
     This is usually either a literal integer value or the name of an alias
     for a previously defined value, though more complex expressions are
     sometimes employed for <<compile-time-constants, compile time
     constants>>.
   * attr:bitpos is a literal integer bit position in a bitmask.
     The bit position must be in the range [0,30] when used as a flag bit in
     a `Vk*FlagBits` data type.
     Bit positions 31 and up may be used for values that are not flag bits,
     or for <<adding-bitflags, flag bits used with 64-bit flag types>>.
     Exactly one of attr:value and attr:bitpos must be present in an tag:enum
     tag.
   * attr:name - required.
     Enumerant name, a legal C preprocessor token name.
   * attr:api - optional comma-separated list of <<schema:apiname, API
     names>> for which this definition is specialized, so that different APIs
     may have different values for the same token.
     This definition is only used if the requested API name matches the
     attribute.
     May be used to address subtle incompatibilities.
   * attr:deprecated - optional.
     Indicates that this enum has been deprecated.
     Possible values are:
   ** `"true"` - deprecated, but no explanation given.
   ** `"ignored"` - functionality described by this enum no longer operates.
   ** `"aliased"` - an old name not following Vulkan conventions.
      The equivalent alias following Vulkan conventions should be used
      instead.
   * attr:type - may be used only when attr:value is specified.
     In this case, attr:type is optional except when defining a
     <<compile-time-constants, compile time constant>>, in which case it is
     required when using some output generator paths.
     If present the attribute must be a C scalar type corresponding to the
     type of attr:value, although only `uint32_t`, `uint64_t`, and `float`
     are currently meaningful.
     attr:type is used by some output generators to generate constant
     declarations, although the default behavior is to use C `#define` for
     compile time constants.
   * attr:alias - optional.
     Name of another enumerant this is an alias of, used where token names
     have been changed as a result of profile changes or for consistency
     purposes.
     An enumerant alias is simply a different attr:name for the exact same
     attr:value or attr:bitpos.
   * attr:protect - optional.
     An additional preprocessor token used to protect an enum definition.

 [NOTE]
 .Note
 ====
 Using attr:alias on a tag:enum means you want the attr:name defined by the
 tag to be treated as an alias of the token name in the attr:alias attribute
 value.
 For example, the following tag defines `VK_ALIAS` as an alias of `VK_VALUE`:

 [source,xml]
 --------------------------------------
 <enum name="VK_ALIAS" alias="VK_VALUE">
 --------------------------------------
 ====

 [NOTE]
 .Note
 ====
 In older versions of the schema, attr:type was described as allowing only
 the C integer suffix types `u` and `ull`, which is inconsistent with the
 current definition.
 However, attr:type was not actually used in the registry processing scripts
 or `vk.xml` at the time the current definition was introduced, so this is
 expected to be a benign change.
 ====


 == Contents of tag:enum Tags

 tag:enum tags have no allowed contents.
 All information is contained in the attributes.


 [[tag-unused]]
 = Unused Enumerants (tag:unused Tag)

 Each tag:unused tag defines a range of enumerants which is allocated, but
 not yet assigned to specific enums.
 This just tracks the unused values for the Registrar's use, and is not used
 for header generation.

 [NOTE]
 .Note
 ====
 tag:unused tags could be generated and inserted automatically, which would
 be a good way to avoid the attributes becoming out of date.
 However, they are rarely used in the Vulkan XML schema, unlike the OpenGL
 XML schema it was based on.
 ====

 == Attributes of tag:unused Tags

   * attr:start - required, attr:end - optional.
     Integers defining the start and end of an unused range of enumerants.
     attr:start must be {leq} attr:end.
     If attr:end is not present, then attr:start defines a single unused
     enumerant.
     This range should not exceed the range reserved by the surrounding
     tag:enums tag.
   * attr:vendor - optional.
     String describing the vendor or purposes to whom a reserved range of
     enumerants is allocated.
     Usually identical to the attr:vendor attribute of the surrounding
     attr:enums block.
   * attr:comment - optional.
     Arbitrary string (unused).

 == Contents of tag:unused Tags

 None.


 [[tag-commands]]
 = Command Blocks (tag:commands Tag)

 The tag:commands tag contains definitions of each of the functions
 (commands) used in the API.

 == Attributes of tag:commands Tags

   * attr:comment - optional.
     Arbitrary string (unused).

 == Contents of tag:commands Tags

 Each tag:commands block contains zero or more tag:command tags, in arbitrary
 order (although they are typically ordered by sorting on the command name,
 to improve human readability).


 [[tag-command]]
 = Commands (tag:command Tag)

 The tag:command tag contains a structured definition of a single API command
 (function).

 == Attributes of tag:command Tags

 There are two ways to define a command.
 The first uses a set of attributes to the tag:command tag defining
 properties of the command used for constructing automatic validation rules,
 and the contents of the tag:command tag define the name, signature, and
 parameters of the command.
 In this case the allowed attributes include:

   * attr:tasks - optional.
     A string identifying the tasks this command performs, as described in
     the "`Queue Operation`" section of the <<vulkan-spec, Vulkan API
     Specification>>.
     The format of the string is one or more of the terms `"action"`,
     `"synchronization"`, `"state"`, and `"indirection"`, with multiple terms
     separated by commas (`","`).
   * attr:queues - optional.
     A string identifying the command queues this command can be placed on.
     The format of the string is one or more of the terms `"compute"`,
     `"decode"`, `"encode"`, `"graphics"`, `"transfer"`, `"sparse_binding"`,
     and `"opticalflow"`, with multiple terms separated by commas (`","`).
   * attr:successcodes - optional.
     A string describing possible successful return codes from the command,
     as a comma-separated list of Vulkan result code names.
   * attr:errorcodes - optional.
     A string describing possible error return codes from the command, as a
     comma-separated list of Vulkan result code names.
   * attr:renderpass - optional.
     A string identifying whether the command can be issued only inside a
     render pass (`"inside"`), only outside a render pass (`"outside"`), or
     both (`"both"`).
   * attr:videocoding - optional.
     A string identifying whether the command can be issued only inside a
     video coding scope (`"inside"`), only outside a video coding scope
     (`"outside"`), or both (`"both"`); the default is `"outside"` for
     commands that do not specify it.
   * attr:cmdbufferlevel - optional.
     A string identifying the command buffer levels that this command can be
     called by.
     The format of the string is one or more of the terms `"primary"` and
     `"secondary"`, with multiple terms separated by commas (`","`).
   * attr:comment - optional.
     Arbitrary string (unused).

 The second way of defining a command is as an alias of another command.
 For example when an extension is promoted from extension to core status, the
 commands defined by that extensions become aliases of the corresponding new
 core commands.
 In this case, only two attributes are allowed:

   * attr:name - required.
     A string naming the command defined by the tag.
   * attr:alias - required.
     A string naming the command that attr:name is an alias of.
     The string must be the same as the attr:name value of another
     tag:command defining another command.

 Both forms of tag:command support these options:

   * attr:api - optional <<schema:apiname, API names>> for which this
     definition is specialized, so that different APIs may have different
     values for the same token.
     This definition is only used if the requested API name matches the
     attribute.
     May be used to address subtle incompatibilities.

 == Contents of tag:command Tags

   * tag:proto is required and must be the first element.
     It is a tag defining the C function prototype of a command as described
     below, up to the function name and return type but not including
     function parameters.
   * tag:param elements for each command parameter follow, defining its name
     and type, as described below.
     If a command takes no arguments, it has no tag:param tags.

 Following these elements, the remaining elements in a tag:command tag are
 optional and may be in any order:

   * tag:alias - optional.
     Has no attributes and contains a string which is the name of another
     command this command is an alias of, used when promoting a function from
     vendor to Khronos extension or Khronos extension to core API status.
     A command alias describes the case where there are two function names
     which implement the same behavior.
   * tag:description - optional.
     Unused text.
   * tag:implicitexternsyncparams - optional.
     Contains a list of tag:param tags, each containing asciidoc source text
     describing an object which is not a parameter of the command but is
     related to one, and which also <<tag-command:param:attr,requires
     external synchronization>>.
     The text is intended to be incorporated into the API specification.

 [NOTE]
 .Note
 ====
 Versions of the registry documentation prior to 1.1.93 asserted that command
 aliases "`resolve to the _same_ entry point in the underlying layer stack.`"
 Whilst this may be true on many implementations, it is not required - each
 command alias must be queried separately through `vkGetInstanceProcAddr`
 or `vkGetDeviceProcAddr`.
 ====


 [[tag-command:proto]]
 == Command Prototype (tag:proto Tags)

 The tag:proto tag defines the return type and name of a command.

 === Attributes of tag:proto Tags

 None.

 // attr:group - group name, an arbitrary string.
 //
 // If the group name is defined, it may be interpreted as described in
 // <<tag-group:meaning>>.

 === Contents of tag:proto Tags

 The text elements of a tag:proto tag, with all other tags removed, is legal
 C code describing the return type and name of a command.
 In addition to text, it may contain two semantic tags:

   * The tag:type tag is optional, and contains text which is a valid type
     name found in a tag:type tag.
     It indicates that this type must be previously defined for the
     definition of the command to succeed.
     Builtin C types, and any derived types which are expected to be found in
     other header files, should not be wrapped in tag:type tags.
   * The tag:name tag is required, and contains the command name being
     described.


 [[tag-command:param]]
 == Command Parameter (tag:param Tags)

 The tag:param tag defines the type and name of a parameter.
 Its contents are very similar to the tag:member tag used to define struct
 and union members.


 [[tag-command:param:attr]]
 === Attributes of tag:param Tags

   * attr:api - optional <<schema:apiname, API names>> for which this
     definition is specialized, so that different APIs may have different
     definitions for the same type.
     This definition is only used if the requested API name matches the
     attribute.
     May be used to address subtle incompatibilities.
   * attr:len - if the param is an array, len may be one or more of the
     following things, separated by commas (one for each array indirection):
     another param of that command; `"null-terminated"` for a string; `"1"`
     to indicate it is just a pointer (used for nested pointers); or an
     equation in math markup for incorporation in the specification (a LaTeX
     math expression delimited by `latexmath:[` and `]`.
     The only variables in the equation should be the names of this or other
     parameters.
   * attr:altlen - if the attr:len attribute is specified, and contains a
     `latexmath:` equation, this attribute should be specified with an
     equivalent equation using only C builtin operators, C math library
     function names, and variables as allowed for attr:len.
     It must be a valid C99 expression whose result is equal to attr:len for
     all possible inputs.
     It is a comma separated list that has size equal to only the `latexmath`
     item count in attr:len list.
     This attribute is intended to support consumers of the XML who need to
     generate validation code from the allowed length.
   * attr:optional - optional.
     A value of `"true"` specifies that this parameter can be omitted by
     providing `NULL` (for pointers), `VK_NULL_HANDLE` (for handles), or 0
     (for other scalar types).
     If not present, the value is assumed to be `"false"` (the parameter must
     not be omitted).
     If the parameter is a pointer to one of those types, multiple values may
     be provided, separated by commas - one for each pointer indirection.
 +
 --
 [NOTE]
 .Note
 ====
 While the attr:optional attribute can be used for scalar types such as
 integers, it does not affect the output generators included with the
 <<vulkan-spec, Vulkan API Specification>>.
 In this case, the attribute serves only as an indicator to human readers of
 the XML.

 Explicitly specifying `optional="false"` is not supported, but
 `optional="false,true"` is supported for a pointer type.
 ====
 --
   * attr:selector - optional.
     If the parameter is a union, attr:selector identifies another parameter
     of the command that is used to select which of that union's members are
     valid.
   * attr:noautovalidity - prevents automatic validity language being
     generated for the tagged item.
     Only suppresses item-specific validity - parenting issues etc.
     are still captured.
   * attr:externsync - optional.
     A value of `"true"` indicates that this parameter (e.g. the object a
     handle refers to, or the contents of an array a pointer refers to) is
     modified by the command, and is not protected against modification in
     multiple app threads.
     If only certain members of an object or elements of an array are
     modified, multiple strings may be provided, separated by commas.
     Each string describes a member which is modified.
     For example, the `VkPresentInfoKHR` struct includes attr:externsync
     attributes for the `pPresentInfo` array indicating that only specific
     members of each element of the array are modified:
 +
 --
 [source,xml]
 --------------------------------------
 <param externsync="pPresentInfo-&gt;pWaitSemaphores[],pPresentInfo-&gt;pSwapchains[]">const <type>VkPresentInfoKHR</type>* <name>pPresentInfo</name></param>
 --------------------------------------

 Parameters which do not have an attr:externsync attribute are assumed to not
 require external synchronization.
 --
   * attr:objecttype - only applicable for parameters which are `uint64_t`
     values representing a Vulkan object handle.
     Specifies the name of another parameter which must be a `VkObjectType`
     or `VkDebugReportObjectTypeEXT` value specifying the type of object the
     handle refers to.
   * attr:validstructs - optional.
     Allowed only when the parameter type is a pointer to an abstract
     `VkBaseInStructure` or `VkBaseOutStructure` type.
     This is a comma-separated list of structures which can either be
     passed as the parameter, or can appear anywhere in the `pNext` chain of
     the parameter.


 === Contents of tag:param Tags

 The text elements of a tag:param tag, with all other tags removed, is legal
 C code describing the type and name of a function parameter.
 In addition it may contain two semantic tags:

   * The tag:type tag is optional, and contains text which is a valid type
     name found in tag:type tag, and indicates that this type must be
     previously defined for the definition of the command to succeed.
     Builtin C types, and any derived types which are expected to be found in
     other header files, should not be wrapped in tag:type tags.
   * The tag:name tag is required, and contains the parameter name being
     described.

 == Example of a tag:commands Tag

 [source,xml]
 --------------------------------------
 <commands>
     <command>
         <proto><type>VkResult</type> <name>vkCreateInstance</name></proto>
         <param>const <type>VkInstanceCreateInfo</type>* <name>pCreateInfo</name></param>
         <param><type>VkInstance</type>* <name>pInstance</name></param>
     </command>
 </commands>
 --------------------------------------

 When processed into a C header, this results in

 [source,c]
 --------------------------------------
 VkResult vkCreateInstance(
     const VkInstanceCreateInfo* pCreateInfo,
     VkInstance* pInstance);
 --------------------------------------


 [[tag-feature]]
 = API Features and Versions (tag:feature Tag)

 API features are described in individual tag:feature tags.
 A feature is the set of interfaces (enumerants and commands) defined by a
 particular API and version, such as Vulkan 1.0, and includes all profiles of
 that API and version.

 == Attributes of tag:feature Tags

   * attr:api - required comma-separated list of <<schema:apiname, API
     names>> for which this feature is defined, such as `vulkan`.
   * attr:name - required.
     Version name, used as the C preprocessor token under which the version's
     interfaces are protected against multiple inclusion.
     Example: `"VK_VERSION_1_0"`.
   * attr:number - required.
     Feature version number, usually a string interpreted as
     `majorNumber.minorNumber`.
     Example: `4.2`.
   * attr:sortorder - optional.
     A decimal number which specifies an order relative to other tag:feature
     tags when calling output generators.
     Defaults to `0`.
     Rarely used, for when ordering by attr:name is insufficient.
   * attr:protect - optional.
     An additional preprocessor token used to protect a feature definition.
     Usually another feature or extension attr:name.
     Rarely used, for odd circumstances where the definition of a feature or
     extension requires another to be defined first.
   * attr:comment - optional.
     Arbitrary string (unused).

 [NOTE]
 .Note
 ====
 The attr:name attribute used for Vulkan core versions, such as
 `"VK_VERSION_1_0"`, is not an API construct.
 It is used only as a preprocessor guard in the headers, and an asciidoctor
 conditional in the specification sources.
 The similar `"VK_API_VERSION_1_0"` symbols are part of the API and their
 values are packed integers containing Vulkan core version numbers.
 ====

 == Contents of tag:feature Tags

 Zero or more <<tag-required,tag:require and tag:remove tags>>, in arbitrary
 order.
 Each tag describes a set of interfaces that is respectively required for, or
 removed from, this feature, as described below.

 == Example of a tag:feature Tag

 [source,xml]
 --------------------------------------
 <feature api="vulkan" name="VK_VERSION_1_0" number="1.0">
     <require comment="Header boilerplate">
         <type name="vk_platform"/>
     </require>
     <require comment="API constants">
         <enum name="VK_MAX_PHYSICAL_DEVICE_NAME"/>
         <enum name="VK_LOD_CLAMP_NONE"/>
     </require>
     <require comment="Device initialization">
         <command name="vkCreateInstance"/>
     </require>
 </feature>
 --------------------------------------

 When processed into a C header for Vulkan, this results in:

 [source,c]
 --------------------------------------
 #ifndef VK_VERSION_1_0
 #define VK_VERSION_1_0 1
 #define VK_MAX_EXTENSION_NAME   256
 #define VK_LOD_CLAMP_NONE       MAX_FLOAT
 typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)(const VkInstanceCreateInfo* pCreateInfo, VkInstance* pInstance);
 #ifndef VK_NO_PROTOTYPES
 VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance(
     const VkInstanceCreateInfo*                 pCreateInfo,
     VkInstance*                                 pInstance);
 #endif
 #endif /* VK_VERSION_1_0 */
 --------------------------------------


 [[tag-extensions]]
 = Extension Blocks (tag:extensions Tag)

 The tag:extensions tag contains definitions of each of the extensions which
 are defined for the API.

 == Attributes of tag:extensions Tags

   * attr:comment - optional.
     Arbitrary string (unused).

 == Contents of tag:extensions Tags

 Each tag:extensions block contains zero or more tag:extension tags, each
 describing an API extension, in arbitrary order (although they are typically
 ordered by sorting on the extension name, to improve human readability).


 [[tag-extension]]
 = API Extensions (tag:extension Tag)

 API extensions are described in individual tag:extension tags.
 An extension is the set of interfaces defined by a particular API extension
 specification, such as `ARB_multitexture`.
 tag:extension is similar to tag:feature, but instead of having an
 attr:number attribute, it instead has a attr:supported attribute, which
 describes the set of API names which the extension can potentially be
 implemented against.

 == Attributes of tag:extension Tags

   * attr:name - required.
     Extension name, following the conventions in the <<vulkan-spec, Vulkan
     API Specification>>.
     Example: `name="VK_VERSION_1_0"`.
   * attr:number - required.
     A decimal number which is the registered, unique extension number for
     attr:name.
   * attr:sortorder - optional.
     A decimal number which specifies an order relative to other
     tag:extension tags when calling output generators.
     Defaults to `0`.
     Rarely used, for when ordering by attr:number is insufficient.
   * attr:author - optional.
     The author name, such as a full company name.
     If not present, this can be taken from the corresponding tag:tag
     attribute.
     However, `EXT` and other multi-vendor extensions may not have a
     well-defined author or contact in the tag.
     This attribute is not used in processing the XML.
     It is just metadata, mostly used to track the original author of an
     extension (which may have since been promoted to use a different author
     ID).
   * attr:contact - optional.
     The contact who registered or is currently responsible for extensions
     and layers using the tag, including sufficient contact information to
     reach the contact such as individual name together with GitHub username
     (`@username`), Khronos internal Gitlab username (`gitlab:@username`) if
     no public GitHub contact is available, or other contact information.
     If not present, this can be taken from the corresponding tag:tag
     attribute just like attr:author.
   * attr:type - required if the attr:supported attribute is not
     `'disabled'`.
     Must be either `'device'` or `'instance'`, if present.
   * [[depends-expressions]] attr:depends - optional.
     String containing a boolean expression of one or more API core version
     and extension names.
     The extension requires the expression in the string to be satisfied to
     use any functionality it defines (for instance extensions), or to use
     any device-level functionality it provides (for device extensions).
     Supported operators include `,` for logical OR, `+` for logical AND, and
     `(` `)` for grouping.
     `,` and `+` are of equal precedence, and lower than `(` `)`.
     Expressions must be evaluated left-to-right for operators of the same
     precedence.
     Terms which are core version names are true if the corresponding
     API version is supported.
     Terms which are extension names are true if the corresponding extension
     is enabled.
 +
 --
 [NOTE]
 .Note
 ====
 attr:depends is a breaking change in Vulkan 1.3.241, replacing the
 `requires` and `requiresCore` attributes.
 For example, an extension which previously specified these two attributes in
 `vk.xml`:

 * `requires="VK_KHR_dep_a,VK_EXT_dep_b"`
 * `requiresCore="1.1"`

 should replace them both with

 * `depends="VK_VERSION_1_1+VK_KHR_dep_a+VK_EXT_dep_b"`

 Note that the use of `,` in the old `requires` attribute was treated as a
 logical AND, and must be replaced by `+` in the `depends` attribute.
 ====
 --
   * attr:protect - optional.
     An additional preprocessor token used to protect an extension
     definition.
     Usually another feature or extension attr:name.
     Rarely used, for odd circumstances where the definition of an extension
     requires another extension or a header file to be defined first.
   * attr:platform - optional.
     Indicates that the extension is specific to the platform identified by
     the attribute value, and should be emitted conditional on that platform
     being available, in a platform-specific header, etc.
     The attribute value must be the same as one of the tag:platform tag:name
     attribute values.
   * attr:supported - comma-separated list of required <<schema:apiname, API
     names>> for which this extension is defined.
     When the extension tag is just reserving an extension number, use
     `supported="disabled"` to indicate this extension should never be
     processed.
     Interfaces defined in a `disabled` extension block are tentative at best
     and must: not be generated or otherwise used by scripts processing the
     XML.
     The only exception to this rule is for scripts used solely for
     reserving, or checking for reserved bitflag values.
   * attr:ratified - optional comma-separated list of <<scheme:apiname, API
     names>> for which this extension has been ratified by the Khronos Board
     of Promoters.
     Defaults to the empty string if not specified.
   * attr:promotedto - optional.
     A Vulkan version or a name of an extension that this extension was
     _promoted_ to.
     E.g. `"VK_VERSION_1_1"`, or `"VK_KHR_draw_indirect_count"`.
   * attr:deprecatedby - optional.
     A Vulkan version or a name of an extension that _deprecates_ this
     extension.
     It may be an empty string.
     E.g. `"VK_VERSION_1_1"`, or `"VK_EXT_debug_utils"`, or `""`.
   * attr:obsoletedby - optional.
     A Vulkan version or a name of an extension that _obsoletes_ this
     extension.
     It may be an empty string.
     E.g. `"VK_VERSION_1_1"`, or `"VK_KHR_maintenance1"`, or `""`.
   * attr:provisional - optional.
     `"true"` if this extension is released provisionally.
     Defaults to `"false"` if not specified.
   * attr:specialuse - optional.
     If present, must contain one or more tokens separated by commas,
     indicating a special purpose of the extension.
     Tokens may include:
   ** 'cadsupport' - for support of CAD software.
   ** 'd3demulation' - for support of Direct3D emulation layers or libraries,
      or applications porting from Direct3D.
   ** 'debugging' - for debugging an application.
   ** 'devtools' - for support of developer tools, such as capture-replay
      libraries.
   ** 'glemulation' - for support of OpenGL and/or OpenGL ES emulation layers
      or libraries, or applications porting from those APIs.
   * attr:comment - optional.
     Arbitrary string (unused).

 [NOTE]
 .Note
 ====
 The attr:depends attribute is used to specify other extensions that *must*
 be enabled for an extension to be enabled.

 In some cases, an extension may include functionality which is only defined
 *if* another extension is enabled.
 Such functionality should be specified within a tag:require tag, using the
 attr:depends attribute to specify that extension.
 ====

 == Contents of tag:extension Tags

 Zero or more <<tag-required,tag:require and tag:remove tags>>, in arbitrary
 order.
 Each tag describes a set of interfaces that is respectively required for, or
 removed from, this extension, as described below.

 == Example of an tag:extensions Tag

 [source,xml]
 --------------------------------------
 <extension name="VK_KHR_display_swapchain" number="4" supported="vulkan">
     <require>
         <enum value="9" name="VK_KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION"/>
         <enum value="4" name="VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NUMBER"/>
         <enum value="&quot;VK_KHR_display_swapchain&quot;"
               name="VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME"/>
         <type name="VkDisplayPresentInfoKHR"/>
         <command name="vkCreateSharedSwapchainsKHR"/>
     </require>
 </extension>
 --------------------------------------

 The attr:supported attribute says that the extension is defined for the
 default profile (`vulkan`).
 When processed into a C header for the `vulkan` profile, this results in
 header contents something like (assuming corresponding definitions of the
 specified tag:type and tag:command elsewhere in the XML):

 [source,c]
 --------------------------------------
 #define VK_KHR_display_swapchain 1
 #define VK_KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION 9
 #define VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NUMBER 4
 #define VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME "VK_KHR_display_swapchain"

 typedef struct VkDisplayPresentInfoKHR {
     VkStructureType                             sType;
     const void*                                 pNext;
     VkRect2D                                    srcRect;
     VkRect2D                                    dstRect;
     VkBool32                                    persistent;
 } VkDisplayPresentInfoKHR;

 typedef VkResult (VKAPI_PTR *PFN_vkCreateSharedSwapchainsKHR)(
     VkDevice device, uint32_t swapchainCount,
     const VkSwapchainCreateInfoKHR* pCreateInfos,
     const VkAllocationCallbacks* pAllocator,
     VkSwapchainKHR* pSwapchains);

 #ifndef VK_NO_PROTOTYPES
 VKAPI_ATTR VkResult VKAPI_CALL vkCreateSharedSwapchainsKHR(
     VkDevice                                    device,
     uint32_t                                    swapchainCount,
     const VkSwapchainCreateInfoKHR*             pCreateInfos,
     const VkAllocationCallbacks*                pAllocator,
     VkSwapchainKHR*                             pSwapchains);
 #endif
 --------------------------------------


 [[tag-required]]
 = Required and Removed Interfaces (tag:require and tag:remove Tags)

 A tag:require block defines a set of interfaces (types, enumerants and
 commands) 'required' by a tag:feature or tag:extension.
 A tag:remove block defines a set of interfaces 'removed' by a tag:feature.
 This is primarily for future profiles of an API which may choose to
 deprecate and/or remove some interfaces.
 Extensions should never remove interfaces, although this usage is allowed by
 the schema).
 Except for the tag name and behavior, the contents of tag:require and
 tag:remove tags are identical.

 == Attributes of tag:require and tag:remove Tags

   * attr:profile - optional.
     String name of an API profile.
     Interfaces in the tag are only required (or removed) if the specified
     profile is being generated.
     If not specified, interfaces are required (or removed) for all API
     profiles.
   * attr:comment - optional.
     Arbitrary string (unused).
   * attr:api - optional comma-separated list of <<schema:apiname, API
     names>> requiring or removing these interfaces.
     Interfaces in the tag are only required (or removed) if the requested
     API name matches an element of the attribute.
     If not specified, interfaces are required (or removed) for all APIs.

 [NOTE]
 .Note
 ====
 The attr:api attribute is only supported inside tag:extension tags, since
 tag:feature tags already define a specific API.
 ====

 == Attributes of tag:require Tags

 These attributes are allowed only for a tag:require tag.

   * attr:depends - optional, and only for tag:require tags.
     String containing a boolean expression of one or more API core version
     and extension names.
     The <<depends-expressions, syntax of this string>> is identical to that
     of the tag:extension attr:depends attribute.
     Interfaces in the tag are only required if the expression is satisfied.
 +
 --
 [NOTE]
 .Note
 ====
 attr:depends is a breaking change in Vulkan 1.3.241, replacing the
 `extension` and `feature` attributes.
 ====
 --

 == Contents of tag:require and tag:remove Tags

 Zero or more of the following tags, in any order:

 === Comment Tags

 <<tag-comment, tag:comment>> (as described above).

 === Command Tags

 tag:command specifies an required (or removed) command defined in a
 tag:commands block.
 The tag has no content, but contains attributes:

   * attr:name - required.
     Name of the command.
   * attr:comment - optional.
     Arbitrary string (unused).

 === Enum Tags

 tag:enum specifies an required (or removed) enumerant defined in a tag:enums
 block.
 All forms of this tag support the following attributes:

   * attr:name - required.
     Name of the enumerant.
   * attr:comment - optional.
     Arbitrary string (unused).
   * attr:api - optional comma-separated list of <<schema:apiname, API
     names>> for which this definition is specialized, so that different APIs
     may have different values for the same token.
     This definition is only used if the requested API name matches the
     attribute.
     May be used to address subtle incompatibilities.

 There are two forms of tag:enum tags:

 _Reference enums_ simply pull in the definition of an enumerant given in a
 separate tag:enums block.
 No attributes other than attr:name and attr:comment are supported for them.
 tag:enum tags appearing inside tag:remove tags should always be reference
 enums.
 Reference enums may also be used inside tag:require tags, if the
 corresponding value is defined in a tag:enums block.
 This is typically used for constants not part of an enumerated type.

 _Extension enums_ define the value of an enumerant inline in an tag:feature
 or tag:extensions block.
 Typically these are used to add additional values specified by an extension
 or core feature to an existing enumerated type.
 There are a variety of attributes which are used to specify the value of the
 enumerant:

   * attr:value and attr:type - define a constant value in the same fashion
     as an tag:enum tag in an <<tag-enum,tag:enums>> block.
   * attr:bitpos - define a constant bitmask value in the same fashion as an
     <<tag-enum,tag:enum>> tag in an tag:enums block.
     attr:bitpos is a literal integer bit position in a bitmask.
     The same value and usage constraints apply to this bit position as are
     applied to the <<tag-enum, attr:bitpos attribute of an tag:enum tag.
   * attr:extends - the name of a separately defined enumerated type (e.g. a
     tag:type tag with attr:category``="enum"``) to which the extension
     enumerant is added.
     The enumerated type is required to complete the definition of the
     enumerant, in the same fashion as the attr:requires attribute of a
     tag:type tag.
     If not present, the enumerant is treated as a global constant value.
   * attr:extnumber - an extension number.
     The extension number in turn specifies the starting value of a block
     (range) of values reserved for enumerants defined by or associated with
     the corresponding tag:extension tag with the same attr:number.
     This is used when an extension or core feature needs to extend an
     enumerated type in a block defined by a different extension.
   * Attribute attr:offset - the offset within an extension block.
     If attr:extnumber is not present, the extension number defining that
     block is given by the attr:number attribute of the surrounding
     tag:extension tag.
     The numeric value of an enumerant is computed as defined in the
     ``Assigning Extension Token Values`" section of the <<vulkan-styleguide,
     Vulkan Documentation and Extensions: Procedures and Conventions>>
     document.
   * Attribute attr:dir - if present, the calculated enumerant value will be
     negative, instead of positive.
     Negative enumerant values are normally used only for Vulkan error codes.
     The attribute value must be specified as `dir="-"`.
   * attr:alias - the name of another enumerant this is an alias of.
     An enumerant alias is simply a different name for the same enumerant
     value.
     This is typically used when promoting an enumerant defined by an
     extension to a new core version of the API.
     The old extension enumerant is still defined, but as an alias of the new
     core enumerant.
     It may also be used when token names have been changed as a result of
     profile changes, or for consistency purposes.
   * attr:protect - define a preprocessor protection symbol for the enum in
     the same fashion as a tag:enum tag in an <<tag-enum,tag:enums>> block.

 Not all combinations of attributes are either meaningful or supported.
 The attr:protect attribute may always be present.
 For other attributes, the allowed combinations are:

 .Valid Combinations of attr:enum Attributes for Extension Enums
 |====
 | Description                   | attr:value | attr:bitpos | attr:alias | attr:offset | attr:extnumber | attr:dir | attr:extends
 | Numeric value                 | *Yes*      | No          | No         | No          | No             | No       | *Yes*^2^
 | Bitmask value                 | No         | *Yes*       | No         | No          | No             | No       | *Yes*^2^
 | Alias of another enumerant    | No         | No          | *Yes*      | No          | No             | No       | *Yes*^2^
 | Value added to an enumeration | No         | No          | No         | *Yes*       | *Yes*^1^       | *Yes*^3^ | *Yes*
 |====

 [1]: Optional.
 If attr:extnumber is not present, the tag:enum tag may only be within a
 tag:extension.
 Otherwise, the tag:enum tag may also be within a tag:feature.

 [2]: Optional.
 If attr:extends is not present, the enumerant value is a global constant.
 Otherwise, the value is added to the specified enumeration.

 [3]: Optional.
 If not present, the computed value will be positive.

 Examples of <<tag-required-examples,various types of extension enumerants>>
 are given below.


 === Type Tags

 tag:type specifies a required (or removed) type defined in a tag:types
 block.
 Most types are picked up implicitly by using the tag:type tags of commands,
 but in a few cases, additional types need to be specified explicitly.
 It is unlikely that a type would ever be removed, although this usage is
 allowed by the schema.
 The tag has no content, but contains elements:

   * attr:name - required.
     Name of the type.
   * attr:comment - optional.
     Arbitrary string (unused).


 [[tag-required-examples]]
 == Examples of Extension Enumerants

 Examples of some of the supported extension enumerant tag:enum tags are
 given below.

 [source,xml]
 --------------------------------------
 <extensions>
     <extension name="VK_KHR_test_extension" number="1" supported="vulkan">
         <require>
             <enum value="42" name="VK_KHR_TEST_ANSWER"/>
             <enum bitpos="29" name="VK_KHR_TEST_BITMASK"/>
             <enum offset="0" dir="-" extends="VkResult"
                   name="VK_ERROR_SURFACE_LOST_KHR"/>
             <enum offset="1" extends="VkResult"
                   name="VK_SUBOPTIMAL_KHR"/>
             <enum bitpos="30" extends="VkCullModeFlagBits"
                   name="VK_KHR_TEST_CULL_MODE_BIT"/>
         </require>
     </extension>
 </extensions>
 --------------------------------------

 The corresponding header file will include definitions like this:

 [source,c]
 --------------------------------------
 typedef enum VkResult {
     <previously defined VkResult enumerant values},
     VK_ERROR_SURFACE_LOST_KHR = -1000000000,
     VK_SUBOPTIMAL_KHR = 1000000001,
     VK_KHR_EXTENSION_BIT = 0x80000000,
 };

 #define VK_KHR_test_extension 1
 #define VK_KHR_theanswer 42
 #define VK_KHR_bitmask 0x20000000
 --------------------------------------


 [[tag-formats]]
 = Formats (tag:formats Tag)

 The tag:formats tag contains definitions of each of the image formats which
 are defined for the API.

 == Attributes of tag:formats Tags

 None.

 //  * attr:comment - optional.
 //    Arbitrary string (unused).

 == Contents of tag:formats Tags

 A tag:formats block contains zero or more tag:format tags, each describing
 an image format, in arbitrary order.


 [[tag-format]]
 = Image Format (tag:format Tag)

 Image formats are described in individual tag:format tags.
 An image format corresponds to a Vulkan `VkFormat` enumerant.
 This tag contains information specifying the structure and meaning of
 different parts of the format.
 The meaning of different parts of the format information is described in
 more detail in the "`Format Definition`" section of the <<vulkan-spec,
 Vulkan API Specification>>.

 == Attributes of tag:format Tags

   * attr:name - required.
     Format name, matching a `VkFormat` tag:enum attr:name.
     Example: `name="VK_FORMAT_R8_UNORM"`.
   * attr:class - required.
     Format class.
     A string whose value is shared by a group of formats which may be
     compatible, and is a textual description of something important that
     group has in common.
     Example: `class="8-bit"`.
   * attr:blockSize - required.
     A decimal integer which is the texel block size, in bytes, of the
     format.
   * attr:texelsPerBlock - required
     A decimal integer which is the number of texels in a texel block of the
     format.
   * attr:blockExtent - optional.
     Three-dimensional extent of a texel block.
     A comma-separated list of three decimal integers.
     If not present, `blockExtent="1,1,1"` is assumed.
   * attr:packed - optional.
     A decimal integer which is the number of bits into which the format is
     packed.
     If defined, a single image element in this format can be stored in the
     same space as a scalar type of this bit width.
   * attr:compressed - optional.
     A string whose value is shared by a group of formats which use the same
     general texture compression scheme, and is a textual description of that
     scheme.
     Example: `compressed="ASTC LDR"`.
   * attr:chroma - optional.
     A string used to mark if {YCbCr} samplers are required by default when
     using this format.
     Must be one of the three values `"420"`, `"422"`, or `"444"`
     corresponding to different {YCbCr} encodings.

 == Contents of tag:format Tags

 One or more <<tag-component,tag:component>> tags.
 The order of tag:component tags corresponds to the memory order of
 components of the format.
 Each tag describes the size and format of that component.

 Zero or more <<tag-plane,tag:plane>> tags, in arbitrary order.
 Each tag describes the scale of a specific image plane of the format
 relative to the overall format.

 Zero or more <<tag-spirvimageformat,tag:spirvimageformat>> tags, in
 arbitrary order.
 Each tag describes a SPIR-V format name corresponding to the tag:format.

 == Example of a tag:format Tag

 [source,xml]
 --------------------------------------
 <format name="VK_FORMAT_G16_B16R16_2PLANE_420_UNORM" class="16-bit 2-plane 420" blockSize="6" texelsPerBlock="1" chroma="420">
     <component name="G" bits="16" numericFormat="UNORM" planeIndex="0"/>
     <component name="B" bits="16" numericFormat="UNORM" planeIndex="1"/>
     <component name="R" bits="16" numericFormat="UNORM" planeIndex="1"/>
     <plane index="0" widthDivisor="1" heightDivisor="1" compatible="VK_FORMAT_R16_UNORM"/>
     <plane index="1" widthDivisor="2" heightDivisor="2" compatible="VK_FORMAT_R16G16_UNORM"/>
 </format>
 --------------------------------------


 [[tag-component]]
 = Format Components (tag:component Tag)

 The tag:component tag contains definitions of each of the components which
 are part of an image format.

 == Attributes of tag:component Tags

   * attr:name - required.
     A string specifying the name of this component.
     Must be one of the values `"R"`, `"G"`, `"B"`, `"A"`, `"D"`, or `"S"`
     corresponding to red, green, blue, alpha, depth, and stencil components,
     respectively.
   * attr:bits - required.
     Must be either a decimal integer which is the number of bits in this
     component, or `"compressed"`, corresponding to a specific compression
     scheme.
   * attr:numericFormat - required.
     A string specifying the scalar data type of the component.
     Must be one of the following values:
   ** `"SFLOAT"` - signed floating-point numbers
   ** `"SINT"` - signed integer values in the range [-2^n-1^,2^n-1^-1]
   ** `"SNORM"` - signed normalized values in the range [-1,1]
   ** `"SRGB"` - R, G, and B components are unsigned normalized values that represent values using sRGB nonlinear encoding, while the A component (if one exists) is a regular unsigned normalized value
   ** `"SSCALED"` - signed integer values that get converted to floating-point in the range [-2^n-1^,2^n-1^-1]
   ** `"UFLOAT"` - unsigned floating-point numbers (used by packed, shared exponent, and some compressed formats)
   ** `"UINT"` - unsigned integer values in the range [0,2^n^-1]
   ** `"UNORM"` - unsigned normalized values in the range [0,1]
   ** `"USCALED"` - unsigned integer values that get converted to floating-point in the range [0,2^n^-1]
   * attr:planeIndex - optional.
     A decimal integer specifying which plane this component lies in.
     If present, must correspond to the attr:index attribute value of a
     tag:plane tag for the same tag:component.

 == Contents of tag:component Tags

 None.


 [[tag-plane]]
 = Format Planes (tag:plane Tag)

 The tag:plane tag contains definitions of each of the image planes which are
 part of an image format.

 == Attributes of tag:plane Tags

   * attr:index - required.
     An integer specifying the image plane being defined.
     Image planes are in the range [0,_p_-1] where _p_ is the number of
     planes in the format.
   * attr:widthDivisor - required.
     An integer specifying the relative width of this plane.
     A value of _k_ means that this plane is 1/_k_ the width of the overall
     format.
   * attr:heightDivisor - required.
     An integer specifying the relative height of this plane.
     A value of _k_ means that this plane is 1/_k_ the height of the overall
     format.
   * attr:compatible - required.
     A string naming another, single-plane format that this plane is
     compatible with.
     Must match the attr:name of another attr:format.

 == Contents of tag:plane Tags

 None.


 [[tag-spirvimageformat]]
 = SPIR-V Image Formats (tag:spirvimageformat Tag)

 The tag:spirvimageformat tag specifies the name of a SPIR-V image format
 equivalent to this format.

 == Attributes of tag:spirvimageformat Tags

   * attr:name - required.
     The name of the SPIR-V image format.
     Example: `name="R11fG11fB10f"`.

 == Contents of tag:spirvimageformat Tags

 None.


 [[tag-spirvextensions]]
 = SPIR-V Extensions (tag:spirvextensions Tag)

 The tag:spirvextensions tag contains definitions of each of the SPIR-V
 extensions which are defined for the API.

 == Attributes of tag:spirvextensions Tags

   * attr:comment - optional.
     Arbitrary string (unused).

 == Contents of tag:spirvextensions Tags

 Each tag:spirvextensions block contains zero or more tag:spirvextension tags, each
 describing an single SPIR-V extension, in arbitrary order.


 [[tag-spirvextension]]
 = SPIR-V Extension (tag:spirvextension Tag)

 SPIR-V extensions are described in individual tag:spirvextension tags.
 A SPIR-V extension is enabled by API versions or extensions.

 == Attributes of tag:spirvextension Tags

   * attr:name - required.
     SPIR-V extension name.
     Example: `name="SPV_KHR_variable_pointers"`

 == Contents of tag:spirvextension Tags

 One or more <<tag-spirvenable,tag:enable>> tags, in arbitrary order.
 Each tag describes a single enabling mechanism for the extension.

 == Example of a tag:spirvextensions Tag

 [source,xml]
 --------------------------------------
 <spirvextension name="SPV_KHR_multiview">
     <enable version="VK_VERSION_1_1"/>
     <enable extension="VK_KHR_multiview"/>
 </spirvextension>
 --------------------------------------


 [[tag-spirvcapabilities]]
 = SPIR-V Capabilities (tag:spirvcapabilities Tag)

 The tag:spirvcapabilities tag contains definitions of each of the SPIR-V
 capabilities which are defined for the API.

 == Attributes of tag:spirvcapabilities Tags

   * attr:comment - optional.
     Arbitrary string (unused).

 == Contents of tag:spirvcapabilities Tags

 Each tag:spirvcapabilities block contains zero or more tag:spirvcapability
 tags, each describing an single SPIR-V capability, in arbitrary order.


 [[tag-spirvcapability]]
 = SPIR-V Capability (tag:spirvcapability Tag)

 SPIR-V capabilities are described in individual tag:spirvcapability tags.
 A SPIR-V capability is enabled by API versions, extensions, features, or
 properties.

 == Attributes of tag:spirvcapability Tags

   * attr:name - required.
     SPIR-V capability name.
     Example: `name="SPV_KHR_variable_pointers"`

 == Contents of tag:spirvcapability Tags

 One or more <<tag-spirvenable,tag:enable>> tags, in arbitrary order.
 Each tag describes a single enabling mechanism for the capability.

 == Example of a tag:spirvcapabilities Tag

 [source,xml]
 --------------------------------------
 <spirvcapability name="ImageCubeArray">
     <enable struct="VkPhysicalDeviceFeatures" feature="imageCubeArray" requires="VK_VERSION_1_0"/>
 </spirvcapability>
 <spirvcapability name="GroupNonUniform">
     <enable property="VkPhysicalDeviceVulkan11Properties" member="subgroupSupportedOperations" value="VK_SUBGROUP_FEATURE_BASIC_BIT" requires="VK_VERSION_1_1"/>
 </spirvcapability>
 --------------------------------------


 [[tag-spirvenable]]
 = SPIR-V Enables (tag:enable Tag)

 The tag:enable tag describes a single mechanism in the API which enables a
 tag:spirvextension or tag:spirvcapability.
 There are four forms of tag:enable tags corresponding to different ways the
 API may advertise enablement, though not all forms may be used with
 tag:spirvextension tags.
 Each form is described separately below.

 [[tag-syncstage]]
 = Sync Stage (tag:syncstage Tag)

 The tag:syncstage tag contains definitions of each Pipeline stage.

 == Attributes of tag:syncstage Tags

   * attr:name - required.
     VkPipelineStageFlagBits2 name
   * attr:alias - optional.
     Semantically equivalent name which is an alias of attr:name.

 == Contents of tag:syncstage Tags

 More information about the Pipeline stage using either
 tag:syncequivalent or tag:syncsupport

 [[tag-syncaccess]]
 = Sync Access (tag:syncaccess Tag)

 The tag:syncaccess tag contains definitions of each Access mask.

 == Attributes of tag:syncaccess Tags

   * attr:name - required.
     VkAccessFlagBits2 name
   * attr:alias - optional.
     Semantically equivalent name which is an alias of attr:name.

 == Contents of tag:syncaccess Tags

 More information about the Access mask using either
 tag:syncequivalent or tag:syncsupport

 [[tag-syncpipeline]]
 = Sync Pipeline (tag:syncpipeline Tag)

 The tag:syncpipeline tag contains definitions of each type of Pipeline.

 == Attributes of tag:syncpipeline Tags

   * attr:name - required.
     A unique string identifying the pipeline.

 == Contents of tag:syncpipeline Tags

 The tag:syncpipeline lists each pipeline stage in logical order using
 tag:syncpipelinestage. Stages have extra attributes to describe
 special ordering within the list

 [[tag-syncsupport]]
 = Sync Support (tag:syncsupport Tag)

 The tag:syncsupport tag contains information what support there is for
 a given Sync element.

 == Attributes of tag:syncsupport Tags

   * attr:queues - optional.
     A comma-separated list of Queue types that are supported.
   * attr:stage - optional.
     A comma-separated list of Sync Stages that are supported.
     This is used to cross-reference with tag:syncstage

 [[tag-syncequivalent]]
 = Sync Equivalent (tag:syncequivalent Tag)

 The tag:syncequivalent tag contains information showing a one-to-many
 relationship of Sync elements

 == Attributes of tag:syncsupport Tags

   * attr:stage - optional.
     A comma-separated list of Sync Stages that are the OR logical
     equivalence of the parent Sync Element
   * attr:access - optional.
     A comma-separated list of Sync Accesses that are the OR logical
     equivalence of the parent Sync Element

 == Attributes for API Version Number Enables

   * attr:version - required.
     An API feature name, matching a tag:feature attr:name attribute value.

 If the API version is supported, the SPIR-V extension or capability is
 enabled.

 == Attributes for API Extension Enables

   * attr:extension - required.
     An API extension name, matching an tag:extension attr:name attribute
     value.

 If the API extension is supported and enabled, the SPIR-V extension or
 capability is enabled.

 == Attributes for API Feature Enables

   * attr:struct - required.
     An API feature structure name, matching a tag:struct attr:name attribute
     value.
   * attr:feature - required.
     An API feature name, matching a tag:member tag:name value of the feature
     structure.
   * attr:requires - required.
     A comma-separated list of API feature version numbers and/or extension
     names.
   * attr:alias - optional.
     Another API feature name which is an alias of attr:feature.
     Needed when the same feature is provided by two different API versions
     or extensions.

 If one of the API feature version numbers or extensions in the attr:requires
 list is supported or enabled, respectively; and if the attr:feature name is
 enabled in the feature structure, the SPIR-V capability is enabled.

 API feature enables are not supported for tag:spirvextension tags.

 == Attributes for API Property Enables

   * attr:property - required.
     An API property structure name, matching a tag:struct attr:name
     attribute value.
   * attr:member - required.
     An API property name, matching a tag:member tag:name value of the
     attr:property structure.
   * attr:value - required.
     A value, matching an API tag:enum tag:name value.
     If the property is a bitfield, tag:value must be a bitmask value
     belonging to the attr:member bitfield type.
     Otherwise, tag:value must be an tag:enum name defined for the
     attr:member enumeration type.
   * attr:requires - optional.
     A comma-separated list of API feature version numbers and/or extension
     names.

 If one of the API feature version numbers or extensions in the attr:requires
 list is supported or enabled, respectively; and if the attr:member property
 contains the tag:value bit, or matches the tag:value, the SPIR-V capability
 is enabled.

 API property enables are not supported for tag:spirvextension tags.

 == Contents of tag:enable Tags

 None.


 [[examples]]
 = Examples / FAQ / How Do I?

 For people new to the Registry, it will not be immediately obvious how to
 make changes.
 This section includes some tips and examples that will help you make changes
 to the Vulkan headers by changing the Registry XML description.

 First, follow the steps described to <<starting,get the Vulkan GitHub
 repository>> containing the registry and assemble the tools necessary to
 work with the XML registry.
 Once you are able to regenerate the Vulkan headers from `vk.xml`, you can
 start making changes.


 == General Strategy

 If you are _adding_ to the API, perform the following steps to _create_ the
 description of that API element:

   * For each type, enum group, compile time constant, and command being
     added, create appropriate new tag:type, tag:enums, tag:enum, or
     tag:command tags defining the interface in question.
   * Make sure that all added types and commands appropriately tag their
     dependencies on other types by adding nested tag:type tags.
   * Make sure that each new tag defines the name of the corresponding type,
     enum group, constant, or command, and that structure/union types and
     commands tag the types and names of all their members and parameters.
     This is essential for the automatic dependency process to work.

 If you are _modifying_ existing APIs, just make appropriate changes in the
 existing tags.

 Once the definition is added, proceed to the next section to create
 dependencies on the changed feature.


 == API Feature Dependencies

 When you add new API elements, they will not result in corresponding changes
 in the generated header unless they are _required_ by the interface being
 generated.
 This makes it possible to include different API versions and extensions in a
 single registry and pull them out as needed.
 So you must introduce a dependency on new features in the corresponding
 tag:feature tag.

 There are multiple API versions defined for Vulkan at this time.
 The initial Vulkan 1.0 tag can be found by searching for

 [source,xml]
 --------------------------------------
 <feature api="vulkan" name="VK_VERSION_1_0"
 --------------------------------------

 Inside a tag:feature tag are multiple tag:require tags.
 Some of these tags are used to express extension interactions, and others
 only as a logical grouping mechanism for related parts of that API feature.


 === API Feature Walkthrough

 This section walks through the first few required API features in the
 `vk.xml` tag:feature tag, showing how each requirement pulls in type, token,
 and command definitions and turns those into definitions in the C header
 file `vulkan_core.h`.

 Consider the first few lines of the tag:feature:

 [source,xml]
 --------------------------------------
 <require comment="Header boilerplate">
     <type name="vk_platform"/>
 </require>
 <require comment="API constants">
     <enum name="VK_MAX_PHYSICAL_DEVICE_NAME"/>
     <enum name="VK_MAX_EXTENSION_NAME"/>
     ...
 </require>
 <require comment="Device initialization">
     <command name="vkCreateInstance"/>
     ...
 --------------------------------------

 The first tag:require block says to require a type named `vk_platform`.
 If you look at the beginning of the tag:types section, there is a
 corresponding definition section:

 [source,xml]
 --------------------------------------
 <type name="vk_platform">#include "vk_platform.h"
 #define VK_MAKE_VERSION(major, minor, patch) \
     ((major &lt;&lt; 22) | (minor &lt;&lt; 12) | patch)
     ...
 --------------------------------------

 This section is invoked by the requirement and emits a bunch of boilerplate
 C code.
 The explicit dependency is not strictly required since `vk_platform` will be
 required by many other types, but placing it first causes this to appear
 first in the output file.

 Note that `vk_platform` does not correspond to an actual C type, but instead
 to a collection of freeform preprocessor includes and macros and comments.
 Most other tag:type tags do define a specific type and are much simpler, but
 this approach can be used to inject arbitrary C into the Vulkan headers
 *when there is no other way*.
 In general inserting arbitrary C is strongly discouraged outside of specific
 special cases like this.

 The next tag:require block pulls in some compile time constants.
 These correspond to the definitions found in the first tag:enums section of
 `vk.xml`:

 [source,xml]
 --------------------------------------
 <enums name="API Constants"
        comment="Vulkan hardcoded constants - not an enumerated type, part of the header boilerplate">
     <enum value="256"        name="VK_MAX_PHYSICAL_DEVICE_NAME"/>
     <enum value="256"        name="VK_MAX_EXTENSION_NAME"/>
     ...
 --------------------------------------

 The third tag:require block starts pulling in some Vulkan commands.
 The first command corresponds to the following definition found in the
 tag:commands section of `vk.xml`:

 [source,xml]
 --------------------------------------
 <commands>
     <command>
         <proto><type>VkResult</type> <name>vkCreateInstance</name></proto>
         <param>const <type>VkInstanceCreateInfo</type>* <name>pCreateInfo</name></param>
         <param><type>VkInstance</type>* <name>pInstance</name></param>
     </command>
     ...
 --------------------------------------

 In turn, the tag:command tag requires the tag:types `VkResult`,
 `VkInstanceCreateInfo`, and `VkInstance` as part of its definition.
 The definitions of these types are determined as follows:

 For `VkResult`, the corresponding required tag:type is:

 [source,xml]
 --------------------------------------
 <type name="VkResult" category="enum"/>
 --------------------------------------

 Since this is an enumeration type, it simply links to an tag:enums tag with
 the same name:

 [source,xml]
 --------------------------------------
 <enums name="VkResult" type="enum" comment="API result codes">
         <comment>Return codes (positive values)</comment>
     <enum value="0"     name="VK_SUCCESS"/>
     <enum value="1"     name="VK_UNSUPPORTED"/>
     <enum value="2"     name="VK_NOT_READY"/>
     ...
         <comment>Error codes (negative values)</comment>
     <enum value="-1"    name="VK_ERROR_OUT_OF_HOST_MEMORY" comment="A host memory allocation has failed"/>
     ...
 --------------------------------------

 For `VkInstanceCreateInfo`, the required tag:type is:

 [source,xml]
 --------------------------------------
 <type category="struct" name="VkInstanceCreateInfo">
     <member values="VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO"><type>VkStructureType</type> <name>sType</name></member>
     <member>const void*                         <name>pNext</name></member>
     <member>const <type>VkApplicationInfo</type>* <name>pAppInfo</name></member>
     <member>const <type>VkAllocCallbacks</type>* <name>pAllocCb</name></member>
     <member><type>uint32_t</type>               <name>extensionCount</name></member>
     <member>const <type>char</type>*const*      <name>ppEnabledExtensionNames</name></member>
 </type>
 --------------------------------------

 This is a structure type, defining a C `struct` with all the members defined
 in each tag:member tag in order.
 In addition, it requires some other types, whose definitions are located by
 name in exactly the same fashion.

 For the final direct dependency of the command, `VkInstance`, the required
 tag:type is:

 [source,xml]
 --------------------------------------
     <comment>Types which can be void pointers or class pointers, selected at compile time</comment>
 <type>VK_DEFINE_BASE_HANDLE(<name>VkObject</name>)</type>
 <type>VK_DEFINE_DISP_SUBCLASS_HANDLE(<name>VkInstance</name>, <type>VkObject</type>)</type>
 --------------------------------------

 In this case, the type `VkInstance` is defined by a special compile time
 macro which defines it as a derived class of `VkObject` (for `C```) or a
 less typesafe definition (for C).
 This macro is not part of the type dependency analysis, just the boilerplate
 used in the header.

 If these are the only tag:feature dependencies in `vk.xml`, the resulting
 `vulkan_core.h` header will look like this:

 [source,c]
 --------------------------------------
 #ifndef VULKAN_H_
 #define VULKAN_H_ 1

 #ifdef __cplusplus
 extern "C" {
 #endif

 /*
 ** Copyright 2015-2023 The Khronos Group Inc.
     ...
 */

 /*
 ** This header is generated from the Khronos Vulkan XML API Registry.
 **
 ** Generated on date 20170208
 */


 #define VK_VERSION_1_0 1
 #include "vk_platform.h"
 #define VK_MAKE_VERSION(major, minor, patch) \
     ((major << 22) | (minor << 12) | patch)

 // Vulkan API version supported by this file
 #define VK_API_VERSION VK_MAKE_VERSION(0, 104, 0)

 #if defined (__cplusplus) && (VK_UINTPTRLEAST64_MAX == UINTPTR_MAX)
     #define VK_TYPE_SAFE_COMPATIBLE_HANDLES 1
 #endif

 #if defined(VK_TYPE_SAFE_COMPATIBLE_HANDLES) && !defined(VK_DISABLE_TYPE_SAFE_HANDLES)
     #define VK_DEFINE_PTR_HANDLE(_obj) struct _obj##_T { char _placeholder; }; typedef _obj##_T* _obj;
     #define VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base) struct _obj##_T : public _base##_T {}; typedef _obj##_T* _obj;

     #define VK_DEFINE_BASE_HANDLE(_obj) VK_DEFINE_PTR_HANDLE(_obj)
     #define VK_DEFINE_DISP_SUBCLASS_HANDLE(_obj, _base) VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base)
     #define VK_DEFINE_NONDISP_SUBCLASS_HANDLE(_obj, _base) VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base)
 #else
     #define VK_DEFINE_BASE_HANDLE(_obj) typedef VkUintPtrLeast64 _obj;
     #define VK_DEFINE_DISP_SUBCLASS_HANDLE(_obj, _base) typedef uintptr_t _obj;
     #define VK_DEFINE_NONDISP_SUBCLASS_HANDLE(_obj, _base) typedef VkUintPtrLeast64 _obj;
 #endif

 typedef enum {
     VK_SUCCESS = 0,
     VK_UNSUPPORTED = 1,
     VK_NOT_READY = 2,
     ...
 } VkResult;
 typedef enum {
     VK_STRUCTURE_TYPE_APPLICATION_INFO = 0,
     ...
 } VKStructureType;
 typedef struct {
     VkStructureType                             sType;
     const void*                                 pNext;
     const char*                                 pAppName;
     uint32_t                                    appVersion;
     const char*                                 pEngineName;
     uint32_t                                    engineVersion;
     uint32_t                                    apiVersion;
 } VkApplicationInfo;
 typedef enum {
     VK_SYSTEM_ALLOC_TYPE_API_OBJECT = 0,
     ...
 } VkSystemAllocType;
 typedef void* (VKAPI_PTR *PFN_vkAllocFunction)(
     void*                           pUserData,
     size_t                          size,
     size_t                          alignment,
     VkSystemAllocType               allocType);
 typedef void (VKAPI_PTR *PFN_vkFreeFunction)(
     void*                           pUserData,
     void*                           pMem);
 typedef struct {
     void*                                       pUserData;
     PFN_vkAllocFunction                         pfnAlloc;
     PFN_vkFreeFunction                          pfnFree;
 } VkAllocCallbacks;
 typedef struct {
     VkStructureType                             sType;
     const void*                                 pNext;
     const VkApplicationInfo*                    pAppInfo;
     const VkAllocCallbacks*                     pAllocCb;
     uint32_t                                    extensionCount;
     const char*const*                           ppEnabledExtensionNames;
 } VkInstanceCreateInfo;
 VK_DEFINE_BASE_HANDLE(VkObject)
 VK_DEFINE_DISP_SUBCLASS_HANDLE(VkInstance, VkObject)
 #define VK_MAX_PHYSICAL_DEVICE_NAME       256
 #define VK_MAX_EXTENSION_NAME             256
 typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)(const VkInstanceCreateInfo* pCreateInfo, VkInstance* pInstance);
 #ifndef VK_NO_PROTOTYPES
 VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance(
     const VkInstanceCreateInfo*                 pCreateInfo,
     VkInstance*                                 pInstance);
 #endif

 #ifdef __cplusplus
 }
 #endif

 #endif
 --------------------------------------

 Note that several additional types are pulled in by the type dependency
 analysis, but only those types, commands, and tokens required by the
 specified features are generated.


 [[compile-time-constants]]
 == How to Add a Compile Time Constant

 Go to the desired tag:feature or tag:extension tag.
 Add (if not present) a nested tag:require block labelled

 [source,xml]
 --------------------------------------
 <require comment="API constants">
 --------------------------------------

 In this block, add an (appropriately indented) tag like

 [source,xml]
 --------------------------------------
     <enum name="VK_THE_ANSWER"/>
 --------------------------------------

 Then go to the tag:enums block labelled

 [source,xml]
 --------------------------------------
 <enums comment="Misc. hardcoded constants - not an enumerated type">
 --------------------------------------

 In this block, add a tag whose attr:name attribute matches the attr:name you
 defined above and whose attr:value attribute is the value to give the
 constant:

 [source,xml]
 --------------------------------------
     <enum value="42" type="uint32_t" name="VK_THE_ANSWER"/>
 --------------------------------------

 The attr:type attribute must be present, and must have one of the allowed
 values `uint32_t`, `uint64_t`, or `float`.


 [[compile-time-constants-format]]
 == Allowed Format of Compile Time Constants

 The attr:value attribute must be a legal C99 constant scalar expression when
 evaluated at compilation time.
 Allowed expressions are additionally restricted to the following syntax:

   * a single C decimal integer or floating-point value
   * optionally prefixed with `~`
   * optionally suffixed with `U`, `UL`, `ULL`, or `F`
   * and the entire expression optionally surrounded by paired `(` and `)`.


 == How to Add a Struct or Union Type

 For this example, assume we want to define a type corresponding to a C
 `struct` defined as follows:

 [source,c]
 --------------------------------------
 typedef struct {
     VkStructureType          sType;
     const void*              pNext;
     const VkApplicationInfo* pAppInfo;
     const VkAllocCallbacks*  pAllocCb;
     uint32_t                 extensionCount;
     const char*const*        ppEnabledExtensionNames;
 } VkInstanceCreateInfo;
 --------------------------------------

 If `VkInstanceCreateInfo` is the type of a parameter of a command in the
 API, make sure that command's definition (see below for how to add a
 command) puts `VkInstanceCreateInfo` in nested tag:type tags where it is
 used.

 Otherwise, if the struct type is not used directly by a command in the API,
 nor required by a chain of type dependencies for other commands, an explicit
 tag:type dependency should be added to the tag:feature tag.
 Go to the tag:types tag and search for the nested block labelled

 [source,xml]
 --------------------------------------
 <require comment="Types not directly used by the API. Include e.g. structs that are not parameter types of commands, but still defined by the API.">
     ...
 --------------------------------------

 In this block, add a tag whose attr:name attribute matches the attr:name of
 the struct type being defined:

 [source,xml]
 --------------------------------------
 <require comment="API types not used by commands">
     <type name="VkInstanceCreateInfo"/>
     ...
 --------------------------------------

 Then go to the tag:types tag and add a new tag:type tag defining the struct
 names and members, somewhere below the corresponding comment, like this:

 [source,xml]
 --------------------------------------
 <types>
     ...
         <comment>Struct types</comment>
     <type category="struct" name="VkInstanceCreateInfo">
         <member><type>VkStructureType</type>
                 <name>sType</name></member>
         <member>const void*
                 <name>pNext</name></member>
         <member>const <type>VkApplicationInfo</type>*
                 <name>pAppInfo</name></member>
         <member>const <type>VkAllocCallbacks</type>*
                 <name>pAllocCb</name></member>
         <member><type>uint32_t</type>
                 <name>extensionCount</name></member>
         <member>const <type>char</type>*const*
                 <name>ppEnabledExtensionNames</name></member>
     </type>
     ...
 --------------------------------------

 If any of the member types are types also defined in the header, make sure
 to enclose those type names in nested tag:type tags, as shown above.
 Basic C types should not be tagged.

 If the type is a C `union`, rather than a `struct`, then set the value of
 the attr:category attribute to `"union"` instead of `"struct"`.


 == How to Add an Enumerated Type

 For this example, assume we want to define a type corresponding to a C
 `enum` defined as follows:

 [source,c]
 --------------------------------------
 typedef enum {
     VK_DEVICE_CREATE_VALIDATION_BIT = 0x00000001,
     VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT = 0x00000002;
 } VkDeviceCreateFlagBits.
 --------------------------------------

 If `VkDeviceCreateFlagBits` is the type of a parameter to a command in the
 API, or of a member in a structure or union, make sure that command
 parameter or struct member's definition puts `VkDeviceCreateFlagBits` in
 nested tag:type tags where it is used.

 Otherwise, if the enumerated type is not used directly by a command in the
 API, nor required by a chain of type dependencies for commands and structs,
 an explicit tag:type dependency should be added to the tag:feature tag in
 exactly the same fashion as described above for `struct` types.

 Next, go to the line labelled

 [source,xml]
 --------------------------------------
 <comment>Vulkan enumerant (token) definitions</comment>
 --------------------------------------

 At an appropriate point below this line, add an tag:enums tag whose
 attr:name attribute matches the tag:type name `VkDeviceCreateFlagBits`, and
 whose contents correspond to the individual fields of the enumerated type:

 [source,xml]
 --------------------------------------
 <enums name="VkDeviceCreateFlagBits" type="bitmask">
     <enum bitpos="0" name="VK_DEVICE_CREATE_VALIDATION_BIT"/>
     <enum bitpos="1" name="VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT"/>
 </enums>
 --------------------------------------

 Several other attributes of the tag:enums tag can be set.
 In this case, the attr:type attribute is set to `"bitmask"`, indicating that
 the individual enumerants represent elements of a bitmask.

 The individual tag:enum tags define the enumerants, just like the definition
 for compile time constants described above.
 In this case, because the enumerants are bits in a bitmask, their values are
 specified using the attr:bitpos attribute.
 The value of this attribute must be an integer in the range [0,30]
 specifying a single bit number, and the resulting value is printed as a
 hexadecimal constant corresponding to that bit.

 It is also possible to specify enumerant values using the attr:value
 attribute, in which case the specified numeric value is passed through to
 the C header unchanged.


 [[adding-bitflags]]
 == How to Add Bit Flags

 Bit masks are defined by two types in the xml - the type of the mask itself,
 and the type of the valid flags.

 For this example, assume we want to define bit flags that can handle up to
 64 independent values as follows:

 [source,c]
 --------------------------------------
 // Flag bits for VkExampleFlagBits
 typedef VkFlags64 VkExampleFlagBits;
 static const VkExampleFlagBits VK_EXAMPLE_NONE = 0;
 static const VkExampleFlagBits VK_EXAMPLE_FIRST_BIT = 0x00000001;
 static const VkExampleFlagBits VK_EXAMPLE_SECOND_BIT = 0x00000002;

 typedef VkFlags64 VkExampleFlags;
 --------------------------------------

 An explicit tag:type dependency should be added to the tag:feature tag in
 exactly the same fashion as described above for `struct` types.

 Firstly, a definition is needed for the flags type used as a parameter to
 commands or member of functions.
 Go to the line labelled:

 [source,xml]
 --------------------------------------
 <comment>Bitmask types</comment>
 --------------------------------------

 At the end of the list of `VkFlags` and `VkFlags64` types, add a definition
 of the flags type like so:

 [source,xml]
 --------------------------------------
 <type bitvalues="VkExampleFlagBits" category="bitmask">typedef <type>VkFlags64</type> <name>VkExampleFlags</name>;</type>
 --------------------------------------

 The attr:category defines this as a `"bitmask"` type.
 The attr:bitvalues attribute identifies the `*FlagBits` entry defining the
 flag bits associated with this type.

 Next, go to the line labelled:

 [source,xml]
 --------------------------------------
 <comment>Types generated from corresponding enums tags below</comment>
 --------------------------------------

 At an appropriate point in the list of enum types after this comment, add
 the following line:

 [source,xml]
 --------------------------------------
 <type name="VkExampleFlagBits" category="enum"/>
 --------------------------------------

 This defines a type for the flag bits for generators that need it.
 The attr:category attribute of `"enum"` identifies that this is an
 enumerated type.

 Finally, go to the line labelled:

 [source,xml]
 --------------------------------------
 <comment>Vulkan enumerant (token) definitions</comment>
 --------------------------------------

 At the end of the list of enum definitions below this line, add an tag:enums
 tag whose attr:name attribute matches the tag:type name `VkExampleFlagBits`,
 and whose contents correspond to the individual fields of the enumerated
 type:

 [source,xml]
 --------------------------------------
 <enums name="VkExampleFlagBits" type="bitmask" bitwidth="64">
     <enum value="0" name="VK_EXAMPLE_NONE"/>
     <enum bitpos="0" name="VK_EXAMPLE_FIRST_BIT"/>
     <enum bitpos="1" name="VK_EXAMPLE_SECOND_BIT"/>
 </enums>
 --------------------------------------

 The attr:type attribute is set to `"bitmask"`, indicating that the
 individual enumerants represent elements of a bitmask.
 The attr:bitwidth attribute is set to `"64"` indicating that this is a
 64-bit flag type.

 The individual tag:enum tags define the enumerants, just like the definition
 for compile time constants described above.
 In this case, a "no flags" type is defined in `VK_EXAMPLE_NONE` with the
 attr:value attribute defining it to have a hard value of 0.
 The other types have their values are specified using the attr:bitpos
 attribute, as these are actual bit flag values.
 The value of this attribute must be an integer in the range [0,63]
 specifying a single bit number, and the resulting value is printed as a
 hexadecimal constant corresponding to that bit.


 === 32-bit Flags

 Bit flags can also be defined using 32-bit C enum types.
 Doing so is broadly similar to 64-bit bit flags, but with a few key
 differences.
 For this example, assume we want to define the same type as above, but
 corresponding to a C `enum` and flags type defined as follows:

 [source,c]
 --------------------------------------
 typedef enum VkExampleFlagBits {
     VK_EXAMPLE_NONE
     VK_DEVICE_CREATE_VALIDATION_BIT = 0x00000001,
     VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT = 0x00000002;
 } VkExampleFlagBits;

 typedef VkFlags VkExampleFlags;
 --------------------------------------

 To add this to the xml, entries need to be added to the XML in the same way
 as above, but with slightly different attributes:

 For the flag type definition, the entry should use `VkFlags` instead of
 `VkFlags64`, and require the flag bits type, instead of specifying the
 attr:bitvalues attribute:

 [source,xml]
 --------------------------------------
 <type requires="VkExampleFlagBits" category="bitmask">typedef <type>VkFlags</type> <name>VkExampleFlags</name>;</type>
 --------------------------------------

 For the definition of the enumerated flag values themselves, the bitwidth
 needs to either be changed to `"32"`, or omitted entirely (which defaults to
 a bitwidth of 32) as follows:

 [source,xml]
 --------------------------------------
 <enums name="VkExampleFlagBits" type="bitmask">
 --------------------------------------

 Note that 32-bit bitmasks must use an integer in the range [0,30] - C enums
 are only guaranteed to support signed 32-bit integer values, and defining an
 unsigned value for the 31st bit could change the size of the enum type.
 The generator scripts will warn about values exceeding this range.


 == How to Add a Command

 For this example, assume we want to define the command:

 [source,c]
 --------------------------------------
 VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance(
     const VkInstanceCreateInfo*                 pCreateInfo,
     VkInstance*                                 pInstance);
 --------------------------------------

 Commands must always be explicitly required in the tag:feature tag.
 In that tag, you can use an existing tag:require block including API
 features which the new command should be grouped with, or define a new
 block.
 For this example, add a new block, and require the command by using the
 tag:command tag inside that block:

 [source,xml]
 --------------------------------------
 <feature api="vulkan" name="VK_VERSION_1_0" number="1.0" comment="Vulkan core API interface definitions">
     ...
     <require comment="Device initialization">
         <command name="vkCreateInstance"/>
     </require>
     ...
 </feature>
 --------------------------------------

 The tag:require block may include a attr:comment attribute whose value is a
 descriptive comment of the contents required within that block.
 The comment is not currently used in header generation, but might be in the
 future, so use comments which are polite and meaningful to users of the
 generated header files.

 Then go to the tag:commands tag and add a new tag:command tag defining the
 command, preferably sorted into alphabetic order with other commands for
 ease of reading, as follows:

 [source,xml]
 --------------------------------------
 <commands comment="Vulkan command definitions">
     ...
     <command>
         <proto><type>VkResult</type>
                <name>vkCreateInstance</name></proto>
         <param>const <type>VkInstanceCreateInfo</type>*
                <name>pCreateInfo</name></param>
         <param><type>VkInstance</type>*
                <name>pInstance</name></param>
     </command>
     ...
 </commands>
 --------------------------------------

 The tag:proto tag defines the return type and function name of the command.
 The tag:param tags define the command's parameters in the order in which
 they are passed, including the parameter type and name.
 The contents are laid out in the same way as the structure tag:member tags
 described previously.


 == More Complicated API Representations

 The registry schema can represent a good deal of additional information, for
 example by creating multiple tag:feature tags defining different API
 versions and extensions.
 This capability is not yet relevant to Vulkan.
 Those capabilities will be documented as they are needed.


 == More Complicated Output Formats and Other Languages

 The registry schema is oriented towards C-language APIs.
 Types and commands are defined using syntax which is a subset of C,
 especially for structure members and command parameters.
 It would be possible to use a language-independent syntax for representing
 such information, but since we are writing a C API, any such representation
 would have to be converted into C anyway at some stage.

 The `vulkan.h` header is written using an _output generator_ object in the
 Python scripts.
 This output generator is specialized for C, but the design of the scripts is
 intended to support writing output generators for other languages as well as
 purposes such as documentation (e.g. generating asciidoc fragments
 corresponding to types and commands for use in the API specification and
 reference pages).
 When targeting other languages, the amount of parsing required to convert
 type declarations into other languages is small.
 However, it will probably be necessary to modify some of the boilerplate C
 text, or specialize the tags by language, to support such generators.


 == Additional Semantic Tagging

 The schema is being extended to support semantic tags describing various
 properties of API features, such as:

   * constraints on allowed scalar values to function parameters (non-`NULL`,
     normalized floating-point, etc.)
   * length of arrays corresponding to function pointer parameters
   * miscellaneous properties of commands such as whether the application or
     system is responsible for threadsafe use; which queues they may be
     issued on; whether they are aliases or otherwise related to other
     commands; etc.

 These tags will be used by other tools for purposes such as helping create
 validation layers, generating serialization code, and so on.
 We would like to eventually represent everything about the API that is
 amenable to automatic processing within the registry schema.
 Please make suggestions on the GitHub issue tracker.


 [[general:stability]]
 == Stability of the XML Database and Schema

 The Vulkan XML schema is evolving in response to corresponding changes in
 the Vulkan API and ecosystem.
 Most such change will probably be confined to adding attributes to existing
 tags and properly expressing the relationships to them, and making API
 changes corresponding to accepted feature requests.
 Changes to the schema should be described in the <<changelog,change log>> of
 this document.
 Changes to the `.xml` files and Python scripts are logged in GitHub history.


 [[changelog]]
 = Change Log

   * 2023-06-28 - remove support for tag:member and tag:param attr:optional
     attribute value `"false"` (internal issue 3548).
   * 2023-06-14 - removed deprecated attr:start and attr:end from tag:enums
   * 2023-05-18 - Add tag:sync to help define all sync objects in the XML
   * 2023-03-29 - add tag:extension attr:ratified attribute to express
     ratification status.
   * 2023-02-26 - add normative references section, cite it as needed, and
     update description of tag:extension tags to refer to the style guide for
     computing numeric enumerant values (public issue 2069).
   * 2023-02-22 - specify that attr:depends expressions are
     <<depends-expressions, evaluated left-to-right>> for operators of the
     same precedence (public issue 2062).
   * 2023-02-14 - replace tag:extension attributes attr:requiresCore and
     attr:requires, and tag:require attributes attr:feature and
     attr:extension, by a new attr:depends attribute. This is an intentional
     breaking change to support a more flexible and consistent expression
     syntax for these dependencies (internal issues 2883, 3272).
   * 2023-01-11 - add attr:deprecated attribute to tag:enum, tag:type,
     and tag:type tag:member tags.
   * 2022-11-23 - update tag:command attr:queues syntax to include all queue
     types currently in use.
   * 2022-08-12 - update tag:requires attr:extension syntax to support
     logical OR and AND constructs for multiple extensions (internal issue
     2922).
   * 2022-07-11 - Add attr:videocoding attribute to <<tag-command,tag:command>>
     tags to indicate whether a command buffer command can be recorded inside,
     outside, or both inside and outside of a video coding scope.
   * 2022-06-29 - Add tag:command attribute attr:tasks (internal issue 3117).
   * 2022-06-22 - Add attr:validstructs attribute to command
     <<tag-command:param:attr, tag:param>> tags when using an abstract
     `VkBaseInStructure` or `VkBaseOutStructure` as the formal parameter
     type.
   * 2022-06-16 - Add `VkSparseImageFormatProperties*` to the list of
     structure types allowed to have 'limittype' member attributes.
   * 2022-06-08 - Add `exact`, `bits`, `mul` and `pot` limit types.
   * 2022-06-08 - Update description of types to which the attr:limittype
     attribute of structure tag:member tags can be applied (internal issue
     3101).
   * 2022-06-08 - Update description of tag:extension attr:requires attribute
     such that the specified extensions must be *enabled*, not just
     *supported*. This is consistent with the following NOTE, the
     specification description of "`required extensions`", and actual use in
     the XML of this attribute (internal issue 3116).
   * 2021-12-13 - Add attr:api attribute to the tag:member and tag:param
     tags.
   * 2021-11-29 - Add attr:api attribute to the tag:command tag.
   * 2021-10-11 - Add description of the tag:formats tag for describing
     Vulkan `VkFormat` image formats, and of the tag:spirvextensions and
     tag:spirvcapabilities tags for describing enabling mechanisms for SPIR-V
     extensions (internal issue 2484).
   * 2021-09-13 - Further clarify that attr:api and attr:supported attributes
     are comma-separated list of API names (internal issue 2809).
   * 2021-08-22 - Update introductory descriptions of toolchain and scripts.
   * 2021-08-15 - Add an explicit description of the tag:enum attr:extends
     attribute as introducing a requirement for the enumerated type being
     extended.
   * 2021-07-12 - Note that tag:extension tags describing instance extensions
     must not have dependencies on device extensions (internal issue 2387).
   * 2021-06-14 - Add an `objecttype` attribute which specifies the
     relationship between a Vulkan handle and another member or parameter
     specifying the type of object that handle refers to (public issue 1536).
   * 2021-06-06 - Update description of the attr:supported attribute of
     <<tag-extension, tag:extension tags>> to mandate that `disabled`
     extensions are not processed (public issue 1549).
   * 2021-04-21 - Add the attr:limittype attribute to <<tag-type, structure
     tag:member tags>>, to describe how queried limits are interpreted
     (internal issue 2427).
   * 2021-03-30 - Add a description of the <<compile-time-constants-format,
     allowed format of compile time constants>> (internal merge request
     4451).
   * 2021-03-22 - Update allowed values for the attr:type attribute of
     tag:enum tags and make it mandatory (internal issue 2564).
   * 2021-01-11 - Expand the scope of the attr:optional attribute tag:member
     and tag:param tags to specify that the member or parameter may be 0 for
     all scalar types, not just bitmasks and array sizes (internal issue
     2435).
   * 2020-11-23 - Add `objtypeenum` attribute to <<tag:type, tag:type>> tags
     to link the object name to the corresponding `VK_OBJECT_TYPE_*`
     enumerant, if any (internal issue 2393).
   * 2020-11-22 - Add requirement that `pNext` members have the
     `optional="true"` attribute set (internal issue 2428).
   * 2020-10-14 - Remove advice to set the attr:noautovalidity attribute on
     the `pNext` member of extending structures in the <<tag:type, tag:type
     tag>>, since the validity generator scripts now take care of this
     (internal issue 2335).
   * 2020-06-02 - Add description of how to switch between 64- and 32-bit
     flags.
   * 2020-05-07 - Update description of <<schema:apiname, API Names>> to
     current usage, including allowing specifying multiple API names for a
     given feature or extension.
   * 2020-04-29 - Expand use of attr:category `basetype` in tag:type tags to
     include external API types.
   * 2020-02-20 - Clarify that tag:enum tags inside tag:remove tags must be
     reference enums, not containing attributes defining values.
   * 2020-01-13 - Restrict attr:bitpos to [0,30] to avoid poorly defined
     compiler behavior.
   * 2019-08-25 - Add attr:sortorder attribute to tag:feature and
     tag:extension tags.
   * 2018-12-06 - Specify that command aliases are not guaranteed to resolve
     to the same entry point in the underlying layer stack, matching a
     related clarification in the Vulkan Specification.
   * 2018-10-01 - Add description of the default value of attr:optional
     member and parameter attributes, if not specified.
   * 2018-08-28 - Add optional attr:provisional attribute to tag:extension
     tags.
   * 2018-07-07 - Add optional attr:promotedto, attr:deprecatedby, and
     attr:obsoletedby attributes to tag:extension tags.
   * 2018-06-25 - Remove attr:vendorids tags for Khronos vendor IDs.
   * 2018-05-08 - Add tag:driverids and tag:driverid tags for describing
     Vulkan driver implementation identification information.
   * 2018-04-15 - Add attr:requiresCore.
   * 2018-03-07 - Updated for Vulkan 1.1 release.
   * 2018-02-21 - Add descriptions of the attr:extnumber and attr:alias
     attributes used for defining tag:enum attributes, the attr:alias
     attribute used for defining tag:type aliases, the attr:name and
     attr:alias attributes used for defining tag:command aliases, the
     attr:platform attribute of tag:extension tags, and the attr:feature
     attribute of tag:require tags; and update the document to the header
     naming and grouping scheme used starting in Vulkan 1.1.
   * 2018-01-07 - Add tag:platforms and tag:platform tags for describing
     Vulkan platform names and preprocessor symbols.
   * 2017-09-10 - Define syntax of member and parameter attr:altlen
     attributes, for use by code generators.
   * 2017-09-01 - Define syntax of member and parameter attr:len attributes
     consistently and correctly for current uses of latexmath:
   * 2017-08-24 - Note that the tag:extension attribute attr:type must be
     specified if the extension is not disabled.
   * 2017-07-27 - Finish removing validextensionstructs attribute and
     replacing it with structextends.
   * 2017-07-14 - Add comment attributes or tags as valid content in several
     places, replacing XML comments which could not be preserved by XML
     transformation tools.
   * 2017-02-20 - Change to asciidoctor markup and move into the
     specification source directory for ease of building.
   * 2016-09-27 - Remove tag:validity and tag:usage tags, since these
     explicit usage statements have been moved to the specification source.
   * 2016-08-26 - Update for the single-branch model.
   * 2016-07-28 - Add attr:type and attr:requires attributes to tag:extension
     tags.
   * 2016-02-22 - Change math markup in attr:len attributes to use asciidoc
     `latexmath:[$` and `$]` delimiters.
   * 2016-02-19 - Add attr:successcodes and attr:errorcodes attributes of
     tag:command tags.
     Add a subsection to the introduction describing the schema choices and
     how to file issues against the registry.
   * 2016-02-07 - Add attr:vendorids tags for Khronos vendor IDs.
   * 2015-12-10 - Add attr:author and attr:contact attributes for
     tag:extension tags.
   * 2015-12-07 - Move `vulkan/vulkan.h` to a subdirectory.
   * 2015-12-01 - Add tag:tags tags for author tags.
   * 2015-11-18 - Bring documentation and schema up to date for extension
     enumerants.
   * 2015-11-02 - Bring documentation and schema up to date with several
     recent merges, including tag:validity tags.
     Still out of date WRT extension enumerants, but that will change soon.
   * 2015-09-08 - Rename `threadsafe` attribute to attr:externsync, and
     `implicitunsafeparams` tag to attr:implicitexternsync.
   * 2015-09-07 - Update tag:command tag description to remove the
     attr:threadsafe attribute and replace it with a combination of
     attr:threadunsafe attributes on individual parameters, and
     tag:implicitunsafeparams tags describing additional unsafe objects for
     the command.
   * 2015-08-04 - Add `basetype` and `funcpointer` attr:category values for
     type tags, and explain the intended use and order in which types in each
     category are emitted.
   * 2015-07-02 - Update description of Makefile targets.
     Add descriptions of attr:threadsafe, attr:queues, and attr:renderpass
     attributes of <<tag-command,tag:command>> tags, and of attr:modified
     attributes of <<tag-command:param,tag:param>> tags.
   * 2015-06-17 - add descriptions of allowed attr:category attribute values
     of tag:type tags, used to group and sort related categories of
     declarations together in the generated header.
   * 2015-06-04 - Add <<examples,examples of making changes and additions>>
     to the registry.
   * 2015-06-03 - Move location to new `vulkan` Git repository.
     Add definition of tag:type tags for C struct/unions.
     Start adding <<examples,examples of making changes>>.
   * 2015-06-02 - Branch from OpenGL specfile documentation and bring up to
     date with current Vulkan schema.
   * 2015-07-10 - Remove contractions to match the style guide.
   * 2015-07-19 - Move this document from LaTeX to asciidoc source format and
     make minor changes to markup.