Vulkan^® Documentation and Extensions: Procedures and Conventions

The key words must, required, should, recommend, may, and optional in this document are to be interpreted as described in RFC 2119 and by the Vulkan Specification in the “Terminology” section.

The style guide is broken into four sections:

Vulkan Documentation is primarily written in Asciidoctor, a text markup language. We use the command-line asciidoctor client that is actively maintained by asciidoctor, which is documented on its website at https://asciidoctor.org.

References to the Asciidoctor User Manual are to sections in the document at https://asciidoctor.org/docs/user-manual/.

Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is available for Linux, MacOS, and Microsoft Windows.

Normative references are references to external documents or resources to which documentation authors must comply.

Association for Computing Machinery. Citation Style and Reference Formats. Retrieved July 27, 2019. https://www.acm.org/publications/authors/reference-formatting .

International Organization for Standardization. Data elements and interchange formats — Information interchange — Representation of dates and times (2004-12-01). https://www.iso.org/standard/40874.html . Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples.

Khronos Vulkan Working Group. KhronosGroup/Vulkan-Docs project on GitHub (July 5, 2016). https://github.com/KhronosGroup/Vulkan-Docs .

Jon Leech. The Khronos Vulkan API Registry (February 26, 2023). https://registry.khronos.org/vulkan/specs/1.3/registry.html .

Khronos Vulkan Working Group. Vulkan 1.3.242 - A Specification (February 26, 2023). https://registry.khronos.org/vulkan/ .

Version 1.3.242 is the latest patch release of the Vulkan API Specification as of the time this reference was last updated, but the Specification is frequently updated with minor bugfixes and clarifications. When a more recent patch release is made, it becomes the normative reference for the API.

apiext: VK_KHR_surface

apiext (with backquotes): VK_KHR_surface

Names of identifiers should generally be written with full words, as a concise description of what that identifier is. For example, the type of a structure containing information about how to create an instance is VkInstanceCreateInfo.

Abbreviations and prefixes are sometimes used in the API when they do not impede clarity. All abbreviations and prefixes used in the API must be approved by the Vulkan working group, and be added to the Common Abbreviations and Standard Prefixes sections, respectively. Whenever an approved abbreviation exists for a particular word, it should be used in place of the full word unless there is good reason not to.

