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