Appendix F: 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 https://www.khronos.org/registry/vulkan/#apiregistry .

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 vulkan.h (Informative)

Applications normally will include the header vulkan.h. In turn, vulkan.h always includes the following headers:

  • vk_platform.h, defining platform-specific macros and headers.

  • vulkan_core.h, defining APIs for the Vulkan core and all registered extensions other than window system-specific extensions.

In addition, specific preprocessor macros defined at the time vulkan.h is included cause header files for the corresponding window system-specific extension interfaces to be included.

Vulkan Platform-Specific Header vk_platform.h (Informative)

Platform-specific macros and interfaces are defined in vk_platform.h. These macros are used to control platform-dependent behavior, and their exact definitions are under the control of specific platforms and Vulkan implementations.

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 function declarations. This macro controls calling conventions for C++11 and GCC/Clang-style compilers.

VKAPI_CALL is a macro placed after the return type in Vulkan API function declarations. 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 definition as VKAPI_ATTR or VKAPI_CALL, depending on the compiler.

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

If the VK_NO_STDINT_H macro is defined by the application at compile time, extended integer types used by the Vulkan API, such as uint8_t, must also be defined by the application. Otherwise, the Vulkan headers will not compile. If 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 vulkan_core.h

Applications that do not make use of window system-specific extensions may simply include 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 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)// Patch version should always be set to 0

VK_API_VERSION_1_1 returns the API version number for Vulkan 1.1. 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.1 version number
#define VK_API_VERSION_1_1 VK_MAKE_VERSION(1, 1, 0)// Patch version should always be set to 0

VK_API_VERSION is now commented out of vulkan_core.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) // 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))
  • 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.

Vulkan Header File Version Number

VK_HEADER_VERSION is the version number of the vulkan_core.h header. This value is kept synchronized with the patch version of the released Specification.

// Version of this file
#define VK_HEADER_VERSION 92
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_core.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 vulkan_core.h 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

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 that platform. Before including these platform-specific Vulkan headers, applications must include both 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.h includes 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 vulkan.h.

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.

Table 87. Window System Extensions and Headers
Extension Name Window System Name Platform-specific Header Required External Headers Controlling vulkan.h Macro

VK_KHR_android_surface

Android

vulkan_android.h

None

VK_USE_PLATFORM_ANDROID_KHR

VK_KHR_wayland_surface

Wayland

vulkan_wayland.h

<wayland-client.h>

VK_USE_PLATFORM_WAYLAND_KHR

VK_KHR_win32_surface, VK_KHR_external_memory_win32, VK_KHR_win32_keyed_mutex, VK_KHR_external_semaphore_win32, VK_KHR_external_fence_win32, VK_NV_external_memory_win32, VK_NV_win32_keyed_mutex

Microsoft Windows

vulkan_win32.h

<windows.h>

VK_USE_PLATFORM_WIN32_KHR

VK_KHR_xcb_surface

X11 Xcb

vulkan_xcb.h

<xcb/xcb.h>

VK_USE_PLATFORM_XCB_KHR

VK_KHR_xlib_surface

X11 Xlib

vulkan_xlib.h

<X11/Xlib.h>

VK_USE_PLATFORM_XLIB_KHR

VK_EXT_acquire_xlib_display

X11 XRAndR

vulkan_xlib_xrandr.h

<X11/Xlib.h>, <X11/extensions/Xrandr.h>

VK_USE_PLATFORM_XLIB_XRANDR_EXT

VK_MVK_ios_surface

iOS

vulkan_ios.h

None

VK_USE_PLATFORM_IOS_MVK

VK_MVK_macos_surface

macOS

vulkan_macos.h

None

VK_USE_PLATFORM_MACOS_MVK

VK_NN_vi_surface

VI

vulkan_vi.h

None

VK_USE_PLATFORM_VI_NN

Note

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.