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[[devsandqueues]] 6= Devices and Queues 7 8Once Vulkan is initialized, devices and queues are the primary objects used 9to interact with a Vulkan implementation. 10 11[open,refpage='VkPhysicalDevice',desc='Opaque handle to a physical device object',type='handles'] 12-- 13 14Vulkan separates the concept of _physical_ and _logical_ devices. 15A physical device usually represents a single complete implementation of 16Vulkan (excluding instance-level functionality) available to the host, of 17which there are a finite number. 18A logical device represents an instance of that implementation with its own 19state and resources independent of other logical devices. 20 21Physical devices are represented by sname:VkPhysicalDevice handles: 22 23include::../api/handles/VkPhysicalDevice.txt[] 24 25-- 26 27 28[[devsandqueues-physical-device-enumeration]] 29== Physical Devices 30 31[open,refpage='vkEnumeratePhysicalDevices',desc='Enumerates the physical devices accessible to a Vulkan instance',type='protos'] 32-- 33 34To retrieve a list of physical device objects representing the physical 35devices installed in the system, call: 36 37include::../api/protos/vkEnumeratePhysicalDevices.txt[] 38 39 * pname:instance is a handle to a Vulkan instance previously created with 40 flink:vkCreateInstance. 41 * pname:pPhysicalDeviceCount is a pointer to an integer related to the 42 number of physical devices available or queried, as described below. 43 * pname:pPhysicalDevices is either `NULL` or a pointer to an array of 44 sname:VkPhysicalDevice handles. 45 46If pname:pPhysicalDevices is `NULL`, then the number of physical devices 47available is returned in pname:pPhysicalDeviceCount. 48Otherwise, pname:pPhysicalDeviceCount must: point to a variable set by the 49user to the number of elements in the pname:pPhysicalDevices array, and on 50return the variable is overwritten with the number of handles actually 51written to pname:pPhysicalDevices. 52If pname:pPhysicalDeviceCount is less than the number of physical devices 53available, at most pname:pPhysicalDeviceCount structures will be written. 54If pname:pPhysicalDeviceCount is smaller than the number of physical devices 55available, ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, 56to indicate that not all the available physical devices were returned. 57 58include::../validity/protos/vkEnumeratePhysicalDevices.txt[] 59-- 60 61[open,refpage='vkGetPhysicalDeviceProperties',desc='Returns properties of a physical device',type='protos'] 62-- 63 64To query general properties of physical devices once enumerated, call: 65 66include::../api/protos/vkGetPhysicalDeviceProperties.txt[] 67 68 * pname:physicalDevice is the handle to the physical device whose 69 properties will be queried. 70 * pname:pProperties points to an instance of the 71 slink:VkPhysicalDeviceProperties structure, that will be filled with 72 returned information. 73 74include::../validity/protos/vkGetPhysicalDeviceProperties.txt[] 75-- 76 77[open,refpage='VkPhysicalDeviceProperties',desc='Structure specifying physical device properties',type='structs'] 78-- 79 80The sname:VkPhysicalDeviceProperties structure is defined as: 81 82include::../api/structs/VkPhysicalDeviceProperties.txt[] 83 84 * pname:apiVersion is the version of Vulkan supported by the device, 85 encoded as described in the <<fundamentals-versionnum,API Version 86 Numbers and Semantics>> section. 87 * pname:driverVersion is the vendor-specified version of the driver. 88 * pname:vendorID is a unique identifier for the _vendor_ (see below) of 89 the physical device. 90 * pname:deviceID is a unique identifier for the physical device among 91 devices available from the vendor. 92 * pname:deviceType is a elink:VkPhysicalDeviceType specifying the type of 93 device. 94 * pname:deviceName is a null-terminated UTF-8 string containing the name 95 of the device. 96 * pname:pipelineCacheUUID is an array of size ename:VK_UUID_SIZE, 97 containing 8-bit values that represent a universally unique identifier 98 for the device. 99 * pname:limits is the slink:VkPhysicalDeviceLimits structure which 100 specifies device-specific limits of the physical device. 101 See <<features-limits,Limits>> for details. 102 * pname:sparseProperties is the slink:VkPhysicalDeviceSparseProperties 103 structure which specifies various sparse related properties of the 104 physical device. 105 See <<sparsememory-physicalprops,Sparse Properties>> for details. 106 107ifdef::VK_VERSION_1_1[] 108[NOTE] 109.Note 110==== 111The value of pname:apiVersion may: be different than the version returned by 112flink:vkEnumerateInstanceVersion; either higher or lower. 113In such cases, the application must: not use functionality that exceeds the 114version of Vulkan associated with a given object. 115The pname:pApiVersion parameter returned by flink:vkEnumerateInstanceVersion 116is the version associated with a slink:VkInstance and its children, except 117for a slink:VkPhysicalDevice and its children. 118sname:VkPhysicalDeviceProperties::pname:apiVersion is the version associated 119with a slink:VkPhysicalDevice and its children. 120==== 121endif::VK_VERSION_1_1[] 122 123The pname:vendorID and pname:deviceID fields are provided to allow 124applications to adapt to device characteristics that are not adequately 125exposed by other Vulkan queries. 126 127[NOTE] 128.Note 129==== 130These may: include performance profiles, hardware errata, or other 131characteristics. 132==== 133 134The _vendor_ identified by pname:vendorID is the entity responsible for the 135most salient characteristics of the underlying implementation of the 136slink:VkPhysicalDevice being queried. 137 138[NOTE] 139.Note 140==== 141For example, in the case of a discrete GPU implementation, this should: be 142the GPU chipset vendor. 143In the case of a hardware accelerator integrated into a system-on-chip 144(SoC), this should: be the supplier of the silicon IP used to create the 145accelerator. 146==== 147 148If the vendor has a https://pcisig.com/membership/member-companies[PCI 149vendor ID], the low 16 bits of pname:vendorID must: contain that PCI vendor 150ID, and the remaining bits must: be set to zero. 151Otherwise, the value returned must: be a valid Khronos vendor ID, obtained 152as described in the <<vulkan-styleguide,Vulkan Documentation and Extensions: 153Procedures and Conventions>> document in the section "`Registering a Vendor 154ID with Khronos`". 155Khronos vendor IDs are allocated starting at 0x10000, to distinguish them 156from the PCI vendor ID namespace. 157Khronos vendor IDs are symbolically defined in the elink:VkVendorId type. 158 159The vendor is also responsible for the value returned in pname:deviceID. 160If the implementation is driven primarily by a https://pcisig.com/[PCI 161device] with a https://pcisig.com/[PCI device ID], the low 16 bits of 162pname:deviceID must: contain that PCI device ID, and the remaining bits 163must: be set to zero. 164Otherwise, the choice of what values to return may: be dictated by operating 165system or platform policies - but should: uniquely identify both the device 166version and any major configuration options (for example, core count in the 167case of multicore devices). 168 169[NOTE] 170.Note 171==== 172The same device ID should: be used for all physical implementations of that 173device version and configuration. 174For example, all uses of a specific silicon IP GPU version and configuration 175should: use the same device ID, even if those uses occur in different SoCs. 176==== 177 178include::../validity/structs/VkPhysicalDeviceProperties.txt[] 179-- 180 181[open,refpage='VkVendorId',desc='Khronos vendor IDs',type='enums'] 182-- 183Khronos vendor IDs which may: be returned in 184slink:VkPhysicalDeviceProperties::pname:vendorID are: 185 186include::../api/enums/VkVendorId.txt[] 187 188[NOTE] 189.Note 190==== 191Khronos vendor IDs may be allocated by vendors at any time. 192Only the latest canonical versions of this Specification, of the 193corresponding `vk.xml` API Registry, and of the corresponding 194`vulkan_core.h` header file must: contain all reserved Khronos vendor IDs. 195 196Only Khronos vendor IDs are given symbolic names at present. 197PCI vendor IDs returned by the implementation can be looked up in the 198PCI-SIG database. 199==== 200 201-- 202 203 204[open,refpage='VkPhysicalDeviceType',desc='Supported physical device types',type='enums'] 205-- 206 207The physical device types which may: be returned in 208slink:VkPhysicalDeviceProperties::pname:deviceType are: 209 210include::../api/enums/VkPhysicalDeviceType.txt[] 211 212 * ename:VK_PHYSICAL_DEVICE_TYPE_OTHER - the device does not match any 213 other available types. 214 * ename:VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU - the device is typically 215 one embedded in or tightly coupled with the host. 216 * ename:VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU - the device is typically a 217 separate processor connected to the host via an interlink. 218 * ename:VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU - the device is typically a 219 virtual node in a virtualization environment. 220 * ename:VK_PHYSICAL_DEVICE_TYPE_CPU - the device is typically running on 221 the same processors as the host. 222 223The physical device type is advertised for informational purposes only, and 224does not directly affect the operation of the system. 225However, the device type may: correlate with other advertised properties or 226capabilities of the system, such as how many memory heaps there are. 227 228-- 229 230ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 231 232[open,refpage='vkGetPhysicalDeviceProperties2',desc='Returns properties of a physical device',type='protos'] 233-- 234 235To query general properties of physical devices once enumerated, call: 236 237ifdef::VK_VERSION_1_1[] 238include::../api/protos/vkGetPhysicalDeviceProperties2.txt[] 239endif::VK_VERSION_1_1[] 240 241ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] 242 243ifdef::VK_KHR_get_physical_device_properties2[] 244include::../api/protos/vkGetPhysicalDeviceProperties2KHR.txt[] 245endif::VK_KHR_get_physical_device_properties2[] 246 247 * pname:physicalDevice is the handle to the physical device whose 248 properties will be queried. 249 * pname:pProperties points to an instance of the 250 slink:VkPhysicalDeviceProperties2 structure, that will be filled with 251 returned information. 252 253Each structure in pname:pProperties and its pname:pNext chain contain 254members corresponding to properties or implementation-dependent limits. 255fname:vkGetPhysicalDeviceProperties2 writes each member to a value 256indicating the value of that property or limit. 257 258include::../validity/protos/vkGetPhysicalDeviceProperties2.txt[] 259-- 260 261[open,refpage='VkPhysicalDeviceProperties2',desc='Structure specifying physical device properties',type='structs'] 262-- 263 264The sname:VkPhysicalDeviceProperties2 structure is defined as: 265 266include::../api/structs/VkPhysicalDeviceProperties2.txt[] 267 268ifdef::VK_KHR_get_physical_device_properties2[] 269or the equivalent 270 271include::../api/structs/VkPhysicalDeviceProperties2KHR.txt[] 272endif::VK_KHR_get_physical_device_properties2[] 273 274 * pname:sType is the type of this structure. 275 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 276 * pname:properties is a structure of type slink:VkPhysicalDeviceProperties 277 describing the properties of the physical device. 278 This structure is written with the same values as if it were written by 279 flink:vkGetPhysicalDeviceProperties. 280 281The pname:pNext chain of this structure is used to extend the structure with 282properties defined by extensions. 283 284include::../validity/structs/VkPhysicalDeviceProperties2.txt[] 285-- 286 287ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 288 289[open,refpage='VkPhysicalDeviceIDProperties',desc='Structure specifying IDs related to the physical device',type='structs'] 290-- 291 292To query the UUID and LUID of a device, add 293slink:VkPhysicalDeviceIDProperties to the pname:pNext chain of the 294slink:VkPhysicalDeviceProperties2 structure. 295The sname:VkPhysicalDeviceIDProperties structure is defined as: 296 297include::../api/structs/VkPhysicalDeviceIDProperties.txt[] 298 299ifdef::VK_KHR_external_memory_capabilities[] 300or the equivalent 301 302include::../api/structs/VkPhysicalDeviceIDPropertiesKHR.txt[] 303endif::VK_KHR_external_memory_capabilities[] 304 305 * pname:sType is the type of this structure. 306 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 307 * pname:deviceUUID is an array of size ename:VK_UUID_SIZE, containing 308 8-bit values that represent a universally unique identifier for the 309 device. 310 * pname:driverUUID is an array of size ename:VK_UUID_SIZE, containing 311 8-bit values that represent a universally unique identifier for the 312 driver build in use by the device. 313 * pname:deviceLUID is an array of size ename:VK_LUID_SIZE, containing 314 8-bit values that represent a locally unique identifier for the device. 315 * pname:deviceNodeMask is a bitfield identifying the node within a linked 316 device adapter corresponding to the device. 317 * pname:deviceLUIDValid is a boolean value that will be ename:VK_TRUE if 318 pname:deviceLUID contains a valid LUID and pname:deviceNodeMask contains 319 a valid node mask, and ename:VK_FALSE if they do not. 320 321pname:deviceUUID must: be immutable for a given device across instances, 322processes, driver APIs, driver versions, and system reboots. 323 324Applications can: compare the pname:driverUUID value across instance and 325process boundaries, and can: make similar queries in external APIs to 326determine whether they are capable of sharing memory objects and resources 327using them with the device. 328 329pname:deviceUUID and/or pname:driverUUID must: be used to determine whether 330a particular external object can be shared between driver components, where 331such a restriction exists as defined in the compatibility table for the 332particular object type: 333 334ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 335 * <<external-memory-handle-types-compatibility,External memory handle 336 types compatibility>> 337endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 338ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] 339 * <<external-semaphore-handle-types-compatibility,External semaphore 340 handle types compatibility>> 341endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] 342ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] 343 * <<external-fence-handle-types-compatibility,External fence handle types 344 compatibility>> 345endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] 346 347If pname:deviceLUIDValid is ename:VK_FALSE, the contents of pname:deviceLUID 348and pname:deviceNodeMask are undefined. 349If pname:deviceLUIDValid is ename:VK_TRUE and Vulkan is running on the 350Windows operating system, the contents of pname:deviceLUID can: be cast to 351an sname:LUID object and must: be equal to the locally unique identifier of 352a sname:IDXGIAdapter1 object that corresponds to pname:physicalDevice. 353If pname:deviceLUIDValid is ename:VK_TRUE, pname:deviceNodeMask must: 354contain exactly one bit. 355If Vulkan is running on an operating system that supports the Direct3D 12 356API and pname:physicalDevice corresponds to an individual device in a linked 357device adapter, pname:deviceNodeMask identifies the Direct3D 12 node 358corresponding to pname:physicalDevice. 359Otherwise, pname:deviceNodeMask must: be `1`. 360 361[NOTE] 362.Note 363==== 364Although they have identical descriptions, 365slink:VkPhysicalDeviceIDProperties::pname:deviceUUID may differ from 366slink:VkPhysicalDeviceProperties2::pname:pipelineCacheUUID. 367The former is intended to identify and correlate devices across API and 368driver boundaries, while the latter is used to identify a compatible device 369and driver combination to use when serializing and de-serializing pipeline 370state. 371==== 372 373[NOTE] 374.Note 375==== 376While slink:VkPhysicalDeviceIDProperties::pname:deviceUUID is specified to 377remain consistent across driver versions and system reboots, it is not 378intended to be usable as a serializable persistent identifier for a device. 379It may change when a device is physically added to, removed from, or moved 380to a different connector in a system while that system is powered down. 381Further, there is no reasonable way to verify with conformance testing that 382a given device retains the same UUID in a given system across all driver 383versions supported in that system. 384While implementations should make every effort to report consistent device 385UUIDs across driver versions, applications should avoid relying on the 386persistence of this value for uses other than identifying compatible devices 387for external object sharing purposes. 388==== 389 390include::../validity/structs/VkPhysicalDeviceIDProperties.txt[] 391-- 392 393endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 394 395endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 396 397[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties',desc='Reports properties of the queues of the specified physical device',type='protos'] 398-- 399 400To query properties of queues available on a physical device, call: 401 402include::../api/protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[] 403 404 * pname:physicalDevice is the handle to the physical device whose 405 properties will be queried. 406 * pname:pQueueFamilyPropertyCount is a pointer to an integer related to 407 the number of queue families available or queried, as described below. 408 * pname:pQueueFamilyProperties is either `NULL` or a pointer to an array 409 of slink:VkQueueFamilyProperties structures. 410 411If pname:pQueueFamilyProperties is `NULL`, then the number of queue families 412available is returned in pname:pQueueFamilyPropertyCount. 413Otherwise, pname:pQueueFamilyPropertyCount must: point to a variable set by 414the user to the number of elements in the pname:pQueueFamilyProperties 415array, and on return the variable is overwritten with the number of 416structures actually written to pname:pQueueFamilyProperties. 417If pname:pQueueFamilyPropertyCount is less than the number of queue families 418available, at most pname:pQueueFamilyPropertyCount structures will be 419written. 420 421include::../validity/protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[] 422-- 423 424[open,refpage='VkQueueFamilyProperties',desc='Structure providing information about a queue family',type='structs'] 425-- 426 427The sname:VkQueueFamilyProperties structure is defined as: 428 429include::../api/structs/VkQueueFamilyProperties.txt[] 430 431 * pname:queueFlags is a bitmask of elink:VkQueueFlagBits indicating 432 capabilities of the queues in this queue family. 433 * pname:queueCount is the unsigned integer count of queues in this queue 434 family. 435 * pname:timestampValidBits is the unsigned integer count of meaningful 436 bits in the timestamps written via fname:vkCmdWriteTimestamp. 437 The valid range for the count is 36..64 bits, or a value of 0, 438 indicating no support for timestamps. 439 Bits outside the valid range are guaranteed to be zeros. 440 * pname:minImageTransferGranularity is the minimum granularity supported 441 for image transfer operations on the queues in this queue family. 442 443The value returned in pname:minImageTransferGranularity has a unit of 444compressed texel blocks for images having a block-compressed format, and a 445unit of texels otherwise. 446 447Possible values of pname:minImageTransferGranularity are: 448 449 * [eq]#(0,0,0)# which indicates that only whole mip levels must: be 450 transferred using the image transfer operations on the corresponding 451 queues. 452 In this case, the following restrictions apply to all offset and extent 453 parameters of image transfer operations: 454 455 ** The pname:x, pname:y, and pname:z members of a slink:VkOffset3D 456 parameter must: always be zero. 457 ** The pname:width, pname:height, and pname:depth members of a 458 slink:VkExtent3D parameter must: always match the width, height, and 459 depth of the image subresource corresponding to the parameter, 460 respectively. 461 462 * [eq]#(A~x~, A~y~, A~z~)# where [eq]#A~x~#, [eq]#A~y~#, and [eq]#A~z~# 463 are all integer powers of two. 464 In this case the following restrictions apply to all image transfer 465 operations: 466 467 ** pname:x, pname:y, and pname:z of a slink:VkOffset3D parameter must: be 468 integer multiples of [eq]#A~x~#, [eq]#A~y~#, and [eq]#A~z~#, 469 respectively. 470 ** pname:width of a slink:VkExtent3D parameter must: be an integer 471 multiple of [eq]#A~x~#, or else [eq]#pname:x {plus} pname:width# must: 472 equal the width of the image subresource corresponding to the 473 parameter. 474 ** pname:height of a slink:VkExtent3D parameter must: be an integer 475 multiple of [eq]#A~y~#, or else [eq]#pname:y {plus} pname:height# must: 476 equal the height of the image subresource corresponding to the 477 parameter. 478 ** pname:depth of a slink:VkExtent3D parameter must: be an integer 479 multiple of [eq]#A~z~#, or else [eq]#pname:z {plus} pname:depth# must: 480 equal the depth of the image subresource corresponding to the 481 parameter. 482 ** If the format of the image corresponding to the parameters is one of 483 the block-compressed formats then for the purposes of the above 484 calculations the granularity must: be scaled up by the compressed texel 485 block dimensions. 486 487Queues supporting graphics and/or compute operations must: report 488[eq]#(1,1,1)# in pname:minImageTransferGranularity, meaning that there are 489no additional restrictions on the granularity of image transfer operations 490for these queues. 491Other queues supporting image transfer operations are only required: to 492support whole mip level transfers, thus pname:minImageTransferGranularity 493for queues belonging to such queue families may: be [eq]#(0,0,0)#. 494 495The <<memory-device,Device Memory>> section describes memory properties 496queried from the physical device. 497 498For physical device feature queries see the <<features, Features>> chapter. 499 500include::../validity/structs/VkQueueFamilyProperties.txt[] 501-- 502 503[open,refpage='VkQueueFlagBits',desc='Bitmask specifying capabilities of queues in a queue family',type='enums'] 504-- 505 506Bits which may: be set in slink:VkQueueFamilyProperties::pname:queueFlags 507indicating capabilities of queues in a queue family are: 508 509include::../api/enums/VkQueueFlagBits.txt[] 510 511 * ename:VK_QUEUE_GRAPHICS_BIT specifies that queues in this queue family 512 support graphics operations. 513 * ename:VK_QUEUE_COMPUTE_BIT specifies that queues in this queue family 514 support compute operations. 515 * ename:VK_QUEUE_TRANSFER_BIT specifies that queues in this queue family 516 support transfer operations. 517 * ename:VK_QUEUE_SPARSE_BINDING_BIT specifies that queues in this queue 518 family support sparse memory management operations (see 519 <<sparsememory,Sparse Resources>>). 520 If any of the sparse resource features are enabled, then at least one 521 queue family must: support this bit. 522ifdef::VK_VERSION_1_1[] 523 * if ename:VK_QUEUE_PROTECTED_BIT is set, then the queues in this queue 524 family support the ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit. 525 (see <<memory-protected-memory,Protected Memory>>). 526 If the protected memory physical device feature is supported, then at 527 least one queue family of at least one physical device exposed by the 528 implementation must: support this bit. 529endif::VK_VERSION_1_1[] 530 531If an implementation exposes any queue family that supports graphics 532operations, at least one queue family of at least one physical device 533exposed by the implementation must: support both graphics and compute 534operations. 535 536ifdef::VK_VERSION_1_1[] 537Furthermore, if the protected memory physical device feature is supported, 538then at least one queue family of at least one physical device exposed by 539the implementation must: support graphics operations, compute operations, 540and protected memory operations. 541endif::VK_VERSION_1_1[] 542 543[NOTE] 544.Note 545==== 546All commands that are allowed on a queue that supports transfer operations 547are also allowed on a queue that supports either graphics or compute 548operations. 549Thus, if the capabilities of a queue family include 550ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT, then reporting 551the ename:VK_QUEUE_TRANSFER_BIT capability separately for that queue family 552is optional:. 553==== 554 555For further details see <<devsandqueues-queues,Queues>>. 556 557-- 558 559[open,refpage='VkQueueFlags',desc='Bitmask of VkQueueFlagBits',type='enums'] 560-- 561include::../api/flags/VkQueueFlags.txt[] 562 563sname:VkQueueFlags is a bitmask type for setting a mask of zero or more 564slink:VkQueueFlagBits. 565-- 566 567ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 568 569[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties2',desc='Reports properties of the queues of the specified physical device',type='protos'] 570-- 571 572To query properties of queues available on a physical device, call: 573 574ifdef::VK_VERSION_1_1[] 575include::../api/protos/vkGetPhysicalDeviceQueueFamilyProperties2.txt[] 576endif::VK_VERSION_1_1[] 577 578ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] 579 580ifdef::VK_KHR_get_physical_device_properties2[] 581include::../api/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.txt[] 582endif::VK_KHR_get_physical_device_properties2[] 583 584 * pname:physicalDevice is the handle to the physical device whose 585 properties will be queried. 586 * pname:pQueueFamilyPropertyCount is a pointer to an integer related to 587 the number of queue families available or queried, as described in 588 flink:vkGetPhysicalDeviceQueueFamilyProperties. 589 * pname:pQueueFamilyProperties is either `NULL` or a pointer to an array 590 of slink:VkQueueFamilyProperties2 structures. 591 592fname:vkGetPhysicalDeviceQueueFamilyProperties2 behaves similarly to 593flink:vkGetPhysicalDeviceQueueFamilyProperties, with the ability to return 594extended information in a pname:pNext chain of output structures. 595 596include::../validity/protos/vkGetPhysicalDeviceQueueFamilyProperties2.txt[] 597-- 598 599[open,refpage='VkQueueFamilyProperties2',desc='Structure providing information about a queue family',type='structs'] 600-- 601 602The sname:VkQueueFamilyProperties2 structure is defined as: 603 604include::../api/structs/VkQueueFamilyProperties2.txt[] 605 606ifdef::VK_KHR_get_physical_device_properties2[] 607or the equivalent 608 609include::../api/structs/VkQueueFamilyProperties2KHR.txt[] 610endif::VK_KHR_get_physical_device_properties2[] 611 612 * pname:sType is the type of this structure. 613 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 614 * pname:queueFamilyProperties is a structure of type 615 slink:VkQueueFamilyProperties which is populated with the same values as 616 in flink:vkGetPhysicalDeviceQueueFamilyProperties. 617 618include::../validity/structs/VkQueueFamilyProperties2.txt[] 619-- 620 621ifdef::VK_NV_device_diagnostic_checkpoints[] 622include::VK_NV_device_diagnostic_checkpoints/queue_checkpoint_properties.txt[] 623endif::VK_NV_device_diagnostic_checkpoints[] 624 625endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 626 627[[devsandqueues-devices]] 628== Devices 629 630Device objects represent logical connections to physical devices. 631Each device exposes a number of _queue families_ each having one or more 632_queues_. 633All queues in a queue family support the same operations. 634 635As described in <<devsandqueues-physical-device-enumeration,Physical 636Devices>>, a Vulkan application will first query for all physical devices in 637a system. 638Each physical device can: then be queried for its capabilities, including 639its queue and queue family properties. 640Once an acceptable physical device is identified, an application will create 641a corresponding logical device. 642An application must: create a separate logical device for each physical 643device it will use. 644The created logical device is then the primary interface to the physical 645device. 646 647How to enumerate the physical devices in a system and query those physical 648devices for their queue family properties is described in the 649<<devsandqueues-physical-device-enumeration, Physical Device Enumeration>> 650section above. 651 652ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[] 653 654A single logical device can: also be created from multiple physical devices, 655if those physical devices belong to the same device group. 656A _device group_ is a set of physical devices that support accessing each 657other's memory and recording a single command buffer that can: be executed 658on all the physical devices. 659Device groups are enumerated by calling 660flink:vkEnumeratePhysicalDeviceGroups, and a logical device is created from 661a subset of the physical devices in a device group by passing the physical 662devices through slink:VkDeviceGroupDeviceCreateInfo. 663 664[open,refpage='vkEnumeratePhysicalDeviceGroups',desc='Enumerates groups of physical devices that can be used to create a single logical device',type='protos'] 665-- 666 667To retrieve a list of the device groups present in the system, call: 668 669ifdef::VK_VERSION_1_1[] 670include::../api/protos/vkEnumeratePhysicalDeviceGroups.txt[] 671endif::VK_VERSION_1_1[] 672 673ifdef::VK_VERSION_1_1+VK_KHR_device_group_creation[or the equivalent command] 674 675ifdef::VK_KHR_device_group_creation[] 676include::../api/protos/vkEnumeratePhysicalDeviceGroupsKHR.txt[] 677endif::VK_KHR_device_group_creation[] 678 679 * pname:instance is a handle to a Vulkan instance previously created with 680 flink:vkCreateInstance. 681 * pname:pPhysicalDeviceGroupCount is a pointer to an integer related to 682 the number of device groups available or queried, as described below. 683 * pname:pPhysicalDeviceGroupProperties is either `NULL` or a pointer to an 684 array of slink:VkPhysicalDeviceGroupProperties structures. 685 686If pname:pPhysicalDeviceGroupProperties is `NULL`, then the number of device 687groups available is returned in pname:pPhysicalDeviceGroupCount. 688Otherwise, pname:pPhysicalDeviceGroupCount must: point to a variable set by 689the user to the number of elements in the 690pname:pPhysicalDeviceGroupProperties array, and on return the variable is 691overwritten with the number of structures actually written to 692pname:pPhysicalDeviceGroupProperties. 693If pname:pPhysicalDeviceGroupCount is less than the number of device groups 694available, at most pname:pPhysicalDeviceGroupCount structures will be 695written. 696If pname:pPhysicalDeviceGroupCount is smaller than the number of device 697groups available, ename:VK_INCOMPLETE will be returned instead of 698ename:VK_SUCCESS, to indicate that not all the available device groups were 699returned. 700 701Every physical device must: be in exactly one device group. 702 703include::../validity/protos/vkEnumeratePhysicalDeviceGroups.txt[] 704-- 705 706[open,refpage='VkPhysicalDeviceGroupProperties',desc='Structure specifying physical device group properties',type='structs'] 707-- 708 709The sname:VkPhysicalDeviceGroupProperties structure is defined as: 710 711include::../api/structs/VkPhysicalDeviceGroupProperties.txt[] 712 713ifdef::VK_KHR_device_group_creation[] 714or the equivalent 715 716include::../api/structs/VkPhysicalDeviceGroupPropertiesKHR.txt[] 717endif::VK_KHR_device_group_creation[] 718 719 * pname:sType is the type of this structure. 720 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 721 * pname:physicalDeviceCount is the number of physical devices in the 722 group. 723 * pname:physicalDevices is an array of physical device handles 724 representing all physical devices in the group. 725 The first pname:physicalDeviceCount elements of the array will be valid. 726 * pname:subsetAllocation specifies whether logical devices created from 727 the group support allocating device memory on a subset of devices, via 728 the pname:deviceMask member of the slink:VkMemoryAllocateFlagsInfo. 729 If this is ename:VK_FALSE, then all device memory allocations are made 730 across all physical devices in the group. 731 If pname:physicalDeviceCount is `1`, then pname:subsetAllocation must: 732 be ename:VK_FALSE. 733 734-- 735 736endif::VK_VERSION_1_1,VK_KHR_device_group_creation[] 737 738 739[[devsandqueues-device-creation]] 740=== Device Creation 741 742[open,refpage='VkDevice',desc='Opaque handle to a device object',type='handles'] 743-- 744 745Logical devices are represented by sname:VkDevice handles: 746 747include::../api/handles/VkDevice.txt[] 748 749-- 750 751[open,refpage='vkCreateDevice',desc='Create a new device instance',type='protos'] 752-- 753 754A logical device is created as a _connection_ to a physical device. 755To create a logical device, call: 756 757include::../api/protos/vkCreateDevice.txt[] 758 759 * pname:physicalDevice must: be one of the device handles returned from a 760 call to fname:vkEnumeratePhysicalDevices (see 761 <<devsandqueues-physical-device-enumeration, Physical Device 762 Enumeration>>). 763 * pname:pCreateInfo is a pointer to a slink:VkDeviceCreateInfo structure 764 containing information about how to create the device. 765 * pname:pAllocator controls host memory allocation as described in the 766 <<memory-allocation, Memory Allocation>> chapter. 767 * pname:pDevice points to a handle in which the created slink:VkDevice is 768 returned. 769 770fname:vkCreateDevice verifies that extensions and features requested in the 771pname:ppEnabledExtensionNames and pname:pEnabledFeatures members of 772pname:pCreateInfo, respectively, are supported by the implementation. 773If any requested extension is not supported, fname:vkCreateDevice must: 774return ename:VK_ERROR_EXTENSION_NOT_PRESENT. 775If any requested feature is not supported, fname:vkCreateDevice must: return 776ename:VK_ERROR_FEATURE_NOT_PRESENT. 777Support for extensions can: be checked before creating a device by querying 778flink:vkEnumerateDeviceExtensionProperties. 779Support for features can: similarly be checked by querying 780flink:vkGetPhysicalDeviceFeatures. 781 782After verifying and enabling the extensions the sname:VkDevice object is 783created and returned to the application. 784If a requested extension is only supported by a layer, both the layer and 785the extension need to be specified at fname:vkCreateInstance time for the 786creation to succeed. 787 788Multiple logical devices can: be created from the same physical device. 789Logical device creation may: fail due to lack of device-specific resources 790(in addition to the other errors). 791If that occurs, fname:vkCreateDevice will return 792ename:VK_ERROR_TOO_MANY_OBJECTS. 793 794.Valid Usage 795**** 796 * [[VUID-vkCreateDevice-ppEnabledExtensionNames-01387]] 797 All <<extended-functionality-extensions-dependencies, required 798 extensions>> for each extension in the 799 slink:VkDeviceCreateInfo::pname:ppEnabledExtensionNames list must: also 800 be present in that list. 801**** 802 803include::../validity/protos/vkCreateDevice.txt[] 804-- 805 806[open,refpage='VkDeviceCreateInfo',desc='Structure specifying parameters of a newly created device',type='structs'] 807-- 808 809The sname:VkDeviceCreateInfo structure is defined as: 810 811include::../api/structs/VkDeviceCreateInfo.txt[] 812 813 * pname:sType is the type of this structure. 814 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 815 * pname:flags is reserved for future use. 816 * pname:queueCreateInfoCount is the unsigned integer size of the 817 pname:pQueueCreateInfos array. 818 Refer to the <<devsandqueues-queue-creation,Queue Creation>> section 819 below for further details. 820 * pname:pQueueCreateInfos is a pointer to an array of 821 slink:VkDeviceQueueCreateInfo structures describing the queues that are 822 requested to be created along with the logical device. 823 Refer to the <<devsandqueues-queue-creation,Queue Creation>> section 824 below for further details. 825 * pname:enabledLayerCount is deprecated and ignored. 826 * pname:ppEnabledLayerNames is deprecated and ignored. 827 See <<extended-functionality-device-layer-deprecation,Device Layer 828 Deprecation>>. 829 * pname:enabledExtensionCount is the number of device extensions to 830 enable. 831 * pname:ppEnabledExtensionNames is a pointer to an array of 832 pname:enabledExtensionCount null-terminated UTF-8 strings containing the 833 names of extensions to enable for the created device. 834 See the <<extended-functionality-extensions,Extensions>> section for 835 further details. 836 * pname:pEnabledFeatures is `NULL` or a pointer to a 837 slink:VkPhysicalDeviceFeatures structure that contains boolean 838 indicators of all the features to be enabled. 839 Refer to the <<features-features,Features>> section for further details. 840 841.Valid Usage 842**** 843 * [[VUID-VkDeviceCreateInfo-queueFamilyIndex-00372]] 844ifndef::VK_VERSION_1_1[] 845 The pname:queueFamilyIndex member of each element of 846 pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos 847endif::VK_VERSION_1_1[] 848ifdef::VK_VERSION_1_1[] 849 The pname:queueFamilyIndex member of each element of 850 pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos, 851 except that two members can share the same pname:queueFamilyIndex if one 852 is a protected-capable queue and one is not a protected-capable queue. 853endif::VK_VERSION_1_1[] 854ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 855 * [[VUID-VkDeviceCreateInfo-pNext-00373]] 856 If the pname:pNext chain includes a slink:VkPhysicalDeviceFeatures2 857 structure, then pname:pEnabledFeatures must: be `NULL` 858endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 859ifdef::VK_AMD_negative_viewport_height[] 860ifdef::VK_VERSION_1_1[] 861 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-01840]] 862 pname:ppEnabledExtensionNames must: not contain 863 code:VK_AMD_negative_viewport_height 864endif::VK_VERSION_1_1[] 865ifndef::VK_VERSION_1_1[] 866ifdef::VK_KHR_maintenance1[] 867 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-00374]] 868 pname:ppEnabledExtensionNames must: not contain both 869 `<<VK_KHR_maintenance1>>` and `<<VK_AMD_negative_viewport_height>>` 870endif::VK_KHR_maintenance1[] 871endif::VK_VERSION_1_1[] 872endif::VK_AMD_negative_viewport_height[] 873**** 874 875include::../validity/structs/VkDeviceCreateInfo.txt[] 876-- 877 878[open,refpage='VkDeviceCreateFlags',desc='Reserved for future use',type='enums'] 879-- 880include::../api/flags/VkDeviceCreateFlags.txt[] 881 882sname:VkDeviceCreateFlags is a bitmask type for setting a mask, but is 883currently reserved for future use. 884-- 885 886ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[] 887 888[open,refpage='VkDeviceGroupDeviceCreateInfo',desc='Create a logical device from multiple physical devices',type='structs'] 889-- 890 891A logical device can: be created that connects to one or more physical 892devices by including a sname:VkDeviceGroupDeviceCreateInfo structure in the 893pname:pNext chain of slink:VkDeviceCreateInfo. 894The sname:VkDeviceGroupDeviceCreateInfo structure is defined as: 895 896include::../api/structs/VkDeviceGroupDeviceCreateInfo.txt[] 897 898ifdef::VK_KHR_device_group_creation[] 899or the equivalent 900 901include::../api/structs/VkDeviceGroupDeviceCreateInfoKHR.txt[] 902endif::VK_KHR_device_group_creation[] 903 904 * pname:sType is the type of this structure. 905 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 906 * pname:physicalDeviceCount is the number of elements in the 907 pname:pPhysicalDevices array. 908 * pname:pPhysicalDevices is an array of physical device handles belonging 909 to the same device group. 910 911The elements of the pname:pPhysicalDevices array are an ordered list of the 912physical devices that the logical device represents. 913These must: be a subset of a single device group, and need not be in the 914same order as they were enumerated. 915The order of the physical devices in the pname:pPhysicalDevices array 916determines the _device index_ of each physical device, with element [eq]#i# 917being assigned a device index of [eq]#i#. 918Certain commands and structures refer to one or more physical devices by 919using device indices or _device masks_ formed using device indices. 920 921A logical device created without using sname:VkDeviceGroupDeviceCreateInfo, 922or with pname:physicalDeviceCount equal to zero, is equivalent to a 923pname:physicalDeviceCount of one and pname:pPhysicalDevices pointing to the 924pname:physicalDevice parameter to flink:vkCreateDevice. 925In particular, the device index of that physical device is zero. 926 927.Valid Usage 928**** 929 * [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00375]] 930 Each element of pname:pPhysicalDevices must: be unique 931 * [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00376]] 932 All elements of pname:pPhysicalDevices must: be in the same device group 933 as enumerated by flink:vkEnumeratePhysicalDeviceGroups 934 * [[VUID-VkDeviceGroupDeviceCreateInfo-physicalDeviceCount-00377]] 935 If pname:physicalDeviceCount is not `0`, the pname:physicalDevice 936 parameter of flink:vkCreateDevice must: be an element of 937 pname:pPhysicalDevices. 938**** 939 940include::../validity/structs/VkDeviceGroupDeviceCreateInfo.txt[] 941 942-- 943 944endif::VK_VERSION_1_1,VK_KHR_device_group_creation[] 945 946 947[[devsandqueues-use]] 948=== Device Use 949 950The following is a high-level list of sname:VkDevice uses along with 951references on where to find more information: 952 953 * Creation of queues. 954 See the <<devsandqueues-queues,Queues>> section below for further 955 details. 956 * Creation and tracking of various synchronization constructs. 957 See <<synchronization,Synchronization and Cache Control>> for further 958 details. 959 * Allocating, freeing, and managing memory. 960 See <<memory,Memory Allocation>> and <<resources,Resource Creation>> for 961 further details. 962 * Creation and destruction of command buffers and command buffer pools. 963 See <<commandbuffers,Command Buffers>> for further details. 964 * Creation, destruction, and management of graphics state. 965 See <<pipelines,Pipelines>> and <<descriptorsets,Resource Descriptors>>, 966 among others, for further details. 967 968 969[[devsandqueues-lost-device]] 970=== Lost Device 971 972A logical device may: become _lost_ for a number of implementation-specific 973reasons, indicating that pending and future command execution may: fail and 974cause resources and backing memory to become undefined. 975 976[NOTE] 977.Note 978==== 979Typical reasons for device loss will include things like execution timing 980out (to prevent denial of service), power management events, platform 981resource management, or implementation errors. 982==== 983 984When this happens, certain commands will return ename:VK_ERROR_DEVICE_LOST 985(see <<fundamentals-errorcodes,Error Codes>> for a list of such commands). 986After any such event, the logical device is considered _lost_. 987It is not possible to reset the logical device to a non-lost state, however 988the lost state is specific to a logical device (sname:VkDevice), and the 989corresponding physical device (sname:VkPhysicalDevice) may: be otherwise 990unaffected. 991 992In some cases, the physical device may: also be lost, and attempting to 993create a new logical device will fail, returning ename:VK_ERROR_DEVICE_LOST. 994This is usually indicative of a problem with the underlying implementation, 995or its connection to the host. 996If the physical device has not been lost, and a new logical device is 997successfully created from that physical device, it must: be in the non-lost 998state. 999 1000[NOTE] 1001.Note 1002==== 1003Whilst logical device loss may: be recoverable, in the case of physical 1004device loss, it is unlikely that an application will be able to recover 1005unless additional, unaffected physical devices exist on the system. 1006The error is largely informational and intended only to inform the user that 1007a platform issue has occurred, and should: be investigated further. 1008For example, underlying hardware may: have developed a fault or become 1009physically disconnected from the rest of the system. 1010In many cases, physical device loss may: cause other more serious issues 1011such as the operating system crashing; in which case it may: not be reported 1012via the Vulkan API. 1013==== 1014 1015[NOTE] 1016.Note 1017==== 1018Undefined behavior caused by an application error may: cause a device to 1019become lost. 1020However, such undefined behavior may: also cause unrecoverable damage to the 1021process, and it is then not guaranteed that the API objects, including the 1022sname:VkPhysicalDevice or the sname:VkInstance are still valid or that the 1023error is recoverable. 1024==== 1025 1026When a device is lost, its child objects are not implicitly destroyed and 1027their handles are still valid. 1028Those objects must: still be destroyed before their parents or the device 1029can: be destroyed (see the <<fundamentals-objectmodel-lifetime,Object 1030Lifetime>> section). 1031The host address space corresponding to device memory mapped using 1032flink:vkMapMemory is still valid, and host memory accesses to these mapped 1033regions are still valid, but the contents are undefined. 1034It is still legal to call any API command on the device and child objects. 1035 1036Once a device is lost, command execution may: fail, and commands that return 1037a elink:VkResult may: return ename:VK_ERROR_DEVICE_LOST. 1038Commands that do not allow run-time errors must: still operate correctly for 1039valid usage and, if applicable, return valid data. 1040 1041Commands that wait indefinitely for device execution (namely 1042flink:vkDeviceWaitIdle, flink:vkQueueWaitIdle, flink:vkWaitForFences 1043ifdef::VK_KHR_swapchain[] 1044or flink:vkAcquireNextImageKHR 1045endif::VK_KHR_swapchain[] 1046with a maximum pname:timeout, and flink:vkGetQueryPoolResults with the 1047ename:VK_QUERY_RESULT_WAIT_BIT bit set in pname:flags) must: return in 1048finite time even in the case of a lost device, and return either 1049ename:VK_SUCCESS or ename:VK_ERROR_DEVICE_LOST. 1050For any command that may: return ename:VK_ERROR_DEVICE_LOST, for the purpose 1051of determining whether a command buffer is in the 1052<<commandbuffers-lifecycle, pending state>>, or whether resources are 1053considered in-use by the device, a return value of 1054ename:VK_ERROR_DEVICE_LOST is equivalent to ename:VK_SUCCESS. 1055 1056ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 1057 1058The content of any external memory objects that have been exported from or 1059imported to a lost device become undefined. 1060Objects on other logical devices or in other APIs which are associated with 1061the same underlying memory resource as the external memory objects on the 1062lost device are unaffected other than their content becoming undefined. 1063The layout of subresources of images on other logical devices that are bound 1064to sname:VkDeviceMemory objects associated with the same underlying memory 1065resources as external memory objects on the lost device becomes 1066ename:VK_IMAGE_LAYOUT_UNDEFINED. 1067 1068endif::VK_VERSION_1_1,VK_KHR_external_memory[] 1069 1070ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[] 1071 1072The state of sname:VkSemaphore objects on other logical devices created by 1073<<synchronization-semaphores-importing,importing a semaphore payload>> with 1074temporary permanence which was exported from the lost device is undefined. 1075The state of sname:VkSemaphore objects on other logical devices that 1076permanently share a semaphore payload with a sname:VkSemaphore object on the 1077lost device is undefined, and remains undefined following any subsequent 1078signal operations. 1079Implementations must: ensure pending and subsequently submitted wait 1080operations on such semaphores behave as defined in 1081<<synchronization-semaphores-waiting-state,Semaphore State Requirements For 1082Wait Operations>> for external semaphores not in a valid state for a wait 1083operation. 1084 1085endif::VK_VERSION_1_1,VK_KHR_external_semaphore[] 1086 1087ifdef::editing-notes[] 1088[NOTE] 1089.editing-note 1090==== 1091TODO (piman) - I do not think we are very clear about what "`in-use by the 1092device`" means. 1093==== 1094endif::editing-notes[] 1095 1096 1097[[devsandqueues-destruction]] 1098=== Device Destruction 1099 1100[open,refpage='vkDestroyDevice',desc='Destroy a logical device',type='protos'] 1101-- 1102 1103To destroy a device, call: 1104 1105include::../api/protos/vkDestroyDevice.txt[] 1106 1107 * pname:device is the logical device to destroy. 1108 * pname:pAllocator controls host memory allocation as described in the 1109 <<memory-allocation, Memory Allocation>> chapter. 1110 1111To ensure that no work is active on the device, flink:vkDeviceWaitIdle can: 1112be used to gate the destruction of the device. 1113Prior to destroying a device, an application is responsible for 1114destroying/freeing any Vulkan objects that were created using that device as 1115the first parameter of the corresponding ftext:vkCreate* or 1116ftext:vkAllocate* command. 1117 1118[NOTE] 1119.Note 1120==== 1121The lifetime of each of these objects is bound by the lifetime of the 1122sname:VkDevice object. 1123Therefore, to avoid resource leaks, it is critical that an application 1124explicitly free all of these resources prior to calling 1125fname:vkDestroyDevice. 1126==== 1127 1128.Valid Usage 1129**** 1130 * [[VUID-vkDestroyDevice-device-00378]] 1131 All child objects created on pname:device must: have been destroyed 1132 prior to destroying pname:device 1133 * [[VUID-vkDestroyDevice-device-00379]] 1134 If sname:VkAllocationCallbacks were provided when pname:device was 1135 created, a compatible set of callbacks must: be provided here 1136 * [[VUID-vkDestroyDevice-device-00380]] 1137 If no sname:VkAllocationCallbacks were provided when pname:device was 1138 created, pname:pAllocator must: be `NULL` 1139**** 1140 1141include::../validity/protos/vkDestroyDevice.txt[] 1142-- 1143 1144 1145[[devsandqueues-queues]] 1146== Queues 1147 1148 1149[[devsandqueues-queueprops]] 1150=== Queue Family Properties 1151 1152As discussed in the <<devsandqueues-physical-device-enumeration,Physical 1153Device Enumeration>> section above, the 1154flink:vkGetPhysicalDeviceQueueFamilyProperties command is used to retrieve 1155details about the queue families and queues supported by a device. 1156 1157Each index in the pname:pQueueFamilyProperties array returned by 1158flink:vkGetPhysicalDeviceQueueFamilyProperties describes a unique queue 1159family on that physical device. 1160These indices are used when creating queues, and they correspond directly 1161with the pname:queueFamilyIndex that is passed to the flink:vkCreateDevice 1162command via the slink:VkDeviceQueueCreateInfo structure as described in the 1163<<devsandqueues-queue-creation,Queue Creation>> section below. 1164 1165Grouping of queue families within a physical device is 1166implementation-dependent. 1167 1168[NOTE] 1169.Note 1170==== 1171The general expectation is that a physical device groups all queues of 1172matching capabilities into a single family. 1173However, while implementations should: do this, it is possible that a 1174physical device may: return two separate queue families with the same 1175capabilities. 1176==== 1177 1178Once an application has identified a physical device with the queue(s) that 1179it desires to use, it will create those queues in conjunction with a logical 1180device. 1181This is described in the following section. 1182 1183 1184[[devsandqueues-queue-creation]] 1185=== Queue Creation 1186 1187[open,refpage='VkQueue',desc='Opaque handle to a queue object',type='handles'] 1188-- 1189 1190Creating a logical device also creates the queues associated with that 1191device. 1192The queues to create are described by a set of slink:VkDeviceQueueCreateInfo 1193structures that are passed to flink:vkCreateDevice in 1194pname:pQueueCreateInfos. 1195 1196Queues are represented by sname:VkQueue handles: 1197 1198include::../api/handles/VkQueue.txt[] 1199 1200-- 1201 1202[open,refpage='VkDeviceQueueCreateInfo',desc='Structure specifying parameters of a newly created device queue',type='structs'] 1203-- 1204 1205The sname:VkDeviceQueueCreateInfo structure is defined as: 1206 1207include::../api/structs/VkDeviceQueueCreateInfo.txt[] 1208 1209 * pname:sType is the type of this structure. 1210 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1211ifndef::VK_VERSION_1_1[] 1212 * pname:flags is reserved for future use. 1213endif::VK_VERSION_1_1[] 1214ifdef::VK_VERSION_1_1[] 1215 * pname:flags is a bitmask indicating behavior of the queue. 1216endif::VK_VERSION_1_1[] 1217 * pname:queueFamilyIndex is an unsigned integer indicating the index of 1218 the queue family to create on this device. 1219 This index corresponds to the index of an element of the 1220 pname:pQueueFamilyProperties array that was returned by 1221 fname:vkGetPhysicalDeviceQueueFamilyProperties. 1222 * pname:queueCount is an unsigned integer specifying the number of queues 1223 to create in the queue family indicated by pname:queueFamilyIndex. 1224 * pname:pQueuePriorities is an array of pname:queueCount normalized 1225 floating point values, specifying priorities of work that will be 1226 submitted to each created queue. 1227 See <<devsandqueues-priority,Queue Priority>> for more information. 1228 1229.Valid Usage 1230**** 1231 * [[VUID-VkDeviceQueueCreateInfo-queueFamilyIndex-00381]] 1232 pname:queueFamilyIndex must: be less than 1233 pname:pQueueFamilyPropertyCount returned by 1234 fname:vkGetPhysicalDeviceQueueFamilyProperties 1235 * [[VUID-VkDeviceQueueCreateInfo-queueCount-00382]] 1236 pname:queueCount must: be less than or equal to the pname:queueCount 1237 member of the sname:VkQueueFamilyProperties structure, as returned by 1238 fname:vkGetPhysicalDeviceQueueFamilyProperties in the 1239 pname:pQueueFamilyProperties[pname:queueFamilyIndex] 1240 * [[VUID-VkDeviceQueueCreateInfo-pQueuePriorities-00383]] 1241 Each element of pname:pQueuePriorities must: be between `0.0` and `1.0` 1242 inclusive 1243**** 1244 1245include::../validity/structs/VkDeviceQueueCreateInfo.txt[] 1246-- 1247 1248ifdef::VK_VERSION_1_1[] 1249 1250[open,refpage='VkDeviceQueueCreateFlagBits',desc='Bitmask specifying behavior of the queue',type='enums'] 1251-- 1252 1253Bits which can: be set in slink:VkDeviceQueueCreateInfo::pname:flags to 1254specify usage behavior of the queue are: 1255 1256include::../api/enums/VkDeviceQueueCreateFlagBits.txt[] 1257 1258 * ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT specifies that the device 1259 queue is a protected-capable queue. 1260 If the protected memory feature is not enabled, the 1261 ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit of pname:flags must: not 1262 be set. 1263 1264-- 1265 1266endif::VK_VERSION_1_1[] 1267 1268[open,refpage='VkDeviceQueueCreateFlags',desc='Bitmask of VkDeviceQueueCreateFlagBits',type='enums'] 1269-- 1270include::../api/flags/VkDeviceQueueCreateFlags.txt[] 1271 1272sname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask of zero 1273or more slink:VkDeviceQueueCreateFlagBits. 1274-- 1275 1276ifdef::VK_EXT_global_priority[] 1277 1278[open,refpage='VkDeviceQueueGlobalPriorityCreateInfoEXT',desc='Specify a system wide priority',type='structs'] 1279-- 1280 1281A queue can: be created with a system-wide priority by including a 1282sname:VkDeviceQueueGlobalPriorityCreateInfoEXT structure in the pname:pNext 1283chain of slink:VkDeviceQueueCreateInfo. 1284 1285The sname:VkDeviceQueueGlobalPriorityCreateInfoEXT structure is defined as: 1286 1287include::../api/structs/VkDeviceQueueGlobalPriorityCreateInfoEXT.txt[] 1288 1289 * pname:sType is the type of this structure. 1290 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1291 * pname:globalPriority is the system-wide priority associated to this 1292 queue as specified by elink:VkQueueGlobalPriorityEXT 1293 1294A queue created without specifying 1295sname:VkDeviceQueueGlobalPriorityCreateInfoEXT will default to 1296ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT. 1297 1298include::../validity/structs/VkDeviceQueueGlobalPriorityCreateInfoEXT.txt[] 1299-- 1300 1301[open,refpage='VkQueueGlobalPriorityEXT',desc='Values specifying a system-wide queue priority',type='enums'] 1302-- 1303 1304Possible values of 1305slink:VkDeviceQueueGlobalPriorityCreateInfoEXT::pname:globalPriority, 1306specifying a system-wide priority level are: 1307 1308include::../api/enums/VkQueueGlobalPriorityEXT.txt[] 1309 1310Priority values are sorted in ascending order. 1311A comparison operation on the enum values can be used to determine the 1312priority order. 1313 1314 * ename:VK_QUEUE_GLOBAL_PRIORITY_LOW_EXT is below the system default. 1315 Useful for non-interactive tasks. 1316 * ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT is the system default 1317 priority. 1318 * ename:VK_QUEUE_GLOBAL_PRIORITY_HIGH_EXT is above the system default. 1319 * ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_EXT is the highest priority. 1320 Useful for critical tasks. 1321-- 1322 1323Queues with higher system priority may: be allotted more processing time 1324than queues with lower priority. 1325An implementation may: allow a higher-priority queue to starve a 1326lower-priority queue until the higher-priority queue has no further commands 1327to execute. 1328 1329Priorities imply no ordering or scheduling constraints. 1330 1331No specific guarantees are made about higher priority queues receiving more 1332processing time or better quality of service than lower priority queues. 1333 1334The global priority level of a queue takes precedence over the per-process 1335queue priority (sname:VkDeviceQueueCreateInfo::pname:pQueuePriorities). 1336 1337Abuse of this feature may: result in starving the rest of the system of 1338implementation resources. 1339Therefore, the driver implementation may: deny requests to acquire a 1340priority above the default priority 1341(ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) if the caller does not have 1342sufficient privileges. 1343In this scenario ename:VK_ERROR_NOT_PERMITTED_EXT is returned. 1344 1345The driver implementation may: fail the queue allocation request if 1346resources required to complete the operation have been exhausted (either by 1347the same process or a different process). 1348In this scenario ename:VK_ERROR_INITIALIZATION_FAILED is returned. 1349 1350endif::VK_EXT_global_priority[] 1351 1352[open,refpage='vkGetDeviceQueue',desc='Get a queue handle from a device',type='protos'] 1353-- 1354 1355To retrieve a handle to a slink:VkQueue object, call: 1356 1357include::../api/protos/vkGetDeviceQueue.txt[] 1358 1359 * pname:device is the logical device that owns the queue. 1360 * pname:queueFamilyIndex is the index of the queue family to which the 1361 queue belongs. 1362 * pname:queueIndex is the index within this queue family of the queue to 1363 retrieve. 1364 * pname:pQueue is a pointer to a slink:VkQueue object that will be filled 1365 with the handle for the requested queue. 1366 1367ifdef::VK_VERSION_1_1[] 1368fname:vkGetDeviceQueue must: only be used to get queues that were created 1369with the pname:flags parameter of sname:VkDeviceQueueCreateInfo set to zero. 1370To get queues that were created with a non-zero pname:flags parameter use 1371flink:vkGetDeviceQueue2. 1372endif::VK_VERSION_1_1[] 1373 1374.Valid Usage 1375**** 1376 * [[VUID-vkGetDeviceQueue-queueFamilyIndex-00384]] 1377 pname:queueFamilyIndex must: be one of the queue family indices 1378 specified when pname:device was created, via the 1379 sname:VkDeviceQueueCreateInfo structure 1380 * [[VUID-vkGetDeviceQueue-queueIndex-00385]] 1381 pname:queueIndex must: be less than the number of queues created for the 1382 specified queue family index when pname:device was created, via the 1383 pname:queueCount member of the sname:VkDeviceQueueCreateInfo structure 1384 * [[VUID-vkGetDeviceQueue-flags-01841]] 1385 slink:VkDeviceQueueCreateInfo::pname:flags must: have been set to zero 1386 when pname:device was created 1387**** 1388 1389include::../validity/protos/vkGetDeviceQueue.txt[] 1390-- 1391 1392ifdef::VK_VERSION_1_1[] 1393 1394[open,refpage='vkGetDeviceQueue2',desc='Get a queue handle from a device',type='protos'] 1395-- 1396 1397To retrieve a handle to a slink:VkQueue object with specific 1398pname:VkDeviceQueueCreateFlags creation flags, call: 1399 1400include::../api/protos/vkGetDeviceQueue2.txt[] 1401 1402 * pname:device is the logical device that owns the queue. 1403 * pname:pQueueInfo points to an instance of the slink:VkDeviceQueueInfo2 1404 structure, describing the parameters used to create the device queue. 1405 * pname:pQueue is a pointer to a slink:VkQueue object that will be filled 1406 with the handle for the requested queue. 1407 1408include::../validity/protos/vkGetDeviceQueue2.txt[] 1409-- 1410 1411[open,refpage='VkDeviceQueueInfo2',desc='Structure specifying the parameters used for device queue creation',type='structs'] 1412-- 1413 1414The sname:VkDeviceQueueInfo2 structure is defined as: 1415 1416include::../api/structs/VkDeviceQueueInfo2.txt[] 1417 1418 * pname:sType is the type of this structure. 1419 * pname:pNext is `NULL` or a pointer to an extension-specific structure. 1420 The pname:pNext chain of sname:VkDeviceQueueInfo2 is used to provide 1421 additional image parameters to fname:vkGetDeviceQueue2. 1422 * pname:flags is a elink:VkDeviceQueueCreateFlags value indicating the 1423 flags used to create the device queue. 1424 * pname:queueFamilyIndex is the index of the queue family to which the 1425 queue belongs. 1426 * pname:queueIndex is the index within this queue family of the queue to 1427 retrieve. 1428 1429The queue returned by fname:vkGetDeviceQueue2 must: have the same 1430pname:flags value from this structure as that used at device creation time 1431in a sname:VkDeviceQueueCreateInfo instance. 1432If no matching pname:flags were specified at device creation time then 1433pname:pQueue will return code:VK_NULL_HANDLE. 1434 1435.Valid Usage 1436**** 1437 * [[VUID-VkDeviceQueueInfo2-queueFamilyIndex-01842]] 1438 pname:queueFamilyIndex must: be one of the queue family indices 1439 specified when pname:device was created, via the 1440 sname:VkDeviceQueueCreateInfo structure 1441 * [[VUID-VkDeviceQueueInfo2-queueIndex-01843]] 1442 pname:queueIndex must: be less than the number of queues created for the 1443 specified queue family index and sname:VkDeviceQueueCreateFlags member 1444 pname:flags equal to this pname:flags value when pname:device was 1445 created, via the pname:queueCount member of the 1446 sname:VkDeviceQueueCreateInfo structure 1447**** 1448 1449include::../validity/structs/VkDeviceQueueInfo2.txt[] 1450-- 1451 1452endif::VK_VERSION_1_1[] 1453 1454 1455[[devsandqueues-index]] 1456=== Queue Family Index 1457 1458The queue family index is used in multiple places in Vulkan in order to tie 1459operations to a specific family of queues. 1460 1461When retrieving a handle to the queue via fname:vkGetDeviceQueue, the queue 1462family index is used to select which queue family to retrieve the 1463sname:VkQueue handle from as described in the previous section. 1464 1465When creating a sname:VkCommandPool object (see 1466<<commandbuffers-pools,Command Pools>>), a queue family index is specified 1467in the slink:VkCommandPoolCreateInfo structure. 1468Command buffers from this pool can: only be submitted on queues 1469corresponding to this queue family. 1470 1471When creating sname:VkImage (see <<resources-images,Images>>) and 1472sname:VkBuffer (see <<resources-buffers,Buffers>>) resources, a set of queue 1473families is included in the slink:VkImageCreateInfo and 1474slink:VkBufferCreateInfo structures to specify the queue families that can: 1475access the resource. 1476 1477When inserting a slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier 1478(see <<synchronization-events>>) a source and destination queue family index 1479is specified to allow the ownership of a buffer or image to be transferred 1480from one queue family to another. 1481See the <<resources-sharing,Resource Sharing>> section for details. 1482 1483 1484[[devsandqueues-priority]] 1485=== Queue Priority 1486 1487Each queue is assigned a priority, as set in the 1488slink:VkDeviceQueueCreateInfo structures when creating the device. 1489The priority of each queue is a normalized floating point value between 0.0 1490and 1.0, which is then translated to a discrete priority level by the 1491implementation. 1492Higher values indicate a higher priority, with 0.0 being the lowest priority 1493and 1.0 being the highest. 1494 1495Within the same device, queues with higher priority may: be allotted more 1496processing time than queues with lower priority. 1497The implementation makes no guarantees with regards to ordering or 1498scheduling among queues with the same priority, other than the constraints 1499defined by any <<synchronization, explicit synchronization primitives>>. 1500The implementation make no guarantees with regards to queues across 1501different devices. 1502 1503An implementation may: allow a higher-priority queue to starve a 1504lower-priority queue on the same sname:VkDevice until the higher-priority 1505queue has no further commands to execute. 1506The relationship of queue priorities must: not cause queues on one 1507sname:VkDevice to starve queues on another sname:VkDevice. 1508 1509No specific guarantees are made about higher priority queues receiving more 1510processing time or better quality of service than lower priority queues. 1511 1512 1513[[devsandqueues-submission]] 1514=== Queue Submission 1515 1516Work is submitted to a queue via _queue submission_ commands such as 1517flink:vkQueueSubmit. 1518Queue submission commands define a set of _queue operations_ to be executed 1519by the underlying physical device, including synchronization with semaphores 1520and fences. 1521 1522Submission commands take as parameters a target queue, zero or more 1523_batches_ of work, and an optional: fence to signal upon completion. 1524Each batch consists of three distinct parts: 1525 1526 . Zero or more semaphores to wait on before execution of the rest of the 1527 batch. 1528 ** If present, these describe a <<synchronization-semaphores-waiting, 1529 semaphore wait operation>>. 1530 . Zero or more work items to execute. 1531 ** If present, these describe a _queue operation_ matching the work 1532 described. 1533 . Zero or more semaphores to signal upon completion of the work items. 1534 ** If present, these describe a <<synchronization-semaphores-signaling, 1535 semaphore signal operation>>. 1536 1537If a fence is present in a queue submission, it describes a 1538<<synchronization-fences-signaling, fence signal operation>>. 1539 1540All work described by a queue submission command must: be submitted to the 1541queue before the command returns. 1542 1543 1544[[devsandqueues-sparsebinding]] 1545==== Sparse Memory Binding 1546 1547In Vulkan it is possible to sparsely bind memory to buffers and images as 1548described in the <<sparsememory,Sparse Resource>> chapter. 1549Sparse memory binding is a queue operation. 1550A queue whose flags include the ename:VK_QUEUE_SPARSE_BINDING_BIT must: be 1551able to support the mapping of a virtual address to a physical address on 1552the device. 1553This causes an update to the page table mappings on the device. 1554This update must: be synchronized on a queue to avoid corrupting page table 1555mappings during execution of graphics commands. 1556By binding the sparse memory resources on queues, all commands that are 1557dependent on the updated bindings are synchronized to only execute after the 1558binding is updated. 1559See the <<synchronization,Synchronization and Cache Control>> chapter for 1560how this synchronization is accomplished. 1561 1562 1563[[devsandqueues-queuedestruction]] 1564=== Queue Destruction 1565 1566Queues are created along with a logical device during fname:vkCreateDevice. 1567All queues associated with a logical device are destroyed when 1568fname:vkDestroyDevice is called on that device. 1569