The Khronos^® Vulkan^® API Registry

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.

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.

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.

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:

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.

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.

None.

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

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

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

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

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

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

The valid contents depend on the category attribute.

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:

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.

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

An example showing a tag with attribute type`="enum"` is given above. The following example is for non-enumerated tokens.

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

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

None.

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

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:

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:

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

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

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.

When processed into a C header, this results in

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.

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

Each extensions block contains zero or more 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).

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.

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):

These attribues are allowed only for a require tag.

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

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

The corresponding header file will include definitions like this:

If you are adding to the API, perform the following steps to create the description of that API element:

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.

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:

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.

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

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

Then go to the enums block labelled

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:

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

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

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

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:

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

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

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

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:

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.

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:

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:

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

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:

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

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:

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:

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.

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

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:

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:

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.

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.

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.

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

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.

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.