diff options
Diffstat (limited to 'codegen/vulkan/registry.txt')
| -rw-r--r-- | codegen/vulkan/registry.txt | 2575 |
1 files changed, 0 insertions, 2575 deletions
diff --git a/codegen/vulkan/registry.txt b/codegen/vulkan/registry.txt deleted file mode 100644 index baa49141..00000000 --- a/codegen/vulkan/registry.txt +++ /dev/null @@ -1,2575 +0,0 @@ -// 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. |