Author: Jon Leech

# The Khronos® Vulkan® API Registry

Jon Leech
version 1.4.350, 2026-05-13 16:39:33Z
from git branch: makepkg commit: 81b1d516cbf42f04a3c7f781977c499945b5e5dc

Loading… please wait.

Copyright 2014-2026 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

https://github.com/KhronosGroup/Vulkan-Docs

The authoritative copy of the Registry is maintained in the default branch, currently `main`.

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

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

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

https://github.com/KhronosGroup/Vulkan-Headers/

### 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

https://github.com/KhronosGroup/Vulkan-Docs/issues

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.

Jon Leech and Tobias Hector. Vulkan Documentation and Extensions: Procedures and Conventions (February 26, 2023). https://registry.khronos.org/vulkan/specs/latest/styleguide.html .

Khronos Vulkan Working Group. Vulkan 1.4 - A Specification (December 2, 2024). https://registry.khronos.org/vulkan/ .

## 2. Getting Started

See `xml/BUILD.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. If you build at the latest repository tag, the resulting headers should be identical to the latest versions in the Vulkan-Headers repository.

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

Other Makefile targets in `xml/` include:

- `validate` - validate `vk.xml` against the XML schema. Recommended if you are making nontrivial changes.

- The asciidoc includes used by the Vulkan API 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` and scripts `genvk.py`, `reg.py`, and `generator.py`. The scripts are described below and are all located in the `scripts` directory under the repository root.

### 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 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 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. 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 the `requires` 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 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`.

### 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 `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.

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

- `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 a `type` tag, and resulting in a C `enum` 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.

- `formats` - defines properties of image formats. Only one tag is used, wrapping all the formats.

- `spirvextensions` - defines relationship between SPIR-V extensions and API interfaces which enable each extension. Only one tag is used, wrapping all the SPIR-V extensions.

- `spirvcapabilities` - defines relationship between SPIR-V capabilities and API interfaces which enable each capability. Only one tag is used, wrapping all the SPIR-V capabilities.

- `sync` - Defines sync objects

- `syncstage` - Defines all Pipeline Stages

- `syncaccess` - Defines all Access Types

- `syncpipeline` - Defines Pipeline’s logical ordering

- `videocodecs` - Defines video codecs

- `videocodec` - Defines a video codec category or specific video codec

- `videoprofiles` - Defines video profiles supported by a specific video codec

- `videoprofilemember` - Defines video profiles with respect to specific video profile structure members

- `videoprofile` - Defines a video profile with respect to specific video profile structure members

- `videocapabilities` - Specifies a capability structure that applies to the video codec category or specific video codec

- `videoformat` - Defines a video format category that applies to the video codec category or specific video codec

- `videoformatproperties` - Specifies a video format property structure that applies to a video format category

- `videorequirecapabilities` - Defines a video capability prerequisite

#### 5.2.1. Comment Tags (`comment` Tag)

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

- `comment` - optional. Arbitrary string (unused).

### 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

- `name` - required. The platform name. This must be a short alphanumeric string corresponding to the platform name, valid as part of a C99 identifier. Lower-case is preferred. In some cases, it may be desirable to distinguish a subset of platform functionality from the entire platform. In these cases, the platform name should begin with the entire platform name, followed by `_` and the subset name.

  Note | For example, `name="xlib"` is used for the X Window System, Xlib client library platform. `name="xlib_xrandr"` is used for the XRandR functionality within the `xlib` platform.

- `protect` - required. This must be a C99 preprocessor token beginning with `VK_USE_PLATFORM_` followed by the platform name, converted to upper case, followed by `_` and the extension suffix of the corresponding window system-specific extension supporting the platform.

  Note | For example, `protect="VK_USE_PLATFORM_XLIB_XRANDR_EXT"` is used for the `xlib_xrandr` platform name.

- `comment` - optional. Arbitrary string (unused).

### 7.2. Contents of `platform` Tags

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

## 8. Author ID Blocks (`tags` Tag)

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

### 8.1. Attributes of `tags` Tags

- `comment` - optional. Arbitrary string (unused).

### 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

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

### 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

- `comment` - optional. Arbitrary string (unused).

### 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 Windows `HANDLE`, the `type` tag can insert a `#include` directive to pull in that header.

### 11.1. Shared Attributes of `type` Tags

All `type` tags may include these attributes:

- `alias` - optional (unless not allowed by other tags, as defined below). Another type name which this type is an alias of. Must match the name of another `type` element. This is typically used when promoting a type defined by an extension to a new core version of the API. The old extension type is still defined, but as an alias of the new type.

- `api` - optional comma-separated list of 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 (unless not allowed by other tags, as defined below). A string which indicates that this type contains a more complex structured definition. At present the only accepted categories are `basetype`, `bitmask`, `define`, `enum`, `funcpointer`, `group`, `handle`, `include`, `struct`, and `union`, as described below.

- `comment` - optional. Arbitrary string (unused).

- `requires` - optional. Another type name this type requires to complete its definition.

- `deprecated` - optional. Indicates that this type has been marked as legacy. Possible values are:

  - `"true"` - marked as legacy, but no explanation given.

  - `"aliased"` - an old name not following Vulkan conventions. The equivalent alias following Vulkan conventions should be used instead.

- `name` - optional (unless required by other tags, as described below). Name of this type (if not defined in the tag body).

### 11.2. C Type Declarations

Several `type` `category` categories permit or require a C type declaration in the tag content. This is free-form text which must be legal C, but the content can, and sometimes must contain embedded tag metadata:

- `type` - optional. May appear multiple times. Contains text which is a valid type name found in another `type` tag, and indicates that this type must be previously defined for the definition of the type to succeed.

- `name` - contains the name of this type (if not defined in the `name` attribute).

- `comment` - optional. Contains an arbitrary string (unused).

#### 11.2.1. Constraints on Type Categories

There is not a hard restriction on which sorts of definitions may be made in a given category, but the intended purpose of each category should be respected. In particular, when generating header files, types within each category are grouped together, and categories are generated in the order given by the following list.

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:

- `basetype` - built-in C language types; scalar API typedefs, such as the definition of `VkFlags`; and types defined by external APIs, such as an underlying OS or window system.

- `bitmask` - enumeration types whose members are bitmasks.

- `define` - C macro `#define` directives.

- `enum` - enumerated types.

- `funcpointer` - C function pointer typedefs.

- `handle` - scalar API types defined using platform-dependent macros, such as `VkInstance`.

- `include` (`#include`) directives).

- `struct` and `union` - the corresponding C aggregate types.

### 11.3. Contents of `type` Tags

The valid combinations of additional attributes, and valid contents of `type` tags are defined below.

#### 11.3.1. Dependency Relationships

When both the `name` and `requires` tags are present, but the `category` tag is not present, the tag simply defines a dependency relationship - whatever required the specified `name` will also require the specified `requires`.

This form is used when referring to external header files that define multiple external types, such as the `X11/Xlib.h` header which defines X11 types such as `Display` and `VisualID`.

No additional attributes are allowed for dependency relationships, including `alias`.

No content is allowed for dependency relationships.

#### 11.3.2. Base Types - `category` `"basetype"`

Base types are scalar or incomplete types, either external such as Android’s `ANativeWindow` or Vulkan types such as `VkBool32`.

No additional attributes are allowed for base types, including `alias`.

Base type content consists of a C Type Declaration.

#### 11.3.3. Bitmask Types - `category` `"bitmask"`

Bitmask types are scalar types representing a mask of 32 or 64 bits, as typedefs of `VkFlags` or `VkFlags64`.

