// Copyright 2015-2021 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.txt[] -- [[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.txt[] * 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.txt[] -- [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.txt[] * 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.txt[] -- [open,refpage='VkPhysicalDeviceProperties',desc='Structure specifying physical device properties',type='structs'] -- The sname:VkPhysicalDeviceProperties structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceProperties.txt[] * pname:apiVersion is the version of Vulkan supported by the device, encoded as described in <>. * 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 <> for details. * pname:sparseProperties is the slink:VkPhysicalDeviceSparseProperties structure specifying various sparse related properties of the physical device. See <> 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. ==== 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 <> 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.txt[] -- [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.txt[] [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::deviceName. include::{generated}/api/enums/VK_MAX_PHYSICAL_DEVICE_NAME_SIZE.txt[] -- [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.txt[] * 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.txt[] 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.txt[] 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.txt[] -- [open,refpage='VkPhysicalDeviceProperties2',desc='Structure specifying physical device properties',type='structs'] -- The sname:VkPhysicalDeviceProperties2 structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceProperties2.txt[] ifdef::VK_KHR_get_physical_device_properties2[] or the equivalent include::{generated}/api/structs/VkPhysicalDeviceProperties2KHR.txt[] endif::VK_KHR_get_physical_device_properties2[] * pname:sType is the type of 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.txt[] -- 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.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. :anchor-prefix: include::{chapters}/devsandqueues.txt[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 <> with <> 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 <> with <> 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 <> are available in all stages, or are restricted to fragment and compute stages. include::{chapters}/limits.txt[tag=VK_KHR_maintenance2-properties] include::{chapters}/limits.txt[tag=VK_KHR_multiview-properties] include::{chapters}/limits.txt[tag=VK_KHR_protected_memory-properties] include::{chapters}/limits.txt[tag=VK_KHR_maintenance3-properties] :refpage: VkPhysicalDeviceVulkan11Properties include::{chapters}/limits.txt[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.txt[] -- [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.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. :anchor-prefix: include::{chapters}/devsandqueues.txt[tag=VK_KHR_driver_properties-properties] include::{chapters}/limits.txt[tag=VK_KHR_shader_float_controls-properties] include::{chapters}/limits.txt[tag=VK_EXT_descriptor_indexing-properties] include::{chapters}/limits.txt[tag=VK_KHR_depth_stencil_resolve-properties] include::{chapters}/limits.txt[tag=VK_EXT_sampler_filter_minmax-properties] include::{chapters}/limits.txt[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.txt[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.txt[] -- endif::VK_VERSION_1_2[] 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.txt[] ifdef::VK_KHR_external_memory_capabilities[] or the equivalent include::{generated}/api/structs/VkPhysicalDeviceIDPropertiesKHR.txt[] endif::VK_KHR_external_memory_capabilities[] * pname:sType is the type of 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.txt[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[] * <> endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] * <> endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] * <> 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 can not 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.txt[] -- [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::deviceUUID and slink:VkPhysicalDeviceIDProperties::driverUUID. include::{generated}/api/enums/VK_UUID_SIZE.txt[] -- [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::deviceLUID. include::{generated}/api/enums/VK_LUID_SIZE.txt[] 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.txt[] 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.txt[] ifdef::VK_KHR_driver_properties[] or the equivalent include::{generated}/api/structs/VkPhysicalDeviceDriverPropertiesKHR.txt[] endif::VK_KHR_driver_properties[] * pname:sType is the type of 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.txt[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.txt[] -- [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.txt[] ifdef::VK_KHR_driver_properties[] or the equivalent include::{generated}/api/enums/VkDriverIdKHR.txt[] 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::driverName. include::{generated}/api/enums/VK_MAX_DRIVER_NAME_SIZE.txt[] ifdef::VK_KHR_driver_properties[] or the equivalent include::{generated}/api/enums/VK_MAX_DRIVER_NAME_SIZE_KHR.txt[] 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::driverInfo. include::{generated}/api/enums/VK_MAX_DRIVER_INFO_SIZE.txt[] ifdef::VK_KHR_driver_properties[] or the equivalent include::{generated}/api/enums/VK_MAX_DRIVER_INFO_SIZE_KHR.txt[] 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.txt[] ifdef::VK_KHR_driver_properties[] or the equivalent include::{generated}/api/structs/VkConformanceVersionKHR.txt[] 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.txt[] -- 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.txt[] * pname:sType is the type of 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.txt[tag=limits_desc] These are properties of the PCI bus information of a physical device. include::{generated}/validity/structs/VkPhysicalDevicePCIBusInfoPropertiesEXT.txt[] -- 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.txt[] * pname:sType is the type of 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.txt[tag=limits_desc] These are properties of the DRM information of a physical device. include::{generated}/validity/structs/VkPhysicalDeviceDrmPropertiesEXT.txt[] -- endif::VK_EXT_physical_device_drm[] endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] ifdef::VK_KHR_shader_integer_dot_product[] [open,refpage='VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR',desc='Structure containing information about integer dot product support for a physical device',type='structs'] -- The sname:VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. * 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 <>. :refpage: VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR include::{chapters}/limits.txt[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/VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR.txt[] -- endif::VK_KHR_shader_integer_dot_product[] [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.txt[] * 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.txt[] -- [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.txt[] * 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_KHR_synchronization2[] flink:vkCmdWriteTimestamp2KHR or endif::VK_KHR_synchronization2[] flink:vkCmdWriteTimestamp. The valid range for the count is 36..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 <> section describes memory properties queried from the physical device. For physical device feature queries see the <> chapter. include::{generated}/validity/structs/VkQueueFamilyProperties.txt[] -- [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.txt[] * 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 <>). If any of the sparse resource features are enabled, then at least one queue family must: support this bit. ifdef::VK_KHR_video_decode_queue[] * ename:VK_QUEUE_VIDEO_DECODE_BIT_KHR specifies that queues in this queue family support 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. endif::VK_KHR_video_encode_queue[] 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 <>). If the physical device supports the 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 protected memory 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 <>. -- [open,refpage='VkQueueFlags',desc='Bitmask of VkQueueFlagBits',type='flags'] -- include::{generated}/api/flags/VkQueueFlags.txt[] 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.txt[] 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.txt[] 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.txt[] -- [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.txt[] ifdef::VK_KHR_get_physical_device_properties2[] or the equivalent include::{generated}/api/structs/VkQueueFamilyProperties2KHR.txt[] endif::VK_KHR_get_physical_device_properties2[] * pname:sType is the type of 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.txt[] -- ifdef::VK_EXT_global_priority_query[] [open,refpage='VkQueueFamilyGlobalPriorityPropertiesEXT',desc='Return structure for queue family global priority information query',type='structs'] -- The definition of slink:VkQueueFamilyGlobalPriorityPropertiesEXT is: include::{generated}/api/structs/VkQueueFamilyGlobalPriorityPropertiesEXT.txt[] * pname:sType is the type of 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. 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:VkQueueGlobalPriorityEXT 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_EXT, ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT and ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_EXT is not allowed. ==== include::{generated}/validity/structs/VkQueueFamilyGlobalPriorityPropertiesEXT.txt[] -- endif::VK_EXT_global_priority_query[] ifdef::VK_NV_device_diagnostic_checkpoints[] include::{chapters}/VK_NV_device_diagnostic_checkpoints/queue_checkpoint_properties.txt[] endif::VK_NV_device_diagnostic_checkpoints[] endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] ifdef::VK_KHR_performance_query[] include::{chapters}/VK_KHR_performance_query/queuefamily.txt[] 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 <>, 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 <> 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.txt[] 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.txt[] 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.txt[] -- [open,refpage='VkPhysicalDeviceGroupProperties',desc='Structure specifying physical device group properties',type='structs'] -- The sname:VkPhysicalDeviceGroupProperties structure is defined as: include::{generated}/api/structs/VkPhysicalDeviceGroupProperties.txt[] ifdef::VK_KHR_device_group_creation[] or the equivalent include::{generated}/api/structs/VkPhysicalDeviceGroupPropertiesKHR.txt[] endif::VK_KHR_device_group_creation[] * pname:sType is the type of 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.txt[] -- [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::physicalDevices. include::{generated}/api/enums/VK_MAX_DEVICE_GROUP_SIZE.txt[] ifdef::VK_KHR_device_group_creation[] or the equivalent include::{generated}/api/enums/VK_MAX_DEVICE_GROUP_SIZE_KHR.txt[] 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.txt[] -- [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.txt[] * pname:physicalDevice must: be one of the device handles returned from a call to fname:vkEnumeratePhysicalDevices (see <>). * 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 <> 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. After verifying and enabling the extensions the sname:VkDevice object is created and returned to the application. 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). If that occurs, fname:vkCreateDevice will return ename:VK_ERROR_TOO_MANY_OBJECTS. .Valid Usage **** * [[VUID-vkCreateDevice-ppEnabledExtensionNames-01387]] All <> for each extension in the slink:VkDeviceCreateInfo::pname:ppEnabledExtensionNames list must: also be present in that list **** include::{generated}/validity/protos/vkCreateDevice.txt[] -- [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.txt[] * pname:sType is the type of 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 <> 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 <> section below for further details. * pname:enabledLayerCount is deprecated and ignored. * pname:ppEnabledLayerNames is deprecated and ignored. See <>. * 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 <> 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 <> section for further details. .Valid Usage **** ifndef::VK_VERSION_1_1[] * [[VUID-VkDeviceCreateInfo-queueFamilyIndex-00372]] The pname:queueFamilyIndex member of each element of pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos endif::VK_VERSION_1_1[] ifdef::VK_VERSION_1_1[] * [[VUID-VkDeviceCreateInfo-queueFamilyIndex-02802]] The pname:queueFamilyIndex member of each element of pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos, except that two members can share the same pname:queueFamilyIndex if one is a protected-capable queue and one is not a protected-capable queue 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]] pname:ppEnabledExtensionNames must: not contain `apiext:VK_AMD_negative_viewport_height` endif::VK_VERSION_1_1[] ifndef::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_VERSION_1_1[] 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-ppEnabledExtensions-04476]] If pname:ppEnabledExtensions 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-ppEnabledExtensions-02831]] If pname:ppEnabledExtensions 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-ppEnabledExtensions-02832]] If pname:ppEnabledExtensions 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-ppEnabledExtensions-02833]] If pname:ppEnabledExtensions 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-ppEnabledExtensions-02834]] If pname:ppEnabledExtensions 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-ppEnabledExtensions-02835]] If pname:ppEnabledExtensions 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_KHR_portability_subset[] * [[VUID-VkDeviceCreateInfo-pProperties-04451]] If the `apiext:VK_KHR_portability_subset` extension is included in pname:pProperties of flink:vkEnumerateDeviceExtensionProperties, pname:ppEnabledExtensions 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 <> is enabled, <> must: not be enabled * [[VUID-VkDeviceCreateInfo-shadingRateImage-04479]] If <> is enabled, <> must: not be enabled * [[VUID-VkDeviceCreateInfo-shadingRateImage-04480]] If <> is enabled, <> 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 <> is enabled, <> must: not be enabled * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04482]] If <> is enabled, <> must: not be enabled * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04483]] If <> is enabled, <> 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 <> is enabled, <> must: be enabled endif::VK_EXT_shader_image_atomic_int64[] ifdef::VK_EXT_shader_atomic_float[] * [[VUID-VkDeviceCreateInfo-None-04897]] If <> is enabled, <> must: be enabled * [[VUID-VkDeviceCreateInfo-None-04898]] If <> is enabled, <> must: be enabled endif::VK_EXT_shader_atomic_float[] ifdef::VK_EXT_shader_atomic_float2[] * [[VUID-VkDeviceCreateInfo-sparseImageFloat32AtomicMinMax-04975]] If <> is enabled, <> must: be enabled endif::VK_EXT_shader_atomic_float2[] **** include::{generated}/validity/structs/VkDeviceCreateInfo.txt[] -- [open,refpage='VkDeviceCreateFlags',desc='Reserved for future use',type='flags'] -- include::{generated}/api/flags/VkDeviceCreateFlags.txt[] 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.txt[] ifdef::VK_KHR_device_group_creation[] or the equivalent include::{generated}/api/structs/VkDeviceGroupDeviceCreateInfoKHR.txt[] endif::VK_KHR_device_group_creation[] * pname:sType is the type of 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.txt[] -- 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.txt[] * pname:sType is the type of 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.txt[] -- [open,refpage='VkMemoryOverallocationBehaviorAMD',desc='Specify memory overallocation behavior',type='enums'] -- Possible values for slink:VkDeviceMemoryOverallocationCreateInfoAMD::pname:overallocationBehavior include: include::{generated}/api/enums/VkMemoryOverallocationBehaviorAMD.txt[] * 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.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:flags is a bitmask of elink:VkDeviceDiagnosticsConfigFlagBitsNV specifying addtional parameters for configuring diagnostic tools. include::{generated}/validity/structs/VkDeviceDiagnosticsConfigCreateInfoNV.txt[] -- [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.txt[] * 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 <> for draw calls, dispatches, ifdef::VK_NV_ray_tracing[] trace rays, endif::VK_NV_ray_tracing[] and copies. The CPU call stack at the time of the command will be associated as the marker data for the automatically inserted checkpoints. -- [open,refpage='VkDeviceDiagnosticsConfigFlagsNV',desc='Bitmask of VkDeviceDiagnosticsConfigFlagBitsNV',type='flags'] -- include::{generated}/api/flags/VkDeviceDiagnosticsConfigFlagsNV.txt[] 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.txt[] * pname:sType is the type of 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.txt[] -- [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.txt[] * 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.txt[] * pname:sType is the type of 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 <> 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.txt[] -- [open,refpage='VkDeviceMemoryReportFlagsEXT',desc='Reserved for future use',type='flags'] -- include::{generated}/api/flags/VkDeviceMemoryReportFlagsEXT.txt[] 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.txt[] * 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_EXT_private_data[] [open,refpage='VkDevicePrivateDataCreateInfoEXT',desc='Reserve private data slots',type='structs'] -- To reserve private data storage slots, add a slink:VkDevicePrivateDataCreateInfoEXT 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/VkDevicePrivateDataCreateInfoEXT.txt[] * pname:sType is the type of 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/VkDevicePrivateDataCreateInfoEXT.txt[] -- endif::VK_EXT_private_data[] [[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 <> section below for further details. * Creation and tracking of various synchronization constructs. See <> for further details. * Allocating, freeing, and managing memory. See <> and <> for further details. * Creation and destruction of command buffers and command buffer pools. See <> for further details. * Creation, destruction, and management of graphics state. See <> and <>, 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:. [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 <> 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 <> 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 commands that return a elink:VkResult may: return ename:VK_ERROR_DEVICE_LOST. 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 <>, 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_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 <> 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 <> 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.txt[] * pname:device is the logical device to destroy. * pname:pAllocator controls host memory allocation as described in the <> 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. ==== .Valid Usage **** * [[VUID-vkDestroyDevice-device-00378]] All child objects created on pname:device must: have been destroyed prior to destroying pname:device * [[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` **** include::{generated}/validity/protos/vkDestroyDevice.txt[] -- [[devsandqueues-queues]] == Queues [[devsandqueues-queueprops]] === Queue Family Properties As discussed in the <> 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 <> 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.txt[] -- [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.txt[] * pname:sType is the type of 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 queue. endif::VK_VERSION_1_1[] * pname:queueFamilyIndex is an unsigned integer indicating the index of the queue family in which to create the queue 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. * 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 <> 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 <> 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[] **** include::{generated}/validity/structs/VkDeviceQueueCreateInfo.txt[] -- 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 to specify usage behavior of the queue are: include::{generated}/api/enums/VkDeviceQueueCreateFlagBits.txt[] * 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.txt[] 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[] [open,refpage='VkDeviceQueueGlobalPriorityCreateInfoEXT',desc='Specify a system wide priority',type='structs'] -- A queue can: be created with a system-wide priority by adding a sname:VkDeviceQueueGlobalPriorityCreateInfoEXT structure to the pname:pNext chain of slink:VkDeviceQueueCreateInfo. The sname:VkDeviceQueueGlobalPriorityCreateInfoEXT structure is defined as: include::{generated}/api/structs/VkDeviceQueueGlobalPriorityCreateInfoEXT.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to a structure extending this structure. * pname:globalPriority is the system-wide priority associated to this queue as specified by elink:VkQueueGlobalPriorityEXT A queue created without specifying sname:VkDeviceQueueGlobalPriorityCreateInfoEXT will default to ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT. include::{generated}/validity/structs/VkDeviceQueueGlobalPriorityCreateInfoEXT.txt[] -- [open,refpage='VkQueueGlobalPriorityEXT',desc='Values specifying a system-wide queue priority',type='enums'] -- Possible values of slink:VkDeviceQueueGlobalPriorityCreateInfoEXT::pname:globalPriority, specifying a system-wide priority level are: include::{generated}/api/enums/VkQueueGlobalPriorityEXT.txt[] 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_EXT is below the system default. Useful for non-interactive tasks. * ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT is the system default priority. * ename:VK_QUEUE_GLOBAL_PRIORITY_HIGH_EXT is above the system default. * ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_EXT 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_EXT) if the caller does not have sufficient privileges. In this scenario ename:VK_ERROR_NOT_PERMITTED_EXT 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[] If the <> feature is enabled and the requested global priority is not reported via slink:VkQueueFamilyGlobalPriorityPropertiesEXT, the driver implementation must: fail the queue creation. In this scenario, ename:VK_ERROR_INITIALIZATION_FAILED is returned. endif::VK_EXT_global_priority_query[] endif::VK_EXT_global_priority[] [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.txt[] * 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.txt[] -- 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.txt[] * 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.txt[] -- [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.txt[] * pname:sType is the type of 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 within this queue family of the queue to retrieve. 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. If no matching pname:flags were specified at device creation time, then the handle returned in pname:pQueue must: be `NULL`. .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.txt[] -- 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 <>), 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 <>) and sname:VkBuffer (see <>) 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 <>), 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 <> 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 <>. 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_KHR_synchronization2[] flink:vkQueueSubmit2KHR or endif::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 <>. . 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 <>. If a fence is present in a queue submission, it describes a <>. All work described by a queue submission command must: be submitted to the queue before the command returns. [[devsandqueues-sparsebinding]] ==== Sparse Memory Binding In Vulkan it is possible to sparsely bind memory to buffers and images as described in the <> 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 <> chapter for how this synchronization is accomplished. [[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.