410 lines
15 KiB
Plaintext
410 lines
15 KiB
Plaintext
// Copyright (c) 2016-2017 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-sType]]
|
|
== Structure Types
|
|
|
|
[open,refpage='VkStructureType',desc='Vulkan structure types (pname:stype)',type='enums']
|
|
--
|
|
|
|
Vulkan structures containing pname:sType members must: have a value of
|
|
pname:sType matching the type of the structure, as described more fully in
|
|
<<fundamentals-validusage-sType,Valid Usage for Structure Types>>.
|
|
Structure types supported by the Vulkan API include:
|
|
|
|
include::../api/enums/VkStructureType.txt[]
|
|
|
|
--
|
|
|
|
|
|
[[boilerplate-flags]]
|
|
== Flag Types
|
|
|
|
Vulkan flag types are all bitmasks aliasing the base type basetype:VkFlags
|
|
and with corresponding bit flag types defining the valid bits for that flag,
|
|
as described in <<fundamentals-validusage-flags, Valid Usage for Flags>>.
|
|
Flag types supported by the Vulkan API include:
|
|
|
|
// All of these types have autogenerated ref pages at present, although
|
|
// bringing that content into the spec (by adding // refBegin and // refEnd
|
|
// comments and explanatory text for the ref pages) would be more complete.
|
|
|
|
include::../api/flags/VkAccessFlags.txt[]
|
|
include::../api/flags/VkAttachmentDescriptionFlags.txt[]
|
|
include::../api/flags/VkBufferCreateFlags.txt[]
|
|
include::../api/flags/VkBufferUsageFlags.txt[]
|
|
include::../api/flags/VkBufferViewCreateFlags.txt[]
|
|
include::../api/flags/VkColorComponentFlags.txt[]
|
|
include::../api/flags/VkCommandBufferResetFlags.txt[]
|
|
include::../api/flags/VkCommandBufferUsageFlags.txt[]
|
|
include::../api/flags/VkCommandPoolCreateFlags.txt[]
|
|
include::../api/flags/VkCommandPoolResetFlags.txt[]
|
|
include::../api/flags/VkCullModeFlags.txt[]
|
|
include::../api/flags/VkDependencyFlags.txt[]
|
|
include::../api/flags/VkDescriptorPoolCreateFlags.txt[]
|
|
include::../api/flags/VkDescriptorPoolResetFlags.txt[]
|
|
include::../api/flags/VkDescriptorSetLayoutCreateFlags.txt[]
|
|
ifdef::VK_KHR_descriptor_update_template[]
|
|
include::../api/flags/VkDescriptorUpdateTemplateCreateFlagsKHR.txt[]
|
|
endif::VK_KHR_descriptor_update_template[]
|
|
include::../api/flags/VkDeviceCreateFlags.txt[]
|
|
ifdef::VK_KHX_device_group[]
|
|
include::../api/flags/VkDeviceGroupPresentModeFlagsKHX.txt[]
|
|
endif::VK_KHX_device_group[]
|
|
include::../api/flags/VkDeviceQueueCreateFlags.txt[]
|
|
include::../api/flags/VkEventCreateFlags.txt[]
|
|
include::../api/flags/VkFenceCreateFlags.txt[]
|
|
include::../api/flags/VkFormatFeatureFlags.txt[]
|
|
include::../api/flags/VkFramebufferCreateFlags.txt[]
|
|
include::../api/flags/VkImageAspectFlags.txt[]
|
|
include::../api/flags/VkImageCreateFlags.txt[]
|
|
include::../api/flags/VkImageUsageFlags.txt[]
|
|
include::../api/flags/VkImageViewCreateFlags.txt[]
|
|
ifdef::VK_NVX_device_generated_commands[]
|
|
include::../api/flags/VkIndirectCommandsLayoutUsageFlagsNVX.txt[]
|
|
endif::VK_NVX_device_generated_commands[]
|
|
include::../api/flags/VkInstanceCreateFlags.txt[]
|
|
ifdef::VK_KHX_device_group[]
|
|
include::../api/flags/VkMemoryAllocateFlagsKHX.txt[]
|
|
endif::VK_KHX_device_group[]
|
|
include::../api/flags/VkMemoryHeapFlags.txt[]
|
|
include::../api/flags/VkMemoryMapFlags.txt[]
|
|
include::../api/flags/VkMemoryPropertyFlags.txt[]
|
|
ifdef::VK_NVX_device_generated_commands[]
|
|
include::../api/flags/VkObjectEntryUsageFlagsNVX.txt[]
|
|
endif::VK_NVX_device_generated_commands[]
|
|
ifdef::VK_KHX_device_group[]
|
|
include::../api/flags/VkPeerMemoryFeatureFlagsKHX.txt[]
|
|
endif::VK_KHX_device_group[]
|
|
include::../api/flags/VkPipelineCacheCreateFlags.txt[]
|
|
ifdef::VK_EXT_validation_cache[]
|
|
include::../api/flags/VkValidationCacheCreateFlagsEXT.txt[]
|
|
endif::VK_EXT_validation_cache[]
|
|
include::../api/flags/VkPipelineColorBlendStateCreateFlags.txt[]
|
|
ifdef::VK_NV_fragment_coverage_to_color[]
|
|
include::../api/flags/VkPipelineCoverageToColorStateCreateFlagsNV.txt[]
|
|
endif::VK_NV_fragment_coverage_to_color[]
|
|
ifdef::VK_NV_framebuffer_mixed_samples[]
|
|
include::../api/flags/VkPipelineCoverageModulationStateCreateFlagsNV.txt[]
|
|
endif::VK_NV_framebuffer_mixed_samples[]
|
|
include::../api/flags/VkPipelineCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineDepthStencilStateCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineDynamicStateCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineInputAssemblyStateCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineLayoutCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineMultisampleStateCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineRasterizationStateCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineShaderStageCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineStageFlags.txt[]
|
|
include::../api/flags/VkPipelineTessellationStateCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineVertexInputStateCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineViewportStateCreateFlags.txt[]
|
|
ifdef::VK_NV_viewport_swizzle[]
|
|
include::../api/flags/VkPipelineViewportSwizzleStateCreateFlagsNV.txt[]
|
|
endif::VK_NV_viewport_swizzle[]
|
|
ifdef::VK_EXT_discard_rectangles[]
|
|
include::../api/flags/VkPipelineDiscardRectangleStateCreateFlagsEXT.txt[]
|
|
endif::VK_EXT_discard_rectangles[]
|
|
include::../api/flags/VkQueryControlFlags.txt[]
|
|
include::../api/flags/VkQueryPipelineStatisticFlags.txt[]
|
|
include::../api/flags/VkQueryPoolCreateFlags.txt[]
|
|
include::../api/flags/VkQueryResultFlags.txt[]
|
|
include::../api/flags/VkQueueFlags.txt[]
|
|
include::../api/flags/VkRenderPassCreateFlags.txt[]
|
|
include::../api/flags/VkSampleCountFlags.txt[]
|
|
include::../api/flags/VkSamplerCreateFlags.txt[]
|
|
include::../api/flags/VkSemaphoreCreateFlags.txt[]
|
|
include::../api/flags/VkShaderModuleCreateFlags.txt[]
|
|
include::../api/flags/VkShaderStageFlags.txt[]
|
|
include::../api/flags/VkSparseImageFormatFlags.txt[]
|
|
include::../api/flags/VkSparseMemoryBindFlags.txt[]
|
|
include::../api/flags/VkStencilFaceFlags.txt[]
|
|
include::../api/flags/VkSubpassDescriptionFlags.txt[]
|
|
ifdef::VK_EXT_display_surface_counter[]
|
|
include::../api/flags/VkSurfaceCounterFlagsEXT.txt[]
|
|
endif::VK_EXT_display_surface_counter[]
|
|
|
|
|
|
[[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 +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 +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 #defined 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+ | +VK_USE_PLATFORM_ANDROID_KHR+ | Android Native | +<android/native_window.h>+
|
|
| +VK_KHR_mir_surface+ | +VK_USE_PLATFORM_MIR_KHR+ | Mir | +<mir_toolkit/client_types.h>+
|
|
| +VK_KHR_wayland_surface+ | +VK_USE_PLATFORM_WAYLAND_KHR+ | Wayland | +<wayland-client.h>+
|
|
| +VK_KHR_win32_surface+ | +VK_USE_PLATFORM_WIN32_KHR+ | Microsoft Windows | +<windows.h>+
|
|
| +VK_KHR_xcb_surface+ | +VK_USE_PLATFORM_XCB_KHR+ | X Window System Xcb library | +<xcb/xcb.h>+
|
|
| +VK_KHR_xlib_surface+ | +VK_USE_PLATFORM_XLIB_KHR+ | X Window System Xlib library | +<X11/Xlib.h>+
|
|
ifdef::VK_MVK_ios_surface[]
|
|
| +VK_MVK_ios_surface+ | +VK_USE_PLATFORM_IOS_MVK+ | iOS | None
|
|
endif::VK_MVK_ios_surface[]
|
|
ifdef::VK_MVK_macos_surface[]
|
|
| +VK_MVK_macos_surface+ | +VK_USE_PLATFORM_MACOS_MVK+ | macOS | None
|
|
endif::VK_MVK_macos_surface[]
|
|
ifdef::VK_NN_vi_surface[]
|
|
| +VK_NN_vi_surface+ | +VK_USE_PLATFORM_VI_NN+ | VI | None
|
|
endif::VK_NN_vi_surface[]
|
|
|====
|
|
|
|
// @refEnd WSIheaders
|