| // Copyright (c) 2013-2018 Khronos Group. This work is licensed under a |
| // Creative Commons Attribution 4.0 International License; see |
| // http://creativecommons.org/licenses/by/4.0/ |
| |
| = The Khronos Vulkan^(R)^ API Registry |
| Jon Leech |
| :data-uri: |
| :icons: font |
| :toc2: |
| :toclevels: 3 |
| :max-width: 100 |
| :numbered: |
| :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::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 `master` branch. |
| |
| [NOTE] |
| .Note |
| ==== |
| The older version of the registry in the `1.0` branch is out of date. |
| ==== |
| |
| 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 in under |
| `include/vulkan/`. |
| |
| |
| == 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/master/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 `master` branch. |
| * 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. The result should be identical to the version you just pulled from |
| Github. They can be compared by, for example: |
| |
| `git diff ../include/vulkan/` |
| |
| 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`, `genvk.py`, `reg.py`, and `generator.py`. |
| |
| If you are using other platforms, issues or merge requests with additional |
| documentation on using the tools on those platforms would be very helpful. |
| |
| |
| == 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 |
| |
| The schema supports, but does not currently use an attr:api attribute on |
| several tags. This is an arbitrary string, specified at header generation |
| time, for labelling properties of a specific API or API profile. The string |
| can be, but is not necessarily, an actual API name. Names starting with `vk` |
| are suggested if and when we start defining profiles of Vulkan. |
| |
| |
| [[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. An API name (see tag:feature below) which |
| specializes this definition of the named type, so that the same API |
| types may have different definitions for e.g. GL ES and GL. This is |
| unlikely to be used in Vulkan, where a single API supports desktop |
| and mobile devices, but the functionality is retained. |
| * 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 chained structures - the chained structures |
| themselves should have their `pNext` tagged with attr:noautovalidity. |
| This will generate a validity statement on the top level structure |
| that validates the entire chain in one go, rather than each chained |
| structure repeating the list of valid structs. |
| |
| == 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 - a value of `"true"` or `"false"` determines whether this |
| member can be omitted by providing `NULL` (for pointers), |
| `VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values |
| that are the size of an array in the same structure. If the member |
| is a pointer to one of those types, multiple values may be provided, |
| separated by commas - one for each pointer indirection. |
| * 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. |
| |
| ==== 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). |
| |
| 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` (scalar typedefs, such as the definition of `VkFlags`) |
| * `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 implementers 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). |
| |
| == 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 or attr:bitpos - exactly one of these is allowed and |
| required. attr:value is an enumerant value in the form of a legal C |
| constant (usually a literal decimal or hexadecimal integer, though |
| arbitrary strings are allowed). attr:bitpos is a literal integer bit |
| position in a bitmask. |
| * attr:name - required. Enumerant name, a legal C preprocessor token |
| name. |
| * attr:api - optional. An API name which specializes this definition |
| of the named enum, so that different APIs may have different values |
| for the same token. May be used to address a subtle |
| incompatibilities. |
| * attr:type - optional. Used only when attr:value is specified. C |
| suffix for the value to force it to a specific type. Currently only |
| `u` and `ull` are used, for `unsigned` 32- and 64-bit integer |
| values, respectively. Separated from attr:value since this eases |
| parsing and sorting of values, and rarely used. |
| * 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. |
| |
| == 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:pipeline - optional. A string identifying the pipeline type |
| that this command uses when executed. The format of the string is one of |
| the terms `"compute"`, `"transfer"`, or `"graphics"`. |
| * 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 resolve to the _same_ |
| entry point in the underlying layer stack. |
| * 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. |
| |
| |
| [[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 - a value of `"true"` or `"false"` determines whether this |
| member can be omitted by providing `NULL` (for pointers), |
| `VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values |
| that are the size of an array in the same command. If the member is |
| a pointer to one of those types, multiple values may be provided, |
| separated by commas - one for each pointer indirection. |
| * 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. |
| -- |
| |
| === 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 name>> this feature is for, |
| such as `vk`. |
| * 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: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: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 |
| avaliable, 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. |
| * 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. A regular expression with an implicit `^` and |
| `$` bracketing it, which should match the attr:api tag of a set of |
| tag:feature tags. When the extension tag is just reserving an extension |
| number, and no interfaces are yet defined, use `supported="disabled"` to |
| indicate this extension should never be processed. |
| * 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_county'. |
| * 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: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. An <<schema:apiname,API name>>. |
| Interfaces in the tag are only required (or removed) if the |
| specified API is being generated. 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. An API name which specializes this definition of |
| the enumerant attr:name, so that different APIs may have different |
| values for the same token. 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. Reference enums are the most common usage, |
| and no attributes other than attr:name and attr:comment are supported |
| for them. |
| |
| _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, although not all combinations of attributes are either meaningful |
| or supported. Possible attributes are described first, followed by the |
| allowed combinations: |
| |
| * 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: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. 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:api - an API name which specializes this definition of the named |
| enum, so that different APIs may have different values for the same |
| token. May be used to address subtle incompatibilities. |
| |
| |
| .Valid Combinations of attr:enum Attributes |
| |==== |
| | 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_theanswer"/> |
| <enum bitpos="29" name="VK_KHR_bitmask"/> |
| <enum offset="0" dir="-" extends="VkResult" |
| name="VK_ERROR_SURFACE_LOST_KHR"/> |
| <enum offset="1" extends="VkResult" |
| name="VK_SUBOPTIMAL_KHR"/> |
| <enum bitpos="31" extends="VkResult" |
| name="VK_KHR_EXTENSION_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 (c) 2015-2018 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 _dummy; }; 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. |
| |
| |
| == 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" name="VK_THE_ANSWER"/> |
| -------------------------------------- |
| |
| |
| == 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,31] 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. |
| |
| |
| == 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 |
| |
| * 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-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. |