If the `alias` attribute is specified, the `name` attribute must also be specified, and no content is allowed.

Otherwise, the `name` is optional and is normally not provided. Other attributes which may be specified in this case are:

- `requires` - containing the name of a 32-bit `Vk*FlagBits` `enum` type defining individual flag values.

- `bitvalues` - contains the name of a 64-bit `Vk*FlagBits2` `enum` type defining individual flag values. This is used instead of `requires` because these types do not define an actual C enumerated types for their flag values, defining them simply as `uint64_t` values.

Bitmask type content consists of a C Type Declaration.

#### 11.3.4. Macro Definitions - `category` `"define"`

Macro definitions are uncommon and used for purposes such as the Vulkan API version defined by the header file, or for assembling a version number from major, minor, release, and variant numbers.

The `name` is optional and is normally not provided, being specified in the content instead.

Macro definition content consists of a <<`types`:declarations, C Type Declaration>>. However, unlike most such declarations, the content does not actually define a type. Instead, the content is a legal C `#define` statement.

#### 11.3.5. Enumeranted Type References - `category` `"enum"`

Enumeranted types refer to `enums` tags where individual enumerants for the type are defined.

The `name` attribute must be specified.

If the `alias` attribute is specified, `name` is declared as an alias of that enumerated type.

Otherwise, `name` must match the `name` of a `enum` which actually defines individual enumerant values. Those values are used to generate the type declaration.

Note | The `enums` tag is not redundant. It is simpler to use `enums` as a container that is indirectly referred to, than to have included the enumerant definitions inside the type tag.

No content is allowed.

#### 11.3.6. Function Pointers - `category` `"funcpointer"`

Function pointer types represent callback functions passed by an application to Vulkan API commands for purposes such as allocations and debugging.

The `name` is optional and is normally not provided.

No additional attributes are allowed for function pointer types, including `alias`.

The content of a function pointer tag is structurally identical to the content of a `command` tag. Refer to that tag for the allowed content. However, instead of generating a declaratio of a function prototype and corresponding pointer to that function, only the function pointer is generated.

Note | Many attributes are supported for `command` `param` tags, primarily used to generate valid usage statements, which are only relevant when calling into Vulkan - not in callbacks from it. While these attributes are syntactically legal for function pointer types, they are not used when generating the function pointer and should not be included.

#### 11.3.7. Handle Types - `category` `"handle"`

Handle types are scalar types representing a handle to an object in the Vulkan implementation, such as `VkDevice` or `VkInstance`. They are defined using compile time macros, since the representation of a handle differs depending on the ABI and API variant being compiled for.

If the `alias` attribute is specified, the `name` attribute must also be specified, and no content is allowed.

Otherwise, the `name` is optional and is normally not provided. Other attributes which may be specified in this case are:

- `parent` - optional. Name of another handle type which this type is a subclass of, such as `parent="VkDevice"` for a `VkQueue` handle.

- `objtypeenum` - required. Name of a `VkObjectType` enumerant which specifies this handle type.

Handle content consists of a <<`types`:declarations, C Type Declaration>>. The declaration should use the `VK_DEFINE_HANDLE` or `VK_DEFINE_NON_DISPATCHABLE_HANDLE` macros with the handle `name` as an argument.

#### 11.3.8. Include Files - `category` `"include"`

Include file definitions are uncommon. They are used to define C `#include` files needed by the Vulkan headers to define external types, including video codec headers; and to pull in the platform-dependent `vk_platform.h` header included with the Vulkan SDK.

The `name` attribute is required. It is usually the pathname of the external header file to include.

No additional attributes are allowed for function pointer types, including `alias`.

If present, include file content should be a C `#include` directive for the specified `name`.

Note | Include files which are external headers, such as `X11/Xlib.h`, usually do not have tag content. These headers can be included under application control from the platform-dependent `vulkan.h` header, or explicitly included by the application. Include files which are Vulkan video codec headers are not platform-dependent, but included with the Vulkan SDK. Tag content for these files explicitly includes them.

#### 11.3.9. Structure Types - `category` `"struct"` or `"union"`

Structure and union types define the corresponding C types.

If the `alias` attribute is specified, the `name` attribute must also be specified, and no content is allowed.

Otherwise, the `name` is required. Many other attributes may be specified

Other attributes which may be specified in this case are:

- `allowduplicate` - optional. Must be `"true"` or `"false"`. The default value if unspecified is `"false"`. If `"true"`, then more than one instance of this type may be present in a `pNext` chain.

- `requiredlimittype` - optional. If provided, the attribute value must be `"true"`. The default value if unspecified is `"false"`. If `"true"`, then this type’s `member` tags, other than `sType` and `pNext`, must include `limittype` attributes.

- `returnedonly` - optional. If provided, the attribute value must be `"true"`. The default value if unspecified is `"false"`. If `"true"`, it indicates that this type will always be filled in (returned by) the API from a query, rather than filled in by an application passing it to the API. In this case, the type’s `pNext` `member` must be declared `const`.

- `structextends` - optional. This is a comma-separated list of structures whose `pNext` chain can include this type. This should 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 at once, rather than each extending structure repeating the list of valid structs. There is no need to set the `noautovalidity` attribute on the `pNext` members of extending structures.

Struct and union content is 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. Member tags may define many attributes providing metadata about that member.

##### Attributes of `member` Tags

- `altlen` - if the `len` attribute (see below) is also specified, and contains a `latexmath:` equation, this contains one or more of the other options for representing an array length defined for that attribute, separated by commas (one for each array indirection). This attribute is for consumers of the XML who need to generate validation code from the allowed length without wanting to parse arbitrary LaTeX formatting.

