registry/vulkan/appendices/boilerplate.txt

// Copyright 2016-2021 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
https://www.khronos.org/registry/vulkan/#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.





==== 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.txt[]
--

[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.txt[]
--

[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.txt[]
--


==== 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.txt[]

  * 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.txt[]

  * 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
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE and dname:VK_NULL_HANDLE definitions
to be overridden by the application.
If dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when
`{core_header}` is compiled, the default definitions for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE and dname: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.txt[]
--

[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.txt[]

[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.
====

--

[[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 systems must: be included at compile time, or
platform-specific types must: be forward-declared.
The Vulkan header files cannot 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 should 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`,
ifdef::VK_NV_external_memory_win32[]
  `apiext:VK_NV_external_memory_win32`,
endif::VK_NV_external_memory_win32[]
ifdef::VK_NV_win32_keyed_mutex[]
  `apiext:VK_NV_win32_keyed_mutex`
endif::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
ifdef::VK_EXT_directfb_surface[]
| `apiext:VK_EXT_directfb_surface`      | DirectFB               | `vulkan_directfb.h`      | `<directfb/directfb.h>`        | dname:VK_USE_PLATFORM_DIRECTFB_EXT
endif::VK_EXT_directfb_surface[]
ifdef::VK_EXT_acquire_xlib_display[]
| `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
endif::VK_EXT_acquire_xlib_display[]
ifdef::VK_GGP_stream_descriptor_surface[]
| `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
endif::VK_GGP_stream_descriptor_surface[]
ifdef::VK_MVK_ios_surface[]
| `apiext:VK_MVK_ios_surface`           | iOS                    | `vulkan_ios.h`           | None                           | dname:VK_USE_PLATFORM_IOS_MVK
endif::VK_MVK_ios_surface[]
ifdef::VK_MVK_macos_surface[]
| `apiext:VK_MVK_macos_surface`         | macOS                  | `vulkan_macos.h`         | None                           | dname:VK_USE_PLATFORM_MACOS_MVK
endif::VK_MVK_macos_surface[]
ifdef::VK_NN_vi_surface[]
| `apiext:VK_NN_vi_surface`             | VI                     | `vulkan_vi.h`            | None                           | dname:VK_USE_PLATFORM_VI_NN
endif::VK_NN_vi_surface[]
ifdef::VK_FUCHSIA_imagepipe_surface[]
| `apiext:VK_FUCHSIA_imagepipe_surface` | Fuchsia                | `vulkan_fuchsia.h`       | `<zircon/types.h>`             | dname:VK_USE_PLATFORM_FUCHSIA
endif::VK_FUCHSIA_imagepipe_surface[]
ifdef::VK_EXT_metal_surface[]
| `apiext:VK_EXT_metal_surface`         | Metal on CoreAnimation | `vulkan_metal.h`         | None                           | dname:VK_USE_PLATFORM_METAL_EXT
endif::VK_EXT_metal_surface[]
ifdef::VK_QNX_screen_surface[]
| `apiext:VK_QNX_screen_surface`        | QNX Screen             | `vulkan_screen.h`        | `<screen/screen.h>`            | dname:VK_USE_PLATFORM_SCREEN_QNX
endif::VK_QNX_screen_surface[]
|====

[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.
====
--