// 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 <>. 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 <>. 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 <> 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 <> 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 <> 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 <>. 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 ++ 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 ++ 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]] .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