- `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. This is the only case in which the same `member` `name` may appear multiple times.

- `deprecated` - optional. Indicates that this member has been marked as legacy. Possible values are:

  - `"true"` - marked as legacy, but no explanation given.

  - `"unused"` - this member is not used by the implementation and must be 0.

- `externsync` - optional. If provided, the attribute value must be `"true"`. The default value if unspecified is `"false"`. If `"true"`, it indicates whether the member should be externally synchronized when accessed by Vulkan.

- `featurelink` - optional. This attribute is only used for members representing a boolean API feature, when the anchor link in the Vulkan Specification does not match the member `name`. Used for features in extensions that were later promoted but with changes. The attribute value should be a feature name for which a corresponding `features-name` anchor exists.

- `len` - optional. Valid length of the data array described by the member, in array elements. If the member is a static array, the length must be less than or equal to the size of the array. If not present for a static array, all elements of the array are considered valid. If the member is a pointer, `len` is the length of the pointed-to data. `len` must contain one or more expressions defining length (one for each level of array indirection), separated by commas. Each expression may be one of:

  - an equation in math markup for incorporation in the specification (a LaTeX math expression delimited by `‘and‘`. The only variables in the equation should be the names of members of the structure. Use the `altlen` attribute in this case to provide both human- and code-friendly representations of the length.

  - the name of another `member` of the structure specifying the length for the corresponding indirection;

  - `"null-terminated"`, indicating a pointer to a null-terminated UTF-8 string;

  - `"1"` indicating it is just a pointer (used for nested pointers);

  - a C99 expression that refers to another member of the structure, indirectly specifying the length for the corresponding indirection;

  - or a custom expression that cannot be used directly by code generation and needs manual handling in generators.

- `limittype` - optional. Specifies the type of a device limit corresponding to the `member`. Only applicable for members of `VkFormatProperties`, `VkFormatProperties2`, `VkPhysicalDeviceProperties`, `VkPhysicalDeviceProperties2`, `VkPhysicalDeviceLimits`, `VkQueueFamilyProperties`, `VkQueueFamilyProperties2`, `VkSparseImageFormatProperties`, `VkSparseImageFormatProperties2`, `VkVideoCapabilitiesKHR`, `VkVideoFormatPropertiesKHR`, and structures extending or members of any of those structures. The attribute value describes how a value should be compared with the value of a member in order to check whether it fits the limit. Valid `limittype` values are:

  - `"min"` and `"max"` denote minimum and maximum limits. They may also apply to arrays and `VkExtent*D`. For `VkBool32`, if the property is `VK_TRUE`, `"min"` indicates the presence of a requirement, while `"max"` indicates the presence of a capability, respectively.

  - `"pot"` denotes a value that must be a power of two. They may also apply to arrays and `VkExtent*D`.

  - `"mul"` denotes a value that must be an integer multiple of this limit. They may also apply to arrays and `VkExtent*D`.

  - `"bits"` corresponds to the bits precision of an implementation.

  - `"bitmask"` corresponds to bitmasks, where set bits indicate the presence of a capability.

  - `"range"` specifies a [min, max] range.

  - `"struct"` means that the member’s fields should be compared.

  - `"exact"` specifies a limit that must exactly match the member value.

  - `"noauto"` limits cannot be trivially compared and must be manually handled in generators. `"noauto"` is the default value, if `limittype` is needed but unspecified.

- `noautovalidity` - optional. If provided, the attribute value must be `"true"`. The default value if unspecified is `"false"`. If `"true"`, it prevents automatic validity language being generated for the `member`. Note that this only suppresses item-specific validity - parenting relationships, for example, are still generated.

- `objecttype` - optional. Only applicable for members which are Vulkan object handles. The attribute value is the name of another `member`, whose value must be a `VkObjectType` or `VkDebugReportObjectTypeEXT` value specifying the type of object the handle refers to.

- `optional` - optional. Must be `"true"` or `"false"`. The default value if unspecified is `"false"`. `"true"` specifies that this member can contain a sentinel value indicating that no corresponding object or explicit value is referred to: `NULL` for pointers, `VK_NULL_HANDLE` for handles, or 0 for other scalar types. `"false"` specifies that the member must contain a value object reference or explicit value. If the member is a pointer, multiple values may be provided, separated by commas - one for each pointer indirection. Structure members with `name` `pNext` must always be specified with `optional="true"`, since there is no requirement that any member of a `pNext` chain have a following member in the chain.

  Note | While the `optional` attribute can be used for scalar types such as integers, it does not affect the output generators included with the Vulkan API Specification. In this case, the attribute serves only as an indicator to human readers of the XML. Explicitly specifying `optional="false"` is not supported, but `optional="false,true"` is supported for a pointer type.

- `selection` - optional. For a member of a union, `selection` identifies one or more comma-separated values of the `selector` that indicate this member is valid.

- `selector` - optional. For a member of a union, `selector` is the name of another member of the type that is used to select which of that union’s members are valid.

- `stride` - optional. If the member is an array, `stride` is the name of another member of the type containing the byte stride between consecutive elements in the array. The array is assumed to be tightly packed if omitted.

- `values` - optional. This attribute must be provided for the `sType` `member` of a structure, but may not be provided for other members. The attribute value is a comma-separated list of names of enumerants that are valid for the structure type. Usually there is only a single value.

##### Contents of `member` Tags

Member content consists of a <<`types`:declarations, C Type Declaration>>. In addition to the allowed tags for such a declaration, the following tags are supported:

- `name` tag - required. Contains the struct or union member name being described. Unlike other C type declarations, the `name` tag must always be provided in `member` tags.

- `enum` - optional. May appear multiple times. Contains a valid enumerant name found in another `type` tag, and which must be previously defined for the definition of the struct or union to be complete. Normally this is used only to semantically tag static array lengths.

- `comment` - optional. Contains an arbitrary string (unused).

### 11.4. 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>dstEnum</name></member>
            <member><type>Vklongint</type> <name>dstVal</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.

## 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

- `name` - optional. String naming the C `enum` type whose members are defined by this enum group. If present, this attribute should match the `name` attribute of a corresponding `type` tag.

- `type` - required. String describing the data type of the values of this group of enums. The accepted categories are `bitmask`, `constants`, and `enum`, as described below.

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

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

### 12.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

## 13. Enumerants (`enum` Tag)

Each `enum` tag defines a single API token.

### 13.1. Attributes of `enum` Tags

- `value` is a numeric value in the form of a legal C expression when evaluated at compile time in the generated header files. This is usually either a literal integer value or the name of an alias for a previously defined value, though more complex expressions are sometimes employed for compile time constants.

- `bitpos` is a literal integer bit position in a bitmask. The bit position must be in the range [0,30] when used as a flag bit in a `Vk*FlagBits` data type. Bit positions 31 and up may be used for values that are not flag bits, or for flag bits used with 64-bit flag types. Exactly one of `value` and `bitpos` must be present in an `enum` tag.

- `name` - required. Enumerant name, a legal C preprocessor token name.

- `api` - optional comma-separated list of 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.

- `deprecated` - optional. Indicates that this enum has been marked as legacy. Possible values are:

  - `"true"` - marked as legacy, but no explanation given.

  - `"unused"` - this enum is not used by the implementation and must not be passed to the API.

  - `"aliased"` - an old name not following Vulkan conventions. The equivalent alias following Vulkan conventions should be used instead.

- `type` - may be used only when `value` is specified. In this case, `type` is optional except when defining a compile time constant, in which case it is required when using some output generator paths. If present the attribute must be a C scalar type corresponding to the type of `value`, although only `uint8_t`, `uint32_t`, `uint64_t`, and `float` are currently meaningful. `type` is used by some output generators to generate constant declarations, although the default behavior is to use C `#define` for compile time constants.

- `alias` - optional. Name of another enumerant this is an alias of, used where token names have been changed as a result of profile changes or for consistency purposes. An enumerant alias is simply a different `name` for the exact same `value` or `bitpos`.

- `protect` - optional. An additional preprocessor token or boolean expression used to protect an enum definition with conditional compilation directives in generated headers. May be a single preprocessor token (e.g. `VK_USE_PLATFORM_WIN32_KHR`) or a boolean expression using the same syntax as `depends`, extended with support for logical NOT:

  - `,` for logical OR

  - `+` for logical AND

  - `()` for grouping

  - `!` prefix on a token for logical NOT

    `,` and `+` are of equal precedence, and lower than `()`. Expressions are evaluated left-to-right for operators of the same precedence.

    Single tokens (with no operators) generate `#ifdef` directives in the output header, while expressions generate `#if` directives with `defined()` macros around each term (and `!defined()` for negated terms).

    Examples:

- `protect="VK_A"` generates `#ifdef VK_A`

- `protect="VK_A,VK_B"` generates `#if defined(VK_A) || defined(VK_B)`

- `protect="VK_A+VK_B"` generates `#if defined(VK_A) && defined(VK_B)`

- `protect="(VK_A+VK_B),VK_C"` generates `#if (defined(VK_A) && defined(VK_B)) || defined(VK_C)`

- `protect="VK_A+!VK_B"` generates `#if defined(VK_A) && !defined(VK_B)`

Note | Tagging two enums with the same value and no other context will result in an error during spec generation, to avoid accidental aliasing. However there are times where aliasing is deliberate and desirable. Using `alias` on an `enum` indicates that two values are deliberate aliases of each other. For example, the following tag defines `VK_ENUM_TYPE_NEW` as a new alias of `VK_ENUM_TYPE_ORIGINAL`:
    <enum extends="VkEnumType" name="VK_ENUM_TYPE_NEW" alias="VK_ENUM_TYPE_ORIGINAL">
