1// Copyright 2016-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-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://registry.khronos.org/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 `{full_header}` (Informative) 36 37Applications normally will include the header `{full_header}`. 38In turn, `{full_header}` always includes the following headers: 39 40 * <<boilerplate-platform-macros,`vk_platform.h`>>, defining 41 platform-specific macros and headers. 42 * <<boilerplate-vulkan-core,`{core_header}`>>, defining APIs for the 43 Vulkan core and all registered extensions _other_ than 44 <<boilerplate-wsi-header, window system-specific>> and 45 <<boilerplate-provisional-header, provisional>> extensions, which are 46 included in separate header files. 47 48In addition, specific preprocessor macros defined at the time 49`{full_header}` is included cause header files for the corresponding window 50system-specific and provisional interfaces to be included, as described 51below. 52 53 54[[boilerplate-platform-macros]] 55=== Vulkan Platform-Specific Header `vk_platform.h` (Informative) 56 57Platform-specific macros and interfaces are defined in `vk_platform.h`. 58These macros are used to control platform-dependent behavior, and their 59exact definitions are under the control of specific platforms and Vulkan 60implementations. 61 62 63[[boilerplate-platform-specific-calling-conventions]] 64==== Platform-Specific Calling Conventions 65 66On many platforms the following macros are empty strings, causing platform- 67and compiler-specific default calling conventions to be used. 68 69[open,refpage='VKAPI_ATTR',desc='Vulkan function attribute macro',type='freeform',anchor='boilerplate-platform-specific-calling-conventions',xrefs='VKAPI_CALL VKAPI_PTR'] 70-- 71dname:VKAPI_ATTR is a macro placed before the return type in Vulkan API 72function declarations. 73This macro controls calling conventions for C++11 and GCC/Clang-style 74compilers. 75-- 76 77[open,refpage='VKAPI_CALL',desc='Vulkan function calling conventions macro',type='freeform',anchor='boilerplate-platform-specific-calling-conventions',xrefs='VKAPI_ATTR VKAPI_PTR'] 78-- 79dname:VKAPI_CALL is a macro placed after the return type in Vulkan API 80function declarations. 81This macro controls calling conventions for MSVC-style compilers. 82-- 83 84[open,refpage='VKAPI_PTR',desc='Vulkan function pointer calling conventions macro',type='freeform',anchor='boilerplate-platform-specific-calling-conventions',xrefs='VKAPI_ATTR VKAPI_CALL'] 85-- 86dname:VKAPI_PTR is a macro placed between the '(' and '*' in Vulkan API 87function pointer declarations. 88This macro also controls calling conventions, and typically has the same 89definition as dname:VKAPI_ATTR or dname:VKAPI_CALL, depending on the 90compiler. 91-- 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 100Additionally, 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[[boilerplate-platform-specific-header-control]] 109==== Platform-Specific Header Control 110 111[open,refpage='VK_NO_STDINT_H',desc='Control definition of <stdint.h> types',type='freeform',anchor='boilerplate-platform-specific-header-control'] 112-- 113If the dname:VK_NO_STDINT_H macro is defined by the application at compile 114time, extended integer types used by the Vulkan API, such as code:uint8_t, 115must: also be defined by the application. 116Otherwise, the Vulkan headers will not compile. 117If dname:VK_NO_STDINT_H is not defined, the system `<stdint.h>` is used to 118define these types. 119There is a fallback path when Microsoft Visual Studio version 2008 and 120earlier versions are detected at compile time. 121-- 122 123[open,refpage='VK_NO_STDDEF_H',desc='Control definition of <stddef.h> types',type='freeform',anchor='boilerplate-platform-specific-header-control'] 124-- 125If the dname:VK_NO_STDDEF_H macro is defined by the application at compile 126time, code:size_t, must: also be defined by the application. 127Otherwise, the Vulkan headers will not compile. 128If dname:VK_NO_STDDEF_H is not defined, the system `<stddef.h>` is used to 129define this type. 130-- 131 132 133[[boilerplate-vulkan-core]] 134=== Vulkan Core API Header `{core_header}` 135 136Applications that do not make use of window system-specific extensions may 137simply include `{core_header}` instead of `{full_header}`, although there is 138usually no reason to do so. 139In addition to the Vulkan API, `{core_header}` also defines a small number 140of C preprocessor macros that are described below. 141 142 143 144 145 146==== Vulkan Header File Version Number 147 148[open,refpage='VK_HEADER_VERSION',desc='Vulkan header file version number',type='defines'] 149-- 150dname:VK_HEADER_VERSION is the version number of the `{core_header}` header. 151This value is kept synchronized with the patch version of the released 152Specification. 153 154include::{generated}/api/defines/VK_HEADER_VERSION.adoc[] 155-- 156 157[open,refpage='VK_HEADER_VERSION_COMPLETE',desc='Vulkan header file complete version number',type='defines'] 158-- 159dname:VK_HEADER_VERSION_COMPLETE is the complete version number of the 160`{core_header}` header, comprising the major, minor, and patch versions. 161The major/minor values are kept synchronized with the complete version of 162the released Specification. 163This value is intended for use by automated tools to identify exactly which 164version of the header was used during their generation. 165 166Applications should not use this value as their 167slink:VkApplicationInfo::pname:apiVersion. 168Instead applications should explicitly select a specific fixed major/minor 169API version using, for example, one of the dname:VK_API_VERSION_*_* values. 170 171include::{generated}/api/defines/VK_HEADER_VERSION_COMPLETE.adoc[] 172-- 173 174[open,refpage='VK_API_VERSION',desc='Deprecated version number macro',type='defines'] 175-- 176dname:VK_API_VERSION is now commented out of `{core_header}` and cannot: be 177used. 178 179include::{generated}/api/defines/VK_API_VERSION.adoc[] 180-- 181 182 183==== Vulkan Handle Macros 184 185[open,refpage='VK_DEFINE_HANDLE',desc='Declare a dispatchable object handle',type='defines',xrefs='VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue'] 186-- 187dname:VK_DEFINE_HANDLE defines a <<fundamentals-objectmodel-overview, 188dispatchable handle>> type. 189 190include::{generated}/api/defines/VK_DEFINE_HANDLE.adoc[] 191 192 * pname:object is the name of the resulting C type. 193 194The only dispatchable handle types are those related to device and instance 195management, such as slink:VkDevice. 196-- 197 198[open,refpage='VK_DEFINE_NON_DISPATCHABLE_HANDLE',desc='Declare a non-dispatchable object handle',type='defines',xrefs='VkBuffer'] 199-- 200dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE defines a 201<<fundamentals-objectmodel-overview, non-dispatchable handle>> type. 202 203include::{generated}/api/defines/VK_DEFINE_NON_DISPATCHABLE_HANDLE.adoc[] 204 205 * pname:object is the name of the resulting C type. 206 207Most Vulkan handle types, such as slink:VkBuffer, are non-dispatchable. 208 209[NOTE] 210.Note 211==== 212The `{core_header}` header allows the 213dlink:VK_DEFINE_NON_DISPATCHABLE_HANDLE and dlink:VK_NULL_HANDLE definitions 214to be overridden by the application. 215If dlink:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when 216`{core_header}` is compiled, the default definitions for 217dlink:VK_DEFINE_NON_DISPATCHABLE_HANDLE and dlink:VK_NULL_HANDLE are 218skipped. 219This allows the application to define a binary-compatible custom handle 220which may: provide more type-safety or other features needed by the 221application. 222Applications must: not define handles in a way that is not binary compatible 223- where binary compatibility is platform dependent. 224==== 225-- 226 227[open,refpage='VK_NULL_HANDLE',desc='Reserved non-valid object handle',type='defines'] 228-- 229dname:VK_NULL_HANDLE is a reserved value representing a non-valid object 230handle. 231It may be passed to and returned from Vulkan commands only when 232<<fundamentals-validusage-handles, specifically allowed>>. 233 234include::{generated}/api/defines/VK_NULL_HANDLE.adoc[] 235-- 236 237[open,refpage='VK_USE_64_BIT_PTR_DEFINES',desc='Defines whether non-dispatchable handles are a 64-bit pointer type or a 64-bit unsigned integer type',type='defines'] 238-- 239dname:VK_USE_64_BIT_PTR_DEFINES defines whether the default non-dispatchable 240handles are declared using either a 64-bit pointer type or a 64-bit unsigned 241integer type. 242 243dname:VK_USE_64_BIT_PTR_DEFINES is set to '1' to use a 64-bit pointer type 244or any other value to use a 64-bit unsigned integer type. 245 246include::{generated}/api/defines/VK_USE_64_BIT_PTR_DEFINES.adoc[] 247 248[NOTE] 249.Note 250==== 251The `{core_header}` header allows the dname:VK_USE_64_BIT_PTR_DEFINES 252definition to be overridden by the application. 253This allows the application to select either a 64-bit pointer type or a 25464-bit unsigned integer type for non-dispatchable handles in the case where 255the predefined preprocessor check does not identify the desired 256configuration. 257==== 258 259[NOTE] 260.Note 261==== 262This macro was introduced starting with the Vulkan 1.2.174 headers, and its 263availability can be checked at compile time by requiring 264`dname:VK_HEADER_VERSION >= 174`. 265 266It is not available if you are using older headers, such as may be shipped 267with an older Vulkan SDK. 268Developers requiring this functionality may wish to include a copy of the 269current Vulkan headers with their project in this case. 270==== 271-- 272 273 274[[boilerplate-wsi-header]] 275== Window System-Specific Header Control (Informative) 276 277[open,refpage='WSIheaders',desc='Control inclusion of window system interface extensions',type='freeform',anchor='boilerplate-wsi-header',xrefs='provisional-headers'] 278-- 279To use a Vulkan extension supporting a platform-specific window system, 280header files for that window system must: be included at compile time, or 281platform-specific types must: be forward-declared. 282The Vulkan header files are unable to determine whether or not an external 283header is available at compile time, so platform-specific extensions are 284provided in separate headers from the core API and platform-independent 285extensions, allowing applications to decide which ones they need to be 286defined and how the external headers are included. 287 288Extensions dependent on particular sets of platform headers, or that 289forward-declare platform-specific types, are declared in a header named for 290that platform. 291Before including these platform-specific Vulkan headers, applications must: 292include both `{core_header}` and any external native headers the platform 293extensions depend on. 294 295As a convenience for applications that do not need the flexibility of 296separate platform-specific Vulkan headers, `{full_header}` includes 297`{core_header}`, and then conditionally includes platform-specific Vulkan 298headers and the external headers they depend on. 299Applications control which platform-specific headers are included by 300#defining macros before including `{full_header}`. 301 302The correspondence between platform-specific extensions, external headers 303they require, the platform-specific header which declares them, and the 304preprocessor macros which enable inclusion by `{full_header}` are shown in 305the <<boilerplate-wsi-header-table,following table>>. 306 307[[boilerplate-wsi-header-table]] 308.Window System Extensions and Headers 309[options="header"] 310|==== 311| Extension Name | Window System Name | Platform-specific Header | Required External Headers | Controlling `{full_header}` Macro 312| `apiext:VK_KHR_android_surface` | Android | `vulkan_android.h` | None | dname:VK_USE_PLATFORM_ANDROID_KHR 313| `apiext:VK_KHR_wayland_surface` | Wayland | `vulkan_wayland.h` | `<wayland-client.h>` | dname:VK_USE_PLATFORM_WAYLAND_KHR 314| `apiext:VK_KHR_win32_surface`, 315 `apiext:VK_KHR_external_memory_win32`, 316 `apiext:VK_KHR_win32_keyed_mutex`, 317 `apiext:VK_KHR_external_semaphore_win32`, 318 `apiext:VK_KHR_external_fence_win32`, 319 `apiext:VK_NV_external_memory_win32`, 320 `apiext:VK_NV_win32_keyed_mutex` 321 | Microsoft Windows | `vulkan_win32.h` | `<windows.h>` | dname:VK_USE_PLATFORM_WIN32_KHR 322| `apiext:VK_KHR_xcb_surface` | X11 Xcb | `vulkan_xcb.h` | `<xcb/xcb.h>` | dname:VK_USE_PLATFORM_XCB_KHR 323| `apiext:VK_KHR_xlib_surface` | X11 Xlib | `vulkan_xlib.h` | `<X11/Xlib.h>` | dname:VK_USE_PLATFORM_XLIB_KHR 324| `apiext:VK_EXT_directfb_surface` | DirectFB | `vulkan_directfb.h` | `<directfb/directfb.h>` | dname:VK_USE_PLATFORM_DIRECTFB_EXT 325| `apiext:VK_EXT_acquire_xlib_display` | X11 XRAndR | `vulkan_xlib_xrandr.h` | `<X11/Xlib.h>`, 326 `<X11/extensions{wbro}/Xrandr.h>` | dname:VK_USE_PLATFORM_XLIB_XRANDR_EXT 327| `apiext:VK_GGP_stream_descriptor_surface`, 328 `apiext:VK_GGP_frame_token` 329 | Google Games Platform | `vulkan_ggp.h` | <ggp_c/vulkan_types.h> | dname:VK_USE_PLATFORM_GGP 330| `apiext:VK_MVK_ios_surface` | iOS | `vulkan_ios.h` | None | dname:VK_USE_PLATFORM_IOS_MVK 331| `apiext:VK_MVK_macos_surface` | macOS | `vulkan_macos.h` | None | dname:VK_USE_PLATFORM_MACOS_MVK 332| `apiext:VK_NN_vi_surface` | VI | `vulkan_vi.h` | None | dname:VK_USE_PLATFORM_VI_NN 333| `apiext:VK_FUCHSIA_imagepipe_surface` | Fuchsia | `vulkan_fuchsia.h` | `<zircon/types.h>` | dname:VK_USE_PLATFORM_FUCHSIA 334| `apiext:VK_EXT_metal_surface` | Metal on CoreAnimation | `vulkan_metal.h` | None | dname:VK_USE_PLATFORM_METAL_EXT 335| `apiext:VK_QNX_screen_surface` | QNX Screen | `vulkan_screen.h` | `<screen/screen.h>` | dname:VK_USE_PLATFORM_SCREEN_QNX 336|==== 337 338[NOTE] 339.Note 340==== 341This section describes the purpose of the headers independently of the 342specific underlying functionality of the window system extensions 343themselves. 344Each extension name will only link to a description of that extension when 345viewing a specification built with that extension included. 346==== 347-- 348 349 350[[boilerplate-provisional-header]] 351== Provisional Extension Header Control (Informative) 352 353[open,refpage='provisional-headers',desc='Control inclusion of provisional extensions',type='freeform',alias='VK_ENABLE_BETA_EXTENSIONS',anchor='boilerplate-provisional-header',xrefs='WSIheaders'] 354-- 355_Provisional_ extensions should: not be used in production applications. 356The functionality defined by such extensions may: change in ways that break 357backwards compatibility between revisions, and before final release of a 358non-provisional version of that extension. 359 360Provisional extensions are defined in a separate _provisional header_, 361`vulkan_beta.h`, allowing applications to decide whether or not to include 362them. 363The mechanism is similar to <<boilerplate-wsi-header, window system-specific 364headers>>: before including `vulkan_beta.h`, applications must: include 365`{core_header}`. 366 367[NOTE] 368.Note 369==== 370Sometimes a provisional extension will include a subset of its interfaces in 371`{core_header}`. 372This may occur if the provisional extension is promoted from an existing 373vendor or EXT extension and some of the existing interfaces are defined as 374aliases of the provisional extension interfaces. 375All other interfaces of that provisional extension which are not aliased 376will be included in `vulkan_beta.h`. 377==== 378 379As a convenience for applications, `{full_header}` conditionally includes 380`vulkan_beta.h`. 381Applications can: control inclusion of `vulkan_beta.h` by #defining the 382macro etext:VK_ENABLE_BETA_EXTENSIONS before including `{full_header}`. 383 384[NOTE] 385.Note 386==== 387Starting in version 1.2.171 of the Specification, all provisional enumerants 388are protected by the macro etext:VK_ENABLE_BETA_EXTENSIONS. 389Applications needing to use provisional extensions must always define this 390macro, even if they are explicitly including `vulkan_beta.h`. 391This is a minor change to behavior, affecting only provisional extensions. 392==== 393 394[NOTE] 395.Note 396==== 397This section describes the purpose of the provisional header independently 398of the specific provisional extensions which are contained in that header at 399any given time. 400The extension appendices for provisional extensions note their provisional 401status, and link back to this section for more information. 402Provisional extensions are intended to provide early access for 403bleeding-edge developers, with the understanding that extension interfaces 404may change in response to developer feedback. 405Provisional extensions are very likely to eventually be updated and released 406as non-provisional extensions, but there is no guarantee this will happen, 407or how long it will take if it does happen. 408==== 409-- 410 411 412[[boilerplate-video-std-headers]] 413== Video Std Headers 414 415Performing video coding operations usually involves the application having 416to provide various parameters, data structures, or other syntax elements 417specific to the particular video compression standard used, and the 418associated semantics are covered by the specification of those. 419 420The interface descriptions of these are available in the header files 421derived from the `video.xml` XML file, which is the canonical 422machine-readable description of data structures and enumerations that are 423associated with the externally-provided video compression standards. 424 425[[boilerplate-video-std-header-table]] 426.Video Std Headers 427[options="header"] 428|==== 429| Video Std Header Name | Description | Header File | Related Extensions 430| `vulkan_video_codecs_common` | Codec-independent common definitions | `<vk_video/vulkan_video_codecs_common.h>` | - 431| `vulkan_video_codec_h264std` | ITU-T H.264 common definitions | `<vk_video/vulkan_video_codec_h264std.h>` | apiext:VK_KHR_video_decode_h264, apiext:VK_EXT_video_encode_h264 432| `vulkan_video_codec_h264std_decode` | ITU-T H.264 decode-specific definitions | `<vk_video/vulkan_video_codec_h264std_decode.h>` | apiext:VK_KHR_video_decode_h264 433| `vulkan_video_codec_h264std_encode` | ITU-T H.264 encode-specific definitions | `<vk_video/vulkan_video_codec_h264std_encode.h>` | apiext:VK_EXT_video_encode_h264 434| `vulkan_video_codec_h265std` | ITU-T H.265 common definitions | `<vk_video/vulkan_video_codec_h265std.h>` | apiext:VK_KHR_video_decode_h265, apiext:VK_EXT_video_encode_h265 435| `vulkan_video_codec_h265std_decode` | ITU-T H.265 decode-specific definitions | `<vk_video/vulkan_video_codec_h265std_decode.h>` | apiext:VK_KHR_video_decode_h265 436| `vulkan_video_codec_h265std_encode` | ITU-T H.265 encode-specific definitions | `<vk_video/vulkan_video_codec_h265std_encode.h>` | apiext:VK_EXT_video_encode_h265 437|==== 438