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