/ registry.txt
registry.txt
1 // Copyright (c) 2013-2019 Khronos Group. This work is licensed under a 2 // Creative Commons Attribution 4.0 International License; see 3 // http://creativecommons.org/licenses/by/4.0/ 4 5 = The Khronos^®^ Vulkan^®^ API Registry 6 Jon Leech 7 :data-uri: 8 :icons: font 9 :toc2: 10 :toclevels: 3 11 :max-width: 100 12 :numbered: 13 :doctype: book 14 :imagewidth: 800 15 :fullimagewidth: width="800" 16 :cl: : 17 18 // Various special / math symbols. This is easier to edit with than Unicode. 19 include::config/attribs.txt[] 20 21 :leveloffset: 1 22 23 <<<< 24 25 include::copyright-ccby.txt[] 26 27 <<<< 28 29 [[introduction]] 30 = Introduction 31 32 This document describes the Khronos Vulkan API Registry schema, and 33 provides some additional information about using the registry and 34 scripts to generate a variety of outputs, including C header files as 35 well as several types of asciidoc include files used in the Vulkan API 36 specification and reference pages. The underlying XML files and scripts 37 are located on the Khronos public Github server at URL 38 39 https://github.com/KhronosGroup/Vulkan-Docs 40 41 The authoritative copy of the Registry is maintained in the `master` branch. 42 43 [NOTE] 44 .Note 45 ==== 46 The older version of the registry in the `1.0` branch is out of date. 47 ==== 48 49 The registry uses an XML representation of the Vulkan API, together with 50 a set of Python scripts to manipulate the registry once loaded. The 51 scripts rely on the Python `etree` package to parse and operate on XML. 52 An XML schema and validator target are included. 53 54 The schema is based on, but not identical to that used for the previously 55 published OpenGL, OpenGL ES and EGL API registries. It was extended to 56 represent additional types and concepts not needed for those APIs, such as 57 structure and enumerant types, as well as additional types 58 of registered information specific to Vulkan. 59 60 The Vulkan C header files generated from the registry are checked in under 61 `include/vulkan/`. 62 63 64 == Schema Choices 65 66 The XML schema is not pure XML all the way down. In particular, command 67 return types/names and parameters, and structure members, are described in 68 mixed-mode tag containing C declarations of the appropriate information, 69 with some XML nodes annotating particular parts of the declaration such as 70 its base type and name. This choice is based on prior experience with the 71 SGI `.spec` file format used to describe OpenGL, and greatly eases human 72 reading and writing the XML, and generating C-oriented output. The cost is 73 that people writing output generators for other languages will have to 74 include enough logic to parse the C declarations and extract the relevant 75 information. 76 77 People who do not find the supplied Python scripts to suit their needs 78 are likely to write their own parsers, interpreters, and/or converters 79 operating on the registry XML. We hope that we have provided enough 80 information in this document, the RNC schema (`registry.rnc`), and 81 comments in the Registry (`vk.xml`) itself to enable such projects. If 82 not and you need clarifications; if you have other problems using the 83 registry; or if you have proposed changes and enhancements, then please 84 file issues on Khronos' public Github project at 85 86 https://github.com/KhronosGroup/Vulkan-Docs/issues 87 88 Please tag your issues with `[Registry]` in the subject line to help us 89 categorize them. We have considered separating the registry from the 90 specification source into a separate repository, but since there is so 91 much specification valid usage language imbedded in the registry XML, 92 this is unlikely to happen. 93 94 95 [[starting]] 96 = Getting Started 97 98 See 99 https://gitlab.khronos.org/vulkan/vulkan/blob/master/xml/README.adoc[`xml/README.adoc`] 100 in the `Vulkan-Docs` repository for information on required toolchain 101 components such as Python 3, pass:[g++], and GNU make. 102 103 Once you have the right tools installed, perform the following steps: 104 105 * Check out the `Vulkan-Docs` repository linked above from Khronos 106 Github (there are instructions at the link) 107 * `cd` to the root directory in your checked-out repo 108 * Switch to the `master` branch. 109 * Invoke `make clean ; make install ; make test` 110 111 This should regenerate `vulkan_core.h` and a variety of platform-specific 112 headers, install them in `../include/vulkan/`, and verify that the headers build 113 properly. The result should be identical to the version you just pulled from 114 Github. They can be compared by, for example: 115 116 `git diff ../include/vulkan/` 117 118 The `install` target also generates source code for a simple extension 119 loader library in `../src/ext_loader/`. 120 121 Other Makefile targets in `xml/` include: 122 123 * `validate` - validate `vk.xml` against the XML schema. Recommended 124 if you are making nontrivial changes. 125 * The asciidoc includes used by the Specification and Reference Pages 126 are built using the 'make generated' target in the parent directory Makefile, 127 although they use the scripts and XML in this directory. These files 128 are generated dynamically when building the specs, since their 129 contents depend on the exact set of extensions the Specification is 130 being built to include. 131 132 If you just want to modify the API, changing `vk.xml` and running `make` 133 should be all that is needed. See <<examples>> for some examples of 134 modifying the XML. 135 136 If you want to use the registry for reasons other than generating the 137 header file, extension loader, and asciidoc includes, or to generate 138 headers for languages other than C, start with the Makefile rules and 139 the files `vk.xml`, `genvk.py`, `reg.py`, and `generator.py`. 140 141 If you are using other platforms, issues or merge requests with additional 142 documentation on using the tools on those platforms would be very helpful. 143 144 145 == Header Generation Script - `genvk.py` 146 147 When generating header files using the `genvk.py` script, an API name 148 and profile name are required, as shown in the Makefile examples. 149 Additionally, specific API versions and extensions can be required or 150 excluded. Based on this information, the generator script extracts the 151 relevant interfaces and creates a C-language header file for them. 152 `genvk.py` contains predefined generator options for the current Vulkan 153 Specification release. 154 155 The generator script is intended to be generalizable to other languages by 156 writing new generator classes. Such generators would have to rewrite the C 157 types and definitions in the XML to something appropriate to their language. 158 159 160 == Registry Processing Script - `reg.py` 161 162 XML processing is done in `reg.py`, which contains several objects and 163 methods for loading registries and extracting interfaces and extensions for 164 use in header generation. There is some internal documentation in the form 165 of comments, although nothing more extensive exists yet. 166 167 168 == Output Generator Script - `generator.py` 169 170 Once the registry is loaded, the `COutputGenerator` class defined in 171 `generator.py` is used to create a header file. The 172 `DocOutputGenerator` class is used to create the asciidoc include 173 files. Output generators for other purposes can be added as needed. 174 There are a variety of output generators included: 175 176 * `cgenerator.py` - generate C header file 177 * `docgenerator.py` - generate asciidoc includes for APIs 178 * `hostsyncgenerator.py` - generate host sync table includes for APIs 179 * `validitygenerator.py` - generate validity language includes 180 * `pygenerator.py` - generate a Python dictionary-based encoding of 181 portions of the registry, used during spec generation 182 * `extensionStubSource.py` - generate a simple C extension loader. 183 184 185 [[schema]] 186 = Vulkan Registry Schema 187 188 The format of the Vulkan registry is a top level tag:registry tag 189 containing tag:types, tag:enums, tag:commands, tag:feature, and 190 tag:extension tags describing the different elements of an API, as 191 explained below. 192 This description corresponds to a formal Relax NG schema file, 193 `registry.rnc`, against which the XML registry files can be validated. 194 195 At present the only registry in this schema is the core Vulkan API registry, 196 `vk.xml`. 197 198 199 [[schema:profile]] 200 == Profiles 201 202 Types and enumerants can have different definitions depending on the API 203 profile requested. This capability is not used in the current Vulkan API but 204 may be in the future. Features and extensions can include some elements 205 conditionally depending on the API profile requested. 206 207 208 [[schema:apiname]] 209 == API Names 210 211 The schema supports, but does not currently use an attr:api attribute on 212 several tags. This is an arbitrary string, specified at header generation 213 time, for labelling properties of a specific API or API profile. The string 214 can be, but is not necessarily, an actual API name. Names starting with `vk` 215 are suggested if and when we start defining profiles of Vulkan. 216 217 218 [[schema:root]] 219 = Registry Root (tag:registry tag) 220 221 A tag:registry contains the entire definition of one or more related 222 APIs. 223 224 == Attributes of tag:registry tags 225 226 None. 227 228 == Contents of tag:registry tags 229 230 Zero or more of each of the following tags, normally in this order 231 (although order should not be important): 232 233 * tag:comment - Contains arbitrary text, such as a copyright 234 statement. 235 * <<tag-platforms,tag:platforms>> - defines platform names corresponding 236 to platform-specific <<tag-extension,API extensions>>. 237 * <<tag-tags,tag:tags>> - defines author IDs used for 238 extensions and layers. 239 Author IDs are described in detail in the "`Layers & Extensions`" 240 section of the "`Vulkan Documentation and Extensions: Procedures and 241 Conventions`" document. 242 * <<tag-types,tag:types>> - defines API types. Usually only one 243 tag is used. 244 * <<tag-enums,tag:enums>> - defines API token names and values. 245 Usually multiple tags are used. Related groups may be tagged as an 246 enumerated type corresponding to a tag:type tag, and resulting in a 247 C `enum` declaration. This ability is heavily used in the Vulkan 248 API. 249 * <<tag-commands,tag:commands>> - defines API commands 250 (functions). Usually only one tag is used. 251 * <<tag-feature,tag:feature>> - defines API feature interfaces 252 (API versions, more or less). One tag per feature set. 253 * <<tag-extensions,tag:extensions>> - defines API extension 254 interfaces. Usually only one tag is used, wrapping many extensions. 255 256 257 [[tag-comment]] 258 === Comment Tags (tag:comment tag) 259 260 A tag:comment tag contains an arbitrary string, and is unused. 261 Comment tags may appear in multiple places in the schema, as described 262 below. 263 Comment tags are removed by output generators if they would otherwise appear 264 in generated headers, asciidoc include files, etc. 265 266 267 [[tag-platforms]] 268 = Platform Name Blocks (tag:platforms tag) 269 270 A tag:platforms contains descriptions of platform IDs for platforms 271 supported by window system-specific extensions to Vulkan. 272 273 == Attributes of tag:platforms tags 274 275 * attr:comment - optional. Arbitrary string (unused). 276 277 == Contents of tag:platforms tags 278 279 Zero or more tag:platform tags, in arbitrary order (though they are 280 typically ordered by sorting on the platform name). 281 282 283 [[tag-platform]] 284 = Platform Names (tag:platform tag) 285 286 A tag:platform tag describes a single platform name. 287 288 == Attributes of tag:platform tags 289 290 * attr:name - required. 291 The platform name. 292 This must be a short alphanumeric string corresponding to the platform 293 name, valid as part of a C99 identifier. 294 Lower-case is preferred. 295 In some cases, it may be desirable to distinguish a subset of platform 296 functionality from the entire platform. 297 In these cases, the platform name should begin with the entire platform 298 name, followed by `_` and the subset name. 299 + 300 -- 301 [NOTE] 302 .Note 303 ==== 304 For example, 305 306 `name="xlib"` 307 308 is used for the X Window System, Xlib client library platform. 309 310 `name="xlib_xrandr"` 311 312 is used for the XRandR functionality within the `xlib` platform. 313 ==== 314 -- 315 * attr:protect - required. 316 This must be a C99 preprocessor token beginning with `VK_USE_PLATFORM_` 317 followed by the platform name, converted to upper case, followed by `_` 318 and the extension suffix of the corresponding window system-specific 319 extension supporting the platform. 320 + 321 -- 322 [NOTE] 323 .Note 324 ==== 325 For example, 326 327 `protect="VK_USE_PLATFORM_XLIB_XRANDR_EXT"` 328 329 is used for the `xlib_xrandr` platform name. 330 ==== 331 -- 332 * attr:comment - optional. Arbitrary string (unused). 333 334 == Contents of tag:platform tags 335 336 No contents are allowed. All information is contained in the attributes. 337 338 339 [[tag-tags]] 340 = Author ID Blocks (tag:tags tag) 341 342 A tag:tags tag contains tag:authorid tags describing reserved author IDs 343 used by extension and layer authors. 344 345 == Attributes of tag:tags tags 346 347 * attr:comment - optional. Arbitrary string (unused). 348 349 == Contents of tag:tags tags 350 351 Zero or more tag:tag tags, in arbitrary order (though they are typically 352 ordered by sorting on the author ID). 353 354 355 [[tag-tag]] 356 = Author IDs (tag:tag tag) 357 358 A tag:tag tag contains information defining a single author ID. 359 360 == Attributes of tag:tag tags 361 362 * attr:name - required. The author ID, as registered with Khronos. 363 A short, upper-case string, usually an abbreviation of an author, 364 project or company name. 365 * attr:author - required. 366 The author name, such as a full company or project name. 367 * attr:contact - required. 368 The contact who registered or is currently responsible for extensions 369 and layers using the ID, including sufficient contact information to 370 reach the contact such as individual name together with email address, 371 Github username, or other contact information. 372 373 == Contents of tag:tag tags 374 375 No contents are allowed. All information is contained in the attributes. 376 377 378 [[tag-types]] 379 = API Type Blocks (tag:types tag) 380 381 A tag:types tag contains definitions of derived types used in the API. 382 383 == Attributes of tag:types tags 384 385 * attr:comment - optional. Arbitrary string (unused). 386 387 == Contents of tag:types tags 388 389 Zero or more tag:type and tag:comment tags, in arbitrary order (though they 390 are typically ordered by putting dependencies of other types earlier in the 391 list). 392 The tag:comment tags are used mostly to indicate grouping of related types. 393 394 395 [[tag-type]] 396 = API Type (tag:type tag) 397 398 A tag:type tag contains information which can be used to generate C code 399 corresponding to the type. In many cases, this is simply legal C code, with 400 attributes or embedded tags denoting the type name and other types used in 401 defining this type. In some cases, additional attribute and embedded type 402 information is used to generate more complicated C types. 403 404 == Attributes of tag:type tags 405 406 * attr:requires - optional. Another type name this type requires to 407 complete its definition. 408 * attr:name - optional. Name of this type (if not defined in the tag 409 body). 410 * attr:alias - optional. Another type name which this type is an alias of. 411 Must match the name of another tag:type element. This is typically used 412 when promoting a type defined by an extension to a new core version of 413 the API. The old extension type is still defined, but as an alias of the 414 new type. 415 * attr:api - optional. An API name (see tag:feature below) which 416 specializes this definition of the named type, so that the same API 417 types may have different definitions for e.g. GL ES and GL. This is 418 unlikely to be used in Vulkan, where a single API supports desktop 419 and mobile devices, but the functionality is retained. 420 * attr:category - optional. A string which indicates that this type 421 contains a more complex structured definition. At present the only 422 accepted categories are `basetype`, `bitmask`, `define`, `enum`, 423 `funcpointer`, `group`, `handle`, `include`, `struct`, and `union`, 424 as described below. 425 * attr:comment - optional. Arbitrary string (unused). 426 * attr:parent only applicable if category is `handle`. Notes another 427 type with the `handle` category that acts as a parent object for 428 this type. 429 * attr:returnedonly only applicable if category is `struct` or 430 `union`. Notes that this struct/union is going to be filled in by 431 the API, rather than an application filling it out and passing it to 432 the API. 433 * attr:structextends only applicable if category is `struct` or `union`. 434 This is a comma-separated list of structures whose `pNext` can include 435 this type. 436 This should usually only list the top-level structure that is 437 extended, for all possible chained structures - the chained structures 438 themselves should have their `pNext` tagged with attr:noautovalidity. 439 This will generate a validity statement on the top level structure 440 that validates the entire chain in one go, rather than each chained 441 structure repeating the list of valid structs. 442 443 == Contents of tag:type tags 444 445 The valid contents depend on the attr:category attribute. 446 447 === Enumerated types - attr:category `"enum"` 448 449 If the attr:category tag has the value `enum`, the type is a C 450 enumeration. The body of the tag is ignored in this case. The value of 451 the attr:name attribute must be provided and must match the attr:name 452 attribute of a <<tag-enums,tag:enums>> tag. The enumerant values defined 453 within the tag:enums tag are used to generate a C `enum` type 454 declaration. 455 456 === Structure types - attr:category `"struct"` or `"union"` 457 458 If the attr:category tag has the values `struct` or `union`, the type is a C 459 structure or union, respectively. In this case, the attr:name attribute must 460 be provided, and the contents of the tag:type tag are a series of tag:member 461 tags defining the members of the aggregate type, in order, interleaved with 462 any number of tag:comment tags. 463 464 ==== Structure member (tag:member) tags 465 466 The tag:member tag defines the type and name of a structure or union 467 member. 468 469 ==== Attributes of tag:member tags 470 471 * attr:values - only valid on the `sType` member of a struct. This is a 472 comma-separated list of enumerant values that are valid for the 473 structure type; usually there is only a single value. 474 * attr:len - if the member is an array, len may be one or more of the 475 following things, separated by commas (one for each array 476 indirection): another member of that struct; `"null-terminated"` for 477 a string; `"1"` to indicate it is just a pointer (used for nested 478 pointers); or an equation in math markup for incorporation in the 479 specification (a LaTeX math expression delimited by `latexmath:[` and 480 `]`. 481 The only variables in the equation should be the names of members of the 482 structure. 483 * attr:altlen - if the attr:len attribute is specified, and 484 contains a `latexmath:` equation, this attribute should 485 be specified with an equivalent equation using only C builtin operators, 486 C math library function names, and variables as allowed for attr:len. 487 It must be a valid C99 expression whose result is equal to attr:len for 488 all possible inputs. 489 It is a comma separated list that has size equal to only the `latexmath` 490 item count in attr:len list. 491 This attribute is intended to support consumers of the XML who need to 492 generate validation code from the allowed length. 493 * attr:externsync - denotes that the member should be externally 494 synchronized when accessed by Vulkan 495 * attr:optional - optional. 496 A value of `"true"` or `"false"` determines whether this 497 member can be omitted by providing `NULL` (for pointers), 498 `VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values 499 that are the size of an array in the same structure. If the member 500 is a pointer to one of those types, multiple values may be provided, 501 separated by commas - one for each pointer indirection. 502 If not present, the value is assumed to be `"false"` (the member must 503 not be omitted). 504 * attr:noautovalidity - prevents automatic validity language being 505 generated for the tagged item. Only suppresses item-specific 506 validity - parenting issues etc. are still captured. 507 It must also be used for structures that have no implicit validity when 508 such structure has explicit validity. 509 510 ==== Contents of tag:member tags 511 512 The text elements of a tag:member tag, with all other tags removed, 513 is a legal C declaration of a struct or union member. In addition it may 514 contain several semantic tags: 515 516 * The tag:type tag is optional. It contains text which is a valid type 517 name found in another tag:type tag, and indicates that this type 518 must be previously defined for the definition of the command to 519 succeed. Builtin C types should not be wrapped in tag:type tags. 520 * The tag:name tag is required, and contains the struct/union member 521 name being described. 522 * The tag:enum tag is optional. It contains text which is a valid 523 enumerant name found in another tag:type tag, and indicates that this 524 enumerant must be previously defined for the definition of the command 525 to succeed. Typically this is used to semantically tag static array 526 lengths. 527 * The tag:comment tag is optional. It contains an arbitrary string 528 (unused). 529 530 531 === All other types 532 533 If the attr:category attribute is one of `basetype`, `bitmask`, 534 `define`, `funcpointer`, `group`, `handle` or 535 `include`, or is not specified, tag:type contains text which is legal 536 C code for a type declaration. It may also contain embedded tags: 537 538 * tag:type - nested type tags contain other type names which are 539 required by the definition of this type. 540 * tag:apientry/ - insert a platform calling convention macro here 541 during header generation, used mostly for function pointer types. 542 * tag:name - contains the name of this type (if not defined in the tag 543 attributes). 544 545 There is no restriction on which sorts of definitions may be made in a given 546 category, although the contents of tags with attr:category `enum`, 547 `struct` or `union` are interpreted specially as described above. 548 549 However, when generating the header, types within each category are grouped 550 together, and categories are generated in the order given by the following 551 list. Therefore, types in a category should correspond to the intended 552 purpose given for that category. If this recommendation is not followed, it 553 is possible that the resulting header file will not compile due to 554 out-of-order type dependencies. The intended purpose of each category is: 555 556 * `include` (`#include`) directives) 557 * `define` (macro `#define` directives) 558 * `basetype` (scalar typedefs, such as the definition of `VkFlags`) 559 * `handle` (invocations of macros defining scalar types such as 560 `VkInstance`) 561 * `enum` (enumeration types and `#define` for constant values) 562 * `group` (currently unused) 563 * `bitmask` (enumeration types whose members are bitmasks) 564 * `funcpointer` (function pointer typedefs) 565 * `struct` and `union` together (struct and union types) 566 567 568 [[tag-types:example]] 569 == Example of a tag:types tag 570 571 [source,xml] 572 -------------------------------------- 573 <types> 574 <type name="stddef">#include <stddef.h></type> 575 <type requires="stddef">typedef ptrdiff_t <name>VKlongint</name>;</type> 576 <type name="VkEnum" category="enum"/> 577 <type category="struct" name="VkStruct"> 578 <member><type>VkEnum</type> <name>srcEnum</name></member> 579 <member><type>VkEnum</type> <name>dstEnum</name></member> 580 </type> 581 </types> 582 583 <enums name="VkEnum" type="enum"> 584 <enum value="0" name="VK_ENUM_ZERO"/> 585 <enum value="42" name="VK_ENUM_FORTY_TWO"/> 586 </enums> 587 -------------------------------------- 588 589 The `VkStruct` type is defined to require the types `VkEnum` and 590 `VKlongint` as well. If `VkStruct` is in turn required by a command 591 or another type during header generation, it will result in the following 592 declarations: 593 594 [source,c] 595 -------------------------------------- 596 #include <stddef.h> 597 typedef ptrdiff_t VKlongint. 598 599 typedef enum { 600 VK_ENUM_ZERO = 0, 601 VK_ENUM_FORTY_TWO = 42 602 } VkEnum; 603 604 typedef struct { 605 VkEnum dstEnum; 606 VkLongint dstVal; 607 } VkStruct; 608 -------------------------------------- 609 610 Note that the angle brackets around `stddef.h` are represented as XML 611 entities in the registry. This could also be done using a CDATA block but 612 unless there are many characters requiring special representation in XML, 613 using entities is preferred. 614 615 616 [[tag-enums]] 617 = Enumerant Blocks (tag:enums tag) 618 619 The tag:enums tags contain individual tag:enum tags describing each of 620 the token names used in the API. In some cases these correspond to a C 621 `enum`, and in some cases they are simply compile time constants (e.g. 622 `#define`). 623 624 [NOTE] 625 .Note 626 ==== 627 It would make more sense to call these `const` or `define` tags. 628 This is a historical hangover from the OpenGL XML format which this schema 629 was based on. 630 ==== 631 632 633 == Attributes of tag:enums tags 634 635 * attr:name - optional. String naming the C `enum` type whose members are 636 defined by this enum group. If present, this attribute should match the 637 attr:name attribute of a corresponding tag:type tag. 638 * attr:type - optional. String describing the data type of the values of 639 this group of enums. At present the only accepted categories are `enum` 640 and `bitmask`, as described below. 641 * attr:start, attr:end - optional. Integers defining the start and end of 642 a reserved range of enumerants for a particular vendor or purpose. 643 attr:start must be less than or equal to attr:end. These fields define 644 formal enumerant allocations, and are made by the Khronos Registrar on 645 request from implementers following the enum allocation policy. 646 * attr:vendor - optional. String describing the vendor or purpose to whom 647 a reserved range of enumerants is allocated. 648 * attr:comment - optional. Arbitrary string (unused). 649 650 == Contents of tag:enums tags 651 652 Each tag:enums block contains zero or more tag:enum, tag:unused, and 653 tag:comment tags, in arbitrary order (although they are typically ordered by 654 sorting on enumerant values, to improve human readability). 655 656 == Example of tag:enums tags 657 658 <<tag-types:example,An example>> showing a tag with attribute 659 attr:type`="enum"` is given above. The following example is for 660 non-enumerated tokens. 661 662 [source,xml] 663 -------------------------------------- 664 <enums> 665 <enum value="256" name="VK_MAX_EXTENSION_NAME"/> 666 <enum value="MAX_FLOAT" name="VK_LOD_CLAMP_NONE"/> 667 </enums> 668 -------------------------------------- 669 670 When processed into a C header, and assuming all these tokens were 671 required, this results in 672 673 [source,c] 674 -------------------------------------- 675 #define VK_MAX_EXTENSION_NAME 256 676 #define VK_LOD_CLAMP_NONE MAX_FLOAT 677 -------------------------------------- 678 679 680 [[tag-enum]] 681 = Enumerants (tag:enum tag) 682 683 Each tag:enum tag defines a single Vulkan (or other API) token. 684 685 == Attributes of tag:enum tags 686 687 * attr:value or attr:bitpos - exactly one of these is allowed and 688 required. attr:value is an enumerant value in the form of a legal C 689 constant (usually a literal decimal or hexadecimal integer, though 690 arbitrary strings are allowed). attr:bitpos is a literal integer bit 691 position in a bitmask. 692 * attr:name - required. Enumerant name, a legal C preprocessor token 693 name. 694 * attr:api - optional. An API name which specializes this definition 695 of the named enum, so that different APIs may have different values 696 for the same token. May be used to address a subtle 697 incompatibilities. 698 * attr:type - optional. Used only when attr:value is specified. C 699 suffix for the value to force it to a specific type. Currently only 700 `u` and `ull` are used, for `unsigned` 32- and 64-bit integer 701 values, respectively. Separated from attr:value since this eases 702 parsing and sorting of values, and rarely used. 703 * attr:alias - optional. Name of another enumerant this is an alias 704 of, used where token names have been changed as a result of profile 705 changes or for consistency purposes. An enumerant alias is simply a 706 different attr:name for the exact same attr:value or attr:bitpos. 707 708 == Contents of tag:enum tags 709 710 tag:enum tags have no allowed contents. All information is contained 711 in the attributes. 712 713 714 [[tag-unused]] 715 = Unused Enumerants (tag:unused tag) 716 717 Each tag:unused tag defines a range of enumerants which is allocated, but 718 not yet assigned to specific enums. This just tracks the unused values for 719 the Registrar's use, and is not used for header generation. 720 721 [NOTE] 722 .Note 723 ==== 724 tag:unused tags could be generated and inserted automatically, which would 725 be a good way to avoid the attributes becoming out of date. However, they 726 are rarely used in the Vulkan XML schema, unlike the OpenGL XML schema it 727 was based on. 728 ==== 729 730 == Attributes of tag:unused tags 731 732 * attr:start - required, attr:end - optional. Integers defining the 733 start and end of an unused range of enumerants. attr:start must be 734 {leq} attr:end. If attr:end is not present, then attr:start defines a 735 single unused enumerant. This range should not exceed the range 736 reserved by the surrounding tag:enums tag. 737 * attr:vendor - optional. String describing the vendor or purposes to 738 whom a reserved range of enumerants is allocated. Usually identical 739 to the attr:vendor attribute of the surrounding attr:enums block. 740 * attr:comment - optional. Arbitrary string (unused). 741 742 == Contents of tag:unused tags 743 744 None. 745 746 747 [[tag-commands]] 748 = Command Blocks (tag:commands tag) 749 750 The tag:commands tag contains definitions of each of the functions 751 (commands) used in the API. 752 753 == Attributes of tag:commands tags 754 755 * attr:comment - optional. Arbitrary string (unused). 756 757 == Contents of tag:commands tags 758 759 Each tag:commands block contains zero or more tag:command tags, in 760 arbitrary order (although they are typically ordered by sorting on the 761 command name, to improve human readability). 762 763 764 [[tag-command]] 765 = Commands (tag:command tag) 766 767 The tag:command tag contains a structured definition of a single API 768 command (function). 769 770 == Attributes of tag:command tags 771 772 There are two ways to define a command. The first uses a set of attributes 773 to the tag:command tag defining properties of the command used for 774 constructing automatic validation rules, and the contents of the tag:command 775 tag define the name, signature, and parameters of the command. In this case 776 the allowed attributes include: 777 778 * attr:queues - optional. A string identifying the command queues this 779 command can be placed on. The format of the string is one or more of 780 the terms `"compute"`, `"transfer"`, and `"graphics"`, with multiple 781 terms separated by commas (`","`). 782 * attr:successcodes - optional. A string describing possible 783 successful return codes from the command, as a comma-separated list 784 of Vulkan result code names. 785 * attr:errorcodes - optional. A string describing possible error 786 return codes from the command, as a comma-separated list of Vulkan 787 result code names. 788 * attr:renderpass - optional. A string identifying whether the command 789 can be issued only inside a render pass (`"inside"`), only outside a 790 render pass (`"outside"`), or both (`"both"`). 791 * attr:cmdbufferlevel - optional. A string identifying the command 792 buffer levels that this command can be called by. The format of the 793 string is one or more of the terms `"primary"` and `"secondary"`, 794 with multiple terms separated by commas (`","`). 795 * attr:pipeline - optional. A string identifying the pipeline type 796 that this command uses when executed. The format of the string is one of 797 the terms `"compute"`, `"transfer"`, or `"graphics"`. 798 * attr:comment - optional. Arbitrary string (unused). 799 800 The second way of defining a command is as an alias of another command. For 801 example when an extension is promoted from extension to core status, the 802 commands defined by that extensions become aliases of the corresponding new 803 core commands. In this case, only two attributes are allowed: 804 805 * attr:name - required. A string naming the command defined by the tag. 806 * attr:alias - required. A string naming the command that attr:name is an 807 alias of. The string must be the same as the attr:name value of another 808 tag:command defining another command. 809 810 == Contents of tag:command tags 811 812 * tag:proto is required and must be the first element. It is a tag 813 defining the C function prototype of a command as described below, 814 up to the function name and return type but not including function 815 parameters. 816 * tag:param elements for each command parameter follow, defining its 817 name and type, as described below. If a command takes no arguments, 818 it has no tag:param tags. 819 820 Following these elements, the remaining elements in a tag:command 821 tag are optional and may be in any order: 822 823 * tag:alias - optional. Has no attributes and contains a string which 824 is the name of another command this command is an alias of, used 825 when promoting a function from vendor to Khronos extension or 826 Khronos extension to core API status. A command alias describes the case 827 where there are two function names which implement the same behavior. 828 * tag:description - optional. Unused text. 829 * tag:implicitexternsyncparams - optional. Contains a list of tag:param 830 tags, each containing asciidoc source text describing an object which is 831 not a parameter of the command but is related to one, and which also 832 <<tag-command:param:attr,requires external synchronization>>. The text 833 is intended to be incorporated into the API specification. 834 835 [NOTE] 836 .Note 837 ==== 838 Versions of the registry documentation prior to 1.1.93 asserted that 839 command aliases "`resolve to the _same_ entry point in the underlying layer 840 stack.`" 841 Whilst this may be true on many implementations, it is not required - each 842 command alias must be queried separately through flink:vkGetInstanceProcAddr 843 or flink:vkGetDeviceProcAddr. 844 ==== 845 846 847 [[tag-command:proto]] 848 == Command prototype (tag:proto tags) 849 850 The tag:proto tag defines the return type and name of a command. 851 852 === Attributes of tag:proto tags 853 854 None. 855 856 // attr:group - group name, an arbitrary string. 857 // 858 // If the group name is defined, it may be interpreted as described in 859 // <<tag-group:meaning>>. 860 861 === Contents of tag:proto tags 862 863 The text elements of a tag:proto tag, with all other tags removed, is 864 legal C code describing the return type and name of a command. In addition 865 to text, it may contain two semantic tags: 866 867 * The tag:type tag is optional, and contains text which is a valid 868 type name found in a tag:type tag. It indicates that this type must 869 be previously defined for the definition of the command to succeed. 870 Builtin C types, and any derived types which are expected to be 871 found in other header files, should not be wrapped in tag:type tags. 872 * The tag:name tag is required, and contains the command name being 873 described. 874 875 876 [[tag-command:param]] 877 == Command parameter (tag:param tags) 878 879 The tag:param tag defines the type and name of a parameter. Its contents 880 are very similar to the tag:member tag used to define struct and union 881 members. 882 883 884 [[tag-command:param:attr]] 885 === Attributes of tag:param tags 886 887 * attr:len - if the param is an array, len may be one or more of the 888 following things, separated by commas (one for each array 889 indirection): another param of that command; `"null-terminated"` for 890 a string; `"1"` to indicate it is just a pointer (used for nested 891 pointers); or an equation in math markup for incorporation in the 892 specification (a LaTeX math expression delimited by `latexmath:[` and 893 `]`. 894 The only variables in the equation should be the names of this or other 895 parameters. 896 * attr:altlen - if the attr:len attribute is specified, and 897 contains a `latexmath:` equation, this attribute should 898 be specified with an equivalent equation using only C builtin operators, 899 C math library function names, and variables as allowed for attr:len. 900 It must be a valid C99 expression whose result is equal to attr:len for 901 all possible inputs. 902 It is a comma separated list that has size equal to only the `latexmath` 903 item count in attr:len list. 904 This attribute is intended to support consumers of the XML who need to 905 generate validation code from the allowed length. 906 * attr:optional - optional. A value of `"true"` or `"false"` determines whether this 907 parameter can be omitted by providing `NULL` (for pointers), 908 `VK_NULL_HANDLE` (for handles), 0 (for bitmasks), or 0 for values 909 that are the size of an array in the same command. If the parameter is 910 a pointer to one of those types, multiple values may be provided, 911 separated by commas - one for each pointer indirection. If not present, 912 the value is assumed to be `"false"` (the parameter must not be 913 omitted). 914 * attr:noautovalidity - prevents automatic validity language being 915 generated for the tagged item. Only suppresses item-specific 916 validity - parenting issues etc. are still captured. 917 * attr:externsync - optional. A value of `"true"` indicates that this 918 parameter (e.g. the object a handle refers to, or the contents of an 919 array a pointer refers to) is modified by the command, and is not 920 protected against modification in multiple app threads. If only certain 921 members of an object or elements of an array are modified, multiple 922 strings may be provided, separated by commas. Each string describes a 923 member which is modified. For example, the `vkQueueSubmit` command 924 includes attr:externsync attributes for the `pSubmits` array indicating 925 that only specific members of each element of the array are modified: 926 + 927 -- 928 [source,xml] 929 -------------------------------------- 930 <param len="submitCount" externsync="pSubmits[].pWaitSemaphores[],pSubmits[].pSignalSemaphores[]">const <type>VkSubmitInfo</type>* <name>pSubmits</name></param> 931 -------------------------------------- 932 933 Parameters which do not have an attr:externsync attribute are assumed to not 934 require external synchronization. 935 -- 936 937 === Contents of tag:param tags 938 939 The text elements of a tag:param tag, with all other tags removed, is 940 legal C code describing the type and name of a function parameter. In 941 addition it may contain two semantic tags: 942 943 * The tag:type tag is optional, and contains text which is a valid 944 type name found in tag:type tag, and indicates that this type must 945 be previously defined for the definition of the command to succeed. 946 Builtin C types, and any derived types which are expected to be 947 found in other header files, should not be wrapped in tag:type tags. 948 * The tag:name tag is required, and contains the parameter name being 949 described. 950 951 == Example of a tag:commands tag 952 953 [source,xml] 954 -------------------------------------- 955 <commands> 956 <command> 957 <proto><type>VkResult</type> <name>vkCreateInstance</name></proto> 958 <param>const <type>VkInstanceCreateInfo</type>* <name>pCreateInfo</name></param> 959 <param><type>VkInstance</type>* <name>pInstance</name></param> 960 </command> 961 </commands> 962 -------------------------------------- 963 964 When processed into a C header, this results in 965 966 [source,c] 967 -------------------------------------- 968 VkResult vkCreateInstance( 969 const VkInstanceCreateInfo* pCreateInfo, 970 VkInstance* pInstance); 971 -------------------------------------- 972 973 974 [[tag-feature]] 975 = API Features and Versions (tag:feature tag) 976 977 API features are described in individual tag:feature tags. A feature is 978 the set of interfaces (enumerants and commands) defined by a particular API 979 and version, such as Vulkan 1.0, and includes all profiles of that API and 980 version. 981 982 == Attributes of tag:feature tags 983 984 * attr:api - required. <<schema:apiname,API name>> this feature is for, 985 such as `vk`. 986 * attr:name - required. Version name, used as the C preprocessor token 987 under which the version's interfaces are protected against multiple 988 inclusion. Example: `"VK_VERSION_1_0"`. 989 * attr:number - required. Feature version number, usually a string 990 interpreted as `majorNumber.minorNumber`. Example: `4.2`. 991 * attr:protect - optional. An additional preprocessor token used to 992 protect a feature definition. Usually another feature or extension 993 attr:name. Rarely used, for odd circumstances where the definition 994 of a feature or extension requires another to be defined first. 995 * attr:comment - optional. Arbitrary string (unused). 996 997 [NOTE] 998 .Note 999 ==== 1000 The attr:name attribute used for Vulkan core versions, such as 1001 `"VK_VERSION_1_0"`, is not an API construct. 1002 It is used only as a preprocessor guard in the headers, and an asciidoctor 1003 conditional in the specification sources. 1004 The similar `"VK_API_VERSION_1_0"` symbols are part of the API and their 1005 values are packed integers containing Vulkan core version numbers. 1006 ==== 1007 1008 == Contents of tag:feature tags 1009 1010 Zero or more <<tag-required,tag:require and tag:remove tags>>, in arbitrary 1011 order. Each tag describes a set of interfaces that is respectively required 1012 for, or removed from, this feature, as described below. 1013 1014 == Example of a tag:feature tag 1015 1016 [source,xml] 1017 -------------------------------------- 1018 <feature api="vulkan" name="VK_VERSION_1_0" number="1.0"> 1019 <require comment="Header boilerplate"> 1020 <type name="vk_platform"/> 1021 </require> 1022 <require comment="API constants"> 1023 <enum name="VK_MAX_PHYSICAL_DEVICE_NAME"/> 1024 <enum name="VK_LOD_CLAMP_NONE"/> 1025 </require> 1026 <require comment="Device initialization"> 1027 <command name="vkCreateInstance"/> 1028 </require> 1029 </feature> 1030 -------------------------------------- 1031 1032 When processed into a C header for Vulkan, this results in: 1033 1034 [source,c] 1035 -------------------------------------- 1036 #ifndef VK_VERSION_1_0 1037 #define VK_VERSION_1_0 1 1038 #define VK_MAX_EXTENSION_NAME 256 1039 #define VK_LOD_CLAMP_NONE MAX_FLOAT 1040 typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)(const VkInstanceCreateInfo* pCreateInfo, VkInstance* pInstance); 1041 #ifndef VK_NO_PROTOTYPES 1042 VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance( 1043 const VkInstanceCreateInfo* pCreateInfo, 1044 VkInstance* pInstance); 1045 #endif 1046 #endif /* VK_VERSION_1_0 */ 1047 -------------------------------------- 1048 1049 1050 [[tag-extensions]] 1051 = Extension Blocks (tag:extensions tag) 1052 1053 The tag:extensions tag contains definitions of each of the extenions 1054 which are defined for the API. 1055 1056 == Attributes of tag:extensions tags 1057 1058 * attr:comment - optional. Arbitrary string (unused). 1059 1060 == Contents of tag:extensions tags 1061 1062 Each tag:extensions block contains zero or more tag:extension tags, 1063 each describing an API extension, in arbitrary order (although they are 1064 typically ordered by sorting on the extension name, to improve human 1065 readability). 1066 1067 1068 [[tag-extension]] 1069 = API Extensions (tag:extension tag) 1070 1071 API extensions are described in individual tag:extension tags. An 1072 extension is the set of interfaces defined by a particular API extension 1073 specification, such as `ARB_multitexture`. tag:extension is 1074 similar to tag:feature, but instead of having attr:version and 1075 attr:profile attributes, instead has a attr:supported attribute, 1076 which describes the set of API names which the extension can potentially 1077 be implemented against. 1078 1079 == Attributes of tag:extension tags 1080 1081 * attr:name - required. Extension name, following the conventions in 1082 the Vulkan Specification. Example: `name="VK_VERSION_1_0"`. 1083 * attr:number - required. A decimal number which is the registered, 1084 unique extension number for attr:name. 1085 * attr:author - optional. The author name, such as a full company 1086 name. If not present, this can be taken from the corresponding 1087 tag:tag attribute. However, `EXT` and other multi-vendor extensions 1088 may not have a well-defined author or contact in the tag. This attribute 1089 is not used in processing the XML. It is just metadata, mostly used to 1090 track the original author of an extension (which may have since been 1091 promoted to use a different author ID). 1092 * attr:contact - optional. The contact who registered or is currently 1093 responsible for extensions and layers using the tag, including 1094 sufficient contact information to reach the contact such as individual 1095 name together with Github username (`@username`), Khronos internal 1096 Gitlab username (`gitlab:@username`) if no public Github contact is 1097 available, or other contact information. If not present, this can be 1098 taken from the corresponding tag:tag attribute just like attr:author. 1099 * attr:type - required if the attr:supported attribute is not 1100 `'disabled'`. Must be either `'device'` or `'instance'`, if present. 1101 * attr:requires - optional. Comma-separated list of extension names this 1102 extension requires to be supported. 1103 * attr:requiresCore - optional. Core version of Vulkan required by the 1104 extension, e.g. "1.1". Defaults to "1.0". 1105 * attr:protect - optional. An additional preprocessor token used to 1106 protect an extension definition. Usually another feature or 1107 extension attr:name. Rarely used, for odd circumstances where the 1108 definition of an extension requires another extension or a header 1109 file to be defined first. 1110 * attr:platform - optional. Indicates that the extension is specific to 1111 the platform identified by the attribute value, and should be emitted 1112 conditional on that platform being available, in a platform-specific 1113 header, etc. The attribute value must be the same as one of the 1114 tag:platform tag:name attribute values. 1115 * attr:supported - required. A regular expression with an implicit `^` and 1116 `$` bracketing it, which should match the attr:api tag of a set of 1117 tag:feature tags. When the extension tag is just reserving an extension 1118 number, and no interfaces are yet defined, use `supported="disabled"` to 1119 indicate this extension should never be processed. 1120 * attr:promotedto - optional. A Vulkan version or a name of an extension 1121 that this extension was _promoted_ to. E.g. `"VK_VERSION_1_1"`, or 1122 `"VK_KHR_draw_indirect_count"`. 1123 * attr:deprecatedby - optional. A Vulkan version or a name of an extension 1124 that _deprecates_ this extension. It may be an empty string. E.g. 1125 `"VK_VERSION_1_1"`, or `"VK_EXT_debug_utils"`, or `""`. 1126 * attr:obsoletedby - optional. A Vulkan version or a name of an extension 1127 that _obsoletes_ this extension. It may be an empty string. E.g. 1128 `"VK_VERSION_1_1"`, or `"VK_KHR_maintenance1"`, or `""`. 1129 * attr:provisional - optional. 'true' if this extension is released 1130 provisionally. 1131 * attr:comment - optional. Arbitrary string (unused). 1132 1133 1134 [NOTE] 1135 .Note 1136 ==== 1137 The attr:requires attribute is used to specify other extensions that *must* 1138 be enabled for an extension to be enabled. 1139 1140 In some cases, an extension may include functionality which is only defined 1141 *if* another extension is enabled. Such functionality should be specified 1142 within a tag:require, using the attr:extension attribute to specify that 1143 extension. 1144 ==== 1145 1146 == Contents of tag:extension tags 1147 1148 Zero or more <<tag-required,tag:require and tag:remove tags>>, in arbitrary 1149 order. Each tag describes a set of interfaces that is respectively required 1150 for, or removed from, this extension, as described below. 1151 1152 == Example of an tag:extensions tag 1153 1154 [source,xml] 1155 -------------------------------------- 1156 <extension name="VK_KHR_display_swapchain" number="4" supported="vulkan"> 1157 <require> 1158 <enum value="9" name="VK_KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION"/> 1159 <enum value="4" name="VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NUMBER"/> 1160 <enum value=""VK_KHR_display_swapchain"" 1161 name="VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME"/> 1162 <type name="VkDisplayPresentInfoKHR"/> 1163 <command name="vkCreateSharedSwapchainsKHR"/> 1164 </require> 1165 </extension> 1166 -------------------------------------- 1167 1168 The attr:supported attribute says that the extension is defined for the 1169 default profile (`vulkan`). When processed into a C header for the 1170 `vulkan` profile, this results in header contents something like 1171 (assuming corresponding definitions of the specified tag:type and 1172 tag:command elsewhere in the XML): 1173 1174 [source,c] 1175 -------------------------------------- 1176 #define VK_KHR_display_swapchain 1 1177 #define VK_KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION 9 1178 #define VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NUMBER 4 1179 #define VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME "VK_KHR_display_swapchain" 1180 1181 typedef struct VkDisplayPresentInfoKHR { 1182 VkStructureType sType; 1183 const void* pNext; 1184 VkRect2D srcRect; 1185 VkRect2D dstRect; 1186 VkBool32 persistent; 1187 } VkDisplayPresentInfoKHR; 1188 1189 typedef VkResult (VKAPI_PTR *PFN_vkCreateSharedSwapchainsKHR)( 1190 VkDevice device, uint32_t swapchainCount, 1191 const VkSwapchainCreateInfoKHR* pCreateInfos, 1192 const VkAllocationCallbacks* pAllocator, 1193 VkSwapchainKHR* pSwapchains); 1194 1195 #ifndef VK_NO_PROTOTYPES 1196 VKAPI_ATTR VkResult VKAPI_CALL vkCreateSharedSwapchainsKHR( 1197 VkDevice device, 1198 uint32_t swapchainCount, 1199 const VkSwapchainCreateInfoKHR* pCreateInfos, 1200 const VkAllocationCallbacks* pAllocator, 1201 VkSwapchainKHR* pSwapchains); 1202 #endif 1203 -------------------------------------- 1204 1205 1206 [[tag-required]] 1207 = Required and Removed Interfaces (tag:require and tag:remove tags) 1208 1209 A tag:require block defines a set of interfaces (types, enumerants and 1210 commands) 'required' by a tag:feature 1211 or tag:extension. A tag:remove block defines a set of interfaces 1212 'removed' by a tag:feature. This is primarily for 1213 future profiles of an API which may choose to deprecate and/or remove 1214 some interfaces. 1215 Extensions should never remove interfaces, although this 1216 usage is allowed by the schema). Except for the tag name and behavior, 1217 the contents of tag:require and tag:remove tags are identical. 1218 1219 == Attributes of tag:require and tag:remove tags 1220 1221 * attr:profile - optional. String name of an API profile. Interfaces 1222 in the tag are only required (or removed) if the specified profile 1223 is being generated. If not specified, interfaces are required (or 1224 removed) for all API profiles. 1225 * attr:comment - optional. Arbitrary string (unused). 1226 * attr:api - optional. An <<schema:apiname,API name>>. 1227 Interfaces in the tag are only required (or removed) if the 1228 specified API is being generated. If not specified, interfaces are 1229 required (or removed) for all APIs. 1230 1231 1232 [NOTE] 1233 .Note 1234 ==== 1235 The attr:api attribute is only supported inside tag:extension tags, 1236 since tag:feature tags already define a specific API. 1237 ==== 1238 1239 == Attributes of tag:require tags 1240 1241 These attribues are allowed only for a tag:require tag. 1242 1243 * attr:extension - optional, and only for tag:require tags. String 1244 containing an API extension name. Interfaces in the tag are only 1245 required if the string matches the attr:name of an tag:extension tag, 1246 and that extension is enabled. 1247 * attr:feature - optional, and only for tag:require tags. String 1248 containing an API feature name. Interfaces in the tag are only required 1249 if the string matches the attr:name of a tag:feature tag, and that 1250 feature is enabled. 1251 1252 [NOTE] 1253 .Note 1254 ==== 1255 The attr:extension attribute currently does not affect output generators in 1256 any way, and is simply metadata. This will be addressed as we better define 1257 different types of dependencies between extensions. 1258 ==== 1259 1260 == Contents of tag:require and tag:remove tags 1261 1262 Zero or more of the following tags, in any order: 1263 1264 === Comment Tags 1265 1266 <<tag-comment, tag:comment>> (as described above). 1267 1268 === Command Tags 1269 1270 tag:command specifies an required (or removed) command defined 1271 in a tag:commands block. The tag has no content, but contains 1272 attributes: 1273 1274 * attr:name - required. Name of the command. 1275 * attr:comment - optional. Arbitrary string (unused). 1276 1277 === Enum tags 1278 1279 tag:enum specifies an required (or removed) enumerant defined in a 1280 tag:enums block. All forms of this tag support the following attributes: 1281 1282 * attr:name - required. Name of the enumerant. 1283 * attr:comment - optional. Arbitrary string (unused). 1284 * attr:api - optional. An API name which specializes this definition of 1285 the enumerant attr:name, so that different APIs may have different 1286 values for the same token. May be used to address subtle 1287 incompatibilities. 1288 1289 There are two forms of tag:enum tags: 1290 1291 _Reference enums_ simply pull in the definition of an enumerant given in 1292 a separate tag:enums block. Reference enums are the most common usage, 1293 and no attributes other than attr:name and attr:comment are supported 1294 for them. 1295 1296 _Extension enums_ define the value of an enumerant inline in an tag:feature 1297 or tag:extensions block. Typically these are used to add additional values 1298 specified by an extension or core feature to an existing enumerated type. 1299 There are a variety of attributes which are used to specify the value of the 1300 enumerant, although not all combinations of attributes are either meaningful 1301 or supported. Possible attributes are described first, followed by the 1302 allowed combinations: 1303 1304 * attr:value and attr:type - define a constant value in the same fashion 1305 as an tag:enum tag in an <<tag-enum,tag:enums>> block. 1306 * attr:bitpos - define a constant bitmask value in the same fashion as an 1307 <<tag-enum,tag:enum>> tag in an tag:enums block. 1308 * attr:extends - the name of a separately defined enumerated type (e.g. a 1309 tag:type tag with attr:category``="enum"``) to which the extension 1310 enumerant is added. If not present, the enumerant is treated as a global 1311 constant value. 1312 * attr:extnumber - an extension number. The extension number in turn 1313 specifies the starting value of a block (range) of values reserved for 1314 enumerants defined by or associated with the corresponding tag:extension 1315 tag with the same attr:number. This is used when an extension or core 1316 feature needs to extend an enumerated type in a block defined by a 1317 different extension. 1318 * Attribute attr:offset - the offset within an extension block. If 1319 attr:extnumber is not present, the extension number defining that block 1320 is given by the attr:number attribute of the surrounding tag:extension 1321 tag. The actual numeric value of the enumerant is computed as defined in 1322 the "`Layers and Extensions`" appendix of the Vulkan Specification. 1323 * Attribute attr:dir - if present, the calculated enumerant value will be 1324 negative, instead of positive. Negative enumerant values are normally 1325 used only for Vulkan error codes. The attribute value must be specified 1326 as `dir="-"`. 1327 * attr:alias - the name of another enumerant this is an alias of. An 1328 enumerant alias is simply a different name for the same enumerant value. 1329 This is typically used when promoting an enumerant defined by an 1330 extension to a new core version of the API. The old extension enumerant 1331 is still defined, but as an alias of the new core enumerant. It may also 1332 be used when token names have been changed as a result of profile 1333 changes, or for consistency purposes. 1334 * attr:api - an API name which specializes this definition of the named 1335 enum, so that different APIs may have different values for the same 1336 token. May be used to address subtle incompatibilities. 1337 1338 1339 .Valid Combinations of attr:enum Attributes 1340 |==== 1341 | attr:value | attr:bitpos | attr:alias | attr:offset | attr:extnumber | attr:dir | attr:extends | Description 1342 | {yes} | {no} | {no} | {no} | {no} | {no} | {opt}^2^ | Numeric value 1343 | {no} | {yes} | {no} | {no} | {no} | {no} | {opt}^2^ | Bitmask value 1344 | {no} | {no} | {yes} | {no} | {no} | {no} | {opt}^2^ | Alias of another enumerant 1345 | {no} | {no} | {no} | {yes} | {opt}^1^ | {opt} | {yes} | Value added to an enumeration 1346 | {no} | {no} | {no} | {yes} | {opt}^1^ | {opt} | {yes} | Value added to an enumeration 1347 |==== 1348 1349 [1]: If attr:extnumber is not present, the tag:enum tag may only be within a 1350 tag:extension. Otherwise, the tag:enum tag may also be within a tag:feature. 1351 1352 [2]: If attr:extends is not present, the enumerant value is a global 1353 constant. Otherwise, the value is added to the specified enumeration. 1354 1355 Examples of <<tag-required-examples,various types of extension enumerants>> 1356 are given below. 1357 1358 1359 === Type tags 1360 1361 tag:type specifies a required (or removed) type defined in a 1362 tag:types block. Most types are picked up implicitly by using the 1363 tag:type tags of commands, but in a few cases, additional types need 1364 to be specified explicitly. It is unlikely that a type would ever be 1365 removed, although this usage is allowed by the schema. The tag has no 1366 content, but contains elements: 1367 1368 * attr:name - required. Name of the type. 1369 * attr:comment - optional. Arbitrary string (unused). 1370 1371 1372 [[tag-required-examples]] 1373 == Examples of Extension Enumerants 1374 1375 Examples of some of the supported extension enumerant tag:enum tags are 1376 given below. 1377 1378 [source,xml] 1379 -------------------------------------- 1380 <extensions> 1381 <extension name="VK_KHR_test_extension" number="1" supported="vulkan"> 1382 <require> 1383 <enum value="42" name="VK_KHR_theanswer"/> 1384 <enum bitpos="29" name="VK_KHR_bitmask"/> 1385 <enum offset="0" dir="-" extends="VkResult" 1386 name="VK_ERROR_SURFACE_LOST_KHR"/> 1387 <enum offset="1" extends="VkResult" 1388 name="VK_SUBOPTIMAL_KHR"/> 1389 <enum bitpos="31" extends="VkResult" 1390 name="VK_KHR_EXTENSION_BIT"/> 1391 </require> 1392 </extension> 1393 </extensions> 1394 -------------------------------------- 1395 1396 The corresponding header file will include definitions like this: 1397 1398 [source,c] 1399 -------------------------------------- 1400 typedef enum VkResult { 1401 <previously defined VkResult enumerant values}, 1402 VK_ERROR_SURFACE_LOST_KHR = -1000000000, 1403 VK_SUBOPTIMAL_KHR = 1000000001, 1404 VK_KHR_EXTENSION_BIT = 0x80000000, 1405 }; 1406 1407 #define VK_KHR_test_extension 1 1408 #define VK_KHR_theanswer 42 1409 #define VK_KHR_bitmask 0x20000000 1410 -------------------------------------- 1411 1412 1413 [[examples]] 1414 = Examples / FAQ / How Do I? 1415 1416 For people new to the Registry, it will not be immediately obvious how 1417 to make changes. This section includes some tips and examples that will 1418 help you make changes to the Vulkan headers by changing the Registry XML 1419 description. 1420 1421 First, follow the steps described to <<starting,get the Vulkan Github 1422 repository>> containing the registry and assemble the tools necessary to 1423 work with the XML registry. Once you are able to regenerate the Vulkan 1424 headers from `vk.xml`, you can start making changes. 1425 1426 1427 == General Strategy 1428 1429 If you are _adding_ to the API, perform the following steps to _create_ 1430 the description of that API element: 1431 1432 * For each type, enum group, compile time constant, and command being 1433 added, create appropriate new tag:type, tag:enums, tag:enum, or 1434 tag:command tags defining the interface in question. 1435 * Make sure that all added types and commands appropriately tag their 1436 dependencies on other types by adding nested tag:type tags. 1437 * Make sure that each new tag defines the name of the corresponding 1438 type, enum group, constant, or command, and that structure/union 1439 types and commands tag the types and names of all their members and 1440 parameters. This is essential for the automatic dependency process 1441 to work. 1442 1443 If you are _modifying_ existing APIs, just make appropriate changes 1444 in the existing tags. 1445 1446 Once the definition is added, proceed to the next section to create 1447 dependencies on the changed feature. 1448 1449 1450 == API Feature Dependencies 1451 1452 When you add new API elements, they will not result in corresponding changes 1453 in the generated header unless they are _required_ by the interface 1454 being generated. This makes it possible to include different API versions 1455 and extensions in a single registry and pull them out as needed. So you must 1456 introduce a dependency on new features in the corresponding tag:feature 1457 tag. 1458 1459 Initially, the only API feature is Vulkan 1.0, so there is only one 1460 tag:feature tag in `vk.xml`. You can find it by searching 1461 for the following block of `vk.xml`: 1462 1463 [source,xml] 1464 -------------------------------------- 1465 <comment> 1466 <feature api="vulkan" name="VK_VERSION_1_0" number="1.0" 1467 comment="Vulkan core API interface definitions"> 1468 -------------------------------------- 1469 1470 Inside the tag:feature tag are nested multiple tag:require tags. These 1471 are just being used as a logical grouping mechanism for related parts of 1472 Vulkan 1.0 at present, though they may have more meaningful roles in the 1473 future if different API profiles are defined. 1474 1475 1476 === API Feature Walkthrough 1477 1478 This section walks through the first few required API features in the 1479 `vk.xml` tag:feature tag, showing how each requirement pulls in type, token, 1480 and command definitions and turns those into definitions in the C header 1481 file `vulkan_core.h`. 1482 1483 Consider the first few lines of the tag:feature: 1484 1485 [source,xml] 1486 -------------------------------------- 1487 <require comment="Header boilerplate"> 1488 <type name="vk_platform"/> 1489 </require> 1490 <require comment="API constants"> 1491 <enum name="VK_MAX_PHYSICAL_DEVICE_NAME"/> 1492 <enum name="VK_MAX_EXTENSION_NAME"/> 1493 ... 1494 </require> 1495 <require comment="Device initialization"> 1496 <command name="vkCreateInstance"/> 1497 ... 1498 -------------------------------------- 1499 1500 The first tag:require block says to require a type named `vk_platform`. 1501 If you look at the beginning of the tag:types section, there is a 1502 corresponding definition section: 1503 1504 [source,xml] 1505 -------------------------------------- 1506 <type name="vk_platform">#include "vk_platform.h" 1507 #define VK_MAKE_VERSION(major, minor, patch) \ 1508 ((major << 22) | (minor << 12) | patch) 1509 ... 1510 -------------------------------------- 1511 1512 This section is invoked by the requirement and emits a bunch of 1513 boilerplate C code. The explicit dependency is not strictly required 1514 since `vk_platform` will be required by many other types, but placing it 1515 first causes this to appear first in the output file. 1516 1517 Note that `vk_platform` does not correspond to an actual C type, but instead 1518 to a collection of freeform preprocessor includes and macros and comments. 1519 Most other tag:type tags do define a specific type and are much simpler, but 1520 this approach can be used to inject arbitrary C into the Vulkan headers 1521 *when there is no other way*. In general inserting arbitrary C is strongly 1522 discouraged outside of specific special cases like this. 1523 1524 The next tag:require block pulls in some compile time constants. These 1525 correspond to the definitions found in the first tag:enums section of 1526 `vk.xml`: 1527 1528 [source,xml] 1529 -------------------------------------- 1530 <enums name="API Constants" 1531 comment="Vulkan hardcoded constants - not an enumerated type, part of the header boilerplate"> 1532 <enum value="256" name="VK_MAX_PHYSICAL_DEVICE_NAME"/> 1533 <enum value="256" name="VK_MAX_EXTENSION_NAME"/> 1534 ... 1535 -------------------------------------- 1536 1537 The third tag:require block starts pulling in some Vulkan commands. The 1538 first command corresponds to the following definition found in the 1539 tag:commands section of `vk.xml`: 1540 1541 [source,xml] 1542 -------------------------------------- 1543 <commands> 1544 <command> 1545 <proto><type>VkResult</type> <name>vkCreateInstance</name></proto> 1546 <param>const <type>VkInstanceCreateInfo</type>* <name>pCreateInfo</name></param> 1547 <param><type>VkInstance</type>* <name>pInstance</name></param> 1548 </command> 1549 ... 1550 -------------------------------------- 1551 1552 In turn, the tag:command tag requires the tag:types `VkResult`, 1553 `VkInstanceCreateInfo`, and `VkInstance` as part of its 1554 definition. The definitions of these types are determined as follows: 1555 1556 For `VkResult`, the corresponding required tag:type is: 1557 1558 [source,xml] 1559 -------------------------------------- 1560 <type name="VkResult" category="enum"/> 1561 -------------------------------------- 1562 1563 Since this is an enumeration type, it simply links to an tag:enums tag 1564 with the same name: 1565 1566 [source,xml] 1567 -------------------------------------- 1568 <enums name="VkResult" type="enum" comment="API result codes"> 1569 <comment>Return codes (positive values)</comment> 1570 <enum value="0" name="VK_SUCCESS"/> 1571 <enum value="1" name="VK_UNSUPPORTED"/> 1572 <enum value="2" name="VK_NOT_READY"/> 1573 ... 1574 <comment>Error codes (negative values)</comment> 1575 <enum value="-1" name="VK_ERROR_OUT_OF_HOST_MEMORY" comment="A host memory allocation has failed"/> 1576 ... 1577 -------------------------------------- 1578 1579 For `VkInstanceCreateInfo`, the required tag:type is: 1580 1581 [source,xml] 1582 -------------------------------------- 1583 <type category="struct" name="VkInstanceCreateInfo"> 1584 <member values="VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO"><type>VkStructureType</type> <name>sType</name></member> 1585 <member>const void* <name>pNext</name></member> 1586 <member>const <type>VkApplicationInfo</type>* <name>pAppInfo</name></member> 1587 <member>const <type>VkAllocCallbacks</type>* <name>pAllocCb</name></member> 1588 <member><type>uint32_t</type> <name>extensionCount</name></member> 1589 <member>const <type>char</type>*const* <name>ppEnabledExtensionNames</name></member> 1590 </type> 1591 -------------------------------------- 1592 1593 This is a structure type, defining a C `struct` with all the members 1594 defined in each tag:member tag in order. In addition, it requires some 1595 other types, whose definitions are located by name in exactly the same 1596 fashion. 1597 1598 For the final direct dependency of the command, `VkInstance`, the 1599 required tag:type is: 1600 1601 [source,xml] 1602 -------------------------------------- 1603 <comment>Types which can be void pointers or class pointers, selected at compile time</comment> 1604 <type>VK_DEFINE_BASE_HANDLE(<name>VkObject</name>)</type> 1605 <type>VK_DEFINE_DISP_SUBCLASS_HANDLE(<name>VkInstance</name>, <type>VkObject</type>)</type> 1606 -------------------------------------- 1607 1608 In this case, the type `VkInstance` is defined by a special compile time 1609 macro which defines it as a derived class of `VkObject` (for `C```) or a 1610 less typesafe definition (for C). This macro is not part of the type 1611 dependency analysis, just the boilerplate used in the header. 1612 1613 If these are the only tag:feature dependencies in `vk.xml`, the 1614 resulting `vulkan_core.h` header will look like this: 1615 1616 [source,c] 1617 -------------------------------------- 1618 #ifndef VULKAN_H_ 1619 #define VULKAN_H_ 1 1620 1621 #ifdef __cplusplus 1622 extern "C" { 1623 #endif 1624 1625 /* 1626 ** Copyright (c) 2015-2019 The Khronos Group Inc. 1627 ... 1628 */ 1629 1630 /* 1631 ** This header is generated from the Khronos Vulkan XML API Registry. 1632 ** 1633 ** Generated on date 20170208 1634 */ 1635 1636 1637 #define VK_VERSION_1_0 1 1638 #include "vk_platform.h" 1639 #define VK_MAKE_VERSION(major, minor, patch) \ 1640 ((major << 22) | (minor << 12) | patch) 1641 1642 // Vulkan API version supported by this file 1643 #define VK_API_VERSION VK_MAKE_VERSION(0, 104, 0) 1644 1645 #if defined (__cplusplus) && (VK_UINTPTRLEAST64_MAX == UINTPTR_MAX) 1646 #define VK_TYPE_SAFE_COMPATIBLE_HANDLES 1 1647 #endif 1648 1649 #if defined(VK_TYPE_SAFE_COMPATIBLE_HANDLES) && !defined(VK_DISABLE_TYPE_SAFE_HANDLES) 1650 #define VK_DEFINE_PTR_HANDLE(_obj) struct _obj##_T { char _dummy; }; typedef _obj##_T* _obj; 1651 #define VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base) struct _obj##_T : public _base##_T {}; typedef _obj##_T* _obj; 1652 1653 #define VK_DEFINE_BASE_HANDLE(_obj) VK_DEFINE_PTR_HANDLE(_obj) 1654 #define VK_DEFINE_DISP_SUBCLASS_HANDLE(_obj, _base) VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base) 1655 #define VK_DEFINE_NONDISP_SUBCLASS_HANDLE(_obj, _base) VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base) 1656 #else 1657 #define VK_DEFINE_BASE_HANDLE(_obj) typedef VkUintPtrLeast64 _obj; 1658 #define VK_DEFINE_DISP_SUBCLASS_HANDLE(_obj, _base) typedef uintptr_t _obj; 1659 #define VK_DEFINE_NONDISP_SUBCLASS_HANDLE(_obj, _base) typedef VkUintPtrLeast64 _obj; 1660 #endif 1661 1662 typedef enum { 1663 VK_SUCCESS = 0, 1664 VK_UNSUPPORTED = 1, 1665 VK_NOT_READY = 2, 1666 ... 1667 } VkResult; 1668 typedef enum { 1669 VK_STRUCTURE_TYPE_APPLICATION_INFO = 0, 1670 ... 1671 } VKStructureType; 1672 typedef struct { 1673 VkStructureType sType; 1674 const void* pNext; 1675 const char* pAppName; 1676 uint32_t appVersion; 1677 const char* pEngineName; 1678 uint32_t engineVersion; 1679 uint32_t apiVersion; 1680 } VkApplicationInfo; 1681 typedef enum { 1682 VK_SYSTEM_ALLOC_TYPE_API_OBJECT = 0, 1683 ... 1684 } VkSystemAllocType; 1685 typedef void* (VKAPI_PTR *PFN_vkAllocFunction)( 1686 void* pUserData, 1687 size_t size, 1688 size_t alignment, 1689 VkSystemAllocType allocType); 1690 typedef void (VKAPI_PTR *PFN_vkFreeFunction)( 1691 void* pUserData, 1692 void* pMem); 1693 typedef struct { 1694 void* pUserData; 1695 PFN_vkAllocFunction pfnAlloc; 1696 PFN_vkFreeFunction pfnFree; 1697 } VkAllocCallbacks; 1698 typedef struct { 1699 VkStructureType sType; 1700 const void* pNext; 1701 const VkApplicationInfo* pAppInfo; 1702 const VkAllocCallbacks* pAllocCb; 1703 uint32_t extensionCount; 1704 const char*const* ppEnabledExtensionNames; 1705 } VkInstanceCreateInfo; 1706 VK_DEFINE_BASE_HANDLE(VkObject) 1707 VK_DEFINE_DISP_SUBCLASS_HANDLE(VkInstance, VkObject) 1708 #define VK_MAX_PHYSICAL_DEVICE_NAME 256 1709 #define VK_MAX_EXTENSION_NAME 256 1710 typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)(const VkInstanceCreateInfo* pCreateInfo, VkInstance* pInstance); 1711 #ifndef VK_NO_PROTOTYPES 1712 VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance( 1713 const VkInstanceCreateInfo* pCreateInfo, 1714 VkInstance* pInstance); 1715 #endif 1716 1717 #ifdef __cplusplus 1718 } 1719 #endif 1720 1721 #endif 1722 -------------------------------------- 1723 1724 Note that several additional types are pulled in by the type dependency 1725 analysis, but only those types, commands, and tokens required by the 1726 specified features are generated. 1727 1728 1729 == How To Add A Compile Time Constant 1730 1731 Go to the desired tag:feature or tag:extension tag. Add (if not present) a 1732 nested tag:require block labelled 1733 1734 [source,xml] 1735 -------------------------------------- 1736 <require comment="API constants"> 1737 -------------------------------------- 1738 1739 In this block, add an (appropriately indented) tag like 1740 1741 [source,xml] 1742 -------------------------------------- 1743 <enum name="VK_THE_ANSWER"/> 1744 -------------------------------------- 1745 1746 Then go to the tag:enums block labelled 1747 1748 [source,xml] 1749 -------------------------------------- 1750 <enums comment="Misc. hardcoded constants - not an enumerated type"> 1751 -------------------------------------- 1752 1753 In this block, add a tag whose attr:name attribute matches the attr:name 1754 you defined above and whose attr:value attribute is the value to give the 1755 constant: 1756 1757 [source,xml] 1758 -------------------------------------- 1759 <enum value="42" name="VK_THE_ANSWER"/> 1760 -------------------------------------- 1761 1762 1763 == How To Add A Struct or Union Type 1764 1765 For this example, assume we want to define a type 1766 corresponding to a C `struct` defined as follows: 1767 1768 [source,c] 1769 -------------------------------------- 1770 typedef struct { 1771 VkStructureType sType; 1772 const void* pNext; 1773 const VkApplicationInfo* pAppInfo; 1774 const VkAllocCallbacks* pAllocCb; 1775 uint32_t extensionCount; 1776 const char*const* ppEnabledExtensionNames; 1777 } VkInstanceCreateInfo; 1778 -------------------------------------- 1779 1780 If `VkInstanceCreateInfo` is the type of a parameter of a command in 1781 the API, make sure that command's definition (see below for how to add a 1782 command) puts `VkInstanceCreateInfo` in nested tag:type tags where 1783 it is used. 1784 1785 Otherwise, if the struct type is not used directly by a command in the API, 1786 nor required by a chain of type dependencies for other commands, an explicit 1787 tag:type dependency should be added to the tag:feature tag. Go to the 1788 tag:types tag and search for the nested block labelled 1789 1790 [source,xml] 1791 -------------------------------------- 1792 <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."> 1793 ... 1794 -------------------------------------- 1795 1796 In this block, add a tag whose attr:name attribute matches the attr:name 1797 of the struct type being defined: 1798 1799 [source,xml] 1800 -------------------------------------- 1801 <require comment="API types not used by commands"> 1802 <type name="VkInstanceCreateInfo"/> 1803 ... 1804 -------------------------------------- 1805 1806 Then go to the tag:types tag and add a new tag:type tag defining 1807 the struct names and members, somewhere below 1808 the corresponding comment, like this: 1809 1810 [source,xml] 1811 -------------------------------------- 1812 <types> 1813 ... 1814 <comment>Struct types</comment> 1815 <type category="struct" name="VkInstanceCreateInfo"> 1816 <member><type>VkStructureType</type> 1817 <name>sType</name></member> 1818 <member>const void* 1819 <name>pNext</name></member> 1820 <member>const <type>VkApplicationInfo</type>* 1821 <name>pAppInfo</name></member> 1822 <member>const <type>VkAllocCallbacks</type>* 1823 <name>pAllocCb</name></member> 1824 <member><type>uint32_t</type> 1825 <name>extensionCount</name></member> 1826 <member>const <type>char</type>*const* 1827 <name>ppEnabledExtensionNames</name></member> 1828 </type> 1829 ... 1830 -------------------------------------- 1831 1832 If any of the member types are types also defined in the header, make sure 1833 to enclose those type names in nested tag:type tags, as shown above. Basic 1834 C types should not be tagged. 1835 1836 If the type is a C `union`, rather than a `struct`, then set the 1837 value of the attr:category attribute to `"union"` instead of 1838 `"struct"`. 1839 1840 1841 == How To Add An Enumerated Type 1842 1843 For this example, assume we want to define a type corresponding to a C 1844 `enum` defined as follows: 1845 1846 [source,c] 1847 -------------------------------------- 1848 typedef enum { 1849 VK_DEVICE_CREATE_VALIDATION_BIT = 0x00000001, 1850 VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT = 0x00000002; 1851 } VkDeviceCreateFlagBits. 1852 -------------------------------------- 1853 1854 If `VkDeviceCreateFlagBits` is the type of a parameter to a command in 1855 the API, or of a member in a structure or union, make sure that command 1856 parameter or struct member's definition puts `VkDeviceCreateFlagBits` 1857 in nested tag:type tags where it is used. 1858 1859 Otherwise, if the enumerated type is not used directly by a command in the 1860 API, nor required by a chain of type dependencies for commands and structs, 1861 an explicit tag:type dependency should be added to the tag:feature tag 1862 in exactly the same fashion as described above for `struct` types. 1863 1864 Next, go to the line labelled 1865 1866 [source,xml] 1867 -------------------------------------- 1868 <comment>Vulkan enumerant (token) definitions</comment> 1869 -------------------------------------- 1870 1871 At an appropriate point below this line, add an tag:enums tag whose 1872 attr:name attribute matches the tag:type name `VkDeviceCreateFlagBits`, and 1873 whose contents correspond to the individual fields of the enumerated type: 1874 1875 [source,xml] 1876 -------------------------------------- 1877 <enums name="VkDeviceCreateFlagBits" type="bitmask"> 1878 <enum bitpos="0" name="VK_DEVICE_CREATE_VALIDATION_BIT"/> 1879 <enum bitpos="1" name="VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT"/> 1880 </enums> 1881 -------------------------------------- 1882 1883 Several other attributes of the tag:enums tag can be set. In this case, 1884 the attr:type attribute is set to `"bitmask"`, indicating that the 1885 individual enumerants represent elements of a bitmask. 1886 1887 The individual tag:enum tags define the enumerants, just like the 1888 definition for compile time constants described above. In this case, because 1889 the enumerants are bits in a bitmask, their values are specified using the 1890 attr:bitpos attribute. The value of this attribute must be an integer in 1891 the range [0,31] specifying a single bit number, and the resulting value 1892 is printed as a hexadecimal constant corresponding to that bit. 1893 1894 It is also possible to specify enumerant values using the attr:value 1895 attribute, in which case the specified numeric value is passed through to 1896 the C header unchanged. 1897 1898 1899 == How to Add A Command 1900 1901 For this example, assume we want to define the command: 1902 1903 [source,c] 1904 -------------------------------------- 1905 VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance( 1906 const VkInstanceCreateInfo* pCreateInfo, 1907 VkInstance* pInstance); 1908 -------------------------------------- 1909 1910 Commands must always be explicitly required in the tag:feature tag. In 1911 that tag, you can use an existing tag:require block including API features 1912 which the new command should be grouped with, or define a new block. For 1913 this example, add a new block, and require the command by using the 1914 tag:command tag inside that block: 1915 1916 [source,xml] 1917 -------------------------------------- 1918 <feature api="vulkan" name="VK_VERSION_1_0" number="1.0" comment="Vulkan core API interface definitions"> 1919 ... 1920 <require comment="Device initialization"> 1921 <command name="vkCreateInstance"/> 1922 </require> 1923 ... 1924 </feature> 1925 -------------------------------------- 1926 1927 The tag:require block may include a attr:comment attribute whose value 1928 is a descriptive comment of the contents required within that block. The 1929 comment is not currently used in header generation, but might be in the 1930 future, so use comments which are polite and meaningful to users of 1931 the generated header files. 1932 1933 Then go to the tag:commands tag and add a new tag:command tag defining 1934 the command, preferably sorted into alphabetic order with other commands for 1935 ease of reading, as follows: 1936 1937 [source,xml] 1938 -------------------------------------- 1939 <commands comment="Vulkan command definitions"> 1940 ... 1941 <command> 1942 <proto><type>VkResult</type> 1943 <name>vkCreateInstance</name></proto> 1944 <param>const <type>VkInstanceCreateInfo</type>* 1945 <name>pCreateInfo</name></param> 1946 <param><type>VkInstance</type>* 1947 <name>pInstance</name></param> 1948 </command> 1949 ... 1950 </commands> 1951 -------------------------------------- 1952 1953 The tag:proto tag defines the return type and function name of the 1954 command. The tag:param tags define the command's parameters in the order 1955 in which they are passed, including the parameter type and name. The contents 1956 are laid out in the same way as the structure tag:member tags described 1957 previously. 1958 1959 1960 == More Complicated API Representations 1961 1962 The registry schema can represent a good deal of additional information, for 1963 example by creating multiple tag:feature tags defining different API 1964 versions and extensions. This capability is not yet relevant to Vulkan. 1965 Those capabilities will be documented as they are needed. 1966 1967 1968 == More Complicated Output Formats And Other Languages 1969 1970 The registry schema is oriented towards C-language APIs. Types and commands 1971 are defined using syntax which is a subset of C, especially for structure 1972 members and command parameters. It would be possible to use a 1973 language-independent syntax for representing such information, but since we 1974 are writing a C API, any such representation would have to be converted into 1975 C anyway at some stage. 1976 1977 The `vulkan.h` header is written using an _output generator_ object 1978 in the Python scripts. This output generator is specialized for C, but the 1979 design of the scripts is intended to support writing output generators for 1980 other languages as well as purposes such as documentation (e.g. generating 1981 asciidoc fragments corresponding to types and commands for use in the API 1982 specification and reference pages). When targeting other languages, the 1983 amount of parsing required to convert type declarations into other languages 1984 is small. However, it will probably be necessary to modify some of the 1985 boilerplate C text, or specialize the tags by language, to support such 1986 generators. 1987 1988 1989 == Additional Semantic Tagging 1990 1991 The schema is being extended to support semantic tags describing 1992 various properties of API features, such as: 1993 1994 * constraints on allowed scalar values to function parameters 1995 (non-`NULL`, normalized floating-point, etc.) 1996 * length of arrays corresponding to function pointer parameters 1997 * miscellaneous properties of commands such as whether the application 1998 or system is responsible for threadsafe use; which queues they may 1999 be issued on; whether they are aliases or otherwise related to other 2000 commands; etc. 2001 2002 These tags will be used by other tools for purposes such as helping 2003 create validation layers, generating serialization code, and so on. We 2004 would like to eventually represent everything about the API that is 2005 amenable to automatic processing within the registry schema. Please make 2006 suggestions on the Github issue tracker. 2007 2008 2009 [[general:stability]] 2010 == Stability of the XML Database and Schema 2011 2012 The Vulkan XML schema is evolving in response to corresponding changes 2013 in the Vulkan API and ecosystem. Most such change will probably be 2014 confined to adding attributes to existing tags and properly expressing 2015 the relationships to them, and making API changes corresponding to 2016 accepted feature requests. Changes to the schema should be described in 2017 the <<changelog,change log>> of this document. Changes to the `.xml` 2018 files and Python scripts are logged in Github history. 2019 2020 2021 [[changelog]] 2022 = Change Log 2023 2024 * 2018-12-06 - Specify that command aliases are not guaranteed to resolve 2025 to the same entry point in the underlying layer stack, matching a 2026 related clarification in the Vulkan Specification. 2027 * 2018-10-01 - Add description of the default value of attr:optional 2028 member and parameter attributes, if not specified. 2029 * 2018-08-28 - Add optional attr:provisional attribute to tag:extension 2030 tags. 2031 * 2018-07-07 - Add optional attr:promotedto, attr:deprecatedby, and 2032 attr:obsoletedby attributes to tag:extension tags. 2033 * 2018-06-25 - Remove attr:vendorids tags for Khronos vendor IDs. 2034 * 2018-04-15 - Add attr:requiresCore. 2035 * 2018-03-07 - Updated for Vulkan 1.1 release. 2036 * 2018-02-21 - Add descriptions of the attr:extnumber and attr:alias 2037 attributes used for defining tag:enum attributes, the attr:alias 2038 attribute used for defining tag:type aliases, the attr:name and 2039 attr:alias attributes used for defining tag:command aliases, the 2040 attr:platform attribute of tag:extension tags, and the attr:feature 2041 attribute of tag:require tags; and update the document to the header 2042 naming and grouping scheme used starting in Vulkan 1.1. 2043 * 2018-01-07 - Add tag:platforms and tag:platform tags for describing 2044 Vulkan platform names and preprocessor symbols. 2045 * 2017-09-10 - Define syntax of member and parameter attr:altlen 2046 attributes, for use by code generators. 2047 * 2017-09-01 - Define syntax of member and parameter attr:len attributes 2048 consistently and correctly for current uses of latexmath: 2049 * 2017-08-24 - Note that the tag:extension attribute attr:type must be 2050 specified if the extension is not disabled. 2051 * 2017-07-27 - Finish removing validextensionstructs attribute and 2052 replacing it with structextends. 2053 * 2017-07-14 - Add comment attributes or tags as valid content in several 2054 places, replacing XML comments which could not be preserved by XML 2055 transformation tools. 2056 * 2017-02-20 - Change to asciidoctor markup and move into the 2057 specification source directory for ease of building. 2058 * 2016-09-27 - Remove tag:validity and tag:usage tags, since these 2059 explicit usage statements have been moved to the specification source. 2060 * 2016-08-26 - Update for the single-branch model. 2061 * 2016-07-28 - Add attr:type and attr:requires attributes to tag:extension 2062 tags. 2063 * 2016-02-22 - Change math markup in attr:len attributes to use 2064 asciidoc `latexmath:[$` and `$]` delimiters. 2065 * 2016-02-19 - Add attr:successcodes and attr:errorcodes attributes of 2066 tag:command tags. Add a subsection to the introduction describing 2067 the schema choices and how to file issues against the registry. 2068 * 2016-02-07 - Add attr:vendorids tags for Khronos vendor IDs. 2069 * 2015-12-10 - Add attr:author and attr:contact attributes for 2070 tag:extension tags. 2071 * 2015-12-07 - Move `vulkan/vulkan.h` to a subdirectory. 2072 * 2015-12-01 - Add tag:tags tags for author tags. 2073 * 2015-11-18 - Bring documentation and schema up to date for extension 2074 enumerants. 2075 * 2015-11-02 - Bring documentation and schema up to date with several 2076 recent merges, including tag:validity tags. Still out of date WRT 2077 extension enumerants, but that will change soon. 2078 * 2015-09-08 - Rename `threadsafe` attribute to attr:externsync, and 2079 `implicitunsafeparams` tag to attr:implicitexternsync. 2080 * 2015-09-07 - Update tag:command tag description to remove the 2081 attr:threadsafe attribute and replace it with a combination of 2082 attr:threadunsafe attributes on individual parameters, and 2083 tag:implicitunsafeparams tags describing additional unsafe objects 2084 for the command. 2085 * 2015-08-04 - Add `basetype` and `funcpointer` attr:category values 2086 for type tags, and explain the intended use and order in which types 2087 in each category are emitted. 2088 * 2015-07-02 - Update description of Makefile targets. Add descriptions of 2089 attr:threadsafe, attr:queues, and attr:renderpass attributes of 2090 <<tag-command,tag:command>> tags, and of attr:modified attributes of 2091 <<tag-command:param,tag:param>> tags. 2092 * 2015-06-17 - add descriptions of allowed attr:category attribute 2093 values of tag:type tags, used to group and sort related categories 2094 of declarations together in the generated header. 2095 * 2015-06-04 - Add <<examples,examples of making changes and additions>> 2096 to the registry. 2097 * 2015-06-03 - Move location to new `vulkan` Git repository. Add 2098 definition of tag:type tags for C struct/unions. Start adding 2099 <<examples,examples of making changes>>. 2100 * 2015-06-02 - Branch from OpenGL specfile documentation and bring up 2101 to date with current Vulkan schema. 2102 * 2015-07-10 - Remove contractions to match the style guide. 2103 * 2015-07-19 - Move this document from LaTeX to asciidoc source format and 2104 make minor changes to markup.