1. Introduction

This document contains required procedures and conventions when writing specifications for new Vulkan APIs, extensions and layers, or related Khronos® documentation such as white papers and tutorials; or contributing to existing Vulkan specifications. These are collectively referred to as Vulkan Documentation or just documentation below. The primary focus is the API Specification and API extensions, although all of the markup and most of the writing style is equally applicable to other documentation.

The primary purpose is to achieve consistency across the API, as well as across all of our source and output documents. Consistency makes it easier for developers, editors, reviewers, and users of our documentation to understand and modify it.

This document is now formally voted on and approved by the Vulkan Working Group. This means that unless explicitly stated otherwise, the procedures and conventions must be followed. If you have a strong desire to modify the procedures and conventions, such changes must be made through the normal Vulkan Working Group processes.

1.1. Terminology

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 1.1 Specification in the “Terminology” section.

1.2. Document Structure

The style guide is broken into four sections:

• API Naming Conventions - the required rules for choosing names of Vulkan identifiers of all types.

• Extensions and Layers - the required procedures for creating formal Vulkan extensions and layers.

• Markup Style - the required and recommended markup style for writing asciidoc and XML source that follows consistent formatting and layout guidelines, tags special terms and phrases for proper processing by the spec generation tools, etc.

• Writing Style - the required and recommended writing style for overall and fine-grained structure and conventions, normative language use, API naming conventions, common words and phrases to use and to avoid, linking and cross-referencing, etc.

1.3. Asciidoc Markup

Vulkan Documentation is primarily written in Asciidoc, a form of text markup language. Specifically we’re using the version of Asciidoc that is actively maintained by asciidoctor, which is documented on its website at http://www.asciidoctor.org/.

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

Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is available for Linux, MacOS, and Microsoft Windows. Multiple preview tools also exist for the language, primarily using AsciidoctorJ (https://github.com/asciidoctor/asciidoctorj) or asciidoctor.js (https://github.com/asciidoctor/asciidoctor.js). In particular, GitHub and GitLab both have asciidoc previews for .adoc or .asciidoc files in repositories, and live preview extensions exist for Chrome and Firefox.

The Asciidoctor toolchain and build process are not addressed by this document, which concentrates solely on source documents.

1.4. Normative References

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

International Organization for Standardization, Data elements and interchange formats — Information interchange — Representation of dates and times, http://www.iso.org/iso/catalogue_detail?csnumber=40874, 2004-12-01. Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples.

Khronos Vulkan Working Group, KhronosGroup/Vulkan-Docs project on GitHub, https://github.com/KhronosGroup/Vulkan-Docs, 2016-07-05.

Vulkan Working Group, Vulkan 1.1.70 - A Specification, https://www.khronos.org/registry/vulkan/, 2018-03-07

Version 1.1.70 is the latest patch release of the Vulkan API Specification as of the time this reference was created, but that 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.

2. API Naming Conventions

Identifiers in the Vulkan API (e.g. types, parameters, constants, etc.) all follow a set of naming rules, providing a consistent scheme for developers.

The Vulkan C API uses prefixes as an implicit namespace control mechanism. Bindings to other languages can choose not to use these prefixes if the language provides an explicit namespace mechanism.

2.1. General Naming Rules

Names of identifiers should generally be written with full words, avoiding abbreviations, 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 are in common use. 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 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.

2.2. Preprocessor Defines

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:

• The header guard for each header includes an additional underscore _ at the end of the identifier.

• Example: VULKAN_H_

• Definitions that denote the presence of an extension follow the extension name string convention.

• Example: VK_KHR_sampler_mirror_clamp_to_edge

• Three VKAPI_* definitions are defined by the platform header to alias certain platform-specific identifiers related to calling conventions.

• Examples: VKAPI_ATTR, VKAPI_CALL and VKAPI_PTR

• Preprocessor defines are occasionally used to create aliases between other Vulkan identifiers, which usually happens when something was originally misnamed. In these cases, the fixed name is added to the API, and the old name is made into an alias of that. In these cases, the name will be whatever the original misnamed identifier was.

Example
// VK_VERSION_MAJOR (Macro)
#define VK_VERSION_MAJOR(version) ((uint32_t)(version) >> 22)

#define VK_HEADER_VERSION 10

2.3. Type Names

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.

Example
// VkImage (Handle)
VK_NONDISP_HANDLE(VkImage)

// VkFlags (Base type)
typedef uint32_t VkFlags;

// VkResult (Enum type)
typedef enum VkResult {
...
};

// VkApplicationInfo (Struct)
typedef struct VkApplicationInfo {
...
} VkApplicationInfo;

// VkClearColorValue (Union)
typedef union VkClearColorValue {
...
} VkClearColorValue;

2.3.1. Extension Structure Names

Structures which extend other structures through the pNext chain should reflect the name of the base structure they extend. Currently there are two examples of such naming schemes.

New structures which add extended object creation parameters to a base structure should use this naming scheme:

Table 1. Extended Object Information Structures
Base Structure Name Extension Structure Name

VkObjectCreateInfo

VkObjectNameCreateInfoAuthor

Object is the name of the object being created. Name is a short name for the extension or the new information added by that extension. Author is the author ID of the extension.

New structures which extend API queries, such as the vkGetPhysicalDeviceFeatures2KHR and vkGetPhysicalDeviceProperties2KHR commands defined by the VK_KHR_get_physical_device_properties2 extension, should use this naming scheme:

Table 2. Extended Query Structures
Base Structure Name Extension Structure Name

vkGetPhysicalDeviceFeatures2KHR

VkPhysicalDeviceNameFeaturesAuthor

vkGetPhysicalDeviceProperties2KHR

VkPhysicalDeviceNamePropertiesAuthor

Name is a short name for the extension, or for the new feature or property being queried, such as Multiview or DiscardRectangle. Author is the author ID of the extension.

2.4. Enumerant Names

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. VkStructureTypeVK_STRUCTURE_TYPE_*).

This rule applies to all enumerants, with one exception.

• The VkResult enumerants are split into two sub types: error and success codes.

• Success codes are not prefixed with anything other than VK_.

• Error codes are prefixed with VK_ERROR_.

Example
// VK_FORMAT_UNDEFINED, VK_FORMAT_R4G4_UNORM_PACK8 (Enumerants)
typedef enum VkFormat {
VK_FORMAT_UNDEFINED = 0,
VK_FORMAT_R4G4_UNORM_PACK8 = 1,
...
};

// VkResult codes (Exception)
typedef enum VkResult {
VK_SUCCESS = 0,
...
VK_ERROR_OUT_OF_HOST_MEMORY = -1,
...
} VkResult;

2.5. Command Names

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

prefix

This is usually "vk", but will be "vkCmd" if it is a command used to record into a command buffer, or "vkQueue" if it directly affects a queue.

Verb

The verb that describes the action being performed. A list of most verbs used in Vulkan is available here.

Object

The name of the object being acted upon by the command.

Property

The property of the object which is being acted upon by the command, and is omitted in cases where the whole object is being acted upon (e.g. creation commands).

These rules apply to all command declarations.

Example
// Creation command
VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance( ... );

// Command buffer recording command
VKAPI_ATTR VkResult VKAPI_CALL vkCmdBindPipeline( ... );

// Get command
VKAPI_ATTR VkResult VKAPI_CALL vkGetQueryPoolResults( ... );
 Note There are three exceptions to the above rule in the core Vulkan API: vkDeviceWaitIdle vkCmdNextSubpass vkCmdPipelineBarrier These names are left as-is to maintain compatibility. There are additionally a number of exceptions in a few existing extensions.

2.5.1. Query Commands

A number of commands in the API are used to determine the properties of some object in the implementation.

The queried properties may either be invariant, or they may change based on application behaviour. If the results are not invariant, the lifetime of the results should be clearly described in the command description. See Lifetime of Retrieved Results in the specification for more information.

These commands fall into two categories from a naming perspective:

Capability Queries

These are commands which query capabilities of objects that an implementation can provide. Such commands use the verb "Enumerate" to identify themselves.

e.g. vkEnumeratePhysicalDeviceProperties

Whilst these commands describe properties of the named object, they do not accept a parameter of that object type - though they usually have a parameter for the parent type.

Object State Queries

These commands are used to query the current properties of an object that has been created. Such commands use the verb "Get" to identify themselves.

e.g. vkGetPhysicalDeviceQueueFamilyProperties

These commands always have a parameter of the object type.

2.5.2. Command Verbs

Below is a list of many of the verbs currently in use in core Vulkan and KHR extensions, along with their meanings. The list is not guaranteed to be up to date, but covers all core and KHR verbs at the time of writing.

Verb Meaning

Acquire

Acquire ownership of an object from an external source

Allocate

Allocates memory in a pool or memory heap and creates object - paired with "Free"

Begin

Start of a range of command buffer commands with different behaviour than those outside the range - "End" marks the end of the range

Bind

Binds an object to another object

Blit

Performs a filtered and scaled copy of pixels from one image to another

Clear

Sets all pixels in an image to the same value

Copy

A raw copy of data from one object to another with no transformation of the data

Create

Creates an object - paired with "Destroy"

Destroy

Destroys an object - paired with "Create"

Dispatch

Kicks off a set of compute tasks

Draw

Kicks off a set of rasterization tasks

End

End of a range of command buffer commands with different behaviour than those outside the range - "Begin" marks the start of the range

Enumerate

Queries the capabilities of objects that could be created, before creating them

Execute

Executes commands recorded in another command buffer

Fill

Sets all data units in a buffer to the same value

Flush

Flushes data from the host to the device

Free

Destroys an object and then frees memory back to a pool or memory heap - paired with "Allocate"

Get

Queries the state of an existing object

Import

Imports the payload from an external object into a Vulkan object

Invalidate

Invalidates data on the host, forcing newer data on the device to be read

Map

Maps an allocation into host memory - paired with "Unmap"

Merge

Merges two objects

Present

Presents an image to a surface

Push

Pushes data to the device as part of a command stream

Release

Releases ownership of an object to an external source

Reset

Resets the state of an object to an initial state

Resolve

Resolves multiple samples in a multisampled image to an image with one sample per pixel

Set

Sets the state of an object

Submit

Submits a set of commands to a queue

Unmap

Unmaps an allocation from host memory - paired with "Map"

Update

Updates entries in a descriptor set

Wait

Waits for some signal

Write

Writes values to an object

2.5.3. Function Pointer Type Names

Function pointer names are declared exactly as the equivalent statically declared command would be declared, but prefixed with PFN_, standing for "Pointer to FunctioN".

Example
// PFN_vkCreateInstance (Function Pointer)
typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)( ... );

2.6. Function Parameter and Struct/Union Member Names

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 that describes 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 that describes 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 member of a chained extension structure is an array whose length must match the length of an array of the base structure, then the chained extension 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:

• The sType member of structures is abbreviated as it is used in almost every structure.

• The slightly odd naming prevents it clashing with any future variables.

• The s stands for “structure”, referring to its enumerant type.

Example
// Function parameters, including a twice indirected pointer.
VKAPI_ATTR VkResult VKAPI_CALL vkMapMemory(
VkDevice                                    device,
VkDeviceMemory                              memory,
VkDeviceSize                                offset,
VkDeviceSize                                size,
VkMemoryMapFlags                            flags,
void**                                      ppData);

// Structure members, including the sType exception and a single indirected
// pointer.
typedef struct VkMemoryBarrier {
VkStructureType    sType;
const void*        pNext;
} VkMemoryBarrier;

// Function pointer members
typedef struct VkAllocationCallbacks {
void*                                   pUserData;
PFN_vkAllocationFunction                pfnAllocation;
PFN_vkReallocationFunction              pfnReallocation;
PFN_vkFreeFunction                      pfnFree;
} VkAllocationCallbacks;

// Size member (pCode is not a specific array of anything, it is just a
// pointer to memory)
VkStructureType              sType;
const void*                  pNext;
size_t                       codeSize;
const uint32_t*              pCode;

// Count member
typedef struct VkSparseImageMemoryBindInfo {
VkImage                           image;
uint32_t                          bindCount;
const VkSparseImageMemoryBind*    pBinds;
} VkSparseImageMemoryBindInfo;

2.7. Extension Identifier Naming Conventions

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.

2.7.1. Extension Type Names

Types defined by extensions have the author ID appended to the end of the type name.

Example
// VkSurfaceFormatKHR (structure type with KHR appended)
typedef struct VkSurfaceFormatKHR {
VkFormat           format;
VkColorSpaceKHR    colorSpace;
} VkSurfaceFormatKHR;

2.7.2. Extension Enumerant Names

Enumerants defined by extensions have the author ID appended to the end of the enumerant name, separated by an underscore. This includes the begin, end, range and max values added to enumeranted type definitions by the generator scripts.

 There is one exception to this rule in the VK_KHR_sampler_mirror_clamp_to_edge extension. This functionality was included in the original spec, but quickly separated out at release. Due to this late change, the single enum exposed has retained its original identifier to avoid compatibility issues: VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
Example
// VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR (enumerant with _KHR appended)
typedef enum VkCompositeAlphaFlagBitsKHR {
VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR = 0x00000001,
...
} VkCompositeAlphaFlagBitsKHR;

2.7.3. Extension Function Names

Function and function pointer type names defined by extensions have the author ID appended to the end of the name.

Example
// vkDestroySurfaceKHR (function with KHR appended)
VKAPI_ATTR void VKAPI_CALL vkDestroySurfaceKHR(
VkInstance                                  instance,
VkSurfaceKHR                                surface,
const VkAllocationCallbacks*                pAllocator);

typedef void (VKAPI_PTR *PFN_vkDestroySurfaceKHR)(
VkInstance                                  instance,
VkSurfaceKHR                                surface,
const VkAllocationCallbacks*                pAllocator);

2.8. Common Abbreviations

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

Src

Source

Dst

Destination

Min

Minimum

Max

Maximum

Rect

Rectangle

Info

Information

Lod

Level of Detail

Mip

Related to a mipmap. Use “mipmap” in full only when it is a standalone term. If referred to some associating with a mipmap, such as levels, sampling mode, size, tail images, etc., use “mip” as a standalone prefix word, e.g. maxMipLevels, VK_MIP_MODE, etc. This is analogous to the spelling conventions for mip-related terms

 The names mipmapMode, mipmapPrecisionBits, VkSamplerMipmapMode, and VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT are exceptions to this general usage guideline, for historical reasons.
ID

Identifier

UUID

Universally Unique Identifier

Op

Operation

R

Red color component

G

Green color component

B

Blue color component

A

Alpha color component

2.9. Standard Prefixes

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:

VK/Vk/vk

Vulkan namespace
All types, commands, enumerants and C macro definitions in the Vulkan specification are prefixed with these two characters, according to the rules defined above.

PFN/pfn

Function Pointer
Denotes that a type is a function pointer, or that a variable is of a pointer type.

p

Pointer
Variable is a pointer.

vkCmd

Commands that record commands in command buffers
These API commands do not result in immediate processing on the device. Instead, they record the requested action in a command buffer for execution when the command buffer is submitted to a queue.

s

Structure
Used to denote the VK_STRUCTURE_TYPE* member of each structure in sType.

3. API Versions, Extensions, and Layers

This chapter describes required and recommended processes for writing specification language for different core API versions, extensions, and API layers. It is concerned with processes and registration, while fine-grained naming conventions are included in the API Naming Conventions chapter.

 Note The mechanism and process of specifying extensions is subject to change, as we receive feedback from authors and further requirements of documentation tooling. This document will be updated as changes are made.

3.1. Introduction

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

• Avoiding naming collisions between extensions developed by mutually unaware parties, both in the extension names themselves, as well as their token, command, and type names.

• Allocating enumerant values for tokens added by extensions

• Creating a defined order between extensions. Extensions with higher numbers may have dependencies upon extensions with lower numbers, and must define any relevant interactions with lower-numbered extensions.

• Provides a central repository for documentation and header changes associated with extensions

3.2. General Rules/Guidelines

Some general rules to simplify the specific rules below:

• API versions, extensions and layers must each have a globally unique name.

• All commands and tokens must have a globally unique name.

• API versions and extensions can expose new commands, types, and/or tokens, but layers must not.

• However, layers can expose their own extensions, which in turn are allowed to expose new commands and tokens.

• All extensions must be registered with Khronos.

• Extensions in general are strictly additive and backwards-compatible with each other and with the core API. However, as described in more detail the Fundamentals chapter of the Vulkan API Specification, explicit incompatibilities may exist, and must be documented.

3.3. Version, Extension, and Layer Naming Conventions

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

• When specifying extensions and layers to enable in the API.

• As a preprocessor symbol in the vulkan_core.h header file indicating that an extension interface is defined at compile time.

• To control building the Vulkan Specification from asciidoc source containing multiple versions and extensions, by explicitly enabling their inclusion.

 Note Published extensions are documented as part of the master branch of the KhronosGroup/Vulkan-Docs project. They can optionally be included or excluded when generating specifications.

There is a rigid syntax for these names:

• Versions are named with the syntax VK_VERSION_<major>_<minor>.

• Extensions are named with the syntax VK_<author>_<name>.

• Layers are named with the syntax VK_LAYER_<author>_<name> or VK_LAYER_<fqdn>_<name>.

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.

3.3.1. Version, Extension and Layer Name Strings

The <name> portion of version, extension and layer names is a concise name describing its purpose or functionality. The underscore (_) character is used as a delimiter between words. Every alphabetic character of the name must be in lower case.

3.3.2. Author IDs for Extensions and Layers

Extension and layer names also contain an author ID, indicated by <author> above, identifying the author of the extension/layer. This ID is a short, capitalized string identifying an author, such as a Khronos member developing Vulkan implementations for their devices, or a non-Khronos developer creating Vulkan layers. Author IDs must be registered with Khronos.

Some authors have platform communities they wish to distinguish between, and can register additional author IDs for that purpose. For example, Google has separate Android and Chrome communities.

Details on how to register an author ID are provided below. Layer authors not wishing to register an author ID with Khronos can instead use a fully-qualified domain name (FQDN, indicated by <fqdn> above) as the ID. The FQDN should be a domain name owned by the author. FQDNs cannot be used for extensions, only for layers.

• The following are examples of extension and layer names, demonstrating the above syntax:

• Extension names all use the base prefix VK_.

• Khronos-ratified extensions add the reserved author ID KHR and use the prefix VK_KHR_.

• The following author IDs are reserved and must not be used:

• VK - To avoid confusion with the top-level VK_ prefix.

• VULKAN - To avoid confusion with the name of the Vulkan API.

• LAYER - To avoid confusion with the higher-level “LAYER” prefix.

• KHRONOS - To avoid confusion with the Khronos organization.

• Multi-author extensions that have not been ratified by Khronos (those developed via cooperation between, and intended to be supported by two or more registered authors) add the special author ID EXT to the base prefix, and will use the prefix VK_EXT_.

• Traditional author-specific extensions developed by one author (or one author in cooperation with non-authors) add the author ID to the base prefix. For example, NVIDIA will use the prefix VK_NV_, and Valve will use the prefix VK_VALVE_. Some authors can have additional registered author IDs for special purposes. For example, an Android extension developed by Google - but part of an Android open-source community project, and so not a proprietary Google extension - will use the author ID ANDROID.

• Layer names follow the same conventions as extensions, but use the base prefix VK_LAYER_.

• Because layers need not be registered with Khronos, an alternative mechanism is needed to allow creating unique layer names without registering an author ID. Layer authors that prefer not to register an author ID can instead use a fully-qualified domain name (FQDN) in reverse-order as an author ID, replacing . (period) with _ (underscore) characters. The restriction that layer names must be valid C identifiers means that some FQDNs cannot be used as part of layer names.

 Note The KHX author ID was used for experimental extensions, as described in the “Layers & Extensions” appendix of the Vulkan API Specification. As of the initial Vulkan 1.1 public release, all KHX extensions have been promoted to KHR status, and this mechanism is no longer used.
Example
// Core API version name for Vulkan 1.1
VK_VERSION_1_1

// Khronos extension name
VK_KHR_mirror_clamp_to_edge

// Multivendor extension name
VK_EXT_debug_marker

// Vendor extension name using author ID NV

// Vendor layer name using author ID LUNARG
VK_LAYER_LUNARG_vktrace

// Layer name using the FQDN www.3dxcl.invalid instead of an author ID
VK_LAYER_invalid_3dxcl_www
 Note To avoid linking to a nonexistent domain, the reserved TLD .invalid is used in the example above.

3.4. Extension Command, Type, and Token Naming Conventions

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.

3.5. The Vulkan Registry

The canonical definition of the Vulkan APIs is kept in an XML file known as the Vulkan registry. The registry is kept in xml/vk.xml in the master branch 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.

3.6. Registering an Author ID with Khronos

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

3.7. Registering a Vendor ID with Khronos

Vulkan implementers 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 master 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 a Vulkan implementation and require one for that purpose.

3.8. Registering Extensions and Layers

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

• Receiving an extension number.

• Adding the extension or layer name to the list in vk.xml and appearing on the Khronos registry website, which will link to associated documentation hosted on Khronos.

• For extensions which add to the Vulkan API, including definitions of those additions to vk.xml.

Registration for Khronos members is handled by filing a merge request in the internal gitlab repository against the branch containing the core specification against which the extension or layer will be written. The merge must modify vk.xml to define extension names, API interfaces, and related information. Registration is not complete until the registry maintainer has validated and accepted the merge.