When a number is part of an identifier, it is treated as a word if it is a standalone number, such as the extension name token VK_KHR_GET_MEMORY_REQUIREMENTS_2_EXTENSION_NAME for the VK_KHR_get_memory_requirements2 extension. For uses where the number is part of a common abbreviation such as 2D or R8B8`, the entire abbreviation is treated as a word.

Preprocessor definitions include an underscore _ as a delimiter between words, with every character in upper case.

Each definition is prefixed with VK_, followed by the name.

This rule applies to most declarations with the C Preprocessor’s #define token, including macros and constants. There are however a few exceptions:

Type names are declared with no separator between words. Each word starts with a capital letter, and every other character in each word is lower case.

Each type name is prefixed with Vk.

This rule applies to all type definitions except function pointer types, including struct and union types, handles, base typedefs, and enumerant types.

Enumerants include an underscore _ as a delimiter between words, with every character in upper case.

Each enumerant name is prefixed with VK_.

Enumerants are prefixed with the exact name of the type it belongs to, converted to the correct case (e.g. VkStructureType → VK_STRUCTURE_TYPE_*).

This rule applies to all enumerants, with one exception.

Command names are declared with no separator between words. Each word starts with a capital letter, and every other character in each word is lower case.

The structure of a command name should be as follows:

prefix Verb Object Property

These rules apply to all command declarations.

Function parameter names are declared with no separator between words. Each new word, except for the first, starts with a capital letter. All other characters in the parameter name are in lower case.

Members/parameters of a type that is not a base type should generally be named in a similar way to the type itself, with additional context added for clarity when necessary.

Pointer members/parameters are prefixed with a number of p characters, with one p for each level of indirection.

Function pointer members/parameters are prefixed with pfn.

Any member describing the size of a memory allocation should be suffixed with Size. If the context is self-evident from the structure name, then it may simply be named size.

Any member describing the number of something, such as an array length or number of internal allocations, should be suffixed with Count. The size rule overrides this rule, though it is possible to have multiple sizes (e.g. sizeCount). If the member is an array length, then the name of length should correspond to the name of the array member, usually XYZCount for an array named pXYZs. If a structure in a pNext chain is an array whose length must match the length of an array of the base structure, then that extending structure should include an array length member with the same name as the length in the base structure.

These rules apply to all function parameters and struct/union members, with a single exception:

Identifiers defined by an extension are modified by appending the extension’s author ID to the end of the identifier, as described below. Author IDs are obtained as described in the Extension and Layer Naming Conventions section.

If an extension becomes part of core, a new version of the extension’s identifiers should be created, that do not contain the author ID at the end of the identifier. The original identifiers should be kept in order to maintain source-level compatibility with existing applications making use of the earlier extension’s identifiers.

Abbreviations and acronyms are sometimes used in the Vulkan API Specification and the Vulkan API where they are considered clear and commonplace. All such abbreviations used in the core API are defined here. Extensions should also use these abbreviations where appropriate.

Prefixes are used in the API to denote specific semantic meaning of Vulkan names, or as a label to avoid name clashes, and are explained here:

Formats naming conventions

The Khronos extension registries and extension naming conventions serve several purposes:

The first step in the process should be to fill out a proposal document, and iterate on that before committing to writing specification language.

The main reasons to do this are to ensure that everyone understands the nature of the problem being addressed, to be clear why a particular solution was chosen in lieu of others, and to allow for design changes before committing to specification text. If a potential implementor has concerns with any of the design choices, it is much easier to change details in a proposal document than it is to rewrite specification text.

In the top level proposals folder there is a template (template.adoc) for writing design proposals, including guidance on how it should be used.

For some simpler extensions it may not be necessary to write a proposal document if both the problem is well understood and the solution well bounded, so this is not a required piece of documentation. However it may still be useful to write this in a proposal document.

Once a proposal is written, the Vulkan Working Group and other interested parties should be asked to review and provide feedback before specification work begins.

Some general rules to simplify the specific rules below:

Versions, extensions and layers have formal names. These names are used in a variety of places:

There is a rigid syntax for these names:

All these names include a VK_ prefix, as described in the Preprocessor Defines section above. In addition, layers add a LAYER_ prefix.

All these names must be valid C language identifiers.

Extensions may add new commands, types, and tokens, or collectively “objects”, to the Vulkan API. These objects are given globally unique names by appending the author ID defined above for the extension name as described in the Extension Identifier Naming Conventions section above.

The canonical definition of the Vulkan APIs is kept in an XML file known as the Vulkan API Registry. The registry is kept in xml/vk.xml in the default branch (main) of the KhronosGroup/Vulkan-Docs project, containing the most recently released Vulkan API specification. The registry contains reserved author IDs, core and extension interface definitions, definitions of individual commands and structures, and other information which must be agreed on by all implementations. The registry is used to maintain a single, consistent global namespace for the registered entities, to generate the Khronos-supplied Vulkan header files, and to create a variety of related documentation used in generating the API specification and reference pages. Other uses of the registry outside Khronos include the LunarG Loader and Validation Layers, and a variety of language bindings.

Previous Khronos APIs could only officially be modified by Khronos members. In an effort to build a more flexible platform, Vulkan allows non-Khronos developers to extend and modify the API via layers and extensions in the same manner as Khronos members. However, extensions must still be registered with Khronos. A mechanism for non-members to register layers and extensions is provided.

Extension authors will be able to create an account on GitHub and register an author ID with Khronos through the KhronosGroup/Vulkan-Docs project. The author ID must be used for any extensions that author registers. The same mechanism will be used to request registration of extensions or layers with Khronos, as described below.

To reserve an author ID, propose a merge request against vk.xml in the default branch. The merge must add a <tag> XML tag and fill in the name, author and contact attributes with the requested author ID, the author’s formal name (e.g. company or project name), and contact email address, respectively. The author ID will only be reserved once this merge request is accepted.

Please do not try to reserve author IDs which clearly belong to another existing company or project which may wish to develop Vulkan extensions or layers in the future, as a matter of courtesy and respect. Khronos may decline to register author IDs that are not requested in good faith.

Vulkan implementors must report a valid vendor ID for their implementation when queried by vkGetPhysicalDeviceProperties, as described in the “Devices and Queues” section of the Vulkan API Specification. If there is no valid PCI vendor ID defined for the physical device, implementations must obtain a Khronos vendor ID.

Khronos vendor IDs are reserved in a similar fashion to author IDs. While vendor IDs are not directly related to API extensions, the reservation process is similar, and so is described in this section.

To reserve an Khronos vendor ID, you must first have a Khronos author ID. Propose a merge request against vk.xml in the default branch. The merge must define a new enumerant by adding an <enum> tag to the VkVendorId <enums> tag, following the existing examples. The value attribute of the <enum> must be the next available unused value, and is the reserved vendor ID. The name attribute must be VK_VENDOR_ID_<author>, where <author> is the author tag. The vendor ID will be reserved only once this merge request has been accepted.

Please do not try to reserve vendor IDs unless you are making a good faith effort to develop an implementation of a Khronos API and require one for that purpose.

Extensions must be registered with Khronos. Layers should be registered, but registration is not required. Registration means:

Registration for Khronos members is handled by filing a merge request in the internal gitlab repository modifying vk.xml in the default branch, containing the core specification against which the extension or layer will be written. Registration is not complete until the registry maintainer has validated and accepted the merge.

A similar mechanism is used to register extensions not authored by Khronos members. Implementors who are not Khronos members and who need to create extensions must register with Khronos by creating a GitHub account, and registering their author ID and/or FQDNs to that account. They can then submit new extension registration requests by proposing merges to vk.xml. On acceptance of the merge, the extension will be registered, though its specification need not be checked into the Khronos GitHub repository at that point.

The registration process can be split into several steps to accommodate extension number assignment prior to extension publication:

API versions and extensions are documented as modifications to the Vulkan specification. Changes specific to a version or extension are protected by asciidoctor conditionals. The changes are only visible in generated documentation when the Specification is built with an asciidoctor attribute of that name defined. Khronos publishes three forms of the Vulkan Specification: the core API (e.g. versions 1.x) only; core API with all registered KHR and EXT extensions; and core API with all registered extensions.

Extensions can define their own enumeration types and assign any values to their enumerants that they like. Each enumeration has a private namespace, so collisions are not a problem. However, when extending existing enumeration objects with new values, care must be taken to preserve global uniqueness of values. Enumerations which define new bits in a bitmask are treated specially as described in Reserving Bitmask Values below.

Each extension is assigned a range of values that can be used to create globally-unique enum values. Most values will be negative numbers, but positive numbers are also reserved. The ability to create both positive and negative extension values is necessary to enable extending enumerations such as VkResult that assign special meaning to negative and positive values. Therefore, 1000 positive and 1000 negative values are reserved for each extension. Extensions must not define enum values outside their reserved range without explicit permission from the owner of those values (e.g. from the author of another extension whose range is infringed on, or from the Khronos Registrar if the values do not belong to any extension’s range).

The information needed to add new values to the XML are as follows:

Individual enumerant values are calculated as offsets in the range defined by the extension number, as follows:

The exact syntax for specifying extension enumerant values is defined in the Vulkan API Registry schema documentation. Extension authors should also refer to existing extensions for examples.

If an extension is promoted to another extension or to a core API version, the enumerant values should remain the same as they were in the original extension, in order to maintain binary compatibility with existing applications. In this case, the extension number will need to be specified explicitly to keep the promoted enumerant value unchanged.

When an extension introduces a new flags (*Flags) type, it should also introduce a corresponding new bitmask (*FlagBits) type. The flags type contains zero or more bits from the bitmask, and is used to specify sets of bits for commands or structures.

In some cases, a new flags type will be defined with no individual bits yet specified. This usage occurs when the flags are intended for future expansion. In this case, even though the corresponding bitmask type is not yet useful, the (empty) bitmask type should be defined in vk.xml. The empty bitmask type and corresponding flags type should be given boilerplate definitions in the specification.

In addition to any tokens specific to the functionality of an extension, all extensions must define two additional tokens.

For example, for the WSI extension VK_KHR_surface, at the time of writing the following definitions were in effect:

Expanding on previous discussion, extensions can add values to existing enums; and can add their own commands, enums, typedefs, etc. This is done by adding to vk.xml. All such additions will be included in the Vulkan header files supplied by Khronos.

If the extension adds a new handle to Vulkan, a corresponding value must be added to VkObjectType (as defined in the “Debugging” section of the Vulkan API Specification) in order to allow components to identify and track objects of the new type.

The new enumeration value must conform to the naming defined in the Extension Enumerant Names section. In this case, the type’s Vk prefix is replaced with the enum prefix VK_OBJECT_TYPE_, and the rest of the handle name is converted as described in that section.

Function pointer declarations and function prototypes for all core Vulkan API commands are included in the Vulkan header files. These come from the official XML specification of the Vulkan API hosted by Khronos.

Function pointer declarations are also included in the Vulkan header for all commands defined by registered extensions. Function prototypes for extensions may be included in the headers. Extension commands that are part of the Vulkan ABI must be flagged in the XML. Function prototypes will be included in the headers for all extension commands that are part of the Vulkan ABI.

An extension can be considered platform specific, in which case its interfaces in the header files are protected by #ifdefs. This is orthogonal to whether an extension command is considered to be part of the Vulkan ABI.

The initial set of WSI extension commands (i.e. for VK_KHR_surface, VK_KHR_swapchain, and VK_KHR_*_surface) are considered to be part of the Vulkan ABI. Function prototypes for these WSI commands are included in platform-specific files such as vulkan_android.h. See the “Window System-Specific Header Control (Informative)” section of the Vulkan Specification for more details.

vkGetInstanceProcAddr and vkGetDeviceProcAddr can be used in order to obtain function pointer addresses for core and extension commands (per the description in the “Command Function Pointers” section of the Vulkan API Specification). Different Vulkan API loaders can choose to statically export functions for some or all of the core Vulkan API commands, and can statically export functions for some or all extension commands. If a loader statically exports a function, an application can link against that function without needing to call one of the vkGet*ProcAddr commands.

Extending structures modify the behavior of existing commands or structures by providing additional parameters, using the pNext field of an existing structure to point to a chain of additional structures. This mechanism is described in more detail in the “Valid Usage for Structure Pointer Chains” section of the Vulkan API Specification.

Multiple extending structures affecting the same structure, defined by multiple core versions or extensions, can be chained together in this fashion. Any structure which can be chained in this fashion must begin with the following two members:

It is in principle possible for extensions to provide additional parameters through alternate means, such as passing a handle parameter to a structure with a sType value defined by the extension. This approach is strongly discouraged.

When chaining multiple extending structures together, the implementation will process the chain starting with the base structure and proceeding through each successive extending structure in turn. Extending structures should behave in the same fashion no matter the order of chaining, and must define their interactions with other extensions such that the results are deterministic.

If an extending structure must be present in a pNext chain in specific ordering relative to other structures in the chain in order to provide deterministic results, it must define that ordering and expected behavior as part of its specification and valid usage statements.

Validation of structure types in pNext chains is automatically generated from the registry, based on the description of structextends in the registry document.

When there is a Valid Usage interaction between a parent structure and an extending structure appearing in the pNext chain of the parent, that interaction must be described in the explicit Valid Usage section of the parent structure, rather than the extending structure, and must be protected by appropriate extension-specific ifdef constructs.

For example, a constraint added to the VkImageCreateInfo structure by the presence of structures defined by two extensions which cannot interact is described as:

However, a constraint added to VkBufferCreateInfo by an extending structure in the VK_NV_dedicated_allocation extension must not be described as part of the extending structure’s valid usage:

Instead, define the constraint as part of the parent VkBufferCreateInfo structure’s valid usage:

A feature structure is a structure that extends VkPhysicalDeviceFeatures2 and VkDeviceCreateInfo, and which provides VkBool32 members to indicate implementation support for individual features.

Every device or physical-device extension that adds or modifies device-level commands, or adds new structures or enum values used in device-level commands, must define a feature structure.

If an extension requires a feature structure, then any mandatory features must be described in the Feature Requirements section. New extensions must mandate that implementations support at least one feature of an extension.

For WSI extensions, it is often necessary to extend VkSurfaceCapabilities2KHR in order to enable compatibility between a VkSurface and a VkPhysicalDevice to be queried. Every device or physical-device extension that relies upon support from the window system should implement this query.

The presence of a structure extending VkSurfaceCapabilities2KHR does not remove the requirement for a feature structure if any device-level functionality is introduced by an extension.

The asciidoctor source for the Vulkan Specification and related documents is under an open source license.

When creating a new file, add the following copyright and license statement at the top:

YEAR should be replaced by the year in which the file was created.

AUTHOR is normally “The Khronos Group Inc.”. If a new file is created by a member company or outside contributor, use that entity’s legal name as the author.

SPDX-License-Identifier gives the license used for the file, following the SPDX standard for short identifiers in source files. CC-BY-4.0 is the short identifier for the Creative Commons Attribution 4.0 International license.

No matter who holds the copyright on a source file for the Specification, it must be placed under the CC-BY-4.0 license. When contributing to the Specification, contributors are required to execute a Contributor License Agreement to this effect.

When updating an existing file, modify the following copyright and license statement to include the year(s) of modification. For example:

indicates a file which has been modified in 2018, 2019, and 2020 inclusive.

Files which are not actual specification source but are “code-like”, such as scripts and Makefiles, are normally placed under the Apache 2.0 license. Use SPDX-License-Identifier: Apache-2.0 for such files.

Chapters and sections follow a rigid template consisting of an optional anchor (if other parts of the document cross-reference the section) followed by a one line title and a blank line. The anchor is typically the base name of the file containing the chapter, with a lowercased version of the section name following, with spaces replaced by dashes.

Always use the one-line title form, with one to four = signs preceding the chapter/section title. The two-line title form cannot be easily searched for, and often looks like other types of asciidoctor delimiters. Using a mix of one-line and two-line titles causes compatibility issues, and using the two-line title form may implicitly set a backwards-compatibility syntax mode we do not want.

Always precede the anchor by two blank lines (except at the beginning of a file), and follow the title by a blank line, to set off sections visibly.

This is a sample section structurally similar to the Vulkan API Specification, nested one level inside a chapter. Sections can be nested up to level 5, although not all levels are included in the Table of Contents.

Asciidoc source should be text filled to 76 columns with hard line breaks. Each sentence in a paragraph ends with a newline to minimize git diff conflicts. Except when necessary for lists or other markup, text should begin at the first column of each line (leading spaces are often semantically meaningful in asciidoctor markup).

UTF-8 characters outside the ASCII subset should be used sparingly, only when needed for non-English names. Instead use asciidoctor markup for special characters, if required. For example, two hyphens produces an em-dash:

As an exception, multiplication should be marked with the unicode multiplication symbol “×” (and not an asterisk) when used in plain text. You may also use the {times} asciidoctor attribute for this symbol. In math sections, the same symbol should be referred to as \times. In code sections, a conventional asterisk (*) should be used instead.

The trailing + character causes a hard break in asciidoctor markup, and should not be used except for this purpose. Markup addition with the {plus} asciidoctor attribute, except in LaTeX math and source blocks.

See the Asciidoctor docs for supported special characters, as well as use of entity references.

Quotation marks should use the 66/99 convention. That is, double asymmetric quotation marks, indicated by a quotation mark then a backtick as opening marks, and a backtick then quotation mark as closing marks ("`like this`"), which renders “like this”.

Never use hard tabs or trailing blanks.

This section discusses Asciidoc macros used in the document. In addition to the macros defined by asciidoctor itself, additional macros are defined by the Vulkan API Specification and Reference Page configuration files.

There are several possible types of notes. Depending on the type of output, they are rendered in different styles, but always include a note title, and are usually set off in a box or with an icon. While asciidoctor supports a wide set of admonition paragraphs such as TIP, IMPORTANT, WARNING, and CAUTION, we always use the NOTE form, augmented by a note title. Each type of note is discussed below.

There are a variety of common terms that have several equivalent word choices. Always use the words or phrases in the first column instead of the alternate terms. This list may not be comprehensive; when in doubt, be guided by the existing Vulkan API Specification.

When describing undefined behavior that results only in the values of specified variables, or the contents of specified memory, becoming undefined or implementation-defined, use the undefined: macro to indicate that each use of the term “undefined” has been carefully considered and accurately represents the degree of undefined behavior allowed.

The word “undefined” should not be used without the trailing :. This is enforced by internal CI tests.

The undefined: macro does not result in visible markup in the output document, and is not itself a normative term. The macro is simply markup to help ensure that use of the word has been consciously chosen.

When describing more general types of undefined behavior (up to and including termination of the application), do not use the term “undefined”. Instead, specify that the application must: not create circumstances that would lead to such behavior. Such statements should be written as valid usage statements, if possible.

The Vulkan API Specification describes API commands followed by descriptions of their parameters, which are usually simple scalar types, handles or pointers to Vulkan objects or arrays of objects; enumerated types specifying values or bitmasks which affect the operation of a command; or structures containing combinations of scalar types and objects. The templates and examples shown and annotated here are based on the Vulkan API Specification. Do not vary from them without compelling need.

Normative parts of the Vulkan API Specification should describe what something does, rather than how or why an application would want to use it.

When explicitly allowed by the Specification, the reserved value NULL may be used for pointer parameters and members and dispatchable object handles, and the reserved value VK_NULL_HANDLE may be used for non-dispatchable Vulkan object handle parameters and members. Otherwise, pointers and handles must refer to valid memory and valid Vulkan objects, respectively.

Explanations of why and how should largely be confined to reference documentation, sample code, tutorials, and other such documents. Occasional non-normative explanations can be included in the Vulkan API Specification using informative notes.

Language specifying behavior of a command or structure that does not originate in an extension should be placed in a single contiguous region of the specification.

When defining a new command or structure from an extension that introduces additional behavior or options, do not insert such new language in a way that “orphans” part of an existing description by splitting up the existing language.

This constraint does not apply to enumerated types. Language for new enumerants defined by extensions should be added to the existing enumerant definition, protected by asciidoctor conditionals for the new extension.

There is a considerable amount of math in the documentation, ranging from simple arithmetic expressions to complicated conditionals. There are two ways of marking up math expressions, described below.

When describing an extending structure which is passed to an existing command by including it in the pNext chain of a structure parameter of that command, introduce the structure description in this fashion:

When describing properties of a structure included in a pNext chain, refer to that structure as “included in the pNext chain” rather than `"present in`" or other similar terms, in this fashion:

