mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-20 01:58:06 +00:00
95dd2f34c5
* Bump API patch number and header version number to 28 for this update.
Github Issues:
* Minor spelling and typography cleanup, add definitions of
ename:VK_FALSE and ename:VK_TRUE as just what their names say
(public issues 220, 318, 325, 365; internal issues 451, 496)
* Clarify that the pname:maxDescriptorSet limits in the
<<features-limits-required,Required Limits>> table are n *
maxPerStage limit (where n=number of supported stages) (public issue
254).
* Minor cleanup to <<boilerplate-platform-macros,Platform-Specific
Macro Definitions>> appendix (public issue 314).
* Add valid usage statement to slink:VkPipelineLayoutCreateInfo
disallowing multiple push constant ranges for the same shader stage
(public issue 340).
* Clarify the elink:VkSharingMode description of what executing the
"same" barriers means in case of ownership transfer (public issue
347).
* Rename copyright.txt and add COPYING.md to try and reduce confusion
about applicable copyrights (public issue 350).
* Extend the table in the <<boilerplate-wsi-header, Window System-Specific
Header Control>> section to describe the external headers included when
each etext:VK_USE_PLATFORM_* macro is defined (public issue 376).
Internal Issues:
* Add "Revision History" to the PDF outputs following the table of
contents, to match HTML outputs (internal issue 43).
* Clarified that flink:vkMapMemory may fail due to virtual address
space limitations (internal issue 346).
* Add +refBody+ comment markup for ref page autoextraction when required
(internal issue 400).
* Document proper use of "mipmap" and "mip" in the style guide API
naming rules, matching the spelling rules (internal issue 471).
* Tweak the <<extensions,Layers and Extensions>> appendix to note that
the Specification may be built with arbitrary combinations of
extensions (internal issue 483).
* Remove incorrect statement allowing
slink:VkClearAttachment::pname:colorAttachment to be >=
slink:VkSubpassDescription::pname:colorAttachmentCount (internal
issue 488).
* The <<features-limits-viewportboundsrange,viewportBoundsRange>> is
expressed in terms of the pname:maxViewportDimensions but this is
actually two values. Clarify that it's based on the larger of the two
(if they differ) (internal issue 499).
Other Issues:
* Reflowed text of the entire spec using the 'reflow' Makefile gater,
to (hopefully) reduce future internal git churn as edits are made
and extensions added in return for one-time pain. This has no
perceptible change on the spec outputs but considerable changes on
the asciidoc source (internal issue 367).
340 lines
13 KiB
Plaintext
340 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+
|
|
|
|
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.
|
|
|
|
|
|
=== 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
|
|
|
|
|
|
=== 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>+
|
|
|====
|
|
|
|
// @refEnd WSIheaders
|