1// Copyright 2013-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5// Core versions and extensions to enable 6// Must be included before the header and attribs.adoc 7include::{generated}/specattribs.adoc[] 8 9= The Khronos^®^ Vulkan^®^ API Registry 10Jon Leech 11:data-uri: 12:icons: font 13:toc2: 14:toclevels: 3 15:numbered: 16:source-highlighter: rouge 17:rouge-style: github 18:doctype: book 19:imagewidth: 800 20:fullimagewidth: width="800" 21:attribute-missing: warn 22:cl: : 23 24// Various special / math symbols. This is easier to edit with than Unicode. 25include::{config}/attribs.adoc[] 26 27:leveloffset: 1 28 29<<<< 30 31include::{config}/copyright-ccby.adoc[] 32 33<<<< 34 35[[introduction]] 36= Introduction 37 38This document describes the Khronos Vulkan API Registry schema, and provides 39some additional information about using the registry and scripts to generate 40a variety of outputs, including C header files as well as several types of 41asciidoc include files used in the Vulkan API specification and reference 42pages. 43The underlying XML files and scripts are located on the Khronos public 44GitHub server at URL 45 46https://github.com/KhronosGroup/Vulkan-Docs 47 48The authoritative copy of the Registry is maintained in the default branch, 49currently `main`. 50 51The registry uses an XML representation of the Vulkan API, together with a 52set of Python scripts to manipulate the registry once loaded. 53The scripts rely on the Python `etree` package to parse and operate on XML. 54An XML schema and validator target are included. 55 56The schema is based on, but not identical to that used for the previously 57published OpenGL, OpenGL ES and EGL API registries. 58It was extended to represent additional types and concepts not needed for 59those APIs, such as structure and enumerant types, as well as additional 60types of registered information specific to Vulkan. 61 62The Vulkan C header files generated from the registry are checked into a 63separate repository under 64 65https://github.com/KhronosGroup/Vulkan-Headers/ 66 67 68== Schema Choices 69 70The XML schema is not pure XML all the way down. 71In particular, command return types/names and parameters, and structure 72members, are described in mixed-mode tag containing C declarations of the 73appropriate information, with some XML nodes annotating particular parts of 74the declaration such as its base type and name. 75This choice is based on prior experience with the SGI `.spec` file format 76used to describe OpenGL, and greatly eases human reading and writing the 77XML, and generating C-oriented output. 78The cost is that people writing output generators for other languages will 79have to include enough logic to parse the C declarations and extract the 80relevant information. 81 82People who do not find the supplied Python scripts to suit their needs are 83likely to write their own parsers, interpreters, and/or converters operating 84on the registry XML. 85We hope that we have provided enough information in this document, the RNC 86schema (`registry.rnc`), and comments in the Registry (`vk.xml`) itself to 87enable such projects. 88If not and you need clarifications; if you have other problems using the 89registry; or if you have proposed changes and enhancements, then please file 90issues on Khronos' public GitHub project at 91 92https://github.com/KhronosGroup/Vulkan-Docs/issues 93 94Please tag your issues with `[Registry]` in the subject line to help us 95categorize them. 96 97 98[[introduction-normative]] 99== Normative References 100 101Normative references are references to external documents or resources to 102which documentation authors must comply. 103 104[[vulkan-styleguide]] Jon Leech and Tobias Hector. 105_Vulkan Documentation and Extensions: Procedures and Conventions_ (February 10626, 2023). 107https://registry.khronos.org/vulkan/specs/1.3/styleguide.html . 108 109[[vulkan-spec]] Khronos Vulkan Working Group. 110_Vulkan 1.3.242 - A Specification_ (February 26, 2023). 111https://registry.khronos.org/vulkan/ . 112 113 114[[starting]] 115= Getting Started 116 117See 118https://gitlab.khronos.org/vulkan/vulkan/blob/main/xml/README.adoc[`xml/README.adoc`] 119in the `Vulkan-Docs` repository for information on required toolchain 120components such as Python 3, pass:[g++], and GNU make. 121 122Once you have the right tools installed, perform the following steps: 123 124 * Check out the `Vulkan-Docs` repository linked above from Khronos GitHub 125 (there are instructions at the link) 126 * `cd` to the root directory in your checked-out repo 127 * Switch to the default branch (`main`). 128 * Invoke `make clean ; make install ; make test` 129 130This should regenerate `vulkan_core.h` and a variety of platform-specific 131headers, install them in `../include/vulkan/`, and verify that the headers 132build properly. 133If you build at the latest repository tag, the resulting headers should be 134identical to the latest versions in the 135link:https://github.com/KhronosGroup/Vulkan-Headers/[Vulkan-Headers 136repository]. 137 138The `install` target also generates source code for a simple extension 139loader library in `../src/ext_loader/`. 140 141Other Makefile targets in `xml/` include: 142 143 * `validate` - validate `vk.xml` against the XML schema. 144 Recommended if you are making nontrivial changes. 145 * The asciidoc includes used by the <<vulkan-spec, Vulkan API 146 Specification>> and Reference Pages are built using the 'make generated' 147 target in the parent directory Makefile, although they use the scripts 148 and XML in this directory. 149 These files are generated dynamically when building the specs, since 150 their contents depend on the exact set of extensions the Specification 151 is being built to include. 152 153If you just want to modify the API, changing `vk.xml` and running `make` 154should be all that is needed. 155See <<examples>> for some examples of modifying the XML. 156 157If you want to use the registry for reasons other than generating the header 158file, extension loader, and asciidoc includes, or to generate headers for 159languages other than C, start with the Makefile rules and the files 160`vk.xml` and scripts `genvk.py`, `reg.py`, and `generator.py`. 161The scripts are described below and are all located in the `scripts` 162directory under the repository root. 163 164== Header Generation Script - `genvk.py` 165 166When generating header files using the `genvk.py` script, an API name and 167profile name are required, as shown in the Makefile examples. 168Additionally, specific API versions and extensions can be required or 169excluded. 170Based on this information, the generator script extracts the relevant 171interfaces and creates a C-language header file for them. 172`genvk.py` contains predefined generator options for the current 173<<vulkan-spec, Vulkan API Specification>> release. 174 175The generator script is intended to be generalizable to other languages by 176writing new generator classes. 177Such generators would have to rewrite the C types and definitions in the XML 178to something appropriate to their language. 179 180 181== Registry Processing Script - `reg.py` 182 183XML processing is done in `reg.py`, which contains several objects and 184methods for loading registries and extracting interfaces and extensions for 185use in header generation. 186There is some internal documentation in the form of comments, although 187nothing more extensive exists yet. 188 189 190== Output Generator Script - `generator.py` 191 192Once the registry is loaded, the `COutputGenerator` class defined in 193`generator.py` is used to create a header file. 194The `DocOutputGenerator` class is used to create the asciidoc include files. 195Output generators for other purposes can be added as needed. 196There are a variety of output generators included: 197 198 * `cgenerator.py` - generate C header file 199 * `docgenerator.py` - generate asciidoc includes for APIs 200 * `hostsyncgenerator.py` - generate host sync table includes for APIs 201 * `validitygenerator.py` - generate validity language includes 202 * `pygenerator.py` - generate a Python dictionary-based encoding of 203 portions of the registry, used during spec generation 204 * `extensionStubSource.py` - generate a simple C extension loader. 205 206 207[[schema]] 208= Vulkan Registry Schema 209 210The format of the Vulkan registry is a top level tag:registry tag containing 211tag:types, tag:enums, tag:commands, tag:feature, and tag:extension tags 212describing the different elements of an API, as explained below. 213This description corresponds to a formal Relax NG schema file, 214`registry.rnc`, against which the XML registry files can be validated. 215 216At present the only registry in this schema is the core Vulkan API registry, 217`vk.xml`. 218 219 220[[schema:profile]] 221== Profiles 222 223Types and enumerants can have different definitions depending on the API 224profile requested. 225This capability is not used in the current Vulkan API but may be in the 226future. 227Features and extensions can include some elements conditionally depending on 228the API profile requested. 229 230 231[[schema:apiname]] 232== API Names 233 234Specific API versions features and extensions can be tagged as belonging to 235to classes of features with the use of _API names_. 236This is intended to allow multiple closely-related API specifications in the 237same family - such as desktop and mobile specifications - to share the same 238XML. 239An API name is an arbitrary alphanumeric string, although it should be 240chosen to match the corresponding API. 241For example, Vulkan and OpenXR use `vulkan` and `openxr` as their API names, 242respectively. 243 244The attr:api attribute of the tag:feature tag and the attr:supported 245attribute of the tag:extensions tag must be comma-separated lists of one or 246more API names, all of which match that feature or extension. 247When generating headers and other artifacts from the XML, an API name may be 248specified to the processing scripts, causing the selection of only those 249features and extensions whose API names match the specified name. 250 251Several other tags for defining types and groups of types also support 252attr:api attributes. 253If present, the attribute value must be a comma-separated list of one or 254more API names. 255This allows specializing a definition for different, closely related APIs. 256 257 258[[schema:root]] 259= Registry Root (tag:registry Tag) 260 261A tag:registry contains the entire definition of one or more related APIs. 262 263== Attributes of tag:registry Tags 264 265None. 266 267== Contents of tag:registry Tags 268 269Zero or more of each of the following tags, normally in this order (although 270order should not be important): 271 272 * tag:comment - Contains arbitrary text, such as a copyright statement. 273 * <<tag-platforms,tag:platforms>> - defines platform names corresponding 274 to platform-specific <<tag-extension,API extensions>>. 275 * <<tag-tags,tag:tags>> - defines author IDs used for extensions and 276 layers. 277 Author IDs are described in detail in the "`Layers & Extensions`" 278 section of the "`Vulkan Documentation and Extensions: Procedures and 279 Conventions`" document. 280 * <<tag-types,tag:types>> - defines API types. 281 Usually only one tag is used. 282 * <<tag-enums,tag:enums>> - defines API token names and values. 283 Usually multiple tags are used. 284 Related groups may be tagged as an enumerated type corresponding to a 285 tag:type tag, and resulting in a C `enum` declaration. 286 This ability is heavily used in the Vulkan API. 287 * <<tag-commands,tag:commands>> - defines API commands (functions). 288 Usually only one tag is used. 289 * <<tag-feature,tag:feature>> - defines API feature interfaces (API 290 versions, more or less). 291 One tag per feature set. 292 * <<tag-extensions,tag:extensions>> - defines API extension interfaces. 293 Usually only one tag is used, wrapping many extensions. 294 * <<tag-formats,tag:formats>> - defines properties of image formats. 295 Only one tag is used, wrapping all the formats. 296 * <<tag-spirvextensions,tag:spirvextensions>> - defines relationship 297 between SPIR-V extensions and API interfaces which enable each 298 extension. 299 Only one tag is used, wrapping all the SPIR-V extensions. 300 * <<tag-spirvcapabilities,tag:spirvcapabilities>> - defines relationship 301 between SPIR-V capabilities and API interfaces which enable each 302 capability. 303 Only one tag is used, wrapping all the SPIR-V capabilities. 304 * <<tag-sync,tag:sync>> - Defines sync objects 305 * <<tag-syncstage,tag::syncstage>> - Defines all Pipeline Stages 306 * <<tag-syncaccess,tag::syncaccess>> - Defines all Access Types 307 * <<tag-syncpipeline,tag::syncpipeline>> - Defines Pipeline's logical ordering 308 309 310[[tag-comment]] 311=== Comment Tags (tag:comment Tag) 312 313A tag:comment tag contains an arbitrary string, and is unused. 314Comment tags may appear in multiple places in the schema, as described 315below. 316Comment tags are removed by output generators if they would otherwise appear 317in generated headers, asciidoc include files, etc. 318 319 320[[tag-platforms]] 321= Platform Name Blocks (tag:platforms Tag) 322 323A tag:platforms contains descriptions of platform IDs for platforms 324supported by window system-specific extensions to Vulkan. 325 326== Attributes of tag:platforms Tags 327 328 * attr:comment - optional. 329 Arbitrary string (unused). 330 331== Contents of tag:platforms Tags 332 333Zero or more tag:platform tags, in arbitrary order (though they are 334typically ordered by sorting on the platform name). 335 336 337[[tag-platform]] 338= Platform Names (tag:platform Tag) 339 340A tag:platform tag describes a single platform name. 341 342== Attributes of tag:platform Tags 343 344 * attr:name - required. 345 The platform name. 346 This must be a short alphanumeric string corresponding to the platform 347 name, valid as part of a C99 identifier. 348 Lower-case is preferred. 349 In some cases, it may be desirable to distinguish a subset of platform 350 functionality from the entire platform. 351 In these cases, the platform name should begin with the entire platform 352 name, followed by `_` and the subset name. 353+ 354-- 355[NOTE] 356.Note 357==== 358For example, 359 360`name="xlib"` 361 362is used for the X Window System, Xlib client library platform. 363 364`name="xlib_xrandr"` 365 366is used for the XRandR functionality within the `xlib` platform. 367==== 368-- 369 * attr:protect - required. 370 This must be a C99 preprocessor token beginning with `VK_USE_PLATFORM_` 371 followed by the platform name, converted to upper case, followed by `_` 372 and the extension suffix of the corresponding window system-specific 373 extension supporting the platform. 374+ 375-- 376[NOTE] 377.Note 378==== 379For example, 380 381`protect="VK_USE_PLATFORM_XLIB_XRANDR_EXT"` 382 383is used for the `xlib_xrandr` platform name. 384==== 385-- 386 * attr:comment - optional. 387 Arbitrary string (unused). 388 389== Contents of tag:platform Tags 390 391No contents are allowed. 392All information is contained in the attributes. 393 394 395[[tag-tags]] 396= Author ID Blocks (tag:tags Tag) 397 398A tag:tags tag contains tag:authorid tags describing reserved author IDs 399used by extension and layer authors. 400 401== Attributes of tag:tags Tags 402 403 * attr:comment - optional. 404 Arbitrary string (unused). 405 406== Contents of tag:tags Tags 407 408Zero or more tag:tag tags, in arbitrary order (though they are typically 409ordered by sorting on the author ID). 410 411 412[[tag-tag]] 413= Author IDs (tag:tag Tag) 414 415A tag:tag tag contains information defining a single author ID. 416 417== Attributes of tag:tag Tags 418 419 * attr:name - required. 420 The author ID, as registered with Khronos. 421 A short, upper-case string, usually an abbreviation of an author, 422 project or company name. 423 * attr:author - required. 424 The author name, such as a full company or project name. 425 * attr:contact - required. 426 The contact who registered or is currently responsible for extensions 427 and layers using the ID, including sufficient contact information to 428 reach the contact such as individual name together with email address, 429 GitHub username, or other contact information. 430 431== Contents of tag:tag Tags 432 433No contents are allowed. 434All information is contained in the attributes. 435 436 437[[tag-types]] 438= API Type Blocks (tag:types Tag) 439 440A tag:types tag contains definitions of derived types used in the API. 441 442== Attributes of tag:types Tags 443 444 * attr:comment - optional. 445 Arbitrary string (unused). 446 447== Contents of tag:types Tags 448 449Zero or more tag:type and tag:comment tags, in arbitrary order (though they 450are typically ordered by putting dependencies of other types earlier in the 451list). 452The tag:comment tags are used mostly to indicate grouping of related types. 453 454 455[[tag-type]] 456= API Type (tag:type Tag) 457 458A tag:type tag contains information which can be used to generate C code 459corresponding to the type. 460In many cases, this is simply legal C code, with attributes or embedded tags 461denoting the type name and other types used in defining this type. 462In some cases, additional attribute and embedded type information is used to 463generate more complicated C types. 464 465== Attributes of tag:type Tags 466 467 * attr:requires - optional. 468 Another type name this type requires to complete its definition. 469 * attr:name - optional. 470 Name of this type (if not defined in the tag body). 471 * attr:alias - optional. 472 Another type name which this type is an alias of. 473 Must match the name of another tag:type element. 474 This is typically used when promoting a type defined by an extension to 475 a new core version of the API. 476 The old extension type is still defined, but as an alias of the new 477 type. 478 * attr:api - optional comma-separated list of <<schema:apiname, API names>> 479 for which this definition is specialized, so that different APIs may 480 have different definitions for the same type. 481 This definition is only used if the requested API name matches the 482 attribute. 483 May be used to address subtle incompatibilities. 484 * attr:category - optional. 485 A string which indicates that this type contains a more complex 486 structured definition. 487 At present the only accepted categories are `basetype`, `bitmask`, 488 `define`, `enum`, `funcpointer`, `group`, `handle`, `include`, `struct`, 489 and `union`, as described below. 490 * attr:comment - optional. 491 Arbitrary string (unused). 492 * attr:deprecated - optional. 493 Indicates that this type has been deprecated. 494 Possible values are: 495 ** `"true"` - deprecated, but no explanation given. 496 ** `"aliased"` - an old name not following Vulkan conventions. 497 The equivalent alias following Vulkan conventions should be used 498 instead. 499 * attr:parent - only applicable if `"category"` is `handle`. 500 Notes another type with the `handle` category that acts as a parent 501 object for this type. 502 * attr:returnedonly - only applicable if `"category"` is `struct` or 503 `union`. 504 Notes that this struct/union is going to be filled in by the API, rather 505 than an application filling it out and passing it to the API. 506 * attr:structextends only applicable if category is `struct` or `union`. 507 This is a comma-separated list of structures whose `pNext` can include 508 this type. 509 This should usually only list the top-level structure that is extended, 510 for all possible extending structures. 511 This will generate a validity statement on the top level structure that 512 validates the entire chain in one go, rather than each extending 513 structure repeating the list of valid structs. 514 There is no need to set the attr:noautovalidity attribute on the `pNext` 515 members of extending structures. 516 * attr:allowduplicate - only applicable if attr:category is `"struct"`. 517 If `"true"`, then structures whose `pNext` chains include this structure 518 may include more than one instance of it. 519 * attr:objtypeenum - only applicable at present if attr:category is 520 `"handle"`. 521 Specifies the name of a `VkObjectType` enumerant which corresponds to 522 this type. 523 The enumerant must be defined. 524 525== Contents of tag:type Tags 526 527The valid contents depend on the attr:category attribute. 528 529=== Enumerated Types - attr:category `"enum"` 530 531If the attr:category tag has the value `enum`, the type is a C enumeration. 532The body of the tag is ignored in this case. 533The value of the attr:name attribute must be provided and must match the 534attr:name attribute of a <<tag-enums,tag:enums>> tag. 535The enumerant values defined within the tag:enums tag are used to generate a 536C `enum` type declaration. 537 538=== Structure Types - attr:category `"struct"` or `"union"` 539 540If the attr:category tag has the values `struct` or `union`, the type is a C 541structure or union, respectively. 542In this case, the attr:name attribute must be provided, and the contents of 543the tag:type tag are a series of tag:member tags defining the members of the 544aggregate type, in order, interleaved with any number of tag:comment tags. 545 546==== Structure Member (tag:member) Tags 547 548The tag:member tag defines the type and name of a structure or union member. 549 550==== Attributes of tag:member Tags 551 552 * attr:api - optional <<schema:apiname, API names>> for which this 553 definition is specialized, so that different APIs may have different 554 definitions for the same type. 555 This definition is only used if the requested API name matches the 556 attribute. 557 May be used to address subtle incompatibilities. 558 * attr:values - only valid on the `sType` member of a struct. 559 This is a comma-separated list of enumerant values that are valid for 560 the structure type; usually there is only a single value. 561 * attr:len - if the member is an array, len may be one or more of the 562 following things, separated by commas (one for each array indirection): 563 another member of that struct; `"null-terminated"` for a string; `"1"` 564 to indicate it is just a pointer (used for nested pointers); or an 565 equation in math markup for incorporation in the specification (a LaTeX 566 math expression delimited by `latexmath:[` and `]`. 567 The only variables in the equation should be the names of members of the 568 structure. 569 * attr:altlen - if the attr:len attribute is specified, and contains a 570 `latexmath:` equation, this attribute should be specified with an 571 equivalent equation using only C builtin operators, C math library 572 function names, and variables as allowed for attr:len. 573 It must be a valid C99 expression whose result is equal to attr:len for 574 all possible inputs. 575 It is a comma separated list that has size equal to only the `latexmath` 576 item count in attr:len list. 577 This attribute is intended to support consumers of the XML who need to 578 generate validation code from the allowed length. 579 * attr:deprecated - optional. 580 Indicates that this member has been deprecated. 581 Possible values are: 582 ** `"true"` - deprecated, but no explanation given. 583 ** `"ignored"` - functionality described by this member no longer 584 operates. 585 * attr:externsync - denotes that the member should be externally 586 synchronized when accessed by Vulkan 587 * attr:optional - optional. 588 A value of `"true"` specifies that this member can be omitted by 589 providing `NULL` (for pointers), `VK_NULL_HANDLE` (for handles), or 0 590 (for other scalar types). 591 If not present, the value is assumed to be `"false"` (the member must 592 not be omitted). 593 If the member is a pointer to one of those types, multiple values may be 594 provided, separated by commas - one for each pointer indirection. 595 Structure members with name `pNext` must always be specified with 596 `optional="true"`, since there is no requirement that any member of a 597 `pNext` chain have a following member in the chain. 598+ 599-- 600[NOTE] 601.Note 602==== 603While the attr:optional attribute can be used for scalar types such as 604integers, it does not affect the output generators included with the 605<<vulkan-spec, Vulkan API Specification>>. 606In this case, the attribute serves only as an indicator to human readers of 607the XML. 608 609Explicitly specifying `optional="false"` is not supported, but 610`optional="false,true"` is supported for a pointer type. 611==== 612-- 613 * attr:selector - optional. 614 If the member is a union, attr:selector identifies another member of the 615 struct that is used to select which of that union's members are valid. 616 * attr:selection - optional. 617 For a member of a union, attr:selection identifies a value of the 618 attr:selector that indicates this member is valid. 619 * attr:noautovalidity - prevents automatic validity language being 620 generated for the tagged item. 621 Only suppresses item-specific validity - parenting issues etc. 622 are still captured. 623 It must also be used for structures that have no implicit validity when 624 such structure has explicit validity. 625 * attr:limittype - only applicable for members of 626 `VkFormatProperties`, `VkFormatProperties2`, 627 `VkPhysicalDeviceProperties`, `VkPhysicalDeviceProperties2`, 628 `VkPhysicalDeviceLimits`, `VkQueueFamilyProperties`, 629 `VkQueueFamilyProperties2`, `VkSparseImageFormatProperties`, 630 `VkSparseImageFormatProperties2`, and structures extending or members of 631 any of those structures. 632 Specifies the type of a device limit. 633 This type describes how a value might be compared with the value of a 634 member in order to check whether it fits the limit. 635 Valid values: 636 ** `"min"` and `"max"` denote minimum and maximum limits. 637 They may also apply to arrays and `VkExtent*D`. 638 ** `"not"` specifies a feature is supported when false. 639 ** `"pot"` denotes a value that has to be a power of two value. 640 They may also apply to arrays and `VkExtent*D`. 641 ** `"mul"` denotes a value that must be an integer multiple of this limit. 642 They may also apply to arrays and `VkExtent*D`. 643 ** `"bits"` corresponds to the bits precision of an implementation. 644 ** `"bitmask"` corresponds to bitmasks and `VkBool32`, where set bits 645 indicate the presence of a capability 646 ** `"range"` specifies a [min, max] range 647 ** `"struct"` means that the member's fields should be compared. 648 ** `"exact"` specifies a limit that must be a specific value. 649 ** `"noauto"` limits cannot be trivially compared. 650 This is the default value, if unspecified. 651 * attr:objecttype - only applicable for members which are `uint64_t` 652 values representing a Vulkan object handle. 653 Specifies the name of another member which must be a `VkObjectType` or 654 `VkDebugReportObjectTypeEXT` value specifying the type of object the 655 handle refers to. 656 * attr:stride - if the member is an array, stride specifies the name of 657 another member containing the byte stride between consecutive elements 658 in the array. Is assumed tightly packed if omitted. 659 660 661==== Contents of tag:member Tags 662 663The text elements of a tag:member tag, with all other tags removed, is a 664legal C declaration of a struct or union member. 665In addition it may contain several semantic tags: 666 667 * The tag:type tag is optional. 668 It contains text which is a valid type name found in another tag:type 669 tag, and indicates that this type must be previously defined for the 670 definition of the command to succeed. 671 Builtin C types should not be wrapped in tag:type tags. 672 * The tag:name tag is required, and contains the struct/union member name 673 being described. 674 * The tag:enum tag is optional. 675 It contains text which is a valid enumerant name found in another 676 tag:type tag, and indicates that this enumerant must be previously 677 defined for the definition of the command to succeed. 678 Typically this is used to semantically tag static array lengths. 679 * The tag:comment tag is optional. 680 It contains an arbitrary string (unused). 681 682 683=== All Other Types 684 685If the attr:category attribute is one of `basetype`, `bitmask`, `define`, 686`funcpointer`, `group`, `handle` or `include`, or is not specified, tag:type 687contains text which is legal C code for a type declaration. 688It may also contain embedded tags: 689 690 * tag:type - nested type tags contain other type names which are required 691 by the definition of this type. 692 * tag:apientry/ - insert a platform calling convention macro here during 693 header generation, used mostly for function pointer types. 694 * tag:name - contains the name of this type (if not defined in the tag 695 attributes). 696 * tag:bitvalues - contains the name of the enumeration defining flag 697 values for a `bitmask` type. 698 Ignored for other types. 699 700There is no restriction on which sorts of definitions may be made in a given 701category, although the contents of tags with attr:category `enum`, `struct` 702or `union` are interpreted specially as described above. 703 704However, when generating the header, types within each category are grouped 705together, and categories are generated in the order given by the following 706list. 707Therefore, types in a category should correspond to the intended purpose 708given for that category. 709If this recommendation is not followed, it is possible that the resulting 710header file will not compile due to out-of-order type dependencies. 711The intended purpose of each category is: 712 713 * `include` (`#include`) directives) 714 * `define` (macro `#define` directives) 715 * `basetype` (built-in C language types; scalar API typedefs, such as the 716 definition of `VkFlags`; and types defined by external APIs, such as an 717 underlying OS or window system 718 * `handle` (invocations of macros defining scalar types such as 719 `VkInstance`) 720 * `enum` (enumeration types and `#define` for constant values) 721 * `group` (currently unused) 722 * `bitmask` (enumeration types whose members are bitmasks) 723 * `funcpointer` (function pointer typedefs) 724 * `struct` and `union` together (struct and union types) 725 726 727[[tag-types:example]] 728== Example of a tag:types Tag 729 730[source,xml] 731-------------------------------------- 732<types> 733 <type name="stddef">#include <stddef.h></type> 734 <type requires="stddef">typedef ptrdiff_t <name>VKlongint</name>;</type> 735 <type name="VkEnum" category="enum"/> 736 <type category="struct" name="VkStruct"> 737 <member><type>VkEnum</type> <name>srcEnum</name></member> 738 <member><type>VkEnum</type> <name>dstEnum</name></member> 739 </type> 740</types> 741 742<enums name="VkEnum" type="enum"> 743 <enum value="0" name="VK_ENUM_ZERO"/> 744 <enum value="42" name="VK_ENUM_FORTY_TWO"/> 745</enums> 746-------------------------------------- 747 748The `VkStruct` type is defined to require the types `VkEnum` and `VKlongint` 749as well. 750If `VkStruct` is in turn required by a command or another type during header 751generation, it will result in the following declarations: 752 753[source,c] 754-------------------------------------- 755#include <stddef.h> 756typedef ptrdiff_t VKlongint. 757 758typedef enum { 759 VK_ENUM_ZERO = 0, 760 VK_ENUM_FORTY_TWO = 42 761} VkEnum; 762 763typedef struct { 764 VkEnum dstEnum; 765 VkLongint dstVal; 766} VkStruct; 767-------------------------------------- 768 769Note that the angle brackets around `stddef.h` are represented as XML 770entities in the registry. 771This could also be done using a CDATA block but unless there are many 772characters requiring special representation in XML, using entities is 773preferred. 774 775 776[[tag-enums]] 777= Enumerant Blocks (tag:enums Tag) 778 779The tag:enums tags contain individual tag:enum tags describing each of the 780token names used in the API. 781In some cases these correspond to a C `enum`, and in some cases they are 782simply compile time constants (e.g. `#define`). 783 784[NOTE] 785.Note 786==== 787It would make more sense to call these `const` or `define` tags. 788This is a historical hangover from the OpenGL XML format which this schema 789was based on. 790==== 791 792 793== Attributes of tag:enums Tags 794 795 * attr:name - optional. 796 String naming the C `enum` type whose members are defined by this enum 797 group. 798 If present, this attribute should match the attr:name attribute of a 799 corresponding tag:type tag. 800 * attr:type - optional. 801 String describing the data type of the values of this group of enums. 802 At present the only accepted categories are `enum` and `bitmask`, as 803 described below. 804 * attr:comment - optional. 805 Arbitrary string (unused). 806 * attr:bitwidth - optional. 807 Bit width required for the generated enum value type. 808 If omitted, a default value of 32 is used. 809 810== Contents of tag:enums Tags 811 812Each tag:enums block contains zero or more tag:enum, tag:unused, and 813tag:comment tags, in arbitrary order (although they are typically ordered by 814sorting on enumerant values, to improve human readability). 815 816== Example of tag:enums Tags 817 818<<tag-types:example,An example>> showing a tag with attribute 819attr:type`="enum"` is given above. 820The following example is for non-enumerated tokens. 821 822[source,xml] 823-------------------------------------- 824<enums> 825 <enum value="256" name="VK_MAX_EXTENSION_NAME"/> 826 <enum value="MAX_FLOAT" name="VK_LOD_CLAMP_NONE"/> 827</enums> 828-------------------------------------- 829 830When processed into a C header, and assuming all these tokens were required, 831this results in 832 833[source,c] 834-------------------------------------- 835#define VK_MAX_EXTENSION_NAME 256 836#define VK_LOD_CLAMP_NONE MAX_FLOAT 837-------------------------------------- 838 839 840[[tag-enum]] 841= Enumerants (tag:enum Tag) 842 843Each tag:enum tag defines a single Vulkan (or other API) token. 844 845== Attributes of tag:enum Tags 846 847 * attr:value is a numeric value in the form of a legal C expression when 848 evaluated at compile time in the generated header files. 849 This is usually either a literal integer value or the name of an alias 850 for a previously defined value, though more complex expressions are 851 sometimes employed for <<compile-time-constants, compile time 852 constants>>. 853 * attr:bitpos is a literal integer bit position in a bitmask. 854 The bit position must be in the range [0,30] when used as a flag bit in 855 a `Vk*FlagBits` data type. 856 Bit positions 31 and up may be used for values that are not flag bits, 857 or for <<adding-bitflags, flag bits used with 64-bit flag types>>. 858 Exactly one of attr:value and attr:bitpos must be present in an tag:enum 859 tag. 860 * attr:name - required. 861 Enumerant name, a legal C preprocessor token name. 862 * attr:api - optional comma-separated list of <<schema:apiname, API 863 names>> for which this definition is specialized, so that different APIs 864 may have different values for the same token. 865 This definition is only used if the requested API name matches the 866 attribute. 867 May be used to address subtle incompatibilities. 868 * attr:deprecated - optional. 869 Indicates that this enum has been deprecated. 870 Possible values are: 871 ** `"true"` - deprecated, but no explanation given. 872 ** `"ignored"` - functionality described by this enum no longer operates. 873 ** `"aliased"` - an old name not following Vulkan conventions. 874 The equivalent alias following Vulkan conventions should be used 875 instead. 876 * attr:type - may be used only when attr:value is specified. 877 In this case, attr:type is optional except when defining a 878 <<compile-time-constants, compile time constant>>, in which case it is 879 required when using some output generator paths. 880 If present the attribute must be a C scalar type corresponding to the 881 type of attr:value, although only `uint32_t`, `uint64_t`, and `float` 882 are currently meaningful. 883 attr:type is used by some output generators to generate constant 884 declarations, although the default behavior is to use C `#define` for 885 compile time constants. 886 * attr:alias - optional. 887 Name of another enumerant this is an alias of, used where token names 888 have been changed as a result of profile changes or for consistency 889 purposes. 890 An enumerant alias is simply a different attr:name for the exact same 891 attr:value or attr:bitpos. 892 * attr:protect - optional. 893 An additional preprocessor token used to protect an enum definition. 894 895[NOTE] 896.Note 897==== 898Using attr:alias on a tag:enum means you want the attr:name defined by the 899tag to be treated as an alias of the token name in the attr:alias attribute 900value. 901For example, the following tag defines `VK_ALIAS` as an alias of `VK_VALUE`: 902 903[source,xml] 904-------------------------------------- 905<enum name="VK_ALIAS" alias="VK_VALUE"> 906-------------------------------------- 907==== 908 909[NOTE] 910.Note 911==== 912In older versions of the schema, attr:type was described as allowing only 913the C integer suffix types `u` and `ull`, which is inconsistent with the 914current definition. 915However, attr:type was not actually used in the registry processing scripts 916or `vk.xml` at the time the current definition was introduced, so this is 917expected to be a benign change. 918==== 919 920 921== Contents of tag:enum Tags 922 923tag:enum tags have no allowed contents. 924All information is contained in the attributes. 925 926 927[[tag-unused]] 928= Unused Enumerants (tag:unused Tag) 929 930Each tag:unused tag defines a range of enumerants which is allocated, but 931not yet assigned to specific enums. 932This just tracks the unused values for the Registrar's use, and is not used 933for header generation. 934 935[NOTE] 936.Note 937==== 938tag:unused tags could be generated and inserted automatically, which would 939be a good way to avoid the attributes becoming out of date. 940However, they are rarely used in the Vulkan XML schema, unlike the OpenGL 941XML schema it was based on. 942==== 943 944== Attributes of tag:unused Tags 945 946 * attr:start - required, attr:end - optional. 947 Integers defining the start and end of an unused range of enumerants. 948 attr:start must be {leq} attr:end. 949 If attr:end is not present, then attr:start defines a single unused 950 enumerant. 951 This range should not exceed the range reserved by the surrounding 952 tag:enums tag. 953 * attr:vendor - optional. 954 String describing the vendor or purposes to whom a reserved range of 955 enumerants is allocated. 956 Usually identical to the attr:vendor attribute of the surrounding 957 attr:enums block. 958 * attr:comment - optional. 959 Arbitrary string (unused). 960 961== Contents of tag:unused Tags 962 963None. 964 965 966[[tag-commands]] 967= Command Blocks (tag:commands Tag) 968 969The tag:commands tag contains definitions of each of the functions 970(commands) used in the API. 971 972== Attributes of tag:commands Tags 973 974 * attr:comment - optional. 975 Arbitrary string (unused). 976 977== Contents of tag:commands Tags 978 979Each tag:commands block contains zero or more tag:command tags, in arbitrary 980order (although they are typically ordered by sorting on the command name, 981to improve human readability). 982 983 984[[tag-command]] 985= Commands (tag:command Tag) 986 987The tag:command tag contains a structured definition of a single API command 988(function). 989 990== Attributes of tag:command Tags 991 992There are two ways to define a command. 993The first uses a set of attributes to the tag:command tag defining 994properties of the command used for constructing automatic validation rules, 995and the contents of the tag:command tag define the name, signature, and 996parameters of the command. 997In this case the allowed attributes include: 998 999 * attr:tasks - optional. 1000 A string identifying the tasks this command performs, as described in 1001 the "`Queue Operation`" section of the <<vulkan-spec, Vulkan API 1002 Specification>>. 1003 The format of the string is one or more of the terms `"action"`, 1004 `"synchronization"`, `"state"`, and `"indirection"`, with multiple terms 1005 separated by commas (`","`). 1006 * attr:queues - optional. 1007 A string identifying the command queues this command can be placed on. 1008 The format of the string is one or more of the terms `"compute"`, 1009 `"decode"`, `"encode"`, `"graphics"`, `"transfer"`, `"sparse_binding"`, 1010 and `"opticalflow"`, with multiple terms separated by commas (`","`). 1011 * attr:successcodes - optional. 1012 A string describing possible successful return codes from the command, 1013 as a comma-separated list of Vulkan result code names. 1014 * attr:errorcodes - optional. 1015 A string describing possible error return codes from the command, as a 1016 comma-separated list of Vulkan result code names. 1017 * attr:renderpass - optional. 1018 A string identifying whether the command can be issued only inside a 1019 render pass (`"inside"`), only outside a render pass (`"outside"`), or 1020 both (`"both"`). 1021 * attr:videocoding - optional. 1022 A string identifying whether the command can be issued only inside a 1023 video coding scope (`"inside"`), only outside a video coding scope 1024 (`"outside"`), or both (`"both"`); the default is `"outside"` for 1025 commands that do not specify it. 1026 * attr:cmdbufferlevel - optional. 1027 A string identifying the command buffer levels that this command can be 1028 called by. 1029 The format of the string is one or more of the terms `"primary"` and 1030 `"secondary"`, with multiple terms separated by commas (`","`). 1031 * attr:comment - optional. 1032 Arbitrary string (unused). 1033 1034The second way of defining a command is as an alias of another command. 1035For example when an extension is promoted from extension to core status, the 1036commands defined by that extensions become aliases of the corresponding new 1037core commands. 1038In this case, only two attributes are allowed: 1039 1040 * attr:name - required. 1041 A string naming the command defined by the tag. 1042 * attr:alias - required. 1043 A string naming the command that attr:name is an alias of. 1044 The string must be the same as the attr:name value of another 1045 tag:command defining another command. 1046 1047Both forms of tag:command support these options: 1048 1049 * attr:api - optional <<schema:apiname, API names>> for which this 1050 definition is specialized, so that different APIs may have different 1051 values for the same token. 1052 This definition is only used if the requested API name matches the 1053 attribute. 1054 May be used to address subtle incompatibilities. 1055 1056== Contents of tag:command Tags 1057 1058 * tag:proto is required and must be the first element. 1059 It is a tag defining the C function prototype of a command as described 1060 below, up to the function name and return type but not including 1061 function parameters. 1062 * tag:param elements for each command parameter follow, defining its name 1063 and type, as described below. 1064 If a command takes no arguments, it has no tag:param tags. 1065 1066Following these elements, the remaining elements in a tag:command tag are 1067optional and may be in any order: 1068 1069 * tag:alias - optional. 1070 Has no attributes and contains a string which is the name of another 1071 command this command is an alias of, used when promoting a function from 1072 vendor to Khronos extension or Khronos extension to core API status. 1073 A command alias describes the case where there are two function names 1074 which implement the same behavior. 1075 * tag:description - optional. 1076 Unused text. 1077 * tag:implicitexternsyncparams - optional. 1078 Contains a list of tag:param tags, each containing asciidoc source text 1079 describing an object which is not a parameter of the command but is 1080 related to one, and which also <<tag-command:param:attr,requires 1081 external synchronization>>. 1082 The text is intended to be incorporated into the API specification. 1083 1084[NOTE] 1085.Note 1086==== 1087Versions of the registry documentation prior to 1.1.93 asserted that command 1088aliases "`resolve to the _same_ entry point in the underlying layer stack.`" 1089Whilst this may be true on many implementations, it is not required - each 1090command alias must be queried separately through `vkGetInstanceProcAddr` 1091or `vkGetDeviceProcAddr`. 1092==== 1093 1094 1095[[tag-command:proto]] 1096== Command Prototype (tag:proto Tags) 1097 1098The tag:proto tag defines the return type and name of a command. 1099 1100=== Attributes of tag:proto Tags 1101 1102None. 1103 1104// attr:group - group name, an arbitrary string. 1105// 1106// If the group name is defined, it may be interpreted as described in 1107// <<tag-group:meaning>>. 1108 1109=== Contents of tag:proto Tags 1110 1111The text elements of a tag:proto tag, with all other tags removed, is legal 1112C code describing the return type and name of a command. 1113In addition to text, it may contain two semantic tags: 1114 1115 * The tag:type tag is optional, and contains text which is a valid type 1116 name found in a tag:type tag. 1117 It indicates that this type must be previously defined for the 1118 definition of the command to succeed. 1119 Builtin C types, and any derived types which are expected to be found in 1120 other header files, should not be wrapped in tag:type tags. 1121 * The tag:name tag is required, and contains the command name being 1122 described. 1123 1124 1125[[tag-command:param]] 1126== Command Parameter (tag:param Tags) 1127 1128The tag:param tag defines the type and name of a parameter. 1129Its contents are very similar to the tag:member tag used to define struct 1130and union members. 1131 1132 1133[[tag-command:param:attr]] 1134=== Attributes of tag:param Tags 1135 1136 * attr:api - optional <<schema:apiname, API names>> for which this 1137 definition is specialized, so that different APIs may have different 1138 definitions for the same type. 1139 This definition is only used if the requested API name matches the 1140 attribute. 1141 May be used to address subtle incompatibilities. 1142 * attr:len - if the param is an array, len may be one or more of the 1143 following things, separated by commas (one for each array indirection): 1144 another param of that command; `"null-terminated"` for a string; `"1"` 1145 to indicate it is just a pointer (used for nested pointers); or an 1146 equation in math markup for incorporation in the specification (a LaTeX 1147 math expression delimited by `latexmath:[` and `]`. 1148 The only variables in the equation should be the names of this or other 1149 parameters. 1150 * attr:altlen - if the attr:len attribute is specified, and contains a 1151 `latexmath:` equation, this attribute should be specified with an 1152 equivalent equation using only C builtin operators, C math library 1153 function names, and variables as allowed for attr:len. 1154 It must be a valid C99 expression whose result is equal to attr:len for 1155 all possible inputs. 1156 It is a comma separated list that has size equal to only the `latexmath` 1157 item count in attr:len list. 1158 This attribute is intended to support consumers of the XML who need to 1159 generate validation code from the allowed length. 1160 * attr:optional - optional. 1161 A value of `"true"` specifies that this parameter can be omitted by 1162 providing `NULL` (for pointers), `VK_NULL_HANDLE` (for handles), or 0 1163 (for other scalar types). 1164 If not present, the value is assumed to be `"false"` (the parameter must 1165 not be omitted). 1166 If the parameter is a pointer to one of those types, multiple values may 1167 be provided, separated by commas - one for each pointer indirection. 1168+ 1169-- 1170[NOTE] 1171.Note 1172==== 1173While the attr:optional attribute can be used for scalar types such as 1174integers, it does not affect the output generators included with the 1175<<vulkan-spec, Vulkan API Specification>>. 1176In this case, the attribute serves only as an indicator to human readers of 1177the XML. 1178 1179Explicitly specifying `optional="false"` is not supported, but 1180`optional="false,true"` is supported for a pointer type. 1181==== 1182-- 1183 * attr:selector - optional. 1184 If the parameter is a union, attr:selector identifies another parameter 1185 of the command that is used to select which of that union's members are 1186 valid. 1187 * attr:noautovalidity - prevents automatic validity language being 1188 generated for the tagged item. 1189 Only suppresses item-specific validity - parenting issues etc. 1190 are still captured. 1191 * attr:externsync - optional. 1192 A value of `"true"` indicates that this parameter (e.g. the object a 1193 handle refers to, or the contents of an array a pointer refers to) is 1194 modified by the command, and is not protected against modification in 1195 multiple app threads. 1196 If only certain members of an object or elements of an array are 1197 modified, multiple strings may be provided, separated by commas. 1198 Each string describes a member which is modified. 1199 For example, the `VkPresentInfoKHR` struct includes attr:externsync 1200 attributes for the `pPresentInfo` array indicating that only specific 1201 members of each element of the array are modified: 1202+ 1203-- 1204[source,xml] 1205-------------------------------------- 1206<param externsync="pPresentInfo->pWaitSemaphores[],pPresentInfo->pSwapchains[]">const <type>VkPresentInfoKHR</type>* <name>pPresentInfo</name></param> 1207-------------------------------------- 1208 1209Parameters which do not have an attr:externsync attribute are assumed to not 1210require external synchronization. 1211-- 1212 * attr:objecttype - only applicable for parameters which are `uint64_t` 1213 values representing a Vulkan object handle. 1214 Specifies the name of another parameter which must be a `VkObjectType` 1215 or `VkDebugReportObjectTypeEXT` value specifying the type of object the 1216 handle refers to. 1217 * attr:validstructs - optional. 1218 Allowed only when the parameter type is a pointer to an abstract 1219 `VkBaseInStructure` or `VkBaseOutStructure` type. 1220 This is a comma-separated list of structures which can either be 1221 passed as the parameter, or can appear anywhere in the `pNext` chain of 1222 the parameter. 1223 1224 1225=== Contents of tag:param Tags 1226 1227The text elements of a tag:param tag, with all other tags removed, is legal 1228C code describing the type and name of a function parameter. 1229In addition it may contain two semantic tags: 1230 1231 * The tag:type tag is optional, and contains text which is a valid type 1232 name found in tag:type tag, and indicates that this type must be 1233 previously defined for the definition of the command to succeed. 1234 Builtin C types, and any derived types which are expected to be found in 1235 other header files, should not be wrapped in tag:type tags. 1236 * The tag:name tag is required, and contains the parameter name being 1237 described. 1238 1239== Example of a tag:commands Tag 1240 1241[source,xml] 1242-------------------------------------- 1243<commands> 1244 <command> 1245 <proto><type>VkResult</type> <name>vkCreateInstance</name></proto> 1246 <param>const <type>VkInstanceCreateInfo</type>* <name>pCreateInfo</name></param> 1247 <param><type>VkInstance</type>* <name>pInstance</name></param> 1248 </command> 1249</commands> 1250-------------------------------------- 1251 1252When processed into a C header, this results in 1253 1254[source,c] 1255-------------------------------------- 1256VkResult vkCreateInstance( 1257 const VkInstanceCreateInfo* pCreateInfo, 1258 VkInstance* pInstance); 1259-------------------------------------- 1260 1261 1262[[tag-feature]] 1263= API Features and Versions (tag:feature Tag) 1264 1265API features are described in individual tag:feature tags. 1266A feature is the set of interfaces (enumerants and commands) defined by a 1267particular API and version, such as Vulkan 1.0, and includes all profiles of 1268that API and version. 1269 1270== Attributes of tag:feature Tags 1271 1272 * attr:api - required comma-separated list of <<schema:apiname, API 1273 names>> for which this feature is defined, such as `vulkan`. 1274 * attr:name - required. 1275 Version name, used as the C preprocessor token under which the version's 1276 interfaces are protected against multiple inclusion. 1277 Example: `"VK_VERSION_1_0"`. 1278 * attr:number - required. 1279 Feature version number, usually a string interpreted as 1280 `majorNumber.minorNumber`. 1281 Example: `4.2`. 1282 * attr:sortorder - optional. 1283 A decimal number which specifies an order relative to other tag:feature 1284 tags when calling output generators. 1285 Defaults to `0`. 1286 Rarely used, for when ordering by attr:name is insufficient. 1287 * attr:protect - optional. 1288 An additional preprocessor token used to protect a feature definition. 1289 Usually another feature or extension attr:name. 1290 Rarely used, for odd circumstances where the definition of a feature or 1291 extension requires another to be defined first. 1292 * attr:comment - optional. 1293 Arbitrary string (unused). 1294 1295[NOTE] 1296.Note 1297==== 1298The attr:name attribute used for Vulkan core versions, such as 1299`"VK_VERSION_1_0"`, is not an API construct. 1300It is used only as a preprocessor guard in the headers, and an asciidoctor 1301conditional in the specification sources. 1302The similar `"VK_API_VERSION_1_0"` symbols are part of the API and their 1303values are packed integers containing Vulkan core version numbers. 1304==== 1305 1306== Contents of tag:feature Tags 1307 1308Zero or more <<tag-required,tag:require and tag:remove tags>>, in arbitrary 1309order. 1310Each tag describes a set of interfaces that is respectively required for, or 1311removed from, this feature, as described below. 1312 1313== Example of a tag:feature Tag 1314 1315[source,xml] 1316-------------------------------------- 1317<feature api="vulkan" name="VK_VERSION_1_0" number="1.0"> 1318 <require comment="Header boilerplate"> 1319 <type name="vk_platform"/> 1320 </require> 1321 <require comment="API constants"> 1322 <enum name="VK_MAX_PHYSICAL_DEVICE_NAME"/> 1323 <enum name="VK_LOD_CLAMP_NONE"/> 1324 </require> 1325 <require comment="Device initialization"> 1326 <command name="vkCreateInstance"/> 1327 </require> 1328</feature> 1329-------------------------------------- 1330 1331When processed into a C header for Vulkan, this results in: 1332 1333[source,c] 1334-------------------------------------- 1335#ifndef VK_VERSION_1_0 1336#define VK_VERSION_1_0 1 1337#define VK_MAX_EXTENSION_NAME 256 1338#define VK_LOD_CLAMP_NONE MAX_FLOAT 1339typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)(const VkInstanceCreateInfo* pCreateInfo, VkInstance* pInstance); 1340#ifndef VK_NO_PROTOTYPES 1341VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance( 1342 const VkInstanceCreateInfo* pCreateInfo, 1343 VkInstance* pInstance); 1344#endif 1345#endif /* VK_VERSION_1_0 */ 1346-------------------------------------- 1347 1348 1349[[tag-extensions]] 1350= Extension Blocks (tag:extensions Tag) 1351 1352The tag:extensions tag contains definitions of each of the extensions which 1353are defined for the API. 1354 1355== Attributes of tag:extensions Tags 1356 1357 * attr:comment - optional. 1358 Arbitrary string (unused). 1359 1360== Contents of tag:extensions Tags 1361 1362Each tag:extensions block contains zero or more tag:extension tags, each 1363describing an API extension, in arbitrary order (although they are typically 1364ordered by sorting on the extension name, to improve human readability). 1365 1366 1367[[tag-extension]] 1368= API Extensions (tag:extension Tag) 1369 1370API extensions are described in individual tag:extension tags. 1371An extension is the set of interfaces defined by a particular API extension 1372specification, such as `ARB_multitexture`. 1373tag:extension is similar to tag:feature, but instead of having an 1374attr:number attribute, it instead has a attr:supported attribute, which 1375describes the set of API names which the extension can potentially be 1376implemented against. 1377 1378== Attributes of tag:extension Tags 1379 1380 * attr:name - required. 1381 Extension name, following the conventions in the <<vulkan-spec, Vulkan 1382 API Specification>>. 1383 Example: `name="VK_VERSION_1_0"`. 1384 * attr:number - required. 1385 A decimal number which is the registered, unique extension number for 1386 attr:name. 1387 * attr:sortorder - optional. 1388 A decimal number which specifies an order relative to other 1389 tag:extension tags when calling output generators. 1390 Defaults to `0`. 1391 Rarely used, for when ordering by attr:number is insufficient. 1392 * attr:author - optional. 1393 The author name, such as a full company name. 1394 If not present, this can be taken from the corresponding tag:tag 1395 attribute. 1396 However, `EXT` and other multi-vendor extensions may not have a 1397 well-defined author or contact in the tag. 1398 This attribute is not used in processing the XML. 1399 It is just metadata, mostly used to track the original author of an 1400 extension (which may have since been promoted to use a different author 1401 ID). 1402 * attr:contact - optional. 1403 The contact who registered or is currently responsible for extensions 1404 and layers using the tag, including sufficient contact information to 1405 reach the contact such as individual name together with GitHub username 1406 (`@username`), Khronos internal Gitlab username (`gitlab:@username`) if 1407 no public GitHub contact is available, or other contact information. 1408 If not present, this can be taken from the corresponding tag:tag 1409 attribute just like attr:author. 1410 * attr:type - required if the attr:supported attribute is not 1411 `'disabled'`. 1412 Must be either `'device'` or `'instance'`, if present. 1413 * [[depends-expressions]] attr:depends - optional. 1414 String containing a boolean expression of one or more API core version 1415 and extension names. 1416 The extension requires the expression in the string to be satisfied to 1417 use any functionality it defines (for instance extensions), or to use 1418 any device-level functionality it provides (for device extensions). 1419 Supported operators include `,` for logical OR, `+` for logical AND, and 1420 `(` `)` for grouping. 1421 `,` and `+` are of equal precedence, and lower than `(` `)`. 1422 Expressions must be evaluated left-to-right for operators of the same 1423 precedence. 1424 Terms which are core version names are true if the corresponding 1425 API version is supported. 1426 Terms which are extension names are true if the corresponding extension 1427 is enabled. 1428+ 1429-- 1430[NOTE] 1431.Note 1432==== 1433attr:depends is a breaking change in Vulkan 1.3.241, replacing the 1434`requires` and `requiresCore` attributes. 1435For example, an extension which previously specified these two attributes in 1436`vk.xml`: 1437 1438* `requires="VK_KHR_dep_a,VK_EXT_dep_b"` 1439* `requiresCore="1.1"` 1440 1441should replace them both with 1442 1443* `depends="VK_VERSION_1_1+VK_KHR_dep_a+VK_EXT_dep_b"` 1444 1445Note that the use of `,` in the old `requires` attribute was treated as a 1446logical AND, and must be replaced by `+` in the `depends` attribute. 1447==== 1448-- 1449 * attr:protect - optional. 1450 An additional preprocessor token used to protect an extension 1451 definition. 1452 Usually another feature or extension attr:name. 1453 Rarely used, for odd circumstances where the definition of an extension 1454 requires another extension or a header file to be defined first. 1455 * attr:platform - optional. 1456 Indicates that the extension is specific to the platform identified by 1457 the attribute value, and should be emitted conditional on that platform 1458 being available, in a platform-specific header, etc. 1459 The attribute value must be the same as one of the tag:platform tag:name 1460 attribute values. 1461 * attr:supported - comma-separated list of required <<schema:apiname, API 1462 names>> for which this extension is defined. 1463 When the extension tag is just reserving an extension number, use 1464 `supported="disabled"` to indicate this extension should never be 1465 processed. 1466 Interfaces defined in a `disabled` extension block are tentative at best 1467 and must: not be generated or otherwise used by scripts processing the 1468 XML. 1469 The only exception to this rule is for scripts used solely for 1470 reserving, or checking for reserved bitflag values. 1471 * attr:ratified - optional comma-separated list of <<scheme:apiname, API 1472 names>> for which this extension has been ratified by the Khronos Board 1473 of Promoters. 1474 Defaults to the empty string if not specified. 1475 * attr:promotedto - optional. 1476 A Vulkan version or a name of an extension that this extension was 1477 _promoted_ to. 1478 E.g. `"VK_VERSION_1_1"`, or `"VK_KHR_draw_indirect_count"`. 1479 As discussed in the "`Extending Vulkan`" chapter of the <<vulkan-spec, 1480 Vulkan API Specification>>, the `promotedto` relationship is not a 1481 promise of exact API-level compatibility, and replacing use of one 1482 interface with the other must not be done purely mechanically. 1483 * attr:deprecatedby - optional. 1484 A Vulkan version or a name of an extension that _deprecates_ this 1485 extension. 1486 It may be an empty string. 1487 E.g. `"VK_VERSION_1_1"`, or `"VK_EXT_debug_utils"`, or `""`. 1488 * attr:obsoletedby - optional. 1489 A Vulkan version or a name of an extension that _obsoletes_ this 1490 extension. 1491 It may be an empty string. 1492 E.g. `"VK_VERSION_1_1"`, or `"VK_KHR_maintenance1"`, or `""`. 1493 * attr:provisional - optional. 1494 `"true"` if this extension is released provisionally. 1495 Defaults to `"false"` if not specified. 1496 * attr:specialuse - optional. 1497 If present, must contain one or more tokens separated by commas, 1498 indicating a special purpose of the extension. 1499 Tokens may include: 1500 ** 'cadsupport' - for support of CAD software. 1501 ** 'd3demulation' - for support of Direct3D emulation layers or libraries, 1502 or applications porting from Direct3D. 1503 ** 'debugging' - for debugging an application. 1504 ** 'devtools' - for support of developer tools, such as capture-replay 1505 libraries. 1506 ** 'glemulation' - for support of OpenGL and/or OpenGL ES emulation layers 1507 or libraries, or applications porting from those APIs. 1508 * attr:comment - optional. 1509 Arbitrary string (unused). 1510 1511[NOTE] 1512.Note 1513==== 1514The attr:depends attribute is used to specify other extensions that *must* 1515be enabled for an extension to be enabled. 1516 1517In some cases, an extension may include functionality which is only defined 1518*if* another extension is enabled. 1519Such functionality should be specified within a tag:require tag, using the 1520attr:depends attribute to specify that extension. 1521==== 1522 1523== Contents of tag:extension Tags 1524 1525Zero or more <<tag-required,tag:require and tag:remove tags>>, in arbitrary 1526order. 1527Each tag describes a set of interfaces that is respectively required for, or 1528removed from, this extension, as described below. 1529 1530== Example of an tag:extensions Tag 1531 1532[source,xml] 1533-------------------------------------- 1534<extension name="VK_KHR_display_swapchain" number="4" supported="vulkan"> 1535 <require> 1536 <enum value="9" name="VK_KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION"/> 1537 <enum value="4" name="VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NUMBER"/> 1538 <enum value=""VK_KHR_display_swapchain"" 1539 name="VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME"/> 1540 <type name="VkDisplayPresentInfoKHR"/> 1541 <command name="vkCreateSharedSwapchainsKHR"/> 1542 </require> 1543</extension> 1544-------------------------------------- 1545 1546The attr:supported attribute says that the extension is defined for the 1547default profile (`vulkan`). 1548When processed into a C header for the `vulkan` profile, this results in 1549header contents something like (assuming corresponding definitions of the 1550specified tag:type and tag:command elsewhere in the XML): 1551 1552[source,c] 1553-------------------------------------- 1554#define VK_KHR_display_swapchain 1 1555#define VK_KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION 9 1556#define VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NUMBER 4 1557#define VK_KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME "VK_KHR_display_swapchain" 1558 1559typedef struct VkDisplayPresentInfoKHR { 1560 VkStructureType sType; 1561 const void* pNext; 1562 VkRect2D srcRect; 1563 VkRect2D dstRect; 1564 VkBool32 persistent; 1565} VkDisplayPresentInfoKHR; 1566 1567typedef VkResult (VKAPI_PTR *PFN_vkCreateSharedSwapchainsKHR)( 1568 VkDevice device, uint32_t swapchainCount, 1569 const VkSwapchainCreateInfoKHR* pCreateInfos, 1570 const VkAllocationCallbacks* pAllocator, 1571 VkSwapchainKHR* pSwapchains); 1572 1573#ifndef VK_NO_PROTOTYPES 1574VKAPI_ATTR VkResult VKAPI_CALL vkCreateSharedSwapchainsKHR( 1575 VkDevice device, 1576 uint32_t swapchainCount, 1577 const VkSwapchainCreateInfoKHR* pCreateInfos, 1578 const VkAllocationCallbacks* pAllocator, 1579 VkSwapchainKHR* pSwapchains); 1580#endif 1581-------------------------------------- 1582 1583 1584[[tag-required]] 1585= Required and Removed Interfaces (tag:require and tag:remove Tags) 1586 1587A tag:require block defines a set of interfaces (types, enumerants and 1588commands) 'required' by a tag:feature or tag:extension. 1589A tag:remove block defines a set of interfaces 'removed' by a tag:feature. 1590This is primarily for future profiles of an API which may choose to 1591deprecate and/or remove some interfaces. 1592Extensions should never remove interfaces, although this usage is allowed by 1593the schema). 1594Except for the tag name and behavior, the contents of tag:require and 1595tag:remove tags are identical. 1596 1597== Attributes of tag:require and tag:remove Tags 1598 1599 * attr:profile - optional. 1600 String name of an API profile. 1601 Interfaces in the tag are only required (or removed) if the specified 1602 profile is being generated. 1603 If not specified, interfaces are required (or removed) for all API 1604 profiles. 1605 * attr:comment - optional. 1606 Arbitrary string (unused). 1607 * attr:api - optional comma-separated list of <<schema:apiname, API 1608 names>> requiring or removing these interfaces. 1609 Interfaces in the tag are only required (or removed) if the requested 1610 API name matches an element of the attribute. 1611 If not specified, interfaces are required (or removed) for all APIs. 1612 1613[NOTE] 1614.Note 1615==== 1616The attr:api attribute is only supported inside tag:extension tags, since 1617tag:feature tags already define a specific API. 1618==== 1619 1620== Attributes of tag:require Tags 1621 1622These attributes are allowed only for a tag:require tag. 1623 1624 * attr:depends - optional, and only for tag:require tags. 1625 String containing a boolean expression of one or more API core version 1626 and extension names. 1627 The <<depends-expressions, syntax of this string>> is identical to that 1628 of the tag:extension attr:depends attribute. 1629 Interfaces in the tag are only required if the expression is satisfied. 1630+ 1631-- 1632[NOTE] 1633.Note 1634==== 1635attr:depends is a breaking change in Vulkan 1.3.241, replacing the 1636`extension` and `feature` attributes. 1637==== 1638-- 1639 1640== Contents of tag:require and tag:remove Tags 1641 1642Zero or more of the following tags, in any order: 1643 1644=== Comment Tags 1645 1646<<tag-comment, tag:comment>> (as described above). 1647 1648=== Command Tags 1649 1650tag:command specifies an required (or removed) command defined in a 1651tag:commands block. 1652The tag has no content, but contains attributes: 1653 1654 * attr:name - required. 1655 Name of the command. 1656 * attr:comment - optional. 1657 Arbitrary string (unused). 1658 1659=== Enum Tags 1660 1661tag:enum specifies an required (or removed) enumerant defined in a tag:enums 1662block. 1663All forms of this tag support the following attributes: 1664 1665 * attr:name - required. 1666 Name of the enumerant. 1667 * attr:comment - optional. 1668 Arbitrary string (unused). 1669 * attr:api - optional comma-separated list of <<schema:apiname, API 1670 names>> for which this definition is specialized, so that different APIs 1671 may have different values for the same token. 1672 This definition is only used if the requested API name matches the 1673 attribute. 1674 May be used to address subtle incompatibilities. 1675 1676There are two forms of tag:enum tags: 1677 1678_Reference enums_ simply pull in the definition of an enumerant given in a 1679separate tag:enums block. 1680No attributes other than attr:name and attr:comment are supported for them. 1681tag:enum tags appearing inside tag:remove tags should always be reference 1682enums. 1683Reference enums may also be used inside tag:require tags, if the 1684corresponding value is defined in a tag:enums block. 1685This is typically used for constants not part of an enumerated type. 1686 1687_Extension enums_ define the value of an enumerant inline in an tag:feature 1688or tag:extensions block. 1689Typically these are used to add additional values specified by an extension 1690or core feature to an existing enumerated type. 1691There are a variety of attributes which are used to specify the value of the 1692enumerant: 1693 1694 * attr:value and attr:type - define a constant value in the same fashion 1695 as an tag:enum tag in an <<tag-enum,tag:enums>> block. 1696 * attr:bitpos - define a constant bitmask value in the same fashion as an 1697 <<tag-enum,tag:enum>> tag in an tag:enums block. 1698 attr:bitpos is a literal integer bit position in a bitmask. 1699 The same value and usage constraints apply to this bit position as are 1700 applied to the <<tag-enum, attr:bitpos attribute of an tag:enum tag. 1701 * attr:extends - the name of a separately defined enumerated type (e.g. a 1702 tag:type tag with attr:category``="enum"``) to which the extension 1703 enumerant is added. 1704 The enumerated type is required to complete the definition of the 1705 enumerant, in the same fashion as the attr:requires attribute of a 1706 tag:type tag. 1707 If not present, the enumerant is treated as a global constant value. 1708 * attr:extnumber - an extension number. 1709 The extension number in turn specifies the starting value of a block 1710 (range) of values reserved for enumerants defined by or associated with 1711 the corresponding tag:extension tag with the same attr:number. 1712 This is used when an extension or core feature needs to extend an 1713 enumerated type in a block defined by a different extension. 1714 * Attribute attr:offset - the offset within an extension block. 1715 If attr:extnumber is not present, the extension number defining that 1716 block is given by the attr:number attribute of the surrounding 1717 tag:extension tag. 1718 The numeric value of an enumerant is computed as defined in the 1719 ``Assigning Extension Token Values`" section of the <<vulkan-styleguide, 1720 Vulkan Documentation and Extensions: Procedures and Conventions>> 1721 document. 1722 * Attribute attr:dir - if present, the calculated enumerant value will be 1723 negative, instead of positive. 1724 Negative enumerant values are normally used only for Vulkan error codes. 1725 The attribute value must be specified as `dir="-"`. 1726 * attr:alias - the name of another enumerant this is an alias of. 1727 An enumerant alias is simply a different name for the same enumerant 1728 value. 1729 This is typically used when promoting an enumerant defined by an 1730 extension to a new core version of the API. 1731 The old extension enumerant is still defined, but as an alias of the new 1732 core enumerant. 1733 It may also be used when token names have been changed as a result of 1734 profile changes, or for consistency purposes. 1735 * attr:protect - define a preprocessor protection symbol for the enum in 1736 the same fashion as a tag:enum tag in an <<tag-enum,tag:enums>> block. 1737 1738Not all combinations of attributes are either meaningful or supported. 1739The attr:protect attribute may always be present. 1740For other attributes, the allowed combinations are: 1741 1742.Valid Combinations of attr:enum Attributes for Extension Enums 1743|==== 1744| Description | attr:value | attr:bitpos | attr:alias | attr:offset | attr:extnumber | attr:dir | attr:extends 1745| Numeric value | *Yes* | No | No | No | No | No | *Yes*^2^ 1746| Bitmask value | No | *Yes* | No | No | No | No | *Yes*^2^ 1747| Alias of another enumerant | No | No | *Yes* | No | No | No | *Yes*^2^ 1748| Value added to an enumeration | No | No | No | *Yes* | *Yes*^1^ | *Yes*^3^ | *Yes* 1749|==== 1750 1751[1]: Optional. 1752If attr:extnumber is not present, the tag:enum tag may only be within a 1753tag:extension. 1754Otherwise, the tag:enum tag may also be within a tag:feature. 1755 1756[2]: Optional. 1757If attr:extends is not present, the enumerant value is a global constant. 1758Otherwise, the value is added to the specified enumeration. 1759 1760[3]: Optional. 1761If not present, the computed value will be positive. 1762 1763Examples of <<tag-required-examples,various types of extension enumerants>> 1764are given below. 1765 1766 1767=== Type Tags 1768 1769tag:type specifies a required (or removed) type defined in a tag:types 1770block. 1771Most types are picked up implicitly by using the tag:type tags of commands, 1772but in a few cases, additional types need to be specified explicitly. 1773It is unlikely that a type would ever be removed, although this usage is 1774allowed by the schema. 1775The tag has no content, but contains elements: 1776 1777 * attr:name - required. 1778 Name of the type. 1779 * attr:comment - optional. 1780 Arbitrary string (unused). 1781 1782 1783[[tag-required-examples]] 1784== Examples of Extension Enumerants 1785 1786Examples of some of the supported extension enumerant tag:enum tags are 1787given below. 1788 1789[source,xml] 1790-------------------------------------- 1791<extensions> 1792 <extension name="VK_KHR_test_extension" number="1" supported="vulkan"> 1793 <require> 1794 <enum value="42" name="VK_KHR_TEST_ANSWER"/> 1795 <enum bitpos="29" name="VK_KHR_TEST_BITMASK"/> 1796 <enum offset="0" dir="-" extends="VkResult" 1797 name="VK_ERROR_SURFACE_LOST_KHR"/> 1798 <enum offset="1" extends="VkResult" 1799 name="VK_SUBOPTIMAL_KHR"/> 1800 <enum bitpos="30" extends="VkCullModeFlagBits" 1801 name="VK_KHR_TEST_CULL_MODE_BIT"/> 1802 </require> 1803 </extension> 1804</extensions> 1805-------------------------------------- 1806 1807The corresponding header file will include definitions like this: 1808 1809[source,c] 1810-------------------------------------- 1811typedef enum VkResult { 1812 <previously defined VkResult enumerant values}, 1813 VK_ERROR_SURFACE_LOST_KHR = -1000000000, 1814 VK_SUBOPTIMAL_KHR = 1000000001, 1815 VK_KHR_EXTENSION_BIT = 0x80000000, 1816}; 1817 1818#define VK_KHR_test_extension 1 1819#define VK_KHR_theanswer 42 1820#define VK_KHR_bitmask 0x20000000 1821-------------------------------------- 1822 1823 1824[[tag-formats]] 1825= Formats (tag:formats Tag) 1826 1827The tag:formats tag contains definitions of each of the image formats which 1828are defined for the API. 1829 1830== Attributes of tag:formats Tags 1831 1832None. 1833 1834// * attr:comment - optional. 1835// Arbitrary string (unused). 1836 1837== Contents of tag:formats Tags 1838 1839A tag:formats block contains zero or more tag:format tags, each describing 1840an image format, in arbitrary order. 1841 1842 1843[[tag-format]] 1844= Image Format (tag:format Tag) 1845 1846Image formats are described in individual tag:format tags. 1847An image format corresponds to a Vulkan `VkFormat` enumerant. 1848This tag contains information specifying the structure and meaning of 1849different parts of the format. 1850The meaning of different parts of the format information is described in 1851more detail in the "`Format Definition`" section of the <<vulkan-spec, 1852Vulkan API Specification>>. 1853 1854== Attributes of tag:format Tags 1855 1856 * attr:name - required. 1857 Format name, matching a `VkFormat` tag:enum attr:name. 1858 Example: `name="VK_FORMAT_R8_UNORM"`. 1859 * attr:class - required. 1860 Format class. 1861 A string whose value is shared by a group of formats which may be 1862 compatible, and is a textual description of something important that 1863 group has in common. 1864 Example: `class="8-bit"`. 1865 * attr:blockSize - required. 1866 A decimal integer which is the texel block size, in bytes, of the 1867 format. 1868 * attr:texelsPerBlock - required 1869 A decimal integer which is the number of texels in a texel block of the 1870 format. 1871 * attr:blockExtent - optional. 1872 Three-dimensional extent of a texel block. 1873 A comma-separated list of three decimal integers. 1874 If not present, `blockExtent="1,1,1"` is assumed. 1875 * attr:packed - optional. 1876 A decimal integer which is the number of bits into which the format is 1877 packed. 1878 If defined, a single image element in this format can be stored in the 1879 same space as a scalar type of this bit width. 1880 * attr:compressed - optional. 1881 A string whose value is shared by a group of formats which use the same 1882 general texture compression scheme, and is a textual description of that 1883 scheme. 1884 Example: `compressed="ASTC LDR"`. 1885 * attr:chroma - optional. 1886 A string used to mark if {YCbCr} samplers are required by default when 1887 using this format. 1888 Must be one of the three values `"420"`, `"422"`, or `"444"` 1889 corresponding to different {YCbCr} encodings. 1890 1891== Contents of tag:format Tags 1892 1893One or more <<tag-component,tag:component>> tags. 1894The order of tag:component tags corresponds to the memory order of 1895components of the format. 1896Each tag describes the size and format of that component. 1897 1898Zero or more <<tag-plane,tag:plane>> tags, in arbitrary order. 1899Each tag describes the scale of a specific image plane of the format 1900relative to the overall format. 1901 1902Zero or more <<tag-spirvimageformat,tag:spirvimageformat>> tags, in 1903arbitrary order. 1904Each tag describes a SPIR-V format name corresponding to the tag:format. 1905 1906== Example of a tag:format Tag 1907 1908[source,xml] 1909-------------------------------------- 1910<format name="VK_FORMAT_G16_B16R16_2PLANE_420_UNORM" class="16-bit 2-plane 420" blockSize="6" texelsPerBlock="1" chroma="420"> 1911 <component name="G" bits="16" numericFormat="UNORM" planeIndex="0"/> 1912 <component name="B" bits="16" numericFormat="UNORM" planeIndex="1"/> 1913 <component name="R" bits="16" numericFormat="UNORM" planeIndex="1"/> 1914 <plane index="0" widthDivisor="1" heightDivisor="1" compatible="VK_FORMAT_R16_UNORM"/> 1915 <plane index="1" widthDivisor="2" heightDivisor="2" compatible="VK_FORMAT_R16G16_UNORM"/> 1916</format> 1917-------------------------------------- 1918 1919 1920[[tag-component]] 1921= Format Components (tag:component Tag) 1922 1923The tag:component tag contains definitions of each of the components which 1924are part of an image format. 1925 1926== Attributes of tag:component Tags 1927 1928 * attr:name - required. 1929 A string specifying the name of this component. 1930 Must be one of the values `"R"`, `"G"`, `"B"`, `"A"`, `"D"`, or `"S"` 1931 corresponding to red, green, blue, alpha, depth, and stencil components, 1932 respectively. 1933 * attr:bits - required. 1934 Must be either a decimal integer which is the number of bits in this 1935 component, or `"compressed"`, corresponding to a specific compression 1936 scheme. 1937 * attr:numericFormat - required. 1938 A string specifying the scalar data type of the component. 1939 Must be one of the following values: 1940 ** `"SFLOAT"` - signed floating-point numbers 1941 ** `"SINT"` - signed integer values in the range [-2^n-1^,2^n-1^-1] 1942 ** `"SNORM"` - signed normalized values in the range [-1,1] 1943 ** `"SRGB"` - R, G, and B components are unsigned normalized values that represent values using sRGB nonlinear encoding, while the A component (if one exists) is a regular unsigned normalized value 1944 ** `"SSCALED"` - signed integer values that get converted to floating-point in the range [-2^n-1^,2^n-1^-1] 1945 ** `"UFLOAT"` - unsigned floating-point numbers (used by packed, shared exponent, and some compressed formats) 1946 ** `"UINT"` - unsigned integer values in the range [0,2^n^-1] 1947 ** `"UNORM"` - unsigned normalized values in the range [0,1] 1948 ** `"USCALED"` - unsigned integer values that get converted to floating-point in the range [0,2^n^-1] 1949 * attr:planeIndex - optional. 1950 A decimal integer specifying which plane this component lies in. 1951 If present, must correspond to the attr:index attribute value of a 1952 tag:plane tag for the same tag:component. 1953 1954== Contents of tag:component Tags 1955 1956None. 1957 1958 1959[[tag-plane]] 1960= Format Planes (tag:plane Tag) 1961 1962The tag:plane tag contains definitions of each of the image planes which are 1963part of an image format. 1964 1965== Attributes of tag:plane Tags 1966 1967 * attr:index - required. 1968 An integer specifying the image plane being defined. 1969 Image planes are in the range [0,_p_-1] where _p_ is the number of 1970 planes in the format. 1971 * attr:widthDivisor - required. 1972 An integer specifying the relative width of this plane. 1973 A value of _k_ means that this plane is 1/_k_ the width of the overall 1974 format. 1975 * attr:heightDivisor - required. 1976 An integer specifying the relative height of this plane. 1977 A value of _k_ means that this plane is 1/_k_ the height of the overall 1978 format. 1979 * attr:compatible - required. 1980 A string naming another, single-plane format that this plane is 1981 compatible with. 1982 Must match the attr:name of another attr:format. 1983 1984== Contents of tag:plane Tags 1985 1986None. 1987 1988 1989[[tag-spirvimageformat]] 1990= SPIR-V Image Formats (tag:spirvimageformat Tag) 1991 1992The tag:spirvimageformat tag specifies the name of a SPIR-V image format 1993equivalent to this format. 1994 1995== Attributes of tag:spirvimageformat Tags 1996 1997 * attr:name - required. 1998 The name of the SPIR-V image format. 1999 Example: `name="R11fG11fB10f"`. 2000 2001== Contents of tag:spirvimageformat Tags 2002 2003None. 2004 2005 2006[[tag-spirvextensions]] 2007= SPIR-V Extensions (tag:spirvextensions Tag) 2008 2009The tag:spirvextensions tag contains definitions of each of the SPIR-V 2010extensions which are defined for the API. 2011 2012== Attributes of tag:spirvextensions Tags 2013 2014 * attr:comment - optional. 2015 Arbitrary string (unused). 2016 2017== Contents of tag:spirvextensions Tags 2018 2019Each tag:spirvextensions block contains zero or more tag:spirvextension tags, each 2020describing an single SPIR-V extension, in arbitrary order. 2021 2022 2023[[tag-spirvextension]] 2024= SPIR-V Extension (tag:spirvextension Tag) 2025 2026SPIR-V extensions are described in individual tag:spirvextension tags. 2027A SPIR-V extension is enabled by API versions or extensions. 2028 2029== Attributes of tag:spirvextension Tags 2030 2031 * attr:name - required. 2032 SPIR-V extension name. 2033 Example: `name="SPV_KHR_variable_pointers"` 2034 2035== Contents of tag:spirvextension Tags 2036 2037One or more <<tag-spirvenable,tag:enable>> tags, in arbitrary order. 2038Each tag describes a single enabling mechanism for the extension. 2039 2040== Example of a tag:spirvextensions Tag 2041 2042[source,xml] 2043-------------------------------------- 2044<spirvextension name="SPV_KHR_multiview"> 2045 <enable version="VK_VERSION_1_1"/> 2046 <enable extension="VK_KHR_multiview"/> 2047</spirvextension> 2048-------------------------------------- 2049 2050 2051[[tag-spirvcapabilities]] 2052= SPIR-V Capabilities (tag:spirvcapabilities Tag) 2053 2054The tag:spirvcapabilities tag contains definitions of each of the SPIR-V 2055capabilities which are defined for the API. 2056 2057== Attributes of tag:spirvcapabilities Tags 2058 2059 * attr:comment - optional. 2060 Arbitrary string (unused). 2061 2062== Contents of tag:spirvcapabilities Tags 2063 2064Each tag:spirvcapabilities block contains zero or more tag:spirvcapability 2065tags, each describing an single SPIR-V capability, in arbitrary order. 2066 2067 2068[[tag-spirvcapability]] 2069= SPIR-V Capability (tag:spirvcapability Tag) 2070 2071SPIR-V capabilities are described in individual tag:spirvcapability tags. 2072A SPIR-V capability is enabled by API versions, extensions, features, or 2073properties. 2074 2075== Attributes of tag:spirvcapability Tags 2076 2077 * attr:name - required. 2078 SPIR-V capability name. 2079 Example: `name="SPV_KHR_variable_pointers"` 2080 2081== Contents of tag:spirvcapability Tags 2082 2083One or more <<tag-spirvenable,tag:enable>> tags, in arbitrary order. 2084Each tag describes a single enabling mechanism for the capability. 2085 2086== Example of a tag:spirvcapabilities Tag 2087 2088[source,xml] 2089-------------------------------------- 2090<spirvcapability name="ImageCubeArray"> 2091 <enable struct="VkPhysicalDeviceFeatures" feature="imageCubeArray" requires="VK_VERSION_1_0"/> 2092</spirvcapability> 2093<spirvcapability name="GroupNonUniform"> 2094 <enable property="VkPhysicalDeviceVulkan11Properties" member="subgroupSupportedOperations" value="VK_SUBGROUP_FEATURE_BASIC_BIT" requires="VK_VERSION_1_1"/> 2095</spirvcapability> 2096-------------------------------------- 2097 2098 2099[[tag-spirvenable]] 2100= SPIR-V Enables (tag:enable Tag) 2101 2102The tag:enable tag describes a single mechanism in the API which enables a 2103tag:spirvextension or tag:spirvcapability. 2104There are four forms of tag:enable tags corresponding to different ways the 2105API may advertise enablement, though not all forms may be used with 2106tag:spirvextension tags. 2107Each form is described separately below. 2108 2109[[tag-syncstage]] 2110= Sync Stage (tag:syncstage Tag) 2111 2112The tag:syncstage tag contains definitions of each Pipeline stage. 2113 2114== Attributes of tag:syncstage Tags 2115 2116 * attr:name - required. 2117 VkPipelineStageFlagBits2 name 2118 * attr:alias - optional. 2119 Semantically equivalent name which is an alias of attr:name. 2120 2121== Contents of tag:syncstage Tags 2122 2123More information about the Pipeline stage using either 2124tag:syncequivalent or tag:syncsupport 2125 2126[[tag-syncaccess]] 2127= Sync Access (tag:syncaccess Tag) 2128 2129The tag:syncaccess tag contains definitions of each Access mask. 2130 2131== Attributes of tag:syncaccess Tags 2132 2133 * attr:name - required. 2134 VkAccessFlagBits2 name 2135 * attr:alias - optional. 2136 Semantically equivalent name which is an alias of attr:name. 2137 2138== Contents of tag:syncaccess Tags 2139 2140More information about the Access mask using either 2141tag:syncequivalent or tag:syncsupport 2142 2143[[tag-syncpipeline]] 2144= Sync Pipeline (tag:syncpipeline Tag) 2145 2146The tag:syncpipeline tag contains definitions of each type of Pipeline. 2147 2148== Attributes of tag:syncpipeline Tags 2149 2150 * attr:name - required. 2151 A unique string identifying the pipeline. 2152 2153== Contents of tag:syncpipeline Tags 2154 2155The tag:syncpipeline lists each pipeline stage in logical order using 2156tag:syncpipelinestage. Stages have extra attributes to describe 2157special ordering within the list 2158 2159[[tag-syncsupport]] 2160= Sync Support (tag:syncsupport Tag) 2161 2162The tag:syncsupport tag contains information what support there is for 2163a given Sync element. 2164 2165== Attributes of tag:syncsupport Tags 2166 2167 * attr:queues - optional. 2168 A comma-separated list of Queue types that are supported. 2169 * attr:stage - optional. 2170 A comma-separated list of Sync Stages that are supported. 2171 This is used to cross-reference with tag:syncstage 2172 2173[[tag-syncequivalent]] 2174= Sync Equivalent (tag:syncequivalent Tag) 2175 2176The tag:syncequivalent tag contains information showing a one-to-many 2177relationship of Sync elements 2178 2179== Attributes of tag:syncsupport Tags 2180 2181 * attr:stage - optional. 2182 A comma-separated list of Sync Stages that are the OR logical 2183 equivalence of the parent Sync Element 2184 * attr:access - optional. 2185 A comma-separated list of Sync Accesses that are the OR logical 2186 equivalence of the parent Sync Element 2187 2188== Attributes for API Version Number Enables 2189 2190 * attr:version - required. 2191 An API feature name, matching a tag:feature attr:name attribute value. 2192 2193If the API version is supported, the SPIR-V extension or capability is 2194enabled. 2195 2196== Attributes for API Extension Enables 2197 2198 * attr:extension - required. 2199 An API extension name, matching an tag:extension attr:name attribute 2200 value. 2201 2202If the API extension is supported and enabled, the SPIR-V extension or 2203capability is enabled. 2204 2205== Attributes for API Feature Enables 2206 2207 * attr:struct - required. 2208 An API feature structure name, matching a tag:struct attr:name attribute 2209 value. 2210 * attr:feature - required. 2211 An API feature name, matching a tag:member tag:name value of the feature 2212 structure. 2213 * attr:requires - required. 2214 A comma-separated list of API feature version numbers and/or extension 2215 names. 2216 * attr:alias - optional. 2217 Another API feature name which is an alias of attr:feature. 2218 Needed when the same feature is provided by two different API versions 2219 or extensions. 2220 2221If one of the API feature version numbers or extensions in the attr:requires 2222list is supported or enabled, respectively; and if the attr:feature name is 2223enabled in the feature structure, the SPIR-V capability is enabled. 2224 2225API feature enables are not supported for tag:spirvextension tags. 2226 2227== Attributes for API Property Enables 2228 2229 * attr:property - required. 2230 An API property structure name, matching a tag:struct attr:name 2231 attribute value. 2232 * attr:member - required. 2233 An API property name, matching a tag:member tag:name value of the 2234 attr:property structure. 2235 * attr:value - required. 2236 A value, matching an API tag:enum tag:name value. 2237 If the property is a bitfield, tag:value must be a bitmask value 2238 belonging to the attr:member bitfield type. 2239 Otherwise, tag:value must be an tag:enum name defined for the 2240 attr:member enumeration type. 2241 * attr:requires - optional. 2242 A comma-separated list of API feature version numbers and/or extension 2243 names. 2244 2245If one of the API feature version numbers or extensions in the attr:requires 2246list is supported or enabled, respectively; and if the attr:member property 2247contains the tag:value bit, or matches the tag:value, the SPIR-V capability 2248is enabled. 2249 2250API property enables are not supported for tag:spirvextension tags. 2251 2252== Contents of tag:enable Tags 2253 2254None. 2255 2256 2257[[examples]] 2258= Examples / FAQ / How Do I? 2259 2260For people new to the Registry, it will not be immediately obvious how to 2261make changes. 2262This section includes some tips and examples that will help you make changes 2263to the Vulkan headers by changing the Registry XML description. 2264 2265First, follow the steps described to <<starting,get the Vulkan GitHub 2266repository>> containing the registry and assemble the tools necessary to 2267work with the XML registry. 2268Once you are able to regenerate the Vulkan headers from `vk.xml`, you can 2269start making changes. 2270 2271 2272== General Strategy 2273 2274If you are _adding_ to the API, perform the following steps to _create_ the 2275description of that API element: 2276 2277 * For each type, enum group, compile time constant, and command being 2278 added, create appropriate new tag:type, tag:enums, tag:enum, or 2279 tag:command tags defining the interface in question. 2280 * Make sure that all added types and commands appropriately tag their 2281 dependencies on other types by adding nested tag:type tags. 2282 * Make sure that each new tag defines the name of the corresponding type, 2283 enum group, constant, or command, and that structure/union types and 2284 commands tag the types and names of all their members and parameters. 2285 This is essential for the automatic dependency process to work. 2286 2287If you are _modifying_ existing APIs, just make appropriate changes in the 2288existing tags. 2289 2290Once the definition is added, proceed to the next section to create 2291dependencies on the changed feature. 2292 2293 2294== API Feature Dependencies 2295 2296When you add new API elements, they will not result in corresponding changes 2297in the generated header unless they are _required_ by the interface being 2298generated. 2299This makes it possible to include different API versions and extensions in a 2300single registry and pull them out as needed. 2301So you must introduce a dependency on new features in the corresponding 2302tag:feature tag. 2303 2304There are multiple API versions defined for Vulkan at this time. 2305The initial Vulkan 1.0 tag can be found by searching for 2306 2307[source,xml] 2308-------------------------------------- 2309<feature api="vulkan" name="VK_VERSION_1_0" 2310-------------------------------------- 2311 2312Inside a tag:feature tag are multiple tag:require tags. 2313Some of these tags are used to express extension interactions, and others 2314only as a logical grouping mechanism for related parts of that API feature. 2315 2316 2317=== API Feature Walkthrough 2318 2319This section walks through the first few required API features in the 2320`vk.xml` tag:feature tag, showing how each requirement pulls in type, token, 2321and command definitions and turns those into definitions in the C header 2322file `vulkan_core.h`. 2323 2324Consider the first few lines of the tag:feature: 2325 2326[source,xml] 2327-------------------------------------- 2328<require comment="Header boilerplate"> 2329 <type name="vk_platform"/> 2330</require> 2331<require comment="API constants"> 2332 <enum name="VK_MAX_PHYSICAL_DEVICE_NAME"/> 2333 <enum name="VK_MAX_EXTENSION_NAME"/> 2334 ... 2335</require> 2336<require comment="Device initialization"> 2337 <command name="vkCreateInstance"/> 2338 ... 2339-------------------------------------- 2340 2341The first tag:require block says to require a type named `vk_platform`. 2342If you look at the beginning of the tag:types section, there is a 2343corresponding definition section: 2344 2345[source,xml] 2346-------------------------------------- 2347<type name="vk_platform">#include "vk_platform.h" 2348#define VK_MAKE_VERSION(major, minor, patch) \ 2349 ((major << 22) | (minor << 12) | patch) 2350 ... 2351-------------------------------------- 2352 2353This section is invoked by the requirement and emits a bunch of boilerplate 2354C code. 2355The explicit dependency is not strictly required since `vk_platform` will be 2356required by many other types, but placing it first causes this to appear 2357first in the output file. 2358 2359Note that `vk_platform` does not correspond to an actual C type, but instead 2360to a collection of freeform preprocessor includes and macros and comments. 2361Most other tag:type tags do define a specific type and are much simpler, but 2362this approach can be used to inject arbitrary C into the Vulkan headers 2363*when there is no other way*. 2364In general inserting arbitrary C is strongly discouraged outside of specific 2365special cases like this. 2366 2367The next tag:require block pulls in some compile time constants. 2368These correspond to the definitions found in the first tag:enums section of 2369`vk.xml`: 2370 2371[source,xml] 2372-------------------------------------- 2373<enums name="API Constants" 2374 comment="Vulkan hardcoded constants - not an enumerated type, part of the header boilerplate"> 2375 <enum value="256" name="VK_MAX_PHYSICAL_DEVICE_NAME"/> 2376 <enum value="256" name="VK_MAX_EXTENSION_NAME"/> 2377 ... 2378-------------------------------------- 2379 2380The third tag:require block starts pulling in some Vulkan commands. 2381The first command corresponds to the following definition found in the 2382tag:commands section of `vk.xml`: 2383 2384[source,xml] 2385-------------------------------------- 2386<commands> 2387 <command> 2388 <proto><type>VkResult</type> <name>vkCreateInstance</name></proto> 2389 <param>const <type>VkInstanceCreateInfo</type>* <name>pCreateInfo</name></param> 2390 <param><type>VkInstance</type>* <name>pInstance</name></param> 2391 </command> 2392 ... 2393-------------------------------------- 2394 2395In turn, the tag:command tag requires the tag:types `VkResult`, 2396`VkInstanceCreateInfo`, and `VkInstance` as part of its definition. 2397The definitions of these types are determined as follows: 2398 2399For `VkResult`, the corresponding required tag:type is: 2400 2401[source,xml] 2402-------------------------------------- 2403<type name="VkResult" category="enum"/> 2404-------------------------------------- 2405 2406Since this is an enumeration type, it simply links to an tag:enums tag with 2407the same name: 2408 2409[source,xml] 2410-------------------------------------- 2411<enums name="VkResult" type="enum" comment="API result codes"> 2412 <comment>Return codes (positive values)</comment> 2413 <enum value="0" name="VK_SUCCESS"/> 2414 <enum value="1" name="VK_UNSUPPORTED"/> 2415 <enum value="2" name="VK_NOT_READY"/> 2416 ... 2417 <comment>Error codes (negative values)</comment> 2418 <enum value="-1" name="VK_ERROR_OUT_OF_HOST_MEMORY" comment="A host memory allocation has failed"/> 2419 ... 2420-------------------------------------- 2421 2422For `VkInstanceCreateInfo`, the required tag:type is: 2423 2424[source,xml] 2425-------------------------------------- 2426<type category="struct" name="VkInstanceCreateInfo"> 2427 <member values="VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO"><type>VkStructureType</type> <name>sType</name></member> 2428 <member>const void* <name>pNext</name></member> 2429 <member>const <type>VkApplicationInfo</type>* <name>pAppInfo</name></member> 2430 <member>const <type>VkAllocCallbacks</type>* <name>pAllocCb</name></member> 2431 <member><type>uint32_t</type> <name>extensionCount</name></member> 2432 <member>const <type>char</type>*const* <name>ppEnabledExtensionNames</name></member> 2433</type> 2434-------------------------------------- 2435 2436This is a structure type, defining a C `struct` with all the members defined 2437in each tag:member tag in order. 2438In addition, it requires some other types, whose definitions are located by 2439name in exactly the same fashion. 2440 2441For the final direct dependency of the command, `VkInstance`, the required 2442tag:type is: 2443 2444[source,xml] 2445-------------------------------------- 2446 <comment>Types which can be void pointers or class pointers, selected at compile time</comment> 2447<type>VK_DEFINE_BASE_HANDLE(<name>VkObject</name>)</type> 2448<type>VK_DEFINE_DISP_SUBCLASS_HANDLE(<name>VkInstance</name>, <type>VkObject</type>)</type> 2449-------------------------------------- 2450 2451In this case, the type `VkInstance` is defined by a special compile time 2452macro which defines it as a derived class of `VkObject` (for `C```) or a 2453less typesafe definition (for C). 2454This macro is not part of the type dependency analysis, just the boilerplate 2455used in the header. 2456 2457If these are the only tag:feature dependencies in `vk.xml`, the resulting 2458`vulkan_core.h` header will look like this: 2459 2460[source,c] 2461-------------------------------------- 2462#ifndef VULKAN_H_ 2463#define VULKAN_H_ 1 2464 2465#ifdef __cplusplus 2466extern "C" { 2467#endif 2468 2469/* 2470** Copyright 2015-2024 The Khronos Group Inc. 2471 ... 2472*/ 2473 2474/* 2475** This header is generated from the Khronos Vulkan XML API Registry. 2476** 2477** Generated on date 20170208 2478*/ 2479 2480 2481#define VK_VERSION_1_0 1 2482#include "vk_platform.h" 2483#define VK_MAKE_VERSION(major, minor, patch) \ 2484 ((major << 22) | (minor << 12) | patch) 2485 2486// Vulkan API version supported by this file 2487#define VK_API_VERSION VK_MAKE_VERSION(0, 104, 0) 2488 2489#if defined (__cplusplus) && (VK_UINTPTRLEAST64_MAX == UINTPTR_MAX) 2490 #define VK_TYPE_SAFE_COMPATIBLE_HANDLES 1 2491#endif 2492 2493#if defined(VK_TYPE_SAFE_COMPATIBLE_HANDLES) && !defined(VK_DISABLE_TYPE_SAFE_HANDLES) 2494 #define VK_DEFINE_PTR_HANDLE(_obj) struct _obj##_T { char _placeholder; }; typedef _obj##_T* _obj; 2495 #define VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base) struct _obj##_T : public _base##_T {}; typedef _obj##_T* _obj; 2496 2497 #define VK_DEFINE_BASE_HANDLE(_obj) VK_DEFINE_PTR_HANDLE(_obj) 2498 #define VK_DEFINE_DISP_SUBCLASS_HANDLE(_obj, _base) VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base) 2499 #define VK_DEFINE_NONDISP_SUBCLASS_HANDLE(_obj, _base) VK_DEFINE_PTR_SUBCLASS_HANDLE(_obj, _base) 2500#else 2501 #define VK_DEFINE_BASE_HANDLE(_obj) typedef VkUintPtrLeast64 _obj; 2502 #define VK_DEFINE_DISP_SUBCLASS_HANDLE(_obj, _base) typedef uintptr_t _obj; 2503 #define VK_DEFINE_NONDISP_SUBCLASS_HANDLE(_obj, _base) typedef VkUintPtrLeast64 _obj; 2504#endif 2505 2506typedef enum { 2507 VK_SUCCESS = 0, 2508 VK_UNSUPPORTED = 1, 2509 VK_NOT_READY = 2, 2510 ... 2511} VkResult; 2512typedef enum { 2513 VK_STRUCTURE_TYPE_APPLICATION_INFO = 0, 2514 ... 2515} VKStructureType; 2516typedef struct { 2517 VkStructureType sType; 2518 const void* pNext; 2519 const char* pAppName; 2520 uint32_t appVersion; 2521 const char* pEngineName; 2522 uint32_t engineVersion; 2523 uint32_t apiVersion; 2524} VkApplicationInfo; 2525typedef enum { 2526 VK_SYSTEM_ALLOC_TYPE_API_OBJECT = 0, 2527 ... 2528} VkSystemAllocType; 2529typedef void* (VKAPI_PTR *PFN_vkAllocFunction)( 2530 void* pUserData, 2531 size_t size, 2532 size_t alignment, 2533 VkSystemAllocType allocType); 2534typedef void (VKAPI_PTR *PFN_vkFreeFunction)( 2535 void* pUserData, 2536 void* pMem); 2537typedef struct { 2538 void* pUserData; 2539 PFN_vkAllocFunction pfnAlloc; 2540 PFN_vkFreeFunction pfnFree; 2541} VkAllocCallbacks; 2542typedef struct { 2543 VkStructureType sType; 2544 const void* pNext; 2545 const VkApplicationInfo* pAppInfo; 2546 const VkAllocCallbacks* pAllocCb; 2547 uint32_t extensionCount; 2548 const char*const* ppEnabledExtensionNames; 2549} VkInstanceCreateInfo; 2550VK_DEFINE_BASE_HANDLE(VkObject) 2551VK_DEFINE_DISP_SUBCLASS_HANDLE(VkInstance, VkObject) 2552#define VK_MAX_PHYSICAL_DEVICE_NAME 256 2553#define VK_MAX_EXTENSION_NAME 256 2554typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)(const VkInstanceCreateInfo* pCreateInfo, VkInstance* pInstance); 2555#ifndef VK_NO_PROTOTYPES 2556VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance( 2557 const VkInstanceCreateInfo* pCreateInfo, 2558 VkInstance* pInstance); 2559#endif 2560 2561#ifdef __cplusplus 2562} 2563#endif 2564 2565#endif 2566-------------------------------------- 2567 2568Note that several additional types are pulled in by the type dependency 2569analysis, but only those types, commands, and tokens required by the 2570specified features are generated. 2571 2572 2573[[compile-time-constants]] 2574== How to Add a Compile Time Constant 2575 2576Go to the desired tag:feature or tag:extension tag. 2577Add (if not present) a nested tag:require block labelled 2578 2579[source,xml] 2580-------------------------------------- 2581<require comment="API constants"> 2582-------------------------------------- 2583 2584In this block, add an (appropriately indented) tag like 2585 2586[source,xml] 2587-------------------------------------- 2588 <enum name="VK_THE_ANSWER"/> 2589-------------------------------------- 2590 2591Then go to the tag:enums block labelled 2592 2593[source,xml] 2594-------------------------------------- 2595<enums comment="Misc. hardcoded constants - not an enumerated type"> 2596-------------------------------------- 2597 2598In this block, add a tag whose attr:name attribute matches the attr:name you 2599defined above and whose attr:value attribute is the value to give the 2600constant: 2601 2602[source,xml] 2603-------------------------------------- 2604 <enum value="42" type="uint32_t" name="VK_THE_ANSWER"/> 2605-------------------------------------- 2606 2607The attr:type attribute must be present, and must have one of the allowed 2608values `uint32_t`, `uint64_t`, or `float`. 2609 2610 2611[[compile-time-constants-format]] 2612== Allowed Format of Compile Time Constants 2613 2614The attr:value attribute must be a legal C99 constant scalar expression when 2615evaluated at compilation time. 2616Allowed expressions are additionally restricted to the following syntax: 2617 2618 * a single C decimal integer or floating-point value 2619 * optionally prefixed with `~` 2620 * optionally suffixed with `U`, `UL`, `ULL`, or `F` 2621 * and the entire expression optionally surrounded by paired `(` and `)`. 2622 2623 2624== How to Add a Struct or Union Type 2625 2626For this example, assume we want to define a type corresponding to a C 2627`struct` defined as follows: 2628 2629[source,c] 2630-------------------------------------- 2631typedef struct { 2632 VkStructureType sType; 2633 const void* pNext; 2634 const VkApplicationInfo* pAppInfo; 2635 const VkAllocCallbacks* pAllocCb; 2636 uint32_t extensionCount; 2637 const char*const* ppEnabledExtensionNames; 2638} VkInstanceCreateInfo; 2639-------------------------------------- 2640 2641If `VkInstanceCreateInfo` is the type of a parameter of a command in the 2642API, make sure that command's definition (see below for how to add a 2643command) puts `VkInstanceCreateInfo` in nested tag:type tags where it is 2644used. 2645 2646Otherwise, if the struct type is not used directly by a command in the API, 2647nor required by a chain of type dependencies for other commands, an explicit 2648tag:type dependency should be added to the tag:feature tag. 2649Go to the tag:types tag and search for the nested block labelled 2650 2651[source,xml] 2652-------------------------------------- 2653<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."> 2654 ... 2655-------------------------------------- 2656 2657In this block, add a tag whose attr:name attribute matches the attr:name of 2658the struct type being defined: 2659 2660[source,xml] 2661-------------------------------------- 2662<require comment="API types not used by commands"> 2663 <type name="VkInstanceCreateInfo"/> 2664 ... 2665-------------------------------------- 2666 2667Then go to the tag:types tag and add a new tag:type tag defining the struct 2668names and members, somewhere below the corresponding comment, like this: 2669 2670[source,xml] 2671-------------------------------------- 2672<types> 2673 ... 2674 <comment>Struct types</comment> 2675 <type category="struct" name="VkInstanceCreateInfo"> 2676 <member><type>VkStructureType</type> 2677 <name>sType</name></member> 2678 <member>const void* 2679 <name>pNext</name></member> 2680 <member>const <type>VkApplicationInfo</type>* 2681 <name>pAppInfo</name></member> 2682 <member>const <type>VkAllocCallbacks</type>* 2683 <name>pAllocCb</name></member> 2684 <member><type>uint32_t</type> 2685 <name>extensionCount</name></member> 2686 <member>const <type>char</type>*const* 2687 <name>ppEnabledExtensionNames</name></member> 2688 </type> 2689 ... 2690-------------------------------------- 2691 2692If any of the member types are types also defined in the header, make sure 2693to enclose those type names in nested tag:type tags, as shown above. 2694Basic C types should not be tagged. 2695 2696If the type is a C `union`, rather than a `struct`, then set the value of 2697the attr:category attribute to `"union"` instead of `"struct"`. 2698 2699 2700== How to Add an Enumerated Type 2701 2702For this example, assume we want to define a type corresponding to a C 2703`enum` defined as follows: 2704 2705[source,c] 2706-------------------------------------- 2707typedef enum { 2708 VK_DEVICE_CREATE_VALIDATION_BIT = 0x00000001, 2709 VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT = 0x00000002; 2710} VkDeviceCreateFlagBits. 2711-------------------------------------- 2712 2713If `VkDeviceCreateFlagBits` is the type of a parameter to a command in the 2714API, or of a member in a structure or union, make sure that command 2715parameter or struct member's definition puts `VkDeviceCreateFlagBits` in 2716nested tag:type tags where it is used. 2717 2718Otherwise, if the enumerated type is not used directly by a command in the 2719API, nor required by a chain of type dependencies for commands and structs, 2720an explicit tag:type dependency should be added to the tag:feature tag in 2721exactly the same fashion as described above for `struct` types. 2722 2723Next, go to the line labelled 2724 2725[source,xml] 2726-------------------------------------- 2727<comment>Vulkan enumerant (token) definitions</comment> 2728-------------------------------------- 2729 2730At an appropriate point below this line, add an tag:enums tag whose 2731attr:name attribute matches the tag:type name `VkDeviceCreateFlagBits`, and 2732whose contents correspond to the individual fields of the enumerated type: 2733 2734[source,xml] 2735-------------------------------------- 2736<enums name="VkDeviceCreateFlagBits" type="bitmask"> 2737 <enum bitpos="0" name="VK_DEVICE_CREATE_VALIDATION_BIT"/> 2738 <enum bitpos="1" name="VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT"/> 2739</enums> 2740-------------------------------------- 2741 2742Several other attributes of the tag:enums tag can be set. 2743In this case, the attr:type attribute is set to `"bitmask"`, indicating that 2744the individual enumerants represent elements of a bitmask. 2745 2746The individual tag:enum tags define the enumerants, just like the definition 2747for compile time constants described above. 2748In this case, because the enumerants are bits in a bitmask, their values are 2749specified using the attr:bitpos attribute. 2750The value of this attribute must be an integer in the range [0,30] 2751specifying a single bit number, and the resulting value is printed as a 2752hexadecimal constant corresponding to that bit. 2753 2754It is also possible to specify enumerant values using the attr:value 2755attribute, in which case the specified numeric value is passed through to 2756the C header unchanged. 2757 2758 2759[[adding-bitflags]] 2760== How to Add Bit Flags 2761 2762Bit masks are defined by two types in the xml - the type of the mask itself, 2763and the type of the valid flags. 2764 2765For this example, assume we want to define bit flags that can handle up to 276664 independent values as follows: 2767 2768[source,c] 2769-------------------------------------- 2770// Flag bits for VkExampleFlagBits 2771typedef VkFlags64 VkExampleFlagBits; 2772static const VkExampleFlagBits VK_EXAMPLE_NONE = 0; 2773static const VkExampleFlagBits VK_EXAMPLE_FIRST_BIT = 0x00000001; 2774static const VkExampleFlagBits VK_EXAMPLE_SECOND_BIT = 0x00000002; 2775 2776typedef VkFlags64 VkExampleFlags; 2777-------------------------------------- 2778 2779An explicit tag:type dependency should be added to the tag:feature tag in 2780exactly the same fashion as described above for `struct` types. 2781 2782Firstly, a definition is needed for the flags type used as a parameter to 2783commands or member of functions. 2784Go to the line labelled: 2785 2786[source,xml] 2787-------------------------------------- 2788<comment>Bitmask types</comment> 2789-------------------------------------- 2790 2791At the end of the list of `VkFlags` and `VkFlags64` types, add a definition 2792of the flags type like so: 2793 2794[source,xml] 2795-------------------------------------- 2796<type bitvalues="VkExampleFlagBits" category="bitmask">typedef <type>VkFlags64</type> <name>VkExampleFlags</name>;</type> 2797-------------------------------------- 2798 2799The attr:category defines this as a `"bitmask"` type. 2800The attr:bitvalues attribute identifies the `*FlagBits` entry defining the 2801flag bits associated with this type. 2802 2803Next, go to the line labelled: 2804 2805[source,xml] 2806-------------------------------------- 2807<comment>Types generated from corresponding enums tags below</comment> 2808-------------------------------------- 2809 2810At an appropriate point in the list of enum types after this comment, add 2811the following line: 2812 2813[source,xml] 2814-------------------------------------- 2815<type name="VkExampleFlagBits" category="enum"/> 2816-------------------------------------- 2817 2818This defines a type for the flag bits for generators that need it. 2819The attr:category attribute of `"enum"` identifies that this is an 2820enumerated type. 2821 2822Finally, go to the line labelled: 2823 2824[source,xml] 2825-------------------------------------- 2826<comment>Vulkan enumerant (token) definitions</comment> 2827-------------------------------------- 2828 2829At the end of the list of enum definitions below this line, add an tag:enums 2830tag whose attr:name attribute matches the tag:type name `VkExampleFlagBits`, 2831and whose contents correspond to the individual fields of the enumerated 2832type: 2833 2834[source,xml] 2835-------------------------------------- 2836<enums name="VkExampleFlagBits" type="bitmask" bitwidth="64"> 2837 <enum value="0" name="VK_EXAMPLE_NONE"/> 2838 <enum bitpos="0" name="VK_EXAMPLE_FIRST_BIT"/> 2839 <enum bitpos="1" name="VK_EXAMPLE_SECOND_BIT"/> 2840</enums> 2841-------------------------------------- 2842 2843The attr:type attribute is set to `"bitmask"`, indicating that the 2844individual enumerants represent elements of a bitmask. 2845The attr:bitwidth attribute is set to `"64"` indicating that this is a 284664-bit flag type. 2847 2848The individual tag:enum tags define the enumerants, just like the definition 2849for compile time constants described above. 2850In this case, a "no flags" type is defined in `VK_EXAMPLE_NONE` with the 2851attr:value attribute defining it to have a hard value of 0. 2852The other types have their values are specified using the attr:bitpos 2853attribute, as these are actual bit flag values. 2854The value of this attribute must be an integer in the range [0,63] 2855specifying a single bit number, and the resulting value is printed as a 2856hexadecimal constant corresponding to that bit. 2857 2858 2859=== 32-bit Flags 2860 2861Bit flags can also be defined using 32-bit C enum types. 2862Doing so is broadly similar to 64-bit bit flags, but with a few key 2863differences. 2864For this example, assume we want to define the same type as above, but 2865corresponding to a C `enum` and flags type defined as follows: 2866 2867[source,c] 2868-------------------------------------- 2869typedef enum VkExampleFlagBits { 2870 VK_EXAMPLE_NONE 2871 VK_DEVICE_CREATE_VALIDATION_BIT = 0x00000001, 2872 VK_DEVICE_CREATE_MULTI_DEVICE_IQ_MATCH_BIT = 0x00000002; 2873} VkExampleFlagBits; 2874 2875typedef VkFlags VkExampleFlags; 2876-------------------------------------- 2877 2878To add this to the xml, entries need to be added to the XML in the same way 2879as above, but with slightly different attributes: 2880 2881For the flag type definition, the entry should use `VkFlags` instead of 2882`VkFlags64`, and require the flag bits type, instead of specifying the 2883attr:bitvalues attribute: 2884 2885[source,xml] 2886-------------------------------------- 2887<type requires="VkExampleFlagBits" category="bitmask">typedef <type>VkFlags</type> <name>VkExampleFlags</name>;</type> 2888-------------------------------------- 2889 2890For the definition of the enumerated flag values themselves, the bitwidth 2891needs to either be changed to `"32"`, or omitted entirely (which defaults to 2892a bitwidth of 32) as follows: 2893 2894[source,xml] 2895-------------------------------------- 2896<enums name="VkExampleFlagBits" type="bitmask"> 2897-------------------------------------- 2898 2899Note that 32-bit bitmasks must use an integer in the range [0,30] - C enums 2900are only guaranteed to support signed 32-bit integer values, and defining an 2901unsigned value for the 31st bit could change the size of the enum type. 2902The generator scripts will warn about values exceeding this range. 2903 2904 2905== How to Add a Command 2906 2907For this example, assume we want to define the command: 2908 2909[source,c] 2910-------------------------------------- 2911VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance( 2912 const VkInstanceCreateInfo* pCreateInfo, 2913 VkInstance* pInstance); 2914-------------------------------------- 2915 2916Commands must always be explicitly required in the tag:feature tag. 2917In that tag, you can use an existing tag:require block including API 2918features which the new command should be grouped with, or define a new 2919block. 2920For this example, add a new block, and require the command by using the 2921tag:command tag inside that block: 2922 2923[source,xml] 2924-------------------------------------- 2925<feature api="vulkan" name="VK_VERSION_1_0" number="1.0" comment="Vulkan core API interface definitions"> 2926 ... 2927 <require comment="Device initialization"> 2928 <command name="vkCreateInstance"/> 2929 </require> 2930 ... 2931</feature> 2932-------------------------------------- 2933 2934The tag:require block may include a attr:comment attribute whose value is a 2935descriptive comment of the contents required within that block. 2936The comment is not currently used in header generation, but might be in the 2937future, so use comments which are polite and meaningful to users of the 2938generated header files. 2939 2940Then go to the tag:commands tag and add a new tag:command tag defining the 2941command, preferably sorted into alphabetic order with other commands for 2942ease of reading, as follows: 2943 2944[source,xml] 2945-------------------------------------- 2946<commands comment="Vulkan command definitions"> 2947 ... 2948 <command> 2949 <proto><type>VkResult</type> 2950 <name>vkCreateInstance</name></proto> 2951 <param>const <type>VkInstanceCreateInfo</type>* 2952 <name>pCreateInfo</name></param> 2953 <param><type>VkInstance</type>* 2954 <name>pInstance</name></param> 2955 </command> 2956 ... 2957</commands> 2958-------------------------------------- 2959 2960The tag:proto tag defines the return type and function name of the command. 2961The tag:param tags define the command's parameters in the order in which 2962they are passed, including the parameter type and name. 2963The contents are laid out in the same way as the structure tag:member tags 2964described previously. 2965 2966 2967== More Complicated API Representations 2968 2969The registry schema can represent a good deal of additional information, for 2970example by creating multiple tag:feature tags defining different API 2971versions and extensions. 2972This capability is not yet relevant to Vulkan. 2973Those capabilities will be documented as they are needed. 2974 2975 2976== More Complicated Output Formats and Other Languages 2977 2978The registry schema is oriented towards C-language APIs. 2979Types and commands are defined using syntax which is a subset of C, 2980especially for structure members and command parameters. 2981It would be possible to use a language-independent syntax for representing 2982such information, but since we are writing a C API, any such representation 2983would have to be converted into C anyway at some stage. 2984 2985The `vulkan.h` header is written using an _output generator_ object in the 2986Python scripts. 2987This output generator is specialized for C, but the design of the scripts is 2988intended to support writing output generators for other languages as well as 2989purposes such as documentation (e.g. generating asciidoc fragments 2990corresponding to types and commands for use in the API specification and 2991reference pages). 2992When targeting other languages, the amount of parsing required to convert 2993type declarations into other languages is small. 2994However, it will probably be necessary to modify some of the boilerplate C 2995text, or specialize the tags by language, to support such generators. 2996 2997 2998== Additional Semantic Tagging 2999 3000The schema is being extended to support semantic tags describing various 3001properties of API features, such as: 3002 3003 * constraints on allowed scalar values to function parameters (non-`NULL`, 3004 normalized floating-point, etc.) 3005 * length of arrays corresponding to function pointer parameters 3006 * miscellaneous properties of commands such as whether the application or 3007 system is responsible for threadsafe use; which queues they may be 3008 issued on; whether they are aliases or otherwise related to other 3009 commands; etc. 3010 3011These tags will be used by other tools for purposes such as helping create 3012validation layers, generating serialization code, and so on. 3013We would like to eventually represent everything about the API that is 3014amenable to automatic processing within the registry schema. 3015Please make suggestions on the GitHub issue tracker. 3016 3017 3018[[general:stability]] 3019== Stability of the XML Database and Schema 3020 3021The Vulkan XML schema is evolving in response to corresponding changes in 3022the Vulkan API and ecosystem. 3023Most such change will probably be confined to adding attributes to existing 3024tags and properly expressing the relationships to them, and making API 3025changes corresponding to accepted feature requests. 3026Changes to the schema should be described in the <<changelog,change log>> of 3027this document. 3028Changes to the `.xml` files and Python scripts are logged in GitHub history. 3029 3030 3031[[changelog]] 3032= Change Log 3033 3034 * 2023-11-24 - Clarify that the `promotedto` relationship which may be 3035 defined for <<tag-extension, tag:extension>> tags does not promise exact 3036 API-level compatibility (internal issue 4819). 3037 * 2023-06-28 - remove support for tag:member and tag:param attr:optional 3038 attribute value `"false"` (internal issue 3548). 3039 * 2023-06-14 - removed deprecated attr:start and attr:end from tag:enums 3040 * 2023-05-18 - Add tag:sync to help define all sync objects in the XML 3041 * 2023-03-29 - add tag:extension attr:ratified attribute to express 3042 ratification status. 3043 * 2023-02-26 - add normative references section, cite it as needed, and 3044 update description of tag:extension tags to refer to the style guide for 3045 computing numeric enumerant values (public issue 2069). 3046 * 2023-02-22 - specify that attr:depends expressions are 3047 <<depends-expressions, evaluated left-to-right>> for operators of the 3048 same precedence (public issue 2062). 3049 * 2023-02-14 - replace tag:extension attributes attr:requiresCore and 3050 attr:requires, and tag:require attributes attr:feature and 3051 attr:extension, by a new attr:depends attribute. This is an intentional 3052 breaking change to support a more flexible and consistent expression 3053 syntax for these dependencies (internal issues 2883, 3272). 3054 * 2023-01-11 - add attr:deprecated attribute to tag:enum, tag:type, 3055 and tag:type tag:member tags. 3056 * 2022-11-23 - update tag:command attr:queues syntax to include all queue 3057 types currently in use. 3058 * 2022-08-12 - update tag:requires attr:extension syntax to support 3059 logical OR and AND constructs for multiple extensions (internal issue 3060 2922). 3061 * 2022-07-11 - Add attr:videocoding attribute to <<tag-command,tag:command>> 3062 tags to indicate whether a command buffer command can be recorded inside, 3063 outside, or both inside and outside of a video coding scope. 3064 * 2022-06-29 - Add tag:command attribute attr:tasks (internal issue 3117). 3065 * 2022-06-22 - Add attr:validstructs attribute to command 3066 <<tag-command:param:attr, tag:param>> tags when using an abstract 3067 `VkBaseInStructure` or `VkBaseOutStructure` as the formal parameter 3068 type. 3069 * 2022-06-16 - Add `VkSparseImageFormatProperties*` to the list of 3070 structure types allowed to have 'limittype' member attributes. 3071 * 2022-06-08 - Add `exact`, `bits`, `mul` and `pot` limit types. 3072 * 2022-06-08 - Update description of types to which the attr:limittype 3073 attribute of structure tag:member tags can be applied (internal issue 3074 3101). 3075 * 2022-06-08 - Update description of tag:extension attr:requires attribute 3076 such that the specified extensions must be *enabled*, not just 3077 *supported*. This is consistent with the following NOTE, the 3078 specification description of "`required extensions`", and actual use in 3079 the XML of this attribute (internal issue 3116). 3080 * 2021-12-13 - Add attr:api attribute to the tag:member and tag:param 3081 tags. 3082 * 2021-11-29 - Add attr:api attribute to the tag:command tag. 3083 * 2021-10-11 - Add description of the tag:formats tag for describing 3084 Vulkan `VkFormat` image formats, and of the tag:spirvextensions and 3085 tag:spirvcapabilities tags for describing enabling mechanisms for SPIR-V 3086 extensions (internal issue 2484). 3087 * 2021-09-13 - Further clarify that attr:api and attr:supported attributes 3088 are comma-separated list of API names (internal issue 2809). 3089 * 2021-08-22 - Update introductory descriptions of toolchain and scripts. 3090 * 2021-08-15 - Add an explicit description of the tag:enum attr:extends 3091 attribute as introducing a requirement for the enumerated type being 3092 extended. 3093 * 2021-07-12 - Note that tag:extension tags describing instance extensions 3094 must not have dependencies on device extensions (internal issue 2387). 3095 * 2021-06-14 - Add an `objecttype` attribute which specifies the 3096 relationship between a Vulkan handle and another member or parameter 3097 specifying the type of object that handle refers to (public issue 1536). 3098 * 2021-06-06 - Update description of the attr:supported attribute of 3099 <<tag-extension, tag:extension tags>> to mandate that `disabled` 3100 extensions are not processed (public issue 1549). 3101 * 2021-04-21 - Add the attr:limittype attribute to <<tag-type, structure 3102 tag:member tags>>, to describe how queried limits are interpreted 3103 (internal issue 2427). 3104 * 2021-03-30 - Add a description of the <<compile-time-constants-format, 3105 allowed format of compile time constants>> (internal merge request 3106 4451). 3107 * 2021-03-22 - Update allowed values for the attr:type attribute of 3108 tag:enum tags and make it mandatory (internal issue 2564). 3109 * 2021-01-11 - Expand the scope of the attr:optional attribute tag:member 3110 and tag:param tags to specify that the member or parameter may be 0 for 3111 all scalar types, not just bitmasks and array sizes (internal issue 3112 2435). 3113 * 2020-11-23 - Add `objtypeenum` attribute to <<tag:type, tag:type>> tags 3114 to link the object name to the corresponding `VK_OBJECT_TYPE_*` 3115 enumerant, if any (internal issue 2393). 3116 * 2020-11-22 - Add requirement that `pNext` members have the 3117 `optional="true"` attribute set (internal issue 2428). 3118 * 2020-10-14 - Remove advice to set the attr:noautovalidity attribute on 3119 the `pNext` member of extending structures in the <<tag:type, tag:type 3120 tag>>, since the validity generator scripts now take care of this 3121 (internal issue 2335). 3122 * 2020-06-02 - Add description of how to switch between 64- and 32-bit 3123 flags. 3124 * 2020-05-07 - Update description of <<schema:apiname, API Names>> to 3125 current usage, including allowing specifying multiple API names for a 3126 given feature or extension. 3127 * 2020-04-29 - Expand use of attr:category `basetype` in tag:type tags to 3128 include external API types. 3129 * 2020-02-20 - Clarify that tag:enum tags inside tag:remove tags must be 3130 reference enums, not containing attributes defining values. 3131 * 2020-01-13 - Restrict attr:bitpos to [0,30] to avoid poorly defined 3132 compiler behavior. 3133 * 2019-08-25 - Add attr:sortorder attribute to tag:feature and 3134 tag:extension tags. 3135 * 2018-12-06 - Specify that command aliases are not guaranteed to resolve 3136 to the same entry point in the underlying layer stack, matching a 3137 related clarification in the Vulkan Specification. 3138 * 2018-10-01 - Add description of the default value of attr:optional 3139 member and parameter attributes, if not specified. 3140 * 2018-08-28 - Add optional attr:provisional attribute to tag:extension 3141 tags. 3142 * 2018-07-07 - Add optional attr:promotedto, attr:deprecatedby, and 3143 attr:obsoletedby attributes to tag:extension tags. 3144 * 2018-06-25 - Remove attr:vendorids tags for Khronos vendor IDs. 3145 * 2018-05-08 - Add tag:driverids and tag:driverid tags for describing 3146 Vulkan driver implementation identification information. 3147 * 2018-04-15 - Add attr:requiresCore. 3148 * 2018-03-07 - Updated for Vulkan 1.1 release. 3149 * 2018-02-21 - Add descriptions of the attr:extnumber and attr:alias 3150 attributes used for defining tag:enum attributes, the attr:alias 3151 attribute used for defining tag:type aliases, the attr:name and 3152 attr:alias attributes used for defining tag:command aliases, the 3153 attr:platform attribute of tag:extension tags, and the attr:feature 3154 attribute of tag:require tags; and update the document to the header 3155 naming and grouping scheme used starting in Vulkan 1.1. 3156 * 2018-01-07 - Add tag:platforms and tag:platform tags for describing 3157 Vulkan platform names and preprocessor symbols. 3158 * 2017-09-10 - Define syntax of member and parameter attr:altlen 3159 attributes, for use by code generators. 3160 * 2017-09-01 - Define syntax of member and parameter attr:len attributes 3161 consistently and correctly for current uses of latexmath: 3162 * 2017-08-24 - Note that the tag:extension attribute attr:type must be 3163 specified if the extension is not disabled. 3164 * 2017-07-27 - Finish removing validextensionstructs attribute and 3165 replacing it with structextends. 3166 * 2017-07-14 - Add comment attributes or tags as valid content in several 3167 places, replacing XML comments which could not be preserved by XML 3168 transformation tools. 3169 * 2017-02-20 - Change to asciidoctor markup and move into the 3170 specification source directory for ease of building. 3171 * 2016-09-27 - Remove tag:validity and tag:usage tags, since these 3172 explicit usage statements have been moved to the specification source. 3173 * 2016-08-26 - Update for the single-branch model. 3174 * 2016-07-28 - Add attr:type and attr:requires attributes to tag:extension 3175 tags. 3176 * 2016-02-22 - Change math markup in attr:len attributes to use asciidoc 3177 `latexmath:[$` and `$]` delimiters. 3178 * 2016-02-19 - Add attr:successcodes and attr:errorcodes attributes of 3179 tag:command tags. 3180 Add a subsection to the introduction describing the schema choices and 3181 how to file issues against the registry. 3182 * 2016-02-07 - Add attr:vendorids tags for Khronos vendor IDs. 3183 * 2015-12-10 - Add attr:author and attr:contact attributes for 3184 tag:extension tags. 3185 * 2015-12-07 - Move `vulkan/vulkan.h` to a subdirectory. 3186 * 2015-12-01 - Add tag:tags tags for author tags. 3187 * 2015-11-18 - Bring documentation and schema up to date for extension 3188 enumerants. 3189 * 2015-11-02 - Bring documentation and schema up to date with several 3190 recent merges, including tag:validity tags. 3191 Still out of date WRT extension enumerants, but that will change soon. 3192 * 2015-09-08 - Rename `threadsafe` attribute to attr:externsync, and 3193 `implicitunsafeparams` tag to attr:implicitexternsync. 3194 * 2015-09-07 - Update tag:command tag description to remove the 3195 attr:threadsafe attribute and replace it with a combination of 3196 attr:threadunsafe attributes on individual parameters, and 3197 tag:implicitunsafeparams tags describing additional unsafe objects for 3198 the command. 3199 * 2015-08-04 - Add `basetype` and `funcpointer` attr:category values for 3200 type tags, and explain the intended use and order in which types in each 3201 category are emitted. 3202 * 2015-07-02 - Update description of Makefile targets. 3203 Add descriptions of attr:threadsafe, attr:queues, and attr:renderpass 3204 attributes of <<tag-command,tag:command>> tags, and of attr:modified 3205 attributes of <<tag-command:param,tag:param>> tags. 3206 * 2015-06-17 - add descriptions of allowed attr:category attribute values 3207 of tag:type tags, used to group and sort related categories of 3208 declarations together in the generated header. 3209 * 2015-06-04 - Add <<examples,examples of making changes and additions>> 3210 to the registry. 3211 * 2015-06-03 - Move location to new `vulkan` Git repository. 3212 Add definition of tag:type tags for C struct/unions. 3213 Start adding <<examples,examples of making changes>>. 3214 * 2015-06-02 - Branch from OpenGL specfile documentation and bring up to 3215 date with current Vulkan schema. 3216 * 2015-07-10 - Remove contractions to match the style guide. 3217 * 2015-07-19 - Move this document from LaTeX to asciidoc source format and 3218 make minor changes to markup. 3219