2576 lines
100 KiB
Plaintext
2576 lines
100 KiB
Plaintext
// Copyright 2013-2021 The Khronos Group Inc.
|
|
//
|
|
// SPDX-License-Identifier: CC-BY-4.0
|
|
|
|
= The Khronos^®^ Vulkan^®^ API Registry
|
|
Jon Leech
|
|
:data-uri:
|
|
:icons: font
|
|
:toc2:
|
|
:toclevels: 3
|
|
:numbered:
|
|
:source-highlighter: rouge
|
|
:rouge-style: github
|
|
:doctype: book
|
|
:imagewidth: 800
|
|
:fullimagewidth: width="800"
|
|
:cl: :
|
|
|
|
// Various special / math symbols. This is easier to edit with than Unicode.
|
|
include::{config}/attribs.txt[]
|
|
|
|
:leveloffset: 1
|
|
|
|
<<<<
|
|
|
|
include::{config}/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 default branch,
|
|
currently `main`.
|
|
|
|
The registry uses an XML representation of the Vulkan API, together with a
|
|
set of Python scripts to manipulate the registry once loaded.
|
|
The scripts rely on the Python `etree` package to parse and operate on XML.
|
|
An XML schema and validator target are included.
|
|
|
|
The schema is based on, but not identical to that used for the previously
|
|
published OpenGL, OpenGL ES and EGL API registries.
|
|
It was extended to represent additional types and concepts not needed for
|
|
those APIs, such as structure and enumerant types, as well as additional
|
|
types of registered information specific to Vulkan.
|
|
|
|
The Vulkan C header files generated from the registry are checked into a
|
|
separate repository under
|
|
|
|
https://github.com/KhronosGroup/Vulkan-Headers/
|
|
|
|
|
|
== Schema Choices
|
|
|
|
The XML schema is not pure XML all the way down.
|
|
In particular, command return types/names and parameters, and structure
|
|
members, are described in mixed-mode tag containing C declarations of the
|
|
appropriate information, with some XML nodes annotating particular parts of
|
|
the declaration such as its base type and name.
|
|
This choice is based on prior experience with the SGI `.spec` file format
|
|
used to describe OpenGL, and greatly eases human reading and writing the
|
|
XML, and generating C-oriented output.
|
|
The cost is that people writing output generators for other languages will
|
|
have to include enough logic to parse the C declarations and extract the
|
|
relevant information.
|
|
|
|
People who do not find the supplied Python scripts to suit their needs are
|
|
likely to write their own parsers, interpreters, and/or converters operating
|
|
on the registry XML.
|
|
We hope that we have provided enough information in this document, the RNC
|
|
schema (`registry.rnc`), and comments in the Registry (`vk.xml`) itself to
|
|
enable such projects.
|
|
If not and you need clarifications; if you have other problems using the
|
|
registry; or if you have proposed changes and enhancements, then please file
|
|
issues on Khronos' public Github project at
|
|
|
|
https://github.com/KhronosGroup/Vulkan-Docs/issues
|
|
|
|
Please tag your issues with `[Registry]` in the subject line to help us
|
|
categorize them.
|
|
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/main/xml/README.adoc[`xml/README.adoc`]
|
|
in the `Vulkan-Docs` repository for information on required toolchain
|
|
components such as Python 3, pass:[g++], and GNU make.
|
|
|
|
Once you have the right tools installed, perform the following steps:
|
|
|
|
* Check out the `Vulkan-Docs` repository linked above from Khronos Github
|
|
(there are instructions at the link)
|
|
* `cd` to the root directory in your checked-out repo
|
|
* Switch to the default branch (`main`).
|
|
* Invoke `make clean ; make install ; make test`
|
|
|
|
This should regenerate `vulkan_core.h` and a variety of platform-specific
|
|
headers, install them in `../include/vulkan/`, and verify that the headers
|
|
build properly.
|
|
If you build at the latest repository tag, the resulting headers should be
|
|
identical to the latest versions in the
|
|
link:https://github.com/KhronosGroup/Vulkan-Headers/[Vulkan-Headers
|
|
repository].
|
|
|
|
The `install` target also generates source code for a simple extension
|
|
loader library in `../src/ext_loader/`.
|
|
|
|
Other Makefile targets in `xml/` include:
|
|
|
|
* `validate` - validate `vk.xml` against the XML schema.
|
|
Recommended if you are making nontrivial changes.
|
|
* The asciidoc includes used by the Specification and Reference Pages are
|
|
built using the 'make generated' target in the parent directory
|
|
Makefile, although they use the scripts and XML in this directory.
|
|
These files are generated dynamically when building the specs, since
|
|
their contents depend on the exact set of extensions the Specification
|
|
is being built to include.
|
|
|
|
If you just want to modify the API, changing `vk.xml` and running `make`
|
|
should be all that is needed.
|
|
See <<examples>> for some examples of modifying the XML.
|
|
|
|
If you want to use the registry for reasons other than generating the header
|
|
file, extension loader, and asciidoc includes, or to generate headers for
|
|
languages other than C, start with the Makefile rules and the files
|
|
`vk.xml` and scripts `genvk.py`, `reg.py`, and `generator.py`.
|
|
The scripts are described below and are all located in the `scripts`
|
|
directory under the repository root.
|
|
|
|
== Header Generation Script - `genvk.py`
|
|
|
|
When generating header files using the `genvk.py` script, an API name and
|
|
profile name are required, as shown in the Makefile examples.
|
|
Additionally, specific API versions and extensions can be required or
|
|
excluded.
|
|
Based on this information, the generator script extracts the relevant
|
|
interfaces and creates a C-language header file for them.
|
|
`genvk.py` contains predefined generator options for the current Vulkan
|
|
Specification release.
|
|
|
|
The generator script is intended to be generalizable to other languages by
|
|
writing new generator classes.
|
|
Such generators would have to rewrite the C types and definitions in the XML
|
|
to something appropriate to their language.
|
|
|
|
|
|
== Registry Processing Script - `reg.py`
|
|
|
|
XML processing is done in `reg.py`, which contains several objects and
|
|
methods for loading registries and extracting interfaces and extensions for
|
|
use in header generation.
|
|
There is some internal documentation in the form of comments, although
|
|
nothing more extensive exists yet.
|
|
|
|
|
|
== Output Generator Script - `generator.py`
|
|
|
|
Once the registry is loaded, the `COutputGenerator` class defined in
|
|
`generator.py` is used to create a header file.
|
|
The `DocOutputGenerator` class is used to create the asciidoc include files.
|
|
Output generators for other purposes can be added as needed.
|
|
There are a variety of output generators included:
|
|
|
|
* `cgenerator.py` - generate C header file
|
|
* `docgenerator.py` - generate asciidoc includes for APIs
|
|
* `hostsyncgenerator.py` - generate host sync table includes for APIs
|
|
* `validitygenerator.py` - generate validity language includes
|
|
* `pygenerator.py` - generate a Python dictionary-based encoding of
|
|
portions of the registry, used during spec generation
|
|
* `extensionStubSource.py` - generate a simple C extension loader.
|
|
|
|
|
|
[[schema]]
|
|
= Vulkan Registry Schema
|
|
|
|
The format of the Vulkan registry is a top level tag:registry tag containing
|
|
tag:types, tag:enums, tag:commands, tag:feature, and tag:extension tags
|
|
describing the different elements of an API, as explained below.
|
|
This description corresponds to a formal Relax NG schema file,
|
|
`registry.rnc`, against which the XML registry files can be validated.
|
|
|
|
At present the only registry in this schema is the core Vulkan API registry,
|
|
`vk.xml`.
|
|
|
|
|
|
[[schema:profile]]
|
|
== Profiles
|
|
|
|
Types and enumerants can have different definitions depending on the API
|
|
profile requested.
|
|
This capability is not used in the current Vulkan API but may be in the
|
|
future.
|
|
Features and extensions can include some elements conditionally depending on
|
|
the API profile requested.
|
|
|
|
|
|
[[schema:apiname]]
|
|
== API Names
|
|
|
|
Specific API versions features and extensions can be tagged as belonging to
|
|
to classes of features with the use of _API names_.
|
|
This is intended to allow multiple closely-related API specifications in the
|
|
same family - such as desktop and mobile specifications - to share the same
|
|
XML.
|
|
An API name is an arbitrary alphanumeric string, although it should be
|
|
chosen to match the corresponding API.
|
|
For example, Vulkan and OpenXR use `vulkan` and `openxr` as their API names,
|
|
respectively.
|
|
|
|
The attr:api attribute of the tag:feature tag and the attr:supported
|
|
attribute of the tag:extensions tag must be comma-separated lists of one or
|
|
more API names, all of which match that feature or extension.
|
|
When generating headers and other artifacts from the XML, an API name may be
|
|
specified to the processing scripts, causing the selection of only those
|
|
features and extensions whose API names match the specified name.
|
|
|
|
Several other tags for defining types and groups of types also support
|
|
attr:api attributes.
|
|
If present, the attribute value must be a comma-separated list of one or
|
|
more API names.
|
|
This allows specializing a definition for different, closely related APIs.
|
|
|
|
|
|
[[schema:root]]
|
|
= Registry Root (tag:registry tag)
|
|
|
|
A tag:registry contains the entire definition of one or more related APIs.
|
|
|
|
== Attributes of tag:registry tags
|
|
|
|
None.
|
|
|
|
== Contents of tag:registry tags
|
|
|
|
Zero or more of each of the following tags, normally in this order (although
|
|
order should not be important):
|
|
|
|
* tag:comment - Contains arbitrary text, such as a copyright statement.
|
|
* <<tag-platforms,tag:platforms>> - defines platform names corresponding
|
|
to platform-specific <<tag-extension,API extensions>>.
|
|
* <<tag-tags,tag:tags>> - defines author IDs used for extensions and
|
|
layers.
|
|
Author IDs are described in detail in the "`Layers & Extensions`"
|
|
section of the "`Vulkan Documentation and Extensions: Procedures and
|
|
Conventions`" document.
|
|
* <<tag-types,tag:types>> - defines API types.
|
|
Usually only one tag is used.
|
|
* <<tag-enums,tag:enums>> - defines API token names and values.
|
|
Usually multiple tags are used.
|
|
Related groups may be tagged as an enumerated type corresponding to a
|
|
tag:type tag, and resulting in a C `enum` declaration.
|
|
This ability is heavily used in the Vulkan API.
|
|
* <<tag-commands,tag:commands>> - defines API commands (functions).
|
|
Usually only one tag is used.
|
|
* <<tag-feature,tag:feature>> - defines API feature interfaces (API
|
|
versions, more or less).
|
|
One tag per feature set.
|
|
* <<tag-extensions,tag:extensions>> - defines API extension interfaces.
|
|
Usually only one tag is used, wrapping many extensions.
|
|
|
|
|
|
[[tag-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 <<schema:apiname, API names>> for which this
|
|
definition is specialized, so that different APIs may have different
|
|
definitions for the same type.
|
|
This definition is only used if the requested API name matches the
|
|
attribute.
|
|
May be used to address subtle incompatibilities.
|
|
* attr:category - optional.
|
|
A string which indicates that this type contains a more complex
|
|
structured definition.
|
|
At present the only accepted categories are `basetype`, `bitmask`,
|
|
`define`, `enum`, `funcpointer`, `group`, `handle`, `include`, `struct`,
|
|
and `union`, as described below.
|
|
* attr:comment - optional.
|
|
Arbitrary string (unused).
|
|
* attr:parent - only applicable if `"category"` is `handle`.
|
|
Notes another type with the `handle` category that acts as a parent
|
|
object for this type.
|
|
* attr:returnedonly - only applicable if `"category"` is `struct` or
|
|
`union`.
|
|
Notes that this struct/union is going to be filled in by the API, rather
|
|
than an application filling it out and passing it to the API.
|
|
* attr:structextends only applicable if category is `struct` or `union`.
|
|
This is a comma-separated list of structures whose `pNext` can include
|
|
this type.
|
|
This should usually only list the top-level structure that is extended,
|
|
for all possible extending structures.
|
|
This will generate a validity statement on the top level structure that
|
|
validates the entire chain in one go, rather than each extending
|
|
structure repeating the list of valid structs.
|
|
There is no need to set the attr:noautovalidity attribute on the `pNext`
|
|
members of extending structures.
|
|
* attr:allowduplicate - only applicable if attr:category is `"struct"`.
|
|
If `"true"`, then structures whose `pNext` chains include this structure
|
|
may include more than one instance of it.
|
|
* attr:objtypeenum - only applicable at present if attr:category is
|
|
`"handle"`.
|
|
Specifies the name of a `VkObjectType` enumerant which corresponds to
|
|
this type.
|
|
The enumerant must be defined.
|
|
|
|
== Contents of tag:type tags
|
|
|
|
The valid contents depend on the attr:category attribute.
|
|
|
|
=== Enumerated types - attr:category `"enum"`
|
|
|
|
If the attr:category tag has the value `enum`, the type is a C enumeration.
|
|
The body of the tag is ignored in this case.
|
|
The value of the attr:name attribute must be provided and must match the
|
|
attr:name attribute of a <<tag-enums,tag:enums>> tag.
|
|
The enumerant values defined within the tag:enums tag are used to generate a
|
|
C `enum` type declaration.
|
|
|
|
=== Structure types - attr:category `"struct"` or `"union"`
|
|
|
|
If the attr:category tag has the values `struct` or `union`, the type is a C
|
|
structure or union, respectively.
|
|
In this case, the attr:name attribute must be provided, and the contents of
|
|
the tag:type tag are a series of tag:member tags defining the members of the
|
|
aggregate type, in order, interleaved with any number of tag:comment tags.
|
|
|
|
==== Structure member (tag:member) tags
|
|
|
|
The tag:member tag defines the type and name of a structure or union member.
|
|
|
|
==== Attributes of tag:member tags
|
|
|
|
* attr: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), or 0 (for other scalar types).
|
|
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).
|
|
Structure members with name `pNext` must always be specified with
|
|
`optional="true"`, since there is no requirement that any member of a
|
|
`pNext` chain have a following member in the chain.
|
|
+
|
|
--
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
While the attr:optional attribute can be used for scalar types such as
|
|
integers, it does not affect the output generators included with the Vulkan
|
|
Specification.
|
|
In this case, the attribute serves only as an indicator to human readers of
|
|
the XML.
|
|
====
|
|
--
|
|
* attr:selector - optional.
|
|
If the member is a union, attr:selector identifies another member of the
|
|
struct that is used to select which of that union's members are valid.
|
|
* attr:selection - optional.
|
|
For a member of a union, attr:selection identifies a value of the
|
|
attr:selector that indicates this member is valid.
|
|
* attr:noautovalidity - prevents automatic validity language being
|
|
generated for the tagged item.
|
|
Only suppresses item-specific validity - parenting issues etc.
|
|
are still captured.
|
|
It must also be used for structures that have no implicit validity when
|
|
such structure has explicit validity.
|
|
* attr:limittype - only applicable for members of
|
|
VkPhysicalDeviceProperties and VkPhysicalDeviceProperties2, their
|
|
substrucutres, and extensions.
|
|
Specifies the type of a device limit.
|
|
This type describes how a value might be compared with the value of a
|
|
member in order to check whether it fits the limit.
|
|
Valid values:
|
|
** `"min"` and `"max"` denote minimum and maximum limits.
|
|
They may also apply to arrays and `VkExtent*D`.
|
|
** `"bitmask"` corresponds to bitmasks and `VkBool32`, where set bits
|
|
indicate the presence of a capability
|
|
** `"range"` specifies a [min, max] range
|
|
** `"struct"` means that the member's fields should be compared.
|
|
** `"noauto"` limits cannot be trivially compared.
|
|
This is the default value, if unspecified.
|
|
* attr:objecttype - only applicable for members which are `uint64_t`
|
|
values representing a Vulkan obejct handle.
|
|
Specifies the name of another member which must be a `VkObjectType` or
|
|
`VkDebugReportObjectTypeEXT` value specifying the type of object the
|
|
handle refers to.
|
|
|
|
==== Contents of tag:member tags
|
|
|
|
The text elements of a tag:member tag, with all other tags removed, is a
|
|
legal C declaration of a struct or union member.
|
|
In addition it may contain several semantic tags:
|
|
|
|
* The tag:type tag is optional.
|
|
It contains text which is a valid type name found in another tag:type
|
|
tag, and indicates that this type must be previously defined for the
|
|
definition of the command to succeed.
|
|
Builtin C types should not be wrapped in tag:type tags.
|
|
* The tag:name tag is required, and contains the struct/union member name
|
|
being described.
|
|
* The tag:enum tag is optional.
|
|
It contains text which is a valid enumerant name found in another
|
|
tag:type tag, and indicates that this enumerant must be previously
|
|
defined for the definition of the command to succeed.
|
|
Typically this is used to semantically tag static array lengths.
|
|
* The tag:comment tag is optional.
|
|
It contains an arbitrary string (unused).
|
|
|
|
|
|
=== All other types
|
|
|
|
If the attr:category attribute is one of `basetype`, `bitmask`, `define`,
|
|
`funcpointer`, `group`, `handle` or `include`, or is not specified, tag:type
|
|
contains text which is legal C code for a type declaration.
|
|
It may also contain embedded tags:
|
|
|
|
* tag:type - nested type tags contain other type names which are required
|
|
by the definition of this type.
|
|
* tag:apientry/ - insert a platform calling convention macro here during
|
|
header generation, used mostly for function pointer types.
|
|
* tag:name - contains the name of this type (if not defined in the tag
|
|
attributes).
|
|
* tag:bitvalues - contains the name of the enumeration defining flag
|
|
values for a `bitmask` type.
|
|
Ignored for other types.
|
|
|
|
There is no restriction on which sorts of definitions may be made in a given
|
|
category, although the contents of tags with attr:category `enum`, `struct`
|
|
or `union` are interpreted specially as described above.
|
|
|
|
However, when generating the header, types within each category are grouped
|
|
together, and categories are generated in the order given by the following
|
|
list.
|
|
Therefore, types in a category should correspond to the intended purpose
|
|
given for that category.
|
|
If this recommendation is not followed, it is possible that the resulting
|
|
header file will not compile due to out-of-order type dependencies.
|
|
The intended purpose of each category is:
|
|
|
|
* `include` (`#include`) directives)
|
|
* `define` (macro `#define` directives)
|
|
* `basetype` (built-in C language types; scalar API typedefs, such as the
|
|
definition of `VkFlags`; and types defined by external APIs, such as an
|
|
underlying OS or window system
|
|
* `handle` (invocations of macros defining scalar types such as
|
|
`VkInstance`)
|
|
* `enum` (enumeration types and `#define` for constant values)
|
|
* `group` (currently unused)
|
|
* `bitmask` (enumeration types whose members are bitmasks)
|
|
* `funcpointer` (function pointer typedefs)
|
|
* `struct` and `union` together (struct and union types)
|
|
|
|
|
|
[[tag-types:example]]
|
|
== Example of a tag:types tag
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<types>
|
|
<type name="stddef">#include <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 implementors 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).
|
|
* attr:bitwidth - optional.
|
|
Bit width required for the generated enum value type.
|
|
If omitted, a default value of 32 is used.
|
|
|
|
== Contents of tag:enums tags
|
|
|
|
Each tag:enums block contains zero or more tag:enum, tag:unused, and
|
|
tag:comment tags, in arbitrary order (although they are typically ordered by
|
|
sorting on enumerant values, to improve human readability).
|
|
|
|
== Example of tag:enums tags
|
|
|
|
<<tag-types:example,An example>> showing a tag with attribute
|
|
attr:type`="enum"` is given above.
|
|
The following example is for non-enumerated tokens.
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<enums>
|
|
<enum value="256" name="VK_MAX_EXTENSION_NAME"/>
|
|
<enum value="MAX_FLOAT" name="VK_LOD_CLAMP_NONE"/>
|
|
</enums>
|
|
--------------------------------------
|
|
|
|
When processed into a C header, and assuming all these tokens were required,
|
|
this results in
|
|
|
|
[source,c]
|
|
--------------------------------------
|
|
#define VK_MAX_EXTENSION_NAME 256
|
|
#define VK_LOD_CLAMP_NONE MAX_FLOAT
|
|
--------------------------------------
|
|
|
|
|
|
[[tag-enum]]
|
|
= Enumerants (tag:enum tag)
|
|
|
|
Each tag:enum tag defines a single Vulkan (or other API) token.
|
|
|
|
== Attributes of tag:enum tags
|
|
|
|
* attr:value is a numeric value in the form of a legal C expression when
|
|
evaluated at compile time in the generated header files.
|
|
This is usually either a literal integer value or the name of an alias
|
|
for a previously defined value, though more complex expressions are
|
|
sometimes employed for <<compile-time-constants, compile time
|
|
constants>>.
|
|
* attr:bitpos is a literal integer bit position in a bitmask.
|
|
The bit position must be in the range [0,30] when used as a flag bit in
|
|
a `Vk*FlagBits` data type.
|
|
Bit positions 31 and up may be used for values that are not flag bits,
|
|
or for <<adding-bitflags, flag bits used with 64-bit flag types>>.
|
|
Exactly one of attr:value and attr:bitpos must be present in an tag:enum
|
|
tag.
|
|
* attr:name - required.
|
|
Enumerant name, a legal C preprocessor token name.
|
|
* attr:api - optional <<schema:apiname, API names>> for which this
|
|
definition is specialized, so that different APIs may have different
|
|
values for the same token.
|
|
This definition is only used if the requested API name matches the
|
|
attribute.
|
|
May be used to address subtle incompatibilities.
|
|
* attr:type - may be used only when attr:value is specified.
|
|
In this case, attr:type is optional except when defining a
|
|
<<compile-time-constants, compile time constant>>, in which case it is
|
|
required when using some output generator paths.
|
|
If present the attribute must be a C scalar type corresponding to the
|
|
type of attr:value, although only `uint32_t`, `uint64_t`, and `float`
|
|
are currently meaningful.
|
|
attr:type is used by some output generators to generate constant
|
|
declarations, although the default behavior is to use C `#define` for
|
|
compile-time constants.
|
|
* attr:alias - optional.
|
|
Name of another enumerant this is an alias of, used where token names
|
|
have been changed as a result of profile changes or for consistency
|
|
purposes.
|
|
An enumerant alias is simply a different attr:name for the exact same
|
|
attr:value or attr:bitpos.
|
|
* attr:protect - optional.
|
|
An additional preprocessor token used to protect an enum definition.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
In older versions of the schema, attr:type was described as allowing only
|
|
the C integer suffix types `u` and `ull`, which is inconsistent with the
|
|
current definition.
|
|
However, attr:type was not actually used in the registry processing scripts
|
|
or `vk.xml` at the time the current definition was introduced, so this is
|
|
expected to be a benign change.
|
|
====
|
|
|
|
|
|
== Contents of tag:enum tags
|
|
|
|
tag:enum tags have no allowed contents.
|
|
All information is contained in the attributes.
|
|
|
|
|
|
[[tag-unused]]
|
|
= Unused Enumerants (tag:unused tag)
|
|
|
|
Each tag:unused tag defines a range of enumerants which is allocated, but
|
|
not yet assigned to specific enums.
|
|
This just tracks the unused values for the Registrar's use, and is not used
|
|
for header generation.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
tag:unused tags could be generated and inserted automatically, which would
|
|
be a good way to avoid the attributes becoming out of date.
|
|
However, they are rarely used in the Vulkan XML schema, unlike the OpenGL
|
|
XML schema it was based on.
|
|
====
|
|
|
|
== Attributes of tag:unused tags
|
|
|
|
* attr:start - required, attr:end - optional.
|
|
Integers defining the start and end of an unused range of enumerants.
|
|
attr:start must be {leq} attr:end.
|
|
If attr:end is not present, then attr:start defines a single unused
|
|
enumerant.
|
|
This range should not exceed the range reserved by the surrounding
|
|
tag:enums tag.
|
|
* attr:vendor - optional.
|
|
String describing the vendor or purposes to whom a reserved range of
|
|
enumerants is allocated.
|
|
Usually identical to the attr:vendor attribute of the surrounding
|
|
attr:enums block.
|
|
* attr:comment - optional.
|
|
Arbitrary string (unused).
|
|
|
|
== Contents of tag:unused tags
|
|
|
|
None.
|
|
|
|
|
|
[[tag-commands]]
|
|
= Command Blocks (tag:commands tag)
|
|
|
|
The tag:commands tag contains definitions of each of the functions
|
|
(commands) used in the API.
|
|
|
|
== Attributes of tag:commands tags
|
|
|
|
* attr:comment - optional.
|
|
Arbitrary string (unused).
|
|
|
|
== Contents of tag:commands tags
|
|
|
|
Each tag:commands block contains zero or more tag:command tags, in arbitrary
|
|
order (although they are typically ordered by sorting on the command name,
|
|
to improve human readability).
|
|
|
|
|
|
[[tag-command]]
|
|
= Commands (tag:command tag)
|
|
|
|
The tag:command tag contains a structured definition of a single API command
|
|
(function).
|
|
|
|
== Attributes of tag:command tags
|
|
|
|
There are two ways to define a command.
|
|
The first uses a set of attributes to the tag:command tag defining
|
|
properties of the command used for constructing automatic validation rules,
|
|
and the contents of the tag:command tag define the name, signature, and
|
|
parameters of the command.
|
|
In this case the allowed attributes include:
|
|
|
|
* attr: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: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), or 0 (for other scalar types).
|
|
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).
|
|
+
|
|
--
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
While the attr:optional attribute can be used for scalar types such as
|
|
integers, it does not affect the output generators included with the Vulkan
|
|
Specification.
|
|
In this case, the attribute serves only as an indicator to human readers of
|
|
the XML.
|
|
====
|
|
--
|
|
* attr:selector - optional.
|
|
If the parameter is a union, attr:selector identifies another parameter
|
|
of the command that is used to select which of that union's members are
|
|
valid.
|
|
* attr:noautovalidity - prevents automatic validity language being
|
|
generated for the tagged item.
|
|
Only suppresses item-specific validity - parenting issues etc.
|
|
are still captured.
|
|
* attr:externsync - optional.
|
|
A value of `"true"` indicates that this parameter (e.g. the object a
|
|
handle refers to, or the contents of an array a pointer refers to) is
|
|
modified by the command, and is not protected against modification in
|
|
multiple app threads.
|
|
If only certain members of an object or elements of an array are
|
|
modified, multiple strings may be provided, separated by commas.
|
|
Each string describes a member which is modified.
|
|
For example, the `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.
|
|
--
|
|
* attr:objecttype - only applicable for parameters which are `uint64_t`
|
|
values representing a Vulkan obejct handle.
|
|
Specifies the name of another parameter which must be a `VkObjectType`
|
|
or `VkDebugReportObjectTypeEXT` value specifying the type of object the
|
|
handle refers to.
|
|
|
|
=== 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 names>> this feature is
|
|
defined for, such as `vulkan`.
|
|
* attr:name - required.
|
|
Version name, used as the C preprocessor token under which the version's
|
|
interfaces are protected against multiple inclusion.
|
|
Example: `"VK_VERSION_1_0"`.
|
|
* attr:number - required.
|
|
Feature version number, usually a string interpreted as
|
|
`majorNumber.minorNumber`.
|
|
Example: `4.2`.
|
|
* attr:sortorder - optional.
|
|
A decimal number which specifies an order relative to other tag:feature
|
|
tags when calling output generators.
|
|
Defaults to `0`.
|
|
Rarely used, for when ordering by attr:name is insufficient.
|
|
* attr:protect - optional.
|
|
An additional preprocessor token used to protect a feature definition.
|
|
Usually another feature or extension attr:name.
|
|
Rarely used, for odd circumstances where the definition of a feature or
|
|
extension requires another to be defined first.
|
|
* attr:comment - optional.
|
|
Arbitrary string (unused).
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The attr:name attribute used for Vulkan core versions, such as
|
|
`"VK_VERSION_1_0"`, is not an API construct.
|
|
It is used only as a preprocessor guard in the headers, and an asciidoctor
|
|
conditional in the specification sources.
|
|
The similar `"VK_API_VERSION_1_0"` symbols are part of the API and their
|
|
values are packed integers containing Vulkan core version numbers.
|
|
====
|
|
|
|
== Contents of tag:feature tags
|
|
|
|
Zero or more <<tag-required,tag:require and tag:remove tags>>, in arbitrary
|
|
order.
|
|
Each tag describes a set of interfaces that is respectively required for, or
|
|
removed from, this feature, as described below.
|
|
|
|
== Example of a tag:feature tag
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<feature api="vulkan" name="VK_VERSION_1_0" number="1.0">
|
|
<require comment="Header boilerplate">
|
|
<type name="vk_platform"/>
|
|
</require>
|
|
<require comment="API constants">
|
|
<enum name="VK_MAX_PHYSICAL_DEVICE_NAME"/>
|
|
<enum name="VK_LOD_CLAMP_NONE"/>
|
|
</require>
|
|
<require comment="Device initialization">
|
|
<command name="vkCreateInstance"/>
|
|
</require>
|
|
</feature>
|
|
--------------------------------------
|
|
|
|
When processed into a C header for Vulkan, this results in:
|
|
|
|
[source,c]
|
|
--------------------------------------
|
|
#ifndef VK_VERSION_1_0
|
|
#define VK_VERSION_1_0 1
|
|
#define VK_MAX_EXTENSION_NAME 256
|
|
#define VK_LOD_CLAMP_NONE MAX_FLOAT
|
|
typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)(const VkInstanceCreateInfo* pCreateInfo, VkInstance* pInstance);
|
|
#ifndef VK_NO_PROTOTYPES
|
|
VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance(
|
|
const VkInstanceCreateInfo* pCreateInfo,
|
|
VkInstance* pInstance);
|
|
#endif
|
|
#endif /* VK_VERSION_1_0 */
|
|
--------------------------------------
|
|
|
|
|
|
[[tag-extensions]]
|
|
= Extension Blocks (tag:extensions tag)
|
|
|
|
The tag:extensions tag contains definitions of each of the 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:sortorder - optional.
|
|
A decimal number which specifies an order relative to other
|
|
tag:extension tags when calling output generators.
|
|
Defaults to `0`.
|
|
Rarely used, for when ordering by attr:number is insufficient.
|
|
* attr:author - optional.
|
|
The author name, such as a full company name.
|
|
If not present, this can be taken from the corresponding tag:tag
|
|
attribute.
|
|
However, `EXT` and other multi-vendor extensions may not have a
|
|
well-defined author or contact in the tag.
|
|
This attribute is not used in processing the XML.
|
|
It is just metadata, mostly used to track the original author of an
|
|
extension (which may have since been promoted to use a different author
|
|
ID).
|
|
* attr:contact - optional.
|
|
The contact who registered or is currently responsible for extensions
|
|
and layers using the tag, including sufficient contact information to
|
|
reach the contact such as individual name together with Github username
|
|
(`@username`), Khronos internal Gitlab username (`gitlab:@username`) if
|
|
no public Github contact is available, or other contact information.
|
|
If not present, this can be taken from the corresponding tag:tag
|
|
attribute just like attr:author.
|
|
* attr:type - required if the attr:supported attribute is not
|
|
`'disabled'`.
|
|
Must be either `'device'` or `'instance'`, if present.
|
|
* attr:requires - optional.
|
|
Comma-separated list of extension names this extension requires to be
|
|
supported.
|
|
Extensions whose attr:type is `'instance'` must not require extensions
|
|
whose attr:type is `'device'`.
|
|
* 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 <<schema:apiname, API names>> this extension
|
|
is defined for.
|
|
When the extension tag is just reserving an extension number, use
|
|
`supported="disabled"` to indicate this extension should never be
|
|
processed.
|
|
Interfaces defined in a `disabled` extension block are tentative at best
|
|
and must: not be generated or otherwise used by scripts processing the
|
|
XML.
|
|
The only exception to this rule is for scripts used solely for
|
|
reserving, or checking for reserved bitflag values.
|
|
* attr: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:specialuse - optional.
|
|
If present, must contain one or more tokens separated by commas,
|
|
indicating a special purpose of the extension.
|
|
Tokens may include:
|
|
** 'cadsupport' - for support of CAD software.
|
|
** 'd3demulation' - for support of Direct3D emulation layers or libraries,
|
|
or applications porting from Direct3D.
|
|
** 'debugging' - for debugging an application.
|
|
** 'devtools' - for support of developer tools, such as capture-replay
|
|
libraries.
|
|
** 'glemulation' - for support of OpenGL and/or OpenGL ES emulation layers
|
|
or libraries, or applications porting from those APIs.
|
|
* attr:comment - optional.
|
|
Arbitrary string (unused).
|
|
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The attr: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 <<schema:apiname, API names>> requiring or removing
|
|
these interfaces.
|
|
Interfaces in the tag are only required (or removed) if the requested
|
|
API name matches the attribute.
|
|
If not specified, interfaces are required (or removed) for all APIs.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The attr:api attribute is only supported inside tag:extension tags, since
|
|
tag:feature tags already define a specific API.
|
|
====
|
|
|
|
== Attributes of tag:require tags
|
|
|
|
These 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 <<schema:apiname, API names>> for which this
|
|
definition is specialized, so that different APIs may have different
|
|
values for the same token.
|
|
This definition is only used if the requested API name matches the
|
|
attribute.
|
|
May be used to address subtle incompatibilities.
|
|
|
|
There are two forms of tag:enum tags:
|
|
|
|
_Reference enums_ simply pull in the definition of an enumerant given in a
|
|
separate tag:enums block.
|
|
No attributes other than attr:name and attr:comment are supported for them.
|
|
tag:enum tags appearing inside tag:remove tags should always be reference
|
|
enums.
|
|
Reference enums may also be used inside tag:require tags, if the
|
|
corresponding value is defined in a tag:enums block.
|
|
This is typically used for constants not part of an enumerated type.
|
|
|
|
_Extension enums_ define the value of an enumerant inline in an tag:feature
|
|
or tag:extensions block.
|
|
Typically these are used to add additional values specified by an extension
|
|
or core feature to an existing enumerated type.
|
|
There are a variety of attributes which are used to specify the value of the
|
|
enumerant:
|
|
|
|
* attr:value and attr:type - define a constant value in the same fashion
|
|
as an tag:enum tag in an <<tag-enum,tag:enums>> block.
|
|
* attr:bitpos - define a constant bitmask value in the same fashion as an
|
|
<<tag-enum,tag:enum>> tag in an tag:enums block.
|
|
attr:bitpos is a literal integer bit position in a bitmask.
|
|
The same value and usage constraints apply to this bit position as are
|
|
applied to the <<tag-enum, attr:bitpos attribute of an tag:enum tag.
|
|
* attr:extends - the name of a separately defined enumerated type (e.g. a
|
|
tag:type tag with attr:category``="enum"``) to which the extension
|
|
enumerant is added.
|
|
The enumerated type is required to complete the definition of the
|
|
enumerant, in the same fashion as the attr:requires attribute of a
|
|
tag:type tag.
|
|
If not present, the enumerant is treated as a global constant value.
|
|
* attr:extnumber - an extension number.
|
|
The extension number in turn specifies the starting value of a block
|
|
(range) of values reserved for enumerants defined by or associated with
|
|
the corresponding tag:extension tag with the same attr:number.
|
|
This is used when an extension or core feature needs to extend an
|
|
enumerated type in a block defined by a different extension.
|
|
* Attribute attr:offset - the offset within an extension block.
|
|
If attr:extnumber is not present, the extension number defining that
|
|
block is given by the attr:number attribute of the surrounding
|
|
tag:extension tag.
|
|
The 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:protect - define a preprocessor protection symbol for the enum in
|
|
the same fashion as a tag:enum tag in an <<tag-enum,tag:enums>> block.
|
|
|
|
Not all combinations of attributes are either meaningful or supported.
|
|
The attr:protect attribute may always be present.
|
|
For other attributes, the allowed combinations are:
|
|
|
|
.Valid Combinations of attr:enum Attributes for Extension Enums
|
|
|====
|
|
| 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_TEST_ANSWER"/>
|
|
<enum bitpos="29" name="VK_KHR_TEST_BITMASK"/>
|
|
<enum offset="0" dir="-" extends="VkResult"
|
|
name="VK_ERROR_SURFACE_LOST_KHR"/>
|
|
<enum offset="1" extends="VkResult"
|
|
name="VK_SUBOPTIMAL_KHR"/>
|
|
<enum bitpos="30" extends="VkCullModeFlagBits"
|
|
name="VK_KHR_TEST_CULL_MODE_BIT"/>
|
|
</require>
|
|
</extension>
|
|
</extensions>
|
|
--------------------------------------
|
|
|
|
The corresponding header file will include definitions like this:
|
|
|
|
[source,c]
|
|
--------------------------------------
|
|
typedef enum VkResult {
|
|
<previously defined VkResult enumerant values},
|
|
VK_ERROR_SURFACE_LOST_KHR = -1000000000,
|
|
VK_SUBOPTIMAL_KHR = 1000000001,
|
|
VK_KHR_EXTENSION_BIT = 0x80000000,
|
|
};
|
|
|
|
#define VK_KHR_test_extension 1
|
|
#define VK_KHR_theanswer 42
|
|
#define VK_KHR_bitmask 0x20000000
|
|
--------------------------------------
|
|
|
|
|
|
[[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 2015-2021 The Khronos Group Inc.
|
|
...
|
|
*/
|
|
|
|
/*
|
|
** This header is generated from the Khronos Vulkan XML API Registry.
|
|
**
|
|
** Generated on date 20170208
|
|
*/
|
|
|
|
|
|
#define VK_VERSION_1_0 1
|
|
#include "vk_platform.h"
|
|
#define VK_MAKE_VERSION(major, minor, patch) \
|
|
((major << 22) | (minor << 12) | patch)
|
|
|
|
// Vulkan API version supported by this file
|
|
#define VK_API_VERSION VK_MAKE_VERSION(0, 104, 0)
|
|
|
|
#if defined (__cplusplus) && (VK_UINTPTRLEAST64_MAX == UINTPTR_MAX)
|
|
#define VK_TYPE_SAFE_COMPATIBLE_HANDLES 1
|
|
#endif
|
|
|
|
#if defined(VK_TYPE_SAFE_COMPATIBLE_HANDLES) && !defined(VK_DISABLE_TYPE_SAFE_HANDLES)
|
|
#define VK_DEFINE_PTR_HANDLE(_obj) struct _obj##_T { char _placeholder; }; typedef _obj##_T* _obj;
|
|
#define VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base) struct _obj##_T : public _base##_T {}; typedef _obj##_T* _obj;
|
|
|
|
#define VK_DEFINE_BASE_HANDLE(_obj) VK_DEFINE_PTR_HANDLE(_obj)
|
|
#define VK_DEFINE_DISP_SUBCLASS_HANDLE(_obj, _base) VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base)
|
|
#define VK_DEFINE_NONDISP_SUBCLASS_HANDLE(_obj, _base) VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base)
|
|
#else
|
|
#define VK_DEFINE_BASE_HANDLE(_obj) typedef VkUintPtrLeast64 _obj;
|
|
#define VK_DEFINE_DISP_SUBCLASS_HANDLE(_obj, _base) typedef uintptr_t _obj;
|
|
#define VK_DEFINE_NONDISP_SUBCLASS_HANDLE(_obj, _base) typedef VkUintPtrLeast64 _obj;
|
|
#endif
|
|
|
|
typedef enum {
|
|
VK_SUCCESS = 0,
|
|
VK_UNSUPPORTED = 1,
|
|
VK_NOT_READY = 2,
|
|
...
|
|
} VkResult;
|
|
typedef enum {
|
|
VK_STRUCTURE_TYPE_APPLICATION_INFO = 0,
|
|
...
|
|
} VKStructureType;
|
|
typedef struct {
|
|
VkStructureType sType;
|
|
const void* pNext;
|
|
const char* pAppName;
|
|
uint32_t appVersion;
|
|
const char* pEngineName;
|
|
uint32_t engineVersion;
|
|
uint32_t apiVersion;
|
|
} VkApplicationInfo;
|
|
typedef enum {
|
|
VK_SYSTEM_ALLOC_TYPE_API_OBJECT = 0,
|
|
...
|
|
} VkSystemAllocType;
|
|
typedef void* (VKAPI_PTR *PFN_vkAllocFunction)(
|
|
void* pUserData,
|
|
size_t size,
|
|
size_t alignment,
|
|
VkSystemAllocType allocType);
|
|
typedef void (VKAPI_PTR *PFN_vkFreeFunction)(
|
|
void* pUserData,
|
|
void* pMem);
|
|
typedef struct {
|
|
void* pUserData;
|
|
PFN_vkAllocFunction pfnAlloc;
|
|
PFN_vkFreeFunction pfnFree;
|
|
} VkAllocCallbacks;
|
|
typedef struct {
|
|
VkStructureType sType;
|
|
const void* pNext;
|
|
const VkApplicationInfo* pAppInfo;
|
|
const VkAllocCallbacks* pAllocCb;
|
|
uint32_t extensionCount;
|
|
const char*const* ppEnabledExtensionNames;
|
|
} VkInstanceCreateInfo;
|
|
VK_DEFINE_BASE_HANDLE(VkObject)
|
|
VK_DEFINE_DISP_SUBCLASS_HANDLE(VkInstance, VkObject)
|
|
#define VK_MAX_PHYSICAL_DEVICE_NAME 256
|
|
#define VK_MAX_EXTENSION_NAME 256
|
|
typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)(const VkInstanceCreateInfo* pCreateInfo, VkInstance* pInstance);
|
|
#ifndef VK_NO_PROTOTYPES
|
|
VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance(
|
|
const VkInstanceCreateInfo* pCreateInfo,
|
|
VkInstance* pInstance);
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|
|
--------------------------------------
|
|
|
|
Note that several additional types are pulled in by the type dependency
|
|
analysis, but only those types, commands, and tokens required by the
|
|
specified features are generated.
|
|
|
|
|
|
[[compile-time-constants]]
|
|
== How To Add A Compile Time Constant
|
|
|
|
Go to the desired tag:feature or tag:extension tag.
|
|
Add (if not present) a nested tag:require block labelled
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<require comment="API constants">
|
|
--------------------------------------
|
|
|
|
In this block, add an (appropriately indented) tag like
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<enum name="VK_THE_ANSWER"/>
|
|
--------------------------------------
|
|
|
|
Then go to the tag:enums block labelled
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<enums comment="Misc. hardcoded constants - not an enumerated type">
|
|
--------------------------------------
|
|
|
|
In this block, add a tag whose attr:name attribute matches the attr:name you
|
|
defined above and whose attr:value attribute is the value to give the
|
|
constant:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<enum value="42" type="uint32_t" name="VK_THE_ANSWER"/>
|
|
--------------------------------------
|
|
|
|
The attr:type attribute must be present, and must have one of the allowed
|
|
values `uint32_t`, `uint64_t`, or `float`.
|
|
|
|
|
|
[[compile-time-constants-format]]
|
|
== Allowed Format of Compile Time Constants
|
|
|
|
The attr:value attribute must be a legal C99 constant scalar expression when
|
|
evaluated at compilation time.
|
|
Allowed expressions are additionally restricted to the following syntax:
|
|
|
|
* a single C decimal integer or floating-point value
|
|
* optionally prefixed with `~`
|
|
* optionally suffixed with `U`, `UL`, `ULL`, or `F`
|
|
* and the entire expression optionally surrounded by paired `(` and `)`.
|
|
|
|
|
|
== How To Add A Struct or Union Type
|
|
|
|
For this example, assume we want to define a type corresponding to a C
|
|
`struct` defined as follows:
|
|
|
|
[source,c]
|
|
--------------------------------------
|
|
typedef struct {
|
|
VkStructureType sType;
|
|
const void* pNext;
|
|
const VkApplicationInfo* pAppInfo;
|
|
const VkAllocCallbacks* pAllocCb;
|
|
uint32_t extensionCount;
|
|
const char*const* ppEnabledExtensionNames;
|
|
} VkInstanceCreateInfo;
|
|
--------------------------------------
|
|
|
|
If `VkInstanceCreateInfo` is the type of a parameter of a command in the
|
|
API, make sure that command's definition (see below for how to add a
|
|
command) puts `VkInstanceCreateInfo` in nested tag:type tags where it is
|
|
used.
|
|
|
|
Otherwise, if the struct type is not used directly by a command in the API,
|
|
nor required by a chain of type dependencies for other commands, an explicit
|
|
tag:type dependency should be added to the tag:feature tag.
|
|
Go to the tag:types tag and search for the nested block labelled
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<require comment="Types not directly used by the API. Include e.g. structs that are not parameter types of commands, but still defined by the API.">
|
|
...
|
|
--------------------------------------
|
|
|
|
In this block, add a tag whose attr:name attribute matches the attr:name of
|
|
the struct type being defined:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<require comment="API types not used by commands">
|
|
<type name="VkInstanceCreateInfo"/>
|
|
...
|
|
--------------------------------------
|
|
|
|
Then go to the tag:types tag and add a new tag:type tag defining the struct
|
|
names and members, somewhere below the corresponding comment, like this:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<types>
|
|
...
|
|
<comment>Struct types</comment>
|
|
<type category="struct" name="VkInstanceCreateInfo">
|
|
<member><type>VkStructureType</type>
|
|
<name>sType</name></member>
|
|
<member>const void*
|
|
<name>pNext</name></member>
|
|
<member>const <type>VkApplicationInfo</type>*
|
|
<name>pAppInfo</name></member>
|
|
<member>const <type>VkAllocCallbacks</type>*
|
|
<name>pAllocCb</name></member>
|
|
<member><type>uint32_t</type>
|
|
<name>extensionCount</name></member>
|
|
<member>const <type>char</type>*const*
|
|
<name>ppEnabledExtensionNames</name></member>
|
|
</type>
|
|
...
|
|
--------------------------------------
|
|
|
|
If any of the member types are types also defined in the header, make sure
|
|
to enclose those type names in nested tag:type tags, as shown above.
|
|
Basic C types should not be tagged.
|
|
|
|
If the type is a C `union`, rather than a `struct`, then set the value of
|
|
the attr:category attribute to `"union"` instead of `"struct"`.
|
|
|
|
|
|
== How To Add An Enumerated Type
|
|
|
|
For this example, assume we want to define a type corresponding to a C
|
|
`enum` defined as follows:
|
|
|
|
[source,c]
|
|
--------------------------------------
|
|
typedef enum {
|
|
VK_DEVICE_CREATE_VALIDATION_BIT = 0x00000001,
|
|
VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT = 0x00000002;
|
|
} VkDeviceCreateFlagBits.
|
|
--------------------------------------
|
|
|
|
If `VkDeviceCreateFlagBits` is the type of a parameter to a command in the
|
|
API, or of a member in a structure or union, make sure that command
|
|
parameter or struct member's definition puts `VkDeviceCreateFlagBits` in
|
|
nested tag:type tags where it is used.
|
|
|
|
Otherwise, if the enumerated type is not used directly by a command in the
|
|
API, nor required by a chain of type dependencies for commands and structs,
|
|
an explicit tag:type dependency should be added to the tag:feature tag in
|
|
exactly the same fashion as described above for `struct` types.
|
|
|
|
Next, go to the line labelled
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<comment>Vulkan enumerant (token) definitions</comment>
|
|
--------------------------------------
|
|
|
|
At an appropriate point below this line, add an tag:enums tag whose
|
|
attr:name attribute matches the tag:type name `VkDeviceCreateFlagBits`, and
|
|
whose contents correspond to the individual fields of the enumerated type:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<enums name="VkDeviceCreateFlagBits" type="bitmask">
|
|
<enum bitpos="0" name="VK_DEVICE_CREATE_VALIDATION_BIT"/>
|
|
<enum bitpos="1" name="VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT"/>
|
|
</enums>
|
|
--------------------------------------
|
|
|
|
Several other attributes of the tag:enums tag can be set.
|
|
In this case, the attr:type attribute is set to `"bitmask"`, indicating that
|
|
the individual enumerants represent elements of a bitmask.
|
|
|
|
The individual tag:enum tags define the enumerants, just like the definition
|
|
for compile time constants described above.
|
|
In this case, because the enumerants are bits in a bitmask, their values are
|
|
specified using the attr:bitpos attribute.
|
|
The value of this attribute must be an integer in the range [0,30]
|
|
specifying a single bit number, and the resulting value is printed as a
|
|
hexadecimal constant corresponding to that bit.
|
|
|
|
It is also possible to specify enumerant values using the attr:value
|
|
attribute, in which case the specified numeric value is passed through to
|
|
the C header unchanged.
|
|
|
|
|
|
[[adding-bitflags]]
|
|
== How To Add Bit Flags
|
|
|
|
Bit masks are defined by two types in the xml - the type of the mask itself,
|
|
and the type of the valid flags.
|
|
|
|
For this example, assume we want to define bit flags that can handle up to
|
|
64 independent values as follows:
|
|
|
|
[source,c]
|
|
--------------------------------------
|
|
// Flag bits for VkExampleFlagBits
|
|
typedef VkFlags64 VkExampleFlagBits;
|
|
static const VkExampleFlagBits VK_EXAMPLE_NONE = 0;
|
|
static const VkExampleFlagBits VK_EXAMPLE_FIRST_BIT = 0x00000001;
|
|
static const VkExampleFlagBits VK_EXAMPLE_SECOND_BIT = 0x00000002;
|
|
|
|
typedef VkFlags64 VkExampleFlags;
|
|
--------------------------------------
|
|
|
|
An explicit tag:type dependency should be added to the tag:feature tag in
|
|
exactly the same fashion as described above for `struct` types.
|
|
|
|
Firstly, a definition is needed for the flags type used as a parameter to
|
|
commands or member of functions.
|
|
Go to the line labelled:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<comment>Bitmask types</comment>
|
|
--------------------------------------
|
|
|
|
At the end of the list of `VkFlags` and `VkFlags64` types, add a definition
|
|
of the flags type like so:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<type bitvalues="VkExampleFlagBits" category="bitmask">typedef <type>VkFlags64</type> <name>VkExampleFlags</name>;</type>
|
|
--------------------------------------
|
|
|
|
The attr:category defines this as a `"bitmask"` type.
|
|
The attr:bitvalues attribute identifies the `*FlagBits` entry defining the
|
|
flag bits associated with this type.
|
|
|
|
Next, go to the line labelled:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<comment>Types generated from corresponding enums tags below</comment>
|
|
--------------------------------------
|
|
|
|
At an appropriate point in the list of enum types after this comment, add
|
|
the following line:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<type name="VkExampleFlagBits" category="enum"/>
|
|
--------------------------------------
|
|
|
|
This defines a type for the flag bits for generators that need it.
|
|
The attr:category attribute of `"enum"` identifies that this is an
|
|
enumerated type.
|
|
|
|
Finally, go to the line labelled:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<comment>Vulkan enumerant (token) definitions</comment>
|
|
--------------------------------------
|
|
|
|
At the end of the list of enum definitions below this line, add an tag:enums
|
|
tag whose attr:name attribute matches the tag:type name `VkExampleFlagBits`,
|
|
and whose contents correspond to the individual fields of the enumerated
|
|
type:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<enums name="VkExampleFlagBits" type="bitmask" bitwidth="64">
|
|
<enum value="0" name="VK_EXAMPLE_NONE"/>
|
|
<enum bitpos="0" name="VK_EXAMPLE_FIRST_BIT"/>
|
|
<enum bitpos="1" name="VK_EXAMPLE_SECOND_BIT"/>
|
|
</enums>
|
|
--------------------------------------
|
|
|
|
The attr:type attribute is set to `"bitmask"`, indicating that the
|
|
individual enumerants represent elements of a bitmask.
|
|
The attr:bitwidth attribute is set to `"64"` indicating that this is a
|
|
64-bit flag type.
|
|
|
|
The individual tag:enum tags define the enumerants, just like the definition
|
|
for compile time constants described above.
|
|
In this case, a "no flags" type is defined in `VK_EXAMPLE_NONE` with the
|
|
attr:value attribute defining it to have a hard value of 0.
|
|
The other types have their values are specified using the attr:bitpos
|
|
attribute, as these are actual bit flag values.
|
|
The value of this attribute must be an integer in the range [0,63]
|
|
specifying a single bit number, and the resulting value is printed as a
|
|
hexadecimal constant corresponding to that bit.
|
|
|
|
|
|
=== 32-bit Flags
|
|
|
|
Bit flags can also be defined using 32-bit C enum types.
|
|
Doing so is broadly similar to 64-bit bit flags, but with a few key
|
|
differences.
|
|
For this example, assume we want to define the same type as above, but
|
|
corresponding to a C `enum` and flags type defined as follows:
|
|
|
|
[source,c]
|
|
--------------------------------------
|
|
typedef enum VkExampleFlagBits {
|
|
VK_EXAMPLE_NONE
|
|
VK_DEVICE_CREATE_VALIDATION_BIT = 0x00000001,
|
|
VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT = 0x00000002;
|
|
} VkExampleFlagBits;
|
|
|
|
typedef VkFlags VkExampleFlags;
|
|
--------------------------------------
|
|
|
|
To add this to the xml, entries need to be added to the XML in the same way
|
|
as above, but with slightly different attributes:
|
|
|
|
For the flag type definition, the entry should use `VkFlags` instead of
|
|
`VkFlags64`, and require the flag bits type, instead of specifying the
|
|
attr:bitvalues attribute:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<type requires="VkExampleFlagBits" category="bitmask">typedef <type>VkFlags</type> <name>VkExampleFlags</name>;</type>
|
|
--------------------------------------
|
|
|
|
For the definition of the enumerated flag values themselves, the bitwidth
|
|
needs to either be changed to `"32"`, or omitted entirely (which defaults to
|
|
a bitwidth of 32) as follows:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<enums name="VkExampleFlagBits" type="bitmask">
|
|
--------------------------------------
|
|
|
|
Note that 32-bit bitmasks must use an integer in the range [0,30] - C enums
|
|
are only guaranteed to support signed 32-bit integer values, and defining an
|
|
unsigned value for the 31st bit could change the size of the enum type.
|
|
The generator scripts will warn about values exceeding this range.
|
|
|
|
|
|
== How to Add A Command
|
|
|
|
For this example, assume we want to define the command:
|
|
|
|
[source,c]
|
|
--------------------------------------
|
|
VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance(
|
|
const VkInstanceCreateInfo* pCreateInfo,
|
|
VkInstance* pInstance);
|
|
--------------------------------------
|
|
|
|
Commands must always be explicitly required in the tag:feature tag.
|
|
In that tag, you can use an existing tag:require block including API
|
|
features which the new command should be grouped with, or define a new
|
|
block.
|
|
For this example, add a new block, and require the command by using the
|
|
tag:command tag inside that block:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<feature api="vulkan" name="VK_VERSION_1_0" number="1.0" comment="Vulkan core API interface definitions">
|
|
...
|
|
<require comment="Device initialization">
|
|
<command name="vkCreateInstance"/>
|
|
</require>
|
|
...
|
|
</feature>
|
|
--------------------------------------
|
|
|
|
The tag:require block may include a attr:comment attribute whose value is a
|
|
descriptive comment of the contents required within that block.
|
|
The comment is not currently used in header generation, but might be in the
|
|
future, so use comments which are polite and meaningful to users of the
|
|
generated header files.
|
|
|
|
Then go to the tag:commands tag and add a new tag:command tag defining the
|
|
command, preferably sorted into alphabetic order with other commands for
|
|
ease of reading, as follows:
|
|
|
|
[source,xml]
|
|
--------------------------------------
|
|
<commands comment="Vulkan command definitions">
|
|
...
|
|
<command>
|
|
<proto><type>VkResult</type>
|
|
<name>vkCreateInstance</name></proto>
|
|
<param>const <type>VkInstanceCreateInfo</type>*
|
|
<name>pCreateInfo</name></param>
|
|
<param><type>VkInstance</type>*
|
|
<name>pInstance</name></param>
|
|
</command>
|
|
...
|
|
</commands>
|
|
--------------------------------------
|
|
|
|
The tag:proto tag defines the return type and function name of the command.
|
|
The tag:param tags define the command's parameters in the order in which
|
|
they are passed, including the parameter type and name.
|
|
The contents are laid out in the same way as the structure tag:member tags
|
|
described previously.
|
|
|
|
|
|
== More Complicated API Representations
|
|
|
|
The registry schema can represent a good deal of additional information, for
|
|
example by creating multiple tag:feature tags defining different API
|
|
versions and extensions.
|
|
This capability is not yet relevant to Vulkan.
|
|
Those capabilities will be documented as they are needed.
|
|
|
|
|
|
== More Complicated Output Formats And Other Languages
|
|
|
|
The registry schema is oriented towards C-language APIs.
|
|
Types and commands are defined using syntax which is a subset of C,
|
|
especially for structure members and command parameters.
|
|
It would be possible to use a language-independent syntax for representing
|
|
such information, but since we are writing a C API, any such representation
|
|
would have to be converted into C anyway at some stage.
|
|
|
|
The `vulkan.h` header is written using an _output generator_ object in the
|
|
Python scripts.
|
|
This output generator is specialized for C, but the design of the scripts is
|
|
intended to support writing output generators for other languages as well as
|
|
purposes such as documentation (e.g. generating asciidoc fragments
|
|
corresponding to types and commands for use in the API specification and
|
|
reference pages).
|
|
When targeting other languages, the amount of parsing required to convert
|
|
type declarations into other languages is small.
|
|
However, it will probably be necessary to modify some of the boilerplate C
|
|
text, or specialize the tags by language, to support such generators.
|
|
|
|
|
|
== Additional Semantic Tagging
|
|
|
|
The schema is being extended to support semantic tags describing various
|
|
properties of API features, such as:
|
|
|
|
* constraints on allowed scalar values to function parameters (non-`NULL`,
|
|
normalized floating-point, etc.)
|
|
* length of arrays corresponding to function pointer parameters
|
|
* miscellaneous properties of commands such as whether the application or
|
|
system is responsible for threadsafe use; which queues they may be
|
|
issued on; whether they are aliases or otherwise related to other
|
|
commands; etc.
|
|
|
|
These tags will be used by other tools for purposes such as helping create
|
|
validation layers, generating serialization code, and so on.
|
|
We would like to eventually represent everything about the API that is
|
|
amenable to automatic processing within the registry schema.
|
|
Please make suggestions on the Github issue tracker.
|
|
|
|
|
|
[[general:stability]]
|
|
== Stability of the XML Database and Schema
|
|
|
|
The Vulkan XML schema is evolving in response to corresponding changes in
|
|
the Vulkan API and ecosystem.
|
|
Most such change will probably be confined to adding attributes to existing
|
|
tags and properly expressing the relationships to them, and making API
|
|
changes corresponding to accepted feature requests.
|
|
Changes to the schema should be described in the <<changelog,change log>> of
|
|
this document.
|
|
Changes to the `.xml` files and Python scripts are logged in Github history.
|
|
|
|
|
|
[[changelog]]
|
|
= Change Log
|
|
|
|
* 2021-08-22 - Update introductory descriptions of toolchain and scripts.
|
|
* 2021-08-15 - Add an explicit description of the tag:enum attr:extends
|
|
attribute as introducing a requirement for the enumerated type being
|
|
extended.
|
|
* 2021-07-12 - Note that tag:extension tags describing instance extensions
|
|
must not have dependencies on device extensions (internal issue 2387).
|
|
* 2021-06-14 - Add an `objecttype` attribute which specifies the
|
|
relationship between a Vulkan handle and another member or parameter
|
|
specifying the type of object that handle refers to (public issue 1536).
|
|
* 2021-06-06 - Update description of the attr:supported attribute of
|
|
<<tag-extension, tag:extension tags>> to mandate that `disabled`
|
|
extensions are not processed (public issue 1549).
|
|
* 2021-04-21 - Add the attr:limittype attribute to <<tag-type, structure
|
|
tag:member tags>>, to describe how queried limits are interpreted
|
|
(internal issue 2427).
|
|
* 2021-03-30 - Add a description of the <<compile-time-constants-format,
|
|
allowed format of compile time constants>> (internal merge request
|
|
4451).
|
|
* 2021-03-22 - Update allowed values for the attr:type attribute of
|
|
tag:enum tags and make it mandatory (internal issue 2564).
|
|
* 2021-01-11 - Expand the scope of the attr:optional attribute tag:member
|
|
and tag:param tags to specify that the member or parameter may be 0 for
|
|
all scalar types, not just bitmasks and array sizes (internal issue
|
|
2435).
|
|
* 2020-11-23 - Add `objtypeenum` attribute to <<tag:type, tag:type>> tags
|
|
to link the object name to the corresponding `VK_OBJECT_TYPE_*`
|
|
enumerant, if any (internal issue 2393).
|
|
* 2020-11-22 - Add requirement that `pNext` members have the
|
|
`optional="true"` attribute set (internal issue 2428).
|
|
* 2020-10-14 - Remove advice to set the attr:noautovalidity attribute on
|
|
the `pNext` member of extending structures in the <<tag:type, tag:type
|
|
tag>>, since the validity generator scripts now take care of this
|
|
(internal issue 2335).
|
|
* 2020-06-02 - Add description of how to switch between 64- and 32-bit
|
|
flags.
|
|
* 2020-05-07 - Update description of <<schema:apiname, API Names>> to
|
|
current usage, including allowing specifying multiple API names for a
|
|
given feature or extension.
|
|
* 2020-04-29 - Expand use of attr:category `basetype` in tag:type tags to
|
|
include external API types.
|
|
* 2020-02-20 - Clarify that tag:enum tags inside tag:remove tags must be
|
|
reference enums, not containing attributes defining values.
|
|
* 2020-01-13 - Restrict attr:bitpos to [0,30] to avoid poorly defined
|
|
compiler behavior.
|
|
* 2019-08-25 - Add attr:sortorder attribute to tag:feature and
|
|
tag:extension tags.
|
|
* 2018-12-06 - Specify that command aliases are not guaranteed to resolve
|
|
to the same entry point in the underlying layer stack, matching a
|
|
related clarification in the Vulkan Specification.
|
|
* 2018-10-01 - Add description of the default value of attr:optional
|
|
member and parameter attributes, if not specified.
|
|
* 2018-08-28 - Add optional attr:provisional attribute to tag:extension
|
|
tags.
|
|
* 2018-07-07 - Add optional attr:promotedto, attr:deprecatedby, and
|
|
attr:obsoletedby attributes to tag:extension tags.
|
|
* 2018-06-25 - Remove attr:vendorids tags for Khronos vendor IDs.
|
|
* 2018-05-08 - Add tag:driverids and tag:driverid tags for describing
|
|
Vulkan driver implementation identification information.
|
|
* 2018-04-15 - Add attr:requiresCore.
|
|
* 2018-03-07 - Updated for Vulkan 1.1 release.
|
|
* 2018-02-21 - Add descriptions of the attr:extnumber and attr:alias
|
|
attributes used for defining tag:enum attributes, the attr:alias
|
|
attribute used for defining tag:type aliases, the attr:name and
|
|
attr:alias attributes used for defining tag:command aliases, the
|
|
attr:platform attribute of tag:extension tags, and the attr:feature
|
|
attribute of tag:require tags; and update the document to the header
|
|
naming and grouping scheme used starting in Vulkan 1.1.
|
|
* 2018-01-07 - Add tag:platforms and tag:platform tags for describing
|
|
Vulkan platform names and preprocessor symbols.
|
|
* 2017-09-10 - Define syntax of member and parameter attr:altlen
|
|
attributes, for use by code generators.
|
|
* 2017-09-01 - Define syntax of member and parameter attr:len attributes
|
|
consistently and correctly for current uses of latexmath:
|
|
* 2017-08-24 - Note that the tag:extension attribute attr:type must be
|
|
specified if the extension is not disabled.
|
|
* 2017-07-27 - Finish removing validextensionstructs attribute and
|
|
replacing it with structextends.
|
|
* 2017-07-14 - Add comment attributes or tags as valid content in several
|
|
places, replacing XML comments which could not be preserved by XML
|
|
transformation tools.
|
|
* 2017-02-20 - Change to asciidoctor markup and move into the
|
|
specification source directory for ease of building.
|
|
* 2016-09-27 - Remove tag:validity and tag:usage tags, since these
|
|
explicit usage statements have been moved to the specification source.
|
|
* 2016-08-26 - Update for the single-branch model.
|
|
* 2016-07-28 - Add attr:type and attr:requires attributes to tag:extension
|
|
tags.
|
|
* 2016-02-22 - Change math markup in attr:len attributes to use asciidoc
|
|
`latexmath:[$` and `$]` delimiters.
|
|
* 2016-02-19 - Add attr:successcodes and attr:errorcodes attributes of
|
|
tag:command tags.
|
|
Add a subsection to the introduction describing the schema choices and
|
|
how to file issues against the registry.
|
|
* 2016-02-07 - Add attr:vendorids tags for Khronos vendor IDs.
|
|
* 2015-12-10 - Add attr:author and attr:contact attributes for
|
|
tag:extension tags.
|
|
* 2015-12-07 - Move `vulkan/vulkan.h` to a subdirectory.
|
|
* 2015-12-01 - Add tag:tags tags for author tags.
|
|
* 2015-11-18 - Bring documentation and schema up to date for extension
|
|
enumerants.
|
|
* 2015-11-02 - Bring documentation and schema up to date with several
|
|
recent merges, including tag:validity tags.
|
|
Still out of date WRT extension enumerants, but that will change soon.
|
|
* 2015-09-08 - Rename `threadsafe` attribute to attr:externsync, and
|
|
`implicitunsafeparams` tag to attr:implicitexternsync.
|
|
* 2015-09-07 - Update tag:command tag description to remove the
|
|
attr:threadsafe attribute and replace it with a combination of
|
|
attr:threadunsafe attributes on individual parameters, and
|
|
tag:implicitunsafeparams tags describing additional unsafe objects for
|
|
the command.
|
|
* 2015-08-04 - Add `basetype` and `funcpointer` attr:category values for
|
|
type tags, and explain the intended use and order in which types in each
|
|
category are emitted.
|
|
* 2015-07-02 - Update description of Makefile targets.
|
|
Add descriptions of attr:threadsafe, attr:queues, and attr:renderpass
|
|
attributes of <<tag-command,tag:command>> tags, and of attr:modified
|
|
attributes of <<tag-command:param,tag:param>> tags.
|
|
* 2015-06-17 - add descriptions of allowed attr:category attribute values
|
|
of tag:type tags, used to group and sort related categories of
|
|
declarations together in the generated header.
|
|
* 2015-06-04 - Add <<examples,examples of making changes and additions>>
|
|
to the registry.
|
|
* 2015-06-03 - Move location to new `vulkan` Git repository.
|
|
Add definition of tag:type tags for C struct/unions.
|
|
Start adding <<examples,examples of making changes>>.
|
|
* 2015-06-02 - Branch from OpenGL specfile documentation and bring up to
|
|
date with current Vulkan schema.
|
|
* 2015-07-10 - Remove contractions to match the style guide.
|
|
* 2015-07-19 - Move this document from LaTeX to asciidoc source format and
|
|
make minor changes to markup.
|