1// Copyright 2015-2021 The Khronos Group, Inc. 2// 3// SPDX-License-Identifier: CC-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-- 13Vulkan separates the concept of _physical_ and _logical_ devices. 14A physical device usually represents a single complete implementation of 15Vulkan (excluding instance-level functionality) available to the host, of 16which there are a finite number. 17A logical device represents an instance of that implementation with its own 18state and resources independent of other logical devices. 19 20Physical devices are represented by sname:VkPhysicalDevice handles: 21 22include::{generated}/api/handles/VkPhysicalDevice.txt[] 23-- 24 25 26[[devsandqueues-physical-device-enumeration]] 27== Physical Devices 28 29[open,refpage='vkEnumeratePhysicalDevices',desc='Enumerates the physical devices accessible to a Vulkan instance',type='protos'] 30-- 31To retrieve a list of physical device objects representing the physical 32devices installed in the system, call: 33 34include::{generated}/api/protos/vkEnumeratePhysicalDevices.txt[] 35 36 * pname:instance is a handle to a Vulkan instance previously created with 37 flink:vkCreateInstance. 38 * pname:pPhysicalDeviceCount is a pointer to an integer related to the 39 number of physical devices available or queried, as described below. 40 * pname:pPhysicalDevices is either `NULL` or a pointer to an array of 41 sname:VkPhysicalDevice handles. 42 43If pname:pPhysicalDevices is `NULL`, then the number of physical devices 44available is returned in pname:pPhysicalDeviceCount. 45Otherwise, pname:pPhysicalDeviceCount must: point to a variable set by the 46user to the number of elements in the pname:pPhysicalDevices array, and on 47return the variable is overwritten with the number of handles actually 48written to pname:pPhysicalDevices. 49If pname:pPhysicalDeviceCount is less than the number of physical devices 50available, at most pname:pPhysicalDeviceCount structures will be written, 51and ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to 52indicate that not all the available physical devices were returned. 53 54include::{generated}/validity/protos/vkEnumeratePhysicalDevices.txt[] 55-- 56 57[open,refpage='vkGetPhysicalDeviceProperties',desc='Returns properties of a physical device',type='protos'] 58-- 59To query general properties of physical devices once enumerated, call: 60 61include::{generated}/api/protos/vkGetPhysicalDeviceProperties.txt[] 62 63 * pname:physicalDevice is the handle to the physical device whose 64 properties will be queried. 65 * pname:pProperties is a pointer to a slink:VkPhysicalDeviceProperties 66 structure in which properties are returned. 67 68include::{generated}/validity/protos/vkGetPhysicalDeviceProperties.txt[] 69-- 70 71[open,refpage='VkPhysicalDeviceProperties',desc='Structure specifying physical device properties',type='structs'] 72-- 73The sname:VkPhysicalDeviceProperties structure is defined as: 74 75include::{generated}/api/structs/VkPhysicalDeviceProperties.txt[] 76 77 * pname:apiVersion is the version of Vulkan supported by the device, 78 encoded as described in <<extendingvulkan-coreversions-versionnumbers>>. 79 * pname:driverVersion is the vendor-specified version of the driver. 80 * pname:vendorID is a unique identifier for the _vendor_ (see below) of 81 the physical device. 82 * pname:deviceID is a unique identifier for the physical device among 83 devices available from the vendor. 84 * pname:deviceType is a elink:VkPhysicalDeviceType specifying the type of 85 device. 86 * pname:deviceName is an array of ename:VK_MAX_PHYSICAL_DEVICE_NAME_SIZE 87 code:char containing a null-terminated UTF-8 string which is the name of 88 the device. 89 * pname:pipelineCacheUUID is an array of ename:VK_UUID_SIZE code:uint8_t 90 values representing a universally unique identifier for the device. 91 * pname:limits is the slink:VkPhysicalDeviceLimits structure specifying 92 device-specific limits of the physical device. 93 See <<limits,Limits>> for details. 94 * pname:sparseProperties is the slink:VkPhysicalDeviceSparseProperties 95 structure specifying various sparse related properties of the physical 96 device. 97 See <<sparsememory-physicalprops,Sparse Properties>> for details. 98 99ifdef::VK_VERSION_1_1[] 100[NOTE] 101.Note 102==== 103The value of pname:apiVersion may: be different than the version returned by 104flink:vkEnumerateInstanceVersion; either higher or lower. 105In such cases, the application must: not use functionality that exceeds the 106version of Vulkan associated with a given object. 107The pname:pApiVersion parameter returned by flink:vkEnumerateInstanceVersion 108is the version associated with a slink:VkInstance and its children, except 109for a slink:VkPhysicalDevice and its children. 110sname:VkPhysicalDeviceProperties::pname:apiVersion is the version associated 111with a slink:VkPhysicalDevice and its children. 112==== 113endif::VK_VERSION_1_1[] 114 115[NOTE] 116.Note 117==== 118The encoding of pname:driverVersion is implementation-defined. 119It may: not use the same encoding as pname:apiVersion. 120Applications should follow information from the _vendor_ on how to extract 121the version information from pname:driverVersion. 122==== 123 124The pname:vendorID and pname:deviceID fields are provided to allow 125applications to adapt to device characteristics that are not adequately 126exposed by other Vulkan queries. 127 128[NOTE] 129.Note 130==== 131These may: include performance profiles, hardware errata, or other 132characteristics. 133==== 134 135The _vendor_ identified by pname:vendorID is the entity responsible for the 136most salient characteristics of the underlying implementation of the 137slink:VkPhysicalDevice being queried. 138 139[NOTE] 140.Note 141==== 142For example, in the case of a discrete GPU implementation, this should: be 143the GPU chipset vendor. 144In the case of a hardware accelerator integrated into a system-on-chip 145(SoC), this should: be the supplier of the silicon IP used to create the 146accelerator. 147==== 148 149If the vendor has a https://pcisig.com/membership/member-companies[PCI 150vendor ID], the low 16 bits of pname:vendorID must: contain that PCI vendor 151ID, and the remaining bits must: be set to zero. 152Otherwise, the value returned must: be a valid Khronos vendor ID, obtained 153as described in the <<vulkan-styleguide,Vulkan Documentation and Extensions: 154Procedures and Conventions>> document in the section "`Registering a Vendor 155ID with Khronos`". 156Khronos vendor IDs are allocated starting at 0x10000, to distinguish them 157from the PCI vendor ID namespace. 158Khronos vendor IDs are symbolically defined in the elink:VkVendorId type. 159 160The vendor is also responsible for the value returned in pname:deviceID. 161If the implementation is driven primarily by a https://pcisig.com/[PCI 162device] with a https://pcisig.com/[PCI device ID], the low 16 bits of 163pname:deviceID must: contain that PCI device ID, and the remaining bits 164must: be set to zero. 165Otherwise, the choice of what values to return may: be dictated by operating 166system or platform policies - but should: uniquely identify both the device 167version and any major configuration options (for example, core count in the 168case of multicore devices). 169 170[NOTE] 171.Note 172==== 173The same device ID should: be used for all physical implementations of that 174device version and configuration. 175For example, all uses of a specific silicon IP GPU version and configuration 176should: use the same device ID, even if those uses occur in different SoCs. 177==== 178 179include::{generated}/validity/structs/VkPhysicalDeviceProperties.txt[] 180-- 181 182[open,refpage='VkVendorId',desc='Khronos vendor IDs',type='enums'] 183-- 184Khronos vendor IDs which may: be returned in 185slink:VkPhysicalDeviceProperties::pname:vendorID are: 186 187include::{generated}/api/enums/VkVendorId.txt[] 188 189[NOTE] 190.Note 191==== 192Khronos vendor IDs may be allocated by vendors at any time. 193Only the latest canonical versions of this Specification, of the 194corresponding `vk.xml` API Registry, and of the corresponding 195`{core_header}` header file must: contain all reserved Khronos vendor IDs. 196 197Only Khronos vendor IDs are given symbolic names at present. 198PCI vendor IDs returned by the implementation can be looked up in the 199PCI-SIG database. 200==== 201-- 202 203[open,refpage='VK_MAX_PHYSICAL_DEVICE_NAME_SIZE',desc='Length of a physical device name string',type='consts'] 204-- 205ename:VK_MAX_PHYSICAL_DEVICE_NAME_SIZE is the length in code:char values of 206an array containing a physical device name string, as returned in 207slink:VkPhysicalDeviceProperties::deviceName. 208 209include::{generated}/api/enums/VK_MAX_PHYSICAL_DEVICE_NAME_SIZE.txt[] 210-- 211 212[open,refpage='VkPhysicalDeviceType',desc='Supported physical device types',type='enums'] 213-- 214The physical device types which may: be returned in 215slink:VkPhysicalDeviceProperties::pname:deviceType are: 216 217include::{generated}/api/enums/VkPhysicalDeviceType.txt[] 218 219 * ename:VK_PHYSICAL_DEVICE_TYPE_OTHER - the device does not match any 220 other available types. 221 * ename:VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU - the device is typically 222 one embedded in or tightly coupled with the host. 223 * ename:VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU - the device is typically a 224 separate processor connected to the host via an interlink. 225 * ename:VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU - the device is typically a 226 virtual node in a virtualization environment. 227 * ename:VK_PHYSICAL_DEVICE_TYPE_CPU - the device is typically running on 228 the same processors as the host. 229 230The physical device type is advertised for informational purposes only, and 231does not directly affect the operation of the system. 232However, the device type may: correlate with other advertised properties or 233capabilities of the system, such as how many memory heaps there are. 234-- 235 236ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 237[open,refpage='vkGetPhysicalDeviceProperties2',desc='Returns properties of a physical device',type='protos'] 238-- 239To query general properties of physical devices once enumerated, call: 240 241ifdef::VK_VERSION_1_1[] 242include::{generated}/api/protos/vkGetPhysicalDeviceProperties2.txt[] 243endif::VK_VERSION_1_1[] 244 245ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] 246 247ifdef::VK_KHR_get_physical_device_properties2[] 248include::{generated}/api/protos/vkGetPhysicalDeviceProperties2KHR.txt[] 249endif::VK_KHR_get_physical_device_properties2[] 250 251 * pname:physicalDevice is the handle to the physical device whose 252 properties will be queried. 253 * pname:pProperties is a pointer to a slink:VkPhysicalDeviceProperties2 254 structure in which properties are returned. 255 256Each structure in pname:pProperties and its pname:pNext chain contains 257members corresponding to implementation-dependent properties, behaviors, or 258limits. 259fname:vkGetPhysicalDeviceProperties2 fills in each member to specify the 260corresponding value for the implementation. 261 262include::{generated}/validity/protos/vkGetPhysicalDeviceProperties2.txt[] 263-- 264 265[open,refpage='VkPhysicalDeviceProperties2',desc='Structure specifying physical device properties',type='structs'] 266-- 267The sname:VkPhysicalDeviceProperties2 structure is defined as: 268 269include::{generated}/api/structs/VkPhysicalDeviceProperties2.txt[] 270 271ifdef::VK_KHR_get_physical_device_properties2[] 272or the equivalent 273 274include::{generated}/api/structs/VkPhysicalDeviceProperties2KHR.txt[] 275endif::VK_KHR_get_physical_device_properties2[] 276 277 * pname:sType is the type of this structure. 278 * pname:pNext is `NULL` or a pointer to a structure extending this 279 structure. 280 * pname:properties is a slink:VkPhysicalDeviceProperties structure 281 describing properties of the physical device. 282 This structure is written with the same values as if it were written by 283 flink:vkGetPhysicalDeviceProperties. 284 285The pname:pNext chain of this structure is used to extend the structure with 286properties defined by extensions. 287 288include::{generated}/validity/structs/VkPhysicalDeviceProperties2.txt[] 289-- 290 291ifdef::VK_VERSION_1_2[] 292[open,refpage='VkPhysicalDeviceVulkan11Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.1',type='structs'] 293-- 294The sname:VkPhysicalDeviceVulkan11Properties structure is defined as: 295 296include::{generated}/api/structs/VkPhysicalDeviceVulkan11Properties.txt[] 297 298 * pname:sType is the type of this structure. 299 * pname:pNext is `NULL` or a pointer to a structure extending this 300 structure. 301 302:anchor-prefix: 303include::{chapters}/devsandqueues.txt[tag=VK_KHR_external_memory_capabilities-properties] 304 * [[{anchor-prefix}limits-subgroup-size]] pname:subgroupSize is the 305 default number of invocations in each subgroup. 306 pname:subgroupSize is at least 1 if any of the physical device's queues 307 support ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT. 308 pname:subgroupSize is a power-of-two. 309 * [[{anchor-prefix}limits-subgroupSupportedStages]] 310 pname:subgroupSupportedStages is a bitfield of 311 elink:VkShaderStageFlagBits describing the shader stages that 312 <<shaders-group-operations, group operations>> with 313 <<shaders-scope-subgroup, subgroup scope>> are supported in. 314 pname:subgroupSupportedStages will have the 315 ename:VK_SHADER_STAGE_COMPUTE_BIT bit set if any of the physical 316 device's queues support ename:VK_QUEUE_COMPUTE_BIT. 317 * pname:subgroupSupportedOperations is a bitmask of 318 elink:VkSubgroupFeatureFlagBits specifying the sets of 319 <<shaders-group-operations, group operations>> with 320 <<shaders-scope-subgroup, subgroup scope>> supported on this device. 321 pname:subgroupSupportedOperations will have the 322 ename:VK_SUBGROUP_FEATURE_BASIC_BIT bit set if any of the physical 323 device's queues support ename:VK_QUEUE_GRAPHICS_BIT or 324 ename:VK_QUEUE_COMPUTE_BIT. 325 * [[{anchor-prefix}limits-subgroupQuadOperationsInAllStages]] 326 pname:subgroupQuadOperationsInAllStages is a boolean specifying whether 327 <<shaders-quad-operations,quad group operations>> are available in all 328 stages, or are restricted to fragment and compute stages. 329include::{chapters}/limits.txt[tag=VK_KHR_maintenance2-properties] 330include::{chapters}/limits.txt[tag=VK_KHR_multiview-properties] 331include::{chapters}/limits.txt[tag=VK_KHR_protected_memory-properties] 332include::{chapters}/limits.txt[tag=VK_KHR_maintenance3-properties] 333 334:refpage: VkPhysicalDeviceVulkan11Properties 335include::{chapters}/limits.txt[tag=limits_desc] 336 337These properties correspond to Vulkan 1.1 functionality. 338 339The members of sname:VkPhysicalDeviceVulkan11Properties have the same values 340as the corresponding members of slink:VkPhysicalDeviceIDProperties, 341slink:VkPhysicalDeviceSubgroupProperties, 342slink:VkPhysicalDevicePointClippingProperties, 343slink:VkPhysicalDeviceMultiviewProperties, 344slink:VkPhysicalDeviceProtectedMemoryProperties, and 345slink:VkPhysicalDeviceMaintenance3Properties. 346 347include::{generated}/validity/structs/VkPhysicalDeviceVulkan11Properties.txt[] 348-- 349 350[open,refpage='VkPhysicalDeviceVulkan12Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.2',type='structs'] 351-- 352The sname:VkPhysicalDeviceVulkan12Properties structure is defined as: 353 354include::{generated}/api/structs/VkPhysicalDeviceVulkan12Properties.txt[] 355 356 * pname:sType is the type of this structure. 357 * pname:pNext is `NULL` or a pointer to a structure extending this 358 structure. 359 360:anchor-prefix: 361include::{chapters}/devsandqueues.txt[tag=VK_KHR_driver_properties-properties] 362include::{chapters}/limits.txt[tag=VK_KHR_shader_float_controls-properties] 363include::{chapters}/limits.txt[tag=VK_EXT_descriptor_indexing-properties] 364include::{chapters}/limits.txt[tag=VK_KHR_depth_stencil_resolve-properties] 365include::{chapters}/limits.txt[tag=VK_EXT_sampler_filter_minmax-properties] 366include::{chapters}/limits.txt[tag=VK_KHR_timeline_semaphore-properties] 367 * [[limits-framebufferIntegerColorSampleCounts]] 368 pname:framebufferIntegerColorSampleCounts is a bitmask of 369 elink:VkSampleCountFlagBits indicating the color sample counts that are 370 supported for all framebuffer color attachments with integer formats. 371 372:refpage: VkPhysicalDeviceVulkan12Properties 373include::{chapters}/limits.txt[tag=limits_desc] 374 375These properties correspond to Vulkan 1.2 functionality. 376 377The members of sname:VkPhysicalDeviceVulkan12Properties must: have the same 378values as the corresponding members of 379slink:VkPhysicalDeviceDriverProperties, 380slink:VkPhysicalDeviceFloatControlsProperties, 381slink:VkPhysicalDeviceDescriptorIndexingProperties, 382slink:VkPhysicalDeviceDepthStencilResolveProperties, 383slink:VkPhysicalDeviceSamplerFilterMinmaxProperties, and 384slink:VkPhysicalDeviceTimelineSemaphoreProperties. 385 386include::{generated}/validity/structs/VkPhysicalDeviceVulkan12Properties.txt[] 387-- 388endif::VK_VERSION_1_2[] 389 390ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 391[open,refpage='VkPhysicalDeviceIDProperties',desc='Structure specifying IDs related to the physical device',type='structs'] 392-- 393The sname:VkPhysicalDeviceIDProperties structure is defined as: 394 395include::{generated}/api/structs/VkPhysicalDeviceIDProperties.txt[] 396 397ifdef::VK_KHR_external_memory_capabilities[] 398or the equivalent 399 400include::{generated}/api/structs/VkPhysicalDeviceIDPropertiesKHR.txt[] 401endif::VK_KHR_external_memory_capabilities[] 402 403 * pname:sType is the type of this structure. 404 * pname:pNext is `NULL` or a pointer to a structure extending this 405 structure. 406 407// Must have preceding whitespace 408ifdef::VK_VERSION_1_2[:anchor-prefix: extension-] 409ifndef::VK_VERSION_1_2[:anchor-prefix:] 410// tag::VK_KHR_external_memory_capabilities-properties[] 411 * pname:deviceUUID is an array of ename:VK_UUID_SIZE code:uint8_t values 412 representing a universally unique identifier for the device. 413 * pname:driverUUID is an array of ename:VK_UUID_SIZE code:uint8_t values 414 representing a universally unique identifier for the driver build in use 415 by the device. 416 * pname:deviceLUID is an array of ename:VK_LUID_SIZE code:uint8_t values 417 representing a locally unique identifier for the device. 418 * pname:deviceNodeMask is a code:uint32_t bitfield identifying the node 419 within a linked device adapter corresponding to the device. 420 * pname:deviceLUIDValid is a boolean value that will be ename:VK_TRUE if 421 pname:deviceLUID contains a valid LUID and pname:deviceNodeMask contains 422 a valid node mask, and ename:VK_FALSE if they do not. 423// end::VK_KHR_external_memory_capabilities-properties[] 424 425:refpage: VkPhysicalDeviceIDProperties 426include::{chapters}/limits.txt[tag=limits_desc] 427 428pname:deviceUUID must: be immutable for a given device across instances, 429processes, driver APIs, driver versions, and system reboots. 430 431Applications can: compare the pname:driverUUID value across instance and 432process boundaries, and can: make similar queries in external APIs to 433determine whether they are capable of sharing memory objects and resources 434using them with the device. 435 436pname:deviceUUID and/or pname:driverUUID must: be used to determine whether 437a particular external object can be shared between driver components, where 438such a restriction exists as defined in the compatibility table for the 439particular object type: 440 441ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 442 * <<external-memory-handle-types-compatibility,External memory handle 443 types compatibility>> 444endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 445ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] 446 * <<external-semaphore-handle-types-compatibility,External semaphore 447 handle types compatibility>> 448endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] 449ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] 450 * <<external-fence-handle-types-compatibility,External fence handle types 451 compatibility>> 452endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] 453 454If pname:deviceLUIDValid is ename:VK_FALSE, the values of pname:deviceLUID 455and pname:deviceNodeMask are undefined:. 456If pname:deviceLUIDValid is ename:VK_TRUE and Vulkan is running on the 457Windows operating system, the contents of pname:deviceLUID can: be cast to 458an code:LUID object and must: be equal to the locally unique identifier of a 459code:IDXGIAdapter1 object that corresponds to pname:physicalDevice. 460If pname:deviceLUIDValid is ename:VK_TRUE, pname:deviceNodeMask must: 461contain exactly one bit. 462If Vulkan is running on an operating system that supports the Direct3D 12 463API and pname:physicalDevice corresponds to an individual device in a linked 464device adapter, pname:deviceNodeMask identifies the Direct3D 12 node 465corresponding to pname:physicalDevice. 466Otherwise, pname:deviceNodeMask must: be `1`. 467 468[NOTE] 469.Note 470==== 471Although they have identical descriptions, 472slink:VkPhysicalDeviceIDProperties::pname:deviceUUID may differ from 473slink:VkPhysicalDeviceProperties2::pname:pipelineCacheUUID. 474The former is intended to identify and correlate devices across API and 475driver boundaries, while the latter is used to identify a compatible device 476and driver combination to use when serializing and de-serializing pipeline 477state. 478 479Implementations should: return pname:deviceUUID values which are likely to 480be unique even in the presence of multiple Vulkan implementations (such as a 481GPU driver and a software renderer; two drivers for different GPUs; or the 482same Vulkan driver running on two logically different devices). 483 484Khronos' conformance testing can not guarantee that pname:deviceUUID values 485are actually unique, so implementors should make their own best efforts to 486ensure this. 487In particular, hard-coded pname:deviceUUID values, especially all-`0` bits, 488should: never be used. 489 490A combination of values unique to the vendor, the driver, and the hardware 491environment can be used to provide a pname:deviceUUID which is unique to a 492high degree of certainty. 493Some possible inputs to such a computation are: 494 495 * Information reported by flink:vkGetPhysicalDeviceProperties 496 * PCI device ID (if defined) 497 * PCI bus ID, or similar system configuration information. 498 * Driver binary checksums. 499==== 500 501 502[NOTE] 503.Note 504==== 505While slink:VkPhysicalDeviceIDProperties::pname:deviceUUID is specified to 506remain consistent across driver versions and system reboots, it is not 507intended to be usable as a serializable persistent identifier for a device. 508It may change when a device is physically added to, removed from, or moved 509to a different connector in a system while that system is powered down. 510Further, there is no reasonable way to verify with conformance testing that 511a given device retains the same UUID in a given system across all driver 512versions supported in that system. 513While implementations should make every effort to report consistent device 514UUIDs across driver versions, applications should avoid relying on the 515persistence of this value for uses other than identifying compatible devices 516for external object sharing purposes. 517==== 518 519include::{generated}/validity/structs/VkPhysicalDeviceIDProperties.txt[] 520-- 521 522[open,refpage='VK_UUID_SIZE',desc='Length of a universally unique device or driver build identifier',type='consts'] 523-- 524ename:VK_UUID_SIZE is the length in code:uint8_t values of an array 525containing a universally unique device or driver build identifier, as 526returned in slink:VkPhysicalDeviceIDProperties::deviceUUID and 527slink:VkPhysicalDeviceIDProperties::driverUUID. 528 529include::{generated}/api/enums/VK_UUID_SIZE.txt[] 530-- 531 532[open,refpage='VK_LUID_SIZE',desc='Length of a locally unique device identifier',type='consts',alias='VK_LUID_SIZE_KHR'] 533-- 534ename:VK_LUID_SIZE is the length in code:uint8_t values of an array 535containing a locally unique device identifier, as returned in 536slink:VkPhysicalDeviceIDProperties::deviceLUID. 537 538include::{generated}/api/enums/VK_LUID_SIZE.txt[] 539 540ifdef::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 541or the equivalent 542 543include::{generated}/api/enums/VK_LUID_SIZE_KHR.txt[] 544endif::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 545-- 546endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 547 548ifdef::VK_VERSION_1_2,VK_KHR_driver_properties[] 549[open,refpage='VkPhysicalDeviceDriverProperties',desc='Structure containing driver identification information',type='structs',alias='VkPhysicalDeviceDriverPropertiesKHR'] 550-- 551The sname:VkPhysicalDeviceDriverProperties structure is defined as: 552 553include::{generated}/api/structs/VkPhysicalDeviceDriverProperties.txt[] 554 555ifdef::VK_KHR_driver_properties[] 556or the equivalent 557 558include::{generated}/api/structs/VkPhysicalDeviceDriverPropertiesKHR.txt[] 559endif::VK_KHR_driver_properties[] 560 561 * pname:sType is the type of this structure. 562 * pname:pNext is `NULL` or a pointer to a structure extending this 563 structure. 564 565// Must have preceding whitespace 566ifdef::VK_VERSION_1_2[:anchor-prefix: extension-] 567ifndef::VK_VERSION_1_2[:anchor-prefix:] 568// tag::VK_KHR_driver_properties-properties[] 569 * pname:driverID is a unique identifier for the driver of the physical 570 device. 571 * pname:driverName is an array of ename:VK_MAX_DRIVER_NAME_SIZE code:char 572 containing a null-terminated UTF-8 string which is the name of the 573 driver. 574 * pname:driverInfo is an array of ename:VK_MAX_DRIVER_INFO_SIZE code:char 575 containing a null-terminated UTF-8 string with additional information 576 about the driver. 577 * pname:conformanceVersion is the version of the Vulkan conformance test 578 this driver is conformant against (see slink:VkConformanceVersion). 579// end::VK_KHR_driver_properties-properties[] 580 581:refpage: VkPhysicalDeviceDriverProperties 582include::{chapters}/limits.txt[tag=limits_desc] 583 584These are properties of the driver corresponding to a physical device. 585 586pname:driverID must: be immutable for a given driver across instances, 587processes, driver versions, and system reboots. 588 589include::{generated}/validity/structs/VkPhysicalDeviceDriverProperties.txt[] 590-- 591 592[open,refpage='VkDriverId',desc='Khronos driver IDs',type='enums',alias='VkDriverIdKHR'] 593-- 594Khronos driver IDs which may: be returned in 595slink:VkPhysicalDeviceDriverProperties::pname:driverID are: 596 597include::{generated}/api/enums/VkDriverId.txt[] 598 599ifdef::VK_KHR_driver_properties[] 600or the equivalent 601 602include::{generated}/api/enums/VkDriverIdKHR.txt[] 603endif::VK_KHR_driver_properties[] 604 605[NOTE] 606.Note 607==== 608Khronos driver IDs may be allocated by vendors at any time. 609There may be multiple driver IDs for the same vendor, representing different 610drivers (for e.g. different platforms, proprietary or open source, etc.). 611Only the latest canonical versions of this Specification, of the 612corresponding `vk.xml` API Registry, and of the corresponding 613`{core_header}` header file must: contain all reserved Khronos driver IDs. 614 615Only driver IDs registered with Khronos are given symbolic names. 616There may: be unregistered driver IDs returned. 617==== 618-- 619 620[open,refpage='VK_MAX_DRIVER_NAME_SIZE',desc='Maximum length of a physical device driver name string',type='consts',alias='VK_MAX_DRIVER_NAME_SIZE_KHR'] 621-- 622ename:VK_MAX_DRIVER_NAME_SIZE is the length in code:char values of an array 623containing a driver name string, as returned in 624slink:VkPhysicalDeviceDriverProperties::driverName. 625 626include::{generated}/api/enums/VK_MAX_DRIVER_NAME_SIZE.txt[] 627 628ifdef::VK_KHR_driver_properties[] 629or the equivalent 630 631include::{generated}/api/enums/VK_MAX_DRIVER_NAME_SIZE_KHR.txt[] 632endif::VK_KHR_driver_properties[] 633-- 634 635[open,refpage='VK_MAX_DRIVER_INFO_SIZE',desc='Length of a physical device driver information string',type='consts',alias='VK_MAX_DRIVER_INFO_SIZE_KHR'] 636-- 637ename:VK_MAX_DRIVER_INFO_SIZE is the length in code:char values of an array 638containing a driver information string, as returned in 639slink:VkPhysicalDeviceDriverProperties::driverInfo. 640 641include::{generated}/api/enums/VK_MAX_DRIVER_INFO_SIZE.txt[] 642 643ifdef::VK_KHR_driver_properties[] 644or the equivalent 645 646include::{generated}/api/enums/VK_MAX_DRIVER_INFO_SIZE_KHR.txt[] 647endif::VK_KHR_driver_properties[] 648-- 649 650[open,refpage='VkConformanceVersion',desc='Structure containing the conformance test suite version the implementation is compliant with',type='structs',alias='VkConformanceVersionKHR'] 651-- 652The conformance test suite version an implementation is compliant with is 653described with the sname:VkConformanceVersion structure: 654 655include::{generated}/api/structs/VkConformanceVersion.txt[] 656 657ifdef::VK_KHR_driver_properties[] 658or the equivalent 659 660include::{generated}/api/structs/VkConformanceVersionKHR.txt[] 661endif::VK_KHR_driver_properties[] 662 663 * pname:major is the major version number of the conformance test suite. 664 * pname:minor is the minor version number of the conformance test suite. 665 * pname:subminor is the subminor version number of the conformance test 666 suite. 667 * pname:patch is the patch version number of the conformance test suite. 668 669include::{generated}/validity/structs/VkConformanceVersion.txt[] 670-- 671endif::VK_VERSION_1_2,VK_KHR_driver_properties[] 672 673ifdef::VK_EXT_pci_bus_info[] 674[open,refpage='VkPhysicalDevicePCIBusInfoPropertiesEXT',desc='Structure containing PCI bus information of a physical device',type='structs'] 675-- 676The sname:VkPhysicalDevicePCIBusInfoPropertiesEXT structure is defined as: 677 678include::{generated}/api/structs/VkPhysicalDevicePCIBusInfoPropertiesEXT.txt[] 679 680 * pname:sType is the type of this structure. 681 * pname:pNext is `NULL` or a pointer to a structure extending this 682 structure. 683 * pname:pciDomain is the PCI bus domain. 684 * pname:pciBus is the PCI bus identifier. 685 * pname:pciDevice is the PCI device identifier. 686 * pname:pciFunction is the PCI device function identifier. 687 688:refpage: VkPhysicalDevicePCIBusInfoPropertiesEXT 689include::{chapters}/limits.txt[tag=limits_desc] 690 691These are properties of the PCI bus information of a physical device. 692 693include::{generated}/validity/structs/VkPhysicalDevicePCIBusInfoPropertiesEXT.txt[] 694-- 695endif::VK_EXT_pci_bus_info[] 696 697ifdef::VK_EXT_physical_device_drm[] 698[open,refpage='VkPhysicalDeviceDrmPropertiesEXT',desc='Structure containing DRM information of a physical device',type='structs'] 699-- 700The sname:VkPhysicalDeviceDrmPropertiesEXT structure is defined as: 701 702include::{generated}/api/structs/VkPhysicalDeviceDrmPropertiesEXT.txt[] 703 704 * pname:sType is the type of this structure. 705 * pname:pNext is `NULL` or a pointer to a structure extending this 706 structure. 707 * pname:hasPrimary is a boolean indicating whether the physical device has 708 a DRM primary node. 709 * pname:hasRender is a boolean indicating whether the physical device has 710 a DRM render node. 711 * pname:primaryMajor is the DRM primary node major number, if any. 712 * pname:primaryMinor is the DRM primary node minor number, if any. 713 * pname:renderMajor is the DRM render node major number, if any. 714 * pname:renderMinor is the DRM render node minor number, if any. 715 716:refpage: VkPhysicalDeviceDrmPropertiesEXT 717include::{chapters}/limits.txt[tag=limits_desc] 718 719These are properties of the DRM information of a physical device. 720 721include::{generated}/validity/structs/VkPhysicalDeviceDrmPropertiesEXT.txt[] 722-- 723endif::VK_EXT_physical_device_drm[] 724endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 725 726ifdef::VK_KHR_shader_integer_dot_product[] 727[open,refpage='VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR',desc='Structure containing information about integer dot product support for a physical device',type='structs'] 728-- 729The sname:VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR structure is 730defined as: 731 732include::{generated}/api/structs/VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR.txt[] 733 734 * pname:sType is the type of this structure. 735 * pname:pNext is `NULL` or a pointer to a structure extending this 736 structure. 737 * pname:integerDotProduct8BitUnsignedAccelerated is a boolean that will be 738 ename:VK_TRUE if the support for 8-bit unsigned dot product operations 739 using the code:OpUDotKHR SPIR-V instruction is accelerated 740 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 741 * pname:integerDotProduct8BitSignedAccelerated is a boolean that will be 742 ename:VK_TRUE if the support for 8-bit signed dot product operations 743 using the code:OpSDotKHR SPIR-V instruction is accelerated 744 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 745 * pname:integerDotProduct8BitMixedSignednessAccelerated is a boolean that 746 will be ename:VK_TRUE if the support for 8-bit mixed signedness dot 747 product operations using the code:OpSUDotKHR SPIR-V instruction is 748 accelerated <<devsandqueues-integer-dot-product-accelerated,as defined 749 below>>. 750 * pname:integerDotProduct4x8BitPackedUnsignedAccelerated is a boolean that 751 will be ename:VK_TRUE if the support for 8-bit unsigned dot product 752 operations from operands packed into 32-bit integers using the 753 code:OpUDotKHR SPIR-V instruction is accelerated 754 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 755 * pname:integerDotProduct4x8BitPackedSignedAccelerated is a boolean that 756 will be ename:VK_TRUE if the support for 8-bit signed dot product 757 operations from operands packed into 32-bit integers using the 758 code:OpSDotKHR SPIR-V instruction is accelerated 759 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 760 * pname:integerDotProduct4x8BitPackedMixedSignednessAccelerated is a 761 boolean that will be ename:VK_TRUE if the support for 8-bit mixed 762 signedness dot product operations from operands packed into 32-bit 763 integers using the code:OpSUDotKHR SPIR-V instruction is accelerated 764 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 765 * pname:integerDotProduct16BitUnsignedAccelerated is a boolean that will 766 be ename:VK_TRUE if the support for 16-bit unsigned dot product 767 operations using the code:OpUDotKHR SPIR-V instruction is accelerated 768 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 769 * pname:integerDotProduct16BitSignedAccelerated is a boolean that will be 770 ename:VK_TRUE if the support for 16-bit signed dot product operations 771 using the code:OpSDotKHR SPIR-V instruction is accelerated 772 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 773 * pname:integerDotProduct16BitMixedSignednessAccelerated is a boolean that 774 will be ename:VK_TRUE if the support for 16-bit mixed signedness dot 775 product operations using the code:OpSUDotKHR SPIR-V instruction is 776 accelerated <<devsandqueues-integer-dot-product-accelerated,as defined 777 below>>. 778 * pname:integerDotProduct32BitUnsignedAccelerated is a boolean that will 779 be ename:VK_TRUE if the support for 32-bit unsigned dot product 780 operations using the code:OpUDotKHR SPIR-V instruction is accelerated 781 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 782 * pname:integerDotProduct32BitSignedAccelerated is a boolean that will be 783 ename:VK_TRUE if the support for 32-bit signed dot product operations 784 using the code:OpSDotKHR SPIR-V instruction is accelerated 785 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 786 * pname:integerDotProduct32BitMixedSignednessAccelerated is a boolean that 787 will be ename:VK_TRUE if the support for 32-bit mixed signedness dot 788 product operations using the code:OpSUDotKHR SPIR-V instruction is 789 accelerated <<devsandqueues-integer-dot-product-accelerated,as defined 790 below>>. 791 * pname:integerDotProduct64BitUnsignedAccelerated is a boolean that will 792 be ename:VK_TRUE if the support for 64-bit unsigned dot product 793 operations using the code:OpUDotKHR SPIR-V instruction is accelerated 794 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 795 * pname:integerDotProduct64BitSignedAccelerated is a boolean that will be 796 ename:VK_TRUE if the support for 64-bit signed dot product operations 797 using the code:OpSDotKHR SPIR-V instruction is accelerated 798 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 799 * pname:integerDotProduct64BitMixedSignednessAccelerated is a boolean that 800 will be ename:VK_TRUE if the support for 64-bit mixed signedness dot 801 product operations using the code:OpSUDotKHR SPIR-V instruction is 802 accelerated <<devsandqueues-integer-dot-product-accelerated,as defined 803 below>>. 804 * pname:integerDotProductAccumulatingSaturating8BitUnsignedAccelerated is 805 a boolean that will be ename:VK_TRUE if the support for 8-bit unsigned 806 accumulating saturating dot product operations using the 807 code:OpUDotAccSatKHR SPIR-V instruction is accelerated 808 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 809 * pname:integerDotProductAccumulatingSaturating8BitSignedAccelerated is a 810 boolean that will be ename:VK_TRUE if the support for 8-bit signed 811 accumulating saturating dot product operations using the 812 code:OpSDotAccSatKHR SPIR-V instruction is accelerated 813 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 814 * pname:integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated 815 is a boolean that will be ename:VK_TRUE if the support for 8-bit mixed 816 signedness accumulating saturating dot product operations using the 817 code:OpSUDotAccSatKHR SPIR-V instruction is accelerated 818 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 819 * pname:integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated 820 is a boolean that will be ename:VK_TRUE if the support for 8-bit 821 unsigned accumulating saturating dot product operations from operands 822 packed into 32-bit integers using the code:OpUDotAccSatKHR SPIR-V 823 instruction is accelerated 824 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 825 * pname:integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated 826 is a boolean that will be ename:VK_TRUE if the support for 8-bit signed 827 accumulating saturating dot product operations from operands packed into 828 32-bit integers using the code:OpSDotAccSatKHR SPIR-V instruction is 829 accelerated <<devsandqueues-integer-dot-product-accelerated,as defined 830 below>>. 831 * pname:integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated 832 is a boolean that will be ename:VK_TRUE if the support for 8-bit mixed 833 signedness accumulating saturating dot product operations from operands 834 packed into 32-bit integers using the code:OpSUDotAccSatKHR SPIR-V 835 instruction is accelerated 836 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 837 * pname:integerDotProductAccumulatingSaturating16BitUnsignedAccelerated is 838 a boolean that will be ename:VK_TRUE if the support for 16-bit unsigned 839 accumulating saturating dot product operations using the 840 code:OpUDotAccSatKHR SPIR-V instruction is accelerated 841 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 842 * pname:integerDotProductAccumulatingSaturating16BitSignedAccelerated is a 843 boolean that will be ename:VK_TRUE if the support for 16-bit signed 844 accumulating saturating dot product operations using the 845 code:OpSDotAccSatKHR SPIR-V instruction is accelerated 846 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 847 * pname:integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated 848 is a boolean that will be ename:VK_TRUE if the support for 16-bit mixed 849 signedness accumulating saturating dot product operations using the 850 code:OpSUDotAccSatKHR SPIR-V instruction is accelerated 851 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 852 * pname:integerDotProductAccumulatingSaturating32BitUnsignedAccelerated is 853 a boolean that will be ename:VK_TRUE if the support for 32-bit unsigned 854 accumulating saturating dot product operations using the 855 code:OpUDotAccSatKHR SPIR-V instruction is accelerated 856 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 857 * pname:integerDotProductAccumulatingSaturating32BitSignedAccelerated is a 858 boolean that will be ename:VK_TRUE if the support for 32-bit signed 859 accumulating saturating dot product operations using the 860 code:OpSDotAccSatKHR SPIR-V instruction is accelerated 861 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 862 * pname:integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated 863 is a boolean that will be ename:VK_TRUE if the support for 32-bit mixed 864 signedness accumulating saturating dot product operations using the 865 code:OpSUDotAccSatKHR SPIR-V instruction is accelerated 866 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 867 * pname:integerDotProductAccumulatingSaturating64BitUnsignedAccelerated is 868 a boolean that will be ename:VK_TRUE if the support for 64-bit unsigned 869 accumulating saturating dot product operations using the 870 code:OpUDotAccSatKHR SPIR-V instruction is accelerated 871 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 872 * pname:integerDotProductAccumulatingSaturating64BitSignedAccelerated is a 873 boolean that will be ename:VK_TRUE if the support for 64-bit signed 874 accumulating saturating dot product operations using the 875 code:OpSDotAccSatKHR SPIR-V instruction is accelerated 876 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 877 * pname:integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated 878 is a boolean that will be ename:VK_TRUE if the support for 64-bit mixed 879 signedness accumulating saturating dot product operations using the 880 code:OpSUDotAccSatKHR SPIR-V instruction is accelerated 881 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 882 883:refpage: VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR 884include::{chapters}/limits.txt[tag=limits_desc] 885 886These are properties of the integer dot product acceleration information of 887a physical device. 888 889[[devsandqueues-integer-dot-product-accelerated]] 890[NOTE] 891.Note 892==== 893A dot product operation is deemed accelerated if its implementation provides 894a performance advantage over application-provided code composed from 895elementary instructions and/or other dot product instructions, either 896because the implementation uses optimized machine code sequences whose 897generation from application-provided code cannot be guaranteed or because it 898uses hardware features that cannot otherwise be targeted from 899application-provided code. 900==== 901 902include::{generated}/validity/structs/VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR.txt[] 903-- 904endif::VK_KHR_shader_integer_dot_product[] 905 906[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties',desc='Reports properties of the queues of the specified physical device',type='protos'] 907-- 908To query properties of queues available on a physical device, call: 909 910include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[] 911 912 * pname:physicalDevice is the handle to the physical device whose 913 properties will be queried. 914 * pname:pQueueFamilyPropertyCount is a pointer to an integer related to 915 the number of queue families available or queried, as described below. 916 * pname:pQueueFamilyProperties is either `NULL` or a pointer to an array 917 of slink:VkQueueFamilyProperties structures. 918 919If pname:pQueueFamilyProperties is `NULL`, then the number of queue families 920available is returned in pname:pQueueFamilyPropertyCount. 921Implementations must: support at least one queue family. 922Otherwise, pname:pQueueFamilyPropertyCount must: point to a variable set by 923the user to the number of elements in the pname:pQueueFamilyProperties 924array, and on return the variable is overwritten with the number of 925structures actually written to pname:pQueueFamilyProperties. 926If pname:pQueueFamilyPropertyCount is less than the number of queue families 927available, at most pname:pQueueFamilyPropertyCount structures will be 928written. 929 930include::{generated}/validity/protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[] 931-- 932 933[open,refpage='VkQueueFamilyProperties',desc='Structure providing information about a queue family',type='structs'] 934-- 935The sname:VkQueueFamilyProperties structure is defined as: 936 937include::{generated}/api/structs/VkQueueFamilyProperties.txt[] 938 939 * pname:queueFlags is a bitmask of elink:VkQueueFlagBits indicating 940 capabilities of the queues in this queue family. 941 * pname:queueCount is the unsigned integer count of queues in this queue 942 family. 943 Each queue family must: support at least one queue. 944 * pname:timestampValidBits is the unsigned integer count of meaningful 945 bits in the timestamps written via 946ifdef::VK_KHR_synchronization2[] 947 flink:vkCmdWriteTimestamp2KHR or 948endif::VK_KHR_synchronization2[] 949 flink:vkCmdWriteTimestamp. 950 The valid range for the count is 36..64 bits, or a value of 0, 951 indicating no support for timestamps. 952 Bits outside the valid range are guaranteed to be zeros. 953 * pname:minImageTransferGranularity is the minimum granularity supported 954 for image transfer operations on the queues in this queue family. 955 956The value returned in pname:minImageTransferGranularity has a unit of 957compressed texel blocks for images having a block-compressed format, and a 958unit of texels otherwise. 959 960Possible values of pname:minImageTransferGranularity are: 961 962 * [eq]#(0,0,0)# specifies that only whole mip levels must: be transferred 963 using the image transfer operations on the corresponding queues. 964 In this case, the following restrictions apply to all offset and extent 965 parameters of image transfer operations: 966 ** The pname:x, pname:y, and pname:z members of a slink:VkOffset3D 967 parameter must: always be zero. 968 ** The pname:width, pname:height, and pname:depth members of a 969 slink:VkExtent3D parameter must: always match the width, height, and 970 depth of the image subresource corresponding to the parameter, 971 respectively. 972 * [eq]#(A~x~, A~y~, A~z~)# where [eq]#A~x~#, [eq]#A~y~#, and [eq]#A~z~# 973 are all integer powers of two. 974 In this case the following restrictions apply to all image transfer 975 operations: 976 ** pname:x, pname:y, and pname:z of a slink:VkOffset3D parameter must: be 977 integer multiples of [eq]#A~x~#, [eq]#A~y~#, and [eq]#A~z~#, 978 respectively. 979 ** pname:width of a slink:VkExtent3D parameter must: be an integer 980 multiple of [eq]#A~x~#, or else [eq]#pname:x {plus} pname:width# must: 981 equal the width of the image subresource corresponding to the 982 parameter. 983 ** pname:height of a slink:VkExtent3D parameter must: be an integer 984 multiple of [eq]#A~y~#, or else [eq]#pname:y {plus} pname:height# must: 985 equal the height of the image subresource corresponding to the 986 parameter. 987 ** pname:depth of a slink:VkExtent3D parameter must: be an integer 988 multiple of [eq]#A~z~#, or else [eq]#pname:z {plus} pname:depth# must: 989 equal the depth of the image subresource corresponding to the 990 parameter. 991 ** If the format of the image corresponding to the parameters is one of 992 the block-compressed formats then for the purposes of the above 993 calculations the granularity must: be scaled up by the compressed texel 994 block dimensions. 995 996Queues supporting graphics and/or compute operations must: report 997[eq]#(1,1,1)# in pname:minImageTransferGranularity, meaning that there are 998no additional restrictions on the granularity of image transfer operations 999for these queues. 1000Other queues supporting image transfer operations are only required: to 1001support whole mip level transfers, thus pname:minImageTransferGranularity 1002for queues belonging to such queue families may: be [eq]#(0,0,0)#. 1003 1004The <<memory-device,Device Memory>> section describes memory properties 1005queried from the physical device. 1006 1007For physical device feature queries see the <<features, Features>> chapter. 1008 1009include::{generated}/validity/structs/VkQueueFamilyProperties.txt[] 1010-- 1011 1012[open,refpage='VkQueueFlagBits',desc='Bitmask specifying capabilities of queues in a queue family',type='enums'] 1013-- 1014Bits which may: be set in slink:VkQueueFamilyProperties::pname:queueFlags 1015indicating capabilities of queues in a queue family are: 1016 1017include::{generated}/api/enums/VkQueueFlagBits.txt[] 1018 1019 * ename:VK_QUEUE_GRAPHICS_BIT specifies that queues in this queue family 1020 support graphics operations. 1021 * ename:VK_QUEUE_COMPUTE_BIT specifies that queues in this queue family 1022 support compute operations. 1023 * ename:VK_QUEUE_TRANSFER_BIT specifies that queues in this queue family 1024 support transfer operations. 1025 * ename:VK_QUEUE_SPARSE_BINDING_BIT specifies that queues in this queue 1026 family support sparse memory management operations (see 1027 <<sparsememory,Sparse Resources>>). 1028 If any of the sparse resource features are enabled, then at least one 1029 queue family must: support this bit. 1030ifdef::VK_KHR_video_decode_queue[] 1031 * ename:VK_QUEUE_VIDEO_DECODE_BIT_KHR specifies that queues in this queue 1032 family support Video Decode operations. 1033endif::VK_KHR_video_decode_queue[] 1034ifdef::VK_KHR_video_encode_queue[] 1035 * ename:VK_QUEUE_VIDEO_ENCODE_BIT_KHR specifies that queues in this queue 1036 family support Video Encode operations. 1037endif::VK_KHR_video_encode_queue[] 1038ifdef::VK_VERSION_1_1[] 1039 * ename:VK_QUEUE_PROTECTED_BIT specifies that queues in this queue family 1040 support the ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit. 1041 (see <<memory-protected-memory,Protected Memory>>). 1042 If the physical device supports the pname:protectedMemory feature, at 1043 least one of its queue families must: support this bit. 1044endif::VK_VERSION_1_1[] 1045 1046If an implementation exposes any queue family that supports graphics 1047operations, at least one queue family of at least one physical device 1048exposed by the implementation must: support both graphics and compute 1049operations. 1050 1051ifdef::VK_VERSION_1_1[] 1052Furthermore, if the protected memory physical device feature is supported, 1053then at least one queue family of at least one physical device exposed by 1054the implementation must: support graphics operations, compute operations, 1055and protected memory operations. 1056endif::VK_VERSION_1_1[] 1057 1058[NOTE] 1059.Note 1060==== 1061All commands that are allowed on a queue that supports transfer operations 1062are also allowed on a queue that supports either graphics or compute 1063operations. 1064Thus, if the capabilities of a queue family include 1065ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT, then reporting 1066the ename:VK_QUEUE_TRANSFER_BIT capability separately for that queue family 1067is optional:. 1068==== 1069 1070For further details see <<devsandqueues-queues,Queues>>. 1071-- 1072 1073[open,refpage='VkQueueFlags',desc='Bitmask of VkQueueFlagBits',type='flags'] 1074-- 1075include::{generated}/api/flags/VkQueueFlags.txt[] 1076 1077tname:VkQueueFlags is a bitmask type for setting a mask of zero or more 1078elink:VkQueueFlagBits. 1079-- 1080 1081ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1082[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties2',desc='Reports properties of the queues of the specified physical device',type='protos'] 1083-- 1084To query properties of queues available on a physical device, call: 1085 1086ifdef::VK_VERSION_1_1[] 1087include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties2.txt[] 1088endif::VK_VERSION_1_1[] 1089 1090ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] 1091 1092ifdef::VK_KHR_get_physical_device_properties2[] 1093include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.txt[] 1094endif::VK_KHR_get_physical_device_properties2[] 1095 1096 * pname:physicalDevice is the handle to the physical device whose 1097 properties will be queried. 1098 * pname:pQueueFamilyPropertyCount is a pointer to an integer related to 1099 the number of queue families available or queried, as described in 1100 flink:vkGetPhysicalDeviceQueueFamilyProperties. 1101 * pname:pQueueFamilyProperties is either `NULL` or a pointer to an array 1102 of slink:VkQueueFamilyProperties2 structures. 1103 1104fname:vkGetPhysicalDeviceQueueFamilyProperties2 behaves similarly to 1105flink:vkGetPhysicalDeviceQueueFamilyProperties, with the ability to return 1106extended information in a pname:pNext chain of output structures. 1107 1108include::{generated}/validity/protos/vkGetPhysicalDeviceQueueFamilyProperties2.txt[] 1109-- 1110 1111[open,refpage='VkQueueFamilyProperties2',desc='Structure providing information about a queue family',type='structs'] 1112-- 1113The sname:VkQueueFamilyProperties2 structure is defined as: 1114 1115include::{generated}/api/structs/VkQueueFamilyProperties2.txt[] 1116 1117ifdef::VK_KHR_get_physical_device_properties2[] 1118or the equivalent 1119 1120include::{generated}/api/structs/VkQueueFamilyProperties2KHR.txt[] 1121endif::VK_KHR_get_physical_device_properties2[] 1122 1123 * pname:sType is the type of this structure. 1124 * pname:pNext is `NULL` or a pointer to a structure extending this 1125 structure. 1126 * pname:queueFamilyProperties is a slink:VkQueueFamilyProperties structure 1127 which is populated with the same values as in 1128 flink:vkGetPhysicalDeviceQueueFamilyProperties. 1129 1130include::{generated}/validity/structs/VkQueueFamilyProperties2.txt[] 1131-- 1132 1133ifdef::VK_EXT_global_priority_query[] 1134 1135[open,refpage='VkQueueFamilyGlobalPriorityPropertiesEXT',desc='Return structure for queue family global priority information query',type='structs'] 1136-- 1137 1138The definition of slink:VkQueueFamilyGlobalPriorityPropertiesEXT is: 1139 1140include::{generated}/api/structs/VkQueueFamilyGlobalPriorityPropertiesEXT.txt[] 1141 1142 * pname:sType is the type of this structure. 1143 * pname:pNext is `NULL` or a pointer to a structure extending this 1144 structure. 1145 * pname:priorityCount is the number of supported global queue priorities 1146 in this queue family, and it must: be greater than 0. 1147 * pname:priorities is an array of ename:VK_MAX_GLOBAL_PRIORITY_SIZE_EXT 1148 elink:VkQueueGlobalPriorityEXT enums representing all supported global 1149 queue priorities in this queue family. 1150 The first pname:priorityCount elements of the array will be valid. 1151 1152The valid elements of pname:priorities must: not contain any duplicate 1153values. 1154 1155The valid elements of pname:priorities must: be a continuous sequence of 1156elink:VkQueueGlobalPriorityEXT enums in the ascending order. 1157 1158[NOTE] 1159.Note 1160==== 1161For example, returning pname:priorityCount as 3 with supported 1162pname:priorities as ename:VK_QUEUE_GLOBAL_PRIORITY_LOW_EXT, 1163ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT and 1164ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_EXT is not allowed. 1165==== 1166 1167include::{generated}/validity/structs/VkQueueFamilyGlobalPriorityPropertiesEXT.txt[] 1168 1169-- 1170 1171endif::VK_EXT_global_priority_query[] 1172 1173ifdef::VK_NV_device_diagnostic_checkpoints[] 1174include::{chapters}/VK_NV_device_diagnostic_checkpoints/queue_checkpoint_properties.txt[] 1175endif::VK_NV_device_diagnostic_checkpoints[] 1176 1177endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1178 1179ifdef::VK_KHR_performance_query[] 1180include::{chapters}/VK_KHR_performance_query/queuefamily.txt[] 1181endif::VK_KHR_performance_query[] 1182 1183 1184[[devsandqueues-devices]] 1185== Devices 1186 1187Device objects represent logical connections to physical devices. 1188Each device exposes a number of _queue families_ each having one or more 1189_queues_. 1190All queues in a queue family support the same operations. 1191 1192As described in <<devsandqueues-physical-device-enumeration,Physical 1193Devices>>, a Vulkan application will first query for all physical devices in 1194a system. 1195Each physical device can: then be queried for its capabilities, including 1196its queue and queue family properties. 1197Once an acceptable physical device is identified, an application will create 1198a corresponding logical device. 1199The created logical device is then the primary interface to the physical 1200device. 1201 1202How to enumerate the physical devices in a system and query those physical 1203devices for their queue family properties is described in the 1204<<devsandqueues-physical-device-enumeration, Physical Device Enumeration>> 1205section above. 1206 1207ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[] 1208 1209A single logical device can: be created from multiple physical devices, if 1210those physical devices belong to the same device group. 1211A _device group_ is a set of physical devices that support accessing each 1212other's memory and recording a single command buffer that can: be executed 1213on all the physical devices. 1214Device groups are enumerated by calling 1215flink:vkEnumeratePhysicalDeviceGroups, and a logical device is created from 1216a subset of the physical devices in a device group by passing the physical 1217devices through slink:VkDeviceGroupDeviceCreateInfo. 1218For two physical devices to be in the same device group, they must: support 1219identical extensions, features, and properties. 1220 1221[NOTE] 1222.Note 1223==== 1224Physical devices in the same device group must: be so similar because there 1225are no rules for how different features/properties would interact. 1226They must: return the same values for nearly every invariant 1227ftext:vkGetPhysicalDevice* feature, property, capability, etc., but could 1228potentially differ for certain queries based on things like having a 1229different display connected, or a different compositor. 1230The specification does not attempt to enumerate which state is in each 1231category, because such a list would quickly become out of date. 1232==== 1233 1234[open,refpage='vkEnumeratePhysicalDeviceGroups',desc='Enumerates groups of physical devices that can be used to create a single logical device',type='protos'] 1235-- 1236To retrieve a list of the device groups present in the system, call: 1237 1238ifdef::VK_VERSION_1_1[] 1239include::{generated}/api/protos/vkEnumeratePhysicalDeviceGroups.txt[] 1240endif::VK_VERSION_1_1[] 1241 1242ifdef::VK_VERSION_1_1+VK_KHR_device_group_creation[or the equivalent command] 1243 1244ifdef::VK_KHR_device_group_creation[] 1245include::{generated}/api/protos/vkEnumeratePhysicalDeviceGroupsKHR.txt[] 1246endif::VK_KHR_device_group_creation[] 1247 1248 * pname:instance is a handle to a Vulkan instance previously created with 1249 flink:vkCreateInstance. 1250 * pname:pPhysicalDeviceGroupCount is a pointer to an integer related to 1251 the number of device groups available or queried, as described below. 1252 * pname:pPhysicalDeviceGroupProperties is either `NULL` or a pointer to an 1253 array of slink:VkPhysicalDeviceGroupProperties structures. 1254 1255If pname:pPhysicalDeviceGroupProperties is `NULL`, then the number of device 1256groups available is returned in pname:pPhysicalDeviceGroupCount. 1257Otherwise, pname:pPhysicalDeviceGroupCount must: point to a variable set by 1258the user to the number of elements in the 1259pname:pPhysicalDeviceGroupProperties array, and on return the variable is 1260overwritten with the number of structures actually written to 1261pname:pPhysicalDeviceGroupProperties. 1262If pname:pPhysicalDeviceGroupCount is less than the number of device groups 1263available, at most pname:pPhysicalDeviceGroupCount structures will be 1264written, and ename:VK_INCOMPLETE will be returned instead of 1265ename:VK_SUCCESS, to indicate that not all the available device groups were 1266returned. 1267 1268Every physical device must: be in exactly one device group. 1269 1270include::{generated}/validity/protos/vkEnumeratePhysicalDeviceGroups.txt[] 1271-- 1272 1273[open,refpage='VkPhysicalDeviceGroupProperties',desc='Structure specifying physical device group properties',type='structs'] 1274-- 1275The sname:VkPhysicalDeviceGroupProperties structure is defined as: 1276 1277include::{generated}/api/structs/VkPhysicalDeviceGroupProperties.txt[] 1278 1279ifdef::VK_KHR_device_group_creation[] 1280or the equivalent 1281 1282include::{generated}/api/structs/VkPhysicalDeviceGroupPropertiesKHR.txt[] 1283endif::VK_KHR_device_group_creation[] 1284 1285 * pname:sType is the type of this structure. 1286 * pname:pNext is `NULL` or a pointer to a structure extending this 1287 structure. 1288 * pname:physicalDeviceCount is the number of physical devices in the 1289 group. 1290 * pname:physicalDevices is an array of ename:VK_MAX_DEVICE_GROUP_SIZE 1291 slink:VkPhysicalDevice handles representing all physical devices in the 1292 group. 1293 The first pname:physicalDeviceCount elements of the array will be valid. 1294 * pname:subsetAllocation specifies whether logical devices created from 1295 the group support allocating device memory on a subset of devices, via 1296 the pname:deviceMask member of the slink:VkMemoryAllocateFlagsInfo. 1297 If this is ename:VK_FALSE, then all device memory allocations are made 1298 across all physical devices in the group. 1299 If pname:physicalDeviceCount is `1`, then pname:subsetAllocation must: 1300 be ename:VK_FALSE. 1301 1302include::{generated}/validity/structs/VkPhysicalDeviceGroupProperties.txt[] 1303-- 1304 1305[open,refpage='VK_MAX_DEVICE_GROUP_SIZE',desc='Length of a physical device handle array',type='consts',alias='VK_MAX_DEVICE_GROUP_SIZE_KHR'] 1306-- 1307ename:VK_MAX_DEVICE_GROUP_SIZE is the length of an array containing 1308slink:VkPhysicalDevice handle values representing all physical devices in a 1309group, as returned in 1310slink:VkPhysicalDeviceGroupProperties::physicalDevices. 1311 1312include::{generated}/api/enums/VK_MAX_DEVICE_GROUP_SIZE.txt[] 1313 1314ifdef::VK_KHR_device_group_creation[] 1315or the equivalent 1316 1317include::{generated}/api/enums/VK_MAX_DEVICE_GROUP_SIZE_KHR.txt[] 1318endif::VK_KHR_device_group_creation[] 1319-- 1320endif::VK_VERSION_1_1,VK_KHR_device_group_creation[] 1321 1322 1323[[devsandqueues-device-creation]] 1324=== Device Creation 1325 1326[open,refpage='VkDevice',desc='Opaque handle to a device object',type='handles'] 1327-- 1328Logical devices are represented by sname:VkDevice handles: 1329 1330include::{generated}/api/handles/VkDevice.txt[] 1331-- 1332 1333[open,refpage='vkCreateDevice',desc='Create a new device instance',type='protos'] 1334-- 1335A logical device is created as a _connection_ to a physical device. 1336To create a logical device, call: 1337 1338include::{generated}/api/protos/vkCreateDevice.txt[] 1339 1340 * pname:physicalDevice must: be one of the device handles returned from a 1341 call to fname:vkEnumeratePhysicalDevices (see 1342 <<devsandqueues-physical-device-enumeration, Physical Device 1343 Enumeration>>). 1344 * pname:pCreateInfo is a pointer to a slink:VkDeviceCreateInfo structure 1345 containing information about how to create the device. 1346 * pname:pAllocator controls host memory allocation as described in the 1347 <<memory-allocation, Memory Allocation>> chapter. 1348 * pname:pDevice is a pointer to a handle in which the created 1349 slink:VkDevice is returned. 1350 1351fname:vkCreateDevice verifies that extensions and features requested in the 1352pname:ppEnabledExtensionNames and pname:pEnabledFeatures members of 1353pname:pCreateInfo, respectively, are supported by the implementation. 1354If any requested extension is not supported, fname:vkCreateDevice must: 1355return ename:VK_ERROR_EXTENSION_NOT_PRESENT. 1356If any requested feature is not supported, fname:vkCreateDevice must: return 1357ename:VK_ERROR_FEATURE_NOT_PRESENT. 1358Support for extensions can: be checked before creating a device by querying 1359flink:vkEnumerateDeviceExtensionProperties. 1360Support for features can: similarly be checked by querying 1361flink:vkGetPhysicalDeviceFeatures. 1362 1363After verifying and enabling the extensions the sname:VkDevice object is 1364created and returned to the application. 1365 1366Multiple logical devices can: be created from the same physical device. 1367Logical device creation may: fail due to lack of device-specific resources 1368(in addition to other errors). 1369If that occurs, fname:vkCreateDevice will return 1370ename:VK_ERROR_TOO_MANY_OBJECTS. 1371 1372.Valid Usage 1373**** 1374 * [[VUID-vkCreateDevice-ppEnabledExtensionNames-01387]] 1375 All <<extendingvulkan-extensions-extensiondependencies, required device 1376 extensions>> for each extension in the 1377 slink:VkDeviceCreateInfo::pname:ppEnabledExtensionNames list must: also 1378 be present in that list 1379**** 1380 1381include::{generated}/validity/protos/vkCreateDevice.txt[] 1382-- 1383 1384[open,refpage='VkDeviceCreateInfo',desc='Structure specifying parameters of a newly created device',type='structs'] 1385-- 1386The sname:VkDeviceCreateInfo structure is defined as: 1387 1388include::{generated}/api/structs/VkDeviceCreateInfo.txt[] 1389 1390 * pname:sType is the type of this structure. 1391 * pname:pNext is `NULL` or a pointer to a structure extending this 1392 structure. 1393 * pname:flags is reserved for future use. 1394 * pname:queueCreateInfoCount is the unsigned integer size of the 1395 pname:pQueueCreateInfos array. 1396 Refer to the <<devsandqueues-queue-creation,Queue Creation>> section 1397 below for further details. 1398 * pname:pQueueCreateInfos is a pointer to an array of 1399 slink:VkDeviceQueueCreateInfo structures describing the queues that are 1400 requested to be created along with the logical device. 1401 Refer to the <<devsandqueues-queue-creation,Queue Creation>> section 1402 below for further details. 1403 * pname:enabledLayerCount is deprecated and ignored. 1404 * pname:ppEnabledLayerNames is deprecated and ignored. 1405 See <<extendingvulkan-layers-devicelayerdeprecation>>. 1406 * pname:enabledExtensionCount is the number of device extensions to 1407 enable. 1408 * pname:ppEnabledExtensionNames is a pointer to an array of 1409 pname:enabledExtensionCount null-terminated UTF-8 strings containing the 1410 names of extensions to enable for the created device. 1411 See the <<extendingvulkan-extensions>> section for further details. 1412 * pname:pEnabledFeatures is `NULL` or a pointer to a 1413 slink:VkPhysicalDeviceFeatures structure containing boolean indicators 1414 of all the features to be enabled. 1415 Refer to the <<features,Features>> section for further details. 1416 1417.Valid Usage 1418**** 1419ifndef::VK_VERSION_1_1[] 1420 * [[VUID-VkDeviceCreateInfo-queueFamilyIndex-00372]] 1421 The pname:queueFamilyIndex member of each element of 1422 pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos 1423endif::VK_VERSION_1_1[] 1424ifdef::VK_VERSION_1_1[] 1425 * [[VUID-VkDeviceCreateInfo-queueFamilyIndex-02802]] 1426 The pname:queueFamilyIndex member of each element of 1427 pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos, 1428 except that two members can share the same pname:queueFamilyIndex if one 1429 is a protected-capable queue and one is not a protected-capable queue 1430endif::VK_VERSION_1_1[] 1431ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1432 * [[VUID-VkDeviceCreateInfo-pNext-00373]] 1433 If the pname:pNext chain includes a slink:VkPhysicalDeviceFeatures2 1434 structure, then pname:pEnabledFeatures must: be `NULL` 1435endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1436ifdef::VK_AMD_negative_viewport_height[] 1437ifdef::VK_VERSION_1_1[] 1438 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-01840]] 1439 pname:ppEnabledExtensionNames must: not contain 1440 `apiext:VK_AMD_negative_viewport_height` 1441endif::VK_VERSION_1_1[] 1442ifndef::VK_VERSION_1_1[] 1443ifdef::VK_KHR_maintenance1[] 1444 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-00374]] 1445 pname:ppEnabledExtensionNames must: not contain both 1446 `apiext:VK_KHR_maintenance1` and 1447 `apiext:VK_AMD_negative_viewport_height` 1448endif::VK_KHR_maintenance1[] 1449endif::VK_VERSION_1_1[] 1450endif::VK_AMD_negative_viewport_height[] 1451ifdef::VK_EXT_buffer_device_address+VK_KHR_buffer_device_address[] 1452 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-03328]] 1453 pname:ppEnabledExtensionNames must: not contain both 1454 `apiext:VK_KHR_buffer_device_address` and 1455 `apiext:VK_EXT_buffer_device_address` 1456endif::VK_EXT_buffer_device_address+VK_KHR_buffer_device_address[] 1457ifdef::VK_VERSION_1_2[] 1458ifdef::VK_EXT_buffer_device_address[] 1459 * [[VUID-VkDeviceCreateInfo-pNext-04748]] 1460 if the pname:pNext chain includes a 1461 slink:VkPhysicalDeviceVulkan12Features structure and 1462 slink:VkPhysicalDeviceVulkan12Features::pname:bufferDeviceAddress is 1463 ename:VK_TRUE, pname:ppEnabledExtensionNames must: not contain 1464 `apiext:VK_EXT_buffer_device_address` 1465endif::VK_EXT_buffer_device_address[] 1466 * [[VUID-VkDeviceCreateInfo-pNext-02829]] 1467 If the pname:pNext chain includes a 1468 slink:VkPhysicalDeviceVulkan11Features structure, then it must: not 1469 include a slink:VkPhysicalDevice16BitStorageFeatures, 1470 slink:VkPhysicalDeviceMultiviewFeatures, 1471 slink:VkPhysicalDeviceVariablePointersFeatures, 1472 slink:VkPhysicalDeviceProtectedMemoryFeatures, 1473 slink:VkPhysicalDeviceSamplerYcbcrConversionFeatures, or 1474 slink:VkPhysicalDeviceShaderDrawParametersFeatures structure 1475 * [[VUID-VkDeviceCreateInfo-pNext-02830]] 1476 If the pname:pNext chain includes a 1477 slink:VkPhysicalDeviceVulkan12Features structure, then it must: not 1478 include a slink:VkPhysicalDevice8BitStorageFeatures, 1479 slink:VkPhysicalDeviceShaderAtomicInt64Features, 1480 slink:VkPhysicalDeviceShaderFloat16Int8Features, 1481 slink:VkPhysicalDeviceDescriptorIndexingFeatures, 1482 slink:VkPhysicalDeviceScalarBlockLayoutFeatures, 1483 slink:VkPhysicalDeviceImagelessFramebufferFeatures, 1484 slink:VkPhysicalDeviceUniformBufferStandardLayoutFeatures, 1485 slink:VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures, 1486 slink:VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures, 1487 slink:VkPhysicalDeviceHostQueryResetFeatures, 1488 slink:VkPhysicalDeviceTimelineSemaphoreFeatures, 1489 slink:VkPhysicalDeviceBufferDeviceAddressFeatures, or 1490 slink:VkPhysicalDeviceVulkanMemoryModelFeatures structure 1491ifdef::VK_KHR_shader_draw_parameters[] 1492 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensions-04476]] 1493 If pname:ppEnabledExtensions contains `"VK_KHR_shader_draw_parameters"` 1494 and the pname:pNext chain includes a 1495 slink:VkPhysicalDeviceVulkan11Features structure, then 1496 sname:VkPhysicalDeviceVulkan11Features::pname:shaderDrawParameters must: 1497 be ename:VK_TRUE 1498endif::VK_KHR_shader_draw_parameters[] 1499ifdef::VK_KHR_draw_indirect_count[] 1500 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensions-02831]] 1501 If pname:ppEnabledExtensions contains `"VK_KHR_draw_indirect_count"` and 1502 the pname:pNext chain includes a slink:VkPhysicalDeviceVulkan12Features 1503 structure, then 1504 sname:VkPhysicalDeviceVulkan12Features::pname:drawIndirectCount must: be 1505 ename:VK_TRUE 1506endif::VK_KHR_draw_indirect_count[] 1507ifdef::VK_KHR_sampler_mirror_clamp_to_edge[] 1508 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensions-02832]] 1509 If pname:ppEnabledExtensions contains 1510 `"VK_KHR_sampler_mirror_clamp_to_edge"` and the pname:pNext chain 1511 includes a slink:VkPhysicalDeviceVulkan12Features structure, then 1512 sname:VkPhysicalDeviceVulkan12Features::pname:samplerMirrorClampToEdge 1513 must: be ename:VK_TRUE 1514endif::VK_KHR_sampler_mirror_clamp_to_edge[] 1515ifdef::VK_EXT_descriptor_indexing[] 1516 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensions-02833]] 1517 If pname:ppEnabledExtensions contains `"VK_EXT_descriptor_indexing"` and 1518 the pname:pNext chain includes a slink:VkPhysicalDeviceVulkan12Features 1519 structure, then 1520 sname:VkPhysicalDeviceVulkan12Features::pname:descriptorIndexing must: 1521 be ename:VK_TRUE 1522endif::VK_EXT_descriptor_indexing[] 1523ifdef::VK_EXT_sampler_filter_minmax[] 1524 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensions-02834]] 1525 If pname:ppEnabledExtensions contains `"VK_EXT_sampler_filter_minmax"` 1526 and the pname:pNext chain includes a 1527 slink:VkPhysicalDeviceVulkan12Features structure, then 1528 sname:VkPhysicalDeviceVulkan12Features::pname:samplerFilterMinmax must: 1529 be ename:VK_TRUE 1530endif::VK_EXT_sampler_filter_minmax[] 1531ifdef::VK_EXT_shader_viewport_index_layer[] 1532 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensions-02835]] 1533 If pname:ppEnabledExtensions contains 1534 `"VK_EXT_shader_viewport_index_layer"` and the pname:pNext chain 1535 includes a slink:VkPhysicalDeviceVulkan12Features structure, then 1536 sname:VkPhysicalDeviceVulkan12Features::pname:shaderOutputViewportIndex 1537 and sname:VkPhysicalDeviceVulkan12Features::pname:shaderOutputLayer 1538 must: both be ename:VK_TRUE 1539endif::VK_EXT_shader_viewport_index_layer[] 1540endif::VK_VERSION_1_2[] 1541ifdef::VK_KHR_portability_subset[] 1542 * [[VUID-VkDeviceCreateInfo-pProperties-04451]] 1543 If the `apiext:VK_KHR_portability_subset` extension is included in 1544 pname:pProperties of flink:vkEnumerateDeviceExtensionProperties, 1545 pname:ppEnabledExtensions must: include "VK_KHR_portability_subset" 1546endif::VK_KHR_portability_subset[] 1547ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 1548 * [[VUID-VkDeviceCreateInfo-shadingRateImage-04478]] 1549 If <<features-shadingRateImage,pname:shadingRateImage>> is enabled, 1550 <<features-pipelineFragmentShadingRate, 1551 pname:pipelineFragmentShadingRate>> must: not be enabled 1552 * [[VUID-VkDeviceCreateInfo-shadingRateImage-04479]] 1553 If <<features-shadingRateImage,pname:shadingRateImage>> is enabled, 1554 <<features-primitiveFragmentShadingRate, 1555 pname:primitiveFragmentShadingRate>> must: not be enabled 1556 * [[VUID-VkDeviceCreateInfo-shadingRateImage-04480]] 1557 If <<features-shadingRateImage,pname:shadingRateImage>> is enabled, 1558 <<features-attachmentFragmentShadingRate, 1559 pname:attachmentFragmentShadingRate>> must: not be enabled 1560endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] 1561ifdef::VK_KHR_fragment_shading_rate,VK_EXT_fragment_density_map[] 1562 * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04481]] 1563 If <<features-fragmentDensityMap,pname:fragmentDensityMap>> is enabled, 1564 <<features-pipelineFragmentShadingRate, 1565 pname:pipelineFragmentShadingRate>> must: not be enabled 1566 * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04482]] 1567 If <<features-fragmentDensityMap,pname:fragmentDensityMap>> is enabled, 1568 <<features-primitiveFragmentShadingRate, 1569 pname:primitiveFragmentShadingRate>> must: not be enabled 1570 * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04483]] 1571 If <<features-fragmentDensityMap,pname:fragmentDensityMap>> is enabled, 1572 <<features-attachmentFragmentShadingRate, 1573 pname:attachmentFragmentShadingRate>> must: not be enabled 1574endif::VK_KHR_fragment_shading_rate,VK_EXT_fragment_density_map[] 1575ifdef::VK_EXT_shader_image_atomic_int64[] 1576 * [[VUID-VkDeviceCreateInfo-None-04896]] 1577 If <<features-sparseImageInt64Atomics, pname:sparseImageInt64Atomics>> 1578 is enabled, <<features-shaderImageInt64Atomics, 1579 pname:shaderImageInt64Atomics>> must: be enabled 1580endif::VK_EXT_shader_image_atomic_int64[] 1581ifdef::VK_EXT_shader_atomic_float[] 1582 * [[VUID-VkDeviceCreateInfo-None-04897]] 1583 If <<features-sparseImageFloat32Atomics, 1584 pname:sparseImageFloat32Atomics>> is enabled, 1585 <<features-shaderImageFloat32Atomics, pname:shaderImageFloat32Atomics>> 1586 must: be enabled 1587 * [[VUID-VkDeviceCreateInfo-None-04898]] 1588 If <<features-sparseImageFloat32AtomicAdd, 1589 pname:sparseImageFloat32AtomicAdd>> is enabled, 1590 <<features-shaderImageFloat32AtomicAdd, 1591 pname:shaderImageFloat32AtomicAdd>> must: be enabled 1592endif::VK_EXT_shader_atomic_float[] 1593ifdef::VK_EXT_shader_atomic_float2[] 1594 * [[VUID-VkDeviceCreateInfo-sparseImageFloat32AtomicMinMax-04975]] 1595 If <<features-sparseImageFloat32AtomicMinMax, 1596 pname:sparseImageFloat32AtomicMinMax>> is enabled, 1597 <<features-shaderImageFloat32AtomicMinMax, 1598 pname:shaderImageFloat32AtomicMinMax>> must: be enabled 1599endif::VK_EXT_shader_atomic_float2[] 1600**** 1601 1602include::{generated}/validity/structs/VkDeviceCreateInfo.txt[] 1603-- 1604 1605[open,refpage='VkDeviceCreateFlags',desc='Reserved for future use',type='flags'] 1606-- 1607include::{generated}/api/flags/VkDeviceCreateFlags.txt[] 1608 1609tname:VkDeviceCreateFlags is a bitmask type for setting a mask, but is 1610currently reserved for future use. 1611-- 1612 1613ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[] 1614[open,refpage='VkDeviceGroupDeviceCreateInfo',desc='Create a logical device from multiple physical devices',type='structs'] 1615-- 1616A logical device can: be created that connects to one or more physical 1617devices by adding a sname:VkDeviceGroupDeviceCreateInfo structure to the 1618pname:pNext chain of slink:VkDeviceCreateInfo. 1619The sname:VkDeviceGroupDeviceCreateInfo structure is defined as: 1620 1621include::{generated}/api/structs/VkDeviceGroupDeviceCreateInfo.txt[] 1622 1623ifdef::VK_KHR_device_group_creation[] 1624or the equivalent 1625 1626include::{generated}/api/structs/VkDeviceGroupDeviceCreateInfoKHR.txt[] 1627endif::VK_KHR_device_group_creation[] 1628 1629 * pname:sType is the type of this structure. 1630 * pname:pNext is `NULL` or a pointer to a structure extending this 1631 structure. 1632 * pname:physicalDeviceCount is the number of elements in the 1633 pname:pPhysicalDevices array. 1634 * pname:pPhysicalDevices is a pointer to an array of physical device 1635 handles belonging to the same device group. 1636 1637The elements of the pname:pPhysicalDevices array are an ordered list of the 1638physical devices that the logical device represents. 1639These must: be a subset of a single device group, and need not be in the 1640same order as they were enumerated. 1641The order of the physical devices in the pname:pPhysicalDevices array 1642determines the _device index_ of each physical device, with element [eq]#i# 1643being assigned a device index of [eq]#i#. 1644Certain commands and structures refer to one or more physical devices by 1645using device indices or _device masks_ formed using device indices. 1646 1647A logical device created without using sname:VkDeviceGroupDeviceCreateInfo, 1648or with pname:physicalDeviceCount equal to zero, is equivalent to a 1649pname:physicalDeviceCount of one and pname:pPhysicalDevices pointing to the 1650pname:physicalDevice parameter to flink:vkCreateDevice. 1651In particular, the device index of that physical device is zero. 1652 1653.Valid Usage 1654**** 1655 * [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00375]] 1656 Each element of pname:pPhysicalDevices must: be unique 1657 * [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00376]] 1658 All elements of pname:pPhysicalDevices must: be in the same device group 1659 as enumerated by flink:vkEnumeratePhysicalDeviceGroups 1660 * [[VUID-VkDeviceGroupDeviceCreateInfo-physicalDeviceCount-00377]] 1661 If pname:physicalDeviceCount is not `0`, the pname:physicalDevice 1662 parameter of flink:vkCreateDevice must: be an element of 1663 pname:pPhysicalDevices 1664**** 1665 1666include::{generated}/validity/structs/VkDeviceGroupDeviceCreateInfo.txt[] 1667-- 1668endif::VK_VERSION_1_1,VK_KHR_device_group_creation[] 1669 1670ifdef::VK_AMD_memory_overallocation_behavior[] 1671[open,refpage='VkDeviceMemoryOverallocationCreateInfoAMD',desc='Specify memory overallocation behavior for a Vulkan device',type='structs'] 1672-- 1673To specify whether device memory allocation is allowed beyond the size 1674reported by slink:VkPhysicalDeviceMemoryProperties, add a 1675slink:VkDeviceMemoryOverallocationCreateInfoAMD structure to the pname:pNext 1676chain of the slink:VkDeviceCreateInfo structure. 1677If this structure is not specified, it is as if the 1678ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD value is used. 1679 1680include::{generated}/api/structs/VkDeviceMemoryOverallocationCreateInfoAMD.txt[] 1681 1682 * pname:sType is the type of this structure. 1683 * pname:pNext is `NULL` or a pointer to a structure extending this 1684 structure. 1685 * pname:overallocationBehavior is the desired overallocation behavior. 1686 1687include::{generated}/validity/structs/VkDeviceMemoryOverallocationCreateInfoAMD.txt[] 1688-- 1689 1690[open,refpage='VkMemoryOverallocationBehaviorAMD',desc='Specify memory overallocation behavior',type='enums'] 1691-- 1692Possible values for 1693slink:VkDeviceMemoryOverallocationCreateInfoAMD::pname:overallocationBehavior 1694include: 1695 1696include::{generated}/api/enums/VkMemoryOverallocationBehaviorAMD.txt[] 1697 1698 * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD lets the 1699 implementation decide if overallocation is allowed. 1700 * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_ALLOWED_AMD specifies 1701 overallocation is allowed if platform permits. 1702 * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DISALLOWED_AMD specifies the 1703 application is not allowed to allocate device memory beyond the heap 1704 sizes reported by slink:VkPhysicalDeviceMemoryProperties. 1705 Allocations that are not explicitly made by the application within the 1706 scope of the Vulkan instance are not accounted for. 1707-- 1708endif::VK_AMD_memory_overallocation_behavior[] 1709 1710ifdef::VK_NV_device_diagnostics_config[] 1711[open,refpage='VkDeviceDiagnosticsConfigCreateInfoNV',desc='Specify diagnostics config for a Vulkan device',type='structs'] 1712-- 1713When using the Nsight^(TM)^ Aftermath SDK, to configure how device crash 1714dumps are created, add a slink:VkDeviceDiagnosticsConfigCreateInfoNV 1715structure to the pname:pNext chain of the slink:VkDeviceCreateInfo 1716structure. 1717 1718include::{generated}/api/structs/VkDeviceDiagnosticsConfigCreateInfoNV.txt[] 1719 1720 * pname:sType is the type of this structure. 1721 * pname:pNext is `NULL` or a pointer to a structure extending this 1722 structure. 1723 * pname:flags is a bitmask of elink:VkDeviceDiagnosticsConfigFlagBitsNV 1724 specifying addtional parameters for configuring diagnostic tools. 1725 1726include::{generated}/validity/structs/VkDeviceDiagnosticsConfigCreateInfoNV.txt[] 1727-- 1728 1729[open,refpage='VkDeviceDiagnosticsConfigFlagBitsNV',desc='Bitmask specifying diagnostics flags',type='enums'] 1730-- 1731Bits which can: be set in 1732slink:VkDeviceDiagnosticsConfigCreateInfoNV::pname:flags include: 1733 1734include::{generated}/api/enums/VkDeviceDiagnosticsConfigFlagBitsNV.txt[] 1735 1736 * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_DEBUG_INFO_BIT_NV 1737 enables the generation of debug information for shaders. 1738 * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_RESOURCE_TRACKING_BIT_NV 1739 enables driver side tracking of resources (images, buffers, etc.) used 1740 to augment the device fault information. 1741 * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_AUTOMATIC_CHECKPOINTS_BIT_NV 1742 enables automatic insertion of <<device-diagnostic-checkpoints, 1743 diagnostic checkpoints>> for draw calls, dispatches, 1744ifdef::VK_NV_ray_tracing[] 1745 trace rays, 1746endif::VK_NV_ray_tracing[] 1747 and copies. 1748 The CPU call stack at the time of the command will be associated as the 1749 marker data for the automatically inserted checkpoints. 1750-- 1751 1752[open,refpage='VkDeviceDiagnosticsConfigFlagsNV',desc='Bitmask of VkDeviceDiagnosticsConfigFlagBitsNV',type='flags'] 1753-- 1754include::{generated}/api/flags/VkDeviceDiagnosticsConfigFlagsNV.txt[] 1755 1756tname:VkDeviceDiagnosticsConfigFlagsNV is a bitmask type for setting a mask 1757of zero or more elink:VkDeviceDiagnosticsConfigFlagBitsNV. 1758-- 1759endif::VK_NV_device_diagnostics_config[] 1760 1761ifdef::VK_EXT_device_memory_report[] 1762[open,refpage='VkDeviceDeviceMemoryReportCreateInfoEXT',desc='Register device memory report callbacks for a Vulkan device',type='structs'] 1763-- 1764To register callbacks for underlying device memory events of type 1765elink:VkDeviceMemoryReportEventTypeEXT, add one or multiple 1766slink:VkDeviceDeviceMemoryReportCreateInfoEXT structures to the pname:pNext 1767chain of the slink:VkDeviceCreateInfo structure. 1768 1769include::{generated}/api/structs/VkDeviceDeviceMemoryReportCreateInfoEXT.txt[] 1770 1771 * pname:sType is the type of this structure. 1772 * pname:pNext is `NULL` or a pointer to a structure extending this 1773 structure. 1774 * pname:flags is 0 and reserved for future use. 1775 * pname:pfnUserCallback is the application callback function to call. 1776 * pname:pUserData is user data to be passed to the callback. 1777 1778The callback may: be called from multiple threads simultaneously. 1779 1780The callback must: be called only once by the implementation when a 1781elink:VkDeviceMemoryReportEventTypeEXT event occurs. 1782 1783[NOTE] 1784.Note 1785==== 1786The callback could be called from a background thread other than the thread 1787calling the Vulkan commands. 1788==== 1789 1790include::{generated}/validity/structs/VkDeviceDeviceMemoryReportCreateInfoEXT.txt[] 1791-- 1792 1793[open,refpage='PFN_vkDeviceMemoryReportCallbackEXT',desc='Application-defined device memory report callback function',type='funcpointers'] 1794-- 1795The prototype for the 1796slink:VkDeviceDeviceMemoryReportCreateInfoEXT::pname:pfnUserCallback 1797function implemented by the application is: 1798 1799include::{generated}/api/funcpointers/PFN_vkDeviceMemoryReportCallbackEXT.txt[] 1800 1801 * pname:pCallbackData contains all the callback related data in the 1802 slink:VkDeviceMemoryReportCallbackDataEXT structure. 1803 * pname:pUserData is the user data provided when the 1804 slink:VkDeviceDeviceMemoryReportCreateInfoEXT was created. 1805 1806The callback must: not make calls to any Vulkan commands. 1807-- 1808 1809[open,refpage='VkDeviceMemoryReportCallbackDataEXT',desc='Structure specifying parameters returned to the callback',type='structs'] 1810-- 1811The definition of sname:VkDeviceMemoryReportCallbackDataEXT is: 1812 1813include::{generated}/api/structs/VkDeviceMemoryReportCallbackDataEXT.txt[] 1814 1815 * pname:sType is the type of this structure. 1816 * pname:pNext is `NULL` or a pointer to a structure extending this 1817 structure. 1818 * pname:flags is 0 and reserved for future use. 1819 * pname:type is a elink:VkDeviceMemoryReportEventTypeEXT type specifying 1820 the type of event reported in this 1821 sname:VkDeviceMemoryReportCallbackDataEXT structure. 1822 * pname:memoryObjectId is the unique id for the underlying memory object 1823 as described below. 1824 * pname:size is the size of the memory object in bytes. 1825 If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, 1826 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT or 1827 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, 1828 pname:size is a valid basetype:VkDeviceSize value. 1829 Otherwise, pname:size is undefined:. 1830 * pname:objectType is a elink:VkObjectType value specifying the type of 1831 the object associated with this device memory report event. 1832 If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, 1833 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT, 1834 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT, 1835 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT or 1836 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, 1837 pname:objectType is a valid elink:VkObjectType enum. 1838 Otherwise, pname:objectType is undefined:. 1839 * pname:objectHandle is the object this device memory report event is 1840 attributed to. 1841 If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, 1842 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT, 1843 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT or 1844 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT, 1845 pname:objectHandle is a valid Vulkan handle of the type associated with 1846 pname:objectType as defined in the <<debugging-object-types, 1847 `VkObjectType` and Vulkan Handle Relationship>> table. 1848 Otherwise, pname:objectHandle is undefined:. 1849 * pname:heapIndex describes which memory heap this device memory 1850 allocation is made from. 1851 If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT 1852 or ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, 1853 pname:heapIndex corresponds to one of the valid heaps from the 1854 slink:VkPhysicalDeviceMemoryProperties structure. 1855 Otherwise, pname:heapIndex is undefined:. 1856 1857pname:memoryObjectId is used to avoid double-counting on the same memory 1858object. 1859 1860If an internally-allocated device memory object or a slink:VkDeviceMemory 1861cannot: be exported, pname:memoryObjectId must: be unique in the 1862slink:VkDevice. 1863 1864If an internally-allocated device memory object or a slink:VkDeviceMemory 1865supports being exported, pname:memoryObjectId must: be unique system wide. 1866 1867If an internal device memory object or a slink:VkDeviceMemory is backed by 1868an imported external memory object, pname:memoryObjectId must: be unique 1869system wide. 1870 1871ifdef::implementation-guide[] 1872.Implementor's Note 1873**** 1874If the heap backing an internally-allocated device memory cannot: be used to 1875back slink:VkDeviceMemory, implementations can: advertise that heap with no 1876types. 1877**** 1878endif::implementation-guide[] 1879 1880[NOTE] 1881.Note 1882==== 1883This structure should only be considered valid during the lifetime of the 1884triggered callback. 1885 1886For ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT and 1887ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT events, 1888pname:objectHandle usually will not yet exist when the application or tool 1889receives the callback. 1890pname:objectHandle will only exist when the create or allocate call that 1891triggered the event returns, and if the allocation or import ends up failing 1892pname:objectHandle will not ever exist. 1893==== 1894 1895include::{generated}/validity/structs/VkDeviceMemoryReportCallbackDataEXT.txt[] 1896-- 1897 1898[open,refpage='VkDeviceMemoryReportFlagsEXT',desc='Reserved for future use',type='flags'] 1899-- 1900include::{generated}/api/flags/VkDeviceMemoryReportFlagsEXT.txt[] 1901 1902tname:VkDeviceMemoryReportFlagsEXT is a bitmask type for setting a mask, but 1903is currently reserved for future use. 1904-- 1905 1906[open,refpage='VkDeviceMemoryReportEventTypeEXT',desc='Events that can occur on a device memory object',type='enums'] 1907-- 1908Possible values of slink:VkDeviceMemoryReportCallbackDataEXT::pname:type, 1909specifying event types which cause the device driver to call the callback, 1910are: 1911 1912include::{generated}/api/enums/VkDeviceMemoryReportEventTypeEXT.txt[] 1913 1914 * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT specifies this 1915 event corresponds to the allocation of an internal device memory object 1916 or a slink:VkDeviceMemory. 1917 * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT specifies this event 1918 corresponds to the deallocation of an internally-allocated device memory 1919 object or a slink:VkDeviceMemory. 1920 * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT specifies this event 1921 corresponds to the import of an external memory object. 1922 * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT specifies this 1923 event is the release of an imported external memory object. 1924 * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT specifies 1925 this event corresponds to the failed allocation of an internal device 1926 memory object or a slink:VkDeviceMemory. 1927-- 1928endif::VK_EXT_device_memory_report[] 1929 1930ifdef::VK_EXT_private_data[] 1931[open,refpage='VkDevicePrivateDataCreateInfoEXT',desc='Reserve private data slots',type='structs'] 1932-- 1933To reserve private data storage slots, add a 1934slink:VkDevicePrivateDataCreateInfoEXT structure to the pname:pNext chain of 1935the slink:VkDeviceCreateInfo structure. 1936Reserving slots in this manner is not strictly necessary, but doing so may: 1937improve performance. 1938 1939include::{generated}/api/structs/VkDevicePrivateDataCreateInfoEXT.txt[] 1940 1941 * pname:sType is the type of this structure. 1942 * pname:pNext is `NULL` or a pointer to a structure extending this 1943 structure. 1944 * pname:privateDataSlotRequestCount is the amount of slots to reserve. 1945 1946include::{generated}/validity/structs/VkDevicePrivateDataCreateInfoEXT.txt[] 1947-- 1948endif::VK_EXT_private_data[] 1949 1950 1951[[devsandqueues-use]] 1952=== Device Use 1953 1954The following is a high-level list of sname:VkDevice uses along with 1955references on where to find more information: 1956 1957 * Creation of queues. 1958 See the <<devsandqueues-queues,Queues>> section below for further 1959 details. 1960 * Creation and tracking of various synchronization constructs. 1961 See <<synchronization,Synchronization and Cache Control>> for further 1962 details. 1963 * Allocating, freeing, and managing memory. 1964 See <<memory,Memory Allocation>> and <<resources,Resource Creation>> for 1965 further details. 1966 * Creation and destruction of command buffers and command buffer pools. 1967 See <<commandbuffers,Command Buffers>> for further details. 1968 * Creation, destruction, and management of graphics state. 1969 See <<pipelines,Pipelines>> and <<descriptorsets,Resource Descriptors>>, 1970 among others, for further details. 1971 1972 1973[[devsandqueues-lost-device]] 1974=== Lost Device 1975 1976A logical device may: become _lost_ for a number of implementation-specific 1977reasons, indicating that pending and future command execution may: fail and 1978cause resources and backing memory to become undefined:. 1979 1980[NOTE] 1981.Note 1982==== 1983Typical reasons for device loss will include things like execution timing 1984out (to prevent denial of service), power management events, platform 1985resource management, implementation errors. 1986 1987Applications not adhering to <<fundamentals-validusage, valid usage>> may 1988also result in device loss being reported, however this is not guaranteed. 1989Even if device loss is reported, the system may be in an unrecoverable 1990state, and further usage of the API is still considered invalid. 1991==== 1992 1993When this happens, certain commands will return ename:VK_ERROR_DEVICE_LOST. 1994After any such event, the logical device is considered _lost_. 1995It is not possible to reset the logical device to a non-lost state, however 1996the lost state is specific to a logical device (sname:VkDevice), and the 1997corresponding physical device (sname:VkPhysicalDevice) may: be otherwise 1998unaffected. 1999 2000In some cases, the physical device may: also be lost, and attempting to 2001create a new logical device will fail, returning ename:VK_ERROR_DEVICE_LOST. 2002This is usually indicative of a problem with the underlying implementation, 2003or its connection to the host. 2004If the physical device has not been lost, and a new logical device is 2005successfully created from that physical device, it must: be in the non-lost 2006state. 2007 2008[NOTE] 2009.Note 2010==== 2011Whilst logical device loss may: be recoverable, in the case of physical 2012device loss, it is unlikely that an application will be able to recover 2013unless additional, unaffected physical devices exist on the system. 2014The error is largely informational and intended only to inform the user that 2015a platform issue has occurred, and should: be investigated further. 2016For example, underlying hardware may: have developed a fault or become 2017physically disconnected from the rest of the system. 2018In many cases, physical device loss may: cause other more serious issues 2019such as the operating system crashing; in which case it may: not be reported 2020via the Vulkan API. 2021==== 2022 2023When a device is lost, its child objects are not implicitly destroyed and 2024their handles are still valid. 2025Those objects must: still be destroyed before their parents or the device 2026can: be destroyed (see the <<fundamentals-objectmodel-lifetime,Object 2027Lifetime>> section). 2028The host address space corresponding to device memory mapped using 2029flink:vkMapMemory is still valid, and host memory accesses to these mapped 2030regions are still valid, but the contents are undefined:. 2031It is still legal to call any API command on the device and child objects. 2032 2033Once a device is lost, command execution may: fail, and commands that return 2034a elink:VkResult may: return ename:VK_ERROR_DEVICE_LOST. 2035Commands that do not allow runtime errors must: still operate correctly for 2036valid usage and, if applicable, return valid data. 2037 2038Commands that wait indefinitely for device execution (namely 2039flink:vkDeviceWaitIdle, flink:vkQueueWaitIdle, flink:vkWaitForFences 2040ifdef::VK_KHR_swapchain[] 2041or flink:vkAcquireNextImageKHR 2042endif::VK_KHR_swapchain[] 2043with a maximum pname:timeout, and flink:vkGetQueryPoolResults with the 2044ename:VK_QUERY_RESULT_WAIT_BIT bit set in pname:flags) must: return in 2045finite time even in the case of a lost device, and return either 2046ename:VK_SUCCESS or ename:VK_ERROR_DEVICE_LOST. 2047For any command that may: return ename:VK_ERROR_DEVICE_LOST, for the purpose 2048of determining whether a command buffer is in the 2049<<commandbuffers-lifecycle, pending state>>, or whether resources are 2050considered in-use by the device, a return value of 2051ename:VK_ERROR_DEVICE_LOST is equivalent to ename:VK_SUCCESS. 2052 2053ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 2054 2055The content of any external memory objects that have been exported from or 2056imported to a lost device become undefined:. 2057Objects on other logical devices or in other APIs which are associated with 2058the same underlying memory resource as the external memory objects on the 2059lost device are unaffected other than their content becoming undefined:. 2060The layout of subresources of images on other logical devices that are bound 2061to sname:VkDeviceMemory objects associated with the same underlying memory 2062resources as external memory objects on the lost device becomes 2063ename:VK_IMAGE_LAYOUT_UNDEFINED. 2064 2065endif::VK_VERSION_1_1,VK_KHR_external_memory[] 2066 2067ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[] 2068 2069The state of sname:VkSemaphore objects on other logical devices created by 2070<<synchronization-semaphores-importing,importing a semaphore payload>> with 2071temporary permanence which was exported from the lost device is undefined:. 2072The state of sname:VkSemaphore objects on other logical devices that 2073permanently share a semaphore payload with a sname:VkSemaphore object on the 2074lost device is undefined:, and remains undefined: following any subsequent 2075signal operations. 2076Implementations must: ensure pending and subsequently submitted wait 2077operations on such semaphores behave as defined in 2078<<synchronization-semaphores-waiting-state,Semaphore State Requirements For 2079Wait Operations>> for external semaphores not in a valid state for a wait 2080operation. 2081 2082endif::VK_VERSION_1_1,VK_KHR_external_semaphore[] 2083 2084ifdef::editing-notes[] 2085[NOTE] 2086.editing-note 2087==== 2088TODO (piman) - I do not think we are very clear about what "`in-use by the 2089device`" means. 2090==== 2091endif::editing-notes[] 2092 2093 2094[[devsandqueues-destruction]] 2095=== Device Destruction 2096 2097[open,refpage='vkDestroyDevice',desc='Destroy a logical device',type='protos'] 2098-- 2099To destroy a device, call: 2100 2101include::{generated}/api/protos/vkDestroyDevice.txt[] 2102 2103 * pname:device is the logical device to destroy. 2104 * pname:pAllocator controls host memory allocation as described in the 2105 <<memory-allocation, Memory Allocation>> chapter. 2106 2107To ensure that no work is active on the device, flink:vkDeviceWaitIdle can: 2108be used to gate the destruction of the device. 2109Prior to destroying a device, an application is responsible for 2110destroying/freeing any Vulkan objects that were created using that device as 2111the first parameter of the corresponding ftext:vkCreate* or 2112ftext:vkAllocate* command. 2113 2114[NOTE] 2115.Note 2116==== 2117The lifetime of each of these objects is bound by the lifetime of the 2118sname:VkDevice object. 2119Therefore, to avoid resource leaks, it is critical that an application 2120explicitly free all of these resources prior to calling 2121fname:vkDestroyDevice. 2122==== 2123 2124.Valid Usage 2125**** 2126 * [[VUID-vkDestroyDevice-device-00378]] 2127 All child objects created on pname:device must: have been destroyed 2128 prior to destroying pname:device 2129 * [[VUID-vkDestroyDevice-device-00379]] 2130 If sname:VkAllocationCallbacks were provided when pname:device was 2131 created, a compatible set of callbacks must: be provided here 2132 * [[VUID-vkDestroyDevice-device-00380]] 2133 If no sname:VkAllocationCallbacks were provided when pname:device was 2134 created, pname:pAllocator must: be `NULL` 2135**** 2136 2137include::{generated}/validity/protos/vkDestroyDevice.txt[] 2138-- 2139 2140 2141[[devsandqueues-queues]] 2142== Queues 2143 2144 2145[[devsandqueues-queueprops]] 2146=== Queue Family Properties 2147 2148As discussed in the <<devsandqueues-physical-device-enumeration,Physical 2149Device Enumeration>> section above, the 2150flink:vkGetPhysicalDeviceQueueFamilyProperties command is used to retrieve 2151details about the queue families and queues supported by a device. 2152 2153Each index in the pname:pQueueFamilyProperties array returned by 2154flink:vkGetPhysicalDeviceQueueFamilyProperties describes a unique queue 2155family on that physical device. 2156These indices are used when creating queues, and they correspond directly 2157with the pname:queueFamilyIndex that is passed to the flink:vkCreateDevice 2158command via the slink:VkDeviceQueueCreateInfo structure as described in the 2159<<devsandqueues-queue-creation,Queue Creation>> section below. 2160 2161Grouping of queue families within a physical device is 2162implementation-dependent. 2163 2164[NOTE] 2165.Note 2166==== 2167The general expectation is that a physical device groups all queues of 2168matching capabilities into a single family. 2169However, while implementations should: do this, it is possible that a 2170physical device may: return two separate queue families with the same 2171capabilities. 2172==== 2173 2174Once an application has identified a physical device with the queue(s) that 2175it desires to use, it will create those queues in conjunction with a logical 2176device. 2177This is described in the following section. 2178 2179 2180[[devsandqueues-queue-creation]] 2181=== Queue Creation 2182 2183[open,refpage='VkQueue',desc='Opaque handle to a queue object',type='handles'] 2184-- 2185Creating a logical device also creates the queues associated with that 2186device. 2187The queues to create are described by a set of slink:VkDeviceQueueCreateInfo 2188structures that are passed to flink:vkCreateDevice in 2189pname:pQueueCreateInfos. 2190 2191Queues are represented by sname:VkQueue handles: 2192 2193include::{generated}/api/handles/VkQueue.txt[] 2194-- 2195 2196[open,refpage='VkDeviceQueueCreateInfo',desc='Structure specifying parameters of a newly created device queue',type='structs'] 2197-- 2198The sname:VkDeviceQueueCreateInfo structure is defined as: 2199 2200include::{generated}/api/structs/VkDeviceQueueCreateInfo.txt[] 2201 2202 * pname:sType is the type of this structure. 2203 * pname:pNext is `NULL` or a pointer to a structure extending this 2204 structure. 2205ifndef::VK_VERSION_1_1[] 2206 * pname:flags is reserved for future use. 2207endif::VK_VERSION_1_1[] 2208ifdef::VK_VERSION_1_1[] 2209 * pname:flags is a bitmask indicating behavior of the queue. 2210endif::VK_VERSION_1_1[] 2211 * pname:queueFamilyIndex is an unsigned integer indicating the index of 2212 the queue family in which to create the queue on this device. 2213 This index corresponds to the index of an element of the 2214 pname:pQueueFamilyProperties array that was returned by 2215 fname:vkGetPhysicalDeviceQueueFamilyProperties. 2216 * pname:queueCount is an unsigned integer specifying the number of queues 2217 to create in the queue family indicated by pname:queueFamilyIndex. 2218 * pname:pQueuePriorities is a pointer to an array of pname:queueCount 2219 normalized floating point values, specifying priorities of work that 2220 will be submitted to each created queue. 2221 See <<devsandqueues-priority,Queue Priority>> for more information. 2222 2223.Valid Usage 2224**** 2225 * [[VUID-VkDeviceQueueCreateInfo-queueFamilyIndex-00381]] 2226 pname:queueFamilyIndex must: be less than 2227 pname:pQueueFamilyPropertyCount returned by 2228 fname:vkGetPhysicalDeviceQueueFamilyProperties 2229 * [[VUID-VkDeviceQueueCreateInfo-queueCount-00382]] 2230 pname:queueCount must: be less than or equal to the pname:queueCount 2231 member of the sname:VkQueueFamilyProperties structure, as returned by 2232 fname:vkGetPhysicalDeviceQueueFamilyProperties in the 2233 pname:pQueueFamilyProperties[queueFamilyIndex] 2234 * [[VUID-VkDeviceQueueCreateInfo-pQueuePriorities-00383]] 2235 Each element of pname:pQueuePriorities must: be between `0.0` and `1.0` 2236 inclusive 2237ifdef::VK_VERSION_1_1[] 2238 * [[VUID-VkDeviceQueueCreateInfo-flags-02861]] 2239 If the <<features-protectedMemory, protected memory>> feature is not 2240 enabled, the ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit of 2241 pname:flags must: not be set 2242 * [[VUID-VkDeviceQueueCreateInfo-flags-06449]] 2243 If pname:flags includes ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, 2244 pname:queueFamilyIndex must: be the index of a queue family that 2245 includes the ename:VK_QUEUE_PROTECTED_BIT capability 2246endif::VK_VERSION_1_1[] 2247**** 2248 2249include::{generated}/validity/structs/VkDeviceQueueCreateInfo.txt[] 2250-- 2251 2252ifdef::VK_VERSION_1_1[] 2253[open,refpage='VkDeviceQueueCreateFlagBits',desc='Bitmask specifying behavior of the queue',type='enums'] 2254-- 2255Bits which can: be set in slink:VkDeviceQueueCreateInfo::pname:flags to 2256specify usage behavior of the queue are: 2257 2258include::{generated}/api/enums/VkDeviceQueueCreateFlagBits.txt[] 2259 2260 * ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT specifies that the device 2261 queue is a protected-capable queue. 2262-- 2263endif::VK_VERSION_1_1[] 2264 2265[open,refpage='VkDeviceQueueCreateFlags',desc='Bitmask of VkDeviceQueueCreateFlagBits',type='flags'] 2266-- 2267include::{generated}/api/flags/VkDeviceQueueCreateFlags.txt[] 2268 2269ifndef::VK_VERSION_1_1[] 2270tname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask, but is 2271currently reserved for future use. 2272endif::VK_VERSION_1_1[] 2273ifdef::VK_VERSION_1_1[] 2274tname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask of zero 2275or more elink:VkDeviceQueueCreateFlagBits. 2276endif::VK_VERSION_1_1[] 2277-- 2278 2279ifdef::VK_EXT_global_priority[] 2280[open,refpage='VkDeviceQueueGlobalPriorityCreateInfoEXT',desc='Specify a system wide priority',type='structs'] 2281-- 2282A queue can: be created with a system-wide priority by adding a 2283sname:VkDeviceQueueGlobalPriorityCreateInfoEXT structure to the pname:pNext 2284chain of slink:VkDeviceQueueCreateInfo. 2285 2286The sname:VkDeviceQueueGlobalPriorityCreateInfoEXT structure is defined as: 2287 2288include::{generated}/api/structs/VkDeviceQueueGlobalPriorityCreateInfoEXT.txt[] 2289 2290 * pname:sType is the type of this structure. 2291 * pname:pNext is `NULL` or a pointer to a structure extending this 2292 structure. 2293 * pname:globalPriority is the system-wide priority associated to this 2294 queue as specified by elink:VkQueueGlobalPriorityEXT 2295 2296A queue created without specifying 2297sname:VkDeviceQueueGlobalPriorityCreateInfoEXT will default to 2298ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT. 2299 2300include::{generated}/validity/structs/VkDeviceQueueGlobalPriorityCreateInfoEXT.txt[] 2301-- 2302 2303[open,refpage='VkQueueGlobalPriorityEXT',desc='Values specifying a system-wide queue priority',type='enums'] 2304-- 2305Possible values of 2306slink:VkDeviceQueueGlobalPriorityCreateInfoEXT::pname:globalPriority, 2307specifying a system-wide priority level are: 2308 2309include::{generated}/api/enums/VkQueueGlobalPriorityEXT.txt[] 2310 2311Priority values are sorted in ascending order. 2312A comparison operation on the enum values can be used to determine the 2313priority order. 2314 2315 * ename:VK_QUEUE_GLOBAL_PRIORITY_LOW_EXT is below the system default. 2316 Useful for non-interactive tasks. 2317 * ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT is the system default 2318 priority. 2319 * ename:VK_QUEUE_GLOBAL_PRIORITY_HIGH_EXT is above the system default. 2320 * ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_EXT is the highest priority. 2321 Useful for critical tasks. 2322-- 2323 2324Queues with higher system priority may: be allotted more processing time 2325than queues with lower priority. 2326An implementation may: allow a higher-priority queue to starve a 2327lower-priority queue until the higher-priority queue has no further commands 2328to execute. 2329 2330Priorities imply no ordering or scheduling constraints. 2331 2332No specific guarantees are made about higher priority queues receiving more 2333processing time or better quality of service than lower priority queues. 2334 2335The global priority level of a queue takes precedence over the per-process 2336queue priority (slink:VkDeviceQueueCreateInfo::pname:pQueuePriorities). 2337 2338Abuse of this feature may: result in starving the rest of the system of 2339implementation resources. 2340Therefore, the driver implementation may: deny requests to acquire a 2341priority above the default priority 2342(ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) if the caller does not have 2343sufficient privileges. 2344In this scenario ename:VK_ERROR_NOT_PERMITTED_EXT is returned. 2345 2346The driver implementation may: fail the queue allocation request if 2347resources required to complete the operation have been exhausted (either by 2348the same process or a different process). 2349In this scenario ename:VK_ERROR_INITIALIZATION_FAILED is returned. 2350 2351ifdef::VK_EXT_global_priority_query[] 2352If the <<features-globalPriorityQuery, pname:globalPriorityQuery>> feature 2353is enabled and the requested global priority is not reported via 2354slink:VkQueueFamilyGlobalPriorityPropertiesEXT, the driver implementation 2355must: fail the queue creation. 2356In this scenario, ename:VK_ERROR_INITIALIZATION_FAILED is returned. 2357endif::VK_EXT_global_priority_query[] 2358endif::VK_EXT_global_priority[] 2359 2360[open,refpage='vkGetDeviceQueue',desc='Get a queue handle from a device',type='protos'] 2361-- 2362To retrieve a handle to a slink:VkQueue object, call: 2363 2364include::{generated}/api/protos/vkGetDeviceQueue.txt[] 2365 2366 * pname:device is the logical device that owns the queue. 2367 * pname:queueFamilyIndex is the index of the queue family to which the 2368 queue belongs. 2369 * pname:queueIndex is the index within this queue family of the queue to 2370 retrieve. 2371 * pname:pQueue is a pointer to a slink:VkQueue object that will be filled 2372 with the handle for the requested queue. 2373 2374ifdef::VK_VERSION_1_1[] 2375fname:vkGetDeviceQueue must: only be used to get queues that were created 2376with the pname:flags parameter of slink:VkDeviceQueueCreateInfo set to zero. 2377To get queues that were created with a non-zero pname:flags parameter use 2378flink:vkGetDeviceQueue2. 2379endif::VK_VERSION_1_1[] 2380 2381.Valid Usage 2382**** 2383 * [[VUID-vkGetDeviceQueue-queueFamilyIndex-00384]] 2384 pname:queueFamilyIndex must: be one of the queue family indices 2385 specified when pname:device was created, via the 2386 slink:VkDeviceQueueCreateInfo structure 2387 * [[VUID-vkGetDeviceQueue-queueIndex-00385]] 2388 pname:queueIndex must: be less than the value of 2389 slink:VkDeviceQueueCreateInfo::pname:queueCount for the queue family 2390 indicated by pname:queueFamilyIndex when pname:device was created 2391 * [[VUID-vkGetDeviceQueue-flags-01841]] 2392 slink:VkDeviceQueueCreateInfo::pname:flags must: have been set to zero 2393 when pname:device was created 2394**** 2395 2396include::{generated}/validity/protos/vkGetDeviceQueue.txt[] 2397-- 2398 2399ifdef::VK_VERSION_1_1[] 2400[open,refpage='vkGetDeviceQueue2',desc='Get a queue handle from a device',type='protos'] 2401-- 2402To retrieve a handle to a slink:VkQueue object with specific 2403tlink:VkDeviceQueueCreateFlags creation flags, call: 2404 2405include::{generated}/api/protos/vkGetDeviceQueue2.txt[] 2406 2407 * pname:device is the logical device that owns the queue. 2408 * pname:pQueueInfo is a pointer to a slink:VkDeviceQueueInfo2 structure, 2409 describing parameters of the device queue to be retrieved. 2410 * pname:pQueue is a pointer to a slink:VkQueue object that will be filled 2411 with the handle for the requested queue. 2412 2413include::{generated}/validity/protos/vkGetDeviceQueue2.txt[] 2414-- 2415 2416[open,refpage='VkDeviceQueueInfo2',desc='Structure specifying the parameters used for device queue creation',type='structs'] 2417-- 2418The sname:VkDeviceQueueInfo2 structure is defined as: 2419 2420include::{generated}/api/structs/VkDeviceQueueInfo2.txt[] 2421 2422 * pname:sType is the type of this structure. 2423 * pname:pNext is `NULL` or a pointer to a structure extending this 2424 structure. 2425 The pname:pNext chain of sname:VkDeviceQueueInfo2 can: be used to 2426 provide additional device queue parameters to fname:vkGetDeviceQueue2. 2427 * pname:flags is a tlink:VkDeviceQueueCreateFlags value indicating the 2428 flags used to create the device queue. 2429 * pname:queueFamilyIndex is the index of the queue family to which the 2430 queue belongs. 2431 * pname:queueIndex is the index within this queue family of the queue to 2432 retrieve. 2433 2434The queue returned by fname:vkGetDeviceQueue2 must: have the same 2435pname:flags value from this structure as that used at device creation time 2436in a slink:VkDeviceQueueCreateInfo structure. 2437If no matching pname:flags were specified at device creation time, then the 2438handle returned in pname:pQueue must: be `NULL`. 2439 2440.Valid Usage 2441**** 2442 * [[VUID-VkDeviceQueueInfo2-queueFamilyIndex-01842]] 2443 pname:queueFamilyIndex must: be one of the queue family indices 2444 specified when pname:device was created, via the 2445 slink:VkDeviceQueueCreateInfo structure 2446 * [[VUID-VkDeviceQueueInfo2-flags-06225]] 2447 pname:flags must: be equal to slink:VkDeviceQueueCreateInfo::pname:flags 2448 for a slink:VkDeviceQueueCreateInfo structure for the queue family 2449 indicated by pname:queueFamilyIndex when pname:device was created 2450 * [[VUID-VkDeviceQueueInfo2-queueIndex-01843]] 2451 pname:queueIndex must: be less than 2452 slink:VkDeviceQueueCreateInfo::pname:queueCount for the corresponding 2453 queue family and flags indicated by pname:queueFamilyIndex and 2454 pname:flags when pname:device was created 2455**** 2456 2457include::{generated}/validity/structs/VkDeviceQueueInfo2.txt[] 2458-- 2459endif::VK_VERSION_1_1[] 2460 2461 2462[[devsandqueues-index]] 2463=== Queue Family Index 2464 2465The queue family index is used in multiple places in Vulkan in order to tie 2466operations to a specific family of queues. 2467 2468When retrieving a handle to the queue via fname:vkGetDeviceQueue, the queue 2469family index is used to select which queue family to retrieve the 2470sname:VkQueue handle from as described in the previous section. 2471 2472When creating a sname:VkCommandPool object (see 2473<<commandbuffers-pools,Command Pools>>), a queue family index is specified 2474in the slink:VkCommandPoolCreateInfo structure. 2475Command buffers from this pool can: only be submitted on queues 2476corresponding to this queue family. 2477 2478When creating sname:VkImage (see <<resources-images,Images>>) and 2479sname:VkBuffer (see <<resources-buffers,Buffers>>) resources, a set of queue 2480families is included in the slink:VkImageCreateInfo and 2481slink:VkBufferCreateInfo structures to specify the queue families that can: 2482access the resource. 2483 2484When inserting a slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier 2485(see <<synchronization-pipeline-barriers>>), a source and destination queue 2486family index is specified to allow the ownership of a buffer or image to be 2487transferred from one queue family to another. 2488See the <<resources-sharing,Resource Sharing>> section for details. 2489 2490 2491[[devsandqueues-priority]] 2492=== Queue Priority 2493 2494Each queue is assigned a priority, as set in the 2495slink:VkDeviceQueueCreateInfo structures when creating the device. 2496The priority of each queue is a normalized floating point value between 0.0 2497and 1.0, which is then translated to a discrete priority level by the 2498implementation. 2499Higher values indicate a higher priority, with 0.0 being the lowest priority 2500and 1.0 being the highest. 2501 2502Within the same device, queues with higher priority may: be allotted more 2503processing time than queues with lower priority. 2504The implementation makes no guarantees with regards to ordering or 2505scheduling among queues with the same priority, other than the constraints 2506defined by any <<synchronization, explicit synchronization primitives>>. 2507The implementation makes no guarantees with regards to queues across 2508different devices. 2509 2510An implementation may: allow a higher-priority queue to starve a 2511lower-priority queue on the same sname:VkDevice until the higher-priority 2512queue has no further commands to execute. 2513The relationship of queue priorities must: not cause queues on one 2514sname:VkDevice to starve queues on another sname:VkDevice. 2515 2516No specific guarantees are made about higher priority queues receiving more 2517processing time or better quality of service than lower priority queues. 2518 2519 2520[[devsandqueues-submission]] 2521=== Queue Submission 2522 2523Work is submitted to a queue via _queue submission_ commands such as 2524ifdef::VK_KHR_synchronization2[] 2525flink:vkQueueSubmit2KHR or 2526endif::VK_KHR_synchronization2[] 2527flink:vkQueueSubmit. 2528Queue submission commands define a set of _queue operations_ to be executed 2529by the underlying physical device, including synchronization with semaphores 2530and fences. 2531 2532Submission commands take as parameters a target queue, zero or more 2533_batches_ of work, and an optional: fence to signal upon completion. 2534Each batch consists of three distinct parts: 2535 2536 . Zero or more semaphores to wait on before execution of the rest of the 2537 batch. 2538 ** If present, these describe a <<synchronization-semaphores-waiting, 2539 semaphore wait operation>>. 2540 . Zero or more work items to execute. 2541 ** If present, these describe a _queue operation_ matching the work 2542 described. 2543 . Zero or more semaphores to signal upon completion of the work items. 2544 ** If present, these describe a <<synchronization-semaphores-signaling, 2545 semaphore signal operation>>. 2546 2547If a fence is present in a queue submission, it describes a 2548<<synchronization-fences-signaling, fence signal operation>>. 2549 2550All work described by a queue submission command must: be submitted to the 2551queue before the command returns. 2552 2553 2554[[devsandqueues-sparsebinding]] 2555==== Sparse Memory Binding 2556 2557In Vulkan it is possible to sparsely bind memory to buffers and images as 2558described in the <<sparsememory,Sparse Resource>> chapter. 2559Sparse memory binding is a queue operation. 2560A queue whose flags include the ename:VK_QUEUE_SPARSE_BINDING_BIT must: be 2561able to support the mapping of a virtual address to a physical address on 2562the device. 2563This causes an update to the page table mappings on the device. 2564This update must: be synchronized on a queue to avoid corrupting page table 2565mappings during execution of graphics commands. 2566By binding the sparse memory resources on queues, all commands that are 2567dependent on the updated bindings are synchronized to only execute after the 2568binding is updated. 2569See the <<synchronization,Synchronization and Cache Control>> chapter for 2570how this synchronization is accomplished. 2571 2572 2573[[devsandqueues-queuedestruction]] 2574=== Queue Destruction 2575 2576Queues are created along with a logical device during fname:vkCreateDevice. 2577All queues associated with a logical device are destroyed when 2578fname:vkDestroyDevice is called on that device. 2579