381 lines
14 KiB
Plaintext
381 lines
14 KiB
Plaintext
// Copyright (c) 2016-2018 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-vk-platform,`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>);
|
|
----------------------------------------
|
|
|
|
Additionaly, 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.
|
|
|
|
|
|
[[boilerplate-versions]]
|
|
==== Vulkan Version Number Macros
|
|
|
|
<<fundamentals-versionnum,API Version Numbers>> are packed into integers.
|
|
These macros manipulate version numbers in useful ways.
|
|
|
|
[open,refpage='VK_VERSION_MAJOR',desc='Extract API major version number',type='defines']
|
|
--
|
|
|
|
dname:VK_VERSION_MAJOR extracts the API major version number from a packed
|
|
version number:
|
|
|
|
include::../api/defines/VK_VERSION_MAJOR.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='VK_VERSION_MINOR',desc='Extract API minor version number',type='defines']
|
|
--
|
|
|
|
dname:VK_VERSION_MINOR extracts the API minor version number from a packed
|
|
version number:
|
|
|
|
include::../api/defines/VK_VERSION_MINOR.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='VK_VERSION_PATCH',desc='Extract API patch version number',type='defines']
|
|
--
|
|
|
|
dname:VK_VERSION_PATCH extracts the API patch version number from a packed
|
|
version number:
|
|
|
|
include::../api/defines/VK_VERSION_PATCH.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='VK_API_VERSION_1_0',desc='Return API version number for Vulkan 1.0',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties']
|
|
--
|
|
|
|
dname:VK_API_VERSION_1_0 returns the API version number for Vulkan 1.0.
|
|
The patch version number in this macro will always be zero.
|
|
The supported patch version for a physical device can: be queried with
|
|
flink:vkGetPhysicalDeviceProperties.
|
|
|
|
include::../api/defines/VK_API_VERSION_1_0.txt[]
|
|
|
|
--
|
|
|
|
ifdef::VK_VERSION_1_1[]
|
|
[open,refpage='VK_API_VERSION_1_1',desc='Return API version number for Vulkan 1.1',type='defines',xrefs='vkCreateInstance vkGetPhysicalDeviceProperties']
|
|
--
|
|
|
|
dname:VK_API_VERSION_1_1 returns the API version number for Vulkan 1.1.
|
|
The patch version number in this macro will always be zero.
|
|
The supported patch version for a physical device can: be queried with
|
|
flink:vkGetPhysicalDeviceProperties.
|
|
|
|
include::../api/defines/VK_API_VERSION_1_1.txt[]
|
|
|
|
--
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
[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[]
|
|
|
|
--
|
|
|
|
[open,refpage='VK_MAKE_VERSION',desc='Construct an API version number',type='defines',xrefs='VkApplicationInfo vkCreateInstance']
|
|
--
|
|
|
|
dname:VK_MAKE_VERSION constructs an API version number.
|
|
|
|
include::../api/defines/VK_MAKE_VERSION.txt[]
|
|
|
|
* pname:major is the major version number.
|
|
* pname:minor is the minor version number.
|
|
* pname:patch is the patch version number.
|
|
|
|
This macro can: be used when constructing the
|
|
slink:VkApplicationInfo::pname:apiVersion parameter passed to
|
|
flink:vkCreateInstance.
|
|
|
|
--
|
|
|
|
|
|
==== 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[]
|
|
|
|
--
|
|
|
|
|
|
==== 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_mir_surface>>` | Mir | `vulkan_mir.h` | `<mir_toolkit/client_types.h>` | dname:VK_USE_PLATFORM_MIR_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/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
|