// 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 <> 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. 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 <>. ** 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; ---- [[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 <>. `_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 <> 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/KHX extensions, along with their meanings. The list is not guaranteed to be up to date, but covers all core and KHR/KHX 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 <> 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 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.