xref: /third_party/vk-gl-cts/external/vulkan-docs/src/chapters/devsandqueues.adoc

// Copyright 2015-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[devsandqueues]]
= Devices and Queues

Once Vulkan is initialized, devices and queues are the primary objects used
to interact with a Vulkan implementation.

[open,refpage='VkPhysicalDevice',desc='Opaque handle to a physical device object',type='handles']
--
Vulkan separates the concept of _physical_ and _logical_ devices.
A physical device usually represents a single complete implementation of
Vulkan (excluding instance-level functionality) available to the host, of
which there are a finite number.
A logical device represents an instance of that implementation with its own
state and resources independent of other logical devices.

Physical devices are represented by sname:VkPhysicalDevice handles:

include::{generated}/api/handles/VkPhysicalDevice.adoc[]
--


[[devsandqueues-physical-device-enumeration]]
== Physical Devices

[open,refpage='vkEnumeratePhysicalDevices',desc='Enumerates the physical devices accessible to a Vulkan instance',type='protos']
--
To retrieve a list of physical device objects representing the physical
devices installed in the system, call:

include::{generated}/api/protos/vkEnumeratePhysicalDevices.adoc[]

  * pname:instance is a handle to a Vulkan instance previously created with
    flink:vkCreateInstance.
  * pname:pPhysicalDeviceCount is a pointer to an integer related to the
    number of physical devices available or queried, as described below.
  * pname:pPhysicalDevices is either `NULL` or a pointer to an array of
    sname:VkPhysicalDevice handles.

If pname:pPhysicalDevices is `NULL`, then the number of physical devices
available is returned in pname:pPhysicalDeviceCount.
Otherwise, pname:pPhysicalDeviceCount must: point to a variable set by the
user to the number of elements in the pname:pPhysicalDevices array, and on
return the variable is overwritten with the number of handles actually
written to pname:pPhysicalDevices.
If pname:pPhysicalDeviceCount is less than the number of physical devices
available, at most pname:pPhysicalDeviceCount structures will be written,
and ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
indicate that not all the available physical devices were returned.

include::{generated}/validity/protos/vkEnumeratePhysicalDevices.adoc[]
--

[open,refpage='vkGetPhysicalDeviceProperties',desc='Returns properties of a physical device',type='protos']
--
To query general properties of physical devices once enumerated, call:

include::{generated}/api/protos/vkGetPhysicalDeviceProperties.adoc[]

  * pname:physicalDevice is the handle to the physical device whose
    properties will be queried.
  * pname:pProperties is a pointer to a slink:VkPhysicalDeviceProperties
    structure in which properties are returned.

include::{generated}/validity/protos/vkGetPhysicalDeviceProperties.adoc[]
--

[open,refpage='VkPhysicalDeviceProperties',desc='Structure specifying physical device properties',type='structs']
--
The sname:VkPhysicalDeviceProperties structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceProperties.adoc[]

  * pname:apiVersion is the version of Vulkan supported by the device,
    encoded as described in <<extendingvulkan-coreversions-versionnumbers>>.
  * pname:driverVersion is the vendor-specified version of the driver.
  * pname:vendorID is a unique identifier for the _vendor_ (see below) of
    the physical device.
  * pname:deviceID is a unique identifier for the physical device among
    devices available from the vendor.
  * pname:deviceType is a elink:VkPhysicalDeviceType specifying the type of
    device.
  * pname:deviceName is an array of ename:VK_MAX_PHYSICAL_DEVICE_NAME_SIZE
    code:char containing a null-terminated UTF-8 string which is the name of
    the device.
  * pname:pipelineCacheUUID is an array of ename:VK_UUID_SIZE code:uint8_t
    values representing a universally unique identifier for the device.
  * pname:limits is the slink:VkPhysicalDeviceLimits structure specifying
    device-specific limits of the physical device.
    See <<limits, Limits>> for details.
  * pname:sparseProperties is the slink:VkPhysicalDeviceSparseProperties
    structure specifying various sparse related properties of the physical
    device.
    See <<sparsememory-physicalprops, Sparse Properties>> for details.

ifdef::VK_VERSION_1_1[]
[NOTE]
.Note
====
The value of pname:apiVersion may: be different than the version returned by
flink:vkEnumerateInstanceVersion; either higher or lower.
In such cases, the application must: not use functionality that exceeds the
version of Vulkan associated with a given object.
The pname:pApiVersion parameter returned by flink:vkEnumerateInstanceVersion
is the version associated with a slink:VkInstance and its children, except
for a slink:VkPhysicalDevice and its children.
sname:VkPhysicalDeviceProperties::pname:apiVersion is the version associated
with a slink:VkPhysicalDevice and its children.
====
endif::VK_VERSION_1_1[]

[NOTE]
.Note
====
The encoding of pname:driverVersion is implementation-defined.
It may: not use the same encoding as pname:apiVersion.
Applications should follow information from the _vendor_ on how to extract
the version information from pname:driverVersion.
====

ifdef::VK_VERSION_1_3[]
On implementations that claim support for the <<roadmap-2022, Roadmap 2022>>
profile, the major and minor version expressed by pname:apiVersion must: be
at least Vulkan 1.3.
endif::VK_VERSION_1_3[]

The pname:vendorID and pname:deviceID fields are provided to allow
applications to adapt to device characteristics that are not adequately
exposed by other Vulkan queries.

[NOTE]
.Note
====
These may: include performance profiles, hardware errata, or other
characteristics.
====

The _vendor_ identified by pname:vendorID is the entity responsible for the
most salient characteristics of the underlying implementation of the
slink:VkPhysicalDevice being queried.

[NOTE]
.Note
====
For example, in the case of a discrete GPU implementation, this should: be
the GPU chipset vendor.
In the case of a hardware accelerator integrated into a system-on-chip
(SoC), this should: be the supplier of the silicon IP used to create the
accelerator.
====

