Vulkan-Docs/doc/specs/vulkan/style/naming.txt

// Copyright (c) 2015-2017 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.


[[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;
----


== 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_APPLICATION_INFO`).

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;
----


== Function Names

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

Function names are prefixed with `vk`, with the exception of functions that
record commands into a command buffer and are instead prefixed with `vkCmd`.

This rule applies to all function declarations.

[source, c]
.Example
----
// Function call
VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance( ... );

// Command buffer function
VKAPI_ATTR VkResult VKAPI_CALL vkCmdBindPipeline( ... );
----


[[naming-funcpointers]]
=== Function Pointer Type Names

Function pointer names are declared exactly as the equivalent statically
declared function 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 software.

=== 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
{apiname} 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.