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 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.
Applications normally will include the header
vulkan.h always includes the following headers:
In addition, specific preprocessor macros defined at the time
vulkan.h is included cause header files for the corresponding window
system-specific and provisional interfaces to be included, as described
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
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>);
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.
VK_NO_STDDEF_H macro is defined by the application at compile
size_t, must also be defined by the application.
Otherwise, the Vulkan headers will not compile.
VK_NO_STDDEF_H is not defined, the system
<stddef.h> is used to
define this type.
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.
VK_HEADER_VERSION is the version number of the
This value is kept synchronized with the patch version of the released
// Provided by VK_VERSION_1_0 // Version of this file #define VK_HEADER_VERSION 177
VK_HEADER_VERSION_COMPLETE is the complete version number of the
vulkan_core.h header, comprising the major, minor, and patch versions.
The major/minor values are kept synchronized with the complete version of
the released Specification.
This value is intended for use by automated tools to identify exactly which
version of the header was used during their generation.
Applications should not use this value as their
Instead applications should explicitly select a specific fixed major/minor
API version using, for example, one of the
// Provided by VK_VERSION_1_0 // Complete version of this file #define VK_HEADER_VERSION_COMPLETE VK_MAKE_API_VERSION(0, 1, 2, VK_HEADER_VERSION)
VK_API_VERSION is now commented out of
vulkan_core.h and cannot be
// Provided by VK_VERSION_1_0 // 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_DEFINE_HANDLE defines a dispatchable handle type.
// Provided by VK_VERSION_1_0 #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;
objectis the name of the resulting C type.
The only dispatchable handle types are those related to device and instance management, such as VkDevice.
VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a
non-dispatchable handle type.
// Provided by VK_VERSION_1_0 #ifndef VK_DEFINE_NON_DISPATCHABLE_HANDLE #if (VK_USE_64_BIT_PTR_DEFINES==1) #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
// Provided by VK_VERSION_1_0 #ifndef VK_DEFINE_NON_DISPATCHABLE_HANDLE #if (VK_USE_64_BIT_PTR_DEFINES==1) #if __cplusplus >= 201103L || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201103L)) #define VK_NULL_HANDLE nullptr #else #define VK_NULL_HANDLE ((void*)0) #endif #else #define VK_NULL_HANDLE 0ULL #endif #endif #ifndef VK_NULL_HANDLE #define VK_NULL_HANDLE 0 #endif
VK_USE_64_BIT_PTR_DEFINES defines whether the default non-dispatchable
handles are declared using either a 64-bit pointer type or a 64-bit unsigned
VK_USE_64_BIT_PTR_DEFINES is set to '1' to use a 64-bit pointer type
or any other value to use a 64-bit unsigned integer type.
// Provided by VK_VERSION_1_0 #ifndef VK_USE_64_BIT_PTR_DEFINES #if defined(__LP64__) || defined(_WIN64) || (defined(__x86_64__) && !defined(__ILP32__) ) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__) #define VK_USE_64_BIT_PTR_DEFINES 1 #else #define VK_USE_64_BIT_PTR_DEFINES 0 #endif #endif
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 following table.
|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.
Provisional extensions should not be used in production applications. The functionality defined by such extensions may change in ways that break backwards compatibility between revisions, and before final release of a non-provisional version of that extension.
Provisional extensions are defined in a separate provisional header,
vulkan_beta.h, allowing applications to decide whether or not to include
The mechanism is similar to window system-specific
headers: before including
vulkan_beta.h, applications must include
Sometimes a provisional extension will include a subset of its interfaces in
As a convenience for applications,
vulkan.h conditionally includes
Applications can control inclusion of
vulkan_beta.h by #defining the
VK_ENABLE_BETA_EXTENSIONS before including
Starting in version 1.2.171 of the Specification, all provisional enumerants
are protected by the macro
This section describes the purpose of the provisional header independently of the specific provisional extensions which are contained in that header at any given time. The extension appendices for provisional extensions note their provisional status, and link back to this section for more information. Provisional extensions are intended to provide early access for bleeding-edge developers, with the understanding that extension interfaces may change in response to developer feedback. Provisional extensions are very likely to eventually be updated and released as non-provisional extensions, but there is no guarantee this will happen, or how long it will take if it does happen.