| // Copyright 2015-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| [[resources]] |
| = Resource Creation |
| |
| Vulkan supports two primary resource types: _buffers_ and _images_. |
| Resources are views of memory with associated formatting and dimensionality. |
| Buffers are essentially unformatted arrays of bytes whereas images contain |
| format information, can: be multidimensional and may: have associated |
| metadata. |
| |
| |
| [[resources-buffers]] |
| == Buffers |
| |
| [open,refpage='VkBuffer',desc='Opaque handle to a buffer object',type='handles'] |
| -- |
| Buffers represent linear arrays of data which are used for various purposes |
| by binding them to a graphics or compute pipeline via descriptor sets or via |
| certain commands, or by directly specifying them as parameters to certain |
| commands. |
| |
| Buffers are represented by sname:VkBuffer handles: |
| |
| include::{generated}/api/handles/VkBuffer.txt[] |
| -- |
| |
| [open,refpage='vkCreateBuffer',desc='Create a new buffer object',type='protos'] |
| -- |
| To create buffers, call: |
| |
| include::{generated}/api/protos/vkCreateBuffer.txt[] |
| |
| * pname:device is the logical device that creates the buffer object. |
| * pname:pCreateInfo is a pointer to a slink:VkBufferCreateInfo structure |
| containing parameters affecting creation of the buffer. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pBuffer is a pointer to a slink:VkBuffer handle in which the |
| resulting buffer object is returned. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCreateBuffer-flags-00911]] |
| If the pname:flags member of pname:pCreateInfo includes |
| ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, creating this sname:VkBuffer |
| must: not cause the total required sparse memory for all currently valid |
| sparse resources on the device to exceed |
| sname:VkPhysicalDeviceLimits::pname:sparseAddressSpaceSize |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| * [[VUID-vkCreateBuffer-pNext-06387]] |
| If using the slink:VkBuffer for an import operation from a |
| slink:VkBufferCollectionFUCHSIA where a |
| slink:VkBufferCollectionBufferCreateInfoFUCHSIA has been chained to |
| pname:pNext, pname:pCreateInfo must: match the |
| slink:VkBufferConstraintsInfoFUCHSIA::pname:createInfo used when setting |
| the constraints on the buffer collection with |
| flink:vkSetBufferCollectionBufferConstraintsFUCHSIA |
| endif::VK_FUCHSIA_buffer_collection[] |
| **** |
| |
| include::{generated}/validity/protos/vkCreateBuffer.txt[] |
| -- |
| |
| [open,refpage='VkBufferCreateInfo',desc='Structure specifying the parameters of a newly created buffer object',type='structs'] |
| -- |
| The sname:VkBufferCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkBufferCreateFlagBits specifying |
| additional parameters of the buffer. |
| * pname:size is the size in bytes of the buffer to be created. |
| * pname:usage is a bitmask of elink:VkBufferUsageFlagBits specifying |
| allowed usages of the buffer. |
| * pname:sharingMode is a elink:VkSharingMode value specifying the sharing |
| mode of the buffer when it will be accessed by multiple queue families. |
| * pname:queueFamilyIndexCount is the number of entries in the |
| pname:pQueueFamilyIndices array. |
| * pname:pQueueFamilyIndices is a pointer to an array of queue families |
| that will access this buffer. |
| It is ignored if pname:sharingMode is not |
| ename:VK_SHARING_MODE_CONCURRENT. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBufferCreateInfo-size-00912]] |
| pname:size must: be greater than `0` |
| * [[VUID-VkBufferCreateInfo-sharingMode-00913]] |
| If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, |
| pname:pQueueFamilyIndices must: be a valid pointer to an array of |
| pname:queueFamilyIndexCount code:uint32_t values |
| * [[VUID-VkBufferCreateInfo-sharingMode-00914]] |
| If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, |
| pname:queueFamilyIndexCount must: be greater than `1` |
| ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| * [[VUID-VkBufferCreateInfo-sharingMode-01391]] |
| If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element |
| of pname:pQueueFamilyIndices must: be unique and must: be less than |
| pname:pQueueFamilyPropertyCount returned by |
| flink:vkGetPhysicalDeviceQueueFamilyProperties for the |
| pname:physicalDevice that was used to create pname:device |
| endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| * [[VUID-VkBufferCreateInfo-sharingMode-01419]] |
| If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element |
| of pname:pQueueFamilyIndices must: be unique and must: be less than |
| pname:pQueueFamilyPropertyCount returned by either |
| flink:vkGetPhysicalDeviceQueueFamilyProperties or |
| flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the |
| pname:physicalDevice that was used to create pname:device |
| endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| * [[VUID-VkBufferCreateInfo-flags-00915]] |
| If the <<features-sparseBinding,sparse bindings>> feature is not |
| enabled, pname:flags must: not contain |
| ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT |
| * [[VUID-VkBufferCreateInfo-flags-00916]] |
| If the <<features-sparseResidencyBuffer,sparse buffer residency>> |
| feature is not enabled, pname:flags must: not contain |
| ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT |
| * [[VUID-VkBufferCreateInfo-flags-00917]] |
| If the <<features-sparseResidencyAliased,sparse aliased residency>> |
| feature is not enabled, pname:flags must: not contain |
| ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT |
| * [[VUID-VkBufferCreateInfo-flags-00918]] |
| If pname:flags contains ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT or |
| ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT, it must: also contain |
| ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| * [[VUID-VkBufferCreateInfo-pNext-00920]] |
| If the pname:pNext chain includes a |
| slink:VkExternalMemoryBufferCreateInfo structure, its pname:handleTypes |
| member must: only contain bits that are also in |
| slink:VkExternalBufferProperties::pname:externalMemoryProperties.compatibleHandleTypes, |
| as returned by flink:vkGetPhysicalDeviceExternalBufferProperties with |
| pname:pExternalBufferInfo->handleType equal to any one of the handle |
| types specified in |
| slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-VkBufferCreateInfo-flags-01887]] |
| If the protected memory feature is not enabled, pname:flags must: not |
| contain ename:VK_BUFFER_CREATE_PROTECTED_BIT |
| * [[VUID-VkBufferCreateInfo-None-01888]] |
| If any of the bits ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, |
| ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or |
| ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT are set, |
| ename:VK_BUFFER_CREATE_PROTECTED_BIT must: not also be set |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_NV_dedicated_allocation[] |
| * [[VUID-VkBufferCreateInfo-pNext-01571]] |
| If the pname:pNext chain includes a |
| slink:VkDedicatedAllocationBufferCreateInfoNV structure, and the |
| pname:dedicatedAllocation member of the chained structure is |
| ename:VK_TRUE, then pname:flags must: not include |
| ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT, |
| ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or |
| ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT |
| endif::VK_NV_dedicated_allocation[] |
| ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] |
| ifdef::VK_EXT_buffer_device_address[] |
| * [[VUID-VkBufferCreateInfo-deviceAddress-02604]] |
| If slink:VkBufferDeviceAddressCreateInfoEXT::pname:deviceAddress is not |
| zero, pname:flags must: include |
| ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT |
| endif::VK_EXT_buffer_device_address[] |
| ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| * [[VUID-VkBufferCreateInfo-opaqueCaptureAddress-03337]] |
| If |
| slink:VkBufferOpaqueCaptureAddressCreateInfo::pname:opaqueCaptureAddress |
| is not zero, pname:flags must: include |
| ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT |
| endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| * [[VUID-VkBufferCreateInfo-flags-03338]] |
| If pname:flags includes |
| ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, the |
| <<features-bufferDeviceAddressCaptureReplay,bufferDeviceAddressCaptureReplay>> |
| or |
| <<features-bufferDeviceAddressCaptureReplayEXT,sname:VkPhysicalDeviceBufferDeviceAddressFeaturesEXT::pname:bufferDeviceAddressCaptureReplay>> |
| feature must: be enabled |
| endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] |
| ifdef::VK_KHR_video_decode_queue[] |
| * [[VUID-VkBufferCreateInfo-usage-04813]] |
| If pname:usage includes ename:VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR, |
| ename:VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR, then the pname:pNext |
| chain must: include a valid slink:VkVideoProfilesKHR structure which |
| includes at least one slink:VkVideoProfileKHR with a decode |
| codec-operation |
| endif::VK_KHR_video_decode_queue[] |
| ifdef::VK_KHR_video_encode_queue[] |
| * [[VUID-VkBufferCreateInfo-usage-04814]] |
| If pname:usage includes ename:VK_BUFFER_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, |
| ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR, then the pname:pNext |
| chain must: include a valid slink:VkVideoProfilesKHR structure which |
| includes at least one slink:VkVideoProfileKHR with a encode |
| codec-operation |
| endif::VK_KHR_video_encode_queue[] |
| ifdef::VK_KHR_maintenance4[] |
| * [[VUID-VkBufferCreateInfo-size-06409]] |
| pname:size must: be less than or equal to |
| slink:VkPhysicalDeviceMaintenance4PropertiesKHR::pname:maxBufferSize |
| endif::VK_KHR_maintenance4[] |
| **** |
| |
| include::{generated}/validity/structs/VkBufferCreateInfo.txt[] |
| -- |
| |
| [open,refpage='VkBufferUsageFlagBits',desc='Bitmask specifying allowed usage of a buffer',type='enums'] |
| -- |
| Bits which can: be set in slink:VkBufferCreateInfo::pname:usage, specifying |
| usage behavior of a buffer, are: |
| |
| include::{generated}/api/enums/VkBufferUsageFlagBits.txt[] |
| |
| * ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT specifies that the buffer can: be |
| used as the source of a _transfer command_ (see the definition of |
| <<synchronization-pipeline-stages-transfer, |
| ename:VK_PIPELINE_STAGE_TRANSFER_BIT>>). |
| * ename:VK_BUFFER_USAGE_TRANSFER_DST_BIT specifies that the buffer can: be |
| used as the destination of a transfer command. |
| * ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT specifies that the buffer |
| can: be used to create a sname:VkBufferView suitable for occupying a |
| sname:VkDescriptorSet slot of type |
| ename:VK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER. |
| * ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT specifies that the buffer |
| can: be used to create a sname:VkBufferView suitable for occupying a |
| sname:VkDescriptorSet slot of type |
| ename:VK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER. |
| * ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT specifies that the buffer can: |
| be used in a sname:VkDescriptorBufferInfo suitable for occupying a |
| sname:VkDescriptorSet slot either of type |
| ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER or |
| ename:VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC. |
| * ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT specifies that the buffer can: |
| be used in a sname:VkDescriptorBufferInfo suitable for occupying a |
| sname:VkDescriptorSet slot either of type |
| ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER or |
| ename:VK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC. |
| * ename:VK_BUFFER_USAGE_INDEX_BUFFER_BIT specifies that the buffer is |
| suitable for passing as the pname:buffer parameter to |
| flink:vkCmdBindIndexBuffer. |
| * ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT specifies that the buffer is |
| suitable for passing as an element of the pname:pBuffers array to |
| flink:vkCmdBindVertexBuffers. |
| * ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT specifies that the buffer is |
| suitable for passing as the pname:buffer parameter to |
| flink:vkCmdDrawIndirect, flink:vkCmdDrawIndexedIndirect, |
| ifdef::VK_NV_mesh_shader[] |
| flink:vkCmdDrawMeshTasksIndirectNV, |
| flink:vkCmdDrawMeshTasksIndirectCountNV, |
| endif::VK_NV_mesh_shader[] |
| or flink:vkCmdDispatchIndirect. |
| ifdef::VK_NV_device_generated_commands[] |
| It is also suitable for passing as the pname:buffer member of |
| sname:VkIndirectCommandsStreamNV, or pname:sequencesCountBuffer or |
| pname:sequencesIndexBuffer or pname:preprocessedBuffer member of |
| sname:VkGeneratedCommandsInfoNV |
| endif::VK_NV_device_generated_commands[] |
| ifdef::VK_EXT_conditional_rendering[] |
| * ename:VK_BUFFER_USAGE_CONDITIONAL_RENDERING_BIT_EXT specifies that the |
| buffer is suitable for passing as the pname:buffer parameter to |
| flink:vkCmdBeginConditionalRenderingEXT. |
| endif::VK_EXT_conditional_rendering[] |
| ifdef::VK_EXT_transform_feedback[] |
| * ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_BUFFER_BIT_EXT specifies that |
| the buffer is suitable for using for binding as a transform feedback |
| buffer with flink:vkCmdBindTransformFeedbackBuffersEXT. |
| * ename:VK_BUFFER_USAGE_TRANSFORM_FEEDBACK_COUNTER_BUFFER_BIT_EXT |
| specifies that the buffer is suitable for using as a counter buffer with |
| flink:vkCmdBeginTransformFeedbackEXT and |
| flink:vkCmdEndTransformFeedbackEXT. |
| endif::VK_EXT_transform_feedback[] |
| ifdef::VK_NV_ray_tracing[] |
| * ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV specifies that the buffer is |
| suitable for use in flink:vkCmdTraceRaysNV. |
| endif::VK_NV_ray_tracing[] |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| * ename:VK_BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR specifies that the |
| buffer is suitable for use as a <<shader-binding-table,Shader Binding |
| Table>>. |
| endif::VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_KHR_acceleration_structure[] |
| * ename:VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_BUILD_INPUT_READ_ONLY_BIT_KHR |
| specifies that the buffer is suitable for use as a read-only input to an |
| <<acceleration-structure-building,acceleration structure build>>. |
| * ename:VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR specifies |
| that the buffer is suitable for storage space for a |
| slink:VkAccelerationStructureKHR. |
| endif::VK_KHR_acceleration_structure[] |
| ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] |
| * ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT specifies that the |
| buffer can: be used to retrieve a buffer device address via |
| flink:vkGetBufferDeviceAddress and use that address to access the |
| buffer's memory from a shader. |
| endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] |
| ifdef::VK_KHR_video_decode_queue[] |
| * ename:VK_BUFFER_USAGE_VIDEO_DECODE_SRC_BIT_KHR specifies that the buffer |
| can: be used as the source bitstream buffer in a |
| <<video-decode-operations, video decode operation>>. |
| * ename:VK_BUFFER_USAGE_VIDEO_DECODE_DST_BIT_KHR specifies that the buffer |
| can: be used as the destination status buffer in a |
| <<video-decode-operations, video decode operation>>. |
| endif::VK_KHR_video_decode_queue[] |
| ifdef::VK_KHR_video_encode_queue[] |
| * ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR specifies that the buffer |
| can: be used as the destination bitstream buffer in a |
| <<video-encode-operations, video encode operation>>. |
| * ename:VK_BUFFER_USAGE_VIDEO_ENCODE_DST_BIT_KHR specifies that the buffer |
| can: be used as the destination status buffer in a |
| <<video-encode-operations, video encode operation>>. |
| endif::VK_KHR_video_encode_queue[] |
| -- |
| |
| [open,refpage='VkBufferUsageFlags',desc='Bitmask of VkBufferUsageFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkBufferUsageFlags.txt[] |
| |
| tname:VkBufferUsageFlags is a bitmask type for setting a mask of zero or |
| more elink:VkBufferUsageFlagBits. |
| -- |
| |
| [open,refpage='VkBufferCreateFlagBits',desc='Bitmask specifying additional parameters of a buffer',type='enums'] |
| -- |
| Bits which can: be set in slink:VkBufferCreateInfo::pname:flags, specifying |
| additional parameters of a buffer, are: |
| |
| include::{generated}/api/enums/VkBufferCreateFlagBits.txt[] |
| |
| * ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT specifies that the buffer will |
| be backed using sparse memory binding. |
| * ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT specifies that the buffer |
| can: be partially backed using sparse memory binding. |
| Buffers created with this flag must: also be created with the |
| ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag. |
| * ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT specifies that the buffer will |
| be backed using sparse memory binding with memory ranges that might also |
| simultaneously be backing another buffer (or another portion of the same |
| buffer). |
| Buffers created with this flag must: also be created with the |
| ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag. |
| ifdef::VK_VERSION_1_1[] |
| * ename:VK_BUFFER_CREATE_PROTECTED_BIT specifies that the buffer is a |
| protected buffer. |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] |
| * ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT specifies that |
| the buffer's address can: be saved and reused on a subsequent run (e.g. |
| for trace capture and replay), see |
| slink:VkBufferOpaqueCaptureAddressCreateInfo for more detail. |
| endif::VK_VERSION_1_2,VK_EXT_buffer_device_address,VK_KHR_buffer_device_address[] |
| |
| See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and |
| <<features,Physical Device Features>> for details of the sparse memory |
| features supported on a device. |
| -- |
| |
| [open,refpage='VkBufferCreateFlags',desc='Bitmask of VkBufferCreateFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkBufferCreateFlags.txt[] |
| |
| tname:VkBufferCreateFlags is a bitmask type for setting a mask of zero or |
| more elink:VkBufferCreateFlagBits. |
| -- |
| |
| ifdef::VK_NV_dedicated_allocation[] |
| [open,refpage='VkDedicatedAllocationBufferCreateInfoNV',desc='Specify that a buffer is bound to a dedicated memory resource',type='structs'] |
| -- |
| If the pname:pNext chain includes a |
| sname:VkDedicatedAllocationBufferCreateInfoNV structure, then that structure |
| includes an enable controlling whether the buffer will have a dedicated |
| memory allocation bound to it. |
| |
| The sname:VkDedicatedAllocationBufferCreateInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:dedicatedAllocation specifies whether the buffer will have a |
| dedicated allocation bound to it. |
| |
| include::{generated}/validity/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[] |
| -- |
| endif::VK_NV_dedicated_allocation[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| [open,refpage='VkExternalMemoryBufferCreateInfo',desc='Specify that a buffer may be backed by external memory',type='structs'] |
| -- |
| To define a set of external memory handle types that may: be used as backing |
| store for a buffer, add a slink:VkExternalMemoryBufferCreateInfo structure |
| to the pname:pNext chain of the slink:VkBufferCreateInfo structure. |
| The sname:VkExternalMemoryBufferCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkExternalMemoryBufferCreateInfo.txt[] |
| |
| ifdef::VK_KHR_external_memory[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkExternalMemoryBufferCreateInfoKHR.txt[] |
| endif::VK_KHR_external_memory[] |
| |
| [NOTE] |
| .Note |
| ==== |
| A sname:VkExternalMemoryBufferCreateInfo structure with a non-zero |
| pname:handleTypes field must be included in the creation parameters for a |
| buffer that will be bound to memory that is either exported or imported. |
| ==== |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:handleTypes is zero, or a bitmask of |
| elink:VkExternalMemoryHandleTypeFlagBits specifying one or more external |
| memory handle types. |
| |
| include::{generated}/validity/structs/VkExternalMemoryBufferCreateInfo.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| [open,refpage='VkBufferOpaqueCaptureAddressCreateInfo',desc='Request a specific address for a buffer',type='structs',alias='VkBufferOpaqueCaptureAddressCreateInfoKHR'] |
| -- |
| To request a specific device address for a buffer, add a |
| slink:VkBufferOpaqueCaptureAddressCreateInfo structure to the pname:pNext |
| chain of the slink:VkBufferCreateInfo structure. |
| The sname:VkBufferOpaqueCaptureAddressCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferOpaqueCaptureAddressCreateInfo.txt[] |
| |
| ifdef::VK_KHR_buffer_device_address[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkBufferOpaqueCaptureAddressCreateInfoKHR.txt[] |
| endif::VK_KHR_buffer_device_address[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:opaqueCaptureAddress is the opaque capture address requested for |
| the buffer. |
| |
| If pname:opaqueCaptureAddress is zero, no specific address is requested. |
| |
| If pname:opaqueCaptureAddress is not zero, then it should: be an address |
| retrieved from flink:vkGetBufferOpaqueCaptureAddress for an identically |
| created buffer on the same implementation. |
| |
| If this structure is not present, it is as if pname:opaqueCaptureAddress is |
| zero. |
| |
| Apps should: avoid creating buffers with app-provided addresses and |
| implementation-provided addresses in the same process, to reduce the |
| likelihood of ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS errors. |
| |
| [NOTE] |
| .Note |
| ==== |
| The expected usage for this is that a trace capture/replay tool will add the |
| ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers |
| that use ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and during capture |
| will save the queried opaque device addresses in the trace. |
| During replay, the buffers will be created specifying the original address |
| so any address values stored in the trace data will remain valid. |
| |
| Implementations are expected to separate such buffers in the GPU address |
| space so normal allocations will avoid using these addresses. |
| Apps/tools should avoid mixing app-provided and implementation-provided |
| addresses for buffers created with |
| ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address |
| space allocation conflicts. |
| ==== |
| |
| include::{generated}/validity/structs/VkBufferOpaqueCaptureAddressCreateInfo.txt[] |
| -- |
| endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| |
| ifdef::VK_EXT_buffer_device_address[] |
| [open,refpage='VkBufferDeviceAddressCreateInfoEXT',desc='Request a specific address for a buffer',type='structs'] |
| -- |
| ifdef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| Alternatively, to |
| endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| ifndef::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| To |
| endif::VK_VERSION_1_2,VK_KHR_buffer_device_address[] |
| request a specific device address for a buffer, add a |
| slink:VkBufferDeviceAddressCreateInfoEXT structure to the pname:pNext chain |
| of the slink:VkBufferCreateInfo structure. |
| The sname:VkBufferDeviceAddressCreateInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferDeviceAddressCreateInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:deviceAddress is the device address requested for the buffer. |
| |
| If pname:deviceAddress is zero, no specific address is requested. |
| |
| If pname:deviceAddress is not zero, then it must: be an address retrieved |
| from an identically created buffer on the same implementation. |
| The buffer must: also be bound to an identically created |
| sname:VkDeviceMemory object. |
| |
| If this structure is not present, it is as if pname:deviceAddress is zero. |
| |
| Apps should: avoid creating buffers with app-provided addresses and |
| implementation-provided addresses in the same process, to reduce the |
| likelihood of ename:VK_ERROR_INVALID_DEVICE_ADDRESS_EXT errors. |
| |
| include::{generated}/validity/structs/VkBufferDeviceAddressCreateInfoEXT.txt[] |
| -- |
| endif::VK_EXT_buffer_device_address[] |
| |
| |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| [open,refpage='VkBufferCollectionBufferCreateInfoFUCHSIA',desc='Create a VkBufferCollectionFUCHSIA-compatible VkBuffer',type='structs'] |
| -- |
| The sname:VkBufferCollectionBufferCreateInfoFUCHSIA structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferCollectionBufferCreateInfoFUCHSIA.txt[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:collection is the slink:VkBufferCollectionFUCHSIA handle |
| * pname:index is the index of the buffer in the buffer collection from |
| which the memory will be imported |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBufferCollectionBufferCreateInfoFUCHSIA-index-06388]] |
| pname:index must: be less than |
| slink:VkBufferCollectionPropertiesFUCHSIA::pname:bufferCount |
| **** |
| |
| include::{generated}/validity/structs/VkBufferCollectionBufferCreateInfoFUCHSIA.txt[] |
| -- |
| endif::VK_FUCHSIA_buffer_collection[] |
| |
| [open,refpage='vkDestroyBuffer',desc='Destroy a buffer object',type='protos'] |
| -- |
| To destroy a buffer, call: |
| |
| include::{generated}/api/protos/vkDestroyBuffer.txt[] |
| |
| * pname:device is the logical device that destroys the buffer. |
| * pname:buffer is the buffer to destroy. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkDestroyBuffer-buffer-00922]] |
| All submitted commands that refer to pname:buffer, either directly or |
| via a sname:VkBufferView, must: have completed execution |
| * [[VUID-vkDestroyBuffer-buffer-00923]] |
| If sname:VkAllocationCallbacks were provided when pname:buffer was |
| created, a compatible set of callbacks must: be provided here |
| * [[VUID-vkDestroyBuffer-buffer-00924]] |
| If no sname:VkAllocationCallbacks were provided when pname:buffer was |
| created, pname:pAllocator must: be `NULL` |
| **** |
| |
| include::{generated}/validity/protos/vkDestroyBuffer.txt[] |
| -- |
| |
| |
| [[resources-buffer-views]] |
| == Buffer Views |
| |
| [open,refpage='VkBufferView',desc='Opaque handle to a buffer view object',type='handles'] |
| -- |
| A _buffer view_ represents a contiguous range of a buffer and a specific |
| format to be used to interpret the data. |
| Buffer views are used to enable shaders to access buffer contents |
| interpreted as formatted data. |
| In order to create a valid buffer view, the buffer must: have been created |
| with at least one of the following usage flags: |
| |
| * ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT |
| * ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT |
| |
| Buffer views are represented by sname:VkBufferView handles: |
| |
| include::{generated}/api/handles/VkBufferView.txt[] |
| -- |
| |
| [open,refpage='vkCreateBufferView',desc='Create a new buffer view object',type='protos'] |
| -- |
| To create a buffer view, call: |
| |
| include::{generated}/api/protos/vkCreateBufferView.txt[] |
| |
| * pname:device is the logical device that creates the buffer view. |
| * pname:pCreateInfo is a pointer to a slink:VkBufferViewCreateInfo |
| structure containing parameters to be used to create the buffer view. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pView is a pointer to a slink:VkBufferView handle in which the |
| resulting buffer view object is returned. |
| |
| include::{generated}/validity/protos/vkCreateBufferView.txt[] |
| -- |
| |
| [open,refpage='VkBufferViewCreateInfo',desc='Structure specifying parameters of a newly created buffer view',type='structs'] |
| -- |
| The sname:VkBufferViewCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferViewCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is reserved for future use. |
| * pname:buffer is a slink:VkBuffer on which the view will be created. |
| * pname:format is a elink:VkFormat describing the format of the data |
| elements in the buffer. |
| * pname:offset is an offset in bytes from the base address of the buffer. |
| Accesses to the buffer view from shaders use addressing that is relative |
| to this starting offset. |
| * pname:range is a size in bytes of the buffer view. |
| If pname:range is equal to ename:VK_WHOLE_SIZE, the range from |
| pname:offset to the end of the buffer is used. |
| If ename:VK_WHOLE_SIZE is used and the remaining size of the buffer is |
| not a multiple of the <<texel-block-size, texel block size>> of |
| pname:format, the nearest smaller multiple is used. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBufferViewCreateInfo-offset-00925]] |
| pname:offset must: be less than the size of pname:buffer |
| ifndef::VK_EXT_texel_buffer_alignment[] |
| * [[VUID-VkBufferViewCreateInfo-offset-00926]] |
| pname:offset must: be a multiple of |
| sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment |
| endif::VK_EXT_texel_buffer_alignment[] |
| * [[VUID-VkBufferViewCreateInfo-range-00928]] |
| If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be |
| greater than `0` |
| * [[VUID-VkBufferViewCreateInfo-range-00929]] |
| If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range must: be |
| an integer multiple of the texel block size of pname:format |
| * [[VUID-VkBufferViewCreateInfo-range-00930]] |
| If pname:range is not equal to ename:VK_WHOLE_SIZE, the number of texel |
| buffer elements given by [eq]#({lfloor}pname:range / (texel block |
| size){rfloor} {times} (texels per block))# where texel block size and |
| texels per block are as defined in the <<formats-compatibility, |
| Compatible Formats>> table for pname:format, must: be less than or equal |
| to sname:VkPhysicalDeviceLimits::pname:maxTexelBufferElements |
| * [[VUID-VkBufferViewCreateInfo-offset-00931]] |
| If pname:range is not equal to ename:VK_WHOLE_SIZE, the sum of |
| pname:offset and pname:range must: be less than or equal to the size of |
| pname:buffer |
| * [[VUID-VkBufferViewCreateInfo-range-04059]] |
| If pname:range is equal to ename:VK_WHOLE_SIZE, the number of texel |
| buffer elements given by [eq]#({lfloor}(size - pname:offset) / (texel |
| block size){rfloor} {times} (texels per block))# where size is the size |
| of pname:buffer, and texel block size and texels per block are as |
| defined in the <<formats-compatibility, Compatible Formats>> table for |
| pname:format, must: be less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxTexelBufferElements |
| * [[VUID-VkBufferViewCreateInfo-buffer-00932]] |
| pname:buffer must: have been created with a pname:usage value containing |
| at least one of ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT or |
| ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT |
| * [[VUID-VkBufferViewCreateInfo-buffer-00933]] |
| If pname:buffer was created with pname:usage containing |
| ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, pname:format must: be |
| supported for uniform texel buffers, as specified by the |
| ename:VK_FORMAT_FEATURE_UNIFORM_TEXEL_BUFFER_BIT flag in |
| sname:VkFormatProperties::pname:bufferFeatures returned by |
| flink:vkGetPhysicalDeviceFormatProperties |
| * [[VUID-VkBufferViewCreateInfo-buffer-00934]] |
| If pname:buffer was created with pname:usage containing |
| ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:format must: be |
| supported for storage texel buffers, as specified by the |
| ename:VK_FORMAT_FEATURE_STORAGE_TEXEL_BUFFER_BIT flag in |
| sname:VkFormatProperties::pname:bufferFeatures returned by |
| flink:vkGetPhysicalDeviceFormatProperties |
| * [[VUID-VkBufferViewCreateInfo-buffer-00935]] |
| If pname:buffer is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| ifdef::VK_EXT_texel_buffer_alignment[] |
| * [[VUID-VkBufferViewCreateInfo-offset-02749]] |
| If the <<features-texelBufferAlignment,texelBufferAlignment>> feature is |
| not enabled, pname:offset must: be a multiple of |
| sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment |
| * [[VUID-VkBufferViewCreateInfo-buffer-02750]] |
| If the <<features-texelBufferAlignment,texelBufferAlignment>> feature is |
| enabled and if pname:buffer was created with pname:usage containing |
| ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:offset must: be a |
| multiple of the lesser of |
| slink:VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::pname:storageTexelBufferOffsetAlignmentBytes |
| or, if |
| slink:VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::pname:storageTexelBufferOffsetSingleTexelAlignment |
| is ename:VK_TRUE, the size of a texel of the requested pname:format. |
| If the size of a texel is a multiple of three bytes, then the size of a |
| single component of pname:format is used instead |
| * [[VUID-VkBufferViewCreateInfo-buffer-02751]] |
| If the <<features-texelBufferAlignment,texelBufferAlignment>> feature is |
| enabled and if pname:buffer was created with pname:usage containing |
| ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT, pname:offset must: be a |
| multiple of the lesser of |
| slink:VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::pname:uniformTexelBufferOffsetAlignmentBytes |
| or, if |
| slink:VkPhysicalDeviceTexelBufferAlignmentPropertiesEXT::pname:uniformTexelBufferOffsetSingleTexelAlignment |
| is ename:VK_TRUE, the size of a texel of the requested pname:format. |
| If the size of a texel is a multiple of three bytes, then the size of a |
| single component of pname:format is used instead |
| endif::VK_EXT_texel_buffer_alignment[] |
| **** |
| |
| include::{generated}/validity/structs/VkBufferViewCreateInfo.txt[] |
| -- |
| |
| [open,refpage='VkBufferViewCreateFlags',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkBufferViewCreateFlags.txt[] |
| |
| tname:VkBufferViewCreateFlags is a bitmask type for setting a mask, but is |
| currently reserved for future use. |
| -- |
| |
| [open,refpage='vkDestroyBufferView',desc='Destroy a buffer view object',type='protos'] |
| -- |
| To destroy a buffer view, call: |
| |
| include::{generated}/api/protos/vkDestroyBufferView.txt[] |
| |
| * pname:device is the logical device that destroys the buffer view. |
| * pname:bufferView is the buffer view to destroy. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkDestroyBufferView-bufferView-00936]] |
| All submitted commands that refer to pname:bufferView must: have |
| completed execution |
| * [[VUID-vkDestroyBufferView-bufferView-00937]] |
| If sname:VkAllocationCallbacks were provided when pname:bufferView was |
| created, a compatible set of callbacks must: be provided here |
| * [[VUID-vkDestroyBufferView-bufferView-00938]] |
| If no sname:VkAllocationCallbacks were provided when pname:bufferView |
| was created, pname:pAllocator must: be `NULL` |
| **** |
| |
| include::{generated}/validity/protos/vkDestroyBufferView.txt[] |
| -- |
| |
| |
| [[resources-images]] |
| == Images |
| |
| [open,refpage='VkImage',desc='Opaque handle to an image object',type='handles'] |
| -- |
| Images represent multidimensional - up to 3 - arrays of data which can: be |
| used for various purposes (e.g. attachments, textures), by binding them to a |
| graphics or compute pipeline via descriptor sets, or by directly specifying |
| them as parameters to certain commands. |
| |
| Images are represented by sname:VkImage handles: |
| |
| include::{generated}/api/handles/VkImage.txt[] |
| -- |
| |
| [open,refpage='vkCreateImage',desc='Create a new image object',type='protos'] |
| -- |
| To create images, call: |
| |
| include::{generated}/api/protos/vkCreateImage.txt[] |
| |
| * pname:device is the logical device that creates the image. |
| * pname:pCreateInfo is a pointer to a slink:VkImageCreateInfo structure |
| containing parameters to be used to create the image. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pImage is a pointer to a slink:VkImage handle in which the |
| resulting image object is returned. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCreateImage-flags-00939]] |
| If the pname:flags member of pname:pCreateInfo includes |
| ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, creating this sname:VkImage |
| must: not cause the total required sparse memory for all currently valid |
| sparse resources on the device to exceed |
| sname:VkPhysicalDeviceLimits::pname:sparseAddressSpaceSize |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| * [[VUID-vkCreateImage-pNext-06389]] |
| If a slink:VkBufferCollectionImageCreateInfoFUCHSIA has been chained to |
| pname:pNext, pname:pCreateInfo must: match the |
| <<sysmem-chosen-create-infos,Sysmem chosen sname:VkImageCreateInfo>> |
| excepting members slink:VkImageCreateInfo::pname:extent and |
| slink:VkImageCreateInfo::pname:usage in the match criteria |
| endif::VK_FUCHSIA_buffer_collection[] |
| **** |
| |
| include::{generated}/validity/protos/vkCreateImage.txt[] |
| -- |
| |
| [open,refpage='VkImageCreateInfo',desc='Structure specifying the parameters of a newly created image object',type='structs'] |
| -- |
| The sname:VkImageCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkImageCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkImageCreateFlagBits describing |
| additional parameters of the image. |
| * pname:imageType is a elink:VkImageType value specifying the basic |
| dimensionality of the image. |
| Layers in array textures do not count as a dimension for the purposes of |
| the image type. |
| * pname:format is a elink:VkFormat describing the format and type of the |
| texel blocks that will be contained in the image. |
| * pname:extent is a slink:VkExtent3D describing the number of data |
| elements in each dimension of the base level. |
| * pname:mipLevels describes the number of levels of detail available for |
| minified sampling of the image. |
| * pname:arrayLayers is the number of layers in the image. |
| * pname:samples is a elink:VkSampleCountFlagBits value specifying the |
| number of <<primsrast-multisampling,samples per texel>>. |
| * pname:tiling is a elink:VkImageTiling value specifying the tiling |
| arrangement of the texel blocks in memory. |
| * pname:usage is a bitmask of elink:VkImageUsageFlagBits describing the |
| intended usage of the image. |
| * pname:sharingMode is a elink:VkSharingMode value specifying the sharing |
| mode of the image when it will be accessed by multiple queue families. |
| * pname:queueFamilyIndexCount is the number of entries in the |
| pname:pQueueFamilyIndices array. |
| * pname:pQueueFamilyIndices is a pointer to an array of queue families |
| that will access this image. |
| It is ignored if pname:sharingMode is not |
| ename:VK_SHARING_MODE_CONCURRENT. |
| * pname:initialLayout is a elink:VkImageLayout value specifying the |
| initial elink:VkImageLayout of all image subresources of the image. |
| See <<resources-image-layouts,Image Layouts>>. |
| |
| Images created with pname:tiling equal to ename:VK_IMAGE_TILING_LINEAR have |
| further restrictions on their limits and capabilities compared to images |
| created with pname:tiling equal to ename:VK_IMAGE_TILING_OPTIMAL. |
| Creation of images with tiling ename:VK_IMAGE_TILING_LINEAR may: not be |
| supported unless other parameters meet all of the constraints: |
| |
| * pname:imageType is ename:VK_IMAGE_TYPE_2D |
| * pname:format is not a depth/stencil format |
| * pname:mipLevels is 1 |
| * pname:arrayLayers is 1 |
| * pname:samples is ename:VK_SAMPLE_COUNT_1_BIT |
| * pname:usage only includes ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT and/or |
| ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| Images created with one of the <<formats-requiring-sampler-ycbcr-conversion, |
| formats that require a sampler Y'C~B~C~R~ conversion>>, have further |
| restrictions on their limits and capabilities compared to images created |
| with other formats. |
| Creation of images with a format requiring |
| <<formats-requiring-sampler-ycbcr-conversion, {YCbCr} conversion>> may: not |
| be supported unless other parameters meet all of the constraints: |
| |
| * pname:imageType is ename:VK_IMAGE_TYPE_2D |
| * pname:mipLevels is 1 |
| * pname:arrayLayers is 1 |
| * pname:samples is ename:VK_SAMPLE_COUNT_1_BIT |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| Implementations may: support additional limits and capabilities beyond those |
| listed above. |
| |
| To determine the set of valid pname:usage bits for a given format, call |
| flink:vkGetPhysicalDeviceFormatProperties. |
| |
| If the size of the resultant image would exceed pname:maxResourceSize, then |
| flink:vkCreateImage must: fail and return |
| ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. |
| This failure may: occur even when all image creation parameters satisfy |
| their valid usage requirements. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| [NOTE] |
| .Note |
| ==== |
| For images created without ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a |
| pname:usage bit is valid if it is supported for the format the image is |
| created with. |
| |
| For images created with ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a |
| pname:usage bit is valid if it is supported for at least one of the formats |
| a sname:VkImageView created from the image can: have (see |
| <<resources-image-views,Image Views>> for more detail). |
| ==== |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| |
| [[resources-image-creation-limits]] |
| .Image Creation Limits |
| **** |
| Valid values for some image creation parameters are limited by a numerical |
| upper bound or by inclusion in a bitset. |
| For example, slink:VkImageCreateInfo::pname:arrayLayers is limited by |
| pname:imageCreateMaxArrayLayers, defined below; and |
| slink:VkImageCreateInfo::pname:samples is limited by |
| pname:imageCreateSampleCounts, also defined below. |
| |
| Several limiting values are defined below, as well as assisting values from |
| which the limiting values are derived. |
| The limiting values are referenced by the relevant valid usage statements of |
| slink:VkImageCreateInfo. |
| |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * Let `uint64_t imageCreateDrmFormatModifiers[]` be the set of |
| <<glossary-drm-format-modifier,Linux DRM format modifiers>> that the |
| resultant image may: have. |
| ** If pname:tiling is not ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, |
| then pname:imageCreateDrmFormatModifiers is empty. |
| ** If slink:VkImageCreateInfo::pname:pNext contains |
| slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, then |
| pname:imageCreateDrmFormatModifiers contains exactly one modifier, |
| slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:drmFormatModifier. |
| ** If slink:VkImageCreateInfo::pname:pNext contains |
| slink:VkImageDrmFormatModifierListCreateInfoEXT, then |
| pname:imageCreateDrmFormatModifiers contains the entire array |
| slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers. |
| endif::VK_EXT_image_drm_format_modifier[] |
| |
| * Let `VkBool32 imageCreateMaybeLinear` indicate if the resultant image |
| may be <<glossary-linear-resource,linear>>. |
| ifndef::VK_EXT_image_drm_format_modifier[] |
| (The definition below is trivial because certain extensions are disabled |
| in this build of the specification). |
| endif::VK_EXT_image_drm_format_modifier[] |
| ** If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, then |
| pname:imageCreateMaybeLinear is ename:VK_TRUE. |
| ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, then |
| pname:imageCreateMaybeLinear is ename:VK_FALSE. |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| ** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then |
| pname:imageCreateMaybeLinear is ename:VK_TRUE if and only if |
| pname:imageCreateDrmFormatModifiers contains |
| etext:DRM_FORMAT_MOD_LINEAR. |
| endif::VK_EXT_image_drm_format_modifier[] |
| |
| * Let `VkFormatFeatureFlags imageCreateFormatFeatures` be the set of valid |
| _format features_ available during image creation. |
| ** If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, then |
| pname:imageCreateFormatFeatures is the value of |
| slink:VkFormatProperties::pname:linearTilingFeatures found by calling |
| flink:vkGetPhysicalDeviceFormatProperties with parameter pname:format |
| equal to slink:VkImageCreateInfo::pname:format. |
| ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| and if the pname:pNext chain includes no slink:VkExternalFormatANDROID |
| structure with non-zero pname:externalFormat, |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| then pname:imageCreateFormatFeatures is the value of |
| slink:VkFormatProperties::pname:optimalTilingFeatures found by calling |
| flink:vkGetPhysicalDeviceFormatProperties with parameter pname:format |
| equal to slink:VkImageCreateInfo::pname:format. |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ** If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and if the |
| pname:pNext chain includes a slink:VkExternalFormatANDROID structure |
| with non-zero pname:externalFormat, then |
| pname:imageCreateFormatFeatures is the value of |
| slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures |
| obtained by flink:vkGetAndroidHardwareBufferPropertiesANDROID with a |
| matching pname:externalFormat value. |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| ** If the pname:pNext chain includes a |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA structure, then |
| pname:imageCreateFormatFeatures is the value of |
| slink:VkBufferCollectionPropertiesFUCHSIA::pname:formatFeatures found |
| by calling flink:vkGetBufferCollectionPropertiesFUCHSIA with a |
| parameter pname:collection equal to |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA::pname:collection |
| endif::VK_FUCHSIA_buffer_collection[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| ** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then |
| the value of pname:imageCreateFormatFeatures is found by calling |
| flink:vkGetPhysicalDeviceFormatProperties2 with |
| slink:VkImageFormatProperties::pname:format equal to |
| slink:VkImageCreateInfo::pname:format and with |
| slink:VkDrmFormatModifierPropertiesListEXT chained into |
| slink:VkImageFormatProperties2; by collecting all members of the |
| returned array |
| slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties |
| whose pname:drmFormatModifier belongs to |
| pname:imageCreateDrmFormatModifiers; and by taking the bitwise |
| intersection, over the collected array members, of |
| pname:drmFormatModifierTilingFeatures. |
| (The resultant pname:imageCreateFormatFeatures may: be empty). |
| endif::VK_EXT_image_drm_format_modifier[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| * Let `VkImageFormatProperties2 imageCreateImageFormatPropertiesList[]` be |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| defined as follows. |
| ** If slink:VkImageCreateInfo::pname:pNext contains no |
| slink:VkExternalFormatANDROID structure with non-zero |
| pname:externalFormat, then pname:imageCreateImageFormatPropertiesList |
| is |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| the list of structures obtained by calling |
| flink:vkGetPhysicalDeviceImageFormatProperties2, possibly multiple |
| times, as follows: |
| *** The parameters slink:VkPhysicalDeviceImageFormatInfo2::pname:format, |
| pname:imageType, pname:tiling, pname:usage, and pname:flags must: be |
| equal to those in slink:VkImageCreateInfo. |
| *** If slink:VkImageCreateInfo::pname:pNext contains a |
| slink:VkExternalMemoryImageCreateInfo structure whose |
| pname:handleTypes is not `0`, then |
| slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: contain a |
| slink:VkPhysicalDeviceExternalImageFormatInfo structure whose |
| pname:handleType is not `0`; and |
| flink:vkGetPhysicalDeviceImageFormatProperties2 must: be called for |
| each handle type in |
| slink:VkExternalMemoryImageCreateInfo::pname:handleTypes, successively |
| setting |
| slink:VkPhysicalDeviceExternalImageFormatInfo::pname:handleType on |
| each call. |
| *** If slink:VkImageCreateInfo::pname:pNext contains no |
| slink:VkExternalMemoryImageCreateInfo structure, or contains a |
| structure whose pname:handleTypes is `0`, then |
| slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: either |
| contain no slink:VkPhysicalDeviceExternalImageFormatInfo structure, or |
| contain a structure whose pname:handleType is `0`. |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| *** If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then |
| slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: contain a |
| slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure where |
| pname:sharingMode is equal to |
| slink:VkImageCreateInfo::pname:sharingMode; and, if pname:sharingMode |
| is ename:VK_SHARING_MODE_CONCURRENT, then pname:queueFamilyIndexCount |
| and pname:pQueueFamilyIndices must: be equal to those in |
| slink:VkImageCreateInfo; and, if pname:flags contains |
| ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, then the |
| slink:VkImageFormatListCreateInfo structure included in the |
| pname:pNext chain of slink:VkPhysicalDeviceImageFormatInfo2 must: be |
| equivalent to the one included in the pname:pNext chain of |
| slink:VkImageCreateInfo; and |
| flink:vkGetPhysicalDeviceImageFormatProperties2 must: be called for |
| each modifier in pname:imageCreateDrmFormatModifiers, successively |
| setting |
| slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT::pname:drmFormatModifier |
| on each call. |
| *** If pname:tiling is not ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, |
| then slink:VkPhysicalDeviceImageFormatInfo2::pname:pNext must: contain |
| no slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT structure. |
| endif::VK_EXT_image_drm_format_modifier[] |
| *** If any call to flink:vkGetPhysicalDeviceImageFormatProperties2 returns |
| an error, then pname:imageCreateImageFormatPropertiesList is defined |
| to be the empty list. |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ** If slink:VkImageCreateInfo::pname:pNext contains a |
| slink:VkExternalFormatANDROID structure with non-zero |
| pname:externalFormat, then pname:imageCreateImageFormatPropertiesList |
| contains a single element where: |
| *** sname:VkImageFormatProperties::pname:maxMipLevels is |
| [eq]#{lfloor}log~2~(max(pname:extent.width, pname:extent.height, |
| pname:extent.depth)){rfloor} {plus} 1#. |
| *** sname:VkImageFormatProperties::pname:maxArrayLayers is |
| slink:VkPhysicalDeviceLimits::pname:maxImageArrayLayers. |
| *** Each component of sname:VkImageFormatProperties::pname:maxExtent is |
| slink:VkPhysicalDeviceLimits::pname:maxImageDimension2D. |
| *** sname:VkImageFormatProperties::pname:sampleCounts contains exactly |
| ename:VK_SAMPLE_COUNT_1_BIT. |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| * Let `uint32_t imageCreateMaxMipLevels` be |
| ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| the value of slink:VkImageFormatProperties::pname:maxMipLevels found by |
| calling flink:vkGetPhysicalDeviceImageFormatProperties with parameters |
| pname:format, pname:imageType, pname:tiling, pname:usage, and |
| pname:flags equal to those in slink:VkImageCreateInfo. |
| If flink:vkGetPhysicalDeviceFormatProperties returns an error, then the |
| value of pname:imageCreateMaxMipLevels is undefined:. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| the minimum value of slink:VkImageFormatProperties::pname:maxMipLevels |
| in pname:imageCreateImageFormatPropertiesList. |
| The value is undefined: if pname:imageCreateImageFormatPropertiesList is |
| empty. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| * Let `uint32_t imageCreateMaxArrayLayers` be |
| ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| defined analogously to pname:imageCreateMaxMipLevels. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| the minimum value of slink:VkImageFormatProperties::pname:maxArrayLayers |
| in pname:imageCreateImageFormatPropertiesList. |
| The value is undefined: if pname:imageCreateImageFormatPropertiesList is |
| empty. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| * Let `VkExtent3D imageCreateMaxExtent` be |
| ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| defined analogously to pname:imageCreateMaxMipLevels. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| the component-wise minimum over all |
| slink:VkImageFormatProperties::pname:maxExtent values in |
| pname:imageCreateImageFormatPropertiesList. |
| The value is undefined: if pname:imageCreateImageFormatPropertiesList is |
| empty. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| * Let `VkSampleCountFlags imageCreateSampleCounts` be |
| ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| defined analogously to pname:imageCreateMaxMipLevels. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| the intersection of each |
| slink:VkImageFormatProperties::pname:sampleCounts in |
| pname:imageCreateImageFormatPropertiesList. |
| The value is undefined: if pname:imageCreateImageFormatPropertiesList is |
| empty. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| **** |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageCreateInfo-imageCreateMaxMipLevels-02251]] |
| Each of the following values (as described in |
| <<resources-image-creation-limits,Image Creation Limits>>) must: not be |
| undefined: : pname:imageCreateMaxMipLevels, |
| pname:imageCreateMaxArrayLayers, pname:imageCreateMaxExtent, and |
| pname:imageCreateSampleCounts |
| * [[VUID-VkImageCreateInfo-sharingMode-00941]] |
| If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, |
| pname:pQueueFamilyIndices must: be a valid pointer to an array of |
| pname:queueFamilyIndexCount code:uint32_t values |
| * [[VUID-VkImageCreateInfo-sharingMode-00942]] |
| If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, |
| pname:queueFamilyIndexCount must: be greater than `1` |
| ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| * [[VUID-VkImageCreateInfo-sharingMode-01392]] |
| If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element |
| of pname:pQueueFamilyIndices must: be unique and must: be less than |
| pname:pQueueFamilyPropertyCount returned by |
| flink:vkGetPhysicalDeviceQueueFamilyProperties for the |
| pname:physicalDevice that was used to create pname:device |
| endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| * [[VUID-VkImageCreateInfo-sharingMode-01420]] |
| If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element |
| of pname:pQueueFamilyIndices must: be unique and must: be less than |
| pname:pQueueFamilyPropertyCount returned by either |
| flink:vkGetPhysicalDeviceQueueFamilyProperties or |
| flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the |
| pname:physicalDevice that was used to create pname:device |
| endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] |
| ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-VkImageCreateInfo-format-00943]] |
| pname:format must: not be ename:VK_FORMAT_UNDEFINED |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-VkImageCreateInfo-pNext-01974]] |
| If the pname:pNext chain includes a slink:VkExternalFormatANDROID |
| structure, and its pname:externalFormat member is non-zero the |
| pname:format must: be ename:VK_FORMAT_UNDEFINED |
| * [[VUID-VkImageCreateInfo-pNext-01975]] |
| If the pname:pNext chain does not include a |
| slink:VkExternalFormatANDROID structure, or does and its |
| pname:externalFormat member is `0`, the pname:format must: not be |
| ename:VK_FORMAT_UNDEFINED |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-VkImageCreateInfo-extent-00944]] |
| pname:extent.width must: be greater than `0` |
| * [[VUID-VkImageCreateInfo-extent-00945]] |
| pname:extent.height must: be greater than `0` |
| * [[VUID-VkImageCreateInfo-extent-00946]] |
| pname:extent.depth must: be greater than `0` |
| * [[VUID-VkImageCreateInfo-mipLevels-00947]] |
| pname:mipLevels must: be greater than `0` |
| * [[VUID-VkImageCreateInfo-arrayLayers-00948]] |
| pname:arrayLayers must: be greater than `0` |
| * [[VUID-VkImageCreateInfo-flags-00949]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, |
| pname:imageType must: be ename:VK_IMAGE_TYPE_2D |
| ifdef::VK_EXT_fragment_density_map[] |
| * [[VUID-VkImageCreateInfo-flags-02557]] |
| If pname:flags contains |
| ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, pname:imageType must: |
| be ename:VK_IMAGE_TYPE_2D |
| endif::VK_EXT_fragment_density_map[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageCreateInfo-flags-00950]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, |
| pname:imageType must: be ename:VK_IMAGE_TYPE_3D |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageCreateInfo-extent-02252]] |
| pname:extent.width must: be less than or equal to |
| pname:imageCreateMaxExtent.width (as defined in |
| <<resources-image-creation-limits,Image Creation Limits>>) |
| * [[VUID-VkImageCreateInfo-extent-02253]] |
| pname:extent.height must: be less than or equal to |
| pname:imageCreateMaxExtent.height (as defined in |
| <<resources-image-creation-limits,Image Creation Limits>>) |
| * [[VUID-VkImageCreateInfo-extent-02254]] |
| pname:extent.depth must: be less than or equal to |
| pname:imageCreateMaxExtent.depth (as defined in |
| <<resources-image-creation-limits,Image Creation Limits>>) |
| * [[VUID-VkImageCreateInfo-imageType-00954]] |
| If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags contains |
| ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width and |
| pname:extent.height must: be equal and pname:arrayLayers must: be |
| greater than or equal to 6 |
| * [[VUID-VkImageCreateInfo-imageType-00956]] |
| If pname:imageType is ename:VK_IMAGE_TYPE_1D, both pname:extent.height |
| and pname:extent.depth must: be `1` |
| * [[VUID-VkImageCreateInfo-imageType-00957]] |
| If pname:imageType is ename:VK_IMAGE_TYPE_2D, pname:extent.depth must: |
| be `1` |
| * [[VUID-VkImageCreateInfo-mipLevels-00958]] |
| pname:mipLevels must: be less than or equal to the number of levels in |
| the complete mipmap chain based on [eq]#pname:extent.width#, |
| [eq]#pname:extent.height#, and [eq]#pname:extent.depth# |
| * [[VUID-VkImageCreateInfo-mipLevels-02255]] |
| pname:mipLevels must: be less than or equal to |
| pname:imageCreateMaxMipLevels (as defined in |
| <<resources-image-creation-limits,Image Creation Limits>>) |
| * [[VUID-VkImageCreateInfo-arrayLayers-02256]] |
| pname:arrayLayers must: be less than or equal to |
| pname:imageCreateMaxArrayLayers (as defined in |
| <<resources-image-creation-limits,Image Creation Limits>>) |
| * [[VUID-VkImageCreateInfo-imageType-00961]] |
| If pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:arrayLayers must: be |
| `1` |
| * [[VUID-VkImageCreateInfo-samples-02257]] |
| If pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, then |
| pname:imageType must: be ename:VK_IMAGE_TYPE_2D, pname:flags must: not |
| contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:mipLevels must: |
| be equal to `1`, and pname:imageCreateMaybeLinear (as defined in |
| <<resources-image-creation-limits,Image Creation Limits>>) must: be |
| ename:VK_FALSE, |
| ifdef::VK_EXT_fragment_density_map[] |
| * [[VUID-VkImageCreateInfo-samples-02558]] |
| If pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, pname:usage must: |
| not contain ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT |
| endif::VK_EXT_fragment_density_map[] |
| * [[VUID-VkImageCreateInfo-usage-00963]] |
| If pname:usage includes ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, |
| then bits other than ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, |
| ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and |
| ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT must: not be set |
| * [[VUID-VkImageCreateInfo-usage-00964]] |
| If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, |
| ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, |
| ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or |
| ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.width must: be |
| less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth |
| * [[VUID-VkImageCreateInfo-usage-00965]] |
| If pname:usage includes ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, |
| ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, |
| ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, or |
| ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.height must: be |
| less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight |
| ifdef::VK_EXT_fragment_density_map[] |
| * [[VUID-VkImageCreateInfo-usage-02559]] |
| If pname:usage includes |
| ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, pname:extent.width |
| must: be less than or equal to |
| latexmath:[\left\lceil{\frac{maxFramebufferWidth}{minFragmentDensityTexelSize_{width}}}\right\rceil] |
| * [[VUID-VkImageCreateInfo-usage-02560]] |
| If pname:usage includes |
| ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, pname:extent.height |
| must: be less than or equal to |
| latexmath:[\left\lceil{\frac{maxFramebufferHeight}{minFragmentDensityTexelSize_{height}}}\right\rceil] |
| endif::VK_EXT_fragment_density_map[] |
| * [[VUID-VkImageCreateInfo-usage-00966]] |
| If pname:usage includes ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, |
| pname:usage must: also contain at least one of |
| ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, |
| ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, or |
| ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT |
| * [[VUID-VkImageCreateInfo-samples-02258]] |
| pname:samples must: be a bit value that is set in |
| pname:imageCreateSampleCounts (as defined in |
| <<resources-image-creation-limits,Image Creation Limits>>) |
| * [[VUID-VkImageCreateInfo-usage-00968]] |
| If the <<features-shaderStorageImageMultisample,multisampled storage |
| images>> feature is not enabled, and pname:usage contains |
| ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:samples must: be |
| ename:VK_SAMPLE_COUNT_1_BIT |
| * [[VUID-VkImageCreateInfo-flags-00969]] |
| If the <<features-sparseBinding,sparse bindings>> feature is not |
| enabled, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT |
| * [[VUID-VkImageCreateInfo-flags-01924]] |
| If the <<features-sparseResidencyAliased,sparse aliased residency>> |
| feature is not enabled, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT |
| * [[VUID-VkImageCreateInfo-tiling-04121]] |
| If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, pname:flags must: not |
| contain ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT |
| * [[VUID-VkImageCreateInfo-imageType-00970]] |
| If pname:imageType is ename:VK_IMAGE_TYPE_1D, pname:flags must: not |
| contain ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT |
| * [[VUID-VkImageCreateInfo-imageType-00971]] |
| If the <<features-sparseResidencyImage2D,sparse residency for 2D |
| images>> feature is not enabled, and pname:imageType is |
| ename:VK_IMAGE_TYPE_2D, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT |
| * [[VUID-VkImageCreateInfo-imageType-00972]] |
| If the <<features-sparseResidencyImage3D,sparse residency for 3D |
| images>> feature is not enabled, and pname:imageType is |
| ename:VK_IMAGE_TYPE_3D, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT |
| * [[VUID-VkImageCreateInfo-imageType-00973]] |
| If the <<features-sparseResidency2Samples,sparse residency for images |
| with 2 samples>> feature is not enabled, pname:imageType is |
| ename:VK_IMAGE_TYPE_2D, and pname:samples is |
| ename:VK_SAMPLE_COUNT_2_BIT, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT |
| * [[VUID-VkImageCreateInfo-imageType-00974]] |
| If the <<features-sparseResidency4Samples,sparse residency for images |
| with 4 samples>> feature is not enabled, pname:imageType is |
| ename:VK_IMAGE_TYPE_2D, and pname:samples is |
| ename:VK_SAMPLE_COUNT_4_BIT, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT |
| * [[VUID-VkImageCreateInfo-imageType-00975]] |
| If the <<features-sparseResidency8Samples,sparse residency for images |
| with 8 samples>> feature is not enabled, pname:imageType is |
| ename:VK_IMAGE_TYPE_2D, and pname:samples is |
| ename:VK_SAMPLE_COUNT_8_BIT, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT |
| * [[VUID-VkImageCreateInfo-imageType-00976]] |
| If the <<features-sparseResidency16Samples,sparse residency for images |
| with 16 samples>> feature is not enabled, pname:imageType is |
| ename:VK_IMAGE_TYPE_2D, and pname:samples is |
| ename:VK_SAMPLE_COUNT_16_BIT, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT |
| * [[VUID-VkImageCreateInfo-flags-00987]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or |
| ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, it must: also contain |
| ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT |
| * [[VUID-VkImageCreateInfo-None-01925]] |
| If any of the bits ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or |
| ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, |
| ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT must: not also be set |
| ifdef::VK_VERSION_1_1[] |
| * [[VUID-VkImageCreateInfo-flags-01890]] |
| If the protected memory feature is not enabled, pname:flags must: not |
| contain ename:VK_IMAGE_CREATE_PROTECTED_BIT |
| * [[VUID-VkImageCreateInfo-None-01891]] |
| If any of the bits ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or |
| ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set, |
| ename:VK_IMAGE_CREATE_PROTECTED_BIT must: not also be set |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifdef::VK_NV_external_memory[] |
| * [[VUID-VkImageCreateInfo-pNext-00988]] |
| If the pname:pNext chain includes a |
| slink:VkExternalMemoryImageCreateInfoNV structure, it must: not contain |
| a slink:VkExternalMemoryImageCreateInfo structure |
| endif::VK_NV_external_memory[] |
| * [[VUID-VkImageCreateInfo-pNext-00990]] |
| If the pname:pNext chain includes a |
| slink:VkExternalMemoryImageCreateInfo structure, its pname:handleTypes |
| member must: only contain bits that are also in |
| slink:VkExternalImageFormatProperties::pname:externalMemoryProperties.compatibleHandleTypes, |
| as returned by flink:vkGetPhysicalDeviceImageFormatProperties2 with |
| pname:format, pname:imageType, pname:tiling, pname:usage, and |
| pname:flags equal to those in this structure, and with a |
| slink:VkPhysicalDeviceExternalImageFormatInfo structure included in the |
| pname:pNext chain, with a pname:handleType equal to any one of the |
| handle types specified in |
| slink:VkExternalMemoryImageCreateInfo::pname:handleTypes |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifdef::VK_NV_external_memory+VK_NV_external_memory_capabilities[] |
| * [[VUID-VkImageCreateInfo-pNext-00991]] |
| If the pname:pNext chain includes a |
| slink:VkExternalMemoryImageCreateInfoNV structure, its pname:handleTypes |
| member must: only contain bits that are also in |
| slink:VkExternalImageFormatPropertiesNV::pname:externalMemoryProperties.compatibleHandleTypes, |
| as returned by flink:vkGetPhysicalDeviceExternalImageFormatPropertiesNV |
| with pname:format, pname:imageType, pname:tiling, pname:usage, and |
| pname:flags equal to those in this structure, and with |
| pname:externalHandleType equal to any one of the handle types specified |
| in slink:VkExternalMemoryImageCreateInfoNV::pname:handleTypes |
| endif::VK_NV_external_memory+VK_NV_external_memory_capabilities[] |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| * [[VUID-VkImageCreateInfo-physicalDeviceCount-01421]] |
| If the logical device was created with |
| slink:VkDeviceGroupDeviceCreateInfo::pname:physicalDeviceCount equal to |
| 1, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT |
| * [[VUID-VkImageCreateInfo-flags-02259]] |
| If pname:flags contains |
| ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT, then |
| pname:mipLevels must: be one, pname:arrayLayers must: be one, |
| pname:imageType must: be ename:VK_IMAGE_TYPE_2D. |
| and pname:imageCreateMaybeLinear (as defined in |
| <<resources-image-creation-limits,Image Creation Limits>>) must: be |
| ename:VK_FALSE |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| * [[VUID-VkImageCreateInfo-flags-01572]] |
| If pname:flags contains |
| ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then pname:format |
| must: be a <<compressed_image_formats,compressed image format>> |
| * [[VUID-VkImageCreateInfo-flags-01573]] |
| If pname:flags contains |
| ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then pname:flags |
| must: also contain ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| * [[VUID-VkImageCreateInfo-initialLayout-00993]] |
| pname:initialLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or |
| ename:VK_IMAGE_LAYOUT_PREINITIALIZED |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] |
| * [[VUID-VkImageCreateInfo-pNext-01443]] |
| If the pname:pNext chain includes a |
| slink:VkExternalMemoryImageCreateInfo or |
| sname:VkExternalMemoryImageCreateInfoNV structure whose |
| pname:handleTypes member is not `0`, pname:initialLayout must: be |
| ename:VK_IMAGE_LAYOUT_UNDEFINED |
| endif::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageCreateInfo-format-06410]] |
| If the image pname:format is one of the |
| <<formats-requiring-sampler-ycbcr-conversion, formats that require a |
| sampler Y'C~B~C~R~ conversion>>, pname:mipLevels must: be 1 |
| * [[VUID-VkImageCreateInfo-format-06411]] |
| If the image pname:format is one of the |
| <<formats-requiring-sampler-ycbcr-conversion, formats that require a |
| sampler Y'C~B~C~R~ conversion>>, pname:samples must: be |
| ename:VK_SAMPLE_COUNT_1_BIT |
| * [[VUID-VkImageCreateInfo-format-06412]] |
| If the image pname:format is one of the |
| <<formats-requiring-sampler-ycbcr-conversion, formats that require a |
| sampler Y'C~B~C~R~ conversion>>, pname:imageType must: be |
| ename:VK_IMAGE_TYPE_2D |
| ifdef::VK_EXT_ycbcr_image_arrays[] |
| * [[VUID-VkImageCreateInfo-format-06413]] |
| If the image pname:format is one of the |
| <<formats-requiring-sampler-ycbcr-conversion, formats that require a |
| sampler Y'C~B~C~R~ conversion>>, and the pname:ycbcrImageArrays feature |
| is not enabled, pname:arrayLayers must: be 1 |
| endif::VK_EXT_ycbcr_image_arrays[] |
| ifndef::VK_EXT_ycbcr_image_arrays[] |
| * [[VUID-VkImageCreateInfo-format-06414]] |
| If the image pname:format is one of the |
| <<formats-requiring-sampler-ycbcr-conversion, formats that require a |
| sampler Y'C~B~C~R~ conversion>>, pname:arrayLayers must: be 1 |
| endif::VK_EXT_ycbcr_image_arrays[] |
| * [[VUID-VkImageCreateInfo-imageCreateFormatFeatures-02260]] |
| If pname:format is a _multi-planar_ format, and if |
| pname:imageCreateFormatFeatures (as defined in |
| <<resources-image-creation-limits,Image Creation Limits>>) does not |
| contain ename:VK_FORMAT_FEATURE_DISJOINT_BIT, then pname:flags must: not |
| contain ename:VK_IMAGE_CREATE_DISJOINT_BIT |
| * [[VUID-VkImageCreateInfo-format-01577]] |
| If pname:format is not a _multi-planar_ format, and pname:flags does not |
| include ename:VK_IMAGE_CREATE_ALIAS_BIT, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_DISJOINT_BIT |
| * [[VUID-VkImageCreateInfo-format-04712]] |
| If pname:format has a code:_422 or code:_420 suffix, pname:width must: |
| be a multiple of 2 |
| * [[VUID-VkImageCreateInfo-format-04713]] |
| If pname:format has a code:_420 suffix, pname:height must: be a multiple |
| of 2 |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkImageCreateInfo-tiling-02261]] |
| If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then |
| the pname:pNext chain must: include exactly one of |
| slink:VkImageDrmFormatModifierListCreateInfoEXT or |
| slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structures |
| * [[VUID-VkImageCreateInfo-pNext-02262]] |
| If the pname:pNext chain includes a |
| slink:VkImageDrmFormatModifierListCreateInfoEXT or |
| slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure, then |
| pname:tiling must: be ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT |
| * [[VUID-VkImageCreateInfo-tiling-02353]] |
| If pname:tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and |
| pname:flags contains ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, then the |
| pname:pNext chain must: include a slink:VkImageFormatListCreateInfo |
| structure with non-zero pname:viewFormatCount |
| endif::VK_EXT_image_drm_format_modifier[] |
| ifdef::VK_EXT_sample_locations[] |
| * [[VUID-VkImageCreateInfo-flags-01533]] |
| If pname:flags contains |
| ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT |
| pname:format must: be a depth or depth/stencil format |
| endif::VK_EXT_sample_locations[] |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-VkImageCreateInfo-pNext-02393]] |
| If the pname:pNext chain includes a |
| slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes |
| member includes |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, |
| pname:imageType must: be ename:VK_IMAGE_TYPE_2D |
| * [[VUID-VkImageCreateInfo-pNext-02394]] |
| If the pname:pNext chain includes a |
| slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes |
| member includes |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID, |
| pname:mipLevels must: either be `1` or equal to the number of levels in |
| the complete mipmap chain based on [eq]#pname:extent.width#, |
| [eq]#pname:extent.height#, and [eq]#pname:extent.depth# |
| * [[VUID-VkImageCreateInfo-pNext-02396]] |
| If the pname:pNext chain includes a slink:VkExternalFormatANDROID |
| structure whose pname:externalFormat member is not `0`, pname:flags |
| must: not include ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT |
| * [[VUID-VkImageCreateInfo-pNext-02397]] |
| If the pname:pNext chain includes a slink:VkExternalFormatANDROID |
| structure whose pname:externalFormat member is not `0`, pname:usage |
| must: not include any usages except ename:VK_IMAGE_USAGE_SAMPLED_BIT |
| * [[VUID-VkImageCreateInfo-pNext-02398]] |
| If the pname:pNext chain includes a slink:VkExternalFormatANDROID |
| structure whose pname:externalFormat member is not `0`, pname:tiling |
| must: be ename:VK_IMAGE_TILING_OPTIMAL |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| * [[VUID-VkImageCreateInfo-format-02795]] |
| If pname:format is a depth-stencil format, pname:usage includes |
| ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and the pname:pNext |
| chain includes a slink:VkImageStencilUsageCreateInfo structure, then its |
| slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: |
| also include ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * [[VUID-VkImageCreateInfo-format-02796]] |
| If pname:format is a depth-stencil format, pname:usage does not include |
| ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, and the pname:pNext |
| chain includes a slink:VkImageStencilUsageCreateInfo structure, then its |
| slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: |
| also not include ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * [[VUID-VkImageCreateInfo-format-02797]] |
| If pname:format is a depth-stencil format, pname:usage includes |
| ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, and the pname:pNext chain |
| includes a slink:VkImageStencilUsageCreateInfo structure, then its |
| slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: |
| also include ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT |
| * [[VUID-VkImageCreateInfo-format-02798]] |
| If pname:format is a depth-stencil format, pname:usage does not include |
| ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, and the pname:pNext chain |
| includes a slink:VkImageStencilUsageCreateInfo structure, then its |
| slink:VkImageStencilUsageCreateInfo::pname:stencilUsage member must: |
| also not include ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT |
| * [[VUID-VkImageCreateInfo-Format-02536]] |
| If pname:Format is a depth-stencil format and the pname:pNext chain |
| includes a slink:VkImageStencilUsageCreateInfo structure with its |
| pname:stencilUsage member including |
| ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.width must: be |
| less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxFramebufferWidth |
| * [[VUID-VkImageCreateInfo-format-02537]] |
| If pname:format is a depth-stencil format and the pname:pNext chain |
| includes a slink:VkImageStencilUsageCreateInfo structure with its |
| pname:stencilUsage member including |
| ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, pname:extent.height must: be |
| less than or equal to |
| sname:VkPhysicalDeviceLimits::pname:maxFramebufferHeight |
| * [[VUID-VkImageCreateInfo-format-02538]] |
| If the <<features-shaderStorageImageMultisample,multisampled storage |
| images>> feature is not enabled, pname:format is a depth-stencil format |
| and the pname:pNext chain includes a slink:VkImageStencilUsageCreateInfo |
| structure with its pname:stencilUsage including |
| ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:samples must: be |
| ename:VK_SAMPLE_COUNT_1_BIT |
| endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| ifdef::VK_NV_corner_sampled_image[] |
| * [[VUID-VkImageCreateInfo-flags-02050]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, |
| pname:imageType must: be ename:VK_IMAGE_TYPE_2D or |
| ename:VK_IMAGE_TYPE_3D |
| * [[VUID-VkImageCreateInfo-flags-02051]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV, it |
| must: not contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT and the |
| pname:format must: not be a depth/stencil format |
| * [[VUID-VkImageCreateInfo-flags-02052]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV and |
| pname:imageType is ename:VK_IMAGE_TYPE_2D, pname:extent.width and |
| pname:extent.height must: be greater than `1` |
| * [[VUID-VkImageCreateInfo-flags-02053]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV and |
| pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:extent.width, |
| pname:extent.height, and pname:extent.depth must: be greater than `1` |
| endif::VK_NV_corner_sampled_image[] |
| ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] |
| * [[VUID-VkImageCreateInfo-imageType-02082]] |
| If pname:usage includes |
| ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, |
| pname:imageType must: be ename:VK_IMAGE_TYPE_2D |
| * [[VUID-VkImageCreateInfo-samples-02083]] |
| If pname:usage includes |
| ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, |
| pname:samples must: be ename:VK_SAMPLE_COUNT_1_BIT |
| endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] |
| ifdef::VK_NV_shading_rate_image[] |
| * [[VUID-VkImageCreateInfo-tiling-02084]] |
| If pname:usage includes ename:VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, |
| pname:tiling must: be ename:VK_IMAGE_TILING_OPTIMAL |
| endif::VK_NV_shading_rate_image[] |
| ifdef::VK_EXT_fragment_density_map[] |
| * [[VUID-VkImageCreateInfo-flags-02565]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, |
| pname:tiling must: be ename:VK_IMAGE_TILING_OPTIMAL |
| * [[VUID-VkImageCreateInfo-flags-02566]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, |
| pname:imageType must: be ename:VK_IMAGE_TYPE_2D |
| * [[VUID-VkImageCreateInfo-flags-02567]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, |
| pname:flags must: not contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT |
| * [[VUID-VkImageCreateInfo-flags-02568]] |
| If pname:flags contains ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT, |
| pname:mipLevels must: be `1` |
| endif::VK_EXT_fragment_density_map[] |
| ifdef::VK_HUAWEI_invocation_mask[] |
| * [[VUID-VkImageCreateInfo-usage-04992]] |
| If pname:usage includes ename:VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI, |
| pname:tiling must: be ename:VK_IMAGE_TILING_LINEAR |
| endif::VK_HUAWEI_invocation_mask[] |
| ifdef::VK_KHR_portability_subset[] |
| * [[VUID-VkImageCreateInfo-imageView2DOn3DImage-04459]] |
| If the `apiext:VK_KHR_portability_subset` extension is enabled, and |
| slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:imageView2DOn3DImage |
| is ename:VK_FALSE, pname:flags must: not contain |
| ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT |
| * [[VUID-VkImageCreateInfo-multisampleArrayImage-04460]] |
| If the `apiext:VK_KHR_portability_subset` extension is enabled, and |
| slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:multisampleArrayImage |
| is ename:VK_FALSE, and pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, |
| then pname:arrayLayers must: be `1` |
| endif::VK_KHR_portability_subset[] |
| ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] |
| * [[VUID-VkImageCreateInfo-pNext-04737]] |
| If a slink:VkImageFormatListCreateInfo structure was included in the |
| pname:pNext chain and |
| slink:VkImageFormatListCreateInfo::pname:viewFormatCount is not zero, |
| then all of the formats in |
| slink:VkImageFormatListCreateInfo::pname:pViewFormats must: be |
| compatible with the pname:format as described in the |
| <<formats-compatibility,compatibility table>> |
| * [[VUID-VkImageCreateInfo-flags-04738]] |
| If pname:flags does not contain ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT |
| and the pname:pNext chain includes a slink:VkImageFormatListCreateInfo |
| structure, then slink:VkImageFormatListCreateInfo::pname:viewFormatCount |
| must: be `0` or `1` |
| endif::VK_VERSION_1_2,VK_KHR_image_format_list[] |
| ifdef::VK_KHR_video_decode_queue[] |
| * [[VUID-VkImageCreateInfo-usage-04815]] |
| If pname:usage includes ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the pname:pNext |
| chain must: include a valid slink:VkVideoProfilesKHR structure which |
| includes at least one slink:VkVideoProfileKHR with a decode |
| codec-operation |
| endif::VK_KHR_video_decode_queue[] |
| ifdef::VK_KHR_video_encode_queue[] |
| * [[VUID-VkImageCreateInfo-usage-04816]] |
| If pname:usage includes ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the pname:pNext |
| chain must: include a valid slink:VkVideoProfilesKHR structure which |
| includes at least one slink:VkVideoProfileKHR with a encode |
| codec-operation |
| endif::VK_KHR_video_encode_queue[] |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| * [[VUID-VkImageCreateInfo-pNext-06390]] |
| If the slink:VkImage is to be used to import memory from a |
| slink:VkBufferCollectionFUCHSIA, a |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA structure must: be |
| chained to pname:pNext. |
| endif::VK_FUCHSIA_buffer_collection[] |
| **** |
| |
| include::{generated}/validity/structs/VkImageCreateInfo.txt[] |
| -- |
| |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| [open,refpage='VkBufferCollectionImageCreateInfoFUCHSIA',desc='Create a VkBufferCollectionFUCHSIA-compatible VkImage',type='structs'] |
| -- |
| The sname:VkBufferCollectionImageCreateInfoFUCHSIA structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferCollectionImageCreateInfoFUCHSIA.txt[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:collection is the slink:VkBufferCollectionFUCHSIA handle |
| * pname:index is the index of the buffer in the buffer collection from |
| which the memory will be imported |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBufferCollectionImageCreateInfoFUCHSIA-index-06391]] |
| pname:index must: be less than |
| slink:VkBufferCollectionPropertiesFUCHSIA::pname:bufferCount |
| **** |
| |
| include::{generated}/validity/structs/VkBufferCollectionImageCreateInfoFUCHSIA.txt[] |
| -- |
| endif::VK_FUCHSIA_buffer_collection[] |
| |
| ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| [open,refpage='VkImageStencilUsageCreateInfo',desc='Specify separate usage flags for the stencil aspect of a depth-stencil image',type='structs',alias='VkImageStencilUsageCreateInfoEXT'] |
| -- |
| The sname:VkImageStencilUsageCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkImageStencilUsageCreateInfo.txt[] |
| |
| ifdef::VK_EXT_separate_stencil_usage[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkImageStencilUsageCreateInfoEXT.txt[] |
| endif::VK_EXT_separate_stencil_usage[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:stencilUsage is a bitmask of elink:VkImageUsageFlagBits describing |
| the intended usage of the stencil aspect of the image. |
| |
| If the pname:pNext chain of slink:VkImageCreateInfo includes a |
| sname:VkImageStencilUsageCreateInfo structure, then that structure includes |
| the usage flags specific to the stencil aspect of the image for an image |
| with a depth-stencil format. |
| |
| This structure specifies image usages which only apply to the stencil aspect |
| of a depth/stencil format image. |
| When this structure is included in the pname:pNext chain of |
| slink:VkImageCreateInfo, the stencil aspect of the image must: only be used |
| as specified by pname:stencilUsage. |
| When this structure is not included in the pname:pNext chain of |
| slink:VkImageCreateInfo, the stencil aspect of an image must: only be used |
| as specified by slink:VkImageCreateInfo::pname:usage. |
| Use of other aspects of an image are unaffected by this structure. |
| |
| This structure can: also be included in the pname:pNext chain of |
| slink:VkPhysicalDeviceImageFormatInfo2 to query additional capabilities |
| specific to image creation parameter combinations including a separate set |
| of usage flags for the stencil aspect of the image using |
| flink:vkGetPhysicalDeviceImageFormatProperties2. |
| When this structure is not included in the pname:pNext chain of |
| sname:VkPhysicalDeviceImageFormatInfo2 then the implicit value of |
| pname:stencilUsage matches that of |
| sname:VkPhysicalDeviceImageFormatInfo2::pname:usage. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageStencilUsageCreateInfo-stencilUsage-02539]] |
| If pname:stencilUsage includes |
| ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT, it must: not include bits |
| other than ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT or |
| ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT |
| **** |
| |
| include::{generated}/validity/structs/VkImageStencilUsageCreateInfo.txt[] |
| -- |
| endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| |
| ifdef::VK_NV_dedicated_allocation[] |
| [open,refpage='VkDedicatedAllocationImageCreateInfoNV',desc='Specify that an image is bound to a dedicated memory resource',type='structs'] |
| -- |
| If the pname:pNext chain includes a |
| sname:VkDedicatedAllocationImageCreateInfoNV structure, then that structure |
| includes an enable controlling whether the image will have a dedicated |
| memory allocation bound to it. |
| |
| The sname:VkDedicatedAllocationImageCreateInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkDedicatedAllocationImageCreateInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:dedicatedAllocation specifies whether the image will have a |
| dedicated allocation bound to it. |
| |
| [NOTE] |
| .Note |
| ==== |
| Using a dedicated allocation for color and depth/stencil attachments or |
| other large images may: improve performance on some devices. |
| ==== |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDedicatedAllocationImageCreateInfoNV-dedicatedAllocation-00994]] |
| If pname:dedicatedAllocation is ename:VK_TRUE, |
| slink:VkImageCreateInfo::pname:flags must: not include |
| ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or |
| ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT |
| **** |
| |
| include::{generated}/validity/structs/VkDedicatedAllocationImageCreateInfoNV.txt[] |
| -- |
| endif::VK_NV_dedicated_allocation[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| [open,refpage='VkExternalMemoryImageCreateInfo',desc='Specify that an image may be backed by external memory',type='structs'] |
| -- |
| To define a set of external memory handle types that may: be used as backing |
| store for an image, add a slink:VkExternalMemoryImageCreateInfo structure to |
| the pname:pNext chain of the slink:VkImageCreateInfo structure. |
| The sname:VkExternalMemoryImageCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkExternalMemoryImageCreateInfo.txt[] |
| |
| ifdef::VK_KHR_external_memory[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkExternalMemoryImageCreateInfoKHR.txt[] |
| endif::VK_KHR_external_memory[] |
| |
| [NOTE] |
| .Note |
| ==== |
| A sname:VkExternalMemoryImageCreateInfo structure with a non-zero |
| pname:handleTypes field must be included in the creation parameters for an |
| image that will be bound to memory that is either exported or imported. |
| ==== |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:handleTypes is zero, or a bitmask of |
| elink:VkExternalMemoryHandleTypeFlagBits specifying one or more external |
| memory handle types. |
| |
| include::{generated}/validity/structs/VkExternalMemoryImageCreateInfo.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| ifdef::VK_NV_external_memory[] |
| [open,refpage='VkExternalMemoryImageCreateInfoNV',desc='Specify that an image may be backed by external memory',type='structs'] |
| -- |
| If the pname:pNext chain includes a sname:VkExternalMemoryImageCreateInfoNV |
| structure, then that structure defines a set of external memory handle types |
| that may: be used as backing store for the image. |
| |
| The sname:VkExternalMemoryImageCreateInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkExternalMemoryImageCreateInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:handleTypes is zero, or a bitmask of |
| elink:VkExternalMemoryHandleTypeFlagBitsNV specifying one or more |
| external memory handle types. |
| |
| include::{generated}/validity/structs/VkExternalMemoryImageCreateInfoNV.txt[] |
| -- |
| endif::VK_NV_external_memory[] |
| |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| [open,refpage='VkExternalFormatANDROID',desc='Structure containing an Android hardware buffer external format',type='structs'] |
| -- |
| To create an image with an |
| <<memory-external-android-hardware-buffer-external-formats,external |
| format>>, add a sname:VkExternalFormatANDROID structure in the pname:pNext |
| chain of slink:VkImageCreateInfo. |
| sname:VkExternalFormatANDROID is defined as: |
| |
| include::{generated}/api/structs/VkExternalFormatANDROID.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:externalFormat is an implementation-defined identifier for the |
| external format |
| |
| If pname:externalFormat is zero, the effect is as if the |
| sname:VkExternalFormatANDROID structure was not present. |
| Otherwise, the pname:image will have the specified external format. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkExternalFormatANDROID-externalFormat-01894]] |
| pname:externalFormat must: be `0` or a value returned in the |
| pname:externalFormat member of |
| slink:VkAndroidHardwareBufferFormatPropertiesANDROID by an earlier call |
| to flink:vkGetAndroidHardwareBufferPropertiesANDROID |
| **** |
| |
| include::{generated}/validity/structs/VkExternalFormatANDROID.txt[] |
| -- |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| ifdef::VK_KHR_swapchain[] |
| [open,refpage='VkImageSwapchainCreateInfoKHR',desc='Specify that an image will be bound to swapchain memory',type='structs'] |
| -- |
| If the pname:pNext chain of slink:VkImageCreateInfo includes a |
| sname:VkImageSwapchainCreateInfoKHR structure, then that structure includes |
| a swapchain handle indicating that the image will be bound to memory from |
| that swapchain. |
| |
| The sname:VkImageSwapchainCreateInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkImageSwapchainCreateInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:swapchain is dlink:VK_NULL_HANDLE or a handle of a swapchain that |
| the image will be bound to. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageSwapchainCreateInfoKHR-swapchain-00995]] |
| If pname:swapchain is not dlink:VK_NULL_HANDLE, the fields of |
| slink:VkImageCreateInfo must: match the |
| <<swapchain-wsi-image-create-info, implied image creation parameters>> |
| of the swapchain |
| **** |
| |
| include::{generated}/validity/structs/VkImageSwapchainCreateInfoKHR.txt[] |
| -- |
| endif::VK_KHR_swapchain[] |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| |
| ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] |
| [open,refpage='VkImageFormatListCreateInfo',desc='Specify that an image can: be used with a particular set of formats',type='structs',alias='VkImageFormatListCreateInfoKHR'] |
| -- |
| If the pname:pNext chain of slink:VkImageCreateInfo includes a |
| sname:VkImageFormatListCreateInfo structure, then that structure contains a |
| list of all formats that can: be used when creating views of this image. |
| |
| The sname:VkImageFormatListCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkImageFormatListCreateInfo.txt[] |
| |
| ifdef::VK_KHR_image_format_list[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkImageFormatListCreateInfoKHR.txt[] |
| endif::VK_KHR_image_format_list[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:viewFormatCount is the number of entries in the pname:pViewFormats |
| array. |
| * pname:pViewFormats is a pointer to an array of elink:VkFormat values |
| specifying all formats which can: be used when creating views of this |
| image. |
| |
| If pname:viewFormatCount is zero, pname:pViewFormats is ignored and the |
| image is created as if the sname:VkImageFormatListCreateInfo structure were |
| not included in the pname:pNext chain of slink:VkImageCreateInfo. |
| |
| include::{generated}/validity/structs/VkImageFormatListCreateInfo.txt[] |
| -- |
| endif::VK_VERSION_1_2,VK_KHR_image_format_list[] |
| |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| [open,refpage='VkImageDrmFormatModifierListCreateInfoEXT',desc='Specify that an image must be created with a DRM format modifier from the provided list',type='structs'] |
| -- |
| If the pname:pNext chain of slink:VkImageCreateInfo includes a |
| slink:VkImageDrmFormatModifierListCreateInfoEXT structure, then the image |
| will be created with one of the <<glossary-drm-format-modifier,Linux DRM |
| format modifiers>> listed in the structure. |
| The choice of modifier is implementation-dependent. |
| |
| The slink:VkImageDrmFormatModifierListCreateInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkImageDrmFormatModifierListCreateInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:drmFormatModifierCount is the length of the |
| pname:pDrmFormatModifiers array. |
| * pname:pDrmFormatModifiers is a pointer to an array of _Linux DRM format |
| modifiers_. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageDrmFormatModifierListCreateInfoEXT-pDrmFormatModifiers-02263]] |
| Each _modifier_ in pname:pDrmFormatModifiers must: be compatible with |
| the parameters in slink:VkImageCreateInfo and its pname:pNext chain, as |
| determined by querying slink:VkPhysicalDeviceImageFormatInfo2 extended |
| with slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT |
| **** |
| |
| include::{generated}/validity/structs/VkImageDrmFormatModifierListCreateInfoEXT.txt[] |
| -- |
| |
| [open,refpage='VkImageDrmFormatModifierExplicitCreateInfoEXT',desc='Specify that an image be created with the provided DRM format modifier and explicit memory layout',type='structs'] |
| -- |
| If the pname:pNext chain of slink:VkImageCreateInfo includes a |
| slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure, then the |
| image will be created with the <<glossary-drm-format-modifier,Linux DRM |
| format modifier>> and memory layout defined by the structure. |
| |
| The slink:VkImageDrmFormatModifierExplicitCreateInfoEXT structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkImageDrmFormatModifierExplicitCreateInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:drmFormatModifier is the _Linux DRM format modifier_ with which |
| the image will be created. |
| * pname:drmFormatModifierPlaneCount is the number of _memory planes_ in |
| the image (as reported by slink:VkDrmFormatModifierPropertiesEXT) as |
| well as the length of the pname:pPlaneLayouts array. |
| * pname:pPlaneLayouts is a pointer to an array of |
| slink:VkSubresourceLayout structures describing the image's _memory |
| planes_. |
| |
| The etext:i^th^ member of pname:pPlaneLayouts describes the layout of the |
| image's etext:i^th^ _memory plane_ (that is, |
| `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT`). |
| In each element of pname:pPlaneLayouts, the implementation must: ignore |
| pname:size. |
| The implementation calculates the size of each plane, which the application |
| can: query with flink:vkGetImageSubresourceLayout. |
| |
| When creating an image with |
| slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, it is the application's |
| responsibility to satisfy all valid usage requirements. |
| However, the implementation must: validate that the provided |
| pname:pPlaneLayouts, when combined with the provided pname:drmFormatModifier |
| and other creation parameters in slink:VkImageCreateInfo and its pname:pNext |
| chain, produce a valid image. |
| (This validation is necessarily implementation-dependent and outside the |
| scope of Vulkan, and therefore not described by valid usage requirements). |
| If this validation fails, then flink:vkCreateImage returns |
| ename:VK_ERROR_INVALID_DRM_FORMAT_MODIFIER_PLANE_LAYOUT_EXT. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-drmFormatModifier-02264]] |
| pname:drmFormatModifier must: be compatible with the parameters in |
| slink:VkImageCreateInfo and its pname:pNext chain, as determined by |
| querying slink:VkPhysicalDeviceImageFormatInfo2 extended with |
| slink:VkPhysicalDeviceImageDrmFormatModifierInfoEXT |
| * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-drmFormatModifierPlaneCount-02265]] |
| pname:drmFormatModifierPlaneCount must: be equal to the |
| slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount |
| associated with slink:VkImageCreateInfo::pname:format and |
| pname:drmFormatModifier, as found by querying |
| slink:VkDrmFormatModifierPropertiesListEXT |
| * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-size-02267]] |
| For each element of pname:pPlaneLayouts, pname:size must: be 0 |
| * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-arrayPitch-02268]] |
| For each element of pname:pPlaneLayouts, pname:arrayPitch must: be 0 if |
| slink:VkImageCreateInfo::pname:arrayLayers is 1 |
| * [[VUID-VkImageDrmFormatModifierExplicitCreateInfoEXT-depthPitch-02269]] |
| For each element of pname:pPlaneLayouts, pname:depthPitch must: be 0 if |
| slink:VkImageCreateInfo::pname:extent.depth is 1 |
| **** |
| |
| include::{generated}/validity/structs/VkImageDrmFormatModifierExplicitCreateInfoEXT.txt[] |
| -- |
| endif::VK_EXT_image_drm_format_modifier[] |
| |
| [open,refpage='VkImageUsageFlagBits',desc='Bitmask specifying intended usage of an image',type='enums'] |
| -- |
| Bits which can: be set in |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| slink:VkImageViewUsageCreateInfo::pname:usage, or |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| slink:VkImageStencilUsageCreateInfo::pname:stencilUsage, or |
| endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| slink:VkImageCreateInfo::pname:usage, specifying intended usage of an image, |
| are: |
| |
| include::{generated}/api/enums/VkImageUsageFlagBits.txt[] |
| |
| * ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT specifies that the image can: be |
| used as the source of a transfer command. |
| * ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT specifies that the image can: be |
| used as the destination of a transfer command. |
| * ename:VK_IMAGE_USAGE_SAMPLED_BIT specifies that the image can: be used |
| to create a sname:VkImageView suitable for occupying a |
| sname:VkDescriptorSet slot either of type |
| ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or |
| ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, and be sampled by a |
| shader. |
| * ename:VK_IMAGE_USAGE_STORAGE_BIT specifies that the image can: be used |
| to create a sname:VkImageView suitable for occupying a |
| sname:VkDescriptorSet slot of type |
| ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE. |
| * ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT specifies that the image can: |
| be used to create a sname:VkImageView suitable for use as a color or |
| resolve attachment in a sname:VkFramebuffer. |
| * ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT specifies that the |
| image can: be used to create a sname:VkImageView suitable for use as a |
| depth/stencil |
| ifdef::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] |
| or depth/stencil resolve |
| endif::VK_VERSION_1_2,VK_KHR_depth_stencil_resolve[] |
| attachment in a sname:VkFramebuffer. |
| * ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT specifies that |
| implementations may: support using <<memory, memory allocations>> with |
| the ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT to back an image with |
| this usage. |
| This bit can: be set for any image that can: be used to create a |
| sname:VkImageView suitable for use as a color, resolve, depth/stencil, |
| or input attachment. |
| * ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT specifies that the image can: |
| be used to create a sname:VkImageView suitable for occupying |
| sname:VkDescriptorSet slot of type |
| ename:VK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT; be read from a shader as an |
| input attachment; and be used as an input attachment in a framebuffer. |
| ifdef::VK_EXT_fragment_density_map[] |
| * ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT specifies that the |
| image can: be used to create a sname:VkImageView suitable for use as a |
| <<fragmentdensitymapops, fragment density map image>>. |
| endif::VK_EXT_fragment_density_map[] |
| ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] |
| * ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies |
| that the image can: be used to create a sname:VkImageView suitable for |
| use as a |
| ifdef::VK_KHR_fragment_shading_rate[] |
| <<primsrast-fragment-shading-rate-attachment, fragment shading rate |
| attachment>> |
| endif::VK_KHR_fragment_shading_rate[] |
| ifdef::VK_KHR_fragment_shading_rate+VK_NV_shading_rate_image[or] |
| ifdef::VK_NV_shading_rate_image[] |
| <<primsrast-shading-rate-image, shading rate image>> |
| endif::VK_NV_shading_rate_image[] |
| endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] |
| ifdef::VK_KHR_video_decode_queue[] |
| * ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR specifies that |
| <<video-decode-operations, video decode operations>> can use the image |
| as a <<reference-picture,reference picture>>, or a source of |
| postprocessing, or transfer operation. |
| * ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR specifies that |
| <<video-decode-operations, video decode operations>> can use the image |
| as a <<video-picture-resources,DPB Video Picture Resource>>, |
| representing a <<reference-picture,reference picture>>. |
| This flag must: be combined with |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR and |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR. |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR is required for DPB image |
| resources because these resources will be associated with |
| <<reference-picture,reference pictures>> after acting as targets for |
| video decode operations. |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR is required for DPB image |
| resources because the <<reference-picture,reference pictures>> |
| associated with them act as information sources for subsequent decode |
| operations. |
| endif::VK_KHR_video_decode_queue[] |
| ifdef::VK_KHR_video_encode_queue[] |
| * ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR specifies that the image |
| can be used as an <<input-encode-picture,input picture>> for |
| <<video-encode-operations, video encode operations>>. |
| * ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR specifies that |
| <<video-encode-operations, video encode operations>> can use the image |
| to hold a <<video-picture-resources,reconstructed picture>>, and to act |
| as a <<reference-picture,reference picture>>. |
| This flag must: be combined with |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR and |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR. |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR is required for a DPB |
| image resource because the reconstructed picture resulting from an |
| encode operation will be written to it. |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR is required for DPB image |
| resources because it can be used as a <<reference-picture,reconstructed |
| reference picture>> source for the encode operation. |
| endif::VK_KHR_video_encode_queue[] |
| -- |
| |
| [open,refpage='VkImageUsageFlags',desc='Bitmask of VkImageUsageFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkImageUsageFlags.txt[] |
| |
| tname:VkImageUsageFlags is a bitmask type for setting a mask of zero or more |
| elink:VkImageUsageFlagBits. |
| |
| [[valid-imageview-imageusage]] |
| When creating a sname:VkImageView one of the following |
| elink:VkImageUsageFlagBits must: be set: |
| |
| * ename:VK_IMAGE_USAGE_SAMPLED_BIT |
| * ename:VK_IMAGE_USAGE_STORAGE_BIT |
| * ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT |
| * ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT |
| * ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT |
| ifdef::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] |
| * ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR |
| endif::VK_NV_shading_rate_image,VK_KHR_fragment_shading_rate[] |
| ifdef::VK_EXT_fragment_density_map[] |
| * ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT |
| endif::VK_EXT_fragment_density_map[] |
| -- |
| |
| [open,refpage='VkImageCreateFlagBits',desc='Bitmask specifying additional parameters of an image',type='enums'] |
| -- |
| Bits which can: be set in slink:VkImageCreateInfo::pname:flags, specifying |
| additional parameters of an image, are: |
| |
| include::{generated}/api/enums/VkImageCreateFlagBits.txt[] |
| |
| * ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT specifies that the image will |
| be backed using sparse memory binding. |
| * ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT specifies that the image can: |
| be partially backed using sparse memory binding. |
| Images created with this flag must: also be created with the |
| ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag. |
| * ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT specifies that the image will |
| be backed using sparse memory binding with memory ranges that might also |
| simultaneously be backing another image (or another portion of the same |
| image). |
| Images created with this flag must: also be created with the |
| ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT flag. |
| * ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that the image can: |
| be used to create a sname:VkImageView with a different format from the |
| image. |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| For <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> formats, |
| ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that a |
| sname:VkImageView can be created of a _plane_ of the image. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT specifies that the image can: |
| be used to create a sname:VkImageView of type |
| ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY. |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT specifies that the image |
| can: be used to create a sname:VkImageView of type |
| ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| ifdef::VK_VERSION_1_1[] |
| * ename:VK_IMAGE_CREATE_PROTECTED_BIT specifies that the image is a |
| protected image. |
| endif::VK_VERSION_1_1[] |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| * ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT specifies that the |
| image can: be used with a non-zero value of the |
| pname:splitInstanceBindRegionCount member of a |
| slink:VkBindImageMemoryDeviceGroupInfo structure passed into |
| flink:vkBindImageMemory2. |
| This flag also has the effect of making the image use the standard |
| sparse image block dimensions. |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| * ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT specifies that the |
| image having a compressed format can: be used to create a |
| sname:VkImageView with an uncompressed format where each texel in the |
| image view corresponds to a compressed texel block of the image. |
| * ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT specifies that the image can: |
| be created with usage flags that are not supported for the format the |
| image is created with but are supported for at least one format a |
| sname:VkImageView created from the image can: have. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * ename:VK_IMAGE_CREATE_DISJOINT_BIT specifies that an image with a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>> must: |
| have each plane separately bound to memory, rather than having a single |
| memory binding for the whole image; the presence of this bit |
| distinguishes a _disjoint image_ from an image without this bit set. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| * ename:VK_IMAGE_CREATE_ALIAS_BIT specifies that two images created with |
| the same creation parameters and aliased to the same memory can: |
| interpret the contents of the memory consistently with each other, |
| subject to the rules described in the <<resources-memory-aliasing,Memory |
| Aliasing>> section. |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| This flag further specifies that each plane of a _disjoint_ image can: |
| share an in-memory non-linear representation with single-plane images, |
| and that a single-plane image can: share an in-memory non-linear |
| representation with a plane of a multi-planar disjoint image, according |
| to the rules in <<formats-compatible-planes>>. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] |
| If the pname:pNext chain includes a |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[slink:VkExternalMemoryImageCreateInfo] |
| // Jon: logic needs to incorporate VK_VERSION_1_1 |
| ifdef::VK_KHR_external_memory+VK_NV_external_memory[or] |
| ifdef::VK_NV_external_memory[slink:VkExternalMemoryImageCreateInfoNV] |
| structure whose pname:handleTypes member is not `0`, it is as if |
| ename:VK_IMAGE_CREATE_ALIAS_BIT is set. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[] |
| endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| ifdef::VK_EXT_sample_locations[] |
| * ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT |
| specifies that an image with a depth or depth/stencil format can: be |
| used with custom sample locations when used as a depth/stencil |
| attachment. |
| endif::VK_EXT_sample_locations[] |
| ifdef::VK_NV_corner_sampled_image[] |
| * ename:VK_IMAGE_CREATE_CORNER_SAMPLED_BIT_NV specifies that the image is |
| a <<resources-images-corner-sampled,corner-sampled image>>. |
| endif::VK_NV_corner_sampled_image[] |
| ifdef::VK_EXT_fragment_density_map[] |
| * ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT specifies that an image can: be |
| in a subsampled format which may: be more optimal when written as an |
| attachment by a render pass that has a fragment density map attachment. |
| Accessing a subsampled image has additional considerations: |
| ** Image data read as an image sampler will have undefined: values if the |
| sampler was not created with pname:flags containing |
| ename:VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT or was not sampled through |
| the use of a combined image sampler with an immutable sampler in |
| sname:VkDescriptorSetLayoutBinding. |
| ** Image data read with an input attachment will have undefined: values if |
| the contents were not written as an attachment in an earlier subpass of |
| the same render pass. |
| ifdef::VK_EXT_fragment_density_map2[] |
| ** Image data read as an image sampler in the fragment shader will be |
| additionally be read by the device during |
| ename:VK_PIPELINE_STAGE_VERTEX_SHADER_BIT if |
| <<limits-subsampledCoarseReconstructionEarlyAccess,sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:subsampledCoarseReconstructionEarlyAccess>> |
| is ename:VK_TRUE and the sampler was created with pname:flags |
| containing |
| ename:VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT. |
| ** Image data read with load operations are resampled to the fragment |
| density of the render pass if |
| <<limits-subsampledLoads,sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:subsampledLoads>> |
| is ename:VK_TRUE. |
| Otherwise, values of image data are undefined:. |
| endif::VK_EXT_fragment_density_map2[] |
| ifndef::VK_EXT_fragment_density_map2[] |
| ** Image data read with load operations may: be resampled to the fragment |
| density of the render pass. |
| endif::VK_EXT_fragment_density_map2[] |
| ** Image contents outside of the render area take on undefined: values if |
| the image is stored as a render pass attachment. |
| endif::VK_EXT_fragment_density_map[] |
| |
| See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and |
| <<sparsememory-physicalfeatures,Sparse Physical Device Features>> for more |
| details. |
| -- |
| |
| [open,refpage='VkImageCreateFlags',desc='Bitmask of VkImageCreateFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkImageCreateFlags.txt[] |
| |
| tname:VkImageCreateFlags is a bitmask type for setting a mask of zero or |
| more elink:VkImageCreateFlagBits. |
| -- |
| |
| [open,refpage='VkImageType',desc='Specifies the type of an image object',type='enums'] |
| -- |
| Possible values of slink:VkImageCreateInfo::pname:imageType, specifying the |
| basic dimensionality of an image, are: |
| |
| include::{generated}/api/enums/VkImageType.txt[] |
| |
| * ename:VK_IMAGE_TYPE_1D specifies a one-dimensional image. |
| * ename:VK_IMAGE_TYPE_2D specifies a two-dimensional image. |
| * ename:VK_IMAGE_TYPE_3D specifies a three-dimensional image. |
| -- |
| |
| [open,refpage='VkImageTiling',desc='Specifies the tiling arrangement of data in an image',type='enums'] |
| -- |
| Possible values of slink:VkImageCreateInfo::pname:tiling, specifying the |
| tiling arrangement of texel blocks in an image, are: |
| |
| include::{generated}/api/enums/VkImageTiling.txt[] |
| |
| * ename:VK_IMAGE_TILING_OPTIMAL specifies optimal tiling (texels are laid |
| out in an implementation-dependent arrangement, for more efficient |
| memory access). |
| * ename:VK_IMAGE_TILING_LINEAR specifies linear tiling (texels are laid |
| out in memory in row-major order, possibly with some padding on each |
| row). |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT indicates that the image's |
| tiling is defined by a <<glossary-drm-format-modifier,Linux DRM format |
| modifier>>. |
| The modifier is specified at image creation with |
| slink:VkImageDrmFormatModifierListCreateInfoEXT or |
| slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, and can: be queried |
| with flink:vkGetImageDrmFormatModifierPropertiesEXT. |
| endif::VK_EXT_image_drm_format_modifier[] |
| -- |
| |
| [open,refpage='vkGetImageSubresourceLayout',desc='Retrieve information about an image subresource',type='protos'] |
| -- |
| To query the memory layout of an image subresource, call: |
| |
| include::{generated}/api/protos/vkGetImageSubresourceLayout.txt[] |
| |
| * pname:device is the logical device that owns the image. |
| * pname:image is the image whose layout is being queried. |
| * pname:pSubresource is a pointer to a slink:VkImageSubresource structure |
| selecting a specific image for the image subresource. |
| * pname:pLayout is a pointer to a slink:VkSubresourceLayout structure in |
| which the layout is returned. |
| |
| ifndef::VK_EXT_image_drm_format_modifier[] |
| The image must: be <<glossary-linear-resource,linear>>. |
| The |
| endif::VK_EXT_image_drm_format_modifier[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| If the image is <<glossary-linear-resource,linear>>, then the |
| endif::VK_EXT_image_drm_format_modifier[] |
| returned layout is valid for <<memory-device-hostaccess, host access>>. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If the image's |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| tiling is ename:VK_IMAGE_TILING_LINEAR and its |
| endif::VK_EXT_image_drm_format_modifier[] |
| format is a <<formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>>, then fname:vkGetImageSubresourceLayout describes one |
| ifdef::VK_EXT_image_drm_format_modifier[_format plane_] |
| ifndef::VK_EXT_image_drm_format_modifier[plane] |
| of the image. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then |
| fname:vkGetImageSubresourceLayout describes one _memory plane_ of the image. |
| If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT and |
| the image is <<glossary-linear-resource,non-linear>>, then the returned |
| layout has an implementation-dependent meaning; the vendor of the image's |
| <<glossary-drm-format-modifier,DRM format modifier>> may: provide |
| documentation that explains how to interpret the returned layout. |
| endif::VK_EXT_image_drm_format_modifier[] |
| |
| fname:vkGetImageSubresourceLayout is invariant for the lifetime of a single |
| image. |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| However, the subresource layout of images in Android hardware buffer |
| external memory is not known until the image has been bound to memory, so |
| applications must: not call flink:vkGetImageSubresourceLayout for such an |
| image before it has been bound. |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| |
| .Valid Usage |
| **** |
| ifndef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-vkGetImageSubresourceLayout-image-00996]] |
| pname:image must: have been created with pname:tiling equal to |
| ename:VK_IMAGE_TILING_LINEAR |
| endif::VK_EXT_image_drm_format_modifier[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-vkGetImageSubresourceLayout-image-02270]] |
| pname:image must: have been created with pname:tiling equal to |
| ename:VK_IMAGE_TILING_LINEAR or |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT |
| endif::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-vkGetImageSubresourceLayout-aspectMask-00997]] |
| The pname:aspectMask member of pname:pSubresource must: only have a |
| single bit set |
| * [[VUID-vkGetImageSubresourceLayout-mipLevel-01716]] |
| The pname:mipLevel member of pname:pSubresource must: be less than the |
| pname:mipLevels specified in slink:VkImageCreateInfo when pname:image |
| was created |
| * [[VUID-vkGetImageSubresourceLayout-arrayLayer-01717]] |
| The pname:arrayLayer member of pname:pSubresource must: be less than the |
| pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image |
| was created |
| * [[VUID-vkGetImageSubresourceLayout-format-04461]] |
| If pname:format is a color format, the pname:aspectMask member of |
| pname:pSubresource must: be ename:VK_IMAGE_ASPECT_COLOR_BIT |
| * [[VUID-vkGetImageSubresourceLayout-format-04462]] |
| If pname:format has a depth component, the pname:aspectMask member of |
| pname:pSubresource must: contain ename:VK_IMAGE_ASPECT_DEPTH_BIT |
| * [[VUID-vkGetImageSubresourceLayout-format-04463]] |
| If pname:format has a stencil component, the pname:aspectMask member of |
| pname:pSubresource must: contain ename:VK_IMAGE_ASPECT_STENCIL_BIT |
| * [[VUID-vkGetImageSubresourceLayout-format-04464]] |
| If pname:format does not contain a stencil or depth component, the |
| pname:aspectMask member of pname:pSubresource must: not contain |
| ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkGetImageSubresourceLayout-format-01581]] |
| If the pname:tiling of the pname:image is ename:VK_IMAGE_TILING_LINEAR |
| and its pname:format is a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>> with |
| two planes, the pname:aspectMask member of pname:pSubresource must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT |
| * [[VUID-vkGetImageSubresourceLayout-format-01582]] |
| If the pname:tiling of the pname:image is ename:VK_IMAGE_TILING_LINEAR |
| and its pname:format is a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>> with |
| three planes, the pname:aspectMask member of pname:pSubresource must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-vkGetImageSubresourceLayout-image-01895]] |
| If pname:image was created with the |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID |
| external memory handle type, then pname:image must: be bound to memory |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-vkGetImageSubresourceLayout-tiling-02271]] |
| If the pname:tiling of the pname:image is |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then the pname:aspectMask |
| member of pname:pSubresource must: be |
| `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` and the index _i_ must: |
| be less than the |
| slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount |
| associated with the image's pname:format and |
| slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier |
| endif::VK_EXT_image_drm_format_modifier[] |
| **** |
| |
| include::{generated}/validity/protos/vkGetImageSubresourceLayout.txt[] |
| -- |
| |
| [open,refpage='VkImageSubresource',desc='Structure specifying an image subresource',type='structs'] |
| -- |
| The sname:VkImageSubresource structure is defined as: |
| |
| include::{generated}/api/structs/VkImageSubresource.txt[] |
| |
| * pname:aspectMask is a tlink:VkImageAspectFlags value selecting the image |
| _aspect_. |
| * pname:mipLevel selects the mipmap level. |
| * pname:arrayLayer selects the array layer. |
| |
| include::{generated}/validity/structs/VkImageSubresource.txt[] |
| -- |
| |
| [open,refpage='VkSubresourceLayout',desc='Structure specifying subresource layout',type='structs'] |
| -- |
| Information about the layout of the image subresource is returned in a |
| sname:VkSubresourceLayout structure: |
| |
| include::{generated}/api/structs/VkSubresourceLayout.txt[] |
| |
| * pname:offset is the byte offset from the start of the image |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or the plane |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| where the image subresource begins. |
| * pname:size is the size in bytes of the image subresource. |
| pname:size includes any extra memory that is required based on |
| pname:rowPitch. |
| * pname:rowPitch describes the number of bytes between each row of texels |
| in an image. |
| * pname:arrayPitch describes the number of bytes between each array layer |
| of an image. |
| * pname:depthPitch describes the number of bytes between each slice of 3D |
| image. |
| |
| If the image is <<glossary-linear-resource,linear>>, then pname:rowPitch, |
| pname:arrayPitch and pname:depthPitch describe the layout of the image |
| subresource in linear memory. |
| For uncompressed formats, pname:rowPitch is the number of bytes between |
| texels with the same x coordinate in adjacent rows (y coordinates differ by |
| one). |
| pname:arrayPitch is the number of bytes between texels with the same x and y |
| coordinate in adjacent array layers of the image (array layer values differ |
| by one). |
| pname:depthPitch is the number of bytes between texels with the same x and y |
| coordinate in adjacent slices of a 3D image (z coordinates differ by one). |
| Expressed as an addressing formula, the starting byte of a texel in the |
| image subresource has address: |
| |
| [source,c] |
| ~~~~ |
| // (x,y,z,layer) are in texel coordinates |
| address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*elementSize + offset |
| ~~~~ |
| |
| For compressed formats, the pname:rowPitch is the number of bytes between |
| compressed texel blocks in adjacent rows. |
| pname:arrayPitch is the number of bytes between compressed texel blocks in |
| adjacent array layers. |
| pname:depthPitch is the number of bytes between compressed texel blocks in |
| adjacent slices of a 3D image. |
| |
| [source,c] |
| ~~~~ |
| // (x,y,z,layer) are in compressed texel block coordinates |
| address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset; |
| ~~~~ |
| |
| The value of pname:arrayPitch is undefined: for images that were not created |
| as arrays. |
| pname:depthPitch is defined only for 3D images. |
| |
| If the image has a |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| _single-plane_ |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| color format |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| and its tiling is ename:VK_IMAGE_TILING_LINEAR |
| endif::VK_EXT_image_drm_format_modifier[] |
| , then the pname:aspectMask member of sname:VkImageSubresource must: be |
| ename:VK_IMAGE_ASPECT_COLOR_BIT. |
| |
| If the image has a depth/stencil format |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| and its tiling is ename:VK_IMAGE_TILING_LINEAR |
| endif::VK_EXT_image_drm_format_modifier[] |
| , then pname:aspectMask must: be either ename:VK_IMAGE_ASPECT_DEPTH_BIT or |
| ename:VK_IMAGE_ASPECT_STENCIL_BIT. |
| On implementations that store depth and stencil aspects separately, querying |
| each of these image subresource layouts will return a different pname:offset |
| and pname:size representing the region of memory used for that aspect. |
| On implementations that store depth and stencil aspects interleaved, the |
| same pname:offset and pname:size are returned and represent the interleaved |
| memory allocation. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If the image has a <<formats-requiring-sampler-ycbcr-conversion,multi-planar |
| format>> |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| and its tiling is ename:VK_IMAGE_TILING_LINEAR |
| endif::VK_EXT_image_drm_format_modifier[] |
| , then the pname:aspectMask member of sname:VkImageSubresource must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or |
| (for 3-plane formats only) ename:VK_IMAGE_ASPECT_PLANE_2_BIT. |
| Querying each of these image subresource layouts will return a different |
| pname:offset and pname:size representing the region of memory used for that |
| plane. |
| If the image is _disjoint_, then the pname:offset is relative to the base |
| address of the plane. |
| If the image is _non-disjoint_, then the pname:offset is relative to the |
| base address of the image. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| If the image's tiling is ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then |
| the pname:aspectMask member of sname:VkImageSubresource must: be one of |
| `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT`, where the maximum allowed |
| plane index _i_ is defined by the |
| slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount |
| associated with the image's slink:VkImageCreateInfo::pname:format and |
| <<glossary-drm-format-modifier,modifier>>. |
| The memory range used by the subresource is described by pname:offset and |
| pname:size. |
| If the image is _disjoint_, then the pname:offset is relative to the base |
| address of the _memory plane_. |
| If the image is _non-disjoint_, then the pname:offset is relative to the |
| base address of the image. |
| If the image is <<glossary-linear-resource,non-linear>>, then |
| pname:rowPitch, pname:arrayPitch, and pname:depthPitch have an |
| implementation-dependent meaning. |
| endif::VK_EXT_image_drm_format_modifier[] |
| |
| include::{generated}/validity/structs/VkSubresourceLayout.txt[] |
| -- |
| |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| [open,refpage='vkGetImageDrmFormatModifierPropertiesEXT',desc='Returns an image\'s DRM format modifier',type='protos'] |
| -- |
| If an image was created with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, |
| then the image has a <<glossary-drm-format-modifier,Linux DRM format |
| modifier>>. |
| To query the _modifier_, call: |
| |
| include::{generated}/api/protos/vkGetImageDrmFormatModifierPropertiesEXT.txt[] |
| |
| * pname:device is the logical device that owns the image. |
| * pname:image is the queried image. |
| * pname:pProperties is a pointer to a |
| slink:VkImageDrmFormatModifierPropertiesEXT structure in which |
| properties of the image's _DRM format modifier_ are returned. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetImageDrmFormatModifierPropertiesEXT-image-02272]] |
| pname:image must: have been created with |
| <<VkImageCreateInfo,pname:tiling>> equal to |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT |
| **** |
| |
| include::{generated}/validity/protos/vkGetImageDrmFormatModifierPropertiesEXT.txt[] |
| -- |
| |
| [open,refpage='VkImageDrmFormatModifierPropertiesEXT',desc='Properties of an image\'s Linux DRM format modifier',type='structs'] |
| -- |
| The slink:VkImageDrmFormatModifierPropertiesEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkImageDrmFormatModifierPropertiesEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:drmFormatModifier returns the image's |
| <<glossary-drm-format-modifier,Linux DRM format modifier>>. |
| |
| If the pname:image was created with |
| slink:VkImageDrmFormatModifierListCreateInfoEXT, then the returned |
| pname:drmFormatModifier must: belong to the list of modifiers provided at |
| time of image creation in |
| slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:pDrmFormatModifiers. |
| If the pname:image was created with |
| slink:VkImageDrmFormatModifierExplicitCreateInfoEXT, then the returned |
| pname:drmFormatModifier must: be the modifier provided at time of image |
| creation in |
| slink:VkImageDrmFormatModifierExplicitCreateInfoEXT::pname:drmFormatModifier. |
| |
| include::{generated}/validity/structs/VkImageDrmFormatModifierPropertiesEXT.txt[] |
| -- |
| endif::VK_EXT_image_drm_format_modifier[] |
| |
| [open,refpage='vkDestroyImage',desc='Destroy an image object',type='protos'] |
| -- |
| To destroy an image, call: |
| |
| include::{generated}/api/protos/vkDestroyImage.txt[] |
| |
| * pname:device is the logical device that destroys the image. |
| * pname:image is the image to destroy. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkDestroyImage-image-01000]] |
| All submitted commands that refer to pname:image, either directly or via |
| a sname:VkImageView, must: have completed execution |
| * [[VUID-vkDestroyImage-image-01001]] |
| If sname:VkAllocationCallbacks were provided when pname:image was |
| created, a compatible set of callbacks must: be provided here |
| * [[VUID-vkDestroyImage-image-01002]] |
| If no sname:VkAllocationCallbacks were provided when pname:image was |
| created, pname:pAllocator must: be `NULL` |
| ifdef::VK_KHR_swapchain[] |
| * [[VUID-vkDestroyImage-image-04882]] |
| pname:image must: not have been acquired from |
| flink:vkGetSwapchainImagesKHR |
| endif::VK_KHR_swapchain[] |
| **** |
| |
| include::{generated}/validity/protos/vkDestroyImage.txt[] |
| -- |
| |
| |
| [[resources-image-format-features]] |
| === Image Format Features |
| |
| Valid uses of a slink:VkImage may: depend on the image's _format features_, |
| defined below. |
| Such constraints are documented in the affected valid usage statement. |
| |
| * If the image was created with ename:VK_IMAGE_TILING_LINEAR, then its set |
| of _format features_ is the value of |
| slink:VkFormatProperties::pname:linearTilingFeatures found by calling |
| flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as |
| slink:VkImageCreateInfo::pname:format. |
| * If the image was created with ename:VK_IMAGE_TILING_OPTIMAL, |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| but without an |
| <<memory-external-android-hardware-buffer-external-formats,Android |
| hardware buffer external format>>, |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| ifndef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| but without an |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| or an |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA, |
| endif::VK_FUCHSIA_buffer_collection[] |
| then its set of _format features_ is the value of |
| slink:VkFormatProperties::pname:optimalTilingFeatures found by calling |
| flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as |
| slink:VkImageCreateInfo::pname:format. |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * If the image was created with an |
| <<memory-external-android-hardware-buffer-external-formats,Android |
| hardware buffer external format>>, then its set of _format features_ is |
| the value of |
| slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures |
| found by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID on |
| the Android hardware buffer that was imported to the |
| slink:VkDeviceMemory to which the image is bound. |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * If the image was created with |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then: |
| ** The image's DRM format modifier is the value of |
| slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:drmFormatModifier |
| found by calling flink:vkGetImageDrmFormatModifierPropertiesEXT. |
| ** Let |
| slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties |
| be the array found by calling |
| flink:vkGetPhysicalDeviceFormatProperties2 on the same pname:format as |
| slink:VkImageCreateInfo::pname:format. |
| ** Let `VkDrmFormatModifierPropertiesEXT prop` be an array element whose |
| pname:drmFormatModifier member is the value of the image's DRM format |
| modifier. |
| ** Then the image set of _format features_ is the value of taking the |
| bitwise intersection over the collected |
| `prop`::pname:drmFormatModifierTilingFeatures. |
| endif::VK_EXT_image_drm_format_modifier[] |
| |
| |
| ifdef::VK_NV_corner_sampled_image[] |
| [[resources-images-corner-sampled]] |
| === Corner-Sampled Images |
| |
| A _corner-sampled image_ is an image where unnormalized texel coordinates |
| are centered on integer values rather than half-integer values. |
| |
| A corner-sampled image has a number of differences compared to conventional |
| texture image: |
| |
| * Texels are centered on integer coordinates. |
| See <<textures-unnormalized-to-integer, Unnormalized Texel Coordinate |
| Operations>> |
| * Normalized coordinates are scaled using [eq]#coord {times} (dim - 1)# |
| rather than [eq]#coord {times} dim#, where dim is the size of one |
| dimension of the image. |
| See <<textures-normalized-to-unnormalized, normalized texel coordinate |
| transform>>. |
| * Partial derivatives are scaled using [eq]#coord {times} (dim - 1)# |
| rather than [eq]#coord {times} dim#. |
| See <<textures-scale-factor,Scale Factor Operation>>. |
| * Calculation of the next higher lod size goes according to |
| [eq]#{lceil}dim / 2{rceil}# rather than [eq]#{lfloor}dim / 2{rfloor}#. |
| See <<resources-image-miplevel-sizing,Image Miplevel Sizing>>. |
| * The minimum level size is 2x2 for 2D images and 2x2x2 for 3D images. |
| See <<resources-image-miplevel-sizing,Image Miplevel Sizing>>. |
| |
| Corner-sampling is only supported for 2D and 3D images. |
| When sampling a corner-sampled image, the sampler addressing mode must: be |
| ename:VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE. |
| Corner-sampled images are not supported as cube maps or depth/stencil |
| images. |
| endif::VK_NV_corner_sampled_image[] |
| |
| |
| [[resources-image-miplevel-sizing]] |
| === Image Miplevel Sizing |
| |
| A _complete mipmap chain_ is the full set of miplevels, from the largest |
| miplevel provided, down to the _minimum miplevel size_. |
| |
| |
| ==== Conventional Images |
| |
| For conventional images, the dimensions of each successive miplevel, |
| [eq]#n+1#, are: |
| |
| {empty}:: [eq]#pname:width~n+1~ = max({lfloor}pname:width~n~/2{rfloor}, |
| 1)# |
| {empty}:: [eq]#pname:height~n+1~ = max({lfloor}pname:height~n~/2{rfloor}, |
| 1)# |
| {empty}:: [eq]#pname:depth~n+1~ = max({lfloor}pname:depth~n~/2{rfloor}, |
| 1)# |
| |
| where [eq]#pname:width~n~#, [eq]#pname:height~n~#, and [eq]#pname:depth~n~# |
| are the dimensions of the next larger miplevel, [eq]#n#. |
| |
| The minimum miplevel size is: |
| |
| * 1 for one-dimensional images, |
| * 1x1 for two-dimensional images, and |
| * 1x1x1 for three-dimensional images. |
| |
| The number of levels in a complete mipmap chain is: |
| |
| {empty}:: [eq]#{lfloor}log~2~(max(pname:width~0~, pname:height~0~, |
| pname:depth~0~)){rfloor} {plus} 1# |
| |
| where [eq]#pname:width~0~#, [eq]#pname:height~0~#, and [eq]#pname:depth~0~# |
| are the dimensions of the largest (most detailed) miplevel, `0`. |
| |
| |
| ifdef::VK_NV_corner_sampled_image[] |
| ==== Corner-Sampled Images |
| |
| For corner-sampled images, the dimensions of each successive miplevel, |
| [eq]#n+1#, are: |
| |
| {empty}:: [eq]#pname:width~n+1~ = max({lceil}pname:width~n~/2{rceil}, 2)# |
| {empty}:: [eq]#pname:height~n+1~ = max({lceil}pname:height~n~/2{rceil}, |
| 2)# |
| {empty}:: [eq]#pname:depth~n+1~ = max({lceil}pname:depth~n~/2{rceil}, 2)# |
| |
| where [eq]#pname:width~n~#, [eq]#pname:height~n~#, and [eq]#pname:depth~n~# |
| are the dimensions of the next larger miplevel, [eq]#n#. |
| |
| The minimum miplevel size is: |
| |
| * 2x2 for two-dimensional images, and |
| * 2x2x2 for three-dimensional images. |
| |
| The number of levels in a complete mipmap chain is: |
| |
| {empty}:: [eq]#{lceil}log~2~(max(pname:width~0~, pname:height~0~, |
| pname:depth~0~)){rceil}# |
| |
| where [eq]#pname:width~0~#, [eq]#pname:height~0~#, and [eq]#pname:depth~0~# |
| are the dimensions of the largest (most detailed) miplevel, `0`. |
| endif::VK_NV_corner_sampled_image[] |
| |
| |
| [[resources-image-layouts]] |
| == Image Layouts |
| |
| Images are stored in implementation-dependent opaque layouts in memory. |
| Each layout has limitations on what kinds of operations are supported for |
| image subresources using the layout. |
| At any given time, the data representing an image subresource in memory |
| exists in a particular layout which is determined by the most recent layout |
| transition that was performed on that image subresource. |
| Applications have control over which layout each image subresource uses, and |
| can: transition an image subresource from one layout to another. |
| Transitions can: happen with an image memory barrier, included as part of a |
| flink:vkCmdPipelineBarrier or a flink:vkCmdWaitEvents command buffer command |
| (see <<synchronization-image-memory-barriers>>), or as part of a subpass |
| dependency within a render pass (see sname:VkSubpassDependency). |
| |
| Image layout is per-image subresource. |
| Separate image subresources of the same image can: be in different layouts |
| at the same time, with the exception that depth and stencil aspects of a |
| given image subresource can: only be in different layouts if the |
| <<features-separateDepthStencilLayouts, pname:separateDepthStencilLayouts>> |
| feature is enabled. |
| |
| [NOTE] |
| .Note |
| ==== |
| Each layout may: offer optimal performance for a specific usage of image |
| memory. |
| For example, an image with a layout of |
| ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL may: provide optimal |
| performance for use as a color attachment, but be unsupported for use in |
| transfer commands. |
| Applications can: transition an image subresource from one layout to another |
| in order to achieve optimal performance when the image subresource is used |
| for multiple kinds of operations. |
| After initialization, applications need not use any layout other than the |
| general layout, though this may: produce suboptimal performance on some |
| implementations. |
| ==== |
| |
| Upon creation, all image subresources of an image are initially in the same |
| layout, where that layout is selected by the |
| sname:VkImageCreateInfo::pname:initialLayout member. |
| The pname:initialLayout must: be either ename:VK_IMAGE_LAYOUT_UNDEFINED or |
| ename:VK_IMAGE_LAYOUT_PREINITIALIZED. |
| If it is ename:VK_IMAGE_LAYOUT_PREINITIALIZED, then the image data can: be |
| preinitialized by the host while using this layout, and the transition away |
| from this layout will preserve that data. |
| If it is ename:VK_IMAGE_LAYOUT_UNDEFINED, then the contents of the data are |
| considered to be undefined:, and the transition away from this layout is not |
| guaranteed to preserve that data. |
| For either of these initial layouts, any image subresources must: be |
| transitioned to another layout before they are accessed by the device. |
| |
| Host access to image memory is only well-defined for |
| <<glossary-linear-resource,linear>> images and for image subresources of |
| those images which are currently in either the |
| ename:VK_IMAGE_LAYOUT_PREINITIALIZED or ename:VK_IMAGE_LAYOUT_GENERAL |
| layout. |
| Calling flink:vkGetImageSubresourceLayout for a linear image returns a |
| subresource layout mapping that is valid for either of those image layouts. |
| |
| [open,refpage='VkImageLayout',desc='Layout of image and image subresources',type='enums'] |
| -- |
| The set of image layouts consists of: |
| |
| include::{generated}/api/enums/VkImageLayout.txt[] |
| |
| The type(s) of device access supported by each layout are: |
| |
| * ename:VK_IMAGE_LAYOUT_UNDEFINED specifies that the layout is unknown. |
| Image memory cannot: be transitioned into this layout. |
| This layout can: be used as the pname:initialLayout member of |
| slink:VkImageCreateInfo. |
| This layout can: be used in place of the current image layout in a |
| layout transition, but doing so will cause the contents of the image's |
| memory to be undefined:. |
| * ename:VK_IMAGE_LAYOUT_PREINITIALIZED specifies that an image's memory is |
| in a defined layout and can: be populated by data, but that it has not |
| yet been initialized by the driver. |
| Image memory cannot: be transitioned into this layout. |
| This layout can: be used as the pname:initialLayout member of |
| slink:VkImageCreateInfo. |
| This layout is intended to be used as the initial layout for an image |
| whose contents are written by the host, and hence the data can: be |
| written to memory immediately, without first executing a layout |
| transition. |
| Currently, ename:VK_IMAGE_LAYOUT_PREINITIALIZED is only useful with |
| <<glossary-linear-resource,linear>> images because there is not a |
| standard layout defined for ename:VK_IMAGE_TILING_OPTIMAL images. |
| * ename:VK_IMAGE_LAYOUT_GENERAL supports all types of device access. |
| ifdef::VK_KHR_synchronization2[] |
| * ename:VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL_KHR specifies a layout that |
| must: only be used with attachment accesses in the graphics pipeline. |
| * ename:VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL_KHR specifies a layout allowing |
| read only access as an attachment, or in shaders as a sampled image, |
| combined image/sampler, or input attachment. |
| endif::VK_KHR_synchronization2[] |
| * ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL must: only be used as a |
| color or resolve attachment in a sname:VkFramebuffer. |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT usage bit enabled. |
| * ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL specifies a |
| layout for both the depth and stencil aspects of a depth/stencil format |
| image allowing read and write access as a depth/stencil attachment. |
| ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] |
| It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL and |
| ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL. |
| endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] |
| * ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL specifies a layout |
| for both the depth and stencil aspects of a depth/stencil format image |
| allowing read only access as a depth/stencil attachment or in shaders as |
| a sampled image, combined image/sampler, or input attachment. |
| ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] |
| It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL and |
| ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL. |
| endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL |
| specifies a layout for depth/stencil format images allowing read and |
| write access to the stencil aspect as a stencil attachment, and read |
| only access to the depth aspect as a depth attachment or in shaders as a |
| sampled image, combined image/sampler, or input attachment. |
| ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] |
| It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL and |
| ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL. |
| endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] |
| * ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL |
| specifies a layout for depth/stencil format images allowing read and |
| write access to the depth aspect as a depth attachment, and read only |
| access to the stencil aspect as a stencil attachment or in shaders as a |
| sampled image, combined image/sampler, or input attachment. |
| ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] |
| It is equivalent to ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL and |
| ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL. |
| endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifdef::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] |
| * ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL specifies a layout for |
| the depth aspect of a depth/stencil format image allowing read and write |
| access as a depth attachment. |
| * ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL specifies a layout for the |
| depth aspect of a depth/stencil format image allowing read-only access |
| as a depth attachment or in shaders as a sampled image, combined |
| image/sampler, or input attachment. |
| * ename:VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL specifies a layout for |
| the stencil aspect of a depth/stencil format image allowing read and |
| write access as a stencil attachment. |
| * ename:VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL specifies a layout for |
| the stencil aspect of a depth/stencil format image allowing read-only |
| access as a stencil attachment or in shaders as a sampled image, |
| combined image/sampler, or input attachment. |
| endif::VK_VERSION_1_2,VK_KHR_separate_depth_stencil_layouts[] |
| * ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL specifies a layout |
| allowing read-only access in a shader as a sampled image, combined |
| image/sampler, or input attachment. |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_SAMPLED_BIT or |
| ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage bits enabled. |
| * ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL must: only be used as a |
| source image of a transfer command (see the definition of |
| <<synchronization-pipeline-stages-transfer, |
| ename:VK_PIPELINE_STAGE_TRANSFER_BIT>>). |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled. |
| * ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL must: only be used as a |
| destination image of a transfer command. |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled. |
| ifdef::VK_KHR_swapchain[] |
| * ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR must: only be used for presenting |
| a presentable image for display. |
| A swapchain's image must: be transitioned to this layout before calling |
| flink:vkQueuePresentKHR, and must: be transitioned away from this layout |
| after calling flink:vkAcquireNextImageKHR. |
| ifdef::VK_KHR_shared_presentable_image[] |
| * ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR is valid only for shared |
| presentable images, and must: be used for any usage the image supports. |
| endif::VK_KHR_shared_presentable_image[] |
| endif::VK_KHR_swapchain[] |
| ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] |
| * ename:VK_IMAGE_LAYOUT_FRAGMENT_SHADING_RATE_ATTACHMENT_OPTIMAL_KHR must: |
| only be used as a |
| ifdef::VK_KHR_fragment_shading_rate[] |
| <<primsrast-fragment-shading-rate-attachment, fragment shading rate |
| attachment>> |
| endif::VK_KHR_fragment_shading_rate[] |
| ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[or] |
| ifdef::VK_NV_shading_rate_image[] |
| <<primsrast-shading-rate-image, shading rate image>>. |
| endif::VK_NV_shading_rate_image[] |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR usage |
| bit enabled. |
| endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] |
| ifdef::VK_EXT_fragment_density_map[] |
| * ename:VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT must: only be |
| used as a fragment density map attachment in a sname:VkRenderPass. |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT usage bit enabled. |
| endif::VK_EXT_fragment_density_map[] |
| ifdef::VK_KHR_video_decode_queue[] |
| * ename:VK_IMAGE_LAYOUT_VIDEO_DECODE_DST_KHR must: only be used as a |
| decode output image of a <<video-decode-operations, video decode |
| operation>>. |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR usage bit enabled. |
| * ename:VK_IMAGE_LAYOUT_VIDEO_DECODE_SRC_KHR must: only be used as a |
| decode source image of a <<video-decode-operations, video decode |
| operation>>. |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR usage bit enabled. |
| * ename:VK_IMAGE_LAYOUT_VIDEO_DECODE_DPB_KHR must: only be used as a |
| decode source or destination image of a <<video-decode-operations, video |
| decode operation>>. |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR usage bit enabled. |
| endif::VK_KHR_video_decode_queue[] |
| ifdef::VK_KHR_video_encode_queue[] |
| * ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_DST_KHR must: only be used as a |
| encode output image of a <<video-encode-operations, video encode |
| operation>>. |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR usage bit enabled. |
| * ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_SRC_KHR must: only be used as a |
| encode source image of a <<video-encode-operations, video encode |
| operation>>. |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR usage bit enabled. |
| * ename:VK_IMAGE_LAYOUT_VIDEO_ENCODE_DPB_KHR must: only be used as a |
| encode source or destination image of a <<video-encode-operations, video |
| encode operation>>. |
| This layout is valid only for image subresources of images created with |
| the ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR usage bit enabled. |
| endif::VK_KHR_video_encode_queue[] |
| |
| The layout of each image subresource is not a state of the image subresource |
| itself, but is rather a property of how the data in memory is organized, and |
| thus for each mechanism of accessing an image in the API the application |
| must: specify a parameter or structure member that indicates which image |
| layout the image subresource(s) are considered to be in when the image will |
| be accessed. |
| For transfer commands, this is a parameter to the command (see <<clears>> |
| and <<copies>>). |
| For use as a framebuffer attachment, this is a member in the substructures |
| of the slink:VkRenderPassCreateInfo (see <<renderpass,Render Pass>>). |
| For use in a descriptor set, this is a member in the |
| sname:VkDescriptorImageInfo structure (see <<descriptorsets-updates>>). |
| -- |
| |
| |
| [[resources-image-layouts-matching-rule]] |
| === Image Layout Matching Rules |
| |
| At the time that any command buffer command accessing an image executes on |
| any queue, the layouts of the image subresources that are accessed must: all |
| match exactly the layout specified via the API controlling those accesses |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| , except in case of accesses to an image with a depth/stencil format |
| performed through descriptors referring to only a single aspect of the |
| image, where the following relaxed matching rules apply: |
| |
| * Descriptors referring just to the depth aspect of a depth/stencil image |
| only need to match in the image layout of the depth aspect, thus |
| ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL and |
| ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL are |
| considered to match. |
| * Descriptors referring just to the stencil aspect of a depth/stencil |
| image only need to match in the image layout of the stencil aspect, thus |
| ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL and |
| ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL are |
| considered to match |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| . |
| |
| When performing a layout transition on an image subresource, the old layout |
| value must: either equal the current layout of the image subresource (at the |
| time the transition executes), or else be ename:VK_IMAGE_LAYOUT_UNDEFINED |
| (implying that the contents of the image subresource need not be preserved). |
| The new layout used in a transition must: not be |
| ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED. |
| |
| ifdef::VK_EXT_sample_locations[] |
| |
| The image layout of each image subresource of a depth/stencil image created |
| with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is |
| dependent on the last sample locations used to render to the image |
| subresource as a depth/stencil attachment, thus applications must: provide |
| the same sample locations that were last used to render to the given image |
| subresource whenever a layout transition of the image subresource happens, |
| otherwise the contents of the depth aspect of the image subresource become |
| undefined:. |
| |
| In addition, depth reads from a depth/stencil attachment referring to an |
| image subresource range of a depth/stencil image created with |
| ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using |
| different sample locations than what have been last used to perform depth |
| writes to the image subresources of the same image subresource range return |
| undefined: values. |
| |
| Similarly, depth writes to a depth/stencil attachment referring to an image |
| subresource range of a depth/stencil image created with |
| ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using |
| different sample locations than what have been last used to perform depth |
| writes to the image subresources of the same image subresource range make |
| the contents of the depth aspect of those image subresources undefined:. |
| |
| endif::VK_EXT_sample_locations[] |
| |
| |
| [[resources-image-views]] |
| == Image Views |
| |
| [open,refpage='VkImageView',desc='Opaque handle to an image view object',type='handles'] |
| -- |
| Image objects are not directly accessed by pipeline shaders for reading or |
| writing image data. |
| Instead, _image views_ representing contiguous ranges of the image |
| subresources and containing additional metadata are used for that purpose. |
| Views must: be created on images of compatible types, and must: represent a |
| valid subset of image subresources. |
| |
| Image views are represented by sname:VkImageView handles: |
| |
| include::{generated}/api/handles/VkImageView.txt[] |
| -- |
| |
| [open,refpage='VK_REMAINING_ARRAY_LAYERS',desc='Sentinel for all remaining array layers',type='consts'] |
| -- |
| ename:VK_REMAINING_ARRAY_LAYERS is a special constant value used for image |
| views to indicate that all remaining array layers in an image after the base |
| layer should be included in the view. |
| |
| include::{generated}/api/enums/VK_REMAINING_ARRAY_LAYERS.txt[] |
| -- |
| |
| [open,refpage='VK_REMAINING_MIP_LEVELS',desc='Sentinel for all remaining array layers',type='consts'] |
| -- |
| ename:VK_REMAINING_MIP_LEVELS is a special constant value used for image |
| views to indicate that all remaining mipmap levels in an image after the |
| base level should be included in the view. |
| |
| include::{generated}/api/enums/VK_REMAINING_MIP_LEVELS.txt[] |
| -- |
| |
| [open,refpage='VkImageViewType',desc='Image view types',type='enums'] |
| -- |
| The types of image views that can: be created are: |
| |
| include::{generated}/api/enums/VkImageViewType.txt[] |
| -- |
| |
| [open,refpage='vkCreateImageView',desc='Create an image view from an existing image',type='protos'] |
| -- |
| To create an image view, call: |
| |
| include::{generated}/api/protos/vkCreateImageView.txt[] |
| |
| * pname:device is the logical device that creates the image view. |
| * pname:pCreateInfo is a pointer to a sname:VkImageViewCreateInfo |
| structure containing parameters to be used to create the image view. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pView is a pointer to a slink:VkImageView handle in which the |
| resulting image view object is returned. |
| |
| include::{generated}/validity/protos/vkCreateImageView.txt[] |
| -- |
| |
| [open,refpage='VkImageViewCreateInfo',desc='Structure specifying parameters of a newly created image view',type='structs'] |
| -- |
| The sname:VkImageViewCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkImageViewCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkImageViewCreateFlagBits describing |
| additional parameters of the image view. |
| * pname:image is a slink:VkImage on which the view will be created. |
| * pname:viewType is a elink:VkImageViewType value specifying the type of |
| the image view. |
| * pname:format is a elink:VkFormat describing the format and type used to |
| interpret texel blocks in the image. |
| * pname:components is a slink:VkComponentMapping structure specifying a |
| remapping of color components (or of depth or stencil components after |
| they have been converted into color components). |
| * pname:subresourceRange is a slink:VkImageSubresourceRange structure |
| selecting the set of mipmap levels and array layers to be accessible to |
| the view. |
| |
| [[resources-image-inherited-usage]] |
| Some of the pname:image creation parameters are inherited by the view. |
| In particular, image view creation inherits the implicit parameter |
| pname:usage specifying the allowed usages of the image view that, by |
| default, takes the value of the corresponding pname:usage parameter |
| specified in slink:VkImageCreateInfo at image creation time. |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| The implicit pname:usage can: be overriden by adding a |
| slink:VkImageViewUsageCreateInfo structure to the pname:pNext chain, but the |
| view usage must: be a subset of the image usage. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| If pname:image has a depth-stencil format and was created with a |
| slink:VkImageStencilUsageCreateInfo structure included in the pname:pNext |
| chain of slink:VkImageCreateInfo, the usage is calculated based on the |
| pname:subresource.aspectMask provided: |
| |
| * If pname:aspectMask includes only ename:VK_IMAGE_ASPECT_STENCIL_BIT, the |
| implicit pname:usage is equal to |
| slink:VkImageStencilUsageCreateInfo::pname:stencilUsage. |
| * If pname:aspectMask includes only ename:VK_IMAGE_ASPECT_DEPTH_BIT, the |
| implicit pname:usage is equal to slink:VkImageCreateInfo::pname:usage. |
| * If both aspects are included in pname:aspectMask, the implicit |
| pname:usage is equal to the intersection of |
| slink:VkImageCreateInfo::pname:usage and |
| slink:VkImageStencilUsageCreateInfo::pname:stencilUsage. |
| endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| |
| If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT |
| flag, |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| and if the pname:format of the image is not |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar>>, |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:format can: be different from the image's format, but if |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| pname:image was created without the |
| ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| they are not equal they must: be _compatible_. |
| Image format compatibility is defined in the |
| <<formats-compatibility-classes,Format Compatibility Classes>> section. |
| Views of compatible formats will have the same mapping between texel |
| coordinates and memory locations irrespective of the pname:format, with only |
| the interpretation of the bit pattern changing. |
| |
| [NOTE] |
| .Note |
| ==== |
| Values intended to be used with one view format may: not be exactly |
| preserved when written or read through a different format. |
| For example, an integer value that happens to have the bit pattern of a |
| floating point denorm or NaN may: be flushed or canonicalized when written |
| or read through a view with a floating point format. |
| Similarly, a value written through a signed normalized format that has a bit |
| pattern exactly equal to [eq]#-2^b^# may: be changed to [eq]#-2^b^ {plus} 1# |
| as described in <<fundamentals-fixedfpconv,Conversion from Normalized |
| Fixed-Point to Floating-Point>>. |
| ==== |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| If pname:image was created with the |
| ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format |
| must: be _compatible_ with the image's format as described above, or must: |
| be an uncompressed format in which case it must: be _size-compatible_ with |
| the image's format, as defined for |
| <<copies-images-format-size-compatibility, copying data between images>>. |
| In this case, the resulting image view's texel dimensions equal the |
| dimensions of the selected mip level divided by the compressed texel block |
| size and rounded up. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| |
| The slink:VkComponentMapping pname:components member describes a remapping |
| from components of the image to components of the vector returned by shader |
| image instructions. |
| This remapping must: be the identity swizzle for storage image descriptors, |
| input attachment descriptors, |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| and framebuffer attachments. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| framebuffer attachments, and any sname:VkImageView used with a combined |
| image sampler that enables <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ |
| conversion>>. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If the image view is to be used with a sampler which supports |
| <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>>, an _identically |
| defined object_ of type slink:VkSamplerYcbcrConversion to that used to |
| create the sampler must: be passed to flink:vkCreateImageView in a |
| slink:VkSamplerYcbcrConversionInfo included in the pname:pNext chain of |
| slink:VkImageViewCreateInfo. |
| Conversely, if a slink:VkSamplerYcbcrConversion object is passed to |
| flink:vkCreateImageView, an identically defined |
| slink:VkSamplerYcbcrConversion object must: be used when sampling the image. |
| |
| If the image has a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> pname:format and |
| pname:subresourceRange.aspectMask is ename:VK_IMAGE_ASPECT_COLOR_BIT, |
| ifdef::VK_KHR_video_decode_queue[] |
| and pname:image has been created with a pname:usage value *not* containing |
| any of the ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, and |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR flags, |
| endif::VK_KHR_video_decode_queue[] |
| then the pname:format must: be identical to the image pname:format, and the |
| sampler to be used with the image view must: enable |
| <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>>. |
| |
| ifdef::VK_KHR_video_decode_queue[] |
| If the image has a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> pname:format and |
| the pname:image has been created with a pname:usage value containing any of |
| the ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, and |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR flags, then all of the |
| <<video-decode-operations, video decode operations>> would ignore the |
| slink:VkSamplerYcbcrConversionInfo structure and/or |
| <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> object, |
| associated with the image view. |
| endif::VK_KHR_video_decode_queue[] |
| ifdef::VK_KHR_video_encode_queue[] |
| If the image has a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> pname:format and |
| the pname:image has been created with a pname:usage value containing any of |
| the ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, and |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR flags, then all of the |
| <<video-encode-operations, video encode operations>> would ignore the |
| slink:VkSamplerYcbcrConversionInfo structure and/or |
| <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>> object, |
| associated with the image view. |
| endif::VK_KHR_video_encode_queue[] |
| |
| If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT |
| and the image has a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> pname:format, |
| and if pname:subresourceRange.aspectMask is |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT, pname:format must: be |
| <<formats-compatible-planes,compatible>> with the corresponding plane of the |
| image, and the sampler to be used with the image view must: not enable |
| <<samplers-YCbCr-conversion,sampler {YCbCr} conversion>>. |
| The pname:width and pname:height of the single-plane image view must: be |
| derived from the multi-planar image's dimensions in the manner listed for |
| <<formats-compatible-planes,plane compatibility>> for the plane. |
| |
| Any view of an image plane will have the same mapping between texel |
| coordinates and memory locations as used by the components of the color |
| aspect, subject to the formulae relating texel coordinates to |
| lower-resolution planes as described in <<textures-chroma-reconstruction, |
| Chroma Reconstruction>>. |
| That is, if an R or B plane has a reduced resolution relative to the G plane |
| of the multi-planar image, the image view operates using the (_u~plane~_, |
| _v~plane~_) unnormalized coordinates of the reduced-resolution plane, and |
| these coordinates access the same memory locations as the (_u~color~_, |
| _v~color~_) unnormalized coordinates of the color aspect for which chroma |
| reconstruction operations operate on the same (_u~plane~_, _v~plane~_) or |
| (_i~plane~_, _j~plane~_) coordinates. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| [[resources-image-views-compatibility]] |
| .Image type and image view type compatibility requirements |
| [cols="35%,50%",options="header"] |
| |==== |
| | Image View Type | Compatible Image Types |
| | ename:VK_IMAGE_VIEW_TYPE_1D | ename:VK_IMAGE_TYPE_1D |
| | ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY | ename:VK_IMAGE_TYPE_1D |
| | ename:VK_IMAGE_VIEW_TYPE_2D | ename:VK_IMAGE_TYPE_2D |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[, ename:VK_IMAGE_TYPE_3D] |
| | ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY | ename:VK_IMAGE_TYPE_2D |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[, ename:VK_IMAGE_TYPE_3D] |
| | ename:VK_IMAGE_VIEW_TYPE_CUBE | ename:VK_IMAGE_TYPE_2D |
| | ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY | ename:VK_IMAGE_TYPE_2D |
| | ename:VK_IMAGE_VIEW_TYPE_3D | ename:VK_IMAGE_TYPE_3D |
| |==== |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageViewCreateInfo-image-01003]] |
| If pname:image was not created with |
| ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT then pname:viewType must: not |
| be ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY |
| * [[VUID-VkImageViewCreateInfo-viewType-01004]] |
| If the <<features-imageCubeArray,image cube map arrays>> feature is not |
| enabled, pname:viewType must: not be ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageViewCreateInfo-image-01005]] |
| If pname:image was created with ename:VK_IMAGE_TYPE_3D but without |
| ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set then pname:viewType |
| must: not be ename:VK_IMAGE_VIEW_TYPE_2D or |
| ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY |
| * [[VUID-VkImageViewCreateInfo-image-04970]] |
| If pname:image was created with ename:VK_IMAGE_TYPE_3D and |
| pname:viewType is ename:VK_IMAGE_VIEW_TYPE_2D or |
| ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY then pname:subresourceRange.levelCount |
| must: be 1 |
| * [[VUID-VkImageViewCreateInfo-image-04971]] |
| If pname:image was created with ename:VK_IMAGE_TYPE_3D and |
| pname:viewType is ename:VK_IMAGE_VIEW_TYPE_2D or |
| ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY then pname:flags must: not contain any |
| of ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and |
| ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT |
| * [[VUID-VkImageViewCreateInfo-image-04972]] |
| If pname:image was created with a pname:samples value not equal to |
| ename:VK_SAMPLE_COUNT_1_BIT then pname:viewType must: be either |
| ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageViewCreateInfo-image-04441]] |
| pname:image must: have been created with a pname:usage value containing |
| at least one of the usages defined in the <<valid-imageview-imageusage, |
| valid image usage>> list for image views |
| * [[VUID-VkImageViewCreateInfo-None-02273]] |
| The <<resources-image-view-format-features,format features>> of the |
| resultant image view must: contain at least one bit |
| * [[VUID-VkImageViewCreateInfo-usage-02274]] |
| If pname:usage contains ename:VK_IMAGE_USAGE_SAMPLED_BIT, then the |
| <<resources-image-view-format-features,format features>> of the |
| resultant image view must: contain |
| ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT |
| * [[VUID-VkImageViewCreateInfo-usage-02275]] |
| If pname:usage contains ename:VK_IMAGE_USAGE_STORAGE_BIT, then the image |
| view's <<resources-image-view-format-features,format features>> must: |
| contain ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT |
| * [[VUID-VkImageViewCreateInfo-usage-02276]] |
| If pname:usage contains ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then |
| the image view's <<resources-image-view-format-features,format |
| features>> must: contain ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT |
| * [[VUID-VkImageViewCreateInfo-usage-02277]] |
| If pname:usage contains |
| ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then the image view's |
| <<resources-image-view-format-features,format features>> must: contain |
| ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * [[VUID-VkImageViewCreateInfo-usage-02652]] |
| If pname:usage contains ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then |
| the image view's <<resources-image-view-format-features,format |
| features>> must: contain at least one of |
| ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or |
| ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * [[VUID-VkImageViewCreateInfo-subresourceRange-01478]] |
| pname:subresourceRange.baseMipLevel must: be less than the |
| pname:mipLevels specified in slink:VkImageCreateInfo when pname:image |
| was created |
| * [[VUID-VkImageViewCreateInfo-subresourceRange-01718]] |
| If pname:subresourceRange.levelCount is not |
| ename:VK_REMAINING_MIP_LEVELS, [eq]#pname:subresourceRange.baseMipLevel |
| {plus} pname:subresourceRange.levelCount# must: be less than or equal to |
| the pname:mipLevels specified in slink:VkImageCreateInfo when |
| pname:image was created |
| ifdef::VK_EXT_fragment_density_map[] |
| * [[VUID-VkImageViewCreateInfo-image-02571]] |
| If pname:image was created with pname:usage containing |
| ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, |
| pname:subresourceRange.levelCount must: be `1` |
| endif::VK_EXT_fragment_density_map[] |
| ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageViewCreateInfo-subresourceRange-01480]] |
| pname:subresourceRange.baseArrayLayer must: be less than the |
| pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image |
| was created |
| * [[VUID-VkImageViewCreateInfo-subresourceRange-01719]] |
| If pname:subresourceRange.layerCount is not |
| ename:VK_REMAINING_ARRAY_LAYERS, |
| [eq]#pname:subresourceRange.baseArrayLayer {plus} |
| pname:subresourceRange.layerCount# must: be less than or equal to the |
| pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image |
| was created |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| * [[VUID-VkImageViewCreateInfo-image-01482]] |
| If pname:image is not a 3D image created with |
| ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or pname:viewType is |
| not ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, |
| pname:subresourceRange.baseArrayLayer must: be less than the |
| pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image |
| was created |
| * [[VUID-VkImageViewCreateInfo-subresourceRange-01483]] |
| If pname:subresourceRange.layerCount is not |
| ename:VK_REMAINING_ARRAY_LAYERS, pname:image is not a 3D image created |
| with ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or |
| pname:viewType is not ename:VK_IMAGE_VIEW_TYPE_2D or |
| ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, pname:subresourceRange.layerCount |
| must: be non-zero and [eq]#pname:subresourceRange.baseArrayLayer {plus} |
| pname:subresourceRange.layerCount# must: be less than or equal to the |
| pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image |
| was created |
| * [[VUID-VkImageViewCreateInfo-image-02724]] |
| If pname:image is a 3D image created with |
| ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and pname:viewType is |
| ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, |
| pname:subresourceRange.baseArrayLayer must: be less than the depth |
| computed from pname:baseMipLevel and pname:extent.depth specified in |
| slink:VkImageCreateInfo when pname:image was created, according to the |
| formula defined in <<resources-image-miplevel-sizing,Image Miplevel |
| Sizing>> |
| * [[VUID-VkImageViewCreateInfo-subresourceRange-02725]] |
| If pname:subresourceRange.layerCount is not |
| ename:VK_REMAINING_ARRAY_LAYERS, pname:image is a 3D image created with |
| ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, and pname:viewType is |
| ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY, |
| pname:subresourceRange.layerCount must: be non-zero and |
| [eq]#pname:subresourceRange.baseArrayLayer {plus} |
| pname:subresourceRange.layerCount# must: be less than or equal to the |
| depth computed from pname:baseMipLevel and pname:extent.depth specified |
| in slink:VkImageCreateInfo when pname:image was created, according to |
| the formula defined in <<resources-image-miplevel-sizing,Image Miplevel |
| Sizing>> |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| // The VU below comes in 4 alternate versions |
| // both disabled, both enabled, maintenance2 only, ycbcr only |
| ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageViewCreateInfo-image-01018]] |
| If pname:image was created with the |
| ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be |
| compatible with the pname:format used to create pname:image, as defined |
| in <<formats-compatibility-classes,Format Compatibility Classes>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| // The nested ifdefs are there in anticipation of the hoped-for day when the |
| // VU extractor and validation layers can handle VU with imbedded |
| // conditionals. They are commented out until then. |
| // |
| // If VK_VERSION_1_1,VK_KHR_maintenance2 and NOT VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageViewCreateInfo-image-01759]] |
| If pname:image was created with the |
| ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, but without the |
| ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format |
| must: be compatible with the pname:format used to create pname:image, as |
| defined in <<formats-compatibility-classes,Format Compatibility |
| Classes>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| // If NOT VK_VERSION_1_1,VK_KHR_maintenance2 and VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion |
| ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageViewCreateInfo-image-01760]] |
| If pname:image was created with the |
| ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, and if the pname:format |
| of the pname:image is not a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, |
| pname:format must: be compatible with the pname:format used to create |
| pname:image, as defined in <<formats-compatibility-classes,Format |
| Compatibility Classes>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| // If VK_VERSION_1_1,VK_KHR_maintenance2 and VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageViewCreateInfo-image-01761]] |
| If pname:image was created with the |
| ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, |
| // ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| but without the ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT |
| flag, |
| // endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| and if the pname:format of the pname:image is not a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:format must: be compatible with the pname:format used to create |
| pname:image, as defined in <<formats-compatibility-classes,Format |
| Compatibility Classes>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| * [[VUID-VkImageViewCreateInfo-image-01583]] |
| If pname:image was created with the |
| ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format |
| must: be compatible with, or must: be an uncompressed format that is |
| size-compatible with, the pname:format used to create pname:image |
| * [[VUID-VkImageViewCreateInfo-image-01584]] |
| If pname:image was created with the |
| ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, the |
| pname:levelCount and pname:layerCount members of pname:subresourceRange |
| must: both be `1` |
| * [[VUID-VkImageViewCreateInfo-image-04739]] |
| If pname:image was created with the |
| ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and |
| pname:format is a non-compressed format, pname:viewType must: not be |
| ename:VK_IMAGE_VIEW_TYPE_3D |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifdef::VK_VERSION_1_2,VK_KHR_image_format_list[] |
| * [[VUID-VkImageViewCreateInfo-pNext-01585]] |
| If a slink:VkImageFormatListCreateInfo structure was included in the |
| pname:pNext chain of the slink:VkImageCreateInfo structure used when |
| creating pname:image and |
| slink:VkImageFormatListCreateInfo::pname:viewFormatCount is not zero |
| then pname:format must: be one of the formats in |
| slink:VkImageFormatListCreateInfo::pname:pViewFormats |
| endif::VK_VERSION_1_2,VK_KHR_image_format_list[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageViewCreateInfo-image-01586]] |
| If pname:image was created with the |
| ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, if the pname:format of |
| the pname:image is a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format, and |
| if pname:subresourceRange.aspectMask is one of |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT, then pname:format must: be compatible |
| with the elink:VkFormat for the plane of the pname:image pname:format |
| indicated by pname:subresourceRange.aspectMask, as defined in |
| <<formats-compatible-planes>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| // The VU below comes in an alternate version when the extension is |
| // enabled. |
| * [[VUID-VkImageViewCreateInfo-image-01019]] |
| If pname:image was not created with the |
| ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be |
| identical to the pname:format used to create pname:image |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| // The nested ifdefs are there in anticipation of the hoped-for day when the |
| // VU extractor and validation layers can handle VU with imbedded |
| // conditionals. They are commented out until then. |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageViewCreateInfo-image-01762]] |
| If pname:image was not created with the |
| ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, |
| // ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| or if the pname:format of the pname:image is a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar>> format and |
| if pname:subresourceRange.aspectMask is ename:VK_IMAGE_ASPECT_COLOR_BIT, |
| // endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| pname:format must: be identical to the pname:format used to create |
| pname:image |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageViewCreateInfo-format-06415]] |
| If the image pname:format is one of the |
| <<formats-requiring-sampler-ycbcr-conversion, formats that require a |
| sampler Y'C~B~C~R~ conversion>>, then the pname:pNext chain must: |
| include a slink:VkSamplerYcbcrConversionInfo structure with a conversion |
| value other than dlink:VK_NULL_HANDLE |
| * [[VUID-VkImageViewCreateInfo-format-04714]] |
| If pname:format has a code:_422 or code:_420 suffix then pname:image |
| must: have been created with a width that is a multiple of 2 |
| * [[VUID-VkImageViewCreateInfo-format-04715]] |
| If pname:format has a code:_420 suffix then pname:image must: have been |
| created with a height that is a multiple of 2 |
| * [[VUID-VkImageViewCreateInfo-pNext-01970]] |
| If the pname:pNext chain includes a slink:VkSamplerYcbcrConversionInfo |
| structure with a pname:conversion value other than dlink:VK_NULL_HANDLE, |
| all members of pname:components must: have the |
| <<resources-image-views-identity-mappings,identity swizzle>> |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageViewCreateInfo-image-01020]] |
| If pname:image is non-sparse then it must: be bound completely and |
| contiguously to a single sname:VkDeviceMemory object |
| * [[VUID-VkImageViewCreateInfo-subResourceRange-01021]] |
| pname:viewType must: be compatible with the type of pname:image as shown |
| in the <<resources-image-views-compatibility,view type compatibility |
| table>> |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-VkImageViewCreateInfo-image-02399]] |
| If pname:image has an |
| <<memory-external-android-hardware-buffer-external-formats,external |
| format>>, pname:format must: be ename:VK_FORMAT_UNDEFINED |
| * [[VUID-VkImageViewCreateInfo-image-02400]] |
| If pname:image has an |
| <<memory-external-android-hardware-buffer-external-formats,external |
| format>>, the pname:pNext chain must: include a |
| slink:VkSamplerYcbcrConversionInfo structure with a pname:conversion |
| object created with the same external format as pname:image |
| * [[VUID-VkImageViewCreateInfo-image-02401]] |
| If pname:image has an |
| <<memory-external-android-hardware-buffer-external-formats,external |
| format>>, all members of pname:components must: be the |
| <<resources-image-views-identity-mappings,identity swizzle>> |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifdef::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] |
| * [[VUID-VkImageViewCreateInfo-image-02086]] |
| If pname:image was created with pname:usage containing |
| ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, |
| pname:viewType must: be ename:VK_IMAGE_VIEW_TYPE_2D or |
| ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY |
| endif::VK_KHR_fragment_shading_rate,VK_NV_shading_rate_image[] |
| ifdef::VK_NV_shading_rate_image[] |
| * [[VUID-VkImageViewCreateInfo-image-02087]] |
| If the <<features-shadingRateImage, pname:shadingRateImage feature>> is |
| enabled, and If pname:image was created with pname:usage containing |
| ename:VK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV, pname:format must: be |
| ename:VK_FORMAT_R8_UINT |
| endif::VK_NV_shading_rate_image[] |
| ifdef::VK_KHR_fragment_shading_rate[] |
| * [[VUID-VkImageViewCreateInfo-usage-04550]] |
| If the <<features-attachmentFragmentShadingRate, |
| pname:attachmentFragmentShadingRate feature>> is enabled, and the |
| pname:usage for the image view includes |
| ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, then the |
| image view's <<resources-image-view-format-features,format features>> |
| must: contain |
| ename:VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR |
| * [[VUID-VkImageViewCreateInfo-usage-04551]] |
| If the <<features-attachmentFragmentShadingRate, |
| pname:attachmentFragmentShadingRate feature>> is enabled, the |
| pname:usage for the image view includes |
| ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, and |
| <<limits-layeredShadingRateAttachments, |
| pname:layeredShadingRateAttachments>> is ename:VK_FALSE, |
| pname:subresourceRange.layerCount must: be `1` |
| endif::VK_KHR_fragment_shading_rate[] |
| ifdef::VK_EXT_fragment_density_map[] |
| * [[VUID-VkImageViewCreateInfo-flags-02572]] |
| If <<features-fragmentDensityMapDynamic,dynamic fragment density map>> |
| feature is not enabled, pname:flags must: not contain |
| ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT |
| ifdef::VK_EXT_fragment_density_map2[] |
| * [[VUID-VkImageViewCreateInfo-flags-03567]] |
| If <<features-fragmentDensityMapDeferred,deferred fragment density map>> |
| feature is not enabled, pname:flags must: not contain |
| ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT |
| * [[VUID-VkImageViewCreateInfo-flags-03568]] |
| If pname:flags contains |
| ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT, |
| pname:flags must: not contain |
| ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT |
| * [[VUID-VkImageViewCreateInfo-image-03569]] |
| If pname:image was created with pname:flags containing |
| ename:VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT and pname:usage containing |
| ename:VK_IMAGE_USAGE_SAMPLED_BIT, pname:subresourceRange.layerCount |
| must: be less than or equal to |
| <<limits-maxSubsampledArrayLayers,sname:VkPhysicalDeviceFragmentDensityMap2PropertiesEXT::pname:maxSubsampledArrayLayers>> |
| endif::VK_EXT_fragment_density_map2[] |
| ifdef::VK_HUAWEI_invocation_mask[] |
| * [[VUID-VkImageViewCreateInfo-invocationMask-04993]] |
| If the <<features-invocationMask, pname:invocationMask feature>> is |
| enabled, and if pname:image was created with pname:usage containing |
| ename:VK_IMAGE_USAGE_INVOCATION_MASK_BIT_HUAWEI, pname:format must: be |
| ename:VK_FORMAT_R8_UINT |
| endif::VK_HUAWEI_invocation_mask[] |
| * [[VUID-VkImageViewCreateInfo-flags-04116]] |
| If pname:flags does not contain |
| ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT and |
| pname:image was created with pname:usage containing |
| ename:VK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT, its pname:flags must: |
| not contain any of ename:VK_IMAGE_CREATE_PROTECTED_BIT, |
| ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, |
| ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or |
| ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT |
| endif::VK_EXT_fragment_density_map[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| ifndef::VK_VERSION_1_2+VK_EXT_separate_stencil_usage[] |
| * [[VUID-VkImageViewCreateInfo-pNext-02661]] |
| If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo |
| structure, its pname:usage member must: not include any bits that were |
| not set in the pname:usage member of the slink:VkImageCreateInfo |
| structure used to create pname:image |
| endif::VK_VERSION_1_2+VK_EXT_separate_stencil_usage[] |
| ifdef::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| * [[VUID-VkImageViewCreateInfo-pNext-02662]] |
| If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo |
| structure, and pname:image was not created with a |
| slink:VkImageStencilUsageCreateInfo structure included in the |
| pname:pNext chain of slink:VkImageCreateInfo, its pname:usage member |
| must: not include any bits that were not set in the pname:usage member |
| of the slink:VkImageCreateInfo structure used to create pname:image |
| * [[VUID-VkImageViewCreateInfo-pNext-02663]] |
| If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo |
| structure, pname:image was created with a |
| slink:VkImageStencilUsageCreateInfo structure included in the |
| pname:pNext chain of slink:VkImageCreateInfo, and |
| pname:subresourceRange.aspectMask includes |
| ename:VK_IMAGE_ASPECT_STENCIL_BIT, the pname:usage member of the |
| slink:VkImageViewUsageCreateInfo structure must: not include any bits |
| that were not set in the pname:usage member of the |
| slink:VkImageStencilUsageCreateInfo structure used to create pname:image |
| * [[VUID-VkImageViewCreateInfo-pNext-02664]] |
| If the pname:pNext chain includes a slink:VkImageViewUsageCreateInfo |
| structure, pname:image was created with a |
| slink:VkImageStencilUsageCreateInfo structure included in the |
| pname:pNext chain of slink:VkImageCreateInfo, and |
| pname:subresourceRange.aspectMask includes bits other than |
| ename:VK_IMAGE_ASPECT_STENCIL_BIT, the pname:usage member of the |
| slink:VkImageViewUsageCreateInfo structure must: not include any bits |
| that were not set in the pname:usage member of the |
| slink:VkImageCreateInfo structure used to create pname:image |
| endif::VK_VERSION_1_2,VK_EXT_separate_stencil_usage[] |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| * [[VUID-VkImageViewCreateInfo-imageViewType-04973]] |
| If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_1D, |
| ename:VK_IMAGE_VIEW_TYPE_2D, or ename:VK_IMAGE_VIEW_TYPE_3D; and |
| pname:subresourceRange.layerCount is not |
| ename:VK_REMAINING_ARRAY_LAYERS, then pname:subresourceRange.layerCount |
| must: be 1 |
| * [[VUID-VkImageViewCreateInfo-imageViewType-04974]] |
| If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_1D, |
| ename:VK_IMAGE_VIEW_TYPE_2D, or ename:VK_IMAGE_VIEW_TYPE_3D; and |
| pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS, |
| then the remaining number of layers must: be 1 |
| * [[VUID-VkImageViewCreateInfo-viewType-02960]] |
| If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE and |
| pname:subresourceRange.layerCount is not |
| ename:VK_REMAINING_ARRAY_LAYERS, pname:subresourceRange.layerCount must: |
| be `6` |
| * [[VUID-VkImageViewCreateInfo-viewType-02961]] |
| If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY and |
| pname:subresourceRange.layerCount is not |
| ename:VK_REMAINING_ARRAY_LAYERS, pname:subresourceRange.layerCount must: |
| be a multiple of `6` |
| * [[VUID-VkImageViewCreateInfo-viewType-02962]] |
| If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE and |
| pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS, |
| the remaining number of layers must: be `6` |
| * [[VUID-VkImageViewCreateInfo-viewType-02963]] |
| If pname:viewType is ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY and |
| pname:subresourceRange.layerCount is ename:VK_REMAINING_ARRAY_LAYERS, |
| the remaining number of layers must: be a multiple of `6` |
| ifdef::VK_KHR_portability_subset[] |
| * [[VUID-VkImageViewCreateInfo-imageViewFormatSwizzle-04465]] |
| If the `apiext:VK_KHR_portability_subset` extension is enabled, and |
| slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:imageViewFormatSwizzle |
| is ename:VK_FALSE, all elements of pname:components must: have the |
| <<resources-image-views-identity-mappings,identity swizzle>> |
| * [[VUID-VkImageViewCreateInfo-imageViewFormatReinterpretation-04466]] |
| If the `apiext:VK_KHR_portability_subset` extension is enabled, and |
| slink:VkPhysicalDevicePortabilitySubsetFeaturesKHR::pname:imageViewFormatReinterpretation |
| is ename:VK_FALSE, the elink:VkFormat in pname:format must: not contain |
| a different number of components, or a different number of bits in each |
| component, than the format of the sname:VkImage in pname:image |
| endif::VK_KHR_portability_subset[] |
| ifdef::VK_KHR_video_decode_queue[] |
| * [[VUID-VkImageViewCreateInfo-image-04817]] |
| If pname:image was created with pname:usage containing |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_DST_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_SRC_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_DECODE_DPB_BIT_KHR, then the pname:viewType |
| must: be ename:VK_IMAGE_VIEW_TYPE_2D or |
| ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY and all members of pname:components |
| must: have the <<resources-image-views-identity-mappings,identity |
| swizzle>> |
| endif::VK_KHR_video_decode_queue[] |
| ifdef::VK_KHR_video_encode_queue[] |
| * [[VUID-VkImageViewCreateInfo-image-04818]] |
| If pname:image was created with pname:usage containing |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DST_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_SRC_BIT_KHR, |
| ename:VK_IMAGE_USAGE_VIDEO_ENCODE_DPB_BIT_KHR, then the pname:viewType |
| must: be ename:VK_IMAGE_VIEW_TYPE_2D or |
| ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY and all members of pname:components |
| must: have the <<resources-image-views-identity-mappings,identity |
| swizzle>> |
| endif::VK_KHR_video_encode_queue[] |
| **** |
| |
| include::{generated}/validity/structs/VkImageViewCreateInfo.txt[] |
| -- |
| |
| [open,refpage='VkImageViewCreateFlagBits',desc='Bitmask specifying additional parameters of an image view',type='enums'] |
| -- |
| Bits which can: be set in slink:VkImageViewCreateInfo::pname:flags, |
| specifying additional parameters of an image view, are: |
| |
| include::{generated}/api/enums/VkImageViewCreateFlagBits.txt[] |
| |
| ifdef::VK_EXT_fragment_density_map[] |
| * ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DYNAMIC_BIT_EXT |
| specifies that the fragment density map will be read by device during |
| ename:VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT |
| endif::VK_EXT_fragment_density_map[] |
| ifdef::VK_EXT_fragment_density_map2[] |
| * ename:VK_IMAGE_VIEW_CREATE_FRAGMENT_DENSITY_MAP_DEFERRED_BIT_EXT |
| specifies that the fragment density map will be read by the host during |
| flink:vkEndCommandBuffer for the primary command buffer that the render |
| pass is recorded into |
| endif::VK_EXT_fragment_density_map2[] |
| -- |
| |
| [open,refpage='VkImageViewCreateFlags',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkImageViewCreateFlags.txt[] |
| |
| tname:VkImageViewCreateFlags is a bitmask type for setting a mask of zero or |
| more elink:VkImageViewCreateFlagBits. |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| [open,refpage='VkImageViewUsageCreateInfo',desc='Specify the intended usage of an image view',type='structs'] |
| -- |
| The set of usages for the created image view can: be restricted compared to |
| the parent image's pname:usage flags by adding a |
| sname:VkImageViewUsageCreateInfo structure to the pname:pNext chain of |
| slink:VkImageViewCreateInfo. |
| |
| The sname:VkImageViewUsageCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkImageViewUsageCreateInfo.txt[] |
| |
| ifdef::VK_KHR_maintenance2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkImageViewUsageCreateInfoKHR.txt[] |
| endif::VK_KHR_maintenance2[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:usage is a bitmask of elink:VkImageUsageFlagBits specifying |
| allowed usages of the image view. |
| |
| When this structure is chained to slink:VkImageViewCreateInfo the |
| pname:usage field overrides the implicit pname:usage parameter inherited |
| from image creation time and its value is used instead for the purposes of |
| determining the valid usage conditions of slink:VkImageViewCreateInfo. |
| |
| include::{generated}/validity/structs/VkImageViewUsageCreateInfo.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2[] |
| |
| [open,refpage='VkImageSubresourceRange',desc='Structure specifying an image subresource range',type='structs'] |
| -- |
| The sname:VkImageSubresourceRange structure is defined as: |
| |
| include::{generated}/api/structs/VkImageSubresourceRange.txt[] |
| |
| * pname:aspectMask is a bitmask of elink:VkImageAspectFlagBits specifying |
| which aspect(s) of the image are included in the view. |
| * pname:baseMipLevel is the first mipmap level accessible to the view. |
| * pname:levelCount is the number of mipmap levels (starting from |
| pname:baseMipLevel) accessible to the view. |
| * pname:baseArrayLayer is the first array layer accessible to the view. |
| * pname:layerCount is the number of array layers (starting from |
| pname:baseArrayLayer) accessible to the view. |
| |
| The number of mipmap levels and array layers must: be a subset of the image |
| subresources in the image. |
| If an application wants to use all mip levels or layers in an image after |
| the pname:baseMipLevel or pname:baseArrayLayer, it can: set pname:levelCount |
| and pname:layerCount to the special values ename:VK_REMAINING_MIP_LEVELS and |
| ename:VK_REMAINING_ARRAY_LAYERS without knowing the exact number of mip |
| levels or layers. |
| |
| For cube and cube array image views, the layers of the image view starting |
| at pname:baseArrayLayer correspond to faces in the order +X, -X, +Y, -Y, +Z, |
| -Z. |
| For cube arrays, each set of six sequential layers is a single cube, so the |
| number of cube maps in a cube map array view is _pname:layerCount / 6_, and |
| image array layer [eq]#(pname:baseArrayLayer {plus} i)# is face index |
| [eq]#(i mod 6)# of cube _i / 6_. |
| If the number of layers in the view, whether set explicitly in |
| pname:layerCount or implied by ename:VK_REMAINING_ARRAY_LAYERS, is not a |
| multiple of 6, the last cube map in the array must: not be accessed. |
| |
| pname:aspectMask must: be only ename:VK_IMAGE_ASPECT_COLOR_BIT, |
| ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT if |
| pname:format is a color, depth-only or stencil-only format, |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| respectively. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| respectively, except if pname:format is a |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar format>>. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| If using a depth/stencil format with both depth and stencil components, |
| pname:aspectMask must: include at least one of |
| ename:VK_IMAGE_ASPECT_DEPTH_BIT and ename:VK_IMAGE_ASPECT_STENCIL_BIT, and |
| can: include both. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| When the sname:VkImageSubresourceRange structure is used to select a subset |
| of the slices of a 3D image's mip level in order to create a 2D or 2D array |
| image view of a 3D image created with |
| ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, pname:baseArrayLayer and |
| pname:layerCount specify the first slice index and the number of slices to |
| include in the created image view. |
| Such an image view can: be used as a framebuffer attachment that refers only |
| to the specified range of slices of the selected mip level. |
| However, any layout transitions performed on such an attachment view during |
| a render pass instance still apply to the entire subresource referenced |
| which includes all the slices of the selected mip level. |
| endif::VK_VERSION_1_1,VK_KHR_maintenance1[] |
| |
| When using an image view of a depth/stencil image to populate a descriptor |
| set (e.g. for sampling in the shader, or for use as an input attachment), |
| the pname:aspectMask must: only include one bit, which selects whether the |
| image view is used for depth reads (i.e. using a floating-point sampler or |
| input attachment in the shader) or stencil reads (i.e. using an unsigned |
| integer sampler or input attachment in the shader). |
| When an image view of a depth/stencil image is used as a depth/stencil |
| framebuffer attachment, the pname:aspectMask is ignored and both depth and |
| stencil image subresources are used. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| When creating a sname:VkImageView, if <<samplers-YCbCr-conversion,sampler |
| {YCbCr} conversion>> is enabled in the sampler, the pname:aspectMask of a |
| pname:subresourceRange used by the sname:VkImageView must: be |
| ename:VK_IMAGE_ASPECT_COLOR_BIT. |
| |
| When creating a sname:VkImageView, if sampler {YCbCr} conversion is not |
| enabled in the sampler and the image pname:format is |
| <<formats-requiring-sampler-ycbcr-conversion,multi-planar>>, the image must: |
| have been created with ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, and the |
| pname:aspectMask of the sname:VkImageView's pname:subresourceRange must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageSubresourceRange-levelCount-01720]] |
| If pname:levelCount is not ename:VK_REMAINING_MIP_LEVELS, it must: be |
| greater than `0` |
| * [[VUID-VkImageSubresourceRange-layerCount-01721]] |
| If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, it must: be |
| greater than `0` |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkImageSubresourceRange-aspectMask-01670]] |
| If pname:aspectMask includes ename:VK_IMAGE_ASPECT_COLOR_BIT, then it |
| must: not include any of ename:VK_IMAGE_ASPECT_PLANE_0_BIT, |
| ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or ename:VK_IMAGE_ASPECT_PLANE_2_BIT |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkImageSubresourceRange-aspectMask-02278]] |
| pname:aspectMask must: not include |
| `VK_IMAGE_ASPECT_MEMORY_PLANE__{ibit}__BIT_EXT` for any index _i_ |
| endif::VK_EXT_image_drm_format_modifier[] |
| **** |
| |
| include::{generated}/validity/structs/VkImageSubresourceRange.txt[] |
| -- |
| |
| [open,refpage='VkImageAspectFlagBits',desc='Bitmask specifying which aspects of an image are included in a view',type='enums'] |
| -- |
| Bits which can: be set in an aspect mask to specify aspects of an image for |
| purposes such as identifying a subresource, are: |
| |
| include::{generated}/api/enums/VkImageAspectFlagBits.txt[] |
| |
| * ename:VK_IMAGE_ASPECT_COLOR_BIT specifies the color aspect. |
| * ename:VK_IMAGE_ASPECT_DEPTH_BIT specifies the depth aspect. |
| * ename:VK_IMAGE_ASPECT_STENCIL_BIT specifies the stencil aspect. |
| * ename:VK_IMAGE_ASPECT_METADATA_BIT specifies the metadata aspect, used |
| for <<sparsememory, sparse resource>> operations. |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * ename:VK_IMAGE_ASPECT_PLANE_0_BIT specifies plane 0 of a _multi-planar_ |
| image format. |
| * ename:VK_IMAGE_ASPECT_PLANE_1_BIT specifies plane 1 of a _multi-planar_ |
| image format. |
| * ename:VK_IMAGE_ASPECT_PLANE_2_BIT specifies plane 2 of a _multi-planar_ |
| image format. |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_0_BIT_EXT specifies _memory plane_ 0. |
| * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_1_BIT_EXT specifies _memory plane_ 1. |
| * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_2_BIT_EXT specifies _memory plane_ 2. |
| * ename:VK_IMAGE_ASPECT_MEMORY_PLANE_3_BIT_EXT specifies _memory plane_ 3. |
| endif::VK_EXT_image_drm_format_modifier[] |
| -- |
| |
| [open,refpage='VkImageAspectFlags',desc='Bitmask of VkImageAspectFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkImageAspectFlags.txt[] |
| |
| tname:VkImageAspectFlags is a bitmask type for setting a mask of zero or |
| more elink:VkImageAspectFlagBits. |
| -- |
| |
| [open,refpage='VkComponentMapping',desc='Structure specifying a color component mapping',type='structs'] |
| -- |
| The sname:VkComponentMapping structure is defined as: |
| |
| include::{generated}/api/structs/VkComponentMapping.txt[] |
| |
| * pname:r is a elink:VkComponentSwizzle specifying the component value |
| placed in the R component of the output vector. |
| * pname:g is a elink:VkComponentSwizzle specifying the component value |
| placed in the G component of the output vector. |
| * pname:b is a elink:VkComponentSwizzle specifying the component value |
| placed in the B component of the output vector. |
| * pname:a is a elink:VkComponentSwizzle specifying the component value |
| placed in the A component of the output vector. |
| |
| include::{generated}/validity/structs/VkComponentMapping.txt[] |
| -- |
| |
| [open,refpage='VkComponentSwizzle',desc='Specify how a component is swizzled',type='enums'] |
| -- |
| Possible values of the members of slink:VkComponentMapping, specifying the |
| component values placed in each component of the output vector, are: |
| |
| include::{generated}/api/enums/VkComponentSwizzle.txt[] |
| |
| * ename:VK_COMPONENT_SWIZZLE_IDENTITY specifies that the component is set |
| to the identity swizzle. |
| * ename:VK_COMPONENT_SWIZZLE_ZERO specifies that the component is set to |
| zero. |
| * ename:VK_COMPONENT_SWIZZLE_ONE specifies that the component is set to |
| either 1 or 1.0, depending on whether the type of the image view format |
| is integer or floating-point respectively, as determined by the |
| <<formats-definition,Format Definition>> section for each |
| elink:VkFormat. |
| * ename:VK_COMPONENT_SWIZZLE_R specifies that the component is set to the |
| value of the R component of the image. |
| * ename:VK_COMPONENT_SWIZZLE_G specifies that the component is set to the |
| value of the G component of the image. |
| * ename:VK_COMPONENT_SWIZZLE_B specifies that the component is set to the |
| value of the B component of the image. |
| * ename:VK_COMPONENT_SWIZZLE_A specifies that the component is set to the |
| value of the A component of the image. |
| |
| [[resources-image-views-identity-mappings]] |
| Setting the identity swizzle on a component is equivalent to setting the |
| identity mapping on that component. |
| That is: |
| |
| .Component Mappings Equivalent To ename:VK_COMPONENT_SWIZZLE_IDENTITY |
| [options="header"] |
| |==== |
| | Component | Identity Mapping |
| | pname:components.r | ename:VK_COMPONENT_SWIZZLE_R |
| | pname:components.g | ename:VK_COMPONENT_SWIZZLE_G |
| | pname:components.b | ename:VK_COMPONENT_SWIZZLE_B |
| | pname:components.a | ename:VK_COMPONENT_SWIZZLE_A |
| |==== |
| -- |
| |
| ifdef::VK_EXT_astc_decode_mode[] |
| [open,refpage='VkImageViewASTCDecodeModeEXT',desc='Structure describing the ASTC decode mode for an image view',type='structs'] |
| -- |
| If the pname:pNext chain includes a sname:VkImageViewASTCDecodeModeEXT |
| structure, then that structure includes a parameter specifying the decode |
| mode for image views using ASTC compressed formats. |
| |
| The sname:VkImageViewASTCDecodeModeEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkImageViewASTCDecodeModeEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:decodeMode is the intermediate format used to decode ASTC |
| compressed formats. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02230]] |
| pname:decodeMode must: be one of ename:VK_FORMAT_R16G16B16A16_SFLOAT, |
| ename:VK_FORMAT_R8G8B8A8_UNORM, or |
| ename:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 |
| * [[VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02231]] |
| If the <<features-astc-decodeModeSharedExponent, |
| pname:decodeModeSharedExponent>> feature is not enabled, |
| pname:decodeMode must: not be ename:VK_FORMAT_E5B9G9R9_UFLOAT_PACK32 |
| * [[VUID-VkImageViewASTCDecodeModeEXT-decodeMode-02232]] |
| If pname:decodeMode is ename:VK_FORMAT_R8G8B8A8_UNORM the image view |
| must: not include blocks using any of the ASTC HDR modes |
| * [[VUID-VkImageViewASTCDecodeModeEXT-format-04084]] |
| pname:format of the image view must: be one of the |
| <<appendix-compressedtex-astc, ASTC Compressed Image Formats>> |
| **** |
| |
| If pname:format uses sRGB encoding then the pname:decodeMode has no effect. |
| |
| include::{generated}/validity/structs/VkImageViewASTCDecodeModeEXT.txt[] |
| -- |
| endif::VK_EXT_astc_decode_mode[] |
| |
| [open,refpage='vkDestroyImageView',desc='Destroy an image view object',type='protos'] |
| -- |
| To destroy an image view, call: |
| |
| include::{generated}/api/protos/vkDestroyImageView.txt[] |
| |
| * pname:device is the logical device that destroys the image view. |
| * pname:imageView is the image view to destroy. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkDestroyImageView-imageView-01026]] |
| All submitted commands that refer to pname:imageView must: have |
| completed execution |
| * [[VUID-vkDestroyImageView-imageView-01027]] |
| If sname:VkAllocationCallbacks were provided when pname:imageView was |
| created, a compatible set of callbacks must: be provided here |
| * [[VUID-vkDestroyImageView-imageView-01028]] |
| If no sname:VkAllocationCallbacks were provided when pname:imageView was |
| created, pname:pAllocator must: be `NULL` |
| **** |
| |
| include::{generated}/validity/protos/vkDestroyImageView.txt[] |
| -- |
| |
| ifdef::VK_NVX_image_view_handle[] |
| [open,refpage='vkGetImageViewHandleNVX',desc='Get the handle for an image view for a specific descriptor type',type='protos'] |
| -- |
| To get the handle for an image view, call: |
| |
| include::{generated}/api/protos/vkGetImageViewHandleNVX.txt[] |
| |
| * pname:device is the logical device that owns the image view. |
| * pname:pInfo describes the image view to query and type of handle. |
| |
| include::{generated}/validity/protos/vkGetImageViewHandleNVX.txt[] |
| -- |
| |
| [open,refpage='VkImageViewHandleInfoNVX',desc='Structure specifying the image view for handle queries',type='structs'] |
| -- |
| The sname:VkImageViewHandleInfoNVX structure is defined as: |
| |
| include::{generated}/api/structs/VkImageViewHandleInfoNVX.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:imageView is the image view to query. |
| * pname:descriptorType is the type of descriptor for which to query a |
| handle. |
| * pname:sampler is the sampler to combine with the image view when |
| generating the handle. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageViewHandleInfoNVX-descriptorType-02654]] |
| pname:descriptorType must: be ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE, |
| ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, or |
| ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER |
| * [[VUID-VkImageViewHandleInfoNVX-sampler-02655]] |
| pname:sampler must: be a valid slink:VkSampler if pname:descriptorType |
| is ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER |
| * [[VUID-VkImageViewHandleInfoNVX-imageView-02656]] |
| If descriptorType is ename:VK_DESCRIPTOR_TYPE_SAMPLED_IMAGE or |
| ename:VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER, the image that |
| pname:imageView was created from must: have been created with the |
| ename:VK_IMAGE_USAGE_SAMPLED_BIT usage bit set |
| * [[VUID-VkImageViewHandleInfoNVX-imageView-02657]] |
| If descriptorType is ename:VK_DESCRIPTOR_TYPE_STORAGE_IMAGE, the image |
| that pname:imageView was created from must: have been created with the |
| ename:VK_IMAGE_USAGE_STORAGE_BIT usage bit set |
| **** |
| |
| include::{generated}/validity/structs/VkImageViewHandleInfoNVX.txt[] |
| -- |
| |
| [open,refpage='vkGetImageViewAddressNVX',desc='Get the device address of an image view',type='protos'] |
| -- |
| To get the device address for an image view, call: |
| |
| include::{generated}/api/protos/vkGetImageViewAddressNVX.txt[] |
| |
| * pname:device is the logical device that owns the image view. |
| * pname:imageView is a handle to the image view. |
| * pname:pProperties contains the device address and size when the call |
| returns. |
| |
| include::{generated}/validity/protos/vkGetImageViewAddressNVX.txt[] |
| -- |
| |
| [open,refpage='VkImageViewAddressPropertiesNVX',desc='Structure specifying the image view for handle queries',type='structs'] |
| -- |
| The sname:VkImageViewAddressPropertiesNVX structure is defined as: |
| |
| include::{generated}/api/structs/VkImageViewAddressPropertiesNVX.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:deviceAddress is the device address of the image view. |
| * pname:size is the size in bytes of the image view device memory. |
| |
| |
| include::{generated}/validity/structs/VkImageViewAddressPropertiesNVX.txt[] |
| -- |
| endif::VK_NVX_image_view_handle[] |
| |
| |
| [[resources-image-view-format-features]] |
| === Image View Format Features |
| |
| Valid uses of a slink:VkImageView may: depend on the image view's _format |
| features_, defined below. |
| Such constraints are documented in the affected valid usage statement. |
| |
| ifndef::VK_KHR_format_feature_flags2[] |
| * If slink:VkImageViewCreateInfo::pname:image was created with |
| ename:VK_IMAGE_TILING_LINEAR, then the image view's set of _format |
| features_ is the value of |
| slink:VkFormatProperties::pname:linearTilingFeatures found by calling |
| flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as |
| slink:VkImageViewCreateInfo::pname:format. |
| endif::VK_KHR_format_feature_flags2[] |
| ifdef::VK_KHR_format_feature_flags2[] |
| * If the extension `apiext:VK_KHR_format_feature_flags2` is enabled and |
| slink:VkImageViewCreateInfo::pname:image was created with |
| ename:VK_IMAGE_TILING_LINEAR, then the image view's set of _format |
| features_ is the value of |
| slink:VkFormatProperties3KHR::pname:linearTilingFeatures found by |
| calling flink:vkGetPhysicalDeviceFormatProperties2 on the same |
| pname:format as slink:VkImageViewCreateInfo::pname:format. |
| * If the extension `apiext:VK_KHR_format_feature_flags2` is not enabled |
| and slink:VkImageViewCreateInfo::pname:image was created with |
| ename:VK_IMAGE_TILING_LINEAR, then the image view's set of _format |
| features_ is the union of the value of |
| slink:VkFormatProperties::pname:linearTilingFeatures found by calling |
| flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as |
| slink:VkImageViewCreateInfo::pname:format, with: |
| - ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT_KHR if |
| the format is a depth/stencil format and the image view features also |
| contain ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT_KHR. |
| - ename:VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT_KHR if the |
| format is one of the <<formats-without-shader-storage-format,extended |
| storage formats>> and pname:shaderStorageImageReadWithoutFormat is |
| enabled on the device. |
| - ename:VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT_KHR if the |
| format is one of the <<formats-without-shader-storage-format,extended |
| storage formats>> and pname:shaderStorageImageWriteWithoutFormat is |
| enabled on the device. |
| endif::VK_KHR_format_feature_flags2[] |
| ifndef::VK_KHR_format_feature_flags2[] |
| * If slink:VkImageViewCreateInfo::pname:image was created with |
| ename:VK_IMAGE_TILING_OPTIMAL, |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| but without an |
| <<memory-external-android-hardware-buffer-external-formats,Android |
| hardware buffer external format>>, |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| then the image view's set of _format features_ is the value of |
| slink:VkFormatProperties::pname:optimalTilingFeatures found by calling |
| flink:vkGetPhysicalDeviceFormatProperties on the same pname:format as |
| slink:VkImageViewCreateInfo::pname:format. |
| endif::VK_KHR_format_feature_flags2[] |
| ifdef::VK_KHR_format_feature_flags2[] |
| * If the extension `apiext:VK_KHR_format_feature_flags2` is enabled and |
| slink:VkImageViewCreateInfo::pname:image was created with |
| ename:VK_IMAGE_TILING_OPTIMAL, |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| but without an |
| <<memory-external-android-hardware-buffer-external-formats,Android |
| hardware buffer external format>>, |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| then the image view's set of _format features_ is the value of |
| slink:VkFormatProperties::pname:optimalTilingFeatures or |
| slink:VkFormatProperties3KHR::pname:optimalTilingFeatures found by |
| calling flink:vkGetPhysicalDeviceFormatProperties or |
| flink:vkGetPhysicalDeviceImageFormatProperties2 on the same pname:format |
| as slink:VkImageViewCreateInfo::pname:format. |
| * If the extension `apiext:VK_KHR_format_feature_flags2` is not enabled |
| and slink:VkImageViewCreateInfo::pname:image was created with |
| ename:VK_IMAGE_TILING_OPTIMAL, |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| but without an |
| <<memory-external-android-hardware-buffer-external-formats,Android |
| hardware buffer external format>>, |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| then the image view's set of _format features_ is the union of the value |
| of slink:VkFormatProperties::pname:optimalTilingFeatures found by |
| calling flink:vkGetPhysicalDeviceFormatProperties on the same |
| pname:format as slink:VkImageViewCreateInfo::pname:format, with: |
| - ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT_KHR if |
| the format is a depth/stencil format and the image view features also |
| contain ename:VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT_KHR. |
| - ename:VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT_KHR if the |
| format is one of the <<formats-without-shader-storage-format,extended |
| storage formats>> and pname:shaderStorageImageReadWithoutFormat is |
| enabled on the device. |
| - ename:VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT_KHR if the |
| format is one of the <<formats-without-shader-storage-format,extended |
| storage formats>> and pname:shaderStorageImageWriteWithoutFormat is |
| enabled on the device. |
| endif::VK_KHR_format_feature_flags2[] |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * If slink:VkImageViewCreateInfo::pname:image was created with an |
| <<memory-external-android-hardware-buffer-external-formats,Android |
| hardware buffer external format>>, then the image views's set of _format |
| features_ is the value of |
| slink:VkAndroidHardwareBufferFormatPropertiesANDROID::pname:formatFeatures |
| found by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID on |
| the Android hardware buffer that was imported to the |
| slink:VkDeviceMemory to which the |
| slink:VkImageViewCreateInfo::pname:image is bound. |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| * If slink:VkImageViewCreateInfo::pname:image was created with a chained |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA, then the image view's |
| set of _format features_ is the value of |
| slink:VkBufferCollectionPropertiesFUCHSIA::pname:formatFeatures found by |
| calling flink:vkGetBufferCollectionPropertiesFUCHSIA on the buffer |
| collection passed as |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA::pname:collection when |
| the image was created. |
| endif::VK_FUCHSIA_buffer_collection[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * If slink:VkImageViewCreateInfo::pname:image was created with |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then: |
| ** The image's DRM format modifier is the value of |
| slink:VkImageDrmFormatModifierListCreateInfoEXT::pname:drmFormatModifier |
| found by calling flink:vkGetImageDrmFormatModifierPropertiesEXT. |
| ** Let |
| slink:VkDrmFormatModifierPropertiesListEXT::pname:pDrmFormatModifierProperties |
| be the array found by calling |
| flink:vkGetPhysicalDeviceFormatProperties2 on the same pname:format as |
| slink:VkImageViewCreateInfo::pname:format. |
| ** Let `VkDrmFormatModifierPropertiesEXT prop` be an array element whose |
| pname:drmFormatModifier member is the value of the image's DRM format |
| modifier. |
| ** Then the image view's set of _format features_ is the value of taking |
| the bitwise intersection, over the collected |
| `prop`::pname:drmFormatModifierTilingFeatures. |
| endif::VK_EXT_image_drm_format_modifier[] |
| |
| |
| ifdef::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] |
| [[resources-acceleration-structures]] |
| == Acceleration Structures |
| |
| [open,refpage='VkAccelerationStructureKHR',desc='Opaque handle to an acceleration structure object',type='handles'] |
| -- |
| :refpage: VkAccelerationStructureKHR |
| |
| Acceleration structures are opaque data structures that are built by the |
| implementation to more efficiently perform spatial queries on the provided |
| geometric data. |
| For this extension, an acceleration structure is either a top-level |
| acceleration structure containing a set of bottom-level acceleration |
| structures or a bottom-level acceleration structure containing either a set |
| of axis-aligned bounding boxes for custom geometry or a set of triangles. |
| |
| Each instance in the top-level acceleration structure contains a reference |
| to a bottom-level acceleration structure as well as an instance transform |
| plus information required to index into the shader bindings. |
| The top-level acceleration structure is what is bound to the acceleration |
| descriptor, for example to trace inside the shader in the ray tracing |
| pipeline. |
| |
| Acceleration structures are represented by sname:VkAccelerationStructureKHR |
| handles: |
| |
| include::{generated}/api/handles/VkAccelerationStructureKHR.txt[] |
| -- |
| |
| ifdef::VK_NV_ray_tracing[] |
| [open,refpage='VkAccelerationStructureNV',desc='Opaque handle to an acceleration structure object',type='handles'] |
| -- |
| :refpage: VkAccelerationStructureNV |
| |
| Acceleration structures for the apiext:VK_NV_ray_tracing extension are |
| represented by the similar sname:VkAccelerationStructureNV handles: |
| |
| include::{generated}/api/handles/VkAccelerationStructureNV.txt[] |
| -- |
| |
| [open,refpage='vkCreateAccelerationStructureNV',desc='Create a new acceleration structure object',type='protos'] |
| -- |
| :refpage: vkCreateAccelerationStructureNV |
| |
| To create acceleration structures, call: |
| |
| include::{generated}/api/protos/vkCreateAccelerationStructureNV.txt[] |
| |
| * pname:device is the logical device that creates the buffer object. |
| * pname:pCreateInfo is a pointer to a |
| slink:VkAccelerationStructureCreateInfoNV structure containing |
| parameters affecting creation of the acceleration structure. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pAccelerationStructure is a pointer to a |
| slink:VkAccelerationStructureNV handle in which the resulting |
| acceleration structure object is returned. |
| |
| Similarly to other objects in Vulkan, the acceleration structure creation |
| merely creates an object with a specific "`shape`" as specified by the |
| information in slink:VkAccelerationStructureInfoNV and pname:compactedSize |
| in pname:pCreateInfo. |
| Populating the data in the object after allocating and binding memory is |
| done with flink:vkCmdBuildAccelerationStructureNV and |
| flink:vkCmdCopyAccelerationStructureNV. |
| |
| Acceleration structure creation uses the count and type information from the |
| geometries, but does not use the data references in the structures. |
| |
| include::{generated}/validity/protos/vkCreateAccelerationStructureNV.txt[] |
| -- |
| |
| [open,refpage='VkAccelerationStructureCreateInfoNV',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] |
| -- |
| :refpage: VkAccelerationStructureCreateInfoNV |
| |
| The sname:VkAccelerationStructureCreateInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkAccelerationStructureCreateInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:compactedSize is the size from the result of |
| flink:vkCmdWriteAccelerationStructuresPropertiesNV if this acceleration |
| structure is going to be the target of a compacting copy. |
| * pname:info is the slink:VkAccelerationStructureInfoNV structure |
| specifying further parameters of the created acceleration structure. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkAccelerationStructureCreateInfoNV-compactedSize-02421]] |
| If pname:compactedSize is not `0` then both pname:info.geometryCount and |
| pname:info.instanceCount must: be `0` |
| **** |
| |
| include::{generated}/validity/structs/VkAccelerationStructureCreateInfoNV.txt[] |
| -- |
| |
| [open,refpage='VkAccelerationStructureInfoNV',desc='Structure specifying the parameters of acceleration structure object',type='structs'] |
| -- |
| :refpage: VkAccelerationStructureInfoNV |
| |
| The sname:VkAccelerationStructureInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkAccelerationStructureInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:type is a elink:VkAccelerationStructureTypeNV value specifying the |
| type of acceleration structure that will be created. |
| * pname:flags is a bitmask of elink:VkBuildAccelerationStructureFlagBitsNV |
| specifying additional parameters of the acceleration structure. |
| * pname:instanceCount specifies the number of instances that will be in |
| the new acceleration structure. |
| * pname:geometryCount specifies the number of geometries that will be in |
| the new acceleration structure. |
| * pname:pGeometries is a pointer to an array of pname:geometryCount |
| slink:VkGeometryNV structures containing the scene data being passed |
| into the acceleration structure. |
| |
| sname:VkAccelerationStructureInfoNV contains information that is used both |
| for acceleration structure creation with |
| flink:vkCreateAccelerationStructureNV and in combination with the actual |
| geometric data to build the acceleration structure with |
| flink:vkCmdBuildAccelerationStructureNV. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkAccelerationStructureInfoNV-geometryCount-02422]] |
| pname:geometryCount must: be less than or equal to |
| slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxGeometryCount |
| * [[VUID-VkAccelerationStructureInfoNV-instanceCount-02423]] |
| pname:instanceCount must: be less than or equal to |
| slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxInstanceCount |
| * [[VUID-VkAccelerationStructureInfoNV-maxTriangleCount-02424]] |
| The total number of triangles in all geometries must: be less than or |
| equal to |
| slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxTriangleCount |
| * [[VUID-VkAccelerationStructureInfoNV-type-02425]] |
| If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV then |
| pname:geometryCount must: be `0` |
| * [[VUID-VkAccelerationStructureInfoNV-type-02426]] |
| If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV |
| then pname:instanceCount must: be `0` |
| * [[VUID-VkAccelerationStructureInfoNV-type-02786]] |
| If pname:type is ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV |
| then the pname:geometryType member of each geometry in pname:pGeometries |
| must: be the same |
| ifdef::VK_KHR_acceleration_structure[] |
| * [[VUID-VkAccelerationStructureInfoNV-type-04623]] |
| pname:type must: not be ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR |
| endif::VK_KHR_acceleration_structure[] |
| * [[VUID-VkAccelerationStructureInfoNV-flags-02592]] |
| If pname:flags has the |
| ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV bit set, |
| then it must: not have the |
| ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV bit set |
| * [[VUID-VkAccelerationStructureInfoNV-scratch-02781]] |
| pname:scratch must: have been created with |
| ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV usage flag |
| * [[VUID-VkAccelerationStructureInfoNV-instanceData-02782]] |
| If pname:instanceData is not dlink:VK_NULL_HANDLE, pname:instanceData |
| must: have been created with ename:VK_BUFFER_USAGE_RAY_TRACING_BIT_NV |
| usage flag |
| **** |
| |
| include::{generated}/validity/structs/VkAccelerationStructureInfoNV.txt[] |
| -- |
| endif::VK_NV_ray_tracing[] |
| |
| ifdef::VK_KHR_acceleration_structure[] |
| [open,refpage='vkCreateAccelerationStructureKHR',desc='Create a new acceleration structure object',type='protos'] |
| -- |
| :refpage: vkCreateAccelerationStructureKHR |
| |
| To create an acceleration structure, call: |
| |
| include::{generated}/api/protos/vkCreateAccelerationStructureKHR.txt[] |
| |
| * pname:device is the logical device that creates the acceleration |
| structure object. |
| * pname:pCreateInfo is a pointer to a |
| slink:VkAccelerationStructureCreateInfoKHR structure containing |
| parameters affecting creation of the acceleration structure. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| * pname:pAccelerationStructure is a pointer to a |
| sname:VkAccelerationStructureKHR handle in which the resulting |
| acceleration structure object is returned. |
| |
| Similar to other objects in Vulkan, the acceleration structure creation |
| merely creates an object with a specific "`shape`". |
| The type and quantity of geometry that can be built into an acceleration |
| structure is determined by the parameters of |
| slink:VkAccelerationStructureCreateInfoKHR. |
| |
| Populating the data in the object after allocating and binding memory is |
| done with commands such as flink:vkCmdBuildAccelerationStructuresKHR, |
| flink:vkBuildAccelerationStructuresKHR, |
| flink:vkCmdCopyAccelerationStructureKHR, and |
| flink:vkCopyAccelerationStructureKHR. |
| |
| The input buffers passed to acceleration structure build commands will be |
| referenced by the implementation for the duration of the command. |
| After the command completes, the acceleration structure may: hold a |
| reference to any acceleration structure specified by an active instance |
| contained therein. |
| Apart from this referencing, acceleration structures must: be fully |
| self-contained. |
| The application may: re-use or free any memory which was used by the command |
| as an input or as scratch without affecting the results of ray traversal. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCreateAccelerationStructureKHR-accelerationStructure-03611]] |
| The <<features-accelerationStructure, pname:accelerationStructure>> |
| feature must: be enabled |
| * [[VUID-vkCreateAccelerationStructureKHR-deviceAddress-03488]] |
| If slink:VkAccelerationStructureCreateInfoKHR::pname:deviceAddress is |
| not zero, the |
| <<features-accelerationStructureCaptureReplay,pname:accelerationStructureCaptureReplay>> |
| feature must: be enabled |
| * [[VUID-vkCreateAccelerationStructureKHR-device-03489]] |
| If pname:device was created with multiple physical devices, then the |
| <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>> |
| feature must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkCreateAccelerationStructureKHR.txt[] |
| -- |
| |
| [open,refpage='VkAccelerationStructureCreateInfoKHR',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] |
| -- |
| :refpage: VkAccelerationStructureCreateInfoKHR |
| |
| The sname:VkAccelerationStructureCreateInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkAccelerationStructureCreateInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:createFlags is a bitmask of |
| elink:VkAccelerationStructureCreateFlagBitsKHR specifying additional |
| creation parameters of the acceleration structure. |
| * pname:buffer is the buffer on which the acceleration structure will be |
| stored. |
| * pname:offset is an offset in bytes from the base address of the buffer |
| at which the acceleration structure will be stored, and must: be a |
| multiple of `256`. |
| * pname:size is the size required for the acceleration structure. |
| * pname:type is a elink:VkAccelerationStructureTypeKHR value specifying |
| the type of acceleration structure that will be created. |
| * pname:deviceAddress is the device address requested for the acceleration |
| structure if the <<features-accelerationStructureCaptureReplay, |
| pname:accelerationStructureCaptureReplay>> feature is being used. |
| |
| If pname:deviceAddress is zero, no specific address is requested. |
| |
| If pname:deviceAddress is not zero, pname:deviceAddress must: be an address |
| retrieved from an identically created acceleration structure on the same |
| implementation. |
| The acceleration structure must: also be placed on an identically created |
| pname:buffer and at the same pname:offset. |
| |
| Applications should: avoid creating acceleration structures with |
| application-provided addresses and implementation-provided addresses in the |
| same process, to reduce the likelihood of |
| ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR errors. |
| |
| [NOTE] |
| .Note |
| ==== |
| The expected usage for this is that a trace capture/replay tool will add the |
| ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT flag to all buffers |
| that use ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT, and will add |
| ename:VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT to all buffers used as |
| storage for an acceleration structure where pname:deviceAddress is not zero. |
| This also means that the tool will need to add |
| ename:VK_MEMORY_ALLOCATE_DEVICE_ADDRESS_BIT to memory allocations to allow |
| the flag to be set where the application may not have otherwise required it. |
| During capture the tool will save the queried opaque device addresses in the |
| trace. |
| During replay, the buffers will be created specifying the original address |
| so any address values stored in the trace data will remain valid. |
| |
| Implementations are expected to separate such buffers in the GPU address |
| space so normal allocations will avoid using these addresses. |
| Apps/tools should avoid mixing app-provided and implementation-provided |
| addresses for buffers created with |
| ename:VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT, to avoid address |
| space allocation conflicts. |
| ==== |
| |
| |
| Applications should: create an acceleration structure with a specific |
| elink:VkAccelerationStructureTypeKHR other than |
| ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR. |
| |
| If the acceleration structure will be the target of a build operation, the |
| required size for an acceleration structure can: be queried with |
| flink:vkGetAccelerationStructureBuildSizesKHR. |
| If the acceleration structure is going to be the target of a compacting |
| copy, flink:vkCmdWriteAccelerationStructuresPropertiesKHR or |
| flink:vkWriteAccelerationStructuresPropertiesKHR can: be used to obtain the |
| compacted size required. |
| |
| ifdef::VK_NV_ray_tracing_motion_blur[] |
| If the acceleration structure will be the target of a build operation with |
| ename:VK_BUILD_ACCELERATION_STRUCTURE_MOTION_BIT_NV it must: include |
| ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV in pname:flags and |
| include slink:VkAccelerationStructureMotionInfoNV as an extension structure |
| in pname:pNext with the number of instances as metadata for the object. |
| endif::VK_NV_ray_tracing_motion_blur[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkAccelerationStructureCreateInfoKHR-deviceAddress-03612]] |
| If pname:deviceAddress is not zero, pname:createFlags must: include |
| ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR |
| * [[VUID-VkAccelerationStructureCreateInfoKHR-createFlags-03613]] |
| If pname:createFlags includes |
| ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR, |
| slink:VkPhysicalDeviceAccelerationStructureFeaturesKHR::pname:accelerationStructureCaptureReplay |
| must: be ename:VK_TRUE |
| * [[VUID-VkAccelerationStructureCreateInfoKHR-buffer-03614]] |
| pname:buffer must: have been created with a pname:usage value containing |
| ename:VK_BUFFER_USAGE_ACCELERATION_STRUCTURE_STORAGE_BIT_KHR |
| * [[VUID-VkAccelerationStructureCreateInfoKHR-buffer-03615]] |
| pname:buffer must: not have been created with |
| ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT |
| * [[VUID-VkAccelerationStructureCreateInfoKHR-offset-03616]] |
| The sum of pname:offset and pname:size must: be less than the size of |
| pname:buffer |
| * [[VUID-VkAccelerationStructureCreateInfoKHR-offset-03734]] |
| pname:offset must: be a multiple of `256` bytes |
| ifdef::VK_NV_ray_tracing_motion_blur[] |
| * [[VUID-VkAccelerationStructureCreateInfoKHR-flags-04954]] |
| If ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV is set in |
| pname:flags and pname:type is |
| ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR, |
| one member of the pname:pNext chain must: be a pointer to a valid instance |
| of slink:VkAccelerationStructureMotionInfoNV |
| * [[VUID-VkAccelerationStructureCreateInfoKHR-flags-04955]] |
| If any geometry includes |
| sname:VkAccelerationStructureGeometryMotionTrianglesDataNV then |
| pname:flags must: contain |
| ename:VK_ACCELERATION_STRUCTURE_CREATE_MOTION_BIT_NV |
| endif::VK_NV_ray_tracing_motion_blur[] |
| **** |
| |
| include::{generated}/validity/structs/VkAccelerationStructureCreateInfoKHR.txt[] |
| -- |
| |
| ifdef::VK_NV_ray_tracing_motion_blur[] |
| [open,refpage='VkAccelerationStructureMotionInfoNV',desc='Structure specifying the parameters of a newly created acceleration structure object',type='structs'] |
| -- |
| :refpage: VkAccelerationStructureMotionInfoNV |
| |
| The sname:VkAccelerationStructureMotionInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkAccelerationStructureMotionInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:maxInstances is the maximum number of instances that may: be used |
| in the motion top-level acceleration structure. |
| * pname:flags is 0 and reserved for future use. |
| |
| include::{generated}/validity/structs/VkAccelerationStructureMotionInfoNV.txt[] |
| -- |
| |
| [open,refpage='VkAccelerationStructureMotionInfoFlagsNV',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkAccelerationStructureMotionInfoFlagsNV.txt[] |
| |
| tname:VkAccelerationStructureMotionInfoFlagsNV is a bitmask type for setting |
| a mask, but is currently reserved for future use. |
| -- |
| endif::VK_NV_ray_tracing_motion_blur[] |
| |
| [open,refpage='vkGetAccelerationStructureBuildSizesKHR',desc='Retrieve the required size for an acceleration structure',type='protos'] |
| -- |
| :refpage: vkGetAccelerationStructureBuildSizesKHR |
| |
| To get the build sizes for an acceleration structure, call: |
| |
| include::{generated}/api/protos/vkGetAccelerationStructureBuildSizesKHR.txt[] |
| |
| * pname:device is the logical device that will be used for creating the |
| acceleration structure. |
| * pname:buildType defines whether host or device operations (or both) are |
| being queried for. |
| * pname:pBuildInfo is a pointer to a |
| slink:VkAccelerationStructureBuildGeometryInfoKHR structure describing |
| parameters of a build operation. |
| * pname:pMaxPrimitiveCounts is a pointer to an array of |
| pname:pBuildInfo->geometryCount code:uint32_t values defining the number |
| of primitives built into each geometry. |
| * pname:pSizeInfo is a pointer to a |
| slink:VkAccelerationStructureBuildSizesInfoKHR structure which returns |
| the size required for an acceleration structure and the sizes required |
| for the scratch buffers, given the build parameters. |
| |
| The pname:srcAccelerationStructure, pname:dstAccelerationStructure, and |
| pname:mode members of pname:pBuildInfo are ignored. |
| Any slink:VkDeviceOrHostAddressKHR members of pname:pBuildInfo are ignored |
| by this command, except that the pname:hostAddress member of |
| slink:VkAccelerationStructureGeometryTrianglesDataKHR::pname:transformData |
| will be examined to check if it is `NULL`. |
| |
| An acceleration structure created with the pname:accelerationStructureSize |
| returned by this command supports any build or update with a |
| slink:VkAccelerationStructureBuildGeometryInfoKHR structure and array of |
| slink:VkAccelerationStructureBuildRangeInfoKHR structures subject to the |
| following properties: |
| |
| * The build command is a host build command, and pname:buildType is |
| ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR or |
| ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR |
| * The build command is a device build command, and pname:buildType is |
| ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR or |
| ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR |
| * For slink:VkAccelerationStructureBuildGeometryInfoKHR: |
| ** Its pname:type, and pname:flags members are equal to those specified in |
| pname:pBuildInfo. |
| ** pname:geometryCount is less than or equal to that specified in |
| pname:pBuildInfo. |
| ** For each element of either pname:pGeometries or pname:ppGeometries at a |
| given index, its pname:geometryType member is equal to that specified |
| in pname:pBuildInfo. |
| ** For each element of either pname:pGeometries or pname:ppGeometries at a |
| given index, with a pname:geometryType member equal to |
| ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the pname:vertexFormat and |
| pname:indexType members of pname:geometry.triangles are equal to those |
| specified in the same element in pname:pBuildInfo. |
| ** For each element of either pname:pGeometries or pname:ppGeometries at a |
| given index, with a pname:geometryType member equal to |
| ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, the pname:maxVertex member of |
| pname:geometry.triangles is less than or equal to that specified in the |
| same element in pname:pBuildInfo. |
| ** For each element of either pname:pGeometries or pname:ppGeometries at a |
| given index, with a pname:geometryType member equal to |
| ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR, if the applicable address in the |
| pname:transformData member of pname:geometry.triangles is not `NULL`, |
| the corresponding pname:transformData.hostAddress parameter in |
| pname:pBuildInfo is not `NULL`. |
| * For each slink:VkAccelerationStructureBuildRangeInfoKHR corresponding to |
| the slink:VkAccelerationStructureBuildGeometryInfoKHR: |
| ** Its pname:primitiveCount member is less than or equal to the |
| corresponding element of pname:pMaxPrimitiveCounts. |
| |
| Similarly, the pname:updateScratchSize value will support any build command |
| specifying the ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR |
| pname:mode under the above conditions, and the pname:buildScratchSize value |
| will support any build command specifying the |
| ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_BUILD_KHR pname:mode under the |
| above conditions. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetAccelerationStructureBuildSizesKHR-rayTracingPipeline-03617]] |
| The <<features-rayTracingPipeline, pname:rayTracingPipeline>> or |
| <<features-rayQuery, pname:rayQuery>> feature must: be enabled |
| * [[VUID-vkGetAccelerationStructureBuildSizesKHR-device-03618]] |
| If pname:device was created with multiple physical devices, then the |
| <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>> |
| feature must: be enabled |
| * [[VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-03619]] |
| If pname:pBuildInfo->geometryCount is not `0`, pname:pMaxPrimitiveCounts |
| must: be a valid pointer to an array of pname:pBuildInfo->geometryCount |
| code:uint32_t values |
| * [[VUID-vkGetAccelerationStructureBuildSizesKHR-pBuildInfo-03785]] |
| If pname:pBuildInfo->pGeometries or pname:pBuildInfo->ppGeometries has a |
| pname:geometryType of ename:VK_GEOMETRY_TYPE_INSTANCES_KHR, each |
| pname:pMaxPrimitiveCounts[i] must: be less than or equal to |
| slink:VkPhysicalDeviceAccelerationStructurePropertiesKHR::pname:maxInstanceCount |
| **** |
| |
| include::{generated}/validity/protos/vkGetAccelerationStructureBuildSizesKHR.txt[] |
| -- |
| |
| [open,refpage='VkAccelerationStructureBuildSizesInfoKHR',desc='Structure specifying build sizes for an acceleration structure',type='structs'] |
| -- |
| :refpage: VkAccelerationStructureBuildSizesInfoKHR |
| |
| The sname:VkAccelerationStructureBuildSizesInfoKHR structure describes the |
| required build sizes for an acceleration structure and scratch buffers and |
| is defined as: |
| |
| include::{generated}/api/structs/VkAccelerationStructureBuildSizesInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:accelerationStructureSize is the size in bytes required in a |
| slink:VkAccelerationStructureKHR for a build or update operation. |
| * pname:updateScratchSize is the size in bytes required in a scratch |
| buffer for an update operation. |
| * pname:buildScratchSize is the size in bytes required in a scratch buffer |
| for a build operation. |
| |
| include::{generated}/validity/structs/VkAccelerationStructureBuildSizesInfoKHR.txt[] |
| -- |
| endif::VK_KHR_acceleration_structure[] |
| |
| [open,refpage='VkAccelerationStructureTypeKHR',desc='Type of acceleration structure',type='enums',alias='VkAccelerationStructureTypeNV'] |
| -- |
| :refpage: VkAccelerationStructureTypeKHR |
| |
| Values which can: be set in |
| ifdef::VK_KHR_acceleration_structure[] |
| slink:VkAccelerationStructureCreateInfoKHR::pname:type |
| endif::VK_KHR_acceleration_structure[] |
| ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] |
| ifdef::VK_NV_ray_tracing[] |
| slink:VkAccelerationStructureInfoNV::pname:type |
| endif::VK_NV_ray_tracing[] |
| specifying the type of acceleration structure, are: |
| |
| include::{generated}/api/enums/VkAccelerationStructureTypeKHR.txt[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkAccelerationStructureTypeNV.txt[] |
| endif::VK_NV_ray_tracing[] |
| |
| * ename:VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR is a top-level |
| acceleration structure containing instance data referring to |
| bottom-level acceleration structures. |
| * ename:VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_KHR is a bottom-level |
| acceleration structure containing the AABBs or geometry to be |
| intersected. |
| * ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR is an acceleration |
| structure whose type is determined at build time used for special |
| circumstances. |
| -- |
| |
| ifdef::VK_KHR_acceleration_structure[] |
| [open,refpage='VkAccelerationStructureCreateFlagBitsKHR',desc='Bitmask specifying additional creation parameters for acceleration structure',type='enums'] |
| -- |
| Bits which can: be set in |
| slink:VkAccelerationStructureCreateInfoKHR::pname:createFlags specifying |
| additional creation parameters for acceleration structures, are: |
| |
| include::{generated}/api/enums/VkAccelerationStructureCreateFlagBitsKHR.txt[] |
| |
| * ename:VK_ACCELERATION_STRUCTURE_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT_KHR |
| specifies that the acceleration structure's address can: be saved and |
| reused on a subsequent run. |
| -- |
| |
| [open,refpage='VkAccelerationStructureCreateFlagsKHR',desc='Bitmask of VkAccelerationStructureCreateFlagBitsKHR',type='flags'] |
| -- |
| include::{generated}/api/flags/VkAccelerationStructureCreateFlagsKHR.txt[] |
| |
| tname:VkAccelerationStructureCreateFlagsKHR is a bitmask type for setting a |
| mask of zero or more elink:VkAccelerationStructureCreateFlagBitsKHR. |
| -- |
| endif::VK_KHR_acceleration_structure[] |
| |
| [open,refpage='VkBuildAccelerationStructureFlagBitsKHR',desc='Bitmask specifying additional parameters for acceleration structure builds',type='enums',alias='VkBuildAccelerationStructureFlagBitsNV'] |
| -- |
| :refpage: VkBuildAccelerationStructureFlagBitsKHR |
| |
| Bits which can: be set in |
| ifdef::VK_KHR_acceleration_structure[] |
| slink:VkAccelerationStructureBuildGeometryInfoKHR::pname:flags |
| endif::VK_KHR_acceleration_structure[] |
| ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] |
| ifdef::VK_NV_ray_tracing[] |
| slink:VkAccelerationStructureInfoNV::pname:flags |
| endif::VK_NV_ray_tracing[] |
| specifying additional parameters for acceleration structure builds, are: |
| |
| include::{generated}/api/enums/VkBuildAccelerationStructureFlagBitsKHR.txt[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkBuildAccelerationStructureFlagBitsNV.txt[] |
| endif::VK_NV_ray_tracing[] |
| |
| * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR indicates |
| that the specified acceleration structure can: be updated with |
| ifdef::VK_KHR_acceleration_structure[] |
| a pname:mode of ename:VK_BUILD_ACCELERATION_STRUCTURE_MODE_UPDATE_KHR in |
| slink:VkAccelerationStructureBuildGeometryInfoKHR |
| endif::VK_KHR_acceleration_structure[] |
| ifdef::VK_KHR_acceleration_structure+VK_NV_ray_tracing[or] |
| ifdef::VK_NV_ray_tracing[] |
| an pname:update of ename:VK_TRUE in |
| flink:vkCmdBuildAccelerationStructureNV |
| endif::VK_NV_ray_tracing[] |
| . |
| * ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR indicates |
| that the specified acceleration structure can: act as the source for a |
| copy acceleration structure command with pname:mode of |
| ename:VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_KHR to produce a |
| compacted acceleration structure. |
| * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR |
| indicates that the given acceleration structure build should: prioritize |
| trace performance over build time. |
| * ename:VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_KHR |
| indicates that the given acceleration structure build should: prioritize |
| build time over trace performance. |
| * ename:VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_KHR indicates that |
| this acceleration structure should: minimize the size of the scratch |
| memory and the final result acceleration structure, potentially at the |
| expense of build time or trace performance. |
| |
| [NOTE] |
| .Note |
| ==== |
| ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_KHR and |
| ename:VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR may: take |
| more time and memory than a normal build, and so should: only be used when |
| those features are needed. |
| ==== |
| -- |
| |
| [open,refpage='VkBuildAccelerationStructureFlagsKHR',desc='Bitmask of VkBuildAccelerationStructureFlagBitsKHR',type='flags',alias='VkBuildAccelerationStructureFlagsNV'] |
| -- |
| :refpage: VkBuildAccelerationStructureFlagsKHR |
| |
| include::{generated}/api/flags/VkBuildAccelerationStructureFlagsKHR.txt[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| or the equivalent |
| |
| include::{generated}/api/flags/VkBuildAccelerationStructureFlagsNV.txt[] |
| endif::VK_NV_ray_tracing[] |
| |
| tname:VkBuildAccelerationStructureFlagsKHR is a bitmask type for setting a |
| mask of zero or more elink:VkBuildAccelerationStructureFlagBitsKHR. |
| -- |
| |
| ifdef::VK_NV_ray_tracing[] |
| [open,refpage='VkGeometryNV',desc='Structure specifying a geometry in a bottom-level acceleration structure',type='structs'] |
| -- |
| :refpage: VkGeometryNV |
| |
| The sname:VkGeometryNV structure describes geometry in a bottom-level |
| acceleration structure and is defined as: |
| |
| include::{generated}/api/structs/VkGeometryNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:geometryType specifies the elink:VkGeometryTypeKHR which this |
| geometry refers to. |
| * pname:geometry contains the geometry data as described in |
| slink:VkGeometryDataNV. |
| * pname:flags has elink:VkGeometryFlagBitsKHR describing options for this |
| geometry. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkGeometryNV-geometryType-03503]] |
| pname:geometryType must: be ename:VK_GEOMETRY_TYPE_TRIANGLES_NV or |
| ename:VK_GEOMETRY_TYPE_AABBS_NV |
| **** |
| |
| include::{generated}/validity/structs/VkGeometryNV.txt[] |
| -- |
| endif::VK_NV_ray_tracing[] |
| |
| [open,refpage='VkGeometryTypeKHR',desc='Enum specifying which type of geometry is provided',type='enums',alias='VkGeometryTypeNV'] |
| -- |
| :refpage: VkGeometryTypeKHR |
| |
| Geometry types are specified by elink:VkGeometryTypeKHR, which takes values: |
| |
| include::{generated}/api/enums/VkGeometryTypeKHR.txt[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkGeometryTypeNV.txt[] |
| endif::VK_NV_ray_tracing[] |
| |
| * ename:VK_GEOMETRY_TYPE_TRIANGLES_KHR specifies a geometry type |
| consisting of triangles. |
| * ename:VK_GEOMETRY_TYPE_AABBS_KHR specifies a geometry type consisting of |
| axis-aligned bounding boxes. |
| ifdef::VK_KHR_acceleration_structure[] |
| * ename:VK_GEOMETRY_TYPE_INSTANCES_KHR specifies a geometry type |
| consisting of acceleration structure instances. |
| endif::VK_KHR_acceleration_structure[] |
| -- |
| |
| [open,refpage='VkGeometryFlagBitsKHR',desc='Bitmask specifying additional parameters for a geometry',type='enums',alias='VkGeometryFlagBitsNV'] |
| -- |
| :refpage: VkGeometryFlagBitsKHR |
| |
| Bits specifying additional parameters for geometries in acceleration |
| structure builds, are: |
| |
| include::{generated}/api/enums/VkGeometryFlagBitsKHR.txt[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkGeometryFlagBitsNV.txt[] |
| endif::VK_NV_ray_tracing[] |
| |
| * ename:VK_GEOMETRY_OPAQUE_BIT_KHR indicates that this geometry does not |
| invoke the any-hit shaders even if present in a hit group. |
| * ename:VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_KHR indicates that |
| the implementation must: only call the any-hit shader a single time for |
| each primitive in this geometry. |
| If this bit is absent an implementation may: invoke the any-hit shader |
| more than once for this geometry. |
| -- |
| |
| [open,refpage='VkGeometryFlagsKHR',desc='Bitmask of VkGeometryFlagBitsKHR',type='flags',alias='VkGeometryFlagsNV'] |
| -- |
| :refpage: VkGeometryFlagsKHR |
| |
| include::{generated}/api/flags/VkGeometryFlagsKHR.txt[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| or the equivalent |
| |
| include::{generated}/api/flags/VkGeometryFlagsNV.txt[] |
| endif::VK_NV_ray_tracing[] |
| |
| tname:VkGeometryFlagsKHR is a bitmask type for setting a mask of zero or |
| more elink:VkGeometryFlagBitsKHR. |
| -- |
| |
| ifdef::VK_NV_ray_tracing[] |
| [open,refpage='VkGeometryDataNV',desc='Structure specifying geometry in a bottom-level acceleration structure',type='structs'] |
| -- |
| :refpage: VkGeometryDataNV |
| |
| The sname:VkGeometryDataNV structure specifes geometry in a bottom-level |
| acceleration structure and is defined as: |
| |
| include::{generated}/api/structs/VkGeometryDataNV.txt[] |
| |
| * pname:triangles contains triangle data if |
| slink:VkGeometryNV::pname:geometryType is |
| ename:VK_GEOMETRY_TYPE_TRIANGLES_NV. |
| * pname:aabbs contains axis-aligned bounding box data if |
| slink:VkGeometryNV::pname:geometryType is |
| ename:VK_GEOMETRY_TYPE_AABBS_NV. |
| |
| include::{generated}/validity/structs/VkGeometryDataNV.txt[] |
| -- |
| |
| [open,refpage='VkGeometryTrianglesNV',desc='Structure specifying a triangle geometry in a bottom-level acceleration structure',type='structs'] |
| -- |
| :refpage: VkGeometryTrianglesNV |
| |
| The sname:VkGeometryTrianglesNV structure specifies triangle geometry in a |
| bottom-level acceleration structure and is defined as: |
| |
| include::{generated}/api/structs/VkGeometryTrianglesNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:vertexData is the buffer containing vertex data for this geometry. |
| * pname:vertexOffset is the offset in bytes within pname:vertexData |
| containing vertex data for this geometry. |
| * pname:vertexCount is the number of valid vertices. |
| * pname:vertexStride is the stride in bytes between each vertex. |
| * pname:vertexFormat is a elink:VkFormat describing the format of each |
| vertex element. |
| * pname:indexData is the buffer containing index data for this geometry. |
| * pname:indexOffset is the offset in bytes within pname:indexData |
| containing index data for this geometry. |
| * pname:indexCount is the number of indices to include in this geometry. |
| * pname:indexType is a elink:VkIndexType describing the format of each |
| index. |
| * pname:transformData is an optional buffer containing an |
| slink:VkTransformMatrixNV structure defining a transformation to be |
| applied to this geometry. |
| * pname:transformOffset is the offset in bytes in pname:transformData of |
| the transform information described above. |
| |
| If pname:indexType is ename:VK_INDEX_TYPE_NONE_NV, then this structure |
| describes a set of triangles determined by pname:vertexCount. |
| Otherwise, this structure describes a set of indexed triangles determined by |
| pname:indexCount. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkGeometryTrianglesNV-vertexOffset-02428]] |
| pname:vertexOffset must: be less than the size of pname:vertexData |
| * [[VUID-VkGeometryTrianglesNV-vertexOffset-02429]] |
| pname:vertexOffset must: be a multiple of the component size of |
| pname:vertexFormat |
| * [[VUID-VkGeometryTrianglesNV-vertexFormat-02430]] |
| pname:vertexFormat must: be one of ename:VK_FORMAT_R32G32B32_SFLOAT, |
| ename:VK_FORMAT_R32G32_SFLOAT, ename:VK_FORMAT_R16G16B16_SFLOAT, |
| ename:VK_FORMAT_R16G16_SFLOAT, ename:VK_FORMAT_R16G16_SNORM, or |
| ename:VK_FORMAT_R16G16B16_SNORM |
| * [[VUID-VkGeometryTrianglesNV-vertexStride-03818]] |
| pname:vertexStride must: be less than or equal to [eq]#2^32^-1# |
| * [[VUID-VkGeometryTrianglesNV-indexOffset-02431]] |
| pname:indexOffset must: be less than the size of pname:indexData |
| * [[VUID-VkGeometryTrianglesNV-indexOffset-02432]] |
| pname:indexOffset must: be a multiple of the element size of |
| pname:indexType |
| * [[VUID-VkGeometryTrianglesNV-indexType-02433]] |
| pname:indexType must: be ename:VK_INDEX_TYPE_UINT16, |
| ename:VK_INDEX_TYPE_UINT32, or ename:VK_INDEX_TYPE_NONE_NV |
| * [[VUID-VkGeometryTrianglesNV-indexData-02434]] |
| pname:indexData must: be dlink:VK_NULL_HANDLE if pname:indexType is |
| ename:VK_INDEX_TYPE_NONE_NV |
| * [[VUID-VkGeometryTrianglesNV-indexData-02435]] |
| pname:indexData must: be a valid sname:VkBuffer handle if |
| pname:indexType is not ename:VK_INDEX_TYPE_NONE_NV |
| * [[VUID-VkGeometryTrianglesNV-indexCount-02436]] |
| pname:indexCount must: be `0` if pname:indexType is |
| ename:VK_INDEX_TYPE_NONE_NV |
| * [[VUID-VkGeometryTrianglesNV-transformOffset-02437]] |
| pname:transformOffset must: be less than the size of pname:transformData |
| * [[VUID-VkGeometryTrianglesNV-transformOffset-02438]] |
| pname:transformOffset must: be a multiple of `16` |
| **** |
| |
| include::{generated}/validity/structs/VkGeometryTrianglesNV.txt[] |
| -- |
| |
| [open,refpage='VkGeometryAABBNV',desc='Structure specifying axis-aligned bounding box geometry in a bottom-level acceleration structure',type='structs'] |
| -- |
| :refpage: VkGeometryAABBNV |
| |
| The sname:VkGeometryAABBNV structure specifies axis-aligned bounding box |
| geometry in a bottom-level acceleration structure, and is defined as: |
| |
| include::{generated}/api/structs/VkGeometryAABBNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:aabbData is the buffer containing axis-aligned bounding box data. |
| * pname:numAABBs is the number of AABBs in this geometry. |
| * pname:stride is the stride in bytes between AABBs in pname:aabbData. |
| * pname:offset is the offset in bytes of the first AABB in pname:aabbData. |
| |
| The AABB data in memory is six 32-bit floats consisting of the minimum x, y, |
| and z values followed by the maximum x, y, and z values. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkGeometryAABBNV-offset-02439]] |
| pname:offset must: be less than the size of pname:aabbData |
| * [[VUID-VkGeometryAABBNV-offset-02440]] |
| pname:offset must: be a multiple of `8` |
| * [[VUID-VkGeometryAABBNV-stride-02441]] |
| pname:stride must: be a multiple of `8` |
| **** |
| |
| include::{generated}/validity/structs/VkGeometryAABBNV.txt[] |
| -- |
| endif::VK_NV_ray_tracing[] |
| |
| [open,refpage='vkDestroyAccelerationStructureKHR',desc='Destroy an acceleration structure object',type='protos'] |
| -- |
| :refpage: vkDestroyAccelerationStructureKHR |
| |
| To destroy an acceleration structure, call: |
| |
| ifdef::VK_KHR_acceleration_structure[] |
| include::{generated}/api/protos/vkDestroyAccelerationStructureKHR.txt[] |
| endif::VK_KHR_acceleration_structure[] |
| |
| * pname:device is the logical device that destroys the acceleration |
| structure. |
| * pname:accelerationStructure is the acceleration structure to destroy. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02442]] |
| All submitted commands that refer to pname:accelerationStructure must: |
| have completed execution |
| * [[VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02443]] |
| If sname:VkAllocationCallbacks were provided when |
| pname:accelerationStructure was created, a compatible set of callbacks |
| must: be provided here |
| * [[VUID-vkDestroyAccelerationStructureKHR-accelerationStructure-02444]] |
| If no sname:VkAllocationCallbacks were provided when |
| pname:accelerationStructure was created, pname:pAllocator must: be |
| `NULL` |
| **** |
| |
| include::{generated}/validity/protos/vkDestroyAccelerationStructureKHR.txt[] |
| -- |
| |
| ifdef::VK_NV_ray_tracing[] |
| [open,refpage='vkDestroyAccelerationStructureNV',desc='Destroy an acceleration structure object',type='protos'] |
| -- |
| :refpage: vkDestroyAccelerationStructureNV |
| |
| To destroy an acceleration structure, call: |
| |
| include::{generated}/api/protos/vkDestroyAccelerationStructureNV.txt[] |
| |
| * pname:device is the logical device that destroys the buffer. |
| * pname:accelerationStructure is the acceleration structure to destroy. |
| * pname:pAllocator controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03752]] |
| All submitted commands that refer to pname:accelerationStructure must: |
| have completed execution |
| * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03753]] |
| If sname:VkAllocationCallbacks were provided when |
| pname:accelerationStructure was created, a compatible set of callbacks |
| must: be provided here |
| * [[VUID-vkDestroyAccelerationStructureNV-accelerationStructure-03754]] |
| If no sname:VkAllocationCallbacks were provided when |
| pname:accelerationStructure was created, pname:pAllocator must: be |
| `NULL` |
| **** |
| |
| include::{generated}/validity/protos/vkDestroyAccelerationStructureNV.txt[] |
| -- |
| |
| [open,refpage='vkGetAccelerationStructureMemoryRequirementsNV',desc='Get acceleration structure memory requirements',type='protos'] |
| -- |
| :refpage: vkGetAccelerationStructureMemoryRequirementsNV |
| |
| An acceleration structure has memory requirements for the structure object |
| itself, scratch space for the build, and scratch space for the update. |
| |
| Scratch space is allocated as a sname:VkBuffer, so for |
| ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV |
| and |
| ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV |
| the pname:pMemoryRequirements->alignment and |
| pname:pMemoryRequirements->memoryTypeBits values returned by this call must: |
| be filled with zero, and should: be ignored by the application. |
| |
| To query the memory requirements, call: |
| |
| include::{generated}/api/protos/vkGetAccelerationStructureMemoryRequirementsNV.txt[] |
| |
| * pname:device is the logical device on which the acceleration structure |
| was created. |
| * pname:pInfo is a pointer to a |
| slink:VkAccelerationStructureMemoryRequirementsInfoNV structure |
| specifying the acceleration structure to get memory requirements for. |
| * pname:pMemoryRequirements is a pointer to a |
| slink:VkMemoryRequirements2KHR structure in which the requested |
| acceleration structure memory requirements are returned. |
| |
| include::{generated}/validity/protos/vkGetAccelerationStructureMemoryRequirementsNV.txt[] |
| -- |
| |
| [open,refpage='VkAccelerationStructureMemoryRequirementsInfoNV',desc='Structure specifying acceleration to query for memory requirements',type='structs'] |
| -- |
| :refpage: VkAccelerationStructureMemoryRequirementsInfoNV |
| |
| The sname:VkAccelerationStructureMemoryRequirementsInfoNV structure is |
| defined as: |
| |
| include::{generated}/api/structs/VkAccelerationStructureMemoryRequirementsInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:type selects the type of memory requirement being queried. |
| ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV |
| returns the memory requirements for the object itself. |
| ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV |
| returns the memory requirements for the scratch memory when doing a |
| build. |
| ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV |
| returns the memory requirements for the scratch memory when doing an |
| update. |
| * pname:accelerationStructure is the acceleration structure to be queried |
| for memory requirements. |
| |
| include::{generated}/validity/structs/VkAccelerationStructureMemoryRequirementsInfoNV.txt[] |
| -- |
| |
| [open,refpage='VkAccelerationStructureMemoryRequirementsTypeNV',desc='Acceleration structure memory requirement type',type='enums'] |
| -- |
| :refpage: VkAccelerationStructureMemoryRequirementsTypeNV |
| |
| Possible values of pname:type in |
| sname:VkAccelerationStructureMemoryRequirementsInfoNV are:, |
| |
| include::{generated}/api/enums/VkAccelerationStructureMemoryRequirementsTypeNV.txt[] |
| |
| * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV |
| requests the memory requirement for the sname:VkAccelerationStructureNV |
| backing store. |
| * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_NV |
| requests the memory requirement for scratch space during the initial |
| build. |
| * ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_NV |
| requests the memory requirement for scratch space during an update. |
| -- |
| endif::VK_NV_ray_tracing[] |
| |
| ifdef::VK_KHR_acceleration_structure[] |
| [open,refpage='VkAccelerationStructureBuildTypeKHR',desc='Acceleration structure build type',type='enums'] |
| -- |
| :refpage: VkAccelerationStructureBuildTypeKHR |
| |
| Possible values of pname:buildType in |
| flink:vkGetAccelerationStructureBuildSizesKHR are: |
| |
| include::{generated}/api/enums/VkAccelerationStructureBuildTypeKHR.txt[] |
| |
| * ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR requests the memory |
| requirement for operations performed by the host. |
| * ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR requests the |
| memory requirement for operations performed by the device. |
| * ename:VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR requests |
| the memory requirement for operations performed by either the host, or |
| the device. |
| -- |
| endif::VK_KHR_acceleration_structure[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| [open,refpage='vkBindAccelerationStructureMemoryNV',desc='Bind acceleration structure memory',type='protos'] |
| -- |
| :refpage: vkBindAccelerationStructureMemoryNV |
| |
| To attach memory to one or more acceleration structures at a time, call: |
| |
| include::{generated}/api/protos/vkBindAccelerationStructureMemoryNV.txt[] |
| |
| * pname:device is the logical device that owns the acceleration structures |
| and memory. |
| * pname:bindInfoCount is the number of elements in pname:pBindInfos. |
| * pname:pBindInfos is a pointer to an array of |
| slink:VkBindAccelerationStructureMemoryInfoNV structures describing |
| acceleration structures and memory to bind. |
| |
| include::{generated}/validity/protos/vkBindAccelerationStructureMemoryNV.txt[] |
| -- |
| |
| [open,refpage='VkBindAccelerationStructureMemoryInfoNV',desc='Structure specifying acceleration structure memory binding',type='structs'] |
| -- |
| :refpage: VkBindAccelerationStructureMemoryInfoNV |
| |
| The sname:VkBindAccelerationStructureMemoryInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkBindAccelerationStructureMemoryInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:accelerationStructure is the acceleration structure to be attached |
| to memory. |
| * pname:memory is a sname:VkDeviceMemory object describing the device |
| memory to attach. |
| * pname:memoryOffset is the start offset of the region of memory that is |
| to be bound to the acceleration structure. |
| The number of bytes returned in the |
| slink:VkMemoryRequirements::pname:size member in pname:memory, starting |
| from pname:memoryOffset bytes, will be bound to the specified |
| acceleration structure. |
| * pname:deviceIndexCount is the number of elements in |
| pname:pDeviceIndices. |
| * pname:pDeviceIndices is a pointer to an array of device indices. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBindAccelerationStructureMemoryInfoNV-accelerationStructure-03620]] |
| pname:accelerationStructure must: not already be backed by a memory |
| object |
| * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-03621]] |
| pname:memoryOffset must: be less than the size of pname:memory |
| * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memory-03622]] |
| pname:memory must: have been allocated using one of the memory types |
| allowed in the pname:memoryTypeBits member of the |
| slink:VkMemoryRequirements structure returned from a call to |
| flink:vkGetAccelerationStructureMemoryRequirementsNV with |
| pname:accelerationStructure and pname:type of |
| ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV |
| * [[VUID-VkBindAccelerationStructureMemoryInfoNV-memoryOffset-03623]] |
| pname:memoryOffset must: be an integer multiple of the pname:alignment |
| member of the slink:VkMemoryRequirements structure returned from a call |
| to flink:vkGetAccelerationStructureMemoryRequirementsNV with |
| pname:accelerationStructure and pname:type of |
| ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV |
| * [[VUID-VkBindAccelerationStructureMemoryInfoNV-size-03624]] |
| The pname:size member of the sname:VkMemoryRequirements structure |
| returned from a call to |
| flink:vkGetAccelerationStructureMemoryRequirementsNV with |
| pname:accelerationStructure and pname:type of |
| ename:VK_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_NV must: |
| be less than or equal to the size of pname:memory minus |
| pname:memoryOffset |
| **** |
| |
| include::{generated}/validity/structs/VkBindAccelerationStructureMemoryInfoNV.txt[] |
| -- |
| |
| [open,refpage='vkGetAccelerationStructureHandleNV',desc='Get opaque acceleration structure handle',type='protos'] |
| -- |
| :refpage: vkGetAccelerationStructureHandleNV |
| |
| To allow constructing geometry instances with device code if desired, we |
| need to be able to query a opaque handle for an acceleration structure. |
| This handle is a value of 8 bytes. |
| To get this handle, call: |
| |
| include::{generated}/api/protos/vkGetAccelerationStructureHandleNV.txt[] |
| |
| * pname:device is the logical device that owns the acceleration |
| structures. |
| * pname:accelerationStructure is the acceleration structure. |
| * pname:dataSize is the size in bytes of the buffer pointed to by |
| pname:pData. |
| * pname:pData is a pointer to a user-allocated buffer where the results |
| will be written. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetAccelerationStructureHandleNV-dataSize-02240]] |
| pname:dataSize must: be large enough to contain the result of the query, |
| as described above |
| * [[VUID-vkGetAccelerationStructureHandleNV-accelerationStructure-02787]] |
| pname:accelerationStructure must: be bound completely and contiguously |
| to a single sname:VkDeviceMemory object via |
| flink:vkBindAccelerationStructureMemoryNV |
| **** |
| |
| include::{generated}/validity/protos/vkGetAccelerationStructureHandleNV.txt[] |
| -- |
| endif::VK_NV_ray_tracing[] |
| |
| ifdef::VK_KHR_acceleration_structure[] |
| [open,refpage='vkGetAccelerationStructureDeviceAddressKHR',desc='Query an address of a acceleration structure',type='protos'] |
| -- |
| :refpage: vkGetAccelerationStructureDeviceAddressKHR |
| |
| To query the 64-bit device address for an acceleration structure, call: |
| |
| include::{generated}/api/protos/vkGetAccelerationStructureDeviceAddressKHR.txt[] |
| |
| * pname:device is the logical device that the acceleration structure was |
| created on. |
| * pname:pInfo is a pointer to a |
| slink:VkAccelerationStructureDeviceAddressInfoKHR structure specifying |
| the acceleration structure to retrieve an address for. |
| |
| The 64-bit return value is an address of the acceleration structure, which |
| can be used for device and shader operations that involve acceleration |
| structures, such as |
| ifdef::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] |
| ray traversal and |
| endif::VK_KHR_ray_tracing_pipeline,VK_KHR_ray_query[] |
| acceleration structure building. |
| |
| If the acceleration structure was created with a non-zero value of |
| slink:VkAccelerationStructureCreateInfoKHR::pname:deviceAddress, the return |
| value will be the same address. |
| |
| If the acceleration structure was created with a pname:type of |
| ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR, the returned address must: |
| be consistent with the relative offset to other acceleration structures with |
| pname:type ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR allocated with |
| the same slink:VkBuffer. |
| That is, the difference in returned addresses between the two must: be the |
| same as the difference in offsets provided at acceleration structure |
| creation. |
| |
| [NOTE] |
| .Note |
| ==== |
| The acceleration structure device address may: be different from the buffer |
| device address corresponding to the acceleration structure's start offset in |
| its storage buffer for acceleration structure types other than |
| ename:VK_ACCELERATION_STRUCTURE_TYPE_GENERIC_KHR. |
| ==== |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetAccelerationStructureDeviceAddressKHR-device-03504]] |
| If pname:device was created with multiple physical devices, then the |
| <<features-bufferDeviceAddressMultiDevice,bufferDeviceAddressMultiDevice>> |
| feature must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkGetAccelerationStructureDeviceAddressKHR.txt[] |
| -- |
| |
| [open,refpage='VkAccelerationStructureDeviceAddressInfoKHR',desc='Structure specifying the acceleration structure to query an address for',type='structs'] |
| -- |
| :refpage: VkAccelerationStructureDeviceAddressInfoKHR |
| |
| The sname:VkAccelerationStructureDeviceAddressInfoKHR structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkAccelerationStructureDeviceAddressInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:accelerationStructure specifies the acceleration structure whose |
| address is being queried. |
| |
| include::{generated}/validity/structs/VkAccelerationStructureDeviceAddressInfoKHR.txt[] |
| -- |
| endif::VK_KHR_acceleration_structure[] |
| endif::VK_NV_ray_tracing,VK_KHR_acceleration_structure[] |
| |
| |
| [[resources-association]] |
| == Resource Memory Association |
| |
| Resources are initially created as _virtual allocations_ with no backing |
| memory. |
| Device memory is allocated separately (see <<memory-device>>) and then |
| associated with the resource. |
| This association is done differently for sparse and non-sparse resources. |
| |
| Resources created with any of the sparse creation flags are considered |
| sparse resources. |
| Resources created without these flags are non-sparse. |
| The details on resource memory association for sparse resources is described |
| in <<sparsememory>>. |
| |
| Non-sparse resources must: be bound completely and contiguously to a single |
| sname:VkDeviceMemory object before the resource is passed as a parameter to |
| any of the following operations: |
| |
| * creating image or buffer views |
| * updating descriptor sets |
| * recording commands in a command buffer |
| |
| Once bound, the memory binding is immutable for the lifetime of the |
| resource. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| |
| In a logical device representing more than one physical device, buffer and |
| image resources exist on all physical devices but can: be bound to memory |
| differently on each. |
| Each such replicated resource is an _instance_ of the resource. |
| For sparse resources, each instance can: be bound to memory arbitrarily |
| differently. |
| For non-sparse resources, each instance can: either be bound to the local or |
| a peer instance of the memory, or for images can: be bound to rectangular |
| regions from the local and/or peer instances. |
| When a resource is used in a descriptor set, each physical device interprets |
| the descriptor according to its own instance's binding to memory. |
| |
| [NOTE] |
| .Note |
| ==== |
| There are no new copy commands to transfer data between physical devices. |
| Instead, an application can: create a resource with a peer mapping and use |
| it as the source or destination of a transfer command executed by a single |
| physical device to copy the data from one physical device to another. |
| ==== |
| |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| |
| [open,refpage='vkGetBufferMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos'] |
| -- |
| To determine the memory requirements for a buffer resource, call: |
| |
| include::{generated}/api/protos/vkGetBufferMemoryRequirements.txt[] |
| |
| * pname:device is the logical device that owns the buffer. |
| * pname:buffer is the buffer to query. |
| * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements |
| structure in which the memory requirements of the buffer object are |
| returned. |
| |
| include::{generated}/validity/protos/vkGetBufferMemoryRequirements.txt[] |
| -- |
| |
| [open,refpage='vkGetImageMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos'] |
| -- |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| To determine the memory requirements for an image resource, call: |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| To determine the memory requirements for an image resource which is not |
| created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT flag set, call: |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| include::{generated}/api/protos/vkGetImageMemoryRequirements.txt[] |
| |
| * pname:device is the logical device that owns the image. |
| * pname:image is the image to query. |
| * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements |
| structure in which the memory requirements of the image object are |
| returned. |
| |
| .Valid Usage |
| **** |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkGetImageMemoryRequirements-image-01588]] |
| pname:image must: not have been created with the |
| ename:VK_IMAGE_CREATE_DISJOINT_BIT flag set |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-vkGetImageMemoryRequirements-image-04004]] |
| If pname:image was created with the |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID |
| external memory handle type, then pname:image must: be bound to memory |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| **** |
| |
| include::{generated}/validity/protos/vkGetImageMemoryRequirements.txt[] |
| -- |
| |
| [open,refpage='VkMemoryRequirements',desc='Structure specifying memory requirements',type='structs'] |
| -- |
| The sname:VkMemoryRequirements structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryRequirements.txt[] |
| |
| * pname:size is the size, in bytes, of the memory allocation required: for |
| the resource. |
| * pname:alignment is the alignment, in bytes, of the offset within the |
| allocation required: for the resource. |
| * pname:memoryTypeBits is a bitmask and contains one bit set for every |
| supported memory type for the resource. |
| Bit `i` is set if and only if the memory type `i` in the |
| sname:VkPhysicalDeviceMemoryProperties structure for the physical device |
| is supported for the resource. |
| |
| include::{generated}/validity/structs/VkMemoryRequirements.txt[] |
| -- |
| |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| The precise size of images that will be bound to external Android hardware |
| buffer memory is unknown until the memory has been imported or allocated, so |
| applications must: not call flink:vkGetImageMemoryRequirements or |
| flink:vkGetImageMemoryRequirements2 with such an slink:VkImage before it has |
| been bound to memory. |
| ifdef::VK_KHR_maintenance4[] |
| For this reason, applications also must: not call |
| flink:vkGetDeviceImageMemoryRequirementsKHR with a slink:VkImageCreateInfo |
| describing an external Android hardware buffer. |
| endif::VK_KHR_maintenance4[] |
| When importing Android hardware buffer memory, the pname:allocationSize can: |
| be determined by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID. |
| When allocating new memory for a slink:VkImage that can: be exported to an |
| Android hardware buffer, the memory's pname:allocationSize must: be zero; |
| the actual size will be determined by the dedicated image's parameters. |
| After the memory has been allocated, the amount of space allocated from the |
| memory's heap can: be obtained by getting the image's memory requirements or |
| by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID with the |
| Android hardware buffer exported from the memory. |
| |
| When allocating new memory for a slink:VkBuffer that can: be exported to an |
| Android hardware buffer an application may: still call |
| flink:vkGetBufferMemoryRequirements or flink:vkGetBufferMemoryRequirements2 |
| with slink:VkBuffer before it has been bound to memory. |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| |
| ifdef::VK_KHR_external_memory_win32[] |
| If the resource being queried was created with the |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_BIT, |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D11_TEXTURE_KMT_BIT, or |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_D3D12_RESOURCE_BIT external memory |
| handle type, the value of pname:size has no meaning and should: be ignored. |
| endif::VK_KHR_external_memory_win32[] |
| |
| The implementation guarantees certain properties about the memory |
| requirements returned by |
| ifdef::VK_KHR_get_memory_requirements2[] |
| flink:vkGetBufferMemoryRequirements2, flink:vkGetImageMemoryRequirements2, |
| endif::VK_KHR_get_memory_requirements2[] |
| ifdef::VK_KHR_maintenance4[] |
| flink:vkGetDeviceBufferMemoryRequirementsKHR, |
| flink:vkGetDeviceImageMemoryRequirementsKHR, |
| endif::VK_KHR_maintenance4[] |
| flink:vkGetBufferMemoryRequirements and flink:vkGetImageMemoryRequirements: |
| |
| * The pname:memoryTypeBits member always contains at least one bit set. |
| * If pname:buffer is a sname:VkBuffer not created with the |
| ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT bit set, or if pname:image is |
| <<glossary-linear-resource,linear>> image, then the pname:memoryTypeBits |
| member always contains at least one bit set corresponding to a |
| sname:VkMemoryType with a pname:propertyFlags that has both the |
| ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit and the |
| ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit set. |
| In other words, mappable coherent memory can: always be attached to |
| these objects. |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| * If pname:buffer was created with |
| slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes set to `0` or |
| pname:image was created with |
| slink:VkExternalMemoryImageCreateInfo::pname:handleTypes set to `0`, the |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| * The |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| pname:memoryTypeBits member always contains at least one bit set |
| corresponding to a sname:VkMemoryType with a pname:propertyFlags that |
| has the ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set. |
| * The pname:memoryTypeBits member is identical for all sname:VkBuffer |
| objects created with the same value for the pname:flags and pname:usage |
| members in the slink:VkBufferCreateInfo structure |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| and the pname:handleTypes member of the |
| slink:VkExternalMemoryBufferCreateInfo structure |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| passed to flink:vkCreateBuffer. |
| Further, if code:usage1 and code:usage2 of type tlink:VkBufferUsageFlags |
| are such that the bits set in code:usage2 are a subset of the bits set |
| in code:usage1, and they have the same |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| pname:flags and |
| slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes, |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| pname:flags, |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| then the bits set in pname:memoryTypeBits returned for code:usage1 must: |
| be a subset of the bits set in pname:memoryTypeBits returned for |
| code:usage2, for all values of pname:flags. |
| * The pname:alignment member is a power of two. |
| * The pname:alignment member is identical for all sname:VkBuffer objects |
| created with the same combination of values for the pname:usage and |
| pname:flags members in the slink:VkBufferCreateInfo structure passed to |
| flink:vkCreateBuffer. |
| ifdef::VK_KHR_maintenance4[] |
| * If the <<features-maintenance4, pname:maintenance4>> feature is enabled, |
| then the pname:alignment member is identical for all sname:VkImage |
| objects created with the same combination of values for the pname:flags, |
| pname:imageType, pname:format, pname:extent, pname:mipLevels, |
| pname:arrayLayers, pname:samples, pname:tiling and pname:usage members |
| in the slink:VkImageCreateInfo structure passed to flink:vkCreateImage. |
| endif::VK_KHR_maintenance4[] |
| * The pname:alignment member satisfies the buffer descriptor offset |
| alignment requirements associated with the sname:VkBuffer's pname:usage: |
| ** If pname:usage included ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT |
| or ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:alignment |
| must: be an integer multiple of |
| sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment. |
| ** If pname:usage included ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT, |
| pname:alignment must: be an integer multiple of |
| sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment. |
| ** If pname:usage included ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, |
| pname:alignment must: be an integer multiple of |
| sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment. |
| * For images created with a color format, the pname:memoryTypeBits member |
| is identical for all sname:VkImage objects created with the same |
| combination of values for the pname:tiling member, the |
| ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the pname:flags member, |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| the ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit of the |
| pname:flags member, |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| pname:handleTypes member of slink:VkExternalMemoryImageCreateInfo, |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage |
| member in the slink:VkImageCreateInfo structure passed to |
| flink:vkCreateImage. |
| * For images created with a depth/stencil format, the pname:memoryTypeBits |
| member is identical for all sname:VkImage objects created with the same |
| combination of values for the pname:format member, the pname:tiling |
| member, the ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the |
| pname:flags member, |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| the ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit of the |
| pname:flags member, |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| pname:handleTypes member of slink:VkExternalMemoryImageCreateInfo, |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage |
| member in the slink:VkImageCreateInfo structure passed to |
| flink:vkCreateImage. |
| * If the memory requirements are for a sname:VkImage, the |
| pname:memoryTypeBits member must: not refer to a sname:VkMemoryType with |
| a pname:propertyFlags that has the |
| ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set if the pname:image |
| did not have ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT bit set in |
| the pname:usage member of the slink:VkImageCreateInfo structure passed |
| to flink:vkCreateImage. |
| * If the memory requirements are for a sname:VkBuffer, the |
| pname:memoryTypeBits member must: not refer to a sname:VkMemoryType with |
| a pname:propertyFlags that has the |
| ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT bit set. |
| + |
| [NOTE] |
| .Note |
| ==== |
| The implication of this requirement is that lazily allocated memory is |
| disallowed for buffers in all cases. |
| ==== |
| * The pname:size member is identical for all sname:VkBuffer objects |
| created with the same combination of creation parameters specified in |
| slink:VkBufferCreateInfo and its pname:pNext chain. |
| * The pname:size member is identical for all sname:VkImage objects created |
| with the same combination of creation parameters specified in |
| slink:VkImageCreateInfo and its pname:pNext chain. |
| + |
| [NOTE] |
| .Note |
| ==== |
| This, however, does not imply that they interpret the contents of the bound |
| memory identically with each other. |
| ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| That additional guarantee, however, can: be explicitly requested using |
| ename:VK_IMAGE_CREATE_ALIAS_BIT. |
| endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| ==== |
| ifdef::VK_KHR_maintenance4[] |
| * If the <<features-maintenance4, pname:maintenance4>> feature is enabled, |
| these additional guarantees apply: |
| ** For a sname:VkBuffer, the pname:size memory requirement is never |
| greater than that of another sname:VkBuffer created with a greater or |
| equal pname:size specified in slink:VkBufferCreateInfo, all other |
| creation parameters being identical. |
| ** For a slink:VkImage, the pname:size memory requirement is never greater |
| than that of another slink:VkImage created with a greater or equal |
| value in each of pname:extent.width, pname:extent.height, and |
| pname:extent.depth; all other creation parameters being identical. |
| ** The memory requirements returned by |
| flink:vkGetDeviceBufferMemoryRequirementsKHR are identical to those |
| that would be returned by flink:vkGetBufferMemoryRequirements2 if it |
| were called with a sname:VkBuffer created with the same |
| slink:VkBufferCreateInfo values. |
| ** The memory requirements returned by |
| flink:vkGetDeviceImageMemoryRequirementsKHR are identical to those that |
| would be returned by flink:vkGetImageMemoryRequirements2 if it were |
| called with a sname:VkImage created with the same |
| slink:VkImageCreateInfo values. |
| endif::VK_KHR_maintenance4[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[] |
| [open,refpage='vkGetBufferMemoryRequirements2',desc='Returns the memory requirements for specified Vulkan object',type='protos'] |
| -- |
| To determine the memory requirements for a buffer resource, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkGetBufferMemoryRequirements2.txt[] |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1+VK_KHR_get_memory_requirements2[or the equivalent command] |
| |
| ifdef::VK_KHR_get_memory_requirements2[] |
| include::{generated}/api/protos/vkGetBufferMemoryRequirements2KHR.txt[] |
| endif::VK_KHR_get_memory_requirements2[] |
| |
| * pname:device is the logical device that owns the buffer. |
| * pname:pInfo is a pointer to a slink:VkBufferMemoryRequirementsInfo2 |
| structure containing parameters required for the memory requirements |
| query. |
| * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 |
| structure in which the memory requirements of the buffer object are |
| returned. |
| |
| include::{generated}/validity/protos/vkGetBufferMemoryRequirements2.txt[] |
| -- |
| |
| ifdef::VK_KHR_maintenance4[] |
| [open,refpage='vkGetDeviceBufferMemoryRequirementsKHR',desc='Returns the memory requirements for specified Vulkan object',type='protos'] |
| -- |
| To determine the memory requirements for a buffer resource without creating |
| an object, call: |
| |
| include::{generated}/api/protos/vkGetDeviceBufferMemoryRequirementsKHR.txt[] |
| |
| * pname:device is the logical device intended to own the buffer. |
| * pname:pInfo is a pointer to a slink:VkDeviceBufferMemoryRequirementsKHR |
| structure containing parameters required for the memory requirements |
| query. |
| * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 |
| structure in which the memory requirements of the buffer object are |
| returned. |
| |
| include::{generated}/validity/protos/vkGetDeviceBufferMemoryRequirementsKHR.txt[] |
| -- |
| endif::VK_KHR_maintenance4[] |
| |
| [open,refpage='VkBufferMemoryRequirementsInfo2',desc='(None)',type='structs'] |
| -- |
| The sname:VkBufferMemoryRequirementsInfo2 structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferMemoryRequirementsInfo2.txt[] |
| |
| ifdef::VK_KHR_get_memory_requirements2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkBufferMemoryRequirementsInfo2KHR.txt[] |
| endif::VK_KHR_get_memory_requirements2[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:buffer is the buffer to query. |
| |
| include::{generated}/validity/structs/VkBufferMemoryRequirementsInfo2.txt[] |
| -- |
| |
| ifdef::VK_KHR_maintenance4[] |
| [open,refpage='VkDeviceBufferMemoryRequirementsKHR',desc='(None)',type='structs'] |
| -- |
| The sname:VkDeviceBufferMemoryRequirementsKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceBufferMemoryRequirementsKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:pCreateInfo is a pointer to a slink:VkBufferCreateInfo structure |
| containing parameters affecting creation of the buffer to query. |
| |
| include::{generated}/validity/structs/VkDeviceBufferMemoryRequirementsKHR.txt[] |
| -- |
| endif::VK_KHR_maintenance4[] |
| |
| [open,refpage='vkGetImageMemoryRequirements2',desc='Returns the memory requirements for specified Vulkan object',type='protos'] |
| -- |
| To determine the memory requirements for an image resource, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkGetImageMemoryRequirements2.txt[] |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1+VK_KHR_get_memory_requirements2[or the equivalent command] |
| |
| ifdef::VK_KHR_get_memory_requirements2[] |
| include::{generated}/api/protos/vkGetImageMemoryRequirements2KHR.txt[] |
| endif::VK_KHR_get_memory_requirements2[] |
| |
| * pname:device is the logical device that owns the image. |
| * pname:pInfo is a pointer to a slink:VkImageMemoryRequirementsInfo2 |
| structure containing parameters required for the memory requirements |
| query. |
| * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 |
| structure in which the memory requirements of the image object are |
| returned. |
| |
| include::{generated}/validity/protos/vkGetImageMemoryRequirements2.txt[] |
| -- |
| |
| ifdef::VK_KHR_maintenance4[] |
| [open,refpage='vkGetDeviceImageMemoryRequirementsKHR',desc='Returns the memory requirements for specified Vulkan object',type='protos'] |
| -- |
| To determine the memory requirements for an image resource without creating |
| an object, call: |
| |
| include::{generated}/api/protos/vkGetDeviceImageMemoryRequirementsKHR.txt[] |
| |
| * pname:device is the logical device intended to own the image. |
| * pname:pInfo is a pointer to a slink:VkDeviceImageMemoryRequirementsKHR |
| structure containing parameters required for the memory requirements |
| query. |
| * pname:pMemoryRequirements is a pointer to a slink:VkMemoryRequirements2 |
| structure in which the memory requirements of the image object are |
| returned. |
| |
| include::{generated}/validity/protos/vkGetDeviceImageMemoryRequirementsKHR.txt[] |
| -- |
| endif::VK_KHR_maintenance4[] |
| |
| [open,refpage='VkImageMemoryRequirementsInfo2',desc='(None)',type='structs'] |
| -- |
| The sname:VkImageMemoryRequirementsInfo2 structure is defined as: |
| |
| include::{generated}/api/structs/VkImageMemoryRequirementsInfo2.txt[] |
| |
| ifdef::VK_KHR_get_memory_requirements2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkImageMemoryRequirementsInfo2KHR.txt[] |
| endif::VK_KHR_get_memory_requirements2[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:image is the image to query. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageMemoryRequirementsInfo2-image-01589]] |
| If pname:image was created with a _multi-planar_ format and the |
| ename:VK_IMAGE_CREATE_DISJOINT_BIT flag, there must: be a |
| slink:VkImagePlaneMemoryRequirementsInfo included in the pname:pNext |
| chain of the slink:VkImageMemoryRequirementsInfo2 structure |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkImageMemoryRequirementsInfo2-image-02279]] |
| If pname:image was created with ename:VK_IMAGE_CREATE_DISJOINT_BIT and |
| with ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then there must: be |
| a slink:VkImagePlaneMemoryRequirementsInfo included in the pname:pNext |
| chain of the slink:VkImageMemoryRequirementsInfo2 structure |
| endif::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkImageMemoryRequirementsInfo2-image-01590]] |
| If pname:image was not created with the |
| ename:VK_IMAGE_CREATE_DISJOINT_BIT flag, there must: not be a |
| slink:VkImagePlaneMemoryRequirementsInfo included in the pname:pNext |
| chain of the slink:VkImageMemoryRequirementsInfo2 structure |
| ifndef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkImageMemoryRequirementsInfo2-image-01591]] |
| If pname:image was created with a single-plane format, there must: not |
| be a slink:VkImagePlaneMemoryRequirementsInfo included in the |
| pname:pNext chain of the slink:VkImageMemoryRequirementsInfo2 structure |
| endif::VK_EXT_image_drm_format_modifier[] |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkImageMemoryRequirementsInfo2-image-02280]] |
| If pname:image was created with a single-plane format and with any |
| pname:tiling other than ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, |
| then there must: not be a slink:VkImagePlaneMemoryRequirementsInfo |
| included in the pname:pNext chain of the |
| slink:VkImageMemoryRequirementsInfo2 structure |
| endif::VK_EXT_image_drm_format_modifier[] |
| ifdef::VK_ANDROID_external_memory_android_hardware_buffer[] |
| * [[VUID-VkImageMemoryRequirementsInfo2-image-01897]] |
| If pname:image was created with the |
| ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID |
| external memory handle type, then pname:image must: be bound to memory |
| endif::VK_ANDROID_external_memory_android_hardware_buffer[] |
| **** |
| |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| include::{generated}/validity/structs/VkImageMemoryRequirementsInfo2.txt[] |
| -- |
| |
| ifdef::VK_KHR_maintenance4[] |
| [open,refpage='VkDeviceImageMemoryRequirementsKHR',desc='(None)',type='structs'] |
| -- |
| The sname:VkDeviceImageMemoryRequirementsKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceImageMemoryRequirementsKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:pCreateInfo is a pointer to a slink:VkImageCreateInfo structure |
| containing parameters affecting creation of the image to query. |
| * pname:planeAspect is a elink:VkImageAspectFlagBits value specifying the |
| aspect corresponding to the image plane to query. |
| This parameter is ignored unless pname:pCreateInfo::pname:flags has |
| ename:VK_IMAGE_CREATE_DISJOINT_BIT |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| or ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT |
| endif::VK_EXT_image_drm_format_modifier[] |
| set. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06416]] |
| The pname:pCreateInfo::pname:pNext chain must: not contain a |
| slink:VkImageSwapchainCreateInfoKHR structure |
| * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06417]] |
| If pname:pCreateInfo::pname:flags has ename:VK_IMAGE_CREATE_DISJOINT_BIT |
| set then pname:planAspect must: not be zero |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06418]] |
| If pname:pCreateInfo::pname:flags has |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT set then pname:planAspect |
| must: not be zero |
| endif::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06419]] |
| If pname:pCreateInfo::pname:flags has ename:VK_IMAGE_CREATE_DISJOINT_BIT |
| set and if the pname:pCreateInfo::pname:tiling is |
| ename:VK_IMAGE_TILING_LINEAR or ename:VK_IMAGE_TILING_OPTIMAL, then |
| pname:planeAspect must: be a single valid _format plane_ for the image |
| (that is, for a two-plane image pname:planeAspect must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT, |
| and for a three-plane image pname:planeAspect must: be |
| ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or |
| ename:VK_IMAGE_ASPECT_PLANE_2_BIT) |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkDeviceImageMemoryRequirementsKHR-pCreateInfo-06420]] |
| If pname:pCreateInfo::pname:flags has |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT set and the |
| pname:pCreateInfo::pname:tiling is |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then pname:planeAspect |
| must: be a single valid _memory plane_ for the image (that is, |
| pname:aspectMask must: specify a plane index that is less than the |
| slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount |
| associated with the image's pname:format and |
| slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier) |
| endif::VK_EXT_image_drm_format_modifier[] |
| **** |
| |
| include::{generated}/validity/structs/VkDeviceImageMemoryRequirementsKHR.txt[] |
| -- |
| endif::VK_KHR_maintenance4[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| [open,refpage='VkImagePlaneMemoryRequirementsInfo',desc='Structure specifying image plane for memory requirements',type='structs'] |
| -- |
| To determine the memory requirements for a plane of a disjoint image, add a |
| sname:VkImagePlaneMemoryRequirementsInfo structure to the pname:pNext chain |
| of the sname:VkImageMemoryRequirementsInfo2 structure. |
| |
| The sname:VkImagePlaneMemoryRequirementsInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkImagePlaneMemoryRequirementsInfo.txt[] |
| |
| ifdef::VK_KHR_sampler_ycbcr_conversion[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkImagePlaneMemoryRequirementsInfoKHR.txt[] |
| endif::VK_KHR_sampler_ycbcr_conversion[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:planeAspect is a elink:VkImageAspectFlagBits value specifying the |
| aspect corresponding to the image plane to query. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-02281]] |
| If the image's pname:tiling is ename:VK_IMAGE_TILING_LINEAR or |
| ename:VK_IMAGE_TILING_OPTIMAL, then pname:planeAspect must: be a single |
| valid _format plane_ for the image (that is, for a two-plane image |
| pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT or |
| ename:VK_IMAGE_ASPECT_PLANE_1_BIT, and for a three-plane image |
| pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, |
| ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT) |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-02282]] |
| If the image's pname:tiling is |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then pname:planeAspect |
| must: be a single valid _memory plane_ for the image (that is, |
| pname:aspectMask must: specify a plane index that is less than the |
| slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount |
| associated with the image's pname:format and |
| slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier) |
| endif::VK_EXT_image_drm_format_modifier[] |
| **** |
| |
| include::{generated}/validity/structs/VkImagePlaneMemoryRequirementsInfo.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| [open,refpage='VkMemoryRequirements2',desc='Structure specifying memory requirements',type='structs'] |
| -- |
| The sname:VkMemoryRequirements2 structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryRequirements2.txt[] |
| |
| ifdef::VK_KHR_get_memory_requirements2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkMemoryRequirements2KHR.txt[] |
| endif::VK_KHR_get_memory_requirements2[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:memoryRequirements is a slink:VkMemoryRequirements structure |
| describing the memory requirements of the resource. |
| |
| include::{generated}/validity/structs/VkMemoryRequirements2.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[] |
| [open,refpage='VkMemoryDedicatedRequirements',desc='Structure describing dedicated allocation requirements of buffer and image resources',type='structs'] |
| -- |
| The sname:VkMemoryDedicatedRequirements structure is defined as: |
| |
| include::{generated}/api/structs/VkMemoryDedicatedRequirements.txt[] |
| |
| ifdef::VK_KHR_dedicated_allocation[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkMemoryDedicatedRequirementsKHR.txt[] |
| endif::VK_KHR_dedicated_allocation[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:prefersDedicatedAllocation specifies that the implementation would |
| prefer a dedicated allocation for this resource. |
| The application is still free to suballocate the resource but it may: |
| get better performance if a dedicated allocation is used. |
| * pname:requiresDedicatedAllocation specifies that a dedicated allocation |
| is required for this resource. |
| |
| To determine the dedicated allocation requirements of a buffer or image |
| resource, add a slink:VkMemoryDedicatedRequirements structure to the |
| pname:pNext chain of the slink:VkMemoryRequirements2 structure passed as the |
| pname:pMemoryRequirements parameter of flink:vkGetBufferMemoryRequirements2 |
| or flink:vkGetImageMemoryRequirements2, respectively. |
| |
| Constraints on the values returned for buffer resources are: |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| * pname:requiresDedicatedAllocation may: be ename:VK_TRUE if the |
| pname:pNext chain of slink:VkBufferCreateInfo for the call to |
| fname:vkCreateBuffer used to create the buffer being queried included a |
| slink:VkExternalMemoryBufferCreateInfo structure, and any of the handle |
| types specified in |
| slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes requires |
| dedicated allocation, as reported by |
| flink:vkGetPhysicalDeviceExternalBufferProperties in |
| sname:VkExternalBufferProperties::pname:externalMemoryProperties.externalMemoryFeatures. |
| Otherwise, pname:requiresDedicatedAllocation will be ename:VK_FALSE. |
| |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| * pname:requiresDedicatedAllocation will be ename:VK_FALSE |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| * When the implementation sets pname:requiresDedicatedAllocation to |
| ename:VK_TRUE, it must: also set pname:prefersDedicatedAllocation to |
| ename:VK_TRUE. |
| * If ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT was set in |
| slink:VkBufferCreateInfo::pname:flags when pname:buffer was created, |
| then both pname:prefersDedicatedAllocation and |
| pname:requiresDedicatedAllocation will be ename:VK_FALSE. |
| |
| Constraints on the values returned for image resources are: |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| * pname:requiresDedicatedAllocation may: be ename:VK_TRUE if the |
| pname:pNext chain of slink:VkImageCreateInfo for the call to |
| flink:vkCreateImage used to create the image being queried included a |
| slink:VkExternalMemoryImageCreateInfo structure, and any of the handle |
| types specified in |
| slink:VkExternalMemoryImageCreateInfo::pname:handleTypes requires |
| dedicated allocation, as reported by |
| flink:vkGetPhysicalDeviceImageFormatProperties2 in |
| sname:VkExternalImageFormatProperties::pname:externalMemoryProperties.externalMemoryFeatures. |
| Otherwise, pname:requiresDedicatedAllocation will be ename:VK_FALSE. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| * pname:requiresDedicatedAllocation will be ename:VK_FALSE |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| * If ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT was set in |
| slink:VkImageCreateInfo::pname:flags when pname:image was created, then |
| both pname:prefersDedicatedAllocation and |
| pname:requiresDedicatedAllocation will be ename:VK_FALSE. |
| |
| include::{generated}/validity/structs/VkMemoryDedicatedRequirements.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[] |
| |
| [open,refpage='vkBindBufferMemory',desc='Bind device memory to a buffer object',type='protos'] |
| -- |
| :refpage: vkBindBufferMemory |
| |
| To attach memory to a buffer object, call: |
| |
| include::{generated}/api/protos/vkBindBufferMemory.txt[] |
| |
| * pname:device is the logical device that owns the buffer and memory. |
| * pname:buffer is the buffer to be attached to memory. |
| * pname:memory is a slink:VkDeviceMemory object describing the device |
| memory to attach. |
| * pname:memoryOffset is the start offset of the region of pname:memory |
| which is to be bound to the buffer. |
| The number of bytes returned in the |
| sname:VkMemoryRequirements::pname:size member in pname:memory, starting |
| from pname:memoryOffset bytes, will be bound to the specified buffer. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| fname:vkBindBufferMemory is equivalent to passing the same parameters |
| through slink:VkBindBufferMemoryInfo to flink:vkBindBufferMemory2. |
| endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/bind_buffer_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkBindBufferMemory.txt[] |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| [open,refpage='vkBindBufferMemory2',desc='Bind device memory to buffer objects',type='protos'] |
| -- |
| To attach memory to buffer objects for one or more buffers at a time, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkBindBufferMemory2.txt[] |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1+VK_KHR_bind_memory2[or the equivalent command] |
| |
| ifdef::VK_KHR_bind_memory2[] |
| include::{generated}/api/protos/vkBindBufferMemory2KHR.txt[] |
| endif::VK_KHR_bind_memory2[] |
| |
| * pname:device is the logical device that owns the buffers and memory. |
| * pname:bindInfoCount is the number of elements in pname:pBindInfos. |
| * pname:pBindInfos is a pointer to an array of pname:bindInfoCount |
| slink:VkBindBufferMemoryInfo structures describing buffers and memory to |
| bind. |
| |
| On some implementations, it may: be more efficient to batch memory bindings |
| into a single command. |
| |
| include::{generated}/validity/protos/vkBindBufferMemory2.txt[] |
| -- |
| |
| [open,refpage='VkBindBufferMemoryInfo',desc='Structure specifying how to bind a buffer to memory',type='structs'] |
| -- |
| :refpage: VkBindBufferMemoryInfo |
| |
| sname:VkBindBufferMemoryInfo contains members corresponding to the |
| parameters of flink:vkBindBufferMemory. |
| |
| The sname:VkBindBufferMemoryInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkBindBufferMemoryInfo.txt[] |
| |
| ifdef::VK_KHR_bind_memory2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkBindBufferMemoryInfoKHR.txt[] |
| endif::VK_KHR_bind_memory2[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:buffer is the buffer to be attached to memory. |
| * pname:memory is a slink:VkDeviceMemory object describing the device |
| memory to attach. |
| * pname:memoryOffset is the start offset of the region of pname:memory |
| which is to be bound to the buffer. |
| The number of bytes returned in the |
| sname:VkMemoryRequirements::pname:size member in pname:memory, starting |
| from pname:memoryOffset bytes, will be bound to the specified buffer. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/bind_buffer_common.txt[] |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| * [[VUID-VkBindBufferMemoryInfo-pNext-01605]] |
| If the pname:pNext chain includes a |
| slink:VkBindBufferMemoryDeviceGroupInfo structure, all instances of |
| pname:memory specified by |
| slink:VkBindBufferMemoryDeviceGroupInfo::pname:pDeviceIndices must: have |
| been allocated |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| **** |
| |
| include::{generated}/validity/structs/VkBindBufferMemoryInfo.txt[] |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| [open,refpage='VkBindBufferMemoryDeviceGroupInfo',desc='Structure specifying device within a group to bind to',type='structs'] |
| -- |
| The sname:VkBindBufferMemoryDeviceGroupInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkBindBufferMemoryDeviceGroupInfo.txt[] |
| |
| // Jon: this conditional needs to be enhanced for 1.1 / bind_memory_2 |
| ifdef::VK_KHR_device_group+VK_KHR_bind_memory2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkBindBufferMemoryDeviceGroupInfoKHR.txt[] |
| endif::VK_KHR_device_group+VK_KHR_bind_memory2[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:deviceIndexCount is the number of elements in |
| pname:pDeviceIndices. |
| * pname:pDeviceIndices is a pointer to an array of device indices. |
| |
| If the pname:pNext chain of slink:VkBindBufferMemoryInfo includes a |
| sname:VkBindBufferMemoryDeviceGroupInfo structure, then that structure |
| determines how memory is bound to buffers across multiple devices in a |
| device group. |
| |
| If pname:deviceIndexCount is greater than zero, then on device index [eq]#i# |
| the buffer is attached to the instance of pname:memory on the physical |
| device with device index [eq]#pname:pDeviceIndices[i]#. |
| |
| If pname:deviceIndexCount is zero and pname:memory comes from a memory heap |
| with the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if |
| pname:pDeviceIndices contains consecutive indices from zero to the number of |
| physical devices in the logical device, minus one. |
| In other words, by default each physical device attaches to its own instance |
| of pname:memory. |
| |
| If pname:deviceIndexCount is zero and pname:memory comes from a memory heap |
| without the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as |
| if pname:pDeviceIndices contains an array of zeros. |
| In other words, by default each physical device attaches to instance zero. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBindBufferMemoryDeviceGroupInfo-deviceIndexCount-01606]] |
| pname:deviceIndexCount must: either be zero or equal to the number of |
| physical devices in the logical device |
| * [[VUID-VkBindBufferMemoryDeviceGroupInfo-pDeviceIndices-01607]] |
| All elements of pname:pDeviceIndices must: be valid device indices |
| **** |
| |
| include::{generated}/validity/structs/VkBindBufferMemoryDeviceGroupInfo.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| |
| [open,refpage='vkBindImageMemory',desc='Bind device memory to an image object',type='protos'] |
| -- |
| :refpage: vkBindImageMemory |
| |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| To attach memory to an image object, call: |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| To attach memory to a sname:VkImage object created without the |
| ename:VK_IMAGE_CREATE_DISJOINT_BIT set, call: |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| |
| include::{generated}/api/protos/vkBindImageMemory.txt[] |
| |
| * pname:device is the logical device that owns the image and memory. |
| * pname:image is the image. |
| * pname:memory is the slink:VkDeviceMemory object describing the device |
| memory to attach. |
| * pname:memoryOffset is the start offset of the region of pname:memory |
| which is to be bound to the image. |
| The number of bytes returned in the |
| sname:VkMemoryRequirements::pname:size member in pname:memory, starting |
| from pname:memoryOffset bytes, will be bound to the specified image. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| fname:vkBindImageMemory is equivalent to passing the same parameters through |
| slink:VkBindImageMemoryInfo to flink:vkBindImageMemory2. |
| endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/bind_image_common.txt[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkBindImageMemory-image-01608]] |
| pname:image must: not have been created with the |
| ename:VK_IMAGE_CREATE_DISJOINT_BIT set |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkBindImageMemory-memory-01047]] |
| pname:memory must: have been allocated using one of the memory types |
| allowed in the pname:memoryTypeBits member of the |
| sname:VkMemoryRequirements structure returned from a call to |
| flink:vkGetImageMemoryRequirements with pname:image |
| * [[VUID-vkBindImageMemory-memoryOffset-01048]] |
| pname:memoryOffset must: be an integer multiple of the pname:alignment |
| member of the sname:VkMemoryRequirements structure returned from a call |
| to flink:vkGetImageMemoryRequirements with pname:image |
| * [[VUID-vkBindImageMemory-size-01049]] |
| The difference of the size of pname:memory and pname:memoryOffset must: |
| be greater than or equal to the pname:size member of the |
| slink:VkMemoryRequirements structure returned from a call to |
| flink:vkGetImageMemoryRequirements with the same pname:image |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| * [[VUID-vkBindImageMemory-image-06392]] |
| If pname:image was created with |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA chained to |
| slink:VkImageCreateInfo::pname:pNext, pname:memory must: be allocated |
| with a slink:VkImportMemoryBufferCollectionFUCHSIA chained to |
| slink:VkMemoryAllocateInfo::pname:pNext |
| endif::VK_FUCHSIA_buffer_collection[] |
| **** |
| |
| include::{generated}/validity/protos/vkBindImageMemory.txt[] |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| [open,refpage='vkBindImageMemory2',desc='Bind device memory to image objects',type='protos'] |
| -- |
| To attach memory to image objects for one or more images at a time, call: |
| |
| ifdef::VK_VERSION_1_1[] |
| include::{generated}/api/protos/vkBindImageMemory2.txt[] |
| endif::VK_VERSION_1_1[] |
| |
| ifdef::VK_VERSION_1_1+VK_KHR_bind_memory2[or the equivalent command] |
| |
| ifdef::VK_KHR_bind_memory2[] |
| include::{generated}/api/protos/vkBindImageMemory2KHR.txt[] |
| endif::VK_KHR_bind_memory2[] |
| |
| * pname:device is the logical device that owns the images and memory. |
| * pname:bindInfoCount is the number of elements in pname:pBindInfos. |
| * pname:pBindInfos is a pointer to an array of slink:VkBindImageMemoryInfo |
| structures, describing images and memory to bind. |
| |
| On some implementations, it may: be more efficient to batch memory bindings |
| into a single command. |
| |
| .Valid Usage |
| **** |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-vkBindImageMemory2-pBindInfos-02858]] |
| If any slink:VkBindImageMemoryInfo::pname:image was created with |
| ename:VK_IMAGE_CREATE_DISJOINT_BIT then all planes of |
| slink:VkBindImageMemoryInfo::pname:image must: be bound individually in |
| separate pname:pBindInfos |
| * [[VUID-vkBindImageMemory2-pBindInfos-04006]] |
| pname:pBindInfos must: not refer to the same image subresource more than |
| once |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| **** |
| |
| include::{generated}/validity/protos/vkBindImageMemory2.txt[] |
| -- |
| |
| [open,refpage='VkBindImageMemoryInfo',desc='Structure specifying how to bind an image to memory',type='structs'] |
| -- |
| :refpage: VkBindImageMemoryInfo |
| |
| sname:VkBindImageMemoryInfo contains members corresponding to the parameters |
| of flink:vkBindImageMemory. |
| |
| The sname:VkBindImageMemoryInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkBindImageMemoryInfo.txt[] |
| |
| ifdef::VK_KHR_bind_memory2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkBindImageMemoryInfoKHR.txt[] |
| endif::VK_KHR_bind_memory2[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:image is the image to be attached to memory. |
| * pname:memory is a slink:VkDeviceMemory object describing the device |
| memory to attach. |
| * pname:memoryOffset is the start offset of the region of pname:memory |
| which is to be bound to the image. |
| The number of bytes returned in the |
| sname:VkMemoryRequirements::pname:size member in pname:memory, starting |
| from pname:memoryOffset bytes, will be bound to the specified image. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/bind_image_common.txt[] |
| ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBindImageMemoryInfo-memory-01612]] |
| pname:memory must: have been allocated using one of the memory types |
| allowed in the pname:memoryTypeBits member of the |
| slink:VkMemoryRequirements structure returned from a call to |
| flink:vkGetImageMemoryRequirements with pname:image |
| * [[VUID-VkBindImageMemoryInfo-memoryOffset-01613]] |
| pname:memoryOffset must: be an integer multiple of the pname:alignment |
| member of the slink:VkMemoryRequirements structure returned from a call |
| to flink:vkGetImageMemoryRequirements with pname:image |
| * [[VUID-VkBindImageMemoryInfo-memory-01614]] |
| The difference of the size of pname:memory and pname:memoryOffset must: |
| be greater than or equal to the pname:size member of the |
| slink:VkMemoryRequirements structure returned from a call to |
| flink:vkGetImageMemoryRequirements with the same pname:image |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| * [[VUID-VkBindImageMemoryInfo-pNext-01615]] |
| If the pname:pNext chain does not include a |
| slink:VkBindImagePlaneMemoryInfo structure, pname:memory must: have been |
| allocated using one of the memory types allowed in the |
| pname:memoryTypeBits member of the slink:VkMemoryRequirements structure |
| returned from a call to flink:vkGetImageMemoryRequirements2 with |
| pname:image |
| * [[VUID-VkBindImageMemoryInfo-pNext-01616]] |
| If the pname:pNext chain does not include a |
| slink:VkBindImagePlaneMemoryInfo structure, pname:memoryOffset must: be |
| an integer multiple of the pname:alignment member of the |
| slink:VkMemoryRequirements structure returned from a call to |
| flink:vkGetImageMemoryRequirements2 with pname:image |
| * [[VUID-VkBindImageMemoryInfo-pNext-01617]] |
| If the pname:pNext chain does not include a |
| slink:VkBindImagePlaneMemoryInfo structure, the difference of the size |
| of pname:memory and pname:memoryOffset must: be greater than or equal to |
| the pname:size member of the slink:VkMemoryRequirements structure |
| returned from a call to flink:vkGetImageMemoryRequirements2 with the |
| same pname:image |
| * [[VUID-VkBindImageMemoryInfo-pNext-01618]] |
| If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo |
| structure, pname:image must: have been created with the |
| ename:VK_IMAGE_CREATE_DISJOINT_BIT bit set |
| * [[VUID-VkBindImageMemoryInfo-pNext-01619]] |
| If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo |
| structure, pname:memory must: have been allocated using one of the |
| memory types allowed in the pname:memoryTypeBits member of the |
| slink:VkMemoryRequirements structure returned from a call to |
| flink:vkGetImageMemoryRequirements2 with pname:image and where |
| slink:VkBindImagePlaneMemoryInfo::pname:planeAspect corresponds to the |
| slink:VkImagePlaneMemoryRequirementsInfo::pname:planeAspect in the |
| slink:VkImageMemoryRequirementsInfo2 structure's pname:pNext chain |
| * [[VUID-VkBindImageMemoryInfo-pNext-01620]] |
| If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo |
| structure, pname:memoryOffset must: be an integer multiple of the |
| pname:alignment member of the slink:VkMemoryRequirements structure |
| returned from a call to flink:vkGetImageMemoryRequirements2 with |
| pname:image and where |
| slink:VkBindImagePlaneMemoryInfo::pname:planeAspect corresponds to the |
| slink:VkImagePlaneMemoryRequirementsInfo::pname:planeAspect in the |
| slink:VkImageMemoryRequirementsInfo2 structure's pname:pNext chain |
| * [[VUID-VkBindImageMemoryInfo-pNext-01621]] |
| If the pname:pNext chain includes a slink:VkBindImagePlaneMemoryInfo |
| structure, the difference of the size of pname:memory and |
| pname:memoryOffset must: be greater than or equal to the pname:size |
| member of the slink:VkMemoryRequirements structure returned from a call |
| to flink:vkGetImageMemoryRequirements2 with the same pname:image and |
| where slink:VkBindImagePlaneMemoryInfo::pname:planeAspect corresponds to |
| the slink:VkImagePlaneMemoryRequirementsInfo::pname:planeAspect in the |
| slink:VkImageMemoryRequirementsInfo2 structure's pname:pNext chain |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| ifndef::VK_VERSION_1_1+VK_KHR_swapchain[] |
| ifndef::VK_KHR_device_group+VK_KHR_swapchain[] |
| * [[VUID-VkBindImageMemoryInfo-memory-01625]] |
| pname:memory must: be a valid slink:VkDeviceMemory handle |
| endif::VK_KHR_device_group+VK_KHR_swapchain[] |
| endif::VK_VERSION_1_1+VK_KHR_swapchain[] |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| * [[VUID-VkBindImageMemoryInfo-pNext-01626]] |
| If the pname:pNext chain includes a |
| slink:VkBindImageMemoryDeviceGroupInfo structure, all instances of |
| pname:memory specified by |
| slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices must: have |
| been allocated |
| * [[VUID-VkBindImageMemoryInfo-pNext-01627]] |
| If the pname:pNext chain includes a |
| slink:VkBindImageMemoryDeviceGroupInfo structure, and |
| slink:VkBindImageMemoryDeviceGroupInfo::pname:splitInstanceBindRegionCount |
| is not zero, then pname:image must: have been created with the |
| ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit set |
| * [[VUID-VkBindImageMemoryInfo-pNext-01628]] |
| If the pname:pNext chain includes a |
| slink:VkBindImageMemoryDeviceGroupInfo structure, all elements of |
| slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions |
| must: be valid rectangles contained within the dimensions of pname:image |
| * [[VUID-VkBindImageMemoryInfo-pNext-01629]] |
| If the pname:pNext chain includes a |
| slink:VkBindImageMemoryDeviceGroupInfo structure, the union of the areas |
| of all elements of |
| slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions |
| that correspond to the same instance of pname:image must: cover the |
| entire image |
| ifdef::VK_KHR_swapchain[] |
| * [[VUID-VkBindImageMemoryInfo-image-01630]] |
| If pname:image was created with a valid swapchain handle in |
| slink:VkImageSwapchainCreateInfoKHR::pname:swapchain, then the |
| pname:pNext chain must: include a |
| slink:VkBindImageMemorySwapchainInfoKHR structure containing the same |
| swapchain handle |
| * [[VUID-VkBindImageMemoryInfo-pNext-01631]] |
| If the pname:pNext chain includes a |
| slink:VkBindImageMemorySwapchainInfoKHR structure, pname:memory must: be |
| dlink:VK_NULL_HANDLE |
| * [[VUID-VkBindImageMemoryInfo-pNext-01632]] |
| If the pname:pNext chain does not include a |
| slink:VkBindImageMemorySwapchainInfoKHR structure, pname:memory must: be |
| a valid slink:VkDeviceMemory handle |
| endif::VK_KHR_swapchain[] |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| **** |
| |
| include::{generated}/validity/structs/VkBindImageMemoryInfo.txt[] |
| -- |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| [open,refpage='VkBindImageMemoryDeviceGroupInfo',desc='Structure specifying device within a group to bind to',type='structs'] |
| -- |
| The sname:VkBindImageMemoryDeviceGroupInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkBindImageMemoryDeviceGroupInfo.txt[] |
| |
| // Jon: this conditional needs to be enhanced for 1.1 / bind_memory_2 |
| ifdef::VK_KHR_device_group+VK_KHR_bind_memory2[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkBindImageMemoryDeviceGroupInfoKHR.txt[] |
| endif::VK_KHR_device_group+VK_KHR_bind_memory2[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:deviceIndexCount is the number of elements in |
| pname:pDeviceIndices. |
| * pname:pDeviceIndices is a pointer to an array of device indices. |
| * pname:splitInstanceBindRegionCount is the number of elements in |
| pname:pSplitInstanceBindRegions. |
| * pname:pSplitInstanceBindRegions is a pointer to an array of |
| slink:VkRect2D structures describing which regions of the image are |
| attached to each instance of memory. |
| |
| If the pname:pNext chain of slink:VkBindImageMemoryInfo includes a |
| sname:VkBindImageMemoryDeviceGroupInfo structure, then that structure |
| determines how memory is bound to images across multiple devices in a device |
| group. |
| |
| If pname:deviceIndexCount is greater than zero, then on device index [eq]#i# |
| pname:image is attached to the instance of the memory on the physical device |
| with device index [eq]#pDeviceIndices[i]#. |
| |
| Let [eq]#N# be the number of physical devices in the logical device. |
| If pname:splitInstanceBindRegionCount is greater than zero, then |
| pname:pSplitInstanceBindRegions is a pointer to an array of [eq]#N^2^# |
| rectangles, where the image region specified by the rectangle at element |
| [eq]#i*N+j# in resource instance [eq]#i# is bound to the memory instance |
| [eq]#j#. |
| The blocks of the memory that are bound to each sparse image block region |
| use an offset in memory, relative to pname:memoryOffset, computed as if the |
| whole image was being bound to a contiguous range of memory. |
| In other words, horizontally adjacent image blocks use consecutive blocks of |
| memory, vertically adjacent image blocks are separated by the number of |
| bytes per block multiplied by the width in blocks of pname:image, and the |
| block at [eq]#(0,0)# corresponds to memory starting at pname:memoryOffset. |
| |
| If pname:splitInstanceBindRegionCount and pname:deviceIndexCount are zero |
| and the memory comes from a memory heap with the |
| ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if |
| pname:pDeviceIndices contains consecutive indices from zero to the number of |
| physical devices in the logical device, minus one. |
| In other words, by default each physical device attaches to its own instance |
| of the memory. |
| |
| If pname:splitInstanceBindRegionCount and pname:deviceIndexCount are zero |
| and the memory comes from a memory heap without the |
| ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if |
| pname:pDeviceIndices contains an array of zeros. |
| In other words, by default each physical device attaches to instance zero. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBindImageMemoryDeviceGroupInfo-deviceIndexCount-01633]] |
| At least one of pname:deviceIndexCount and |
| pname:splitInstanceBindRegionCount must: be zero |
| * [[VUID-VkBindImageMemoryDeviceGroupInfo-deviceIndexCount-01634]] |
| pname:deviceIndexCount must: either be zero or equal to the number of |
| physical devices in the logical device |
| * [[VUID-VkBindImageMemoryDeviceGroupInfo-pDeviceIndices-01635]] |
| All elements of pname:pDeviceIndices must: be valid device indices |
| * [[VUID-VkBindImageMemoryDeviceGroupInfo-splitInstanceBindRegionCount-01636]] |
| pname:splitInstanceBindRegionCount must: either be zero or equal to the |
| number of physical devices in the logical device squared |
| * [[VUID-VkBindImageMemoryDeviceGroupInfo-pSplitInstanceBindRegions-01637]] |
| Elements of pname:pSplitInstanceBindRegions that correspond to the same |
| instance of an image must: not overlap |
| * [[VUID-VkBindImageMemoryDeviceGroupInfo-offset-01638]] |
| The pname:offset.x member of any element of |
| pname:pSplitInstanceBindRegions must: be a multiple of the sparse image |
| block width |
| (sname:VkSparseImageFormatProperties::pname:imageGranularity.width) of |
| all non-metadata aspects of the image |
| * [[VUID-VkBindImageMemoryDeviceGroupInfo-offset-01639]] |
| The pname:offset.y member of any element of |
| pname:pSplitInstanceBindRegions must: be a multiple of the sparse image |
| block height |
| (sname:VkSparseImageFormatProperties::pname:imageGranularity.height) of |
| all non-metadata aspects of the image |
| * [[VUID-VkBindImageMemoryDeviceGroupInfo-extent-01640]] |
| The pname:extent.width member of any element of |
| pname:pSplitInstanceBindRegions must: either be a multiple of the sparse |
| image block width of all non-metadata aspects of the image, or else |
| pname:extent.width {plus} pname:offset.x must: equal the width of the |
| image subresource |
| * [[VUID-VkBindImageMemoryDeviceGroupInfo-extent-01641]] |
| The pname:extent.height member of any element of |
| pname:pSplitInstanceBindRegions must: either be a multiple of the sparse |
| image block height of all non-metadata aspects of the image, or else |
| pname:extent.height {plus} pname:offset.y must: equal the height of the |
| image subresource |
| **** |
| |
| include::{generated}/validity/structs/VkBindImageMemoryDeviceGroupInfo.txt[] |
| -- |
| |
| ifdef::VK_KHR_swapchain[] |
| [open,refpage='VkBindImageMemorySwapchainInfoKHR',desc='Structure specifying swapchain image memory to bind to',type='structs'] |
| -- |
| If the pname:pNext chain of slink:VkBindImageMemoryInfo includes a |
| sname:VkBindImageMemorySwapchainInfoKHR structure, then that structure |
| includes a swapchain handle and image index indicating that the image will |
| be bound to memory from that swapchain. |
| |
| The sname:VkBindImageMemorySwapchainInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkBindImageMemorySwapchainInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:swapchain is dlink:VK_NULL_HANDLE or a swapchain handle. |
| * pname:imageIndex is an image index within pname:swapchain. |
| |
| If pname:swapchain is not `NULL`, the pname:swapchain and pname:imageIndex |
| are used to determine the memory that the image is bound to, instead of |
| pname:memory and pname:memoryOffset. |
| |
| Memory can: be bound to a swapchain and use the pname:pDeviceIndices or |
| pname:pSplitInstanceBindRegions members of |
| slink:VkBindImageMemoryDeviceGroupInfo. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBindImageMemorySwapchainInfoKHR-imageIndex-01644]] |
| pname:imageIndex must: be less than the number of images in |
| pname:swapchain |
| **** |
| |
| include::{generated}/validity/structs/VkBindImageMemorySwapchainInfoKHR.txt[] |
| -- |
| endif::VK_KHR_swapchain[] |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| [open,refpage='VkBindImagePlaneMemoryInfo',desc='Structure specifying how to bind an image plane to memory',type='structs'] |
| -- |
| In order to bind _planes_ of a _disjoint image_, add a |
| sname:VkBindImagePlaneMemoryInfo structure to the pname:pNext chain of |
| slink:VkBindImageMemoryInfo. |
| |
| The sname:VkBindImagePlaneMemoryInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkBindImagePlaneMemoryInfo.txt[] |
| |
| ifdef::VK_KHR_sampler_ycbcr_conversion[] |
| or the equivalent |
| |
| include::{generated}/api/structs/VkBindImagePlaneMemoryInfoKHR.txt[] |
| endif::VK_KHR_sampler_ycbcr_conversion[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:planeAspect is a ename:VkImageAspectFlagBits value specifying the |
| aspect of the disjoint image plane to bind. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBindImagePlaneMemoryInfo-planeAspect-02283]] |
| If the image's pname:tiling is ename:VK_IMAGE_TILING_LINEAR or |
| ename:VK_IMAGE_TILING_OPTIMAL, then pname:planeAspect must: be a single |
| valid _format plane_ for the image (that is, for a two-plane image |
| pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT or |
| ename:VK_IMAGE_ASPECT_PLANE_1_BIT, and for a three-plane image |
| pname:planeAspect must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT, |
| ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT) |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * [[VUID-VkBindImagePlaneMemoryInfo-planeAspect-02284]] |
| If the image's pname:tiling is |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then pname:planeAspect |
| must: be a single valid _memory plane_ for the image (that is, |
| pname:aspectMask must: specify a plane index that is less than the |
| slink:VkDrmFormatModifierPropertiesEXT::pname:drmFormatModifierPlaneCount |
| associated with the image's pname:format and |
| slink:VkImageDrmFormatModifierPropertiesEXT::pname:drmFormatModifier) |
| endif::VK_EXT_image_drm_format_modifier[] |
| **** |
| |
| include::{generated}/validity/structs/VkBindImagePlaneMemoryInfo.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| |
| |
| [[resources-bufferimagegranularity,Buffer-Image Granularity]] |
| .Buffer-Image Granularity |
| There is an implementation-dependent limit, pname:bufferImageGranularity, |
| which specifies a page-like granularity at which linear and non-linear |
| resources must: be placed in adjacent memory locations to avoid aliasing. |
| Two resources which do not satisfy this granularity requirement are said to |
| <<resources-memory-aliasing,alias>>. |
| pname:bufferImageGranularity is specified in bytes, and must: be a power of |
| two. |
| Implementations which do not impose a granularity restriction may: report a |
| pname:bufferImageGranularity value of one. |
| |
| [NOTE] |
| .Note |
| ==== |
| Despite its name, pname:bufferImageGranularity is really a granularity |
| between "`linear`" and "`non-linear`" resources. |
| ==== |
| |
| Given resourceA at the lower memory offset and resourceB at the higher |
| memory offset in the same sname:VkDeviceMemory object, where one resource is |
| linear and the other is non-linear (as defined in the |
| <<glossary-linear-resource,Glossary>>), and the following: |
| |
| [source,c] |
| --------------------------------------------------- |
| resourceA.end = resourceA.memoryOffset + resourceA.size - 1 |
| resourceA.endPage = resourceA.end & ~(bufferImageGranularity-1) |
| resourceB.start = resourceB.memoryOffset |
| resourceB.startPage = resourceB.start & ~(bufferImageGranularity-1) |
| --------------------------------------------------- |
| |
| The following property must: hold: |
| |
| [source,c] |
| --------------------------------------------------- |
| resourceA.endPage < resourceB.startPage |
| --------------------------------------------------- |
| |
| That is, the end of the first resource (A) and the beginning of the second |
| resource (B) must: be on separate "`pages`" of size |
| pname:bufferImageGranularity. |
| pname:bufferImageGranularity may: be different than the physical page size |
| of the memory heap. |
| This restriction is only needed when a linear resource and a non-linear |
| resource are adjacent in memory and will be used simultaneously. |
| The memory ranges of adjacent resources can: be closer than |
| pname:bufferImageGranularity, provided they meet the pname:alignment |
| requirement for the objects in question. |
| |
| Sparse block size in bytes and sparse image and buffer memory alignments |
| must: all be multiples of the pname:bufferImageGranularity. |
| Therefore, memory bound to sparse resources naturally satisfies the |
| pname:bufferImageGranularity. |
| |
| |
| [[resources-sharing]] |
| == Resource Sharing Mode |
| |
| [open,refpage='VkSharingMode',desc='Buffer and image sharing modes',type='enums'] |
| -- |
| Buffer and image objects are created with a _sharing mode_ controlling how |
| they can: be accessed from queues. |
| The supported sharing modes are: |
| |
| include::{generated}/api/enums/VkSharingMode.txt[] |
| |
| * ename:VK_SHARING_MODE_EXCLUSIVE specifies that access to any range or |
| image subresource of the object will be exclusive to a single queue |
| family at a time. |
| * ename:VK_SHARING_MODE_CONCURRENT specifies that concurrent access to any |
| range or image subresource of the object from multiple queue families is |
| supported. |
| |
| [NOTE] |
| .Note |
| ==== |
| ename:VK_SHARING_MODE_CONCURRENT may: result in lower performance access to |
| the buffer or image than ename:VK_SHARING_MODE_EXCLUSIVE. |
| ==== |
| |
| Ranges of buffers and image subresources of image objects created using |
| ename:VK_SHARING_MODE_EXCLUSIVE must: only be accessed by queues in the |
| queue family that has _ownership_ of the resource. |
| Upon creation, such resources are not owned by any queue family; ownership |
| is implicitly acquired upon first use within a queue. |
| Once a resource using ename:VK_SHARING_MODE_EXCLUSIVE is owned by some queue |
| family, the application must: perform a |
| <<synchronization-queue-transfers,queue family ownership transfer>> to make |
| the memory contents of a range or image subresource accessible to a |
| different queue family. |
| |
| [NOTE] |
| .Note |
| ==== |
| Images still require a <<resources-image-layouts, layout transition>> from |
| ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED |
| before being used on the first queue. |
| ==== |
| |
| A queue family can: take ownership of an image subresource or buffer range |
| of a resource created with ename:VK_SHARING_MODE_EXCLUSIVE, without an |
| ownership transfer, in the same way as for a resource that was just created; |
| however, taking ownership in this way has the effect that the contents of |
| the image subresource or buffer range are undefined:. |
| |
| Ranges of buffers and image subresources of image objects created using |
| ename:VK_SHARING_MODE_CONCURRENT must: only be accessed by queues from the |
| queue families specified through the pname:queueFamilyIndexCount and |
| pname:pQueueFamilyIndices members of the corresponding create info |
| structures. |
| -- |
| |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| [[resources-external-sharing]] |
| === External Resource Sharing |
| |
| Resources should: only be accessed in the Vulkan instance that has exclusive |
| ownership of their underlying memory. |
| Only one Vulkan instance has exclusive ownership of a resource's underlying |
| memory at a given time, regardless of whether the resource was created using |
| ename:VK_SHARING_MODE_EXCLUSIVE or ename:VK_SHARING_MODE_CONCURRENT. |
| Applications can transfer ownership of a resource's underlying memory only |
| if the memory has been imported from or exported to another instance or |
| external API using external memory handles. |
| The semantics for transferring ownership outside of the instance are similar |
| to those used for transferring ownership of ename:VK_SHARING_MODE_EXCLUSIVE |
| resources between queues, and is also accomplished using |
| slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier operations. |
| To make the contents of the underlying memory accessible in the destination |
| instance or API, applications must: |
| |
| . Release exclusive ownership from the source instance or API. |
| . Ensure the release operation has completed using semaphores or fences. |
| . Acquire exclusive ownership in the destination instance or API |
| |
| Unlike queue ownership transfers, the destination instance or API is not |
| specified explicitly when releasing ownership, nor is the source instance or |
| API specified when acquiring ownership. |
| Instead, the image or memory barrier's pname:dstQueueFamilyIndex or |
| pname:srcQueueFamilyIndex parameters are set to the reserved queue family |
| index ename:VK_QUEUE_FAMILY_EXTERNAL |
| ifdef::VK_EXT_queue_family_foreign[] |
| or ename:VK_QUEUE_FAMILY_FOREIGN_EXT |
| endif::VK_EXT_queue_family_foreign[] |
| to represent the external destination or source respectively. |
| |
| Binding a resource to a memory object shared between multiple Vulkan |
| instances or other APIs does not change the ownership of the underlying |
| memory. |
| The first entity to access the resource implicitly acquires ownership. |
| An entity can: also implicitly take ownership from another entity in the |
| same way without an explicit ownership transfer. |
| However, taking ownership in this way has the effect that the contents of |
| the underlying memory are undefined:. |
| |
| Accessing a resource backed by memory that is owned by a particular instance |
| or API has the same semantics as accessing a ename:VK_SHARING_MODE_EXCLUSIVE |
| resource, with one exception: Implementations must: ensure layout |
| transitions performed on one member of a set of identical subresources of |
| identical images that alias the same range of an underlying memory object |
| affect the layout of all the subresources in the set. |
| |
| As a corollary, writes to any image subresources in such a set must: not |
| make the contents of memory used by other subresources in the set |
| undefined:. |
| An application can: define the content of a subresource of one image by |
| performing device writes to an identical subresource of another image |
| provided both images are bound to the same region of external memory. |
| Applications may: also add resources to such a set after the content of the |
| existing set members has been defined without making the content undefined: |
| by creating a new image with the initial layout |
| ename:VK_IMAGE_LAYOUT_UNDEFINED and binding it to the same region of |
| external memory as the existing images. |
| |
| [NOTE] |
| .Note |
| ==== |
| Because layout transitions apply to all identical images aliasing the same |
| region of external memory, the actual layout of the memory backing a new |
| image as well as an existing image with defined content will not be |
| undefined:. |
| Such an image is not usable until it acquires ownership of its memory from |
| the existing owner. |
| Therefore, the layout specified as part of this transition will be the true |
| initial layout of the image. |
| The undefined: layout specified when creating it is a placeholder to |
| simplify valid usage requirements. |
| ==== |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| |
| [[resources-memory-aliasing]] |
| == Memory Aliasing |
| |
| A range of a sname:VkDeviceMemory allocation is _aliased_ if it is bound to |
| multiple resources simultaneously, as described below, via |
| flink:vkBindImageMemory, flink:vkBindBufferMemory, |
| ifdef::VK_NV_ray_tracing[] |
| flink:vkBindAccelerationStructureMemoryNV, |
| endif::VK_NV_ray_tracing[] |
| ifndef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| or via <<sparsememory-resource-binding,sparse memory bindings>>. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| via <<sparsememory-resource-binding,sparse memory bindings>>, or by binding |
| the memory to resources in multiple Vulkan instances or external APIs using |
| external memory handle export and import mechanisms. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| Consider two resources, resource~A~ and resource~B~, bound respectively to |
| memory range~A~ and range~B~. |
| Let paddedRange~A~ and paddedRange~B~ be, respectively, range~A~ and |
| range~B~ aligned to pname:bufferImageGranularity. |
| If the resources are both linear or both non-linear (as defined in the |
| <<glossary-linear-resource,Glossary>>), then the resources _alias_ the |
| memory in the intersection of range~A~ and range~B~. |
| If one resource is linear and the other is non-linear, then the resources |
| _alias_ the memory in the intersection of paddedRange~A~ and paddedRange~B~. |
| |
| Applications can: alias memory, but use of multiple aliases is subject to |
| several constraints. |
| |
| [NOTE] |
| .Note |
| ==== |
| Memory aliasing can: be useful to reduce the total device memory footprint |
| of an application, if some large resources are used for disjoint periods of |
| time. |
| ==== |
| |
| When a <<glossary-linear-resource,non-linear>>, |
| non-ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image is bound to an aliased |
| range, all image subresources of the image _overlap_ the range. |
| When a linear image is bound to an aliased range, the image subresources |
| that (according to the image's advertised layout) include bytes from the |
| aliased range overlap the range. |
| When a ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT image has sparse image |
| blocks bound to an aliased range, only image subresources including those |
| sparse image blocks overlap the range, and when the memory bound to the |
| image's mip tail overlaps an aliased range all image subresources in the mip |
| tail overlap the range. |
| |
| Buffers, and linear image subresources in either the |
| ename:VK_IMAGE_LAYOUT_PREINITIALIZED or ename:VK_IMAGE_LAYOUT_GENERAL |
| layouts, are _host-accessible subresources_. |
| That is, the host has a well-defined addressing scheme to interpret the |
| contents, and thus the layout of the data in memory can: be consistently |
| interpreted across aliases if each of those aliases is a host-accessible |
| subresource. |
| Non-linear images, and linear image subresources in other layouts, are not |
| host-accessible. |
| |
| If two aliases are both host-accessible, then they interpret the contents of |
| the memory in consistent ways, and data written to one alias can: be read by |
| the other alias. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| [[resources-memory-aliasing-consistency]] |
| If two aliases are both images that were created with identical creation |
| parameters, both were created with the ename:VK_IMAGE_CREATE_ALIAS_BIT flag |
| set, and both are bound identically to memory |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| except for slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices and |
| slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions, |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| then they interpret the contents of the memory in consistent ways, and data |
| written to one alias can: be read by the other alias. |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| [[resources-memory-aliasing-consistency-planes]] |
| Additionally, if an individual plane of a multi-planar image and a |
| single-plane image alias the same memory, then they also interpret the |
| contents of the memory in consistent ways under the same conditions, but |
| with the following modifications: |
| |
| * Both must: have been created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT |
| flag. |
| * The single-plane image must: have a elink:VkFormat that is |
| <<formats-compatible-planes,equivalent>> to that of the multi-planar |
| image's individual plane. |
| * The single-plane image and the individual plane of the multi-planar |
| image must: be bound identically to memory |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| except for slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices |
| and |
| slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions. |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| * The pname:width and pname:height of the single-plane image are derived |
| from the multi-planar image's dimensions in the manner listed for |
| <<formats-compatible-planes,plane compatibility>> for the aliased plane. |
| ifdef::VK_EXT_image_drm_format_modifier[] |
| * If either image's pname:tiling is |
| ename:VK_IMAGE_TILING_DRM_FORMAT_MODIFIER_EXT, then both images must: be |
| <<glossary-linear-resource,linear>>. |
| endif::VK_EXT_image_drm_format_modifier[] |
| * All other creation parameters must: be identical |
| |
| endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[] |
| endif::VK_VERSION_1_1,VK_KHR_bind_memory2[] |
| |
| ifdef::VK_VERSION_1_1,VK_KHR_external_memory[] |
| Aliases created by binding the same memory to resources in multiple Vulkan |
| instances or external APIs using external memory handle export and import |
| mechanisms interpret the contents of the memory in consistent ways, and data |
| written to one alias can: be read by the other alias. |
| endif::VK_VERSION_1_1,VK_KHR_external_memory[] |
| |
| Otherwise, the aliases interpret the contents of the memory differently, and |
| writes via one alias make the contents of memory partially or completely |
| undefined: to the other alias. |
| If the first alias is a host-accessible subresource, then the bytes affected |
| are those written by the memory operations according to its addressing |
| scheme. |
| If the first alias is not host-accessible, then the bytes affected are those |
| overlapped by the image subresources that were written. |
| If the second alias is a host-accessible subresource, the affected bytes |
| become undefined:. |
| If the second alias is not host-accessible, all sparse image blocks (for |
| sparse partially-resident images) or all image subresources (for non-sparse |
| image and fully resident sparse images) that overlap the affected bytes |
| become undefined:. |
| |
| If any image subresources are made undefined: due to writes to an alias, |
| then each of those image subresources must: have its layout transitioned |
| from ename:VK_IMAGE_LAYOUT_UNDEFINED to a valid layout before it is used, or |
| from ename:VK_IMAGE_LAYOUT_PREINITIALIZED if the memory has been written by |
| the host. |
| If any sparse blocks of a sparse image have been made undefined:, then only |
| the image subresources containing them must: be transitioned. |
| |
| Use of an overlapping range by two aliases must: be separated by a memory |
| dependency using the appropriate <<synchronization-access-types, access |
| types>> if at least one of those uses performs writes, whether the aliases |
| interpret memory consistently or not. |
| If buffer or image memory barriers are used, the scope of the barrier must: |
| contain the entire range and/or set of image subresources that overlap. |
| |
| If two aliasing image views are used in the same framebuffer, then the |
| render pass must: declare the attachments using the |
| <<renderpass-aliasing,ename:VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT>>, and |
| follow the other rules listed in that section. |
| |
| [NOTE] |
| .Note |
| ==== |
| Memory recycled via an application suballocator (i.e. without freeing and |
| reallocating the memory objects) is not substantially different from memory |
| aliasing. |
| However, a suballocator usually waits on a fence before recycling a region |
| of memory, and signaling a fence involves sufficient implicit dependencies |
| to satisfy all the above requirements. |
| ==== |
| |
| |
| ifdef::VK_FUCHSIA_buffer_collection[] |
| [[resources-buffer-collection-fuchsia]] |
| == Buffer Collections |
| |
| [open,refpage='VkBufferCollectionFUCHSIA',desc='Opaque handle to a buffer collection object',type='handles'] |
| -- |
| Fuchsia's FIDL-based Sysmem service interoperates with Vulkan via the |
| `apiext:VK_FUCHSIA_buffer_collection` extension. |
| |
| A buffer collection is a set of one or more buffers which were allocated |
| together as a group and which all have the same properties. |
| These properties describe the buffers' internal representation, such as its |
| dimensions and memory layout. |
| This ensures that all of the buffers can be used interchangeably by tasks |
| that require swapping among multiple buffers, such as double-buffered |
| graphics rendering. |
| |
| On Fuchsia, the Sysmem service uses buffer collections as a core construct |
| in its design. |
| |
| Buffer collections are represented by sname:VkBufferCollectionFUCHSIA |
| handles: |
| |
| include::{generated}/api/handles/VkBufferCollectionFUCHSIA.txt[] |
| -- |
| |
| |
| === Definitions |
| |
| * FIDL - Fuchsia Interface Definition Language. |
| The declarative language used to define FIDL interprocess communication |
| interfaces on Fuchsia. |
| FIDL files use the `fidl` extension. |
| FIDL is also used to refer to the services defined by interfaces |
| declared in the FIDL language |
| * Sysmem - The FIDL service that facilitates optimal buffer sharing and |
| reuse on Fuchsia |
| * client - Any participant of the buffer collection e.g. the Vulkan |
| application |
| * token - A code:zx_handle_t Zircon channel object that allows |
| participation in the buffer collection |
| |
| |
| === Platform initialization for buffer collections |
| To initialize a buffer collection on Fuchsia: |
| |
| * Connect to the Sysmem service to initialize a Sysmem allocator |
| * Create an initial buffer collection token using the Sysmem allocator |
| * Duplicate the token for each participant beyond the initiator |
| * See the Sysmem Overview and fuchsia.sysmem FIDL documentation on |
| fuchsia.dev for more detailed information |
| |
| |
| === Create the buffer collection |
| |
| [open,refpage='vkCreateBufferCollectionFUCHSIA',desc='Create a new buffer collection',type='protos'] |
| -- |
| To create an slink:VkBufferCollectionFUCHSIA for Vulkan to participate in |
| the buffer collection: |
| |
| include::{generated}/api/protos/vkCreateBufferCollectionFUCHSIA.txt[] |
| |
| * pname:device is the logical device that creates the |
| sname:VkBufferCollectionFUCHSIA |
| * pname:pCreateInfo is a pointer to a |
| slink:VkBufferCollectionCreateInfoFUCHSIA structure containing |
| parameters affecting creation of the buffer collection |
| * pname:pAllocator is a pointer to a slink:VkAllocationCallbacks structure |
| which controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter |
| * pname:pBufferCollection is a pointer to a |
| slink:VkBufferCollectionFUCHSIA handle in which the resulting buffer |
| collection object is returned |
| |
| include::{generated}/validity/protos/vkCreateBufferCollectionFUCHSIA.txt[] |
| |
| .Host Access |
| **** |
| All functions referencing a slink:VkBufferCollectionFUCHSIA must: be |
| externally synchronized with the exception of |
| fname:vkCreateBufferCollectionFUCHSIA. |
| **** |
| -- |
| |
| |
| [open,refpage='VkBufferCollectionCreateInfoFUCHSIA',desc='Structure specifying desired parameters to create the buffer collection',type='structs'] |
| -- |
| The sname:VkBufferCollectionCreateInfoFUCHSIA structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferCollectionCreateInfoFUCHSIA.txt[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:collectionToken is a fname:zx_handle_t containing the Sysmem |
| client's buffer collection token |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBufferCollectionCreateInfoFUCHSIA-collectionToken-06393]] |
| pname:collectionToken must: be a valid code:zx_handle_t to a Zircon |
| channel allocated from Sysmem |
| (code:fuchsia.sysmem.Allocator/AllocateSharedCollection) with |
| code:ZX_DEFAULT_CHANNEL_RIGHTS rights |
| **** |
| |
| include::{generated}/validity/structs/VkBufferCollectionCreateInfoFUCHSIA.txt[] |
| -- |
| |
| |
| === Set the constraints |
| Buffer collections can be established for slink:VkImage allocations or |
| slink:VkBuffer allocations. |
| |
| |
| ==== Set image-based buffer collection constraints |
| |
| [open,refpage='vkSetBufferCollectionImageConstraintsFUCHSIA',desc='Set image-based constraints for a buffer collection',type='protos'] |
| -- |
| Setting the constraints on the buffer collection initiates the format |
| negotiation and allocation of the buffer collection. |
| To set the constraints on a slink:VkImage buffer collection, call: |
| |
| include::{generated}/api/protos/vkSetBufferCollectionImageConstraintsFUCHSIA.txt[] |
| |
| * pname:device is the logical device |
| * pname:collection is the slink:VkBufferCollectionFUCHSIA handle |
| * pname:pImageConstraintsInfo is a pointer to a |
| slink:VkImageConstraintsInfoFUCHSIA structure |
| |
| fname:vkSetBufferCollectionImageConstraintsFUCHSIA may: fail if |
| pname:pImageConstraintsInfo::pname:formatConstraintsCount is larger than the |
| implementation-defined limit. |
| If that occurs, flink:vkSetBufferCollectionImageConstraintsFUCHSIA will |
| return VK_ERROR_INITIALIZATION_FAILED. |
| |
| fname:vkSetBufferCollectionImageConstraintsFUCHSIA may: fail if the |
| implementation does not support any of the formats described by the |
| pname:pImageConstraintsInfo structure. |
| If that occurs, flink:vkSetBufferCollectionImageConstraintsFUCHSIA will |
| return ename:VK_ERROR_FORMAT_NOT_SUPPORTED. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkSetBufferCollectionImageConstraintsFUCHSIA-collection-06394]] |
| fname:vkSetBufferCollectionImageConstraintsFUCHSIA or |
| fname:vkSetBufferCollectionBufferConstraintsFUCHSIA must: not have |
| already been called on pname:collection |
| **** |
| |
| include::{generated}/validity/protos/vkSetBufferCollectionImageConstraintsFUCHSIA.txt[] |
| -- |
| |
| [open,refpage='VkImageConstraintsInfoFUCHSIA',desc='Structure of image-based buffer collection constraints',type='structs'] |
| -- |
| The sname:VkImageConstraintsInfoFUCHSIA structure is defined as: |
| |
| include::{generated}/api/structs/VkImageConstraintsInfoFUCHSIA.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:formatConstraintsCount is the number of elements in |
| pname:pFormatConstraints. |
| * pname:pFormatConstraints is an array of |
| slink:VkImageFormatConstraintsInfoFUCHSIA structures of size |
| pname:formatConstraintsCount that is used to further constrain buffer |
| collection format selection for image-based buffer collections. |
| * pname:bufferCollectionConstraints is a |
| slink:VkBufferCollectionConstraintsInfoFUCHSIA structure used to supply |
| parameters for the negotiation and allocation for buffer-based buffer |
| collections. |
| * pname:flags is a elink:VkImageConstraintsInfoFlagBitsFUCHSIA value |
| specifying hints about the type of memory Sysmem should allocate for the |
| buffer collection. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06395]] |
| All elements of pname:pFormatConstraints must: have at least one bit set |
| in its |
| slink:VkImageFormatConstraintsInfoFUCHSIA::pname:requiredFormatFeatures |
| * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06396]] |
| If pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains |
| ename:VK_IMAGE_USAGE_SAMPLED_BIT, then |
| pname:pFormatConstraints::pname:requiredFormatFeatures must: contain |
| ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT |
| * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06397]] |
| If pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains |
| ename:VK_IMAGE_USAGE_STORAGE_BIT, then |
| pname:pFormatConstraints::pname:requiredFormatFeatures must: contain |
| ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT |
| * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06398]] |
| If pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains |
| ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, then |
| pname:pFormatConstraints::pname:requiredFormatFeatures must: contain |
| ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT |
| * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06399]] |
| If pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains |
| ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, then |
| pname:pFormatConstraints::pname:requiredFormatFeatures must: contain |
| ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * [[VUID-VkImageConstraintsInfoFUCHSIA-pFormatConstraints-06400]] |
| If pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains |
| ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, then |
| pname:pFormatConstraints::pname:requiredFormatFeatures must: contain at |
| least one of ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT or |
| ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT |
| ifdef::VK_KHR_fragment_shading_rate[] |
| * [[VUID-VkImageConstraintsInfoFUCHSIA-attachmentFragmentShadingRate-06401]] |
| If the <<features-attachmentFragmentShadingRate, |
| pname:attachmentFragmentShadingRate feature>> is enabled, and |
| pname:pFormatConstraints::pname:imageCreateInfo::pname:usage contains |
| ename:VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR, then |
| pname:pFormatConstraints::pname:requiredFormatFeatures must: contain |
| ename:VK_FORMAT_FEATURE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR |
| endif::VK_KHR_fragment_shading_rate[] |
| **** |
| |
| include::{generated}/validity/structs/VkImageConstraintsInfoFUCHSIA.txt[] |
| -- |
| |
| [open,refpage='VkImageConstraintsInfoFlagsFUCHSIA',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkImageConstraintsInfoFlagsFUCHSIA.txt[] |
| |
| tname:VkImageConstraintsInfoFlagsFUCHSIA is a bitmask type for setting a |
| mask of zero or more elink:VkImageConstraintsInfoFlagBitsFUCHSIA bits. |
| -- |
| |
| [open,refpage='VkImageConstraintsInfoFlagBitsFUCHSIA',desc='Bitmask specifying image constraints flags',type='enums'] |
| -- |
| Bits which can: be set in |
| elink:VkImageConstraintsInfoFlagBitsFUCHSIA::pname:flags include: |
| |
| include::{generated}/api/enums/VkImageConstraintsInfoFlagBitsFUCHSIA.txt[] |
| |
| General hints about the type of memory that should be allocated by Sysmem |
| based on the expected usage of the images in the buffer collection include: |
| |
| * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_RARELY_FUCHSIA |
| * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_READ_OFTEN_FUCHSIA |
| * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_RARELY_FUCHSIA |
| * ename:VK_IMAGE_CONSTRAINTS_INFO_CPU_WRITE_OFTEN_FUCHSIA |
| |
| For protected memory: |
| |
| * ename:VK_IMAGE_CONSTRAINTS_INFO_PROTECTED_OPTIONAL_FUCHSIA specifies |
| that protected memory is optional for the buffer collection. |
| |
| Note that if all participants in the buffer collection (Vulkan or otherwise) |
| specify that protected memory is optional, Sysmem will not allocate |
| protected memory. |
| -- |
| |
| [open,refpage='VkImageFormatConstraintsInfoFUCHSIA',desc='Structure image-based buffer collection constraints',type='structs'] |
| -- |
| The sname:VkImageFormatConstraintsInfoFUCHSIA structure is defined as: |
| |
| include::{generated}/api/structs/VkImageFormatConstraintsInfoFUCHSIA.txt[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:imageCreateInfo is the slink:VkImageCreateInfo used to create a |
| slink:VkImage that is to use memory from the |
| slink:VkBufferCollectionFUCHSIA |
| * pname:requiredFormatFeatures is a bitmask of |
| ename:VkFormatFeatureFlagBits specifying required features of the |
| buffers in the buffer collection |
| * pname:flags is reserved for future use |
| * pname:sysmemPixelFormat is a code:PixelFormatType value from the |
| `fuchsia.sysmem/image_formats.fidl` FIDL interface |
| * pname:colorSpaceCount the element count of pname:pColorSpaces |
| * pname:pColorSpaces is an array of slink:VkSysmemColorSpaceFUCHSIA |
| structs of size pname:colorSpaceCount |
| |
| include::{generated}/validity/structs/VkImageFormatConstraintsInfoFUCHSIA.txt[] |
| -- |
| |
| [open,refpage='VkImageFormatConstraintsFlagsFUCHSIA',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkImageFormatConstraintsFlagsFUCHSIA.txt[] |
| |
| tname:VkImageFormatConstraintsFlagsFUCHSIA is a bitmask type for setting a |
| mask, but is currently reserved for future use. |
| -- |
| |
| [open,refpage='VkBufferCollectionConstraintsInfoFUCHSIA',desc='Structure of general buffer collection constraints',type='structs'] |
| -- |
| The sname:VkBufferCollectionConstraintsInfoFUCHSIA structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferCollectionConstraintsInfoFUCHSIA.txt[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:minBufferCount is the minimum number of buffers available in the |
| collection |
| * pname:maxBufferCount is the maximum number of buffers allowed in the |
| collection |
| * pname:minBufferCountForCamping is the per-participant minimum buffers |
| for camping |
| * pname:minBufferCountForDedicatedSlack is the per-participant minimum |
| buffers for dedicated slack |
| * pname:minBufferCountForSharedSlack is the per-participant minimum |
| buffers for shared slack |
| |
| Sysmem uses all buffer count parameters in combination to determine the |
| number of buffers it will allocate. |
| Sysmem defines buffer count constraints in |
| `fuchsia.sysmem/constraints.fidl`. |
| |
| _Camping_ as referred to by pname:minBufferCountForCamping, is the number of |
| buffers that should be available for the participant that are not for |
| transient use. |
| This number of buffers is required for the participant to logically operate. |
| |
| _Slack_ as referred to by pname:minBufferCountForDedicatedSlack and |
| pname:minBufferCountForSharedSlack, refers to the number of buffers desired |
| by participants for optimal performance. |
| pname:minBufferCountForDedicatedSlack refers to the current participant. |
| pname:minBufferCountForSharedSlack refers to buffer slack for all |
| participants in the collection. |
| |
| include::{generated}/validity/structs/VkBufferCollectionConstraintsInfoFUCHSIA.txt[] |
| -- |
| |
| [open,refpage='VkSysmemColorSpaceFUCHSIA',desc='Structure describing the buffer collections color space',type='structs'] |
| -- |
| |
| The sname:VkSysmemColorSpaceFUCHSIA structure is defined as: |
| |
| include::{generated}/api/structs/VkSysmemColorSpaceFUCHSIA.txt[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:colorSpace value of the Sysmem code:ColorSpaceType |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkSysmemColorSpaceFUCHSIA-colorSpace-06402]] |
| pname:colorSpace must: be a code:ColorSpaceType as defined in |
| `fuchsia.sysmem/image_formats.fidl` |
| **** |
| |
| include::{generated}/validity/structs/VkSysmemColorSpaceFUCHSIA.txt[] |
| -- |
| |
| |
| ==== Set buffer-based buffer collection constraints |
| |
| [open,refpage='vkSetBufferCollectionBufferConstraintsFUCHSIA',desc='Set buffer-based constraints for a buffer collection',type='protos'] |
| -- |
| To set the constraints on a slink:VkBuffer buffer collection, call: |
| |
| include::{generated}/api/protos/vkSetBufferCollectionBufferConstraintsFUCHSIA.txt[] |
| |
| * pname:device is the logical device |
| * pname:collection is the slink:VkBufferCollectionFUCHSIA handle |
| * pname:pBufferConstraintsInfo is a pointer to a |
| slink:VkBufferConstraintsInfoFUCHSIA structure |
| |
| fname:vkSetBufferCollectionBufferConstraintsFUCHSIA may: fail if the |
| implementation does not support the constraints specified in the |
| pname:bufferCollectionConstraints structure. |
| If that occurs, flink:vkSetBufferCollectionBufferConstraintsFUCHSIA will |
| return ename:VK_ERROR_FORMAT_NOT_SUPPORTED. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkSetBufferCollectionBufferConstraintsFUCHSIA-collection-06403]] |
| fname:vkSetBufferCollectionImageConstraintsFUCHSIA or |
| fname:vkSetBufferCollectionBufferConstraintsFUCHSIA must: not have |
| already been called on pname:collection |
| **** |
| |
| include::{generated}/validity/protos/vkSetBufferCollectionBufferConstraintsFUCHSIA.txt[] |
| -- |
| |
| [open,refpage='VkBufferConstraintsInfoFUCHSIA',desc='Structure buffer-based buffer collection constraints',type='structs'] |
| -- |
| The sname:VkBufferConstraintsInfoFUCHSIA structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferConstraintsInfoFUCHSIA.txt[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:pBufferCreateInfo a pointer to a slink:VkBufferCreateInfo struct |
| describing the buffer attributes for the buffer collection |
| * pname:requiredFormatFeatures bitmask of ename:VkFormatFeatureFlagBits |
| required features of the buffers in the buffer collection |
| * pname:bufferCollectionConstraints is used to supply parameters for the |
| negotiation and allocation of the buffer collection |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkBufferConstraintsInfoFUCHSIA-requiredFormatFeatures-06404]] |
| The pname:requiredFormatFeatures bitmask of |
| ename:VkFormatFeatureFlagBits must: be chosen from among the buffer |
| compatible format features listed in |
| <<buffer-compatible-format-features,buffer compatible format features>> |
| **** |
| |
| include::{generated}/validity/structs/VkBufferConstraintsInfoFUCHSIA.txt[] |
| -- |
| |
| |
| === Retrieve buffer collection properties |
| |
| [open,refpage='vkGetBufferCollectionPropertiesFUCHSIA',desc='Retrieve properties from a buffer collection',type='protos'] |
| -- |
| After constraints have been set on the buffer collection by calling |
| flink:vkSetBufferCollectionImageConstraintsFUCHSIA or |
| flink:vkSetBufferCollectionBufferConstraintsFUCHSIA, call |
| fname:vkGetBufferCollectionPropertiesFUCHSIA to retrieve the negotiated and |
| finalized properties of the buffer collection. |
| |
| The call to fname:vkGetBufferCollectionPropertiesFUCHSIA is synchronous. |
| It waits for the Sysmem format negotiation and buffer collection allocation |
| to complete before returning. |
| |
| include::{generated}/api/protos/vkGetBufferCollectionPropertiesFUCHSIA.txt[] |
| |
| * pname:device is the logical device handle |
| * pname:collection is the slink:VkBufferCollectionFUCHSIA handle |
| * pname:pProperties is a pointer to the retrieved |
| slink:VkBufferCollectionPropertiesFUCHSIA struct |
| |
| [[sysmem-chosen-create-infos]] |
| For image-based buffer collections, upon calling |
| fname:vkGetBufferCollectionPropertiesFUCHSIA, Sysmem will choose an element |
| of the slink:VkImageConstraintsInfoFUCHSIA::pname:pImageCreateInfos |
| established by the preceding call to |
| flink:vkSetBufferCollectionImageConstraintsFUCHSIA. |
| The index of the element chosen is stored in and can be retrieved from |
| slink:VkBufferCollectionPropertiesFUCHSIA::pname:createInfoIndex. |
| |
| For buffer-based buffer collections, a single slink:VkBufferCreateInfo is |
| specified as slink:VkBufferConstraintsInfoFUCHSIA::pname:createInfo. |
| slink:VkBufferCollectionPropertiesFUCHSIA::pname:createInfoIndex will |
| therefore always be zero. |
| |
| fname:vkGetBufferCollectionPropertiesFUCHSIA may: fail if Sysmem is unable |
| to resolve the constraints of all of the participants in the buffer |
| collection. |
| If that occurs, fname:vkGetBufferCollectionPropertiesFUCHSIA will return |
| ename:VK_ERROR_INITIALIZATION_FAILED. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetBufferCollectionPropertiesFUCHSIA-None-06405]] |
| Prior to calling flink:vkGetBufferCollectionPropertiesFUCHSIA, the |
| constraints on the buffer collection must: have been set by either |
| flink:vkSetBufferCollectionImageConstraintsFUCHSIA or |
| flink:vkSetBufferCollectionBufferConstraintsFUCHSIA. |
| **** |
| |
| include::{generated}/validity/protos/vkGetBufferCollectionPropertiesFUCHSIA.txt[] |
| -- |
| |
| [open,refpage='VkBufferCollectionPropertiesFUCHSIA',desc='Structure specifying the negotiated format chosen by Sysmem',type='structs'] |
| -- |
| |
| The sname:VkBufferCollectionPropertiesFUCHSIA structure is defined as: |
| |
| include::{generated}/api/structs/VkBufferCollectionPropertiesFUCHSIA.txt[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:memoryTypeBits is a bitmask containing one bit set for every |
| memory type which the buffer collection can be imported as buffer |
| collection |
| * pname:bufferCount is the number of buffers in the collection |
| * pname:createInfoIndex as described in <<sysmem-chosen-create-infos, |
| Sysmem chosen create infos>> |
| * pname:sysmemPixelFormat is the Sysmem code:PixelFormatType as defined in |
| `fuchsia.sysmem/image_formats.fidl` |
| * pname:formatFeatures is a bitmask of elink:VkFormatFeatureFlagBits |
| shared by the buffer collection |
| * pname:sysmemColorSpaceIndex is a slink:VkSysmemColorSpaceFUCHSIA struct |
| specifying the color space |
| * pname:samplerYcbcrConversionComponents is a slink:VkComponentMapping |
| struct specifying the component mapping |
| * pname:suggestedYcbcrModel is a elink:VkSamplerYcbcrModelConversion value |
| specifying the suggested {YCbCr} model |
| * pname:suggestedYcbcrRange is a elink:VkSamplerYcbcrRange value |
| specifying the suggested {YCbCr} range |
| * pname:suggestedXChromaOffset is a elink:VkChromaLocation value |
| specifying the suggested X chroma offset |
| * pname:suggestedYChromaOffset is a elink:VkChromaLocation value |
| specifying the suggested Y chroma offset |
| |
| pname:sysmemColorSpace is only set for image-based buffer collections where |
| the constraints were specified using slink:VkImageConstraintsInfoFUCHSIA in |
| a call to flink:vkSetBufferCollectionImageConstraintsFUCHSIA. |
| |
| For image-based buffer collections, pname:createInfoIndex will identify both |
| the slink:VkImageConstraintsInfoFUCHSIA::pname:pImageCreateInfos element and |
| the slink:VkImageConstraintsInfoFUCHSIA::pname:pFormatConstraints element |
| chosen by Sysmem when flink:vkSetBufferCollectionImageConstraintsFUCHSIA was |
| called. |
| The value of pname:sysmemColorSpaceIndex will be an index to one of the |
| color spaces provided in the |
| slink:VkImageFormatConstraintsInfoFUCHSIA::pname:pColorSpaces array. |
| |
| The implementation must have pname:formatFeatures with all bits set that |
| were set in |
| slink:VkImageFormatConstraintsInfoFUCHSIA::pname:requiredFormatFeatures, by |
| the call to flink:vkSetBufferCollectionImageConstraintsFUCHSIA, at |
| pname:createInfoIndex (other bits could be set as well). |
| |
| include::{generated}/validity/structs/VkBufferCollectionPropertiesFUCHSIA.txt[] |
| -- |
| |
| |
| === Memory allocation |
| |
| To import memory from a buffer collection into a slink:VkImage or a |
| slink:VkBuffer, chain a slink:VkImportMemoryBufferCollectionFUCHSIA |
| structure to the pname:pNext member of the slink:VkMemoryAllocateInfo in the |
| call to flink:vkAllocateMemory. |
| |
| [open,refpage='VkImportMemoryBufferCollectionFUCHSIA',desc='Structure to specify the Sysmem buffer to import',type='structs'] |
| -- |
| The sname:VkImportMemoryBufferCollectionFUCHSIA structure is defined as: |
| |
| include::{generated}/api/structs/VkImportMemoryBufferCollectionFUCHSIA.txt[] |
| |
| * pname:sType is the type of this structure |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure |
| * pname:collection is the slink:VkBufferCollectionFUCHSIA handle |
| * pname:index the index of the buffer to import from pname:collection |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkImportMemoryBufferCollectionFUCHSIA-index-06406]] |
| pname:index must: be less than the value retrieved as |
| slink:VkBufferCollectionPropertiesFUCHSIA:bufferCount |
| **** |
| |
| include::{generated}/validity/structs/VkImportMemoryBufferCollectionFUCHSIA.txt[] |
| -- |
| |
| [open,refpage='vkDestroyBufferCollectionFUCHSIA',desc='Destroy a buffer collection',type='protos'] |
| -- |
| To release a slink:VkBufferCollectionFUCHSIA: |
| |
| include::{generated}/api/protos/vkDestroyBufferCollectionFUCHSIA.txt[] |
| |
| * pname:device is the logical device that creates the |
| sname:VkBufferCollectionFUCHSIA |
| * pname:collection is the slink:VkBufferCollectionFUCHSIA handle |
| * pname:pAllocator is a pointer to a slink:VkAllocationCallbacks structure |
| which controls host memory allocation as described in the |
| <<memory-allocation, Memory Allocation>> chapter |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkDestroyBufferCollectionFUCHSIA-collection-06407]] |
| slink:VkImage and slink:VkBuffer objects that referenced |
| pname:collection upon creation by inclusion of a |
| slink:VkBufferCollectionImageCreateInfoFUCHSIA or |
| slink:VkBufferCollectionBufferCreateInfoFUCHSIA chained to their |
| slink:VkImageCreateInfo or slink:VkBufferCreateInfo structures |
| respectively, may: outlive pname:collection. |
| **** |
| |
| include::{generated}/validity/protos/vkDestroyBufferCollectionFUCHSIA.txt[] |
| -- |
| endif::VK_FUCHSIA_buffer_collection[] |