Typically this will result in a C definition explicitly aliasing the other:
    VK_ENUM_TYPE_NEW = VK_ENUM_TYPE_ORIGINAL;
Providing a `bitpos` or `value` tag alongside the `alias` tag will still indicate that the aliasing is deliberate:
    <enum extends="VkEnumType" value="0" name="VK_ENUM_TYPE_NEW" alias="VK_ENUM_TYPE_ORIGINAL">
However the generated C will use the `bitpos` or `value` instead:
    VK_ENUM_TYPE_NEW = 0;

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

- `start` - required, `end` - optional. Integers defining the start and end of an unused range of enumerants. `start` must be ≤ `end`. If `end` is not present, then `start` defines a single unused enumerant. This range should not exceed the range reserved by the surrounding `enums` tag.

- `vendor` - optional. String describing the vendor or purposes to whom a reserved range of enumerants is allocated. Usually identical to the `vendor` attribute of the surrounding `enums` block.

- `comment` - optional. Arbitrary string (unused).

### 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

- `comment` - optional. Arbitrary string (unused).

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

- `tasks` - optional. A comma-separated list of tasks this command performs, as described in the “Queue Operation” section of the Vulkan API Specification. The tasks may include `"action"`, `"indirection"`, `"state"`, and `"synchronization"`.

- `queues` - optional. A comma-separated list of command queue types this command can be placed on. The queue types are Vulkan `VkQueueFlagBits` names.

- `successcodes` - optional. A comma-separated list of possible successful return codes from the command. The codes are Vulkan `VkResult` code names.

- `errorcodes` - optional. A comma-separated list of possible error return codes from the command. The codes are Vulkan `VkResult` code names.

  Note | `errorcodes` must include `VK_ERROR_UNKNOWN` and `VK_ERROR_VALIDATION_FAILED` even if there are no other possible error codes.

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

- `videocoding` - optional. A string identifying whether the command can be issued only inside a video coding scope (`"inside"`), only outside a video coding scope (`"outside"`), or both (`"both"`); the default is `"outside"` for commands that do not specify it.

- `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 (`","`).

- `conditionalrendering` - required for `vkCmd*` commands. Not allowed for other commands. A value of `"true"` specifies that this command is affected by conditional rendering, and `"false"` that it is not affected.

- `allownoqueues` - optional. A value of `"true"` specifies that this command can be used in a device with no queues. If not present, the value is assumed to be `"false"`.

- `export` - optional. A comma-separated list of names exporting this command. The names are arbitrary words, but usually correspond to Vulkan loader or library names.

- `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 that `name` is an alias of. The string must be the same as the `name` value of another `command` defining another command.

Both forms of `command` support these options:

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

### 16.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 no `param` 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 of `param` tags, each containing asciidoc source text describing an object which is not a parameter of the command but is related to one, and which also 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`.

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

- The `type` tag is optional, and contains text which is a valid type name found in a `type` tag. It indicates that this type must be previously defined for the definition of the command to succeed.

- The `name` tag is required, and contains the command name being described.

### 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

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

