Vulkan-Docs/registry.txt

// Copyright (c) 2013-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

= The Khronos Vulkan^(R)^ API Registry
Jon Leech
:data-uri:
:icons: font
:toc2:
:toclevels: 3
:max-width: 100
:numbered:
:doctype: book
:imagewidth: 800
:fullimagewidth: width="800"
:cl: :

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

:leveloffset: 1

<<<<

include::copyright-ccby.txt[]

<<<<

[[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 `master` branch.

[NOTE]
.Note
====
The older version of the registry in the `1.0` branch is out of date.
====

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 in under
`include/vulkan/`.


== 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. We have considered separating the registry from the
specification source into a separate repository, but since there is so
much specification valid usage language imbedded in the registry XML,
this is unlikely to happen.


[[starting]]
= Getting Started

See
https://gitlab.khronos.org/vulkan/vulkan/blob/master/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 `master` branch.
  * 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. The result should be identical to the version you just pulled from
Github. They can be compared by, for example:

`git diff ../include/vulkan/`

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 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`, `genvk.py`, `reg.py`, and `generator.py`.

If you are using other platforms, issues or merge requests with additional
documentation on using the tools on those platforms would be very helpful.


== 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
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

The schema supports, but does not currently use an attr:api attribute on
several tags. This is an arbitrary string, specified at header generation
time, for labelling properties of a specific API or API profile. The string
can be, but is not necessarily, an actual API name. Names starting with `vk`
are suggested if and when we start defining profiles of Vulkan.


[[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-vendorids,tag:vendorids>> - defines Khronos vendor IDs,
    described in detail in the "`Layers and Extensions`" appendix of the
    Vulkan Specification.
  * <<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-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-vendorids]]
= Vendor ID Blocks (tag:vendorids tag)

A tag:vendorids tag contains descriptions of vendor IDs for physical devices
which do not have PCI vendor IDs.

== Attributes of tag:vendorids tags

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

== Contents of tag:vendorids tags

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


[[tag-vendorid]]
= Vendor IDs (tag:vendorid tag)

A tag:vendorid tag describes a single vendor ID.

== Attributes of tag:vendorid tags

  * attr:name - required.
    The author ID, as registered with Khronos.
    This must match an author ID in the attr:name field of a tag:tag tag.
  * attr:id - required. The reserved vendor ID, as a hexadecimal number.
  * attr:comment - optional. Arbitrary string (unused).

== Contents of tag:vendorid tags

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


[[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. An API name (see tag:feature below) which
    specializes this definition of the named type, so that the same API
    types may have different definitions for e.g. GL ES and GL. This is
    unlikely to be used in Vulkan, where a single API supports desktop
    and mobile devices, but the functionality is retained.
  * 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: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 chained structures - the chained structures
    themselves should have their `pNext` tagged with attr:noautovalidity.
    This will generate a validity statement on the top level structure
    that validates the entire chain in one go, rather than each chained
    structure repeating the list of valid structs.

== 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: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:externsync - denotes that the member should be externally
    synchronized when accessed by Vulkan
  * attr:optional - a value of `"true"` or `"false"` determines whether this
    member can be omitted by providing `NULL` (for pointers),
    `VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values
    that are the size of an array in the same structure. If the member
    is a pointer to one of those types, multiple values may be provided,
    separated by commas - one for each pointer indirection.
  * attr:noautovalidity - prevents automatic validity language being
    generated for the tagged item. Only suppresses item-specific
    validity - parenting issues etc. are still captured.

==== 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).

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` (scalar typedefs, such as the definition of `VkFlags`)
  * `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:start, attr:end - optional. Integers defining the start and end of
    a reserved range of enumerants for a particular vendor or purpose.
    attr:start must be less than or equal to attr:end. These fields define
    formal enumerant allocations, and are made by the Khronos Registrar on
    request from implementers following the enum allocation policy.
  * attr:vendor - optional. String describing the vendor or purpose to whom
    a reserved range of enumerants is allocated.
  * attr:comment - optional. Arbitrary string (unused).

== 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 or attr:bitpos - exactly one of these is allowed and
    required. attr:value is an enumerant value in the form of a legal C
    constant (usually a literal decimal or hexadecimal integer, though
    arbitrary strings are allowed). attr:bitpos is a literal integer bit
    position in a bitmask.
  * attr:name - required. Enumerant name, a legal C preprocessor token
    name.
  * attr:api - optional. An API name which specializes this definition
    of the named enum, so that different APIs may have different values
    for the same token. May be used to address a subtle
    incompatibilities.
  * attr:type - optional. Used only when attr:value is specified. C
    suffix for the value to force it to a specific type. Currently only
    `u` and `ull` are used, for `unsigned` 32- and 64-bit integer
    values, respectively. Separated from attr:value since this eases
    parsing and sorting of values, and rarely used.
  * 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.

== 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: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"`, `"transfer"`, and `"graphics"`, 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: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:pipeline - optional. A string identifying the pipeline type
    that this command uses when executed. The format of the string is one of
    the terms `"compute"`, `"transfer"`, or `"graphics"`.
  * 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.

== 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 resolve to the _same_
    entry point in the underlying layer stack.
  * 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.


[[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: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 - a value of `"true"` or `"false"` determines whether this
    member can be omitted by providing `NULL` (for pointers),
    `VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values
    that are the size of an array in the same command. If the member is
    a pointer to one of those types, multiple values may be provided,
    separated by commas - one for each pointer indirection.
  * 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 `vkQueueSubmit` command
    includes attr:externsync attributes for the `pSubmits` array indicating
    that only specific members of each element of the array are modified:
+
--
[source,xml]
--------------------------------------
<param len="submitCount" externsync="pSubmits[].pWaitSemaphores[],pSubmits[].pSignalSemaphores[]">const <type>VkSubmitInfo</type>* <name>pSubmits</name></param>
--------------------------------------

Parameters which do not have an attr:externsync attribute are assumed to not
require external synchronization.
--

=== 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. <<schema:apiname,API name>> this feature is for,
    such as `vk`.
  * 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: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 extenions
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 attr:version and
attr:profile attributes, 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 Specification. Example: `name="VK_VERSION_1_0"`.
  * attr:number - required. A decimal number which is the registered,
    unique extension number for attr:name.
  * 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 email address, Github username, 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.
  * attr:requires - optional. Comma-separated list of extension names this
    extension requires to be supported.
  * 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 - required. A regular expression with an implicit `^` and
    `$` bracketing it, which should match the attr:api tag of a set of
    tag:feature tags. When the extension tag is just reserving an extension
    number, and no interfaces are yet defined, use `supported="disabled"` to
    indicate this extension should never be processed.
  * attr:comment - optional. Arbitrary string (unused).


[NOTE]
.Note
====
The attr:requires 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, using the attr:extension 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. An <<schema:apiname,API name>>.
    Interfaces in the tag are only required (or removed) if the
    specified API is being generated. 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 attribues are allowed only for a tag:require tag.

  * attr:extension - optional, and only for tag:require tags. String
    containing an API extension name. Interfaces in the tag are only
    required if the string matches the attr:name of an tag:extension tag,
    and that extension is enabled.
  * attr:feature - optional, and only for tag:require tags. String
    containing an API feature name. Interfaces in the tag are only required
    if the string matches the attr:name of a tag:feature tag, and that
    feature is enabled.

[NOTE]
.Note
====
The attr:extension attribute currently does not affect output generators in
any way, and is simply metadata. This will be addressed as we better define
different types of dependencies between extensions.
====

== 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. An API name which specializes this definition of
    the enumerant attr:name, so that different APIs may have different
    values for the same token. 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. Reference enums are the most common usage,
and no attributes other than attr:name and attr:comment are supported
for them.

_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, although not all combinations of attributes are either meaningful
or supported. Possible attributes are described first, followed by the
allowed combinations:

  * 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: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. 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 actual numeric value of the enumerant is computed as defined in
    the "`Layers and Extensions`" appendix of the Vulkan Specification.
  * 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:api - an API name which specializes this definition of the named
    enum, so that different APIs may have different values for the same
    token. May be used to address subtle incompatibilities.


.Valid Combinations of attr:enum Attributes
|====
| attr:value | attr:bitpos | attr:alias | attr:offset | attr:extnumber | attr:dir | attr:extends | Description
| {yes}      | {no}        | {no}       | {no}        | {no}           | {no}     | {opt}^2^     | Numeric value
| {no}       | {yes}       | {no}       | {no}        | {no}           | {no}     | {opt}^2^     | Bitmask value
| {no}       | {no}        | {yes}      | {no}        | {no}           | {no}     | {opt}^2^     | Alias of another enumerant
| {no}       | {no}        | {no}       | {yes}       | {opt}^1^       | {opt}    | {yes}        | Value added to an enumeration
| {no}       | {no}        | {no}       | {yes}       | {opt}^1^       | {opt}    | {yes}        | Value added to an enumeration
|====

[1]: 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]: If attr:extends is not present, the enumerant value is a global
constant. Otherwise, the value is added to the specified enumeration.

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_theanswer"/>
            <enum bitpos="29" name="VK_KHR_bitmask"/>
            <enum offset="0" dir="-" extends="VkResult"
                  name="VK_ERROR_SURFACE_LOST_KHR"/>
            <enum offset="1" extends="VkResult"
                  name="VK_SUBOPTIMAL_KHR"/>
            <enum bitpos="31" extends="VkResult"
                  name="VK_KHR_EXTENSION_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
--------------------------------------


[[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.

Initially, the only API feature is Vulkan 1.0, so there is only one
tag:feature tag in `vk.xml`. You can find it by searching
for the following block of `vk.xml`:

[source,xml]
--------------------------------------
<comment>
<feature api="vulkan" name="VK_VERSION_1_0" number="1.0"
         comment="Vulkan core API interface definitions">
--------------------------------------

Inside the tag:feature tag are nested multiple tag:require tags. These
are just being used as a logical grouping mechanism for related parts of
Vulkan 1.0 at present, though they may have more meaningful roles in the
future if different API profiles are defined.


=== 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 (c) 2015-2018 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 _dummy; }; 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.


== 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"    name="VK_THE_ANSWER"/>
--------------------------------------


== 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,31] 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.


== 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

  * 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.