Copyright (c) 2014-2020 The Khronos Group Inc.
SPDX-License-Identifier: CC-BY-4.0
1. 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
The authoritative copy of the Registry is maintained in the default
branch, currently main
.
Note
The older version of the registry in the |
The registry uses an XML representation of the Vulkan API, together with
a set of Python scripts to manipulate the registry once loaded. The
scripts rely on the Python etree
package to parse and operate on XML.
An XML schema and validator target are included.
The schema is based on, but not identical to that used for the previously published OpenGL, OpenGL ES and EGL API registries. It was extended to represent additional types and concepts not needed for those APIs, such as structure and enumerant types, as well as additional types of registered information specific to Vulkan.
The Vulkan C header files generated from the registry are checked in under
include/vulkan/
.
1.1. 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
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.
2. Getting Started
See
xml/README.adoc
in the Vulkan-Docs
repository for information on required toolchain
components such as Python 3, 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. The result should be identical to the version you just pulled from
Github. They can be compared by, for example:
git diff ../include/vulkan/
The install
target also generates source code for a simple extension
loader library in ../src/ext_loader/
.
Other Makefile targets in xml/
include:
-
validate
- validatevk.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 / FAQ / How Do I? for some examples of
modifying the XML.
If you want to use the registry for reasons other than generating the
header file, extension loader, and asciidoc includes, or to generate
headers for languages other than C, start with the Makefile rules and
the files vk.xml
, genvk.py
, reg.py
, and generator.py
.
If you are using other platforms, issues or merge requests with additional documentation on using the tools on those platforms would be very helpful.
2.1. 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.
2.2. 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.
2.3. 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.
3. Vulkan Registry Schema
The format of the Vulkan registry is a top level registry
tag
containing types
, enums
, commands
, feature
, and
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
.
3.1. 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.
3.2. 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 api
attribute of the feature
tag and the supported
attribute of the 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
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.
4. Registry Root (registry
tag)
A registry
contains the entire definition of one or more related
APIs.
4.2. Contents of registry
tags
Zero or more of each of the following tags, normally in this order (although order should not be important):
-
comment
- Contains arbitrary text, such as a copyright statement. -
platforms
- defines platform names corresponding to platform-specific API extensions. -
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. -
types
- defines API types. Usually only one tag is used. -
enums
- defines API token names and values. Usually multiple tags are used. Related groups may be tagged as an enumerated type corresponding to atype
tag, and resulting in a Cenum
declaration. This ability is heavily used in the Vulkan API. -
commands
- defines API commands (functions). Usually only one tag is used. -
feature
- defines API feature interfaces (API versions, more or less). One tag per feature set. -
extensions
- defines API extension interfaces. Usually only one tag is used, wrapping many extensions.
5. Platform Name Blocks (platforms
tag)
A platforms
contains descriptions of platform IDs for platforms
supported by window system-specific extensions to Vulkan.
6. Platform Names (platform
tag)
A platform
tag describes a single platform name.
6.1. Attributes of platform
tags
-
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.NoteFor 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. -
protect
- required. This must be a C99 preprocessor token beginning withVK_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.NoteFor example,
protect="VK_USE_PLATFORM_XLIB_XRANDR_EXT"
is used for the
xlib_xrandr
platform name. -
comment
- optional. Arbitrary string (unused).
7. Author ID Blocks (tags
tag)
A tags
tag contains authorid
tags describing reserved author IDs
used by extension and layer authors.
8. Author IDs (tag
tag)
A tag
tag contains information defining a single author ID.
8.1. Attributes of tag
tags
-
name
- required. The author ID, as registered with Khronos. A short, upper-case string, usually an abbreviation of an author, project or company name. -
author
- required. The author name, such as a full company or project name. -
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.
10. API Type (type
tag)
A 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.
10.1. Attributes of type
tags
-
requires
- optional. Another type name this type requires to complete its definition. -
name
- optional. Name of this type (if not defined in the tag body). -
alias
- optional. Another type name which this type is an alias of. Must match the name of anothertype
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. -
api
- optional 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. -
category
- optional. A string which indicates that this type contains a more complex structured definition. At present the only accepted categories arebasetype
,bitmask
,define
,enum
,funcpointer
,group
,handle
,include
,struct
, andunion
, as described below. -
comment
- optional. Arbitrary string (unused). -
parent
- only applicable if"category"
ishandle
. Notes another type with thehandle
category that acts as a parent object for this type. -
returnedonly
- only applicable if"category"
isstruct
orunion
. 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. -
structextends
only applicable if category isstruct
orunion
. This is a comma-separated list of structures whosepNext
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 thenoautovalidity
attribute on thepNext
members of extending structures. -
allowduplicate
- only applicable ifcategory
is"struct"
. If"true"
, then structures whosepNext
chains include this structure may include more than one instance of it. -
objtypeenum
- only applicable at present ifcategory
is"handle"
. Specifies the name of aVkObjectType
enumerant which corresponds to this type. The enumerant must be defined.
10.2. Contents of type
tags
The valid contents depend on the category
attribute.
10.2.1. Enumerated types - category
"enum"
If the 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 name
attribute must be provided and must match the name
attribute of a enums
tag. The enumerant values defined
within the enums
tag are used to generate a C enum
type
declaration.
10.2.2. Structure types - category
"struct"
or "union"
If the category
tag has the values struct
or union
, the type is a C
structure or union, respectively. In this case, the name
attribute must
be provided, and the contents of the type
tag are a series of member
tags defining the members of the aggregate type, in order, interleaved with
any number of comment
tags.
Structure member (member
) tags
The member
tag defines the type and name of a structure or union
member.
Attributes of member
tags
-
values
- only valid on thesType
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. -
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. The only variables in the equation should be the names of members of the structure.
-
altlen
- if thelen
attribute is specified, and contains alatexmath:
equation, this attribute should be specified with an equivalent equation using only C builtin operators, C math library function names, and variables as allowed forlen
. It must be a valid C99 expression whose result is equal tolen
for all possible inputs. It is a comma separated list that has size equal to only thelatexmath
item count inlen
list. This attribute is intended to support consumers of the XML who need to generate validation code from the allowed length. -
externsync
- denotes that the member should be externally synchronized when accessed by Vulkan -
optional
- optional. A value of"true"
or"false"
determines whether this member can be omitted by providingNULL
(for pointers),VK_NULL_HANDLE
(for handles), 0 (for bitmasks), or 0 for values that are the size of an array in the same structure. If the member is a pointer to one of those types, multiple values may be provided, separated by commas - one for each pointer indirection. If not present, the value is assumed to be"false"
(the member must not be omitted). Structure members with namepNext
must always be specified withoptional="true"
, since there is no requirement that any member of apNext
chain have a following member in the chain. -
selector
- optional. If the member is a union,selector
identifies another member of the struct that is used to select which of that union’s members are valid. -
selection
- optional. For a member of a union,selection
identifies a value of theselector
that indicates this member is valid. -
noautovalidity
- prevents automatic validity language being generated for the tagged item. Only suppresses item-specific validity - parenting issues etc. are still captured. It must also be used for structures that have no implicit validity when such structure has explicit validity.
Contents of member
tags
The text elements of a 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
type
tag is optional. It contains text which is a valid type name found in anothertype
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 intype
tags. -
The
name
tag is required, and contains the struct/union member name being described. -
The
enum
tag is optional. It contains text which is a valid enumerant name found in anothertype
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
comment
tag is optional. It contains an arbitrary string (unused).
10.2.3. All other types
If the category
attribute is one of basetype
, bitmask
,
define
, funcpointer
, group
, handle
or
include
, or is not specified, type
contains text which is legal
C code for a type declaration. It may also contain embedded tags:
-
type
- nested type tags contain other type names which are required by the definition of this type. -
apientry
/ - insert a platform calling convention macro here during header generation, used mostly for function pointer types. -
name
- contains the name of this type (if not defined in the tag attributes). -
bitvalues
- contains the name of the enumeration defining flag values for abitmask
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 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 ofVkFlags
; and types defined by external APIs, such as an underlying OS or window system -
handle
(invocations of macros defining scalar types such asVkInstance
) -
enum
(enumeration types and#define
for constant values) -
group
(currently unused) -
bitmask
(enumeration types whose members are bitmasks) -
funcpointer
(function pointer typedefs) -
struct
andunion
together (struct and union types)
10.3. Example of a types
tag
<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:
#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.
11. Enumerant Blocks (enums
tag)
The enums
tags contain individual 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
It would make more sense to call these |
11.1. Attributes of enums
tags
-
name
- optional. String naming the Cenum
type whose members are defined by this enum group. If present, this attribute should match thename
attribute of a correspondingtype
tag. -
type
- optional. String describing the data type of the values of this group of enums. At present the only accepted categories areenum
andbitmask
, as described below. -
start
,end
- optional. Integers defining the start and end of a reserved range of enumerants for a particular vendor or purpose.start
must be less than or equal toend
. These fields define formal enumerant allocations, and are made by the Khronos Registrar on request from implementers following the enum allocation policy. -
vendor
- optional. String describing the vendor or purpose to whom a reserved range of enumerants is allocated. -
comment
- optional. Arbitrary string (unused). -
bitwidth
- optional. Bit width required for the generated enum value type. If omitted, a default value of 32 is used.
11.2. Contents of enums
tags
Each enums
block contains zero or more enum
, unused
, and
comment
tags, in arbitrary order (although they are typically ordered by
sorting on enumerant values, to improve human readability).
11.3. Example of enums
tags
An example showing a tag with attribute
type
`="enum"` is given above. The following example is for
non-enumerated tokens.
<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
#define VK_MAX_EXTENSION_NAME 256
#define VK_LOD_CLAMP_NONE MAX_FLOAT
12. Enumerants (enum
tag)
Each enum
tag defines a single Vulkan (or other API) token.
12.1. Attributes of enum
tags
-
value
is an enumerant value in the form of a legal C constant (usually a literal decimal or hexadecimal integer, though arbitrary strings are allowed). -
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 aVk*FlagBits
data type. Bit positions 31 and up may be used for values that are not flag bits. Exactly one ofvalue
andbitpos
must be present in anenum
tag. -
name
- required. Enumerant name, a legal C preprocessor token name. -
api
- optional 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. -
type
- optional. Used only whenvalue
is specified. C suffix for the value to force it to a specific type. Currently onlyu
andull
are used, forunsigned
32- and 64-bit integer values, respectively. Separated fromvalue
since this eases parsing and sorting of values, and rarely used. -
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 differentname
for the exact samevalue
orbitpos
.
13. Unused Enumerants (unused
tag)
Each 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
|
13.1. Attributes of unused
tags
-
start
- required,end
- optional. Integers defining the start and end of an unused range of enumerants.start
must be ≤end
. Ifend
is not present, thenstart
defines a single unused enumerant. This range should not exceed the range reserved by the surroundingenums
tag. -
vendor
- optional. String describing the vendor or purposes to whom a reserved range of enumerants is allocated. Usually identical to thevendor
attribute of the surroundingenums
block. -
comment
- optional. Arbitrary string (unused).
14. Command Blocks (commands
tag)
The commands
tag contains definitions of each of the functions
(commands) used in the API.
15. Commands (command
tag)
The command
tag contains a structured definition of a single API
command (function).
15.1. Attributes of command
tags
There are two ways to define a command. The first uses a set of attributes
to the command
tag defining properties of the command used for
constructing automatic validation rules, and the contents of the command
tag define the name, signature, and parameters of the command. In this case
the allowed attributes include:
-
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 (","
). -
successcodes
- optional. A string describing possible successful return codes from the command, as a comma-separated list of Vulkan result code names. -
errorcodes
- optional. A string describing possible error return codes from the command, as a comma-separated list of Vulkan result code names. -
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"
). -
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 (","
). -
pipeline
- optional. A string identifying the pipeline type that this command uses when executed. The format of the string is one of the terms"compute"
,"transfer"
, or"graphics"
. -
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:
-
name
- required. A string naming the command defined by the tag. -
alias
- required. A string naming the command thatname
is an alias of. The string must be the same as thename
value of anothercommand
defining another command.
15.2. Contents of command
tags
-
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. -
param
elements for each command parameter follow, defining its name and type, as described below. If a command takes no arguments, it has noparam
tags.
Following these elements, the remaining elements in a command
tag are optional and may be in any order:
-
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. -
description
- optional. Unused text. -
implicitexternsyncparams
- optional. Contains a list ofparam
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 requires external synchronization. The text is intended to be incorporated into the API specification.
Note
Versions of the registry documentation prior to 1.1.93 asserted that command aliases “resolve to the same entry point in the underlying layer stack.” Whilst this may be true on many implementations, it is not required - each command alias must be queried separately through vkGetInstanceProcAddr or vkGetDeviceProcAddr. |
15.3. Command prototype (proto
tags)
The proto
tag defines the return type and name of a command.
15.3.2. Contents of proto
tags
The text elements of a 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
type
tag is optional, and contains text which is a valid type name found in atype
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 intype
tags. -
The
name
tag is required, and contains the command name being described.
15.4. Command parameter (param
tags)
The param
tag defines the type and name of a parameter. Its contents
are very similar to the member
tag used to define struct and union
members.
15.4.1. Attributes of param
tags
-
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. The only variables in the equation should be the names of this or other parameters.
-
altlen
- if thelen
attribute is specified, and contains alatexmath:
equation, this attribute should be specified with an equivalent equation using only C builtin operators, C math library function names, and variables as allowed forlen
. It must be a valid C99 expression whose result is equal tolen
for all possible inputs. It is a comma separated list that has size equal to only thelatexmath
item count inlen
list. This attribute is intended to support consumers of the XML who need to generate validation code from the allowed length. -
optional
- optional. A value of"true"
or"false"
determines whether this parameter can be omitted by providingNULL
(for pointers),VK_NULL_HANDLE
(for handles), 0 (for bitmasks), or 0 for values that are the size of an array in the same command. If the parameter is a pointer to one of those types, multiple values may be provided, separated by commas - one for each pointer indirection. If not present, the value is assumed to be"false"
(the parameter must not be omitted). -
selector
- optional. If the parameter is a union,selector
identifies another parameter of the command that is used to select which of that union’s members are valid. -
noautovalidity
- prevents automatic validity language being generated for the tagged item. Only suppresses item-specific validity - parenting issues etc. are still captured. -
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, thevkQueueSubmit
command includesexternsync
attributes for thepSubmits
array indicating that only specific members of each element of the array are modified:<param len="submitCount" externsync="pSubmits[].pWaitSemaphores[],pSubmits[].pSignalSemaphores[]">const <type>VkSubmitInfo</type>* <name>pSubmits</name></param>
Parameters which do not have an
externsync
attribute are assumed to not require external synchronization.
15.4.2. Contents of param
tags
The text elements of a 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
type
tag is optional, and contains text which is a valid type name found intype
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 intype
tags. -
The
name
tag is required, and contains the parameter name being described.
15.5. Example of a commands
tag
<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
VkResult vkCreateInstance(
const VkInstanceCreateInfo* pCreateInfo,
VkInstance* pInstance);
16. API Features and Versions (feature
tag)
API features are described in individual 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.
16.1. Attributes of feature
tags
-
api
- required API names this feature is defined for, such asvulkan
. -
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"
. -
number
- required. Feature version number, usually a string interpreted asmajorNumber.minorNumber
. Example:4.2
. -
sortorder
- optional. A decimal number which specifies an order relative to otherfeature
tags when calling output generators. Defaults to0
. Rarely used, for when ordering byname
is insufficient. -
protect
- optional. An additional preprocessor token used to protect a feature definition. Usually another feature or extensionname
. Rarely used, for odd circumstances where the definition of a feature or extension requires another to be defined first. -
comment
- optional. Arbitrary string (unused).
Note
The |
16.2. Contents of feature
tags
Zero or more require
and 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.
16.3. Example of a feature
tag
<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:
#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 */
17. Extension Blocks (extensions
tag)
The extensions
tag contains definitions of each of the extenions
which are defined for the API.
18. API Extensions (extension
tag)
API extensions are described in individual extension
tags. An
extension is the set of interfaces defined by a particular API extension
specification, such as ARB_multitexture
. extension
is
similar to feature
, but instead of having version
and
profile
attributes, instead has a supported
attribute,
which describes the set of API names which the extension can potentially
be implemented against.
18.1. Attributes of extension
tags
-
name
- required. Extension name, following the conventions in the Vulkan Specification. Example:name="VK_VERSION_1_0"
. -
number
- required. A decimal number which is the registered, unique extension number forname
. -
sortorder
- optional. A decimal number which specifies an order relative to otherextension
tags when calling output generators. Defaults to0
. Rarely used, for when ordering bynumber
is insufficient. -
author
- optional. The author name, such as a full company name. If not present, this can be taken from the correspondingtag
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). -
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 correspondingtag
attribute just likeauthor
. -
type
- required if thesupported
attribute is not'disabled'
. Must be either'device'
or'instance'
, if present. -
requires
- optional. Comma-separated list of extension names this extension requires to be supported. -
requiresCore
- optional. Core version of Vulkan required by the extension, e.g. "1.1". Defaults to "1.0". -
protect
- optional. An additional preprocessor token used to protect an extension definition. Usually another feature or extensionname
. Rarely used, for odd circumstances where the definition of an extension requires another extension or a header file to be defined first. -
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 theplatform
name
attribute values. -
supported
- required API names this extension is defined for. When the extension tag is just reserving an extension number, and no interfaces are yet defined, usesupported="disabled"
to indicate this extension should never be processed. -
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"
. -
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""
. -
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""
. -
provisional
- optional. 'true' if this extension is released provisionally. -
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.
-
-
comment
- optional. Arbitrary string (unused).
Note
The In some cases, an extension may include functionality which is only defined
if another extension is enabled. Such functionality should be specified
within a |
18.2. Contents of extension
tags
Zero or more require
and 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.
18.3. Example of an extensions
tag
<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 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 type
and
command
elsewhere in the XML):
#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
19. Required and Removed Interfaces (require
and remove
tags)
A require
block defines a set of interfaces (types, enumerants and
commands) 'required' by a feature
or extension
. A remove
block defines a set of interfaces
'removed' by a 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 require
and remove
tags are identical.
19.1. Attributes of require
and remove
tags
-
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. -
comment
- optional. Arbitrary string (unused). -
api
- optional 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
The |
19.2. Attributes of require
tags
These attribues are allowed only for a require
tag.
-
extension
- optional, and only forrequire
tags. String containing an API extension name. Interfaces in the tag are only required if the string matches thename
of anextension
tag, and that extension is enabled. -
feature
- optional, and only forrequire
tags. String containing an API feature name. Interfaces in the tag are only required if the string matches thename
of afeature
tag, and that feature is enabled.
Note
The |
19.3. Contents of require
and remove
tags
Zero or more of the following tags, in any order:
19.3.1. Comment Tags
comment
(as described above).
19.3.2. Command Tags
command
specifies an required (or removed) command defined
in a commands
block. The tag has no content, but contains
attributes:
-
name
- required. Name of the command. -
comment
- optional. Arbitrary string (unused).
19.3.3. Enum tags
enum
specifies an required (or removed) enumerant defined in a
enums
block. All forms of this tag support the following attributes:
-
name
- required. Name of the enumerant. -
comment
- optional. Arbitrary string (unused). -
api
- optional 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 enum
tags:
Reference enums simply pull in the definition of an enumerant given in a
separate enums
block. No attributes other than name
and
comment
are supported for them. enum
tags appearing inside
remove
tags should always be reference enums. Reference enums may also
be used inside require
tags, if the corresponding value is defined in a
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 feature
or extensions
block. Typically these are used to add additional values
specified by an extension or core feature to an existing enumerated type.
There are a variety of attributes which are used to specify the value of the
enumerant, although not all combinations of attributes are either meaningful
or supported. Possible attributes are described first, followed by the
allowed combinations:
-
value
andtype
- define a constant value in the same fashion as anenum
tag in anenums
block. -
bitpos
- define a constant bitmask value in the same fashion as anenum
tag in anenums
block.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,bitpos
attribute of anenum
tag. -
extends
- the name of a separately defined enumerated type (e.g. atype
tag withcategory
="enum"
) to which the extension enumerant is added. If not present, the enumerant is treated as a global constant value. -
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 correspondingextension
tag with the samenumber
. This is used when an extension or core feature needs to extend an enumerated type in a block defined by a different extension. -
Attribute
offset
- the offset within an extension block. Ifextnumber
is not present, the extension number defining that block is given by thenumber
attribute of the surroundingextension
tag. The actual numeric value of the enumerant is computed as defined in the “Layers and Extensions” appendix of the Vulkan Specification. -
Attribute
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 asdir="-"
. -
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.
|
|
|
|
|
|
|
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 extnumber
is not present, the enum
tag may only be within a
extension
. Otherwise, the enum
tag may also be within a feature
.
[2]: If extends
is not present, the enumerant value is a global
constant. Otherwise, the value is added to the specified enumeration.
Examples of various types of extension enumerants are given below.
19.3.4. Type tags
type
specifies a required (or removed) type defined in a
types
block. Most types are picked up implicitly by using the
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:
-
name
- required. Name of the type. -
comment
- optional. Arbitrary string (unused).
19.4. Examples of Extension Enumerants
Examples of some of the supported extension enumerant enum
tags are
given below.
<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:
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
20. 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 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.
20.1. 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
type
,enums
,enum
, orcommand
tags defining the interface in question. -
Make sure that all added types and commands appropriately tag their dependencies on other types by adding nested
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.
20.2. 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 feature
tag.
Initially, the only API feature is Vulkan 1.0, so there is only one
feature
tag in vk.xml
. You can find it by searching
for the following block of vk.xml
:
<comment>
<feature api="vulkan" name="VK_VERSION_1_0" number="1.0"
comment="Vulkan core API interface definitions">
Inside the feature
tag are nested multiple 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.
20.2.1. API Feature Walkthrough
This section walks through the first few required API features in the
vk.xml
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 feature
:
<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 require
block says to require a type named vk_platform
.
If you look at the beginning of the types
section, there is a
corresponding definition section:
<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 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 require
block pulls in some compile time constants. These
correspond to the definitions found in the first enums
section of
vk.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 require
block starts pulling in some Vulkan commands. The
first command corresponds to the following definition found in the
commands
section of vk.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 command
tag requires the types
VkResult
,
VkInstanceCreateInfo
, and VkInstance
as part of its
definition. The definitions of these types are determined as follows:
For VkResult
, the corresponding required type
is:
<type name="VkResult" category="enum"/>
Since this is an enumeration type, it simply links to an enums
tag
with the same name:
<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 type
is:
<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 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 type
is:
<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 feature
dependencies in vk.xml
, the
resulting vulkan_core.h
header will look like this:
#ifndef VULKAN_H_
#define VULKAN_H_ 1
#ifdef __cplusplus
extern "C" {
#endif
/*
** Copyright (c) 2015-2020 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.
20.3. How To Add A Compile Time Constant
Go to the desired feature
or extension
tag. Add (if not present) a
nested require
block labelled
<require comment="API constants">
In this block, add an (appropriately indented) tag like
<enum name="VK_THE_ANSWER"/>
Then go to the enums
block labelled
<enums comment="Misc. hardcoded constants - not an enumerated type">
In this block, add a tag whose name
attribute matches the name
you defined above and whose value
attribute is the value to give the
constant:
<enum value="42" name="VK_THE_ANSWER"/>
20.4. 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:
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 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
type
dependency should be added to the feature
tag. Go to the
types
tag and search for the nested block labelled
<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 name
attribute matches the name
of the struct type being defined:
<require comment="API types not used by commands">
<type name="VkInstanceCreateInfo"/>
...
Then go to the types
tag and add a new type
tag defining
the struct names and members, somewhere below
the corresponding comment, like this:
<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 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 category
attribute to "union"
instead of
"struct"
.
20.5. How To Add An Enumerated Type
For this example, assume we want to define a type corresponding to a C
enum
defined as follows:
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 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 type
dependency should be added to the feature
tag
in exactly the same fashion as described above for struct
types.
Next, go to the line labelled
<comment>Vulkan enumerant (token) definitions</comment>
At an appropriate point below this line, add an enums
tag whose
name
attribute matches the type
name VkDeviceCreateFlagBits
, and
whose contents correspond to the individual fields of the enumerated type:
<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 enums
tag can be set. In this case,
the type
attribute is set to "bitmask"
, indicating that the
individual enumerants represent elements of a bitmask.
The individual 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
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 value
attribute, in which case the specified numeric value is passed through to
the C header unchanged.
20.6. 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:
typedef VkFlags64 VkExampleFlags;
// Flag bits for VkExampleFlags
static const VkExampleFlags VK_EXAMPLE_NONE = 0;
static const VkExampleFlags VK_EXAMPLE_FIRST_BIT = 0x00000001;
static const VkExampleFlags VK_EXAMPLE_SECOND_BIT = 0x00000002;
An explicit type
dependency should be added to the 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:
<comment>Bitmask types</comment>
At the end of the list of VkFlags
and VkFlags64
types, add a definition
of the flags type like so:
<type bitvalues="VkExampleFlagBits" category="bitmask">typedef <type>VkFlags64</type> <name>VkExampleFlags</name>;</type>
The category
defines this as a "bitmask"
type. The bitvalues
attribute identifies the *FlagBits
entry defining the flag bits
associated with this type.
Next, go to the line labelled:
<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:
<type name="VkExampleFlagBits" category="enum"/>
This defines a type for the flag bits for generators that need it.
The category
attribute of "enum"
identifies that this is an
enumerated type.
Finally, go to the line labelled:
<comment>Vulkan enumerant (token) definitions</comment>
At the end of the list of enum definitions below this line, add an
enums
tag whose name
attribute matches the type
name
VkExampleFlagBits
, and whose contents correspond to the individual
fields of the enumerated type:
<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 type
attribute is set to "bitmask"
, indicating that the
individual enumerants represent elements of a bitmask.
The bitwidth
attribute is set to "64"
indicating that this is a
64-bit flag type.
The individual 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 value
attribute defining it to have a hard value of 0. The other types have their
values are specified using the 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.
20.6.1. 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:
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
bitvalues
attribute:
<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:
<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.
20.7. How to Add A Command
For this example, assume we want to define the command:
VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance(
const VkInstanceCreateInfo* pCreateInfo,
VkInstance* pInstance);
Commands must always be explicitly required in the feature
tag. In
that tag, you can use an existing 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
command
tag inside that block:
<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 require
block may include a 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 commands
tag and add a new command
tag defining
the command, preferably sorted into alphabetic order with other commands for
ease of reading, as follows:
<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 proto
tag defines the return type and function name of the
command. The 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 member
tags described
previously.
20.8. More Complicated API Representations
The registry schema can represent a good deal of additional information, for
example by creating multiple 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.
20.9. 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.
20.10. 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.
20.11. 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 change log of this document. Changes to the .xml
files and Python scripts are logged in Github history.
21. Change Log
-
2020-11-23 - Add
objtypeenum
attribute to <<type
,type
>> tags to link the object name to the correspondingVK_OBJECT_TYPE_*
enumerant, if any (internal issue 2393). -
2020-11-22 - Add requirement that
pNext
members have theoptional="true"
attribute set (internal issue 2428). -
2020-10-14 - Remove advice to set the
noautovalidity
attribute on thepNext
member of extending structures in the <<type
,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 API Names to current usage, including allowing specifying multiple API names for a given feature or extension.
-
2020-04-29 - Expand use of
category
basetype
intype
tags to include external API types. -
2020-02-20 - Clarify that
enum
tags insideremove
tags must be reference enums, not containing attributes defining values. -
2020-01-13 - Restrict
bitpos
to [0,30] to avoid poorly defined compiler behavior. -
2019-08-25 - Add
sortorder
attribute tofeature
andextension
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
optional
member and parameter attributes, if not specified. -
2018-08-28 - Add optional
provisional
attribute toextension
tags. -
2018-07-07 - Add optional
promotedto
,deprecatedby
, andobsoletedby
attributes toextension
tags. -
2018-06-25 - Remove
vendorids
tags for Khronos vendor IDs. -
2018-05-08 - Add
driverids
anddriverid
tags for describing Vulkan driver implementation identification information. -
2018-04-15 - Add
requiresCore
. -
2018-03-07 - Updated for Vulkan 1.1 release.
-
2018-02-21 - Add descriptions of the
extnumber
andalias
attributes used for definingenum
attributes, thealias
attribute used for definingtype
aliases, thename
andalias
attributes used for definingcommand
aliases, theplatform
attribute ofextension
tags, and thefeature
attribute ofrequire
tags; and update the document to the header naming and grouping scheme used starting in Vulkan 1.1. -
2018-01-07 - Add
platforms
andplatform
tags for describing Vulkan platform names and preprocessor symbols. -
2017-09-10 - Define syntax of member and parameter
altlen
attributes, for use by code generators. -
2017-09-01 - Define syntax of member and parameter
len
attributes consistently and correctly for current uses of latexmath: -
2017-08-24 - Note that the
extension
attributetype
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
validity
andusage
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
type
andrequires
attributes toextension
tags. -
2016-02-22 - Change math markup in
len
attributes to use asciidocdelimiters.
-
2016-02-19 - Add
successcodes
anderrorcodes
attributes ofcommand
tags. Add a subsection to the introduction describing the schema choices and how to file issues against the registry. -
2016-02-07 - Add
vendorids
tags for Khronos vendor IDs. -
2015-12-10 - Add
author
andcontact
attributes forextension
tags. -
2015-12-07 - Move
vulkan/vulkan.h
to a subdirectory. -
2015-12-01 - Add
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
validity
tags. Still out of date WRT extension enumerants, but that will change soon. -
2015-09-08 - Rename
threadsafe
attribute toexternsync
, andimplicitunsafeparams
tag toimplicitexternsync
. -
2015-09-07 - Update
command
tag description to remove thethreadsafe
attribute and replace it with a combination ofthreadunsafe
attributes on individual parameters, andimplicitunsafeparams
tags describing additional unsafe objects for the command. -
2015-08-04 - Add
basetype
andfuncpointer
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
threadsafe
,queues
, andrenderpass
attributes ofcommand
tags, and ofmodified
attributes ofparam
tags. -
2015-06-17 - add descriptions of allowed
category
attribute values oftype
tags, used to group and sort related categories of declarations together in the generated header. -
2015-06-04 - Add examples of making changes and additions to the registry.
-
2015-06-03 - Move location to new
vulkan
Git repository. Add definition oftype
tags for C struct/unions. Start adding 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.