status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/appendices/boilerplate.txt

296 lines
10 KiB
Plaintext
Raw Blame History

// 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-macros]]
== Macro Definitions in +vulkan.h+
The supplied +vulkan.h+ header 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[]
--
[open,refpage='VK_API_VERSION',desc='Deprecated version number macro',type='defines']
--
dname:VK_API_VERSION is now commented out of +vulkan.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.h+ header.
This value is currently kept synchronized with the release number of the
Specification.
However, it is not guaranteed to remain synchronized, since most
Specification updates have no effect on +vulkan.h+.
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.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 the
+vulkan.h+ header 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-platform-macros]]
== Platform-Specific Macro Definitions in +vk_platform.h+
Additional platform-specific macros and interfaces are defined using the
included +vk_platform.h+ file.
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 dname:VK_NO_STDINT_H macro is defined by the application at compile
time, extended integer types used by `vulkan.h`, such as code:uint8_t, must:
also be defined by the application.
Otherwise, `vulkan.h` will not compile.
If dname:VK_NO_STDINT_H is not defined, the system `<stdint.h>` is used to
define these types, or 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-wsi-header]]
=== Window System-Specific Header Control
// @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.
The Vulkan header files cannot determine whether or not an external header
is available at compile time, so applications wishing to use such an
extension must: `#define` a macro causing such headers to be included.
If this is not done, the corresponding extension interfaces will not be
defined and they will be unusable.
The extensions, required: compile time symbols to enable them, window
systems they correspond to, and external header files that are included when
the macro is ``#define``d are shown in the
<<boilerplate-wsi-header-table,following table>>.
[[boilerplate-wsi-header-table]]
.Window System Extensions and Required Compile Time Symbol Definitions
[options="header"]
|====
| Extension Name | Required Compile Time Symbol | Window System Name | External Header Files Used
| `<<VK_KHR_android_surface>>` | dname:VK_USE_PLATFORM_ANDROID_KHR | Android Native | `<android/native_window.h>`
| `<<VK_KHR_mir_surface>>` | dname:VK_USE_PLATFORM_MIR_KHR | Mir | `<mir_toolkit/client_types.h>`
| `<<VK_KHR_wayland_surface>>` | dname:VK_USE_PLATFORM_WAYLAND_KHR | Wayland | `<wayland-client.h>`
| `<<VK_KHR_win32_surface>>` | dname:VK_USE_PLATFORM_WIN32_KHR | Microsoft Windows | `<windows.h>`
| `<<VK_KHR_xcb_surface>>` | dname:VK_USE_PLATFORM_XCB_KHR | X Window System Xcb library | `<xcb/xcb.h>`
| `<<VK_KHR_xlib_surface>>` | dname:VK_USE_PLATFORM_XLIB_KHR | X Window System Xlib library | `<X11/Xlib.h>`
ifdef::VK_MVK_ios_surface[]
| `<<VK_MVK_ios_surface>>` | dname:VK_USE_PLATFORM_IOS_MVK | iOS | None
endif::VK_MVK_ios_surface[]
ifdef::VK_MVK_macos_surface[]
| `<<VK_MVK_macos_surface>>` | dname:VK_USE_PLATFORM_MACOS_MVK | macOS | None
endif::VK_MVK_macos_surface[]
ifdef::VK_NN_vi_surface[]
| `<<VK_NN_vi_surface>>` | dname:VK_USE_PLATFORM_VI_NN | VI | None
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
Reference in New Issue View Git Blame Copy Permalink