Since this process could in principle be completely automated, this suggests a scalable mechanism for accepting registration of non-Khronos extensions. Non-Khronos members who want 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:

• Acquire an extension number. This is done by proposing a merge request against vk.xml similarly to how author IDs are reserved. The merge should add a new <extension> tag at the end of the file with attributes specifying the proposed extension name, the next unused sequential extension number, the author and contact information (if different than that already specified for the author ID used in the extension name), and finally, specifying supported="disabled". The extension number will be reserved only once this merge request is accepted into the master branch.

• Develop and test the extension using the registered extension number.

• Publish the extension to Khronos using the previously registered extension number, by submitting merge requests to the master branch defining the changes specific to the extension. Changes to both the specification source, and to vk.xml will be needed.

• Extension changes to the specification source must be protected by asciidoc conditionals as described in the Documenting Extensions section.

• Changes to vk.xml must define the extension interfaces in the <extension> block, and must also change the supported attribute value of the <extension> to supported="vulkan".

• When publishing an extension, mark it as enabled by proposing a merge to the master branch changing the supported attribute value of the <extension> to supported="vulkan". This should be completely automated and under the control of the publishers, to allow them to align publication on Khronos with product releases. However, complete automation might be difficult, since steps such as regenerating and validating the Vulkan header files are involved. Once the merge is accepted and the corresponding updated header with the new extension interface is committed to the master branch, publication is complete.

• Publishing on the Khronos public GitHub repository is preferred whenever possible. Khronos members may instead create branches on Khronos' internal gitlab server, but those branches will eventually be mirrored to GitHub.

• Once the merge request defining an extension has been accepted into the master branch, publication is complete - although it may not be visible on GitHub until the next regular core Specification update is pushed out.

• It is still possible to publish a separate branch of the repository with appropriate changes relative to the core Vulkan API branch instead, but this approach is deprecated and discouraged. If this is done, all changes to vk.xml must still be made in the master branch.

3.9. Documenting API Versions and Extensions

API versions and extensions are documented as modifications to the Vulkan specification. Changes specific to a version or extension are protected by asciidoc conditionals. The changes are only visible in generated documentation when the Specification is built with an asciidoc attribute of that name defined.

For example, the VK_KHR_surface extension is now documented in the master branch of the GitHub KhronosGroup/Vulkan-Docs project. However, specifications generated from this branch will only include the extension when the Makefile is invoked appropriately.

3.9.1. Changes for New Extensions

Most language defining extensions can be localized either into a small number of asciidoc include files which are conditionally included in the core specification chapters and appendices, or into parts of vk.xml defining the extension interfaces.

 Note We do not yet fully document an example of including a new version or extension. New versions are authored only by Khronos and examples will be available at such time that we publish a new version. Extension authors should refer to the master branch and search for the names of existing extensions, such as VK_KHR_surface, for markup examples. Some aspects of the changes for this example extension are described below.

Changes for extensions include (but may not be limited to) the following:

• All extensions must add an appendix to the Vulkan specification. The appendix should be modeled after the VK_KHR_shader_draw_parameters extension in appendices/VK_KHR_shader_draw_parameters.txt, which contains metainformation about the extension (as well as code examples, and revision history). This example is complicated because VK_KHR_shader_draw_parameters has a variety of external dependencies and interactions. The VK_EXT_debug_marker extension is a simpler, standalone example.

• In the preamble to the appendix, start with an asciidoc include of the automatically generated meta information. This information includes the extension name string, type, number, revision, and contact information from vk.xml.

• Following the include, add as many of the following sections as are meaningful:

• Status - Complete, Draft, or other. When an extension is published in the master branch, it is normally assumed to be complete; the Status field should be removed at this time, unless it contains additional information.

• Last Modified Date - if wanted, although git log queries can provide equivalent information.

• IP Status - Such as No known IP claims.

• Interactions and External Dependencies - may include requirements or interactions with optional Vulkan features, SPIR-V (SPV) and OpenGL extensions, and interactions (other than strictly requiring) with other Vulkan extensions.

• Contributors - Names and corporate affiliations of people who have made significant direct contributions to this extension.

• Each extension’s appendix file is automatically included from appendices/extensions.txt via code generated from vk.xml. It is no longer necessary to explicit include the appendices.

• Extensions usually make significant additions and changes to the Vulkan specification. They often add an entirely new chapter, or a new section of an existing chapter, defining the new functions, structures, and enumerants. For example, in the case of VK_EXT_debug_marker, it adds a new section of the “Debugging” chapter in chapters/debugging.txt, by including in that file:

Example Markup
ifdef::VK_EXT_debug_marker[]
include::chapters/VK_EXT_debug_marker/wsi.txt[]
endif::VK_EXT_debug_marker[]
• In every other place where the extension alters the behavior of the core Specification, make such changes and protect the modifications with the same asciidoc conditionals. For example, VK_KHR_surface adds new error codes to Vulkan. These are added to chapters/fundamentals.txt in the “Return Codes” section as follows:

Example Markup
... list of existing error codes
ifdef::VK_KHR_surface[]
include::VK_KHR_surface/VkResultErrorDescriptions_surface.txt[]
endif::VK_KHR_surface[]
• If two extensions interact, the asciidoc conditionals must be carefully structured so as to properly document the interactions if the specification is built with both extensions. Asciidoc conditionals allow "and" and "or" constructs (see: http://asciidoctor.org/docs/user-manual/#conditional-preprocessor-directives and http://asciidoctor.org/docs/user-manual/#checking-multiple-attributes-ifdef-and-ifndef-only).

Example Markup
ifdef::VK_KHR_foo[]
... discussion of VK_KHR_foo ...
ifdef::VK_KHR_fum[]
... discussion of interactions between VK_KHR_foo and VK_KHR_fum ...
endif::VK_KHR_fum[]
endif::VK_KHR_foo[]

ifdef::VK_KHR_fum[]
... discussion of VK_KHR_fum ...
endif::VK_KHR_fum[]
• In cases where a new extension (A) modifies both core and an existing extension (B), if the new extension (A) becomes part of the core at a future release (i.e. is no longer an extension), the portion of the new extension that modified the existing extension (B) effectively becomes part of that existing extension. Thus, at the new core release, enabling the pre-existing extension (B) also enables the functionality that was previously enabled by enabling the previously-new extension (A).

• For vendor extensions, changes made to existing core Specification source files and to vk.xml all fall under the Contributor License Agreement. Vendors may use their own copyright on new files they add to the master branch, although that copyright must be compatible with the Specification copyright.

• In most cases, there will be at most two new files added to the specification: extensions/extension_name.txt, and chapters/extension_name.txt. If you need more than one new file in either the chapters/ or extensions/ directories, create a subdirectory named with the extension name and place the new files there. For example, instead of chapters/VK_KHR_android_surface.txt, there is chapters/VK_KHR_android_surface/platformCreateSurface_android.txt and chapters/VK_KHR_android_surface/platformQuerySupport_android.txt, both of which are conditionally included elsewhere in the core specification files.

• Valid Usage statements referring to interactions between structures in a pNext chain must be described in the parent structure’s language, as specified in more detail below.

• Valid Usage statements must be kept atomic with regards to extension conditionals - do not surround part of a single statement with conditionals. Valid usage statements are automatically extracted from the specification for use by ecosystem components like the validation layers, and the extraction scripts need to know which valid usage statements apply to which extensions. The loops required to deal with partial statements are simply not worth the trouble. For example, instead of

Example Markup
  * If pname:buffer was created with a sharing mode of
ename:VK_SHARING_MODE_EXCLUSIVE, pname:srcQueueFamilyIndex and
pname:dstQueueFamilyIndex must: either both be
ename:VK_QUEUE_FAMILY_IGNORED, or both be a valid queue family (see
<<devsandqueues-queueprops>>)
ifdef::VK_KHR_external_memory[]
unless one of them is ename:VK_QUEUE_FAMILY_EXTERNAL_KHR and the other
is ename:VK_QUEUE_FAMILY_IGNORED.
endif::VK_KHR_external_memory[]

Use

Example Markup
  * If pname:buffer was created with a sharing mode of
ename:VK_SHARING_MODE_EXCLUSIVE, pname:srcQueueFamilyIndex and
pname:dstQueueFamilyIndex must: either both be
ename:VK_QUEUE_FAMILY_IGNORED, or both be a valid queue family (see
<<devsandqueues-queueprops>>)

3.9.2. Changes for New API Versions

When creating a new version of the core API, such as Vulkan 1.1, changes are done similarly to extensions, with the following differences:

 Note This list is being developed in conjunction with the Vulkan 1.1 Specification, is probably incomplete, and is subject to change. Items marked TBD are still being discussed within the Vulkan Working Group.
• New API versions will be more tightly integrated into the specification sources than extensions, although it’s still helpful to partition changes into new files when they’re sufficiently self-contained.

• New API versions must add an appendix to the Vulkan specification. Unlike the extension appendices, this appendix simply summarizes release information (dates of Ratification by the Khronos Board of Promoters, and of public release), the contributor list, and high-level descriptions of new features in this version (including the names of any extensions promoted to core status in this version).

• TBD - we might choose to include a new API summary with links into the spec body for new features, as well.

• TBD - how to name and where to include this appendix file.

• Changes to the Specification for new versions will range from small changes to existing language, to new commands and structures, to adding entire new chapters. New chapters must be defined in separate files under the chapters/ directory, and included at an appropriate point in vkspec.txt or other specification source files. Other changes and additions are included inline in existing chapters.

• All changes that are specific to the new version must be protected by the asciidoc conditional (e.g. the version name). For example, in the case of Vulkan 1.1:

Example Markup
Add a new chapter:

ifdef::VK_VERSION_1_1[]
include::chapters/newchapter11.txt[]
endif::VK_VERSION_1_1[]

ifdef::VK_VERSION_1_1[]
... language describing the new command, structure, or enumeration
endif::VK_VERSION_1_1[]
• The specification must continue to be a valid document when the new version is not defined, so that (for example) the Vulkan 1.1 branch specification can continue to be updated.

• TBD - how to deprecate extensions which have been promoted to core status in the new version, while continuing to have those extensions appear then older versions of the specification are being built.

• The same constraints described above for Valid Usage statements modified by extensions apply for new versions.

3.10. Assigning Extension Token Values

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

 Note Typically, extensions use a unique offset for each enumeration constant they add, yielding 1000 distinct token values per extension. Since each enumeration object has its own namespace, if an extension needs to add many enumeration constant values, it can reuse offsets on a per-type basis.

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

• The extension name (e.g. VK_KHR_swapchain) that is adding the new enumeration constant.

• The existing enumeration type being extended (e.g. VkStructureType).

• The name of the new enumeration token being added (e.g. VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR).

• The offset, which is an integer between 0 and 999 relative to the base being used for the extension.

• The direction may be specified to indicate a negative value (dir="-") when needed for negative VkResult values indicating errors, like VK_ERROR_SURFACE_LOST_KHR. The default direction is positive, if not specified.

Implicit is the registered number of an extension, which is used to create a range of unused values offset against a global extension base value. Individual enumerant values are calculated as offsets in that range. Values are calculated as follows:

• base_value = 1000000000

• range_size = 1000

• enum_offset(extension_number, offset) = base_value + (extension_number - 1) × range_size + offset

• Positive values: enum_offset(extension_number, offset})

