1// Copyright (c) 2016-2018 Khronos Group. This work is licensed under a 2// Creative Commons Attribution 4.0 International License; see 3// http://creativecommons.org/licenses/by/4.0/ 4 5[appendix] 6[[boilerplate]] 7= API Boilerplate 8 9This appendix defines Vulkan API features that are infrastructure required 10for a complete functional description of Vulkan, but do not logically belong 11elsewhere in the Specification. 12 13 14[[boilerplate-headers]] 15== Vulkan Header Files 16 17Vulkan is defined as an API in the C99 language. 18Khronos provides a corresponding set of header files for applications using 19the API, which may be used in either C or C++ code. 20The interface descriptions in the specification are the same as the 21interfaces defined in these header files, and both are derived from the 22`vk.xml` XML API Registry, which is the canonical machine-readable 23description of the Vulkan API. 24The Registry, scripts used for processing it into various forms, and 25documentation of the registry schema are available as described at 26https://www.khronos.org/registry/vulkan/#apiregistry . 27 28Language bindings for other languages can be defined using the information 29in the Specification and the Registry. 30Khronos does not provide any such bindings, but third-party developers have 31created some additional bindings. 32 33 34[[boilerplate-vulkan-h]] 35=== Vulkan Combined API Header `vulkan.h` (Informative) 36 37Applications normally will include the header `vulkan.h`. 38In turn, `vulkan.h` always includes the following headers: 39 40 * <<boilerplate-platform-macros,`vk_platform.h`>>, defining 41 platform-specific macros and headers. 42 * <<boilerplate-vulkan-core,`vulkan_core.h`>>, defining APIs for the 43 Vulkan core and all registered extensions _other_ than window 44 system-specific extensions. 45 46In addition, specific preprocessor macros defined at the time `vulkan.h` is 47included cause header files for the corresponding <<boilerplate-wsi-header, 48window system-specific extension interfaces>> to be included. 49 50 51[[boilerplate-platform-macros]] 52=== Vulkan Platform-Specific Header `vk_platform.h` (Informative) 53 54Platform-specific macros and interfaces are defined in `vk_platform.h`. 55These macros are used to control platform-dependent behavior, and their 56exact definitions are under the control of specific platforms and Vulkan 57implementations. 58 59 60[[boilerplate-platform-specific-calling-conventions]] 61==== Platform-Specific Calling Conventions 62 63On many platforms the following macros are empty strings, causing platform- 64and compiler-specific default calling conventions to be used. 65 66// @refBegin VKAPI_ATTR Vulkan function attributes 67 68dname:VKAPI_ATTR is a macro placed before the return type in Vulkan API 69function declarations. 70This macro controls calling conventions for C++11 and GCC/Clang-style 71compilers. 72 73// @refEnd VKAPI_ATTR VKAPI_CALL VKAPI_PTR 74 75// @refBegin VKAPI_CALL Vulkan function calling conventions 76 77dname:VKAPI_CALL is a macro placed after the return type in Vulkan API 78function declarations. 79This macro controls calling conventions for MSVC-style compilers. 80 81// @refEnd VKAPI_CALL VKAPI_ATTR VKAPI_PTR 82 83// @refBegin VKAPI_PTR Vulkan function pointer calling conventions 84 85dname:VKAPI_PTR is a macro placed between the '(' and '*' in Vulkan API 86function pointer declarations. 87This macro also controls calling conventions, and typically has the same 88definition as dname:VKAPI_ATTR or dname:VKAPI_CALL, depending on the 89compiler. 90 91// @refEnd VKAPI_PTR VKAPI_ATTR VKAPI_CALL 92 93With these macros, a Vulkan function declaration takes the form of: 94 95[source,c++] 96---------------------------------------- 97VKAPI_ATTR <return_type> VKAPI_CALL <command_name>(<command_parameters>); 98---------------------------------------- 99 100Additionaly, a Vulkan function pointer type declaration takes the form of: 101 102[source,c++] 103---------------------------------------- 104typedef <return_type> (VKAPI_PTR *PFN_<command_name>)(<command_parameters>); 105---------------------------------------- 106 107 108==== Platform-Specific Header Control 109 110// @refBegin VK_NO_STDINT_H Control definition of `<stdint.h>` types 111 112If the code:VK_NO_STDINT_H macro is defined by the application at compile 113time, extended integer types used by the Vulkan API, such as code:uint8_t, 114must: also be defined by the application. 115Otherwise, the Vulkan headers will not compile. 116If code:VK_NO_STDINT_H is not defined, the system `<stdint.h>` is used to 117define these types. 118There is a fallback path when Microsoft Visual Studio version 2008 and 119earlier versions are detected at compile time. 120 121// @refEnd VK_NO_STDINT_H 122 123 124[[boilerplate-vulkan-core]] 125=== Vulkan Core API Header `vulkan_core.h` 126 127Applications that do not make use of window system-specific extensions may 128simply include `vulkan_core.h` instead of `vulkan.h`, although there is 129usually no reason to do so. 130In addition to the Vulkan API, `vulkan_core.h` also defines a small number 131of C preprocessor macros that are described below. 132 133 134[[boilerplate-versions]] 135==== Vulkan Version Number Macros 136 137<<fundamentals-versionnum,API Version Numbers>> are packed into integers. 138These macros manipulate version numbers in useful ways. 139 140[open,refpage='VK_VERSION_MAJOR',desc='Extract API major version number',type='defines'] 141-- 142 143dname:VK_VERSION_MAJOR extracts the API major version number from a packed 144version number: 145 146include::../api/defines/VK_VERSION_MAJOR.txt[] 147 148-- 149 150[open,refpage='VK_VERSION_MINOR',desc='Extract API minor version number',type='defines'] 151-- 152 153dname:VK_VERSION_MINOR extracts the API minor version number from a packed 154version number: 155 156include::../api/defines/VK_VERSION_MINOR.txt[] 157 158-- 159 160[open,refpage='VK_VERSION_PATCH',desc='Extract API patch version number',type='defines'] 161-- 162 163dname:VK_VERSION_PATCH extracts the API patch version number from a packed 164version number: 165 166include::../api/defines/VK_VERSION_PATCH.txt[] 167 168-- 169 170[open,refpage='VK_API_VERSION_1_0',desc='Return API version number for Vulkan 1.0',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] 171-- 172 173dname:VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0. 174The patch version number in this macro will always be zero. 175The supported patch version for a physical device can: be queried with 176flink:vkGetPhysicalDeviceProperties. 177 178include::../api/defines/VK_API_VERSION_1_0.txt[] 179 180-- 181 182ifdef::VK_VERSION_1_1[] 183[open,refpage='VK_API_VERSION_1_1',desc='Return API version number for Vulkan 1.1',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties'] 184-- 185 186dname:VK_API_VERSION_1_1 returns the API version number for Vulkan 1.1. 187The patch version number in this macro will always be zero. 188The supported patch version for a physical device can: be queried with 189flink:vkGetPhysicalDeviceProperties. 190 191include::../api/defines/VK_API_VERSION_1_1.txt[] 192 193-- 194endif::VK_VERSION_1_1[] 195 196[open,refpage='VK_API_VERSION',desc='Deprecated version number macro',type='defines'] 197-- 198 199dname:VK_API_VERSION is now commented out of `vulkan_core.h` and cannot: be 200used. 201 202include::../api/defines/VK_API_VERSION.txt[] 203 204-- 205 206[open,refpage='VK_MAKE_VERSION',desc='Construct an API version number',type='defines',xrefs='VkApplicationInfo vkCreateInstance'] 207-- 208 209dname:VK_MAKE_VERSION constructs an API version number. 210 211include::../api/defines/VK_MAKE_VERSION.txt[] 212 213 * pname:major is the major version number. 214 * pname:minor is the minor version number. 215 * pname:patch is the patch version number. 216 217This macro can: be used when constructing the 218slink:VkApplicationInfo::pname:apiVersion parameter passed to 219flink:vkCreateInstance. 220 221-- 222 223 224==== Vulkan Header File Version Number 225 226[open,refpage='VK_HEADER_VERSION',desc='Vulkan header file version number',type='defines'] 227-- 228 229dname:VK_HEADER_VERSION is the version number of the `vulkan_core.h` header. 230This value is kept synchronized with the patch version of the released 231Specification. 232 233include::../api/defines/VK_HEADER_VERSION.txt[] 234 235-- 236 237 238==== Vulkan Handle Macros 239 240[open,refpage='VK_DEFINE_HANDLE',desc='Declare a dispatchable object handle',type='defines',xrefs='VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue'] 241-- 242 243dname:VK_DEFINE_HANDLE defines a <<fundamentals-objectmodel-overview, 244dispatchable handle>> type. 245 246include::../api/defines/VK_DEFINE_HANDLE.txt[] 247 248 * pname:object is the name of the resulting C type. 249 250The only dispatchable handle types are those related to device and instance 251management, such as slink:VkDevice. 252 253-- 254 255[open,refpage='VK_DEFINE_NON_DISPATCHABLE_HANDLE',desc='Declare a non-dispatchable object handle',type='defines',xrefs='VkBuffer'] 256-- 257 258dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a 259<<fundamentals-objectmodel-overview, non-dispatchable handle>> type. 260 261include::../api/defines/VK_DEFINE_NON_DISPATCHABLE_HANDLE.txt[] 262 263 * pname:object is the name of the resulting C type. 264 265Most Vulkan handle types, such as slink:VkBuffer, are non-dispatchable. 266 267[NOTE] 268.Note 269==== 270The `vulkan_core.h` header allows the 271dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE definition to be overridden by the 272application. 273If dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when 274`vulkan_core.h` is compiled, the default definition is skipped. 275This allows the application to define a binary-compatible custom handle 276which may: provide more type-safety or other features needed by the 277application. 278Behavior is undefined if the application defines a non-binary-compatible 279handle and may: result in memory corruption or application termination. 280Binary compatibility is platform dependent so the application must: be 281careful if it overrides the default dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE 282definition. 283==== 284 285-- 286 287[open,refpage='VK_NULL_HANDLE',desc='Reserved non-valid object handle',type='defines'] 288-- 289 290dname:VK_NULL_HANDLE is a reserved value representing a non-valid object 291handle. 292It may be passed to and returned from Vulkan commands only when 293<<fundamentals-validusage-handles, specifically allowed>>. 294 295include::../api/defines/VK_NULL_HANDLE.txt[] 296 297-- 298 299 300[[boilerplate-wsi-header]] 301== Window System-Specific Header Control (Informative) 302 303// @refBegin WSIheaders Control inclusion of window system interface extensions 304 305To use a Vulkan extension supporting a platform-specific window system, 306header files for that window systems must: be included at compile time, or 307platform-specific types must: be forward-declared. 308The Vulkan header files cannot determine whether or not an external header 309is available at compile time, so platform-specific extensions are provided 310in separate headers from the core API and platform-independent extensions, 311allowing applications to decide which ones should be defined and how the 312external headers are included. 313 314Extensions dependent on particular sets of platform headers, or that 315forward-declare platform-specific types, are declared in a header named for 316that platform. 317Before including these platform-specific Vulkan headers, applications must: 318include both `vulkan_core.h` and any external native headers the platform 319extensions depend on. 320 321As a convenience for applications that do not need the flexibility of 322separate platform-specific Vulkan headers, `vulkan.h` includes 323`vulkan_core.h`, and then conditionally includes platform-specific Vulkan 324headers and the external headers they depend on. 325Applications control which platform-specific headers are included by 326#defining macros before including `vulkan.h`. 327 328The correspondence between platform-specific extensions, external headers 329they require, the platform-specific header which declares them, and the 330preprocessor macros which enable inclusion by `vulkan.h` are shown in the 331<<boilerplate-wsi-header-table,following table>>. 332 333[[boilerplate-wsi-header-table]] 334.Window System Extensions and Headers 335[options="header"] 336|==== 337| Extension Name | Window System Name | Platform-specific Header | Required External Headers | Controlling `vulkan.h` Macro 338| `<<VK_KHR_android_surface>>` | Android | `vulkan_android.h` | None | dname:VK_USE_PLATFORM_ANDROID_KHR 339| `<<VK_KHR_mir_surface>>` | Mir | `vulkan_mir.h` | `<mir_toolkit/client_types.h>` | dname:VK_USE_PLATFORM_MIR_KHR 340| `<<VK_KHR_wayland_surface>>` | Wayland | `vulkan_wayland.h` | `<wayland-client.h>` | dname:VK_USE_PLATFORM_WAYLAND_KHR 341| `<<VK_KHR_win32_surface>>`, 342 `<<VK_KHR_external_memory_win32>>`, 343 `<<VK_KHR_win32_keyed_mutex>>`, 344 `<<VK_KHR_external_semaphore_win32>>`, 345 `<<VK_KHR_external_fence_win32>>`, 346ifdef::VK_NV_external_memory_win32[] 347 `<<VK_NV_external_memory_win32>>`, 348endif::VK_NV_external_memory_win32[] 349ifdef::VK_NV_win32_keyed_mutex[] 350 `<<VK_NV_win32_keyed_mutex>>` 351endif::VK_NV_win32_keyed_mutex[] 352 | Microsoft Windows | `vulkan_win32.h` | `<windows.h>` | dname:VK_USE_PLATFORM_WIN32_KHR 353| `<<VK_KHR_xcb_surface>>` | X11 Xcb | `vulkan_xcb.h` | `<xcb/xcb.h>` | dname:VK_USE_PLATFORM_XCB_KHR 354| `<<VK_KHR_xlib_surface>>` | X11 Xlib | `vulkan_xlib.h` | `<X11/Xlib.h>` | dname:VK_USE_PLATFORM_XLIB_KHR 355ifdef::VK_EXT_acquire_xlib_display[] 356| `<<VK_EXT_acquire_xlib_display>>` | X11 XRAndR | `vulkan_xlib_xrandr.h` | `<X11/Xlib.h>`, 357 `<X11/extensions/Xrandr.h>` | dname:VK_USE_PLATFORM_XLIB_XRANDR_EXT 358endif::VK_EXT_acquire_xlib_display[] 359ifdef::VK_MVK_ios_surface[] 360| `<<VK_MVK_ios_surface>>` | iOS | `vulkan_ios.h` | None | dname:VK_USE_PLATFORM_IOS_MVK 361endif::VK_MVK_ios_surface[] 362ifdef::VK_MVK_macos_surface[] 363| `<<VK_MVK_macos_surface>>` | macOS | `vulkan_macos.h` | None | dname:VK_USE_PLATFORM_MACOS_MVK 364endif::VK_MVK_macos_surface[] 365ifdef::VK_NN_vi_surface[] 366| `<<VK_NN_vi_surface>>` | VI | `vulkan_vi.h` | None | dname:VK_USE_PLATFORM_VI_NN 367endif::VK_NN_vi_surface[] 368|==== 369 370[NOTE] 371.Note 372==== 373This section describes the purpose of the headers independently of the 374specific underlying functionality of the window system extensions 375themselves. 376Each extension name will only link to a description of that extension when 377viewing a specification built with that extension included. 378==== 379 380// @refEnd WSIheaders 381