1// Copyright 2015-2024 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_EXT_layer_settings[] 466include::{chapters}/VK_EXT_layer_settings.adoc[] 467endif::VK_EXT_layer_settings[] 468 469ifdef::VK_LUNARG_direct_driver_loading[] 470[open,refpage='VkDirectDriverLoadingListLUNARG',desc='Structure specifying additional drivers to load',type='structs'] 471-- 472The sname:VkDirectDriverLoadingListLUNARG structure is defined as: 473 474include::{generated}/api/structs/VkDirectDriverLoadingListLUNARG.adoc[] 475 476 * pname:sType is a elink:VkStructureType value identifying this structure. 477 * pname:pNext is `NULL` or a pointer to a structure extending this 478 structure. 479 * pname:mode controls the mode in which to load the provided drivers. 480 * pname:driverCount is the number of driver manifest paths. 481 * pname:pDrivers is a pointer to an array of pname:driverCount 482 slink:VkDirectDriverLoadingInfoLUNARG structures. 483 484When creating a Vulkan instance for which additional drivers are to be 485included, add a sname:VkDirectDriverLoadingListLUNARG structure to the pNext 486chain of the slink:VkInstanceCreateInfo structure, and include in it the 487list of sname:VkDirectDriverLoadingInfoLUNARG structures which contain the 488information necessary to load additional drivers. 489 490include::{generated}/validity/structs/VkDirectDriverLoadingListLUNARG.adoc[] 491-- 492 493[open,refpage='VkDirectDriverLoadingInfoLUNARG',desc='Structure specifying the information required to load an additional driver',type='structs'] 494-- 495The sname:VkDirectDriverLoadingInfoLUNARG structure is defined as: 496 497include::{generated}/api/structs/VkDirectDriverLoadingInfoLUNARG.adoc[] 498 499 * pname:sType is a elink:VkStructureType value identifying this structure. 500 * pname:pNext is `NULL` or a pointer to a structure extending this 501 structure. 502 * pname:flags is reserved for future use. 503 * pname:pfnGetInstanceProcAddr is a tlink:PFN_vkGetInstanceProcAddrLUNARG 504 pointer to the driver flink:vkGetInstanceProcAddr function. 505 506include::{generated}/validity/structs/VkDirectDriverLoadingInfoLUNARG.adoc[] 507-- 508 509[open,refpage='VkDirectDriverLoadingModeLUNARG',desc='Specify loader behavior of added drivers',type='enums'] 510-- 511Possible values of slink:VkDirectDriverLoadingListLUNARG::pname:mode, 512specifying the mode in which drivers are used, are: 513 514include::{generated}/api/enums/VkDirectDriverLoadingModeLUNARG.adoc[] 515 516 * ename:VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG specifies that the 517 provided drivers are used instead of the system-loaded drivers. 518 * ename:VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG specifies that the 519 provided drivers are used in addition to the system-loaded drivers. 520-- 521 522[open,refpage='VkDirectDriverLoadingFlagsLUNARG',desc='Reserved for future use',type='flags'] 523-- 524include::{generated}/api/flags/VkDirectDriverLoadingFlagsLUNARG.adoc[] 525 526tname:VkDirectDriverLoadingFlagsLUNARG is a bitmask type for setting a mask, 527but is currently reserved for future use. 528-- 529 530[open,refpage='PFN_vkGetInstanceProcAddrLUNARG',desc='Type definition for vkGetInstanceProcAddr',type='funcpointers'] 531-- 532The type of tlink:PFN_vkGetInstanceProcAddrLUNARG is: 533 534include::{generated}/api/funcpointers/PFN_vkGetInstanceProcAddrLUNARG.adoc[] 535 536 * pname:instance is a slink:VkInstance handle. 537 * pname:pName is the name of a Vulkan command. 538 539This type is compatible with the type of a pointer to the 540flink:vkGetInstanceProcAddr command, but is used only to specify device 541driver addresses in 542slink:VkDirectDriverLoadingInfoLUNARG::pname:pfnGetInstanceProcAddr. 543 544[NOTE] 545.Note 546==== 547This type exists only because of limitations in the XML schema and 548processing scripts, and its name may change in the future. 549Ideally we would use the tname:PFN_vkGetInstanceProcAddr type generated in 550the `vulkan_core.h` header. 551==== 552-- 553endif::VK_LUNARG_direct_driver_loading[] 554 555[open,refpage='VkApplicationInfo',desc='Structure specifying application information',type='structs'] 556-- 557The sname:VkApplicationInfo structure is defined as: 558 559include::{generated}/api/structs/VkApplicationInfo.adoc[] 560 561 * pname:sType is a elink:VkStructureType value identifying this structure. 562 * pname:pNext is `NULL` or a pointer to a structure extending this 563 structure. 564 * pname:pApplicationName is `NULL` or is a pointer to a null-terminated 565 UTF-8 string containing the name of the application. 566 * pname:applicationVersion is an unsigned integer variable containing the 567 developer-supplied version number of the application. 568 * pname:pEngineName is `NULL` or is a pointer to a null-terminated UTF-8 569 string containing the name of the engine (if any) used to create the 570 application. 571 * pname:engineVersion is an unsigned integer variable containing the 572 developer-supplied version number of the engine used to create the 573 application. 574ifndef::VK_VERSION_1_1[] 575 * pname:apiVersion is the version of the Vulkan API against which the 576 application expects to run, encoded as described in 577 <<extendingvulkan-coreversions-versionnumbers>>. 578 If pname:apiVersion is 0 the implementation must: ignore it, otherwise 579 if the implementation does not support the requested pname:apiVersion, 580 or an effective substitute for pname:apiVersion, it must: return 581 ename:VK_ERROR_INCOMPATIBLE_DRIVER. 582endif::VK_VERSION_1_1[] 583ifdef::VK_VERSION_1_1[] 584 * pname:apiVersion must: be the highest version of Vulkan that the 585 application is designed to use, encoded as described in 586 <<extendingvulkan-coreversions-versionnumbers>>. 587endif::VK_VERSION_1_1[] 588 The patch version number specified in pname:apiVersion is ignored when 589 creating an instance object. 590 The variant version of the instance must: match that requested in 591 pname:apiVersion. 592 593ifdef::VK_VERSION_1_1[] 594Vulkan 1.0 implementations were required to return 595ename:VK_ERROR_INCOMPATIBLE_DRIVER if pname:apiVersion was larger than 1.0. 596Implementations that support Vulkan 1.1 or later must: not return 597ename:VK_ERROR_INCOMPATIBLE_DRIVER for any value of pname:apiVersion 598ifndef::VKSC_VERSION_1_0[.] 599ifdef::VKSC_VERSION_1_0[, unless an incompatible variant is requested.] 600 601ifdef::VKSC_VERSION_1_0[] 602[NOTE] 603.Note 604==== 605Vulkan SC 1.0 is based on Vulkan 1.2 and thus instance creation may only 606fail with ename:VK_ERROR_INCOMPATIBLE_DRIVER if an incompatible variant is 607requested - that is if the Vulkan SC API is requested from a Vulkan 608implementation or if the Vulkan API is requested from a Vulkan SC 609implementation. 610==== 611endif::VKSC_VERSION_1_0[] 612 613ifndef::VKSC_VERSION_1_0[] 614[NOTE] 615.Note 616==== 617Because Vulkan 1.0 implementations may: fail with 618ename:VK_ERROR_INCOMPATIBLE_DRIVER, applications should: determine the 619version of Vulkan available before calling flink:vkCreateInstance. 620If the flink:vkGetInstanceProcAddr returns `NULL` for 621flink:vkEnumerateInstanceVersion, it is a Vulkan 1.0 implementation. 622Otherwise, the application can: call flink:vkEnumerateInstanceVersion to 623determine the version of Vulkan. 624==== 625 626As long as the instance supports at least Vulkan 1.1, an application can: 627use different versions of Vulkan with an instance than it does with a device 628or physical device. 629 630[NOTE] 631.Note 632==== 633The Khronos validation layers will treat pname:apiVersion as the highest API 634version the application targets, and will validate API usage against the 635minimum of that version and the implementation version (instance or device, 636depending on context). 637If an application tries to use functionality from a greater version than 638this, a validation error will be triggered. 639 640For example, if the instance supports Vulkan 1.1 and three physical devices 641support Vulkan 1.0, Vulkan 1.1, and Vulkan 1.2, respectively, and if the 642application sets pname:apiVersion to 1.2, the application can: use the 643following versions of Vulkan: 644 645 * Vulkan 1.0 can: be used with the instance and with all physical devices. 646 * Vulkan 1.1 can: be used with the instance and with the physical devices 647 that support Vulkan 1.1 and Vulkan 1.2. 648 * Vulkan 1.2 can: be used with the physical device that supports Vulkan 649 1.2. 650 651If we modify the above example so that the application sets pname:apiVersion 652to 1.1, then the application must: not use Vulkan 1.2 functionality on the 653physical device that supports Vulkan 1.2. 654==== 655endif::VKSC_VERSION_1_0[] 656 657[NOTE] 658.Note 659==== 660Providing a `NULL` slink:VkInstanceCreateInfo::pname:pApplicationInfo or 661providing an pname:apiVersion of 0 is equivalent to providing an 662pname:apiVersion of 663ifndef::VKSC_VERSION_1_0[`VK_MAKE_API_VERSION(0,1,0,0)`.] 664ifdef::VKSC_VERSION_1_0[`VK_MAKE_API_VERSION(1,1,0,0)`.] 665==== 666endif::VK_VERSION_1_1[] 667 668ifdef::VK_EXT_application_parameters[] 669To provide _application parameters_ at instance creation time, an 670application can: link one or more slink:VkApplicationParametersEXT 671structures to the pname:pNext chain of the sname:VkApplicationInfo 672structure. 673 674If slink:VkApplicationParametersEXT::pname:vendorID does not correspond to 675an ICD that is currently available, or if 676slink:VkApplicationParametersEXT::pname:deviceID is not `0` and does not 677correspond to a physical device that is available on the system, 678flink:vkCreateInstance will fail and return 679ename:VK_ERROR_INCOMPATIBLE_DRIVER. 680If slink:VkApplicationParametersEXT::pname:deviceID is `0`, the application 681parameter applies to all physical devices supported by the ICD identified by 682slink:VkApplicationParametersEXT::pname:vendorID. 683 684If slink:VkApplicationParametersEXT::pname:key is not a valid 685implementation-defined application parameter key for the instance being 686created with pname:vendorID, or if pname:value is not a valid value for the 687specified pname:key, flink:vkCreateInstance will fail and return 688ename:VK_ERROR_INITIALIZATION_FAILED. 689 690For any implementation-defined application parameter pname:key that exists 691but is not set by the application, the implementation-specific default value 692is used. 693endif::VK_EXT_application_parameters[] 694 695.Valid Usage 696**** 697ifndef::VKSC_VERSION_1_0[] 698 * [[VUID-VkApplicationInfo-apiVersion-04010]] 699 If pname:apiVersion is not `0`, then it must: be greater than or equal 700 to dlink:VK_API_VERSION_1_0 701endif::VKSC_VERSION_1_0[] 702ifdef::VKSC_VERSION_1_0[] 703 * [[VUID-VkApplicationInfo-apiVersion-05021]] 704 If pname:apiVersion is not `0` and its variant is 705 dname:VKSC_API_VARIANT, then it must: be greater than or equal to 706 dlink:VKSC_API_VERSION_1_0 707endif::VKSC_VERSION_1_0[] 708ifdef::VK_EXT_application_parameters[] 709 * [[VUID-VkApplicationInfo-key-05093]] 710 The pname:key value of each slink:VkApplicationParametersEXT structure 711 in the slink:VkApplicationInfo::pname:pNext chain must: be unique for 712 each pname:vendorID and pname:deviceID pairing 713endif::VK_EXT_application_parameters[] 714**** 715 716include::{generated}/validity/structs/VkApplicationInfo.adoc[] 717-- 718 719ifdef::VK_EXT_application_parameters[] 720[open,refpage='VkApplicationParametersEXT',desc='Structure specifying application parameters to an instance or device',type='structs'] 721-- 722The sname:VkApplicationParametersEXT structure is defined as: 723 724include::{generated}/api/structs/VkApplicationParametersEXT.adoc[] 725 726 * pname:sType is a elink:VkStructureType value identifying this structure. 727 * pname:pNext is `NULL` or a pointer to a structure extending this 728 structure. 729 * pname:vendorID is the slink:VkPhysicalDeviceProperties::pname:vendorID 730 of the ICD that the application parameter is applied to. 731 * pname:deviceID is `0` or the 732 slink:VkPhysicalDeviceProperties::pname:deviceID of the physical device 733 that the application parameter is applied to. 734 * pname:key is a 32-bit vendor-specific enumerant identifying the 735 application parameter that is being set. 736 * pname:value is the 64-bit value that is being set for the application 737 parameter specified by pname:key. 738 739include::{generated}/validity/structs/VkApplicationParametersEXT.adoc[] 740-- 741endif::VK_EXT_application_parameters[] 742 743[open,refpage='vkDestroyInstance',desc='Destroy an instance of Vulkan',type='protos'] 744-- 745To destroy an instance, call: 746 747include::{generated}/api/protos/vkDestroyInstance.adoc[] 748 749 * pname:instance is the handle of the instance to destroy. 750 * pname:pAllocator controls host memory allocation as described in the 751 <<memory-allocation, Memory Allocation>> chapter. 752 753.Valid Usage 754**** 755 * [[VUID-vkDestroyInstance-instance-00629]] 756 All child objects created using pname:instance must: have been destroyed 757 prior to destroying pname:instance 758ifndef::VKSC_VERSION_1_0[] 759 * [[VUID-vkDestroyInstance-instance-00630]] 760 If sname:VkAllocationCallbacks were provided when pname:instance was 761 created, a compatible set of callbacks must: be provided here 762 * [[VUID-vkDestroyInstance-instance-00631]] 763 If no sname:VkAllocationCallbacks were provided when pname:instance was 764 created, pname:pAllocator must: be `NULL` 765endif::VKSC_VERSION_1_0[] 766**** 767 768include::{generated}/validity/protos/vkDestroyInstance.adoc[] 769-- 770