• Negative values: enum_offset(extension_number, offset})

The exact syntax for specifying extension enumerant values is defined in the readme.pdf specifying the format of vk.xml, and extension authors can also refer to existing extensions for examples.

If an extension becomes part of core, the enumerant values should remain the same as they were in the original extension, in order to maintain binary compatibility with existing applications.

Enumerants which define bitmask values are a special case, since there are only a small number of unused bits available for extensions. For core Vulkan API and KHR extension bitmask types, reservations must be approved by a vote of the Vulkan Working Group. For EXT and vendor extension bitmask types, reservations must be approved by the listed contact of the extension. Bits are not reserved, and must not be used in a published implementation or specification until the reservation is merged into vk.xml by the registry maintainer.

3.11. Required Extension Tokens

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

• VK_EXTNAME_SPEC_VERSION is an integer constant which is the revision of the extension named VK_extname (EXTNAME is all upper-case, while extname is the capitalization of the actual extension name). This value begins at 1 with the initial version of an extension specification, and is incremented when changes are made. Note that the revision of an extension defined in the Vulkan header files and the revision supported by the Vulkan implementation (the specVersion field of the VkExtensionProperties structure corresponding to the extension and returned by one of the extension queries) may differ. The revision value indicates a patch version of the extension specification, and differences in this version number maintain full compatibility, as defined in the API Version Numbers and Semantics section of the Vulkan API Specification.

 Note Any changes requiring the addition or removal of a type or command should be done by creating a new extension. The resulting extension should take care to include the appropriate dependency information on the original extension.
 Note When the Debug Report extension (VK_EXT_debug_report) was recently updated to include the enum values of VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_KHR_EXT and VK_DEBUG_REPORT_OBJECT_TYPE_DISPLAY_MODE_KHR_EXT, we violated this policy. That change was done prior to this revision policy clarification. From this point forward, we intend to follow this policy.
• VK_EXTNAME_EXTENSION_NAME is a string constant which is the name of the extension.

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

#define VK_KHR_SURFACE_SPEC_VERSION 24
#define VK_KHR_SURFACE_EXTENSION_NAME "VK_KHR_surface"

3.12. Extension Handles, Objects, Enums, and Typedefs

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.

Conversion of Handle to VkObjectType Examples:
 VkSurfaceKHR                  -> VK_OBJECT_TYPE_SURFACE_KHR
VkDescriptorUpdateTemplateKHR -> VK_OBJECT_TYPE_DESCRIPTOR_UPDATE_TEMPLATE_KHR
 Note Application developers are encouraged to be careful when using switch statements with Vulkan API enums. This is because extensions can add new values to existing enums. The use of a default: statement, within a switch, may avoid future compilation issues.

3.13. Extension Function Prototypes

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.

 Note Based on feedback from implementers, Khronos expects the Android, Linux, and Windows Vulkan SDKs to include our header files, and export the supported WSI functions for those platforms from their loader libraries. Other implementations can make different choices for their headers and loader libraries, but are encouraged to be consistent with these implementations.

3.14. Accessing Extension Functions from Programs

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.

 Note The Vulkan API loader for Android, Linux, and Windows exports functions for all core Vulkan API commands, and for a set of WSI extension commands that are applicable to those operating systems (see Vulkan loader documentation for the relevant platform/OS for details). The WSI functions are considered special, because they are required for many applications.

3.15. Extension Interactions

Extensions modifying the behavior of existing commands should provide additional parameters by using the pNext field of an existing structure, pointing to a new structure defined by the extension, as described in the “Valid Usage” section of the Vulkan API Specification. Extension structures defined by multiple extensions affecting the same structure can be chained together in this fashion. Any structure which can be chained in this fashion must begin with the following two members:

VkStructureType        sType;
const void*            pNext;

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 defined by the extension, but this approach is discouraged and should not be used.

When chaining multiple extensions to a structure, the implementation will process the chain starting with the base parameter and proceeding through each successive chained structure in turn. Extensions should be defined to accept any order of chaining, and must define their interactions with other extensions such that the results are deterministic. If an extension needs a specific ordering of its extension structure with respect to other extensions in a chain to provide deterministic results, it must define the required ordering and expected behavior as part of its specification.

Validation of such extended structure chains is automatically generated from the registry, as described in the description of structextends in the registry document.

3.16. Valid Usage and Extension pNext Chains

When there is a Valid Usage interaction between a parent structure and another 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 chained structure, and must be protected by appropriate extension-specific ifdef constructs.

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

Example Markup
// CORRECT: define interaction with children in parent VkImageCreateInfo
// structure
ifdef::VK_NV_external_memory+VK_KHR_external_memory[]
* If the pname:pNext chain contains an instance of
slink:VkExternalMemoryImageCreateInfoNV, it must: not contain an
endif::VK_NV_external_memory+VK_KHR_external_memory[]

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

Example Markup
// WRONG! Do not define interaction with parent in child
// VkDedicatedAllocationBufferCreateInfoNV structure
* If pname:dedicatedAllocation is ename:VK_TRUE,
sname:VkBufferCreateInfo::pname:flags must: not include
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT,
ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or
ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT

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

Example Markup
// REWRITTEN CORRECTLY: Define interaction with child in
// parent VkBufferCreateInfo structure
ifdef::VK_NV_dedicated_allocation[]
* If the pname:pNext chain contains an instance of
pname:dedicatedAllocation member of the chained structure is
ename:VK_TRUE, then pname:flags must: not include
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT,
ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or
ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT
endif::VK_NV_dedicated_allocation[]

4. Markup Style

This chapter demonstrates Asciidoc and Specification structure, including text layout and markup style.

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 (see section 19 of the Asciidoctor User Manual) 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 asciidoc delimiters. Using a mix of one-line and two-line titles causes compatibility issues, and using the two-line title form implicitly sets syntax compatibility mode.

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.

Example Markup
[[markup]]
= Markup Style

[[markup-sample-section]]
== Sample Section

4.1. Sample Section

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.

4.2. Asciidoc Markup And Text Layout

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 asciidoc markup).

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

 Example Markup An — em-dash → 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 × asciidoc 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.

See section 40 of the Asciidoctor User Manual 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.

• In some cases, limitations of asciidoc markup may result in lines that are longer than 76 characters and cannot easily be shortened without compromising the output documents.

4.2.1. Blocks

There are a variety of asciidoc block constructs. With the exception of tables and of open blocks used to group markup together, blocks should be delimited by exactly four repeated characters indicating the block type, for consistency. The block types and delimiters are shown in the following table.

Table 3. Asciidoc Block Delimiters

Open

--

Example

====

For Notes

Passthrough

++++

For some kinds of math markup

Comment

////

Listing

----

For source code listings

Sidebar

****

Table

|====

For tables

Quote

____

Currently unused in the Vulkan Specification

Literal

…​.

Currently unused in the Vulkan Specification

4.2.2. Footnotes

Use manually marked-up footnotes (the asciidoc footnote construct is OK for PDF outputs, but does not work well with long HTML documents since it places all footnotes at the end of the document).

Refer to footnotes with asciidoc superscript notation1, and mark up the footnotes below, but near the references as labelled lists. Manually assigned footnote numbers will inevitably be reused, which is OK as long as the colliding numbers are not in the same section.

1

Like this example footnote.

 Example Markup See reference^2^ 2:: Reference 2. → See reference2 2 Reference 2.

4.2.3. Lists

Bullet Lists and Continuation Blocks
• Bullet lists are the preferred form of list, aside from glossary definitions.

• Lists should have text indented by 4 spaces and the list item delimiter (e.g. one or more asterisks, for bullet lists) indented by two spaces.

Note that continuation blocks for list items longer than one paragraph cannot be indented, only the first paragraph.

In general, successive list items should not be separated by white space. However, list continuation blocks should be followed by a + on a line by itself, or by a blank line, due to limitations of the asciidoc parser.

• Indent bullet lists two spaces (to the bullet), 4 spaces (to the text, if it extends over multiple lines). This lets us visually distinguish lists from other kinds of markup.

• Nested lists should align the leftmost list item delimiter (bullet, etc.) with the parent delimiter.

Example Markup
  * This is the first item in a bullet list.
* The second item is described with two paragraphs.
The second paragraph is in a continuation block:
+
This is a continuation block containing the second paragraph,
+
** This is a nested list item for the second item.
Since it follows a continuation block, it must be separated by a blank
line or + from that block.
• This is the first item in a bullet list.

• The second item is described with two paragraphs. The second paragraph is in a continuation block:

This is a continuation block containing the second paragraph,

• This is a nested list item for the second item. Since it follows a continuation block, it must be separated by a blank line or + from that block.

• It’s possible to continue a paragraph of the first bullet after a list of sub-bullets if so desired by using continuations in a similar fashion:

Example Markup
  * This an item in a bullet list.
+
** This is a nested list item for the second item.
Since it follows a continuation block, it must be separated by a blank
line or + from that block.
+
This is a continuation of the first bullet
• This an item in a bullet list.

• This is a nested list item for the second item. Since it follows a continuation block, it must be separated by a blank line or + from that block.

This is a continuation of the first bullet

Labelled Lists

Labelled lists may be used in some cases such as footnotes; glossary entries; and long lists of information about similar names, such as the “Features, Limits, and Formats” chapter of the Vulkan Specification. Whenever labelled lists are used the label and its terminating double colon must be alone on a line, followed by the contents of that list entry.

For consistency do not use labels ending in three or four colons, or two semicolons, even though these forms are allowed in asciidoc markup.

Example Markup
Glossary Entry::
This is a glossary entry.

2016-02-16
Numbered Lists

Numbered lists may be used if strictly necessary to place an ordering on list items. Always use implicit numbering, with the bullet point being a single period.

1. Explicit numbering with a number preceding the period is prone to accumulating errors as edits are made.

2. In addition, the markup is harder to recognize for scripts and tools (other than asciidoc itself) operating on the document source.

Example Markup
. First list item.
. Second list item.
. Etc.

4.2.4. Anchors and Cross-references

In general, chapters and sections should always have anchors, following the naming convention discussed above. Anchors to other sections of the document may be inserted as needed. In addition, the autogenerated include files defining commands, structures, enumerations and flags all define anchors whose name is the name of the command or type being defined, so it is easy to link to a (for example) a command name such as vkCreateCommandPool. However, using the markup macros described below is preferred when linking to anchors corresponding to API names, such as vkCreateCommandPool.

