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