• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// Copyright 2015-2021 The Khronos Group, Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5[[initialization]]
6= Initialization
7
8Before using Vulkan, an application must: initialize it by loading the
9Vulkan commands, and creating a sname:VkInstance object.
10
11
12[[initialization-functionpointers]]
13== Command Function Pointers
14
15Vulkan commands are not necessarily exposed by static linking on a platform.
16Commands to query function pointers for Vulkan commands are described below.
17
18[NOTE]
19.Note
20====
21When extensions are <<extendingvulkan-compatibility-promotion,promoted>> or
22otherwise incorporated into another extension or Vulkan core version,
23command <<extendingvulkan-compatibility-aliases,aliases>> may be included.
24Whilst the behavior of each command alias is identical, the behavior of
25retrieving each alias's function pointer is not.
26A function pointer for a given alias can only be retrieved if the extension
27or version that introduced that alias is supported and enabled, irrespective
28of whether any other alias is available.
29====
30
31[open,refpage='vkGetInstanceProcAddr',desc='Return a function pointer for a command',type='protos',xrefs='PFN_vkVoidFunction']
32--
33Function pointers for all Vulkan commands can: be obtained with the command:
34
35include::{generated}/api/protos/vkGetInstanceProcAddr.txt[]
36
37  * pname:instance is the instance that the function pointer will be
38    compatible with, or `NULL` for commands not dependent on any instance.
39  * pname:pName is the name of the command to obtain.
40
41fname:vkGetInstanceProcAddr itself is obtained in a platform- and loader-
42specific manner.
43Typically, the loader library will export this command as a function symbol,
44so applications can: link against the loader library, or load it dynamically
45and look up the symbol using platform-specific APIs.
46
47The table below defines the various use cases for
48fname:vkGetInstanceProcAddr and expected return value ("`fp`" is "`function
49pointer`") for each case.
50A valid returned function pointer ("`fp`") must: not be `NULL`.
51
52The returned function pointer is of type tlink:PFN_vkVoidFunction, and must:
53be cast to the type of the command being queried before use.
54
55.fname:vkGetInstanceProcAddr behavior
56[width="80%",options="header"]
57|====
58| pname:instance   | pname:pName                                  | return value
59| *^1^             | `NULL`                                       | undefined:
60| invalid non-`NULL` instance | *^1^                              | undefined:
61ifdef::VK_VERSION_1_2[]
62| `NULL`           | flink:vkGetInstanceProcAddr                  | fp^5^
63endif::VK_VERSION_1_2[]
64| `NULL`           | _global command_^2^                          | fp
65| instance         | core _dispatchable command_                  | fp^3^
66| instance         | enabled instance extension dispatchable command for pname:instance    | fp^3^
67| instance         | available device extension^4^ dispatchable command for pname:instance | fp^3^
682+|  any other case, not covered above                            | `NULL`
69|====
70
711::
72    "*" means any representable value for the parameter (including valid
73    values, invalid values, and `NULL`).
74
752::
76    The global commands are:
77ifdef::VK_VERSION_1_1[flink:vkEnumerateInstanceVersion,]
78    flink:vkEnumerateInstanceExtensionProperties,
79    flink:vkEnumerateInstanceLayerProperties, and flink:vkCreateInstance.
80    Dispatchable commands are all other commands which are not global.
81
823::
83    The returned function pointer must: only be called with a dispatchable
84    object (the first parameter) that is pname:instance or a child of
85    pname:instance, e.g. slink:VkInstance, slink:VkPhysicalDevice,
86    slink:VkDevice, slink:VkQueue, or slink:VkCommandBuffer.
87
884::
89    An "`available device extension`" is a device extension supported by any
90    physical device enumerated by pname:instance.
91
92ifdef::VK_VERSION_1_2[]
935::
94    Starting with Vulkan 1.2, fname:vkGetInstanceProcAddr can resolve itself
95    with a `NULL` instance pointer.
96endif::VK_VERSION_1_2[]
97
98include::{generated}/validity/protos/vkGetInstanceProcAddr.txt[]
99--
100
101[open,refpage='vkGetDeviceProcAddr',desc='Return a function pointer for a command',type='protos',xrefs='PFN_vkVoidFunction']
102--
103In order to support systems with multiple Vulkan implementations, the
104function pointers returned by fname:vkGetInstanceProcAddr may: point to
105dispatch code that calls a different real implementation for different
106slink:VkDevice objects or their child objects.
107The overhead of the internal dispatch for slink:VkDevice objects can be
108avoided by obtaining device-specific function pointers for any commands that
109use a device or device-child object as their dispatchable object.
110Such function pointers can: be obtained with the command:
111
112include::{generated}/api/protos/vkGetDeviceProcAddr.txt[]
113
114The table below defines the various use cases for fname:vkGetDeviceProcAddr
115and expected return value ("`fp`" is "`function pointer`") for each case.
116A valid returned function pointer ("`fp`") must: not be `NULL`.
117
118The returned function pointer is of type tlink:PFN_vkVoidFunction, and must:
119be cast to the type of the command being queried before use.
120The function pointer must: only be called with a dispatchable object (the
121first parameter) that is pname:device or a child of pname:device.
122
123.fname:vkGetDeviceProcAddr behavior
124[width="80%",options="header"]
125|====
126| pname:device   | pname:pName                      | return value
127| `NULL`         | *^1^                             | undefined:
128| invalid device | *^1^                             | undefined:
129| device         | `NULL`                           | undefined:
130| device         | core device-level dispatchable command^2^ | fp^3^
131| device         | enabled extension device-level dispatchable command^2^ | fp^3^
1322+| any other case, not covered above               | `NULL`
133|====
134
1351::
136    "*" means any representable value for the parameter (including valid
137    values, invalid values, and `NULL`).
138
1392::
140    In this function, device-level excludes all physical-device-level
141    commands.
142
1433::
144    The returned function pointer must: only be called with a dispatchable
145    object (the first parameter) that is pname:device or a child of
146    pname:device e.g. slink:VkDevice, slink:VkQueue, or
147    slink:VkCommandBuffer.
148
149include::{generated}/validity/protos/vkGetDeviceProcAddr.txt[]
150--
151
152[open,refpage='PFN_vkVoidFunction',desc='Placeholder function pointer type returned by queries',type='funcpointers',xrefs='vkGetDeviceProcAddr vkGetInstanceProcAddr']
153--
154The definition of tlink:PFN_vkVoidFunction is:
155
156include::{generated}/api/funcpointers/PFN_vkVoidFunction.txt[]
157--
158
159
160ifdef::VK_VERSION_1_1[]
161=== Extending Physical Device Core Functionality
162
163New core physical-device-level functionality can: be used when the
164physical-device version is greater than or equal to the version of Vulkan
165that added the new functionality.
166The Vulkan version supported by a physical device can: be obtained by
167calling flink:vkGetPhysicalDeviceProperties.
168endif::VK_VERSION_1_1[]
169
170
171ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
172[[initialization-phys-dev-extensions]]
173=== Extending Physical Device From Device Extensions
174
175When the `apiext:VK_KHR_get_physical_device_properties2` extension is
176enabled,
177ifdef::VK_VERSION_1_1[]
178or when both the instance and the physical-device versions are at least 1.1,
179endif::VK_VERSION_1_1[]
180physical-device-level functionality of a device extension can: be used with
181a physical device if the corresponding extension is enumerated by
182flink:vkEnumerateDeviceExtensionProperties for that physical device, even
183before a logical device has been created.
184
185To obtain a function pointer for a physical-device-level command from a
186device extension, an application can: use flink:vkGetInstanceProcAddr.
187This function pointer may: point to dispatch code, which calls a different
188real implementation for different sname:VkPhysicalDevice objects.
189Applications must: not use a slink:VkPhysicalDevice in any command added by
190an extension or core version that is not supported by that physical device.
191
192Device extensions may: define structures that can: be added to the
193ptext:pNext chain of physical-device-level commands.
194endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
195
196
197[[initialization-instances]]
198== Instances
199
200[open,refpage='VkInstance',desc='Opaque handle to an instance object',type='handles']
201--
202There is no global state in Vulkan and all per-application state is stored
203in a sname:VkInstance object.
204Creating a sname:VkInstance object initializes the Vulkan library and allows
205the application to pass information about itself to the implementation.
206
207Instances are represented by sname:VkInstance handles:
208
209include::{generated}/api/handles/VkInstance.txt[]
210--
211
212ifdef::VK_VERSION_1_1[]
213[open,refpage='vkEnumerateInstanceVersion',desc='Query instance-level version before instance creation',type='protos']
214--
215To query the version of instance-level functionality supported by the
216implementation, call:
217
218include::{generated}/api/protos/vkEnumerateInstanceVersion.txt[]
219
220  * pname:pApiVersion is a pointer to a code:uint32_t, which is the version
221    of Vulkan supported by instance-level functionality, encoded as
222    described in <<extendingvulkan-coreversions-versionnumbers>>.
223
224[NOTE]
225.Note
226====
227The intended behaviour of flink:vkEnumerateInstanceVersion is that an
228implementation should: not need to perform memory allocations and should:
229unconditionally return ename:VK_SUCCESS.
230The loader, and any enabled layers, may: return
231ename:VK_ERROR_OUT_OF_HOST_MEMORY in the case of a failed memory allocation.
232====
233
234include::{generated}/validity/protos/vkEnumerateInstanceVersion.txt[]
235--
236endif::VK_VERSION_1_1[]
237
238[open,refpage='vkCreateInstance',desc='Create a new Vulkan instance',type='protos']
239--
240To create an instance object, call:
241
242include::{generated}/api/protos/vkCreateInstance.txt[]
243
244  * pname:pCreateInfo is a pointer to a slink:VkInstanceCreateInfo structure
245    controlling creation of the instance.
246  * pname:pAllocator controls host memory allocation as described in the
247    <<memory-allocation, Memory Allocation>> chapter.
248  * pname:pInstance points a slink:VkInstance handle in which the resulting
249    instance is returned.
250
251fname:vkCreateInstance verifies that the requested layers exist.
252If not, fname:vkCreateInstance will return ename:VK_ERROR_LAYER_NOT_PRESENT.
253Next fname:vkCreateInstance verifies that the requested extensions are
254supported (e.g. in the implementation or in any enabled instance layer) and
255if any requested extension is not supported, fname:vkCreateInstance must:
256return ename:VK_ERROR_EXTENSION_NOT_PRESENT.
257After verifying and enabling the instance layers and extensions the
258sname:VkInstance object is created and returned to the application.
259If a requested extension is only supported by a layer, both the layer and
260the extension need to be specified at fname:vkCreateInstance time for the
261creation to succeed.
262
263.Valid Usage
264****
265  * [[VUID-vkCreateInstance-ppEnabledExtensionNames-01388]]
266    All <<extendingvulkan-extensions-extensiondependencies, required
267    extensions>> for each extension in the
268    slink:VkInstanceCreateInfo::pname:ppEnabledExtensionNames list must:
269    also be present in that list
270****
271
272include::{generated}/validity/protos/vkCreateInstance.txt[]
273--
274
275[open,refpage='VkInstanceCreateInfo',desc='Structure specifying parameters of a newly created instance',type='structs']
276--
277The sname:VkInstanceCreateInfo structure is defined as:
278
279include::{generated}/api/structs/VkInstanceCreateInfo.txt[]
280
281  * pname:sType is the type of this structure.
282  * pname:pNext is `NULL` or a pointer to a structure extending this
283    structure.
284  * pname:flags is reserved for future use.
285  * pname:pApplicationInfo is `NULL` or a pointer to a
286    sname:VkApplicationInfo structure.
287    If not `NULL`, this information helps implementations recognize behavior
288    inherent to classes of applications.
289    slink:VkApplicationInfo is defined in detail below.
290  * pname:enabledLayerCount is the number of global layers to enable.
291  * pname:ppEnabledLayerNames is a pointer to an array of
292    pname:enabledLayerCount null-terminated UTF-8 strings containing the
293    names of layers to enable for the created instance.
294    The layers are loaded in the order they are listed in this array, with
295    the first array element being the closest to the application, and the
296    last array element being the closest to the driver.
297    See the <<extendingvulkan-layers>> section for further details.
298  * pname:enabledExtensionCount is the number of global extensions to
299    enable.
300  * pname:ppEnabledExtensionNames is a pointer to an array of
301    pname:enabledExtensionCount null-terminated UTF-8 strings containing the
302    names of extensions to enable.
303
304ifdef::VK_EXT_debug_report,VK_EXT_debug_utils[]
305To capture events that occur while creating or destroying an instance, an
306application can link a
307ifdef::VK_EXT_debug_report[]
308slink:VkDebugReportCallbackCreateInfoEXT structure
309ifdef::VK_EXT_debug_utils[]
310or a
311endif::VK_EXT_debug_utils[]
312endif::VK_EXT_debug_report[]
313ifdef::VK_EXT_debug_utils[]
314slink:VkDebugUtilsMessengerCreateInfoEXT structure
315endif::VK_EXT_debug_utils[]
316to the pname:pNext element of the sname:VkInstanceCreateInfo structure given
317to fname:vkCreateInstance.
318This callback is only valid for the duration of the flink:vkCreateInstance
319and the flink:vkDestroyInstance call.
320Use
321ifdef::VK_EXT_debug_report[]
322flink:vkCreateDebugReportCallbackEXT
323ifdef::VK_EXT_debug_utils[]
324or
325endif::VK_EXT_debug_utils[]
326endif::VK_EXT_debug_report[]
327ifdef::VK_EXT_debug_utils[]
328flink:vkCreateDebugUtilsMessengerEXT
329endif::VK_EXT_debug_utils[]
330to create persistent callback objects.
331
332.Valid Usage
333****
334ifdef::VK_EXT_debug_report[]
335  * [[VUID-VkInstanceCreateInfo-pNext-04925]]
336    If the pname:pNext chain of sname:VkInstanceCreateInfo includes a
337    sname:VkDebugReportCallbackCreateInfoEXT structure, the list of enabled
338    extensions in pname:ppEnabledExtensionNames must: contain
339    apiext:VK_EXT_debug_report
340endif::VK_EXT_debug_report[]
341ifdef::VK_EXT_debug_utils[]
342  * [[VUID-VkInstanceCreateInfo-pNext-04926]]
343    If the pname:pNext chain of sname:VkInstanceCreateInfo includes a
344    sname:VkDebugUtilsMessengerCreateInfoEXT structure, the list of enabled
345    extensions in pname:ppEnabledExtensionNames must: contain
346    apiext:VK_EXT_debug_utils
347endif::VK_EXT_debug_utils[]
348****
349endif::VK_EXT_debug_report,VK_EXT_debug_utils[]
350
351include::{generated}/validity/structs/VkInstanceCreateInfo.txt[]
352--
353
354[open,refpage='VkInstanceCreateFlags',desc='Reserved for future use',type='flags']
355--
356include::{generated}/api/flags/VkInstanceCreateFlags.txt[]
357
358tname:VkInstanceCreateFlags is a bitmask type for setting a mask, but is
359currently reserved for future use.
360--
361
362ifdef::VK_EXT_validation_flags[]
363include::{chapters}/VK_EXT_validation_flags.txt[]
364endif::VK_EXT_validation_flags[]
365
366ifdef::VK_EXT_validation_features[]
367include::{chapters}/VK_EXT_validation_features.txt[]
368endif::VK_EXT_validation_features[]
369
370[open,refpage='VkApplicationInfo',desc='Structure specifying application information',type='structs']
371--
372The sname:VkApplicationInfo structure is defined as:
373
374include::{generated}/api/structs/VkApplicationInfo.txt[]
375
376  * pname:sType is the type of this structure.
377  * pname:pNext is `NULL` or a pointer to a structure extending this
378    structure.
379  * pname:pApplicationName is `NULL` or is a pointer to a null-terminated
380    UTF-8 string containing the name of the application.
381  * pname:applicationVersion is an unsigned integer variable containing the
382    developer-supplied version number of the application.
383  * pname:pEngineName is `NULL` or is a pointer to a null-terminated UTF-8
384    string containing the name of the engine (if any) used to create the
385    application.
386  * pname:engineVersion is an unsigned integer variable containing the
387    developer-supplied version number of the engine used to create the
388    application.
389ifndef::VK_VERSION_1_1[]
390  * pname:apiVersion is the version of the Vulkan API against which the
391    application expects to run, encoded as described in
392    <<extendingvulkan-coreversions-versionnumbers>>.
393    If pname:apiVersion is 0 the implementation must: ignore it, otherwise
394    if the implementation does not support the requested pname:apiVersion,
395    or an effective substitute for pname:apiVersion, it must: return
396    ename:VK_ERROR_INCOMPATIBLE_DRIVER.
397endif::VK_VERSION_1_1[]
398ifdef::VK_VERSION_1_1[]
399  * pname:apiVersion must: be the highest version of Vulkan that the
400    application is designed to use, encoded as described in
401    <<extendingvulkan-coreversions-versionnumbers>>.
402endif::VK_VERSION_1_1[]
403    The patch version number specified in pname:apiVersion is ignored when
404    creating an instance object.
405    Only the major and minor versions of the instance must: match those
406    requested in pname:apiVersion.
407
408ifdef::VK_VERSION_1_1[]
409Vulkan 1.0 implementations were required to return
410ename:VK_ERROR_INCOMPATIBLE_DRIVER if pname:apiVersion was larger than 1.0.
411Implementations that support Vulkan 1.1 or later must: not return
412ename:VK_ERROR_INCOMPATIBLE_DRIVER for any value of pname:apiVersion.
413
414[NOTE]
415.Note
416====
417Because Vulkan 1.0 implementations may: fail with
418ename:VK_ERROR_INCOMPATIBLE_DRIVER, applications should: determine the
419version of Vulkan available before calling flink:vkCreateInstance.
420If the flink:vkGetInstanceProcAddr returns `NULL` for
421flink:vkEnumerateInstanceVersion, it is a Vulkan 1.0 implementation.
422Otherwise, the application can: call flink:vkEnumerateInstanceVersion to
423determine the version of Vulkan.
424====
425
426As long as the instance supports at least Vulkan 1.1, an application can:
427use different versions of Vulkan with an instance than it does with a device
428or physical device.
429
430[NOTE]
431.Note
432====
433The Khronos validation layers will treat pname:apiVersion as the highest API
434version the application targets, and will validate API usage against the
435minimum of that version and the implementation version (instance or device,
436depending on context).
437If an application tries to use functionality from a greater version than
438this, a validation error will be triggered.
439
440For example, if the instance supports Vulkan 1.1 and three physical devices
441support Vulkan 1.0, Vulkan 1.1, and Vulkan 1.2, respectively, and if the
442application sets pname:apiVersion to 1.2, the application can: use the
443following versions of Vulkan:
444
445  * Vulkan 1.0 can: be used with the instance and with all physical devices.
446  * Vulkan 1.1 can: be used with the instance and with the physical devices
447    that support Vulkan 1.1 and Vulkan 1.2.
448  * Vulkan 1.2 can: be used with the physical device that supports Vulkan
449    1.2.
450
451If we modify the above example so that the application sets pname:apiVersion
452to 1.1, then the application must: not use Vulkan 1.2 functionality on the
453physical device that supports Vulkan 1.2.
454====
455
456Implicit layers must: be disabled if they do not support a version at least
457as high as pname:apiVersion.
458See the <<LoaderInterfaceArchitecture, "`Architecture of the Vulkan Loader
459Interfaces`">> document for additional information.
460
461[NOTE]
462.Note
463====
464Providing a `NULL` slink:VkInstanceCreateInfo::pname:pApplicationInfo or
465providing an pname:apiVersion of 0 is equivalent to providing an
466pname:apiVersion of `VK_MAKE_API_VERSION(0,1,0,0)`.
467====
468endif::VK_VERSION_1_1[]
469
470.Valid Usage
471****
472  * [[VUID-VkApplicationInfo-apiVersion-04010]]
473    If pname:apiVersion is not `0`, then it must: be greater than or equal
474    to dlink:VK_API_VERSION_1_0
475****
476
477include::{generated}/validity/structs/VkApplicationInfo.txt[]
478--
479
480[open,refpage='vkDestroyInstance',desc='Destroy an instance of Vulkan',type='protos']
481--
482To destroy an instance, call:
483
484include::{generated}/api/protos/vkDestroyInstance.txt[]
485
486  * pname:instance is the handle of the instance to destroy.
487  * pname:pAllocator controls host memory allocation as described in the
488    <<memory-allocation, Memory Allocation>> chapter.
489
490.Valid Usage
491****
492  * [[VUID-vkDestroyInstance-instance-00629]]
493    All child objects created using pname:instance must: have been destroyed
494    prior to destroying pname:instance
495  * [[VUID-vkDestroyInstance-instance-00630]]
496    If sname:VkAllocationCallbacks were provided when pname:instance was
497    created, a compatible set of callbacks must: be provided here
498  * [[VUID-vkDestroyInstance-instance-00631]]
499    If no sname:VkAllocationCallbacks were provided when pname:instance was
500    created, pname:pAllocator must: be `NULL`
501****
502
503include::{generated}/validity/protos/vkDestroyInstance.txt[]
504--
505