The next section is a sample based on the Vulkan API Specification, and describes a command and related structures and enumerated types in enough detail to see the different usage patterns and layout / markup used. Informative notes discussing markup and guidelines are interspersed with the example description to explain how and why it looks as it does.

This demonstrates how to create a continuation paragraph in a member description. This paragraph is not present in the actual specification the example is based on.

Explicit valid usage statements must be written at a point that all information needed to evaluate them is known. In particular, if validity of structure parameters depends on other parameters of a command that structure is passed to, such valid usage statements must be written for the command, rather than the structure.

Each explicit valid usage statement should be a single, self-contained assertion, possibly involving multiple subexpressions or parameters. For example, instead of writing “width, height, and depth must all be greater than zero”, write each condition as a separate statement. In contrast, “width × height must be less than 1024” is a single assertion involving multiple parameters.

Do not use “unless” to call out exceptions - always write valid usage statements of the form “if A then B”. This may result in harder to read statements in a few cases, but maintains consistency. In many cases, it may lead to a simpler VU statement, or splitting one large VU into multiple new ones.

A valid usage statement may used nested bullet lists or other asciidoc markup.

Be clear on the distinction between a “valid pointer” and a “pointer to a valid object” when writing valid usage statements. See the “Valid Usage” section of the Vulkan Specification, and particularly the “Valid Usage for Pointers” section.

