1// Copyright 2015-2023 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 by calling: 34 35include::{generated}/api/protos/vkGetInstanceProcAddr.adoc[] 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: 61| `NULL` | _global command_^2^ | fp 62ifdef::VK_VERSION_1_2[] 63| `NULL` | flink:vkGetInstanceProcAddr | fp^5^ 64endif::VK_VERSION_1_2[] 65| instance | flink:vkGetInstanceProcAddr | fp 66| instance | core _dispatchable command_ | fp^3^ 67| instance | enabled instance extension dispatchable command for pname:instance | fp^3^ 68| instance | available device extension^4^ dispatchable command for pname:instance | fp^3^ 692+| any other case, not covered above | `NULL` 70|==== 71 721:: 73 "*" means any representable value for the parameter (including valid 74 values, invalid values, and `NULL`). 75 762:: 77 The global commands are: 78ifdef::VK_VERSION_1_1[flink:vkEnumerateInstanceVersion,] 79 flink:vkEnumerateInstanceExtensionProperties, 80 flink:vkEnumerateInstanceLayerProperties, and flink:vkCreateInstance. 81 Dispatchable commands are all other commands which are not global. 82 833:: 84 The returned function pointer must: only be called with a dispatchable 85 object (the first parameter) that is pname:instance or a child of 86 pname:instance, e.g. slink:VkInstance, slink:VkPhysicalDevice, 87 slink:VkDevice, slink:VkQueue, or slink:VkCommandBuffer. 88 894:: 90 An "`available device extension`" is a device extension supported by any 91 physical device enumerated by pname:instance. 92 93ifdef::VK_VERSION_1_2[] 945:: 95ifndef::VKSC_VERSION_1_0[Starting with Vulkan 1.2, ] 96 fname:vkGetInstanceProcAddr can resolve itself with a `NULL` instance 97 pointer. 98endif::VK_VERSION_1_2[] 99 100include::{generated}/validity/protos/vkGetInstanceProcAddr.adoc[] 101-- 102 103[open,refpage='vkGetDeviceProcAddr',desc='Return a function pointer for a command',type='protos',xrefs='PFN_vkVoidFunction'] 104-- 105In order to support systems with multiple Vulkan implementations, the 106function pointers returned by flink:vkGetInstanceProcAddr may: point to 107dispatch code that calls a different real implementation for different 108slink:VkDevice objects or their child objects. 109The overhead of the internal dispatch for slink:VkDevice objects can be 110avoided by obtaining device-specific function pointers for any commands that 111use a device or device-child object as their dispatchable object. 112Such function pointers can: be obtained by calling: 113 114include::{generated}/api/protos/vkGetDeviceProcAddr.adoc[] 115 116The table below defines the various use cases for fname:vkGetDeviceProcAddr 117and expected return value ("`fp`" is "`function pointer`") for each case. 118A valid returned function pointer ("`fp`") must: not be `NULL`. 119 120The returned function pointer is of type tlink:PFN_vkVoidFunction, and must: 121be cast to the type of the command being queried before use. 122The function pointer must: only be called with a dispatchable object (the 123first parameter) that is pname:device or a child of pname:device. 124 125.fname:vkGetDeviceProcAddr behavior 126[width="80%",options="header"] 127|==== 128| pname:device | pname:pName | return value 129| `NULL` | *^1^ | undefined: 130| invalid device | *^1^ | undefined: 131| device | `NULL` | undefined: 132| device | requested core version^2^ device-level dispatchable command^3^ | fp^4^ 133| device | enabled extension device-level dispatchable command^3^ | fp^4^ 1342+| any other case, not covered above | `NULL` 135|==== 136 1371:: 138 "*" means any representable value for the parameter (including valid 139 values, invalid values, and `NULL`). 140 1412:: 142 Device-level commands which are part of the core version specified by 143 slink:VkApplicationInfo::pname:apiVersion when creating the instance 144 will always return a valid function pointer. 145ifndef::VK_KHR_maintenance5[] 146 Core commands beyond that version which are supported by the 147 implementation may: either return `NULL` or a function pointer. 148 If a function pointer is returned, it must: not be called. 149endif::VK_KHR_maintenance5[] 150ifdef::VK_KHR_maintenance5[] 151 If the <<features-maintenance5, pname:maintenance5>> feature is enabled, 152 core commands beyond that version which are supported by the 153 implementation will return `NULL`, otherwise the implementation may: 154 either return `NULL` or a function pointer. 155 If a function pointer is returned, it must: not be called. 156endif::VK_KHR_maintenance5[] 157 1583:: 159 In this function, device-level excludes all physical-device-level 160 commands. 161 1624:: 163 The returned function pointer must: only be called with a dispatchable 164 object (the first parameter) that is pname:device or a child of 165 pname:device e.g. slink:VkDevice, slink:VkQueue, or 166 slink:VkCommandBuffer. 167 168include::{generated}/validity/protos/vkGetDeviceProcAddr.adoc[] 169-- 170 171[open,refpage='PFN_vkVoidFunction',desc='Placeholder function pointer type returned by queries',type='funcpointers',xrefs='vkGetDeviceProcAddr vkGetInstanceProcAddr'] 172-- 173The definition of tlink:PFN_vkVoidFunction is: 174 175include::{generated}/api/funcpointers/PFN_vkVoidFunction.adoc[] 176 177This type is returned from command function pointer queries, and must: be 178cast to an actual command function pointer before use. 179-- 180 181 182ifdef::VK_VERSION_1_1[] 183=== Extending Physical Device Core Functionality 184 185New core physical-device-level functionality can: be used when the 186physical-device version is greater than or equal to the version of Vulkan 187that added the new functionality. 188The Vulkan version supported by a physical device can: be obtained by 189calling flink:vkGetPhysicalDeviceProperties. 190endif::VK_VERSION_1_1[] 191 192 193ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 194[[initialization-phys-dev-extensions]] 195=== Extending Physical Device From Device Extensions 196 197ifdef::VKSC_VERSION_1_0[In Vulkan SC 1.0,] 198ifndef::VKSC_VERSION_1_0[] 199When the `apiext:VK_KHR_get_physical_device_properties2` extension is 200enabled, 201ifdef::VK_VERSION_1_1[] 202or when both the instance and the physical-device versions are at least 1.1, 203endif::VK_VERSION_1_1[] 204endif::VKSC_VERSION_1_0[] 205physical-device-level functionality of a device extension can: be used with 206a physical device if the corresponding extension is enumerated by 207flink:vkEnumerateDeviceExtensionProperties for that physical device, even 208before a logical device has been created. 209 210To obtain a function pointer for a physical-device-level command from a 211device extension, an application can: use flink:vkGetInstanceProcAddr. 212This function pointer may: point to dispatch code, which calls a different 213real implementation for different sname:VkPhysicalDevice objects. 214Applications must: not use a slink:VkPhysicalDevice in any command added by 215an extension or core version that is not supported by that physical device. 216 217Device extensions may: define structures that can: be added to the 218ptext:pNext chain of physical-device-level commands. 219endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 220 221 222[[initialization-instances]] 223== Instances 224 225[open,refpage='VkInstance',desc='Opaque handle to an instance object',type='handles'] 226-- 227There is no global state in Vulkan and all per-application state is stored 228in a sname:VkInstance object. 229Creating a sname:VkInstance object initializes the Vulkan library and allows 230the application to pass information about itself to the implementation. 231 232Instances are represented by sname:VkInstance handles: 233 234include::{generated}/api/handles/VkInstance.adoc[] 235-- 236 237ifdef::VK_VERSION_1_1[] 238[open,refpage='vkEnumerateInstanceVersion',desc='Query instance-level version before instance creation',type='protos'] 239-- 240To query the version of instance-level functionality supported by the 241implementation, call: 242 243include::{generated}/api/protos/vkEnumerateInstanceVersion.adoc[] 244 245 * pname:pApiVersion is a pointer to a code:uint32_t, which is the version 246 of Vulkan supported by instance-level functionality, encoded as 247 described in <<extendingvulkan-coreversions-versionnumbers>>. 248 249[NOTE] 250.Note 251==== 252The intended behaviour of flink:vkEnumerateInstanceVersion is that an 253implementation should: not need to perform memory allocations and should: 254unconditionally return ename:VK_SUCCESS. 255The loader, and any enabled layers, may: return 256ename:VK_ERROR_OUT_OF_HOST_MEMORY in the case of a failed memory allocation. 257==== 258 259include::{generated}/validity/protos/vkEnumerateInstanceVersion.adoc[] 260-- 261endif::VK_VERSION_1_1[] 262 263[open,refpage='vkCreateInstance',desc='Create a new Vulkan instance',type='protos'] 264-- 265To create an instance object, call: 266 267include::{generated}/api/protos/vkCreateInstance.adoc[] 268 269 * pname:pCreateInfo is a pointer to a slink:VkInstanceCreateInfo structure 270 controlling creation of the instance. 271 * pname:pAllocator controls host memory allocation as described in the 272 <<memory-allocation, Memory Allocation>> chapter. 273 * pname:pInstance points a slink:VkInstance handle in which the resulting 274 instance is returned. 275 276fname:vkCreateInstance verifies that the requested layers exist. 277If not, fname:vkCreateInstance will return ename:VK_ERROR_LAYER_NOT_PRESENT. 278Next fname:vkCreateInstance verifies that the requested extensions are 279supported (e.g. in the implementation or in any enabled instance layer) and 280if any requested extension is not supported, fname:vkCreateInstance must: 281return ename:VK_ERROR_EXTENSION_NOT_PRESENT. 282After verifying and enabling the instance layers and extensions the 283sname:VkInstance object is created and returned to the application. 284If a requested extension is only supported by a layer, both the layer and 285the extension need to be specified at fname:vkCreateInstance time for the 286creation to succeed. 287 288.Valid Usage 289**** 290 * [[VUID-vkCreateInstance-ppEnabledExtensionNames-01388]] 291 All <<extendingvulkan-extensions-extensiondependencies, required 292 extensions>> for each extension in the 293 slink:VkInstanceCreateInfo::pname:ppEnabledExtensionNames list must: 294 also be present in that list 295**** 296 297include::{generated}/validity/protos/vkCreateInstance.adoc[] 298-- 299 300[open,refpage='VkInstanceCreateInfo',desc='Structure specifying parameters of a newly created instance',type='structs'] 301-- 302The sname:VkInstanceCreateInfo structure is defined as: 303 304include::{generated}/api/structs/VkInstanceCreateInfo.adoc[] 305 306 * pname:sType is a elink:VkStructureType value identifying this structure. 307 * pname:pNext is `NULL` or a pointer to a structure extending this 308 structure. 309 * pname:flags is a bitmask of elink:VkInstanceCreateFlagBits indicating 310 the behavior of the instance. 311 * pname:pApplicationInfo is `NULL` or a pointer to a 312 sname:VkApplicationInfo structure. 313 If not `NULL`, this information helps implementations recognize behavior 314 inherent to classes of applications. 315 slink:VkApplicationInfo is defined in detail below. 316 * pname:enabledLayerCount is the number of global layers to enable. 317 * pname:ppEnabledLayerNames is a pointer to an array of 318 pname:enabledLayerCount null-terminated UTF-8 strings containing the 319 names of layers to enable for the created instance. 320 The layers are loaded in the order they are listed in this array, with 321 the first array element being the closest to the application, and the 322 last array element being the closest to the driver. 323 See the <<extendingvulkan-layers>> section for further details. 324 * pname:enabledExtensionCount is the number of global extensions to 325 enable. 326 * pname:ppEnabledExtensionNames is a pointer to an array of 327 pname:enabledExtensionCount null-terminated UTF-8 strings containing the 328 names of extensions to enable. 329 330ifdef::VK_EXT_debug_report,VK_EXT_debug_utils[] 331To capture events that occur while creating or destroying an instance, an 332application can: link a 333ifdef::VK_EXT_debug_report[] 334slink:VkDebugReportCallbackCreateInfoEXT structure 335ifdef::VK_EXT_debug_utils[] 336or a 337endif::VK_EXT_debug_utils[] 338endif::VK_EXT_debug_report[] 339ifdef::VK_EXT_debug_utils[] 340slink:VkDebugUtilsMessengerCreateInfoEXT structure 341endif::VK_EXT_debug_utils[] 342to the pname:pNext element of the sname:VkInstanceCreateInfo structure given 343to fname:vkCreateInstance. 344This callback is only valid for the duration of the flink:vkCreateInstance 345and the flink:vkDestroyInstance call. 346Use 347ifdef::VK_EXT_debug_report[] 348flink:vkCreateDebugReportCallbackEXT 349ifdef::VK_EXT_debug_utils[] 350or 351endif::VK_EXT_debug_utils[] 352endif::VK_EXT_debug_report[] 353ifdef::VK_EXT_debug_utils[] 354flink:vkCreateDebugUtilsMessengerEXT 355endif::VK_EXT_debug_utils[] 356to create persistent callback objects. 357endif::VK_EXT_debug_report,VK_EXT_debug_utils[] 358 359ifdef::VK_LUNARG_direct_driver_loading[] 360An application can add additional drivers by including the 361slink:VkDirectDriverLoadingListLUNARG struct to the pname:pNext element of 362the sname:VkInstanceCreateInfo structure given to fname:vkCreateInstance. 363 364[NOTE] 365.Note 366==== 367slink:VkDirectDriverLoadingListLUNARG allows applications to ship drivers 368with themselves. 369Only drivers that are designed to work with it should be used, such as 370drivers that implement Vulkan in software or that implement Vulkan by 371translating it to a different API. 372Any driver that requires installation should not be used, such as hardware 373drivers. 374==== 375endif::VK_LUNARG_direct_driver_loading[] 376 377ifdef::VK_EXT_debug_report,VK_EXT_debug_utils,VK_KHR_portability_enumeration,VK_LUNARG_direct_driver_loading[] 378.Valid Usage 379**** 380ifdef::VK_EXT_debug_report[] 381 * [[VUID-VkInstanceCreateInfo-pNext-04925]] 382 If the pname:pNext chain of sname:VkInstanceCreateInfo includes a 383 sname:VkDebugReportCallbackCreateInfoEXT structure, the list of enabled 384 extensions in pname:ppEnabledExtensionNames must: contain 385 `apiext:VK_EXT_debug_report` 386endif::VK_EXT_debug_report[] 387ifdef::VK_EXT_debug_utils[] 388 * [[VUID-VkInstanceCreateInfo-pNext-04926]] 389 If the pname:pNext chain of sname:VkInstanceCreateInfo includes a 390 sname:VkDebugUtilsMessengerCreateInfoEXT structure, the list of enabled 391 extensions in pname:ppEnabledExtensionNames must: contain 392 `apiext:VK_EXT_debug_utils` 393endif::VK_EXT_debug_utils[] 394ifdef::VK_EXT_metal_objects[] 395 * [[VUID-VkInstanceCreateInfo-pNext-06779]] 396 If the pname:pNext chain includes a 397 slink:VkExportMetalObjectCreateInfoEXT structure, its 398 pname:exportObjectType member must: be either 399 ename:VK_EXPORT_METAL_OBJECT_TYPE_METAL_DEVICE_BIT_EXT or 400 ename:VK_EXPORT_METAL_OBJECT_TYPE_METAL_COMMAND_QUEUE_BIT_EXT 401endif::VK_EXT_metal_objects[] 402ifdef::VK_KHR_portability_enumeration[] 403 * [[VUID-VkInstanceCreateInfo-flags-06559]] 404 If pname:flags has the 405 ename:VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR bit set, the list 406 of enabled extensions in pname:ppEnabledExtensionNames must: contain 407 `apiext:VK_KHR_portability_enumeration` 408endif::VK_KHR_portability_enumeration[] 409ifdef::VK_LUNARG_direct_driver_loading[] 410 * [[VUID-VkInstanceCreateInfo-pNext-09400]] 411 If the pname:pNext chain of sname:VkInstanceCreateInfo includes a 412 slink:VkDirectDriverLoadingListLUNARG structure, the list of enabled 413 extensions in pname:ppEnabledExtensionNames must: contain 414 apiext:VK_LUNARG_direct_driver_loading 415endif::VK_LUNARG_direct_driver_loading[] 416**** 417endif::VK_EXT_debug_report,VK_EXT_debug_utils,VK_KHR_portability_enumeration,VK_LUNARG_direct_driver_loading[] 418 419include::{generated}/validity/structs/VkInstanceCreateInfo.adoc[] 420-- 421 422[open,refpage='VkInstanceCreateFlagBits',desc='Bitmask specifying behavior of the instance',type='enums'] 423-- 424include::{generated}/api/enums/VkInstanceCreateFlagBits.adoc[] 425 426ifdef::VK_KHR_portability_enumeration[] 427 * ename:VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR specifies that 428 the instance will enumerate available Vulkan Portability-compliant 429 physical devices and groups in addition to the Vulkan physical devices 430 and groups that are enumerated by default. 431endif::VK_KHR_portability_enumeration[] 432 433ifndef::VK_KHR_portability_enumeration[] 434[NOTE] 435.Note 436==== 437All bits for this type are defined by extensions, and none of those 438extensions are enabled in this build of the specification. 439==== 440endif::VK_KHR_portability_enumeration[] 441-- 442 443[open,refpage='VkInstanceCreateFlags',desc='Bitmask of VkInstanceCreateFlagBits',type='flags'] 444-- 445include::{generated}/api/flags/VkInstanceCreateFlags.adoc[] 446 447ifndef::VK_KHR_portability_enumeration[] 448tname:VkInstanceCreateFlags is a bitmask type for setting a mask, but is 449currently reserved for future use. 450endif::VK_KHR_portability_enumeration[] 451ifdef::VK_KHR_portability_enumeration[] 452tname:VkInstanceCreateFlags is a bitmask type for setting a mask of zero or 453more elink:VkInstanceCreateFlagBits. 454endif::VK_KHR_portability_enumeration[] 455-- 456 457ifdef::VK_EXT_validation_flags[] 458include::{chapters}/VK_EXT_validation_flags.adoc[] 459endif::VK_EXT_validation_flags[] 460 461ifdef::VK_EXT_validation_features[] 462include::{chapters}/VK_EXT_validation_features.adoc[] 463endif::VK_EXT_validation_features[] 464 465ifdef::VK_LUNARG_direct_driver_loading[] 466[open,refpage='VkDirectDriverLoadingListLUNARG',desc='Structure specifying additional drivers to load',type='structs'] 467-- 468The sname:VkDirectDriverLoadingListLUNARG structure is defined as: 469 470include::{generated}/api/structs/VkDirectDriverLoadingListLUNARG.adoc[] 471 472 * pname:sType is a elink:VkStructureType value identifying this structure. 473 * pname:pNext is `NULL` or a pointer to a structure extending this 474 structure. 475 * pname:mode controls the mode in which to load the provided drivers. 476 * pname:driverCount is the number of driver manifest paths. 477 * pname:pDrivers is a pointer to an array of pname:driverCount 478 slink:VkDirectDriverLoadingInfoLUNARG structures. 479 480When creating a Vulkan instance for which additional drivers are to be 481included, add a sname:VkDirectDriverLoadingListLUNARG structure to the pNext 482chain of the slink:VkInstanceCreateInfo structure, and include in it the 483list of sname:VkDirectDriverLoadingInfoLUNARG structures which contain the 484information necessary to load additional drivers. 485 486include::{generated}/validity/structs/VkDirectDriverLoadingListLUNARG.adoc[] 487-- 488 489[open,refpage='VkDirectDriverLoadingInfoLUNARG',desc='Structure specifying the information required to load an additional driver',type='structs'] 490-- 491The sname:VkDirectDriverLoadingInfoLUNARG structure is defined as: 492 493include::{generated}/api/structs/VkDirectDriverLoadingInfoLUNARG.adoc[] 494 495 * pname:sType is a elink:VkStructureType value identifying this structure. 496 * pname:pNext is `NULL` or a pointer to a structure extending this 497 structure. 498 * pname:flags is reserved for future use. 499 * pname:pfnGetInstanceProcAddr is a tlink:PFN_vkGetInstanceProcAddrLUNARG 500 pointer to the driver flink:vkGetInstanceProcAddr function. 501 502include::{generated}/validity/structs/VkDirectDriverLoadingInfoLUNARG.adoc[] 503-- 504 505[open,refpage='VkDirectDriverLoadingModeLUNARG',desc='Specify loader behavior of added drivers',type='enums'] 506-- 507Possible values of slink:VkDirectDriverLoadingListLUNARG::pname:mode, 508specifying the mode in which drivers are used, are: 509 510include::{generated}/api/enums/VkDirectDriverLoadingModeLUNARG.adoc[] 511 512 * ename:VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG specifies that the 513 provided drivers are used instead of the system-loaded drivers. 514 * ename:VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG specifies that the 515 provided drivers are used in addition to the system-loaded drivers. 516-- 517 518[open,refpage='VkDirectDriverLoadingFlagsLUNARG',desc='Reserved for future use',type='flags'] 519-- 520include::{generated}/api/flags/VkDirectDriverLoadingFlagsLUNARG.adoc[] 521 522tname:VkDirectDriverLoadingFlagsLUNARG is a bitmask type for setting a mask, 523but is currently reserved for future use. 524-- 525 526[open,refpage='PFN_vkGetInstanceProcAddrLUNARG',desc='Type definition for vkGetInstanceProcAddr',type='funcpointers'] 527-- 528The type of tlink:PFN_vkGetInstanceProcAddrLUNARG is: 529 530include::{generated}/api/funcpointers/PFN_vkGetInstanceProcAddrLUNARG.adoc[] 531 532 * pname:instance is a slink:VkInstance handle. 533 * pname:pName is the name of a Vulkan command. 534 535This type is compatible with the type of a pointer to the 536flink:vkGetInstanceProcAddr command, but is used only to specify device 537driver addresses in 538slink:VkDirectDriverLoadingInfoLUNARG::pname:pfnGetInstanceProcAddr. 539 540[NOTE] 541.Note 542==== 543This type exists only because of limitations in the XML schema and 544processing scripts, and its name may change in the future. 545Ideally we would use the tname:PFN_vkGetInstanceProcAddr type generated in 546the `vulkan_core.h` header. 547==== 548-- 549endif::VK_LUNARG_direct_driver_loading[] 550 551[open,refpage='VkApplicationInfo',desc='Structure specifying application information',type='structs'] 552-- 553The sname:VkApplicationInfo structure is defined as: 554 555include::{generated}/api/structs/VkApplicationInfo.adoc[] 556 557 * pname:sType is a elink:VkStructureType value identifying this structure. 558 * pname:pNext is `NULL` or a pointer to a structure extending this 559 structure. 560 * pname:pApplicationName is `NULL` or is a pointer to a null-terminated 561 UTF-8 string containing the name of the application. 562 * pname:applicationVersion is an unsigned integer variable containing the 563 developer-supplied version number of the application. 564 * pname:pEngineName is `NULL` or is a pointer to a null-terminated UTF-8 565 string containing the name of the engine (if any) used to create the 566 application. 567 * pname:engineVersion is an unsigned integer variable containing the 568 developer-supplied version number of the engine used to create the 569 application. 570ifndef::VK_VERSION_1_1[] 571 * pname:apiVersion is the version of the Vulkan API against which the 572 application expects to run, encoded as described in 573 <<extendingvulkan-coreversions-versionnumbers>>. 574 If pname:apiVersion is 0 the implementation must: ignore it, otherwise 575 if the implementation does not support the requested pname:apiVersion, 576 or an effective substitute for pname:apiVersion, it must: return 577 ename:VK_ERROR_INCOMPATIBLE_DRIVER. 578endif::VK_VERSION_1_1[] 579ifdef::VK_VERSION_1_1[] 580 * pname:apiVersion must: be the highest version of Vulkan that the 581 application is designed to use, encoded as described in 582 <<extendingvulkan-coreversions-versionnumbers>>. 583endif::VK_VERSION_1_1[] 584 The patch version number specified in pname:apiVersion is ignored when 585 creating an instance object. 586 The variant version of the instance must: match that requested in 587 pname:apiVersion. 588 589ifdef::VK_VERSION_1_1[] 590Vulkan 1.0 implementations were required to return 591ename:VK_ERROR_INCOMPATIBLE_DRIVER if pname:apiVersion was larger than 1.0. 592Implementations that support Vulkan 1.1 or later must: not return 593ename:VK_ERROR_INCOMPATIBLE_DRIVER for any value of pname:apiVersion 594ifndef::VKSC_VERSION_1_0[.] 595ifdef::VKSC_VERSION_1_0[, unless an incompatible variant is requested.] 596 597ifdef::VKSC_VERSION_1_0[] 598[NOTE] 599.Note 600==== 601Vulkan SC 1.0 is based on Vulkan 1.2 and thus instance creation may only 602fail with ename:VK_ERROR_INCOMPATIBLE_DRIVER if an incompatible variant is 603requested - that is if the Vulkan SC API is requested from a Vulkan 604implementation or if the Vulkan API is requested from a Vulkan SC 605implementation. 606==== 607endif::VKSC_VERSION_1_0[] 608 609ifndef::VKSC_VERSION_1_0[] 610[NOTE] 611.Note 612==== 613Because Vulkan 1.0 implementations may: fail with 614ename:VK_ERROR_INCOMPATIBLE_DRIVER, applications should: determine the 615version of Vulkan available before calling flink:vkCreateInstance. 616If the flink:vkGetInstanceProcAddr returns `NULL` for 617flink:vkEnumerateInstanceVersion, it is a Vulkan 1.0 implementation. 618Otherwise, the application can: call flink:vkEnumerateInstanceVersion to 619determine the version of Vulkan. 620==== 621 622As long as the instance supports at least Vulkan 1.1, an application can: 623use different versions of Vulkan with an instance than it does with a device 624or physical device. 625 626[NOTE] 627.Note 628==== 629The Khronos validation layers will treat pname:apiVersion as the highest API 630version the application targets, and will validate API usage against the 631minimum of that version and the implementation version (instance or device, 632depending on context). 633If an application tries to use functionality from a greater version than 634this, a validation error will be triggered. 635 636For example, if the instance supports Vulkan 1.1 and three physical devices 637support Vulkan 1.0, Vulkan 1.1, and Vulkan 1.2, respectively, and if the 638application sets pname:apiVersion to 1.2, the application can: use the 639following versions of Vulkan: 640 641 * Vulkan 1.0 can: be used with the instance and with all physical devices. 642 * Vulkan 1.1 can: be used with the instance and with the physical devices 643 that support Vulkan 1.1 and Vulkan 1.2. 644 * Vulkan 1.2 can: be used with the physical device that supports Vulkan 645 1.2. 646 647If we modify the above example so that the application sets pname:apiVersion 648to 1.1, then the application must: not use Vulkan 1.2 functionality on the 649physical device that supports Vulkan 1.2. 650==== 651endif::VKSC_VERSION_1_0[] 652 653[NOTE] 654.Note 655==== 656Providing a `NULL` slink:VkInstanceCreateInfo::pname:pApplicationInfo or 657providing an pname:apiVersion of 0 is equivalent to providing an 658pname:apiVersion of 659ifndef::VKSC_VERSION_1_0[`VK_MAKE_API_VERSION(0,1,0,0)`.] 660ifdef::VKSC_VERSION_1_0[`VK_MAKE_API_VERSION(1,1,0,0)`.] 661==== 662endif::VK_VERSION_1_1[] 663 664ifdef::VK_EXT_application_parameters[] 665To provide _application parameters_ at instance creation time, an 666application can: link one or more slink:VkApplicationParametersEXT 667structures to the pname:pNext chain of the sname:VkApplicationInfo 668structure. 669 670If slink:VkApplicationParametersEXT::pname:vendorID does not correspond to 671an ICD that is currently available, or if 672slink:VkApplicationParametersEXT::pname:deviceID is not `0` and does not 673correspond to a physical device that is available on the system, 674flink:vkCreateInstance will fail and return 675ename:VK_ERROR_INCOMPATIBLE_DRIVER. 676If slink:VkApplicationParametersEXT::pname:deviceID is `0`, the application 677parameter applies to all physical devices supported by the ICD identified by 678slink:VkApplicationParametersEXT::pname:vendorID. 679 680If slink:VkApplicationParametersEXT::pname:key is not a valid 681implementation-defined application parameter key for the instance being 682created with pname:vendorID, or if pname:value is not a valid value for the 683specified pname:key, flink:vkCreateInstance will fail and return 684ename:VK_ERROR_INITIALIZATION_FAILED. 685 686For any implementation-defined application parameter pname:key that exists 687but is not set by the application, the implementation-specific default value 688is used. 689endif::VK_EXT_application_parameters[] 690 691.Valid Usage 692**** 693ifndef::VKSC_VERSION_1_0[] 694 * [[VUID-VkApplicationInfo-apiVersion-04010]] 695 If pname:apiVersion is not `0`, then it must: be greater than or equal 696 to dlink:VK_API_VERSION_1_0 697endif::VKSC_VERSION_1_0[] 698ifdef::VKSC_VERSION_1_0[] 699 * [[VUID-VkApplicationInfo-apiVersion-05021]] 700 If pname:apiVersion is not `0` and its variant is 701 dname:VKSC_API_VARIANT, then it must: be greater than or equal to 702 dlink:VKSC_API_VERSION_1_0 703endif::VKSC_VERSION_1_0[] 704ifdef::VK_EXT_application_parameters[] 705 * [[VUID-VkApplicationInfo-key-05093]] 706 The pname:key value of each slink:VkApplicationParametersEXT structure 707 in the slink:VkApplicationInfo::pname:pNext chain must: be unique for 708 each pname:vendorID and pname:deviceID pairing 709endif::VK_EXT_application_parameters[] 710**** 711 712include::{generated}/validity/structs/VkApplicationInfo.adoc[] 713-- 714 715ifdef::VK_EXT_application_parameters[] 716[open,refpage='VkApplicationParametersEXT',desc='Structure specifying application parameters to an instance or device',type='structs'] 717-- 718The sname:VkApplicationParametersEXT structure is defined as: 719 720include::{generated}/api/structs/VkApplicationParametersEXT.adoc[] 721 722 * pname:sType is a elink:VkStructureType value identifying this structure. 723 * pname:pNext is `NULL` or a pointer to a structure extending this 724 structure. 725 * pname:vendorID is the slink:VkPhysicalDeviceProperties::pname:vendorID 726 of the ICD that the application parameter is applied to. 727 * pname:deviceID is `0` or the 728 slink:VkPhysicalDeviceProperties::pname:deviceID of the physical device 729 that the application parameter is applied to. 730 * pname:key is a 32-bit vendor-specific enumerant identifying the 731 application parameter that is being set. 732 * pname:value is the 64-bit value that is being set for the application 733 parameter specified by pname:key. 734 735include::{generated}/validity/structs/VkApplicationParametersEXT.adoc[] 736-- 737endif::VK_EXT_application_parameters[] 738 739[open,refpage='vkDestroyInstance',desc='Destroy an instance of Vulkan',type='protos'] 740-- 741To destroy an instance, call: 742 743include::{generated}/api/protos/vkDestroyInstance.adoc[] 744 745 * pname:instance is the handle of the instance to destroy. 746 * pname:pAllocator controls host memory allocation as described in the 747 <<memory-allocation, Memory Allocation>> chapter. 748 749.Valid Usage 750**** 751 * [[VUID-vkDestroyInstance-instance-00629]] 752 All child objects created using pname:instance must: have been destroyed 753 prior to destroying pname:instance 754ifndef::VKSC_VERSION_1_0[] 755 * [[VUID-vkDestroyInstance-instance-00630]] 756 If sname:VkAllocationCallbacks were provided when pname:instance was 757 created, a compatible set of callbacks must: be provided here 758 * [[VUID-vkDestroyInstance-instance-00631]] 759 If no sname:VkAllocationCallbacks were provided when pname:instance was 760 created, pname:pAllocator must: be `NULL` 761endif::VKSC_VERSION_1_0[] 762**** 763 764include::{generated}/validity/protos/vkDestroyInstance.adoc[] 765-- 766