E.3. Macro Definitions in vulkan.h

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

### E.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.
    //#define VK_API_VERSION VK_MAKE_VERSION(1, 0, 0)

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

### E.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
    #define VK_HEADER_VERSION 25

### E.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(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

- `object` is the name of the resulting C type.

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

| Note
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