When clauses in valid usage statements apply only when specific extensions and/or core API versions are enabled at runtime, use appropriate asciidoctor conditionals around such clauses.

Explicit valid usage statements must be assigned Valid Usage ID tags before publication. This process is described in the Valid Usage ID Tags appendix, but is normally performed only when preparing to integrate functionality into the Vulkan Specification prior to publication. It is something authors of new functionality should be aware of, but are not themselves responsible for. For example, when writing the explicit vkCreateCommandPool::queueFamilyIndex valid usage statement shown above, the tag

was inserted by a script, not the original author.

If the same set of valid usage statements are going to be common to multiple commands or structures, these should be extracted into a separate file under chapters/commonvalidity/. The file name should be short but to the point (e.g. draw_common.adoc), and then the file can be included in the relevant API features using standard include syntax:

Common VU includes should appear before individual VUs for consistency.

The file itself should be structured with the comment // Common Valid Usage used as a delimiter at the start and end of the file, with a comment describing in more detail where these are included, and then the valid usage statement bullets outside of a valid usage block. For example:

Finally, the original feature section needs to define the :refpage: attribute to match the name of the feature, as this is used to correctly generate links to expanded common valid usage statements in the built specification.

In general, this methodology should be preferred over any other method of consolidation - e.g. calling out a block of common valid usage statements, or referencing the valid usage statements of another command. However, for cases where the boilerplate of setting this up creates more text than a simple copy paste (e.g. only two commands consume a single valid usage statement), the original VUs can be left intact.

