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