455 lines
13 KiB
Plaintext
455 lines
13 KiB
Plaintext
// Copyright (c) 2015-2016 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.
|
|
|
|
|
|
=== 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.
|