mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-26 13:05:13 +00:00
521e98405f
* Update release number to 120.
Github Issues:
* Add slink:VkAccelerationStructureTypeNV explicitly to extension XML for
`<<VK_NV_ray_tracing>>` (public issue 848).
* Add missing valid usage statements for feature flags in
slink:VkCommandBufferInheritanceInfo (public pull request 1017).
Internal Issues:
* Clarify behavior of non-premultiplied destination colors for
`<<VK_EXT_blend_operation_advanced>>` prior to the definition of
slink:VkBlendOverlapEXT (internal issue 1766).
* Fix the confusing phrasing "`no other queue must: be (doing something)`"
for flink:vkQueuePresentKHR, flink:vkQueueSubmit, and
flink:vkQueueBindSparse (internal issue 1774).
* Add `<<VK_EXT_validation_features>>` flag to enable best practices
checks, which will soon be available in the validation layer (internal
issue 1779).
* Specify allowed characters for VUID tag name components in the style
guide (internal issue 1788).
* Update links to SPIR-V extension specifications, and parameterize their
markup in case the URLs change in the future (internal issue 1797).
* Fix an off-by-one error in the valid usage statement for
slink:VkPipelineExecutableInfoKHR (internal merge request 3303).
* Clean up markup indentation not matching the style guide (internal merge
request 3314).
* Minor script updates to allow refpage aliases, generate a dynamic TOC
for refpages, generate Apache rewrite rules for aliases, open external
links from refpages in a new window, and synchronize with the OpenCL
scripts. This will shortly enable a paned navigation setup for refpages,
similar to the OpenCL 2.2 refpages (internal merge request 3322).
* Script updates to add tests to the checker, refactor and reformat code,
generate better text for some valid usage statements, use more Pythonic
idioms, and synchronize with the OpenXR scripts (internal merge request
3239).
* Script updates and minor fixes in spec language to not raise checker
errors for refpage markup of pages not existing in the API, such as
VKAPI_NO_STDINT_H. Remove corresponding suppression of some
check_spec_links.py tests from .gitlab-ci.yml and 'allchecks' target
(internal merge request 3315).
306 lines
13 KiB
Plaintext
306 lines
13 KiB
Plaintext
// 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.
|
|
|
|
[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 dlink: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 dlink: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.
|
|
--
|
|
|
|
|
|
|
|
[[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::{generated}/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::{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 `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.
|
|
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[]
|
|
--
|
|
|
|
|
|
[[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-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 `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_GGP_stream_descriptor_surface[]
|
|
| `<<VK_GGP_stream_descriptor_surface>>`,
|
|
`<<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[]
|
|
| `<<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[]
|
|
ifdef::VK_FUCHSIA_imagepipe_surface[]
|
|
| `<<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[]
|
|
| `<<VK_EXT_metal_surface>>` | Metal on CoreAnimation | `vulkan_metal.h` | None | dname:VK_USE_PLATFORM_METAL_EXT
|
|
endif::VK_EXT_metal_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.
|
|
====
|
|
--
|