Vulkan-Docs/appendices/boilerplate.txt

// Copyright (c) 2016-2019 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/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 `vulkan.h` (Informative)

Applications normally will include the header `vulkan.h`.
In turn, `vulkan.h` always includes the following headers:

  * <<boilerplate-platform-macros,`vk_platform.h`>>, defining
    platform-specific macros and headers.
  * <<boilerplate-vulkan-core,`vulkan_core.h`>>, defining APIs for the
    Vulkan core and all registered extensions _other_ than window
    system-specific extensions.

In addition, specific preprocessor macros defined at the time `vulkan.h` is
included cause header files for the corresponding <<boilerplate-wsi-header,
window system-specific extension interfaces>> to be included.


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

// @refBegin VKAPI_ATTR Vulkan function attributes

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.

// @refEnd VKAPI_ATTR VKAPI_CALL VKAPI_PTR

// @refBegin VKAPI_CALL Vulkan function calling conventions

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.

// @refEnd VKAPI_CALL VKAPI_ATTR VKAPI_PTR

// @refBegin VKAPI_PTR Vulkan function pointer calling conventions

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.

// @refEnd VKAPI_PTR VKAPI_ATTR VKAPI_CALL

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>);
----------------------------------------


==== Platform-Specific Header Control

// @refBegin VK_NO_STDINT_H Control definition of `<stdint.h>` types

If the code: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 code: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.

// @refEnd VK_NO_STDINT_H


[[boilerplate-vulkan-core]]
=== Vulkan Core API Header `vulkan_core.h`

Applications that do not make use of window system-specific extensions may
simply include `vulkan_core.h` instead of `vulkan.h`, although there is
usually no reason to do so.
In addition to the Vulkan API, `vulkan_core.h` 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 `vulkan_core.h` header.
This value is kept synchronized with the patch version of the released
Specification.

include::../api/defines/VK_HEADER_VERSION.txt[]

--

[open,refpage='VK_API_VERSION',desc='Deprecated version number macro',type='defines']
--

dname:VK_API_VERSION is now commented out of `vulkan_core.h` and cannot: be
used.

include::../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::../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::../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 `vulkan_core.h` header allows the
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE definition to be overridden by the
application.
If dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE is already defined when
`vulkan_core.h` is compiled, the default definition is 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.
Behavior is undefined: if the application defines a non-binary-compatible
handle and may: result in memory corruption or application termination.
Binary compatibility is platform dependent so the application must: be
careful if it overrides the default dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE
definition.
====

--

[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::../api/defines/VK_NULL_HANDLE.txt[]

--


[[boilerplate-wsi-header]]
== Window System-Specific Header Control (Informative)

// @refBegin WSIheaders Control inclusion of window system interface extensions

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 `vulkan_core.h` 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, `vulkan.h` includes
`vulkan_core.h`, 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 `vulkan.h`.

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 `vulkan.h` 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 `vulkan.h` Macro
| `<<VK_KHR_android_surface>>`       | Android            | `vulkan_android.h`       | None                           | dname:VK_USE_PLATFORM_ANDROID_KHR
| `<<VK_KHR_wayland_surface>>`       | Wayland            | `vulkan_wayland.h`       | `<wayland-client.h>`           | dname:VK_USE_PLATFORM_WAYLAND_KHR
| `<<VK_KHR_win32_surface>>`,
  `<<VK_KHR_external_memory_win32>>`,
  `<<VK_KHR_win32_keyed_mutex>>`,
  `<<VK_KHR_external_semaphore_win32>>`,
  `<<VK_KHR_external_fence_win32>>`,
ifdef::VK_NV_external_memory_win32[]
  `<<VK_NV_external_memory_win32>>`,
endif::VK_NV_external_memory_win32[]
ifdef::VK_NV_win32_keyed_mutex[]
  `<<VK_NV_win32_keyed_mutex>>`
endif::VK_NV_win32_keyed_mutex[]
                                     | Microsoft Windows  | `vulkan_win32.h`         | `<windows.h>`                  | dname:VK_USE_PLATFORM_WIN32_KHR
| `<<VK_KHR_xcb_surface>>`           | X11 Xcb            | `vulkan_xcb.h`           | `<xcb/xcb.h>`                  | dname:VK_USE_PLATFORM_XCB_KHR
| `<<VK_KHR_xlib_surface>>`          | X11 Xlib           | `vulkan_xlib.h`          | `<X11/Xlib.h>`                 | dname:VK_USE_PLATFORM_XLIB_KHR
ifdef::VK_EXT_acquire_xlib_display[]
| `<<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_MVK_ios_surface[]
| `<<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[]
| `<<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[]
| `<<VK_NN_vi_surface>>`             | VI                 | `vulkan_vi.h`            | None                           | dname:VK_USE_PLATFORM_VI_NN
endif::VK_NN_vi_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.
====

// @refEnd WSIheaders