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