If the vendor has a https://pcisig.com/membership/member-companies[PCI
vendor ID], the low 16 bits of pname:vendorID must: contain that PCI vendor
ID, and the remaining bits must: be set to zero.
Otherwise, the value returned must: be a valid Khronos vendor ID, obtained
as described in the <<vulkan-styleguide,Vulkan Documentation and Extensions:
Procedures and Conventions>> document in the section "`Registering a Vendor
ID with Khronos`".
Khronos vendor IDs are allocated starting at 0x10000, to distinguish them
from the PCI vendor ID namespace.
Khronos vendor IDs are symbolically defined in the elink:VkVendorId type.

The vendor is also responsible for the value returned in pname:deviceID.
If the implementation is driven primarily by a https://pcisig.com/[PCI
device] with a https://pcisig.com/[PCI device ID], the low 16 bits of
pname:deviceID must: contain that PCI device ID, and the remaining bits
must: be set to zero.
Otherwise, the choice of what values to return may: be dictated by operating
system or platform policies - but should: uniquely identify both the device
version and any major configuration options (for example, core count in the
case of multicore devices).

[NOTE]
.Note
====
The same device ID should: be used for all physical implementations of that
device version and configuration.
For example, all uses of a specific silicon IP GPU version and configuration
should: use the same device ID, even if those uses occur in different SoCs.
====

include::{generated}/validity/structs/VkPhysicalDeviceProperties.adoc[]
--

[open,refpage='VkVendorId',desc='Khronos vendor IDs',type='enums']
--
Khronos vendor IDs which may: be returned in
slink:VkPhysicalDeviceProperties::pname:vendorID are:

include::{generated}/api/enums/VkVendorId.adoc[]

[NOTE]
.Note
====
Khronos vendor IDs may be allocated by vendors at any time.
Only the latest canonical versions of this Specification, of the
corresponding `vk.xml` API Registry, and of the corresponding
`{core_header}` header file must: contain all reserved Khronos vendor IDs.

Only Khronos vendor IDs are given symbolic names at present.
PCI vendor IDs returned by the implementation can be looked up in the
PCI-SIG database.
====
--

[open,refpage='VK_MAX_PHYSICAL_DEVICE_NAME_SIZE',desc='Length of a physical device name string',type='consts']
--
ename:VK_MAX_PHYSICAL_DEVICE_NAME_SIZE is the length in code:char values of
an array containing a physical device name string, as returned in
slink:VkPhysicalDeviceProperties::pname:deviceName.

include::{generated}/api/enums/VK_MAX_PHYSICAL_DEVICE_NAME_SIZE.adoc[]
--

[open,refpage='VkPhysicalDeviceType',desc='Supported physical device types',type='enums']
--
The physical device types which may: be returned in
slink:VkPhysicalDeviceProperties::pname:deviceType are:

include::{generated}/api/enums/VkPhysicalDeviceType.adoc[]

  * ename:VK_PHYSICAL_DEVICE_TYPE_OTHER - the device does not match any
    other available types.
  * ename:VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU - the device is typically
    one embedded in or tightly coupled with the host.
  * ename:VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU - the device is typically a
    separate processor connected to the host via an interlink.
  * ename:VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU - the device is typically a
    virtual node in a virtualization environment.
  * ename:VK_PHYSICAL_DEVICE_TYPE_CPU - the device is typically running on
    the same processors as the host.

The physical device type is advertised for informational purposes only, and
does not directly affect the operation of the system.
However, the device type may: correlate with other advertised properties or
capabilities of the system, such as how many memory heaps there are.
--

ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[open,refpage='vkGetPhysicalDeviceProperties2',desc='Returns properties of a physical device',type='protos']
--
To query general properties of physical devices once enumerated, call:

ifdef::VK_VERSION_1_1[]
include::{generated}/api/protos/vkGetPhysicalDeviceProperties2.adoc[]
endif::VK_VERSION_1_1[]

ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command]

ifdef::VK_KHR_get_physical_device_properties2[]
include::{generated}/api/protos/vkGetPhysicalDeviceProperties2KHR.adoc[]
endif::VK_KHR_get_physical_device_properties2[]

  * pname:physicalDevice is the handle to the physical device whose
    properties will be queried.
  * pname:pProperties is a pointer to a slink:VkPhysicalDeviceProperties2
    structure in which properties are returned.

Each structure in pname:pProperties and its pname:pNext chain contains
members corresponding to implementation-dependent properties, behaviors, or
limits.
fname:vkGetPhysicalDeviceProperties2 fills in each member to specify the
corresponding value for the implementation.

include::{generated}/validity/protos/vkGetPhysicalDeviceProperties2.adoc[]
--

[open,refpage='VkPhysicalDeviceProperties2',desc='Structure specifying physical device properties',type='structs']
--
The sname:VkPhysicalDeviceProperties2 structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceProperties2.adoc[]

ifdef::VK_KHR_get_physical_device_properties2[]
or the equivalent

include::{generated}/api/structs/VkPhysicalDeviceProperties2KHR.adoc[]
endif::VK_KHR_get_physical_device_properties2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:properties is a slink:VkPhysicalDeviceProperties structure
    describing properties of the physical device.
    This structure is written with the same values as if it were written by
    flink:vkGetPhysicalDeviceProperties.

The pname:pNext chain of this structure is used to extend the structure with
properties defined by extensions.

include::{generated}/validity/structs/VkPhysicalDeviceProperties2.adoc[]
--

ifdef::VK_VERSION_1_2[]
[open,refpage='VkPhysicalDeviceVulkan11Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.1',type='structs']
--
The sname:VkPhysicalDeviceVulkan11Properties structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceVulkan11Properties.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.

:anchor-prefix:
include::{chapters}/devsandqueues.adoc[tag=VK_KHR_external_memory_capabilities-properties]
  * [[{anchor-prefix}limits-subgroup-size]] pname:subgroupSize is the
    default number of invocations in each subgroup.
    pname:subgroupSize is at least 1 if any of the physical device's queues
    support ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT.
    pname:subgroupSize is a power-of-two.
  * [[{anchor-prefix}limits-subgroupSupportedStages]]
    pname:subgroupSupportedStages is a bitfield of
    elink:VkShaderStageFlagBits describing the shader stages that
    <<shaders-group-operations, group operations>> with
    <<shaders-scope-subgroup, subgroup scope>> are supported in.
    pname:subgroupSupportedStages will have the
    ename:VK_SHADER_STAGE_COMPUTE_BIT bit set if any of the physical
    device's queues support ename:VK_QUEUE_COMPUTE_BIT.
  * pname:subgroupSupportedOperations is a bitmask of
    elink:VkSubgroupFeatureFlagBits specifying the sets of
    <<shaders-group-operations, group operations>> with
    <<shaders-scope-subgroup, subgroup scope>> supported on this device.
    pname:subgroupSupportedOperations will have the
    ename:VK_SUBGROUP_FEATURE_BASIC_BIT bit set if any of the physical
    device's queues support ename:VK_QUEUE_GRAPHICS_BIT or
    ename:VK_QUEUE_COMPUTE_BIT.
  * [[{anchor-prefix}limits-subgroupQuadOperationsInAllStages]]
    pname:subgroupQuadOperationsInAllStages is a boolean specifying whether
    <<shaders-quad-operations,quad group operations>> are available in all
    stages, or are restricted to fragment and compute stages.
include::{chapters}/limits.adoc[tag=VK_KHR_maintenance2-properties]
include::{chapters}/limits.adoc[tag=VK_KHR_multiview-properties]
include::{chapters}/limits.adoc[tag=VK_KHR_protected_memory-properties]
include::{chapters}/limits.adoc[tag=VK_KHR_maintenance3-properties]

:refpage: VkPhysicalDeviceVulkan11Properties
include::{chapters}/limits.adoc[tag=limits_desc]

These properties correspond to Vulkan 1.1 functionality.

The members of sname:VkPhysicalDeviceVulkan11Properties have the same values
as the corresponding members of slink:VkPhysicalDeviceIDProperties,
slink:VkPhysicalDeviceSubgroupProperties,
slink:VkPhysicalDevicePointClippingProperties,
slink:VkPhysicalDeviceMultiviewProperties,
slink:VkPhysicalDeviceProtectedMemoryProperties, and
slink:VkPhysicalDeviceMaintenance3Properties.

include::{generated}/validity/structs/VkPhysicalDeviceVulkan11Properties.adoc[]
--

[open,refpage='VkPhysicalDeviceVulkan12Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.2',type='structs']
--
The sname:VkPhysicalDeviceVulkan12Properties structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceVulkan12Properties.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.

:anchor-prefix:
include::{chapters}/devsandqueues.adoc[tag=VK_KHR_driver_properties-properties]
include::{chapters}/limits.adoc[tag=VK_KHR_shader_float_controls-properties]
include::{chapters}/limits.adoc[tag=VK_EXT_descriptor_indexing-properties]
include::{chapters}/limits.adoc[tag=VK_KHR_depth_stencil_resolve-properties]
include::{chapters}/limits.adoc[tag=VK_EXT_sampler_filter_minmax-properties]
include::{chapters}/limits.adoc[tag=VK_KHR_timeline_semaphore-properties]
  * [[limits-framebufferIntegerColorSampleCounts]]
    pname:framebufferIntegerColorSampleCounts is a bitmask of
    elink:VkSampleCountFlagBits indicating the color sample counts that are
    supported for all framebuffer color attachments with integer formats.

:refpage: VkPhysicalDeviceVulkan12Properties
include::{chapters}/limits.adoc[tag=limits_desc]

These properties correspond to Vulkan 1.2 functionality.

The members of sname:VkPhysicalDeviceVulkan12Properties must: have the same
values as the corresponding members of
slink:VkPhysicalDeviceDriverProperties,
slink:VkPhysicalDeviceFloatControlsProperties,
slink:VkPhysicalDeviceDescriptorIndexingProperties,
slink:VkPhysicalDeviceDepthStencilResolveProperties,
slink:VkPhysicalDeviceSamplerFilterMinmaxProperties, and
slink:VkPhysicalDeviceTimelineSemaphoreProperties.

include::{generated}/validity/structs/VkPhysicalDeviceVulkan12Properties.adoc[]
--
endif::VK_VERSION_1_2[]

ifdef::VKSC_VERSION_1_0[]
[open,refpage='VkPhysicalDeviceVulkanSC10Properties',desc='Structure describing safety critical properties supported by an implementation',type='structs']
--
The sname:VkPhysicalDeviceVulkanSC10Properties structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceVulkanSC10Properties.adoc[]

:anchor-prefix:
  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * [[limits-deviceNoDynamicHostAllocations]]
    pname:deviceNoDynamicHostAllocations indicates whether the
    implementation will perform dynamic host memory allocations for physical
    or logical device commands.
    If pname:deviceNoDynamicHostAllocations is ename:VK_TRUE the
    implementation will allocate host memory for objects based on the
    provided slink:VkDeviceObjectReservationCreateInfo limits during
    flink:vkCreateDevice.
    Under valid API usage, ename:VK_ERROR_OUT_OF_HOST_MEMORY may: only be
    returned by commands which do not explicitly disallow it.
  * [[limits-deviceDestroyFreesMemory]] pname:deviceDestroyFreesMemory
    indicates whether destroying the device frees all memory resources back
    to the system.
  * [[limits-commandPoolMultipleCommandBuffersRecording]]
    pname:commandPoolMultipleCommandBuffersRecording indicates whether
    multiple command buffers from the same command pool can: be in the
    <<commandbuffers-lifecycle, recording state>> at the same time.
  * [[limits-commandPoolResetCommandBuffer]]
    pname:commandPoolResetCommandBuffer indicates whether command buffers
    support flink:vkResetCommandBuffer, and flink:vkBeginCommandBuffer when
    not in the <<commandbuffers-lifecycle, initial state>>.
  * [[limits-commandBufferSimultaneousUse]]
    pname:commandBufferSimultaneousUse indicates whether command buffers
    support ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT.
  * [[limits-secondaryCommandBufferNullOrImagelessFramebuffer]]
    pname:secondaryCommandBufferNullOrImagelessFramebuffer indicates whether
    the pname:framebuffer member of sname:VkCommandBufferInheritanceInfo
    may: be equal to dlink:VK_NULL_HANDLE or be created with a
    slink:VkFramebufferCreateInfo::pname:flags value that includes
    ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT if the command buffer will be
    executed within a render pass instance.
  * [[limits-recycleDescriptorSetMemory]] pname:recycleDescriptorSetMemory
    indicates whether descriptor pools are able to immediately reuse pool
    memory from descriptor sets that have been freed.
    If this is ename:VK_FALSE, then memory may: only be reallocated after
    flink:vkResetDescriptorPool is called.
  * [[limits-recyclePipelineMemory]] pname:recyclePipelineMemory indicates
    whether the memory for a pipeline is available for reuse by new
    pipelines after the pipeline is destroyed.
  * [[limits-maxRenderPassSubpasses]] pname:maxRenderPassSubpasses is the
    maximum number of subpasses in a render pass.
  * [[limits-maxRenderPassDependencies]] pname:maxRenderPassDependencies is
    the maximum number of dependencies in a render pass.
  * [[limits-maxSubpassInputAttachments]] pname:maxSubpassInputAttachments
    is the maximum number of input attachments in a subpass.
  * [[limits-maxSubpassPreserveAttachments]]
    pname:maxSubpassPreserveAttachments is the maximum number of preserve
    attachments in a subpass.
  * [[limits-maxFramebufferAttachments]] pname:maxFramebufferAttachments is
    the maximum number of attachments in a framebuffer, as well as the
    maximum number of attachments in a render pass.
  * [[limits-maxDescriptorSetLayoutBindings]]
    pname:maxDescriptorSetLayoutBindings is the maximum number of bindings
    in a descriptor set layout.
  * [[limits-maxQueryFaultCount]] pname:maxQueryFaultCount is the maximum
    number of faults that the implementation can: record, to be reported via
    flink:vkGetFaultData.
  * [[limits-maxCallbackFaultCount]] pname:maxCallbackFaultCount is the
    maximum number of faults that the implementation can: report via a
    single call to tlink:PFN_vkFaultCallbackFunction.
  * [[limits-maxCommandPoolCommandBuffers]]
    pname:maxCommandPoolCommandBuffers is the maximum number of command
    buffers that can: be allocated from a single command pool.
  * [[limits-maxCommandBufferSize]] pname:maxCommandBufferSize is the
    maximum supported size of a single command buffer in bytes.
    Applications can: use flink:vkGetCommandPoolMemoryConsumption to compare
    a command buffer's current memory usage to this limit.

[NOTE]
.Note
====
Implementations that do not have a fixed upper bound on the number of
command buffers that may: be allocated from a command pool can: report
0xFFFFFFFFU for pname:maxCommandPoolCommandBuffers.

Implementations that do not have a fixed upper bound on the command buffer
size can: report code:UINT64_MAX for pname:maxCommandBufferSize.
====

:refpage: VkPhysicalDeviceVulkanSC10Properties
include::{chapters}/limits.adoc[tag=limits_desc]

These properties correspond to Vulkan SC 1.0 functionality.

ifdef::hidden[]
// tag::scaddition[]
  * slink:VkPhysicalDeviceVulkanSC10Properties <<SCID-1>>
// end::scaddition[]
endif::hidden[]

include::{generated}/validity/structs/VkPhysicalDeviceVulkanSC10Properties.adoc[]
--
endif::VKSC_VERSION_1_0[]

ifdef::VK_VERSION_1_3[]
[open,refpage='VkPhysicalDeviceVulkan13Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.3',type='structs']
--
The sname:VkPhysicalDeviceVulkan13Properties structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceVulkan13Properties.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.

:anchor-prefix:
include::{chapters}/limits.adoc[tag=VK_EXT_subgroup_size_control-properties]
include::{chapters}/limits.adoc[tag=VK_EXT_inline_uniform_block-properties]
  * [[{anchor-prefix}limits-maxInlineUniformTotalSize]]
    pname:maxInlineUniformTotalSize is the maximum total size in bytes of
    all inline uniform block bindings, across all pipeline shader stages and
    descriptor set numbers, that can: be included in a pipeline layout.
    Descriptor bindings with a descriptor type of
    ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK count against this limit.
include::{chapters}/devsandqueues.adoc[tag=VK_KHR_shader_integer_dot_product-properties]
include::{chapters}/limits.adoc[tag=VK_EXT_texel_buffer_alignment-properties]
include::{chapters}/limits.adoc[tag=VK_KHR_maintenance4-properties]

:refpage: VkPhysicalDeviceVulkan13Properties
include::{chapters}/limits.adoc[tag=limits_desc]

These properties correspond to Vulkan 1.3 functionality.

The members of sname:VkPhysicalDeviceVulkan13Properties must: have the same
values as the corresponding members of
slink:VkPhysicalDeviceInlineUniformBlockProperties and
slink:VkPhysicalDeviceSubgroupSizeControlProperties.

include::{generated}/validity/structs/VkPhysicalDeviceVulkan13Properties.adoc[]
--
endif::VK_VERSION_1_3[]

ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
[open,refpage='VkPhysicalDeviceIDProperties',desc='Structure specifying IDs related to the physical device',type='structs']
--
The sname:VkPhysicalDeviceIDProperties structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceIDProperties.adoc[]

ifdef::VK_KHR_external_memory_capabilities[]
or the equivalent

include::{generated}/api/structs/VkPhysicalDeviceIDPropertiesKHR.adoc[]
endif::VK_KHR_external_memory_capabilities[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.

// Must have preceding whitespace
ifdef::VK_VERSION_1_2[:anchor-prefix: extension-]
ifndef::VK_VERSION_1_2[:anchor-prefix:]
// tag::VK_KHR_external_memory_capabilities-properties[]
  * pname:deviceUUID is an array of ename:VK_UUID_SIZE code:uint8_t values
    representing a universally unique identifier for the device.
  * pname:driverUUID is an array of ename:VK_UUID_SIZE code:uint8_t values
    representing a universally unique identifier for the driver build in use
    by the device.
  * pname:deviceLUID is an array of ename:VK_LUID_SIZE code:uint8_t values
    representing a locally unique identifier for the device.
  * pname:deviceNodeMask is a code:uint32_t bitfield identifying the node
    within a linked device adapter corresponding to the device.
  * pname:deviceLUIDValid is a boolean value that will be ename:VK_TRUE if
    pname:deviceLUID contains a valid LUID and pname:deviceNodeMask contains
    a valid node mask, and ename:VK_FALSE if they do not.
// end::VK_KHR_external_memory_capabilities-properties[]

:refpage: VkPhysicalDeviceIDProperties
include::{chapters}/limits.adoc[tag=limits_desc]

pname:deviceUUID must: be immutable for a given device across instances,
processes, driver APIs, driver versions, and system reboots.

Applications can: compare the pname:driverUUID value across instance and
process boundaries, and can: make similar queries in external APIs to
determine whether they are capable of sharing memory objects and resources
using them with the device.

pname:deviceUUID and/or pname:driverUUID must: be used to determine whether
a particular external object can be shared between driver components, where
such a restriction exists as defined in the compatibility table for the
particular object type:

ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[]
  * <<external-memory-handle-types-compatibility,External memory handle
    types compatibility>>
endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[]
ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[]
  * <<external-semaphore-handle-types-compatibility,External semaphore
    handle types compatibility>>
endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[]
ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[]
  * <<external-fence-handle-types-compatibility,External fence handle types
    compatibility>>
endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[]

If pname:deviceLUIDValid is ename:VK_FALSE, the values of pname:deviceLUID
and pname:deviceNodeMask are undefined:.
If pname:deviceLUIDValid is ename:VK_TRUE and Vulkan is running on the
Windows operating system, the contents of pname:deviceLUID can: be cast to
an code:LUID object and must: be equal to the locally unique identifier of a
code:IDXGIAdapter1 object that corresponds to pname:physicalDevice.
If pname:deviceLUIDValid is ename:VK_TRUE, pname:deviceNodeMask must:
contain exactly one bit.
If Vulkan is running on an operating system that supports the Direct3D 12
API and pname:physicalDevice corresponds to an individual device in a linked
device adapter, pname:deviceNodeMask identifies the Direct3D 12 node
corresponding to pname:physicalDevice.
Otherwise, pname:deviceNodeMask must: be `1`.

[NOTE]
.Note
====
Although they have identical descriptions,
slink:VkPhysicalDeviceIDProperties::pname:deviceUUID may differ from
slink:VkPhysicalDeviceProperties2::pname:pipelineCacheUUID.
The former is intended to identify and correlate devices across API and
driver boundaries, while the latter is used to identify a compatible device
and driver combination to use when serializing and de-serializing pipeline
state.

Implementations should: return pname:deviceUUID values which are likely to
be unique even in the presence of multiple Vulkan implementations (such as a
GPU driver and a software renderer; two drivers for different GPUs; or the
same Vulkan driver running on two logically different devices).

Khronos' conformance testing is unable to guarantee that pname:deviceUUID
values are actually unique, so implementors should: make their own best
efforts to ensure this.
In particular, hard-coded pname:deviceUUID values, especially all-`0` bits,
should: never be used.

A combination of values unique to the vendor, the driver, and the hardware
environment can be used to provide a pname:deviceUUID which is unique to a
high degree of certainty.
Some possible inputs to such a computation are:

  * Information reported by flink:vkGetPhysicalDeviceProperties
  * PCI device ID (if defined)
  * PCI bus ID, or similar system configuration information.
  * Driver binary checksums.
====


[NOTE]
.Note
====
While slink:VkPhysicalDeviceIDProperties::pname:deviceUUID is specified to
remain consistent across driver versions and system reboots, it is not
intended to be usable as a serializable persistent identifier for a device.
It may change when a device is physically added to, removed from, or moved
to a different connector in a system while that system is powered down.
Further, there is no reasonable way to verify with conformance testing that
a given device retains the same UUID in a given system across all driver
versions supported in that system.
While implementations should make every effort to report consistent device
UUIDs across driver versions, applications should avoid relying on the
persistence of this value for uses other than identifying compatible devices
for external object sharing purposes.
====

include::{generated}/validity/structs/VkPhysicalDeviceIDProperties.adoc[]
--

[open,refpage='VK_UUID_SIZE',desc='Length of a universally unique device or driver build identifier',type='consts']
--
ename:VK_UUID_SIZE is the length in code:uint8_t values of an array
containing a universally unique device or driver build identifier, as
returned in slink:VkPhysicalDeviceIDProperties::pname:deviceUUID and
slink:VkPhysicalDeviceIDProperties::pname:driverUUID.

include::{generated}/api/enums/VK_UUID_SIZE.adoc[]
--

[open,refpage='VK_LUID_SIZE',desc='Length of a locally unique device identifier',type='consts',alias='VK_LUID_SIZE_KHR']
--
ename:VK_LUID_SIZE is the length in code:uint8_t values of an array
containing a locally unique device identifier, as returned in
slink:VkPhysicalDeviceIDProperties::pname:deviceLUID.

include::{generated}/api/enums/VK_LUID_SIZE.adoc[]

ifdef::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
or the equivalent

include::{generated}/api/enums/VK_LUID_SIZE_KHR.adoc[]
endif::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]
--
endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[]

ifdef::VK_VERSION_1_2,VK_KHR_driver_properties[]
[open,refpage='VkPhysicalDeviceDriverProperties',desc='Structure containing driver identification information',type='structs',alias='VkPhysicalDeviceDriverPropertiesKHR']
--
The sname:VkPhysicalDeviceDriverProperties structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceDriverProperties.adoc[]

ifdef::VK_KHR_driver_properties[]
or the equivalent

include::{generated}/api/structs/VkPhysicalDeviceDriverPropertiesKHR.adoc[]
endif::VK_KHR_driver_properties[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.

// Must have preceding whitespace
ifdef::VK_VERSION_1_2[:anchor-prefix: extension-]
ifndef::VK_VERSION_1_2[:anchor-prefix:]
// tag::VK_KHR_driver_properties-properties[]
  * pname:driverID is a unique identifier for the driver of the physical
    device.
  * pname:driverName is an array of ename:VK_MAX_DRIVER_NAME_SIZE code:char
    containing a null-terminated UTF-8 string which is the name of the
    driver.
  * pname:driverInfo is an array of ename:VK_MAX_DRIVER_INFO_SIZE code:char
    containing a null-terminated UTF-8 string with additional information
    about the driver.
  * pname:conformanceVersion is the version of the Vulkan conformance test
    this driver is conformant against (see slink:VkConformanceVersion).
// end::VK_KHR_driver_properties-properties[]

:refpage: VkPhysicalDeviceDriverProperties
include::{chapters}/limits.adoc[tag=limits_desc]

These are properties of the driver corresponding to a physical device.

pname:driverID must: be immutable for a given driver across instances,
processes, driver versions, and system reboots.

include::{generated}/validity/structs/VkPhysicalDeviceDriverProperties.adoc[]
--

[open,refpage='VkDriverId',desc='Khronos driver IDs',type='enums',alias='VkDriverIdKHR']
--
Khronos driver IDs which may: be returned in
slink:VkPhysicalDeviceDriverProperties::pname:driverID are:

include::{generated}/api/enums/VkDriverId.adoc[]

ifdef::VK_KHR_driver_properties[]
or the equivalent

include::{generated}/api/enums/VkDriverIdKHR.adoc[]
endif::VK_KHR_driver_properties[]

[NOTE]
.Note
====
Khronos driver IDs may be allocated by vendors at any time.
There may be multiple driver IDs for the same vendor, representing different
drivers (for e.g. different platforms, proprietary or open source, etc.).
Only the latest canonical versions of this Specification, of the
corresponding `vk.xml` API Registry, and of the corresponding
`{core_header}` header file must: contain all reserved Khronos driver IDs.

Only driver IDs registered with Khronos are given symbolic names.
There may: be unregistered driver IDs returned.
====
--

[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']
--
ename:VK_MAX_DRIVER_NAME_SIZE is the length in code:char values of an array
containing a driver name string, as returned in
slink:VkPhysicalDeviceDriverProperties::pname:driverName.

include::{generated}/api/enums/VK_MAX_DRIVER_NAME_SIZE.adoc[]

ifdef::VK_KHR_driver_properties[]
or the equivalent

include::{generated}/api/enums/VK_MAX_DRIVER_NAME_SIZE_KHR.adoc[]
endif::VK_KHR_driver_properties[]
--

[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']
--
ename:VK_MAX_DRIVER_INFO_SIZE is the length in code:char values of an array
containing a driver information string, as returned in
slink:VkPhysicalDeviceDriverProperties::pname:driverInfo.

include::{generated}/api/enums/VK_MAX_DRIVER_INFO_SIZE.adoc[]

ifdef::VK_KHR_driver_properties[]
or the equivalent

include::{generated}/api/enums/VK_MAX_DRIVER_INFO_SIZE_KHR.adoc[]
endif::VK_KHR_driver_properties[]
--

[open,refpage='VkConformanceVersion',desc='Structure containing the conformance test suite version the implementation is compliant with',type='structs',alias='VkConformanceVersionKHR']
--
The conformance test suite version an implementation is compliant with is
described with the sname:VkConformanceVersion structure:

include::{generated}/api/structs/VkConformanceVersion.adoc[]

ifdef::VK_KHR_driver_properties[]
or the equivalent

include::{generated}/api/structs/VkConformanceVersionKHR.adoc[]
endif::VK_KHR_driver_properties[]

  * pname:major is the major version number of the conformance test suite.
  * pname:minor is the minor version number of the conformance test suite.
  * pname:subminor is the subminor version number of the conformance test
    suite.
  * pname:patch is the patch version number of the conformance test suite.

include::{generated}/validity/structs/VkConformanceVersion.adoc[]
--
endif::VK_VERSION_1_2,VK_KHR_driver_properties[]

ifdef::VK_EXT_pci_bus_info[]
[open,refpage='VkPhysicalDevicePCIBusInfoPropertiesEXT',desc='Structure containing PCI bus information of a physical device',type='structs']
--
The sname:VkPhysicalDevicePCIBusInfoPropertiesEXT structure is defined as:

include::{generated}/api/structs/VkPhysicalDevicePCIBusInfoPropertiesEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:pciDomain is the PCI bus domain.
  * pname:pciBus is the PCI bus identifier.
  * pname:pciDevice is the PCI device identifier.
  * pname:pciFunction is the PCI device function identifier.

:refpage: VkPhysicalDevicePCIBusInfoPropertiesEXT
include::{chapters}/limits.adoc[tag=limits_desc]

These are properties of the PCI bus information of a physical device.

include::{generated}/validity/structs/VkPhysicalDevicePCIBusInfoPropertiesEXT.adoc[]
--
endif::VK_EXT_pci_bus_info[]

ifdef::VK_EXT_physical_device_drm[]
[open,refpage='VkPhysicalDeviceDrmPropertiesEXT',desc='Structure containing DRM information of a physical device',type='structs']
--
The sname:VkPhysicalDeviceDrmPropertiesEXT structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceDrmPropertiesEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:hasPrimary is a boolean indicating whether the physical device has
    a DRM primary node.
  * pname:hasRender is a boolean indicating whether the physical device has
    a DRM render node.
  * pname:primaryMajor is the DRM primary node major number, if any.
  * pname:primaryMinor is the DRM primary node minor number, if any.
  * pname:renderMajor is the DRM render node major number, if any.
  * pname:renderMinor is the DRM render node minor number, if any.

:refpage: VkPhysicalDeviceDrmPropertiesEXT
include::{chapters}/limits.adoc[tag=limits_desc]

These are properties of the DRM information of a physical device.

include::{generated}/validity/structs/VkPhysicalDeviceDrmPropertiesEXT.adoc[]
--
endif::VK_EXT_physical_device_drm[]
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]

ifdef::VK_VERSION_1_3,VK_KHR_shader_integer_dot_product[]
[open,refpage='VkPhysicalDeviceShaderIntegerDotProductProperties',desc='Structure containing information about integer dot product support for a physical device',type='structs',alias='VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR']
--
The sname:VkPhysicalDeviceShaderIntegerDotProductProperties structure is
defined as:

include::{generated}/api/structs/VkPhysicalDeviceShaderIntegerDotProductProperties.adoc[]

ifdef::VK_KHR_shader_integer_dot_product[]
or the equivalent

include::{generated}/api/structs/VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR.adoc[]
endif::VK_KHR_shader_integer_dot_product[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.

// Must have preceding whitespace
ifdef::VK_VERSION_1_3[:anchor-prefix: extension-]
ifndef::VK_VERSION_1_3[:anchor-prefix:]
// NOTE: none of these properties currently have anchors, so the
// {anchor-prefix} is not used in the property descriptions.
// tag::VK_KHR_shader_integer_dot_product-properties[]
  * pname:integerDotProduct8BitUnsignedAccelerated is a boolean that will be
    ename:VK_TRUE if the support for 8-bit unsigned dot product operations
    using the code:OpUDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct8BitSignedAccelerated is a boolean that will be
    ename:VK_TRUE if the support for 8-bit signed dot product operations
    using the code:OpSDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct8BitMixedSignednessAccelerated is a boolean that
    will be ename:VK_TRUE if the support for 8-bit mixed signedness dot
    product operations using the code:OpSUDotKHR SPIR-V instruction is
    accelerated <<devsandqueues-integer-dot-product-accelerated,as defined
    below>>.
  * pname:integerDotProduct4x8BitPackedUnsignedAccelerated is a boolean that
    will be ename:VK_TRUE if the support for 8-bit unsigned dot product
    operations from operands packed into 32-bit integers using the
    code:OpUDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct4x8BitPackedSignedAccelerated is a boolean that
    will be ename:VK_TRUE if the support for 8-bit signed dot product
    operations from operands packed into 32-bit integers using the
    code:OpSDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct4x8BitPackedMixedSignednessAccelerated is a
    boolean that will be ename:VK_TRUE if the support for 8-bit mixed
    signedness dot product operations from operands packed into 32-bit
    integers using the code:OpSUDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct16BitUnsignedAccelerated is a boolean that will
    be ename:VK_TRUE if the support for 16-bit unsigned dot product
    operations using the code:OpUDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct16BitSignedAccelerated is a boolean that will be
    ename:VK_TRUE if the support for 16-bit signed dot product operations
    using the code:OpSDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct16BitMixedSignednessAccelerated is a boolean that
    will be ename:VK_TRUE if the support for 16-bit mixed signedness dot
    product operations using the code:OpSUDotKHR SPIR-V instruction is
    accelerated <<devsandqueues-integer-dot-product-accelerated,as defined
    below>>.
  * pname:integerDotProduct32BitUnsignedAccelerated is a boolean that will
    be ename:VK_TRUE if the support for 32-bit unsigned dot product
    operations using the code:OpUDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct32BitSignedAccelerated is a boolean that will be
    ename:VK_TRUE if the support for 32-bit signed dot product operations
    using the code:OpSDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct32BitMixedSignednessAccelerated is a boolean that
    will be ename:VK_TRUE if the support for 32-bit mixed signedness dot
    product operations using the code:OpSUDotKHR SPIR-V instruction is
    accelerated <<devsandqueues-integer-dot-product-accelerated,as defined
    below>>.
  * pname:integerDotProduct64BitUnsignedAccelerated is a boolean that will
    be ename:VK_TRUE if the support for 64-bit unsigned dot product
    operations using the code:OpUDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct64BitSignedAccelerated is a boolean that will be
    ename:VK_TRUE if the support for 64-bit signed dot product operations
    using the code:OpSDotKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProduct64BitMixedSignednessAccelerated is a boolean that
    will be ename:VK_TRUE if the support for 64-bit mixed signedness dot
    product operations using the code:OpSUDotKHR SPIR-V instruction is
    accelerated <<devsandqueues-integer-dot-product-accelerated,as defined
    below>>.
  * pname:integerDotProductAccumulatingSaturating8BitUnsignedAccelerated is
    a boolean that will be ename:VK_TRUE if the support for 8-bit unsigned
    accumulating saturating dot product operations using the
    code:OpUDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating8BitSignedAccelerated is a
    boolean that will be ename:VK_TRUE if the support for 8-bit signed
    accumulating saturating dot product operations using the
    code:OpSDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated
    is a boolean that will be ename:VK_TRUE if the support for 8-bit mixed
    signedness accumulating saturating dot product operations using the
    code:OpSUDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated
    is a boolean that will be ename:VK_TRUE if the support for 8-bit
    unsigned accumulating saturating dot product operations from operands
    packed into 32-bit integers using the code:OpUDotAccSatKHR SPIR-V
    instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated
    is a boolean that will be ename:VK_TRUE if the support for 8-bit signed
    accumulating saturating dot product operations from operands packed into
    32-bit integers using the code:OpSDotAccSatKHR SPIR-V instruction is
    accelerated <<devsandqueues-integer-dot-product-accelerated,as defined
    below>>.
  * pname:integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated
    is a boolean that will be ename:VK_TRUE if the support for 8-bit mixed
    signedness accumulating saturating dot product operations from operands
    packed into 32-bit integers using the code:OpSUDotAccSatKHR SPIR-V
    instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating16BitUnsignedAccelerated is
    a boolean that will be ename:VK_TRUE if the support for 16-bit unsigned
    accumulating saturating dot product operations using the
    code:OpUDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating16BitSignedAccelerated is a
    boolean that will be ename:VK_TRUE if the support for 16-bit signed
    accumulating saturating dot product operations using the
    code:OpSDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated
    is a boolean that will be ename:VK_TRUE if the support for 16-bit mixed
    signedness accumulating saturating dot product operations using the
    code:OpSUDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating32BitUnsignedAccelerated is
    a boolean that will be ename:VK_TRUE if the support for 32-bit unsigned
    accumulating saturating dot product operations using the
    code:OpUDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating32BitSignedAccelerated is a
    boolean that will be ename:VK_TRUE if the support for 32-bit signed
    accumulating saturating dot product operations using the
    code:OpSDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated
    is a boolean that will be ename:VK_TRUE if the support for 32-bit mixed
    signedness accumulating saturating dot product operations using the
    code:OpSUDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating64BitUnsignedAccelerated is
    a boolean that will be ename:VK_TRUE if the support for 64-bit unsigned
    accumulating saturating dot product operations using the
    code:OpUDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating64BitSignedAccelerated is a
    boolean that will be ename:VK_TRUE if the support for 64-bit signed
    accumulating saturating dot product operations using the
    code:OpSDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
  * pname:integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated
    is a boolean that will be ename:VK_TRUE if the support for 64-bit mixed
    signedness accumulating saturating dot product operations using the
    code:OpSUDotAccSatKHR SPIR-V instruction is accelerated
    <<devsandqueues-integer-dot-product-accelerated,as defined below>>.
// end::VK_KHR_shader_integer_dot_product-properties[]

:refpage: VkPhysicalDeviceShaderIntegerDotProductProperties
include::{chapters}/limits.adoc[tag=limits_desc]

These are properties of the integer dot product acceleration information of
a physical device.

[[devsandqueues-integer-dot-product-accelerated]]
[NOTE]
.Note
====
A dot product operation is deemed accelerated if its implementation provides
a performance advantage over application-provided code composed from
elementary instructions and/or other dot product instructions, either
because the implementation uses optimized machine code sequences whose
generation from application-provided code cannot be guaranteed or because it
uses hardware features that cannot otherwise be targeted from
application-provided code.
====

include::{generated}/validity/structs/VkPhysicalDeviceShaderIntegerDotProductProperties.adoc[]
--
endif::VK_VERSION_1_3,VK_KHR_shader_integer_dot_product[]

ifdef::VK_QCOM_image_processing[]
[open,refpage='VkPhysicalDeviceImageProcessingPropertiesQCOM',desc='Structure containing image processing properties',type='structs']
--
The sname:VkPhysicalDeviceImageProcessingPropertiesQCOM structure is defined
as:

include::{generated}/api/structs/VkPhysicalDeviceImageProcessingPropertiesQCOM.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * [[limits-weightfilter-phases]] pname:maxWeightFilterPhases is the
    maximum value that can: be specified for
    slink:VkImageViewSampleWeightCreateInfoQCOM::pname:numPhases in
    <<textures-weightimage-filterphases, weight image sampling>> operations.
  * [[limits-weightfilter-maxdimension]] pname:maxWeightFilterDimension is a
    slink:VkExtent2D describing the largest dimensions (pname:width and
    pname:height) that can: be specified for
    slink:VkImageViewSampleWeightCreateInfoQCOM::pname:filterSize.
  * [[limits-blockmatch-maxblocksize]] pname:maxBlockMatchRegion is a
    slink:VkExtent2D describing the largest dimensions (pname:width and
    pname:height) that can: be specified for code:blockSize in
    <<textures-blockmatch,block matching>> operations.
  * [[limits-boxfilter-maxblocksize]] pname:maxBoxFilterBlockSize is a
    slink:VkExtent2D describing the maximum dimensions (pname:width and
    pname:height) that can: be specified for code:blocksize in
    <<textures-boxfilter,box filter sampling>> operations.

:refpage: VkPhysicalDeviceImageProcessingPropertiesQCOM
include::{chapters}/limits.adoc[tag=limits_desc]

These are properties of the image processing information of a physical
device.

include::{generated}/validity/structs/VkPhysicalDeviceImageProcessingPropertiesQCOM.adoc[]
--
endif::VK_QCOM_image_processing[]

ifdef::VK_EXT_shader_tile_image[]
[open,refpage='VkPhysicalDeviceShaderTileImagePropertiesEXT',desc='Structure containing information about tile image support for a physical device',type='structs']
--
The sname:VkPhysicalDeviceShaderTileImagePropertiesEXT structure is defined
as:

include::{generated}/api/structs/VkPhysicalDeviceShaderTileImagePropertiesEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:shaderTileImageCoherentReadAccelerated is a boolean that will be
    ename:VK_TRUE if coherent reads of tile image data is accelerated.
  * pname:shaderTileImageReadSampleFromPixelRateInvocation is a boolean that
    will be ename:VK_TRUE if reading from samples from a pixel rate fragment
    invocation is supported when
    slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples > 1.
  * pname:shaderTileImageReadFromHelperInvocation is a boolean that will be
    ename:VK_TRUE if reads of tile image data from helper fragment
    invocations result in valid values.

:refpage: VkPhysicalDeviceShaderTileImagePropertiesEXT
include::{chapters}/limits.adoc[tag=limits_desc]

These are properties of the tile image information of a physical device.

include::{generated}/validity/structs/VkPhysicalDeviceShaderTileImagePropertiesEXT.adoc[]
--
endif::VK_EXT_shader_tile_image[]

ifdef::VK_QCOM_image_processing2[]
[open,refpage='VkPhysicalDeviceImageProcessing2PropertiesQCOM',desc='Structure containing image processing2 properties',type='structs']
--
The sname:VkPhysicalDeviceImageProcessing2PropertiesQCOM structure is
defined as:

include::{generated}/api/structs/VkPhysicalDeviceImageProcessing2PropertiesQCOM.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.

  * [[limits-blockmatch-maxWindowExtent]] pname:maxBlockMatchWindow is a
    slink:VkExtent2D describing the largest dimensions (pname:width and
    pname:height) that can: be specified for the block match window.

:refpage: VkPhysicalDeviceImageProcessing2PropertiesQCOM
include::{chapters}/limits.adoc[tag=limits_desc]

These are properties of the image processing2 information of a physical
device.

include::{generated}/validity/structs/VkPhysicalDeviceImageProcessing2PropertiesQCOM.adoc[]
--
endif::VK_QCOM_image_processing2[]

ifdef::VK_MSFT_layered_driver[]
[open,refpage='VkPhysicalDeviceLayeredDriverPropertiesMSFT',desc='Structure containing information about driver layering for a physical device',type='structs']
--
The sname:VkPhysicalDeviceLayeredDriverPropertiesMSFT structure is defined
as:

include::{generated}/api/structs/VkPhysicalDeviceLayeredDriverPropertiesMSFT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:underlyingAPI is a elink:VkLayeredDriverUnderlyingApiMSFT value
    indicating which underlying API is used to implement the layered driver,
    or ename:VK_LAYERED_DRIVER_UNDERLYING_API_NONE_MSFT if the driver is not
    layered.

These are properties of the driver layering information of a physical
device.

include::{generated}/validity/structs/VkPhysicalDeviceLayeredDriverPropertiesMSFT.adoc[]
--

[open,refpage='VkLayeredDriverUnderlyingApiMSFT',desc='Layered driver underlying APIs',type='enums']
--
Underlying APIs which may: be returned in
slink:VkPhysicalDeviceLayeredDriverPropertiesMSFT::pname:underlyingAPI are:

include::{generated}/api/enums/VkLayeredDriverUnderlyingApiMSFT.adoc[]
--
endif::VK_MSFT_layered_driver[]

ifdef::VK_ARM_scheduling_controls[]
[open,refpage='VkPhysicalDeviceSchedulingControlsPropertiesARM',desc='Structure containing scheduling control properties of a physical device',type='structs']
--
The sname:VkPhysicalDeviceSchedulingControlsPropertiesARM structure is
defined as:

include::{generated}/api/structs/VkPhysicalDeviceSchedulingControlsPropertiesARM.adoc[]

  * [[limits-schedulingControlsFlags]]pname:schedulingControlsFlags
    specifies the specific scheduling controls that a physical device
    supports.

:refpage: VkPhysicalDeviceSchedulingControlsPropertiesARM
include::{chapters}/limits.adoc[tag=limits_desc]

include::{generated}/validity/structs/VkPhysicalDeviceSchedulingControlsPropertiesARM.adoc[]
--

[open,refpage='VkPhysicalDeviceSchedulingControlsFlagBitsARM',desc='Bitmask specifying scheduling controls supported by a physical device',type='enums']
--
Bits which can: be set in
slink:VkPhysicalDeviceSchedulingControlsPropertiesARM::pname:schedulingControlsFlags,
specifying supported scheduling controls, are:

include::{generated}/api/enums/VkPhysicalDeviceSchedulingControlsFlagBitsARM.adoc[]

  * ename:VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM
    indicates that a slink:VkDeviceQueueShaderCoreControlCreateInfoARM
    structure may: be included in the pname:pNext chain of a
    slink:VkDeviceQueueCreateInfo or slink:VkDeviceCreateInfo structure.
--

[open,refpage='VkPhysicalDeviceSchedulingControlsFlagsARM',desc='Bitmask of VkPhysicalDeviceSchedulingControlsFlagBitsARM',type='flags']
--
include::{generated}/api/flags/VkPhysicalDeviceSchedulingControlsFlagsARM.adoc[]

tname:VkPhysicalDeviceSchedulingControlsFlagsARM is a bitmask type for
setting a mask of zero or more
elink:VkPhysicalDeviceSchedulingControlsFlagBitsARM.
--
endif::VK_ARM_scheduling_controls[]

[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties',desc='Reports properties of the queues of the specified physical device',type='protos']
--
To query properties of queues available on a physical device, call:

include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties.adoc[]

  * pname:physicalDevice is the handle to the physical device whose
    properties will be queried.
  * pname:pQueueFamilyPropertyCount is a pointer to an integer related to
    the number of queue families available or queried, as described below.
  * pname:pQueueFamilyProperties is either `NULL` or a pointer to an array
    of slink:VkQueueFamilyProperties structures.

If pname:pQueueFamilyProperties is `NULL`, then the number of queue families
available is returned in pname:pQueueFamilyPropertyCount.
Implementations must: support at least one queue family.
Otherwise, pname:pQueueFamilyPropertyCount must: point to a variable set by
the user to the number of elements in the pname:pQueueFamilyProperties
array, and on return the variable is overwritten with the number of
structures actually written to pname:pQueueFamilyProperties.
If pname:pQueueFamilyPropertyCount is less than the number of queue families
available, at most pname:pQueueFamilyPropertyCount structures will be
written.

include::{generated}/validity/protos/vkGetPhysicalDeviceQueueFamilyProperties.adoc[]
--

[open,refpage='VkQueueFamilyProperties',desc='Structure providing information about a queue family',type='structs']
--
The sname:VkQueueFamilyProperties structure is defined as:

include::{generated}/api/structs/VkQueueFamilyProperties.adoc[]

  * pname:queueFlags is a bitmask of elink:VkQueueFlagBits indicating
    capabilities of the queues in this queue family.
  * pname:queueCount is the unsigned integer count of queues in this queue
    family.
    Each queue family must: support at least one queue.
  * pname:timestampValidBits is the unsigned integer count of meaningful
    bits in the timestamps written via
ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[]
    flink:vkCmdWriteTimestamp2 or
endif::VK_VERSION_1_3,VK_KHR_synchronization2[]
    flink:vkCmdWriteTimestamp.
    The valid range for the count is 36 to 64 bits, or a value of 0,
    indicating no support for timestamps.
    Bits outside the valid range are guaranteed to be zeros.
  * pname:minImageTransferGranularity is the minimum granularity supported
    for image transfer operations on the queues in this queue family.

The value returned in pname:minImageTransferGranularity has a unit of
compressed texel blocks for images having a block-compressed format, and a
unit of texels otherwise.

Possible values of pname:minImageTransferGranularity are:

  * [eq]#(0,0,0)# specifies that only whole mip levels must: be transferred
    using the image transfer operations on the corresponding queues.
    In this case, the following restrictions apply to all offset and extent
    parameters of image transfer operations:
  ** The pname:x, pname:y, and pname:z members of a slink:VkOffset3D
     parameter must: always be zero.
  ** The pname:width, pname:height, and pname:depth members of a
     slink:VkExtent3D parameter must: always match the width, height, and
     depth of the image subresource corresponding to the parameter,
     respectively.
  * [eq]#(A~x~, A~y~, A~z~)# where [eq]#A~x~#, [eq]#A~y~#, and [eq]#A~z~#
    are all integer powers of two.
    In this case the following restrictions apply to all image transfer
    operations:
  ** pname:x, pname:y, and pname:z of a slink:VkOffset3D parameter must: be
     integer multiples of [eq]#A~x~#, [eq]#A~y~#, and [eq]#A~z~#,
     respectively.
  ** pname:width of a slink:VkExtent3D parameter must: be an integer
     multiple of [eq]#A~x~#, or else [eq]#pname:x {plus} pname:width# must:
     equal the width of the image subresource corresponding to the
     parameter.
  ** pname:height of a slink:VkExtent3D parameter must: be an integer
     multiple of [eq]#A~y~#, or else [eq]#pname:y {plus} pname:height# must:
     equal the height of the image subresource corresponding to the
     parameter.
  ** pname:depth of a slink:VkExtent3D parameter must: be an integer
     multiple of [eq]#A~z~#, or else [eq]#pname:z {plus} pname:depth# must:
     equal the depth of the image subresource corresponding to the
     parameter.
  ** If the format of the image corresponding to the parameters is one of
     the block-compressed formats then for the purposes of the above
     calculations the granularity must: be scaled up by the compressed texel
     block dimensions.

Queues supporting graphics and/or compute operations must: report
[eq]#(1,1,1)# in pname:minImageTransferGranularity, meaning that there are
no additional restrictions on the granularity of image transfer operations
for these queues.
Other queues supporting image transfer operations are only required: to
support whole mip level transfers, thus pname:minImageTransferGranularity
for queues belonging to such queue families may: be [eq]#(0,0,0)#.

The <<memory-device,Device Memory>> section describes memory properties
queried from the physical device.

For physical device feature queries see the <<features, Features>> chapter.

include::{generated}/validity/structs/VkQueueFamilyProperties.adoc[]
--

[open,refpage='VkQueueFlagBits',desc='Bitmask specifying capabilities of queues in a queue family',type='enums']
--
Bits which may: be set in slink:VkQueueFamilyProperties::pname:queueFlags,
indicating capabilities of queues in a queue family are:

include::{generated}/api/enums/VkQueueFlagBits.adoc[]

  * ename:VK_QUEUE_GRAPHICS_BIT specifies that queues in this queue family
    support graphics operations.
  * ename:VK_QUEUE_COMPUTE_BIT specifies that queues in this queue family
    support compute operations.
  * ename:VK_QUEUE_TRANSFER_BIT specifies that queues in this queue family
    support transfer operations.
  * ename:VK_QUEUE_SPARSE_BINDING_BIT specifies that queues in this queue
    family support sparse memory management operations (see
    <<sparsememory,Sparse Resources>>).
    If any of the sparse resource features are enabled, then at least one
    queue family must: support this bit.
ifdef::VKSC_VERSION_1_0[]
    This flag is not supported in Vulkan SC <<SCID-8>>.
ifdef::hidden[]
// tag::scremoved[]
  * elink:VkQueueFlagBits
  ** ename:VK_QUEUE_SPARSE_BINDING_BIT <<SCID-8>>
// end::scremoved[]
endif::hidden[]
endif::VKSC_VERSION_1_0[]
ifdef::VK_KHR_video_decode_queue[]
  * ename:VK_QUEUE_VIDEO_DECODE_BIT_KHR specifies that queues in this queue
    family support <<video-decode-operations,video decode operations>>.
endif::VK_KHR_video_decode_queue[]
ifdef::VK_KHR_video_encode_queue[]
  * ename:VK_QUEUE_VIDEO_ENCODE_BIT_KHR specifies that queues in this queue
    family support <<video-encode-operations,video encode operations>>.
endif::VK_KHR_video_encode_queue[]
ifdef::VK_NV_optical_flow[]
  * ename:VK_QUEUE_OPTICAL_FLOW_BIT_NV specifies that queues in this queue
    family support optical flow operations.
endif::VK_NV_optical_flow[]
ifdef::VK_VERSION_1_1[]
  * ename:VK_QUEUE_PROTECTED_BIT specifies that queues in this queue family
    support the ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit.
    (see <<memory-protected-memory,Protected Memory>>).
    If the physical device supports the <<features-protectedMemory,
    pname:protectedMemory>> feature, at least one of its queue families
    must: support this bit.
endif::VK_VERSION_1_1[]

If an implementation exposes any queue family that supports graphics
operations, at least one queue family of at least one physical device
exposed by the implementation must: support both graphics and compute
operations.

ifdef::VK_VERSION_1_1[]
Furthermore, if the <<features-protectedMemory, pname:protectedMemory>>
physical device feature is supported, then at least one queue family of at
least one physical device exposed by the implementation must: support
graphics operations, compute operations, and protected memory operations.
endif::VK_VERSION_1_1[]

[NOTE]
.Note
====
All commands that are allowed on a queue that supports transfer operations
are also allowed on a queue that supports either graphics or compute
operations.
Thus, if the capabilities of a queue family include
ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT, then reporting
the ename:VK_QUEUE_TRANSFER_BIT capability separately for that queue family
is optional:.
====

For further details see <<devsandqueues-queues,Queues>>.
--

[open,refpage='VkQueueFlags',desc='Bitmask of VkQueueFlagBits',type='flags']
--
include::{generated}/api/flags/VkQueueFlags.adoc[]

tname:VkQueueFlags is a bitmask type for setting a mask of zero or more
elink:VkQueueFlagBits.
--

ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
[open,refpage='vkGetPhysicalDeviceQueueFamilyProperties2',desc='Reports properties of the queues of the specified physical device',type='protos']
--
To query properties of queues available on a physical device, call:

ifdef::VK_VERSION_1_1[]
include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties2.adoc[]
endif::VK_VERSION_1_1[]

ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command]

ifdef::VK_KHR_get_physical_device_properties2[]
include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.adoc[]
endif::VK_KHR_get_physical_device_properties2[]

  * pname:physicalDevice is the handle to the physical device whose
    properties will be queried.
  * pname:pQueueFamilyPropertyCount is a pointer to an integer related to
    the number of queue families available or queried, as described in
    flink:vkGetPhysicalDeviceQueueFamilyProperties.
  * pname:pQueueFamilyProperties is either `NULL` or a pointer to an array
    of slink:VkQueueFamilyProperties2 structures.

fname:vkGetPhysicalDeviceQueueFamilyProperties2 behaves similarly to
flink:vkGetPhysicalDeviceQueueFamilyProperties, with the ability to return
extended information in a pname:pNext chain of output structures.

include::{generated}/validity/protos/vkGetPhysicalDeviceQueueFamilyProperties2.adoc[]
--

[open,refpage='VkQueueFamilyProperties2',desc='Structure providing information about a queue family',type='structs']
--
The sname:VkQueueFamilyProperties2 structure is defined as:

include::{generated}/api/structs/VkQueueFamilyProperties2.adoc[]

ifdef::VK_KHR_get_physical_device_properties2[]
or the equivalent

include::{generated}/api/structs/VkQueueFamilyProperties2KHR.adoc[]
endif::VK_KHR_get_physical_device_properties2[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:queueFamilyProperties is a slink:VkQueueFamilyProperties structure
    which is populated with the same values as in
    flink:vkGetPhysicalDeviceQueueFamilyProperties.

include::{generated}/validity/structs/VkQueueFamilyProperties2.adoc[]
--

ifdef::VK_EXT_global_priority_query,VK_KHR_global_priority[]
[open,refpage='VkQueueFamilyGlobalPriorityPropertiesKHR',desc='Return structure for queue family global priority information query',type='structs']
--
The definition of slink:VkQueueFamilyGlobalPriorityPropertiesKHR is:

include::{generated}/api/structs/VkQueueFamilyGlobalPriorityPropertiesKHR.adoc[]
ifdef::VK_EXT_global_priority_query[]
or the equivalent

include::{generated}/api/structs/VkQueueFamilyGlobalPriorityPropertiesEXT.adoc[]
endif::VK_EXT_global_priority_query[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:priorityCount is the number of supported global queue priorities
    in this queue family, and it must: be greater than 0.
  * pname:priorities is an array of ename:VK_MAX_GLOBAL_PRIORITY_SIZE_EXT
    elink:VkQueueGlobalPriorityEXT enums representing all supported global
    queue priorities in this queue family.
    The first pname:priorityCount elements of the array will be valid.

If the sname:VkQueueFamilyGlobalPriorityPropertiesKHR structure is included
in the pname:pNext chain of the slink:VkQueueFamilyProperties2 structure
passed to flink:vkGetPhysicalDeviceQueueFamilyProperties2, it is filled in
with the list of supported global queue priorities for the indicated family.

The valid elements of pname:priorities must: not contain any duplicate
values.

The valid elements of pname:priorities must: be a continuous sequence of
elink:VkQueueGlobalPriorityKHR enums in the ascending order.

[NOTE]
.Note
====
For example, returning pname:priorityCount as 3 with supported
pname:priorities as ename:VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR,
ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR and
ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR is not allowed.
====

include::{generated}/validity/structs/VkQueueFamilyGlobalPriorityPropertiesKHR.adoc[]
--

[open,refpage='VK_MAX_GLOBAL_PRIORITY_SIZE_KHR',desc='Length of an array of global queue priorities',type='consts']
--
ename:VK_MAX_GLOBAL_PRIORITY_SIZE_KHR is the length of an array of
elink:VkQueueGlobalPriorityKHR enumerants representing supported queue
priorities, as returned in
slink:VkQueueFamilyGlobalPriorityPropertiesKHR::pname:priorities.

include::{generated}/api/enums/VK_MAX_GLOBAL_PRIORITY_SIZE_KHR.adoc[]

ifdef::VK_EXT_global_priority_query[]
or the equivalent

include::{generated}/api/enums/VK_MAX_GLOBAL_PRIORITY_SIZE_EXT.adoc[]
endif::VK_EXT_global_priority_query[]
--
endif::VK_EXT_global_priority_query,VK_KHR_global_priority[]

ifdef::VK_NV_device_diagnostic_checkpoints[]
include::{chapters}/VK_NV_device_diagnostic_checkpoints/queue_checkpoint_properties.adoc[]
endif::VK_NV_device_diagnostic_checkpoints[]

endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]

ifdef::VK_KHR_video_queue[]
[open,refpage='VkQueueFamilyVideoPropertiesKHR',desc='Structure describing video codec operations supported by a queue family',type='structs']
--
The slink:VkQueueFamilyVideoPropertiesKHR structure is defined as:

include::{generated}/api/structs/VkQueueFamilyVideoPropertiesKHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:videoCodecOperations is a bitmask of
    elink:VkVideoCodecOperationFlagBitsKHR that indicates the set of video
    codec operations supported by the queue family.

If this structure is included in the pname:pNext chain of the
slink:VkQueueFamilyProperties2 structure passed to
flink:vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with the
set of video codec operations supported by the specified queue family.

include::{generated}/validity/structs/VkQueueFamilyVideoPropertiesKHR.adoc[]
--

[open,refpage='VkQueueFamilyQueryResultStatusPropertiesKHR',desc='Structure specifying support for result status query',type='structs']
--
The slink:VkQueueFamilyQueryResultStatusPropertiesKHR structure is defined
as:

include::{generated}/api/structs/VkQueueFamilyQueryResultStatusPropertiesKHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:queryResultStatusSupport reports ename:VK_TRUE if query type
    ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR and use of
    ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR are supported.

If this structure is included in the pname:pNext chain of the
slink:VkQueueFamilyProperties2 structure passed to
flink:vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with
information about whether <<queries-result-status-only,result status
queries>> are supported by the specified queue family.

include::{generated}/validity/structs/VkQueueFamilyQueryResultStatusPropertiesKHR.adoc[]
--
endif::VK_KHR_video_queue[]

ifdef::VK_KHR_performance_query[]
include::{chapters}/VK_KHR_performance_query/queuefamily.adoc[]
endif::VK_KHR_performance_query[]


[[devsandqueues-devices]]
== Devices

Device objects represent logical connections to physical devices.
Each device exposes a number of _queue families_ each having one or more
_queues_.
All queues in a queue family support the same operations.

As described in <<devsandqueues-physical-device-enumeration,Physical
Devices>>, a Vulkan application will first query for all physical devices in
a system.
Each physical device can: then be queried for its capabilities, including
its queue and queue family properties.
Once an acceptable physical device is identified, an application will create
a corresponding logical device.
The created logical device is then the primary interface to the physical
device.

How to enumerate the physical devices in a system and query those physical
devices for their queue family properties is described in the
<<devsandqueues-physical-device-enumeration, Physical Device Enumeration>>
section above.

ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[]

A single logical device can: be created from multiple physical devices, if
those physical devices belong to the same device group.
A _device group_ is a set of physical devices that support accessing each
other's memory and recording a single command buffer that can: be executed
on all the physical devices.
Device groups are enumerated by calling
flink:vkEnumeratePhysicalDeviceGroups, and a logical device is created from
a subset of the physical devices in a device group by passing the physical
devices through slink:VkDeviceGroupDeviceCreateInfo.
For two physical devices to be in the same device group, they must: support
identical extensions, features, and properties.

[NOTE]
.Note
====
Physical devices in the same device group must: be so similar because there
are no rules for how different features/properties would interact.
They must: return the same values for nearly every invariant
ftext:vkGetPhysicalDevice* feature, property, capability, etc., but could
potentially differ for certain queries based on things like having a
different display connected, or a different compositor.
The specification does not attempt to enumerate which state is in each
category, because such a list would quickly become out of date.
====

[open,refpage='vkEnumeratePhysicalDeviceGroups',desc='Enumerates groups of physical devices that can be used to create a single logical device',type='protos']
--
To retrieve a list of the device groups present in the system, call:

ifdef::VK_VERSION_1_1[]
include::{generated}/api/protos/vkEnumeratePhysicalDeviceGroups.adoc[]
endif::VK_VERSION_1_1[]

ifdef::VK_VERSION_1_1+VK_KHR_device_group_creation[or the equivalent command]

ifdef::VK_KHR_device_group_creation[]
include::{generated}/api/protos/vkEnumeratePhysicalDeviceGroupsKHR.adoc[]
endif::VK_KHR_device_group_creation[]

  * pname:instance is a handle to a Vulkan instance previously created with
    flink:vkCreateInstance.
  * pname:pPhysicalDeviceGroupCount is a pointer to an integer related to
    the number of device groups available or queried, as described below.
  * pname:pPhysicalDeviceGroupProperties is either `NULL` or a pointer to an
    array of slink:VkPhysicalDeviceGroupProperties structures.

If pname:pPhysicalDeviceGroupProperties is `NULL`, then the number of device
groups available is returned in pname:pPhysicalDeviceGroupCount.
Otherwise, pname:pPhysicalDeviceGroupCount must: point to a variable set by
the user to the number of elements in the
pname:pPhysicalDeviceGroupProperties array, and on return the variable is
overwritten with the number of structures actually written to
pname:pPhysicalDeviceGroupProperties.
If pname:pPhysicalDeviceGroupCount is less than the number of device groups
available, at most pname:pPhysicalDeviceGroupCount structures will be
written, and ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS, to indicate that not all the available device groups were
returned.

Every physical device must: be in exactly one device group.

include::{generated}/validity/protos/vkEnumeratePhysicalDeviceGroups.adoc[]
--

[open,refpage='VkPhysicalDeviceGroupProperties',desc='Structure specifying physical device group properties',type='structs']
--
The sname:VkPhysicalDeviceGroupProperties structure is defined as:

include::{generated}/api/structs/VkPhysicalDeviceGroupProperties.adoc[]

ifdef::VK_KHR_device_group_creation[]
or the equivalent

include::{generated}/api/structs/VkPhysicalDeviceGroupPropertiesKHR.adoc[]
endif::VK_KHR_device_group_creation[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:physicalDeviceCount is the number of physical devices in the
    group.
  * pname:physicalDevices is an array of ename:VK_MAX_DEVICE_GROUP_SIZE
    slink:VkPhysicalDevice handles representing all physical devices in the
    group.
    The first pname:physicalDeviceCount elements of the array will be valid.
  * pname:subsetAllocation specifies whether logical devices created from
    the group support allocating device memory on a subset of devices, via
    the pname:deviceMask member of the slink:VkMemoryAllocateFlagsInfo.
    If this is ename:VK_FALSE, then all device memory allocations are made
    across all physical devices in the group.
    If pname:physicalDeviceCount is `1`, then pname:subsetAllocation must:
    be ename:VK_FALSE.

include::{generated}/validity/structs/VkPhysicalDeviceGroupProperties.adoc[]
--

[open,refpage='VK_MAX_DEVICE_GROUP_SIZE',desc='Length of a physical device handle array',type='consts',alias='VK_MAX_DEVICE_GROUP_SIZE_KHR']
--
ename:VK_MAX_DEVICE_GROUP_SIZE is the length of an array containing
slink:VkPhysicalDevice handle values representing all physical devices in a
group, as returned in
slink:VkPhysicalDeviceGroupProperties::pname:physicalDevices.

include::{generated}/api/enums/VK_MAX_DEVICE_GROUP_SIZE.adoc[]

ifdef::VK_KHR_device_group_creation[]
or the equivalent

include::{generated}/api/enums/VK_MAX_DEVICE_GROUP_SIZE_KHR.adoc[]
endif::VK_KHR_device_group_creation[]
--
endif::VK_VERSION_1_1,VK_KHR_device_group_creation[]


[[devsandqueues-device-creation]]
=== Device Creation

[open,refpage='VkDevice',desc='Opaque handle to a device object',type='handles']
--
Logical devices are represented by sname:VkDevice handles:

include::{generated}/api/handles/VkDevice.adoc[]
--

[open,refpage='vkCreateDevice',desc='Create a new device instance',type='protos']
--
A logical device is created as a _connection_ to a physical device.
To create a logical device, call:

include::{generated}/api/protos/vkCreateDevice.adoc[]

  * pname:physicalDevice must: be one of the device handles returned from a
    call to fname:vkEnumeratePhysicalDevices (see
    <<devsandqueues-physical-device-enumeration, Physical Device
    Enumeration>>).
  * pname:pCreateInfo is a pointer to a slink:VkDeviceCreateInfo structure
    containing information about how to create the device.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pDevice is a pointer to a handle in which the created
    slink:VkDevice is returned.

fname:vkCreateDevice verifies that extensions and features requested in the
pname:ppEnabledExtensionNames and pname:pEnabledFeatures members of
pname:pCreateInfo, respectively, are supported by the implementation.
If any requested extension is not supported, fname:vkCreateDevice must:
return ename:VK_ERROR_EXTENSION_NOT_PRESENT.
If any requested feature is not supported, fname:vkCreateDevice must: return
ename:VK_ERROR_FEATURE_NOT_PRESENT.
Support for extensions can: be checked before creating a device by querying
flink:vkEnumerateDeviceExtensionProperties.
Support for features can: similarly be checked by querying
flink:vkGetPhysicalDeviceFeatures.

ifdef::VKSC_VERSION_1_0[]
fname:vkCreateDevice also verifies that mandatory structures and features
for Vulkan SC are present and enabled:

  * The pname:pNext chain must: include a
    slink:VkDeviceObjectReservationCreateInfo structure.
  * The pname:pNext chain must: include a
    slink:VkPhysicalDeviceVulkanSC10Features structure.
ifdef::hidden[]
// tag::scdeviation[]
  * The slink:VkDeviceCreateInfo::pname:pNext chain must: include a
    slink:VkDeviceObjectReservationCreateInfo structure <<SCID-4>>.
  * The slink:VkDeviceCreateInfo::pname:pNext chain must: include a
    slink:VkPhysicalDeviceVulkanSC10Features structure <<SCID-1>>.
// end::scdeviation[]
endif::hidden[]

If any of these conditions are not met, fname:vkCreateDevice must: return
ename:VK_ERROR_INITIALIZATION_FAILED.
endif::VKSC_VERSION_1_0[]

After verifying and enabling the extensions the sname:VkDevice object is
created and returned to the application.

ifndef::VKSC_VERSION_1_0[]
Multiple logical devices can: be created from the same physical device.
Logical device creation may: fail due to lack of device-specific resources
(in addition to other errors).
endif::VKSC_VERSION_1_0[]
ifdef::VKSC_VERSION_1_0[]
An implementation may: allow multiple logical devices to be created from the
same physical device.
Logical device creation may: fail due to lack of device-specific resources,
including too many other logical devices, in addition to other errors.
endif::VKSC_VERSION_1_0[]
If that occurs, fname:vkCreateDevice will return
ename:VK_ERROR_TOO_MANY_OBJECTS.

ifdef::VKSC_VERSION_1_0[]
If the pipeline cache data pointed to by the pname:pInitialData member of
any element of
slink:VkDeviceObjectReservationCreateInfo::pname:pPipelineCacheCreateInfos
is not compatible with the device, then fname:vkCreateDevice will return
ename:VK_ERROR_INVALID_PIPELINE_CACHE_DATA.
ifdef::hidden[]
// tag::scdeviation[]
  * flink:vkCreateDevice returns ename:VK_ERROR_INVALID_PIPELINE_CACHE_DATA
    if the pname:pInitialData member of any element of
    slink:VkDeviceObjectReservationCreateInfo::pname:pPipelineCacheCreateInfos
    is a pointer to incompatible pipeline cache data <<SCID-1>>.
// end::scdeviation[]
endif::hidden[]
endif::VKSC_VERSION_1_0[]

ifdef::VK_EXT_application_parameters[]
To provide _application parameters_ at device creation time, an application
can: link one or more slink:VkApplicationParametersEXT structures to the
pname:pNext chain of the sname:VkDeviceCreateInfo structure.

If the slink:VkApplicationParametersEXT::pname:vendorID and
slink:VkApplicationParametersEXT::pname:deviceID values do not match the
slink:VkPhysicalDeviceProperties::pname:vendorID and
slink:VkPhysicalDeviceProperties::pname:deviceID of pname:physicalDevice,
flink:vkCreateDevice must: return ename:VK_ERROR_INITIALIZATION_FAILED.

If slink:VkApplicationParametersEXT::pname:key is not a valid
implementation-defined application parameter key for the device being
created, or if pname:value is not a valid value for the specified pname:key,
flink:vkCreateDevice will fail and return
ename:VK_ERROR_INITIALIZATION_FAILED.

For any implementation-defined application parameter pname:key that exists
but is not set by the application, the implementation-specific default value
is used.
endif::VK_EXT_application_parameters[]

.Valid Usage
****
  * [[VUID-vkCreateDevice-ppEnabledExtensionNames-01387]]
    All <<extendingvulkan-extensions-extensiondependencies, required device
    extensions>> for each extension in the
    slink:VkDeviceCreateInfo::pname:ppEnabledExtensionNames list must: also
    be present in that list
ifdef::VK_EXT_application_parameters[]
  * [[VUID-vkCreateDevice-key-05092]]
    The pname:key value of each slink:VkApplicationParametersEXT structure
    in the slink:VkDeviceCreateInfo::pname:pNext chain must: be unique
endif::VK_EXT_application_parameters[]
ifdef::VKSC_VERSION_1_0[]
  * [[VUID-vkCreateDevice-deviceMemoryRequestCount-05095]]
    The sum of pname:deviceMemoryRequestCount over all
    sname:VkDeviceObjectReservationCreateInfo structures included in the
    slink:VkDeviceCreateInfo::pname:pNext chain must: be less than or equal
    to slink:VkPhysicalDeviceLimits::pname:maxMemoryAllocationCount
  * [[VUID-vkCreateDevice-samplerRequestCount-05096]]
    The sum of pname:samplerRequestCount over all
    sname:VkDeviceObjectReservationCreateInfo structures included in the
    slink:VkDeviceCreateInfo::pname:pNext chain must: be less than or equal
    to slink:VkPhysicalDeviceLimits::pname:maxSamplerAllocationCount
endif::VKSC_VERSION_1_0[]
****

include::{generated}/validity/protos/vkCreateDevice.adoc[]
--

[open,refpage='VkDeviceCreateInfo',desc='Structure specifying parameters of a newly created device',type='structs']
--
The sname:VkDeviceCreateInfo structure is defined as:

include::{generated}/api/structs/VkDeviceCreateInfo.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is reserved for future use.
  * pname:queueCreateInfoCount is the unsigned integer size of the
    pname:pQueueCreateInfos array.
    Refer to the <<devsandqueues-queue-creation,Queue Creation>> section
    below for further details.
  * pname:pQueueCreateInfos is a pointer to an array of
    slink:VkDeviceQueueCreateInfo structures describing the queues that are
    requested to be created along with the logical device.
    Refer to the <<devsandqueues-queue-creation,Queue Creation>> section
    below for further details.
  * pname:enabledLayerCount is deprecated and ignored.
  * pname:ppEnabledLayerNames is deprecated and ignored.
    See <<extendingvulkan-layers-devicelayerdeprecation>>.
  * pname:enabledExtensionCount is the number of device extensions to
    enable.
  * pname:ppEnabledExtensionNames is a pointer to an array of
    pname:enabledExtensionCount null-terminated UTF-8 strings containing the
    names of extensions to enable for the created device.
    See the <<extendingvulkan-extensions>> section for further details.
  * pname:pEnabledFeatures is `NULL` or a pointer to a
    slink:VkPhysicalDeviceFeatures structure containing boolean indicators
    of all the features to be enabled.
    Refer to the <<features, Features>> section for further details.

.Valid Usage
****
  * [[VUID-VkDeviceCreateInfo-queueFamilyIndex-02802]]
    The pname:queueFamilyIndex member of each element of
    pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos
ifdef::VK_VERSION_1_1[]
    , except that two members can share the same pname:queueFamilyIndex if
    one describes protected-capable queues and one describes queues that are
    not protected-capable
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1[]
  * [[VUID-VkDeviceCreateInfo-pQueueCreateInfos-06755]]
    If multiple elements of pname:pQueueCreateInfos share the same
    pname:queueFamilyIndex, the sum of their pname:queueCount members must:
    be less than or equal to the pname:queueCount member of the
    sname:VkQueueFamilyProperties structure, as returned by
    fname:vkGetPhysicalDeviceQueueFamilyProperties in the
    pname:pQueueFamilyProperties[queueFamilyIndex]
ifdef::VK_KHR_global_priority,VK_EXT_global_priority[]
  * [[VUID-VkDeviceCreateInfo-pQueueCreateInfos-06654]]
    If multiple elements of pname:pQueueCreateInfos share the same
    pname:queueFamilyIndex, then all of such elements must: have the same
    global priority level, which can: be specified explicitly by the
    including a slink:VkDeviceQueueGlobalPriorityCreateInfoKHR structure in
    the pname:pNext chain, or by the implicit default value
endif::VK_KHR_global_priority,VK_EXT_global_priority[]
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
  * [[VUID-VkDeviceCreateInfo-pNext-00373]]
    If the pname:pNext chain includes a slink:VkPhysicalDeviceFeatures2
    structure, then pname:pEnabledFeatures must: be `NULL`
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
ifdef::VK_AMD_negative_viewport_height[]
ifdef::VK_VERSION_1_1[]
  * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-01840]]
    If slink:VkPhysicalDeviceProperties::pname:apiVersion advertises Vulkan
    1.1 or later, pname:ppEnabledExtensionNames must: not contain
    `apiext:VK_AMD_negative_viewport_height`
endif::VK_VERSION_1_1[]
ifdef::VK_KHR_maintenance1[]
  * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-00374]]
    pname:ppEnabledExtensionNames must: not contain both
    `apiext:VK_KHR_maintenance1` and
    `apiext:VK_AMD_negative_viewport_height`
endif::VK_KHR_maintenance1[]
endif::VK_AMD_negative_viewport_height[]
ifdef::VK_EXT_buffer_device_address+VK_KHR_buffer_device_address[]
  * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-03328]]
    pname:ppEnabledExtensionNames must: not contain both
    `apiext:VK_KHR_buffer_device_address` and
    `apiext:VK_EXT_buffer_device_address`
endif::VK_EXT_buffer_device_address+VK_KHR_buffer_device_address[]
ifdef::VK_VERSION_1_2[]
ifdef::VK_EXT_buffer_device_address[]
  * [[VUID-VkDeviceCreateInfo-pNext-04748]]
    If the pname:pNext chain includes a
    slink:VkPhysicalDeviceVulkan12Features structure and
    slink:VkPhysicalDeviceVulkan12Features::pname:bufferDeviceAddress is
    ename:VK_TRUE, pname:ppEnabledExtensionNames must: not contain
    `apiext:VK_EXT_buffer_device_address`
endif::VK_EXT_buffer_device_address[]
  * [[VUID-VkDeviceCreateInfo-pNext-02829]]
    If the pname:pNext chain includes a
    slink:VkPhysicalDeviceVulkan11Features structure, then it must: not
    include a slink:VkPhysicalDevice16BitStorageFeatures,
    slink:VkPhysicalDeviceMultiviewFeatures,
    slink:VkPhysicalDeviceVariablePointersFeatures,
    slink:VkPhysicalDeviceProtectedMemoryFeatures,
    slink:VkPhysicalDeviceSamplerYcbcrConversionFeatures, or
    slink:VkPhysicalDeviceShaderDrawParametersFeatures structure
  * [[VUID-VkDeviceCreateInfo-pNext-02830]]
    If the pname:pNext chain includes a
    slink:VkPhysicalDeviceVulkan12Features structure, then it must: not
    include a slink:VkPhysicalDevice8BitStorageFeatures,
    slink:VkPhysicalDeviceShaderAtomicInt64Features,
    slink:VkPhysicalDeviceShaderFloat16Int8Features,
    slink:VkPhysicalDeviceDescriptorIndexingFeatures,
    slink:VkPhysicalDeviceScalarBlockLayoutFeatures,
    slink:VkPhysicalDeviceImagelessFramebufferFeatures,
    slink:VkPhysicalDeviceUniformBufferStandardLayoutFeatures,
    slink:VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures,
    slink:VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures,
    slink:VkPhysicalDeviceHostQueryResetFeatures,
    slink:VkPhysicalDeviceTimelineSemaphoreFeatures,
    slink:VkPhysicalDeviceBufferDeviceAddressFeatures, or
    slink:VkPhysicalDeviceVulkanMemoryModelFeatures structure
ifdef::VK_KHR_shader_draw_parameters[]
  * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-04476]]
    If pname:ppEnabledExtensionNames contains
    `"VK_KHR_shader_draw_parameters"` and the pname:pNext chain includes a
    slink:VkPhysicalDeviceVulkan11Features structure, then
    sname:VkPhysicalDeviceVulkan11Features::pname:shaderDrawParameters must:
    be ename:VK_TRUE
endif::VK_KHR_shader_draw_parameters[]
ifdef::VK_KHR_draw_indirect_count[]
  * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02831]]
    If pname:ppEnabledExtensionNames contains `"VK_KHR_draw_indirect_count"`
    and the pname:pNext chain includes a
    slink:VkPhysicalDeviceVulkan12Features structure, then
    sname:VkPhysicalDeviceVulkan12Features::pname:drawIndirectCount must: be
    ename:VK_TRUE
endif::VK_KHR_draw_indirect_count[]
ifdef::VK_KHR_sampler_mirror_clamp_to_edge[]
  * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02832]]
    If pname:ppEnabledExtensionNames contains
    `"VK_KHR_sampler_mirror_clamp_to_edge"` and the pname:pNext chain
    includes a slink:VkPhysicalDeviceVulkan12Features structure, then
    sname:VkPhysicalDeviceVulkan12Features::pname:samplerMirrorClampToEdge
    must: be ename:VK_TRUE
endif::VK_KHR_sampler_mirror_clamp_to_edge[]
ifdef::VK_EXT_descriptor_indexing[]
  * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02833]]
    If pname:ppEnabledExtensionNames contains `"VK_EXT_descriptor_indexing"`
    and the pname:pNext chain includes a
    slink:VkPhysicalDeviceVulkan12Features structure, then
    sname:VkPhysicalDeviceVulkan12Features::pname:descriptorIndexing must:
    be ename:VK_TRUE
endif::VK_EXT_descriptor_indexing[]
ifdef::VK_EXT_sampler_filter_minmax[]
  * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02834]]
    If pname:ppEnabledExtensionNames contains
    `"VK_EXT_sampler_filter_minmax"` and the pname:pNext chain includes a
    slink:VkPhysicalDeviceVulkan12Features structure, then
    sname:VkPhysicalDeviceVulkan12Features::pname:samplerFilterMinmax must:
    be ename:VK_TRUE
endif::VK_EXT_sampler_filter_minmax[]
ifdef::VK_EXT_shader_viewport_index_layer[]
  * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02835]]
    If pname:ppEnabledExtensionNames contains
    `"VK_EXT_shader_viewport_index_layer"` and the pname:pNext chain
    includes a slink:VkPhysicalDeviceVulkan12Features structure, then
    sname:VkPhysicalDeviceVulkan12Features::pname:shaderOutputViewportIndex
    and sname:VkPhysicalDeviceVulkan12Features::pname:shaderOutputLayer
    must: both be ename:VK_TRUE
endif::VK_EXT_shader_viewport_index_layer[]
endif::VK_VERSION_1_2[]
ifdef::VK_VERSION_1_3[]
  * [[VUID-VkDeviceCreateInfo-pNext-06532]]
    If the pname:pNext chain includes a
    slink:VkPhysicalDeviceVulkan13Features structure, then it must: not
    include a slink:VkPhysicalDeviceDynamicRenderingFeatures,
    slink:VkPhysicalDeviceImageRobustnessFeatures,
    slink:VkPhysicalDeviceInlineUniformBlockFeatures,
    slink:VkPhysicalDeviceMaintenance4Features,
    slink:VkPhysicalDevicePipelineCreationCacheControlFeatures,
    slink:VkPhysicalDevicePrivateDataFeatures,
    slink:VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures,
    slink:VkPhysicalDeviceShaderIntegerDotProductFeatures,
    slink:VkPhysicalDeviceShaderTerminateInvocationFeatures,
    slink:VkPhysicalDeviceSubgroupSizeControlFeatures,
    slink:VkPhysicalDeviceSynchronization2Features,
    slink:VkPhysicalDeviceTextureCompressionASTCHDRFeatures, or
    slink:VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures structure
// Jon 1.3 TBD - add extension-specific VUs specifying when Vulkan13Features
// members must: be true.
endif::VK_VERSION_1_3[]
ifdef::VK_KHR_portability_subset[]
  * [[VUID-VkDeviceCreateInfo-pProperties-04451]]
    If the `apiext:VK_KHR_portability_subset` extension is included in
    pname:pProperties of flink:vkEnumerateDeviceExtensionProperties,
    pname:ppEnabledExtensionNames must: include
    `"VK_KHR_portability_subset"`
endif::VK_KHR_portability_subset[]
ifdef::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[]
  * [[VUID-VkDeviceCreateInfo-shadingRateImage-04478]]
    If the <<features-shadingRateImage, pname:shadingRateImage>> feature is
    enabled, the <<features-pipelineFragmentShadingRate,
    pname:pipelineFragmentShadingRate>> feature must: not be enabled
  * [[VUID-VkDeviceCreateInfo-shadingRateImage-04479]]
    If the <<features-shadingRateImage, pname:shadingRateImage>> feature is
    enabled, the <<features-primitiveFragmentShadingRate,
    pname:primitiveFragmentShadingRate>> feature must: not be enabled
  * [[VUID-VkDeviceCreateInfo-shadingRateImage-04480]]
    If the <<features-shadingRateImage, pname:shadingRateImage>> feature is
    enabled, the <<features-attachmentFragmentShadingRate,
    pname:attachmentFragmentShadingRate>> feature must: not be enabled
endif::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[]
ifdef::VK_KHR_fragment_shading_rate+VK_EXT_fragment_density_map[]
  * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04481]]
    If the <<features-fragmentDensityMap, pname:fragmentDensityMap>> feature
    is enabled, the <<features-pipelineFragmentShadingRate,
    pname:pipelineFragmentShadingRate>> feature must: not be enabled
  * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04482]]
    If the <<features-fragmentDensityMap, pname:fragmentDensityMap>> feature
    is enabled, the <<features-primitiveFragmentShadingRate,
    pname:primitiveFragmentShadingRate>> feature must: not be enabled
  * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04483]]
    If the <<features-fragmentDensityMap, pname:fragmentDensityMap>> feature
    is enabled, the <<features-attachmentFragmentShadingRate,
    pname:attachmentFragmentShadingRate>> feature must: not be enabled
endif::VK_KHR_fragment_shading_rate+VK_EXT_fragment_density_map[]
ifdef::VK_EXT_shader_image_atomic_int64[]
  * [[VUID-VkDeviceCreateInfo-None-04896]]
    If <<features-sparseImageInt64Atomics, pname:sparseImageInt64Atomics>>
    is enabled, <<features-shaderImageInt64Atomics,
    pname:shaderImageInt64Atomics>> must: be enabled
endif::VK_EXT_shader_image_atomic_int64[]
ifdef::VK_EXT_shader_atomic_float[]
  * [[VUID-VkDeviceCreateInfo-None-04897]]
    If <<features-sparseImageFloat32Atomics,
    pname:sparseImageFloat32Atomics>> is enabled,
    <<features-shaderImageFloat32Atomics, pname:shaderImageFloat32Atomics>>
    must: be enabled
  * [[VUID-VkDeviceCreateInfo-None-04898]]
    If <<features-sparseImageFloat32AtomicAdd,
    pname:sparseImageFloat32AtomicAdd>> is enabled,
    <<features-shaderImageFloat32AtomicAdd,
    pname:shaderImageFloat32AtomicAdd>> must: be enabled
endif::VK_EXT_shader_atomic_float[]
ifdef::VK_EXT_shader_atomic_float2[]
  * [[VUID-VkDeviceCreateInfo-sparseImageFloat32AtomicMinMax-04975]]
    If <<features-sparseImageFloat32AtomicMinMax,
    pname:sparseImageFloat32AtomicMinMax>> is enabled,
    <<features-shaderImageFloat32AtomicMinMax,
    pname:shaderImageFloat32AtomicMinMax>> must: be enabled
endif::VK_EXT_shader_atomic_float2[]
ifdef::VK_EXT_descriptor_buffer[]
ifdef::VK_AMD_shader_fragment_mask[]
  * [[VUID-VkDeviceCreateInfo-None-08095]]
    If <<features-descriptorBuffer, pname:descriptorBuffer>> is enabled,
    pname:ppEnabledExtensionNames must: not contain
    `apiext:VK_AMD_shader_fragment_mask`
endif::VK_AMD_shader_fragment_mask[]
endif::VK_EXT_descriptor_buffer[]
ifdef::VK_ARM_scheduling_controls[]
  * [[VUID-VkDeviceCreateInfo-pNext-09396]]
    If the pname:pNext chain includes a
    slink:VkDeviceQueueShaderCoreControlCreateInfoARM structure, then it
    must: not be included in the pname:pNext chain of any of the
    slink:VkDeviceQueueCreateInfo structures in pname:pQueueCreateInfos.
  * [[VUID-VkDeviceCreateInfo-pNext-09397]]
    If the pname:pNext chain includes a
    slink:VkDeviceQueueShaderCoreControlCreateInfoARM structure then
    slink:VkPhysicalDeviceSchedulingControlsPropertiesARM::pname:schedulingControlsFlags
    must: contain
    ename:VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM.
endif::VK_ARM_scheduling_controls[]
****

include::{generated}/validity/structs/VkDeviceCreateInfo.adoc[]
--

[open,refpage='VkDeviceCreateFlags',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkDeviceCreateFlags.adoc[]

tname:VkDeviceCreateFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
--

ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[]
[open,refpage='VkDeviceGroupDeviceCreateInfo',desc='Create a logical device from multiple physical devices',type='structs']
--
A logical device can: be created that connects to one or more physical
devices by adding a sname:VkDeviceGroupDeviceCreateInfo structure to the
pname:pNext chain of slink:VkDeviceCreateInfo.
The sname:VkDeviceGroupDeviceCreateInfo structure is defined as:

include::{generated}/api/structs/VkDeviceGroupDeviceCreateInfo.adoc[]

ifdef::VK_KHR_device_group_creation[]
or the equivalent

include::{generated}/api/structs/VkDeviceGroupDeviceCreateInfoKHR.adoc[]
endif::VK_KHR_device_group_creation[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:physicalDeviceCount is the number of elements in the
    pname:pPhysicalDevices array.
  * pname:pPhysicalDevices is a pointer to an array of physical device
    handles belonging to the same device group.

The elements of the pname:pPhysicalDevices array are an ordered list of the
physical devices that the logical device represents.
These must: be a subset of a single device group, and need not be in the
same order as they were enumerated.
The order of the physical devices in the pname:pPhysicalDevices array
determines the _device index_ of each physical device, with element [eq]#i#
being assigned a device index of [eq]#i#.
Certain commands and structures refer to one or more physical devices by
using device indices or _device masks_ formed using device indices.

A logical device created without using sname:VkDeviceGroupDeviceCreateInfo,
or with pname:physicalDeviceCount equal to zero, is equivalent to a
pname:physicalDeviceCount of one and pname:pPhysicalDevices pointing to the
pname:physicalDevice parameter to flink:vkCreateDevice.
In particular, the device index of that physical device is zero.

.Valid Usage
****
  * [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00375]]
    Each element of pname:pPhysicalDevices must: be unique
  * [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00376]]
    All elements of pname:pPhysicalDevices must: be in the same device group
    as enumerated by flink:vkEnumeratePhysicalDeviceGroups
  * [[VUID-VkDeviceGroupDeviceCreateInfo-physicalDeviceCount-00377]]
    If pname:physicalDeviceCount is not `0`, the pname:physicalDevice
    parameter of flink:vkCreateDevice must: be an element of
    pname:pPhysicalDevices
****

include::{generated}/validity/structs/VkDeviceGroupDeviceCreateInfo.adoc[]
--
endif::VK_VERSION_1_1,VK_KHR_device_group_creation[]

ifdef::VK_AMD_memory_overallocation_behavior[]
[open,refpage='VkDeviceMemoryOverallocationCreateInfoAMD',desc='Specify memory overallocation behavior for a Vulkan device',type='structs']
--
To specify whether device memory allocation is allowed beyond the size
reported by slink:VkPhysicalDeviceMemoryProperties, add a
slink:VkDeviceMemoryOverallocationCreateInfoAMD structure to the pname:pNext
chain of the slink:VkDeviceCreateInfo structure.
If this structure is not specified, it is as if the
ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD value is used.

include::{generated}/api/structs/VkDeviceMemoryOverallocationCreateInfoAMD.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:overallocationBehavior is the desired overallocation behavior.

include::{generated}/validity/structs/VkDeviceMemoryOverallocationCreateInfoAMD.adoc[]
--

[open,refpage='VkMemoryOverallocationBehaviorAMD',desc='Specify memory overallocation behavior',type='enums']
--
Possible values for
slink:VkDeviceMemoryOverallocationCreateInfoAMD::pname:overallocationBehavior
include:

include::{generated}/api/enums/VkMemoryOverallocationBehaviorAMD.adoc[]

  * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD lets the
    implementation decide if overallocation is allowed.
  * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_ALLOWED_AMD specifies
    overallocation is allowed if platform permits.
  * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DISALLOWED_AMD specifies the
    application is not allowed to allocate device memory beyond the heap
    sizes reported by slink:VkPhysicalDeviceMemoryProperties.
    Allocations that are not explicitly made by the application within the
    scope of the Vulkan instance are not accounted for.
--
endif::VK_AMD_memory_overallocation_behavior[]

ifdef::VK_NV_device_diagnostics_config[]
[open,refpage='VkDeviceDiagnosticsConfigCreateInfoNV',desc='Specify diagnostics config for a Vulkan device',type='structs']
--
When using the Nsight^(TM)^ Aftermath SDK, to configure how device crash
dumps are created, add a slink:VkDeviceDiagnosticsConfigCreateInfoNV
structure to the pname:pNext chain of the slink:VkDeviceCreateInfo
structure.

include::{generated}/api/structs/VkDeviceDiagnosticsConfigCreateInfoNV.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is a bitmask of elink:VkDeviceDiagnosticsConfigFlagBitsNV
    specifying additional parameters for configuring diagnostic tools.

include::{generated}/validity/structs/VkDeviceDiagnosticsConfigCreateInfoNV.adoc[]
--

[open,refpage='VkDeviceDiagnosticsConfigFlagBitsNV',desc='Bitmask specifying diagnostics flags',type='enums']
--
Bits which can: be set in
slink:VkDeviceDiagnosticsConfigCreateInfoNV::pname:flags include:

include::{generated}/api/enums/VkDeviceDiagnosticsConfigFlagBitsNV.adoc[]

  * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_DEBUG_INFO_BIT_NV
    enables the generation of debug information for shaders.
  * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_RESOURCE_TRACKING_BIT_NV
    enables driver side tracking of resources (images, buffers, etc.) used
    to augment the device fault information.
  * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_AUTOMATIC_CHECKPOINTS_BIT_NV
    enables automatic insertion of <<device-diagnostic-checkpoints,
    diagnostic checkpoints>> for draw calls, dispatches,
ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
    trace rays,
endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[]
    and copies.
    The CPU call stack at the time of the command will be associated as the
    marker data for the automatically inserted checkpoints.
  * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_ERROR_REPORTING_BIT_NV
    enables shader error reporting.
--

[open,refpage='VkDeviceDiagnosticsConfigFlagsNV',desc='Bitmask of VkDeviceDiagnosticsConfigFlagBitsNV',type='flags']
--
include::{generated}/api/flags/VkDeviceDiagnosticsConfigFlagsNV.adoc[]

tname:VkDeviceDiagnosticsConfigFlagsNV is a bitmask type for setting a mask
of zero or more elink:VkDeviceDiagnosticsConfigFlagBitsNV.
--
endif::VK_NV_device_diagnostics_config[]

ifdef::VK_EXT_device_memory_report[]
[open,refpage='VkDeviceDeviceMemoryReportCreateInfoEXT',desc='Register device memory report callbacks for a Vulkan device',type='structs']
--
To register callbacks for underlying device memory events of type
elink:VkDeviceMemoryReportEventTypeEXT, add one or multiple
slink:VkDeviceDeviceMemoryReportCreateInfoEXT structures to the pname:pNext
chain of the slink:VkDeviceCreateInfo structure.

include::{generated}/api/structs/VkDeviceDeviceMemoryReportCreateInfoEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is 0 and reserved for future use.
  * pname:pfnUserCallback is the application callback function to call.
  * pname:pUserData is user data to be passed to the callback.

The callback may: be called from multiple threads simultaneously.

The callback must: be called only once by the implementation when a
elink:VkDeviceMemoryReportEventTypeEXT event occurs.

[NOTE]
.Note
====
The callback could be called from a background thread other than the thread
calling the Vulkan commands.
====

include::{generated}/validity/structs/VkDeviceDeviceMemoryReportCreateInfoEXT.adoc[]
--

[open,refpage='PFN_vkDeviceMemoryReportCallbackEXT',desc='Application-defined device memory report callback function',type='funcpointers']
--
The prototype for the
slink:VkDeviceDeviceMemoryReportCreateInfoEXT::pname:pfnUserCallback
function implemented by the application is:

include::{generated}/api/funcpointers/PFN_vkDeviceMemoryReportCallbackEXT.adoc[]

  * pname:pCallbackData contains all the callback related data in the
    slink:VkDeviceMemoryReportCallbackDataEXT structure.
  * pname:pUserData is the user data provided when the
    slink:VkDeviceDeviceMemoryReportCreateInfoEXT was created.

The callback must: not make calls to any Vulkan commands.
--

[open,refpage='VkDeviceMemoryReportCallbackDataEXT',desc='Structure specifying parameters returned to the callback',type='structs']
--
The definition of sname:VkDeviceMemoryReportCallbackDataEXT is:

include::{generated}/api/structs/VkDeviceMemoryReportCallbackDataEXT.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is 0 and reserved for future use.
  * pname:type is a elink:VkDeviceMemoryReportEventTypeEXT type specifying
    the type of event reported in this
    sname:VkDeviceMemoryReportCallbackDataEXT structure.
  * pname:memoryObjectId is the unique id for the underlying memory object
    as described below.
  * pname:size is the size of the memory object in bytes.
    If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT,
    ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT or
    ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT,
    pname:size is a valid basetype:VkDeviceSize value.
    Otherwise, pname:size is undefined:.
  * pname:objectType is a elink:VkObjectType value specifying the type of
    the object associated with this device memory report event.
    If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT,
    ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT,
    ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT,
    ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT or
    ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT,
    pname:objectType is a valid elink:VkObjectType enum.
    Otherwise, pname:objectType is undefined:.
  * pname:objectHandle is the object this device memory report event is
    attributed to.
    If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT,
    ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT,
    ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT or
    ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT,
    pname:objectHandle is a valid Vulkan handle of the type associated with
    pname:objectType as defined in the <<debugging-object-types,
    `VkObjectType` and Vulkan Handle Relationship>> table.
    Otherwise, pname:objectHandle is undefined:.
  * pname:heapIndex describes which memory heap this device memory
    allocation is made from.
    If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT
    or ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT,
    pname:heapIndex corresponds to one of the valid heaps from the
    slink:VkPhysicalDeviceMemoryProperties structure.
    Otherwise, pname:heapIndex is undefined:.

pname:memoryObjectId is used to avoid double-counting on the same memory
object.

If an internally-allocated device memory object or a slink:VkDeviceMemory
cannot: be exported, pname:memoryObjectId must: be unique in the
slink:VkDevice.

If an internally-allocated device memory object or a slink:VkDeviceMemory
supports being exported, pname:memoryObjectId must: be unique system wide.

If an internal device memory object or a slink:VkDeviceMemory is backed by
an imported external memory object, pname:memoryObjectId must: be unique
system wide.

ifdef::implementation-guide[]
.Implementor's Note
****
If the heap backing an internally-allocated device memory cannot: be used to
back slink:VkDeviceMemory, implementations can: advertise that heap with no
types.
****
endif::implementation-guide[]

[NOTE]
.Note
====
This structure should only be considered valid during the lifetime of the
triggered callback.

For ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT and
ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT events,
pname:objectHandle usually will not yet exist when the application or tool
receives the callback.
pname:objectHandle will only exist when the create or allocate call that
triggered the event returns, and if the allocation or import ends up failing
pname:objectHandle will not ever exist.
====

include::{generated}/validity/structs/VkDeviceMemoryReportCallbackDataEXT.adoc[]
--

[open,refpage='VkDeviceMemoryReportFlagsEXT',desc='Reserved for future use',type='flags']
--
include::{generated}/api/flags/VkDeviceMemoryReportFlagsEXT.adoc[]

tname:VkDeviceMemoryReportFlagsEXT is a bitmask type for setting a mask, but
is currently reserved for future use.
--

[open,refpage='VkDeviceMemoryReportEventTypeEXT',desc='Events that can occur on a device memory object',type='enums']
--
Possible values of slink:VkDeviceMemoryReportCallbackDataEXT::pname:type,
specifying event types which cause the device driver to call the callback,
are:

include::{generated}/api/enums/VkDeviceMemoryReportEventTypeEXT.adoc[]

  * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT specifies this
    event corresponds to the allocation of an internal device memory object
    or a slink:VkDeviceMemory.
  * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT specifies this event
    corresponds to the deallocation of an internally-allocated device memory
    object or a slink:VkDeviceMemory.
  * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT specifies this event
    corresponds to the import of an external memory object.
  * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT specifies this
    event is the release of an imported external memory object.
  * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT specifies
    this event corresponds to the failed allocation of an internal device
    memory object or a slink:VkDeviceMemory.
--
endif::VK_EXT_device_memory_report[]

ifdef::VK_VERSION_1_3,VK_EXT_private_data[]
[open,refpage='VkDevicePrivateDataCreateInfo',desc='Reserve private data slots',type='structs',alias='VkDevicePrivateDataCreateInfoEXT']
--
To reserve private data storage slots, add a
slink:VkDevicePrivateDataCreateInfo structure to the pname:pNext chain of
the slink:VkDeviceCreateInfo structure.
Reserving slots in this manner is not strictly necessary, but doing so may:
improve performance.

include::{generated}/api/structs/VkDevicePrivateDataCreateInfo.adoc[]

ifdef::VK_EXT_private_data[]
or the equivalent

include::{generated}/api/structs/VkDevicePrivateDataCreateInfoEXT.adoc[]
endif::VK_EXT_private_data[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:privateDataSlotRequestCount is the amount of slots to reserve.

include::{generated}/validity/structs/VkDevicePrivateDataCreateInfo.adoc[]
--
endif::VK_VERSION_1_3,VK_EXT_private_data[]

ifdef::VKSC_VERSION_1_0[]

[open,refpage='VkDeviceObjectReservationCreateInfo',desc='Request memory reservation',type='structs']
--
Data structures for objects are reserved by the implementation at device
creation time.
The application must: provide upper bounds on numbers of objects and other
limits at device creation time.
To reserve data structures for use by objects created from this device, add
a slink:VkDeviceObjectReservationCreateInfo structure to the pname:pNext
chain of the slink:VkDeviceCreateInfo structure.

include::{generated}/api/structs/VkDeviceObjectReservationCreateInfo.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:pipelineCacheCreateInfoCount is the length of the
    pname:pPipelineCacheCreateInfos array.
  * pname:pPipelineCacheCreateInfos is a pointer to an array of
    slink:VkPipelineCacheCreateInfo structures that contain the creation
    information of the pipeline caches that can: be created on this device.
  * pname:pipelinePoolSizeCount is the length of the
    pname:pPipelinePoolSizes array.
  * pname:pPipelinePoolSizes is a pointer to an array of
    slink:VkPipelinePoolSize structures requesting memory be reserved for
    pipelines of the specified sizes.
  * pname:semaphoreRequestCount is the requested maximum number of
    sname:VkSemaphore objects that can: exist at the same time.
  * pname:commandBufferRequestCount is the requested maximum number of
    sname:VkCommandBuffer objects that can: be reserved by all
    sname:VkCommandPool objects.
  * pname:fenceRequestCount is the requested maximum number of sname:VkFence
    objects that can: exist at the same time.
  * pname:deviceMemoryRequestCount is the requested maximum number of
    sname:VkDeviceMemory objects that can: exist at the same time.
  * pname:bufferRequestCount is the requested maximum number of
    sname:VkBuffer objects that can: exist at the same time.
  * pname:imageRequestCount is the requested maximum number of sname:VkImage
    objects that can: exist at the same time.
  * pname:eventRequestCount is the requested maximum number of sname:VkEvent
    objects that can: exist at the same time.
  * pname:queryPoolRequestCount is the requested maximum number of
    sname:VkQueryPool objects that can: exist at the same time.
  * pname:bufferViewRequestCount is the requested maximum number of
    sname:VkBufferView objects that can: exist at the same time.
  * pname:imageViewRequestCount is the requested maximum number of
    sname:VkImageView objects that can: exist at the same time.
  * pname:layeredImageViewRequestCount is the requested maximum number
    sname:VkImageView objects created with
    slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount greater
    than `1` that can: exist at the same time.
  * pname:pipelineCacheRequestCount is the requested maximum number of
    sname:VkPipelineCache objects that can: exist at the same time.
  * pname:pipelineLayoutRequestCount is the requested maximum number of
    sname:VkPipelineLayout objects that can: exist at the same time.
  * pname:renderPassRequestCount is the requested maximum number of
    sname:VkRenderPass objects that can: exist at the same time.
  * pname:graphicsPipelineRequestCount is the requested maximum number of
    graphics sname:VkPipeline objects that can: exist at the same time.
  * pname:computePipelineRequestCount is the requested maximum number of
    compute sname:VkPipeline objects that can: exist at the same time.
  * pname:descriptorSetLayoutRequestCount is the requested maximum number of
    sname:VkDescriptorSetLayout objects that can: exist at the same time.
  * pname:samplerRequestCount is the requested maximum number of
    sname:VkSampler objects that can: exist at the same time.
  * pname:descriptorPoolRequestCount is the requested maximum number of
    sname:VkDescriptorPool objects that can: exist at the same time.
  * pname:descriptorSetRequestCount is the requested maximum number of
    sname:VkDescriptorSet objects that can: exist at the same time.
  * pname:framebufferRequestCount is the requested maximum number of
    sname:VkFramebuffer objects that can: exist at the same time.
  * pname:commandPoolRequestCount is the requested maximum number of
    sname:VkCommandPool objects that can: exist at the same time.
  * pname:samplerYcbcrConversionRequestCount is the requested maximum number
    of sname:VkSamplerYcbcrConversion objects that can: exist at the same
    time.
  * pname:surfaceRequestCount is deprecated and implementations must: ignore
    it.
  * pname:swapchainRequestCount is the requested maximum number of
    sname:VkSwapchainKHR objects that can: exist at the same time.
  * pname:displayModeRequestCount is deprecated and implementations must:
    ignore it.
  * pname:subpassDescriptionRequestCount is the requested maximum sum of all
    slink:VkRenderPassCreateInfo2::pname:subpassCount values across all
    sname:VkRenderPass objects that can: exist at the same time.
  * pname:attachmentDescriptionRequestCount is the requested maximum sum of
    all slink:VkRenderPassCreateInfo2::pname:attachmentCount values across
    all sname:VkRenderPass objects that can: exist at the same time.
  * pname:descriptorSetLayoutBindingRequestCount is the requested maximum
    sum of all slink:VkDescriptorSetLayoutCreateInfo::pname:bindingCount
    values across all sname:VkDescriptorSetLayout objects that can: exist at
    the same time.
  * pname:descriptorSetLayoutBindingLimit is one greater than the maximum
    value of slink:VkDescriptorSetLayoutBinding::pname:binding that can: be
    used.
  * pname:maxImageViewMipLevels is the maximum value of
    slink:VkImageViewCreateInfo::pname:subresourceRange.levelCount that can:
    be used.
  * pname:maxImageViewArrayLayers is the maximum value of
    slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount that can:
    be used.
  * pname:maxLayeredImageViewMipLevels is the maximum value of
    slink:VkImageViewCreateInfo::pname:subresourceRange.levelCount that can:
    be used when
    slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount is
    greater than `1`.
  * pname:maxOcclusionQueriesPerPool is the requested maximum number of
    ename:VK_QUERY_TYPE_OCCLUSION queries that can: exist at the same time
    in a single query pool.
  * pname:maxPipelineStatisticsQueriesPerPool is the requested maximum
    number of ename:VK_QUERY_TYPE_PIPELINE_STATISTICS queries that can:
    exist at the same time in a single query pool.
  * pname:maxTimestampQueriesPerPool is the requested maximum number of
    ename:VK_QUERY_TYPE_TIMESTAMP queries that can: exist at the same time
    in a single query pool.
  * pname:maxImmutableSamplersPerDescriptorSetLayout is the requested
    maximum number of immutable samplers that can be used across all
    bindings in a descriptor set layout.

Multiple sname:VkDeviceObjectReservationCreateInfo structures can: be
chained together.
The maximum value from all instances of pname:maxImageViewMipLevels,
pname:maxImageViewArrayLayers, pname:maxLayeredImageViewMipLevels,
pname:descriptorSetLayoutBindingLimit, pname:maxOcclusionQueriesPerPool,
pname:maxPipelineStatisticsQueriesPerPool, pname:maxTimestampQueriesPerPool,
and pname:maxImmutableSamplersPerDescriptorSetLayout will be reserved.
For the remaining members, the sum of the requested resources from all
instances of sname:VkDeviceObjectReservationCreateInfo will be reserved.

If
slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory,
pname:deviceDestroyFreesMemory>> is ename:VK_TRUE, the reserved memory is
returned to the system when the device is destroyed, otherwise it may: not
be returned to the system until the process is terminated.

ifdef::hidden[]
// tag::scaddition[]
  * slink:VkDeviceObjectReservationCreateInfo <<SCID-4>>
// end::scaddition[]
endif::hidden[]

.Valid Usage
****
  * [[VUID-VkDeviceObjectReservationCreateInfo-maxImageViewArrayLayers-05014]]
    pname:maxImageViewArrayLayers must: be less than or equal to
    slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers
  * [[VUID-VkDeviceObjectReservationCreateInfo-maxImageViewMipLevels-05015]]
    pname:maxImageViewMipLevels must: be less than or equal to the number of
    levels in the complete mipmap chain based on the maximum of
    slink:VkPhysicalDeviceLimits::pname:maxImageDimension1D,
    pname:maxImageDimension2D, pname:maxImageDimension3D, and
    pname:maxImageDimensionCube
  * [[VUID-VkDeviceObjectReservationCreateInfo-maxLayeredImageViewMipLevels-05016]]
    pname:maxLayeredImageViewMipLevels must: be less than or equal to the
    number of levels in the complete mipmap chain based on
    slink:VkPhysicalDeviceLimits::pname:maxImageDimension1D,
    pname:maxImageDimension2D, pname:maxImageDimension3D, and
    pname:maxImageDimensionCube
  * [[VUID-VkDeviceObjectReservationCreateInfo-subpassDescriptionRequestCount-05017]]
    pname:subpassDescriptionRequestCount must: be less than or equal to
    pname:renderPassRequestCount multiplied by
    slink:VkPhysicalDeviceVulkanSC10Properties::pname:maxRenderPassSubpasses
  * [[VUID-VkDeviceObjectReservationCreateInfo-attachmentDescriptionRequestCount-05018]]
    pname:attachmentDescriptionRequestCount must: be less than or equal to
    pname:renderPassRequestCount multiplied by
    slink:VkPhysicalDeviceVulkanSC10Properties::pname:maxFramebufferAttachments
****

include::{generated}/validity/structs/VkDeviceObjectReservationCreateInfo.adoc[]
--

ifdef::VK_KHR_performance_query[]
[open,refpage='VkPerformanceQueryReservationInfoKHR',desc='Request memory reservation',type='structs']
--
If the pname:pNext chain of slink:VkDeviceObjectReservationCreateInfo
includes a slink:VkPerformanceQueryReservationInfoKHR structure, then the
structure indicates upper bounds on the number of performance queries that
can: exist at the same time in a query pool.

The sname:VkPerformanceQueryReservationInfoKHR structure is defined as:

include::{generated}/api/structs/VkPerformanceQueryReservationInfoKHR.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:maxPerformanceQueriesPerPool is the requested maximum number of
    ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR queries that can: exist at the
    same time in a single query pool.

If the sname:VkDeviceObjectReservationCreateInfo::pname:pNext chain does not
include this structure, then pname:maxPerformanceQueriesPerPool defaults to
`0`.

Multiple sname:VkPerformanceQueryReservationInfoKHR structures can be
chained together.
The maximum value from all instances of pname:maxPerformanceQueriesPerPool
will be reserved.

ifdef::hidden[]
// tag::scaddition[]
ifdef::VK_KHR_performance_query[]
  * slink:VkPerformanceQueryReservationInfoKHR <<SCID-4>>
endif::VK_KHR_performance_query[]
// end::scaddition[]
endif::hidden[]

include::{generated}/validity/structs/VkPerformanceQueryReservationInfoKHR.adoc[]
--
endif::VK_KHR_performance_query[]

ifdef::VK_NV_external_sci_sync2[]
[open,refpage='VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV',desc='Request memory reservation',type='structs']
--
If the pname:pNext chain of slink:VkDeviceObjectReservationCreateInfo
includes a slink:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV
structure, then the structure indicates the maximum number of
slink:VkSemaphoreSciSyncPoolNV objects that can: exist at the same time.

The sname:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV structure is
defined as:

include::{generated}/api/structs/VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:semaphoreSciSyncPoolRequestCount is the requested maximum number
    of slink:VkSemaphoreSciSyncPoolNV objects that can: exist at the same
    time.

If the sname:VkDeviceObjectReservationCreateInfo::pname:pNext chain does not
include this structure, then pname:semaphoreSciSyncPoolRequestCount defaults
to `0`.

Multiple sname:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV
structures can: be chained together.
The sum of the pname:semaphoreSciSyncPoolRequestCount values from all
instances of sname:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV will
be reserved.

include::{generated}/validity/structs/VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV.adoc[]
--
endif::VK_NV_external_sci_sync2[]

[open,refpage='VkPipelinePoolSize',desc='Request memory for pipelines',type='structs']
--
Memory for pipelines is reserved by the implementation at device creation
time.
The application specifies sizes to be reserved and a count for each size,
and when a pipeline is created the application specifies which size to use.

include::{generated}/api/structs/VkPipelinePoolSize.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:poolEntrySize is the size to reserve for each entry.
  * pname:poolEntryCount is the number of entries to reserve.

ifdef::hidden[]
// tag::scaddition[]
  * slink:VkPipelinePoolSize <<SCID-4>>
// end::scaddition[]
endif::hidden[]

include::{generated}/validity/structs/VkPipelinePoolSize.adoc[]
--

endif::VKSC_VERSION_1_0[]

ifdef::VK_ARM_scheduling_controls[]
The number of shader cores used by all the queues of a device can: be
controlled by adding a sname:VkDeviceQueueShaderCoreControlCreateInfoARM
structure to the pname:pNext chain of the slink:VkDeviceCreateInfo
structure.
endif::VK_ARM_scheduling_controls[]

[[devsandqueues-use]]
=== Device Use

The following is a high-level list of sname:VkDevice uses along with
references on where to find more information:

  * Creation of queues.
    See the <<devsandqueues-queues,Queues>> section below for further
    details.
  * Creation and tracking of various synchronization constructs.
    See <<synchronization,Synchronization and Cache Control>> for further
    details.
  * Allocating, freeing, and managing memory.
    See <<memory,Memory Allocation>> and <<resources,Resource Creation>> for
    further details.
  * Creation and destruction of command buffers and command buffer pools.
    See <<commandbuffers,Command Buffers>> for further details.
  * Creation, destruction, and management of graphics state.
    See <<pipelines,Pipelines>> and <<descriptorsets,Resource Descriptors>>,
    among others, for further details.


[[devsandqueues-lost-device]]
=== Lost Device

A logical device may: become _lost_ for a number of implementation-specific
reasons, indicating that pending and future command execution may: fail and
cause resources and backing memory to become undefined:.

ifdef::VKSC_VERSION_1_0[]
[NOTE]
.Note
====
<<fault-handling>> can be used by the implementation to provide more
information on the cause of a device becoming _lost_.
Allowing applications to take appropriate corrective behavior for the cause
of the device lost.
====
endif::VKSC_VERSION_1_0[]

[NOTE]
.Note
====
Typical reasons for device loss will include things like execution timing
out (to prevent denial of service), power management events, platform
resource management, implementation errors.

Applications not adhering to <<fundamentals-validusage, valid usage>> may
also result in device loss being reported, however this is not guaranteed.
Even if device loss is reported, the system may be in an unrecoverable
state, and further usage of the API is still considered invalid.
====

When this happens, certain commands will return ename:VK_ERROR_DEVICE_LOST.
After any such event, the logical device is considered _lost_.
It is not possible to reset the logical device to a non-lost state, however
the lost state is specific to a logical device (sname:VkDevice), and the
corresponding physical device (sname:VkPhysicalDevice) may: be otherwise
unaffected.

In some cases, the physical device may: also be lost, and attempting to
create a new logical device will fail, returning ename:VK_ERROR_DEVICE_LOST.
This is usually indicative of a problem with the underlying implementation,
or its connection to the host.
If the physical device has not been lost, and a new logical device is
successfully created from that physical device, it must: be in the non-lost
state.

[NOTE]
.Note
====
Whilst logical device loss may: be recoverable, in the case of physical
device loss, it is unlikely that an application will be able to recover
unless additional, unaffected physical devices exist on the system.
The error is largely informational and intended only to inform the user that
a platform issue has occurred, and should: be investigated further.
For example, underlying hardware may: have developed a fault or become
physically disconnected from the rest of the system.
In many cases, physical device loss may: cause other more serious issues
such as the operating system crashing; in which case it may: not be reported
via the Vulkan API.
====

When a device is lost, its child objects are not implicitly destroyed and
their handles are still valid.
Those objects must: still be destroyed before their parents or the device
can: be destroyed (see the <<fundamentals-objectmodel-lifetime,Object
Lifetime>> section).
The host address space corresponding to device memory mapped using
flink:vkMapMemory is still valid, and host memory accesses to these mapped
regions are still valid, but the contents are undefined:.
It is still legal to call any API command on the device and child objects.

Once a device is lost, command execution may: fail, and certain commands
that return a elink:VkResult may: return ename:VK_ERROR_DEVICE_LOST.
These commands can be identified by the inclusion of
ename:VK_ERROR_DEVICE_LOST in the Return Codes section for each command.
Commands that do not allow runtime errors must: still operate correctly for
valid usage and, if applicable, return valid data.

Commands that wait indefinitely for device execution (namely
flink:vkDeviceWaitIdle, flink:vkQueueWaitIdle, flink:vkWaitForFences
ifdef::VK_KHR_swapchain[]
or flink:vkAcquireNextImageKHR
endif::VK_KHR_swapchain[]
with a maximum pname:timeout, and flink:vkGetQueryPoolResults with the
ename:VK_QUERY_RESULT_WAIT_BIT bit set in pname:flags) must: return in
finite time even in the case of a lost device, and return either
ename:VK_SUCCESS or ename:VK_ERROR_DEVICE_LOST.
For any command that may: return ename:VK_ERROR_DEVICE_LOST, for the purpose
of determining whether a command buffer is in the
<<commandbuffers-lifecycle, pending state>>, or whether resources are
considered in-use by the device, a return value of
ename:VK_ERROR_DEVICE_LOST is equivalent to ename:VK_SUCCESS.

ifdef::VK_KHR_maintenance5[]
If a device was created with the <<features-maintenance5,
pname:maintenance5>> feature enabled, and any device command returns
ename:VK_ERROR_DEVICE_LOST, then all device commands for which
ename:VK_ERROR_DEVICE_LOST is a valid return value and which happen-after it
on the same host thread must: return ename:VK_ERROR_DEVICE_LOST.

Device commands executing on other threads must: begin returning
ename:VK_ERROR_DEVICE_LOST within finite time.
endif::VK_KHR_maintenance5[]

ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]

The content of any external memory objects that have been exported from or
imported to a lost device become undefined:.
Objects on other logical devices or in other APIs which are associated with
the same underlying memory resource as the external memory objects on the
lost device are unaffected other than their content becoming undefined:.
The layout of subresources of images on other logical devices that are bound
to sname:VkDeviceMemory objects associated with the same underlying memory
resources as external memory objects on the lost device becomes
ename:VK_IMAGE_LAYOUT_UNDEFINED.

endif::VK_VERSION_1_1,VK_KHR_external_memory[]

ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[]

The state of sname:VkSemaphore objects on other logical devices created by
<<synchronization-semaphores-importing,importing a semaphore payload>> with
temporary permanence which was exported from the lost device is undefined:.
The state of sname:VkSemaphore objects on other logical devices that
permanently share a semaphore payload with a sname:VkSemaphore object on the
lost device is undefined:, and remains undefined: following any subsequent
signal operations.
Implementations must: ensure pending and subsequently submitted wait
operations on such semaphores behave as defined in
<<synchronization-semaphores-waiting-state,Semaphore State Requirements For
Wait Operations>> for external semaphores not in a valid state for a wait
operation.

endif::VK_VERSION_1_1,VK_KHR_external_semaphore[]

ifdef::editing-notes[]
[NOTE]
.editing-note
====
TODO (piman) - I do not think we are very clear about what "`in-use by the
device`" means.
====
endif::editing-notes[]


[[devsandqueues-destruction]]
=== Device Destruction

[open,refpage='vkDestroyDevice',desc='Destroy a logical device',type='protos']
--
To destroy a device, call:

include::{generated}/api/protos/vkDestroyDevice.adoc[]

  * pname:device is the logical device to destroy.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.

To ensure that no work is active on the device, flink:vkDeviceWaitIdle can:
be used to gate the destruction of the device.
Prior to destroying a device, an application is responsible for
destroying/freeing any Vulkan objects that were created using that device as
the first parameter of the corresponding ftext:vkCreate* or
ftext:vkAllocate* command.

[NOTE]
.Note
====
The lifetime of each of these objects is bound by the lifetime of the
sname:VkDevice object.
Therefore, to avoid resource leaks, it is critical that an application
explicitly free all of these resources prior to calling
fname:vkDestroyDevice.
====

ifdef::VKSC_VERSION_1_0[]
If
slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory,
pname:deviceDestroyFreesMemory>> is ename:VK_TRUE, the reserved memory for
child objects without explicit free or destroy commands is returned to the
system when the device is destroyed, otherwise it may: not be returned to
the system until the process is terminated.
endif::VKSC_VERSION_1_0[]

.Valid Usage
****
  * [[VUID-vkDestroyDevice-device-05137]]
    All child objects created on pname:device
ifdef::VKSC_VERSION_1_0[]
    , except those with no explicit <<fundamentals-objectmodel-no-destroy,
    free or destroy command>>,
endif::VKSC_VERSION_1_0[]
    must: have been destroyed prior to destroying pname:device
ifndef::VKSC_VERSION_1_0[]
  * [[VUID-vkDestroyDevice-device-00379]]
    If sname:VkAllocationCallbacks were provided when pname:device was
    created, a compatible set of callbacks must: be provided here
  * [[VUID-vkDestroyDevice-device-00380]]
    If no sname:VkAllocationCallbacks were provided when pname:device was
    created, pname:pAllocator must: be `NULL`
endif::VKSC_VERSION_1_0[]
****

include::{generated}/validity/protos/vkDestroyDevice.adoc[]
--


[[devsandqueues-queues]]
== Queues


[[devsandqueues-queueprops]]
=== Queue Family Properties

As discussed in the <<devsandqueues-physical-device-enumeration,Physical
Device Enumeration>> section above, the
flink:vkGetPhysicalDeviceQueueFamilyProperties command is used to retrieve
details about the queue families and queues supported by a device.

Each index in the pname:pQueueFamilyProperties array returned by
flink:vkGetPhysicalDeviceQueueFamilyProperties describes a unique queue
family on that physical device.
These indices are used when creating queues, and they correspond directly
with the pname:queueFamilyIndex that is passed to the flink:vkCreateDevice
command via the slink:VkDeviceQueueCreateInfo structure as described in the
<<devsandqueues-queue-creation,Queue Creation>> section below.

Grouping of queue families within a physical device is
implementation-dependent.

[NOTE]
.Note
====
The general expectation is that a physical device groups all queues of
matching capabilities into a single family.
However, while implementations should: do this, it is possible that a
physical device may: return two separate queue families with the same
capabilities.
====

Once an application has identified a physical device with the queue(s) that
it desires to use, it will create those queues in conjunction with a logical
device.
This is described in the following section.


[[devsandqueues-queue-creation]]
=== Queue Creation

[open,refpage='VkQueue',desc='Opaque handle to a queue object',type='handles']
--
Creating a logical device also creates the queues associated with that
device.
The queues to create are described by a set of slink:VkDeviceQueueCreateInfo
structures that are passed to flink:vkCreateDevice in
pname:pQueueCreateInfos.

Queues are represented by sname:VkQueue handles:

include::{generated}/api/handles/VkQueue.adoc[]
--

[open,refpage='VkDeviceQueueCreateInfo',desc='Structure specifying parameters of a newly created device queue',type='structs']
--
The sname:VkDeviceQueueCreateInfo structure is defined as:

include::{generated}/api/structs/VkDeviceQueueCreateInfo.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
ifndef::VK_VERSION_1_1[]
  * pname:flags is reserved for future use.
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1[]
  * pname:flags is a bitmask indicating behavior of the queues.
endif::VK_VERSION_1_1[]
  * pname:queueFamilyIndex is an unsigned integer indicating the index of
    the queue family in which to create the queues on this device.
    This index corresponds to the index of an element of the
    pname:pQueueFamilyProperties array that was returned by
    fname:vkGetPhysicalDeviceQueueFamilyProperties.
  * pname:queueCount is an unsigned integer specifying the number of queues
    to create in the queue family indicated by pname:queueFamilyIndex, and
    with the behavior specified by pname:flags.
  * pname:pQueuePriorities is a pointer to an array of pname:queueCount
    normalized floating point values, specifying priorities of work that
    will be submitted to each created queue.
    See <<devsandqueues-priority,Queue Priority>> for more information.

.Valid Usage
****
  * [[VUID-VkDeviceQueueCreateInfo-queueFamilyIndex-00381]]
    pname:queueFamilyIndex must: be less than
    pname:pQueueFamilyPropertyCount returned by
    fname:vkGetPhysicalDeviceQueueFamilyProperties
  * [[VUID-VkDeviceQueueCreateInfo-queueCount-00382]]
    pname:queueCount must: be less than or equal to the pname:queueCount
    member of the sname:VkQueueFamilyProperties structure, as returned by
    fname:vkGetPhysicalDeviceQueueFamilyProperties in the
    pname:pQueueFamilyProperties[queueFamilyIndex]
  * [[VUID-VkDeviceQueueCreateInfo-pQueuePriorities-00383]]
    Each element of pname:pQueuePriorities must: be between `0.0` and `1.0`
    inclusive
ifdef::VK_VERSION_1_1[]
  * [[VUID-VkDeviceQueueCreateInfo-flags-02861]]
    If the <<features-protectedMemory, pname:protectedMemory>> feature is
    not enabled, the ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit of
    pname:flags must: not be set
  * [[VUID-VkDeviceQueueCreateInfo-flags-06449]]
    If pname:flags includes ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT,
    pname:queueFamilyIndex must: be the index of a queue family that
    includes the ename:VK_QUEUE_PROTECTED_BIT capability
endif::VK_VERSION_1_1[]
ifdef::VK_ARM_scheduling_controls[]
  * [[VUID-VkDeviceQueueCreateInfo-pNext-09398]]
    If the pname:pNext chain includes a
    slink:VkDeviceQueueShaderCoreControlCreateInfoARM structure then
    slink:VkPhysicalDeviceSchedulingControlsPropertiesARM::pname:schedulingControlsFlags
    must: contain
    ename:VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM.
endif::VK_ARM_scheduling_controls[]
****

include::{generated}/validity/structs/VkDeviceQueueCreateInfo.adoc[]
--

ifdef::VK_VERSION_1_1[]
[open,refpage='VkDeviceQueueCreateFlagBits',desc='Bitmask specifying behavior of the queue',type='enums']
--
Bits which can: be set in slink:VkDeviceQueueCreateInfo::pname:flags,
specifying usage behavior of a queue, are:

include::{generated}/api/enums/VkDeviceQueueCreateFlagBits.adoc[]

  * ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT specifies that the device
    queue is a protected-capable queue.
--
endif::VK_VERSION_1_1[]

[open,refpage='VkDeviceQueueCreateFlags',desc='Bitmask of VkDeviceQueueCreateFlagBits',type='flags']
--
include::{generated}/api/flags/VkDeviceQueueCreateFlags.adoc[]

ifndef::VK_VERSION_1_1[]
tname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask, but is
currently reserved for future use.
endif::VK_VERSION_1_1[]
ifdef::VK_VERSION_1_1[]
tname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask of zero
or more elink:VkDeviceQueueCreateFlagBits.
endif::VK_VERSION_1_1[]
--

ifdef::VK_EXT_global_priority,VK_KHR_global_priority[]
[open,refpage='VkDeviceQueueGlobalPriorityCreateInfoKHR',desc='Specify a system wide priority',type='structs',alias='VkDeviceQueueGlobalPriorityCreateInfoEXT']
--
Queues can: be created with a system-wide priority by adding a
sname:VkDeviceQueueGlobalPriorityCreateInfoKHR structure to the pname:pNext
chain of slink:VkDeviceQueueCreateInfo.

The sname:VkDeviceQueueGlobalPriorityCreateInfoKHR structure is defined as:

include::{generated}/api/structs/VkDeviceQueueGlobalPriorityCreateInfoKHR.adoc[]

ifdef::VK_EXT_global_priority[]
or the equivalent

include::{generated}/api/structs/VkDeviceQueueGlobalPriorityCreateInfoEXT.adoc[]
endif::VK_EXT_global_priority[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:globalPriority is the system-wide priority associated to these
    queues as specified by elink:VkQueueGlobalPriorityEXT

Queues created without specifying
sname:VkDeviceQueueGlobalPriorityCreateInfoKHR will default to
ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR.

include::{generated}/validity/structs/VkDeviceQueueGlobalPriorityCreateInfoKHR.adoc[]
--

[open,refpage='VkQueueGlobalPriorityKHR',desc='Values specifying a system-wide queue priority',type='enums',alias='VkQueueGlobalPriorityEXT']
--
Possible values of
slink:VkDeviceQueueGlobalPriorityCreateInfoKHR::pname:globalPriority,
specifying a system-wide priority level are:

include::{generated}/api/enums/VkQueueGlobalPriorityKHR.adoc[]

ifdef::VK_EXT_global_priority[]
or the equivalent

include::{generated}/api/enums/VkQueueGlobalPriorityEXT.adoc[]
endif::VK_EXT_global_priority[]

Priority values are sorted in ascending order.
A comparison operation on the enum values can be used to determine the
priority order.

  * ename:VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR is below the system default.
    Useful for non-interactive tasks.
  * ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR is the system default
    priority.
  * ename:VK_QUEUE_GLOBAL_PRIORITY_HIGH_KHR is above the system default.
  * ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR is the highest priority.
    Useful for critical tasks.
--

Queues with higher system priority may: be allotted more processing time
than queues with lower priority.
An implementation may: allow a higher-priority queue to starve a
lower-priority queue until the higher-priority queue has no further commands
to execute.

Priorities imply no ordering or scheduling constraints.

No specific guarantees are made about higher priority queues receiving more
processing time or better quality of service than lower priority queues.

The global priority level of a queue takes precedence over the per-process
queue priority (slink:VkDeviceQueueCreateInfo::pname:pQueuePriorities).

Abuse of this feature may: result in starving the rest of the system of
implementation resources.
Therefore, the driver implementation may: deny requests to acquire a
priority above the default priority
(ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR) if the caller does not have
sufficient privileges.
In this scenario ename:VK_ERROR_NOT_PERMITTED_KHR is returned.

The driver implementation may: fail the queue allocation request if
resources required to complete the operation have been exhausted (either by
the same process or a different process).
In this scenario ename:VK_ERROR_INITIALIZATION_FAILED is returned.

ifdef::VK_EXT_global_priority_query,VK_KHR_global_priority[]
If the <<features-globalPriorityQuery, pname:globalPriorityQuery>> feature
is enabled and the requested global priority is not reported via
slink:VkQueueFamilyGlobalPriorityPropertiesKHR, the driver implementation
must: fail the queue creation.
In this scenario, ename:VK_ERROR_INITIALIZATION_FAILED is returned.
endif::VK_EXT_global_priority_query,VK_KHR_global_priority[]
endif::VK_EXT_global_priority,VK_KHR_global_priority[]

ifdef::VK_ARM_scheduling_controls[]
[open,refpage='VkDeviceQueueShaderCoreControlCreateInfoARM',desc='Control the number of shader cores used by queues',type='structs']
--
The number of shader cores used by a queue can: be controlled by adding a
sname:VkDeviceQueueShaderCoreControlCreateInfoARM structure to the
pname:pNext chain of slink:VkDeviceQueueCreateInfo structures.

The sname:VkDeviceQueueShaderCoreControlCreateInfoARM structure is defined
as:

include::{generated}/api/structs/VkDeviceQueueShaderCoreControlCreateInfoARM.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:shaderCoreCount is the number of shader cores this queue uses.

Queues created without specifying
sname:VkDeviceQueueShaderCoreControlCreateInfoARM will default to using all
the shader cores available.

.Valid Usage
****
  * [[VUID-VkDeviceQueueShaderCoreControlCreateInfoARM-shaderCoreCount-09399]]
    pname:shaderCoreCount must: be greater than 0 and less than or equal to
    the total number of shader cores as reported via
    slink:VkPhysicalDeviceShaderCoreBuiltinsPropertiesARM::pname:shaderCoreCount.
****

include::{generated}/validity/structs/VkDeviceQueueShaderCoreControlCreateInfoARM.adoc[]
--
endif::VK_ARM_scheduling_controls[]

[open,refpage='vkGetDeviceQueue',desc='Get a queue handle from a device',type='protos']
--
To retrieve a handle to a slink:VkQueue object, call:

include::{generated}/api/protos/vkGetDeviceQueue.adoc[]

  * pname:device is the logical device that owns the queue.
  * pname:queueFamilyIndex is the index of the queue family to which the
    queue belongs.
  * pname:queueIndex is the index within this queue family of the queue to
    retrieve.
  * pname:pQueue is a pointer to a slink:VkQueue object that will be filled
    with the handle for the requested queue.

ifdef::VK_VERSION_1_1[]
fname:vkGetDeviceQueue must: only be used to get queues that were created
with the pname:flags parameter of slink:VkDeviceQueueCreateInfo set to zero.
To get queues that were created with a non-zero pname:flags parameter use
flink:vkGetDeviceQueue2.
endif::VK_VERSION_1_1[]

.Valid Usage
****
  * [[VUID-vkGetDeviceQueue-queueFamilyIndex-00384]]
    pname:queueFamilyIndex must: be one of the queue family indices
    specified when pname:device was created, via the
    slink:VkDeviceQueueCreateInfo structure
  * [[VUID-vkGetDeviceQueue-queueIndex-00385]]
    pname:queueIndex must: be less than the value of
    slink:VkDeviceQueueCreateInfo::pname:queueCount for the queue family
    indicated by pname:queueFamilyIndex when pname:device was created
  * [[VUID-vkGetDeviceQueue-flags-01841]]
    slink:VkDeviceQueueCreateInfo::pname:flags must: have been set to zero
    when pname:device was created
****

include::{generated}/validity/protos/vkGetDeviceQueue.adoc[]
--

ifdef::VK_VERSION_1_1[]
[open,refpage='vkGetDeviceQueue2',desc='Get a queue handle from a device',type='protos']
--
To retrieve a handle to a slink:VkQueue object with specific
tlink:VkDeviceQueueCreateFlags creation flags, call:

include::{generated}/api/protos/vkGetDeviceQueue2.adoc[]

  * pname:device is the logical device that owns the queue.
  * pname:pQueueInfo is a pointer to a slink:VkDeviceQueueInfo2 structure,
    describing parameters of the device queue to be retrieved.
  * pname:pQueue is a pointer to a slink:VkQueue object that will be filled
    with the handle for the requested queue.

include::{generated}/validity/protos/vkGetDeviceQueue2.adoc[]
--

[open,refpage='VkDeviceQueueInfo2',desc='Structure specifying the parameters used for device queue creation',type='structs']
--
The sname:VkDeviceQueueInfo2 structure is defined as:

include::{generated}/api/structs/VkDeviceQueueInfo2.adoc[]

  * pname:sType is a elink:VkStructureType value identifying this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
    The pname:pNext chain of sname:VkDeviceQueueInfo2 can: be used to
    provide additional device queue parameters to fname:vkGetDeviceQueue2.
  * pname:flags is a tlink:VkDeviceQueueCreateFlags value indicating the
    flags used to create the device queue.
  * pname:queueFamilyIndex is the index of the queue family to which the
    queue belongs.
  * pname:queueIndex is the index of the queue to retrieve from within the
    set of queues that share both the queue family and flags specified.

The queue returned by fname:vkGetDeviceQueue2 must: have the same
pname:flags value from this structure as that used at device creation time
in a slink:VkDeviceQueueCreateInfo structure.

[NOTE]
.Note
====
Normally, if you create both protected-capable and non-protected-capable
queues with the same family, they are treated as separate lists of queues
and pname:queueIndex is relative to the start of the list of queues
specified by both pname:queueFamilyIndex and pname:flags.
However, for historical reasons, some implementations may exhibit different
behavior.
These divergent implementations instead concatenate the lists of queues and
treat pname:queueIndex as relative to the start of the first list of queues
with the given pname:queueFamilyIndex.
This only matters in cases where an application has created both
protected-capable and non-protected-capable queues from the same queue
family.

For such divergent implementations, the maximum value of pname:queueIndex is
equal to the sum of slink:VkDeviceQueueCreateInfo::pname:queueCount minus
one, for all slink:VkDeviceQueueCreateInfo structures that share a common
pname:queueFamilyIndex.

Such implementations will return `NULL` for either the protected or
unprotected queues when calling `vkGetDeviceQueue2` with pname:queueIndex in
the range zero to slink:VkDeviceQueueCreateInfo::pname:queueCount minus one.
In cases where these implementations returned `NULL`, the corresponding
queues are instead located in the extended range described in the preceding
two paragraphs.

This behaviour will not be observed on any driver that has passed Vulkan
conformance test suite version 1.3.3.0, or any subsequent version.
This information can be found by querying
sname:VkPhysicalDeviceDriverProperties::pname:conformanceVersion.
====

.Valid Usage
****
  * [[VUID-VkDeviceQueueInfo2-queueFamilyIndex-01842]]
    pname:queueFamilyIndex must: be one of the queue family indices
    specified when pname:device was created, via the
    slink:VkDeviceQueueCreateInfo structure
  * [[VUID-VkDeviceQueueInfo2-flags-06225]]
    pname:flags must: be equal to slink:VkDeviceQueueCreateInfo::pname:flags
    for a slink:VkDeviceQueueCreateInfo structure for the queue family
    indicated by pname:queueFamilyIndex when pname:device was created
  * [[VUID-VkDeviceQueueInfo2-queueIndex-01843]]
    pname:queueIndex must: be less than
    slink:VkDeviceQueueCreateInfo::pname:queueCount for the corresponding
    queue family and flags indicated by pname:queueFamilyIndex and
    pname:flags when pname:device was created
****

include::{generated}/validity/structs/VkDeviceQueueInfo2.adoc[]
--
endif::VK_VERSION_1_1[]


[[devsandqueues-index]]
=== Queue Family Index

The queue family index is used in multiple places in Vulkan in order to tie
operations to a specific family of queues.

When retrieving a handle to the queue via fname:vkGetDeviceQueue, the queue
family index is used to select which queue family to retrieve the
sname:VkQueue handle from as described in the previous section.

When creating a sname:VkCommandPool object (see
<<commandbuffers-pools,Command Pools>>), a queue family index is specified
in the slink:VkCommandPoolCreateInfo structure.
Command buffers from this pool can: only be submitted on queues
corresponding to this queue family.

When creating sname:VkImage (see <<resources-images,Images>>) and
sname:VkBuffer (see <<resources-buffers,Buffers>>) resources, a set of queue
families is included in the slink:VkImageCreateInfo and
slink:VkBufferCreateInfo structures to specify the queue families that can:
access the resource.

When inserting a slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier
(see <<synchronization-pipeline-barriers>>), a source and destination queue
family index is specified to allow the ownership of a buffer or image to be
transferred from one queue family to another.
See the <<resources-sharing,Resource Sharing>> section for details.


[[devsandqueues-priority]]
=== Queue Priority

Each queue is assigned a priority, as set in the
slink:VkDeviceQueueCreateInfo structures when creating the device.
The priority of each queue is a normalized floating point value between 0.0
and 1.0, which is then translated to a discrete priority level by the
implementation.
Higher values indicate a higher priority, with 0.0 being the lowest priority
and 1.0 being the highest.

Within the same device, queues with higher priority may: be allotted more
processing time than queues with lower priority.
The implementation makes no guarantees with regards to ordering or
scheduling among queues with the same priority, other than the constraints
defined by any <<synchronization, explicit synchronization primitives>>.
The implementation makes no guarantees with regards to queues across
different devices.

An implementation may: allow a higher-priority queue to starve a
lower-priority queue on the same sname:VkDevice until the higher-priority
queue has no further commands to execute.
The relationship of queue priorities must: not cause queues on one
sname:VkDevice to starve queues on another sname:VkDevice.

No specific guarantees are made about higher priority queues receiving more
processing time or better quality of service than lower priority queues.


[[devsandqueues-submission]]
=== Queue Submission

Work is submitted to a queue via _queue submission_ commands such as
ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[]
flink:vkQueueSubmit2 or
endif::VK_VERSION_1_3,VK_KHR_synchronization2[]
flink:vkQueueSubmit.
Queue submission commands define a set of _queue operations_ to be executed
by the underlying physical device, including synchronization with semaphores
and fences.

Submission commands take as parameters a target queue, zero or more
_batches_ of work, and an optional: fence to signal upon completion.
Each batch consists of three distinct parts:

  . Zero or more semaphores to wait on before execution of the rest of the
    batch.
  ** If present, these describe a <<synchronization-semaphores-waiting,
     semaphore wait operation>>.
  . Zero or more work items to execute.
  ** If present, these describe a _queue operation_ matching the work
     described.
  . Zero or more semaphores to signal upon completion of the work items.
  ** If present, these describe a <<synchronization-semaphores-signaling,
     semaphore signal operation>>.

If a fence is present in a queue submission, it describes a
<<synchronization-fences-signaling, fence signal operation>>.

All work described by a queue submission command must: be submitted to the
queue before the command returns.


ifndef::VKSC_VERSION_1_0[]
[[devsandqueues-sparsebinding]]
==== Sparse Memory Binding

In Vulkan it is possible to sparsely bind memory to buffers and images as
described in the <<sparsememory,Sparse Resource>> chapter.
Sparse memory binding is a queue operation.
A queue whose flags include the ename:VK_QUEUE_SPARSE_BINDING_BIT must: be
able to support the mapping of a virtual address to a physical address on
the device.
This causes an update to the page table mappings on the device.
This update must: be synchronized on a queue to avoid corrupting page table
mappings during execution of graphics commands.
By binding the sparse memory resources on queues, all commands that are
dependent on the updated bindings are synchronized to only execute after the
binding is updated.
See the <<synchronization,Synchronization and Cache Control>> chapter for
how this synchronization is accomplished.

endif::VKSC_VERSION_1_0[]

[[devsandqueues-queuedestruction]]
=== Queue Destruction

Queues are created along with a logical device during fname:vkCreateDevice.
All queues associated with a logical device are destroyed when
fname:vkDestroyDevice is called on that device.