426 lines
12 KiB
Plaintext
426 lines
12 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`. If the
|
|
context is self-evident from the structure name, then it may simply be named
|
|
`count`. The `size` rule overrides this rule, though it is possible to have
|
|
multiple sizes (e.g. `sizeCount`).
|
|
|
|
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
|
|
|
|
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.
|