mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-25 12:35:11 +00:00
5abf83f95d
* Update release number to 107.
Public Issues:
* Fix revision date for the `<<VK_AMD_gpu_shader_half_float>>` appendix
(public issue 617).
* Make <<synchronization-pipeline-barriers-subpass-self-dependencies,
subpass self-dependencies>> less restrictive (public issue 777).
* Fix the `<<VK_EXT_full_screen_exclusive>>` dependency on
`<<VK_KHR_win32_surface>>` in `vk.xml` (public pull request 849).
* Remove single-page (`apispec.html`) refpage sub-targets from the
Makefile `allman` target and the build instructions. The target is still
present in the Makefile, but we have not been actively maintaining the
single-page document and do not promise it will work. The full
Specification and the individual API reference pages are what we support
and publish at present (public issue 949).
Internal Issues:
* De-duplicate common valid usage statements shared by multiple commands
or structures by using asciidoctor includes and dynamically assigning
part of the valid usage ID based on which command or structure they're
being applied to (internal issue 779).
* Add reference pages for constructs not part of the formal API, such as
platform calling convention macros, and script changes supporting them
This required suppressing some check_spec_links warning classes in order
to pass CI, until a more sophisticated fix can be done (internal issue
888).
* Change math notation for the elink:VkPrimitiveTopology descriptions to
use short forms `v` and `p` instead of `vertex` and `primitive`,
increasing legibility (internal issue 1611).
* Rewrite generated file includes relative to a globally specified path,
fixing some issues with refpage generation (internal issue 1630).
* Update contributor list for `<<VK_EXT_calibrated_timestamps>>`.
* Fix use of pathlin in `scripts/generator.py` so the script will work on
Windows under Python 3.5 (internal merge request 3107).
* Add missing conditionals around the
<<descriptorsets-accelerationstructure, Acceleration Structure>>
section (internal merge request 3108).
* More script synchronization with OpenXR spec repository (internal merge
request 3109).
* Mark the `<<VK_AMD_gpu_shader_half_float>>` and
`<<VK_AMD_gpu_shader_int16>>` extensions as deprecated in `vk.xml` and
the corresponding extension appendices (internal merge request 3112).
New Extensions:
* `<<VK_EXT_headless_surface>>`
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 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.
|
|
--
|
|
|
|
|
|
|
|
[[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.
|
|
====
|
|
--
|