Sometimes an enumerated type has all values defined by extensions, and each enumerated value defined by the type will be surrounded by an asciidoctor conditional for the corresponding extension. When a specification is built without any of those extensions enabled, the type should still be included, even though it is empty. In this case, the enumerated value descriptions must be followed by one additional conditional section which is only included when none of the relevant extensions are enabled.

For example, the relevant part of the VkDescriptorSetLayoutCreateFlagBits description, whose only value is defined by an extension, will look like this:

The Vulkan reference pages are (mostly) extracted from corresponding sections of the API Specification. This requires that the markup and writing conventions described above be adhered to rigidly.

The extraction scripts for a given page rely on the existence of an asciidoctor open block surrounding markup describing that page, with attributes used to specify properties of the reference page. Additional heuristics and non-asciidoctor tags, described below, are used to identify subsections of a reference page in some cases.

In general the open block introduction will look like:

Attributes which can be set on the block are:

Attributes of the open block must be written in this format, using single quotes as delimiters (even though asciidoctor markup also allows double quotes), and escape single quotes in e.g. the desc attribute value with backquotes.

After the open block is started, the following markup should be provided:

All elements specifying an interface name (open block refpage attributes, interface include lines, and validity include lines) must use the same interface name, if present. Otherwise the extraction script is either unable to extract that page, or will extract the wrong text - and the language will be structurally incorrect, as well. The extraction process is somewhat fragile, so care should be taken and the results of reference page extraction verified after making changes to that portion of the specification source.

