| // Copyright 2016-2023 The Khronos Group Inc. |
| // |
| // SPDX-License-Identifier: CC-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 |
| ifndef::VKSC_VERSION_1_0[https://registry.khronos.org/vulkan/#apiregistry .] |
| ifdef::VKSC_VERSION_1_0[https://registry.khronos.org/vulkansc/#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 `{full_header}` (Informative) |
| |
| Applications normally will include the header `{full_header}`. |
| In turn, `{full_header}` always includes the following headers: |
| |
| * <<boilerplate-platform-macros,`vk_platform.h`>>, defining |
| platform-specific macros and headers. |
| * <<boilerplate-vulkan-core,`{core_header}`>>, defining APIs for the |
| Vulkan core and all registered extensions _other_ than |
| <<boilerplate-wsi-header, window system-specific>> and |
| <<boilerplate-provisional-header, provisional>> extensions, which are |
| included in separate header files. |
| |
| In addition, specific preprocessor macros defined at the time |
| `{full_header}` is included cause header files for the corresponding window |
| system-specific and provisional interfaces to be included, as described |
| below. |
| |
| |
| [[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. |
| |
| [open,refpage='VKAPI_ATTR',desc='Vulkan function attribute macro',type='freeform',anchor='boilerplate-platform-specific-calling-conventions',xrefs='VKAPI_CALL VKAPI_PTR'] |
| -- |
| 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. |
| -- |
| |
| [open,refpage='VKAPI_CALL',desc='Vulkan function calling conventions macro',type='freeform',anchor='boilerplate-platform-specific-calling-conventions',xrefs='VKAPI_ATTR VKAPI_PTR'] |
| -- |
| 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. |
| -- |
| |
| [open,refpage='VKAPI_PTR',desc='Vulkan function pointer calling conventions macro',type='freeform',anchor='boilerplate-platform-specific-calling-conventions',xrefs='VKAPI_ATTR VKAPI_CALL'] |
| -- |
| 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. |
| -- |
| |
| With these macros, a Vulkan function declaration takes the form of: |
| |
| [source,c++] |
| ---- |
| VKAPI_ATTR <return_type> VKAPI_CALL <command_name>(<command_parameters>); |
| ---- |
| |
| Additionally, a Vulkan function pointer type declaration takes the form of: |
| |
| [source,c++] |
| ---- |
| typedef <return_type> (VKAPI_PTR *PFN_<command_name>)(<command_parameters>); |
| ---- |
| |
| |
| [[boilerplate-platform-specific-header-control]] |
| ==== Platform-Specific Header Control |
| |
| [open,refpage='VK_NO_STDINT_H',desc='Control definition of <stdint.h> types',type='freeform',anchor='boilerplate-platform-specific-header-control'] |
| -- |
| If the dname: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 dname: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. |
| -- |
| |
| [open,refpage='VK_NO_STDDEF_H',desc='Control definition of <stddef.h> types',type='freeform',anchor='boilerplate-platform-specific-header-control'] |
| -- |
| If the dname:VK_NO_STDDEF_H macro is defined by the application at compile |
| time, code:size_t, must: also be defined by the application. |
| Otherwise, the Vulkan headers will not compile. |
| If dname:VK_NO_STDDEF_H is not defined, the system `<stddef.h>` is used to |
| define this type. |
| -- |
| |
| |
| [[boilerplate-vulkan-core]] |
| === Vulkan Core API Header `{core_header}` |
| |
| Applications that do not make use of window system-specific extensions may |
| simply include `{core_header}` instead of `{full_header}`, although there is |
| usually no reason to do so. |
| In addition to the Vulkan API, `{core_header}` also defines a small number |
| of C preprocessor macros that are described below. |
| |
| ifdef::VKSC_VERSION_1_0[] |
| `{core_header_hpp}` provides the same functionality as `{core_header}`, but |
| does so in a manner that is aligned for compliance with MISRA C++. |
| In contrast, `{core_header}` is aligned for compliance with MISRA C:2012. |
| endif::VKSC_VERSION_1_0[] |
| |
| |
| |
| |
| ==== 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 `{core_header}` header. |
| This value is kept synchronized with the patch version of the released |
| Specification. |
| |
| include::{generated}/api/defines/VK_HEADER_VERSION.adoc[] |
| -- |
| |
| [open,refpage='VK_HEADER_VERSION_COMPLETE',desc='Vulkan header file complete version number',type='defines'] |
| -- |
| dname:VK_HEADER_VERSION_COMPLETE is the complete version number of the |
| `{core_header}` header, comprising the major, minor, and patch versions. |
| The major/minor values are kept synchronized with the complete version of |
| the released Specification. |
| This value is intended for use by automated tools to identify exactly which |
| version of the header was used during their generation. |
| |
| Applications should not use this value as their |
| slink:VkApplicationInfo::pname:apiVersion. |
| Instead applications should explicitly select a specific fixed major/minor |
| API version using, for example, one of the dname:VK_API_VERSION_*_* values. |
| |
| include::{generated}/api/defines/VK_HEADER_VERSION_COMPLETE.adoc[] |
| -- |
| |
| ifndef::VKSC_VERSION_1_0[] |
| [open,refpage='VK_API_VERSION',desc='Deprecated version number macro',type='defines'] |
| -- |
| dname:VK_API_VERSION is now commented out of `{core_header}` and cannot: be |
| used. |
| |
| include::{generated}/api/defines/VK_API_VERSION.adoc[] |
| -- |
| endif::VKSC_VERSION_1_0[] |
| |
| ==== 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 <<fundamentals-objectmodel-overview, |
| dispatchable handle>> type. |
| |
| include::{generated}/api/defines/VK_DEFINE_HANDLE.adoc[] |
| |
| * 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 |
| <<fundamentals-objectmodel-overview, non-dispatchable handle>> type. |
| |
| include::{generated}/api/defines/VK_DEFINE_NON_DISPATCHABLE_HANDLE.adoc[] |
| |
| * pname:object is the name of the resulting C type. |
| |
| Most Vulkan handle types, such as slink:VkBuffer, are non-dispatchable. |
| |
| [NOTE] |
| .Note |
| ==== |
| The `{core_header}` header allows the |
| dlink:VK_DEFINE_NON_DISPATCHABLE_HANDLE and dlink:VK_NULL_HANDLE definitions |
| to be overridden by the application. |
| If dlink:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when |
| `{core_header}` is compiled, the default definitions for |
| dlink:VK_DEFINE_NON_DISPATCHABLE_HANDLE and dlink:VK_NULL_HANDLE are |
| 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. |
| Applications must: not define handles in a way that is not binary compatible |
| - where binary compatibility is platform dependent. |
| ==== |
| -- |
| |
| [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 |
| <<fundamentals-validusage-handles, specifically allowed>>. |
| |
| include::{generated}/api/defines/VK_NULL_HANDLE.adoc[] |
| -- |
| |
| [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'] |
| -- |
| dname:VK_USE_64_BIT_PTR_DEFINES defines whether the default non-dispatchable |
| handles are declared using either a 64-bit pointer type or a 64-bit unsigned |
| integer type. |
| |
| dname:VK_USE_64_BIT_PTR_DEFINES is set to '1' to use a 64-bit pointer type |
| or any other value to use a 64-bit unsigned integer type. |
| |
| include::{generated}/api/defines/VK_USE_64_BIT_PTR_DEFINES.adoc[] |
| |
| [NOTE] |
| .Note |
| ==== |
| The `{core_header}` header allows the dname:VK_USE_64_BIT_PTR_DEFINES |
| definition to be overridden by the application. |
| This allows the application to select either a 64-bit pointer type or a |
| 64-bit unsigned integer type for non-dispatchable handles in the case where |
| the predefined preprocessor check does not identify the desired |
| configuration. |
| ==== |
| |
| ifndef::VKSC_VERSION_1_0[] |
| [NOTE] |
| .Note |
| ==== |
| This macro was introduced starting with the Vulkan 1.2.174 headers, and its |
| availability can be checked at compile time by requiring |
| `dname:VK_HEADER_VERSION >= 174`. |
| |
| It is not available if you are using older headers, such as may be shipped |
| with an older Vulkan SDK. |
| Developers requiring this functionality may wish to include a copy of the |
| current Vulkan headers with their project in this case. |
| ==== |
| endif::VKSC_VERSION_1_0[] |
| -- |
| |
| |
| [[boilerplate-wsi-header]] |
| == Window System-Specific Header Control (Informative) |
| |
| [open,refpage='WSIheaders',desc='Control inclusion of window system interface extensions',type='freeform',anchor='boilerplate-wsi-header',xrefs='provisional-headers'] |
| -- |
| To use a Vulkan extension supporting a platform-specific window system, |
| header files for that window system must: be included at compile time, or |
| platform-specific types must: be forward-declared. |
| The Vulkan header files are unable to 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 they need to 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 `{core_header}` 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, `{full_header}` includes |
| `{core_header}`, 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 `{full_header}`. |
| |
| 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 `{full_header}` are shown in |
| the <<boilerplate-wsi-header-table,following table>>. |
| |
| [[boilerplate-wsi-header-table]] |
| .Window System Extensions and Headers |
| [options="header"] |
| |==== |
| | Extension Name | Window System Name | Platform-specific Header | Required External Headers | Controlling `{full_header}` Macro |
| | `apiext:VK_KHR_android_surface` | Android | `vulkan_android.h` | None | dname:VK_USE_PLATFORM_ANDROID_KHR |
| | `apiext:VK_KHR_wayland_surface` | Wayland | `vulkan_wayland.h` | `<wayland-client.h>` | dname:VK_USE_PLATFORM_WAYLAND_KHR |
| | `apiext:VK_KHR_win32_surface`, |
| `apiext:VK_KHR_external_memory_win32`, |
| `apiext:VK_KHR_win32_keyed_mutex`, |
| `apiext:VK_KHR_external_semaphore_win32`, |
| `apiext:VK_KHR_external_fence_win32`, |
| `apiext:VK_NV_external_memory_win32`, |
| `apiext:VK_NV_win32_keyed_mutex` |
| | Microsoft Windows | `vulkan_win32.h` | `<windows.h>` | dname:VK_USE_PLATFORM_WIN32_KHR |
| | `apiext:VK_KHR_xcb_surface` | X11 Xcb | `vulkan_xcb.h` | `<xcb/xcb.h>` | dname:VK_USE_PLATFORM_XCB_KHR |
| | `apiext:VK_KHR_xlib_surface` | X11 Xlib | `vulkan_xlib.h` | `<X11/Xlib.h>` | dname:VK_USE_PLATFORM_XLIB_KHR |
| | `apiext:VK_EXT_directfb_surface` | DirectFB | `vulkan_directfb.h` | `<directfb/directfb.h>` | dname:VK_USE_PLATFORM_DIRECTFB_EXT |
| | `apiext:VK_EXT_acquire_xlib_display` | X11 XRAndR | `vulkan_xlib_xrandr.h` | `<X11/Xlib.h>`, |
| `<X11/extensions{wbro}/Xrandr.h>` | dname:VK_USE_PLATFORM_XLIB_XRANDR_EXT |
| | `apiext:VK_GGP_stream_descriptor_surface`, |
| `apiext:VK_GGP_frame_token` | Google Games Platform | `vulkan_ggp.h` | <ggp_c/vulkan_types.h> | dname:VK_USE_PLATFORM_GGP |
| | `apiext:VK_MVK_ios_surface` | iOS | `vulkan_ios.h` | None | dname:VK_USE_PLATFORM_IOS_MVK |
| | `apiext:VK_MVK_macos_surface` | macOS | `vulkan_macos.h` | None | dname:VK_USE_PLATFORM_MACOS_MVK |
| | `apiext:VK_NN_vi_surface` | VI | `vulkan_vi.h` | None | dname:VK_USE_PLATFORM_VI_NN |
| | `apiext:VK_FUCHSIA_imagepipe_surface` | Fuchsia | `vulkan_fuchsia.h` | `<zircon/types.h>` | dname:VK_USE_PLATFORM_FUCHSIA |
| | `apiext:VK_EXT_metal_surface` | Metal on CoreAnimation | `vulkan_metal.h` | None | dname:VK_USE_PLATFORM_METAL_EXT |
| | `apiext:VK_QNX_screen_surface` | QNX Screen | `vulkan_screen.h` | `<screen/screen.h>` | dname:VK_USE_PLATFORM_SCREEN_QNX |
| ifdef::VKSC_VERSION_1_0[] |
| | `apiext:VK_NV_external_sci_sync`, `apiext:VK_NV_external_sci_sync2`, |
| `apiext:VK_NV_external_memory_sci_buf`| NVIDIA Sci | `vulkan_sci.h` | `<nvscisync.h>`, |
| `<nvscibuf.h>` | dname:VK_USE_PLATFORM_SCI |
| endif::VKSC_VERSION_1_0[] |
| |==== |
| |
| [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. |
| ==== |
| -- |
| |
| |
| [[boilerplate-provisional-header]] |
| == Provisional Extension Header Control (Informative) |
| |
| [open,refpage='provisional-headers',desc='Control inclusion of provisional extensions',type='freeform',alias='VK_ENABLE_BETA_EXTENSIONS',anchor='boilerplate-provisional-header',xrefs='WSIheaders'] |
| -- |
| _Provisional_ extensions should: not be used in production applications. |
| The functionality defined by such extensions may: change in ways that break |
| backwards compatibility between revisions, and before final release of a |
| non-provisional version of that extension. |
| |
| Provisional extensions are defined in a separate _provisional header_, |
| `vulkan_beta.h`, allowing applications to decide whether or not to include |
| them. |
| The mechanism is similar to <<boilerplate-wsi-header, window system-specific |
| headers>>: before including `vulkan_beta.h`, applications must: include |
| `{core_header}`. |
| |
| [NOTE] |
| .Note |
| ==== |
| Sometimes a provisional extension will include a subset of its interfaces in |
| `{core_header}`. |
| This may occur if the provisional extension is promoted from an existing |
| vendor or EXT extension and some of the existing interfaces are defined as |
| aliases of the provisional extension interfaces. |
| All other interfaces of that provisional extension which are not aliased |
| will be included in `vulkan_beta.h`. |
| ==== |
| |
| As a convenience for applications, `{full_header}` conditionally includes |
| `vulkan_beta.h`. |
| Applications can: control inclusion of `vulkan_beta.h` by #defining the |
| macro etext:VK_ENABLE_BETA_EXTENSIONS before including `{full_header}`. |
| |
| [NOTE] |
| .Note |
| ==== |
| Starting in version 1.2.171 of the Specification, all provisional enumerants |
| are protected by the macro etext:VK_ENABLE_BETA_EXTENSIONS. |
| Applications needing to use provisional extensions must always define this |
| macro, even if they are explicitly including `vulkan_beta.h`. |
| This is a minor change to behavior, affecting only provisional extensions. |
| ==== |
| |
| [NOTE] |
| .Note |
| ==== |
| This section describes the purpose of the provisional header independently |
| of the specific provisional extensions which are contained in that header at |
| any given time. |
| The extension appendices for provisional extensions note their provisional |
| status, and link back to this section for more information. |
| Provisional extensions are intended to provide early access for |
| bleeding-edge developers, with the understanding that extension interfaces |
| may change in response to developer feedback. |
| Provisional extensions are very likely to eventually be updated and released |
| as non-provisional extensions, but there is no guarantee this will happen, |
| or how long it will take if it does happen. |
| ==== |
| -- |
| |
| |
| ifndef::VKSC_VERSION_1_0[] |
| [[boilerplate-video-std-headers]] |
| == Video Std Headers |
| |
| Performing video coding operations usually involves the application having |
| to provide various parameters, data structures, or other syntax elements |
| specific to the particular video compression standard used, and the |
| associated semantics are covered by the specification of those. |
| |
| The interface descriptions of these are available in the header files |
| derived from the `video.xml` XML file, which is the canonical |
| machine-readable description of data structures and enumerations that are |
| associated with the externally-provided video compression standards. |
| |
| [[boilerplate-video-std-header-table]] |
| .Video Std Headers |
| [options="header"] |
| |==== |
| | Video Std Header Name | Description | Header File | Related Extensions |
| | `vulkan_video_codecs_common` | Codec-independent common definitions | `<vk_video/vulkan_video_codecs_common.h>` | - |
| | `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 |
| | `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 |
| | `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 |
| | `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 |
| | `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 |
| | `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 |
| |==== |
| endif::VKSC_VERSION_1_0[] |
