// 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 <>. 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 <>. 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 <> 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 <> 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 <> 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 <>. 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 VKAPI_CALL (); ---------------------------------------- Additionaly, a Vulkan function pointer type declaration takes the form of: [source,c++] ---------------------------------------- typedef (VKAPI_PTR *PFN_)(); ---------------------------------------- === Platform-Specific Header Control // @refBegin VK_NO_STDINT_H Control definition of ++ types If the dname: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 dname:VK_NO_STDINT_H is not defined, the system `++` 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 ``#define``d are shown in the <>. [[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+ | dname:VK_USE_PLATFORM_ANDROID_KHR | Android Native | `++` | +VK_KHR_mir_surface+ | dname:VK_USE_PLATFORM_MIR_KHR | Mir | `++` | +VK_KHR_wayland_surface+ | dname:VK_USE_PLATFORM_WAYLAND_KHR | Wayland | `++` | +VK_KHR_win32_surface+ | dname:VK_USE_PLATFORM_WIN32_KHR | Microsoft Windows | `++` | +VK_KHR_xcb_surface+ | dname:VK_USE_PLATFORM_XCB_KHR | X Window System Xcb library | `++` | +VK_KHR_xlib_surface+ | dname:VK_USE_PLATFORM_XLIB_KHR | X Window System Xlib library | `++` ifdef::VK_MVK_ios_surface[] | +VK_MVK_ios_surface+ | dname:VK_USE_PLATFORM_IOS_MVK | iOS | None endif::VK_MVK_ios_surface[] ifdef::VK_MVK_macos_surface[] | +VK_MVK_macos_surface+ | dname:VK_USE_PLATFORM_MACOS_MVK | macOS | None endif::VK_MVK_macos_surface[] ifdef::VK_NN_vi_surface[] | +VK_NN_vi_surface+ | dname:VK_USE_PLATFORM_VI_NN | VI | None endif::VK_NN_vi_surface[] |==== // @refEnd WSIheaders