If you want a cross-reference to an anchor to appear as something other than the raw anchor name, always make sure to include that text as part of the cross-reference. There are several different toolchains followed for various forms of asciidoc output, and not all of them treat anchors without alt-text the same way.

Example Markup
In general, chapters and sections should always have anchors, following the
naming convention <<markup,discussed above>>.
...
so it is easy to link to a (for example) a command name such as
<<vkCreateCommandPool,vkCreateCommandPool>>. However, using the
<<markup-macros,markup macros>> described below is preferred when linking to
anchors corresponding to API names, such as flink:vkCreateCommandPool.

4.2.5. Tables

Asciidoc tables should use the block prefix |====. Where feasible, align the | separating cells across rows. This will sometimes result in very wide tables in the source document, but makes it easier to see which cells belong to which column. Alternatively, long cells can be broken onto a separate line with the | separator appearing first, except for the first row of the table, which must all appear on a single line.

Tables should usually be preceded with a short title.

Example Markup
.Normative Terminology Macros
|====
| Macro Name     | Output
| can{cl}        | can:
| cannot{cl}     | cannot:
|====

4.2.6. Figures

All figures (images) must be marked up as follows, to ensure there is an anchor and that the figure is given a caption which shows the figure number and is added to the list of figures:

Example Markup
[[fig-anchorname]]
image::images/imagename.svg[align="center",title="Figure caption",opts="{imageopts}"]

There must be SVG versions of each figure checked into the images/ directory, to support generating both HTML and PDF outputs. The PDF generation pipeline is now able to use SVG images, so PDF versions of each image are no longer required. The opts= attribute defaults to inline, which decreases output image size in the generated HTML. However, the inline option interferes with generating HTML diffs between two specifications with the script we currently use. By using an asciidoctor attribute, this behavior can be controlled.

Asciidoctor restricts captions in figures to be a single line in the source document. If a longer caption is required, follow the figure directive with a sidebar block including the full caption preceded by a link to the figure:

Example Markup
.Caption
****
In the <<fig-anchorname,Figure caption>> diagram, the diagram represents
... long caption text here.
****

4.3. Markup Macros and Normative Terminology

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

4.3.1. API Markup Macros

These macros must be used to tag command, structure, enumeration, enumerant, and other Vulkan-specific names so they can be rendered in a distinctive fashion, link to definitions of those names, and be easily searched for in the source documents. The validation scripts (make allchecks output) also rely on these macros being used consistently and correctly. The API markup macros, with examples of their use, are in the following table:

Table 4. API Markup Macros
Macro Name Usage and Meaning

Generates a cross-reference or link to the definition of the command name in the macro argument. Example: flink:vkCreateCommandPool → vkCreateCommandPool.

fname:

Formats the macro argument like flink:. Does not generate a cross-reference. Example: fname:vkCreateCommandPool → vkCreateCommandPool.

Only use this macro when necessary.

ftext:

Formats the macro argument like fname:. May contain asterisks for wildcards. Not validated. Example: ftext:vkCmd* → vkCmd*.

Only use this macro when necessary.

Generates a cross-reference or link to the definition of the structure or handle in the macro argument. Example: slink:VkMemoryHeap → VkMemoryHeap.

sname:

Formats the macro argument like slink:. Does not generate a cross-reference. May also be an abstract structure or handle name. Example: sname:VkCommandPoolCreateInfo → VkCommandPoolCreateInfo.

Only use this macro when necessary.

stext:

Formats the macro argument like sname:. May contain asterisks for wildcards. Not validated. Example: stext:Vk*CreateInfo → Vk*CreateInfo.

Only use this macro when necessary.

Formats the macro argument as a Vulkan enumerated type name and links to the definition of that enumeration type. Example: elink:VkResult → VkResult.

ename:

Formats the macro argument as a Vulkan enumerant name. Example: ename:VK_EVENT_SET → VK_EVENT_SET. Note that this is not related to elink:, unlike the other macro link:/text: pairings.

etext:

Formats the macro argument like ename:. Not validated. Examples: etext:_RANGE_SIZE → _RANGE_SIZE, etext:VK_IMAGE_CREATE_SPARSE_* → VK_IMAGE_CREATE_SPARSE_*

Only use this macro when necessary.

pname:

Formats the macro argument as a Vulkan parameter or structure member name. Example: pname:device → device.

ptext:

Formats the macro argument like pname:. May contain asterisks for wildcards. Not validated. Example: ptext:sparseResidency* → sparseResidency*.

Only use this macro when necessary.

Generates a cross-reference or link to the definition of the Vulkan type in the macro argument. Example: tlink:PFN_vkAllocationFunction → PFN_vkAllocationFunction. This is only used for function pointer and Vk*Flags types at present, although it is a potentially a catch-all for other types not covered by a more specific macro.

tname:

Formats the macro argument like tlink:. Does not generate a cross-reference. Example: tname:PFN_vkAllocationFunction → PFN_vkAllocationFunction.

Only use this macro when necessary.

Generates a cross-reference or link to the definition of the Vulkan C macro in the macro argument. Example: dlink:VK_NULL_HANDLE → VK_NULL_HANDLE. There are only a few macros in the Vulkan API, described in the “API Boilerplate” appendix of the Vulkan API Specification

dname:

Formats the macro argument like dlink:. Does not generate a cross-reference.

Only use this macro when necessary.

basetype:

Formats the macro argument like a basic scalar type or API handle name. Not validated. Examples: basetype:VkBool32 → VkBool32, basetype:VkDeviceSize → VkDeviceSize.

code:

Formats the macro argument as a code sample. Used for SPIR-V keywords, builtin C types, and names belonging to other APIs such as Linux or Windows system calls. Examples: code:uint32_t → uint32_t, code:ClipDistance → ClipDistance.

When referring to a compound name (function-parameter, or structure-member), combine the macros separated by two colons, resulting in vkCmdBindIndexBuffer::indexType and VkMemoryHeap::flags. This is often done when referring to a particular parameter or member in a part of the document other than the description of the corresponding function or structure.

Example Markup
flink:vkCmdBindIndexBuffer::pname:indexType
slink:VkMemoryHeap::pname:flags
When To Use *name: Macros

