// 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 <> and <> 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 <>. ** 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 <>, 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 <> 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 <> 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 <> [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.