vulkan/style/naming.txt

// Copyright (c) 2015-2018 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[naming]]
= 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.


== 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 stext: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 <<naming-abbreviations,Common
Abbreviations>> and <<naming-prefixes,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
ename: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 etext:2D
or etext:R8B8`, the entire abbreviation is treated as a word.

ifdef::editing-notes[]
[NOTE]
.editing-note
====
Unfortunately, there's an internal inconsistency here between extension name
strings, such as VK_KHR_get_memory_requirements2, and tokens encoding those
names, such as ename:VK_KHR_GET_MEMORY_REQUIREMENTS_2_EXTENSION_NAME.
====
endif::editing-notes[]


[[naming-preprocessor]]
== 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
    <<extensions-naming-conventions-name-strings,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.

[source, c]
.Example
----
// VK_VERSION_MAJOR (Macro)
#define VK_VERSION_MAJOR(version) ((uint32_t)(version) >> 22)

// VK_HEADER_VERSION (Base type)
#define VK_HEADER_VERSION 10
----


== 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 <<naming-funcpointers,
function pointer types>>, including struct and union types, handles, base
typedefs, and enumerant types.

[source, c]
.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;
----


[[naming-extension-structures]]
=== Extension Structure Names

Structures which extend other structures through the pname: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:

.Extended Object Information Structures
[width="60%",options="header"]
|====
| Base Structure Name | Extension Structure Name
| `Vk__Object__CreateInfo`
    | `Vk__ObjectName__CreateInfo__Author__`
|====

`_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:

.Extended Query Structures
[width="60%",options="header"]
|====
| Base Structure Name | Extension Structure Name
| `vkGetPhysicalDeviceFeatures2KHR`
    | `VkPhysicalDevice__Name__Features__Author__`
| `vkGetPhysicalDeviceProperties2KHR`
    | `VkPhysicalDevice__Name__Properties__Author__`
|====

`_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.


== 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. `VkStructureType` ->
`VK_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_`.

[source, c]
.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;
----


== 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 <<command-names-verbs,
    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.

[source, c]
.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
[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.
====


=== 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 <<fundamentals-commandsyntax-results-lifetime,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.


[[command-names-verbs]]
=== 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.

[%autowidth,options="header"]
|===
| 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
|===


[[naming-funcpointers]]
=== 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".

[source, c]
.Example
----
// PFN_vkCreateInstance (Function Pointer)
typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)( ... );
----


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

[source, c]
.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;
    VkAccessFlags      srcAccessMask;
    VkAccessFlags      dstAccessMask;
} VkMemoryBarrier;

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

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

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


[[naming-extension-identifiers]]
== 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
<<extensions-naming-conventions,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.


=== Extension Type Names

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

[source, c]
.Example
----
// VkSurfaceFormatKHR (structure type with KHR appended)
typedef struct VkSurfaceFormatKHR {
    VkFormat           format;
    VkColorSpaceKHR    colorSpace;
} VkSurfaceFormatKHR;
----


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

[NOTE]
====
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:
ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
====

[source, c]
.Example
----
// VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR (enumerant with _KHR appended)
typedef enum VkCompositeAlphaFlagBitsKHR {
    VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR = 0x00000001,
    ...
} VkCompositeAlphaFlagBitsKHR;
----


=== Extension Function Names

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

[source, c]
.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);
----


[[naming-abbreviations]]
== Common Abbreviations

Abbreviations and acronyms are sometimes used in the <<vulkan-spec,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. pname:maxMipLevels, ename:VK_MIP_MODE, etc.
    This is analogous to the <<writing-compount-words,spelling conventions
    for mip-related terms>>

[NOTE]
====
The names pname:mipmapMode, pname:mipmapPrecisionBits,
sname:VkSamplerMipmapMode, and
ename: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


[[naming-prefixes]]
== 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 etext:VK_STRUCTURE_TYPE* member of each structure in
    pname:sType.