• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// Copyright 2015-2024 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[naming]]
6= API Naming Conventions
7
8Identifiers in the Vulkan API (e.g. types, parameters, constants, etc.) all
9follow a set of naming rules, providing a consistent scheme for developers.
10
11The Vulkan C API uses prefixes as an implicit namespace control mechanism.
12Bindings to other languages can choose not to use these prefixes if the
13language provides an explicit namespace mechanism.
14
15
16== General Naming Rules
17
18Names of identifiers should generally be written with full words, as a
19concise description of what that identifier is.
20For example, the type of a structure containing information about how to
21create an instance is stext:VkInstanceCreateInfo.
22
23Abbreviations and prefixes are sometimes used in the API when they do not
24impede clarity.
25All abbreviations and prefixes used in the API must be approved by the
26Vulkan working group, and be added to the <<naming-abbreviations,Common
27Abbreviations>> and <<naming-prefixes,Standard Prefixes>> sections,
28respectively.
29Whenever an approved abbreviation exists for a particular word, it should be
30used in place of the full word unless there is good reason not to.
31
32When a number is part of an identifier, it is treated as a word if it is a
33standalone number, such as the extension name token
34ename:VK_KHR_GET_MEMORY_REQUIREMENTS_2_EXTENSION_NAME for the
35`VK_KHR_get_memory_requirements2` extension.
36For uses where the number is part of a common abbreviation such as etext:2D
37or etext:R8B8`, the entire abbreviation is treated as a word.
38
39ifdef::editing-notes[]
40[NOTE]
41.editing-note
42====
43Unfortunately, there is an internal inconsistency here between extension
44name strings, such as VK_KHR_get_memory_requirements2, and tokens encoding
45those names, such as ename:VK_KHR_GET_MEMORY_REQUIREMENTS_2_EXTENSION_NAME.
46====
47endif::editing-notes[]
48
49
50[[naming-preprocessor]]
51== Preprocessor Defines
52
53Preprocessor definitions include an underscore `_` as a delimiter between
54words, with every character in upper case.
55
56Each definition is prefixed with `VK_`, followed by the name.
57
58This rule applies to most declarations with the C Preprocessor's `#define`
59token, including macros and constants.
60There are however a few exceptions:
61
62  * The header guard for each header includes an additional underscore `_`
63    at the end of the identifier.
64  ** Example: `VULKAN_H_`
65  * Definitions that denote the presence of an extension follow the
66    <<extensions-naming-conventions-name-strings,extension name string
67    convention>>.
68  ** Example: `VK_KHR_sampler_mirror_clamp_to_edge`
69  * Three `VKAPI_*` definitions are defined by the platform header to alias
70    certain platform-specific identifiers related to calling conventions.
71  ** Examples: `VKAPI_ATTR`, `VKAPI_CALL` and `VKAPI_PTR`
72  * Preprocessor defines are occasionally used to create aliases between
73    other Vulkan identifiers, which usually happens when something was
74    originally misnamed.
75    In these cases, the fixed name is added to the API, and the old name is
76    made into an alias of that.
77    In these cases, the name will be whatever the original misnamed
78    identifier was.
79
80[source, c]
81.Example
82----
83// VK_VERSION_MAJOR (Macro)
84#define VK_VERSION_MAJOR(version) ((uint32_t)(version) >> 22)
85
86// VK_HEADER_VERSION (Base type)
87#define VK_HEADER_VERSION 10
88----
89
90
91== Type Names
92
93Type names are declared with no separator between words.
94Each word starts with a capital letter, and every other character in each
95word is lower case.
96
97Each type name is prefixed with `Vk`.
98
99This rule applies to all type definitions except <<naming-funcpointers,
100function pointer types>>, including struct and union types, handles, base
101typedefs, and enumerant types.
102
103[source, c]
104.Example
105----
106// VkImage (Handle)
107VK_NONDISP_HANDLE(VkImage)
108
109// VkFlags (Base type)
110typedef uint32_t VkFlags;
111
112// VkResult (Enum type)
113typedef enum VkResult {
114    ...
115};
116
117// VkApplicationInfo (Struct)
118typedef struct VkApplicationInfo {
119    ...
120} VkApplicationInfo;
121
122// VkClearColorValue (Union)
123typedef union VkClearColorValue {
124    ...
125} VkClearColorValue;
126----
127
128
129[[naming-extension-structures]]
130=== Extending Structure Names
131
132Structures which extend a base structures through its pname:pNext chain
133should reflect the name of the base structure.
134Currently there are two examples of such naming schemes.
135
136New structures which add extended object creation parameters to a base
137structure should use this naming scheme:
138
139.Extended Object Information Structures
140[width="60%",options="header"]
141|====
142| Base Structure Name | Extending Structure Name
143| `Vk__Object__CreateInfo`
144    | `Vk__ObjectName__CreateInfo__Author__`
145|====
146
147`_Object_` is the name of the object being created.
148`_Name_` is a short name for the extension or the new information added by
149that extension.
150`_Author_` is the author ID of the extension.
151
152New structures which extend API queries, such as the
153`vkGetPhysicalDeviceFeatures2KHR` and `vkGetPhysicalDeviceProperties2KHR`
154commands defined by the `VK_KHR_get_physical_device_properties2` extension,
155should use this naming scheme:
156
157.Extended Query Structures
158[width="60%",options="header"]
159|====
160| Base Structure Name | Extending Structure Name
161| `vkGetPhysicalDeviceFeatures2KHR`
162    | `VkPhysicalDevice__Name__Features__Author__`
163| `vkGetPhysicalDeviceProperties2KHR`
164    | `VkPhysicalDevice__Name__Properties__Author__`
165|====
166
167`_Name_` is a short name for the extension, or for the new feature or
168property being queried, such as `Multiview` or `DiscardRectangle`.
169`_Author_` is the author ID of the extension.
170
171
172== Enumerant Names
173
174Enumerants include an underscore `_` as a delimiter between words, with
175every character in upper case.
176
177Each enumerant name is prefixed with `VK_`.
178
179Enumerants are prefixed with the exact name of the type it belongs to,
180converted to the correct case (e.g. `VkStructureType` ->
181`VK_STRUCTURE_TYPE_*`).
182
183This rule applies to all enumerants, with one exception.
184
185  * The `VkResult` enumerants are split into two sub types: error and
186    success codes.
187  ** Success codes are not prefixed with anything other than `VK_`.
188  ** Error codes are prefixed with `VK_ERROR_`.
189
190[source, c]
191.Example
192----
193// VK_FORMAT_UNDEFINED, VK_FORMAT_R4G4_UNORM_PACK8 (Enumerants)
194typedef enum VkFormat {
195    VK_FORMAT_UNDEFINED = 0,
196    VK_FORMAT_R4G4_UNORM_PACK8 = 1,
197    ...
198};
199
200// VkResult codes (Exception)
201typedef enum VkResult {
202    VK_SUCCESS = 0,
203    ...
204    VK_ERROR_OUT_OF_HOST_MEMORY = -1,
205    ...
206} VkResult;
207----
208
209
210== Command Names
211
212Command names are declared with no separator between words.
213Each word starts with a capital letter, and every other character in each
214word is lower case.
215
216The structure of a command name should be as follows:
217
218`__prefix Verb Object Property__`
219
220`_prefix_`::
221    This is usually "vk", but will be "vkCmd" if it is a command used to
222    record into a command buffer, or "vkQueue" if it directly affects a
223    queue.
224
225`_Verb_`::
226    The verb describing the action being performed.
227    A list of most verbs used in Vulkan is available <<command-names-verbs,
228    here>>.
229
230`_Object_`::
231    The name of the object being acted upon by the command.
232
233`_Property_`::
234    The property of the object which is being acted upon by the command, and
235    is omitted in cases where the whole object is being acted upon (e.g.
236    creation commands).
237
238These rules apply to all command declarations.
239
240[source, c]
241.Example
242----
243// Creation command
244VKAPI_ATTR VkResult VKAPI_CALL vkCreateInstance( ... );
245
246// Command buffer recording command
247VKAPI_ATTR VkResult VKAPI_CALL vkCmdBindPipeline( ... );
248
249// Get command
250VKAPI_ATTR VkResult VKAPI_CALL vkGetQueryPoolResults( ... );
251----
252
253.Note
254[NOTE]
255====
256There are three exceptions to the above rule in the core Vulkan API:
257
258  * vkDeviceWaitIdle
259  * vkCmdNextSubpass
260  * vkCmdPipelineBarrier
261
262These names are left as-is to maintain compatibility.
263
264There are additionally a number of exceptions in a few existing extensions.
265====
266
267
268=== Query Commands
269
270A number of commands in the API are used to determine the properties of some
271object in the implementation.
272
273The queried properties may either be invariant, or they may: change based on
274application behavior.
275If the results are not invariant, the lifetime of the results should be
276clearly described in the command description.
277See
278link:html/vkspec.html#fundamentals-commandsyntax-results-lifetime[Lifetime
279of Retrieved Results] in the specification for more information.
280
281These commands fall into two categories from a naming perspective:
282
283Capability Queries::
284
285These are commands which query capabilities of objects that an
286implementation can provide.
287Such commands use the verb "Enumerate" to identify themselves.
288+
289e.g. `vkEnumeratePhysicalDeviceProperties`
290+
291Whilst these commands describe properties of the named object, they do not
292accept a parameter of that object type - though they usually have a
293parameter for the parent type.
294
295Object State Queries::
296
297These commands are used to query the current properties of an object that
298has been created.
299Such commands use the verb "Get" to identify themselves.
300+
301e.g. `vkGetPhysicalDeviceQueueFamilyProperties`
302+
303These commands always have a parameter of the object type.
304
305
306[[command-names-verbs]]
307=== Command Verbs
308
309Below is a list of many of the verbs currently in use in core Vulkan and KHR
310extensions, along with their meanings.
311The list is not guaranteed to be up to date, but covers all core and KHR
312verbs at the time of writing.
313
314[%autowidth,options="header"]
315|===
316| Verb       | Meaning
317| Acquire    | Acquire ownership of an object from an external source
318| Allocate   | Allocates memory in a pool or memory heap and creates object - paired with "Free"
319| Begin      | Start of a range of command buffer commands with different behavior than those outside the range - "End" marks the end of the range
320| Bind       | Binds an object to another object
321| Blit       | Performs a filtered and scaled copy of pixels from one image to another
322| Clear      | Sets all pixels in an image to the same value
323| Copy       | A raw copy of data from one object to another with no transformation of the data
324| Create     | Creates an object - paired with "Destroy"
325| Destroy    | Destroys an object - paired with "Create"
326| Dispatch   | Kicks off a set of compute tasks
327| Draw       | Kicks off a set of rasterization tasks
328| End        | End of a range of command buffer commands with different behavior than those outside the range - "Begin" marks the start of the range
329| Enumerate  | Queries the capabilities of objects that could be created, before creating them
330| Execute    | Executes commands recorded in another command buffer
331| Fill       | Sets all data units in a buffer to the same value
332| Flush      | Flushes data from the host to the device
333| Free       | Destroys an object and then frees memory back to a pool or memory heap - paired with "Allocate"
334| Get        | Queries the state of an existing object
335| Import     | Imports the payload from an external object into a Vulkan object
336| Invalidate | Invalidates data on the host, forcing newer data on the device to be read
337| Map        | Maps an allocation into host memory - paired with "Unmap"
338| Merge      | Merges two objects
339| Present    | Presents an image to a surface
340| Push       | Pushes data to the device as part of a command stream
341| Release    | Releases ownership of an object to an external source
342| Reset      | Resets the state of an object to an initial state
343| Resolve    | Resolves multiple samples in a multisampled image to an image with one sample per pixel
344| Set        | Sets the state of an object
345| Submit     | Submits a set of commands to a queue
346| Unmap      | Unmaps an allocation from host memory - paired with "Map"
347| Update     | Updates entries in a descriptor set
348| Wait       | Waits for some signal
349| Write      | Writes values to an object
350|===
351
352
353[[naming-funcpointers]]
354=== Function Pointer Type Names
355
356Function pointer names are declared exactly as the equivalent statically
357declared command would be declared, but prefixed with `PFN_`, standing for
358"Pointer to FunctioN".
359
360[source, c]
361.Example
362----
363// PFN_vkCreateInstance (Function Pointer)
364typedef VkResult (VKAPI_PTR *PFN_vkCreateInstance)( ... );
365----
366
367
368== Function Parameter and Struct/Union Member Names
369
370Function parameter names are declared with no separator between words.
371Each new word, *except* for the first, starts with a capital letter.
372All other characters in the parameter name are in lower case.
373
374Members/parameters of a type that is not a base type should generally be
375named in a similar way to the type itself, with additional context added for
376clarity when necessary.
377
378Pointer members/parameters are prefixed with a number of `p` characters,
379with one `p` for each level of indirection.
380
381Function pointer members/parameters are prefixed with `pfn`.
382
383Any member describing the size of a memory allocation should be suffixed
384with `Size`.
385If the context is self-evident from the structure name, then it may simply
386be named `size`.
387
388Any member describing the number of something, such as an array length or
389number of internal allocations, should be suffixed with `Count`.
390The `size` rule overrides this rule, though it is possible to have multiple
391sizes (e.g. `sizeCount`).
392If the member is an array length, then the name of length should correspond
393to the name of the array member, usually `XYZCount` for an array named
394`pXYZs`.
395If a structure in a pname:pNext chain is an array whose length must match
396the length of an array of the base structure, then that extending structure
397should include an array length member with the same name as the length in
398the base structure.
399
400These rules apply to all function parameters and struct/union members, with
401a single exception:
402
403  * The `sType` member of structures is abbreviated as it is used in almost
404    every structure.
405  ** The slightly odd naming prevents it clashing with any future variables.
406  ** The `s` stands for "`structure`", referring to its enumerant type.
407
408[source, c]
409.Example
410----
411// Function parameters, including a twice indirected pointer.
412VKAPI_ATTR VkResult VKAPI_CALL vkMapMemory(
413    VkDevice                                    device,
414    VkDeviceMemory                              memory,
415    VkDeviceSize                                offset,
416    VkDeviceSize                                size,
417    VkMemoryMapFlags                            flags,
418    void**                                      ppData);
419
420// Structure members, including the sType exception and a single indirected
421// pointer.
422typedef struct VkMemoryBarrier {
423    VkStructureType    sType;
424    const void*        pNext;
425    VkAccessFlags      srcAccessMask;
426    VkAccessFlags      dstAccessMask;
427} VkMemoryBarrier;
428
429// Function pointer members
430typedef struct VkAllocationCallbacks {
431    void*                                   pUserData;
432    PFN_vkAllocationFunction                pfnAllocation;
433    PFN_vkReallocationFunction              pfnReallocation;
434    PFN_vkFreeFunction                      pfnFree;
435    PFN_vkInternalAllocationNotification    pfnInternalAllocation;
436    PFN_vkInternalFreeNotification          pfnInternalFree;
437} VkAllocationCallbacks;
438
439// Size member (pCode is not a specific array of anything, it is just a
440// pointer to memory)
441typedef struct VkShaderModuleCreateInfo {
442    VkStructureType              sType;
443    const void*                  pNext;
444    VkShaderModuleCreateFlags    flags;
445    size_t                       codeSize;
446    const uint32_t*              pCode;
447} VkShaderModuleCreateInfo;
448
449// Count member
450typedef struct VkSparseImageMemoryBindInfo {
451    VkImage                           image;
452    uint32_t                          bindCount;
453    const VkSparseImageMemoryBind*    pBinds;
454} VkSparseImageMemoryBindInfo;
455----
456
457
458[[naming-extension-identifiers]]
459== Extension Identifier Naming Conventions
460
461Identifiers defined by an extension are modified by appending the
462extension's author ID to the end of the identifier, as described below.
463Author IDs are obtained as described in the
464<<extensions-naming-conventions,Extension and Layer Naming Conventions>>
465section.
466
467If an extension becomes part of core, a new version of the extension's
468identifiers should be created, that do not contain the author ID at the end
469of the identifier.
470The original identifiers should be kept in order to maintain source-level
471compatibility with existing applications making use of the earlier
472extension's identifiers.
473
474
475=== Extension Type Names
476
477Types defined by extensions have the author ID appended to the end of the
478type name.
479
480[source, c]
481.Example
482----
483// VkSurfaceFormatKHR (structure type with KHR appended)
484typedef struct VkSurfaceFormatKHR {
485    VkFormat           format;
486    VkColorSpaceKHR    colorSpace;
487} VkSurfaceFormatKHR;
488----
489
490
491[[naming-extension-enumerant-names]]
492=== Extension Enumerant Names
493
494Enumerants defined by extensions have the author ID appended to the end of
495the enumerant name, separated by an underscore.
496This includes the begin, end, range and max values added to enumeranted type
497definitions by the generator scripts.
498
499[NOTE]
500====
501There is one exception to this rule in the
502`VK_KHR_sampler_mirror_clamp_to_edge` extension.
503This functionality was included in the original specification, but quickly
504separated out at release.
505Due to this late change, the single enum exposed has retained its original
506identifier to avoid compatibility issues:
507ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
508====
509
510[source, c]
511.Example
512----
513// VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR (enumerant with _KHR appended)
514typedef enum VkCompositeAlphaFlagBitsKHR {
515    VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR = 0x00000001,
516    ...
517} VkCompositeAlphaFlagBitsKHR;
518----
519
520
521=== Extension Function Names
522
523Function and function pointer type names defined by extensions have the
524author ID appended to the end of the name.
525
526[source, c]
527.Example
528----
529// vkDestroySurfaceKHR (function with KHR appended)
530VKAPI_ATTR void VKAPI_CALL vkDestroySurfaceKHR(
531    VkInstance                                  instance,
532    VkSurfaceKHR                                surface,
533    const VkAllocationCallbacks*                pAllocator);
534
535typedef void (VKAPI_PTR *PFN_vkDestroySurfaceKHR)(
536    VkInstance                                  instance,
537    VkSurfaceKHR                                surface,
538    const VkAllocationCallbacks*                pAllocator);
539----
540
541
542[[naming-abbreviations]]
543== Common Abbreviations
544
545Abbreviations and acronyms are sometimes used in the <<vulkan-spec,Vulkan
546API Specification>> and the Vulkan API where they are considered clear and
547commonplace.
548All such abbreviations used in the core API are defined here.
549Extensions should also use these abbreviations where appropriate.
550
551Src::
552    Source
553
554Dst::
555    Destination
556
557Min::
558    Minimum
559
560Max::
561    Maximum
562
563Rect::
564    Rectangle
565
566Info::
567    Information
568
569Lod::
570    Level of Detail
571
572Mip::
573    Related to a mipmap.
574    Use "`mipmap`" in full only when it is a standalone term.
575    If referred to some associating with a mipmap, such as levels, sampling
576    mode, size, tail images, etc., use "`mip`" as a standalone prefix word,
577    e.g. pname:maxMipLevels, ename:VK_MIP_MODE, etc.
578    This is analogous to the <<writing-compound-words,spelling conventions
579    for mip-related terms>>
580
581[NOTE]
582====
583The names pname:mipmapMode, pname:mipmapPrecisionBits,
584sname:VkSamplerMipmapMode, and
585ename:VK_SPARSE_IMAGE_FORMAT_SINGLE_MIPTAIL_BIT are exceptions to this
586general usage guideline, for historical reasons.
587====
588
589ID::
590    Identifier
591
592UUID::
593    Universally Unique Identifier
594
595Op::
596    Operation
597
598R::
599    Red color component
600
601G::
602    Green color component
603
604B::
605    Blue color component
606
607A::
608    Alpha color component
609
610
611[[naming-prefixes]]
612== Standard Prefixes
613
614Prefixes are used in the API to denote specific semantic meaning of Vulkan
615names, or as a label to avoid name clashes, and are explained here:
616
617VK/Vk/vk::
618    Vulkan namespace +
619    All types, commands, enumerants and C macro definitions in the Vulkan
620    specification are prefixed with these two characters, according to the
621    rules defined above.
622
623PFN/pfn::
624    Function Pointer +
625    Denotes that a type is a function pointer, or that a variable is of a
626    pointer type.
627
628p::
629    Pointer +
630    Variable is a pointer.
631
632vkCmd::
633    Commands that record commands in command buffers +
634    These API commands do not result in immediate processing on the device.
635    Instead, they record the requested action in a command buffer for
636    execution when the command buffer is submitted to a queue.
637
638s::
639    Structure +
640    Used to denote the etext:VK_STRUCTURE_TYPE* member of each structure in
641    pname:sType.
642
643
644[[format-types]]
645== Format Types
646
647Formats naming conventions
648
649Numeric Format::
650    Describes the suffix found on formats ex.
651    SFLOAT, SINT, SNORM, SRGB, UINT, USCALED, etc
652
653Numeric Type::
654    describes float, signed int, or unsigned int
655
656SPIR-V Type::
657    The combination of the type (ex OpTypeInt), width, and signedness
658