| // Copyright 2015-2023 The Khronos Group Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [[devsandqueues]] |
| = Devices and Queues |
| |
| Once Vulkan is initialized, devices and queues are the primary objects used |
| to interact with a Vulkan implementation. |
| |
| [open,refpage='VkPhysicalDevice',desc='Opaque handle to a physical device object',type='handles'] |
| -- |
| Vulkan separates the concept of _physical_ and _logical_ devices. |
| A physical device usually represents a single complete implementation of |
| Vulkan (excluding instance-level functionality) available to the host, of |
| which there are a finite number. |
| A logical device represents an instance of that implementation with its own |
| state and resources independent of other logical devices. |
| |
| Physical devices are represented by sname:VkPhysicalDevice handles: |
| |
| include::{generated}/api/handles/VkPhysicalDevice.adoc[] |
| -- |
| |
| |
| [[devsandqueues-physical-device-enumeration]] |
| == Physical Devices |
| |
| [open,refpage='vkEnumeratePhysicalDevices',desc='Enumerates the physical devices accessible to a Vulkan instance',type='protos'] |
| -- |
| To retrieve a list of physical device objects representing the physical |
| devices installed in the system, call: |
| |
| include::{generated}/api/protos/vkEnumeratePhysicalDevices.adoc[] |
| |
| * pname:instance is a handle to a Vulkan instance previously created with |
| flink:vkCreateInstance. |
| * pname:pPhysicalDeviceCount is a pointer to an integer related to the |
| number of physical devices available or queried, as described below. |
| * pname:pPhysicalDevices is either `NULL` or a pointer to an array of |
| sname:VkPhysicalDevice handles. |
| |
| If pname:pPhysicalDevices is `NULL`, then the number of physical devices |
| available is returned in pname:pPhysicalDeviceCount. |
| Otherwise, pname:pPhysicalDeviceCount must: point to a variable set by the |
| user to the number of elements in the pname:pPhysicalDevices array, and on |
| return the variable is overwritten with the number of handles actually |
| written to pname:pPhysicalDevices. |
| If pname:pPhysicalDeviceCount is less than the number of physical devices |
| available, at most pname:pPhysicalDeviceCount structures will be written, |
| and ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to |
| indicate that not all the available physical devices were returned. |
| |
| include::{generated}/validity/protos/vkEnumeratePhysicalDevices.adoc[] |
| -- |
| |
| [open,refpage='vkGetPhysicalDeviceProperties',desc='Returns properties of a physical device',type='protos'] |
| -- |
| To query general properties of physical devices once enumerated, call: |
| |
| include::{generated}/api/protos/vkGetPhysicalDeviceProperties.adoc[] |
| |
| * pname:physicalDevice is the handle to the physical device whose |
| properties will be queried. |
| * pname:pProperties is a pointer to a slink:VkPhysicalDeviceProperties |
| structure in which properties are returned. |
| |
| include::{generated}/validity/protos/vkGetPhysicalDeviceProperties.adoc[] |
| -- |
| |
| [open,refpage='VkPhysicalDeviceProperties',desc='Structure specifying physical device properties',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceProperties structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceProperties.adoc[] |
| |
| * pname:apiVersion is the version of Vulkan supported by the device, |
| encoded as described in <<extendingvulkan-coreversions-versionnumbers>>. |
| * pname:driverVersion is the vendor-specified version of the driver. |
| * pname:vendorID is a unique identifier for the _vendor_ (see below) of |
| the physical device. |
| * pname:deviceID is a unique identifier for the physical device among |
| devices available from the vendor. |
| * pname:deviceType is a elink:VkPhysicalDeviceType specifying the type of |
| device. |
| * pname:deviceName is an array of ename:VK_MAX_PHYSICAL_DEVICE_NAME_SIZE |
| code:char containing a null-terminated UTF-8 string which is the name of |
| the device. |
| * pname:pipelineCacheUUID is an array of ename:VK_UUID_SIZE code:uint8_t |
| values representing a universally unique identifier for the device. |
| * pname:limits is the slink:VkPhysicalDeviceLimits structure specifying |
| device-specific limits of the physical device. |
| See <<limits, Limits>> for details. |
| * pname:sparseProperties is the slink:VkPhysicalDeviceSparseProperties |
| structure specifying various sparse related properties of the physical |
| device. |
| See <<sparsememory-physicalprops, Sparse Properties>> for details. |
| |
| ifdef::VK_VERSION_1_1[] |
| [NOTE] |
| .Note |
| ==== |
| The value of pname:apiVersion may: be different than the version returned by |
| flink:vkEnumerateInstanceVersion; either higher or lower. |
| In such cases, the application must: not use functionality that exceeds the |
| version of Vulkan associated with a given object. |
| The pname:pApiVersion parameter returned by flink:vkEnumerateInstanceVersion |
| is the version associated with a slink:VkInstance and its children, except |
| for a slink:VkPhysicalDevice and its children. |
| sname:VkPhysicalDeviceProperties::pname:apiVersion is the version associated |
| with a slink:VkPhysicalDevice and its children. |
| ==== |
| endif::VK_VERSION_1_1[] |
| |
| [NOTE] |
| .Note |
| ==== |
| The encoding of pname:driverVersion is implementation-defined. |
| It may: not use the same encoding as pname:apiVersion. |
| Applications should follow information from the _vendor_ on how to extract |
| the version information from pname:driverVersion. |
| ==== |
| |
| ifdef::VK_VERSION_1_3[] |
| On implementations that claim support for the <<roadmap-2022, Roadmap 2022>> |
| profile, the major and minor version expressed by pname:apiVersion must: be |
| at least Vulkan 1.3. |
| endif::VK_VERSION_1_3[] |
| |
| The pname:vendorID and pname:deviceID fields are provided to allow |
| applications to adapt to device characteristics that are not adequately |
| exposed by other Vulkan queries. |
| |
| [NOTE] |
| .Note |
| ==== |
| These may: include performance profiles, hardware errata, or other |
| characteristics. |
| ==== |
| |
| The _vendor_ identified by pname:vendorID is the entity responsible for the |
| most salient characteristics of the underlying implementation of the |
| slink:VkPhysicalDevice being queried. |
| |
| [NOTE] |
| .Note |
| ==== |
| For example, in the case of a discrete GPU implementation, this should: be |
| the GPU chipset vendor. |
| In the case of a hardware accelerator integrated into a system-on-chip |
| (SoC), this should: be the supplier of the silicon IP used to create the |
| accelerator. |
| ==== |
| |
| If the vendor has a https://pcisig.com/membership/member-companies[PCI |
| vendor ID], the low 16 bits of pname:vendorID must: contain that PCI vendor |
| ID, and the remaining bits must: be set to zero. |
| Otherwise, the value returned must: be a valid Khronos vendor ID, obtained |
| as described in the <<vulkan-styleguide,Vulkan Documentation and Extensions: |
| Procedures and Conventions>> document in the section "`Registering a Vendor |
| ID with Khronos`". |
| Khronos vendor IDs are allocated starting at 0x10000, to distinguish them |
| from the PCI vendor ID namespace. |
| Khronos vendor IDs are symbolically defined in the elink:VkVendorId type. |
| |
| The vendor is also responsible for the value returned in pname:deviceID. |
| If the implementation is driven primarily by a https://pcisig.com/[PCI |
| device] with a https://pcisig.com/[PCI device ID], the low 16 bits of |
| pname:deviceID must: contain that PCI device ID, and the remaining bits |
| must: be set to zero. |
| Otherwise, the choice of what values to return may: be dictated by operating |
| system or platform policies - but should: uniquely identify both the device |
| version and any major configuration options (for example, core count in the |
| case of multicore devices). |
| |
| [NOTE] |
| .Note |
| ==== |
| The same device ID should: be used for all physical implementations of that |
| device version and configuration. |
| For example, all uses of a specific silicon IP GPU version and configuration |
| should: use the same device ID, even if those uses occur in different SoCs. |
| ==== |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceProperties.adoc[] |
| -- |
| |
| [open,refpage='VkVendorId',desc='Khronos vendor IDs',type='enums'] |
| -- |
| Khronos vendor IDs which may: be returned in |
| slink:VkPhysicalDeviceProperties::pname:vendorID are: |
| |
| include::{generated}/api/enums/VkVendorId.adoc[] |
| |
| [NOTE] |
| .Note |
| ==== |
| Khronos vendor IDs may be allocated by vendors at any time. |
| Only the latest canonical versions of this Specification, of the |
| corresponding `vk.xml` API Registry, and of the corresponding |
| `{core_header}` header file must: contain all reserved Khronos vendor IDs. |
| |
| Only Khronos vendor IDs are given symbolic names at present. |
| PCI vendor IDs returned by the implementation can be looked up in the |
| PCI-SIG database. |
| ==== |
| -- |
| |
| [open,refpage='VK_MAX_PHYSICAL_DEVICE_NAME_SIZE',desc='Length of a physical device name string',type='consts'] |
| -- |
| ename:VK_MAX_PHYSICAL_DEVICE_NAME_SIZE is the length in code:char values of |
| an array containing a physical device name string, as returned in |
| slink:VkPhysicalDeviceProperties::pname:deviceName. |
| |
| include::{generated}/api/enums/VK_MAX_PHYSICAL_DEVICE_NAME_SIZE.adoc[] |
| -- |
| |
| [open,refpage='VkPhysicalDeviceType',desc='Supported physical device types',type='enums'] |
| -- |
| The physical device types which may: be returned in |
| slink:VkPhysicalDeviceProperties::pname:deviceType are: |
| |
| include::{generated}/api/enums/VkPhysicalDeviceType.adoc[] |
| |
| * ename:VK_PHYSICAL_DEVICE_TYPE_OTHER - the device does not match any |
| other available types. |
| * ename:VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU - the device is typically |
| one embedded in or tightly coupled with the host. |
| * ename:VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU - the device is typically a |
| separate processor connected to the host via an interlink. |
| * ename:VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU - the device is typically a |
| virtual node in a virtualization environment. |
| * ename:VK_PHYSICAL_DEVICE_TYPE_CPU - the device is typically running on |
| the same processors as the host. |
| |
| The physical device type is advertised for informational purposes only, and |
| does not directly affect the operation of the system. |
| However, the device type may: correlate with other advertised properties or |
| capabilities of the system, such as how many memory heaps there are. |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| [open,refpage='vkGetPhysicalDeviceProperties2',desc='Returns properties of a physical device',type='protos'] |
| -- |
| To query general properties of physical devices once enumerated, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkGetPhysicalDeviceProperties2.adoc[] |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] |
| |
| ifdef::VK_KHR_get_physical_device_properties2[] |
| include::{generated}/api/protos/vkGetPhysicalDeviceProperties2KHR.adoc[] |
| endif::VK_KHR_get_physical_device_properties2[] |
| |
| * pname:physicalDevice is the handle to the physical device whose |
| properties will be queried. |
| * pname:pProperties is a pointer to a slink:VkPhysicalDeviceProperties2 |
| structure in which properties are returned. |
| |
| Each structure in pname:pProperties and its pname:pNext chain contains |
| members corresponding to implementation-dependent properties, behaviors, or |
| limits. |
| fname:vkGetPhysicalDeviceProperties2 fills in each member to specify the |
| corresponding value for the implementation. |
| |
| include::{generated}/validity/protos/vkGetPhysicalDeviceProperties2.adoc[] |
| -- |
| |
| [open,refpage='VkPhysicalDeviceProperties2',desc='Structure specifying physical device properties',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceProperties2 structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceProperties2.adoc[] |
| |
| ifdef::VK_KHR_get_physical_device_properties2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkPhysicalDeviceProperties2KHR.adoc[] |
| endif::VK_KHR_get_physical_device_properties2[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:properties is a slink:VkPhysicalDeviceProperties structure |
| describing properties of the physical device. |
| This structure is written with the same values as if it were written by |
| flink:vkGetPhysicalDeviceProperties. |
| |
| The pname:pNext chain of this structure is used to extend the structure with |
| properties defined by extensions. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceProperties2.adoc[] |
| -- |
| |
| ifdef::VK_VERSION_1_2[] |
| [open,refpage='VkPhysicalDeviceVulkan11Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.1',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceVulkan11Properties structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceVulkan11Properties.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| |
| :anchor-prefix: |
| include::{chapters}/devsandqueues.adoc[tag=VK_KHR_external_memory_capabilities-properties] |
| * [[{anchor-prefix}limits-subgroup-size]] pname:subgroupSize is the |
| default number of invocations in each subgroup. |
| pname:subgroupSize is at least 1 if any of the physical device's queues |
| support ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT. |
| pname:subgroupSize is a power-of-two. |
| * [[{anchor-prefix}limits-subgroupSupportedStages]] |
| pname:subgroupSupportedStages is a bitfield of |
| elink:VkShaderStageFlagBits describing the shader stages that |
| <<shaders-group-operations, group operations>> with |
| <<shaders-scope-subgroup, subgroup scope>> are supported in. |
| pname:subgroupSupportedStages will have the |
| ename:VK_SHADER_STAGE_COMPUTE_BIT bit set if any of the physical |
| device's queues support ename:VK_QUEUE_COMPUTE_BIT. |
| * pname:subgroupSupportedOperations is a bitmask of |
| elink:VkSubgroupFeatureFlagBits specifying the sets of |
| <<shaders-group-operations, group operations>> with |
| <<shaders-scope-subgroup, subgroup scope>> supported on this device. |
| pname:subgroupSupportedOperations will have the |
| ename:VK_SUBGROUP_FEATURE_BASIC_BIT bit set if any of the physical |
| device's queues support ename:VK_QUEUE_GRAPHICS_BIT or |
| ename:VK_QUEUE_COMPUTE_BIT. |
| * [[{anchor-prefix}limits-subgroupQuadOperationsInAllStages]] |
| pname:subgroupQuadOperationsInAllStages is a boolean specifying whether |
| <<shaders-quad-operations,quad group operations>> are available in all |
| stages, or are restricted to fragment and compute stages. |
| include::{chapters}/limits.adoc[tag=VK_KHR_maintenance2-properties] |
| include::{chapters}/limits.adoc[tag=VK_KHR_multiview-properties] |
| include::{chapters}/limits.adoc[tag=VK_KHR_protected_memory-properties] |
| include::{chapters}/limits.adoc[tag=VK_KHR_maintenance3-properties] |
| |
| :refpage: VkPhysicalDeviceVulkan11Properties |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These properties correspond to Vulkan 1.1 functionality. |
| |
| The members of sname:VkPhysicalDeviceVulkan11Properties have the same values |
| as the corresponding members of slink:VkPhysicalDeviceIDProperties, |
| slink:VkPhysicalDeviceSubgroupProperties, |
| slink:VkPhysicalDevicePointClippingProperties, |
| slink:VkPhysicalDeviceMultiviewProperties, |
| slink:VkPhysicalDeviceProtectedMemoryProperties, and |
| slink:VkPhysicalDeviceMaintenance3Properties. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceVulkan11Properties.adoc[] |
| -- |
| |
| [open,refpage='VkPhysicalDeviceVulkan12Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.2',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceVulkan12Properties structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceVulkan12Properties.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| |
| :anchor-prefix: |
| include::{chapters}/devsandqueues.adoc[tag=VK_KHR_driver_properties-properties] |
| include::{chapters}/limits.adoc[tag=VK_KHR_shader_float_controls-properties] |
| include::{chapters}/limits.adoc[tag=VK_EXT_descriptor_indexing-properties] |
| include::{chapters}/limits.adoc[tag=VK_KHR_depth_stencil_resolve-properties] |
| include::{chapters}/limits.adoc[tag=VK_EXT_sampler_filter_minmax-properties] |
| include::{chapters}/limits.adoc[tag=VK_KHR_timeline_semaphore-properties] |
| * [[limits-framebufferIntegerColorSampleCounts]] |
| pname:framebufferIntegerColorSampleCounts is a bitmask of |
| elink:VkSampleCountFlagBits indicating the color sample counts that are |
| supported for all framebuffer color attachments with integer formats. |
| |
| :refpage: VkPhysicalDeviceVulkan12Properties |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These properties correspond to Vulkan 1.2 functionality. |
| |
| The members of sname:VkPhysicalDeviceVulkan12Properties must: have the same |
| values as the corresponding members of |
| slink:VkPhysicalDeviceDriverProperties, |
| slink:VkPhysicalDeviceFloatControlsProperties, |
| slink:VkPhysicalDeviceDescriptorIndexingProperties, |
| slink:VkPhysicalDeviceDepthStencilResolveProperties, |
| slink:VkPhysicalDeviceSamplerFilterMinmaxProperties, and |
| slink:VkPhysicalDeviceTimelineSemaphoreProperties. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceVulkan12Properties.adoc[] |
| -- |
| endif::VK_VERSION_1_2[] |
| |
| ifdef::VKSC_VERSION_1_0[] |
| [open,refpage='VkPhysicalDeviceVulkanSC10Properties',desc='Structure describing safety critical properties supported by an implementation',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceVulkanSC10Properties structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceVulkanSC10Properties.adoc[] |
| |
| :anchor-prefix: |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * [[limits-deviceNoDynamicHostAllocations]] |
| pname:deviceNoDynamicHostAllocations indicates whether the |
| implementation will perform dynamic host memory allocations for physical |
| or logical device commands. |
| If pname:deviceNoDynamicHostAllocations is ename:VK_TRUE the |
| implementation will allocate host memory for objects based on the |
| provided slink:VkDeviceObjectReservationCreateInfo limits during |
| flink:vkCreateDevice. |
| Under valid API usage, ename:VK_ERROR_OUT_OF_HOST_MEMORY may: only be |
| returned by commands which do not explicitly disallow it. |
| * [[limits-deviceDestroyFreesMemory]] pname:deviceDestroyFreesMemory |
| indicates whether destroying the device frees all memory resources back |
| to the system. |
| * [[limits-commandPoolMultipleCommandBuffersRecording]] |
| pname:commandPoolMultipleCommandBuffersRecording indicates whether |
| multiple command buffers from the same command pool can: be in the |
| <<commandbuffers-lifecycle, recording state>> at the same time. |
| * [[limits-commandPoolResetCommandBuffer]] |
| pname:commandPoolResetCommandBuffer indicates whether command buffers |
| support flink:vkResetCommandBuffer, and flink:vkBeginCommandBuffer when |
| not in the <<commandbuffers-lifecycle, initial state>>. |
| * [[limits-commandBufferSimultaneousUse]] |
| pname:commandBufferSimultaneousUse indicates whether command buffers |
| support ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT. |
| * [[limits-secondaryCommandBufferNullOrImagelessFramebuffer]] |
| pname:secondaryCommandBufferNullOrImagelessFramebuffer indicates whether |
| the pname:framebuffer member of sname:VkCommandBufferInheritanceInfo |
| may: be equal to dlink:VK_NULL_HANDLE or be created with a |
| slink:VkFramebufferCreateInfo::pname:flags value that includes |
| ename:VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT if the command buffer will be |
| executed within a render pass instance. |
| * [[limits-recycleDescriptorSetMemory]] pname:recycleDescriptorSetMemory |
| indicates whether descriptor pools are able to immediately reuse pool |
| memory from descriptor sets that have been freed. |
| If this is ename:VK_FALSE, then memory may: only be reallocated after |
| flink:vkResetDescriptorPool is called. |
| * [[limits-recyclePipelineMemory]] pname:recyclePipelineMemory indicates |
| whether the memory for a pipeline is available for reuse by new |
| pipelines after the pipeline is destroyed. |
| * [[limits-maxRenderPassSubpasses]] pname:maxRenderPassSubpasses is the |
| maximum number of subpasses in a render pass. |
| * [[limits-maxRenderPassDependencies]] pname:maxRenderPassDependencies is |
| the maximum number of dependencies in a render pass. |
| * [[limits-maxSubpassInputAttachments]] pname:maxSubpassInputAttachments |
| is the maximum number of input attachments in a subpass. |
| * [[limits-maxSubpassPreserveAttachments]] |
| pname:maxSubpassPreserveAttachments is the maximum number of preserve |
| attachments in a subpass. |
| * [[limits-maxFramebufferAttachments]] pname:maxFramebufferAttachments is |
| the maximum number of attachments in a framebuffer, as well as the |
| maximum number of attachments in a render pass. |
| * [[limits-maxDescriptorSetLayoutBindings]] |
| pname:maxDescriptorSetLayoutBindings is the maximum number of bindings |
| in a descriptor set layout. |
| * [[limits-maxQueryFaultCount]] pname:maxQueryFaultCount is the maximum |
| number of faults that the implementation can: record, to be reported via |
| flink:vkGetFaultData. |
| * [[limits-maxCallbackFaultCount]] pname:maxCallbackFaultCount is the |
| maximum number of faults that the implementation can: report via a |
| single call to tlink:PFN_vkFaultCallbackFunction. |
| * [[limits-maxCommandPoolCommandBuffers]] |
| pname:maxCommandPoolCommandBuffers is the maximum number of command |
| buffers that can: be allocated from a single command pool. |
| * [[limits-maxCommandBufferSize]] pname:maxCommandBufferSize is the |
| maximum supported size of a single command buffer in bytes. |
| Applications can: use flink:vkGetCommandPoolMemoryConsumption to compare |
| a command buffer's current memory usage to this limit. |
| |
| [NOTE] |
| .Note |
| ==== |
| Implementations that do not have a fixed upper bound on the number of |
| command buffers that may: be allocated from a command pool can: report |
| 0xFFFFFFFFU for pname:maxCommandPoolCommandBuffers. |
| |
| Implementations that do not have a fixed upper bound on the command buffer |
| size can: report code:UINT64_MAX for pname:maxCommandBufferSize. |
| ==== |
| |
| :refpage: VkPhysicalDeviceVulkanSC10Properties |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These properties correspond to Vulkan SC 1.0 functionality. |
| |
| ifdef::hidden[] |
| // tag::scaddition[] |
| * slink:VkPhysicalDeviceVulkanSC10Properties <<SCID-1>> |
| // end::scaddition[] |
| endif::hidden[] |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceVulkanSC10Properties.adoc[] |
| -- |
| endif::VKSC_VERSION_1_0[] |
| |
| ifdef::VK_VERSION_1_3[] |
| [open,refpage='VkPhysicalDeviceVulkan13Properties',desc='Structure specifying physical device properties for functionality promoted to Vulkan 1.3',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceVulkan13Properties structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceVulkan13Properties.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| |
| :anchor-prefix: |
| include::{chapters}/limits.adoc[tag=VK_EXT_subgroup_size_control-properties] |
| include::{chapters}/limits.adoc[tag=VK_EXT_inline_uniform_block-properties] |
| * [[{anchor-prefix}limits-maxInlineUniformTotalSize]] |
| pname:maxInlineUniformTotalSize is the maximum total size in bytes of |
| all inline uniform block bindings, across all pipeline shader stages and |
| descriptor set numbers, that can: be included in a pipeline layout. |
| Descriptor bindings with a descriptor type of |
| ename:VK_DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK count against this limit. |
| include::{chapters}/devsandqueues.adoc[tag=VK_KHR_shader_integer_dot_product-properties] |
| include::{chapters}/limits.adoc[tag=VK_EXT_texel_buffer_alignment-properties] |
| include::{chapters}/limits.adoc[tag=VK_KHR_maintenance4-properties] |
| |
| :refpage: VkPhysicalDeviceVulkan13Properties |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These properties correspond to Vulkan 1.3 functionality. |
| |
| The members of sname:VkPhysicalDeviceVulkan13Properties must: have the same |
| values as the corresponding members of |
| slink:VkPhysicalDeviceInlineUniformBlockProperties and |
| slink:VkPhysicalDeviceSubgroupSizeControlProperties. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceVulkan13Properties.adoc[] |
| -- |
| endif::VK_VERSION_1_3[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] |
| [open,refpage='VkPhysicalDeviceIDProperties',desc='Structure specifying IDs related to the physical device',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceIDProperties structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceIDProperties.adoc[] |
| |
| ifdef::VK_KHR_external_memory_capabilities[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkPhysicalDeviceIDPropertiesKHR.adoc[] |
| endif::VK_KHR_external_memory_capabilities[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| |
| // Must have preceding whitespace |
| ifdef::VK_VERSION_1_2[:anchor-prefix: extension-] |
| ifndef::VK_VERSION_1_2[:anchor-prefix:] |
| // tag::VK_KHR_external_memory_capabilities-properties[] |
| * pname:deviceUUID is an array of ename:VK_UUID_SIZE code:uint8_t values |
| representing a universally unique identifier for the device. |
| * pname:driverUUID is an array of ename:VK_UUID_SIZE code:uint8_t values |
| representing a universally unique identifier for the driver build in use |
| by the device. |
| * pname:deviceLUID is an array of ename:VK_LUID_SIZE code:uint8_t values |
| representing a locally unique identifier for the device. |
| * pname:deviceNodeMask is a code:uint32_t bitfield identifying the node |
| within a linked device adapter corresponding to the device. |
| * pname:deviceLUIDValid is a boolean value that will be ename:VK_TRUE if |
| pname:deviceLUID contains a valid LUID and pname:deviceNodeMask contains |
| a valid node mask, and ename:VK_FALSE if they do not. |
| // end::VK_KHR_external_memory_capabilities-properties[] |
| |
| :refpage: VkPhysicalDeviceIDProperties |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| pname:deviceUUID must: be immutable for a given device across instances, |
| processes, driver APIs, driver versions, and system reboots. |
| |
| Applications can: compare the pname:driverUUID value across instance and |
| process boundaries, and can: make similar queries in external APIs to |
| determine whether they are capable of sharing memory objects and resources |
| using them with the device. |
| |
| pname:deviceUUID and/or pname:driverUUID must: be used to determine whether |
| a particular external object can be shared between driver components, where |
| such a restriction exists as defined in the compatibility table for the |
| particular object type: |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] |
| * <<external-memory-handle-types-compatibility,External memory handle |
| types compatibility>> |
| endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] |
| * <<external-semaphore-handle-types-compatibility,External semaphore |
| handle types compatibility>> |
| endif::VK_VERSION_1_1,VK_KHR_external_semaphore_capabilities[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] |
| * <<external-fence-handle-types-compatibility,External fence handle types |
| compatibility>> |
| endif::VK_VERSION_1_1,VK_KHR_external_fence_capabilities[] |
| |
| If pname:deviceLUIDValid is ename:VK_FALSE, the values of pname:deviceLUID |
| and pname:deviceNodeMask are undefined:. |
| If pname:deviceLUIDValid is ename:VK_TRUE and Vulkan is running on the |
| Windows operating system, the contents of pname:deviceLUID can: be cast to |
| an code:LUID object and must: be equal to the locally unique identifier of a |
| code:IDXGIAdapter1 object that corresponds to pname:physicalDevice. |
| If pname:deviceLUIDValid is ename:VK_TRUE, pname:deviceNodeMask must: |
| contain exactly one bit. |
| If Vulkan is running on an operating system that supports the Direct3D 12 |
| API and pname:physicalDevice corresponds to an individual device in a linked |
| device adapter, pname:deviceNodeMask identifies the Direct3D 12 node |
| corresponding to pname:physicalDevice. |
| Otherwise, pname:deviceNodeMask must: be `1`. |
| |
| [NOTE] |
| .Note |
| ==== |
| Although they have identical descriptions, |
| slink:VkPhysicalDeviceIDProperties::pname:deviceUUID may differ from |
| slink:VkPhysicalDeviceProperties2::pname:pipelineCacheUUID. |
| The former is intended to identify and correlate devices across API and |
| driver boundaries, while the latter is used to identify a compatible device |
| and driver combination to use when serializing and de-serializing pipeline |
| state. |
| |
| Implementations should: return pname:deviceUUID values which are likely to |
| be unique even in the presence of multiple Vulkan implementations (such as a |
| GPU driver and a software renderer; two drivers for different GPUs; or the |
| same Vulkan driver running on two logically different devices). |
| |
| Khronos' conformance testing is unable to guarantee that pname:deviceUUID |
| values are actually unique, so implementors should: make their own best |
| efforts to ensure this. |
| In particular, hard-coded pname:deviceUUID values, especially all-`0` bits, |
| should: never be used. |
| |
| A combination of values unique to the vendor, the driver, and the hardware |
| environment can be used to provide a pname:deviceUUID which is unique to a |
| high degree of certainty. |
| Some possible inputs to such a computation are: |
| |
| * Information reported by flink:vkGetPhysicalDeviceProperties |
| * PCI device ID (if defined) |
| * PCI bus ID, or similar system configuration information. |
| * Driver binary checksums. |
| ==== |
| |
| |
| [NOTE] |
| .Note |
| ==== |
| While slink:VkPhysicalDeviceIDProperties::pname:deviceUUID is specified to |
| remain consistent across driver versions and system reboots, it is not |
| intended to be usable as a serializable persistent identifier for a device. |
| It may change when a device is physically added to, removed from, or moved |
| to a different connector in a system while that system is powered down. |
| Further, there is no reasonable way to verify with conformance testing that |
| a given device retains the same UUID in a given system across all driver |
| versions supported in that system. |
| While implementations should make every effort to report consistent device |
| UUIDs across driver versions, applications should avoid relying on the |
| persistence of this value for uses other than identifying compatible devices |
| for external object sharing purposes. |
| ==== |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceIDProperties.adoc[] |
| -- |
| |
| [open,refpage='VK_UUID_SIZE',desc='Length of a universally unique device or driver build identifier',type='consts'] |
| -- |
| ename:VK_UUID_SIZE is the length in code:uint8_t values of an array |
| containing a universally unique device or driver build identifier, as |
| returned in slink:VkPhysicalDeviceIDProperties::pname:deviceUUID and |
| slink:VkPhysicalDeviceIDProperties::pname:driverUUID. |
| |
| include::{generated}/api/enums/VK_UUID_SIZE.adoc[] |
| -- |
| |
| [open,refpage='VK_LUID_SIZE',desc='Length of a locally unique device identifier',type='consts',alias='VK_LUID_SIZE_KHR'] |
| -- |
| ename:VK_LUID_SIZE is the length in code:uint8_t values of an array |
| containing a locally unique device identifier, as returned in |
| slink:VkPhysicalDeviceIDProperties::pname:deviceLUID. |
| |
| include::{generated}/api/enums/VK_LUID_SIZE.adoc[] |
| |
| ifdef::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VK_LUID_SIZE_KHR.adoc[] |
| endif::VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities,VK_KHR_external_semaphore_capabilities,VK_KHR_external_fence_capabilities[] |
| |
| ifdef::VK_VERSION_1_2,VK_KHR_driver_properties[] |
| [open,refpage='VkPhysicalDeviceDriverProperties',desc='Structure containing driver identification information',type='structs',alias='VkPhysicalDeviceDriverPropertiesKHR'] |
| -- |
| The sname:VkPhysicalDeviceDriverProperties structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceDriverProperties.adoc[] |
| |
| ifdef::VK_KHR_driver_properties[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkPhysicalDeviceDriverPropertiesKHR.adoc[] |
| endif::VK_KHR_driver_properties[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| |
| // Must have preceding whitespace |
| ifdef::VK_VERSION_1_2[:anchor-prefix: extension-] |
| ifndef::VK_VERSION_1_2[:anchor-prefix:] |
| // tag::VK_KHR_driver_properties-properties[] |
| * pname:driverID is a unique identifier for the driver of the physical |
| device. |
| * pname:driverName is an array of ename:VK_MAX_DRIVER_NAME_SIZE code:char |
| containing a null-terminated UTF-8 string which is the name of the |
| driver. |
| * pname:driverInfo is an array of ename:VK_MAX_DRIVER_INFO_SIZE code:char |
| containing a null-terminated UTF-8 string with additional information |
| about the driver. |
| * pname:conformanceVersion is the version of the Vulkan conformance test |
| this driver is conformant against (see slink:VkConformanceVersion). |
| // end::VK_KHR_driver_properties-properties[] |
| |
| :refpage: VkPhysicalDeviceDriverProperties |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These are properties of the driver corresponding to a physical device. |
| |
| pname:driverID must: be immutable for a given driver across instances, |
| processes, driver versions, and system reboots. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceDriverProperties.adoc[] |
| -- |
| |
| [open,refpage='VkDriverId',desc='Khronos driver IDs',type='enums',alias='VkDriverIdKHR'] |
| -- |
| Khronos driver IDs which may: be returned in |
| slink:VkPhysicalDeviceDriverProperties::pname:driverID are: |
| |
| include::{generated}/api/enums/VkDriverId.adoc[] |
| |
| ifdef::VK_KHR_driver_properties[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkDriverIdKHR.adoc[] |
| endif::VK_KHR_driver_properties[] |
| |
| [NOTE] |
| .Note |
| ==== |
| Khronos driver IDs may be allocated by vendors at any time. |
| There may be multiple driver IDs for the same vendor, representing different |
| drivers (for e.g. different platforms, proprietary or open source, etc.). |
| Only the latest canonical versions of this Specification, of the |
| corresponding `vk.xml` API Registry, and of the corresponding |
| `{core_header}` header file must: contain all reserved Khronos driver IDs. |
| |
| Only driver IDs registered with Khronos are given symbolic names. |
| There may: be unregistered driver IDs returned. |
| ==== |
| -- |
| |
| [open,refpage='VK_MAX_DRIVER_NAME_SIZE',desc='Maximum length of a physical device driver name string',type='consts',alias='VK_MAX_DRIVER_NAME_SIZE_KHR'] |
| -- |
| ename:VK_MAX_DRIVER_NAME_SIZE is the length in code:char values of an array |
| containing a driver name string, as returned in |
| slink:VkPhysicalDeviceDriverProperties::pname:driverName. |
| |
| include::{generated}/api/enums/VK_MAX_DRIVER_NAME_SIZE.adoc[] |
| |
| ifdef::VK_KHR_driver_properties[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VK_MAX_DRIVER_NAME_SIZE_KHR.adoc[] |
| endif::VK_KHR_driver_properties[] |
| -- |
| |
| [open,refpage='VK_MAX_DRIVER_INFO_SIZE',desc='Length of a physical device driver information string',type='consts',alias='VK_MAX_DRIVER_INFO_SIZE_KHR'] |
| -- |
| ename:VK_MAX_DRIVER_INFO_SIZE is the length in code:char values of an array |
| containing a driver information string, as returned in |
| slink:VkPhysicalDeviceDriverProperties::pname:driverInfo. |
| |
| include::{generated}/api/enums/VK_MAX_DRIVER_INFO_SIZE.adoc[] |
| |
| ifdef::VK_KHR_driver_properties[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VK_MAX_DRIVER_INFO_SIZE_KHR.adoc[] |
| endif::VK_KHR_driver_properties[] |
| -- |
| |
| [open,refpage='VkConformanceVersion',desc='Structure containing the conformance test suite version the implementation is compliant with',type='structs',alias='VkConformanceVersionKHR'] |
| -- |
| The conformance test suite version an implementation is compliant with is |
| described with the sname:VkConformanceVersion structure: |
| |
| include::{generated}/api/structs/VkConformanceVersion.adoc[] |
| |
| ifdef::VK_KHR_driver_properties[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkConformanceVersionKHR.adoc[] |
| endif::VK_KHR_driver_properties[] |
| |
| * pname:major is the major version number of the conformance test suite. |
| * pname:minor is the minor version number of the conformance test suite. |
| * pname:subminor is the subminor version number of the conformance test |
| suite. |
| * pname:patch is the patch version number of the conformance test suite. |
| |
| include::{generated}/validity/structs/VkConformanceVersion.adoc[] |
| -- |
| endif::VK_VERSION_1_2,VK_KHR_driver_properties[] |
| |
| ifdef::VK_EXT_pci_bus_info[] |
| [open,refpage='VkPhysicalDevicePCIBusInfoPropertiesEXT',desc='Structure containing PCI bus information of a physical device',type='structs'] |
| -- |
| The sname:VkPhysicalDevicePCIBusInfoPropertiesEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDevicePCIBusInfoPropertiesEXT.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:pciDomain is the PCI bus domain. |
| * pname:pciBus is the PCI bus identifier. |
| * pname:pciDevice is the PCI device identifier. |
| * pname:pciFunction is the PCI device function identifier. |
| |
| :refpage: VkPhysicalDevicePCIBusInfoPropertiesEXT |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These are properties of the PCI bus information of a physical device. |
| |
| include::{generated}/validity/structs/VkPhysicalDevicePCIBusInfoPropertiesEXT.adoc[] |
| -- |
| endif::VK_EXT_pci_bus_info[] |
| |
| ifdef::VK_EXT_physical_device_drm[] |
| [open,refpage='VkPhysicalDeviceDrmPropertiesEXT',desc='Structure containing DRM information of a physical device',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceDrmPropertiesEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceDrmPropertiesEXT.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:hasPrimary is a boolean indicating whether the physical device has |
| a DRM primary node. |
| * pname:hasRender is a boolean indicating whether the physical device has |
| a DRM render node. |
| * pname:primaryMajor is the DRM primary node major number, if any. |
| * pname:primaryMinor is the DRM primary node minor number, if any. |
| * pname:renderMajor is the DRM render node major number, if any. |
| * pname:renderMinor is the DRM render node minor number, if any. |
| |
| :refpage: VkPhysicalDeviceDrmPropertiesEXT |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These are properties of the DRM information of a physical device. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceDrmPropertiesEXT.adoc[] |
| -- |
| endif::VK_EXT_physical_device_drm[] |
| endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| |
| ifdef::VK_VERSION_1_3,VK_KHR_shader_integer_dot_product[] |
| [open,refpage='VkPhysicalDeviceShaderIntegerDotProductProperties',desc='Structure containing information about integer dot product support for a physical device',type='structs',alias='VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR'] |
| -- |
| The sname:VkPhysicalDeviceShaderIntegerDotProductProperties structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceShaderIntegerDotProductProperties.adoc[] |
| |
| ifdef::VK_KHR_shader_integer_dot_product[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkPhysicalDeviceShaderIntegerDotProductPropertiesKHR.adoc[] |
| endif::VK_KHR_shader_integer_dot_product[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| |
| // Must have preceding whitespace |
| ifdef::VK_VERSION_1_3[:anchor-prefix: extension-] |
| ifndef::VK_VERSION_1_3[:anchor-prefix:] |
| // NOTE: none of these properties currently have anchors, so the |
| // {anchor-prefix} is not used in the property descriptions. |
| // tag::VK_KHR_shader_integer_dot_product-properties[] |
| * pname:integerDotProduct8BitUnsignedAccelerated is a boolean that will be |
| ename:VK_TRUE if the support for 8-bit unsigned dot product operations |
| using the code:OpUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct8BitSignedAccelerated is a boolean that will be |
| ename:VK_TRUE if the support for 8-bit signed dot product operations |
| using the code:OpSDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct8BitMixedSignednessAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 8-bit mixed signedness dot |
| product operations using the code:OpSUDotKHR SPIR-V instruction is |
| accelerated <<devsandqueues-integer-dot-product-accelerated,as defined |
| below>>. |
| * pname:integerDotProduct4x8BitPackedUnsignedAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 8-bit unsigned dot product |
| operations from operands packed into 32-bit integers using the |
| code:OpUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct4x8BitPackedSignedAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 8-bit signed dot product |
| operations from operands packed into 32-bit integers using the |
| code:OpSDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct4x8BitPackedMixedSignednessAccelerated is a |
| boolean that will be ename:VK_TRUE if the support for 8-bit mixed |
| signedness dot product operations from operands packed into 32-bit |
| integers using the code:OpSUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct16BitUnsignedAccelerated is a boolean that will |
| be ename:VK_TRUE if the support for 16-bit unsigned dot product |
| operations using the code:OpUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct16BitSignedAccelerated is a boolean that will be |
| ename:VK_TRUE if the support for 16-bit signed dot product operations |
| using the code:OpSDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct16BitMixedSignednessAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 16-bit mixed signedness dot |
| product operations using the code:OpSUDotKHR SPIR-V instruction is |
| accelerated <<devsandqueues-integer-dot-product-accelerated,as defined |
| below>>. |
| * pname:integerDotProduct32BitUnsignedAccelerated is a boolean that will |
| be ename:VK_TRUE if the support for 32-bit unsigned dot product |
| operations using the code:OpUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct32BitSignedAccelerated is a boolean that will be |
| ename:VK_TRUE if the support for 32-bit signed dot product operations |
| using the code:OpSDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct32BitMixedSignednessAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 32-bit mixed signedness dot |
| product operations using the code:OpSUDotKHR SPIR-V instruction is |
| accelerated <<devsandqueues-integer-dot-product-accelerated,as defined |
| below>>. |
| * pname:integerDotProduct64BitUnsignedAccelerated is a boolean that will |
| be ename:VK_TRUE if the support for 64-bit unsigned dot product |
| operations using the code:OpUDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct64BitSignedAccelerated is a boolean that will be |
| ename:VK_TRUE if the support for 64-bit signed dot product operations |
| using the code:OpSDotKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProduct64BitMixedSignednessAccelerated is a boolean that |
| will be ename:VK_TRUE if the support for 64-bit mixed signedness dot |
| product operations using the code:OpSUDotKHR SPIR-V instruction is |
| accelerated <<devsandqueues-integer-dot-product-accelerated,as defined |
| below>>. |
| * pname:integerDotProductAccumulatingSaturating8BitUnsignedAccelerated is |
| a boolean that will be ename:VK_TRUE if the support for 8-bit unsigned |
| accumulating saturating dot product operations using the |
| code:OpUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating8BitSignedAccelerated is a |
| boolean that will be ename:VK_TRUE if the support for 8-bit signed |
| accumulating saturating dot product operations using the |
| code:OpSDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating8BitMixedSignednessAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 8-bit mixed |
| signedness accumulating saturating dot product operations using the |
| code:OpSUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating4x8BitPackedUnsignedAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 8-bit |
| unsigned accumulating saturating dot product operations from operands |
| packed into 32-bit integers using the code:OpUDotAccSatKHR SPIR-V |
| instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating4x8BitPackedSignedAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 8-bit signed |
| accumulating saturating dot product operations from operands packed into |
| 32-bit integers using the code:OpSDotAccSatKHR SPIR-V instruction is |
| accelerated <<devsandqueues-integer-dot-product-accelerated,as defined |
| below>>. |
| * pname:integerDotProductAccumulatingSaturating4x8BitPackedMixedSignednessAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 8-bit mixed |
| signedness accumulating saturating dot product operations from operands |
| packed into 32-bit integers using the code:OpSUDotAccSatKHR SPIR-V |
| instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating16BitUnsignedAccelerated is |
| a boolean that will be ename:VK_TRUE if the support for 16-bit unsigned |
| accumulating saturating dot product operations using the |
| code:OpUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating16BitSignedAccelerated is a |
| boolean that will be ename:VK_TRUE if the support for 16-bit signed |
| accumulating saturating dot product operations using the |
| code:OpSDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating16BitMixedSignednessAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 16-bit mixed |
| signedness accumulating saturating dot product operations using the |
| code:OpSUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating32BitUnsignedAccelerated is |
| a boolean that will be ename:VK_TRUE if the support for 32-bit unsigned |
| accumulating saturating dot product operations using the |
| code:OpUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating32BitSignedAccelerated is a |
| boolean that will be ename:VK_TRUE if the support for 32-bit signed |
| accumulating saturating dot product operations using the |
| code:OpSDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating32BitMixedSignednessAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 32-bit mixed |
| signedness accumulating saturating dot product operations using the |
| code:OpSUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating64BitUnsignedAccelerated is |
| a boolean that will be ename:VK_TRUE if the support for 64-bit unsigned |
| accumulating saturating dot product operations using the |
| code:OpUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating64BitSignedAccelerated is a |
| boolean that will be ename:VK_TRUE if the support for 64-bit signed |
| accumulating saturating dot product operations using the |
| code:OpSDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| * pname:integerDotProductAccumulatingSaturating64BitMixedSignednessAccelerated |
| is a boolean that will be ename:VK_TRUE if the support for 64-bit mixed |
| signedness accumulating saturating dot product operations using the |
| code:OpSUDotAccSatKHR SPIR-V instruction is accelerated |
| <<devsandqueues-integer-dot-product-accelerated,as defined below>>. |
| // end::VK_KHR_shader_integer_dot_product-properties[] |
| |
| :refpage: VkPhysicalDeviceShaderIntegerDotProductProperties |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These are properties of the integer dot product acceleration information of |
| a physical device. |
| |
| [[devsandqueues-integer-dot-product-accelerated]] |
| [NOTE] |
| .Note |
| ==== |
| A dot product operation is deemed accelerated if its implementation provides |
| a performance advantage over application-provided code composed from |
| elementary instructions and/or other dot product instructions, either |
| because the implementation uses optimized machine code sequences whose |
| generation from application-provided code cannot be guaranteed or because it |
| uses hardware features that cannot otherwise be targeted from |
| application-provided code. |
| ==== |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceShaderIntegerDotProductProperties.adoc[] |
| -- |
| endif::VK_VERSION_1_3,VK_KHR_shader_integer_dot_product[] |
| |
| ifdef::VK_QCOM_image_processing[] |
| [open,refpage='VkPhysicalDeviceImageProcessingPropertiesQCOM',desc='Structure containing image processing properties',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceImageProcessingPropertiesQCOM structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceImageProcessingPropertiesQCOM.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * [[limits-weightfilter-phases]] pname:maxWeightFilterPhases is the |
| maximum value that can: be specified for |
| slink:VkImageViewSampleWeightCreateInfoQCOM::pname:numPhases in |
| <<textures-weightimage-filterphases, weight image sampling>> operations. |
| * [[limits-weightfilter-maxdimension]] pname:maxWeightFilterDimension is a |
| slink:VkExtent2D describing the largest dimensions (pname:width and |
| pname:height) that can: be specified for |
| slink:VkImageViewSampleWeightCreateInfoQCOM::pname:filterSize. |
| * [[limits-blockmatch-maxblocksize]] pname:maxBlockMatchRegion is a |
| slink:VkExtent2D describing the largest dimensions (pname:width and |
| pname:height) that can: be specified for code:blockSize in |
| <<textures-blockmatch,block matching>> operations. |
| * [[limits-boxfilter-maxblocksize]] pname:maxBoxFilterBlockSize is a |
| slink:VkExtent2D describing the maximum dimensions (pname:width and |
| pname:height) that can: be specified for code:blocksize in |
| <<textures-boxfilter,box filter sampling>> operations. |
| |
| :refpage: VkPhysicalDeviceImageProcessingPropertiesQCOM |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These are properties of the image processing information of a physical |
| device. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceImageProcessingPropertiesQCOM.adoc[] |
| -- |
| endif::VK_QCOM_image_processing[] |
| |
| ifdef::VK_EXT_shader_tile_image[] |
| [open,refpage='VkPhysicalDeviceShaderTileImagePropertiesEXT',desc='Structure containing information about tile image support for a physical device',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceShaderTileImagePropertiesEXT structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceShaderTileImagePropertiesEXT.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:shaderTileImageCoherentReadAccelerated is a boolean that will be |
| ename:VK_TRUE if coherent reads of tile image data is accelerated. |
| * pname:shaderTileImageReadSampleFromPixelRateInvocation is a boolean that |
| will be ename:VK_TRUE if reading from samples from a pixel rate fragment |
| invocation is supported when |
| slink:VkPipelineMultisampleStateCreateInfo::pname:rasterizationSamples > 1. |
| * pname:shaderTileImageReadFromHelperInvocation is a boolean that will be |
| ename:VK_TRUE if reads of tile image data from helper fragment |
| invocations result in valid values. |
| |
| :refpage: VkPhysicalDeviceShaderTileImagePropertiesEXT |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These are properties of the tile image information of a physical device. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceShaderTileImagePropertiesEXT.adoc[] |
| -- |
| endif::VK_EXT_shader_tile_image[] |
| |
| ifdef::VK_QCOM_image_processing2[] |
| [open,refpage='VkPhysicalDeviceImageProcessing2PropertiesQCOM',desc='Structure containing image processing2 properties',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceImageProcessing2PropertiesQCOM structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceImageProcessing2PropertiesQCOM.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| |
| * [[limits-blockmatch-maxWindowExtent]] pname:maxBlockMatchWindow is a |
| slink:VkExtent2D describing the largest dimensions (pname:width and |
| pname:height) that can: be specified for the block match window. |
| |
| :refpage: VkPhysicalDeviceImageProcessing2PropertiesQCOM |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| These are properties of the image processing2 information of a physical |
| device. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceImageProcessing2PropertiesQCOM.adoc[] |
| -- |
| endif::VK_QCOM_image_processing2[] |
| |
| ifdef::VK_MSFT_layered_driver[] |
| [open,refpage='VkPhysicalDeviceLayeredDriverPropertiesMSFT',desc='Structure containing information about driver layering for a physical device',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceLayeredDriverPropertiesMSFT structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceLayeredDriverPropertiesMSFT.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:underlyingAPI is a elink:VkLayeredDriverUnderlyingApiMSFT value |
| indicating which underlying API is used to implement the layered driver, |
| or ename:VK_LAYERED_DRIVER_UNDERLYING_API_NONE_MSFT if the driver is not |
| layered. |
| |
| These are properties of the driver layering information of a physical |
| device. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceLayeredDriverPropertiesMSFT.adoc[] |
| -- |
| |
| [open,refpage='VkLayeredDriverUnderlyingApiMSFT',desc='Layered driver underlying APIs',type='enums'] |
| -- |
| Underlying APIs which may: be returned in |
| slink:VkPhysicalDeviceLayeredDriverPropertiesMSFT::pname:underlyingAPI are: |
| |
| include::{generated}/api/enums/VkLayeredDriverUnderlyingApiMSFT.adoc[] |
| -- |
| endif::VK_MSFT_layered_driver[] |
| |
| ifdef::VK_ARM_scheduling_controls[] |
| [open,refpage='VkPhysicalDeviceSchedulingControlsPropertiesARM',desc='Structure containing scheduling control properties of a physical device',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceSchedulingControlsPropertiesARM structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceSchedulingControlsPropertiesARM.adoc[] |
| |
| * [[limits-schedulingControlsFlags]]pname:schedulingControlsFlags |
| specifies the specific scheduling controls that a physical device |
| supports. |
| |
| :refpage: VkPhysicalDeviceSchedulingControlsPropertiesARM |
| include::{chapters}/limits.adoc[tag=limits_desc] |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceSchedulingControlsPropertiesARM.adoc[] |
| -- |
| |
| [open,refpage='VkPhysicalDeviceSchedulingControlsFlagBitsARM',desc='Bitmask specifying scheduling controls supported by a physical device',type='enums'] |
| -- |
| Bits which can: be set in |
| slink:VkPhysicalDeviceSchedulingControlsPropertiesARM::pname:schedulingControlsFlags, |
| specifying supported scheduling controls, are: |
| |
| include::{generated}/api/enums/VkPhysicalDeviceSchedulingControlsFlagBitsARM.adoc[] |
| |
| * ename:VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM |
| indicates that a slink:VkDeviceQueueShaderCoreControlCreateInfoARM |
| structure may: be included in the pname:pNext chain of a |
| slink:VkDeviceQueueCreateInfo or slink:VkDeviceCreateInfo structure. |
| -- |
| |
| [open,refpage='VkPhysicalDeviceSchedulingControlsFlagsARM',desc='Bitmask of VkPhysicalDeviceSchedulingControlsFlagBitsARM',type='flags'] |
| -- |
| include::{generated}/api/flags/VkPhysicalDeviceSchedulingControlsFlagsARM.adoc[] |
| |
| tname:VkPhysicalDeviceSchedulingControlsFlagsARM is a bitmask type for |
| setting a mask of zero or more |
| elink:VkPhysicalDeviceSchedulingControlsFlagBitsARM. |
| -- |
| endif::VK_ARM_scheduling_controls[] |
| |
| [open,refpage='vkGetPhysicalDeviceQueueFamilyProperties',desc='Reports properties of the queues of the specified physical device',type='protos'] |
| -- |
| To query properties of queues available on a physical device, call: |
| |
| include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties.adoc[] |
| |
| * pname:physicalDevice is the handle to the physical device whose |
| properties will be queried. |
| * pname:pQueueFamilyPropertyCount is a pointer to an integer related to |
| the number of queue families available or queried, as described below. |
| * pname:pQueueFamilyProperties is either `NULL` or a pointer to an array |
| of slink:VkQueueFamilyProperties structures. |
| |
| If pname:pQueueFamilyProperties is `NULL`, then the number of queue families |
| available is returned in pname:pQueueFamilyPropertyCount. |
| Implementations must: support at least one queue family. |
| Otherwise, pname:pQueueFamilyPropertyCount must: point to a variable set by |
| the user to the number of elements in the pname:pQueueFamilyProperties |
| array, and on return the variable is overwritten with the number of |
| structures actually written to pname:pQueueFamilyProperties. |
| If pname:pQueueFamilyPropertyCount is less than the number of queue families |
| available, at most pname:pQueueFamilyPropertyCount structures will be |
| written. |
| |
| include::{generated}/validity/protos/vkGetPhysicalDeviceQueueFamilyProperties.adoc[] |
| -- |
| |
| [open,refpage='VkQueueFamilyProperties',desc='Structure providing information about a queue family',type='structs'] |
| -- |
| The sname:VkQueueFamilyProperties structure is defined as: |
| |
| include::{generated}/api/structs/VkQueueFamilyProperties.adoc[] |
| |
| * pname:queueFlags is a bitmask of elink:VkQueueFlagBits indicating |
| capabilities of the queues in this queue family. |
| * pname:queueCount is the unsigned integer count of queues in this queue |
| family. |
| Each queue family must: support at least one queue. |
| * pname:timestampValidBits is the unsigned integer count of meaningful |
| bits in the timestamps written via |
| ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| flink:vkCmdWriteTimestamp2 or |
| endif::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| flink:vkCmdWriteTimestamp. |
| The valid range for the count is 36 to 64 bits, or a value of 0, |
| indicating no support for timestamps. |
| Bits outside the valid range are guaranteed to be zeros. |
| * pname:minImageTransferGranularity is the minimum granularity supported |
| for image transfer operations on the queues in this queue family. |
| |
| The value returned in pname:minImageTransferGranularity has a unit of |
| compressed texel blocks for images having a block-compressed format, and a |
| unit of texels otherwise. |
| |
| Possible values of pname:minImageTransferGranularity are: |
| |
| * [eq]#(0,0,0)# specifies that only whole mip levels must: be transferred |
| using the image transfer operations on the corresponding queues. |
| In this case, the following restrictions apply to all offset and extent |
| parameters of image transfer operations: |
| ** The pname:x, pname:y, and pname:z members of a slink:VkOffset3D |
| parameter must: always be zero. |
| ** The pname:width, pname:height, and pname:depth members of a |
| slink:VkExtent3D parameter must: always match the width, height, and |
| depth of the image subresource corresponding to the parameter, |
| respectively. |
| * [eq]#(A~x~, A~y~, A~z~)# where [eq]#A~x~#, [eq]#A~y~#, and [eq]#A~z~# |
| are all integer powers of two. |
| In this case the following restrictions apply to all image transfer |
| operations: |
| ** pname:x, pname:y, and pname:z of a slink:VkOffset3D parameter must: be |
| integer multiples of [eq]#A~x~#, [eq]#A~y~#, and [eq]#A~z~#, |
| respectively. |
| ** pname:width of a slink:VkExtent3D parameter must: be an integer |
| multiple of [eq]#A~x~#, or else [eq]#pname:x {plus} pname:width# must: |
| equal the width of the image subresource corresponding to the |
| parameter. |
| ** pname:height of a slink:VkExtent3D parameter must: be an integer |
| multiple of [eq]#A~y~#, or else [eq]#pname:y {plus} pname:height# must: |
| equal the height of the image subresource corresponding to the |
| parameter. |
| ** pname:depth of a slink:VkExtent3D parameter must: be an integer |
| multiple of [eq]#A~z~#, or else [eq]#pname:z {plus} pname:depth# must: |
| equal the depth of the image subresource corresponding to the |
| parameter. |
| ** If the format of the image corresponding to the parameters is one of |
| the block-compressed formats then for the purposes of the above |
| calculations the granularity must: be scaled up by the compressed texel |
| block dimensions. |
| |
| Queues supporting graphics and/or compute operations must: report |
| [eq]#(1,1,1)# in pname:minImageTransferGranularity, meaning that there are |
| no additional restrictions on the granularity of image transfer operations |
| for these queues. |
| Other queues supporting image transfer operations are only required: to |
| support whole mip level transfers, thus pname:minImageTransferGranularity |
| for queues belonging to such queue families may: be [eq]#(0,0,0)#. |
| |
| The <<memory-device,Device Memory>> section describes memory properties |
| queried from the physical device. |
| |
| For physical device feature queries see the <<features, Features>> chapter. |
| |
| include::{generated}/validity/structs/VkQueueFamilyProperties.adoc[] |
| -- |
| |
| [open,refpage='VkQueueFlagBits',desc='Bitmask specifying capabilities of queues in a queue family',type='enums'] |
| -- |
| Bits which may: be set in slink:VkQueueFamilyProperties::pname:queueFlags, |
| indicating capabilities of queues in a queue family are: |
| |
| include::{generated}/api/enums/VkQueueFlagBits.adoc[] |
| |
| * ename:VK_QUEUE_GRAPHICS_BIT specifies that queues in this queue family |
| support graphics operations. |
| * ename:VK_QUEUE_COMPUTE_BIT specifies that queues in this queue family |
| support compute operations. |
| * ename:VK_QUEUE_TRANSFER_BIT specifies that queues in this queue family |
| support transfer operations. |
| * ename:VK_QUEUE_SPARSE_BINDING_BIT specifies that queues in this queue |
| family support sparse memory management operations (see |
| <<sparsememory,Sparse Resources>>). |
| If any of the sparse resource features are enabled, then at least one |
| queue family must: support this bit. |
| ifdef::VKSC_VERSION_1_0[] |
| This flag is not supported in Vulkan SC <<SCID-8>>. |
| ifdef::hidden[] |
| // tag::scremoved[] |
| * elink:VkQueueFlagBits |
| ** ename:VK_QUEUE_SPARSE_BINDING_BIT <<SCID-8>> |
| // end::scremoved[] |
| endif::hidden[] |
| endif::VKSC_VERSION_1_0[] |
| ifdef::VK_KHR_video_decode_queue[] |
| * ename:VK_QUEUE_VIDEO_DECODE_BIT_KHR specifies that queues in this queue |
| family support <<video-decode-operations,video decode operations>>. |
| endif::VK_KHR_video_decode_queue[] |
| ifdef::VK_KHR_video_encode_queue[] |
| * ename:VK_QUEUE_VIDEO_ENCODE_BIT_KHR specifies that queues in this queue |
| family support <<video-encode-operations,video encode operations>>. |
| endif::VK_KHR_video_encode_queue[] |
| ifdef::VK_NV_optical_flow[] |
| * ename:VK_QUEUE_OPTICAL_FLOW_BIT_NV specifies that queues in this queue |
| family support optical flow operations. |
| endif::VK_NV_optical_flow[] |
| ifdef::VK_VERSION_1_1[] |
| * ename:VK_QUEUE_PROTECTED_BIT specifies that queues in this queue family |
| support the ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit. |
| (see <<memory-protected-memory,Protected Memory>>). |
| If the physical device supports the <<features-protectedMemory, |
| pname:protectedMemory>> feature, at least one of its queue families |
| must: support this bit. |
| endif::VK_VERSION_1_1[] |
| |
| If an implementation exposes any queue family that supports graphics |
| operations, at least one queue family of at least one physical device |
| exposed by the implementation must: support both graphics and compute |
| operations. |
| |
| ifdef::VK_VERSION_1_1[] |
| Furthermore, if the <<features-protectedMemory, pname:protectedMemory>> |
| physical device feature is supported, then at least one queue family of at |
| least one physical device exposed by the implementation must: support |
| graphics operations, compute operations, and protected memory operations. |
| endif::VK_VERSION_1_1[] |
| |
| [NOTE] |
| .Note |
| ==== |
| All commands that are allowed on a queue that supports transfer operations |
| are also allowed on a queue that supports either graphics or compute |
| operations. |
| Thus, if the capabilities of a queue family include |
| ename:VK_QUEUE_GRAPHICS_BIT or ename:VK_QUEUE_COMPUTE_BIT, then reporting |
| the ename:VK_QUEUE_TRANSFER_BIT capability separately for that queue family |
| is optional:. |
| ==== |
| |
| For further details see <<devsandqueues-queues,Queues>>. |
| -- |
| |
| [open,refpage='VkQueueFlags',desc='Bitmask of VkQueueFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkQueueFlags.adoc[] |
| |
| tname:VkQueueFlags is a bitmask type for setting a mask of zero or more |
| elink:VkQueueFlagBits. |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| [open,refpage='vkGetPhysicalDeviceQueueFamilyProperties2',desc='Reports properties of the queues of the specified physical device',type='protos'] |
| -- |
| To query properties of queues available on a physical device, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties2.adoc[] |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1+VK_KHR_get_physical_device_properties2[or the equivalent command] |
| |
| ifdef::VK_KHR_get_physical_device_properties2[] |
| include::{generated}/api/protos/vkGetPhysicalDeviceQueueFamilyProperties2KHR.adoc[] |
| endif::VK_KHR_get_physical_device_properties2[] |
| |
| * pname:physicalDevice is the handle to the physical device whose |
| properties will be queried. |
| * pname:pQueueFamilyPropertyCount is a pointer to an integer related to |
| the number of queue families available or queried, as described in |
| flink:vkGetPhysicalDeviceQueueFamilyProperties. |
| * pname:pQueueFamilyProperties is either `NULL` or a pointer to an array |
| of slink:VkQueueFamilyProperties2 structures. |
| |
| fname:vkGetPhysicalDeviceQueueFamilyProperties2 behaves similarly to |
| flink:vkGetPhysicalDeviceQueueFamilyProperties, with the ability to return |
| extended information in a pname:pNext chain of output structures. |
| |
| include::{generated}/validity/protos/vkGetPhysicalDeviceQueueFamilyProperties2.adoc[] |
| -- |
| |
| [open,refpage='VkQueueFamilyProperties2',desc='Structure providing information about a queue family',type='structs'] |
| -- |
| The sname:VkQueueFamilyProperties2 structure is defined as: |
| |
| include::{generated}/api/structs/VkQueueFamilyProperties2.adoc[] |
| |
| ifdef::VK_KHR_get_physical_device_properties2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkQueueFamilyProperties2KHR.adoc[] |
| endif::VK_KHR_get_physical_device_properties2[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:queueFamilyProperties is a slink:VkQueueFamilyProperties structure |
| which is populated with the same values as in |
| flink:vkGetPhysicalDeviceQueueFamilyProperties. |
| |
| include::{generated}/validity/structs/VkQueueFamilyProperties2.adoc[] |
| -- |
| |
| ifdef::VK_EXT_global_priority_query,VK_KHR_global_priority[] |
| [open,refpage='VkQueueFamilyGlobalPriorityPropertiesKHR',desc='Return structure for queue family global priority information query',type='structs'] |
| -- |
| The definition of slink:VkQueueFamilyGlobalPriorityPropertiesKHR is: |
| |
| include::{generated}/api/structs/VkQueueFamilyGlobalPriorityPropertiesKHR.adoc[] |
| ifdef::VK_EXT_global_priority_query[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkQueueFamilyGlobalPriorityPropertiesEXT.adoc[] |
| endif::VK_EXT_global_priority_query[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:priorityCount is the number of supported global queue priorities |
| in this queue family, and it must: be greater than 0. |
| * pname:priorities is an array of ename:VK_MAX_GLOBAL_PRIORITY_SIZE_EXT |
| elink:VkQueueGlobalPriorityEXT enums representing all supported global |
| queue priorities in this queue family. |
| The first pname:priorityCount elements of the array will be valid. |
| |
| If the sname:VkQueueFamilyGlobalPriorityPropertiesKHR structure is included |
| in the pname:pNext chain of the slink:VkQueueFamilyProperties2 structure |
| passed to flink:vkGetPhysicalDeviceQueueFamilyProperties2, it is filled in |
| with the list of supported global queue priorities for the indicated family. |
| |
| The valid elements of pname:priorities must: not contain any duplicate |
| values. |
| |
| The valid elements of pname:priorities must: be a continuous sequence of |
| elink:VkQueueGlobalPriorityKHR enums in the ascending order. |
| |
| [NOTE] |
| .Note |
| ==== |
| For example, returning pname:priorityCount as 3 with supported |
| pname:priorities as ename:VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR, |
| ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR and |
| ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR is not allowed. |
| ==== |
| |
| include::{generated}/validity/structs/VkQueueFamilyGlobalPriorityPropertiesKHR.adoc[] |
| -- |
| |
| [open,refpage='VK_MAX_GLOBAL_PRIORITY_SIZE_KHR',desc='Length of an array of global queue priorities',type='consts'] |
| -- |
| ename:VK_MAX_GLOBAL_PRIORITY_SIZE_KHR is the length of an array of |
| elink:VkQueueGlobalPriorityKHR enumerants representing supported queue |
| priorities, as returned in |
| slink:VkQueueFamilyGlobalPriorityPropertiesKHR::pname:priorities. |
| |
| include::{generated}/api/enums/VK_MAX_GLOBAL_PRIORITY_SIZE_KHR.adoc[] |
| |
| ifdef::VK_EXT_global_priority_query[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VK_MAX_GLOBAL_PRIORITY_SIZE_EXT.adoc[] |
| endif::VK_EXT_global_priority_query[] |
| -- |
| endif::VK_EXT_global_priority_query,VK_KHR_global_priority[] |
| |
| ifdef::VK_NV_device_diagnostic_checkpoints[] |
| include::{chapters}/VK_NV_device_diagnostic_checkpoints/queue_checkpoint_properties.adoc[] |
| endif::VK_NV_device_diagnostic_checkpoints[] |
| |
| endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| |
| ifdef::VK_KHR_video_queue[] |
| [open,refpage='VkQueueFamilyVideoPropertiesKHR',desc='Structure describing video codec operations supported by a queue family',type='structs'] |
| -- |
| The slink:VkQueueFamilyVideoPropertiesKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkQueueFamilyVideoPropertiesKHR.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:videoCodecOperations is a bitmask of |
| elink:VkVideoCodecOperationFlagBitsKHR that indicates the set of video |
| codec operations supported by the queue family. |
| |
| If this structure is included in the pname:pNext chain of the |
| slink:VkQueueFamilyProperties2 structure passed to |
| flink:vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with the |
| set of video codec operations supported by the specified queue family. |
| |
| include::{generated}/validity/structs/VkQueueFamilyVideoPropertiesKHR.adoc[] |
| -- |
| |
| [open,refpage='VkQueueFamilyQueryResultStatusPropertiesKHR',desc='Structure specifying support for result status query',type='structs'] |
| -- |
| The slink:VkQueueFamilyQueryResultStatusPropertiesKHR structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkQueueFamilyQueryResultStatusPropertiesKHR.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:queryResultStatusSupport reports ename:VK_TRUE if query type |
| ename:VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR and use of |
| ename:VK_QUERY_RESULT_WITH_STATUS_BIT_KHR are supported. |
| |
| If this structure is included in the pname:pNext chain of the |
| slink:VkQueueFamilyProperties2 structure passed to |
| flink:vkGetPhysicalDeviceQueueFamilyProperties2, then it is filled with |
| information about whether <<queries-result-status-only,result status |
| queries>> are supported by the specified queue family. |
| |
| include::{generated}/validity/structs/VkQueueFamilyQueryResultStatusPropertiesKHR.adoc[] |
| -- |
| endif::VK_KHR_video_queue[] |
| |
| ifdef::VK_KHR_performance_query[] |
| include::{chapters}/VK_KHR_performance_query/queuefamily.adoc[] |
| endif::VK_KHR_performance_query[] |
| |
| |
| [[devsandqueues-devices]] |
| == Devices |
| |
| Device objects represent logical connections to physical devices. |
| Each device exposes a number of _queue families_ each having one or more |
| _queues_. |
| All queues in a queue family support the same operations. |
| |
| As described in <<devsandqueues-physical-device-enumeration,Physical |
| Devices>>, a Vulkan application will first query for all physical devices in |
| a system. |
| Each physical device can: then be queried for its capabilities, including |
| its queue and queue family properties. |
| Once an acceptable physical device is identified, an application will create |
| a corresponding logical device. |
| The created logical device is then the primary interface to the physical |
| device. |
| |
| How to enumerate the physical devices in a system and query those physical |
| devices for their queue family properties is described in the |
| <<devsandqueues-physical-device-enumeration, Physical Device Enumeration>> |
| section above. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[] |
| |
| A single logical device can: be created from multiple physical devices, if |
| those physical devices belong to the same device group. |
| A _device group_ is a set of physical devices that support accessing each |
| other's memory and recording a single command buffer that can: be executed |
| on all the physical devices. |
| Device groups are enumerated by calling |
| flink:vkEnumeratePhysicalDeviceGroups, and a logical device is created from |
| a subset of the physical devices in a device group by passing the physical |
| devices through slink:VkDeviceGroupDeviceCreateInfo. |
| For two physical devices to be in the same device group, they must: support |
| identical extensions, features, and properties. |
| |
| [NOTE] |
| .Note |
| ==== |
| Physical devices in the same device group must: be so similar because there |
| are no rules for how different features/properties would interact. |
| They must: return the same values for nearly every invariant |
| ftext:vkGetPhysicalDevice* feature, property, capability, etc., but could |
| potentially differ for certain queries based on things like having a |
| different display connected, or a different compositor. |
| The specification does not attempt to enumerate which state is in each |
| category, because such a list would quickly become out of date. |
| ==== |
| |
| [open,refpage='vkEnumeratePhysicalDeviceGroups',desc='Enumerates groups of physical devices that can be used to create a single logical device',type='protos'] |
| -- |
| To retrieve a list of the device groups present in the system, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkEnumeratePhysicalDeviceGroups.adoc[] |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1+VK_KHR_device_group_creation[or the equivalent command] |
| |
| ifdef::VK_KHR_device_group_creation[] |
| include::{generated}/api/protos/vkEnumeratePhysicalDeviceGroupsKHR.adoc[] |
| endif::VK_KHR_device_group_creation[] |
| |
| * pname:instance is a handle to a Vulkan instance previously created with |
| flink:vkCreateInstance. |
| * pname:pPhysicalDeviceGroupCount is a pointer to an integer related to |
| the number of device groups available or queried, as described below. |
| * pname:pPhysicalDeviceGroupProperties is either `NULL` or a pointer to an |
| array of slink:VkPhysicalDeviceGroupProperties structures. |
| |
| If pname:pPhysicalDeviceGroupProperties is `NULL`, then the number of device |
| groups available is returned in pname:pPhysicalDeviceGroupCount. |
| Otherwise, pname:pPhysicalDeviceGroupCount must: point to a variable set by |
| the user to the number of elements in the |
| pname:pPhysicalDeviceGroupProperties array, and on return the variable is |
| overwritten with the number of structures actually written to |
| pname:pPhysicalDeviceGroupProperties. |
| If pname:pPhysicalDeviceGroupCount is less than the number of device groups |
| available, at most pname:pPhysicalDeviceGroupCount structures will be |
| written, and ename:VK_INCOMPLETE will be returned instead of |
| ename:VK_SUCCESS, to indicate that not all the available device groups were |
| returned. |
| |
| Every physical device must: be in exactly one device group. |
| |
| include::{generated}/validity/protos/vkEnumeratePhysicalDeviceGroups.adoc[] |
| -- |
| |
| [open,refpage='VkPhysicalDeviceGroupProperties',desc='Structure specifying physical device group properties',type='structs'] |
| -- |
| The sname:VkPhysicalDeviceGroupProperties structure is defined as: |
| |
| include::{generated}/api/structs/VkPhysicalDeviceGroupProperties.adoc[] |
| |
| ifdef::VK_KHR_device_group_creation[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkPhysicalDeviceGroupPropertiesKHR.adoc[] |
| endif::VK_KHR_device_group_creation[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:physicalDeviceCount is the number of physical devices in the |
| group. |
| * pname:physicalDevices is an array of ename:VK_MAX_DEVICE_GROUP_SIZE |
| slink:VkPhysicalDevice handles representing all physical devices in the |
| group. |
| The first pname:physicalDeviceCount elements of the array will be valid. |
| * pname:subsetAllocation specifies whether logical devices created from |
| the group support allocating device memory on a subset of devices, via |
| the pname:deviceMask member of the slink:VkMemoryAllocateFlagsInfo. |
| If this is ename:VK_FALSE, then all device memory allocations are made |
| across all physical devices in the group. |
| If pname:physicalDeviceCount is `1`, then pname:subsetAllocation must: |
| be ename:VK_FALSE. |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceGroupProperties.adoc[] |
| -- |
| |
| [open,refpage='VK_MAX_DEVICE_GROUP_SIZE',desc='Length of a physical device handle array',type='consts',alias='VK_MAX_DEVICE_GROUP_SIZE_KHR'] |
| -- |
| ename:VK_MAX_DEVICE_GROUP_SIZE is the length of an array containing |
| slink:VkPhysicalDevice handle values representing all physical devices in a |
| group, as returned in |
| slink:VkPhysicalDeviceGroupProperties::pname:physicalDevices. |
| |
| include::{generated}/api/enums/VK_MAX_DEVICE_GROUP_SIZE.adoc[] |
| |
| ifdef::VK_KHR_device_group_creation[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VK_MAX_DEVICE_GROUP_SIZE_KHR.adoc[] |
| endif::VK_KHR_device_group_creation[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_device_group_creation[] |
| |
| |
| [[devsandqueues-device-creation]] |
| === Device Creation |
| |
| [open,refpage='VkDevice',desc='Opaque handle to a device object',type='handles'] |
| -- |
| Logical devices are represented by sname:VkDevice handles: |
| |
| include::{generated}/api/handles/VkDevice.adoc[] |
| -- |
| |
| [open,refpage='vkCreateDevice',desc='Create a new device instance',type='protos'] |
| -- |
| A logical device is created as a _connection_ to a physical device. |
| To create a logical device, call: |
| |
| include::{generated}/api/protos/vkCreateDevice.adoc[] |
| |
| * pname:physicalDevice must: be one of the device handles returned from a |
| call to fname:vkEnumeratePhysicalDevices (see |
| <<devsandqueues-physical-device-enumeration, Physical Device |
| Enumeration>>). |
| * pname:pCreateInfo is a pointer to a slink:VkDeviceCreateInfo structure |
| containing information about how to create the device. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pDevice is a pointer to a handle in which the created |
| slink:VkDevice is returned. |
| |
| fname:vkCreateDevice verifies that extensions and features requested in the |
| pname:ppEnabledExtensionNames and pname:pEnabledFeatures members of |
| pname:pCreateInfo, respectively, are supported by the implementation. |
| If any requested extension is not supported, fname:vkCreateDevice must: |
| return ename:VK_ERROR_EXTENSION_NOT_PRESENT. |
| If any requested feature is not supported, fname:vkCreateDevice must: return |
| ename:VK_ERROR_FEATURE_NOT_PRESENT. |
| Support for extensions can: be checked before creating a device by querying |
| flink:vkEnumerateDeviceExtensionProperties. |
| Support for features can: similarly be checked by querying |
| flink:vkGetPhysicalDeviceFeatures. |
| |
| ifdef::VKSC_VERSION_1_0[] |
| fname:vkCreateDevice also verifies that mandatory structures and features |
| for Vulkan SC are present and enabled: |
| |
| * The pname:pNext chain must: include a |
| slink:VkDeviceObjectReservationCreateInfo structure. |
| * The pname:pNext chain must: include a |
| slink:VkPhysicalDeviceVulkanSC10Features structure. |
| ifdef::hidden[] |
| // tag::scdeviation[] |
| * The slink:VkDeviceCreateInfo::pname:pNext chain must: include a |
| slink:VkDeviceObjectReservationCreateInfo structure <<SCID-4>>. |
| * The slink:VkDeviceCreateInfo::pname:pNext chain must: include a |
| slink:VkPhysicalDeviceVulkanSC10Features structure <<SCID-1>>. |
| // end::scdeviation[] |
| endif::hidden[] |
| |
| If any of these conditions are not met, fname:vkCreateDevice must: return |
| ename:VK_ERROR_INITIALIZATION_FAILED. |
| endif::VKSC_VERSION_1_0[] |
| |
| After verifying and enabling the extensions the sname:VkDevice object is |
| created and returned to the application. |
| |
| ifndef::VKSC_VERSION_1_0[] |
| Multiple logical devices can: be created from the same physical device. |
| Logical device creation may: fail due to lack of device-specific resources |
| (in addition to other errors). |
| endif::VKSC_VERSION_1_0[] |
| ifdef::VKSC_VERSION_1_0[] |
| An implementation may: allow multiple logical devices to be created from the |
| same physical device. |
| Logical device creation may: fail due to lack of device-specific resources, |
| including too many other logical devices, in addition to other errors. |
| endif::VKSC_VERSION_1_0[] |
| If that occurs, fname:vkCreateDevice will return |
| ename:VK_ERROR_TOO_MANY_OBJECTS. |
| |
| ifdef::VKSC_VERSION_1_0[] |
| If the pipeline cache data pointed to by the pname:pInitialData member of |
| any element of |
| slink:VkDeviceObjectReservationCreateInfo::pname:pPipelineCacheCreateInfos |
| is not compatible with the device, then fname:vkCreateDevice will return |
| ename:VK_ERROR_INVALID_PIPELINE_CACHE_DATA. |
| ifdef::hidden[] |
| // tag::scdeviation[] |
| * flink:vkCreateDevice returns ename:VK_ERROR_INVALID_PIPELINE_CACHE_DATA |
| if the pname:pInitialData member of any element of |
| slink:VkDeviceObjectReservationCreateInfo::pname:pPipelineCacheCreateInfos |
| is a pointer to incompatible pipeline cache data <<SCID-1>>. |
| // end::scdeviation[] |
| endif::hidden[] |
| endif::VKSC_VERSION_1_0[] |
| |
| ifdef::VK_EXT_application_parameters[] |
| To provide _application parameters_ at device creation time, an application |
| can: link one or more slink:VkApplicationParametersEXT structures to the |
| pname:pNext chain of the sname:VkDeviceCreateInfo structure. |
| |
| If the slink:VkApplicationParametersEXT::pname:vendorID and |
| slink:VkApplicationParametersEXT::pname:deviceID values do not match the |
| slink:VkPhysicalDeviceProperties::pname:vendorID and |
| slink:VkPhysicalDeviceProperties::pname:deviceID of pname:physicalDevice, |
| flink:vkCreateDevice must: return ename:VK_ERROR_INITIALIZATION_FAILED. |
| |
| If slink:VkApplicationParametersEXT::pname:key is not a valid |
| implementation-defined application parameter key for the device being |
| created, or if pname:value is not a valid value for the specified pname:key, |
| flink:vkCreateDevice will fail and return |
| ename:VK_ERROR_INITIALIZATION_FAILED. |
| |
| For any implementation-defined application parameter pname:key that exists |
| but is not set by the application, the implementation-specific default value |
| is used. |
| endif::VK_EXT_application_parameters[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCreateDevice-ppEnabledExtensionNames-01387]] |
| All <<extendingvulkan-extensions-extensiondependencies, required device |
| extensions>> for each extension in the |
| slink:VkDeviceCreateInfo::pname:ppEnabledExtensionNames list must: also |
| be present in that list |
| ifdef::VK_EXT_application_parameters[] |
| * [[VUID-vkCreateDevice-key-05092]] |
| The pname:key value of each slink:VkApplicationParametersEXT structure |
| in the slink:VkDeviceCreateInfo::pname:pNext chain must: be unique |
| endif::VK_EXT_application_parameters[] |
| ifdef::VKSC_VERSION_1_0[] |
| * [[VUID-vkCreateDevice-deviceMemoryRequestCount-05095]] |
| The sum of pname:deviceMemoryRequestCount over all |
| sname:VkDeviceObjectReservationCreateInfo structures must: be less than |
| or equal to slink:VkPhysicalDeviceLimits::pname:maxMemoryAllocationCount |
| * [[VUID-vkCreateDevice-samplerRequestCount-05096]] |
| The sum of pname:samplerRequestCount over all |
| sname:VkDeviceObjectReservationCreateInfo structures must: be less than |
| or equal to |
| slink:VkPhysicalDeviceLimits::pname:maxSamplerAllocationCount |
| endif::VKSC_VERSION_1_0[] |
| **** |
| |
| include::{generated}/validity/protos/vkCreateDevice.adoc[] |
| -- |
| |
| [open,refpage='VkDeviceCreateInfo',desc='Structure specifying parameters of a newly created device',type='structs'] |
| -- |
| The sname:VkDeviceCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceCreateInfo.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is reserved for future use. |
| * pname:queueCreateInfoCount is the unsigned integer size of the |
| pname:pQueueCreateInfos array. |
| Refer to the <<devsandqueues-queue-creation,Queue Creation>> section |
| below for further details. |
| * pname:pQueueCreateInfos is a pointer to an array of |
| slink:VkDeviceQueueCreateInfo structures describing the queues that are |
| requested to be created along with the logical device. |
| Refer to the <<devsandqueues-queue-creation,Queue Creation>> section |
| below for further details. |
| * pname:enabledLayerCount is deprecated and ignored. |
| * pname:ppEnabledLayerNames is deprecated and ignored. |
| See <<extendingvulkan-layers-devicelayerdeprecation>>. |
| * pname:enabledExtensionCount is the number of device extensions to |
| enable. |
| * pname:ppEnabledExtensionNames is a pointer to an array of |
| pname:enabledExtensionCount null-terminated UTF-8 strings containing the |
| names of extensions to enable for the created device. |
| See the <<extendingvulkan-extensions>> section for further details. |
| * pname:pEnabledFeatures is `NULL` or a pointer to a |
| slink:VkPhysicalDeviceFeatures structure containing boolean indicators |
| of all the features to be enabled. |
| Refer to the <<features, Features>> section for further details. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceCreateInfo-queueFamilyIndex-02802]] |
| The pname:queueFamilyIndex member of each element of |
| pname:pQueueCreateInfos must: be unique within pname:pQueueCreateInfos |
| ifdef::VK_VERSION_1_1[] |
| , except that two members can share the same pname:queueFamilyIndex if |
| one describes protected-capable queues and one describes queues that are |
| not protected-capable |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-VkDeviceCreateInfo-pQueueCreateInfos-06755]] |
| If multiple elements of pname:pQueueCreateInfos share the same |
| pname:queueFamilyIndex, the sum of their pname:queueCount members must: |
| be less than or equal to the pname:queueCount member of the |
| sname:VkQueueFamilyProperties structure, as returned by |
| fname:vkGetPhysicalDeviceQueueFamilyProperties in the |
| pname:pQueueFamilyProperties[queueFamilyIndex] |
| ifdef::VK_KHR_global_priority,VK_EXT_global_priority[] |
| * [[VUID-VkDeviceCreateInfo-pQueueCreateInfos-06654]] |
| If multiple elements of pname:pQueueCreateInfos share the same |
| pname:queueFamilyIndex, then all of such elements must: have the same |
| global priority level, which can: be specified explicitly by the |
| including a slink:VkDeviceQueueGlobalPriorityCreateInfoKHR structure in |
| the pname:pNext chain, or by the implicit default value |
| endif::VK_KHR_global_priority,VK_EXT_global_priority[] |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| * [[VUID-VkDeviceCreateInfo-pNext-00373]] |
| If the pname:pNext chain includes a slink:VkPhysicalDeviceFeatures2 |
| structure, then pname:pEnabledFeatures must: be `NULL` |
| endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| ifdef::VK_AMD_negative_viewport_height[] |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-01840]] |
| If slink:VkPhysicalDeviceProperties::pname:apiVersion advertises Vulkan |
| 1.1 or later, pname:ppEnabledExtensionNames must: not contain |
| `apiext:VK_AMD_negative_viewport_height` |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_KHR_maintenance1[] |
| * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-00374]] |
| pname:ppEnabledExtensionNames must: not contain both |
| `apiext:VK_KHR_maintenance1` and |
| `apiext:VK_AMD_negative_viewport_height` |
| endif::VK_KHR_maintenance1[] |
| endif::VK_AMD_negative_viewport_height[] |
| ifdef::VK_EXT_buffer_device_address+VK_KHR_buffer_device_address[] |
| * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-03328]] |
| pname:ppEnabledExtensionNames must: not contain both |
| `apiext:VK_KHR_buffer_device_address` and |
| `apiext:VK_EXT_buffer_device_address` |
| endif::VK_EXT_buffer_device_address+VK_KHR_buffer_device_address[] |
| ifdef::VK_VERSION_1_2[] |
| ifdef::VK_EXT_buffer_device_address[] |
| * [[VUID-VkDeviceCreateInfo-pNext-04748]] |
| If the pname:pNext chain includes a |
| slink:VkPhysicalDeviceVulkan12Features structure and |
| slink:VkPhysicalDeviceVulkan12Features::pname:bufferDeviceAddress is |
| ename:VK_TRUE, pname:ppEnabledExtensionNames must: not contain |
| `apiext:VK_EXT_buffer_device_address` |
| endif::VK_EXT_buffer_device_address[] |
| * [[VUID-VkDeviceCreateInfo-pNext-02829]] |
| If the pname:pNext chain includes a |
| slink:VkPhysicalDeviceVulkan11Features structure, then it must: not |
| include a slink:VkPhysicalDevice16BitStorageFeatures, |
| slink:VkPhysicalDeviceMultiviewFeatures, |
| slink:VkPhysicalDeviceVariablePointersFeatures, |
| slink:VkPhysicalDeviceProtectedMemoryFeatures, |
| slink:VkPhysicalDeviceSamplerYcbcrConversionFeatures, or |
| slink:VkPhysicalDeviceShaderDrawParametersFeatures structure |
| * [[VUID-VkDeviceCreateInfo-pNext-02830]] |
| If the pname:pNext chain includes a |
| slink:VkPhysicalDeviceVulkan12Features structure, then it must: not |
| include a slink:VkPhysicalDevice8BitStorageFeatures, |
| slink:VkPhysicalDeviceShaderAtomicInt64Features, |
| slink:VkPhysicalDeviceShaderFloat16Int8Features, |
| slink:VkPhysicalDeviceDescriptorIndexingFeatures, |
| slink:VkPhysicalDeviceScalarBlockLayoutFeatures, |
| slink:VkPhysicalDeviceImagelessFramebufferFeatures, |
| slink:VkPhysicalDeviceUniformBufferStandardLayoutFeatures, |
| slink:VkPhysicalDeviceShaderSubgroupExtendedTypesFeatures, |
| slink:VkPhysicalDeviceSeparateDepthStencilLayoutsFeatures, |
| slink:VkPhysicalDeviceHostQueryResetFeatures, |
| slink:VkPhysicalDeviceTimelineSemaphoreFeatures, |
| slink:VkPhysicalDeviceBufferDeviceAddressFeatures, or |
| slink:VkPhysicalDeviceVulkanMemoryModelFeatures structure |
| ifdef::VK_KHR_shader_draw_parameters[] |
| * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-04476]] |
| If pname:ppEnabledExtensionNames contains |
| `"VK_KHR_shader_draw_parameters"` and the pname:pNext chain includes a |
| slink:VkPhysicalDeviceVulkan11Features structure, then |
| sname:VkPhysicalDeviceVulkan11Features::pname:shaderDrawParameters must: |
| be ename:VK_TRUE |
| endif::VK_KHR_shader_draw_parameters[] |
| ifdef::VK_KHR_draw_indirect_count[] |
| * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02831]] |
| If pname:ppEnabledExtensionNames contains `"VK_KHR_draw_indirect_count"` |
| and the pname:pNext chain includes a |
| slink:VkPhysicalDeviceVulkan12Features structure, then |
| sname:VkPhysicalDeviceVulkan12Features::pname:drawIndirectCount must: be |
| ename:VK_TRUE |
| endif::VK_KHR_draw_indirect_count[] |
| ifdef::VK_KHR_sampler_mirror_clamp_to_edge[] |
| * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02832]] |
| If pname:ppEnabledExtensionNames contains |
| `"VK_KHR_sampler_mirror_clamp_to_edge"` and the pname:pNext chain |
| includes a slink:VkPhysicalDeviceVulkan12Features structure, then |
| sname:VkPhysicalDeviceVulkan12Features::pname:samplerMirrorClampToEdge |
| must: be ename:VK_TRUE |
| endif::VK_KHR_sampler_mirror_clamp_to_edge[] |
| ifdef::VK_EXT_descriptor_indexing[] |
| * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02833]] |
| If pname:ppEnabledExtensionNames contains `"VK_EXT_descriptor_indexing"` |
| and the pname:pNext chain includes a |
| slink:VkPhysicalDeviceVulkan12Features structure, then |
| sname:VkPhysicalDeviceVulkan12Features::pname:descriptorIndexing must: |
| be ename:VK_TRUE |
| endif::VK_EXT_descriptor_indexing[] |
| ifdef::VK_EXT_sampler_filter_minmax[] |
| * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02834]] |
| If pname:ppEnabledExtensionNames contains |
| `"VK_EXT_sampler_filter_minmax"` and the pname:pNext chain includes a |
| slink:VkPhysicalDeviceVulkan12Features structure, then |
| sname:VkPhysicalDeviceVulkan12Features::pname:samplerFilterMinmax must: |
| be ename:VK_TRUE |
| endif::VK_EXT_sampler_filter_minmax[] |
| ifdef::VK_EXT_shader_viewport_index_layer[] |
| * [[VUID-VkDeviceCreateInfo-ppEnabledExtensionNames-02835]] |
| If pname:ppEnabledExtensionNames contains |
| `"VK_EXT_shader_viewport_index_layer"` and the pname:pNext chain |
| includes a slink:VkPhysicalDeviceVulkan12Features structure, then |
| sname:VkPhysicalDeviceVulkan12Features::pname:shaderOutputViewportIndex |
| and sname:VkPhysicalDeviceVulkan12Features::pname:shaderOutputLayer |
| must: both be ename:VK_TRUE |
| endif::VK_EXT_shader_viewport_index_layer[] |
| endif::VK_VERSION_1_2[] |
| ifdef::VK_VERSION_1_3[] |
| * [[VUID-VkDeviceCreateInfo-pNext-06532]] |
| If the pname:pNext chain includes a |
| slink:VkPhysicalDeviceVulkan13Features structure, then it must: not |
| include a slink:VkPhysicalDeviceDynamicRenderingFeatures, |
| slink:VkPhysicalDeviceImageRobustnessFeatures, |
| slink:VkPhysicalDeviceInlineUniformBlockFeatures, |
| slink:VkPhysicalDeviceMaintenance4Features, |
| slink:VkPhysicalDevicePipelineCreationCacheControlFeatures, |
| slink:VkPhysicalDevicePrivateDataFeatures, |
| slink:VkPhysicalDeviceShaderDemoteToHelperInvocationFeatures, |
| slink:VkPhysicalDeviceShaderIntegerDotProductFeatures, |
| slink:VkPhysicalDeviceShaderTerminateInvocationFeatures, |
| slink:VkPhysicalDeviceSubgroupSizeControlFeatures, |
| slink:VkPhysicalDeviceSynchronization2Features, |
| slink:VkPhysicalDeviceTextureCompressionASTCHDRFeatures, or |
| slink:VkPhysicalDeviceZeroInitializeWorkgroupMemoryFeatures structure |
| // Jon 1.3 TBD - add extension-specific VUs specifying when Vulkan13Features |
| // members must: be true. |
| endif::VK_VERSION_1_3[] |
| ifdef::VK_KHR_portability_subset[] |
| * [[VUID-VkDeviceCreateInfo-pProperties-04451]] |
| If the `apiext:VK_KHR_portability_subset` extension is included in |
| pname:pProperties of flink:vkEnumerateDeviceExtensionProperties, |
| pname:ppEnabledExtensionNames must: include |
| `"VK_KHR_portability_subset"` |
| endif::VK_KHR_portability_subset[] |
| ifdef::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[] |
| * [[VUID-VkDeviceCreateInfo-shadingRateImage-04478]] |
| If the <<features-shadingRateImage, pname:shadingRateImage>> feature is |
| enabled, the <<features-pipelineFragmentShadingRate, |
| pname:pipelineFragmentShadingRate>> feature must: not be enabled |
| * [[VUID-VkDeviceCreateInfo-shadingRateImage-04479]] |
| If the <<features-shadingRateImage, pname:shadingRateImage>> feature is |
| enabled, the <<features-primitiveFragmentShadingRate, |
| pname:primitiveFragmentShadingRate>> feature must: not be enabled |
| * [[VUID-VkDeviceCreateInfo-shadingRateImage-04480]] |
| If the <<features-shadingRateImage, pname:shadingRateImage>> feature is |
| enabled, the <<features-attachmentFragmentShadingRate, |
| pname:attachmentFragmentShadingRate>> feature must: not be enabled |
| endif::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[] |
| ifdef::VK_KHR_fragment_shading_rate+VK_EXT_fragment_density_map[] |
| * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04481]] |
| If the <<features-fragmentDensityMap, pname:fragmentDensityMap>> feature |
| is enabled, the <<features-pipelineFragmentShadingRate, |
| pname:pipelineFragmentShadingRate>> feature must: not be enabled |
| * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04482]] |
| If the <<features-fragmentDensityMap, pname:fragmentDensityMap>> feature |
| is enabled, the <<features-primitiveFragmentShadingRate, |
| pname:primitiveFragmentShadingRate>> feature must: not be enabled |
| * [[VUID-VkDeviceCreateInfo-fragmentDensityMap-04483]] |
| If the <<features-fragmentDensityMap, pname:fragmentDensityMap>> feature |
| is enabled, the <<features-attachmentFragmentShadingRate, |
| pname:attachmentFragmentShadingRate>> feature must: not be enabled |
| endif::VK_KHR_fragment_shading_rate+VK_EXT_fragment_density_map[] |
| ifdef::VK_EXT_shader_image_atomic_int64[] |
| * [[VUID-VkDeviceCreateInfo-None-04896]] |
| If <<features-sparseImageInt64Atomics, pname:sparseImageInt64Atomics>> |
| is enabled, <<features-shaderImageInt64Atomics, |
| pname:shaderImageInt64Atomics>> must: be enabled |
| endif::VK_EXT_shader_image_atomic_int64[] |
| ifdef::VK_EXT_shader_atomic_float[] |
| * [[VUID-VkDeviceCreateInfo-None-04897]] |
| If <<features-sparseImageFloat32Atomics, |
| pname:sparseImageFloat32Atomics>> is enabled, |
| <<features-shaderImageFloat32Atomics, pname:shaderImageFloat32Atomics>> |
| must: be enabled |
| * [[VUID-VkDeviceCreateInfo-None-04898]] |
| If <<features-sparseImageFloat32AtomicAdd, |
| pname:sparseImageFloat32AtomicAdd>> is enabled, |
| <<features-shaderImageFloat32AtomicAdd, |
| pname:shaderImageFloat32AtomicAdd>> must: be enabled |
| endif::VK_EXT_shader_atomic_float[] |
| ifdef::VK_EXT_shader_atomic_float2[] |
| * [[VUID-VkDeviceCreateInfo-sparseImageFloat32AtomicMinMax-04975]] |
| If <<features-sparseImageFloat32AtomicMinMax, |
| pname:sparseImageFloat32AtomicMinMax>> is enabled, |
| <<features-shaderImageFloat32AtomicMinMax, |
| pname:shaderImageFloat32AtomicMinMax>> must: be enabled |
| endif::VK_EXT_shader_atomic_float2[] |
| ifdef::VK_EXT_descriptor_buffer[] |
| ifdef::VK_AMD_shader_fragment_mask[] |
| * [[VUID-VkDeviceCreateInfo-None-08095]] |
| If <<features-descriptorBuffer, pname:descriptorBuffer>> is enabled, |
| pname:ppEnabledExtensionNames must: not contain |
| `apiext:VK_AMD_shader_fragment_mask` |
| endif::VK_AMD_shader_fragment_mask[] |
| endif::VK_EXT_descriptor_buffer[] |
| ifdef::VK_ARM_scheduling_controls[] |
| * [[VUID-VkDeviceCreateInfo-pNext-09396]] |
| If the pname:pNext chain includes a |
| slink:VkDeviceQueueShaderCoreControlCreateInfoARM structure, then it |
| must: not be included in the pname:pNext chain of any of the |
| slink:VkDeviceQueueCreateInfo structures in pname:pQueueCreateInfos. |
| * [[VUID-VkDeviceCreateInfo-pNext-09397]] |
| If the pname:pNext chain includes a |
| slink:VkDeviceQueueShaderCoreControlCreateInfoARM structure then |
| slink:VkPhysicalDeviceSchedulingControlsPropertiesARM::pname:schedulingControlsFlags |
| must: contain |
| ename:VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM. |
| endif::VK_ARM_scheduling_controls[] |
| **** |
| |
| include::{generated}/validity/structs/VkDeviceCreateInfo.adoc[] |
| -- |
| |
| [open,refpage='VkDeviceCreateFlags',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkDeviceCreateFlags.adoc[] |
| |
| tname:VkDeviceCreateFlags is a bitmask type for setting a mask, but is |
| currently reserved for future use. |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group_creation[] |
| [open,refpage='VkDeviceGroupDeviceCreateInfo',desc='Create a logical device from multiple physical devices',type='structs'] |
| -- |
| A logical device can: be created that connects to one or more physical |
| devices by adding a sname:VkDeviceGroupDeviceCreateInfo structure to the |
| pname:pNext chain of slink:VkDeviceCreateInfo. |
| The sname:VkDeviceGroupDeviceCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceGroupDeviceCreateInfo.adoc[] |
| |
| ifdef::VK_KHR_device_group_creation[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkDeviceGroupDeviceCreateInfoKHR.adoc[] |
| endif::VK_KHR_device_group_creation[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:physicalDeviceCount is the number of elements in the |
| pname:pPhysicalDevices array. |
| * pname:pPhysicalDevices is a pointer to an array of physical device |
| handles belonging to the same device group. |
| |
| The elements of the pname:pPhysicalDevices array are an ordered list of the |
| physical devices that the logical device represents. |
| These must: be a subset of a single device group, and need not be in the |
| same order as they were enumerated. |
| The order of the physical devices in the pname:pPhysicalDevices array |
| determines the _device index_ of each physical device, with element [eq]#i# |
| being assigned a device index of [eq]#i#. |
| Certain commands and structures refer to one or more physical devices by |
| using device indices or _device masks_ formed using device indices. |
| |
| A logical device created without using sname:VkDeviceGroupDeviceCreateInfo, |
| or with pname:physicalDeviceCount equal to zero, is equivalent to a |
| pname:physicalDeviceCount of one and pname:pPhysicalDevices pointing to the |
| pname:physicalDevice parameter to flink:vkCreateDevice. |
| In particular, the device index of that physical device is zero. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00375]] |
| Each element of pname:pPhysicalDevices must: be unique |
| * [[VUID-VkDeviceGroupDeviceCreateInfo-pPhysicalDevices-00376]] |
| All elements of pname:pPhysicalDevices must: be in the same device group |
| as enumerated by flink:vkEnumeratePhysicalDeviceGroups |
| * [[VUID-VkDeviceGroupDeviceCreateInfo-physicalDeviceCount-00377]] |
| If pname:physicalDeviceCount is not `0`, the pname:physicalDevice |
| parameter of flink:vkCreateDevice must: be an element of |
| pname:pPhysicalDevices |
| **** |
| |
| include::{generated}/validity/structs/VkDeviceGroupDeviceCreateInfo.adoc[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_device_group_creation[] |
| |
| ifdef::VK_AMD_memory_overallocation_behavior[] |
| [open,refpage='VkDeviceMemoryOverallocationCreateInfoAMD',desc='Specify memory overallocation behavior for a Vulkan device',type='structs'] |
| -- |
| To specify whether device memory allocation is allowed beyond the size |
| reported by slink:VkPhysicalDeviceMemoryProperties, add a |
| slink:VkDeviceMemoryOverallocationCreateInfoAMD structure to the pname:pNext |
| chain of the slink:VkDeviceCreateInfo structure. |
| If this structure is not specified, it is as if the |
| ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD value is used. |
| |
| include::{generated}/api/structs/VkDeviceMemoryOverallocationCreateInfoAMD.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:overallocationBehavior is the desired overallocation behavior. |
| |
| include::{generated}/validity/structs/VkDeviceMemoryOverallocationCreateInfoAMD.adoc[] |
| -- |
| |
| [open,refpage='VkMemoryOverallocationBehaviorAMD',desc='Specify memory overallocation behavior',type='enums'] |
| -- |
| Possible values for |
| slink:VkDeviceMemoryOverallocationCreateInfoAMD::pname:overallocationBehavior |
| include: |
| |
| include::{generated}/api/enums/VkMemoryOverallocationBehaviorAMD.adoc[] |
| |
| * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DEFAULT_AMD lets the |
| implementation decide if overallocation is allowed. |
| * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_ALLOWED_AMD specifies |
| overallocation is allowed if platform permits. |
| * ename:VK_MEMORY_OVERALLOCATION_BEHAVIOR_DISALLOWED_AMD specifies the |
| application is not allowed to allocate device memory beyond the heap |
| sizes reported by slink:VkPhysicalDeviceMemoryProperties. |
| Allocations that are not explicitly made by the application within the |
| scope of the Vulkan instance are not accounted for. |
| -- |
| endif::VK_AMD_memory_overallocation_behavior[] |
| |
| ifdef::VK_NV_device_diagnostics_config[] |
| [open,refpage='VkDeviceDiagnosticsConfigCreateInfoNV',desc='Specify diagnostics config for a Vulkan device',type='structs'] |
| -- |
| When using the Nsight^(TM)^ Aftermath SDK, to configure how device crash |
| dumps are created, add a slink:VkDeviceDiagnosticsConfigCreateInfoNV |
| structure to the pname:pNext chain of the slink:VkDeviceCreateInfo |
| structure. |
| |
| include::{generated}/api/structs/VkDeviceDiagnosticsConfigCreateInfoNV.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkDeviceDiagnosticsConfigFlagBitsNV |
| specifying additional parameters for configuring diagnostic tools. |
| |
| include::{generated}/validity/structs/VkDeviceDiagnosticsConfigCreateInfoNV.adoc[] |
| -- |
| |
| [open,refpage='VkDeviceDiagnosticsConfigFlagBitsNV',desc='Bitmask specifying diagnostics flags',type='enums'] |
| -- |
| Bits which can: be set in |
| slink:VkDeviceDiagnosticsConfigCreateInfoNV::pname:flags include: |
| |
| include::{generated}/api/enums/VkDeviceDiagnosticsConfigFlagBitsNV.adoc[] |
| |
| * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_DEBUG_INFO_BIT_NV |
| enables the generation of debug information for shaders. |
| * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_RESOURCE_TRACKING_BIT_NV |
| enables driver side tracking of resources (images, buffers, etc.) used |
| to augment the device fault information. |
| * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_AUTOMATIC_CHECKPOINTS_BIT_NV |
| enables automatic insertion of <<device-diagnostic-checkpoints, |
| diagnostic checkpoints>> for draw calls, dispatches, |
| ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| trace rays, |
| endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| and copies. |
| The CPU call stack at the time of the command will be associated as the |
| marker data for the automatically inserted checkpoints. |
| * ename:VK_DEVICE_DIAGNOSTICS_CONFIG_ENABLE_SHADER_ERROR_REPORTING_BIT_NV |
| enables shader error reporting. |
| -- |
| |
| [open,refpage='VkDeviceDiagnosticsConfigFlagsNV',desc='Bitmask of VkDeviceDiagnosticsConfigFlagBitsNV',type='flags'] |
| -- |
| include::{generated}/api/flags/VkDeviceDiagnosticsConfigFlagsNV.adoc[] |
| |
| tname:VkDeviceDiagnosticsConfigFlagsNV is a bitmask type for setting a mask |
| of zero or more elink:VkDeviceDiagnosticsConfigFlagBitsNV. |
| -- |
| endif::VK_NV_device_diagnostics_config[] |
| |
| ifdef::VK_EXT_device_memory_report[] |
| [open,refpage='VkDeviceDeviceMemoryReportCreateInfoEXT',desc='Register device memory report callbacks for a Vulkan device',type='structs'] |
| -- |
| To register callbacks for underlying device memory events of type |
| elink:VkDeviceMemoryReportEventTypeEXT, add one or multiple |
| slink:VkDeviceDeviceMemoryReportCreateInfoEXT structures to the pname:pNext |
| chain of the slink:VkDeviceCreateInfo structure. |
| |
| include::{generated}/api/structs/VkDeviceDeviceMemoryReportCreateInfoEXT.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is 0 and reserved for future use. |
| * pname:pfnUserCallback is the application callback function to call. |
| * pname:pUserData is user data to be passed to the callback. |
| |
| The callback may: be called from multiple threads simultaneously. |
| |
| The callback must: be called only once by the implementation when a |
| elink:VkDeviceMemoryReportEventTypeEXT event occurs. |
| |
| [NOTE] |
| .Note |
| ==== |
| The callback could be called from a background thread other than the thread |
| calling the Vulkan commands. |
| ==== |
| |
| include::{generated}/validity/structs/VkDeviceDeviceMemoryReportCreateInfoEXT.adoc[] |
| -- |
| |
| [open,refpage='PFN_vkDeviceMemoryReportCallbackEXT',desc='Application-defined device memory report callback function',type='funcpointers'] |
| -- |
| The prototype for the |
| slink:VkDeviceDeviceMemoryReportCreateInfoEXT::pname:pfnUserCallback |
| function implemented by the application is: |
| |
| include::{generated}/api/funcpointers/PFN_vkDeviceMemoryReportCallbackEXT.adoc[] |
| |
| * pname:pCallbackData contains all the callback related data in the |
| slink:VkDeviceMemoryReportCallbackDataEXT structure. |
| * pname:pUserData is the user data provided when the |
| slink:VkDeviceDeviceMemoryReportCreateInfoEXT was created. |
| |
| The callback must: not make calls to any Vulkan commands. |
| -- |
| |
| [open,refpage='VkDeviceMemoryReportCallbackDataEXT',desc='Structure specifying parameters returned to the callback',type='structs'] |
| -- |
| The definition of sname:VkDeviceMemoryReportCallbackDataEXT is: |
| |
| include::{generated}/api/structs/VkDeviceMemoryReportCallbackDataEXT.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is 0 and reserved for future use. |
| * pname:type is a elink:VkDeviceMemoryReportEventTypeEXT type specifying |
| the type of event reported in this |
| sname:VkDeviceMemoryReportCallbackDataEXT structure. |
| * pname:memoryObjectId is the unique id for the underlying memory object |
| as described below. |
| * pname:size is the size of the memory object in bytes. |
| If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT or |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, |
| pname:size is a valid basetype:VkDeviceSize value. |
| Otherwise, pname:size is undefined:. |
| * pname:objectType is a elink:VkObjectType value specifying the type of |
| the object associated with this device memory report event. |
| If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT, |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT, |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT or |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, |
| pname:objectType is a valid elink:VkObjectType enum. |
| Otherwise, pname:objectType is undefined:. |
| * pname:objectHandle is the object this device memory report event is |
| attributed to. |
| If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT, |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT, |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT or |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT, |
| pname:objectHandle is a valid Vulkan handle of the type associated with |
| pname:objectType as defined in the <<debugging-object-types, |
| `VkObjectType` and Vulkan Handle Relationship>> table. |
| Otherwise, pname:objectHandle is undefined:. |
| * pname:heapIndex describes which memory heap this device memory |
| allocation is made from. |
| If pname:type is ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT |
| or ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT, |
| pname:heapIndex corresponds to one of the valid heaps from the |
| slink:VkPhysicalDeviceMemoryProperties structure. |
| Otherwise, pname:heapIndex is undefined:. |
| |
| pname:memoryObjectId is used to avoid double-counting on the same memory |
| object. |
| |
| If an internally-allocated device memory object or a slink:VkDeviceMemory |
| cannot: be exported, pname:memoryObjectId must: be unique in the |
| slink:VkDevice. |
| |
| If an internally-allocated device memory object or a slink:VkDeviceMemory |
| supports being exported, pname:memoryObjectId must: be unique system wide. |
| |
| If an internal device memory object or a slink:VkDeviceMemory is backed by |
| an imported external memory object, pname:memoryObjectId must: be unique |
| system wide. |
| |
| ifdef::implementation-guide[] |
| .Implementor's Note |
| **** |
| If the heap backing an internally-allocated device memory cannot: be used to |
| back slink:VkDeviceMemory, implementations can: advertise that heap with no |
| types. |
| **** |
| endif::implementation-guide[] |
| |
| [NOTE] |
| .Note |
| ==== |
| This structure should only be considered valid during the lifetime of the |
| triggered callback. |
| |
| For ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT and |
| ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT events, |
| pname:objectHandle usually will not yet exist when the application or tool |
| receives the callback. |
| pname:objectHandle will only exist when the create or allocate call that |
| triggered the event returns, and if the allocation or import ends up failing |
| pname:objectHandle will not ever exist. |
| ==== |
| |
| include::{generated}/validity/structs/VkDeviceMemoryReportCallbackDataEXT.adoc[] |
| -- |
| |
| [open,refpage='VkDeviceMemoryReportFlagsEXT',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkDeviceMemoryReportFlagsEXT.adoc[] |
| |
| tname:VkDeviceMemoryReportFlagsEXT is a bitmask type for setting a mask, but |
| is currently reserved for future use. |
| -- |
| |
| [open,refpage='VkDeviceMemoryReportEventTypeEXT',desc='Events that can occur on a device memory object',type='enums'] |
| -- |
| Possible values of slink:VkDeviceMemoryReportCallbackDataEXT::pname:type, |
| specifying event types which cause the device driver to call the callback, |
| are: |
| |
| include::{generated}/api/enums/VkDeviceMemoryReportEventTypeEXT.adoc[] |
| |
| * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATE_EXT specifies this |
| event corresponds to the allocation of an internal device memory object |
| or a slink:VkDeviceMemory. |
| * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_FREE_EXT specifies this event |
| corresponds to the deallocation of an internally-allocated device memory |
| object or a slink:VkDeviceMemory. |
| * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_IMPORT_EXT specifies this event |
| corresponds to the import of an external memory object. |
| * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_UNIMPORT_EXT specifies this |
| event is the release of an imported external memory object. |
| * ename:VK_DEVICE_MEMORY_REPORT_EVENT_TYPE_ALLOCATION_FAILED_EXT specifies |
| this event corresponds to the failed allocation of an internal device |
| memory object or a slink:VkDeviceMemory. |
| -- |
| endif::VK_EXT_device_memory_report[] |
| |
| ifdef::VK_VERSION_1_3,VK_EXT_private_data[] |
| [open,refpage='VkDevicePrivateDataCreateInfo',desc='Reserve private data slots',type='structs',alias='VkDevicePrivateDataCreateInfoEXT'] |
| -- |
| To reserve private data storage slots, add a |
| slink:VkDevicePrivateDataCreateInfo structure to the pname:pNext chain of |
| the slink:VkDeviceCreateInfo structure. |
| Reserving slots in this manner is not strictly necessary, but doing so may: |
| improve performance. |
| |
| include::{generated}/api/structs/VkDevicePrivateDataCreateInfo.adoc[] |
| |
| ifdef::VK_EXT_private_data[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkDevicePrivateDataCreateInfoEXT.adoc[] |
| endif::VK_EXT_private_data[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:privateDataSlotRequestCount is the amount of slots to reserve. |
| |
| include::{generated}/validity/structs/VkDevicePrivateDataCreateInfo.adoc[] |
| -- |
| endif::VK_VERSION_1_3,VK_EXT_private_data[] |
| |
| ifdef::VKSC_VERSION_1_0[] |
| |
| [open,refpage='VkDeviceObjectReservationCreateInfo',desc='Request memory reservation',type='structs'] |
| -- |
| Data structures for objects are reserved by the implementation at device |
| creation time. |
| The application must: provide upper bounds on numbers of objects and other |
| limits at device creation time. |
| To reserve data structures for use by objects created from this device, add |
| a slink:VkDeviceObjectReservationCreateInfo structure to the pname:pNext |
| chain of the slink:VkDeviceCreateInfo structure. |
| |
| include::{generated}/api/structs/VkDeviceObjectReservationCreateInfo.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:pipelineCacheCreateInfoCount is the length of the |
| pname:pPipelineCacheCreateInfos array. |
| * pname:pPipelineCacheCreateInfos is a pointer to an array of |
| slink:VkPipelineCacheCreateInfo structures that contain the creation |
| information of the pipeline caches that can: be created on this device. |
| * pname:pipelinePoolSizeCount is the length of the |
| pname:pPipelinePoolSizes array. |
| * pname:pPipelinePoolSizes is a pointer to an array of |
| slink:VkPipelinePoolSize structures requesting memory be reserved for |
| pipelines of the specified sizes. |
| * pname:semaphoreRequestCount is the requested maximum number of |
| sname:VkSemaphore objects that can: exist at the same time. |
| * pname:commandBufferRequestCount is the requested maximum number of |
| sname:VkCommandBuffer objects that can: be reserved by all |
| sname:VkCommandPool objects. |
| * pname:fenceRequestCount is the requested maximum number of sname:VkFence |
| objects that can: exist at the same time. |
| * pname:deviceMemoryRequestCount is the requested maximum number of |
| sname:VkDeviceMemory objects that can: exist at the same time. |
| * pname:bufferRequestCount is the requested maximum number of |
| sname:VkBuffer objects that can: exist at the same time. |
| * pname:imageRequestCount is the requested maximum number of sname:VkImage |
| objects that can: exist at the same time. |
| * pname:eventRequestCount is the requested maximum number of sname:VkEvent |
| objects that can: exist at the same time. |
| * pname:queryPoolRequestCount is the requested maximum number of |
| sname:VkQueryPool objects that can: exist at the same time. |
| * pname:bufferViewRequestCount is the requested maximum number of |
| sname:VkBufferView objects that can: exist at the same time. |
| * pname:imageViewRequestCount is the requested maximum number of |
| sname:VkImageView objects that can: exist at the same time. |
| * pname:layeredImageViewRequestCount is the requested maximum number |
| sname:VkImageView objects created with |
| slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount greater |
| than `1` that can: exist at the same time. |
| * pname:pipelineCacheRequestCount is the requested maximum number of |
| sname:VkPipelineCache objects that can: exist at the same time. |
| * pname:pipelineLayoutRequestCount is the requested maximum number of |
| sname:VkPipelineLayout objects that can: exist at the same time. |
| * pname:renderPassRequestCount is the requested maximum number of |
| sname:VkRenderPass objects that can: exist at the same time. |
| * pname:graphicsPipelineRequestCount is the requested maximum number of |
| graphics sname:VkPipeline objects that can: exist at the same time. |
| * pname:computePipelineRequestCount is the requested maximum number of |
| compute sname:VkPipeline objects that can: exist at the same time. |
| * pname:descriptorSetLayoutRequestCount is the requested maximum number of |
| sname:VkDescriptorSetLayout objects that can: exist at the same time. |
| * pname:samplerRequestCount is the requested maximum number of |
| sname:VkSampler objects that can: exist at the same time. |
| * pname:descriptorPoolRequestCount is the requested maximum number of |
| sname:VkDescriptorPool objects that can: exist at the same time. |
| * pname:descriptorSetRequestCount is the requested maximum number of |
| sname:VkDescriptorSet objects that can: exist at the same time. |
| * pname:framebufferRequestCount is the requested maximum number of |
| sname:VkFramebuffer objects that can: exist at the same time. |
| * pname:commandPoolRequestCount is the requested maximum number of |
| sname:VkCommandPool objects that can: exist at the same time. |
| * pname:samplerYcbcrConversionRequestCount is the requested maximum number |
| of sname:VkSamplerYcbcrConversion objects that can: exist at the same |
| time. |
| * pname:surfaceRequestCount is deprecated and implementations must: ignore |
| it. |
| * pname:swapchainRequestCount is the requested maximum number of |
| sname:VkSwapchainKHR objects that can: exist at the same time. |
| * pname:displayModeRequestCount is deprecated and implementations must: |
| ignore it. |
| * pname:subpassDescriptionRequestCount is the requested maximum sum of all |
| slink:VkRenderPassCreateInfo2::pname:subpassCount values across all |
| sname:VkRenderPass objects that can: exist at the same time. |
| * pname:attachmentDescriptionRequestCount is the requested maximum sum of |
| all slink:VkRenderPassCreateInfo2::pname:attachmentCount values across |
| all sname:VkRenderPass objects that can: exist at the same time. |
| * pname:descriptorSetLayoutBindingRequestCount is the requested maximum |
| sum of all slink:VkDescriptorSetLayoutCreateInfo::pname:bindingCount |
| values across all sname:VkDescriptorSetLayout objects that can: exist at |
| the same time. |
| * pname:descriptorSetLayoutBindingLimit is one greater than the maximum |
| value of slink:VkDescriptorSetLayoutBinding::pname:binding that can: be |
| used. |
| * pname:maxImageViewMipLevels is the maximum value of |
| slink:VkImageViewCreateInfo::pname:subresourceRange.levelCount that can: |
| be used. |
| * pname:maxImageViewArrayLayers is the maximum value of |
| slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount that can: |
| be used. |
| * pname:maxLayeredImageViewMipLevels is the maximum value of |
| slink:VkImageViewCreateInfo::pname:subresourceRange.levelCount that can: |
| be used when |
| slink:VkImageViewCreateInfo::pname:subresourceRange.layerCount is |
| greater than `1`. |
| * pname:maxOcclusionQueriesPerPool is the requested maximum number of |
| ename:VK_QUERY_TYPE_OCCLUSION queries that can: exist at the same time |
| in a single query pool. |
| * pname:maxPipelineStatisticsQueriesPerPool is the requested maximum |
| number of ename:VK_QUERY_TYPE_PIPELINE_STATISTICS queries that can: |
| exist at the same time in a single query pool. |
| * pname:maxTimestampQueriesPerPool is the requested maximum number of |
| ename:VK_QUERY_TYPE_TIMESTAMP queries that can: exist at the same time |
| in a single query pool. |
| * pname:maxImmutableSamplersPerDescriptorSetLayout is the requested |
| maximum number of immutable samplers that can be used across all |
| bindings in a descriptor set layout. |
| |
| Multiple sname:VkDeviceObjectReservationCreateInfo structures can: be |
| chained together. |
| The maximum value from all instances of pname:maxImageViewMipLevels, |
| pname:maxImageViewArrayLayers, pname:maxLayeredImageViewMipLevels, |
| pname:descriptorSetLayoutBindingLimit, pname:maxOcclusionQueriesPerPool, |
| pname:maxPipelineStatisticsQueriesPerPool, pname:maxTimestampQueriesPerPool, |
| and pname:maxImmutableSamplersPerDescriptorSetLayout will be reserved. |
| For the remaining members, the sum of the requested resources from all |
| instances of sname:VkDeviceObjectReservationCreateInfo will be reserved. |
| |
| If |
| slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory, |
| pname:deviceDestroyFreesMemory>> is ename:VK_TRUE, the reserved memory is |
| returned to the system when the device is destroyed, otherwise it may: not |
| be returned to the system until the process is terminated. |
| |
| ifdef::hidden[] |
| // tag::scaddition[] |
| * slink:VkDeviceObjectReservationCreateInfo <<SCID-4>> |
| // end::scaddition[] |
| endif::hidden[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceObjectReservationCreateInfo-maxImageViewArrayLayers-05014]] |
| pname:maxImageViewArrayLayers must: be less than or equal to |
| slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers |
| * [[VUID-VkDeviceObjectReservationCreateInfo-maxImageViewMipLevels-05015]] |
| pname:maxImageViewMipLevels must: be less than or equal to the number of |
| levels in the complete mipmap chain based on the maximum of |
| slink:VkPhysicalDeviceLimits::pname:maxImageDimension1D, |
| pname:maxImageDimension2D, pname:maxImageDimension3D, and |
| pname:maxImageDimensionCube |
| * [[VUID-VkDeviceObjectReservationCreateInfo-maxLayeredImageViewMipLevels-05016]] |
| pname:maxLayeredImageViewMipLevels must: be less than or equal to the |
| number of levels in the complete mipmap chain based on |
| slink:VkPhysicalDeviceLimits::pname:maxImageDimension1D, |
| pname:maxImageDimension2D, pname:maxImageDimension3D, and |
| pname:maxImageDimensionCube |
| * [[VUID-VkDeviceObjectReservationCreateInfo-subpassDescriptionRequestCount-05017]] |
| pname:subpassDescriptionRequestCount must: be less than or equal to |
| pname:renderPassRequestCount multiplied by |
| slink:VkPhysicalDeviceVulkanSC10Properties::pname:maxRenderPassSubpasses |
| * [[VUID-VkDeviceObjectReservationCreateInfo-attachmentDescriptionRequestCount-05018]] |
| pname:attachmentDescriptionRequestCount must: be less than or equal to |
| pname:renderPassRequestCount multiplied by |
| slink:VkPhysicalDeviceVulkanSC10Properties::pname:maxFramebufferAttachments |
| **** |
| |
| include::{generated}/validity/structs/VkDeviceObjectReservationCreateInfo.adoc[] |
| -- |
| |
| ifdef::VK_KHR_performance_query[] |
| [open,refpage='VkPerformanceQueryReservationInfoKHR',desc='Request memory reservation',type='structs'] |
| -- |
| If the pname:pNext chain of slink:VkDeviceObjectReservationCreateInfo |
| includes a slink:VkPerformanceQueryReservationInfoKHR structure, then the |
| structure indicates upper bounds on the number of performance queries that |
| can: exist at the same time in a query pool. |
| |
| The sname:VkPerformanceQueryReservationInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkPerformanceQueryReservationInfoKHR.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:maxPerformanceQueriesPerPool is the requested maximum number of |
| ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR queries that can: exist at the |
| same time in a single query pool. |
| |
| If the sname:VkDeviceObjectReservationCreateInfo::pname:pNext chain does not |
| include this structure, then pname:maxPerformanceQueriesPerPool defaults to |
| `0`. |
| |
| Multiple sname:VkPerformanceQueryReservationInfoKHR structures can be |
| chained together. |
| The maximum value from all instances of pname:maxPerformanceQueriesPerPool |
| will be reserved. |
| |
| ifdef::hidden[] |
| // tag::scaddition[] |
| ifdef::VK_KHR_performance_query[] |
| * slink:VkPerformanceQueryReservationInfoKHR <<SCID-4>> |
| endif::VK_KHR_performance_query[] |
| // end::scaddition[] |
| endif::hidden[] |
| |
| include::{generated}/validity/structs/VkPerformanceQueryReservationInfoKHR.adoc[] |
| -- |
| endif::VK_KHR_performance_query[] |
| |
| ifdef::VK_NV_external_sci_sync2[] |
| [open,refpage='VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV',desc='Request memory reservation',type='structs'] |
| -- |
| If the pname:pNext chain of slink:VkDeviceObjectReservationCreateInfo |
| includes a slink:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV |
| structure, then the structure indicates the maximum number of |
| slink:VkSemaphoreSciSyncPoolNV objects that can: exist at the same time. |
| |
| The sname:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:semaphoreSciSyncPoolRequestCount is the requested maximum number |
| of slink:VkSemaphoreSciSyncPoolNV objects that can: exist at the same |
| time. |
| |
| If the sname:VkDeviceObjectReservationCreateInfo::pname:pNext chain does not |
| include this structure, then pname:semaphoreSciSyncPoolRequestCount defaults |
| to `0`. |
| |
| Multiple sname:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV |
| structures can: be chained together. |
| The sum of the pname:semaphoreSciSyncPoolRequestCount values from all |
| instances of sname:VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV will |
| be reserved. |
| |
| include::{generated}/validity/structs/VkDeviceSemaphoreSciSyncPoolReservationCreateInfoNV.adoc[] |
| -- |
| endif::VK_NV_external_sci_sync2[] |
| |
| [open,refpage='VkPipelinePoolSize',desc='Request memory for pipelines',type='structs'] |
| -- |
| Memory for pipelines is reserved by the implementation at device creation |
| time. |
| The application specifies sizes to be reserved and a count for each size, |
| and when a pipeline is created the application specifies which size to use. |
| |
| include::{generated}/api/structs/VkPipelinePoolSize.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:poolEntrySize is the size to reserve for each entry. |
| * pname:poolEntryCount is the number of entries to reserve. |
| |
| ifdef::hidden[] |
| // tag::scaddition[] |
| * slink:VkPipelinePoolSize <<SCID-4>> |
| // end::scaddition[] |
| endif::hidden[] |
| |
| include::{generated}/validity/structs/VkPipelinePoolSize.adoc[] |
| -- |
| |
| endif::VKSC_VERSION_1_0[] |
| |
| ifdef::VK_ARM_scheduling_controls[] |
| The number of shader cores used by all the queues of a device can: be |
| controlled by adding a sname:VkDeviceQueueShaderCoreControlCreateInfoARM |
| structure to the pname:pNext chain of the slink:VkDeviceCreateInfo |
| structure. |
| endif::VK_ARM_scheduling_controls[] |
| |
| [[devsandqueues-use]] |
| === Device Use |
| |
| The following is a high-level list of sname:VkDevice uses along with |
| references on where to find more information: |
| |
| * Creation of queues. |
| See the <<devsandqueues-queues,Queues>> section below for further |
| details. |
| * Creation and tracking of various synchronization constructs. |
| See <<synchronization,Synchronization and Cache Control>> for further |
| details. |
| * Allocating, freeing, and managing memory. |
| See <<memory,Memory Allocation>> and <<resources,Resource Creation>> for |
| further details. |
| * Creation and destruction of command buffers and command buffer pools. |
| See <<commandbuffers,Command Buffers>> for further details. |
| * Creation, destruction, and management of graphics state. |
| See <<pipelines,Pipelines>> and <<descriptorsets,Resource Descriptors>>, |
| among others, for further details. |
| |
| |
| [[devsandqueues-lost-device]] |
| === Lost Device |
| |
| A logical device may: become _lost_ for a number of implementation-specific |
| reasons, indicating that pending and future command execution may: fail and |
| cause resources and backing memory to become undefined:. |
| |
| ifdef::VKSC_VERSION_1_0[] |
| [NOTE] |
| .Note |
| ==== |
| <<fault-handling>> can be used by the implementation to provide more |
| information on the cause of a device becoming _lost_. |
| Allowing applications to take appropriate corrective behavior for the cause |
| of the device lost. |
| ==== |
| endif::VKSC_VERSION_1_0[] |
| |
| [NOTE] |
| .Note |
| ==== |
| Typical reasons for device loss will include things like execution timing |
| out (to prevent denial of service), power management events, platform |
| resource management, implementation errors. |
| |
| Applications not adhering to <<fundamentals-validusage, valid usage>> may |
| also result in device loss being reported, however this is not guaranteed. |
| Even if device loss is reported, the system may be in an unrecoverable |
| state, and further usage of the API is still considered invalid. |
| ==== |
| |
| When this happens, certain commands will return ename:VK_ERROR_DEVICE_LOST. |
| After any such event, the logical device is considered _lost_. |
| It is not possible to reset the logical device to a non-lost state, however |
| the lost state is specific to a logical device (sname:VkDevice), and the |
| corresponding physical device (sname:VkPhysicalDevice) may: be otherwise |
| unaffected. |
| |
| In some cases, the physical device may: also be lost, and attempting to |
| create a new logical device will fail, returning ename:VK_ERROR_DEVICE_LOST. |
| This is usually indicative of a problem with the underlying implementation, |
| or its connection to the host. |
| If the physical device has not been lost, and a new logical device is |
| successfully created from that physical device, it must: be in the non-lost |
| state. |
| |
| [NOTE] |
| .Note |
| ==== |
| Whilst logical device loss may: be recoverable, in the case of physical |
| device loss, it is unlikely that an application will be able to recover |
| unless additional, unaffected physical devices exist on the system. |
| The error is largely informational and intended only to inform the user that |
| a platform issue has occurred, and should: be investigated further. |
| For example, underlying hardware may: have developed a fault or become |
| physically disconnected from the rest of the system. |
| In many cases, physical device loss may: cause other more serious issues |
| such as the operating system crashing; in which case it may: not be reported |
| via the Vulkan API. |
| ==== |
| |
| When a device is lost, its child objects are not implicitly destroyed and |
| their handles are still valid. |
| Those objects must: still be destroyed before their parents or the device |
| can: be destroyed (see the <<fundamentals-objectmodel-lifetime,Object |
| Lifetime>> section). |
| The host address space corresponding to device memory mapped using |
| flink:vkMapMemory is still valid, and host memory accesses to these mapped |
| regions are still valid, but the contents are undefined:. |
| It is still legal to call any API command on the device and child objects. |
| |
| Once a device is lost, command execution may: fail, and certain commands |
| that return a elink:VkResult may: return ename:VK_ERROR_DEVICE_LOST. |
| These commands can be identified by the inclusion of |
| ename:VK_ERROR_DEVICE_LOST in the Return Codes section for each command. |
| Commands that do not allow runtime errors must: still operate correctly for |
| valid usage and, if applicable, return valid data. |
| |
| Commands that wait indefinitely for device execution (namely |
| flink:vkDeviceWaitIdle, flink:vkQueueWaitIdle, flink:vkWaitForFences |
| ifdef::VK_KHR_swapchain[] |
| or flink:vkAcquireNextImageKHR |
| endif::VK_KHR_swapchain[] |
| with a maximum pname:timeout, and flink:vkGetQueryPoolResults with the |
| ename:VK_QUERY_RESULT_WAIT_BIT bit set in pname:flags) must: return in |
| finite time even in the case of a lost device, and return either |
| ename:VK_SUCCESS or ename:VK_ERROR_DEVICE_LOST. |
| For any command that may: return ename:VK_ERROR_DEVICE_LOST, for the purpose |
| of determining whether a command buffer is in the |
| <<commandbuffers-lifecycle, pending state>>, or whether resources are |
| considered in-use by the device, a return value of |
| ename:VK_ERROR_DEVICE_LOST is equivalent to ename:VK_SUCCESS. |
| |
| ifdef::VK_KHR_maintenance5[] |
| If a device was created with the <<features-maintenance5, |
| pname:maintenance5>> feature enabled, and any device command returns |
| ename:VK_ERROR_DEVICE_LOST, then all device commands for which |
| ename:VK_ERROR_DEVICE_LOST is a valid return value and which happen-after it |
| on the same host thread must: return ename:VK_ERROR_DEVICE_LOST. |
| |
| Device commands executing on other threads must: begin returning |
| ename:VK_ERROR_DEVICE_LOST within finite time. |
| endif::VK_KHR_maintenance5[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| The content of any external memory objects that have been exported from or |
| imported to a lost device become undefined:. |
| Objects on other logical devices or in other APIs which are associated with |
| the same underlying memory resource as the external memory objects on the |
| lost device are unaffected other than their content becoming undefined:. |
| The layout of subresources of images on other logical devices that are bound |
| to sname:VkDeviceMemory objects associated with the same underlying memory |
| resources as external memory objects on the lost device becomes |
| ename:VK_IMAGE_LAYOUT_UNDEFINED. |
| |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_semaphore[] |
| |
| The state of sname:VkSemaphore objects on other logical devices created by |
| <<synchronization-semaphores-importing,importing a semaphore payload>> with |
| temporary permanence which was exported from the lost device is undefined:. |
| The state of sname:VkSemaphore objects on other logical devices that |
| permanently share a semaphore payload with a sname:VkSemaphore object on the |
| lost device is undefined:, and remains undefined: following any subsequent |
| signal operations. |
| Implementations must: ensure pending and subsequently submitted wait |
| operations on such semaphores behave as defined in |
| <<synchronization-semaphores-waiting-state,Semaphore State Requirements For |
| Wait Operations>> for external semaphores not in a valid state for a wait |
| operation. |
| |
| endif::VK_VERSION_1_1,VK_KHR_external_semaphore[] |
| |
| ifdef::editing-notes[] |
| [NOTE] |
| .editing-note |
| ==== |
| TODO (piman) - I do not think we are very clear about what "`in-use by the |
| device`" means. |
| ==== |
| endif::editing-notes[] |
| |
| |
| [[devsandqueues-destruction]] |
| === Device Destruction |
| |
| [open,refpage='vkDestroyDevice',desc='Destroy a logical device',type='protos'] |
| -- |
| To destroy a device, call: |
| |
| include::{generated}/api/protos/vkDestroyDevice.adoc[] |
| |
| * pname:device is the logical device to destroy. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| |
| To ensure that no work is active on the device, flink:vkDeviceWaitIdle can: |
| be used to gate the destruction of the device. |
| Prior to destroying a device, an application is responsible for |
| destroying/freeing any Vulkan objects that were created using that device as |
| the first parameter of the corresponding ftext:vkCreate* or |
| ftext:vkAllocate* command. |
| |
| [NOTE] |
| .Note |
| ==== |
| The lifetime of each of these objects is bound by the lifetime of the |
| sname:VkDevice object. |
| Therefore, to avoid resource leaks, it is critical that an application |
| explicitly free all of these resources prior to calling |
| fname:vkDestroyDevice. |
| ==== |
| |
| ifdef::VKSC_VERSION_1_0[] |
| If |
| slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory, |
| pname:deviceDestroyFreesMemory>> is ename:VK_TRUE, the reserved memory for |
| child objects without explicit free or destroy commands is returned to the |
| system when the device is destroyed, otherwise it may: not be returned to |
| the system until the process is terminated. |
| endif::VKSC_VERSION_1_0[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkDestroyDevice-device-05137]] |
| All child objects created on pname:device |
| ifdef::VKSC_VERSION_1_0[] |
| , except those with no explicit <<fundamentals-objectmodel-no-destroy, |
| free or destroy command>>, |
| endif::VKSC_VERSION_1_0[] |
| must: have been destroyed prior to destroying pname:device |
| ifndef::VKSC_VERSION_1_0[] |
| * [[VUID-vkDestroyDevice-device-00379]] |
| If sname:VkAllocationCallbacks were provided when pname:device was |
| created, a compatible set of callbacks must: be provided here |
| * [[VUID-vkDestroyDevice-device-00380]] |
| If no sname:VkAllocationCallbacks were provided when pname:device was |
| created, pname:pAllocator must: be `NULL` |
| endif::VKSC_VERSION_1_0[] |
| **** |
| |
| include::{generated}/validity/protos/vkDestroyDevice.adoc[] |
| -- |
| |
| |
| [[devsandqueues-queues]] |
| == Queues |
| |
| |
| [[devsandqueues-queueprops]] |
| === Queue Family Properties |
| |
| As discussed in the <<devsandqueues-physical-device-enumeration,Physical |
| Device Enumeration>> section above, the |
| flink:vkGetPhysicalDeviceQueueFamilyProperties command is used to retrieve |
| details about the queue families and queues supported by a device. |
| |
| Each index in the pname:pQueueFamilyProperties array returned by |
| flink:vkGetPhysicalDeviceQueueFamilyProperties describes a unique queue |
| family on that physical device. |
| These indices are used when creating queues, and they correspond directly |
| with the pname:queueFamilyIndex that is passed to the flink:vkCreateDevice |
| command via the slink:VkDeviceQueueCreateInfo structure as described in the |
| <<devsandqueues-queue-creation,Queue Creation>> section below. |
| |
| Grouping of queue families within a physical device is |
| implementation-dependent. |
| |
| [NOTE] |
| .Note |
| ==== |
| The general expectation is that a physical device groups all queues of |
| matching capabilities into a single family. |
| However, while implementations should: do this, it is possible that a |
| physical device may: return two separate queue families with the same |
| capabilities. |
| ==== |
| |
| Once an application has identified a physical device with the queue(s) that |
| it desires to use, it will create those queues in conjunction with a logical |
| device. |
| This is described in the following section. |
| |
| |
| [[devsandqueues-queue-creation]] |
| === Queue Creation |
| |
| [open,refpage='VkQueue',desc='Opaque handle to a queue object',type='handles'] |
| -- |
| Creating a logical device also creates the queues associated with that |
| device. |
| The queues to create are described by a set of slink:VkDeviceQueueCreateInfo |
| structures that are passed to flink:vkCreateDevice in |
| pname:pQueueCreateInfos. |
| |
| Queues are represented by sname:VkQueue handles: |
| |
| include::{generated}/api/handles/VkQueue.adoc[] |
| -- |
| |
| [open,refpage='VkDeviceQueueCreateInfo',desc='Structure specifying parameters of a newly created device queue',type='structs'] |
| -- |
| The sname:VkDeviceQueueCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceQueueCreateInfo.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| ifndef::VK_VERSION_1_1[] |
| * pname:flags is reserved for future use. |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_VERSION_1_1[] |
| * pname:flags is a bitmask indicating behavior of the queues. |
| endif::VK_VERSION_1_1[] |
| * pname:queueFamilyIndex is an unsigned integer indicating the index of |
| the queue family in which to create the queues on this device. |
| This index corresponds to the index of an element of the |
| pname:pQueueFamilyProperties array that was returned by |
| fname:vkGetPhysicalDeviceQueueFamilyProperties. |
| * pname:queueCount is an unsigned integer specifying the number of queues |
| to create in the queue family indicated by pname:queueFamilyIndex, and |
| with the behavior specified by pname:flags. |
| * pname:pQueuePriorities is a pointer to an array of pname:queueCount |
| normalized floating point values, specifying priorities of work that |
| will be submitted to each created queue. |
| See <<devsandqueues-priority,Queue Priority>> for more information. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceQueueCreateInfo-queueFamilyIndex-00381]] |
| pname:queueFamilyIndex must: be less than |
| pname:pQueueFamilyPropertyCount returned by |
| fname:vkGetPhysicalDeviceQueueFamilyProperties |
| * [[VUID-VkDeviceQueueCreateInfo-queueCount-00382]] |
| pname:queueCount must: be less than or equal to the pname:queueCount |
| member of the sname:VkQueueFamilyProperties structure, as returned by |
| fname:vkGetPhysicalDeviceQueueFamilyProperties in the |
| pname:pQueueFamilyProperties[queueFamilyIndex] |
| * [[VUID-VkDeviceQueueCreateInfo-pQueuePriorities-00383]] |
| Each element of pname:pQueuePriorities must: be between `0.0` and `1.0` |
| inclusive |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-VkDeviceQueueCreateInfo-flags-02861]] |
| If the <<features-protectedMemory, pname:protectedMemory>> feature is |
| not enabled, the ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT bit of |
| pname:flags must: not be set |
| * [[VUID-VkDeviceQueueCreateInfo-flags-06449]] |
| If pname:flags includes ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT, |
| pname:queueFamilyIndex must: be the index of a queue family that |
| includes the ename:VK_QUEUE_PROTECTED_BIT capability |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_ARM_scheduling_controls[] |
| * [[VUID-VkDeviceQueueCreateInfo-pNext-09398]] |
| If the pname:pNext chain includes a |
| slink:VkDeviceQueueShaderCoreControlCreateInfoARM structure then |
| slink:VkPhysicalDeviceSchedulingControlsPropertiesARM::pname:schedulingControlsFlags |
| must: contain |
| ename:VK_PHYSICAL_DEVICE_SCHEDULING_CONTROLS_SHADER_CORE_COUNT_ARM. |
| endif::VK_ARM_scheduling_controls[] |
| **** |
| |
| include::{generated}/validity/structs/VkDeviceQueueCreateInfo.adoc[] |
| -- |
| |
| ifdef::VK_VERSION_1_1[] |
| [open,refpage='VkDeviceQueueCreateFlagBits',desc='Bitmask specifying behavior of the queue',type='enums'] |
| -- |
| Bits which can: be set in slink:VkDeviceQueueCreateInfo::pname:flags, |
| specifying usage behavior of a queue, are: |
| |
| include::{generated}/api/enums/VkDeviceQueueCreateFlagBits.adoc[] |
| |
| * ename:VK_DEVICE_QUEUE_CREATE_PROTECTED_BIT specifies that the device |
| queue is a protected-capable queue. |
| -- |
| endif::VK_VERSION_1_1[] |
| |
| [open,refpage='VkDeviceQueueCreateFlags',desc='Bitmask of VkDeviceQueueCreateFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkDeviceQueueCreateFlags.adoc[] |
| |
| ifndef::VK_VERSION_1_1[] |
| tname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask, but is |
| currently reserved for future use. |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_VERSION_1_1[] |
| tname:VkDeviceQueueCreateFlags is a bitmask type for setting a mask of zero |
| or more elink:VkDeviceQueueCreateFlagBits. |
| endif::VK_VERSION_1_1[] |
| -- |
| |
| ifdef::VK_EXT_global_priority,VK_KHR_global_priority[] |
| [open,refpage='VkDeviceQueueGlobalPriorityCreateInfoKHR',desc='Specify a system wide priority',type='structs',alias='VkDeviceQueueGlobalPriorityCreateInfoEXT'] |
| -- |
| Queues can: be created with a system-wide priority by adding a |
| sname:VkDeviceQueueGlobalPriorityCreateInfoKHR structure to the pname:pNext |
| chain of slink:VkDeviceQueueCreateInfo. |
| |
| The sname:VkDeviceQueueGlobalPriorityCreateInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceQueueGlobalPriorityCreateInfoKHR.adoc[] |
| |
| ifdef::VK_EXT_global_priority[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkDeviceQueueGlobalPriorityCreateInfoEXT.adoc[] |
| endif::VK_EXT_global_priority[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:globalPriority is the system-wide priority associated to these |
| queues as specified by elink:VkQueueGlobalPriorityEXT |
| |
| Queues created without specifying |
| sname:VkDeviceQueueGlobalPriorityCreateInfoKHR will default to |
| ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR. |
| |
| include::{generated}/validity/structs/VkDeviceQueueGlobalPriorityCreateInfoKHR.adoc[] |
| -- |
| |
| [open,refpage='VkQueueGlobalPriorityKHR',desc='Values specifying a system-wide queue priority',type='enums',alias='VkQueueGlobalPriorityEXT'] |
| -- |
| Possible values of |
| slink:VkDeviceQueueGlobalPriorityCreateInfoKHR::pname:globalPriority, |
| specifying a system-wide priority level are: |
| |
| include::{generated}/api/enums/VkQueueGlobalPriorityKHR.adoc[] |
| |
| ifdef::VK_EXT_global_priority[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkQueueGlobalPriorityEXT.adoc[] |
| endif::VK_EXT_global_priority[] |
| |
| Priority values are sorted in ascending order. |
| A comparison operation on the enum values can be used to determine the |
| priority order. |
| |
| * ename:VK_QUEUE_GLOBAL_PRIORITY_LOW_KHR is below the system default. |
| Useful for non-interactive tasks. |
| * ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR is the system default |
| priority. |
| * ename:VK_QUEUE_GLOBAL_PRIORITY_HIGH_KHR is above the system default. |
| * ename:VK_QUEUE_GLOBAL_PRIORITY_REALTIME_KHR is the highest priority. |
| Useful for critical tasks. |
| -- |
| |
| Queues with higher system priority may: be allotted more processing time |
| than queues with lower priority. |
| An implementation may: allow a higher-priority queue to starve a |
| lower-priority queue until the higher-priority queue has no further commands |
| to execute. |
| |
| Priorities imply no ordering or scheduling constraints. |
| |
| No specific guarantees are made about higher priority queues receiving more |
| processing time or better quality of service than lower priority queues. |
| |
| The global priority level of a queue takes precedence over the per-process |
| queue priority (slink:VkDeviceQueueCreateInfo::pname:pQueuePriorities). |
| |
| Abuse of this feature may: result in starving the rest of the system of |
| implementation resources. |
| Therefore, the driver implementation may: deny requests to acquire a |
| priority above the default priority |
| (ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_KHR) if the caller does not have |
| sufficient privileges. |
| In this scenario ename:VK_ERROR_NOT_PERMITTED_KHR is returned. |
| |
| The driver implementation may: fail the queue allocation request if |
| resources required to complete the operation have been exhausted (either by |
| the same process or a different process). |
| In this scenario ename:VK_ERROR_INITIALIZATION_FAILED is returned. |
| |
| ifdef::VK_EXT_global_priority_query,VK_KHR_global_priority[] |
| If the <<features-globalPriorityQuery, pname:globalPriorityQuery>> feature |
| is enabled and the requested global priority is not reported via |
| slink:VkQueueFamilyGlobalPriorityPropertiesKHR, the driver implementation |
| must: fail the queue creation. |
| In this scenario, ename:VK_ERROR_INITIALIZATION_FAILED is returned. |
| endif::VK_EXT_global_priority_query,VK_KHR_global_priority[] |
| endif::VK_EXT_global_priority,VK_KHR_global_priority[] |
| |
| ifdef::VK_ARM_scheduling_controls[] |
| [open,refpage='VkDeviceQueueShaderCoreControlCreateInfoARM',desc='Control the number of shader cores used by queues',type='structs'] |
| -- |
| The number of shader cores used by a queue can: be controlled by adding a |
| sname:VkDeviceQueueShaderCoreControlCreateInfoARM structure to the |
| pname:pNext chain of slink:VkDeviceQueueCreateInfo structures. |
| |
| The sname:VkDeviceQueueShaderCoreControlCreateInfoARM structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkDeviceQueueShaderCoreControlCreateInfoARM.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:shaderCoreCount is the number of shader cores this queue uses. |
| |
| Queues created without specifying |
| sname:VkDeviceQueueShaderCoreControlCreateInfoARM will default to using all |
| the shader cores available. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceQueueShaderCoreControlCreateInfoARM-shaderCoreCount-09399]] |
| pname:shaderCoreCount must: be greater than 0 and less than or equal to |
| the total number of shader cores as reported via |
| slink:VkPhysicalDeviceShaderCoreBuiltinsPropertiesARM::pname:shaderCoreCount. |
| **** |
| |
| include::{generated}/validity/structs/VkDeviceQueueShaderCoreControlCreateInfoARM.adoc[] |
| -- |
| endif::VK_ARM_scheduling_controls[] |
| |
| [open,refpage='vkGetDeviceQueue',desc='Get a queue handle from a device',type='protos'] |
| -- |
| To retrieve a handle to a slink:VkQueue object, call: |
| |
| include::{generated}/api/protos/vkGetDeviceQueue.adoc[] |
| |
| * pname:device is the logical device that owns the queue. |
| * pname:queueFamilyIndex is the index of the queue family to which the |
| queue belongs. |
| * pname:queueIndex is the index within this queue family of the queue to |
| retrieve. |
| * pname:pQueue is a pointer to a slink:VkQueue object that will be filled |
| with the handle for the requested queue. |
| |
| ifdef::VK_VERSION_1_1[] |
| fname:vkGetDeviceQueue must: only be used to get queues that were created |
| with the pname:flags parameter of slink:VkDeviceQueueCreateInfo set to zero. |
| To get queues that were created with a non-zero pname:flags parameter use |
| flink:vkGetDeviceQueue2. |
| endif::VK_VERSION_1_1[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetDeviceQueue-queueFamilyIndex-00384]] |
| pname:queueFamilyIndex must: be one of the queue family indices |
| specified when pname:device was created, via the |
| slink:VkDeviceQueueCreateInfo structure |
| * [[VUID-vkGetDeviceQueue-queueIndex-00385]] |
| pname:queueIndex must: be less than the value of |
| slink:VkDeviceQueueCreateInfo::pname:queueCount for the queue family |
| indicated by pname:queueFamilyIndex when pname:device was created |
| * [[VUID-vkGetDeviceQueue-flags-01841]] |
| slink:VkDeviceQueueCreateInfo::pname:flags must: have been set to zero |
| when pname:device was created |
| **** |
| |
| include::{generated}/validity/protos/vkGetDeviceQueue.adoc[] |
| -- |
| |
| ifdef::VK_VERSION_1_1[] |
| [open,refpage='vkGetDeviceQueue2',desc='Get a queue handle from a device',type='protos'] |
| -- |
| To retrieve a handle to a slink:VkQueue object with specific |
| tlink:VkDeviceQueueCreateFlags creation flags, call: |
| |
| include::{generated}/api/protos/vkGetDeviceQueue2.adoc[] |
| |
| * pname:device is the logical device that owns the queue. |
| * pname:pQueueInfo is a pointer to a slink:VkDeviceQueueInfo2 structure, |
| describing parameters of the device queue to be retrieved. |
| * pname:pQueue is a pointer to a slink:VkQueue object that will be filled |
| with the handle for the requested queue. |
| |
| include::{generated}/validity/protos/vkGetDeviceQueue2.adoc[] |
| -- |
| |
| [open,refpage='VkDeviceQueueInfo2',desc='Structure specifying the parameters used for device queue creation',type='structs'] |
| -- |
| The sname:VkDeviceQueueInfo2 structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceQueueInfo2.adoc[] |
| |
| * pname:sType is a elink:VkStructureType value identifying this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| The pname:pNext chain of sname:VkDeviceQueueInfo2 can: be used to |
| provide additional device queue parameters to fname:vkGetDeviceQueue2. |
| * pname:flags is a tlink:VkDeviceQueueCreateFlags value indicating the |
| flags used to create the device queue. |
| * pname:queueFamilyIndex is the index of the queue family to which the |
| queue belongs. |
| * pname:queueIndex is the index of the queue to retrieve from within the |
| set of queues that share both the queue family and flags specified. |
| |
| The queue returned by fname:vkGetDeviceQueue2 must: have the same |
| pname:flags value from this structure as that used at device creation time |
| in a slink:VkDeviceQueueCreateInfo structure. |
| |
| [NOTE] |
| .Note |
| ==== |
| Normally, if you create both protected-capable and non-protected-capable |
| queues with the same family, they are treated as separate lists of queues |
| and pname:queueIndex is relative to the start of the list of queues |
| specified by both pname:queueFamilyIndex and pname:flags. |
| However, for historical reasons, some implementations may exhibit different |
| behavior. |
| These divergent implementations instead concatenate the lists of queues and |
| treat pname:queueIndex as relative to the start of the first list of queues |
| with the given pname:queueFamilyIndex. |
| This only matters in cases where an application has created both |
| protected-capable and non-protected-capable queues from the same queue |
| family. |
| |
| For such divergent implementations, the maximum value of pname:queueIndex is |
| equal to the sum of slink:VkDeviceQueueCreateInfo::pname:queueCount minus |
| one, for all slink:VkDeviceQueueCreateInfo structures that share a common |
| pname:queueFamilyIndex. |
| |
| Such implementations will return `NULL` for either the protected or |
| unprotected queues when calling `vkGetDeviceQueue2` with pname:queueIndex in |
| the range zero to slink:VkDeviceQueueCreateInfo::pname:queueCount minus one. |
| In cases where these implementations returned `NULL`, the corresponding |
| queues are instead located in the extended range described in the preceding |
| two paragraphs. |
| |
| This behaviour will not be observed on any driver that has passed Vulkan |
| conformance test suite version 1.3.3.0, or any subsequent version. |
| This information can be found by querying |
| sname:VkPhysicalDeviceDriverProperties::pname:conformanceVersion. |
| ==== |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceQueueInfo2-queueFamilyIndex-01842]] |
| pname:queueFamilyIndex must: be one of the queue family indices |
| specified when pname:device was created, via the |
| slink:VkDeviceQueueCreateInfo structure |
| * [[VUID-VkDeviceQueueInfo2-flags-06225]] |
| pname:flags must: be equal to slink:VkDeviceQueueCreateInfo::pname:flags |
| for a slink:VkDeviceQueueCreateInfo structure for the queue family |
| indicated by pname:queueFamilyIndex when pname:device was created |
| * [[VUID-VkDeviceQueueInfo2-queueIndex-01843]] |
| pname:queueIndex must: be less than |
| slink:VkDeviceQueueCreateInfo::pname:queueCount for the corresponding |
| queue family and flags indicated by pname:queueFamilyIndex and |
| pname:flags when pname:device was created |
| **** |
| |
| include::{generated}/validity/structs/VkDeviceQueueInfo2.adoc[] |
| -- |
| endif::VK_VERSION_1_1[] |
| |
| |
| [[devsandqueues-index]] |
| === Queue Family Index |
| |
| The queue family index is used in multiple places in Vulkan in order to tie |
| operations to a specific family of queues. |
| |
| When retrieving a handle to the queue via fname:vkGetDeviceQueue, the queue |
| family index is used to select which queue family to retrieve the |
| sname:VkQueue handle from as described in the previous section. |
| |
| When creating a sname:VkCommandPool object (see |
| <<commandbuffers-pools,Command Pools>>), a queue family index is specified |
| in the slink:VkCommandPoolCreateInfo structure. |
| Command buffers from this pool can: only be submitted on queues |
| corresponding to this queue family. |
| |
| When creating sname:VkImage (see <<resources-images,Images>>) and |
| sname:VkBuffer (see <<resources-buffers,Buffers>>) resources, a set of queue |
| families is included in the slink:VkImageCreateInfo and |
| slink:VkBufferCreateInfo structures to specify the queue families that can: |
| access the resource. |
| |
| When inserting a slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier |
| (see <<synchronization-pipeline-barriers>>), a source and destination queue |
| family index is specified to allow the ownership of a buffer or image to be |
| transferred from one queue family to another. |
| See the <<resources-sharing,Resource Sharing>> section for details. |
| |
| |
| [[devsandqueues-priority]] |
| === Queue Priority |
| |
| Each queue is assigned a priority, as set in the |
| slink:VkDeviceQueueCreateInfo structures when creating the device. |
| The priority of each queue is a normalized floating point value between 0.0 |
| and 1.0, which is then translated to a discrete priority level by the |
| implementation. |
| Higher values indicate a higher priority, with 0.0 being the lowest priority |
| and 1.0 being the highest. |
| |
| Within the same device, queues with higher priority may: be allotted more |
| processing time than queues with lower priority. |
| The implementation makes no guarantees with regards to ordering or |
| scheduling among queues with the same priority, other than the constraints |
| defined by any <<synchronization, explicit synchronization primitives>>. |
| The implementation makes no guarantees with regards to queues across |
| different devices. |
| |
| An implementation may: allow a higher-priority queue to starve a |
| lower-priority queue on the same sname:VkDevice until the higher-priority |
| queue has no further commands to execute. |
| The relationship of queue priorities must: not cause queues on one |
| sname:VkDevice to starve queues on another sname:VkDevice. |
| |
| No specific guarantees are made about higher priority queues receiving more |
| processing time or better quality of service than lower priority queues. |
| |
| |
| [[devsandqueues-submission]] |
| === Queue Submission |
| |
| Work is submitted to a queue via _queue submission_ commands such as |
| ifdef::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| flink:vkQueueSubmit2 or |
| endif::VK_VERSION_1_3,VK_KHR_synchronization2[] |
| flink:vkQueueSubmit. |
| Queue submission commands define a set of _queue operations_ to be executed |
| by the underlying physical device, including synchronization with semaphores |
| and fences. |
| |
| Submission commands take as parameters a target queue, zero or more |
| _batches_ of work, and an optional: fence to signal upon completion. |
| Each batch consists of three distinct parts: |
| |
| . Zero or more semaphores to wait on before execution of the rest of the |
| batch. |
| ** If present, these describe a <<synchronization-semaphores-waiting, |
| semaphore wait operation>>. |
| . Zero or more work items to execute. |
| ** If present, these describe a _queue operation_ matching the work |
| described. |
| . Zero or more semaphores to signal upon completion of the work items. |
| ** If present, these describe a <<synchronization-semaphores-signaling, |
| semaphore signal operation>>. |
| |
| If a fence is present in a queue submission, it describes a |
| <<synchronization-fences-signaling, fence signal operation>>. |
| |
| All work described by a queue submission command must: be submitted to the |
| queue before the command returns. |
| |
| |
| ifndef::VKSC_VERSION_1_0[] |
| [[devsandqueues-sparsebinding]] |
| ==== Sparse Memory Binding |
| |
| In Vulkan it is possible to sparsely bind memory to buffers and images as |
| described in the <<sparsememory,Sparse Resource>> chapter. |
| Sparse memory binding is a queue operation. |
| A queue whose flags include the ename:VK_QUEUE_SPARSE_BINDING_BIT must: be |
| able to support the mapping of a virtual address to a physical address on |
| the device. |
| This causes an update to the page table mappings on the device. |
| This update must: be synchronized on a queue to avoid corrupting page table |
| mappings during execution of graphics commands. |
| By binding the sparse memory resources on queues, all commands that are |
| dependent on the updated bindings are synchronized to only execute after the |
| binding is updated. |
| See the <<synchronization,Synchronization and Cache Control>> chapter for |
| how this synchronization is accomplished. |
| |
| endif::VKSC_VERSION_1_0[] |
| |
| [[devsandqueues-queuedestruction]] |
| === Queue Destruction |
| |
| Queues are created along with a logical device during fname:vkCreateDevice. |
| All queues associated with a logical device are destroyed when |
| fname:vkDestroyDevice is called on that device. |
