| // 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 <<extendingvulkan-coreversions-versionnumbers>>. |
| * pname:driverVersion is the vendor-specified version of the driver. |
| * pname:vendorID is a unique identifier for the _vendor_ (see below) of |
| the physical device. |
| * pname:deviceID is a unique identifier for the physical device among |
| devices available from the vendor. |
| * pname:deviceType is a elink:VkPhysicalDeviceType specifying the type of |
| device. |
| * pname:deviceName is an array of ename:VK_MAX_PHYSICAL_DEVICE_NAME_SIZE |
| code:char containing a null-terminated UTF-8 string which is the name of |
| the device. |
| * pname:pipelineCacheUUID is an array of ename:VK_UUID_SIZE code:uint8_t |
| values representing a universally unique identifier for the device. |
| * pname:limits is the slink:VkPhysicalDeviceLimits structure specifying |
| device-specific limits of the physical device. |
| See <<limits,Limits>> for details. |
| * pname:sparseProperties is the slink:VkPhysicalDeviceSparseProperties |
| structure specifying various sparse related properties of the physical |
| device. |
| See <<sparsememory-physicalprops,Sparse Properties>> for details. |
| |
| ifdef::VK_VERSION_1_1[] |
| [NOTE] |
| .Note |
| ==== |
| The value of pname:apiVersion may: be different than the version returned by |
| flink:vkEnumerateInstanceVersion; either higher or lower. |
| In such cases, the application must: not use functionality that exceeds the |
| version of Vulkan associated with a given object. |
| The pname:pApiVersion parameter returned by flink:vkEnumerateInstanceVersion |
| is the version associated with a slink:VkInstance and its children, except |
| for a slink:VkPhysicalDevice and its children. |
| sname:VkPhysicalDeviceProperties::pname:apiVersion is the version associated |
| with a slink:VkPhysicalDevice and its children. |
| ==== |
| endif::VK_VERSION_1_1[] |
| |
| [NOTE] |
| .Note |
| ==== |
| The encoding of pname:driverVersion is implementation-defined. |
| It may: not use the same encoding as pname:apiVersion. |
| Applications should follow information from the _vendor_ on how to extract |
| the version information from pname:driverVersion. |
| ==== |
| |
| The pname:vendorID and pname:deviceID fields are provided to allow |
| applications to adapt to device characteristics that are not adequately |
| exposed by other Vulkan queries. |
| |
| [NOTE] |
| .Note |
| ==== |
| These may: include performance profiles, hardware errata, or other |
| characteristics. |
| ==== |
| |
| The _vendor_ identified by pname:vendorID is the entity responsible for the |
| most salient characteristics of the underlying implementation of the |
| slink:VkPhysicalDevice being queried. |
| |
| [NOTE] |
| .Note |
| ==== |
| For example, in the case of a discrete GPU implementation, this should: be |
| the GPU chipset vendor. |
| In the case of a hardware accelerator integrated into a system-on-chip |
| (SoC), this should: be the supplier of the silicon IP used to create the |
| accelerator. |
| ==== |
| |
| If the vendor has a https://pcisig.com/membership/member-companies[PCI |
| vendor ID], the low 16 bits of pname:vendorID must: contain that PCI vendor |
| ID, and the remaining bits must: be set to zero. |
| Otherwise, the value returned must: be a valid Khronos vendor ID, obtained |
| as described in the <<vulkan-styleguide,Vulkan Documentation and Extensions: |
| Procedures and Conventions>> document in the section "`Registering a Vendor |
| ID with Khronos`". |
| Khronos vendor IDs are allocated starting at 0x10000, to distinguish them |
| from the PCI vendor ID namespace. |
| Khronos vendor IDs are symbolically defined in the elink:VkVendorId type. |
| |
| The vendor is also responsible for the value returned in pname:deviceID. |
| If the implementation is driven primarily by a https://pcisig.com/[PCI |
| device] with a https://pcisig.com/[PCI device ID], the low 16 bits of |
| pname:deviceID must: contain that PCI device ID, and the remaining bits |
| must: be set to zero. |
| Otherwise, the choice of what values to return may: be dictated by operating |
| system or platform policies - but should: uniquely identify both the device |
| version and any major configuration options (for example, core count in the |
| case of multicore devices). |
| |
| [NOTE] |
| .Note |
| ==== |
| The same device ID should: be used for all physical implementations of that |
| device version and configuration. |
| For example, all uses of a specific silicon IP GPU version and configuration |
| should: use the same device ID, even if those uses occur in different SoCs. |
| ==== |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceProperties.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 |
| <<shaders-group-operations, group operations>> with |
| <<shaders-scope-subgroup, subgroup scope>> are supported in. |
| pname:subgroupSupportedStages will have the |
| ename:VK_SHADER_STAGE_COMPUTE_BIT bit set if any of the physical |
| device's queues support ename:VK_QUEUE_COMPUTE_BIT. |
| * pname:subgroupSupportedOperations is a bitmask of |
| elink:VkSubgroupFeatureFlagBits specifying the sets of |
| <<shaders-group-operations, group operations>> with |
| <<shaders-scope-subgroup, subgroup scope>> supported on this device. |
| pname:subgroupSupportedOperations will have the |
| ename:VK_SUBGROUP_FEATURE_BASIC_BIT bit set if any of the physical |
| device's queues support ename:VK_QUEUE_GRAPHICS_BIT or |
| ename:VK_QUEUE_COMPUTE_BIT. |
| * [[{anchor-prefix}limits-subgroupQuadOperationsInAllStages]] |
| pname:subgroupQuadOperationsInAllStages is a boolean specifying whether |
| <<shaders-quad-operations,quad group operations>> are available in all |
| stages, or are restricted to fragment and compute stages. |
| include::{chapters}/limits.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[] |
| * <<external-memory-handle-types-compatibility,External memory handle |
| types compatibility>> |
| endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] |
| * <<external-semaphore-handle-types-compatibility,External semaphore |
| handle types compatibility>> |
| endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] |
| * <<external-fence-handle-types-compatibility,External fence handle types |
| compatibility>> |
| endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] |
| |
| If pname:deviceLUIDValid is ename:VK_FALSE, the values of pname:deviceLUID |
| and pname:deviceNodeMask are undefined:. |
| If pname:deviceLUIDValid is ename:VK_TRUE and Vulkan is running on the |
| Windows operating system, the contents of pname:deviceLUID can: be cast to |
| an code:LUID object and must: be equal to the locally unique identifier of a |
| code:IDXGIAdapter1 object that corresponds to pname:physicalDevice. |
| If pname:deviceLUIDValid is ename:VK_TRUE, pname:deviceNodeMask must: |
| contain exactly one bit. |
| If Vulkan is running on an operating system that supports the Direct3D 12 |
| API and pname:physicalDevice corresponds to an individual device in a linked |
| device adapter, pname:deviceNodeMask identifies the Direct3D 12 node |
| corresponding to pname:physicalDevice. |
| Otherwise, pname:deviceNodeMask must: be `1`. |
| |
| [NOTE] |
| .Note |
| ==== |
| Although they have identical descriptions, |
| slink:VkPhysicalDeviceIDProperties::pname:deviceUUID may differ from |
| slink:VkPhysicalDeviceProperties2::pname:pipelineCacheUUID. |
| The former is intended to identify and correlate devices across API and |
| driver boundaries, while the latter is used to identify a compatible device |
| and driver combination to use when serializing and de-serializing pipeline |
| state. |
| |
| Implementations should: return pname:deviceUUID values which are likely to |
| be unique even in the presence of multiple Vulkan implementations (such as a |
| GPU driver and a software renderer; two drivers for different GPUs; or the |
| same Vulkan driver running on two logically different devices). |
| |
| Khronos' conformance testing 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'] |
| -- |
| 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'] |
| -- |
| 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'] |
| -- |
| 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 |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct8BitSignedAccelerated is a boolean that will be |
| ename:VK_TRUE if the support for 8-bit signed dot product operations |
| using the code:OpSDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct8BitMixedSignednessAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 8-bit mixed signedness dot |
| product operations using the code:OpSUDotKHR SPIR-V instruction is |
| accelerated <<devsandqueues-integer-dot-product-accelerated,as defined |
| below>>. |
| * pname:integerDotProduct4x8BitPackedUnsignedAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 8-bit unsigned dot product |
| operations from operands packed into 32-bit integers using the |
| code:OpUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct4x8BitPackedSignedAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 8-bit signed dot product |
| operations from operands packed into 32-bit integers using the |
| code:OpSDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct4x8BitPackedMixedSignednessAccelerated is a |
| boolean that will be ename:VK_TRUE if the support for 8-bit mixed |
| signedness dot product operations from operands packed into 32-bit |
| integers using the code:OpSUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct16BitUnsignedAccelerated is a boolean that will |
| be ename:VK_TRUE if the support for 16-bit unsigned dot product |
| operations using the code:OpUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct16BitSignedAccelerated is a boolean that will be |
| ename:VK_TRUE if the support for 16-bit signed dot product operations |
| using the code:OpSDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct16BitMixedSignednessAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 16-bit mixed signedness dot |
| product operations using the code:OpSUDotKHR SPIR-V instruction is |
| accelerated <<devsandqueues-integer-dot-product-accelerated,as defined |
| below>>. |
| * pname:integerDotProduct32BitUnsignedAccelerated is a boolean that will |
| be ename:VK_TRUE if the support for 32-bit unsigned dot product |
| operations using the code:OpUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct32BitSignedAccelerated is a boolean that will be |
| ename:VK_TRUE if the support for 32-bit signed dot product operations |
| using the code:OpSDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct32BitMixedSignednessAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 32-bit mixed signedness dot |
| product operations using the code:OpSUDotKHR SPIR-V instruction is |
| accelerated <<devsandqueues-integer-dot-product-accelerated,as defined |
| below>>. |
| * pname:integerDotProduct64BitUnsignedAccelerated is a boolean that will |
| be ename:VK_TRUE if the support for 64-bit unsigned dot product |
| operations using the code:OpUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct64BitSignedAccelerated is a boolean that will be |
| ename:VK_TRUE if the support for 64-bit signed dot product operations |
| using the code:OpSDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct64BitMixedSignednessAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 64-bit mixed signedness dot |
| product operations using the code:OpSUDotKHR SPIR-V instruction is |
| accelerated <<devsandqueues-integer-dot-product-accelerated,as defined |
| below>>. |
| * pname:integerDotProductAccumulatingSaturating8BitUnsignedAccelerated is |
| a boolean that will be ename:VK_TRUE if the support for 8-bit unsigned |
| accumulating saturating dot product operations using the |
| code:OpUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating8BitSignedAccelerated is a |
| boolean that will be ename:VK_TRUE if the support for 8-bit signed |
| accumulating saturating dot product operations using the |
| code:OpSDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 8-bit mixed |
| signedness accumulating saturating dot product operations using the |
| code:OpSUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 8-bit |
| unsigned accumulating saturating dot product operations from operands |
| packed into 32-bit integers using the code:OpUDotAccSatKHR SPIR-V |
| instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 8-bit signed |
| accumulating saturating dot product operations from operands packed into |
| 32-bit integers using the code:OpSDotAccSatKHR SPIR-V instruction is |
| accelerated <<devsandqueues-integer-dot-product-accelerated,as defined |
| below>>. |
| * pname:integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 8-bit mixed |
| signedness accumulating saturating dot product operations from operands |
| packed into 32-bit integers using the code:OpSUDotAccSatKHR SPIR-V |
| instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating16BitUnsignedAccelerated is |
| a boolean that will be ename:VK_TRUE if the support for 16-bit unsigned |
| accumulating saturating dot product operations using the |
| code:OpUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating16BitSignedAccelerated is a |
| boolean that will be ename:VK_TRUE if the support for 16-bit signed |
| accumulating saturating dot product operations using the |
| code:OpSDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 16-bit mixed |
| signedness accumulating saturating dot product operations using the |
| code:OpSUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating32BitUnsignedAccelerated is |
| a boolean that will be ename:VK_TRUE if the support for 32-bit unsigned |
| accumulating saturating dot product operations using the |
| code:OpUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating32BitSignedAccelerated is a |
| boolean that will be ename:VK_TRUE if the support for 32-bit signed |
| accumulating saturating dot product operations using the |
| code:OpSDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 32-bit mixed |
| signedness accumulating saturating dot product operations using the |
| code:OpSUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating64BitUnsignedAccelerated is |
| a boolean that will be ename:VK_TRUE if the support for 64-bit unsigned |
| accumulating saturating dot product operations using the |
| code:OpUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating64BitSignedAccelerated is a |
| boolean that will be ename:VK_TRUE if the support for 64-bit signed |
| accumulating saturating dot product operations using the |
| code:OpSDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 64-bit mixed |
| signedness accumulating saturating dot product operations using the |
| code:OpSUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| |
| :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 <<memory-device,Device Memory>> section describes memory properties |
| queried from the physical device. |
| |
| For physical device feature queries see the <<features, Features>> chapter. |
| |
| include::{generated}/validity/structs/VkQueueFamilyProperties.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 |
| <<sparsememory,Sparse Resources>>). |
| 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 <<memory-protected-memory,Protected Memory>>). |
| 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 <<devsandqueues-queues,Queues>>. |
| -- |
| |
| [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::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::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 <<devsandqueues-physical-device-enumeration,Physical |
| Devices>>, a Vulkan application will first query for all physical devices in |
| a system. |
| Each physical device can: then be queried for its capabilities, including |
| its queue and queue family properties. |
| Once an acceptable physical device is identified, an application will create |
| a corresponding logical device. |
| The created logical device is then the primary interface to the physical |
| device. |
| |
| How to enumerate the physical devices in a system and query those physical |
| devices for their queue family properties is described in the |
| <<devsandqueues-physical-device-enumeration, Physical Device Enumeration>> |
| section above. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[] |
| |
| A single logical device can: be created from multiple physical devices, if |
| those physical devices belong to the same device group. |
| A _device group_ is a set of physical devices that support accessing each |
| other's memory and recording a single command buffer that can: be executed |
| on all the physical devices. |
| Device groups are enumerated by calling |
| flink:vkEnumeratePhysicalDeviceGroups, and a logical device is created from |
| a subset of the physical devices in a device group by passing the physical |
| devices through slink:VkDeviceGroupDeviceCreateInfo. |
| For two physical devices to be in the same device group, they must: support |
| identical extensions, features, and properties. |
| |
| [NOTE] |
| .Note |
| ==== |
| Physical devices in the same device group must: be so similar because there |
| are no rules for how different features/properties would interact. |
| They must: return the same values for nearly every invariant |
| ftext:vkGetPhysicalDevice* feature, property, capability, etc., but could |
| potentially differ for certain queries based on things like having a |
| different display connected, or a different compositor. |
| The specification does not attempt to enumerate which state is in each |
| category, because such a list would quickly become out of date. |
| ==== |
| |
| [open,refpage='vkEnumeratePhysicalDeviceGroups',desc='Enumerates groups of physical devices that can be used to create a single logical device',type='protos'] |
| -- |
| To retrieve a list of the device groups present in the system, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkEnumeratePhysicalDeviceGroups.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'] |
| -- |
| 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 |
| <<devsandqueues-physical-device-enumeration, Physical Device |
| Enumeration>>). |
| * pname:pCreateInfo is a pointer to a slink:VkDeviceCreateInfo structure |
| containing information about how to create the device. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pDevice is a pointer to a handle in which the created |
| slink:VkDevice is returned. |
| |
| fname:vkCreateDevice verifies that extensions and features requested in the |
| pname:ppEnabledExtensionNames and pname:pEnabledFeatures members of |
| pname:pCreateInfo, respectively, are supported by the implementation. |
| If any requested extension is not supported, fname:vkCreateDevice must: |
| return ename:VK_ERROR_EXTENSION_NOT_PRESENT. |
| If any requested feature is not supported, fname:vkCreateDevice must: return |
| ename:VK_ERROR_FEATURE_NOT_PRESENT. |
| Support for extensions can: be checked before creating a device by querying |
| flink:vkEnumerateDeviceExtensionProperties. |
| Support for features can: similarly be checked by querying |
| flink:vkGetPhysicalDeviceFeatures. |
| |
| 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 <<extendingvulkan-extensions-extensiondependencies, required device |
| extensions>> 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 <<devsandqueues-queue-creation,Queue Creation>> section |
| below for further details. |
| * pname:pQueueCreateInfos is a pointer to an array of |
| slink:VkDeviceQueueCreateInfo structures describing the queues that are |
| requested to be created along with the logical device. |
| Refer to the <<devsandqueues-queue-creation,Queue Creation>> section |
| below for further details. |
| * pname:enabledLayerCount is deprecated and ignored. |
| * pname:ppEnabledLayerNames is deprecated and ignored. |
| See <<extendingvulkan-layers-devicelayerdeprecation>>. |
| * pname:enabledExtensionCount is the number of device extensions to |
| enable. |
| * pname:ppEnabledExtensionNames is a pointer to an array of |
| pname:enabledExtensionCount null-terminated UTF-8 strings containing the |
| names of extensions to enable for the created device. |
| See the <<extendingvulkan-extensions>> section for further details. |
| * pname:pEnabledFeatures is `NULL` or a pointer to a |
| slink:VkPhysicalDeviceFeatures structure containing boolean indicators |
| of all the features to be enabled. |
| Refer to the <<features,Features>> section for further details. |
| |
| .Valid Usage |
| **** |
| 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 <<features-shadingRateImage,pname:shadingRateImage>> is enabled, |
| <<features-pipelineFragmentShadingRate, |
| pname:pipelineFragmentShadingRate>> must: not be enabled |
| * [[VUID-VkDeviceCreateInfo-shadingRateImage-04479]] |
| If <<features-shadingRateImage,pname:shadingRateImage>> is enabled, |
| <<features-primitiveFragmentShadingRate, |
| pname:primitiveFragmentShadingRate>> must: not be enabled |
| * [[VUID-VkDeviceCreateInfo-shadingRateImage-04480]] |
| If <<features-shadingRateImage,pname:shadingRateImage>> is enabled, |
| <<features-attachmentFragmentShadingRate, |
| pname:attachmentFragmentShadingRate>> 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 <<features-fragmentDensityMap,pname:fragmentDensityMap>> is enabled, |
| <<features-pipelineFragmentShadingRate, |
| pname:pipelineFragmentShadingRate>> must: not be enabled |
| * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04482]] |
| If <<features-fragmentDensityMap,pname:fragmentDensityMap>> is enabled, |
| <<features-primitiveFragmentShadingRate, |
| pname:primitiveFragmentShadingRate>> must: not be enabled |
| * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04483]] |
| If <<features-fragmentDensityMap,pname:fragmentDensityMap>> is enabled, |
| <<features-attachmentFragmentShadingRate, |
| pname:attachmentFragmentShadingRate>> must: not be enabled |
| endif::VK_KHR_fragment_shading_rate,VK_EXT_fragment_density_map[] |
| ifdef::VK_EXT_shader_image_atomic_int64[] |
| * [[VUID-VkDeviceCreateInfo-None-04896]] |
| If <<features-sparseImageInt64Atomics, pname:sparseImageInt64Atomics>> |
| is enabled, <<features-shaderImageInt64Atomics, |
| pname:shaderImageInt64Atomics>> must: be enabled |
| endif::VK_EXT_shader_image_atomic_int64[] |
| ifdef::VK_EXT_shader_atomic_float[] |
| * [[VUID-VkDeviceCreateInfo-None-04897]] |
| If <<features-sparseImageFloat32Atomics, |
| pname:sparseImageFloat32Atomics>> is enabled, |
| <<features-shaderImageFloat32Atomics, pname:shaderImageFloat32Atomics>> |
| must: be enabled |
| * [[VUID-VkDeviceCreateInfo-None-04898]] |
| If <<features-sparseImageFloat32AtomicAdd, |
| pname:sparseImageFloat32AtomicAdd>> is enabled, |
| <<features-shaderImageFloat32AtomicAdd, |
| pname:shaderImageFloat32AtomicAdd>> must: be enabled |
| endif::VK_EXT_shader_atomic_float[] |
| ifdef::VK_EXT_shader_atomic_float2[] |
| * [[VUID-VkDeviceCreateInfo-sparseImageFloat32AtomicMinMax-04975]] |
| If <<features-sparseImageFloat32AtomicMinMax, |
| pname:sparseImageFloat32AtomicMinMax>> is enabled, |
| <<features-shaderImageFloat32AtomicMinMax, |
| pname:shaderImageFloat32AtomicMinMax>> must: be enabled |
| endif::VK_EXT_shader_atomic_float2[] |
| **** |
| |
| 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 <<device-diagnostic-checkpoints, |
| diagnostic checkpoints>> 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 <<debugging-object-types, |
| `VkObjectType` and Vulkan Handle Relationship>> table. |
| Otherwise, pname:objectHandle is undefined:. |
| * pname:heapIndex describes which memory heap this device memory |
| allocation is made from. |
| If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT |
| or ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, |
| pname:heapIndex corresponds to one of the valid heaps from the |
| slink:VkPhysicalDeviceMemoryProperties structure. |
| Otherwise, pname:heapIndex is undefined:. |
| |
| pname:memoryObjectId is used to avoid double-counting on the same memory |
| object. |
| |
| If an internally-allocated device memory object or a slink:VkDeviceMemory |
| cannot: be exported, pname:memoryObjectId must: be unique in the |
| slink:VkDevice. |
| |
| If an internally-allocated device memory object or a slink:VkDeviceMemory |
| supports being exported, pname:memoryObjectId must: be unique system wide. |
| |
| If an internal device memory object or a slink:VkDeviceMemory is backed by |
| an imported external memory object, pname:memoryObjectId must: be unique |
| system wide. |
| |
| ifdef::implementation-guide[] |
| .Implementor's Note |
| **** |
| If the heap backing an internally-allocated device memory cannot: be used to |
| back slink:VkDeviceMemory, implementations can: advertise that heap with no |
| types. |
| **** |
| endif::implementation-guide[] |
| |
| [NOTE] |
| .Note |
| ==== |
| This structure should only be considered valid during the lifetime of the |
| triggered callback. |
| |
| For ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT and |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT events, |
| pname:objectHandle usually will not yet exist when the application or tool |
| receives the callback. |
| pname:objectHandle will only exist when the create or allocate call that |
| triggered the event returns, and if the allocation or import ends up failing |
| pname:objectHandle will not ever exist. |
| ==== |
| |
| include::{generated}/validity/structs/VkDeviceMemoryReportCallbackDataEXT.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 <<devsandqueues-queues,Queues>> section below for further |
| details. |
| * Creation and tracking of various synchronization constructs. |
| See <<synchronization,Synchronization and Cache Control>> for further |
| details. |
| * Allocating, freeing, and managing memory. |
| See <<memory,Memory Allocation>> and <<resources,Resource Creation>> for |
| further details. |
| * Creation and destruction of command buffers and command buffer pools. |
| See <<commandbuffers,Command Buffers>> for further details. |
| * Creation, destruction, and management of graphics state. |
| See <<pipelines,Pipelines>> and <<descriptorsets,Resource Descriptors>>, |
| among others, for further details. |
| |
| |
| [[devsandqueues-lost-device]] |
| === Lost Device |
| |
| A logical device may: become _lost_ for a number of implementation-specific |
| reasons, indicating that pending and future command execution may: fail and |
| cause resources and backing memory to become undefined:. |
| |
| [NOTE] |
| .Note |
| ==== |
| Typical reasons for device loss will include things like execution timing |
| out (to prevent denial of service), power management events, platform |
| resource management, implementation errors. |
| |
| Applications not adhering to <<fundamentals-validusage, valid usage>> may |
| also result in device loss being reported, however this is not guaranteed. |
| Even if device loss is reported, the system may be in an unrecoverable |
| state, and further usage of the API is still considered invalid. |
| ==== |
| |
| When this happens, certain commands will return ename:VK_ERROR_DEVICE_LOST. |
| After any such event, the logical device is considered _lost_. |
| It is not possible to reset the logical device to a non-lost state, however |
| the lost state is specific to a logical device (sname:VkDevice), and the |
| corresponding physical device (sname:VkPhysicalDevice) may: be otherwise |
| unaffected. |
| |
| In some cases, the physical device may: also be lost, and attempting to |
| create a new logical device will fail, returning ename:VK_ERROR_DEVICE_LOST. |
| This is usually indicative of a problem with the underlying implementation, |
| or its connection to the host. |
| If the physical device has not been lost, and a new logical device is |
| successfully created from that physical device, it must: be in the non-lost |
| state. |
| |
| [NOTE] |
| .Note |
| ==== |
| Whilst logical device loss may: be recoverable, in the case of physical |
| device loss, it is unlikely that an application will be able to recover |
| unless additional, unaffected physical devices exist on the system. |
| The error is largely informational and intended only to inform the user that |
| a platform issue has occurred, and should: be investigated further. |
| For example, underlying hardware may: have developed a fault or become |
| physically disconnected from the rest of the system. |
| In many cases, physical device loss may: cause other more serious issues |
| such as the operating system crashing; in which case it may: not be reported |
| via the Vulkan API. |
| ==== |
| |
| When a device is lost, its child objects are not implicitly destroyed and |
| their handles are still valid. |
| Those objects must: still be destroyed before their parents or the device |
| can: be destroyed (see the <<fundamentals-objectmodel-lifetime,Object |
| Lifetime>> section). |
| The host address space corresponding to device memory mapped using |
| flink:vkMapMemory is still valid, and host memory accesses to these mapped |
| regions are still valid, but the contents are undefined:. |
| It is still legal to call any API command on the device and child objects. |
| |
| Once a device is lost, command execution may: fail, and 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 |
| <<commandbuffers-lifecycle, pending state>>, or whether resources are |
| considered in-use by the device, a return value of |
| ename:VK_ERROR_DEVICE_LOST is equivalent to ename:VK_SUCCESS. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| The content of any external memory objects that have been exported from or |
| imported to a lost device become undefined:. |
| Objects on other logical devices or in other APIs which are associated with |
| the same underlying memory resource as the external memory objects on the |
| lost device are unaffected other than their content becoming undefined:. |
| The layout of subresources of images on other logical devices that are bound |
| to sname:VkDeviceMemory objects associated with the same underlying memory |
| resources as external memory objects on the lost device becomes |
| ename:VK_IMAGE_LAYOUT_UNDEFINED. |
| |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[] |
| |
| The state of sname:VkSemaphore objects on other logical devices created by |
| <<synchronization-semaphores-importing,importing a semaphore payload>> with |
| temporary permanence which was exported from the lost device is undefined:. |
| The state of sname:VkSemaphore objects on other logical devices that |
| permanently share a semaphore payload with a sname:VkSemaphore object on the |
| lost device is undefined:, and remains undefined: following any subsequent |
| signal operations. |
| Implementations must: ensure pending and subsequently submitted wait |
| operations on such semaphores behave as defined in |
| <<synchronization-semaphores-waiting-state,Semaphore State Requirements For |
| Wait Operations>> for external semaphores not in a valid state for a wait |
| operation. |
| |
| endif::VK_VERSION_1_1,VK_KHR_external_semaphore[] |
| |
| ifdef::editing-notes[] |
| [NOTE] |
| .editing-note |
| ==== |
| TODO (piman) - I do not think we are very clear about what "`in-use by the |
| device`" means. |
| ==== |
| endif::editing-notes[] |
| |
| |
| [[devsandqueues-destruction]] |
| === Device Destruction |
| |
| [open,refpage='vkDestroyDevice',desc='Destroy a logical device',type='protos'] |
| -- |
| To destroy a device, call: |
| |
| include::{generated}/api/protos/vkDestroyDevice.txt[] |
| |
| * pname:device is the logical device to destroy. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| |
| To ensure that no work is active on the device, flink:vkDeviceWaitIdle can: |
| be used to gate the destruction of the device. |
| Prior to destroying a device, an application is responsible for |
| destroying/freeing any Vulkan objects that were created using that device as |
| the first parameter of the corresponding ftext:vkCreate* or |
| ftext:vkAllocate* command. |
| |
| [NOTE] |
| .Note |
| ==== |
| The lifetime of each of these objects is bound by the lifetime of the |
| sname:VkDevice object. |
| Therefore, to avoid resource leaks, it is critical that an application |
| explicitly free all of these resources prior to calling |
| fname:vkDestroyDevice. |
| ==== |
| |
| .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 <<devsandqueues-physical-device-enumeration,Physical |
| Device Enumeration>> section above, the |
| flink:vkGetPhysicalDeviceQueueFamilyProperties command is used to retrieve |
| details about the queue families and queues supported by a device. |
| |
| Each index in the pname:pQueueFamilyProperties array returned by |
| flink:vkGetPhysicalDeviceQueueFamilyProperties describes a unique queue |
| family on that physical device. |
| These indices are used when creating queues, and they correspond directly |
| with the pname:queueFamilyIndex that is passed to the flink:vkCreateDevice |
| command via the slink:VkDeviceQueueCreateInfo structure as described in the |
| <<devsandqueues-queue-creation,Queue Creation>> section below. |
| |
| Grouping of queue families within a physical device is |
| implementation-dependent. |
| |
| [NOTE] |
| .Note |
| ==== |
| The general expectation is that a physical device groups all queues of |
| matching capabilities into a single family. |
| However, while implementations should: do this, it is possible that a |
| physical device may: return two separate queue families with the same |
| capabilities. |
| ==== |
| |
| Once an application has identified a physical device with the queue(s) that |
| it desires to use, it will create those queues in conjunction with a logical |
| device. |
| This is described in the following section. |
| |
| |
| [[devsandqueues-queue-creation]] |
| === Queue Creation |
| |
| [open,refpage='VkQueue',desc='Opaque handle to a queue object',type='handles'] |
| -- |
| Creating a logical device also creates the queues associated with that |
| device. |
| The queues to create are described by a set of slink:VkDeviceQueueCreateInfo |
| structures that are passed to flink:vkCreateDevice in |
| pname:pQueueCreateInfos. |
| |
| Queues are represented by sname:VkQueue handles: |
| |
| include::{generated}/api/handles/VkQueue.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 <<devsandqueues-priority,Queue Priority>> for more information. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceQueueCreateInfo-queueFamilyIndex-00381]] |
| pname:queueFamilyIndex must: be less than |
| pname:pQueueFamilyPropertyCount returned by |
| fname:vkGetPhysicalDeviceQueueFamilyProperties |
| * [[VUID-VkDeviceQueueCreateInfo-queueCount-00382]] |
| pname:queueCount must: be less than or equal to the pname:queueCount |
| member of the sname:VkQueueFamilyProperties structure, as returned by |
| fname:vkGetPhysicalDeviceQueueFamilyProperties in the |
| pname:pQueueFamilyProperties[queueFamilyIndex] |
| * [[VUID-VkDeviceQueueCreateInfo-pQueuePriorities-00383]] |
| Each element of pname:pQueuePriorities must: be between `0.0` and `1.0` |
| inclusive |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-VkDeviceQueueCreateInfo-flags-02861]] |
| If the <<features-protectedMemory, protected memory>> 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 <<features-globalPriorityQuery, pname:globalPriorityQuery>> 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 |
| <<commandbuffers-pools,Command Pools>>), a queue family index is specified |
| in the slink:VkCommandPoolCreateInfo structure. |
| Command buffers from this pool can: only be submitted on queues |
| corresponding to this queue family. |
| |
| When creating sname:VkImage (see <<resources-images,Images>>) and |
| sname:VkBuffer (see <<resources-buffers,Buffers>>) resources, a set of queue |
| families is included in the slink:VkImageCreateInfo and |
| slink:VkBufferCreateInfo structures to specify the queue families that can: |
| access the resource. |
| |
| When inserting a slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier |
| (see <<synchronization-pipeline-barriers>>), a source and destination queue |
| family index is specified to allow the ownership of a buffer or image to be |
| transferred from one queue family to another. |
| See the <<resources-sharing,Resource Sharing>> section for details. |
| |
| |
| [[devsandqueues-priority]] |
| === Queue Priority |
| |
| Each queue is assigned a priority, as set in the |
| slink:VkDeviceQueueCreateInfo structures when creating the device. |
| The priority of each queue is a normalized floating point value between 0.0 |
| and 1.0, which is then translated to a discrete priority level by the |
| implementation. |
| Higher values indicate a higher priority, with 0.0 being the lowest priority |
| and 1.0 being the highest. |
| |
| Within the same device, queues with higher priority may: be allotted more |
| processing time than queues with lower priority. |
| The implementation makes no guarantees with regards to ordering or |
| scheduling among queues with the same priority, other than the constraints |
| defined by any <<synchronization, explicit synchronization primitives>>. |
| The implementation makes no guarantees with regards to queues across |
| different devices. |
| |
| An implementation may: allow a higher-priority queue to starve a |
| lower-priority queue on the same sname:VkDevice until the higher-priority |
| queue has no further commands to execute. |
| The relationship of queue priorities must: not cause queues on one |
| sname:VkDevice to starve queues on another sname:VkDevice. |
| |
| No specific guarantees are made about higher priority queues receiving more |
| processing time or better quality of service than lower priority queues. |
| |
| |
| [[devsandqueues-submission]] |
| === Queue Submission |
| |
| Work is submitted to a queue via _queue submission_ commands such as |
| ifdef::VK_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 <<synchronization-semaphores-waiting, |
| semaphore wait operation>>. |
| . Zero or more work items to execute. |
| ** If present, these describe a _queue operation_ matching the work |
| described. |
| . Zero or more semaphores to signal upon completion of the work items. |
| ** If present, these describe a <<synchronization-semaphores-signaling, |
| semaphore signal operation>>. |
| |
| If a fence is present in a queue submission, it describes a |
| <<synchronization-fences-signaling, fence signal operation>>. |
| |
| All work described by a queue submission command must: be submitted to the |
| queue before the command returns. |
| |
| |
| [[devsandqueues-sparsebinding]] |
| ==== Sparse Memory Binding |
| |
| In Vulkan it is possible to sparsely bind memory to buffers and images as |
| described in the <<sparsememory,Sparse Resource>> chapter. |
| Sparse memory binding is a queue operation. |
| A queue whose flags include the ename:VK_QUEUE_SPARSE_BINDING_BIT must: be |
| able to support the mapping of a virtual address to a physical address on |
| the device. |
| This causes an update to the page table mappings on the device. |
| This update must: be synchronized on a queue to avoid corrupting page table |
| mappings during execution of graphics commands. |
| By binding the sparse memory resources on queues, all commands that are |
| dependent on the updated bindings are synchronized to only execute after the |
| binding is updated. |
| See the <<synchronization,Synchronization and Cache Control>> chapter for |
| how this synchronization is accomplished. |
| |
| |
| [[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. |
