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