Only use the fname:, sname:, tname:, and dname: macros if no definition of the target type with a corresponding anchor exists in the document. Anchors are automatically defined when including the generated API interface definitions under api/…​/*txt. If an anchor does exist, use the corresponding *link: macro.

 Note There are many legacy uses of the *name: macros that will be replaced over time. These uses date from before anchors were added to the generated API definitions.
When To Use *text: Macros

Only use the ftext:, stext:, etext:, and ptext: macros when describing something that should be rendered like a command, structure, enumerant, or parameter name, respectively, but is not actually one. Typically these macros are used for wildcards describing multiple API names with common prefixes or suffixes, or common subsets of API names.

Other Markup

Uses of standard Asciidoc markup are less common. Occasional asterisk markup is used for emphasis. Underscores are used for glossary terms. Backtick markup is used for the C NULL macro.

Example Markup
*emphasis*
NULL
Glossary Terms

Glossary terms are currently marked up using underscore markup where they are defined in the documents, as well as being added to the formal Glossary appendix in the Vulkan API Specification. However, we will probably change to using custom macros soon, to enable linkage between the glossary and definitions in the spec body.

Example Markup
_Glossary terms_

4.3.2. Normative Terminology

Normative terminology is precisely defined in section 1.3 of the Vulkan API Specification, and is used to visually tag terms which express mandatory and optional behavior of Vulkan implementations, and of applications using Vulkan.

Whenever one of these terms appears in the Vulkan API Specification outside of an informative section, it must be tagged using the macros, to indicate that its use has been carefully considered and is consistent with the definitions in section 1.3. This is extremely important for determining IP that is in and out of Scope during Ratification reviews. The normative terminology macros are defined in the following table:

Table 5. Normative Terminology Macros
Macro Name Output

can:

can

cannot:

cannot

may:

may

may: not

may not

must:

must

must: not

must not

optional:

optional

optionally:

optionally:

required:

required

should:

should

should: not

should not

Note that the macros are lower-case only, so language should be written such that these terms do not appear at the beginning of a sentence (if really necessary, additional capitalized macros could be added).

Optional Behavior

If a described behavior of the implementation is not necessary for conformance, use the terms may: or optional: to describe it.

If a described usage pattern by the application is allowed but not necessary, use the term can: to describe it.

If language flows more logically using the term "may not", use the term may: not to describe it.

Optional Functionality

If functionality (rather than behavior) is optional, it should be described as

Example Markup
not required:

Implementations are not mandated to support functionality which is not required, but if they do, they must behave as described by the Vulkan API Specification. The term functionality includes API features, extensions, and layers.

4.4. Informative, Editing and Implementor’s Notes

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

4.4.1. Informative Notes

Informative notes always appear as part of the document, but are considered non-normative. They usually describe usage advice for applications, and are always given the title Note, as in the following example:

 Note This is an informative note.
Example Markup
[NOTE]
.Note
====
This is an informative note.
====

If an entire chapter or section is considered informative, it should begin with the sentence:

Example Markup
This chapter/section is Informative.

4.4.2. Editing Notes

Editing notes usually only appear in internal (non-published) versions of documents, via asciidoc conditionals. If they are not resolved, or are internal issues that should not be visible in public, they should be removed from the source before pushing content to the canonical GitHub repository. They usually tag places where an outstanding Gitlab/GitHub issue is being worked, and are always given the title editing-note, as in the following example:

Example Markup
ifdef::editing-notes[]
[NOTE]
.editing-note
====
Contents of an editing note go here.
It is good practice to include a Gitlab/GitHub issue number, or link to the
issue, in the editing note.
====
endif::editing-notes[]

4.4.3. Implementor’s Notes

Implementor’s notes may or may not appear in published versions of documents, via asciidoc conditionals. They describe suggested approaches or guidelines for people writing Vulkan implementations, and are rare because the hardware being targeted varies so widely. They are always given the title Implementor’s Note, as in the following example:

Example 1. Implementor’s Note

This is an implementor’s note, marked up as follows:

Example Markup
ifdef::implementation-guide[]
.Implementor's Note
====
Contents of an implementor's note go here.
====
endif::implementation-guide[]

4.5. Word Choices

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.

Table 6. Word Choices

allocate

create

When describing objects or memory resulting from vkAllocate* commands.

application

client

bit field

Technically correct. Vulkan bitmasks are just integers and are not logically addressable at the bit level.

bound

currently bound

Appears primarily in valid usage statements, which are always referring to the current state of the objects they are validating. Rare exceptions may be justified in other cases.

command

function

Except when talking about function pointers returned by vkGet*ProcAddr commands.

create

allocate

When describing objects resulting from vkCreate* commands.

depth/stencil

packed (interleaved, combined, other prefix) depth/stencil, depth-stencil, DepthStencil, etc.

Combined format implicit in the name.

device

GPU / processor / accelerator

The Vulkan specification is functional and could be implemented in many different ways.

heterogeneous

heterogenous

More common

homogeneous

homogenous

More common

host

CPU

host endianness

platform endianness

image subresource

subresource

Except when referring to host-accessible subresources

implementation

system / hardware / software

For consistency, and avoids implied requirements.

indices

indexes

More common

member

field

enumerant specifies

enumerant indicates (denotes)

When giving a brief description of enums in an enumerated type. It is often appropriate to use “enumerant is” when describing the behavior or meaning of enumerants in other places.

parameter are/is

parameter specifies (denotes, indicates)

In cases when are or if are not grammatically appropriate, specifies may be used instead.

parameter is

the value of parameter is

In rare cases, the value of is appropriate. See the existing specification language for examples.

begins / begun

starts / started

For vkBegin* - also see “finish”

finishes / finished

ends / ended

For vkEnd* - also see “begins”

used

referenced

When describing attachments specified in a subpass description.

statically used

referenced

When describing resources or push constants accessed by shader code

a more specific term

referenced

For all other situations.

component

channel

Specifically this refers to color channels/components

 Note The “begin/start” and “end/finish” distinction is still being sorted out. See Gitlab issue #61.

4.5.1. Avoid Contractions

Contractions make the specification sound less formal and using them would be inconsistent with the many non-contraction forms already in use in the spec.

Table 7. Word Choices

are not

aren’t

cannot:

can’t

does not

doesn’t

do not

don’t

has not

hasn’t

is not

isn’t

it is

it’s

that is

that’s

there is

there’s

we are

we’re

will not

won’t

4.5.2. Terms to Use With Caution

The term subset is sometimes used to refer to a strict subset, and sometimes used to refer to a subset which may be equal to the entire set. This is particularly likely to come up when describing bitmasks. Make sure to use either subset or strict subset as appropriate.

4.5.3. Terms to Avoid

Do not describe anything in the documentation using vague or wishy-washy terms. Our goal is to precisely describe behavior of implementations.

The normative terms may:, optional:, and should: are available when implementations may make choices of behavior, but when such choices are allowed, each choice still must have well-defined behavior.

Table 8. Terms to Avoid

expect

And variants such as expected

likely

And variants such as will likely

allowed, could, generally, might, probably, perhaps

And all other such terms of choice. Use may: or can: depending on the context.

may: or may: not

Just use may:.

5. Writing Style

5.1. Miscellaneous Grammar, Spelling, and Punctuation Issues

5.1.1. Use the Oxford Comma (Serial Comma)

When writing a sentence listing a series of items, include a comma before the “and” separating the last item.

Correct: The red, green, blue, and alpha components.

Incorrect: The red, green, blue and alpha components.

5.1.2. Date Format

Whenever possible, write dates in the ISO 8601 format: YYYY-MM-DD.

If needed for consistency with existing dates, e.g. in appendix changelogs, you can also write “Month DD, YYYY” where “Month” is the English name of the month.

Never use ambigious formats such as “09/12/16”.

Example Markup
  * 2016-09-12
* September 12, 2016

5.1.3. A/An and Markup Macros

Use “a” and “an” correctly, based on the sound of the letter beginning the following word.

It is easy to get this wrong when talking about Vulkan API names tagged with the markup macros. For example, if you wanted to say:

A VK_ERROR_DEVICE_LOST error

the correct way to mark this up in asciidoc would be:

A ename:VK_ERROR_DEVICE_LOST error

However, on first glance at this it appears wrong, because the “word” following “a” is the macro name, “ename:”. That starts with a vowel, so the temptation is to say

An ename:VK_ERROR_DEVICE_LOST error may occur.

What matters here is how the output document is formatted.

5.1.4. Numbers in Text

When describing the need for a small number of objects, smaller than ten, spell the number out (e.g. “one”). If you are describing a literal value that is a small number, you may use a numeric value (e.g. “1”).

For example, instead of writing that a bitmask “contains 1 or more bits”, write that it “contains one or more bits”. A counter example is that it is okay to write “For non-stereoscopic-3D applications, this value is 1.”

5.1.5. Use American Spelling Conventions

In case of conflict, use American rather than British spelling conventions, except for noted exceptions in the table below.

Table 9. Spelling

color

colour

signaled

signalled

tessellation

tesselation

Historical exception

5.1.6. Describing Properties of Array Elements

Many Vulkan parameters are arrays, or pointers to arrays. When describing array elements, use the terminology “each element” when the description applies uniformly and independently to every element of the array. For example:

Example Markup
  * Each element of the pname:pCommandBuffers member of each element of
pname:pSubmits must: be in the <<commandbuffers-lifecycle, pending or
executable state>>.

Use the terminology “any element” when the description is of zero or more elements of the array sharing a property. For example:

Example Markup
  * If any element of the pname:pCommandBuffers member of any element
of pname:pSubmits was not recorded with the
ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT, it must: not be in
the <<commandbuffers-lifecycle, pending state>>.

Never use the redundant terminology “any given element”.

5.1.7. Compound Words and Preferred Orthography

Unless there is longstanding precedent in computer science literature, or the word is a noted exception in the table below, do not arbitrarily cram terms together.

This does not apply to parameter names in the API, where capitalization is used to distinguish words. For example, it is proper to refer to the use of a colorSpace member of a structure as a “color space” value.

Table 10. Spelling

bit plane

bitplane

compile time

compile-time

Per Wikipedia “compile time”

color space

colorspace

double-buffer

doublebuffer

entry point

entry-point

Except if needed to disambiguate from surrounding terms

GitHub

Github

Site’s preferred spelling

LOD

lod
level of detail
level-of-detail

Acronym for “Level of Detail”

mip level
mip layer
mip size
mip tail

miplevel
miplayer
mipsize
miptail

“mipmap term” may be used in time

Exceptions

mipmap

mip map

Exception for historical reasons

pNext chain

pNext-chain
pNext extension chain

general-purpose

general purpose

swapchain

swap chain

Exception due to heavy use in WSI extensions

happen-before
happen-after

happen before
happen after

As used in concurrent languages such as C++11, Java and OpenCL C.

Words With "Pre-" Prefixes

When using the prefix “pre” to indicate “prior to”, such as in the words “preinitialized”, “preprocess”, and “pretransform”, do not separate the prefix from the word with a hyphen. This list is not intended to be complete.

5.2. Describing Undefined Behavior

When describing undefined behavior, be clear about what is and is not defined.

Do not write “undefined results” unless the effect of an operation is truly completely undefined (up to and including termination of the application, for example).

More often, what should be done is to say that the values of specified variables, or the contents of specified memory, become undefined or implementation-defined as a result of such operations.

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. Any use of the word “undefined” without the trailing : is suspect. Note that this does not translate into visible markup in the output document; it is simply markup to help track uses of the word.

5.3. Describing Commands and Parameters

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.

 Guideline As a simple example, say “To create a command pool, call vkCreateCommandPool” rather than “You/The application/The user can create a command pool by calling vkCreateCommandPool”.

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.

5.4. Math Markup

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.

5.4.1. Asciidoc Math Markup

Where possible, math is marked up using straight asciidoc features. For commonality with LaTeX math (see below), some common LaTeX operators and names are defined as asciidoc attributes using the same names, expanding to the corresponding Unicode entities. The complete set of these attributes is found in config/attribs.txt.

Table 11. Spelling
Feature Result Sample Markup

Subscripts

ax

[eq]#a~x~#

Superscripts

-2(b-1)

[eq]#-2^(b-1)^#

Struct/parameter names as variables

2bits

[eq]#2^pname:bits^#

Greek Letters (selected)

α, β, γ, δ, Δ, ε, λ, ρ, τ

[eq]#{alpha}, {beta}, {gamma}, {delta}, {DeltaUpper}, {epsilon}, {lambda}, {rho}, {tau}#

Fractions

¼ + ½

[eq]#{onequarter} + {onehalf}#

Closed Ranges

[0,1]

[eq]#[0,1]#

Open Ranges

[0,1)

[eq]#[0,1)#

Arithmetic and Relational Operators

a × b, a ≤ b, a ≠ b, a ≥ b, |x|

[eq]#a {times} b#, [eq]#a {leq} b#, [eq]#a {neq} b#, [eq]#a {geq} b#, [eq]#{vert}x{vert}#

Floor

⌊w - ½⌋

[eq]#{lfloor}w - {onehalf}{rfloor}#

Ceiling

⌈log2(max(width, height))⌉ + 1

[eq]#{lceil}log~2~(max(pname:width, pname:height)){rceil} + 1#

Logical and Set Operators

∧ ¬ ∨ ⊕ ∈

[eq]#{land} {lnot} {lor} {oplus} {elem}#

Partial Derivatives

∂rx / ∂x = 0

[eq]#{partial}r~x~ / {partial}x = 0#

Matrix/Vector Parameter Names

P = t P1 + (1-t) P2

[eq]#**P** = t **P**~1~ + (1-t) **P**~2~#

5.4.2. LaTeX Math Markup

Math markup more complex than easily supported in straight asciidoc markup (examples found in the Vulkan Specification include matrices, tensors, summation notation, conditional assignments, and division of complex expressions) are marked up using LaTeX math notation, which is either passed through to the KaTeX in-browser rendering script for HTML outputs, or passed through asciidoctor-mathematical for PDF outputs.

 Note There are font and style differences between LaTeX and asciidoc math markup which lead to minor visual inconsistencies. We’ll try to make this better over time, but it’s not significant enough to be a big priority.

While LaTeX math macros, including the amsmath package, are supported, general LaTeX constructs are not.

Inline math is encoded using the latexmath: macro. For example:

• $$[0,1]$$

• $$\frac{1 - \frac{x}{2}}{x - 1}$$

• $$\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{c}_2.$$

Example Markup
  * latexmath:[[0,1\]]
* latexmath:[\frac{1 - \frac{x}{2}}{x - 1}]
* latexmath:[\mathbf{c} = t \mathbf{c}_1 + (1-t) \mathbf{c}_2. ]

Note the escaped bracket in markup for the first expression, which is necessary to work around asciidoc macro parsing.

Block math is used for more complex equations. This example uses the aligned environment to delimit the expression.

\begin{aligned} c_{RGB} & = \begin{cases} \frac{c_{sRGB}}{12.92} & \text{for}\ c_{sRGB} \leq 0.04045 \\ \left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \text{for}\ c_{sRGB} > 0.04045 \end{cases} \end{aligned}
Example Markup
[latexmath]
+++++++++++++++++++
\begin{aligned}
c_{RGB} & =
\begin{cases}
\frac{c_{sRGB}}{12.92}                              & \text{for}\  c_{sRGB} \leq 0.04045 \\
\left ( \frac{c_{sRGB}+0.055}{1.055} \right )^{2.4} & \text{for}\  c_{sRGB} > 0.04045
\end{cases}
\end{aligned}
+++++++++++++++++++
Note

The KaTeX processor used to render LaTeX math inside HTML documents does not support all features of LaTeX math.

Similarly, the asciidoctor-mathematical processor does not support everything, though does have some support for AMSMath.

Some workarounds we’ve had to make are:

Table 12. LaTeX math replacements for KaTeX compatibility

nothing

Unnecessary in blocks. Should not be used for inline.

nothing

Unnecessary in blocks. Should not be used for inline.

\begin{align*}

\begin{aligned}

\end{align*}

\end{aligned}

\operatorname{foo}

\mathbin{foo}

{\rm A}

\mathrm{A}

\text{for }

\text{for}\ 

Text ending in spaces is unpredictable - favour escaped spaces after text

See https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX for a list of currently supported LaTeX functionality in KaTeX. You can also use the live katex preview tool on the KaTeX website to double check support, without building the whole spec: https://khan.github.io/KaTeX/

See https://github.com/gjtorikian/mtex2MML/blob/master/SUPPORTED.md for the list of supported operations in the PDF build. \mathop in particular is not supported properly by the PDF build, but most other standard functionality is included.

It is necessary to cross reference these two to make sure that support exists before using anything, but almost all standard functionality is supported for both.

This example is among the most complex expressions in the Vulkan specification:

$V = \begin{cases} (-1)^S \times 0.0, & E = 0, M = 0 \\ (-1)^S \times 2^{-14} \times { M \over 2^{10} }, & E = 0, M \neq 0 \\ (-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) }, & 0 < E < 31 \\ (-1)^S \times Inf, & E = 31, M = 0 \\ NaN, & E = 31, M \neq 0 \end{cases}$
Example Markup
[latexmath]
+++++++++++++++++++
V =
\begin{cases}
(-1)^S \times 0.0,                      & E = 0, M = 0     \\
(-1)^S \times 2^{-14} \times { M \over 2^{10} },
& E = 0,  M \neq 0 \\
(-1)^S \times 2^{E-15} \times { \left( 1 + { M \over 2^{10} } \right) },
& 0 < E < 31       \\
(-1)^S \times Inf,             & E = 31, M = 0             \\
NaN,                           & E = 31, M \neq 0
\end{cases}
+++++++++++++++++++

5.4.3. LaTeX Math in Table Cells

To use [latexmath] or latexmath: constructs inside table cells, the cell separator must be a| instead of just |:

Example Markup
.Advanced Blend Overlap Modes
|====
| Overlap Mode                              | Weighting Equations
| ename:VK_BLEND_OVERLAP_UNCORRELATED_EXT  a|
[latexmath]
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\begin{aligned}
p_0(A_s,A_d) & = A_sA_d \\
p_1(A_s,A_d) & = A_s(1-A_d) \\
p_2(A_s,A_d) & = A_d(1-A_s) \\
\end{aligned}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|====

5.5. Describing Extension Structure Chains

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

When *performing an operation described by the extension struct*, add
the slink:VkExtensionStructNameID to the pname:pNext chain of the
flink:vkBaseFunctionName command *saying what the extension struct
does*.

5.6. An Example Command Description

The next section is a sample based on the Vulkan API Specification, and describes a command 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.

5.7. Sample Command Description: Creating Command Pools

To create a command pool, call:

VkResult vkCreateCommandPool(
VkDevice                                    device,
const VkCommandPoolCreateInfo*              pCreateInfo,
const VkAllocationCallbacks*                pAllocator,
VkCommandPool*                              pCommandPool);
 Guideline Begin the command description with an open block delimiting the contents as a reference page. The open block contains several required attribute values, as described for automatic extraction into a reference page. Use a short, active sentence when describing what commands do, instead of more passive phrasing like “A command pool is created by calling:” or “The application may create a command pool by calling:”. After the description, include the autogenerated prototype for the command from the ../protos/ directory: [open,refpage='VkCreateCommandPool',desc='Create a new command pool object',type='protos'] -- To create a command pool, call: include::../api/protos/vkCreateCommandPool.txt[] Note that each autogenerated command, enumeration, flag, or structure definition include file also defines a corresponding asciidoc anchor which is the base name of the file. In this case, the anchor is named vkCreateCommandPool.
• device is the logical device that the command pool is created on.

• pCreateInfo points to an instance of the VkCommandPoolCreateInfo structure containing information used to create the command pool.

• pAllocator controls host memory allocation as described in the Memory Allocation chapter.

• pCommandPool points to a handle in which the created command pool object is returned.

 Guideline Each command parameter is described in a separate bullet list entry, followed by validity rules, then detailed descriptions of any new structures, flags, or enumerations introduced by this command. Each parameter should appear as a separate bullet list item beginning with the parameter name, in the same order as parameters appear in the command. This aids in extracting short descriptions of parameters for inclusion in annotated headers and similar documentation. Make sure to tag each parameter with the pname: macro. Strive for compact notation, and in particular always try to use the phrasing “pname:param is” rather than wordier forms such as “pname:param specifies” or “The pname:param parameter specifies”. In general there is no need to describe a parameter which is a Vulkan object handle as a handle; for example, say “pname:device is the logical device” rather than “pname:device is a handle to the logical device”. An exception is object creation functions, where a pointer to a handle of the proper type is used to return the newly created object.
Valid Usage (Implicit)
• device must be a valid VkDevice handle

• pCreateInfo must be a valid pointer to a valid VkCommandPoolCreateInfo structure

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

• pCommandPool must be a valid pointer to a VkCommandPool handle

Return Codes
Success
• VK_SUCCESS

Failure
• VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

 Guideline Some parameter and member validation language for commands and structures is implicit (autogenerated from vk.xml), and included from the ../validity/ directories. All Vulkan command and structure language should include the autogenerated file at the end of their descriptions. It is harmless to include a nonexistent file, in the rare cases where no implicit validity language exists. include::../validity/protos/vkCreateCommandPool.txt[] -- End the open block surrounding the command description after the implicit validity include. All content within the block will be extracted for the corresponding reference page.

Open blocks delimiting reference page content should not themselves contain section headers, as asciidoctor can’t render such nested content correctly. Reference pages should in general be relatively short, so this limitation is not severe.

Structures and enumerations first used as parameters of a command are described next.

The VkCommandPoolCreateInfo structure is defined as:

typedef struct VkCommandPoolCreateInfo {
VkStructureType             sType;
const void*                 pNext;
VkCommandPoolCreateFlags    flags;
uint32_t                    queueFamilyIndex;
} VkCommandPoolCreateInfo;
 Guideline Begin the structure description with an open block delimiting the contents as a reference page, in the same fashion as described above for commands. The open block contains several required attribute values, as described for automatic extraction into a reference page. Use a short, active paragraph to introduce the structure, usually just “The VkStructureName structure is defined as:”. After the description, include the autogenerated definition for the structure from the ../structs/ directory: [open,refpage='VkCommandPoolCreateInfo',desc='Structure specifying parameters of a newly created command pool',type='structs'] -- The sname:VkCommandPoolCreateInfo structure is defined as: include::../api/structs/VkCommandPoolCreateInfo.txt[]
• sType is the type of this structure.

• pNext is NULL or a pointer to an extension-specific structure.

• flags is a bitmask of VkCommandPoolCreateFlagBits indicating usage behavior for the pool and command buffers allocated from it.

• queueFamilyIndex designates a queue family as described in section Queue Family Properties. All command buffers allocated from this command pool must be submitted on queues from the same queue family.

 Guideline Each structure member is described in a separate bullet list entry. For the Vk*CreateInfo structures in particular, there is standard boilerplate for the sType and pNext members, followed by the members specific to the structure.  * pname:sType is the type of this structure. * pname:pNext is NULL or a pointer to an extension-specific structure. * pname:flags is a bitmask of elink:VkCommandPoolCreateFlagBits indicating usage behavior for the pool and command buffers allocated from it. * pname:queueFamilyIndex designates a queue family as described in section <>. All command buffers allocated from this command pool must: be submitted on queues from the same queue family. These entries should be short and functional, without describing details of e.g. new enumerant values, function of individual parameter settings, etc. They can refer to other types using the appropriate *link: macros or to related sections of the specification using asciidoc xrefs. In rare cases, an entry will cover multiple paragraphs. In these cases the normal list nesting and indentation guidelines cannot be applied due to limitations of the asciidoc parser. It is usually best to append a continuation block following the first paragraph of such a list item:  * pname:flags is a bitmask indicating usage behavior for the pool and command buffers allocated from it. Bits which can: be set include: + -- // refBegin VkCommandPoolCreateFlagBits - Bitmask specifying usage behavior for a command pool include::../api/enums/VkCommandPoolCreateFlagBits.txt[] -- + ** ename:VK_COMMAND_POOL_CREATE_TRANSIENT_BIT indicates that command buffers allocated from the pool will be short-lived. ** ename:VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT controls whether command buffers allocated from the pool can: be individually reset.
Valid Usage
• queueFamilyIndex must be the index of a queue family available in the calling command’s device parameter

 Guideline In addition to implicit validity language, there may be additional validation language which is explicit. Such language is written in a separate block in the specification, preceding the validity include. The vkCreateCommandPool example above has no such explicit language, but this example does have explicit language.
Valid Usage (Implicit)
• sType must be VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO

• pNext must be NULL

• flags must be a valid combination of VkCommandPoolCreateFlagBits values

 Guideline Following the definition of structure members, add explicit validity language, following by including the implicit (automatically generated) validity language include for this structure: .Valid Usage **** * [[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] pname:queueFamilyIndex must: be the index of a queue family available in the calling command's pname:device parameter **** include::../validity/structs/VkCommandPoolCreateInfo.txt[] 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. Do not use nested lists or other writing structure where Valid Usage statements are not self-contained. This would make it impossible to extract semantically meaningful descriptions for each assigned Valid Usage ID Tag. 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. 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 queueFamilyIndex statement shown above, the tag [[VUID-VkCommandPoolCreateInfo-queueFamilyIndex-00039]] was inserted by a script, not the original author.

5.8. Markup For Empty Enumerated Types

Sometimes an enumerated type has all values defined by extensions, and each enumerated value defined by the type will be surrounded by an asciidoc 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:

include::../api/enums/VkDescriptorSetLayoutCreateFlagBits.txt[]

ifdef::VK_KHR_push_descriptor[]
* ename:VK_DESCRIPTOR_SET_LAYOUT_CREATE_PUSH_DESCRIPTOR_BIT_KHR specifies
that descriptor sets must: not be allocated using this layout, and
endif::VK_KHR_push_descriptor[]

ifndef::VK_KHR_push_descriptor[]
[NOTE]
.Note
====
All bits for this type are defined by extensions, and none of those
extensions are enabled in this build of the specification.
====
endif::VK_KHR_push_descriptor[]

5.9. Markup For Automatic Reference Page Extraction

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 asciidoc open block surrounding markup describing that page, with attributes used to specify properties of the reference page. Additional heuristics and non-asciidoc tags, described below, are used to identify subsections of a reference page in some cases.

In general the open block introduction will look like:

[open,refpage='name',desc='short description',type='pagetype',xrefs='xrefs']
--

Attributes which can be set on the block are:

• refpage - the name of the reference page, e.g. the Vulkan interface (command, structure, enumerant, handle, etc.) name. This attribute is required.

• desc - short description / summary of the page, used in the page title. This attribute is required.

• type - type of the interface, which must match the directory name following api/ in the interface include:: line within the block, and must be one of basetypes, defines, enums, flags, funcpointers, handles, protos, or structs. This attribute is required.

• xrefs - list of whitespace-separated names of other reference pages which should be added to the See Also section of this page. Most cross-references are automatically generated based on the immediate dependency information in vk.xml, but in some cases, such as referring between *FlagBits and *Flags types, this additional tagging is useful. This attribute is optional.

Attributes of the open block must be written in this format, using single quotes as delimiters (even though asciidoc 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:

• A single paragraph of text describing the definition of the interface. This paragraph is optional, but strongly recommended.

• The include line for the interface, which must be consistent with the page name and type in the open block attributes. This paragraph is required.

• A bullet list describing function parameters, structure members, enumerants in an enumerated type, etc. This list should contain no empty lines, as the extraction script classifies the uninterrupted block of text following the include directive as the Parameters or Members section of the ref page. This list is required, unless the interface has nothing to describe, such as an empty structure or enumeration, or a function with no parameters.

• Paragraphs of text making up the Description section of the ref page. This section is optional. If it is necessary due to constraints of asciidoc markup to have an empty line in the bullet list section1, add a // refBody comment immediately following the bullet list and preceding this section:

// refBody
• An explicit Valid Usage block. This block is required if the interface has such Valid Usage constraints.

• The include line for the implicit valid usage block. This line is required for commands and structures, but not for interfaces such as enumerated types, which do not have implicit valid usage blocks.

• Finally, a two-dash asciidoc delimiter closing the open block:

--
1

The only example of such markup in the 1.0.28 Vulkan Specification source is the VkPhysicalDeviceLimits structure description.

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.

6. Image Authoring, Formats, and Style

Images used in the Vulkan documents must be kept in the directory images/ in SVG format.

Images should be authored in the open-source Inkscape tool, downloadable from its website or packaged as an optional install for most Linux distributions. This allows other people to easily edit your images in the future. Also, while SVG is in principle a portable image format, some proprietary image editors have been observed to produce images incompatible with the PDF image pipeline used by the Specification.

Images must be authored at their actual image size in the HTML and PDF output documents, and must not be scaled with asciidoctor options. In most cases, images are included as standalone figures and should occupy the full width of the document - don’t leave unnecessary whitespace on either side of the image.

The PDF output has an available width of just over 660px (at the default 96dpi), and a height somewhere around 1000px (which diagrams should really go nowhere near anyway). The html output is wider (800 pixels) and with practically unlimited height. As the PDF dimensions are more restrictive, images should not exceed these limits.

 Note According to the documentation available, the PDF output should have dimensions of roughly 184mm x 271mm - or equivalently 697px x 1026px (A4 size [asciidoctor default] with a 0.5in margin [prawn-pdf default] on each side). However for reasons currently unknown, at least the available width before images are scaled down lies is about 30-something pixels lower than that; the height where this happens hasn’t been measured, but is likely to similarly be lower than it should be for reasons currently unknown.

Dimensions of elements in the SVG file should be authored in pixels (px) such that lines/strokes are not unnecessarily anti-aliased (e.g. usually stick to integer pixel widths for lines). In many cases it is useful to also set the background grid to px, but it not necessary; Inkscape has reliable conversions between px and mm using a default dpi of 96 (which matches the PDF output), so the output dimension is mostly irrelevant.

Text in images should usually appear at 12 point type so as to match that in the body of the specification, though 10 point text can be used sparingly where necessary (however this is often indicative of the diagram being too cramped, so authors should consider scaling or reworking the diagram instead). Text should use the built-in generic sans serif font so as to ensure the font in the output document matches whatever sans serif font is used for that document. Note that the character set is currently restricted to Windows-1252.

The font and color scheme used for existing images (black, red, and 50% gray) should be used for changes and new images whenever reasonable to do so, to preserve a consistent look and feel. Whilst a white background is typically assumed, explicitly adding white as a color should be avoided - instead leave elements transparent so the diagrams can be used in other documents.

Many other elements are consistent throughout the set of diagrams which should be maintained in new diagrams where possible. Examples include:

• Lines are usually either fully solid, or use a consistent, and relatively spacious, dash style.

• Lines are capped with a consistent arrow shape where relevant.

• Small solid circles representing points are a consistently sized circle.

Whenever reasonable, it is advised to copy an existing similar diagram and edit it rather than creating one from scratch in order to re-use elements and maintain consistency.

6.1. Character sets in SVG files

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 don’t 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 fire 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.

Appendix A: Valid Usage ID Tags

Valid usage statements in the published Vulkan Specification must all be given Valid Usage ID or VUID tags. These tags are asciidoc anchors, intended for use by the validation layer to provide unique names for each validation condition, and a way to link from validation layer reports into the corresponding parts of the Specification.

A.1. Format of VUID Tags

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

[[VUID-blockname-paramname-category]]

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:

[[VUID-blockname-paramname-number]]

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.

A.2. Creating VUID Tags

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 branch which contains the canonical Specification source, invoke the following command:

python3 reflow.py -overwrite -noflow -tagvu chapters/*.txt chapters/*/*.txt

