• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// Copyright 2016-2021 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://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 `{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.txt[]
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.txt[]
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.txt[]
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.txt[]
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.txt[]
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
213dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE and dname:VK_NULL_HANDLE definitions
214to be overridden by the application.
215If dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when
216`{core_header}` is compiled, the default definitions for
217dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE and dname: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.txt[]
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.txt[]
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--
260
261[[boilerplate-wsi-header]]
262== Window System-Specific Header Control (Informative)
263
264[open,refpage='WSIheaders',desc='Control inclusion of window system interface extensions',type='freeform',anchor='boilerplate-wsi-header',xrefs='provisional-headers']
265--
266To use a Vulkan extension supporting a platform-specific window system,
267header files for that window systems must: be included at compile time, or
268platform-specific types must: be forward-declared.
269The Vulkan header files cannot determine whether or not an external header
270is available at compile time, so platform-specific extensions are provided
271in separate headers from the core API and platform-independent extensions,
272allowing applications to decide which ones should be defined and how the
273external headers are included.
274
275Extensions dependent on particular sets of platform headers, or that
276forward-declare platform-specific types, are declared in a header named for
277that platform.
278Before including these platform-specific Vulkan headers, applications must:
279include both `{core_header}` and any external native headers the platform
280extensions depend on.
281
282As a convenience for applications that do not need the flexibility of
283separate platform-specific Vulkan headers, `{full_header}` includes
284`{core_header}`, and then conditionally includes platform-specific Vulkan
285headers and the external headers they depend on.
286Applications control which platform-specific headers are included by
287#defining macros before including `{full_header}`.
288
289The correspondence between platform-specific extensions, external headers
290they require, the platform-specific header which declares them, and the
291preprocessor macros which enable inclusion by `{full_header}` are shown in
292the <<boilerplate-wsi-header-table,following table>>.
293
294[[boilerplate-wsi-header-table]]
295.Window System Extensions and Headers
296[options="header"]
297|====
298| Extension Name                     | Window System Name | Platform-specific Header | Required External Headers      | Controlling `{full_header}` Macro
299| `apiext:VK_KHR_android_surface`       | Android            | `vulkan_android.h`       | None                           | dname:VK_USE_PLATFORM_ANDROID_KHR
300| `apiext:VK_KHR_wayland_surface`       | Wayland            | `vulkan_wayland.h`       | `<wayland-client.h>`           | dname:VK_USE_PLATFORM_WAYLAND_KHR
301| `apiext:VK_KHR_win32_surface`,
302  `apiext:VK_KHR_external_memory_win32`,
303  `apiext:VK_KHR_win32_keyed_mutex`,
304  `apiext:VK_KHR_external_semaphore_win32`,
305  `apiext:VK_KHR_external_fence_win32`,
306ifdef::VK_NV_external_memory_win32[]
307  `apiext:VK_NV_external_memory_win32`,
308endif::VK_NV_external_memory_win32[]
309ifdef::VK_NV_win32_keyed_mutex[]
310  `apiext:VK_NV_win32_keyed_mutex`
311endif::VK_NV_win32_keyed_mutex[]
312                                     | Microsoft Windows      | `vulkan_win32.h`         | `<windows.h>`                  | dname:VK_USE_PLATFORM_WIN32_KHR
313| `apiext:VK_KHR_xcb_surface`           | X11 Xcb                | `vulkan_xcb.h`           | `<xcb/xcb.h>`                  | dname:VK_USE_PLATFORM_XCB_KHR
314| `apiext:VK_KHR_xlib_surface`          | X11 Xlib               | `vulkan_xlib.h`          | `<X11/Xlib.h>`                 | dname:VK_USE_PLATFORM_XLIB_KHR
315ifdef::VK_EXT_directfb_surface[]
316| `apiext:VK_EXT_directfb_surface`      | DirectFB               | `vulkan_directfb.h`      | `<directfb/directfb.h>`        | dname:VK_USE_PLATFORM_DIRECTFB_EXT
317endif::VK_EXT_directfb_surface[]
318ifdef::VK_EXT_acquire_xlib_display[]
319| `apiext:VK_EXT_acquire_xlib_display`  | X11 XRAndR             | `vulkan_xlib_xrandr.h`   | `<X11/Xlib.h>`,
320                                                                                           `<X11/extensions{wbro}/Xrandr.h>`    | dname:VK_USE_PLATFORM_XLIB_XRANDR_EXT
321endif::VK_EXT_acquire_xlib_display[]
322ifdef::VK_GGP_stream_descriptor_surface[]
323| `apiext:VK_GGP_stream_descriptor_surface`,
324  `apiext:VK_GGP_frame_token`
325                                     | Google Games Platform | `vulkan_ggp.h`        | <ggp_c/vulkan_types.h>         | dname:VK_USE_PLATFORM_GGP
326endif::VK_GGP_stream_descriptor_surface[]
327ifdef::VK_MVK_ios_surface[]
328| `apiext:VK_MVK_ios_surface`           | iOS                    | `vulkan_ios.h`           | None                           | dname:VK_USE_PLATFORM_IOS_MVK
329endif::VK_MVK_ios_surface[]
330ifdef::VK_MVK_macos_surface[]
331| `apiext:VK_MVK_macos_surface`         | macOS                  | `vulkan_macos.h`         | None                           | dname:VK_USE_PLATFORM_MACOS_MVK
332endif::VK_MVK_macos_surface[]
333ifdef::VK_NN_vi_surface[]
334| `apiext:VK_NN_vi_surface`             | VI                     | `vulkan_vi.h`            | None                           | dname:VK_USE_PLATFORM_VI_NN
335endif::VK_NN_vi_surface[]
336ifdef::VK_FUCHSIA_imagepipe_surface[]
337| `apiext:VK_FUCHSIA_imagepipe_surface` | Fuchsia                | `vulkan_fuchsia.h`       | `<zircon/types.h>`             | dname:VK_USE_PLATFORM_FUCHSIA
338endif::VK_FUCHSIA_imagepipe_surface[]
339ifdef::VK_EXT_metal_surface[]
340| `apiext:VK_EXT_metal_surface`         | Metal on CoreAnimation | `vulkan_metal.h`         | None                           | dname:VK_USE_PLATFORM_METAL_EXT
341endif::VK_EXT_metal_surface[]
342ifdef::VK_QNX_screen_surface[]
343| `apiext:VK_QNX_screen_surface`        | QNX Screen             | `vulkan_screen.h`        | `<screen/screen.h>`            | dname:VK_USE_PLATFORM_SCREEN_QNX
344endif::VK_QNX_screen_surface[]
345|====
346
347[NOTE]
348.Note
349====
350This section describes the purpose of the headers independently of the
351specific underlying functionality of the window system extensions
352themselves.
353Each extension name will only link to a description of that extension when
354viewing a specification built with that extension included.
355====
356--
357
358
359[[boilerplate-provisional-header]]
360== Provisional Extension Header Control (Informative)
361
362[open,refpage='provisional-headers',desc='Control inclusion of provisional extensions',type='freeform',alias='VK_ENABLE_BETA_EXTENSIONS',anchor='boilerplate-provisional-header',xrefs='WSIheaders']
363--
364_Provisional_ extensions should: not be used in production applications.
365The functionality defined by such extensions may: change in ways that break
366backwards compatibility between revisions, and before final release of a
367non-provisional version of that extension.
368
369Provisional extensions are defined in a separate _provisional header_,
370`vulkan_beta.h`, allowing applications to decide whether or not to include
371them.
372The mechanism is similar to <<boilerplate-wsi-header, window system-specific
373headers>>: before including `vulkan_beta.h`, applications must: include
374`{core_header}`.
375
376[NOTE]
377.Note
378====
379Sometimes a provisional extension will include a subset of its interfaces in
380`{core_header}`.
381This may occur if the provisional extension is promoted from an existing
382vendor or EXT extension and some of the existing interfaces are defined as
383aliases of the provisional extension interfaces.
384All other interfaces of that provisional extension which are not aliased
385will be included in `vulkan_beta.h`.
386====
387
388As a convenience for applications, `{full_header}` conditionally includes
389`vulkan_beta.h`.
390Applications can: control inclusion of `vulkan_beta.h` by #defining the
391macro etext:VK_ENABLE_BETA_EXTENSIONS before including `{full_header}`.
392
393[NOTE]
394.Note
395====
396Starting in version 1.2.171 of the Specification, all provisional enumerants
397are protected by the macro etext:VK_ENABLE_BETA_EXTENSIONS.
398Applications needing to use provisional extensions must always define this
399macro, even if they are explicitly including `vulkan_beta.h`.
400This is a minor change to behavior, affecting only provisional extensions.
401====
402
403[NOTE]
404.Note
405====
406This section describes the purpose of the provisional header independently
407of the specific provisional extensions which are contained in that header at
408any given time.
409The extension appendices for provisional extensions note their provisional
410status, and link back to this section for more information.
411Provisional extensions are intended to provide early access for
412bleeding-edge developers, with the understanding that extension interfaces
413may change in response to developer feedback.
414Provisional extensions are very likely to eventually be updated and released
415as non-provisional extensions, but there is no guarantee this will happen,
416or how long it will take if it does happen.
417====
418--
419