Appendix D: API Boilerplate
This appendix defines Vulkan API features that are infrastructure required for a complete functional description of Vulkan, but do not logically belong elsewhere in the Specification.
Vulkan Header Files
Vulkan is defined as an API in the C99 language.
Khronos provides a corresponding set of header files for applications using
the API, which may be used in either C or C++ code.
The interface descriptions in the specification are the same as the
interfaces defined in these header files, and both are derived from the
vk.xml XML API Registry, which is the canonical machine-readable
description of the Vulkan API.
The Registry, scripts used for processing it into various forms, and
documentation of the registry schema are available as described at
Language bindings for other languages can be defined using the information in the Specification and the Registry. Khronos does not provide any such bindings, but third-party developers have created some additional bindings.
Vulkan Combined API Header
Applications normally will include the header
vulkan.h always includes the following headers:
In addition, specific preprocessor macros defined at the time
included cause header files for the corresponding window system-specific extension interfaces to be included.
Vulkan Platform-Specific Header
Platform-specific macros and interfaces are defined in
These macros are used to control platform-dependent behavior, and their
exact definitions are under the control of specific platforms and Vulkan
Platform-Specific Calling Conventions
On many platforms the following macros are empty strings, causing platform- and compiler-specific default calling conventions to be used.
VKAPI_ATTR is a macro placed before the return type in Vulkan API
This macro controls calling conventions for C++11 and GCC/Clang-style
VKAPI_CALL is a macro placed after the return type in Vulkan API
This macro controls calling conventions for MSVC-style compilers.
VKAPI_PTR is a macro placed between the '(' and '*' in Vulkan API
function pointer declarations.
This macro also controls calling conventions, and typically has the same
VKAPI_CALL, depending on the
With these macros, a Vulkan function declaration takes the form of:
VKAPI_ATTR <return_type> VKAPI_CALL <command_name>(<command_parameters>);
Additionally, a Vulkan function pointer type declaration takes the form of:
typedef <return_type> (VKAPI_PTR *PFN_<command_name>)(<command_parameters>);
Platform-Specific Header Control
VK_NO_STDINT_H macro is defined by the application at compile
time, extended integer types used by the Vulkan API, such as
must also be defined by the application.
Otherwise, the Vulkan headers will not compile.
VK_NO_STDINT_H is not defined, the system
<stdint.h> is used to
define these types.
There is a fallback path when Microsoft Visual Studio version 2008 and
earlier versions are detected at compile time.
Vulkan Core API Header
Applications that do not make use of window system-specific extensions may
vulkan_core.h instead of
vulkan.h, although there is
usually no reason to do so.
In addition to the Vulkan API,
vulkan_core.h also defines a small number
of C preprocessor macros that are described below.
Vulkan Version Number Macros
API Version Numbers are packed into integers. These macros manipulate version numbers in useful ways.
VK_VERSION_MAJOR extracts the API major version number from a packed
#define VK_VERSION_MAJOR(version) ((uint32_t)(version) >> 22)
VK_VERSION_MINOR extracts the API minor version number from a packed
#define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3ff)
VK_VERSION_PATCH extracts the API patch version number from a packed
#define VK_VERSION_PATCH(version) ((uint32_t)(version) & 0xfff)
VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0.
The patch version number in this macro will always be zero.
The supported patch version for a physical device can be queried with
// Vulkan 1.0 version number #define VK_API_VERSION_1_0 VK_MAKE_VERSION(1, 0, 0)// Patch version should always be set to 0
VK_API_VERSION is now commented out of
vulkan_core.h and cannot be
// DEPRECATED: This define has been removed. Specific version defines (e.g. VK_API_VERSION_1_0), or the VK_MAKE_VERSION macro, should be used instead. //#define VK_API_VERSION VK_MAKE_VERSION(1, 0, 0) // Patch version should always be set to 0
VK_MAKE_VERSION constructs an API version number.
#define VK_MAKE_VERSION(major, minor, patch) \ (((major) << 22) | ((minor) << 12) | (patch))
majoris the major version number.
minoris the minor version number.
patchis the patch version number.
Vulkan Header File Version Number
VK_HEADER_VERSION is the version number of the
This value is kept synchronized with the patch version of the released
// Version of this file #define VK_HEADER_VERSION 100
Vulkan Handle Macros
VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a
non-dispatchable handle type.
#if !defined(VK_DEFINE_NON_DISPATCHABLE_HANDLE) #if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__) ) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__) #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object; #else #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object; #endif #endif
objectis the name of the resulting C type.
Most Vulkan handle types, such as VkBuffer, are non-dispatchable.
VK_NULL_HANDLE is a reserved value representing a non-valid object
It may be passed to and returned from Vulkan commands only when
#define VK_NULL_HANDLE 0
Window System-Specific Header Control (Informative)
To use a Vulkan extension supporting a platform-specific window system, header files for that window systems must be included at compile time, or platform-specific types must be forward-declared. The Vulkan header files cannot determine whether or not an external header is available at compile time, so platform-specific extensions are provided in separate headers from the core API and platform-independent extensions, allowing applications to decide which ones should be defined and how the external headers are included.
Extensions dependent on particular sets of platform headers, or that
forward-declare platform-specific types, are declared in a header named for
Before including these platform-specific Vulkan headers, applications must
vulkan_core.h and any external native headers the platform
extensions depend on.
As a convenience for applications that do not need the flexibility of
separate platform-specific Vulkan headers,
vulkan_core.h, and then conditionally includes platform-specific Vulkan
headers and the external headers they depend on.
Applications control which platform-specific headers are included by
#defining macros before including
The correspondence between platform-specific extensions, external headers
they require, the platform-specific header which declares them, and the
preprocessor macros which enable inclusion by
vulkan.h are shown in the
|Extension Name||Window System Name||Platform-specific Header||Required External Headers||Controlling
This section describes the purpose of the headers independently of the specific underlying functionality of the window system extensions themselves. Each extension name will only link to a description of that extension when viewing a specification built with that extension included.