This will add VUID tags to all statements in valid usage blocks which don’t 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 print out a final line like:

WARN:  You must now edit the value of reflow.py:startVUID to 1376 so that future runs will not overwrite existing VUID tags

Second, after verifying the updates are correct using e.g. git diff, edit reflow.py and edit the definition of the variable startVUID as directed:

# The value to start tagging VU statements at, unless overridden by -nextvu
startVUID = 1376

Commit the updated source files and reflow.py together. The next time the script is run, VUID tags will be assigned numbers starting from the current startVUID value.

A.3. Updating VUID Tags When Valid Usage Statements Change

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:

• The changes are non-semantic, such as using consistent phrasing or markup.

• The changes consist of changing KHX to KHR suffixes when promoting a Khronos-defined extension.

 Note This section may need further modification in response to guidelines agreed to by the Vulkan Working Group.

7. Revision History

• 2018-08-13 - Add %inline directive to the Figures section (public pull request 734).

• 2018-07-30 - Added a section on Describing Undefined Behavior (as part of the fixes for public issue 379), and describing why the undefined: macro should always be used.

• 2018-07-08 - Remove requirement to explicitly include extension appendices in the Changes for New Extensions section.

• 2018-06-25 - Modify the process for Registering a Vendor ID with Khronos to define vendor ID values as part of an enumerated type.

