-
Notifications
You must be signed in to change notification settings - Fork 454
/
boilerplate.txt
314 lines (218 loc) · 11.7 KB
/
boilerplate.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
// 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.
// 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 at compile time, it indicates that
the system +<stdint.h>+ does not define some required integer types, and
+vk_platform.h+ will declare fallback definitions of those types. This is
included for backwards compatibility with very old compilers, such as
Microsoft Visual Studio version 2008 or before.
// @refEnd VK_NO_STDINT_H
=== 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_xlib_surface+ | +VK_USE_PLATFORM_XLIB_KHR+ | X11 Xlib library
| +VK_KHR_xcb_surface+ | +VK_USE_PLATFORM_XCB_KHR+ | X11 Xcb library
| +VK_KHR_wayland_surface+ | +VK_USE_PLATFORM_WAYLAND_KHR+ | Wayland
| +VK_KHR_mir_surface+ | +VK_USE_PLATFORM_MIR_KHR+ | Mir
| +VK_KHR_android_surface+ | +VK_USE_PLATFORM_ANDROID_KHR+ | Android Native
| +VK_KHR_win32_surface+ | +VK_USE_PLATFORM_WIN32_KHR+ | Windows Win32
|====
// @refEnd WSIheaders