// Copyright (c) 2016-2018 Khronos Group. This work is licensed under a // Creative Commons Attribution 4.0 International License; see // http://creativecommons.org/licenses/by/4.0/ [appendix] [[boilerplate]] = 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. [[boilerplate-headers]] == 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. [[boilerplate-vulkan-h]] === Vulkan Combined API Header `vulkan.h` (Informative) Applications normally will include the header `vulkan.h`. In turn, `vulkan.h` always includes the following headers: * <>, defining platform-specific macros and headers. * <>, 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 <> to be included. [[boilerplate-platform-macros]] === 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. [[boilerplate-platform-specific-calling-conventions]] ==== Platform-Specific Calling Conventions On many platforms the following macros are empty strings, causing platform- and compiler-specific default calling conventions to be used. // @refBegin VKAPI_ATTR Vulkan function attributes dname: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. // @refEnd VKAPI_ATTR VKAPI_CALL VKAPI_PTR // @refBegin VKAPI_CALL Vulkan function calling conventions dname:VKAPI_CALL is a macro placed after the return type in Vulkan API function declarations. This macro controls calling conventions for MSVC-style compilers. // @refEnd VKAPI_CALL VKAPI_ATTR VKAPI_PTR // @refBegin VKAPI_PTR Vulkan function pointer calling conventions dname: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 dname:VKAPI_ATTR or dname:VKAPI_CALL, depending on the compiler. // @refEnd VKAPI_PTR VKAPI_ATTR VKAPI_CALL With these macros, a Vulkan function declaration takes the form of: [source,c++] ---------------------------------------- VKAPI_ATTR VKAPI_CALL (); ---------------------------------------- Additionally, a Vulkan function pointer type declaration takes the form of: [source,c++] ---------------------------------------- typedef (VKAPI_PTR *PFN_)(); ---------------------------------------- ==== Platform-Specific Header Control // @refBegin VK_NO_STDINT_H Control definition of `` types If the code:VK_NO_STDINT_H macro is defined by the application at compile time, extended integer types used by the Vulkan API, such as code:uint8_t, must: also be defined by the application. Otherwise, the Vulkan headers will not compile. If code:VK_NO_STDINT_H is not defined, the system `` 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. // @refEnd VK_NO_STDINT_H [[boilerplate-vulkan-core]] === 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. [[boilerplate-versions]] ==== Vulkan Version Number Macros <> are packed into integers. These macros manipulate version numbers in useful ways. [open,refpage='VK_VERSION_MAJOR',desc='Extract API major version number',type='defines'] -- dname:VK_VERSION_MAJOR extracts the API major version number from a packed version number: include::../api/defines/VK_VERSION_MAJOR.txt[] -- [open,refpage='VK_VERSION_MINOR',desc='Extract API minor version number',type='defines'] -- dname:VK_VERSION_MINOR extracts the API minor version number from a packed version number: include::../api/defines/VK_VERSION_MINOR.txt[] -- [open,refpage='VK_VERSION_PATCH',desc='Extract API patch version number',type='defines'] -- dname:VK_VERSION_PATCH extracts the API patch version number from a packed version number: include::../api/defines/VK_VERSION_PATCH.txt[] -- [open,refpage='VK_API_VERSION_1_0',desc='Return API version number for Vulkan 1.0',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] -- dname: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 flink:vkGetPhysicalDeviceProperties. include::../api/defines/VK_API_VERSION_1_0.txt[] -- ifdef::VK_VERSION_1_1[] [open,refpage='VK_API_VERSION_1_1',desc='Return API version number for Vulkan 1.1',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] -- dname: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 flink:vkGetPhysicalDeviceProperties. include::../api/defines/VK_API_VERSION_1_1.txt[] -- endif::VK_VERSION_1_1[] [open,refpage='VK_API_VERSION',desc='Deprecated version number macro',type='defines'] -- dname:VK_API_VERSION is now commented out of `vulkan_core.h` and cannot: be used. include::../api/defines/VK_API_VERSION.txt[] -- [open,refpage='VK_MAKE_VERSION',desc='Construct an API version number',type='defines',xrefs='VkApplicationInfo vkCreateInstance'] -- dname:VK_MAKE_VERSION constructs an API version number. include::../api/defines/VK_MAKE_VERSION.txt[] * pname:major is the major version number. * pname:minor is the minor version number. * pname:patch is the patch version number. This macro can: be used when constructing the slink:VkApplicationInfo::pname:apiVersion parameter passed to flink:vkCreateInstance. -- ==== Vulkan Header File Version Number [open,refpage='VK_HEADER_VERSION',desc='Vulkan header file version number',type='defines'] -- dname: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. include::../api/defines/VK_HEADER_VERSION.txt[] -- ==== Vulkan Handle Macros [open,refpage='VK_DEFINE_HANDLE',desc='Declare a dispatchable object handle',type='defines',xrefs='VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue'] -- dname:VK_DEFINE_HANDLE defines a <> type. include::../api/defines/VK_DEFINE_HANDLE.txt[] * pname:object is the name of the resulting C type. The only dispatchable handle types are those related to device and instance management, such as slink:VkDevice. -- [open,refpage='VK_DEFINE_NON_DISPATCHABLE_HANDLE',desc='Declare a non-dispatchable object handle',type='defines',xrefs='VkBuffer'] -- dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a <> type. include::../api/defines/VK_DEFINE_NON_DISPATCHABLE_HANDLE.txt[] * pname:object is the name of the resulting C type. Most Vulkan handle types, such as slink:VkBuffer, are non-dispatchable. [NOTE] .Note ==== The `vulkan_core.h` header allows the dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE definition to be overridden by the application. If dname: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 dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE definition. ==== -- [open,refpage='VK_NULL_HANDLE',desc='Reserved non-valid object handle',type='defines'] -- dname: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 <>. include::../api/defines/VK_NULL_HANDLE.txt[] -- [[boilerplate-wsi-header]] == Window System-Specific Header Control (Informative) // @refBegin WSIheaders Control inclusion of window system interface extensions 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 <>. [[boilerplate-wsi-header-table]] .Window System Extensions and Headers [options="header"] |==== | Extension Name | Window System Name | Platform-specific Header | Required External Headers | Controlling `vulkan.h` Macro | `<>` | Android | `vulkan_android.h` | None | dname:VK_USE_PLATFORM_ANDROID_KHR | `<>` | Wayland | `vulkan_wayland.h` | `` | dname:VK_USE_PLATFORM_WAYLAND_KHR | `<>`, `<>`, `<>`, `<>`, `<>`, ifdef::VK_NV_external_memory_win32[] `<>`, endif::VK_NV_external_memory_win32[] ifdef::VK_NV_win32_keyed_mutex[] `<>` endif::VK_NV_win32_keyed_mutex[] | Microsoft Windows | `vulkan_win32.h` | `` | dname:VK_USE_PLATFORM_WIN32_KHR | `<>` | X11 Xcb | `vulkan_xcb.h` | `` | dname:VK_USE_PLATFORM_XCB_KHR | `<>` | X11 Xlib | `vulkan_xlib.h` | `` | dname:VK_USE_PLATFORM_XLIB_KHR ifdef::VK_EXT_acquire_xlib_display[] | `<>` | X11 XRAndR | `vulkan_xlib_xrandr.h` | ``, `` | dname:VK_USE_PLATFORM_XLIB_XRANDR_EXT endif::VK_EXT_acquire_xlib_display[] ifdef::VK_MVK_ios_surface[] | `<>` | iOS | `vulkan_ios.h` | None | dname:VK_USE_PLATFORM_IOS_MVK endif::VK_MVK_ios_surface[] ifdef::VK_MVK_macos_surface[] | `<>` | macOS | `vulkan_macos.h` | None | dname:VK_USE_PLATFORM_MACOS_MVK endif::VK_MVK_macos_surface[] ifdef::VK_NN_vi_surface[] | `<>` | VI | `vulkan_vi.h` | None | dname:VK_USE_PLATFORM_VI_NN endif::VK_NN_vi_surface[] |==== [NOTE] .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. ==== // @refEnd WSIheaders