• 2018-03-07 - Updated for Vulkan 1.1 release.

• 2018-01-10 - Move details of mandated extension compatibility from the General Rules/Guidelines section into the Fundamentals section of the API Specification, where they are changed slightly to allow explicit incompatibilies (public issue 638).

• 2017-10-27 - Add language about proper use of “valid pointer” and “pointer to valid object” for valid usage statements, in the Sample Command Description section (related to public pull request 547).

• 2017-10-15 - Describe how to write LaTeX Math in Table Cells (internal issue 908).

• 2017-10-15 - Add more details of KHX extensions (public issues 536, 580).

• 2017-09-10 - Add descriptions of how to use each and any to refer to properties of elments of arrays (internal issue 884).

• 2017-09-10 - Add Valid Usage and Extension pNext Chains language specifying where to describe interactions of structures in a pNext` chain (internal issue 715).

• 2017-09-10 - Add example of marking up an enumerated type all of whose values are defined by extensions (internal issue 864).

• 2017-08-25 - Add language to the API Versions, Extensions, and Layers chapter describing how to write new API versions (internal issue 892).

• 2017-06-12 - Add sections describing when to use the *name: and *text: markup macros instead of the *link: macros, and clarify that slink: should be used for handle as well as structure names (internal issue 886).

• 2017-05-08 - Add appendix describing Valid Usage ID Tags and how they’re generated.

• 2017-03-19 - Add naming rule for Extension Structure Names.

• 2017-02-11 - Finish transitioning to asciidoctor markup.

• 2016-09-28 - Add asciidoc math markup guidelines.

• 2016-09-16 - Make style guide markup more consistent with its own recommendations. Simplify some tables of preferred terms. Add sections on block and table markup.

• 2016-09-12 - Describe writing and markup style for labelled lists. Require use of the ISO 8601 date format except in rare legacy cases. Expand the description of Line Lengths and add a description of markup for Footnotes.

• 2016-09-08 - Add a writing section about proper use of “a” and “an” (internal issue 432).

• 2016-08-30 - Remove mustnot: and shouldnot: macro definitions, which are no longer used in the Specification (internal issue 407).

• 2016-08-29 - Add spelling and compound word rules (public issue 352).

• 2016-08-23 - Modify description of specifying extensions in the Layers and Extensions chapter to refer to the new single-branch model for extensions (internal issue 397).

• 2016-07-26 - Add section describing markup for automatic reference page extraction.

• 2016-07-18 - Add examples of function-parameter and structure-member markup (based on public issue 286).

• 2016-07-11 - Change the document title.

• 2016-07-07 - Rename document, change license to CC BY, clarify required and recommended actions, and reserve use of “normative” for the Specifications.

• 2016-06-26 - Move Layers and Extensions chapter from Appendix C of the Vulkan API Specification and merge content with the naming guide. Put extension and naming chapters into their own source files.

• 2016-06-20 - Add API naming guide.

• 2016-05-22 - Add markup and image creation rules, after fixing missing figure captions for public issue 219.

• 2016-05-01 - Include feedback from public issues 120 and 190. Use consistent conventions for defining structures. Use American rather than British spelling conventions.

• 2016-03-12 - Recommend against "the value of".

• 2016-02-26 - Replace use of the "maynot:" macro with "may: not".

• 2016-02-16 - Place asciidoc conversion post-release.

• 2016-02-09 - Added quotation mark convention.

• 2016-02-01 - Add the Oxford Comma section and issue resolution.

• 2016-01-26 - Add bullet-list style description of command parameters.

• 2016-01-11 - Add “Numbers in Text” section from WSI work.

• 2015-12-16 - Make “begin / end” preferred terms to “start / finish”.

• 2015-12-15 - Make “implementation” preferred term instead of “system”.