status-im
/
Vulkan-Docs
mirror of https://github.com/status-im/Vulkan-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/doc/specs/vulkan/appendices/boilerplate.txt

393 lines
15 KiB
Plaintext
Raw Blame History

// 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[]
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+
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.
[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.
=== 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>+
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
Reference in New Issue View Git Blame Copy Permalink