1// Copyright 2015-2023 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.adoc[] 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.adoc[] 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.adoc[] 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.adoc[] 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.adoc[] 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.adoc[] 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 124ifdef::VK_VERSION_1_3[] 125On implementations that claim support for the <<roadmap-2022, Roadmap 2022>> 126profile, the major and minor version expressed by pname:apiVersion must: be 127at least Vulkan 1.3. 128endif::VK_VERSION_1_3[] 129 130The pname:vendorID and pname:deviceID fields are provided to allow 131applications to adapt to device characteristics that are not adequately 132exposed by other Vulkan queries. 133 134[NOTE] 135.Note 136==== 137These may: include performance profiles, hardware errata, or other 138characteristics. 139==== 140 141The _vendor_ identified by pname:vendorID is the entity responsible for the 142most salient characteristics of the underlying implementation of the 143slink:VkPhysicalDevice being queried. 144 145[NOTE] 146.Note 147==== 148For example, in the case of a discrete GPU implementation, this should: be 149the GPU chipset vendor. 150In the case of a hardware accelerator integrated into a system-on-chip 151(SoC), this should: be the supplier of the silicon IP used to create the 152accelerator. 153==== 154 155If the vendor has a https://pcisig.com/membership/member-companies[PCI 156vendor ID], the low 16 bits of pname:vendorID must: contain that PCI vendor 157ID, and the remaining bits must: be set to zero. 158Otherwise, the value returned must: be a valid Khronos vendor ID, obtained 159as described in the <<vulkan-styleguide,Vulkan Documentation and Extensions: 160Procedures and Conventions>> document in the section "`Registering a Vendor 161ID with Khronos`". 162Khronos vendor IDs are allocated starting at 0x10000, to distinguish them 163from the PCI vendor ID namespace. 164Khronos vendor IDs are symbolically defined in the elink:VkVendorId type. 165 166The vendor is also responsible for the value returned in pname:deviceID. 167If the implementation is driven primarily by a https://pcisig.com/[PCI 168device] with a https://pcisig.com/[PCI device ID], the low 16 bits of 169pname:deviceID must: contain that PCI device ID, and the remaining bits 170must: be set to zero. 171Otherwise, the choice of what values to return may: be dictated by operating 172system or platform policies - but should: uniquely identify both the device 173version and any major configuration options (for example, core count in the 174case of multicore devices). 175 176[NOTE] 177.Note 178==== 179The same device ID should: be used for all physical implementations of that 180device version and configuration. 181For example, all uses of a specific silicon IP GPU version and configuration 182should: use the same device ID, even if those uses occur in different SoCs. 183==== 184 185include::{generated}/validity/structs/VkPhysicalDeviceProperties.adoc[] 186-- 187 188[open,refpage='VkVendorId',desc='Khronos vendor IDs',type='enums'] 189-- 190Khronos vendor IDs which may: be returned in 191slink:VkPhysicalDeviceProperties::pname:vendorID are: 192 193include::{generated}/api/enums/VkVendorId.adoc[] 194 195[NOTE] 196.Note 197==== 198Khronos vendor IDs may be allocated by vendors at any time. 199Only the latest canonical versions of this Specification, of the 200corresponding `vk.xml` API Registry, and of the corresponding 201`{core_header}` header file must: contain all reserved Khronos vendor IDs. 202 203Only Khronos vendor IDs are given symbolic names at present. 204PCI vendor IDs returned by the implementation can be looked up in the 205PCI-SIG database. 206==== 207-- 208 209[open,refpage='VK_MAX_PHYSICAL_DEVICE_NAME_SIZE',desc='Length of a physical device name string',type='consts'] 210-- 211ename:VK_MAX_PHYSICAL_DEVICE_NAME_SIZE is the length in code:char values of 212an array containing a physical device name string, as returned in 213slink:VkPhysicalDeviceProperties::pname:deviceName. 214 215include::{generated}/api/enums/VK_MAX_PHYSICAL_DEVICE_NAME_SIZE.adoc[] 216-- 217 218[open,refpage='VkPhysicalDeviceType',desc='Supported physical device types',type='enums'] 219-- 220The physical device types which may: be returned in 221slink:VkPhysicalDeviceProperties::pname:deviceType are: 222 223include::{generated}/api/enums/VkPhysicalDeviceType.adoc[] 224 225 * ename:VK_PHYSICAL_DEVICE_TYPE_OTHER - the device does not match any 226 other available types. 227 * ename:VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU - the device is typically 228 one embedded in or tightly coupled with the host. 229 * ename:VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU - the device is typically a 230 separate processor connected to the host via an interlink. 231 * ename:VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU - the device is typically a 232 virtual node in a virtualization environment. 233 * ename:VK_PHYSICAL_DEVICE_TYPE_CPU - the device is typically running on 234 the same processors as the host. 235 236The physical device type is advertised for informational purposes only, and 237does not directly affect the operation of the system. 238However, the device type may: correlate with other advertised properties or 239capabilities of the system, such as how many memory heaps there are. 240-- 241 242ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 243[open,refpage='vkGetPhysicalDeviceProperties2',desc='Returns properties of a physical device',type='protos'] 244-- 245To query general properties of physical devices once enumerated, call: 246 247ifdef::VK_VERSION_1_1[] 248include::{generated}/api/protos/vkGetPhysicalDeviceProperties2.adoc[] 249endif::VK_VERSION_1_1[] 250 251ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] 252 253ifdef::VK_KHR_get_physical_device_properties2[] 254include::{generated}/api/protos/vkGetPhysicalDeviceProperties2KHR.adoc[] 255endif::VK_KHR_get_physical_device_properties2[] 256 257 * pname:physicalDevice is the handle to the physical device whose 258 properties will be queried. 259 * pname:pProperties is a pointer to a slink:VkPhysicalDeviceProperties2 260 structure in which properties are returned. 261 262Each structure in pname:pProperties and its pname:pNext chain contains 263members corresponding to implementation-dependent properties, behaviors, or 264limits. 265fname:vkGetPhysicalDeviceProperties2 fills in each member to specify the 266corresponding value for the implementation. 267 268include::{generated}/validity/protos/vkGetPhysicalDeviceProperties2.adoc[] 269-- 270 271[open,refpage='VkPhysicalDeviceProperties2',desc='Structure specifying physical device properties',type='structs'] 272-- 273The sname:VkPhysicalDeviceProperties2 structure is defined as: 274 275include::{generated}/api/structs/VkPhysicalDeviceProperties2.adoc[] 276 277ifdef::VK_KHR_get_physical_device_properties2[] 278or the equivalent 279 280include::{generated}/api/structs/VkPhysicalDeviceProperties2KHR.adoc[] 281endif::VK_KHR_get_physical_device_properties2[] 282 283 * pname:sType is a elink:VkStructureType value identifying this structure. 284 * pname:pNext is `NULL` or a pointer to a structure extending this 285 structure. 286 * pname:properties is a slink:VkPhysicalDeviceProperties structure 287 describing properties of the physical device. 288 This structure is written with the same values as if it were written by 289 flink:vkGetPhysicalDeviceProperties. 290 291The pname:pNext chain of this structure is used to extend the structure with 292properties defined by extensions. 293 294include::{generated}/validity/structs/VkPhysicalDeviceProperties2.adoc[] 295-- 296 297ifdef::VK_VERSION_1_2[] 298[open,refpage='VkPhysicalDeviceVulkan11Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.1',type='structs'] 299-- 300The sname:VkPhysicalDeviceVulkan11Properties structure is defined as: 301 302include::{generated}/api/structs/VkPhysicalDeviceVulkan11Properties.adoc[] 303 304 * pname:sType is a elink:VkStructureType value identifying this structure. 305 * pname:pNext is `NULL` or a pointer to a structure extending this 306 structure. 307 308:anchor-prefix: 309include::{chapters}/devsandqueues.adoc[tag=VK_KHR_external_memory_capabilities-properties] 310 * [[{anchor-prefix}limits-subgroup-size]] pname:subgroupSize is the 311 default number of invocations in each subgroup. 312 pname:subgroupSize is at least 1 if any of the physical device's queues 313 support ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT. 314 pname:subgroupSize is a power-of-two. 315 * [[{anchor-prefix}limits-subgroupSupportedStages]] 316 pname:subgroupSupportedStages is a bitfield of 317 elink:VkShaderStageFlagBits describing the shader stages that 318 <<shaders-group-operations, group operations>> with 319 <<shaders-scope-subgroup, subgroup scope>> are supported in. 320 pname:subgroupSupportedStages will have the 321 ename:VK_SHADER_STAGE_COMPUTE_BIT bit set if any of the physical 322 device's queues support ename:VK_QUEUE_COMPUTE_BIT. 323 * pname:subgroupSupportedOperations is a bitmask of 324 elink:VkSubgroupFeatureFlagBits specifying the sets of 325 <<shaders-group-operations, group operations>> with 326 <<shaders-scope-subgroup, subgroup scope>> supported on this device. 327 pname:subgroupSupportedOperations will have the 328 ename:VK_SUBGROUP_FEATURE_BASIC_BIT bit set if any of the physical 329 device's queues support ename:VK_QUEUE_GRAPHICS_BIT or 330 ename:VK_QUEUE_COMPUTE_BIT. 331 * [[{anchor-prefix}limits-subgroupQuadOperationsInAllStages]] 332 pname:subgroupQuadOperationsInAllStages is a boolean specifying whether 333 <<shaders-quad-operations,quad group operations>> are available in all 334 stages, or are restricted to fragment and compute stages. 335include::{chapters}/limits.adoc[tag=VK_KHR_maintenance2-properties] 336include::{chapters}/limits.adoc[tag=VK_KHR_multiview-properties] 337include::{chapters}/limits.adoc[tag=VK_KHR_protected_memory-properties] 338include::{chapters}/limits.adoc[tag=VK_KHR_maintenance3-properties] 339 340:refpage: VkPhysicalDeviceVulkan11Properties 341include::{chapters}/limits.adoc[tag=limits_desc] 342 343These properties correspond to Vulkan 1.1 functionality. 344 345The members of sname:VkPhysicalDeviceVulkan11Properties have the same values 346as the corresponding members of slink:VkPhysicalDeviceIDProperties, 347slink:VkPhysicalDeviceSubgroupProperties, 348slink:VkPhysicalDevicePointClippingProperties, 349slink:VkPhysicalDeviceMultiviewProperties, 350slink:VkPhysicalDeviceProtectedMemoryProperties, and 351slink:VkPhysicalDeviceMaintenance3Properties. 352 353include::{generated}/validity/structs/VkPhysicalDeviceVulkan11Properties.adoc[] 354-- 355 356[open,refpage='VkPhysicalDeviceVulkan12Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.2',type='structs'] 357-- 358The sname:VkPhysicalDeviceVulkan12Properties structure is defined as: 359 360include::{generated}/api/structs/VkPhysicalDeviceVulkan12Properties.adoc[] 361 362 * pname:sType is a elink:VkStructureType value identifying this structure. 363 * pname:pNext is `NULL` or a pointer to a structure extending this 364 structure. 365 366:anchor-prefix: 367include::{chapters}/devsandqueues.adoc[tag=VK_KHR_driver_properties-properties] 368include::{chapters}/limits.adoc[tag=VK_KHR_shader_float_controls-properties] 369include::{chapters}/limits.adoc[tag=VK_EXT_descriptor_indexing-properties] 370include::{chapters}/limits.adoc[tag=VK_KHR_depth_stencil_resolve-properties] 371include::{chapters}/limits.adoc[tag=VK_EXT_sampler_filter_minmax-properties] 372include::{chapters}/limits.adoc[tag=VK_KHR_timeline_semaphore-properties] 373 * [[limits-framebufferIntegerColorSampleCounts]] 374 pname:framebufferIntegerColorSampleCounts is a bitmask of 375 elink:VkSampleCountFlagBits indicating the color sample counts that are 376 supported for all framebuffer color attachments with integer formats. 377 378:refpage: VkPhysicalDeviceVulkan12Properties 379include::{chapters}/limits.adoc[tag=limits_desc] 380 381These properties correspond to Vulkan 1.2 functionality. 382 383The members of sname:VkPhysicalDeviceVulkan12Properties must: have the same 384values as the corresponding members of 385slink:VkPhysicalDeviceDriverProperties, 386slink:VkPhysicalDeviceFloatControlsProperties, 387slink:VkPhysicalDeviceDescriptorIndexingProperties, 388slink:VkPhysicalDeviceDepthStencilResolveProperties, 389slink:VkPhysicalDeviceSamplerFilterMinmaxProperties, and 390slink:VkPhysicalDeviceTimelineSemaphoreProperties. 391 392include::{generated}/validity/structs/VkPhysicalDeviceVulkan12Properties.adoc[] 393-- 394endif::VK_VERSION_1_2[] 395 396ifdef::VKSC_VERSION_1_0[] 397[open,refpage='VkPhysicalDeviceVulkanSC10Properties',desc='Structure describing safety critical properties supported by an implementation',type='structs'] 398-- 399The sname:VkPhysicalDeviceVulkanSC10Properties structure is defined as: 400 401include::{generated}/api/structs/VkPhysicalDeviceVulkanSC10Properties.adoc[] 402 403:anchor-prefix: 404 * pname:sType is a elink:VkStructureType value identifying this structure. 405 * pname:pNext is `NULL` or a pointer to a structure extending this 406 structure. 407 * [[limits-deviceNoDynamicHostAllocations]] 408 pname:deviceNoDynamicHostAllocations indicates whether the 409 implementation will perform dynamic host memory allocations for physical 410 or logical device commands. 411 If pname:deviceNoDynamicHostAllocations is ename:VK_TRUE the 412 implementation will allocate host memory for objects based on the 413 provided slink:VkDeviceObjectReservationCreateInfo limits during 414 flink:vkCreateDevice. 415 Under valid API usage, ename:VK_ERROR_OUT_OF_HOST_MEMORY may: only be 416 returned by commands which do not explicitly disallow it. 417 * [[limits-deviceDestroyFreesMemory]] pname:deviceDestroyFreesMemory 418 indicates whether destroying the device frees all memory resources back 419 to the system. 420 * [[limits-commandPoolMultipleCommandBuffersRecording]] 421 pname:commandPoolMultipleCommandBuffersRecording indicates whether 422 multiple command buffers from the same command pool can: be in the 423 <<commandbuffers-lifecycle, recording state>> at the same time. 424 * [[limits-commandPoolResetCommandBuffer]] 425 pname:commandPoolResetCommandBuffer indicates whether command buffers 426 support flink:vkResetCommandBuffer, and flink:vkBeginCommandBuffer when 427 not in the <<commandbuffers-lifecycle, initial state>>. 428 * [[limits-commandBufferSimultaneousUse]] 429 pname:commandBufferSimultaneousUse indicates whether command buffers 430 support ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT. 431 * [[limits-secondaryCommandBufferNullOrImagelessFramebuffer]] 432 pname:secondaryCommandBufferNullOrImagelessFramebuffer indicates whether 433 the pname:framebuffer member of sname:VkCommandBufferInheritanceInfo 434 may: be equal to dlink:VK_NULL_HANDLE or be created with a 435 slink:VkFramebufferCreateInfo::pname:flags value that includes 436 ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT if the command buffer will be 437 executed within a render pass instance. 438 * [[limits-recycleDescriptorSetMemory]] pname:recycleDescriptorSetMemory 439 indicates whether descriptor pools are able to immediately reuse pool 440 memory from descriptor sets that have been freed. 441 If this is ename:VK_FALSE, then memory may: only be reallocated after 442 flink:vkResetDescriptorPool is called. 443 * [[limits-recyclePipelineMemory]] pname:recyclePipelineMemory indicates 444 whether the memory for a pipeline is available for reuse by new 445 pipelines after the pipeline is destroyed. 446 * [[limits-maxRenderPassSubpasses]] pname:maxRenderPassSubpasses is the 447 maximum number of subpasses in a render pass. 448 * [[limits-maxRenderPassDependencies]] pname:maxRenderPassDependencies is 449 the maximum number of dependencies in a render pass. 450 * [[limits-maxSubpassInputAttachments]] pname:maxSubpassInputAttachments 451 is the maximum number of input attachments in a subpass. 452 * [[limits-maxSubpassPreserveAttachments]] 453 pname:maxSubpassPreserveAttachments is the maximum number of preserve 454 attachments in a subpass. 455 * [[limits-maxFramebufferAttachments]] pname:maxFramebufferAttachments is 456 the maximum number of attachments in a framebuffer, as well as the 457 maximum number of attachments in a render pass. 458 * [[limits-maxDescriptorSetLayoutBindings]] 459 pname:maxDescriptorSetLayoutBindings is the maximum number of bindings 460 in a descriptor set layout. 461 * [[limits-maxQueryFaultCount]] pname:maxQueryFaultCount is the maximum 462 number of faults that the implementation can: record, to be reported via 463 flink:vkGetFaultData. 464 * [[limits-maxCallbackFaultCount]] pname:maxCallbackFaultCount is the 465 maximum number of faults that the implementation can: report via a 466 single call to tlink:PFN_vkFaultCallbackFunction. 467 * [[limits-maxCommandPoolCommandBuffers]] 468 pname:maxCommandPoolCommandBuffers is the maximum number of command 469 buffers that can: be allocated from a single command pool. 470 * [[limits-maxCommandBufferSize]] pname:maxCommandBufferSize is the 471 maximum supported size of a single command buffer in bytes. 472 Applications can: use flink:vkGetCommandPoolMemoryConsumption to compare 473 a command buffer's current memory usage to this limit. 474 475[NOTE] 476.Note 477==== 478Implementations that do not have a fixed upper bound on the number of 479command buffers that may: be allocated from a command pool can: report 4800xFFFFFFFFU for pname:maxCommandPoolCommandBuffers. 481 482Implementations that do not have a fixed upper bound on the command buffer 483size can: report code:UINT64_MAX for pname:maxCommandBufferSize. 484==== 485 486:refpage: VkPhysicalDeviceVulkanSC10Properties 487include::{chapters}/limits.adoc[tag=limits_desc] 488 489These properties correspond to Vulkan SC 1.0 functionality. 490 491ifdef::hidden[] 492// tag::scaddition[] 493 * slink:VkPhysicalDeviceVulkanSC10Properties <<SCID-1>> 494// end::scaddition[] 495endif::hidden[] 496 497include::{generated}/validity/structs/VkPhysicalDeviceVulkanSC10Properties.adoc[] 498-- 499endif::VKSC_VERSION_1_0[] 500 501ifdef::VK_VERSION_1_3[] 502[open,refpage='VkPhysicalDeviceVulkan13Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.3',type='structs'] 503-- 504The sname:VkPhysicalDeviceVulkan13Properties structure is defined as: 505 506include::{generated}/api/structs/VkPhysicalDeviceVulkan13Properties.adoc[] 507 508 * pname:sType is a elink:VkStructureType value identifying this structure. 509 * pname:pNext is `NULL` or a pointer to a structure extending this 510 structure. 511 512:anchor-prefix: 513include::{chapters}/limits.adoc[tag=VK_EXT_subgroup_size_control-properties] 514include::{chapters}/limits.adoc[tag=VK_EXT_inline_uniform_block-properties] 515 * [[{anchor-prefix}limits-maxInlineUniformTotalSize]] 516 pname:maxInlineUniformTotalSize is the maximum total size in bytes of 517 all inline uniform block bindings, across all pipeline shader stages and 518 descriptor set numbers, that can: be included in a pipeline layout. 519 Descriptor bindings with a descriptor type of 520 ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK count against this limit. 521include::{chapters}/devsandqueues.adoc[tag=VK_KHR_shader_integer_dot_product-properties] 522include::{chapters}/limits.adoc[tag=VK_EXT_texel_buffer_alignment-properties] 523include::{chapters}/limits.adoc[tag=VK_KHR_maintenance4-properties] 524 525:refpage: VkPhysicalDeviceVulkan13Properties 526include::{chapters}/limits.adoc[tag=limits_desc] 527 528These properties correspond to Vulkan 1.3 functionality. 529 530The members of sname:VkPhysicalDeviceVulkan13Properties must: have the same 531values as the corresponding members of 532slink:VkPhysicalDeviceInlineUniformBlockProperties and 533slink:VkPhysicalDeviceSubgroupSizeControlProperties. 534 535include::{generated}/validity/structs/VkPhysicalDeviceVulkan13Properties.adoc[] 536-- 537endif::VK_VERSION_1_3[] 538 539ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 540[open,refpage='VkPhysicalDeviceIDProperties',desc='Structure specifying IDs related to the physical device',type='structs'] 541-- 542The sname:VkPhysicalDeviceIDProperties structure is defined as: 543 544include::{generated}/api/structs/VkPhysicalDeviceIDProperties.adoc[] 545 546ifdef::VK_KHR_external_memory_capabilities[] 547or the equivalent 548 549include::{generated}/api/structs/VkPhysicalDeviceIDPropertiesKHR.adoc[] 550endif::VK_KHR_external_memory_capabilities[] 551 552 * pname:sType is a elink:VkStructureType value identifying this structure. 553 * pname:pNext is `NULL` or a pointer to a structure extending this 554 structure. 555 556// Must have preceding whitespace 557ifdef::VK_VERSION_1_2[:anchor-prefix: extension-] 558ifndef::VK_VERSION_1_2[:anchor-prefix:] 559// tag::VK_KHR_external_memory_capabilities-properties[] 560 * pname:deviceUUID is an array of ename:VK_UUID_SIZE code:uint8_t values 561 representing a universally unique identifier for the device. 562 * pname:driverUUID is an array of ename:VK_UUID_SIZE code:uint8_t values 563 representing a universally unique identifier for the driver build in use 564 by the device. 565 * pname:deviceLUID is an array of ename:VK_LUID_SIZE code:uint8_t values 566 representing a locally unique identifier for the device. 567 * pname:deviceNodeMask is a code:uint32_t bitfield identifying the node 568 within a linked device adapter corresponding to the device. 569 * pname:deviceLUIDValid is a boolean value that will be ename:VK_TRUE if 570 pname:deviceLUID contains a valid LUID and pname:deviceNodeMask contains 571 a valid node mask, and ename:VK_FALSE if they do not. 572// end::VK_KHR_external_memory_capabilities-properties[] 573 574:refpage: VkPhysicalDeviceIDProperties 575include::{chapters}/limits.adoc[tag=limits_desc] 576 577pname:deviceUUID must: be immutable for a given device across instances, 578processes, driver APIs, driver versions, and system reboots. 579 580Applications can: compare the pname:driverUUID value across instance and 581process boundaries, and can: make similar queries in external APIs to 582determine whether they are capable of sharing memory objects and resources 583using them with the device. 584 585pname:deviceUUID and/or pname:driverUUID must: be used to determine whether 586a particular external object can be shared between driver components, where 587such a restriction exists as defined in the compatibility table for the 588particular object type: 589 590ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 591 * <<external-memory-handle-types-compatibility,External memory handle 592 types compatibility>> 593endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] 594ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] 595 * <<external-semaphore-handle-types-compatibility,External semaphore 596 handle types compatibility>> 597endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] 598ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] 599 * <<external-fence-handle-types-compatibility,External fence handle types 600 compatibility>> 601endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] 602 603If pname:deviceLUIDValid is ename:VK_FALSE, the values of pname:deviceLUID 604and pname:deviceNodeMask are undefined:. 605If pname:deviceLUIDValid is ename:VK_TRUE and Vulkan is running on the 606Windows operating system, the contents of pname:deviceLUID can: be cast to 607an code:LUID object and must: be equal to the locally unique identifier of a 608code:IDXGIAdapter1 object that corresponds to pname:physicalDevice. 609If pname:deviceLUIDValid is ename:VK_TRUE, pname:deviceNodeMask must: 610contain exactly one bit. 611If Vulkan is running on an operating system that supports the Direct3D 12 612API and pname:physicalDevice corresponds to an individual device in a linked 613device adapter, pname:deviceNodeMask identifies the Direct3D 12 node 614corresponding to pname:physicalDevice. 615Otherwise, pname:deviceNodeMask must: be `1`. 616 617[NOTE] 618.Note 619==== 620Although they have identical descriptions, 621slink:VkPhysicalDeviceIDProperties::pname:deviceUUID may differ from 622slink:VkPhysicalDeviceProperties2::pname:pipelineCacheUUID. 623The former is intended to identify and correlate devices across API and 624driver boundaries, while the latter is used to identify a compatible device 625and driver combination to use when serializing and de-serializing pipeline 626state. 627 628Implementations should: return pname:deviceUUID values which are likely to 629be unique even in the presence of multiple Vulkan implementations (such as a 630GPU driver and a software renderer; two drivers for different GPUs; or the 631same Vulkan driver running on two logically different devices). 632 633Khronos' conformance testing is unable to guarantee that pname:deviceUUID 634values are actually unique, so implementors should: make their own best 635efforts to ensure this. 636In particular, hard-coded pname:deviceUUID values, especially all-`0` bits, 637should: never be used. 638 639A combination of values unique to the vendor, the driver, and the hardware 640environment can be used to provide a pname:deviceUUID which is unique to a 641high degree of certainty. 642Some possible inputs to such a computation are: 643 644 * Information reported by flink:vkGetPhysicalDeviceProperties 645 * PCI device ID (if defined) 646 * PCI bus ID, or similar system configuration information. 647 * Driver binary checksums. 648==== 649 650 651[NOTE] 652.Note 653==== 654While slink:VkPhysicalDeviceIDProperties::pname:deviceUUID is specified to 655remain consistent across driver versions and system reboots, it is not 656intended to be usable as a serializable persistent identifier for a device. 657It may change when a device is physically added to, removed from, or moved 658to a different connector in a system while that system is powered down. 659Further, there is no reasonable way to verify with conformance testing that 660a given device retains the same UUID in a given system across all driver 661versions supported in that system. 662While implementations should make every effort to report consistent device 663UUIDs across driver versions, applications should avoid relying on the 664persistence of this value for uses other than identifying compatible devices 665for external object sharing purposes. 666==== 667 668include::{generated}/validity/structs/VkPhysicalDeviceIDProperties.adoc[] 669-- 670 671[open,refpage='VK_UUID_SIZE',desc='Length of a universally unique device or driver build identifier',type='consts'] 672-- 673ename:VK_UUID_SIZE is the length in code:uint8_t values of an array 674containing a universally unique device or driver build identifier, as 675returned in slink:VkPhysicalDeviceIDProperties::pname:deviceUUID and 676slink:VkPhysicalDeviceIDProperties::pname:driverUUID. 677 678include::{generated}/api/enums/VK_UUID_SIZE.adoc[] 679-- 680 681[open,refpage='VK_LUID_SIZE',desc='Length of a locally unique device identifier',type='consts',alias='VK_LUID_SIZE_KHR'] 682-- 683ename:VK_LUID_SIZE is the length in code:uint8_t values of an array 684containing a locally unique device identifier, as returned in 685slink:VkPhysicalDeviceIDProperties::pname:deviceLUID. 686 687include::{generated}/api/enums/VK_LUID_SIZE.adoc[] 688 689ifdef::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 690or the equivalent 691 692include::{generated}/api/enums/VK_LUID_SIZE_KHR.adoc[] 693endif::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 694-- 695endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] 696 697ifdef::VK_VERSION_1_2,VK_KHR_driver_properties[] 698[open,refpage='VkPhysicalDeviceDriverProperties',desc='Structure containing driver identification information',type='structs',alias='VkPhysicalDeviceDriverPropertiesKHR'] 699-- 700The sname:VkPhysicalDeviceDriverProperties structure is defined as: 701 702include::{generated}/api/structs/VkPhysicalDeviceDriverProperties.adoc[] 703 704ifdef::VK_KHR_driver_properties[] 705or the equivalent 706 707include::{generated}/api/structs/VkPhysicalDeviceDriverPropertiesKHR.adoc[] 708endif::VK_KHR_driver_properties[] 709 710 * pname:sType is a elink:VkStructureType value identifying this structure. 711 * pname:pNext is `NULL` or a pointer to a structure extending this 712 structure. 713 714// Must have preceding whitespace 715ifdef::VK_VERSION_1_2[:anchor-prefix: extension-] 716ifndef::VK_VERSION_1_2[:anchor-prefix:] 717// tag::VK_KHR_driver_properties-properties[] 718 * pname:driverID is a unique identifier for the driver of the physical 719 device. 720 * pname:driverName is an array of ename:VK_MAX_DRIVER_NAME_SIZE code:char 721 containing a null-terminated UTF-8 string which is the name of the 722 driver. 723 * pname:driverInfo is an array of ename:VK_MAX_DRIVER_INFO_SIZE code:char 724 containing a null-terminated UTF-8 string with additional information 725 about the driver. 726 * pname:conformanceVersion is the version of the Vulkan conformance test 727 this driver is conformant against (see slink:VkConformanceVersion). 728// end::VK_KHR_driver_properties-properties[] 729 730:refpage: VkPhysicalDeviceDriverProperties 731include::{chapters}/limits.adoc[tag=limits_desc] 732 733These are properties of the driver corresponding to a physical device. 734 735pname:driverID must: be immutable for a given driver across instances, 736processes, driver versions, and system reboots. 737 738include::{generated}/validity/structs/VkPhysicalDeviceDriverProperties.adoc[] 739-- 740 741[open,refpage='VkDriverId',desc='Khronos driver IDs',type='enums',alias='VkDriverIdKHR'] 742-- 743Khronos driver IDs which may: be returned in 744slink:VkPhysicalDeviceDriverProperties::pname:driverID are: 745 746include::{generated}/api/enums/VkDriverId.adoc[] 747 748ifdef::VK_KHR_driver_properties[] 749or the equivalent 750 751include::{generated}/api/enums/VkDriverIdKHR.adoc[] 752endif::VK_KHR_driver_properties[] 753 754[NOTE] 755.Note 756==== 757Khronos driver IDs may be allocated by vendors at any time. 758There may be multiple driver IDs for the same vendor, representing different 759drivers (for e.g. different platforms, proprietary or open source, etc.). 760Only the latest canonical versions of this Specification, of the 761corresponding `vk.xml` API Registry, and of the corresponding 762`{core_header}` header file must: contain all reserved Khronos driver IDs. 763 764Only driver IDs registered with Khronos are given symbolic names. 765There may: be unregistered driver IDs returned. 766==== 767-- 768 769[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'] 770-- 771ename:VK_MAX_DRIVER_NAME_SIZE is the length in code:char values of an array 772containing a driver name string, as returned in 773slink:VkPhysicalDeviceDriverProperties::pname:driverName. 774 775include::{generated}/api/enums/VK_MAX_DRIVER_NAME_SIZE.adoc[] 776 777ifdef::VK_KHR_driver_properties[] 778or the equivalent 779 780include::{generated}/api/enums/VK_MAX_DRIVER_NAME_SIZE_KHR.adoc[] 781endif::VK_KHR_driver_properties[] 782-- 783 784[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'] 785-- 786ename:VK_MAX_DRIVER_INFO_SIZE is the length in code:char values of an array 787containing a driver information string, as returned in 788slink:VkPhysicalDeviceDriverProperties::pname:driverInfo. 789 790include::{generated}/api/enums/VK_MAX_DRIVER_INFO_SIZE.adoc[] 791 792ifdef::VK_KHR_driver_properties[] 793or the equivalent 794 795include::{generated}/api/enums/VK_MAX_DRIVER_INFO_SIZE_KHR.adoc[] 796endif::VK_KHR_driver_properties[] 797-- 798 799[open,refpage='VkConformanceVersion',desc='Structure containing the conformance test suite version the implementation is compliant with',type='structs',alias='VkConformanceVersionKHR'] 800-- 801The conformance test suite version an implementation is compliant with is 802described with the sname:VkConformanceVersion structure: 803 804include::{generated}/api/structs/VkConformanceVersion.adoc[] 805 806ifdef::VK_KHR_driver_properties[] 807or the equivalent 808 809include::{generated}/api/structs/VkConformanceVersionKHR.adoc[] 810endif::VK_KHR_driver_properties[] 811 812 * pname:major is the major version number of the conformance test suite. 813 * pname:minor is the minor version number of the conformance test suite. 814 * pname:subminor is the subminor version number of the conformance test 815 suite. 816 * pname:patch is the patch version number of the conformance test suite. 817 818include::{generated}/validity/structs/VkConformanceVersion.adoc[] 819-- 820endif::VK_VERSION_1_2,VK_KHR_driver_properties[] 821 822ifdef::VK_EXT_pci_bus_info[] 823[open,refpage='VkPhysicalDevicePCIBusInfoPropertiesEXT',desc='Structure containing PCI bus information of a physical device',type='structs'] 824-- 825The sname:VkPhysicalDevicePCIBusInfoPropertiesEXT structure is defined as: 826 827include::{generated}/api/structs/VkPhysicalDevicePCIBusInfoPropertiesEXT.adoc[] 828 829 * pname:sType is a elink:VkStructureType value identifying this structure. 830 * pname:pNext is `NULL` or a pointer to a structure extending this 831 structure. 832 * pname:pciDomain is the PCI bus domain. 833 * pname:pciBus is the PCI bus identifier. 834 * pname:pciDevice is the PCI device identifier. 835 * pname:pciFunction is the PCI device function identifier. 836 837:refpage: VkPhysicalDevicePCIBusInfoPropertiesEXT 838include::{chapters}/limits.adoc[tag=limits_desc] 839 840These are properties of the PCI bus information of a physical device. 841 842include::{generated}/validity/structs/VkPhysicalDevicePCIBusInfoPropertiesEXT.adoc[] 843-- 844endif::VK_EXT_pci_bus_info[] 845 846ifdef::VK_EXT_physical_device_drm[] 847[open,refpage='VkPhysicalDeviceDrmPropertiesEXT',desc='Structure containing DRM information of a physical device',type='structs'] 848-- 849The sname:VkPhysicalDeviceDrmPropertiesEXT structure is defined as: 850 851include::{generated}/api/structs/VkPhysicalDeviceDrmPropertiesEXT.adoc[] 852 853 * pname:sType is a elink:VkStructureType value identifying this structure. 854 * pname:pNext is `NULL` or a pointer to a structure extending this 855 structure. 856 * pname:hasPrimary is a boolean indicating whether the physical device has 857 a DRM primary node. 858 * pname:hasRender is a boolean indicating whether the physical device has 859 a DRM render node. 860 * pname:primaryMajor is the DRM primary node major number, if any. 861 * pname:primaryMinor is the DRM primary node minor number, if any. 862 * pname:renderMajor is the DRM render node major number, if any. 863 * pname:renderMinor is the DRM render node minor number, if any. 864 865:refpage: VkPhysicalDeviceDrmPropertiesEXT 866include::{chapters}/limits.adoc[tag=limits_desc] 867 868These are properties of the DRM information of a physical device. 869 870include::{generated}/validity/structs/VkPhysicalDeviceDrmPropertiesEXT.adoc[] 871-- 872endif::VK_EXT_physical_device_drm[] 873endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 874 875ifdef::VK_VERSION_1_3,VK_KHR_shader_integer_dot_product[] 876[open,refpage='VkPhysicalDeviceShaderIntegerDotProductProperties',desc='Structure containing information about integer dot product support for a physical device',type='structs',alias='VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR'] 877-- 878The sname:VkPhysicalDeviceShaderIntegerDotProductProperties structure is 879defined as: 880 881include::{generated}/api/structs/VkPhysicalDeviceShaderIntegerDotProductProperties.adoc[] 882 883ifdef::VK_KHR_shader_integer_dot_product[] 884or the equivalent 885 886include::{generated}/api/structs/VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR.adoc[] 887endif::VK_KHR_shader_integer_dot_product[] 888 889 * pname:sType is a elink:VkStructureType value identifying this structure. 890 * pname:pNext is `NULL` or a pointer to a structure extending this 891 structure. 892 893// Must have preceding whitespace 894ifdef::VK_VERSION_1_3[:anchor-prefix: extension-] 895ifndef::VK_VERSION_1_3[:anchor-prefix:] 896// NOTE: none of these properties currently have anchors, so the 897// {anchor-prefix} is not used in the property descriptions. 898// tag::VK_KHR_shader_integer_dot_product-properties[] 899 * pname:integerDotProduct8BitUnsignedAccelerated is a boolean that will be 900 ename:VK_TRUE if the support for 8-bit unsigned dot product operations 901 using the code:OpUDotKHR SPIR-V instruction is accelerated 902 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 903 * pname:integerDotProduct8BitSignedAccelerated is a boolean that will be 904 ename:VK_TRUE if the support for 8-bit signed dot product operations 905 using the code:OpSDotKHR SPIR-V instruction is accelerated 906 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 907 * pname:integerDotProduct8BitMixedSignednessAccelerated is a boolean that 908 will be ename:VK_TRUE if the support for 8-bit mixed signedness dot 909 product operations using the code:OpSUDotKHR SPIR-V instruction is 910 accelerated <<devsandqueues-integer-dot-product-accelerated,as defined 911 below>>. 912 * pname:integerDotProduct4x8BitPackedUnsignedAccelerated is a boolean that 913 will be ename:VK_TRUE if the support for 8-bit unsigned dot product 914 operations from operands packed into 32-bit integers using the 915 code:OpUDotKHR SPIR-V instruction is accelerated 916 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 917 * pname:integerDotProduct4x8BitPackedSignedAccelerated is a boolean that 918 will be ename:VK_TRUE if the support for 8-bit signed dot product 919 operations from operands packed into 32-bit integers using the 920 code:OpSDotKHR SPIR-V instruction is accelerated 921 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 922 * pname:integerDotProduct4x8BitPackedMixedSignednessAccelerated is a 923 boolean that will be ename:VK_TRUE if the support for 8-bit mixed 924 signedness dot product operations from operands packed into 32-bit 925 integers using the code:OpSUDotKHR SPIR-V instruction is accelerated 926 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 927 * pname:integerDotProduct16BitUnsignedAccelerated is a boolean that will 928 be ename:VK_TRUE if the support for 16-bit unsigned dot product 929 operations using the code:OpUDotKHR SPIR-V instruction is accelerated 930 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 931 * pname:integerDotProduct16BitSignedAccelerated is a boolean that will be 932 ename:VK_TRUE if the support for 16-bit signed dot product operations 933 using the code:OpSDotKHR SPIR-V instruction is accelerated 934 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 935 * pname:integerDotProduct16BitMixedSignednessAccelerated is a boolean that 936 will be ename:VK_TRUE if the support for 16-bit mixed signedness dot 937 product operations using the code:OpSUDotKHR SPIR-V instruction is 938 accelerated <<devsandqueues-integer-dot-product-accelerated,as defined 939 below>>. 940 * pname:integerDotProduct32BitUnsignedAccelerated is a boolean that will 941 be ename:VK_TRUE if the support for 32-bit unsigned dot product 942 operations using the code:OpUDotKHR SPIR-V instruction is accelerated 943 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 944 * pname:integerDotProduct32BitSignedAccelerated is a boolean that will be 945 ename:VK_TRUE if the support for 32-bit signed dot product operations 946 using the code:OpSDotKHR SPIR-V instruction is accelerated 947 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 948 * pname:integerDotProduct32BitMixedSignednessAccelerated is a boolean that 949 will be ename:VK_TRUE if the support for 32-bit mixed signedness dot 950 product operations using the code:OpSUDotKHR SPIR-V instruction is 951 accelerated <<devsandqueues-integer-dot-product-accelerated,as defined 952 below>>. 953 * pname:integerDotProduct64BitUnsignedAccelerated is a boolean that will 954 be ename:VK_TRUE if the support for 64-bit unsigned dot product 955 operations using the code:OpUDotKHR SPIR-V instruction is accelerated 956 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 957 * pname:integerDotProduct64BitSignedAccelerated is a boolean that will be 958 ename:VK_TRUE if the support for 64-bit signed dot product operations 959 using the code:OpSDotKHR SPIR-V instruction is accelerated 960 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 961 * pname:integerDotProduct64BitMixedSignednessAccelerated is a boolean that 962 will be ename:VK_TRUE if the support for 64-bit mixed signedness dot 963 product operations using the code:OpSUDotKHR SPIR-V instruction is 964 accelerated <<devsandqueues-integer-dot-product-accelerated,as defined 965 below>>. 966 * pname:integerDotProductAccumulatingSaturating8BitUnsignedAccelerated is 967 a boolean that will be ename:VK_TRUE if the support for 8-bit unsigned 968 accumulating saturating dot product operations using the 969 code:OpUDotAccSatKHR SPIR-V instruction is accelerated 970 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 971 * pname:integerDotProductAccumulatingSaturating8BitSignedAccelerated is a 972 boolean that will be ename:VK_TRUE if the support for 8-bit signed 973 accumulating saturating dot product operations using the 974 code:OpSDotAccSatKHR SPIR-V instruction is accelerated 975 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 976 * pname:integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated 977 is a boolean that will be ename:VK_TRUE if the support for 8-bit mixed 978 signedness accumulating saturating dot product operations using the 979 code:OpSUDotAccSatKHR SPIR-V instruction is accelerated 980 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 981 * pname:integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated 982 is a boolean that will be ename:VK_TRUE if the support for 8-bit 983 unsigned accumulating saturating dot product operations from operands 984 packed into 32-bit integers using the code:OpUDotAccSatKHR SPIR-V 985 instruction is accelerated 986 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 987 * pname:integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated 988 is a boolean that will be ename:VK_TRUE if the support for 8-bit signed 989 accumulating saturating dot product operations from operands packed into 990 32-bit integers using the code:OpSDotAccSatKHR SPIR-V instruction is 991 accelerated <<devsandqueues-integer-dot-product-accelerated,as defined 992 below>>. 993 * pname:integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated 994 is a boolean that will be ename:VK_TRUE if the support for 8-bit mixed 995 signedness accumulating saturating dot product operations from operands 996 packed into 32-bit integers using the code:OpSUDotAccSatKHR SPIR-V 997 instruction is accelerated 998 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 999 * pname:integerDotProductAccumulatingSaturating16BitUnsignedAccelerated is 1000 a boolean that will be ename:VK_TRUE if the support for 16-bit unsigned 1001 accumulating saturating dot product operations using the 1002 code:OpUDotAccSatKHR SPIR-V instruction is accelerated 1003 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 1004 * pname:integerDotProductAccumulatingSaturating16BitSignedAccelerated is a 1005 boolean that will be ename:VK_TRUE if the support for 16-bit signed 1006 accumulating saturating dot product operations using the 1007 code:OpSDotAccSatKHR SPIR-V instruction is accelerated 1008 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 1009 * pname:integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated 1010 is a boolean that will be ename:VK_TRUE if the support for 16-bit mixed 1011 signedness accumulating saturating dot product operations using the 1012 code:OpSUDotAccSatKHR SPIR-V instruction is accelerated 1013 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 1014 * pname:integerDotProductAccumulatingSaturating32BitUnsignedAccelerated is 1015 a boolean that will be ename:VK_TRUE if the support for 32-bit unsigned 1016 accumulating saturating dot product operations using the 1017 code:OpUDotAccSatKHR SPIR-V instruction is accelerated 1018 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 1019 * pname:integerDotProductAccumulatingSaturating32BitSignedAccelerated is a 1020 boolean that will be ename:VK_TRUE if the support for 32-bit signed 1021 accumulating saturating dot product operations using the 1022 code:OpSDotAccSatKHR SPIR-V instruction is accelerated 1023 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 1024 * pname:integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated 1025 is a boolean that will be ename:VK_TRUE if the support for 32-bit mixed 1026 signedness accumulating saturating dot product operations using the 1027 code:OpSUDotAccSatKHR SPIR-V instruction is accelerated 1028 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 1029 * pname:integerDotProductAccumulatingSaturating64BitUnsignedAccelerated is 1030 a boolean that will be ename:VK_TRUE if the support for 64-bit unsigned 1031 accumulating saturating dot product operations using the 1032 code:OpUDotAccSatKHR SPIR-V instruction is accelerated 1033 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 1034 * pname:integerDotProductAccumulatingSaturating64BitSignedAccelerated is a 1035 boolean that will be ename:VK_TRUE if the support for 64-bit signed 1036 accumulating saturating dot product operations using the 1037 code:OpSDotAccSatKHR SPIR-V instruction is accelerated 1038 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 1039 * pname:integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated 1040 is a boolean that will be ename:VK_TRUE if the support for 64-bit mixed 1041 signedness accumulating saturating dot product operations using the 1042 code:OpSUDotAccSatKHR SPIR-V instruction is accelerated 1043 <<devsandqueues-integer-dot-product-accelerated,as defined below>>. 1044// end::VK_KHR_shader_integer_dot_product-properties[] 1045 1046:refpage: VkPhysicalDeviceShaderIntegerDotProductProperties 1047include::{chapters}/limits.adoc[tag=limits_desc] 1048 1049These are properties of the integer dot product acceleration information of 1050a physical device. 1051 1052[[devsandqueues-integer-dot-product-accelerated]] 1053[NOTE] 1054.Note 1055==== 1056A dot product operation is deemed accelerated if its implementation provides 1057a performance advantage over application-provided code composed from 1058elementary instructions and/or other dot product instructions, either 1059because the implementation uses optimized machine code sequences whose 1060generation from application-provided code cannot be guaranteed or because it 1061uses hardware features that cannot otherwise be targeted from 1062application-provided code. 1063==== 1064 1065include::{generated}/validity/structs/VkPhysicalDeviceShaderIntegerDotProductProperties.adoc[] 1066-- 1067endif::VK_VERSION_1_3,VK_KHR_shader_integer_dot_product[] 1068 1069ifdef::VK_QCOM_image_processing[] 1070[open,refpage='VkPhysicalDeviceImageProcessingPropertiesQCOM',desc='Structure containing image processing properties',type='structs'] 1071-- 1072The sname:VkPhysicalDeviceImageProcessingPropertiesQCOM structure is defined 1073as: 1074 1075include::{generated}/api/structs/VkPhysicalDeviceImageProcessingPropertiesQCOM.adoc[] 1076 1077 * pname:sType is a elink:VkStructureType value identifying this structure. 1078 * pname:pNext is `NULL` or a pointer to a structure extending this 1079 structure. 1080 * [[limits-weightfilter-phases]] pname:maxWeightFilterPhases is the 1081 maximum value that can: be specified for 1082 slink:VkImageViewSampleWeightCreateInfoQCOM::pname:numPhases in 1083 <<textures-weightimage-filterphases, weight image sampling>> operations. 1084 * [[limits-weightfilter-maxdimension]] pname:maxWeightFilterDimension is a 1085 slink:VkExtent2D describing the largest dimensions (pname:width and 1086 pname:height) that can: be specified for 1087 slink:VkImageViewSampleWeightCreateInfoQCOM::pname:filterSize. 1088 * [[limits-blockmatch-maxblocksize]] pname:maxBlockMatchRegion is a 1089 slink:VkExtent2D describing the largest dimensions (pname:width and 1090 pname:height) that can: be specified for code:blockSize in 1091 <<textures-blockmatch,block matching>> operations. 1092 * [[limits-boxfilter-maxblocksize]] pname:maxBoxFilterBlockSize is a 1093 slink:VkExtent2D describing the maximum dimensions (pname:width and 1094 pname:height) that can: be specified for code:blocksize in 1095 <<textures-boxfilter,box filter sampling>> operations. 1096 1097:refpage: VkPhysicalDeviceImageProcessingPropertiesQCOM 1098include::{chapters}/limits.adoc[tag=limits_desc] 1099 1100These are properties of the image processing information of a physical 1101device. 1102 1103include::{generated}/validity/structs/VkPhysicalDeviceImageProcessingPropertiesQCOM.adoc[] 1104-- 1105endif::VK_QCOM_image_processing[] 1106 1107ifdef::VK_EXT_shader_tile_image[] 1108[open,refpage='VkPhysicalDeviceShaderTileImagePropertiesEXT',desc='Structure containing information about tile image support for a physical device',type='structs'] 1109-- 1110The sname:VkPhysicalDeviceShaderTileImagePropertiesEXT structure is defined 1111as: 1112 1113include::{generated}/api/structs/VkPhysicalDeviceShaderTileImagePropertiesEXT.adoc[] 1114 1115 * pname:sType is a elink:VkStructureType value identifying this structure. 1116 * pname:pNext is `NULL` or a pointer to a structure extending this 1117 structure. 1118 * pname:shaderTileImageCoherentReadAccelerated is a boolean that will be 1119 ename:VK_TRUE if coherent reads of tile image data is accelerated. 1120 * pname:shaderTileImageReadSampleFromPixelRateInvocation is a boolean that 1121 will be ename:VK_TRUE if reading from samples from a pixel rate fragment 1122 invocation is supported when 1123 slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples > 1. 1124 * pname:shaderTileImageReadFromHelperInvocation is a boolean that will be 1125 ename:VK_TRUE if reads of tile image data from helper fragment 1126 invocations result in valid values. 1127 1128:refpage: VkPhysicalDeviceShaderTileImagePropertiesEXT 1129include::{chapters}/limits.adoc[tag=limits_desc] 1130 1131These are properties of the tile image information of a physical device. 1132 1133include::{generated}/validity/structs/VkPhysicalDeviceShaderTileImagePropertiesEXT.adoc[] 1134-- 1135endif::VK_EXT_shader_tile_image[] 1136 1137ifdef::VK_QCOM_image_processing2[] 1138[open,refpage='VkPhysicalDeviceImageProcessing2PropertiesQCOM',desc='Structure containing image processing2 properties',type='structs'] 1139-- 1140The sname:VkPhysicalDeviceImageProcessing2PropertiesQCOM structure is 1141defined as: 1142 1143include::{generated}/api/structs/VkPhysicalDeviceImageProcessing2PropertiesQCOM.adoc[] 1144 1145 * pname:sType is a elink:VkStructureType value identifying this structure. 1146 * pname:pNext is `NULL` or a pointer to a structure extending this 1147 structure. 1148 1149 * [[limits-blockmatch-maxWindowExtent]] pname:maxBlockMatchWindow is a 1150 slink:VkExtent2D describing the largest dimensions (pname:width and 1151 pname:height) that can: be specified for the block match window. 1152 1153:refpage: VkPhysicalDeviceImageProcessing2PropertiesQCOM 1154include::{chapters}/limits.adoc[tag=limits_desc] 1155 1156These are properties of the image processing2 information of a physical 1157device. 1158 1159include::{generated}/validity/structs/VkPhysicalDeviceImageProcessing2PropertiesQCOM.adoc[] 1160-- 1161endif::VK_QCOM_image_processing2[] 1162 1163ifdef::VK_MSFT_layered_driver[] 1164[open,refpage='VkPhysicalDeviceLayeredDriverPropertiesMSFT',desc='Structure containing information about driver layering for a physical device',type='structs'] 1165-- 1166The sname:VkPhysicalDeviceLayeredDriverPropertiesMSFT structure is defined 1167as: 1168 1169include::{generated}/api/structs/VkPhysicalDeviceLayeredDriverPropertiesMSFT.adoc[] 1170 1171 * pname:sType is a elink:VkStructureType value identifying this structure. 1172 * pname:pNext is `NULL` or a pointer to a structure extending this 1173 structure. 1174 * pname:underlyingAPI is a elink:VkLayeredDriverUnderlyingApiMSFT value 1175 indicating which underlying API is used to implement the layered driver, 1176 or ename:VK_LAYERED_DRIVER_UNDERLYING_API_NONE_MSFT if the driver is not 1177 layered. 1178 1179These are properties of the driver layering information of a physical 1180device. 1181 1182include::{generated}/validity/structs/VkPhysicalDeviceLayeredDriverPropertiesMSFT.adoc[] 1183-- 1184 1185[open,refpage='VkLayeredDriverUnderlyingApiMSFT',desc='Layered driver underlying APIs',type='enums'] 1186-- 1187Underlying APIs which may: be returned in 1188slink:VkPhysicalDeviceLayeredDriverPropertiesMSFT::pname:underlyingAPI are: 1189 1190include::{generated}/api/enums/VkLayeredDriverUnderlyingApiMSFT.adoc[] 1191-- 1192endif::VK_MSFT_layered_driver[] 1193 1194ifdef::VK_ARM_scheduling_controls[] 1195[open,refpage='VkPhysicalDeviceSchedulingControlsPropertiesARM',desc='Structure containing scheduling control properties of a physical device',type='structs'] 1196-- 1197The sname:VkPhysicalDeviceSchedulingControlsPropertiesARM structure is 1198defined as: 1199 1200include::{generated}/api/structs/VkPhysicalDeviceSchedulingControlsPropertiesARM.adoc[] 1201 1202 * [[limits-schedulingControlsFlags]]pname:schedulingControlsFlags 1203 specifies the specific scheduling controls that a physical device 1204 supports. 1205 1206:refpage: VkPhysicalDeviceSchedulingControlsPropertiesARM 1207include::{chapters}/limits.adoc[tag=limits_desc] 1208 1209include::{generated}/validity/structs/VkPhysicalDeviceSchedulingControlsPropertiesARM.adoc[] 1210-- 1211 1212[open,refpage='VkPhysicalDeviceSchedulingControlsFlagBitsARM',desc='Bitmask specifying scheduling controls supported by a physical device',type='enums'] 1213-- 1214Bits which can: be set in 1215slink:VkPhysicalDeviceSchedulingControlsPropertiesARM::pname:schedulingControlsFlags, 1216specifying supported scheduling controls, are: 1217 1218include::{generated}/api/enums/VkPhysicalDeviceSchedulingControlsFlagBitsARM.adoc[] 1219 1220 * ename:VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM 1221 indicates that a slink:VkDeviceQueueShaderCoreControlCreateInfoARM 1222 structure may: be included in the pname:pNext chain of a 1223 slink:VkDeviceQueueCreateInfo or slink:VkDeviceCreateInfo structure. 1224-- 1225 1226[open,refpage='VkPhysicalDeviceSchedulingControlsFlagsARM',desc='Bitmask of VkPhysicalDeviceSchedulingControlsFlagBitsARM',type='flags'] 1227-- 1228include::{generated}/api/flags/VkPhysicalDeviceSchedulingControlsFlagsARM.adoc[] 1229 1230tname:VkPhysicalDeviceSchedulingControlsFlagsARM is a bitmask type for 1231setting a mask of zero or more 1232elink:VkPhysicalDeviceSchedulingControlsFlagBitsARM. 1233-- 1234endif::VK_ARM_scheduling_controls[] 1235 1236[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties',desc='Reports properties of the queues of the specified physical device',type='protos'] 1237-- 1238To query properties of queues available on a physical device, call: 1239 1240include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties.adoc[] 1241 1242 * pname:physicalDevice is the handle to the physical device whose 1243 properties will be queried. 1244 * pname:pQueueFamilyPropertyCount is a pointer to an integer related to 1245 the number of queue families available or queried, as described below. 1246 * pname:pQueueFamilyProperties is either `NULL` or a pointer to an array 1247 of slink:VkQueueFamilyProperties structures. 1248 1249If pname:pQueueFamilyProperties is `NULL`, then the number of queue families 1250available is returned in pname:pQueueFamilyPropertyCount. 1251Implementations must: support at least one queue family. 1252Otherwise, pname:pQueueFamilyPropertyCount must: point to a variable set by 1253the user to the number of elements in the pname:pQueueFamilyProperties 1254array, and on return the variable is overwritten with the number of 1255structures actually written to pname:pQueueFamilyProperties. 1256If pname:pQueueFamilyPropertyCount is less than the number of queue families 1257available, at most pname:pQueueFamilyPropertyCount structures will be 1258written. 1259 1260include::{generated}/validity/protos/vkGetPhysicalDeviceQueueFamilyProperties.adoc[] 1261-- 1262 1263[open,refpage='VkQueueFamilyProperties',desc='Structure providing information about a queue family',type='structs'] 1264-- 1265The sname:VkQueueFamilyProperties structure is defined as: 1266 1267include::{generated}/api/structs/VkQueueFamilyProperties.adoc[] 1268 1269 * pname:queueFlags is a bitmask of elink:VkQueueFlagBits indicating 1270 capabilities of the queues in this queue family. 1271 * pname:queueCount is the unsigned integer count of queues in this queue 1272 family. 1273 Each queue family must: support at least one queue. 1274 * pname:timestampValidBits is the unsigned integer count of meaningful 1275 bits in the timestamps written via 1276ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 1277 flink:vkCmdWriteTimestamp2 or 1278endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 1279 flink:vkCmdWriteTimestamp. 1280 The valid range for the count is 36 to 64 bits, or a value of 0, 1281 indicating no support for timestamps. 1282 Bits outside the valid range are guaranteed to be zeros. 1283 * pname:minImageTransferGranularity is the minimum granularity supported 1284 for image transfer operations on the queues in this queue family. 1285 1286The value returned in pname:minImageTransferGranularity has a unit of 1287compressed texel blocks for images having a block-compressed format, and a 1288unit of texels otherwise. 1289 1290Possible values of pname:minImageTransferGranularity are: 1291 1292 * [eq]#(0,0,0)# specifies that only whole mip levels must: be transferred 1293 using the image transfer operations on the corresponding queues. 1294 In this case, the following restrictions apply to all offset and extent 1295 parameters of image transfer operations: 1296 ** The pname:x, pname:y, and pname:z members of a slink:VkOffset3D 1297 parameter must: always be zero. 1298 ** The pname:width, pname:height, and pname:depth members of a 1299 slink:VkExtent3D parameter must: always match the width, height, and 1300 depth of the image subresource corresponding to the parameter, 1301 respectively. 1302 * [eq]#(A~x~, A~y~, A~z~)# where [eq]#A~x~#, [eq]#A~y~#, and [eq]#A~z~# 1303 are all integer powers of two. 1304 In this case the following restrictions apply to all image transfer 1305 operations: 1306 ** pname:x, pname:y, and pname:z of a slink:VkOffset3D parameter must: be 1307 integer multiples of [eq]#A~x~#, [eq]#A~y~#, and [eq]#A~z~#, 1308 respectively. 1309 ** pname:width of a slink:VkExtent3D parameter must: be an integer 1310 multiple of [eq]#A~x~#, or else [eq]#pname:x {plus} pname:width# must: 1311 equal the width of the image subresource corresponding to the 1312 parameter. 1313 ** pname:height of a slink:VkExtent3D parameter must: be an integer 1314 multiple of [eq]#A~y~#, or else [eq]#pname:y {plus} pname:height# must: 1315 equal the height of the image subresource corresponding to the 1316 parameter. 1317 ** pname:depth of a slink:VkExtent3D parameter must: be an integer 1318 multiple of [eq]#A~z~#, or else [eq]#pname:z {plus} pname:depth# must: 1319 equal the depth of the image subresource corresponding to the 1320 parameter. 1321 ** If the format of the image corresponding to the parameters is one of 1322 the block-compressed formats then for the purposes of the above 1323 calculations the granularity must: be scaled up by the compressed texel 1324 block dimensions. 1325 1326Queues supporting graphics and/or compute operations must: report 1327[eq]#(1,1,1)# in pname:minImageTransferGranularity, meaning that there are 1328no additional restrictions on the granularity of image transfer operations 1329for these queues. 1330Other queues supporting image transfer operations are only required: to 1331support whole mip level transfers, thus pname:minImageTransferGranularity 1332for queues belonging to such queue families may: be [eq]#(0,0,0)#. 1333 1334The <<memory-device,Device Memory>> section describes memory properties 1335queried from the physical device. 1336 1337For physical device feature queries see the <<features, Features>> chapter. 1338 1339include::{generated}/validity/structs/VkQueueFamilyProperties.adoc[] 1340-- 1341 1342[open,refpage='VkQueueFlagBits',desc='Bitmask specifying capabilities of queues in a queue family',type='enums'] 1343-- 1344Bits which may: be set in slink:VkQueueFamilyProperties::pname:queueFlags, 1345indicating capabilities of queues in a queue family are: 1346 1347include::{generated}/api/enums/VkQueueFlagBits.adoc[] 1348 1349 * ename:VK_QUEUE_GRAPHICS_BIT specifies that queues in this queue family 1350 support graphics operations. 1351 * ename:VK_QUEUE_COMPUTE_BIT specifies that queues in this queue family 1352 support compute operations. 1353 * ename:VK_QUEUE_TRANSFER_BIT specifies that queues in this queue family 1354 support transfer operations. 1355 * ename:VK_QUEUE_SPARSE_BINDING_BIT specifies that queues in this queue 1356 family support sparse memory management operations (see 1357 <<sparsememory,Sparse Resources>>). 1358 If any of the sparse resource features are enabled, then at least one 1359 queue family must: support this bit. 1360ifdef::VKSC_VERSION_1_0[] 1361 This flag is not supported in Vulkan SC <<SCID-8>>. 1362ifdef::hidden[] 1363// tag::scremoved[] 1364 * elink:VkQueueFlagBits 1365 ** ename:VK_QUEUE_SPARSE_BINDING_BIT <<SCID-8>> 1366// end::scremoved[] 1367endif::hidden[] 1368endif::VKSC_VERSION_1_0[] 1369ifdef::VK_KHR_video_decode_queue[] 1370 * ename:VK_QUEUE_VIDEO_DECODE_BIT_KHR specifies that queues in this queue 1371 family support <<video-decode-operations,video decode operations>>. 1372endif::VK_KHR_video_decode_queue[] 1373ifdef::VK_KHR_video_encode_queue[] 1374 * ename:VK_QUEUE_VIDEO_ENCODE_BIT_KHR specifies that queues in this queue 1375 family support <<video-encode-operations,video encode operations>>. 1376endif::VK_KHR_video_encode_queue[] 1377ifdef::VK_NV_optical_flow[] 1378 * ename:VK_QUEUE_OPTICAL_FLOW_BIT_NV specifies that queues in this queue 1379 family support optical flow operations. 1380endif::VK_NV_optical_flow[] 1381ifdef::VK_VERSION_1_1[] 1382 * ename:VK_QUEUE_PROTECTED_BIT specifies that queues in this queue family 1383 support the ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit. 1384 (see <<memory-protected-memory,Protected Memory>>). 1385 If the physical device supports the <<features-protectedMemory, 1386 pname:protectedMemory>> feature, at least one of its queue families 1387 must: support this bit. 1388endif::VK_VERSION_1_1[] 1389 1390If an implementation exposes any queue family that supports graphics 1391operations, at least one queue family of at least one physical device 1392exposed by the implementation must: support both graphics and compute 1393operations. 1394 1395ifdef::VK_VERSION_1_1[] 1396Furthermore, if the <<features-protectedMemory, pname:protectedMemory>> 1397physical device feature is supported, then at least one queue family of at 1398least one physical device exposed by the implementation must: support 1399graphics operations, compute operations, and protected memory operations. 1400endif::VK_VERSION_1_1[] 1401 1402[NOTE] 1403.Note 1404==== 1405All commands that are allowed on a queue that supports transfer operations 1406are also allowed on a queue that supports either graphics or compute 1407operations. 1408Thus, if the capabilities of a queue family include 1409ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT, then reporting 1410the ename:VK_QUEUE_TRANSFER_BIT capability separately for that queue family 1411is optional:. 1412==== 1413 1414For further details see <<devsandqueues-queues,Queues>>. 1415-- 1416 1417[open,refpage='VkQueueFlags',desc='Bitmask of VkQueueFlagBits',type='flags'] 1418-- 1419include::{generated}/api/flags/VkQueueFlags.adoc[] 1420 1421tname:VkQueueFlags is a bitmask type for setting a mask of zero or more 1422elink:VkQueueFlagBits. 1423-- 1424 1425ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1426[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties2',desc='Reports properties of the queues of the specified physical device',type='protos'] 1427-- 1428To query properties of queues available on a physical device, call: 1429 1430ifdef::VK_VERSION_1_1[] 1431include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties2.adoc[] 1432endif::VK_VERSION_1_1[] 1433 1434ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] 1435 1436ifdef::VK_KHR_get_physical_device_properties2[] 1437include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.adoc[] 1438endif::VK_KHR_get_physical_device_properties2[] 1439 1440 * pname:physicalDevice is the handle to the physical device whose 1441 properties will be queried. 1442 * pname:pQueueFamilyPropertyCount is a pointer to an integer related to 1443 the number of queue families available or queried, as described in 1444 flink:vkGetPhysicalDeviceQueueFamilyProperties. 1445 * pname:pQueueFamilyProperties is either `NULL` or a pointer to an array 1446 of slink:VkQueueFamilyProperties2 structures. 1447 1448fname:vkGetPhysicalDeviceQueueFamilyProperties2 behaves similarly to 1449flink:vkGetPhysicalDeviceQueueFamilyProperties, with the ability to return 1450extended information in a pname:pNext chain of output structures. 1451 1452include::{generated}/validity/protos/vkGetPhysicalDeviceQueueFamilyProperties2.adoc[] 1453-- 1454 1455[open,refpage='VkQueueFamilyProperties2',desc='Structure providing information about a queue family',type='structs'] 1456-- 1457The sname:VkQueueFamilyProperties2 structure is defined as: 1458 1459include::{generated}/api/structs/VkQueueFamilyProperties2.adoc[] 1460 1461ifdef::VK_KHR_get_physical_device_properties2[] 1462or the equivalent 1463 1464include::{generated}/api/structs/VkQueueFamilyProperties2KHR.adoc[] 1465endif::VK_KHR_get_physical_device_properties2[] 1466 1467 * pname:sType is a elink:VkStructureType value identifying this structure. 1468 * pname:pNext is `NULL` or a pointer to a structure extending this 1469 structure. 1470 * pname:queueFamilyProperties is a slink:VkQueueFamilyProperties structure 1471 which is populated with the same values as in 1472 flink:vkGetPhysicalDeviceQueueFamilyProperties. 1473 1474include::{generated}/validity/structs/VkQueueFamilyProperties2.adoc[] 1475-- 1476 1477ifdef::VK_EXT_global_priority_query,VK_KHR_global_priority[] 1478[open,refpage='VkQueueFamilyGlobalPriorityPropertiesKHR',desc='Return structure for queue family global priority information query',type='structs'] 1479-- 1480The definition of slink:VkQueueFamilyGlobalPriorityPropertiesKHR is: 1481 1482include::{generated}/api/structs/VkQueueFamilyGlobalPriorityPropertiesKHR.adoc[] 1483ifdef::VK_EXT_global_priority_query[] 1484or the equivalent 1485 1486include::{generated}/api/structs/VkQueueFamilyGlobalPriorityPropertiesEXT.adoc[] 1487endif::VK_EXT_global_priority_query[] 1488 1489 * pname:sType is a elink:VkStructureType value identifying this structure. 1490 * pname:pNext is `NULL` or a pointer to a structure extending this 1491 structure. 1492 * pname:priorityCount is the number of supported global queue priorities 1493 in this queue family, and it must: be greater than 0. 1494 * pname:priorities is an array of ename:VK_MAX_GLOBAL_PRIORITY_SIZE_EXT 1495 elink:VkQueueGlobalPriorityEXT enums representing all supported global 1496 queue priorities in this queue family. 1497 The first pname:priorityCount elements of the array will be valid. 1498 1499If the sname:VkQueueFamilyGlobalPriorityPropertiesKHR structure is included 1500in the pname:pNext chain of the slink:VkQueueFamilyProperties2 structure 1501passed to flink:vkGetPhysicalDeviceQueueFamilyProperties2, it is filled in 1502with the list of supported global queue priorities for the indicated family. 1503 1504The valid elements of pname:priorities must: not contain any duplicate 1505values. 1506 1507The valid elements of pname:priorities must: be a continuous sequence of 1508elink:VkQueueGlobalPriorityKHR enums in the ascending order. 1509 1510[NOTE] 1511.Note 1512==== 1513For example, returning pname:priorityCount as 3 with supported 1514pname:priorities as ename:VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR, 1515ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR and 1516ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR is not allowed. 1517==== 1518 1519include::{generated}/validity/structs/VkQueueFamilyGlobalPriorityPropertiesKHR.adoc[] 1520-- 1521 1522[open,refpage='VK_MAX_GLOBAL_PRIORITY_SIZE_KHR',desc='Length of an array of global queue priorities',type='consts'] 1523-- 1524ename:VK_MAX_GLOBAL_PRIORITY_SIZE_KHR is the length of an array of 1525elink:VkQueueGlobalPriorityKHR enumerants representing supported queue 1526priorities, as returned in 1527slink:VkQueueFamilyGlobalPriorityPropertiesKHR::pname:priorities. 1528 1529include::{generated}/api/enums/VK_MAX_GLOBAL_PRIORITY_SIZE_KHR.adoc[] 1530 1531ifdef::VK_EXT_global_priority_query[] 1532or the equivalent 1533 1534include::{generated}/api/enums/VK_MAX_GLOBAL_PRIORITY_SIZE_EXT.adoc[] 1535endif::VK_EXT_global_priority_query[] 1536-- 1537endif::VK_EXT_global_priority_query,VK_KHR_global_priority[] 1538 1539ifdef::VK_NV_device_diagnostic_checkpoints[] 1540include::{chapters}/VK_NV_device_diagnostic_checkpoints/queue_checkpoint_properties.adoc[] 1541endif::VK_NV_device_diagnostic_checkpoints[] 1542 1543endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1544 1545ifdef::VK_KHR_video_queue[] 1546[open,refpage='VkQueueFamilyVideoPropertiesKHR',desc='Structure describing video codec operations supported by a queue family',type='structs'] 1547-- 1548The slink:VkQueueFamilyVideoPropertiesKHR structure is defined as: 1549 1550include::{generated}/api/structs/VkQueueFamilyVideoPropertiesKHR.adoc[] 1551 1552 * pname:sType is a elink:VkStructureType value identifying this structure. 1553 * pname:pNext is `NULL` or a pointer to a structure extending this 1554 structure. 1555 * pname:videoCodecOperations is a bitmask of 1556 elink:VkVideoCodecOperationFlagBitsKHR that indicates the set of video 1557 codec operations supported by the queue family. 1558 1559If this structure is included in the pname:pNext chain of the 1560slink:VkQueueFamilyProperties2 structure passed to 1561flink:vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with the 1562set of video codec operations supported by the specified queue family. 1563 1564include::{generated}/validity/structs/VkQueueFamilyVideoPropertiesKHR.adoc[] 1565-- 1566 1567[open,refpage='VkQueueFamilyQueryResultStatusPropertiesKHR',desc='Structure specifying support for result status query',type='structs'] 1568-- 1569The slink:VkQueueFamilyQueryResultStatusPropertiesKHR structure is defined 1570as: 1571 1572include::{generated}/api/structs/VkQueueFamilyQueryResultStatusPropertiesKHR.adoc[] 1573 1574 * pname:sType is a elink:VkStructureType value identifying this structure. 1575 * pname:pNext is `NULL` or a pointer to a structure extending this 1576 structure. 1577 * pname:queryResultStatusSupport reports ename:VK_TRUE if query type 1578 ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR and use of 1579 ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR are supported. 1580 1581If this structure is included in the pname:pNext chain of the 1582slink:VkQueueFamilyProperties2 structure passed to 1583flink:vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with 1584information about whether <<queries-result-status-only,result status 1585queries>> are supported by the specified queue family. 1586 1587include::{generated}/validity/structs/VkQueueFamilyQueryResultStatusPropertiesKHR.adoc[] 1588-- 1589endif::VK_KHR_video_queue[] 1590 1591ifdef::VK_KHR_performance_query[] 1592include::{chapters}/VK_KHR_performance_query/queuefamily.adoc[] 1593endif::VK_KHR_performance_query[] 1594 1595 1596[[devsandqueues-devices]] 1597== Devices 1598 1599Device objects represent logical connections to physical devices. 1600Each device exposes a number of _queue families_ each having one or more 1601_queues_. 1602All queues in a queue family support the same operations. 1603 1604As described in <<devsandqueues-physical-device-enumeration,Physical 1605Devices>>, a Vulkan application will first query for all physical devices in 1606a system. 1607Each physical device can: then be queried for its capabilities, including 1608its queue and queue family properties. 1609Once an acceptable physical device is identified, an application will create 1610a corresponding logical device. 1611The created logical device is then the primary interface to the physical 1612device. 1613 1614How to enumerate the physical devices in a system and query those physical 1615devices for their queue family properties is described in the 1616<<devsandqueues-physical-device-enumeration, Physical Device Enumeration>> 1617section above. 1618 1619ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[] 1620 1621A single logical device can: be created from multiple physical devices, if 1622those physical devices belong to the same device group. 1623A _device group_ is a set of physical devices that support accessing each 1624other's memory and recording a single command buffer that can: be executed 1625on all the physical devices. 1626Device groups are enumerated by calling 1627flink:vkEnumeratePhysicalDeviceGroups, and a logical device is created from 1628a subset of the physical devices in a device group by passing the physical 1629devices through slink:VkDeviceGroupDeviceCreateInfo. 1630For two physical devices to be in the same device group, they must: support 1631identical extensions, features, and properties. 1632 1633[NOTE] 1634.Note 1635==== 1636Physical devices in the same device group must: be so similar because there 1637are no rules for how different features/properties would interact. 1638They must: return the same values for nearly every invariant 1639ftext:vkGetPhysicalDevice* feature, property, capability, etc., but could 1640potentially differ for certain queries based on things like having a 1641different display connected, or a different compositor. 1642The specification does not attempt to enumerate which state is in each 1643category, because such a list would quickly become out of date. 1644==== 1645 1646[open,refpage='vkEnumeratePhysicalDeviceGroups',desc='Enumerates groups of physical devices that can be used to create a single logical device',type='protos'] 1647-- 1648To retrieve a list of the device groups present in the system, call: 1649 1650ifdef::VK_VERSION_1_1[] 1651include::{generated}/api/protos/vkEnumeratePhysicalDeviceGroups.adoc[] 1652endif::VK_VERSION_1_1[] 1653 1654ifdef::VK_VERSION_1_1+VK_KHR_device_group_creation[or the equivalent command] 1655 1656ifdef::VK_KHR_device_group_creation[] 1657include::{generated}/api/protos/vkEnumeratePhysicalDeviceGroupsKHR.adoc[] 1658endif::VK_KHR_device_group_creation[] 1659 1660 * pname:instance is a handle to a Vulkan instance previously created with 1661 flink:vkCreateInstance. 1662 * pname:pPhysicalDeviceGroupCount is a pointer to an integer related to 1663 the number of device groups available or queried, as described below. 1664 * pname:pPhysicalDeviceGroupProperties is either `NULL` or a pointer to an 1665 array of slink:VkPhysicalDeviceGroupProperties structures. 1666 1667If pname:pPhysicalDeviceGroupProperties is `NULL`, then the number of device 1668groups available is returned in pname:pPhysicalDeviceGroupCount. 1669Otherwise, pname:pPhysicalDeviceGroupCount must: point to a variable set by 1670the user to the number of elements in the 1671pname:pPhysicalDeviceGroupProperties array, and on return the variable is 1672overwritten with the number of structures actually written to 1673pname:pPhysicalDeviceGroupProperties. 1674If pname:pPhysicalDeviceGroupCount is less than the number of device groups 1675available, at most pname:pPhysicalDeviceGroupCount structures will be 1676written, and ename:VK_INCOMPLETE will be returned instead of 1677ename:VK_SUCCESS, to indicate that not all the available device groups were 1678returned. 1679 1680Every physical device must: be in exactly one device group. 1681 1682include::{generated}/validity/protos/vkEnumeratePhysicalDeviceGroups.adoc[] 1683-- 1684 1685[open,refpage='VkPhysicalDeviceGroupProperties',desc='Structure specifying physical device group properties',type='structs'] 1686-- 1687The sname:VkPhysicalDeviceGroupProperties structure is defined as: 1688 1689include::{generated}/api/structs/VkPhysicalDeviceGroupProperties.adoc[] 1690 1691ifdef::VK_KHR_device_group_creation[] 1692or the equivalent 1693 1694include::{generated}/api/structs/VkPhysicalDeviceGroupPropertiesKHR.adoc[] 1695endif::VK_KHR_device_group_creation[] 1696 1697 * pname:sType is a elink:VkStructureType value identifying this structure. 1698 * pname:pNext is `NULL` or a pointer to a structure extending this 1699 structure. 1700 * pname:physicalDeviceCount is the number of physical devices in the 1701 group. 1702 * pname:physicalDevices is an array of ename:VK_MAX_DEVICE_GROUP_SIZE 1703 slink:VkPhysicalDevice handles representing all physical devices in the 1704 group. 1705 The first pname:physicalDeviceCount elements of the array will be valid. 1706 * pname:subsetAllocation specifies whether logical devices created from 1707 the group support allocating device memory on a subset of devices, via 1708 the pname:deviceMask member of the slink:VkMemoryAllocateFlagsInfo. 1709 If this is ename:VK_FALSE, then all device memory allocations are made 1710 across all physical devices in the group. 1711 If pname:physicalDeviceCount is `1`, then pname:subsetAllocation must: 1712 be ename:VK_FALSE. 1713 1714include::{generated}/validity/structs/VkPhysicalDeviceGroupProperties.adoc[] 1715-- 1716 1717[open,refpage='VK_MAX_DEVICE_GROUP_SIZE',desc='Length of a physical device handle array',type='consts',alias='VK_MAX_DEVICE_GROUP_SIZE_KHR'] 1718-- 1719ename:VK_MAX_DEVICE_GROUP_SIZE is the length of an array containing 1720slink:VkPhysicalDevice handle values representing all physical devices in a 1721group, as returned in 1722slink:VkPhysicalDeviceGroupProperties::pname:physicalDevices. 1723 1724include::{generated}/api/enums/VK_MAX_DEVICE_GROUP_SIZE.adoc[] 1725 1726ifdef::VK_KHR_device_group_creation[] 1727or the equivalent 1728 1729include::{generated}/api/enums/VK_MAX_DEVICE_GROUP_SIZE_KHR.adoc[] 1730endif::VK_KHR_device_group_creation[] 1731-- 1732endif::VK_VERSION_1_1,VK_KHR_device_group_creation[] 1733 1734 1735[[devsandqueues-device-creation]] 1736=== Device Creation 1737 1738[open,refpage='VkDevice',desc='Opaque handle to a device object',type='handles'] 1739-- 1740Logical devices are represented by sname:VkDevice handles: 1741 1742include::{generated}/api/handles/VkDevice.adoc[] 1743-- 1744 1745[open,refpage='vkCreateDevice',desc='Create a new device instance',type='protos'] 1746-- 1747A logical device is created as a _connection_ to a physical device. 1748To create a logical device, call: 1749 1750include::{generated}/api/protos/vkCreateDevice.adoc[] 1751 1752 * pname:physicalDevice must: be one of the device handles returned from a 1753 call to fname:vkEnumeratePhysicalDevices (see 1754 <<devsandqueues-physical-device-enumeration, Physical Device 1755 Enumeration>>). 1756 * pname:pCreateInfo is a pointer to a slink:VkDeviceCreateInfo structure 1757 containing information about how to create the device. 1758 * pname:pAllocator controls host memory allocation as described in the 1759 <<memory-allocation, Memory Allocation>> chapter. 1760 * pname:pDevice is a pointer to a handle in which the created 1761 slink:VkDevice is returned. 1762 1763fname:vkCreateDevice verifies that extensions and features requested in the 1764pname:ppEnabledExtensionNames and pname:pEnabledFeatures members of 1765pname:pCreateInfo, respectively, are supported by the implementation. 1766If any requested extension is not supported, fname:vkCreateDevice must: 1767return ename:VK_ERROR_EXTENSION_NOT_PRESENT. 1768If any requested feature is not supported, fname:vkCreateDevice must: return 1769ename:VK_ERROR_FEATURE_NOT_PRESENT. 1770Support for extensions can: be checked before creating a device by querying 1771flink:vkEnumerateDeviceExtensionProperties. 1772Support for features can: similarly be checked by querying 1773flink:vkGetPhysicalDeviceFeatures. 1774 1775ifdef::VKSC_VERSION_1_0[] 1776fname:vkCreateDevice also verifies that mandatory structures and features 1777for Vulkan SC are present and enabled: 1778 1779 * The pname:pNext chain must: include a 1780 slink:VkDeviceObjectReservationCreateInfo structure. 1781 * The pname:pNext chain must: include a 1782 slink:VkPhysicalDeviceVulkanSC10Features structure. 1783ifdef::hidden[] 1784// tag::scdeviation[] 1785 * The slink:VkDeviceCreateInfo::pname:pNext chain must: include a 1786 slink:VkDeviceObjectReservationCreateInfo structure <<SCID-4>>. 1787 * The slink:VkDeviceCreateInfo::pname:pNext chain must: include a 1788 slink:VkPhysicalDeviceVulkanSC10Features structure <<SCID-1>>. 1789// end::scdeviation[] 1790endif::hidden[] 1791 1792If any of these conditions are not met, fname:vkCreateDevice must: return 1793ename:VK_ERROR_INITIALIZATION_FAILED. 1794endif::VKSC_VERSION_1_0[] 1795 1796After verifying and enabling the extensions the sname:VkDevice object is 1797created and returned to the application. 1798 1799ifndef::VKSC_VERSION_1_0[] 1800Multiple logical devices can: be created from the same physical device. 1801Logical device creation may: fail due to lack of device-specific resources 1802(in addition to other errors). 1803endif::VKSC_VERSION_1_0[] 1804ifdef::VKSC_VERSION_1_0[] 1805An implementation may: allow multiple logical devices to be created from the 1806same physical device. 1807Logical device creation may: fail due to lack of device-specific resources, 1808including too many other logical devices, in addition to other errors. 1809endif::VKSC_VERSION_1_0[] 1810If that occurs, fname:vkCreateDevice will return 1811ename:VK_ERROR_TOO_MANY_OBJECTS. 1812 1813ifdef::VKSC_VERSION_1_0[] 1814If the pipeline cache data pointed to by the pname:pInitialData member of 1815any element of 1816slink:VkDeviceObjectReservationCreateInfo::pname:pPipelineCacheCreateInfos 1817is not compatible with the device, then fname:vkCreateDevice will return 1818ename:VK_ERROR_INVALID_PIPELINE_CACHE_DATA. 1819ifdef::hidden[] 1820// tag::scdeviation[] 1821 * flink:vkCreateDevice returns ename:VK_ERROR_INVALID_PIPELINE_CACHE_DATA 1822 if the pname:pInitialData member of any element of 1823 slink:VkDeviceObjectReservationCreateInfo::pname:pPipelineCacheCreateInfos 1824 is a pointer to incompatible pipeline cache data <<SCID-1>>. 1825// end::scdeviation[] 1826endif::hidden[] 1827endif::VKSC_VERSION_1_0[] 1828 1829ifdef::VK_EXT_application_parameters[] 1830To provide _application parameters_ at device creation time, an application 1831can: link one or more slink:VkApplicationParametersEXT structures to the 1832pname:pNext chain of the sname:VkDeviceCreateInfo structure. 1833 1834If the slink:VkApplicationParametersEXT::pname:vendorID and 1835slink:VkApplicationParametersEXT::pname:deviceID values do not match the 1836slink:VkPhysicalDeviceProperties::pname:vendorID and 1837slink:VkPhysicalDeviceProperties::pname:deviceID of pname:physicalDevice, 1838flink:vkCreateDevice must: return ename:VK_ERROR_INITIALIZATION_FAILED. 1839 1840If slink:VkApplicationParametersEXT::pname:key is not a valid 1841implementation-defined application parameter key for the device being 1842created, or if pname:value is not a valid value for the specified pname:key, 1843flink:vkCreateDevice will fail and return 1844ename:VK_ERROR_INITIALIZATION_FAILED. 1845 1846For any implementation-defined application parameter pname:key that exists 1847but is not set by the application, the implementation-specific default value 1848is used. 1849endif::VK_EXT_application_parameters[] 1850 1851.Valid Usage 1852**** 1853 * [[VUID-vkCreateDevice-ppEnabledExtensionNames-01387]] 1854 All <<extendingvulkan-extensions-extensiondependencies, required device 1855 extensions>> for each extension in the 1856 slink:VkDeviceCreateInfo::pname:ppEnabledExtensionNames list must: also 1857 be present in that list 1858ifdef::VK_EXT_application_parameters[] 1859 * [[VUID-vkCreateDevice-key-05092]] 1860 The pname:key value of each slink:VkApplicationParametersEXT structure 1861 in the slink:VkDeviceCreateInfo::pname:pNext chain must: be unique 1862endif::VK_EXT_application_parameters[] 1863ifdef::VKSC_VERSION_1_0[] 1864 * [[VUID-vkCreateDevice-deviceMemoryRequestCount-05095]] 1865 The sum of pname:deviceMemoryRequestCount over all 1866 sname:VkDeviceObjectReservationCreateInfo structures must: be less than 1867 or equal to slink:VkPhysicalDeviceLimits::pname:maxMemoryAllocationCount 1868 * [[VUID-vkCreateDevice-samplerRequestCount-05096]] 1869 The sum of pname:samplerRequestCount over all 1870 sname:VkDeviceObjectReservationCreateInfo structures must: be less than 1871 or equal to 1872 slink:VkPhysicalDeviceLimits::pname:maxSamplerAllocationCount 1873endif::VKSC_VERSION_1_0[] 1874**** 1875 1876include::{generated}/validity/protos/vkCreateDevice.adoc[] 1877-- 1878 1879[open,refpage='VkDeviceCreateInfo',desc='Structure specifying parameters of a newly created device',type='structs'] 1880-- 1881The sname:VkDeviceCreateInfo structure is defined as: 1882 1883include::{generated}/api/structs/VkDeviceCreateInfo.adoc[] 1884 1885 * pname:sType is a elink:VkStructureType value identifying this structure. 1886 * pname:pNext is `NULL` or a pointer to a structure extending this 1887 structure. 1888 * pname:flags is reserved for future use. 1889 * pname:queueCreateInfoCount is the unsigned integer size of the 1890 pname:pQueueCreateInfos array. 1891 Refer to the <<devsandqueues-queue-creation,Queue Creation>> section 1892 below for further details. 1893 * pname:pQueueCreateInfos is a pointer to an array of 1894 slink:VkDeviceQueueCreateInfo structures describing the queues that are 1895 requested to be created along with the logical device. 1896 Refer to the <<devsandqueues-queue-creation,Queue Creation>> section 1897 below for further details. 1898 * pname:enabledLayerCount is deprecated and ignored. 1899 * pname:ppEnabledLayerNames is deprecated and ignored. 1900 See <<extendingvulkan-layers-devicelayerdeprecation>>. 1901 * pname:enabledExtensionCount is the number of device extensions to 1902 enable. 1903 * pname:ppEnabledExtensionNames is a pointer to an array of 1904 pname:enabledExtensionCount null-terminated UTF-8 strings containing the 1905 names of extensions to enable for the created device. 1906 See the <<extendingvulkan-extensions>> section for further details. 1907 * pname:pEnabledFeatures is `NULL` or a pointer to a 1908 slink:VkPhysicalDeviceFeatures structure containing boolean indicators 1909 of all the features to be enabled. 1910 Refer to the <<features, Features>> section for further details. 1911 1912.Valid Usage 1913**** 1914 * [[VUID-VkDeviceCreateInfo-queueFamilyIndex-02802]] 1915 The pname:queueFamilyIndex member of each element of 1916 pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos 1917ifdef::VK_VERSION_1_1[] 1918 , except that two members can share the same pname:queueFamilyIndex if 1919 one describes protected-capable queues and one describes queues that are 1920 not protected-capable 1921endif::VK_VERSION_1_1[] 1922ifdef::VK_VERSION_1_1[] 1923 * [[VUID-VkDeviceCreateInfo-pQueueCreateInfos-06755]] 1924 If multiple elements of pname:pQueueCreateInfos share the same 1925 pname:queueFamilyIndex, the sum of their pname:queueCount members must: 1926 be less than or equal to the pname:queueCount member of the 1927 sname:VkQueueFamilyProperties structure, as returned by 1928 fname:vkGetPhysicalDeviceQueueFamilyProperties in the 1929 pname:pQueueFamilyProperties[queueFamilyIndex] 1930ifdef::VK_KHR_global_priority,VK_EXT_global_priority[] 1931 * [[VUID-VkDeviceCreateInfo-pQueueCreateInfos-06654]] 1932 If multiple elements of pname:pQueueCreateInfos share the same 1933 pname:queueFamilyIndex, then all of such elements must: have the same 1934 global priority level, which can: be specified explicitly by the 1935 including a slink:VkDeviceQueueGlobalPriorityCreateInfoKHR structure in 1936 the pname:pNext chain, or by the implicit default value 1937endif::VK_KHR_global_priority,VK_EXT_global_priority[] 1938endif::VK_VERSION_1_1[] 1939ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1940 * [[VUID-VkDeviceCreateInfo-pNext-00373]] 1941 If the pname:pNext chain includes a slink:VkPhysicalDeviceFeatures2 1942 structure, then pname:pEnabledFeatures must: be `NULL` 1943endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 1944ifdef::VK_AMD_negative_viewport_height[] 1945ifdef::VK_VERSION_1_1[] 1946 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-01840]] 1947 If slink:VkPhysicalDeviceProperties::pname:apiVersion advertises Vulkan 1948 1.1 or later, pname:ppEnabledExtensionNames must: not contain 1949 `apiext:VK_AMD_negative_viewport_height` 1950endif::VK_VERSION_1_1[] 1951ifdef::VK_KHR_maintenance1[] 1952 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-00374]] 1953 pname:ppEnabledExtensionNames must: not contain both 1954 `apiext:VK_KHR_maintenance1` and 1955 `apiext:VK_AMD_negative_viewport_height` 1956endif::VK_KHR_maintenance1[] 1957endif::VK_AMD_negative_viewport_height[] 1958ifdef::VK_EXT_buffer_device_address+VK_KHR_buffer_device_address[] 1959 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-03328]] 1960 pname:ppEnabledExtensionNames must: not contain both 1961 `apiext:VK_KHR_buffer_device_address` and 1962 `apiext:VK_EXT_buffer_device_address` 1963endif::VK_EXT_buffer_device_address+VK_KHR_buffer_device_address[] 1964ifdef::VK_VERSION_1_2[] 1965ifdef::VK_EXT_buffer_device_address[] 1966 * [[VUID-VkDeviceCreateInfo-pNext-04748]] 1967 If the pname:pNext chain includes a 1968 slink:VkPhysicalDeviceVulkan12Features structure and 1969 slink:VkPhysicalDeviceVulkan12Features::pname:bufferDeviceAddress is 1970 ename:VK_TRUE, pname:ppEnabledExtensionNames must: not contain 1971 `apiext:VK_EXT_buffer_device_address` 1972endif::VK_EXT_buffer_device_address[] 1973 * [[VUID-VkDeviceCreateInfo-pNext-02829]] 1974 If the pname:pNext chain includes a 1975 slink:VkPhysicalDeviceVulkan11Features structure, then it must: not 1976 include a slink:VkPhysicalDevice16BitStorageFeatures, 1977 slink:VkPhysicalDeviceMultiviewFeatures, 1978 slink:VkPhysicalDeviceVariablePointersFeatures, 1979 slink:VkPhysicalDeviceProtectedMemoryFeatures, 1980 slink:VkPhysicalDeviceSamplerYcbcrConversionFeatures, or 1981 slink:VkPhysicalDeviceShaderDrawParametersFeatures structure 1982 * [[VUID-VkDeviceCreateInfo-pNext-02830]] 1983 If the pname:pNext chain includes a 1984 slink:VkPhysicalDeviceVulkan12Features structure, then it must: not 1985 include a slink:VkPhysicalDevice8BitStorageFeatures, 1986 slink:VkPhysicalDeviceShaderAtomicInt64Features, 1987 slink:VkPhysicalDeviceShaderFloat16Int8Features, 1988 slink:VkPhysicalDeviceDescriptorIndexingFeatures, 1989 slink:VkPhysicalDeviceScalarBlockLayoutFeatures, 1990 slink:VkPhysicalDeviceImagelessFramebufferFeatures, 1991 slink:VkPhysicalDeviceUniformBufferStandardLayoutFeatures, 1992 slink:VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures, 1993 slink:VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures, 1994 slink:VkPhysicalDeviceHostQueryResetFeatures, 1995 slink:VkPhysicalDeviceTimelineSemaphoreFeatures, 1996 slink:VkPhysicalDeviceBufferDeviceAddressFeatures, or 1997 slink:VkPhysicalDeviceVulkanMemoryModelFeatures structure 1998ifdef::VK_KHR_shader_draw_parameters[] 1999 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-04476]] 2000 If pname:ppEnabledExtensionNames contains 2001 `"VK_KHR_shader_draw_parameters"` and the pname:pNext chain includes a 2002 slink:VkPhysicalDeviceVulkan11Features structure, then 2003 sname:VkPhysicalDeviceVulkan11Features::pname:shaderDrawParameters must: 2004 be ename:VK_TRUE 2005endif::VK_KHR_shader_draw_parameters[] 2006ifdef::VK_KHR_draw_indirect_count[] 2007 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02831]] 2008 If pname:ppEnabledExtensionNames contains `"VK_KHR_draw_indirect_count"` 2009 and the pname:pNext chain includes a 2010 slink:VkPhysicalDeviceVulkan12Features structure, then 2011 sname:VkPhysicalDeviceVulkan12Features::pname:drawIndirectCount must: be 2012 ename:VK_TRUE 2013endif::VK_KHR_draw_indirect_count[] 2014ifdef::VK_KHR_sampler_mirror_clamp_to_edge[] 2015 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02832]] 2016 If pname:ppEnabledExtensionNames contains 2017 `"VK_KHR_sampler_mirror_clamp_to_edge"` and the pname:pNext chain 2018 includes a slink:VkPhysicalDeviceVulkan12Features structure, then 2019 sname:VkPhysicalDeviceVulkan12Features::pname:samplerMirrorClampToEdge 2020 must: be ename:VK_TRUE 2021endif::VK_KHR_sampler_mirror_clamp_to_edge[] 2022ifdef::VK_EXT_descriptor_indexing[] 2023 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02833]] 2024 If pname:ppEnabledExtensionNames contains `"VK_EXT_descriptor_indexing"` 2025 and the pname:pNext chain includes a 2026 slink:VkPhysicalDeviceVulkan12Features structure, then 2027 sname:VkPhysicalDeviceVulkan12Features::pname:descriptorIndexing must: 2028 be ename:VK_TRUE 2029endif::VK_EXT_descriptor_indexing[] 2030ifdef::VK_EXT_sampler_filter_minmax[] 2031 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02834]] 2032 If pname:ppEnabledExtensionNames contains 2033 `"VK_EXT_sampler_filter_minmax"` and the pname:pNext chain includes a 2034 slink:VkPhysicalDeviceVulkan12Features structure, then 2035 sname:VkPhysicalDeviceVulkan12Features::pname:samplerFilterMinmax must: 2036 be ename:VK_TRUE 2037endif::VK_EXT_sampler_filter_minmax[] 2038ifdef::VK_EXT_shader_viewport_index_layer[] 2039 * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02835]] 2040 If pname:ppEnabledExtensionNames contains 2041 `"VK_EXT_shader_viewport_index_layer"` and the pname:pNext chain 2042 includes a slink:VkPhysicalDeviceVulkan12Features structure, then 2043 sname:VkPhysicalDeviceVulkan12Features::pname:shaderOutputViewportIndex 2044 and sname:VkPhysicalDeviceVulkan12Features::pname:shaderOutputLayer 2045 must: both be ename:VK_TRUE 2046endif::VK_EXT_shader_viewport_index_layer[] 2047endif::VK_VERSION_1_2[] 2048ifdef::VK_VERSION_1_3[] 2049 * [[VUID-VkDeviceCreateInfo-pNext-06532]] 2050 If the pname:pNext chain includes a 2051 slink:VkPhysicalDeviceVulkan13Features structure, then it must: not 2052 include a slink:VkPhysicalDeviceDynamicRenderingFeatures, 2053 slink:VkPhysicalDeviceImageRobustnessFeatures, 2054 slink:VkPhysicalDeviceInlineUniformBlockFeatures, 2055 slink:VkPhysicalDeviceMaintenance4Features, 2056 slink:VkPhysicalDevicePipelineCreationCacheControlFeatures, 2057 slink:VkPhysicalDevicePrivateDataFeatures, 2058 slink:VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures, 2059 slink:VkPhysicalDeviceShaderIntegerDotProductFeatures, 2060 slink:VkPhysicalDeviceShaderTerminateInvocationFeatures, 2061 slink:VkPhysicalDeviceSubgroupSizeControlFeatures, 2062 slink:VkPhysicalDeviceSynchronization2Features, 2063 slink:VkPhysicalDeviceTextureCompressionASTCHDRFeatures, or 2064 slink:VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures structure 2065// Jon 1.3 TBD - add extension-specific VUs specifying when Vulkan13Features 2066// members must: be true. 2067endif::VK_VERSION_1_3[] 2068ifdef::VK_KHR_portability_subset[] 2069 * [[VUID-VkDeviceCreateInfo-pProperties-04451]] 2070 If the `apiext:VK_KHR_portability_subset` extension is included in 2071 pname:pProperties of flink:vkEnumerateDeviceExtensionProperties, 2072 pname:ppEnabledExtensionNames must: include 2073 `"VK_KHR_portability_subset"` 2074endif::VK_KHR_portability_subset[] 2075ifdef::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[] 2076 * [[VUID-VkDeviceCreateInfo-shadingRateImage-04478]] 2077 If the <<features-shadingRateImage, pname:shadingRateImage>> feature is 2078 enabled, the <<features-pipelineFragmentShadingRate, 2079 pname:pipelineFragmentShadingRate>> feature must: not be enabled 2080 * [[VUID-VkDeviceCreateInfo-shadingRateImage-04479]] 2081 If the <<features-shadingRateImage, pname:shadingRateImage>> feature is 2082 enabled, the <<features-primitiveFragmentShadingRate, 2083 pname:primitiveFragmentShadingRate>> feature must: not be enabled 2084 * [[VUID-VkDeviceCreateInfo-shadingRateImage-04480]] 2085 If the <<features-shadingRateImage, pname:shadingRateImage>> feature is 2086 enabled, the <<features-attachmentFragmentShadingRate, 2087 pname:attachmentFragmentShadingRate>> feature must: not be enabled 2088endif::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[] 2089ifdef::VK_KHR_fragment_shading_rate+VK_EXT_fragment_density_map[] 2090 * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04481]] 2091 If the <<features-fragmentDensityMap, pname:fragmentDensityMap>> feature 2092 is enabled, the <<features-pipelineFragmentShadingRate, 2093 pname:pipelineFragmentShadingRate>> feature must: not be enabled 2094 * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04482]] 2095 If the <<features-fragmentDensityMap, pname:fragmentDensityMap>> feature 2096 is enabled, the <<features-primitiveFragmentShadingRate, 2097 pname:primitiveFragmentShadingRate>> feature must: not be enabled 2098 * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04483]] 2099 If the <<features-fragmentDensityMap, pname:fragmentDensityMap>> feature 2100 is enabled, the <<features-attachmentFragmentShadingRate, 2101 pname:attachmentFragmentShadingRate>> feature must: not be enabled 2102endif::VK_KHR_fragment_shading_rate+VK_EXT_fragment_density_map[] 2103ifdef::VK_EXT_shader_image_atomic_int64[] 2104 * [[VUID-VkDeviceCreateInfo-None-04896]] 2105 If <<features-sparseImageInt64Atomics, pname:sparseImageInt64Atomics>> 2106 is enabled, <<features-shaderImageInt64Atomics, 2107 pname:shaderImageInt64Atomics>> must: be enabled 2108endif::VK_EXT_shader_image_atomic_int64[] 2109ifdef::VK_EXT_shader_atomic_float[] 2110 * [[VUID-VkDeviceCreateInfo-None-04897]] 2111 If <<features-sparseImageFloat32Atomics, 2112 pname:sparseImageFloat32Atomics>> is enabled, 2113 <<features-shaderImageFloat32Atomics, pname:shaderImageFloat32Atomics>> 2114 must: be enabled 2115 * [[VUID-VkDeviceCreateInfo-None-04898]] 2116 If <<features-sparseImageFloat32AtomicAdd, 2117 pname:sparseImageFloat32AtomicAdd>> is enabled, 2118 <<features-shaderImageFloat32AtomicAdd, 2119 pname:shaderImageFloat32AtomicAdd>> must: be enabled 2120endif::VK_EXT_shader_atomic_float[] 2121ifdef::VK_EXT_shader_atomic_float2[] 2122 * [[VUID-VkDeviceCreateInfo-sparseImageFloat32AtomicMinMax-04975]] 2123 If <<features-sparseImageFloat32AtomicMinMax, 2124 pname:sparseImageFloat32AtomicMinMax>> is enabled, 2125 <<features-shaderImageFloat32AtomicMinMax, 2126 pname:shaderImageFloat32AtomicMinMax>> must: be enabled 2127endif::VK_EXT_shader_atomic_float2[] 2128ifdef::VK_EXT_descriptor_buffer[] 2129ifdef::VK_AMD_shader_fragment_mask[] 2130 * [[VUID-VkDeviceCreateInfo-None-08095]] 2131 If <<features-descriptorBuffer, pname:descriptorBuffer>> is enabled, 2132 pname:ppEnabledExtensionNames must: not contain 2133 `apiext:VK_AMD_shader_fragment_mask` 2134endif::VK_AMD_shader_fragment_mask[] 2135endif::VK_EXT_descriptor_buffer[] 2136ifdef::VK_ARM_scheduling_controls[] 2137 * [[VUID-VkDeviceCreateInfo-pNext-09396]] 2138 If the pname:pNext chain includes a 2139 slink:VkDeviceQueueShaderCoreControlCreateInfoARM structure, then it 2140 must: not be included in the pname:pNext chain of any of the 2141 slink:VkDeviceQueueCreateInfo structures in pname:pQueueCreateInfos. 2142 * [[VUID-VkDeviceCreateInfo-pNext-09397]] 2143 If the pname:pNext chain includes a 2144 slink:VkDeviceQueueShaderCoreControlCreateInfoARM structure then 2145 slink:VkPhysicalDeviceSchedulingControlsPropertiesARM::pname:schedulingControlsFlags 2146 must: contain 2147 ename:VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM. 2148endif::VK_ARM_scheduling_controls[] 2149**** 2150 2151include::{generated}/validity/structs/VkDeviceCreateInfo.adoc[] 2152-- 2153 2154[open,refpage='VkDeviceCreateFlags',desc='Reserved for future use',type='flags'] 2155-- 2156include::{generated}/api/flags/VkDeviceCreateFlags.adoc[] 2157 2158tname:VkDeviceCreateFlags is a bitmask type for setting a mask, but is 2159currently reserved for future use. 2160-- 2161 2162ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[] 2163[open,refpage='VkDeviceGroupDeviceCreateInfo',desc='Create a logical device from multiple physical devices',type='structs'] 2164-- 2165A logical device can: be created that connects to one or more physical 2166devices by adding a sname:VkDeviceGroupDeviceCreateInfo structure to the 2167pname:pNext chain of slink:VkDeviceCreateInfo. 2168The sname:VkDeviceGroupDeviceCreateInfo structure is defined as: 2169 2170include::{generated}/api/structs/VkDeviceGroupDeviceCreateInfo.adoc[] 2171 2172ifdef::VK_KHR_device_group_creation[] 2173or the equivalent 2174 2175include::{generated}/api/structs/VkDeviceGroupDeviceCreateInfoKHR.adoc[] 2176endif::VK_KHR_device_group_creation[] 2177 2178 * pname:sType is a elink:VkStructureType value identifying this structure. 2179 * pname:pNext is `NULL` or a pointer to a structure extending this 2180 structure. 2181 * pname:physicalDeviceCount is the number of elements in the 2182 pname:pPhysicalDevices array. 2183 * pname:pPhysicalDevices is a pointer to an array of physical device 2184 handles belonging to the same device group. 2185 2186The elements of the pname:pPhysicalDevices array are an ordered list of the 2187physical devices that the logical device represents. 2188These must: be a subset of a single device group, and need not be in the 2189same order as they were enumerated. 2190The order of the physical devices in the pname:pPhysicalDevices array 2191determines the _device index_ of each physical device, with element [eq]#i# 2192being assigned a device index of [eq]#i#. 2193Certain commands and structures refer to one or more physical devices by 2194using device indices or _device masks_ formed using device indices. 2195 2196A logical device created without using sname:VkDeviceGroupDeviceCreateInfo, 2197or with pname:physicalDeviceCount equal to zero, is equivalent to a 2198pname:physicalDeviceCount of one and pname:pPhysicalDevices pointing to the 2199pname:physicalDevice parameter to flink:vkCreateDevice. 2200In particular, the device index of that physical device is zero. 2201 2202.Valid Usage 2203**** 2204 * [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00375]] 2205 Each element of pname:pPhysicalDevices must: be unique 2206 * [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00376]] 2207 All elements of pname:pPhysicalDevices must: be in the same device group 2208 as enumerated by flink:vkEnumeratePhysicalDeviceGroups 2209 * [[VUID-VkDeviceGroupDeviceCreateInfo-physicalDeviceCount-00377]] 2210 If pname:physicalDeviceCount is not `0`, the pname:physicalDevice 2211 parameter of flink:vkCreateDevice must: be an element of 2212 pname:pPhysicalDevices 2213**** 2214 2215include::{generated}/validity/structs/VkDeviceGroupDeviceCreateInfo.adoc[] 2216-- 2217endif::VK_VERSION_1_1,VK_KHR_device_group_creation[] 2218 2219ifdef::VK_AMD_memory_overallocation_behavior[] 2220[open,refpage='VkDeviceMemoryOverallocationCreateInfoAMD',desc='Specify memory overallocation behavior for a Vulkan device',type='structs'] 2221-- 2222To specify whether device memory allocation is allowed beyond the size 2223reported by slink:VkPhysicalDeviceMemoryProperties, add a 2224slink:VkDeviceMemoryOverallocationCreateInfoAMD structure to the pname:pNext 2225chain of the slink:VkDeviceCreateInfo structure. 2226If this structure is not specified, it is as if the 2227ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD value is used. 2228 2229include::{generated}/api/structs/VkDeviceMemoryOverallocationCreateInfoAMD.adoc[] 2230 2231 * pname:sType is a elink:VkStructureType value identifying this structure. 2232 * pname:pNext is `NULL` or a pointer to a structure extending this 2233 structure. 2234 * pname:overallocationBehavior is the desired overallocation behavior. 2235 2236include::{generated}/validity/structs/VkDeviceMemoryOverallocationCreateInfoAMD.adoc[] 2237-- 2238 2239[open,refpage='VkMemoryOverallocationBehaviorAMD',desc='Specify memory overallocation behavior',type='enums'] 2240-- 2241Possible values for 2242slink:VkDeviceMemoryOverallocationCreateInfoAMD::pname:overallocationBehavior 2243include: 2244 2245include::{generated}/api/enums/VkMemoryOverallocationBehaviorAMD.adoc[] 2246 2247 * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD lets the 2248 implementation decide if overallocation is allowed. 2249 * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_ALLOWED_AMD specifies 2250 overallocation is allowed if platform permits. 2251 * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DISALLOWED_AMD specifies the 2252 application is not allowed to allocate device memory beyond the heap 2253 sizes reported by slink:VkPhysicalDeviceMemoryProperties. 2254 Allocations that are not explicitly made by the application within the 2255 scope of the Vulkan instance are not accounted for. 2256-- 2257endif::VK_AMD_memory_overallocation_behavior[] 2258 2259ifdef::VK_NV_device_diagnostics_config[] 2260[open,refpage='VkDeviceDiagnosticsConfigCreateInfoNV',desc='Specify diagnostics config for a Vulkan device',type='structs'] 2261-- 2262When using the Nsight^(TM)^ Aftermath SDK, to configure how device crash 2263dumps are created, add a slink:VkDeviceDiagnosticsConfigCreateInfoNV 2264structure to the pname:pNext chain of the slink:VkDeviceCreateInfo 2265structure. 2266 2267include::{generated}/api/structs/VkDeviceDiagnosticsConfigCreateInfoNV.adoc[] 2268 2269 * pname:sType is a elink:VkStructureType value identifying this structure. 2270 * pname:pNext is `NULL` or a pointer to a structure extending this 2271 structure. 2272 * pname:flags is a bitmask of elink:VkDeviceDiagnosticsConfigFlagBitsNV 2273 specifying additional parameters for configuring diagnostic tools. 2274 2275include::{generated}/validity/structs/VkDeviceDiagnosticsConfigCreateInfoNV.adoc[] 2276-- 2277 2278[open,refpage='VkDeviceDiagnosticsConfigFlagBitsNV',desc='Bitmask specifying diagnostics flags',type='enums'] 2279-- 2280Bits which can: be set in 2281slink:VkDeviceDiagnosticsConfigCreateInfoNV::pname:flags include: 2282 2283include::{generated}/api/enums/VkDeviceDiagnosticsConfigFlagBitsNV.adoc[] 2284 2285 * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_DEBUG_INFO_BIT_NV 2286 enables the generation of debug information for shaders. 2287 * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_RESOURCE_TRACKING_BIT_NV 2288 enables driver side tracking of resources (images, buffers, etc.) used 2289 to augment the device fault information. 2290 * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_AUTOMATIC_CHECKPOINTS_BIT_NV 2291 enables automatic insertion of <<device-diagnostic-checkpoints, 2292 diagnostic checkpoints>> for draw calls, dispatches, 2293ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2294 trace rays, 2295endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] 2296 and copies. 2297 The CPU call stack at the time of the command will be associated as the 2298 marker data for the automatically inserted checkpoints. 2299 * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_ERROR_REPORTING_BIT_NV 2300 enables shader error reporting. 2301-- 2302 2303[open,refpage='VkDeviceDiagnosticsConfigFlagsNV',desc='Bitmask of VkDeviceDiagnosticsConfigFlagBitsNV',type='flags'] 2304-- 2305include::{generated}/api/flags/VkDeviceDiagnosticsConfigFlagsNV.adoc[] 2306 2307tname:VkDeviceDiagnosticsConfigFlagsNV is a bitmask type for setting a mask 2308of zero or more elink:VkDeviceDiagnosticsConfigFlagBitsNV. 2309-- 2310endif::VK_NV_device_diagnostics_config[] 2311 2312ifdef::VK_EXT_device_memory_report[] 2313[open,refpage='VkDeviceDeviceMemoryReportCreateInfoEXT',desc='Register device memory report callbacks for a Vulkan device',type='structs'] 2314-- 2315To register callbacks for underlying device memory events of type 2316elink:VkDeviceMemoryReportEventTypeEXT, add one or multiple 2317slink:VkDeviceDeviceMemoryReportCreateInfoEXT structures to the pname:pNext 2318chain of the slink:VkDeviceCreateInfo structure. 2319 2320include::{generated}/api/structs/VkDeviceDeviceMemoryReportCreateInfoEXT.adoc[] 2321 2322 * pname:sType is a elink:VkStructureType value identifying this structure. 2323 * pname:pNext is `NULL` or a pointer to a structure extending this 2324 structure. 2325 * pname:flags is 0 and reserved for future use. 2326 * pname:pfnUserCallback is the application callback function to call. 2327 * pname:pUserData is user data to be passed to the callback. 2328 2329The callback may: be called from multiple threads simultaneously. 2330 2331The callback must: be called only once by the implementation when a 2332elink:VkDeviceMemoryReportEventTypeEXT event occurs. 2333 2334[NOTE] 2335.Note 2336==== 2337The callback could be called from a background thread other than the thread 2338calling the Vulkan commands. 2339==== 2340 2341include::{generated}/validity/structs/VkDeviceDeviceMemoryReportCreateInfoEXT.adoc[] 2342-- 2343 2344[open,refpage='PFN_vkDeviceMemoryReportCallbackEXT',desc='Application-defined device memory report callback function',type='funcpointers'] 2345-- 2346The prototype for the 2347slink:VkDeviceDeviceMemoryReportCreateInfoEXT::pname:pfnUserCallback 2348function implemented by the application is: 2349 2350include::{generated}/api/funcpointers/PFN_vkDeviceMemoryReportCallbackEXT.adoc[] 2351 2352 * pname:pCallbackData contains all the callback related data in the 2353 slink:VkDeviceMemoryReportCallbackDataEXT structure. 2354 * pname:pUserData is the user data provided when the 2355 slink:VkDeviceDeviceMemoryReportCreateInfoEXT was created. 2356 2357The callback must: not make calls to any Vulkan commands. 2358-- 2359 2360[open,refpage='VkDeviceMemoryReportCallbackDataEXT',desc='Structure specifying parameters returned to the callback',type='structs'] 2361-- 2362The definition of sname:VkDeviceMemoryReportCallbackDataEXT is: 2363 2364include::{generated}/api/structs/VkDeviceMemoryReportCallbackDataEXT.adoc[] 2365 2366 * pname:sType is a elink:VkStructureType value identifying this structure. 2367 * pname:pNext is `NULL` or a pointer to a structure extending this 2368 structure. 2369 * pname:flags is 0 and reserved for future use. 2370 * pname:type is a elink:VkDeviceMemoryReportEventTypeEXT type specifying 2371 the type of event reported in this 2372 sname:VkDeviceMemoryReportCallbackDataEXT structure. 2373 * pname:memoryObjectId is the unique id for the underlying memory object 2374 as described below. 2375 * pname:size is the size of the memory object in bytes. 2376 If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, 2377 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT or 2378 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, 2379 pname:size is a valid basetype:VkDeviceSize value. 2380 Otherwise, pname:size is undefined:. 2381 * pname:objectType is a elink:VkObjectType value specifying the type of 2382 the object associated with this device memory report event. 2383 If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, 2384 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT, 2385 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT, 2386 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT or 2387 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, 2388 pname:objectType is a valid elink:VkObjectType enum. 2389 Otherwise, pname:objectType is undefined:. 2390 * pname:objectHandle is the object this device memory report event is 2391 attributed to. 2392 If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, 2393 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT, 2394 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT or 2395 ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT, 2396 pname:objectHandle is a valid Vulkan handle of the type associated with 2397 pname:objectType as defined in the <<debugging-object-types, 2398 `VkObjectType` and Vulkan Handle Relationship>> table. 2399 Otherwise, pname:objectHandle is undefined:. 2400 * pname:heapIndex describes which memory heap this device memory 2401 allocation is made from. 2402 If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT 2403 or ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, 2404 pname:heapIndex corresponds to one of the valid heaps from the 2405 slink:VkPhysicalDeviceMemoryProperties structure. 2406 Otherwise, pname:heapIndex is undefined:. 2407 2408pname:memoryObjectId is used to avoid double-counting on the same memory 2409object. 2410 2411If an internally-allocated device memory object or a slink:VkDeviceMemory 2412cannot: be exported, pname:memoryObjectId must: be unique in the 2413slink:VkDevice. 2414 2415If an internally-allocated device memory object or a slink:VkDeviceMemory 2416supports being exported, pname:memoryObjectId must: be unique system wide. 2417 2418If an internal device memory object or a slink:VkDeviceMemory is backed by 2419an imported external memory object, pname:memoryObjectId must: be unique 2420system wide. 2421 2422ifdef::implementation-guide[] 2423.Implementor's Note 2424**** 2425If the heap backing an internally-allocated device memory cannot: be used to 2426back slink:VkDeviceMemory, implementations can: advertise that heap with no 2427types. 2428**** 2429endif::implementation-guide[] 2430 2431[NOTE] 2432.Note 2433==== 2434This structure should only be considered valid during the lifetime of the 2435triggered callback. 2436 2437For ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT and 2438ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT events, 2439pname:objectHandle usually will not yet exist when the application or tool 2440receives the callback. 2441pname:objectHandle will only exist when the create or allocate call that 2442triggered the event returns, and if the allocation or import ends up failing 2443pname:objectHandle will not ever exist. 2444==== 2445 2446include::{generated}/validity/structs/VkDeviceMemoryReportCallbackDataEXT.adoc[] 2447-- 2448 2449[open,refpage='VkDeviceMemoryReportFlagsEXT',desc='Reserved for future use',type='flags'] 2450-- 2451include::{generated}/api/flags/VkDeviceMemoryReportFlagsEXT.adoc[] 2452 2453tname:VkDeviceMemoryReportFlagsEXT is a bitmask type for setting a mask, but 2454is currently reserved for future use. 2455-- 2456 2457[open,refpage='VkDeviceMemoryReportEventTypeEXT',desc='Events that can occur on a device memory object',type='enums'] 2458-- 2459Possible values of slink:VkDeviceMemoryReportCallbackDataEXT::pname:type, 2460specifying event types which cause the device driver to call the callback, 2461are: 2462 2463include::{generated}/api/enums/VkDeviceMemoryReportEventTypeEXT.adoc[] 2464 2465 * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT specifies this 2466 event corresponds to the allocation of an internal device memory object 2467 or a slink:VkDeviceMemory. 2468 * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT specifies this event 2469 corresponds to the deallocation of an internally-allocated device memory 2470 object or a slink:VkDeviceMemory. 2471 * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT specifies this event 2472 corresponds to the import of an external memory object. 2473 * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT specifies this 2474 event is the release of an imported external memory object. 2475 * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT specifies 2476 this event corresponds to the failed allocation of an internal device 2477 memory object or a slink:VkDeviceMemory. 2478-- 2479endif::VK_EXT_device_memory_report[] 2480 2481ifdef::VK_VERSION_1_3,VK_EXT_private_data[] 2482[open,refpage='VkDevicePrivateDataCreateInfo',desc='Reserve private data slots',type='structs',alias='VkDevicePrivateDataCreateInfoEXT'] 2483-- 2484To reserve private data storage slots, add a 2485slink:VkDevicePrivateDataCreateInfo structure to the pname:pNext chain of 2486the slink:VkDeviceCreateInfo structure. 2487Reserving slots in this manner is not strictly necessary, but doing so may: 2488improve performance. 2489 2490include::{generated}/api/structs/VkDevicePrivateDataCreateInfo.adoc[] 2491 2492ifdef::VK_EXT_private_data[] 2493or the equivalent 2494 2495include::{generated}/api/structs/VkDevicePrivateDataCreateInfoEXT.adoc[] 2496endif::VK_EXT_private_data[] 2497 2498 * pname:sType is a elink:VkStructureType value identifying this structure. 2499 * pname:pNext is `NULL` or a pointer to a structure extending this 2500 structure. 2501 * pname:privateDataSlotRequestCount is the amount of slots to reserve. 2502 2503include::{generated}/validity/structs/VkDevicePrivateDataCreateInfo.adoc[] 2504-- 2505endif::VK_VERSION_1_3,VK_EXT_private_data[] 2506 2507ifdef::VKSC_VERSION_1_0[] 2508 2509[open,refpage='VkDeviceObjectReservationCreateInfo',desc='Request memory reservation',type='structs'] 2510-- 2511Data structures for objects are reserved by the implementation at device 2512creation time. 2513The application must: provide upper bounds on numbers of objects and other 2514limits at device creation time. 2515To reserve data structures for use by objects created from this device, add 2516a slink:VkDeviceObjectReservationCreateInfo structure to the pname:pNext 2517chain of the slink:VkDeviceCreateInfo structure. 2518 2519include::{generated}/api/structs/VkDeviceObjectReservationCreateInfo.adoc[] 2520 2521 * pname:sType is a elink:VkStructureType value identifying this structure. 2522 * pname:pNext is `NULL` or a pointer to a structure extending this 2523 structure. 2524 * pname:pipelineCacheCreateInfoCount is the length of the 2525 pname:pPipelineCacheCreateInfos array. 2526 * pname:pPipelineCacheCreateInfos is a pointer to an array of 2527 slink:VkPipelineCacheCreateInfo structures that contain the creation 2528 information of the pipeline caches that can: be created on this device. 2529 * pname:pipelinePoolSizeCount is the length of the 2530 pname:pPipelinePoolSizes array. 2531 * pname:pPipelinePoolSizes is a pointer to an array of 2532 slink:VkPipelinePoolSize structures requesting memory be reserved for 2533 pipelines of the specified sizes. 2534 * pname:semaphoreRequestCount is the requested maximum number of 2535 sname:VkSemaphore objects that can: exist at the same time. 2536 * pname:commandBufferRequestCount is the requested maximum number of 2537 sname:VkCommandBuffer objects that can: be reserved by all 2538 sname:VkCommandPool objects. 2539 * pname:fenceRequestCount is the requested maximum number of sname:VkFence 2540 objects that can: exist at the same time. 2541 * pname:deviceMemoryRequestCount is the requested maximum number of 2542 sname:VkDeviceMemory objects that can: exist at the same time. 2543 * pname:bufferRequestCount is the requested maximum number of 2544 sname:VkBuffer objects that can: exist at the same time. 2545 * pname:imageRequestCount is the requested maximum number of sname:VkImage 2546 objects that can: exist at the same time. 2547 * pname:eventRequestCount is the requested maximum number of sname:VkEvent 2548 objects that can: exist at the same time. 2549 * pname:queryPoolRequestCount is the requested maximum number of 2550 sname:VkQueryPool objects that can: exist at the same time. 2551 * pname:bufferViewRequestCount is the requested maximum number of 2552 sname:VkBufferView objects that can: exist at the same time. 2553 * pname:imageViewRequestCount is the requested maximum number of 2554 sname:VkImageView objects that can: exist at the same time. 2555 * pname:layeredImageViewRequestCount is the requested maximum number 2556 sname:VkImageView objects created with 2557 slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount greater 2558 than `1` that can: exist at the same time. 2559 * pname:pipelineCacheRequestCount is the requested maximum number of 2560 sname:VkPipelineCache objects that can: exist at the same time. 2561 * pname:pipelineLayoutRequestCount is the requested maximum number of 2562 sname:VkPipelineLayout objects that can: exist at the same time. 2563 * pname:renderPassRequestCount is the requested maximum number of 2564 sname:VkRenderPass objects that can: exist at the same time. 2565 * pname:graphicsPipelineRequestCount is the requested maximum number of 2566 graphics sname:VkPipeline objects that can: exist at the same time. 2567 * pname:computePipelineRequestCount is the requested maximum number of 2568 compute sname:VkPipeline objects that can: exist at the same time. 2569 * pname:descriptorSetLayoutRequestCount is the requested maximum number of 2570 sname:VkDescriptorSetLayout objects that can: exist at the same time. 2571 * pname:samplerRequestCount is the requested maximum number of 2572 sname:VkSampler objects that can: exist at the same time. 2573 * pname:descriptorPoolRequestCount is the requested maximum number of 2574 sname:VkDescriptorPool objects that can: exist at the same time. 2575 * pname:descriptorSetRequestCount is the requested maximum number of 2576 sname:VkDescriptorSet objects that can: exist at the same time. 2577 * pname:framebufferRequestCount is the requested maximum number of 2578 sname:VkFramebuffer objects that can: exist at the same time. 2579 * pname:commandPoolRequestCount is the requested maximum number of 2580 sname:VkCommandPool objects that can: exist at the same time. 2581 * pname:samplerYcbcrConversionRequestCount is the requested maximum number 2582 of sname:VkSamplerYcbcrConversion objects that can: exist at the same 2583 time. 2584 * pname:surfaceRequestCount is deprecated and implementations must: ignore 2585 it. 2586 * pname:swapchainRequestCount is the requested maximum number of 2587 sname:VkSwapchainKHR objects that can: exist at the same time. 2588 * pname:displayModeRequestCount is deprecated and implementations must: 2589 ignore it. 2590 * pname:subpassDescriptionRequestCount is the requested maximum sum of all 2591 slink:VkRenderPassCreateInfo2::pname:subpassCount values across all 2592 sname:VkRenderPass objects that can: exist at the same time. 2593 * pname:attachmentDescriptionRequestCount is the requested maximum sum of 2594 all slink:VkRenderPassCreateInfo2::pname:attachmentCount values across 2595 all sname:VkRenderPass objects that can: exist at the same time. 2596 * pname:descriptorSetLayoutBindingRequestCount is the requested maximum 2597 sum of all slink:VkDescriptorSetLayoutCreateInfo::pname:bindingCount 2598 values across all sname:VkDescriptorSetLayout objects that can: exist at 2599 the same time. 2600 * pname:descriptorSetLayoutBindingLimit is one greater than the maximum 2601 value of slink:VkDescriptorSetLayoutBinding::pname:binding that can: be 2602 used. 2603 * pname:maxImageViewMipLevels is the maximum value of 2604 slink:VkImageViewCreateInfo::pname:subresourceRange.levelCount that can: 2605 be used. 2606 * pname:maxImageViewArrayLayers is the maximum value of 2607 slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount that can: 2608 be used. 2609 * pname:maxLayeredImageViewMipLevels is the maximum value of 2610 slink:VkImageViewCreateInfo::pname:subresourceRange.levelCount that can: 2611 be used when 2612 slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount is 2613 greater than `1`. 2614 * pname:maxOcclusionQueriesPerPool is the requested maximum number of 2615 ename:VK_QUERY_TYPE_OCCLUSION queries that can: exist at the same time 2616 in a single query pool. 2617 * pname:maxPipelineStatisticsQueriesPerPool is the requested maximum 2618 number of ename:VK_QUERY_TYPE_PIPELINE_STATISTICS queries that can: 2619 exist at the same time in a single query pool. 2620 * pname:maxTimestampQueriesPerPool is the requested maximum number of 2621 ename:VK_QUERY_TYPE_TIMESTAMP queries that can: exist at the same time 2622 in a single query pool. 2623 * pname:maxImmutableSamplersPerDescriptorSetLayout is the requested 2624 maximum number of immutable samplers that can be used across all 2625 bindings in a descriptor set layout. 2626 2627Multiple sname:VkDeviceObjectReservationCreateInfo structures can: be 2628chained together. 2629The maximum value from all instances of pname:maxImageViewMipLevels, 2630pname:maxImageViewArrayLayers, pname:maxLayeredImageViewMipLevels, 2631pname:descriptorSetLayoutBindingLimit, pname:maxOcclusionQueriesPerPool, 2632pname:maxPipelineStatisticsQueriesPerPool, pname:maxTimestampQueriesPerPool, 2633and pname:maxImmutableSamplersPerDescriptorSetLayout will be reserved. 2634For the remaining members, the sum of the requested resources from all 2635instances of sname:VkDeviceObjectReservationCreateInfo will be reserved. 2636 2637If 2638slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory, 2639pname:deviceDestroyFreesMemory>> is ename:VK_TRUE, the reserved memory is 2640returned to the system when the device is destroyed, otherwise it may: not 2641be returned to the system until the process is terminated. 2642 2643ifdef::hidden[] 2644// tag::scaddition[] 2645 * slink:VkDeviceObjectReservationCreateInfo <<SCID-4>> 2646// end::scaddition[] 2647endif::hidden[] 2648 2649.Valid Usage 2650**** 2651 * [[VUID-VkDeviceObjectReservationCreateInfo-maxImageViewArrayLayers-05014]] 2652 pname:maxImageViewArrayLayers must: be less than or equal to 2653 slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers 2654 * [[VUID-VkDeviceObjectReservationCreateInfo-maxImageViewMipLevels-05015]] 2655 pname:maxImageViewMipLevels must: be less than or equal to the number of 2656 levels in the complete mipmap chain based on the maximum of 2657 slink:VkPhysicalDeviceLimits::pname:maxImageDimension1D, 2658 pname:maxImageDimension2D, pname:maxImageDimension3D, and 2659 pname:maxImageDimensionCube 2660 * [[VUID-VkDeviceObjectReservationCreateInfo-maxLayeredImageViewMipLevels-05016]] 2661 pname:maxLayeredImageViewMipLevels must: be less than or equal to the 2662 number of levels in the complete mipmap chain based on 2663 slink:VkPhysicalDeviceLimits::pname:maxImageDimension1D, 2664 pname:maxImageDimension2D, pname:maxImageDimension3D, and 2665 pname:maxImageDimensionCube 2666 * [[VUID-VkDeviceObjectReservationCreateInfo-subpassDescriptionRequestCount-05017]] 2667 pname:subpassDescriptionRequestCount must: be less than or equal to 2668 pname:renderPassRequestCount multiplied by 2669 slink:VkPhysicalDeviceVulkanSC10Properties::pname:maxRenderPassSubpasses 2670 * [[VUID-VkDeviceObjectReservationCreateInfo-attachmentDescriptionRequestCount-05018]] 2671 pname:attachmentDescriptionRequestCount must: be less than or equal to 2672 pname:renderPassRequestCount multiplied by 2673 slink:VkPhysicalDeviceVulkanSC10Properties::pname:maxFramebufferAttachments 2674**** 2675 2676include::{generated}/validity/structs/VkDeviceObjectReservationCreateInfo.adoc[] 2677-- 2678 2679ifdef::VK_KHR_performance_query[] 2680[open,refpage='VkPerformanceQueryReservationInfoKHR',desc='Request memory reservation',type='structs'] 2681-- 2682If the pname:pNext chain of slink:VkDeviceObjectReservationCreateInfo 2683includes a slink:VkPerformanceQueryReservationInfoKHR structure, then the 2684structure indicates upper bounds on the number of performance queries that 2685can: exist at the same time in a query pool. 2686 2687The sname:VkPerformanceQueryReservationInfoKHR structure is defined as: 2688 2689include::{generated}/api/structs/VkPerformanceQueryReservationInfoKHR.adoc[] 2690 2691 * pname:sType is a elink:VkStructureType value identifying this structure. 2692 * pname:pNext is `NULL` or a pointer to a structure extending this 2693 structure. 2694 * pname:maxPerformanceQueriesPerPool is the requested maximum number of 2695 ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR queries that can: exist at the 2696 same time in a single query pool. 2697 2698If the sname:VkDeviceObjectReservationCreateInfo::pname:pNext chain does not 2699include this structure, then pname:maxPerformanceQueriesPerPool defaults to 2700`0`. 2701 2702Multiple sname:VkPerformanceQueryReservationInfoKHR structures can be 2703chained together. 2704The maximum value from all instances of pname:maxPerformanceQueriesPerPool 2705will be reserved. 2706 2707ifdef::hidden[] 2708// tag::scaddition[] 2709ifdef::VK_KHR_performance_query[] 2710 * slink:VkPerformanceQueryReservationInfoKHR <<SCID-4>> 2711endif::VK_KHR_performance_query[] 2712// end::scaddition[] 2713endif::hidden[] 2714 2715include::{generated}/validity/structs/VkPerformanceQueryReservationInfoKHR.adoc[] 2716-- 2717endif::VK_KHR_performance_query[] 2718 2719ifdef::VK_NV_external_sci_sync2[] 2720[open,refpage='VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV',desc='Request memory reservation',type='structs'] 2721-- 2722If the pname:pNext chain of slink:VkDeviceObjectReservationCreateInfo 2723includes a slink:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV 2724structure, then the structure indicates the maximum number of 2725slink:VkSemaphoreSciSyncPoolNV objects that can: exist at the same time. 2726 2727The sname:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV structure is 2728defined as: 2729 2730include::{generated}/api/structs/VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV.adoc[] 2731 2732 * pname:sType is a elink:VkStructureType value identifying this structure. 2733 * pname:pNext is `NULL` or a pointer to a structure extending this 2734 structure. 2735 * pname:semaphoreSciSyncPoolRequestCount is the requested maximum number 2736 of slink:VkSemaphoreSciSyncPoolNV objects that can: exist at the same 2737 time. 2738 2739If the sname:VkDeviceObjectReservationCreateInfo::pname:pNext chain does not 2740include this structure, then pname:semaphoreSciSyncPoolRequestCount defaults 2741to `0`. 2742 2743Multiple sname:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV 2744structures can: be chained together. 2745The sum of the pname:semaphoreSciSyncPoolRequestCount values from all 2746instances of sname:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV will 2747be reserved. 2748 2749include::{generated}/validity/structs/VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV.adoc[] 2750-- 2751endif::VK_NV_external_sci_sync2[] 2752 2753[open,refpage='VkPipelinePoolSize',desc='Request memory for pipelines',type='structs'] 2754-- 2755Memory for pipelines is reserved by the implementation at device creation 2756time. 2757The application specifies sizes to be reserved and a count for each size, 2758and when a pipeline is created the application specifies which size to use. 2759 2760include::{generated}/api/structs/VkPipelinePoolSize.adoc[] 2761 2762 * pname:sType is a elink:VkStructureType value identifying this structure. 2763 * pname:pNext is `NULL` or a pointer to a structure extending this 2764 structure. 2765 * pname:poolEntrySize is the size to reserve for each entry. 2766 * pname:poolEntryCount is the number of entries to reserve. 2767 2768ifdef::hidden[] 2769// tag::scaddition[] 2770 * slink:VkPipelinePoolSize <<SCID-4>> 2771// end::scaddition[] 2772endif::hidden[] 2773 2774include::{generated}/validity/structs/VkPipelinePoolSize.adoc[] 2775-- 2776 2777endif::VKSC_VERSION_1_0[] 2778 2779ifdef::VK_ARM_scheduling_controls[] 2780The number of shader cores used by all the queues of a device can: be 2781controlled by adding a sname:VkDeviceQueueShaderCoreControlCreateInfoARM 2782structure to the pname:pNext chain of the slink:VkDeviceCreateInfo 2783structure. 2784endif::VK_ARM_scheduling_controls[] 2785 2786[[devsandqueues-use]] 2787=== Device Use 2788 2789The following is a high-level list of sname:VkDevice uses along with 2790references on where to find more information: 2791 2792 * Creation of queues. 2793 See the <<devsandqueues-queues,Queues>> section below for further 2794 details. 2795 * Creation and tracking of various synchronization constructs. 2796 See <<synchronization,Synchronization and Cache Control>> for further 2797 details. 2798 * Allocating, freeing, and managing memory. 2799 See <<memory,Memory Allocation>> and <<resources,Resource Creation>> for 2800 further details. 2801 * Creation and destruction of command buffers and command buffer pools. 2802 See <<commandbuffers,Command Buffers>> for further details. 2803 * Creation, destruction, and management of graphics state. 2804 See <<pipelines,Pipelines>> and <<descriptorsets,Resource Descriptors>>, 2805 among others, for further details. 2806 2807 2808[[devsandqueues-lost-device]] 2809=== Lost Device 2810 2811A logical device may: become _lost_ for a number of implementation-specific 2812reasons, indicating that pending and future command execution may: fail and 2813cause resources and backing memory to become undefined:. 2814 2815ifdef::VKSC_VERSION_1_0[] 2816[NOTE] 2817.Note 2818==== 2819<<fault-handling>> can be used by the implementation to provide more 2820information on the cause of a device becoming _lost_. 2821Allowing applications to take appropriate corrective behavior for the cause 2822of the device lost. 2823==== 2824endif::VKSC_VERSION_1_0[] 2825 2826[NOTE] 2827.Note 2828==== 2829Typical reasons for device loss will include things like execution timing 2830out (to prevent denial of service), power management events, platform 2831resource management, implementation errors. 2832 2833Applications not adhering to <<fundamentals-validusage, valid usage>> may 2834also result in device loss being reported, however this is not guaranteed. 2835Even if device loss is reported, the system may be in an unrecoverable 2836state, and further usage of the API is still considered invalid. 2837==== 2838 2839When this happens, certain commands will return ename:VK_ERROR_DEVICE_LOST. 2840After any such event, the logical device is considered _lost_. 2841It is not possible to reset the logical device to a non-lost state, however 2842the lost state is specific to a logical device (sname:VkDevice), and the 2843corresponding physical device (sname:VkPhysicalDevice) may: be otherwise 2844unaffected. 2845 2846In some cases, the physical device may: also be lost, and attempting to 2847create a new logical device will fail, returning ename:VK_ERROR_DEVICE_LOST. 2848This is usually indicative of a problem with the underlying implementation, 2849or its connection to the host. 2850If the physical device has not been lost, and a new logical device is 2851successfully created from that physical device, it must: be in the non-lost 2852state. 2853 2854[NOTE] 2855.Note 2856==== 2857Whilst logical device loss may: be recoverable, in the case of physical 2858device loss, it is unlikely that an application will be able to recover 2859unless additional, unaffected physical devices exist on the system. 2860The error is largely informational and intended only to inform the user that 2861a platform issue has occurred, and should: be investigated further. 2862For example, underlying hardware may: have developed a fault or become 2863physically disconnected from the rest of the system. 2864In many cases, physical device loss may: cause other more serious issues 2865such as the operating system crashing; in which case it may: not be reported 2866via the Vulkan API. 2867==== 2868 2869When a device is lost, its child objects are not implicitly destroyed and 2870their handles are still valid. 2871Those objects must: still be destroyed before their parents or the device 2872can: be destroyed (see the <<fundamentals-objectmodel-lifetime,Object 2873Lifetime>> section). 2874The host address space corresponding to device memory mapped using 2875flink:vkMapMemory is still valid, and host memory accesses to these mapped 2876regions are still valid, but the contents are undefined:. 2877It is still legal to call any API command on the device and child objects. 2878 2879Once a device is lost, command execution may: fail, and certain commands 2880that return a elink:VkResult may: return ename:VK_ERROR_DEVICE_LOST. 2881These commands can be identified by the inclusion of 2882ename:VK_ERROR_DEVICE_LOST in the Return Codes section for each command. 2883Commands that do not allow runtime errors must: still operate correctly for 2884valid usage and, if applicable, return valid data. 2885 2886Commands that wait indefinitely for device execution (namely 2887flink:vkDeviceWaitIdle, flink:vkQueueWaitIdle, flink:vkWaitForFences 2888ifdef::VK_KHR_swapchain[] 2889or flink:vkAcquireNextImageKHR 2890endif::VK_KHR_swapchain[] 2891with a maximum pname:timeout, and flink:vkGetQueryPoolResults with the 2892ename:VK_QUERY_RESULT_WAIT_BIT bit set in pname:flags) must: return in 2893finite time even in the case of a lost device, and return either 2894ename:VK_SUCCESS or ename:VK_ERROR_DEVICE_LOST. 2895For any command that may: return ename:VK_ERROR_DEVICE_LOST, for the purpose 2896of determining whether a command buffer is in the 2897<<commandbuffers-lifecycle, pending state>>, or whether resources are 2898considered in-use by the device, a return value of 2899ename:VK_ERROR_DEVICE_LOST is equivalent to ename:VK_SUCCESS. 2900 2901ifdef::VK_KHR_maintenance5[] 2902If a device was created with the <<features-maintenance5, 2903pname:maintenance5>> feature enabled, and any device command returns 2904ename:VK_ERROR_DEVICE_LOST, then all device commands for which 2905ename:VK_ERROR_DEVICE_LOST is a valid return value and which happen-after it 2906on the same host thread must: return ename:VK_ERROR_DEVICE_LOST. 2907 2908Device commands executing on other threads must: begin returning 2909ename:VK_ERROR_DEVICE_LOST within finite time. 2910endif::VK_KHR_maintenance5[] 2911 2912ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] 2913 2914The content of any external memory objects that have been exported from or 2915imported to a lost device become undefined:. 2916Objects on other logical devices or in other APIs which are associated with 2917the same underlying memory resource as the external memory objects on the 2918lost device are unaffected other than their content becoming undefined:. 2919The layout of subresources of images on other logical devices that are bound 2920to sname:VkDeviceMemory objects associated with the same underlying memory 2921resources as external memory objects on the lost device becomes 2922ename:VK_IMAGE_LAYOUT_UNDEFINED. 2923 2924endif::VK_VERSION_1_1,VK_KHR_external_memory[] 2925 2926ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[] 2927 2928The state of sname:VkSemaphore objects on other logical devices created by 2929<<synchronization-semaphores-importing,importing a semaphore payload>> with 2930temporary permanence which was exported from the lost device is undefined:. 2931The state of sname:VkSemaphore objects on other logical devices that 2932permanently share a semaphore payload with a sname:VkSemaphore object on the 2933lost device is undefined:, and remains undefined: following any subsequent 2934signal operations. 2935Implementations must: ensure pending and subsequently submitted wait 2936operations on such semaphores behave as defined in 2937<<synchronization-semaphores-waiting-state,Semaphore State Requirements For 2938Wait Operations>> for external semaphores not in a valid state for a wait 2939operation. 2940 2941endif::VK_VERSION_1_1,VK_KHR_external_semaphore[] 2942 2943ifdef::editing-notes[] 2944[NOTE] 2945.editing-note 2946==== 2947TODO (piman) - I do not think we are very clear about what "`in-use by the 2948device`" means. 2949==== 2950endif::editing-notes[] 2951 2952 2953[[devsandqueues-destruction]] 2954=== Device Destruction 2955 2956[open,refpage='vkDestroyDevice',desc='Destroy a logical device',type='protos'] 2957-- 2958To destroy a device, call: 2959 2960include::{generated}/api/protos/vkDestroyDevice.adoc[] 2961 2962 * pname:device is the logical device to destroy. 2963 * pname:pAllocator controls host memory allocation as described in the 2964 <<memory-allocation, Memory Allocation>> chapter. 2965 2966To ensure that no work is active on the device, flink:vkDeviceWaitIdle can: 2967be used to gate the destruction of the device. 2968Prior to destroying a device, an application is responsible for 2969destroying/freeing any Vulkan objects that were created using that device as 2970the first parameter of the corresponding ftext:vkCreate* or 2971ftext:vkAllocate* command. 2972 2973[NOTE] 2974.Note 2975==== 2976The lifetime of each of these objects is bound by the lifetime of the 2977sname:VkDevice object. 2978Therefore, to avoid resource leaks, it is critical that an application 2979explicitly free all of these resources prior to calling 2980fname:vkDestroyDevice. 2981==== 2982 2983ifdef::VKSC_VERSION_1_0[] 2984If 2985slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory, 2986pname:deviceDestroyFreesMemory>> is ename:VK_TRUE, the reserved memory for 2987child objects without explicit free or destroy commands is returned to the 2988system when the device is destroyed, otherwise it may: not be returned to 2989the system until the process is terminated. 2990endif::VKSC_VERSION_1_0[] 2991 2992.Valid Usage 2993**** 2994 * [[VUID-vkDestroyDevice-device-05137]] 2995 All child objects created on pname:device 2996ifdef::VKSC_VERSION_1_0[] 2997 , except those with no explicit <<fundamentals-objectmodel-no-destroy, 2998 free or destroy command>>, 2999endif::VKSC_VERSION_1_0[] 3000 must: have been destroyed prior to destroying pname:device 3001ifndef::VKSC_VERSION_1_0[] 3002 * [[VUID-vkDestroyDevice-device-00379]] 3003 If sname:VkAllocationCallbacks were provided when pname:device was 3004 created, a compatible set of callbacks must: be provided here 3005 * [[VUID-vkDestroyDevice-device-00380]] 3006 If no sname:VkAllocationCallbacks were provided when pname:device was 3007 created, pname:pAllocator must: be `NULL` 3008endif::VKSC_VERSION_1_0[] 3009**** 3010 3011include::{generated}/validity/protos/vkDestroyDevice.adoc[] 3012-- 3013 3014 3015[[devsandqueues-queues]] 3016== Queues 3017 3018 3019[[devsandqueues-queueprops]] 3020=== Queue Family Properties 3021 3022As discussed in the <<devsandqueues-physical-device-enumeration,Physical 3023Device Enumeration>> section above, the 3024flink:vkGetPhysicalDeviceQueueFamilyProperties command is used to retrieve 3025details about the queue families and queues supported by a device. 3026 3027Each index in the pname:pQueueFamilyProperties array returned by 3028flink:vkGetPhysicalDeviceQueueFamilyProperties describes a unique queue 3029family on that physical device. 3030These indices are used when creating queues, and they correspond directly 3031with the pname:queueFamilyIndex that is passed to the flink:vkCreateDevice 3032command via the slink:VkDeviceQueueCreateInfo structure as described in the 3033<<devsandqueues-queue-creation,Queue Creation>> section below. 3034 3035Grouping of queue families within a physical device is 3036implementation-dependent. 3037 3038[NOTE] 3039.Note 3040==== 3041The general expectation is that a physical device groups all queues of 3042matching capabilities into a single family. 3043However, while implementations should: do this, it is possible that a 3044physical device may: return two separate queue families with the same 3045capabilities. 3046==== 3047 3048Once an application has identified a physical device with the queue(s) that 3049it desires to use, it will create those queues in conjunction with a logical 3050device. 3051This is described in the following section. 3052 3053 3054[[devsandqueues-queue-creation]] 3055=== Queue Creation 3056 3057[open,refpage='VkQueue',desc='Opaque handle to a queue object',type='handles'] 3058-- 3059Creating a logical device also creates the queues associated with that 3060device. 3061The queues to create are described by a set of slink:VkDeviceQueueCreateInfo 3062structures that are passed to flink:vkCreateDevice in 3063pname:pQueueCreateInfos. 3064 3065Queues are represented by sname:VkQueue handles: 3066 3067include::{generated}/api/handles/VkQueue.adoc[] 3068-- 3069 3070[open,refpage='VkDeviceQueueCreateInfo',desc='Structure specifying parameters of a newly created device queue',type='structs'] 3071-- 3072The sname:VkDeviceQueueCreateInfo structure is defined as: 3073 3074include::{generated}/api/structs/VkDeviceQueueCreateInfo.adoc[] 3075 3076 * pname:sType is a elink:VkStructureType value identifying this structure. 3077 * pname:pNext is `NULL` or a pointer to a structure extending this 3078 structure. 3079ifndef::VK_VERSION_1_1[] 3080 * pname:flags is reserved for future use. 3081endif::VK_VERSION_1_1[] 3082ifdef::VK_VERSION_1_1[] 3083 * pname:flags is a bitmask indicating behavior of the queues. 3084endif::VK_VERSION_1_1[] 3085 * pname:queueFamilyIndex is an unsigned integer indicating the index of 3086 the queue family in which to create the queues on this device. 3087 This index corresponds to the index of an element of the 3088 pname:pQueueFamilyProperties array that was returned by 3089 fname:vkGetPhysicalDeviceQueueFamilyProperties. 3090 * pname:queueCount is an unsigned integer specifying the number of queues 3091 to create in the queue family indicated by pname:queueFamilyIndex, and 3092 with the behavior specified by pname:flags. 3093 * pname:pQueuePriorities is a pointer to an array of pname:queueCount 3094 normalized floating point values, specifying priorities of work that 3095 will be submitted to each created queue. 3096 See <<devsandqueues-priority,Queue Priority>> for more information. 3097 3098.Valid Usage 3099**** 3100 * [[VUID-VkDeviceQueueCreateInfo-queueFamilyIndex-00381]] 3101 pname:queueFamilyIndex must: be less than 3102 pname:pQueueFamilyPropertyCount returned by 3103 fname:vkGetPhysicalDeviceQueueFamilyProperties 3104 * [[VUID-VkDeviceQueueCreateInfo-queueCount-00382]] 3105 pname:queueCount must: be less than or equal to the pname:queueCount 3106 member of the sname:VkQueueFamilyProperties structure, as returned by 3107 fname:vkGetPhysicalDeviceQueueFamilyProperties in the 3108 pname:pQueueFamilyProperties[queueFamilyIndex] 3109 * [[VUID-VkDeviceQueueCreateInfo-pQueuePriorities-00383]] 3110 Each element of pname:pQueuePriorities must: be between `0.0` and `1.0` 3111 inclusive 3112ifdef::VK_VERSION_1_1[] 3113 * [[VUID-VkDeviceQueueCreateInfo-flags-02861]] 3114 If the <<features-protectedMemory, pname:protectedMemory>> feature is 3115 not enabled, the ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit of 3116 pname:flags must: not be set 3117 * [[VUID-VkDeviceQueueCreateInfo-flags-06449]] 3118 If pname:flags includes ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, 3119 pname:queueFamilyIndex must: be the index of a queue family that 3120 includes the ename:VK_QUEUE_PROTECTED_BIT capability 3121endif::VK_VERSION_1_1[] 3122ifdef::VK_ARM_scheduling_controls[] 3123 * [[VUID-VkDeviceQueueCreateInfo-pNext-09398]] 3124 If the pname:pNext chain includes a 3125 slink:VkDeviceQueueShaderCoreControlCreateInfoARM structure then 3126 slink:VkPhysicalDeviceSchedulingControlsPropertiesARM::pname:schedulingControlsFlags 3127 must: contain 3128 ename:VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM. 3129endif::VK_ARM_scheduling_controls[] 3130**** 3131 3132include::{generated}/validity/structs/VkDeviceQueueCreateInfo.adoc[] 3133-- 3134 3135ifdef::VK_VERSION_1_1[] 3136[open,refpage='VkDeviceQueueCreateFlagBits',desc='Bitmask specifying behavior of the queue',type='enums'] 3137-- 3138Bits which can: be set in slink:VkDeviceQueueCreateInfo::pname:flags, 3139specifying usage behavior of a queue, are: 3140 3141include::{generated}/api/enums/VkDeviceQueueCreateFlagBits.adoc[] 3142 3143 * ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT specifies that the device 3144 queue is a protected-capable queue. 3145-- 3146endif::VK_VERSION_1_1[] 3147 3148[open,refpage='VkDeviceQueueCreateFlags',desc='Bitmask of VkDeviceQueueCreateFlagBits',type='flags'] 3149-- 3150include::{generated}/api/flags/VkDeviceQueueCreateFlags.adoc[] 3151 3152ifndef::VK_VERSION_1_1[] 3153tname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask, but is 3154currently reserved for future use. 3155endif::VK_VERSION_1_1[] 3156ifdef::VK_VERSION_1_1[] 3157tname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask of zero 3158or more elink:VkDeviceQueueCreateFlagBits. 3159endif::VK_VERSION_1_1[] 3160-- 3161 3162ifdef::VK_EXT_global_priority,VK_KHR_global_priority[] 3163[open,refpage='VkDeviceQueueGlobalPriorityCreateInfoKHR',desc='Specify a system wide priority',type='structs',alias='VkDeviceQueueGlobalPriorityCreateInfoEXT'] 3164-- 3165Queues can: be created with a system-wide priority by adding a 3166sname:VkDeviceQueueGlobalPriorityCreateInfoKHR structure to the pname:pNext 3167chain of slink:VkDeviceQueueCreateInfo. 3168 3169The sname:VkDeviceQueueGlobalPriorityCreateInfoKHR structure is defined as: 3170 3171include::{generated}/api/structs/VkDeviceQueueGlobalPriorityCreateInfoKHR.adoc[] 3172 3173ifdef::VK_EXT_global_priority[] 3174or the equivalent 3175 3176include::{generated}/api/structs/VkDeviceQueueGlobalPriorityCreateInfoEXT.adoc[] 3177endif::VK_EXT_global_priority[] 3178 3179 * pname:sType is a elink:VkStructureType value identifying this structure. 3180 * pname:pNext is `NULL` or a pointer to a structure extending this 3181 structure. 3182 * pname:globalPriority is the system-wide priority associated to these 3183 queues as specified by elink:VkQueueGlobalPriorityEXT 3184 3185Queues created without specifying 3186sname:VkDeviceQueueGlobalPriorityCreateInfoKHR will default to 3187ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR. 3188 3189include::{generated}/validity/structs/VkDeviceQueueGlobalPriorityCreateInfoKHR.adoc[] 3190-- 3191 3192[open,refpage='VkQueueGlobalPriorityKHR',desc='Values specifying a system-wide queue priority',type='enums',alias='VkQueueGlobalPriorityEXT'] 3193-- 3194Possible values of 3195slink:VkDeviceQueueGlobalPriorityCreateInfoKHR::pname:globalPriority, 3196specifying a system-wide priority level are: 3197 3198include::{generated}/api/enums/VkQueueGlobalPriorityKHR.adoc[] 3199 3200ifdef::VK_EXT_global_priority[] 3201or the equivalent 3202 3203include::{generated}/api/enums/VkQueueGlobalPriorityEXT.adoc[] 3204endif::VK_EXT_global_priority[] 3205 3206Priority values are sorted in ascending order. 3207A comparison operation on the enum values can be used to determine the 3208priority order. 3209 3210 * ename:VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR is below the system default. 3211 Useful for non-interactive tasks. 3212 * ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR is the system default 3213 priority. 3214 * ename:VK_QUEUE_GLOBAL_PRIORITY_HIGH_KHR is above the system default. 3215 * ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR is the highest priority. 3216 Useful for critical tasks. 3217-- 3218 3219Queues with higher system priority may: be allotted more processing time 3220than queues with lower priority. 3221An implementation may: allow a higher-priority queue to starve a 3222lower-priority queue until the higher-priority queue has no further commands 3223to execute. 3224 3225Priorities imply no ordering or scheduling constraints. 3226 3227No specific guarantees are made about higher priority queues receiving more 3228processing time or better quality of service than lower priority queues. 3229 3230The global priority level of a queue takes precedence over the per-process 3231queue priority (slink:VkDeviceQueueCreateInfo::pname:pQueuePriorities). 3232 3233Abuse of this feature may: result in starving the rest of the system of 3234implementation resources. 3235Therefore, the driver implementation may: deny requests to acquire a 3236priority above the default priority 3237(ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR) if the caller does not have 3238sufficient privileges. 3239In this scenario ename:VK_ERROR_NOT_PERMITTED_KHR is returned. 3240 3241The driver implementation may: fail the queue allocation request if 3242resources required to complete the operation have been exhausted (either by 3243the same process or a different process). 3244In this scenario ename:VK_ERROR_INITIALIZATION_FAILED is returned. 3245 3246ifdef::VK_EXT_global_priority_query,VK_KHR_global_priority[] 3247If the <<features-globalPriorityQuery, pname:globalPriorityQuery>> feature 3248is enabled and the requested global priority is not reported via 3249slink:VkQueueFamilyGlobalPriorityPropertiesKHR, the driver implementation 3250must: fail the queue creation. 3251In this scenario, ename:VK_ERROR_INITIALIZATION_FAILED is returned. 3252endif::VK_EXT_global_priority_query,VK_KHR_global_priority[] 3253endif::VK_EXT_global_priority,VK_KHR_global_priority[] 3254 3255ifdef::VK_ARM_scheduling_controls[] 3256[open,refpage='VkDeviceQueueShaderCoreControlCreateInfoARM',desc='Control the number of shader cores used by queues',type='structs'] 3257-- 3258The number of shader cores used by a queue can: be controlled by adding a 3259sname:VkDeviceQueueShaderCoreControlCreateInfoARM structure to the 3260pname:pNext chain of slink:VkDeviceQueueCreateInfo structures. 3261 3262The sname:VkDeviceQueueShaderCoreControlCreateInfoARM structure is defined 3263as: 3264 3265include::{generated}/api/structs/VkDeviceQueueShaderCoreControlCreateInfoARM.adoc[] 3266 3267 * pname:sType is a elink:VkStructureType value identifying this structure. 3268 * pname:pNext is `NULL` or a pointer to a structure extending this 3269 structure. 3270 * pname:shaderCoreCount is the number of shader cores this queue uses. 3271 3272Queues created without specifying 3273sname:VkDeviceQueueShaderCoreControlCreateInfoARM will default to using all 3274the shader cores available. 3275 3276.Valid Usage 3277**** 3278 * [[VUID-VkDeviceQueueShaderCoreControlCreateInfoARM-shaderCoreCount-09399]] 3279 pname:shaderCoreCount must: be greater than 0 and less than or equal to 3280 the total number of shader cores as reported via 3281 slink:VkPhysicalDeviceShaderCoreBuiltinsPropertiesARM::pname:shaderCoreCount. 3282**** 3283 3284include::{generated}/validity/structs/VkDeviceQueueShaderCoreControlCreateInfoARM.adoc[] 3285-- 3286endif::VK_ARM_scheduling_controls[] 3287 3288[open,refpage='vkGetDeviceQueue',desc='Get a queue handle from a device',type='protos'] 3289-- 3290To retrieve a handle to a slink:VkQueue object, call: 3291 3292include::{generated}/api/protos/vkGetDeviceQueue.adoc[] 3293 3294 * pname:device is the logical device that owns the queue. 3295 * pname:queueFamilyIndex is the index of the queue family to which the 3296 queue belongs. 3297 * pname:queueIndex is the index within this queue family of the queue to 3298 retrieve. 3299 * pname:pQueue is a pointer to a slink:VkQueue object that will be filled 3300 with the handle for the requested queue. 3301 3302ifdef::VK_VERSION_1_1[] 3303fname:vkGetDeviceQueue must: only be used to get queues that were created 3304with the pname:flags parameter of slink:VkDeviceQueueCreateInfo set to zero. 3305To get queues that were created with a non-zero pname:flags parameter use 3306flink:vkGetDeviceQueue2. 3307endif::VK_VERSION_1_1[] 3308 3309.Valid Usage 3310**** 3311 * [[VUID-vkGetDeviceQueue-queueFamilyIndex-00384]] 3312 pname:queueFamilyIndex must: be one of the queue family indices 3313 specified when pname:device was created, via the 3314 slink:VkDeviceQueueCreateInfo structure 3315 * [[VUID-vkGetDeviceQueue-queueIndex-00385]] 3316 pname:queueIndex must: be less than the value of 3317 slink:VkDeviceQueueCreateInfo::pname:queueCount for the queue family 3318 indicated by pname:queueFamilyIndex when pname:device was created 3319 * [[VUID-vkGetDeviceQueue-flags-01841]] 3320 slink:VkDeviceQueueCreateInfo::pname:flags must: have been set to zero 3321 when pname:device was created 3322**** 3323 3324include::{generated}/validity/protos/vkGetDeviceQueue.adoc[] 3325-- 3326 3327ifdef::VK_VERSION_1_1[] 3328[open,refpage='vkGetDeviceQueue2',desc='Get a queue handle from a device',type='protos'] 3329-- 3330To retrieve a handle to a slink:VkQueue object with specific 3331tlink:VkDeviceQueueCreateFlags creation flags, call: 3332 3333include::{generated}/api/protos/vkGetDeviceQueue2.adoc[] 3334 3335 * pname:device is the logical device that owns the queue. 3336 * pname:pQueueInfo is a pointer to a slink:VkDeviceQueueInfo2 structure, 3337 describing parameters of the device queue to be retrieved. 3338 * pname:pQueue is a pointer to a slink:VkQueue object that will be filled 3339 with the handle for the requested queue. 3340 3341include::{generated}/validity/protos/vkGetDeviceQueue2.adoc[] 3342-- 3343 3344[open,refpage='VkDeviceQueueInfo2',desc='Structure specifying the parameters used for device queue creation',type='structs'] 3345-- 3346The sname:VkDeviceQueueInfo2 structure is defined as: 3347 3348include::{generated}/api/structs/VkDeviceQueueInfo2.adoc[] 3349 3350 * pname:sType is a elink:VkStructureType value identifying this structure. 3351 * pname:pNext is `NULL` or a pointer to a structure extending this 3352 structure. 3353 The pname:pNext chain of sname:VkDeviceQueueInfo2 can: be used to 3354 provide additional device queue parameters to fname:vkGetDeviceQueue2. 3355 * pname:flags is a tlink:VkDeviceQueueCreateFlags value indicating the 3356 flags used to create the device queue. 3357 * pname:queueFamilyIndex is the index of the queue family to which the 3358 queue belongs. 3359 * pname:queueIndex is the index of the queue to retrieve from within the 3360 set of queues that share both the queue family and flags specified. 3361 3362The queue returned by fname:vkGetDeviceQueue2 must: have the same 3363pname:flags value from this structure as that used at device creation time 3364in a slink:VkDeviceQueueCreateInfo structure. 3365 3366[NOTE] 3367.Note 3368==== 3369Normally, if you create both protected-capable and non-protected-capable 3370queues with the same family, they are treated as separate lists of queues 3371and pname:queueIndex is relative to the start of the list of queues 3372specified by both pname:queueFamilyIndex and pname:flags. 3373However, for historical reasons, some implementations may exhibit different 3374behavior. 3375These divergent implementations instead concatenate the lists of queues and 3376treat pname:queueIndex as relative to the start of the first list of queues 3377with the given pname:queueFamilyIndex. 3378This only matters in cases where an application has created both 3379protected-capable and non-protected-capable queues from the same queue 3380family. 3381 3382For such divergent implementations, the maximum value of pname:queueIndex is 3383equal to the sum of slink:VkDeviceQueueCreateInfo::pname:queueCount minus 3384one, for all slink:VkDeviceQueueCreateInfo structures that share a common 3385pname:queueFamilyIndex. 3386 3387Such implementations will return `NULL` for either the protected or 3388unprotected queues when calling `vkGetDeviceQueue2` with pname:queueIndex in 3389the range zero to slink:VkDeviceQueueCreateInfo::pname:queueCount minus one. 3390In cases where these implementations returned `NULL`, the corresponding 3391queues are instead located in the extended range described in the preceding 3392two paragraphs. 3393 3394This behaviour will not be observed on any driver that has passed Vulkan 3395conformance test suite version 1.3.3.0, or any subsequent version. 3396This information can be found by querying 3397sname:VkPhysicalDeviceDriverProperties::pname:conformanceVersion. 3398==== 3399 3400.Valid Usage 3401**** 3402 * [[VUID-VkDeviceQueueInfo2-queueFamilyIndex-01842]] 3403 pname:queueFamilyIndex must: be one of the queue family indices 3404 specified when pname:device was created, via the 3405 slink:VkDeviceQueueCreateInfo structure 3406 * [[VUID-VkDeviceQueueInfo2-flags-06225]] 3407 pname:flags must: be equal to slink:VkDeviceQueueCreateInfo::pname:flags 3408 for a slink:VkDeviceQueueCreateInfo structure for the queue family 3409 indicated by pname:queueFamilyIndex when pname:device was created 3410 * [[VUID-VkDeviceQueueInfo2-queueIndex-01843]] 3411 pname:queueIndex must: be less than 3412 slink:VkDeviceQueueCreateInfo::pname:queueCount for the corresponding 3413 queue family and flags indicated by pname:queueFamilyIndex and 3414 pname:flags when pname:device was created 3415**** 3416 3417include::{generated}/validity/structs/VkDeviceQueueInfo2.adoc[] 3418-- 3419endif::VK_VERSION_1_1[] 3420 3421 3422[[devsandqueues-index]] 3423=== Queue Family Index 3424 3425The queue family index is used in multiple places in Vulkan in order to tie 3426operations to a specific family of queues. 3427 3428When retrieving a handle to the queue via fname:vkGetDeviceQueue, the queue 3429family index is used to select which queue family to retrieve the 3430sname:VkQueue handle from as described in the previous section. 3431 3432When creating a sname:VkCommandPool object (see 3433<<commandbuffers-pools,Command Pools>>), a queue family index is specified 3434in the slink:VkCommandPoolCreateInfo structure. 3435Command buffers from this pool can: only be submitted on queues 3436corresponding to this queue family. 3437 3438When creating sname:VkImage (see <<resources-images,Images>>) and 3439sname:VkBuffer (see <<resources-buffers,Buffers>>) resources, a set of queue 3440families is included in the slink:VkImageCreateInfo and 3441slink:VkBufferCreateInfo structures to specify the queue families that can: 3442access the resource. 3443 3444When inserting a slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier 3445(see <<synchronization-pipeline-barriers>>), a source and destination queue 3446family index is specified to allow the ownership of a buffer or image to be 3447transferred from one queue family to another. 3448See the <<resources-sharing,Resource Sharing>> section for details. 3449 3450 3451[[devsandqueues-priority]] 3452=== Queue Priority 3453 3454Each queue is assigned a priority, as set in the 3455slink:VkDeviceQueueCreateInfo structures when creating the device. 3456The priority of each queue is a normalized floating point value between 0.0 3457and 1.0, which is then translated to a discrete priority level by the 3458implementation. 3459Higher values indicate a higher priority, with 0.0 being the lowest priority 3460and 1.0 being the highest. 3461 3462Within the same device, queues with higher priority may: be allotted more 3463processing time than queues with lower priority. 3464The implementation makes no guarantees with regards to ordering or 3465scheduling among queues with the same priority, other than the constraints 3466defined by any <<synchronization, explicit synchronization primitives>>. 3467The implementation makes no guarantees with regards to queues across 3468different devices. 3469 3470An implementation may: allow a higher-priority queue to starve a 3471lower-priority queue on the same sname:VkDevice until the higher-priority 3472queue has no further commands to execute. 3473The relationship of queue priorities must: not cause queues on one 3474sname:VkDevice to starve queues on another sname:VkDevice. 3475 3476No specific guarantees are made about higher priority queues receiving more 3477processing time or better quality of service than lower priority queues. 3478 3479 3480[[devsandqueues-submission]] 3481=== Queue Submission 3482 3483Work is submitted to a queue via _queue submission_ commands such as 3484ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] 3485flink:vkQueueSubmit2 or 3486endif::VK_VERSION_1_3,VK_KHR_synchronization2[] 3487flink:vkQueueSubmit. 3488Queue submission commands define a set of _queue operations_ to be executed 3489by the underlying physical device, including synchronization with semaphores 3490and fences. 3491 3492Submission commands take as parameters a target queue, zero or more 3493_batches_ of work, and an optional: fence to signal upon completion. 3494Each batch consists of three distinct parts: 3495 3496 . Zero or more semaphores to wait on before execution of the rest of the 3497 batch. 3498 ** If present, these describe a <<synchronization-semaphores-waiting, 3499 semaphore wait operation>>. 3500 . Zero or more work items to execute. 3501 ** If present, these describe a _queue operation_ matching the work 3502 described. 3503 . Zero or more semaphores to signal upon completion of the work items. 3504 ** If present, these describe a <<synchronization-semaphores-signaling, 3505 semaphore signal operation>>. 3506 3507If a fence is present in a queue submission, it describes a 3508<<synchronization-fences-signaling, fence signal operation>>. 3509 3510All work described by a queue submission command must: be submitted to the 3511queue before the command returns. 3512 3513 3514ifndef::VKSC_VERSION_1_0[] 3515[[devsandqueues-sparsebinding]] 3516==== Sparse Memory Binding 3517 3518In Vulkan it is possible to sparsely bind memory to buffers and images as 3519described in the <<sparsememory,Sparse Resource>> chapter. 3520Sparse memory binding is a queue operation. 3521A queue whose flags include the ename:VK_QUEUE_SPARSE_BINDING_BIT must: be 3522able to support the mapping of a virtual address to a physical address on 3523the device. 3524This causes an update to the page table mappings on the device. 3525This update must: be synchronized on a queue to avoid corrupting page table 3526mappings during execution of graphics commands. 3527By binding the sparse memory resources on queues, all commands that are 3528dependent on the updated bindings are synchronized to only execute after the 3529binding is updated. 3530See the <<synchronization,Synchronization and Cache Control>> chapter for 3531how this synchronization is accomplished. 3532 3533endif::VKSC_VERSION_1_0[] 3534 3535[[devsandqueues-queuedestruction]] 3536=== Queue Destruction 3537 3538Queues are created along with a logical device during fname:vkCreateDevice. 3539All queues associated with a logical device are destroyed when 3540fname:vkDestroyDevice is called on that device. 3541