2105 lines
84 KiB
Plaintext
2105 lines
84 KiB
Plaintext
// Copyright (c) 2013-2019 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^®^ 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-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-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 - 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.
|
|
If not present, the value is assumed to be `"false"` (the member must
|
|
not be omitted).
|
|
* 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.
|
|
|
|
==== 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 <stddef.h></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 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 flink:vkGetInstanceProcAddr
|
|
or flink: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: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"` or `"false"` determines whether this
|
|
parameter 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 parameter is
|
|
a pointer to one of those types, multiple values may be provided,
|
|
separated by commas - one for each pointer indirection. If not present,
|
|
the value is assumed to be `"false"` (the parameter must not be
|
|
omitted).
|
|
* 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 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.
|
|
* attr:requires - optional. Comma-separated list of extension names this
|
|
extension requires to be supported.
|
|
* attr:requiresCore - optional. Core version of Vulkan required by the
|
|
extension, e.g. "1.1". Defaults to "1.0".
|
|
* 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: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.
|
|
* 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=""VK_KHR_display_swapchain""
|
|
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 << 22) | (minor << 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-2019 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-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-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.
|