- `len` - valid length of the data described by the parameter. If the parameter is a static array, `len` must be less than or equal to the size of the array; if not present for a static array, all elements of the array are considered valid. If the parameter is a pointer, `len` is the length of the pointed-to data. `len` must contain one or more expressions defining length (one for each array indirection), separated by commas. Each expression may be one of:

  - an equation in math markup for incorporation in the specification (a LaTeX math expression delimited by `‘and‘`. The only variables in the equation should be the names of parameters of the command;

  - the name of another parameter of the command specifying the length for the corresponding indirection;

  - `"null-terminated"`, indicating a pointer to a null-terminated UTF-8 string;

  - `"1"` to indicate it is just a pointer (used for nested pointers);

  - a C99 expression that refers to another parameter of the command indirectly specifying the length for the corresponding indirection;

  - or a custom expression that cannot be used directly by code generation and needs manual handling.

- `altlen` - if the `len` attribute is specified, and contains a `latexmath:` equation, this contains one or more of the other options above, separated by commas (one for each array indirection). This attribute is intended to support consumers of the XML who need to generate validation code from the allowed length.

- `stride` - if the member is an array, stride specifies the name of another member containing the byte stride between consecutive elements in the array. The array is assumed to be tightly packed if omitted.

- `optional` - optional. A value of `"true"` specifies that this parameter can be omitted by providing `NULL` (for pointers), `VK_NULL_HANDLE` (for handles), or 0 (for other scalar types). If not present, the value is assumed to be `"false"` (the parameter must not be omitted). If the parameter is a pointer to one of those types, multiple values may be provided, separated by commas - one for each pointer indirection.

  Note | While the `optional` attribute can be used for scalar types such as integers, it does not affect the output generators included with the Vulkan API Specification. In this case, the attribute serves only as an indicator to human readers of the XML. Explicitly specifying `optional="false"` is not supported, but `optional="false,true"` is supported for a pointer type.

- `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 application threads. If the parameter needs to be externally synchronized under specific conditions, a value of `"maybe"` is used to indicate that the exact rule is specified in the Valid Usage language. If only a certain member of an object or elements of an array are modified, an expression string may be provided, describing the member which is modified. This expression may be prefixed by `maybe:` to indicate conditional external synchronization requirements specified in the Valid Usage language. For example, the `vkSetDebugUtilsObjectNameEXT` command includes `externsync` attributes for the `pNameInfo` parameter indicating that a specific member of the parameter is externally synchronized:

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

- `objecttype` - only applicable for parameters which are `uint64_t` values representing a Vulkan object handle. Specifies the name of another parameter which must be a `VkObjectType` or `VkDebugReportObjectTypeEXT` value specifying the type of object the handle refers to.

- `validstructs` - optional. Allowed only when the parameter type is a pointer to an abstract `VkBaseInStructure` or `VkBaseOutStructure` type. This is a comma-separated list of structures which can either be passed as the parameter, or can appear anywhere in the `pNext` chain of the parameter.

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

- The `type` tag is optional, and contains text which is a valid type name found in `type` tag, and indicates that this type must be previously defined for the definition of the command to succeed.

- The `name` tag is required, and contains the parameter name being described.

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

Some API features may be defined for internal usage only, and not exposed to the public. These are tagged with the `apitype` attribute set to `internal`. These features are not emitted in the generated headers and other artifacts. Instead, they are merged into the first public feature that depends on them. This is done automatically by the generator scripts. If you wish to avoid this merging behavior, you can specify the `-no-internal-api-merging` option to the genvk.py script.

### 17.1. Attributes of `feature` Tags

- `api` - required comma-separated list of API names for which this feature is defined, such as `vulkan`.

- `apitype` - optional. Whether the API block should be exposed publicly (default) or if it is for internal usage. Valid values are `internal` or `public`. Defaults to `public` if not specified.

- `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, but deprecated and will eventually be removed. Feature version number, usually a string interpreted as `majorNumber.minorNumber`. Example: `4.2`.

  Note | `number` is deprecated, replaced by `depends`. `number` is retained only for backwards compatibility with downstream consumers, and will eventually be removed.

- `depends` - optional. String containing a boolean expression of one or more API core version and extension names. The feature requires the expression in the string to be satisfied to use any functionality it defines. Supported operators include `,` for logical OR, `` for logical AND, and `(` `)` for grouping. `,` and `` are of equal precedence, and lower than `(` `)`. Expressions must be evaluated left-to-right for operators of the same precedence. Terms which are core version names are true if the corresponding API version is supported. Terms which are extension names are true if the corresponding extension is enabled.

  Note | `depends` replaces the `number` attribute used in the past. The expected purposes of this attribute include sorting features in dependency order when emitting them from generator scripts, and ensuring that all dependent features are included when building with a specified feature.

- `sortorder` - optional. A decimal number which specifies an order relative to other `feature` tags when calling output generators. Defaults to `0`. Used when ordering by `name` is insufficient.

- `protect` - optional. An additional preprocessor token or boolean expression used to protect a feature definition. Usually another feature or extension `name`. Used when the definition of a feature or extension requires another to be defined first. Supports boolean expressions using the same syntax as `depends` (see `protect` under `enum` for details).

- `comment` - optional. Arbitrary string (unused).

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 `deprecate` tags, 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

- `comment` - optional. Arbitrary string (unused).

### 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 an `number` 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

- `name` - required. Extension name, following the conventions in the Vulkan API Specification. Example: `name="VK_VERSION_1_0"`.

- `number` - required. A decimal number which is the registered, unique extension number for `name`.

- `sortorder` - optional. A decimal number which specifies an order relative to other `extension` tags when calling output generators. Defaults to `0`. Used when ordering by `number` is insufficient.

- `author` - optional. The author name, such as a full company name. If not present, this can be taken from the corresponding `tag` attribute. However, `EXT` and other multi-vendor extensions may not have a well-defined author or contact in the tag. This attribute is not used in processing the XML. It is just metadata, mostly used to track the original author of an extension (which may have since been promoted to use a different author ID).

- `contact` - optional. The contact who registered or is currently responsible for extensions and layers using the tag, including sufficient contact information to reach the contact such as individual name together with GitHub username (`@username`), Khronos internal Gitlab username (`gitlab:@username`) if no public GitHub contact is available, or other contact information. If not present, this can be taken from the corresponding `tag` attribute just like `author`.

- `type` - required if the `supported` attribute is not `'disabled'`. Must be either `'device'` or `'instance'`, if present.

- `depends` - optional. String containing a boolean expression of one or more API core versions and extension names. The extension requires the expression in the string to be satisfied to use any functionality it defines (for instance extensions), or to use any device-level functionality it provides (for device extensions). Supported operators include `,` for logical OR, `` for logical AND, and `(` `)` for grouping. `,` and `` are of equal precedence, and lower than `(` `)`. Expressions must be evaluated left-to-right for operators of the same precedence. Terms which are core version names are true if the corresponding API version is supported. Terms which are extension names are true if the corresponding extension is enabled.

  Note | `depends` is a breaking change in Vulkan 1.3.241, replacing the `requires` and `requiresCore` attributes. For example, an extension which previously specified these two attributes in `vk.xml`: `requires="VK_KHR_dep_a,VK_EXT_dep_b"` `requiresCore="1.1"` should replace them both with `depends="VK_VERSION_1_1+VK_KHR_dep_a+VK_EXT_dep_b"` Note that the use of `,` in the old `requires` attribute was treated as a logical AND, and must be replaced by `+` in the `depends` attribute.

- `protect` - optional. An additional preprocessor token or boolean expression used to protect an extension definition. Usually another feature or extension `name`. Used when the definition of a feature or extension requires another to be defined first. Supports boolean expressions using the same syntax as `depends` (see `protect` under `enum` for details).

- `platform` - optional. Indicates that the extension is specific to the platform identified by the attribute value, and should be emitted conditional on that platform being available, in a platform-specific header, etc. The attribute value must be the same as one of the `platform` `name` attribute values.

- `supported` - comma-separated list of required API names for which this extension is defined. When the extension tag is just reserving an extension number, use `supported="disabled"` to indicate this extension should never be processed. Interfaces defined in a `disabled` extension block are tentative at best and must not be generated or otherwise used by scripts processing the XML. The only exception to this rule is for scripts used solely for reserving, or checking for reserved bitflag values.

- `ratified` - optional comma-separated list of API names for which this extension has been ratified by the Khronos Board of Promoters. Defaults to the empty string if not specified.

- `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"`. As discussed in the “Extending Vulkan” chapter of the Vulkan API Specification, the `promotedto` relationship is not a promise of exact API-level compatibility, and replacing use of one interface with the other must not be done purely mechanically.

- `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. Defaults to `"false"` if not specified.

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

- `nofeatures` - optional. `"true"` if this extension is intended to not have any individual `feature` tags, `"false"` otherwise. Defaults to `"false"` if not specified.

- `comment` - optional. Arbitrary string (unused).

Note | The `depends` attribute is used to specify other extensions that must be enabled for an extension to be enabled. In some cases, an extension may include functionality which is only defined if another extension is enabled. Such functionality should be specified within a `require` tag, using the `depends` 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 marked as 'legacy' by a `feature`. This will mark the tagged functionality in the spec as legacy or superseded by this version. Extensions should never deprecate interfaces, although this usage is allowed by the schema. For historical reasons, the `deprecate` block is still called 'deprecate', but we now use the terms 'legacy' or 'superseded' in the specification instead.

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

### 20.1. Attributes of `require`, `remove`, and `deprecate` Tags

- `profile` - optional. String name of an API profile. Interfaces in the tag are only required, removed, or deprecated if the specified profile is being generated. If not specified, interfaces are required, removed, or deprecated for all API profiles.

- `comment` - optional. Arbitrary string (unused).

- `api` - optional comma-separated list of API names requiring, removing, or deprecating these interfaces. Interfaces in the tag are only required, removed, or deprecated if the requested API name matches an element of the attribute. If not specified, interfaces are required, removed, or deprecated for all APIs.

Note | The `api` attribute is only supported inside `extension` tags, since `feature` tags already define a specific API.

### 20.2. Attributes of `require` Tags

These attributes are allowed only for a `require` tag.

- `depends` - optional, and only for `require` tags. String containing a boolean expression of one or more API core version and extension names. The syntax of this string is identical to that of the `extension` `depends` attribute, except that feature Booleans may additionally be included using C struct notation (e.g. `VkStructName::parameterName`). Terms which are feature Booleans are true if the corresponding feature is enabled for device level functionality, or simply supported otherwise. Interfaces in the tag are only required if the expression is satisfied.

  Note | `depends` is a breaking change in Vulkan 1.3.241, replacing the `extension` and `feature` attributes.

### 20.3. Attributes of `remove` Tags

These attributes are allowed only for a `remove` tag.

- `reasonlink` - optional, and only used when generating individual `feature` documentation. String containing the name of an asciidoc anchor in the Vulkan API Specification to link to, explaining the removal.

### 20.4. Attributes of `deprecate` Tags

These attributes are allowed only for a `deprecate` tag.

- `explanation` - a link to an explanation in the specification of why the tagged functionality is deprecated.

### 20.5. Contents of `require`, `remove`, and `deprecate` Tags

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

#### 20.5.1. Comment Tags

`comment` (as described above).

#### 20.5.2. Command Tags

`command` specifies a required, removed, or deprecated 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).

- `supersededby` - optional. Name of command it is superseded by, `deprecate` block only.

#### 20.5.3. Enum Tags

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

- `name` - required. Name of the enumerant.

- `comment` - optional. Arbitrary string (unused).

- `api` - optional comma-separated list of 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.

- `supersededby` - optional. Name of enum it is superseded by, `deprecate` block only.

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

- `value` and `type` - define a constant value in the same fashion as an `enum` tag in an `enums` block.

- `bitpos` - define a constant bitmask value in the same fashion as an `enum` tag in an `enums` 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 an `enum` tag.

- `extends` - the name of a separately defined enumerated type (e.g. a `type` tag with `category``="enum"`) to which the extension enumerant is added. The enumerated type is required to complete the definition of the enumerant, in the same fashion as the `requires` attribute of a `type` tag. 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 corresponding `extension` tag with the same `number`. This is used when an extension or core feature needs to extend an enumerated type in a block defined by a different extension.

- Attribute `offset` - the offset within an extension block. If `extnumber` is not present, the extension number defining that block is given by the `number` attribute of the surrounding `extension` tag. The numeric value of an enumerant is computed as defined in the `Assigning Extension Token Values` section of the Vulkan Documentation and Extensions: Procedures and Conventions document.

- 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 as `dir="-"`.

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

- `protect` - define a preprocessor protection symbol or boolean expression for the enum in the same fashion as an `enum` tag in an `enums` block. See `protect` under `enum` for syntax details.

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 a `extension`. 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 enumerants are given below.

#### 20.5.4. Type Tags

`type` specifies a required, removed, or deprecated 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 attributes:

- `name` - required. Name of the type.

- `comment` - optional. Arbitrary string (unused).

- `supersededby` - optional. Name of type it is superseded by, `deprecate` block only.

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

- `name` - feature name(s). Can be a single element or a comma-separated list. Each element is the name of the feature, and also the name of a member of the corresponding `struct` structure. If multiple elements are present, indicates that at least one of the elements must be supported. Multiple tags should be used to require multiple features.

- `struct` - feature structure name. Name of the structure queried to determine support for the feature. Must only ever be a single struct name, and all elements of `name` must be from the same structure.

- `comment` - optional. Arbitrary string (unused).

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 `feature` tags 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

- `name` - required. Format name, matching a `VkFormat` `enum` `name`. Example: `name="VK_FORMAT_R8_UNORM"`.

- `class` - required. Format class. A string whose value is shared by a group of formats which may be compatible, and is a textual description of something important that group has in common. Example: `class="8-bit"`.

- `blockSize` - required. A decimal integer which is the texel block size, in bytes, of the format.

- `texelsPerBlock` - required A decimal integer which is the number of texels in a texel block of the format.

- `blockExtent` - optional. Three-dimensional extent of a texel block. A comma-separated list of three decimal integers. If not present, `blockExtent="1,1,1"` is assumed.

- `packed` - optional. A decimal integer which is the number of bits into which the format is packed. If defined, a single image element in this format can be stored in the same space as a scalar type of this bit width.

- `compressed` - optional. A string whose value is shared by a group of formats which use the same general texture compression scheme, and is a textual description of that scheme. Example: `compressed="ASTC LDR"`.

- `chroma` - optional. A string used to mark if Y′CBCR samplers are required by default when using this format. Must be one of the three values `"420"`, `"422"`, or `"444"` corresponding to different Y′CBCR encodings.

### 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

- `name` - required. A string specifying the name of this component. Must be one of the values `"R"`, `"G"`, `"B"`, `"A"`, `"D"`, or `"S"` corresponding to red, green, blue, alpha, depth, and stencil components, respectively.

- `bits` - required. Must be either a decimal integer which is the number of bits in this component, or `"compressed"`, corresponding to a specific compression scheme.

- `numericFormat` - required. A string specifying the scalar data type of the component. Must be one of the following values:

  - `"BOOL"` - boolean integer values where 0 is false, and non-zero is true.

  - `"SFIXED5"` - signed fractional integer values that get converted to floating-point in the range [-1024,1023.96875]

  - `"SFLOAT"` - signed floating-point numbers

  - `"SINT"` - signed integer values in the range [-2n-1,2n-1-1]

  - `"SNORM"` - signed normalized values in the range [-1,1]

  - `"SRGB"` - R, G, and B components are unsigned normalized values that represent values using sRGB nonlinear encoding, while the A component (if one exists) is a regular unsigned normalized value

  - `"SSCALED"` - signed integer values that get converted to floating-point in the range [-2n-1,2n-1-1]

  - `"UFLOAT"` - unsigned floating-point numbers (used by packed, shared exponent, and some compressed formats)

  - `"UINT"` - unsigned integer values in the range [0,2n-1]

  - `"UNORM"` - unsigned normalized values in the range [0,1]

  - `"USCALED"` - unsigned integer values that get converted to floating-point in the range [0,2n-1]

- `planeIndex` - optional. A decimal integer specifying which plane this component lies in. If present, must correspond to the `index` attribute value of a `plane` tag for the same `component`.

### 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

- `index` - required. An integer specifying the image plane being defined. Image planes are in the range [0,p-1] where p is the number of planes in the format.

- `widthDivisor` - required. An integer specifying the relative width of this plane. A value of k means that this plane is 1/k the width of the overall format.

- `heightDivisor` - required. An integer specifying the relative height of this plane. A value of k means that this plane is 1/k the height of the overall format.

- `compatible` - required. A string naming another, single-plane format that this plane is compatible with. Must match the `name` of another `format`.

### 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

- `name` - required. The name of the SPIR-V image format. Example: `name="R11fG11fB10f"`.

### 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

- `comment` - optional. Arbitrary string (unused).

### 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

- `name` - required. SPIR-V extension name. Example: `name="SPV_KHR_variable_pointers"`

### 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

- `comment` - optional. Arbitrary string (unused).

### 28.2. Contents of `spirvcapabilities` Tags

Each `spirvcapabilities` block contains zero or more `spirvcapability` tags, 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

- `name` - required. SPIR-V capability name. Example: `name="SPV_KHR_variable_pointers"`

### 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 a `spirvextension` 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 with `spirvextension` tags. Each form is described separately below.

### 30.1. Attributes for API Version Number Enables

- `version` - required. An API feature name, matching a `feature` `name` attribute value.

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

### 30.2. Attributes for API Extension Enables

- `extension` - required. An API extension name, matching an `extension` `name` attribute value.

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

### 30.3. Attributes for API Feature Enables

- `struct` - required. An API feature structure name, matching a `type` `name` attribute of a structure `type`.

- `feature` - required. An API feature name, matching a `member` `name` value of the feature structure.

- `requires` - required. A comma-separated list of API feature version numbers and/or extension names.

- `alias` - optional. Another API feature name which is an alias of `feature`. Needed when the same feature is provided by two different API versions or extensions.

If one of the API feature version numbers or extensions in the `requires` list 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

- `property` - required. An API feature structure name, matching a `type` `name` attribute of a structure `type`.

- `member` - required. An API property name, matching a `member` `name` value of the `property` structure.

- `value` - required. A value, matching an API `enum` `name` value. If the property is a bitfield, `value` must be a bitmask value belonging to the `member` bitfield type. Otherwise, `value` must be an `enum` name defined for the `member` enumeration type.

- `requires` - optional. A comma-separated list of API feature version numbers and/or extension names.

If one of the API feature version numbers or extensions in the `requires` list 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

- `name` - required. A Vulkan `VkPipelineStageFlagBits2` name.

- `alias` - optional. A semantically equivalent Vulkan `VkPipelineStageFlagBits` name which is an alias of `name`.

### 31.2. Contents of `syncstage` Tags

More information about the Pipeline stage using either `syncequivalent` or `syncsupport`

## 32. Sync Access (`syncaccess` Tag)

The `syncaccess` tag contains definitions of each Access mask.

### 32.1. Attributes of `syncaccess` Tags

- `name` - required. A Vulkan `VkAccessFlagBits2` name.

- `alias` - optional. A semantically equivalent Vulkan `VkAccessFlagBits` name which is an alias of `name`.

### 32.2. Contents of `syncaccess` Tags

More information about the Access mask using either `syncequivalent` or `syncsupport`

## 33. Sync Pipeline (`syncpipeline` Tag)

The `syncpipeline` tag contains definitions of each type of Pipeline.

### 33.1. Attributes of `syncpipeline` Tags

- `name` - required. A unique string identifying the pipeline.

### 33.2. Contents of `syncpipeline` Tags

Zero or more `syncpipelinestage` tags describing each pipeline stage in logical order. Stages have extra attributes describing special ordering within the list.

## 34. Sync Pipeline Stage (`syncpipelinestage` Tag)

The `syncpipelinestage` tag contains definitions of a stage for a `syncpipeline`.

### 34.1. Attributes of `syncpipelinestage` Tags

- order - optional. Must be `"None"` if present, indicating ???.

- before - optional. A Vulkan `VkPipelineStageFlagBits2` name of a pipeline stage following this stage.

- after - optional. A Vulkan `VkPipelineStageFlagBits2` name of a pipeline stage preceding this stage.

### 34.2. Contents of `syncpipeline` Tags

A Vulkan `VkPipelineStageFlagBits2` name of this pipeline stage.

## 35. Sync Support (`syncsupport` Tag)

The `syncsupport` tag defines support for a given Sync element.

### 35.1. Attributes of `syncsupport` Tags

- `queues` - optional. A comma-separated list of queue types that are supported. Each queue type is a Vulkan `VkQueueFlagBits` name.

- `stage` - optional. A comma-separated list of sync stage names that are supported. This is used to cross-reference with `syncstage`

## 36. Sync Equivalent (`syncequivalent` Tag)

The `syncequivalent` tag defines a one-to-many relationship of Sync elements

### 36.1. Attributes of `syncequivalent` Tags

- `stage` - optional. A comma-separated list of sync stages that are the OR logical equivalence of the parent `syncstage`.

- `access` - optional. A comma-separated list of sync accesses that are the OR logical equivalence of the parent `syncstage`.

## 37. Video Codecs (`videocodecs` Tag)

The `videocodecs` tag contains information about video codecs.

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

### 38.1. Attributes of `videocodec` Tags

- `name` - descriptive name of the video codec category or specific video codec

- `extend` - descriptive name of the video codec category a specific video codec specializes

- `value` - the `VkVideoCodecOperationFlagBitsKHR` value identifying a specific video codec

## 39. 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.

### 39.1. Attributes of `videoprofiles` Tags

- `struct` - name of the video profile info structure corresponding to the specific video codec

## 40. Video Profile Member (`videoprofilemember` Tag)

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

### 40.1. Attributes of `videoprofilemember` Tags

- `name` - name of the video profile structure member

## 41. Video Profile (`videoprofile` Tag)

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

### 41.1. Attributes of `videoprofile` Tags

- `name` - descriptive name of the video profile

- `value` - value of the video profile structure member in case of this video profile

## 42. Video Capabilities (`videocapabilities` Tag)

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

### 42.1. Attributes of `videocapabilities` Tags

- `struct` - name of the video capability structure

## 43. Video Format (`videoformat` Tag)

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

### 43.1. Attributes of `videoformat` Tags

- `name` - descriptive name of the video format category

- `usage` - image usage flags expected to be specified in `VkPhysicalDeviceVideoFormatInfoKHR::imageUsage` to query the format properties for the video format category ("," and "+" can be used to express disjunction and conjunction, respectively)

## 44. Video Format Properties (`videoformatproperties` Tag)

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

### 44.1. Attributes of `videoformatproperties` Tags

- `struct` - name of the video format property structure

## 45. Video Capability Prerequisites (`videorequirecapabilities` Tag)

The `videorequirecapabilities` tag can be used inside `videoformat` 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.

### 45.1. Attributes of `videorequirecapabilities` Tags

- `struct` - name of the capability structure used to determine the precondition

- `member` - name of the capability structure member used to determine the precondition

- `value` - the value the member should have to meet the precondition ("," and "+" can be used to express disjunction and conjunction, respectively)

## 46. 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.

### 46.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`, or `command` tags defining the interface in question.

- Make sure that all added types and commands appropriately tag their dependencies on other types by adding nested `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.

### 46.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.

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.

#### 46.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 &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 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" 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 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 2015-2026 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.

### 46.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`.

### 46.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:

- a single C decimal integer or floating-point value

- optionally prefixed with `~`

- optionally suffixed with `U`, `UL`, `ULL`, or `F`

- and the entire expression optionally surrounded by paired `(` and `)`.

### 46.5. 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 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"`.

### 46.6. 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 labeled

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

### 46.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 `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.

#### 46.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 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.

### 46.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 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.

### 46.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.

### 46.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.

### 46.11. 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.

### 46.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.

## 47. Change Log

- 2026-04-07 - Add support for `!` (logical NOT) prefix on tokens in `protect` boolean expressions, generating `!defined()` in output headers.

- 2026-03-04 - Update the `"ignored"` value for the `deprecated` attribute to match updated spec (internal issue 4725), rename to "unused".

- 2026-02-18 - Update the `enum` and `member` `deprecated` attribute to describe `"ignored"` consistently with the generators and specification (internal MR 7998).

- 2026-01-16 - Add support for boolean expressions in the `protect` attribute of several tags.

- 2026-01-14 - Update the `type` `category` `funcpointer` schema to support better semantic tagging, using the same syntax as `command` tags. Heavily refactor the `type` tag descriptions to separately describe the different categories of types, and their allowed schema (internal issue 5).

- 2025-11-11 - Update the `returnedonly` attribute of structure type tags to note that `pNext` members must not be `const` if `returnedonly` is true (internal issue 2734).

- 2025-07-31 - Update the `queues` attribute to use Vulkan flag bit names instead of colloquial simplifications of them, add descriptions of a few missing tags and attributes, and use more consistent phrasing in describing attribute values which are comma-separated lists of separate values (internal issue 4393).

- 2025-06-18 - Allow `selection` attributes of members of `"union"` types to include multiple comma-separated selections of the same member (internal issue 4246).

- 2025-06-11 - Add command attribute `conditionalrendering` to specify if a `vkCmd*` command may be affected by conditional rendering (internal issue 4287).

- 2025-05-07 - Add "maybe" and "maybe:<expression>" to `externsync` (internal issues 4175 and 4217)

- 2025-04-23 - Add `deprecate` blocks to features.

- 2025-03-19 - Establish and clarify the use of "min" and "max" limit types for boolean limits and remove the, now obsolete, "not" limit type.

- 2025-02-19 - Clean up description of the `member` `limittype` `"exact"` value (internal MR 7142).

- 2024-11-12 - Add `extension` `nofeatures` attribute to identify extensions which are known to not have individual `feature` tags (internal issue 3946).

- 2024-10-14 - Add ability to include features in 'depends' attributes for require blocks, as well as enabling simple lists of or/and dependencies

- 2024-09-25 - Add ability to have multiple features as an or’d list of requirements

- 2024-09-18 - Support the `stride` attribute for array pointers in both command `param` and <<`type`, structure `member`>> tags (public issue 2435).

- 2024-08-22 - Add `remove` attribute `reasonlink` and `required` and `remove` attribute `feature`, to support adding requirements for individual Vulkan features to the schema (internal issue 3478).

- Added notes on alternate registry processing frameworks and referred to them for rarely used attributes in the `feature` tag (public issue 2395).

- 2024-07-18 - Remove out of date guidance that builtin and external types should not be wrapped in `type` tags, replaced with actual examples in the `type` section (public issue 2394).

- 2024-07-10 - Add video related meta information tags

- 2024-05-28 - Deprecate the `feature` `number` attribute with the new `depends` tag (public issue 2327).

- 2024-05-08 - Add a `enums` `type` `"constants"` value for compile time constant definitions so they can be treated more consistently (public issue 2359).

- 2024-04-03 - Add `"SFIXED5"` as an allowed `component` `numericFormat` type (internal issue 3802).

- 2024-03-20 - Add a NOTE to the `command` `errorcodes` attribute that certain errors should never be included in the attribute (internal issue 3824).

- 2024-01-31 - Specify the meaning of the `member` `len` attribute of structure members when the member is a static array (internal issue 3743).

- 2023-11-24 - Clarify that the `promotedto` relationship which may be defined for `extension` tags does not promise exact API-level compatibility (internal issue 4819).

- 2023-06-28 - remove support for `member` and `param` `optional` attribute value `"false"` (internal issue 3548).

- 2023-06-14 - removed deprecated `start` and `end` from `enums`

- 2023-05-18 - Add `sync` to help define all sync objects in the XML

- 2023-03-29 - add `extension` `ratified` attribute to express ratification status.

- 2023-02-26 - add normative references section, cite it as needed, and update description of `extension` tags to refer to the style guide for computing numeric enumerant values (public issue 2069).

- 2023-02-22 - specify that `depends` expressions are evaluated left-to-right for operators of the same precedence (public issue 2062).

- 2023-02-14 - replace `extension` attributes `requiresCore` and `requires`, and `require` attributes `feature` and `extension`, by a new `depends` attribute. This is an intentional breaking change to support a more flexible and consistent expression syntax for these dependencies (internal issues 2883, 3272).

- 2023-01-11 - add `deprecated` attribute to `enum`, `type`, and `type` `member` tags.

- 2022-11-23 - update `command` `queues` syntax to include all queue types currently in use.

- 2022-08-12 - update `requires` `extension` syntax to support logical OR and AND constructs for multiple extensions (internal issue 2922).

- 2022-07-11 - Add `videocoding` attribute to `command` tags to indicate whether a command buffer command can be recorded inside, outside, or both inside and outside of a video coding scope.

- 2022-06-29 - Add `command` attribute `tasks` (internal issue 3117).

- 2022-06-22 - Add `validstructs` attribute to command `param` tags when using an abstract `VkBaseInStructure` or `VkBaseOutStructure` as the formal parameter type.

- 2022-06-16 - Add `VkSparseImageFormatProperties*` to the list of structure types allowed to have 'limittype' member attributes.

- 2022-06-08 - Add `exact`, `bits`, `mul` and `pot` limit types.

- 2022-06-08 - Update description of types to which the `limittype` attribute of structure `member` tags can be applied (internal issue 3101).

- 2022-06-08 - Update description of `extension` `requires` attribute such that the specified extensions must be enabled, not just supported. This is consistent with the following NOTE, the specification description of “required extensions”, and actual use in the XML of this attribute (internal issue 3116).

- 2021-12-13 - Add `api` attribute to the `member` and `param` tags.

- 2021-11-29 - Add `api` attribute to the `command` tag.

- 2021-10-11 - Add description of the `formats` tag for describing Vulkan `VkFormat` image formats, and of the `spirvextensions` and `spirvcapabilities` tags for describing enabling mechanisms for SPIR-V extensions (internal issue 2484).

- 2021-09-13 - Further clarify that `api` and `supported` attributes are comma-separated list of API names (internal issue 2809).

- 2021-08-22 - Update introductory descriptions of toolchain and scripts.

- 2021-08-15 - Add an explicit description of the `enum` `extends` attribute as introducing a requirement for the enumerated type being extended.

- 2021-07-12 - Note that `extension` tags describing instance extensions must not have dependencies on device extensions (internal issue 2387).

- 2021-06-14 - Add an `objecttype` attribute which specifies the relationship between a Vulkan handle and another member or parameter specifying the type of object that handle refers to (public issue 1536).

- 2021-06-06 - Update description of the `supported` attribute of `extension` tags to mandate that `disabled` extensions are not processed (public issue 1549).

- 2021-04-21 - Add the `limittype` attribute to structure `member` tags, to describe how queried limits are interpreted (internal issue 2427).

- 2021-03-30 - Add a description of the allowed format of compile time constants (internal merge request 4451).

- 2021-03-22 - Update allowed values for the `type` attribute of `enum` tags and make it mandatory (internal issue 2564).

- 2021-01-11 - Expand the scope of the `optional` attribute `member` and `param` tags to specify that the member or parameter may be 0 for all scalar types, not just bitmasks and array sizes (internal issue 2435).

- 2020-11-23 - Add `objtypeenum` attribute to <<`type`, `type`>> tags to link the object name to the corresponding `VK_OBJECT_TYPE_*` enumerant, if any (internal issue 2393).

- 2020-11-22 - Add requirement that `pNext` members have the `optional="true"` attribute set (internal issue 2428).

- 2020-10-14 - Remove advice to set the `noautovalidity` attribute on the `pNext` 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` in `type` tags to include external API types.

- 2020-02-20 - Clarify that `enum` tags inside `remove` 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 to `feature` and `extension` tags.

- 2018-12-06 - Specify that command aliases are not guaranteed to resolve to the same entry point in the underlying layer stack, matching a related clarification in the Vulkan Specification.

- 2018-10-01 - Add description of the default value of `optional` member and parameter attributes, if not specified.

- 2018-08-28 - Add optional `provisional` attribute to `extension` tags.

- 2018-07-07 - Add optional `promotedto`, `deprecatedby`, and `obsoletedby` attributes to `extension` tags.

- 2018-06-25 - Remove `vendorids` tags for Khronos vendor IDs.

- 2018-05-08 - Add `driverids` and `driverid` 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` and `alias` attributes used for defining `enum` attributes, the `alias` attribute used for defining `type` aliases, the `name` and `alias` attributes used for defining `command` aliases, the `platform` attribute of `extension` tags, and the `feature` attribute of `require` tags; and update the document to the header naming and grouping scheme used starting in Vulkan 1.1.

- 2018-01-07 - Add `platforms` and `platform` 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` attribute `type` must be specified if the extension is not disabled.

- 2017-07-27 - Finish removing validextensionstructs attribute and replacing it with structextends.

- 2017-07-14 - Add comment attributes or tags as valid content in several places, replacing XML comments which could not be preserved by XML transformation tools.

- 2017-02-20 - Change to asciidoctor markup and move into the specification source directory for ease of building.

- 2016-09-27 - Remove `validity` and `usage` tags, since these explicit usage statements have been moved to the specification source.

- 2016-08-26 - Update for the single-branch model.

- 2016-07-28 - Add `type` and `requires` attributes to `extension` tags.

- 2016-02-22 - Change math markup in `len` attributes to use asciidoc `‘and‘` delimiters.

- 2016-02-19 - Add `successcodes` and `errorcodes` attributes of `command` 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` and `contact` attributes for `extension` 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 to `externsync`, and `implicitunsafeparams` tag to `implicitexternsync`.

- 2015-09-07 - Update `command` tag description to remove the `threadsafe` attribute and replace it with a combination of `threadunsafe` attributes on individual parameters, and `implicitunsafeparams` tags describing additional unsafe objects for the command.

- 2015-08-04 - Add `basetype` and `funcpointer` `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`, and `renderpass` attributes of `command` tags, and of `modified` attributes of `param` tags.

- 2015-06-17 - add descriptions of allowed `category` attribute values of `type` 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 of `type` 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.