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