Content that should only appear in reference pages, such as developer-oriented guidelines for reference pages describing extensions, may be conditionally included in the specification as follows:

At the moment, the PDF conversion path only supports the Windows-1252 character set, as we are currently using the standard fonts built into every PDF viewer - such that we do not have to embed a different font. Unfortunately these only support Windows-1252, which is a highly limited character set.

As such, characters not in that set will not display properly when present in an SVG, and will generate a warning when building the PDF. Luckily, Inkscape has an “Object to path” function built in, which will convert text to a raw path, allowing these characters to be supported.

Please ensure that you build the PDF before submitting any new images, particularly with non-standard characters, in order to catch such errors.

For implicit valid usage statements, the tags are formatted like this:

blockname is the name of the function or structure for which a valid usage statement is being generated.

paramname is the name of the parameter being validated. In some cases, the statement does not validate a single parameter and this portion of the tag is absent.

category is the type of statement being generated. There are over one dozen types referring to distinct conditions such as valid objects, required bitmasks, required array lengths, constraints on parent objects, and so on.

For explicit valid usage statements, the tags are formatted like this:

blockname is the name of the function or structure for which a valid usage statement is being generated.

paramname is the name of the parameter being validated. In some cases, the statement does not validate a single parameter and this portion of the tag is replaced by -None-

