331 lines
13 KiB
Plaintext
331 lines
13 KiB
Plaintext
// Copyright (c) 2016 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[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
|
|
|
|
// refBegin VkStructureType Vulkan structure types (pname:stype)
|
|
|
|
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[]
|
|
|
|
// refEnd VkStructureType
|
|
|
|
|
|
[[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[]
|
|
include::../api/flags/VkDeviceCreateFlags.txt[]
|
|
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[]
|
|
include::../api/flags/VkInstanceCreateFlags.txt[]
|
|
include::../api/flags/VkMemoryHeapFlags.txt[]
|
|
include::../api/flags/VkMemoryMapFlags.txt[]
|
|
include::../api/flags/VkMemoryPropertyFlags.txt[]
|
|
include::../api/flags/VkPipelineCacheCreateFlags.txt[]
|
|
include::../api/flags/VkPipelineColorBlendStateCreateFlags.txt[]
|
|
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[]
|
|
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[]
|
|
|
|
|
|
[[boilerplate-macros]]
|
|
== Macro Definitions in +vulkan.h+
|
|
|
|
Vulkan is defined as a C API. 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.
|
|
|
|
// refBegin VK_VERSION_MAJOR - Extract API major version number
|
|
|
|
dname:VK_VERSION_MAJOR extracts the API major version number
|
|
from a packed version number:
|
|
|
|
include::../api/defines/VK_VERSION_MAJOR.txt[]
|
|
|
|
// refEnd VK_VERSION_MAJOR
|
|
|
|
// refBegin VK_VERSION_MINOR - Extract API minor version number
|
|
|
|
dname:VK_VERSION_MINOR extracts the API minor version number
|
|
from a packed version number:
|
|
|
|
include::../api/defines/VK_VERSION_MINOR.txt[]
|
|
|
|
// refEnd VK_VERSION_MINOR
|
|
|
|
// refBegin VK_VERSION_PATCH - Extract API patch version number
|
|
|
|
dname:VK_VERSION_PATCH extracts the API patch version number
|
|
from a packed version number:
|
|
|
|
include::../api/defines/VK_VERSION_PATCH.txt[]
|
|
|
|
// refEnd VK_VERSION_PATCH
|
|
|
|
// refBegin VK_API_VERSION_1_0 - Return API version number for Vulkan 1.0
|
|
|
|
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[]
|
|
|
|
// refEnd VK_API_VERSION_1_0 vkCreateInstance vkGetPhysicalDeviceProperties
|
|
|
|
// refBegin VK_API_VERSION - Deprecated version number macro
|
|
|
|
dname:VK_API_VERSION is now commented out of +vulkan.h+ and cannot: be used.
|
|
|
|
include::../api/defines/VK_API_VERSION.txt[]
|
|
|
|
// refEnd VK_API_VERSION
|
|
|
|
// refBegin VK_MAKE_VERSION - Construct an API version number
|
|
|
|
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.
|
|
|
|
// refEnd VK_MAKE_VERSION VkApplicationInfo vkCreateInstance
|
|
|
|
|
|
=== Vulkan Header File Version Number
|
|
|
|
// refBegin VK_HEADER_VERSION - Vulkan header file version number
|
|
|
|
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[]
|
|
|
|
// refEnd VK_HEADER_VERSION
|
|
|
|
|
|
=== Vulkan Handle macros
|
|
|
|
// refBegin VK_DEFINE_HANDLE - Declare a dispatchable object handle
|
|
|
|
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.
|
|
|
|
// refEnd VK_DEFINE_HANDLE VkCommandBuffer VkDevice VkInstance VkPhysicalDevice VkQueue
|
|
|
|
// refBegin VK_DEFINE_NON_DISPATCHABLE_HANDLE - Declare a non-dispatchable object handle
|
|
|
|
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.
|
|
==================
|
|
|
|
// refEnd VK_DEFINE_NON_DISPATCHABLE_HANDLE VkBuffer
|
|
|
|
// refBegin VK_NULL_HANDLE - Reserved non-valid object handle
|
|
|
|
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[]
|
|
|
|
// refEnd VK_NULL_HANDLE
|
|
|
|
|
|
[[boilerplate-platform-macros]]
|
|
== Platform-Specific Macro Definitions in +vk_platform.h+
|
|
|
|
In addition to the macros described for +vulkan.h+, platform-specific macros
|
|
specified and used in the included +vk_platform.h+ file are described in
|
|
this section. These macros are specifically used to control
|
|
platform-dependent behavior and their exact definitions are under the
|
|
control of specific platforms and Vulkan implementations.
|
|
|
|
|
|
=== Platform-Specific Calling Conventions
|
|
|
|
// @refBegin VKAPI_ATTR - Vulkan function attributes
|
|
|
|
dname:VKAPI_ATTR is a macro placed before the return type in Vulkan API
|
|
function declarations. If not empty, the interpretation of this macro
|
|
depends on the platform and compiler in use, but normally 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. If not empty, the interpretation of this macro
|
|
depends on the platform and compiler in use, but normally 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. If not empty, the interpretation of this
|
|
macro depends on the platform and compiler in use, and normally controls
|
|
calling conventions. dname:VKAPI_PTR typically has the same definition as
|
|
dname:VKAPI_ATTR or dname:VKAPI_CALL, depending on the compiler.
|
|
|
|
// @refEnd VKAPI_PTR VKAPI_ATTR VKAPI_CALL
|
|
|
|
|
|
=== 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 required by +vulkan.h+, such as +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
|
|
|
|
When using different window systems with Khronos extensions, header files
|
|
for those window systems must: be included at compile time in order for the
|
|
corresponding extension definitions to compile. The Vulkan header files
|
|
cannot determine whether or not an external header is available at compile
|
|
time, so applications must: include macros enabling those headers. 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, and window
|
|
systems they correspond to are defined 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
|
|
| +VK_KHR_android_surface+ | +VK_USE_PLATFORM_ANDROID_KHR+ | Android Native
|
|
| +VK_KHR_mir_surface+ | +VK_USE_PLATFORM_MIR_KHR+ | Mir
|
|
| +VK_KHR_wayland_surface+ | +VK_USE_PLATFORM_WAYLAND_KHR+ | Wayland
|
|
| +VK_KHR_win32_surface+ | +VK_USE_PLATFORM_WIN32_KHR+ | Microsoft Windows
|
|
| +VK_KHR_xcb_surface+ | +VK_USE_PLATFORM_XCB_KHR+ | X Window System Xcb library
|
|
| +VK_KHR_xlib_surface+ | +VK_USE_PLATFORM_XLIB_KHR+ | X Window System Xlib library
|
|
|====
|
|
|
|
// @refEnd WSIheaders
|