D.3. Macro Definitions in vulkan.h

Vulkan is defined as a C API. The supplied vulkan.h header defines a small number of C preprocessor macros that are described below.

D.3.1. 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 version number:


#define VK_VERSION_MAJOR(version) ((uint32_t)(version) >> 22)

VK_VERSION_MINOR extracts the API minor version number from a packed version number:


#define VK_VERSION_MINOR(version) (((uint32_t)(version) >> 12) & 0x3ff)

VK_VERSION_PATCH extracts the API patch version number from a packed version number:


#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 vkGetPhysicalDeviceProperties.


// Vulkan 1.0 version number
#define VK_API_VERSION_1_0 VK_MAKE_VERSION(1, 0, 0)

VK_API_VERSION is now commented out of vulkan.h and cannot be used.


// 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.

VK_MAKE_VERSION constructs an API version number.


#define VK_MAKE_VERSION(major, minor, patch) \
    (((major) << 22) | ((minor) << 12) | (patch))

  • major is the major version number.
  • minor is the minor version number.
  • patch is the patch version number.

This macro can be used when constructing the VkApplicationInfo::apiVersion parameter passed to vkCreateInstance.

D.3.2. Vulkan Header File Version Number

VK_HEADER_VERSION is the version number of the vulkan.h header. This value is currently kept synchronized with the release number of the Specification. However, it is not guaranteed to remain synchronized, since most Specification updates have no effect on vulkan.h.


// Version of this file

D.3.3. Vulkan Handle macros

VK_DEFINE_HANDLE defines a dispatchable handle type.


#define VK_DEFINE_HANDLE(object) typedef struct object##_T* object;

  • object is 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.


#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;
        #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object;

  • object is the name of the resulting C type.

Most Vulkan handle types, such as VkBuffer, are non-dispatchable.


The vulkan.h header allows the VK_DEFINE_NON_DISPATCHABLE_HANDLE definition to be overridden by the application. If VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when the vulkan.h header is compiled the default definition is skipped. This allows the application to define a binary-compatible custom handle which may provide more type-safety or other features needed by the application. Behavior is undefined if the application defines a non-binary-compatible handle and may result in memory corruption or application termination. Binary compatibility is platform dependent so the application must be careful if it overrides the default VK_DEFINE_NON_DISPATCHABLE_HANDLE definition.

VK_NULL_HANDLE is a reserved value representing a non-valid object handle. It may be passed to and returned from Vulkan commands only when specifically allowed.


#define VK_NULL_HANDLE 0