number is a unique five digit, zero-filled number used to disambiguate similar tag names.

For implicit valid usage statements generated automatically from vk.xml, VUID tags are created automatically by the generator scripts.

For explicit valid usage statements, VUID tags are generated by passing appropriate options to the script reflow.py.

Since these tags are of use only to the published validation layer, they are needed only in the published Specification sources and outputs. Therefore, authors of extensions, or other branches adding valid usage statements, are not themselves responsible for adding tags in their branches. The specification editors will take care of this as part of the process of publishing updates. For reference purposes, this process is described below:

First, after integrating all new specification language into the internal gitlab default branch (currently main) containing the canonical Specification source, invoke the following command:

This will add VUID tags to all statements in valid usage blocks which do not already have them. Some diagnostics will be reported, but these are do not in general require any action.

After updating all files, the script will update the file scripts/vuidCounts.py containing reserved ranges of VUIDs for the default branch and certain other development branches.

Commit the updated source files and vuidCounts.py together. The next time the script is run, VUID tags will be assigned numbers starting from the next free value in the range available to default branch.

In-development Vulkan extensions are kept in their own branches, with the branch name the same as the name of the extension being developed. VUID tags may be assigned in these branches in the same fashion as in default branch. To enable this, each development branch must be assigned its own independent VUID range in the default branch copy of vuidCounts.py, to prevent collisions. In the event that default branch or any development branch exhausts the available VUID range, reflow.py will report this and stop assigning VUIDs. At that point, a new range must be assigned to the branch in the default branch copy of vuidCounts.py, as well as in the per-branch copy.

Valid usage statements have corresponding tests in the Vulkan Validation Layer. The tests must be changed in response to semantic changes in the VU statements, whether for bug-fixing, adding extension interactions, or otherwise. The rule used when updating explicit VU statements is that the merge request or pull request responsible for making the change must remove the existing VUID tag, so that a new one can be assigned, except in the following cases: