The Khronos® Vulkan® API Registry (original) (raw)

Copyright 2014-2025 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.

The registry uses an XML representation of the Vulkan API, together with a set of Python scripts to manipulate the registry once loaded. The scripts rely on the Python etree package to parse and operate on XML. An XML schema and validator target are included.

The schema is based on, but not identical to that used for the previously published OpenGL, OpenGL ES and EGL API registries. It was extended to represent additional types and concepts not needed for those APIs, such as structure and enumerant types, as well as additional types of registered information specific to Vulkan.

The Vulkan C header files generated from the registry are checked into a separate repository under

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.

1.2. Normative References

Normative references are references to external documents or resources to which documentation authors must comply.

2. Getting Started

Seexml/README.adocin 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:

This should regenerate vulkan_core.h and a variety of platform-specific headers, install them in ../include/vulkan/, and verify that the headers build properly. If you build at the latest repository tag, the resulting headers should be identical to the latest versions in theVulkan-Headers repository.

The install target also generates source code for a simple extension loader library in ../src/ext_loader/.

Other Makefile targets in xml/ include:

If you just want to modify the API, changing vk.xml and running makeshould 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 filesvk.xml and scripts genvk.py, reg.py, and generator.py. The scripts are described below and are all located in the scriptsdirectory under the repository root.

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 currentVulkan API 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 ingenerator.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:

3. Alternate Registry Processing Frameworks

We encourage people needing to process registry XML to use the Python generator framework. It has been successfully used by many other projects, such as OpenXR and many of its software components

Be aware that the schema is not static. Over time, we have introduced a number of non-breaking changes in the form of additional XML tags and attributes. On rare occasion we have made a breaking change, such as replacing therequires syntax and requiresCore attributes for specifying extension and version dependencies with the depends attribute.

While such changes are supported in the Python scripts when they are made, downstreams using other XML processing code are responsible for tracking and implementing corresponding changes.

3.1. Rarely Used Tags and Attributes

If you do implement your own XML processing framework, you are responsible for complying with the interpretation of the schema and its contents, and producing results consistent with the Python framework.

Choosing to not implement processing of certain tags or attributes may produce incorrect outputs. If you are doing this because the tags or attributes are not currently used in the Vulkan XML, you may want to flag a warning or error when they are encountered.

4. Vulkan Registry Schema

The format of the Vulkan registry is a top level registry tag containingtypes, 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.

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

4.2. API Names

Specific API versions features and extensions can be tagged as belonging 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 supportedattribute 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 supportapi 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.

5. Registry Root (registry Tag)

A registry contains the entire definition of one or more related APIs.

5.1. Attributes of registry Tags

None.

5.2. Contents of registry Tags

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

A comment tag contains an arbitrary string, and is unused. Comment tags may appear in multiple places in the schema, as described below. Comment tags are removed by output generators if they would otherwise appear in generated headers, asciidoc include files, etc.

6. Platform Name Blocks (platforms Tag)

A platforms contains descriptions of platform IDs for platforms supported by window system-specific extensions to Vulkan.

6.1. Attributes of platforms Tags

6.2. Contents of platforms Tags

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

7. Platform Names (platform Tag)

A platform tag describes a single platform name.

7.1. Attributes of platform Tags

7.2. Contents of platform Tags

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

A tags tag contains authorid tags describing reserved author IDs used by extension and layer authors.

8.1. Attributes of tags Tags

8.2. Contents of tags Tags

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

9. Author IDs (tag Tag)

A tag tag contains information defining a single author ID.

9.1. Attributes of tag Tags

9.2. Contents of tag Tags

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

10. API Type Blocks (types Tag)

A types tag contains definitions of derived types used in the API.

10.1. Attributes of types Tags

10.2. Contents of types Tags

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.

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

For builtin C types, the corresponding type tag should be an empty stub.

For derived types which are expected to be defined in a header file outside the scope of the Vulkan API, such as an X11 VisualID or a WindowsHANDLE, the type tag can insert a #include directive to pull in that header.

11.1. Attributes of type Tags

11.2. Contents of type Tags

The valid contents depend on the category attribute.

11.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 thename attribute of a enums tag. The enumerant values defined within the enums tag are used to generate a C enum type declaration.

11.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
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:

11.2.3. All Other Types

If the category attribute is one of basetype, bitmask, define,funcpointer, group, handle or include, or is not specified, typecontains text which is legal C code for a type declaration. It may also contain embedded tags:

There is no restriction on which sorts of definitions may be made in a given category, although the contents of tags with category enum, structor 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:

11.3. Example of a types Tag

<types>
    <type name="stddef">#include &lt;stddef.h&gt;</type>
    <type requires="stddef">typedef ptrdiff_t <name>VKlongint</name>;</type>
    <type name="VkEnum" category="enum"/>
    <type category="struct" name="VkStruct">
        <member><type>VkEnum</type> <name>srcEnum</name></member>
        <member><type>VkEnum</type> <name>dstEnum</name></member>
    </type>
</types>

<enums name="VkEnum" type="enum">
    <enum value="0" name="VK_ENUM_ZERO"/>
    <enum value="42" name="VK_ENUM_FORTY_TWO"/>
</enums>

The VkStruct type is defined to require the types VkEnum and VKlongintas 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.

12. 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 const or define tags. This is a historical hangover from the OpenGL XML format which this schema was based on.

12.1. Attributes of enums Tags

12.2. Contents of enums Tags

Each enums block contains zero or more enum, unused, andcomment tags, in arbitrary order (although they are typically ordered by sorting on enumerant values, to improve human readability).

12.3. Example of enums Tags

An example showing a tag with attributetype`="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

13. Enumerants (enum Tag)

Each enum tag defines a single API token.

13.1. Attributes of enum Tags

Note Using alias on an enum means you want the name defined by the tag to be treated as an alias of the token name in the alias attribute value. For example, the following tag defines VK_ALIAS as an alias of VK_VALUE: <enum name="VK_ALIAS" alias="VK_VALUE">
Note In older versions of the schema, type was described as allowing only the C integer suffix types u and ull, which is inconsistent with the current definition. However, type was not actually used in the registry processing scripts or vk.xml at the time the current definition was introduced, so this is expected to be a benign change.

13.2. Contents of enum Tags

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

14. 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 unused tags could be generated and inserted automatically, which would be a good way to avoid the attributes becoming out of date. However, they are rarely used in the Vulkan XML schema, unlike the OpenGL XML schema it was based on.

14.1. Attributes of unused Tags

14.2. Contents of unused Tags

None.

15. Command Blocks (commands Tag)

The commands tag contains definitions of each of the functions (commands) used in the API.

15.1. Attributes of commands Tags

15.2. Contents of commands Tags

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

16. Commands (command Tag)

The command tag contains a structured definition of a single API command (function).

16.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:

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:

Both forms of command support these options:

16.2. Contents of command Tags

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

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 vkGetInstanceProcAddror vkGetDeviceProcAddr.

16.3. Command Prototype (proto Tags)

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

16.3.1. Attributes of proto Tags

None.

16.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:

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

16.4.1. Attributes of param Tags

<param externsync="pNameInfo-&gt;objectHandle">const <type>VkDebugUtilsObjectNameInfoEXT</type>* <name>pNameInfo</name></param>

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

16.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:

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

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

17.1. Attributes of feature Tags

Note The sortorder and protect attributes may not be used in the XML at times. If writing an alternate registry processing framework, refer to the notes on rarely used tags and attributes.
Note The name attribute used for Vulkan core versions, such as"VK_VERSION_1_0", is not an API construct. It is used only as a preprocessor guard in the headers, and an asciidoctor conditional in the specification sources. The similar "VK_API_VERSION_1_0" symbols are part of the API and their values are packed integers containing Vulkan core version numbers.

17.2. Contents of feature Tags

Zero or more require, remove, and deprecatetags, in arbitrary order. Each tag describes a set of interfaces that is respectively required for, removed from, or deprecated by this feature, as described below.

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

18. Extension Blocks (extensions Tag)

The extensions tag contains definitions of each of the extensions which are defined for the API.

18.1. Attributes of extensions Tags

18.2. Contents of extensions Tags

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

19. 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 annumber attribute, it instead has a supported attribute, which describes the set of API names which the extension can potentially be implemented against.

19.1. Attributes of extension Tags

Note The depends attribute is used to specify other extensions that mustbe enabled for an extension to be enabled. In some cases, an extension may include functionality which is only definedif another extension is enabled. Such functionality should be specified within a require tag, using thedepends attribute to specify that extension.

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

19.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="&quot;VK_KHR_display_swapchain&quot;"
              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

20. Required, Removed, and Deprecated Interfaces (require, remove, and deprecate 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.

A deprecate block defines a set of interfaces 'deprecated' by afeature. This will mark the tagged functionality in the spec as deprecated by this version. Extensions should never deprecate interfaces, although this usage is allowed by the schema.

Except for the tag name and behavior, the contents of require, removeand deprecate tags are identical.

20.1. Attributes of require, remove, and deprecate Tags

Note The api attribute is only supported inside extension tags, sincefeature tags already define a specific API.

20.2. Attributes of require Tags

These attributes are allowed only for a require tag.

20.3. Attributes of remove Tags

These attributes are allowed only for a remove tag.

20.4. Attributes of deprecate Tags

These attributes are allowed only for a deprecate tag.

20.5. Contents of require, remove, and deprecate Tags

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

comment (as described above).

20.5.2. Command Tags

command specifies a required, removed, or deprecated command defined in acommands block. The tag has no content, but contains attributes:

20.5.3. Enum Tags

enum specifies a required, removed, or deprecated enumerant defined in an enumsblock. All forms of this tag support the following attributes:

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 an enums block. This is typically used for constants not part of an enumerated type.

Extension enums define the value of an enumerant inline in a featureor 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:

Not all combinations of attributes are either meaningful or supported. The protect attribute may always be present. For other attributes, the allowed combinations are:

Table 1. Valid Combinations of enum Attributes for Extension Enums

Description value bitpos alias offset extnumber dir extends
Numeric value Yes No No No No No Yes2
Bitmask value No Yes No No No No Yes2
Alias of another enumerant No No Yes No No No Yes2
Value added to an enumeration No No No Yes Yes1 Yes3 Yes

[1]: Optional. If extnumber is not present, the enum tag may only be within aextension. Otherwise, the enum tag may also be within a feature.

[2]: Optional. If extends is not present, the enumerant value is a global constant. Otherwise, the value is added to the specified enumeration.

[3]: Optional. If not present, the computed value will be positive.

Examples of various types of extension enumerantsare given below.

20.5.4. Type Tags

type specifies a required, removed, or deprecated type defined in a typesblock. 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 attributes:

20.6. 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.6.1. Individual Feature Tags

feature specifies a required, removed, or deprecated feature, as described in the “Features” chapter of the Vulkan API Specification. The tag has no content, but contains attributes:

Note This tag has the same name as the API Features tag. This is an unfortunate consequence of overloading the term “feature”, originally used in the XML schema to refer to a core version of the API but also used in the Vulkan API Specification to refer to an individual capability introduced by a new extension or core version. Fortunately, there is no ambiguity in XML parsing since the two featuretags are used at different structural levels.
Warning Please note that including an individual feature tag in a require block with a depends attribute that includes parentheses for complex dependencies is currently not supported, and an error will be generated. This will be fixed in future, as it is intended to be supported, but it was not necessary for feature requirements as initially proposed.

21. Formats (formats Tag)

The formats tag contains definitions of each of the image formats which are defined for the API.

21.1. Attributes of formats Tags

None.

21.2. Contents of formats Tags

A formats block contains zero or more format tags, each describing an image format, in arbitrary order.

22. Image Format (format Tag)

Image formats are described in individual format tags. An image format corresponds to a Vulkan VkFormat enumerant. This tag contains information specifying the structure and meaning of different parts of the format. The meaning of different parts of the format information is described in more detail in the “Format Definition” section of the Vulkan API Specification.

22.1. Attributes of format Tags

22.2. Contents of format Tags

One or more component tags. The order of component tags corresponds to the memory order of components of the format. Each tag describes the size and format of that component.

Zero or more plane tags, in arbitrary order. Each tag describes the scale of a specific image plane of the format relative to the overall format.

Zero or more spirvimageformat tags, in arbitrary order. Each tag describes a SPIR-V format name corresponding to the format.

22.3. Example of a format Tag

<format name="VK_FORMAT_G16_B16R16_2PLANE_420_UNORM" class="16-bit 2-plane 420" blockSize="6" texelsPerBlock="1" chroma="420">
    <component name="G" bits="16" numericFormat="UNORM" planeIndex="0"/>
    <component name="B" bits="16" numericFormat="UNORM" planeIndex="1"/>
    <component name="R" bits="16" numericFormat="UNORM" planeIndex="1"/>
    <plane index="0" widthDivisor="1" heightDivisor="1" compatible="VK_FORMAT_R16_UNORM"/>
    <plane index="1" widthDivisor="2" heightDivisor="2" compatible="VK_FORMAT_R16G16_UNORM"/>
</format>

23. Format Components (component Tag)

The component tag contains definitions of each of the components which are part of an image format.

23.1. Attributes of component Tags

23.2. Contents of component Tags

None.

24. Format Planes (plane Tag)

The plane tag contains definitions of each of the image planes which are part of an image format.

24.1. Attributes of plane Tags

24.2. Contents of plane Tags

None.

25. SPIR-V Image Formats (spirvimageformat Tag)

The spirvimageformat tag specifies the name of a SPIR-V image format equivalent to this format.

25.1. Attributes of spirvimageformat Tags

25.2. Contents of spirvimageformat Tags

None.

26. SPIR-V Extensions (spirvextensions Tag)

The spirvextensions tag contains definitions of each of the SPIR-V extensions which are defined for the API.

26.1. Attributes of spirvextensions Tags

26.2. Contents of spirvextensions Tags

Each spirvextensions block contains zero or more spirvextension tags, each describing a single SPIR-V extension, in arbitrary order.

27. SPIR-V Extension (spirvextension Tag)

SPIR-V extensions are described in individual spirvextension tags. A SPIR-V extension is enabled by API versions or extensions.

27.1. Attributes of spirvextension Tags

27.2. Contents of spirvextension Tags

One or more enable tags, in arbitrary order. Each tag describes a single enabling mechanism for the extension.

27.3. Example of a spirvextensions Tag

<spirvextension name="SPV_KHR_multiview">
    <enable version="VK_VERSION_1_1"/>
    <enable extension="VK_KHR_multiview"/>
</spirvextension>

28. SPIR-V Capabilities (spirvcapabilities Tag)

The spirvcapabilities tag contains definitions of each of the SPIR-V capabilities which are defined for the API.

28.1. Attributes of spirvcapabilities Tags

28.2. Contents of spirvcapabilities Tags

Each spirvcapabilities block contains zero or more spirvcapabilitytags, each describing a single SPIR-V capability, in arbitrary order.

29. SPIR-V Capability (spirvcapability Tag)

SPIR-V capabilities are described in individual spirvcapability tags. A SPIR-V capability is enabled by API versions, extensions, features, or properties.

29.1. Attributes of spirvcapability Tags

29.2. Contents of spirvcapability Tags

One or more enable tags, in arbitrary order. Each tag describes a single enabling mechanism for the capability.

29.3. Example of a spirvcapabilities Tag

<spirvcapability name="ImageCubeArray">
    <enable struct="VkPhysicalDeviceFeatures" feature="imageCubeArray" requires="VK_VERSION_1_0"/>
</spirvcapability>
<spirvcapability name="GroupNonUniform">
    <enable property="VkPhysicalDeviceVulkan11Properties" member="subgroupSupportedOperations" value="VK_SUBGROUP_FEATURE_BASIC_BIT" requires="VK_VERSION_1_1"/>
</spirvcapability>

30. SPIR-V Enables (enable Tag)

The enable tag describes a single mechanism in the API which enables aspirvextension or spirvcapability. There are four forms of enable tags corresponding to different ways the API may advertise enablement, though not all forms may be used withspirvextension tags. Each form is described separately below.

30.1. Attributes for API Version Number Enables

If the API version is supported, the SPIR-V extension or capability is enabled.

30.2. Attributes for API Extension Enables

If the API extension is supported and enabled, the SPIR-V extension or capability is enabled.

30.3. Attributes for API Feature Enables

If one of the API feature version numbers or extensions in the requireslist is supported or enabled, respectively; and if the feature name is enabled in the feature structure, the SPIR-V capability is enabled.

API feature enables are not supported for spirvextension tags.

30.4. Attributes for API Property Enables

If one of the API feature version numbers or extensions in the requireslist is supported or enabled, respectively; and if the member property contains the value bit, or matches the value, the SPIR-V capability is enabled.

API property enables are not supported for spirvextension tags.

30.5. Contents of enable Tags

None.

31. Sync Stage (syncstage Tag)

The syncstage tag contains definitions of each Pipeline stage.

31.1. Attributes of syncstage Tags

31.2. Contents of syncstage Tags

More information about the Pipeline stage using eithersyncequivalent or syncsupport

32. Sync Access (syncaccess Tag)

The syncaccess tag contains definitions of each Access mask.

32.1. Attributes of syncaccess Tags

32.2. Contents of syncaccess Tags

More information about the Access mask using eithersyncequivalent or syncsupport

33. Sync Pipeline (syncpipeline Tag)

The syncpipeline tag contains definitions of each type of Pipeline.

33.1. Attributes of syncpipeline Tags

33.2. Contents of syncpipeline Tags

The syncpipeline lists each pipeline stage in logical order usingsyncpipelinestage. Stages have extra attributes to describe special ordering within the list

34. Sync Support (syncsupport Tag)

The syncsupport tag contains information what support there is for a given Sync element.

34.1. Attributes of syncsupport Tags

35. Sync Equivalent (syncequivalent Tag)

The syncequivalent tag contains information showing a one-to-many relationship of Sync elements

35.1. Attributes of syncsupport Tags

36. Video Codecs (videocodecs Tag)

The videocodecs tag contains information about video codecs.

37. Video Codec (videocodec Tag)

The videocodec tag defines a video codec category (e.g. decode or encode) or specific video codec (e.g. H.264 decode).

37.1. Attributes of videocodec Tags

38. Video Profiles (videoprofiles Tag)

The videoprofiles tag defines video profiles supported by a specific video codec. Actual video profiles are derived as combinations of general video profile information included in VkVideoProfileInfoKHR and additional video codec specific video profile structure member values.

38.1. Attributes of videoprofiles Tags

39. Video Profile Member (videoprofilemember Tag)

The videoprofilemember tag defines video profiles with respect to specific video profile structure members.

39.1. Attributes of videoprofilemember Tags

40. Video Profile (videoprofile Tag)

The videoprofile tag defines a video profile with respect to specific video profile structure members.

40.1. Attributes of videoprofile Tags

41. Video Capabilities (videocapabilities Tag)

The videocapabilities tag specifies a capability structure that applies to the video codec category or specific video codec.

41.1. Attributes of videocapabilities Tags

42. Video Format (videoformat Tag)

The videoformat tag defines a video format category that applies to the video codec category or specific video codec.

42.1. Attributes of videoformat Tags

43. Video Format Properties (videoformatproperties Tag)

The videoformatproperties tag specifies a video format property structure that applies to a video format category.

43.1. Attributes of videoformatproperties Tags

44. Video Capability Prerequisites (videorequirecapabilities Tag)

The videorequirecapabilities tag can be used insidevideoformat tags to define video capability prerequisites for video format categories. If more videorequirecapabilities elements are specified, then the overall precondition is the conjunction of the individual preconditions.

44.1. Attributes of videorequirecapabilities Tags

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

45.1. General Strategy

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.

45.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 correspondingfeature tag.

There are multiple API versions defined for Vulkan at this time. The initial Vulkan 1.0 tag can be found by searching for

<feature api="vulkan" name="VK_VERSION_1_0"

Inside a feature tag are multiple require tags. Some of these tags are used to express extension interactions, and others only as a logical grouping mechanism for related parts of that API feature.

45.2.1. API Feature Walkthrough

This section walks through the first few required API features in thevk.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 &lt;&lt; 22) | (minor &lt;&lt; 12) | patch)
    ...

This section is invoked by the requirement and emits a bunch of boilerplate C code. The explicit dependency is not strictly required since vk_platform will be required by many other types, but placing it first causes this to appear first in the output file.

Note that vk_platform does not correspond to an actual C type, but instead to a collection of freeform preprocessor includes and macros and comments. Most other type tags do define a specific type and are much simpler, but this approach can be used to inject arbitrary C into the Vulkan headerswhen 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 ofvk.xml:

<enums name="API Constants" type="constants"
       comment="Vulkan hardcoded constants - not an enumerated type, part of the header boilerplate">
    <enum type="uint32_t" value="256"   name="VK_MAX_PHYSICAL_DEVICE_NAME"/>
    <enum type="uint32_t" 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 thecommands 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 requiredtype 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 resultingvulkan_core.h header will look like this:

#ifndef VULKAN_H_
#define VULKAN_H_ 1

#ifdef __cplusplus
extern "C" {
#endif

/*
** Copyright 2015-2025 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.

45.3. How to Add a Compile Time Constant

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

<require comment="API constants">

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

    <enum name="VK_THE_ANSWER"/>

Then go to the enums block labeled

<enums name="API Constants" type="constants" ...>

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

The type attribute must be present, and must have one of the allowed values uint32_t, uint64_t, or float.

45.4. Allowed Format of Compile Time Constants

The value attribute must be a legal C99 constant scalar expression when evaluated at compilation time. Allowed expressions are additionally restricted to the following syntax:

45.5. How to Add a Struct or Union Type

For this example, assume we want to define a type corresponding to a Cstruct 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 explicittype dependency should be added to the feature tag. Go to the types tag and search for the nested block labeled

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

45.6. How to Add an Enumerated Type

For this example, assume we want to define a type corresponding to a Cenum 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 labeled

<comment>Vulkan enumerant (token) definitions</comment>

At an appropriate point below this line, add an enums tag whosename 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 valueattribute, in which case the specified numeric value is passed through to the C header unchanged.

45.7. 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:

// Flag bits for VkExampleFlagBits
typedef VkFlags64 VkExampleFlagBits;
static const VkExampleFlagBits VK_EXAMPLE_NONE = 0;
static const VkExampleFlagBits VK_EXAMPLE_FIRST_BIT = 0x00000001;
static const VkExampleFlagBits VK_EXAMPLE_SECOND_BIT = 0x00000002;

typedef VkFlags64 VkExampleFlags;

An explicit 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 labeled:

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

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

<comment>Vulkan enumerant (token) definitions</comment>

At the end of the list of enum definitions below this line, add an enumstag 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 thevalue attribute defining it to have a hard value of 0. The other types have their values are specified using the bitposattribute, 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.

45.7.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 ofVkFlags64, and require the flag bits type, instead of specifying thebitvalues 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.

45.8. 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 thecommand 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.

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

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

45.11. Additional Semantic Tagging

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.

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

46. Change Log