3194 lines
141 KiB
Plaintext
3194 lines
141 KiB
Plaintext
// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/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::../api/handles/VkBuffer.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='vkCreateBuffer',desc='Create a new buffer object',type='protos']
|
|
--
|
|
|
|
To create buffers, call:
|
|
|
|
include::../api/protos/vkCreateBuffer.txt[]
|
|
|
|
* pname:device is the logical device that creates the buffer object.
|
|
* pname:pCreateInfo is a pointer to an instance of the
|
|
sname: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 points to a sname: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
|
|
****
|
|
|
|
include::../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::../api/structs/VkBufferCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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 list of queue families that will access
|
|
this buffer (ignored if pname:sharingMode is not
|
|
ename:VK_SHARING_MODE_CONCURRENT).
|
|
|
|
ifdef::editing-notes[]
|
|
[NOTE]
|
|
.editing-note
|
|
==================
|
|
(Jon) Should the constraint on usage != 0 be converted to a Valid Usage
|
|
statement? See gitlab #854.
|
|
==================
|
|
endif::editing-notes[]
|
|
|
|
.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 pointer to an array of
|
|
pname:queueFamilyIndexCount basetype: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_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_KHR_get_physical_device_properties2[]
|
|
ifdef::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:vkGetPhysicalDeviceQueueFamilyProperties2KHR for the
|
|
pname:physicalDevice that was used to create pname:device
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
* [[VUID-VkBufferCreateInfo-flags-00915]]
|
|
If the <<features-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-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-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_KHR_external_memory[]
|
|
* [[VUID-VkBufferCreateInfo-pNext-00920]]
|
|
If the pname:pNext chain contains an instance of
|
|
slink:VkExternalMemoryBufferCreateInfoKHR, its pname:handleTypes member
|
|
must: only contain bits that are also in
|
|
slink:VkExternalBufferPropertiesKHR::pname:externalMemoryProperties.pname:compatibleHandleTypes,
|
|
as returned by flink:vkGetPhysicalDeviceExternalBufferPropertiesKHR with
|
|
pname:pExternalBufferInfo->pname:handleType equal to any one of the
|
|
handle types specified in
|
|
slink:VkExternalMemoryBufferCreateInfoKHR::pname:handleTypes
|
|
endif::VK_KHR_external_memory[]
|
|
****
|
|
|
|
include::../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::../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
|
|
fname: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
|
|
fname:vkCmdBindVertexBuffers.
|
|
* ename:VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT specifies that the buffer is
|
|
suitable for passing as the pname:buffer parameter to
|
|
fname:vkCmdDrawIndirect, fname:vkCmdDrawIndexedIndirect, or
|
|
fname:vkCmdDispatchIndirect.
|
|
ifdef::VK_NVX_device_generated_commands[]
|
|
It is also suitable for passing as the pname:buffer member of
|
|
sname:VkIndirectCommandsTokenNVX, or pname:sequencesCountBuffer or
|
|
pname:sequencesIndexBuffer member of sname:VkCmdProcessCommandsInfoNVX
|
|
endif::VK_NVX_device_generated_commands[]
|
|
|
|
--
|
|
|
|
[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::../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.
|
|
|
|
See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and
|
|
<<features-features,Physical Device Features>> for details of the sparse
|
|
memory features supported on a device.
|
|
|
|
--
|
|
|
|
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 list 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::../api/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:dedicatedAllocation indicates whether the buffer will have a
|
|
dedicated allocation bound to it.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkDedicatedAllocationBufferCreateInfoNV-dedicatedAllocation-00921]]
|
|
If pname:dedicatedAllocation is ename:VK_TRUE,
|
|
sname:VkBufferCreateInfo::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
|
|
****
|
|
|
|
include::../validity/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[]
|
|
--
|
|
|
|
endif::VK_NV_dedicated_allocation[]
|
|
|
|
ifdef::VK_KHR_external_memory[]
|
|
|
|
[open,refpage='VkExternalMemoryBufferCreateInfoKHR',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:VkExternalMemoryBufferCreateInfoKHR
|
|
structure to the pname:pNext chain of the slink:VkBufferCreateInfo
|
|
structure.
|
|
The sname:VkExternalMemoryBufferCreateInfoKHR structure is defined as:
|
|
|
|
include::../api/structs/VkExternalMemoryBufferCreateInfoKHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:handleTypes is a bitmask of
|
|
elink:VkExternalMemoryHandleTypeFlagBitsKHR specifying one or more
|
|
external memory handle types.
|
|
|
|
include::../validity/structs/VkExternalMemoryBufferCreateInfoKHR.txt[]
|
|
--
|
|
|
|
endif::VK_KHR_external_memory[]
|
|
|
|
[open,refpage='vkDestroyBuffer',desc='Destroy a buffer object',type='protos']
|
|
--
|
|
|
|
To destroy a buffer, call:
|
|
|
|
include::../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::../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::../api/handles/VkBufferView.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='vkCreateBufferView',desc='Create a new buffer view object',type='protos']
|
|
--
|
|
|
|
To create a buffer view, call:
|
|
|
|
include::../api/protos/vkCreateBufferView.txt[]
|
|
|
|
* pname:device is the logical device that creates the buffer view.
|
|
* pname:pCreateInfo is a pointer to an instance of the
|
|
sname:VkBufferViewCreateInfo structure containing parameters to be used
|
|
to create the buffer.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pView points to a sname:VkBufferView handle in which the resulting
|
|
buffer view object is returned.
|
|
|
|
include::../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::../api/structs/VkBufferViewCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is reserved for future use.
|
|
* pname:buffer is a sname: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 element size of pname:format, then the nearest
|
|
smaller multiple is used.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBufferViewCreateInfo-offset-00925]]
|
|
pname:offset must: be less than the size of pname:buffer
|
|
* [[VUID-VkBufferViewCreateInfo-offset-00926]]
|
|
pname:offset must: be a multiple of
|
|
sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment
|
|
* [[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
|
|
a multiple of the element size of pname:format
|
|
* [[VUID-VkBufferViewCreateInfo-range-00930]]
|
|
If pname:range is not equal to ename:VK_WHOLE_SIZE, pname:range divided
|
|
by the element size of 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-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
|
|
fname: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
|
|
fname: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
|
|
****
|
|
|
|
include::../validity/structs/VkBufferViewCreateInfo.txt[]
|
|
--
|
|
|
|
[open,refpage='vkDestroyBufferView',desc='Destroy a buffer view object',type='protos']
|
|
--
|
|
|
|
To destroy a buffer view, call:
|
|
|
|
include::../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::../validity/protos/vkDestroyBufferView.txt[]
|
|
--
|
|
|
|
|
|
[[resources-images]]
|
|
== Images
|
|
|
|
[open,refpage='VkImage',desc='Opaque handle to a 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::../api/handles/VkImage.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='vkCreateImage',desc='Create a new image object',type='protos']
|
|
--
|
|
|
|
To create images, call:
|
|
|
|
include::../api/protos/vkCreateImage.txt[]
|
|
|
|
* pname:device is the logical device that creates the image.
|
|
* pname:pCreateInfo is a pointer to an instance of the
|
|
sname: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 points to a sname: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
|
|
****
|
|
|
|
include::../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::../api/structs/VkImageCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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
|
|
data elements 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 the number of sub-data element samples in the image as
|
|
defined in elink:VkSampleCountFlagBits.
|
|
See <<primsrast-multisampling,Multisampling>>.
|
|
* pname:tiling is a elink:VkImageTiling value specifying the tiling
|
|
arrangement of the data elements 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 list of queue families that will access
|
|
this image (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
|
|
|
|
Implementations may: support additional limits and capabilities beyond those
|
|
listed above.
|
|
|
|
To query an implementation's specific capabilities for a given combination
|
|
of pname:format, pname:imageType, pname:tiling, pname:usage,
|
|
ifdef::VK_KHR_external_memory_capabilities[]
|
|
slink:VkExternalMemoryImageCreateInfoKHR::pname:handleTypes
|
|
endif::VK_KHR_external_memory_capabilities[]
|
|
and pname:flags, call
|
|
ifdef::VK_KHR_get_physical_device_properties2[]
|
|
flink:vkGetPhysicalDeviceImageFormatProperties2KHR.
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
ifndef::VK_KHR_get_physical_device_properties2[]
|
|
flink:vkGetPhysicalDeviceImageFormatProperties.
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
The return value indicates whether that combination of image settings is
|
|
supported.
|
|
On success, the sname:VkImageFormatProperties output parameter indicates the
|
|
set of valid pname:samples bits and the limits for pname:extent,
|
|
pname:mipLevels, and pname:arrayLayers.
|
|
|
|
To determine the set of valid pname:usage bits for a given format, call
|
|
flink:vkGetPhysicalDeviceFormatProperties.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageCreateInfo-format-00940]]
|
|
The combination of pname:format, pname:imageType, pname:tiling,
|
|
pname:usage, and pname:flags must: be supported, as indicated by a
|
|
ename:VK_SUCCESS return value from
|
|
fname:vkGetPhysicalDeviceImageFormatProperties invoked with the same
|
|
values passed to the corresponding parameters.
|
|
* [[VUID-VkImageCreateInfo-sharingMode-00941]]
|
|
If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT,
|
|
pname:pQueueFamilyIndices must: be a pointer to an array of
|
|
pname:queueFamilyIndexCount basetype: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_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_KHR_get_physical_device_properties2[]
|
|
ifdef::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:vkGetPhysicalDeviceQueueFamilyProperties2KHR for the
|
|
pname:physicalDevice that was used to create pname:device
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
* [[VUID-VkImageCreateInfo-format-00943]]
|
|
pname:format must: not be ename:VK_FORMAT_UNDEFINED
|
|
* [[VUID-VkImageCreateInfo-extent-00944]]
|
|
pname:extent::pname:width must: be greater than `0`.
|
|
* [[VUID-VkImageCreateInfo-extent-00945]]
|
|
pname:extent::pname:height must: be greater than `0`.
|
|
* [[VUID-VkImageCreateInfo-extent-00946]]
|
|
pname:extent::pname: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_KHR_maintenance1[]
|
|
* [[VUID-VkImageCreateInfo-flags-00950]]
|
|
If pname:flags contains
|
|
ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR, pname:imageType must:
|
|
be ename:VK_IMAGE_TYPE_3D
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageCreateInfo-imageType-00951]]
|
|
If pname:imageType is ename:VK_IMAGE_TYPE_1D, pname:extent.width must:
|
|
be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxImageDimension1D, or
|
|
sname:VkImageFormatProperties::pname:maxExtent.width (as returned by
|
|
fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
|
|
pname:imageType, pname:tiling, pname:usage, and pname:flags equal to
|
|
those in this structure) - whichever is higher
|
|
* [[VUID-VkImageCreateInfo-imageType-00952]]
|
|
If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags does not
|
|
contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width
|
|
and pname:extent.height must: be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxImageDimension2D, or
|
|
sname:VkImageFormatProperties::pname:maxExtent.width/height (as returned
|
|
by fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
|
|
pname:imageType, pname:tiling, pname:usage, and pname:flags equal to
|
|
those in this structure) - whichever is higher
|
|
* [[VUID-VkImageCreateInfo-imageType-00953]]
|
|
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 less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxImageDimensionCube, or
|
|
sname:VkImageFormatProperties::pname:maxExtent.width/height (as returned
|
|
by fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
|
|
pname:imageType, pname:tiling, pname:usage, and pname:flags equal to
|
|
those in this structure) - whichever is higher
|
|
* [[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-00955]]
|
|
If pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:extent.width,
|
|
pname:extent.height and pname:extent.depth must: be less than or equal
|
|
to sname:VkPhysicalDeviceLimits::pname:maxImageDimension3D, or
|
|
sname:VkImageFormatProperties::pname:maxExtent.width/height/depth (as
|
|
returned by fname:vkGetPhysicalDeviceImageFormatProperties with
|
|
pname:format, pname:imageType, pname:tiling, pname:usage, and
|
|
pname:flags equal to those in this structure) - whichever is higher
|
|
* [[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
|
|
[eq]#{lfloor}log~2~(max(pname:extent.width, pname:extent.height,
|
|
pname:extent.depth)){rfloor} {plus} 1#.
|
|
* [[VUID-VkImageCreateInfo-extent-00959]]
|
|
If any of pname:extent.width, pname:extent.height, or pname:extent.depth
|
|
are greater than the equivalently named members of
|
|
sname:VkPhysicalDeviceLimits::pname:maxImageDimension3D, pname:mipLevels
|
|
must: be less than or equal to
|
|
sname:VkImageFormatProperties::pname:maxMipLevels (as returned by
|
|
fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
|
|
pname:imageType, pname:tiling, pname:usage, and pname:flags equal to
|
|
those in this structure)
|
|
* [[VUID-VkImageCreateInfo-arrayLayers-00960]]
|
|
pname:arrayLayers must: be less than or equal to
|
|
sname:VkImageFormatProperties::pname:maxArrayLayers (as returned by
|
|
fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
|
|
pname:imageType, pname:tiling, pname:usage, and pname:flags equal to
|
|
those in this structure)
|
|
* [[VUID-VkImageCreateInfo-imageType-00961]]
|
|
If pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:arrayLayers must: be
|
|
`1`.
|
|
* [[VUID-VkImageCreateInfo-samples-00962]]
|
|
If pname:samples is not ename:VK_SAMPLE_COUNT_1_BIT, pname:imageType
|
|
must: be ename:VK_IMAGE_TYPE_2D, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:tiling must: be
|
|
ename:VK_IMAGE_TILING_OPTIMAL, and pname:mipLevels must: be equal to `1`
|
|
* [[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
|
|
* [[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-00967]]
|
|
pname:samples must: be a bit value that is set in
|
|
sname:VkImageFormatProperties::pname:sampleCounts returned by
|
|
fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
|
|
pname:imageType, pname:tiling, pname:usage, and pname:flags equal to
|
|
those in this structure
|
|
* [[VUID-VkImageCreateInfo-usage-00968]]
|
|
If the <<features-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-features-sparseBinding,sparse bindings>> feature is
|
|
not enabled, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_BINDING_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-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-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-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-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-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-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-tiling-00977]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, pname:format must: be a
|
|
format that has at least one supported feature bit present in the value
|
|
of sname:VkFormatProperties::pname:linearTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageCreateInfo-tiling-00978]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, and
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT, pname:usage must: not contain
|
|
ename:VK_IMAGE_USAGE_SAMPLED_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00979]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, and
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT, pname:usage must: not contain
|
|
ename:VK_IMAGE_USAGE_STORAGE_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00980]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, and
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, pname:usage must: not
|
|
contain ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00981]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, and
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, pname:usage must:
|
|
not contain ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00982]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, pname:format must: be
|
|
a format that has at least one supported feature bit present in the
|
|
value of sname:VkFormatProperties::pname:optimalTilingFeatures returned
|
|
by fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageCreateInfo-tiling-00983]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT, pname:usage must: not contain
|
|
ename:VK_IMAGE_USAGE_SAMPLED_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00984]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT, pname:usage must: not contain
|
|
ename:VK_IMAGE_USAGE_STORAGE_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00985]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, pname:usage must: not
|
|
contain ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00986]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, pname:usage must:
|
|
not contain ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_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
|
|
ifdef::VK_NV_external_memory+VK_KHR_external_memory[]
|
|
* [[VUID-VkImageCreateInfo-pNext-00988]]
|
|
If the pname:pNext chain contains an instance of
|
|
slink:VkExternalMemoryImageCreateInfoNV, it must: not contain an
|
|
instance of slink:VkExternalMemoryImageCreateInfoKHR.
|
|
endif::VK_NV_external_memory+VK_KHR_external_memory[]
|
|
ifdef::VK_KHR_external_memory[]
|
|
* [[VUID-VkImageCreateInfo-pNext-00990]]
|
|
If the pname:pNext chain contains an instance of
|
|
slink:VkExternalMemoryImageCreateInfoKHR, its pname:handleTypes member
|
|
must: only contain bits that are also in
|
|
slink:VkExternalImageFormatPropertiesKHR::pname:externalMemoryProperties::pname:compatibleHandleTypes,
|
|
as returned by flink:vkGetPhysicalDeviceImageFormatProperties2KHR with
|
|
pname:format, pname:imageType, pname:tiling, pname:usage, and
|
|
pname:flags equal to those in this structure, and with an instance of
|
|
slink:VkPhysicalDeviceExternalImageFormatInfoKHR in the pname:pNext
|
|
chain, with a pname:handleType equal to any one of the handle types
|
|
specified in slink:VkExternalMemoryImageCreateInfoKHR::pname:handleTypes
|
|
endif::VK_KHR_external_memory[]
|
|
ifdef::VK_NV_external_memory+VK_NV_external_memory_capabilities[]
|
|
* [[VUID-VkImageCreateInfo-pNext-00991]]
|
|
If the pname:pNext chain contains an instance of
|
|
slink:VkExternalMemoryImageCreateInfoNV, its pname:handleTypes member
|
|
must: only contain bits that are also in
|
|
slink:VkExternalImageFormatPropertiesNV::pname:externalMemoryProperties::pname: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_KHX_device_group[]
|
|
* [[VUID-VkImageCreateInfo-physicalDeviceCount-01421]]
|
|
If the logical device was created with
|
|
slink:VkDeviceGroupDeviceCreateInfoKHX::pname:physicalDeviceCount equal
|
|
to 1, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX
|
|
* [[VUID-VkImageCreateInfo-flags-00992]]
|
|
If pname:flags contains ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX, then
|
|
pname:mipLevels must: be one, pname:arrayLayers must: be one,
|
|
pname:imageType must: be ename:VK_IMAGE_TYPE_2D, and pname:tiling must:
|
|
be ename:VK_IMAGE_TILING_OPTIMAL
|
|
endif::VK_KHX_device_group[]
|
|
* [[VUID-VkImageCreateInfo-initialLayout-00993]]
|
|
pname:initialLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or
|
|
ename:VK_IMAGE_LAYOUT_PREINITIALIZED.
|
|
ifdef::VK_KHR_external_memory,VK_NV_external_memory[]
|
|
* [[VUID-VkImageCreateInfo-pNext-01443]]
|
|
If the pname:pNext chain includes a
|
|
ifdef::VK_KHR_external_memory[slink:VkExternalMemoryImageCreateInfoKHR]
|
|
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`, pname:initialLayout
|
|
must: be ename:VK_IMAGE_LAYOUT_UNDEFINED
|
|
endif::VK_KHR_external_memory,VK_NV_external_memory[]
|
|
****
|
|
|
|
include::../validity/structs/VkImageCreateInfo.txt[]
|
|
--
|
|
|
|
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 list 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::../api/structs/VkDedicatedAllocationImageCreateInfoNV.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:dedicatedAllocation indicates 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,
|
|
sname: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::../validity/structs/VkDedicatedAllocationImageCreateInfoNV.txt[]
|
|
--
|
|
|
|
endif::VK_NV_dedicated_allocation[]
|
|
|
|
ifdef::VK_KHR_external_memory[]
|
|
|
|
[open,refpage='VkExternalMemoryImageCreateInfoKHR',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:VkExternalMemoryImageCreateInfoKHR structure
|
|
to the pname:pNext chain of the slink:VkImageCreateInfo structure.
|
|
The sname:VkExternalMemoryImageCreateInfoKHR structure is defined as:
|
|
|
|
include::../api/structs/VkExternalMemoryImageCreateInfoKHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:handleTypes is a bitmask of
|
|
elink:VkExternalMemoryHandleTypeFlagBitsKHR specifying one or more
|
|
external memory handle types.
|
|
|
|
include::../validity/structs/VkExternalMemoryImageCreateInfoKHR.txt[]
|
|
--
|
|
|
|
endif::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 list 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::../api/structs/VkExternalMemoryImageCreateInfoNV.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:handleTypes is a bitmask of
|
|
elink:VkExternalMemoryHandleTypeFlagBitsNV specifying one or more
|
|
external memory handle types.
|
|
|
|
include::../validity/structs/VkExternalMemoryImageCreateInfoNV.txt[]
|
|
--
|
|
|
|
endif::VK_NV_external_memory[]
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
[open,refpage='VkImageSwapchainCreateInfoKHX',desc='Specify that an image will be bound to swapchain memory',type='structs']
|
|
--
|
|
|
|
If the pname:pNext list of slink:VkImageCreateInfo includes a
|
|
sname:VkImageSwapchainCreateInfoKHX structure, then that structure includes
|
|
a swapchain handle indicating that the image will be bound to memory from
|
|
that swapchain.
|
|
|
|
The sname:VkImageSwapchainCreateInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkImageSwapchainCreateInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:swapchain is dlink:VK_NULL_HANDLE or a handle of a swapchain that
|
|
the image will be bound to.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageSwapchainCreateInfoKHX-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::../validity/structs/VkImageSwapchainCreateInfoKHX.txt[]
|
|
--
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
[open,refpage='VkImageUsageFlagBits',desc='Bitmask specifying intended usage of an image',type='enums']
|
|
--
|
|
|
|
Bits which can: be set in slink:VkImageCreateInfo::pname:usage, specifying
|
|
intended usage of an image, are:
|
|
|
|
include::../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 attachment in a sname:VkFramebuffer.
|
|
* ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT specifies that the memory
|
|
bound to this image will have been allocated with the
|
|
ename:VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT (see <<memory>> for more
|
|
detail).
|
|
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.
|
|
|
|
--
|
|
|
|
[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::../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.
|
|
* 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_KHR_maintenance1[]
|
|
* ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR 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_KHR_maintenance1[]
|
|
ifdef::VK_KHX_device_group[]
|
|
* ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX specifies that the image can: be
|
|
used with a non-zero value of the pname:SFRRectCount member of the
|
|
slink:VkBindImageMemoryInfoKHX structure passed into
|
|
flink:vkBindImageMemory2KHX.
|
|
This flag also has the effect of making the image use the standard
|
|
sparse image block dimensions.
|
|
endif::VK_KHX_device_group[]
|
|
|
|
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.
|
|
|
|
See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and
|
|
<<sparsememory-physicalfeatures,Sparse Physical Device Features>> for more
|
|
details.
|
|
|
|
--
|
|
|
|
[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::../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 data elements in an image, are:
|
|
|
|
include::../api/enums/VkImageTiling.txt[]
|
|
|
|
* ename:VK_IMAGE_TILING_OPTIMAL specifies optimal tiling (texels are laid
|
|
out in an implementation-dependent arrangement, for more optimal 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).
|
|
|
|
--
|
|
|
|
[open,refpage='vkGetImageSubresourceLayout',desc='Retrieve information about an image subresource',type='protos']
|
|
--
|
|
|
|
To query the host access layout of an image subresource, for an image
|
|
created with linear tiling, call:
|
|
|
|
include::../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 points to a slink:VkSubresourceLayout structure in which
|
|
the layout is returned.
|
|
|
|
flink:vkGetImageSubresourceLayout is invariant for the lifetime of a single
|
|
image.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkGetImageSubresourceLayout-image-00996]]
|
|
pname:image must: have been created with pname:tiling equal to
|
|
ename:VK_IMAGE_TILING_LINEAR
|
|
* [[VUID-vkGetImageSubresourceLayout-aspectMask-00997]]
|
|
The pname:aspectMask member of pname:pSubresource must: only have a
|
|
single bit set
|
|
****
|
|
|
|
include::../validity/protos/vkGetImageSubresourceLayout.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageSubresource',desc='Structure specifying a image subresource',type='structs']
|
|
--
|
|
|
|
The sname:VkImageSubresource structure is defined as:
|
|
|
|
include::../api/structs/VkImageSubresource.txt[]
|
|
|
|
* pname:aspectMask is a elink:VkImageAspectFlags selecting the image
|
|
_aspect_.
|
|
* pname:mipLevel selects the mipmap level.
|
|
* pname:arrayLayer selects the array layer.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageSubresource-mipLevel-00998]]
|
|
pname:mipLevel must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when the image was created
|
|
* [[VUID-VkImageSubresource-arrayLayer-00999]]
|
|
pname:arrayLayer must: be less than the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when the image was created
|
|
****
|
|
|
|
include::../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::../api/structs/VkSubresourceLayout.txt[]
|
|
|
|
* pname:offset is the byte offset from the start of the image 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.
|
|
|
|
For images created with linear tiling, 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;
|
|
---------------------------------------------------
|
|
|
|
pname:arrayPitch is undefined for images that were not created as arrays.
|
|
pname:depthPitch is defined only for 3D images.
|
|
|
|
For color formats, the pname:aspectMask member of sname:VkImageSubresource
|
|
must: be ename:VK_IMAGE_ASPECT_COLOR_BIT.
|
|
For depth/stencil formats, 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.
|
|
|
|
include::../validity/structs/VkSubresourceLayout.txt[]
|
|
--
|
|
|
|
[open,refpage='vkDestroyImage',desc='Destroy an image object',type='protos']
|
|
--
|
|
|
|
To destroy an image, call:
|
|
|
|
include::../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`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyImage.txt[]
|
|
--
|
|
|
|
|
|
[[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
|
|
fname:vkCmdPipelineBarrier or a fname:vkCmdWaitEvents command buffer command
|
|
(see <<synchronization-image-memory-barriers>>), or as part of a subpass
|
|
dependency within a render pass (see sname:VkSubpassDependency).
|
|
The image layout is per-image subresource, and separate image subresources
|
|
of the same image can: be in different layouts at the same time with one
|
|
exception - depth and stencil aspects of a given image subresource must:
|
|
always be in the same layout.
|
|
|
|
[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 images created with
|
|
ename:VK_IMAGE_TILING_LINEAR tiling 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::../api/enums/VkImageLayout.txt[]
|
|
|
|
The type(s) of device access supported by each layout are:
|
|
|
|
* ename:VK_IMAGE_LAYOUT_UNDEFINED does not support device access.
|
|
This layout must: only be used as the pname:initialLayout member of
|
|
sname:VkImageCreateInfo or sname:VkAttachmentDescription, or as the
|
|
pname:oldLayout in an image transition.
|
|
When transitioning out of this layout, the contents of the memory are
|
|
not guaranteed to be preserved.
|
|
* ename:VK_IMAGE_LAYOUT_PREINITIALIZED does not support device access.
|
|
This layout must: only be used as the pname:initialLayout member of
|
|
sname:VkImageCreateInfo or sname:VkAttachmentDescription, or as the
|
|
pname:oldLayout in an image transition.
|
|
When transitioning out of this layout, the contents of the memory are
|
|
preserved.
|
|
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
|
|
ename:VK_IMAGE_TILING_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.
|
|
* 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 must: only be
|
|
used as a depth/stencil attachment in a sname:VkFramebuffer.
|
|
This layout is valid only for image subresources of images created with
|
|
the ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL must: only be used
|
|
as a read-only depth/stencil attachment in a sname:VkFramebuffer and/or
|
|
as a read-only image in a shader (which can: be read as a sampled image,
|
|
combined image/sampler and/or input attachment).
|
|
This layout is valid only for image subresources of images created with
|
|
the ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled.
|
|
Only image subresources of images created with
|
|
ename:VK_IMAGE_USAGE_SAMPLED_BIT can: be used as sampled image or
|
|
combined image/sampler in a shader.
|
|
Similarly, only image subresources of images created with
|
|
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT can: be used as input
|
|
attachments.
|
|
* ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL must: only be used as a
|
|
read-only image in a shader (which can: be read as a sampled image,
|
|
combined image/sampler and/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 bit 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[]
|
|
|
|
For each mechanism of accessing an image in the API, there is a parameter or
|
|
structure member that controls the image layout used to access the image.
|
|
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 sname:VkRenderPassCreateInfo (see <<renderpass,Render Pass>>).
|
|
For use in a descriptor set, this is a member in the
|
|
sname:VkDescriptorImageInfo structure (see <<descriptorsets-updates>>).
|
|
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 the layout specified via the API controlling those accesses.
|
|
|
|
The image layout of each image subresource must: be well-defined at each
|
|
point in the image subresource's lifetime.
|
|
This means that when performing a layout transition on the 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.
|
|
|
|
--
|
|
|
|
|
|
[[resources-image-views]]
|
|
== Image Views
|
|
|
|
[open,refpage='VkImageView',desc='Opaque handle to a 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::../api/handles/VkImageView.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='VkImageViewType',desc='Image view types',type='enums']
|
|
--
|
|
|
|
The types of image views that can: be created are:
|
|
|
|
include::../api/enums/VkImageViewType.txt[]
|
|
|
|
The exact image view type is partially implicit, based on the image's type
|
|
and sample count, as well as the view creation parameters as described in
|
|
the <<resources-image-views-compatibility,image view compatibility table>>
|
|
for flink:vkCreateImageView.
|
|
This table also shows which SPIR-V code:OpTypeImage code:Dim and
|
|
code:Arrayed parameters correspond to each image view type.
|
|
|
|
--
|
|
|
|
[open,refpage='vkCreateImageView',desc='Create an image view from an existing image',type='protos']
|
|
--
|
|
|
|
To create an image view, call:
|
|
|
|
include::../api/protos/vkCreateImageView.txt[]
|
|
|
|
* pname:device is the logical device that creates the image view.
|
|
* pname:pCreateInfo is a pointer to an instance of the
|
|
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 points to a sname:VkImageView handle in which the resulting
|
|
image view object is returned.
|
|
|
|
Some of the image creation parameters are inherited by the view.
|
|
The remaining parameters are contained in the pname:pCreateInfo.
|
|
|
|
include::../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::../api/structs/VkImageViewCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is reserved for future use.
|
|
* pname:image is a sname:VkImage on which the view will be created.
|
|
* pname:viewType is an elink:VkImageViewType value specifying the type of
|
|
the image view.
|
|
* pname:format is a elink:VkFormat describing the format and type used to
|
|
interpret data elements in the image.
|
|
* pname:components is a slink:VkComponentMapping specifies 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 selecting the
|
|
set of mipmap levels and array layers to be accessible to the view.
|
|
|
|
If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
|
|
flag, pname:format can: be different from the image's format, but if they
|
|
are not equal they must: be _compatible_.
|
|
Image format compatibility is defined in the
|
|
<<features-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.
|
|
|
|
[[resources-image-views-compatibility]]
|
|
.Image and image view parameter compatibility requirements
|
|
[cols="15%h,35%,50%",options="header"]
|
|
|====
|
|
| Dim, Arrayed, MS | Image parameters | View parameters
|
|
| | pname:imageType = ci.pname:imageType +
|
|
pname:width = ci.pname:extent.width +
|
|
pname:height = ci.pname:extent.height +
|
|
pname:depth = ci.pname:extent.depth +
|
|
pname:arrayLayers = ci.pname:arrayLayers +
|
|
pname:samples = ci.pname:samples +
|
|
pname:flags = ci.pname:flags +
|
|
where ci is the slink:VkImageCreateInfo used to create pname:image.
|
|
ifdef::VK_KHR_maintenance1[]
|
|
| pname:baseArrayLayer, pname:layerCount, and pname:levelCount
|
|
endif::VK_KHR_maintenance1[]
|
|
ifndef::VK_KHR_maintenance1[]
|
|
| pname:baseArrayLayer and pname:layerCount
|
|
endif::VK_KHR_maintenance1[]
|
|
are members of the pname:subresourceRange member.
|
|
| 1D, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_1D +
|
|
pname:width {geq} 1 +
|
|
pname:height = 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples = 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_1D +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 1
|
|
| 1D, 1, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_1D +
|
|
pname:width {geq} 1 +
|
|
pname:height = 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples = 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount {geq} 1
|
|
| 2D, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples = 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 1
|
|
| 2D, 1, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples = 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount {geq} 1
|
|
| 2D, 0, 1 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples > 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 1
|
|
| 2D, 1, 1 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples > 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount {geq} 1
|
|
| CUBE, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height = pname:width +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 6 +
|
|
pname:samples = 1 +
|
|
pname:flags includes ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_CUBE +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 6
|
|
| CUBE, 1, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height = width +
|
|
pname:depth = 1 +
|
|
_N_ {geq} 1 +
|
|
pname:arrayLayers {geq} 6 {times} _N_ +
|
|
pname:samples = 1 +
|
|
pname:flags includes ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 6 {times} _N_, _N_ {geq} 1
|
|
| 3D, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_3D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth {geq} 1 +
|
|
pname:arrayLayers = 1 +
|
|
pname:samples = 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_3D +
|
|
pname:baseArrayLayer = 0 +
|
|
pname:layerCount = 1
|
|
ifdef::VK_KHR_maintenance1[]
|
|
| 3D, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_3D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth {geq} 1 +
|
|
pname:arrayLayers = 1 +
|
|
pname:samples = 1 +
|
|
pname:flags includes ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT +
|
|
pname:flags does not include ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D +
|
|
pname:levelCount = 1 +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 1
|
|
| 3D, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_3D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth {geq} 1 +
|
|
pname:arrayLayers = 1 +
|
|
pname:samples = 1 +
|
|
pname:flags includes ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT +
|
|
pname:flags does not include ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT, ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY +
|
|
pname:levelCount = 1 +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount {geq} 1
|
|
endif::VK_KHR_maintenance1[]
|
|
|====
|
|
|
|
.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-features-imageCubeArray,image cubemap arrays>> feature
|
|
is not enabled, pname:viewType must: not be
|
|
ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
|
|
ifdef::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_KHR set then
|
|
pname:viewType must: not be ename:VK_IMAGE_VIEW_TYPE_2D or
|
|
ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01006]]
|
|
If pname:image was created with ename:VK_IMAGE_TILING_LINEAR,
|
|
pname:format must: be format that has at least one supported feature bit
|
|
present in the value of
|
|
sname:VkFormatProperties::pname:linearTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-image-01007]]
|
|
pname:image must: have been created with a pname:usage value containing
|
|
at least one of 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, or
|
|
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
|
|
* [[VUID-VkImageViewCreateInfo-image-01008]]
|
|
If pname:image was created with ename:VK_IMAGE_TILING_LINEAR and
|
|
pname:usage contains ename:VK_IMAGE_USAGE_SAMPLED_BIT, pname:format
|
|
must: be supported for sampled images, as specified by the
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT flag in
|
|
sname:VkFormatProperties::pname:linearTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-image-01009]]
|
|
If pname:image was created with ename:VK_IMAGE_TILING_LINEAR and
|
|
pname:usage contains ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:format
|
|
must: be supported for storage images, as specified by the
|
|
ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT flag in
|
|
sname:VkFormatProperties::pname:linearTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-image-01010]]
|
|
If pname:image was created with ename:VK_IMAGE_TILING_LINEAR and
|
|
pname:usage contains ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,
|
|
pname:format must: be supported for color attachments, as specified by
|
|
the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in
|
|
sname:VkFormatProperties::pname:linearTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-image-01011]]
|
|
If pname:image was created with ename:VK_IMAGE_TILING_LINEAR and
|
|
pname:usage contains ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT,
|
|
pname:format must: be supported for depth/stencil attachments, as
|
|
specified by the ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
|
|
flag in sname:VkFormatProperties::pname:linearTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-image-01012]]
|
|
If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL,
|
|
pname:format must: be format that has at least one supported feature bit
|
|
present in the value of
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-image-01013]]
|
|
If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL and
|
|
pname:usage contains ename:VK_IMAGE_USAGE_SAMPLED_BIT, pname:format
|
|
must: be supported for sampled images, as specified by the
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT flag in
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-image-01014]]
|
|
If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL and
|
|
pname:usage contains ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:format
|
|
must: be supported for storage images, as specified by the
|
|
ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT flag in
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-image-01015]]
|
|
If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL and
|
|
pname:usage contains ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,
|
|
pname:format must: be supported for color attachments, as specified by
|
|
the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT flag in
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-image-01016]]
|
|
If pname:image was created with ename:VK_IMAGE_TILING_OPTIMAL and
|
|
pname:usage contains ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT,
|
|
pname:format must: be supported for depth/stencil attachments, as
|
|
specified by the ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
|
|
flag in sname:VkFormatProperties::pname:optimalTilingFeatures returned
|
|
by fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-subresourceRange-01478]]
|
|
pname:subresourceRange::pname:baseMipLevel must: be less than the
|
|
pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* [[VUID-VkImageViewCreateInfo-subresourceRange-01479]]
|
|
If pname:subresourceRange::pname:levelCount is not
|
|
ename:VK_REMAINING_MIP_LEVELS, pname:subresourceRange::pname:levelCount
|
|
must: be non-zero and [eq]#pname:subresourceRange::pname:baseMipLevel
|
|
{plus} pname:subresourceRange::pname:levelCount# must: be less than or
|
|
equal to the pname:mipLevels specified in slink:VkImageCreateInfo when
|
|
pname:image was created
|
|
ifndef::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageViewCreateInfo-subresourceRange-01480]]
|
|
pname:subresourceRange::pname:baseArrayLayer must: be less than the
|
|
pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* [[VUID-VkImageViewCreateInfo-subresourceRange-01481]]
|
|
If pname:subresourceRange::pname:layerCount is not
|
|
ename:VK_REMAINING_ARRAY_LAYERS,
|
|
pname:subresourceRange::pname:layerCount must: be non-zero and
|
|
[eq]#pname:subresourceRange::pname:baseArrayLayer {plus}
|
|
pname:subresourceRange::pname:layerCount# must: be less than or equal to
|
|
the pname:arrayLayers specified in slink:VkImageCreateInfo when
|
|
pname:image was created
|
|
endif::VK_KHR_maintenance1[]
|
|
ifdef::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_KHR set, or pname:viewType
|
|
is not ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY,
|
|
pname:subresourceRange::pname:baseArrayLayer must: be less than the
|
|
pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* [[VUID-VkImageViewCreateInfo-subresourceRange-01483]]
|
|
If pname:subresourceRange::pname: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_KHR set, or
|
|
pname:viewType is not ename:VK_IMAGE_VIEW_TYPE_2D or
|
|
ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY,
|
|
pname:subresourceRange::pname:layerCount must: be non-zero and
|
|
[eq]#pname:subresourceRange::pname:baseArrayLayer {plus}
|
|
pname:subresourceRange::pname:layerCount# must: be less than or equal to
|
|
the pname:arrayLayers specified in slink:VkImageCreateInfo when
|
|
pname:image was created
|
|
* [[VUID-VkImageViewCreateInfo-image-01484]]
|
|
If pname:image is a 3D image created with
|
|
ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR set, and
|
|
pname:viewType is ename:VK_IMAGE_VIEW_TYPE_2D or
|
|
ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY,
|
|
pname:subresourceRange::pname:baseArrayLayer must: be less than the
|
|
pname:extent.depth specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* [[VUID-VkImageViewCreateInfo-subresourceRange-01485]]
|
|
If pname:subresourceRange::pname:layerCount is not
|
|
ename:VK_REMAINING_ARRAY_LAYERS, pname:image is a 3D image created with
|
|
ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR set, and
|
|
pname:viewType is ename:VK_IMAGE_VIEW_TYPE_2D or
|
|
ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY,
|
|
pname:subresourceRange::pname:layerCount must: be non-zero and
|
|
[eq]#pname:subresourceRange::pname:baseArrayLayer {plus}
|
|
pname:subresourceRange::pname:layerCount# must: be less than or equal to
|
|
the pname:extent.depth specified in slink:VkImageCreateInfo when
|
|
pname:image was created
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[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 <<features-formats-compatibility-classes,Format Compatibility
|
|
Classes>>
|
|
* [[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
|
|
* [[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:subresourceRange and pname:viewType must: be compatible with the
|
|
image, as described in the
|
|
<<resources-image-views-compatibility,compatibility table>>
|
|
****
|
|
|
|
include::../validity/structs/VkImageViewCreateInfo.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageSubresourceRange',desc='Structure specifying a image subresource range',type='structs']
|
|
--
|
|
|
|
The sname:VkImageSubresourceRange structure is defined as:
|
|
|
|
include::../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, behavior when indexing the last cube is undefined.
|
|
|
|
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, respectively.
|
|
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_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_KHR_maintenance1[]
|
|
|
|
When using an imageView 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 and selects whether the
|
|
imageView 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 imageView 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.
|
|
|
|
The pname:components member is of type slink:VkComponentMapping, and
|
|
describes a remapping from components of the image to components of the
|
|
vector returned by shader image instructions.
|
|
This remapping must: be identity for storage image descriptors, input
|
|
attachment descriptors, and framebuffer attachments.
|
|
|
|
include::../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::../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 sparse <<sparsememory, sparse resource>> operations.
|
|
|
|
--
|
|
|
|
[open,refpage='VkComponentMapping',desc='Structure specifying a color component mapping',type='structs']
|
|
--
|
|
|
|
The sname:VkComponentMapping structure is defined as:
|
|
|
|
include::../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::../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::../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
|
|
<<features-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.
|
|
|
|
Setting the identity swizzle on a component is equivalent to setting the
|
|
identity mapping on that component.
|
|
That is:
|
|
|
|
[[resources-image-views-identity-mappings]]
|
|
.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
|
|
|====
|
|
|
|
--
|
|
|
|
[open,refpage='vkDestroyImageView',desc='Destroy an image view object',type='protos']
|
|
--
|
|
|
|
To destroy an image view, call:
|
|
|
|
include::../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::../validity/protos/vkDestroyImageView.txt[]
|
|
--
|
|
|
|
|
|
[[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_KHX_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_KHX_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::../api/protos/vkGetBufferMemoryRequirements.txt[]
|
|
|
|
* pname:device is the logical device that owns the buffer.
|
|
* pname:buffer is the buffer to query.
|
|
* pname:pMemoryRequirements points to an instance of the
|
|
slink:VkMemoryRequirements structure in which the memory requirements of
|
|
the buffer object are returned.
|
|
|
|
include::../validity/protos/vkGetBufferMemoryRequirements.txt[]
|
|
--
|
|
|
|
[open,refpage='vkGetImageMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos']
|
|
--
|
|
|
|
To determine the memory requirements for an image resource, call:
|
|
|
|
include::../api/protos/vkGetImageMemoryRequirements.txt[]
|
|
|
|
* pname:device is the logical device that owns the image.
|
|
* pname:image is the image to query.
|
|
* pname:pMemoryRequirements points to an instance of the
|
|
slink:VkMemoryRequirements structure in which the memory requirements of
|
|
the image object are returned.
|
|
|
|
include::../validity/protos/vkGetImageMemoryRequirements.txt[]
|
|
--
|
|
|
|
[open,refpage='VkMemoryRequirements',desc='Structure specifying memory requirements',type='structs']
|
|
--
|
|
|
|
The sname:VkMemoryRequirements structure is defined as:
|
|
|
|
include::../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::../validity/structs/VkMemoryRequirements.txt[]
|
|
--
|
|
|
|
The implementation guarantees certain properties about the memory
|
|
requirements returned by 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
|
|
a sname:VkImage that was created with a ename:VK_IMAGE_TILING_LINEAR
|
|
value in the pname:tiling member of the sname:VkImageCreateInfo
|
|
structure passed to fname:vkCreateImage, 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_KHR_external_memory[]
|
|
* If pname:buffer was created with
|
|
slink:VkExternalMemoryBufferCreateInfoKHR::pname:handleTypes set to `0`
|
|
or pname:image was created with
|
|
slink:VkExternalMemoryImageCreateInfoKHR::pname:handleTypes set to `0`,
|
|
the
|
|
endif::VK_KHR_external_memory[]
|
|
ifndef::VK_KHR_external_memory[]
|
|
* The
|
|
endif::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 sname:VkBufferCreateInfo structure
|
|
ifdef::VK_KHR_external_memory[]
|
|
and the pname:handleTypes member of the
|
|
slink:VkExternalMemoryBufferCreateInfoKHR structure
|
|
endif::VK_KHR_external_memory[]
|
|
passed to fname:vkCreateBuffer.
|
|
Further, if code:usage1 and code:usage2 of type elink: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_KHR_external_memory[]
|
|
pname:flags and
|
|
slink:VkExternalMemoryBufferCreateInfoKHR::pname:handleTypes,
|
|
endif::VK_KHR_external_memory[]
|
|
ifndef::VK_KHR_external_memory[]
|
|
pname:flags,
|
|
endif::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 sname:VkBufferCreateInfo structure passed to
|
|
fname:vkCreateBuffer.
|
|
* 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_KHX_device_group[]
|
|
the ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX bit of the pname:flags
|
|
member,
|
|
endif::VK_KHX_device_group[]
|
|
ifdef::VK_KHR_external_memory[]
|
|
pname:handleTypes member of slink:VkExternalMemoryImageCreateInfoKHR,
|
|
endif::VK_KHR_external_memory[]
|
|
and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage
|
|
member in the sname:VkImageCreateInfo structure passed to
|
|
fname: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_KHX_device_group[]
|
|
the ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX bit of the pname:flags
|
|
member,
|
|
endif::VK_KHX_device_group[]
|
|
ifdef::VK_KHR_external_memory[]
|
|
pname:handleTypes member of slink:VkExternalMemoryImageCreateInfoKHR,
|
|
endif::VK_KHR_external_memory[]
|
|
and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage
|
|
member in the sname:VkImageCreateInfo structure passed to
|
|
fname: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
|
|
flink:vkGetImageMemoryRequirements::pname:image did not have
|
|
ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT bit set in the pname:usage
|
|
member of the sname:VkImageCreateInfo structure passed to
|
|
fname: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.
|
|
====
|
|
|
|
ifdef::VK_KHR_get_memory_requirements2[]
|
|
|
|
[open,refpage='vkGetBufferMemoryRequirements2KHR',desc='Returns the memory requirements for specified Vulkan object',type='protos']
|
|
--
|
|
|
|
To determine the memory requirements for a buffer resource, call:
|
|
|
|
include::../api/protos/vkGetBufferMemoryRequirements2KHR.txt[]
|
|
|
|
* pname:device is the logical device that owns the buffer.
|
|
* pname:pInfo is a pointer to an instance of the
|
|
sname:VkBufferMemoryRequirementsInfo2KHR structure containing parameters
|
|
required for the memory requirements query.
|
|
* pname:pMemoryRequirements points to an instance of the
|
|
slink:VkMemoryRequirements2KHR structure in which the memory
|
|
requirements of the buffer object are returned.
|
|
|
|
include::../validity/protos/vkGetBufferMemoryRequirements2KHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBufferMemoryRequirementsInfo2KHR',desc='(None)',type='structs']
|
|
--
|
|
The sname:VkBufferMemoryRequirementsInfo2KHR structure is defined as:
|
|
|
|
include::../api/structs/VkBufferMemoryRequirementsInfo2KHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:buffer is the buffer to query.
|
|
|
|
include::../validity/structs/VkBufferMemoryRequirementsInfo2KHR.txt[]
|
|
--
|
|
|
|
[open,refpage='vkGetImageMemoryRequirements2KHR',desc='Returns the memory requirements for specified Vulkan object',type='protos']
|
|
--
|
|
|
|
To determine the memory requirements for an image resource, call:
|
|
|
|
include::../api/protos/vkGetImageMemoryRequirements2KHR.txt[]
|
|
|
|
* pname:device is the logical device that owns the image.
|
|
* pname:pInfo is a pointer to an instance of the
|
|
sname:VkImageMemoryRequirementsInfo2KHR structure containing parameters
|
|
required for the memory requirements query.
|
|
* pname:pMemoryRequirements points to an instance of the
|
|
slink:VkMemoryRequirements2KHR structure in which the memory
|
|
requirements of the image object are returned.
|
|
|
|
include::../validity/protos/vkGetImageMemoryRequirements2KHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageMemoryRequirementsInfo2KHR',desc='(None)',type='structs']
|
|
--
|
|
The sname:VkImageMemoryRequirementsInfo2KHR structure is defined as:
|
|
|
|
include::../api/structs/VkImageMemoryRequirementsInfo2KHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:image is the image to query.
|
|
|
|
include::../validity/structs/VkImageMemoryRequirementsInfo2KHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkMemoryRequirements2KHR',desc='Structure specifying memory requirements',type='structs']
|
|
--
|
|
|
|
The sname:VkMemoryRequirements2KHR structure is defined as:
|
|
|
|
include::../api/structs/VkMemoryRequirements2KHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:memoryRequirements is a structure of type
|
|
slink:VkMemoryRequirements describing the memory requirements of the
|
|
resource.
|
|
|
|
include::../validity/structs/VkMemoryRequirements2KHR.txt[]
|
|
--
|
|
|
|
endif::VK_KHR_get_memory_requirements2[]
|
|
|
|
ifdef::VK_KHR_dedicated_allocation[]
|
|
|
|
[open,refpage='VkMemoryDedicatedRequirementsKHR',desc='Structure describing dedicated allocation requirements of buffer and image resources',type='structs']
|
|
--
|
|
|
|
To determine the dedicated allocation requirements of a buffer or image
|
|
resource, add a slink:VkMemoryDedicatedRequirementsKHR structure to the
|
|
pname:pNext chain of fname:vkGetBufferMemoryRequirements2KHR or
|
|
fname:vkGetImageMemoryRequirements2KHR.
|
|
|
|
The sname:VkMemoryDedicatedRequirementsKHR structure is defined as:
|
|
|
|
include::../api/structs/VkMemoryDedicatedRequirementsKHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:prefersDedicatedAllocation indicates 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 indicates that a dedicated allocation
|
|
is required for this resource.
|
|
|
|
If the sname:VkMemoryDedicatedRequirementsKHR structure is included in the
|
|
pname:pNext chain of a fname:vkGetBufferMemoryRequirements2KHR call,
|
|
pname:requiresDedicatedAllocation may: be ename:VK_TRUE under one of the
|
|
following conditions:
|
|
|
|
ifndef::VK_KHR_external_memory[]
|
|
* none
|
|
endif::VK_KHR_external_memory[]
|
|
ifdef::VK_KHR_external_memory[]
|
|
* The pname:pNext chain for the call to fname:vkCreateBuffer used to
|
|
create the buffer being queried contained an instance of
|
|
sname:VkExternalMemoryBufferCreateInfoKHR and any of the handle types
|
|
specified in
|
|
sname:VkExternalMemoryBufferCreateInfoKHR::pname:handleTypes requires
|
|
dedicated allocation, as reported by
|
|
flink:vkGetPhysicalDeviceExternalBufferPropertiesKHR in
|
|
sname:VkExternalBufferPropertiesKHR::pname:externalMemoryProperties::pname:externalMemoryFeatures,
|
|
the pname:requiresDedicatedAllocation field will be set to
|
|
ename:VK_TRUE.
|
|
endif::VK_KHR_external_memory[]
|
|
|
|
In all other cases, pname:requiresDedicatedAllocation must: be set to
|
|
ename:VK_FALSE by the implementation whenever a
|
|
sname:VkMemoryDedicatedRequirementsKHR structure is included in the
|
|
pname:pNext chain of a call to fname:vkGetBufferMemoryRequirements2KHR.
|
|
|
|
If the sname:VkMemoryDedicatedRequirementsKHR structure is included in the
|
|
pname:pNext chain of a fname:vkGetBufferMemoryRequirements2KHR call and
|
|
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT was set in
|
|
sname:VkBufferCreateInfo::pname:flags when pname:buffer was created then the
|
|
implementation must: set both pname:prefersDedicatedAllocation and
|
|
pname:requiresDedicatedAllocation to ename:VK_FALSE.
|
|
|
|
If the sname:VkMemoryDedicatedRequirementsKHR structure is included in the
|
|
pname:pNext chain of a fname:vkGetImageMemoryRequirements2KHR call,
|
|
pname:requiresDedicatedAllocation may: be ename:VK_TRUE under one of the
|
|
following conditions:
|
|
|
|
ifndef::VK_KHR_external_memory[]
|
|
* none
|
|
endif::VK_KHR_external_memory[]
|
|
ifdef::VK_KHR_external_memory[]
|
|
* The pname:pNext chain for the call to fname:vkCreateImage used to create
|
|
the image being queried contained an instance of
|
|
sname:VkExternalMemoryImageCreateInfoKHR and any of the handle types
|
|
specified in sname:VkExternalMemoryImageCreateInfoKHR::pname:handleTypes
|
|
require a dedicated allocation, as reported by
|
|
flink:vkGetPhysicalDeviceImageFormatProperties2KHR in
|
|
sname:VkExternalImageFormatPropertiesKHR::pname:externalMemoryProperties::pname:externalMemoryFeatures,
|
|
the pname:requiresDedicatedAllocation field will be set to
|
|
ename:VK_TRUE.
|
|
endif::VK_KHR_external_memory[]
|
|
|
|
In all other cases, pname:requiresDedicatedAllocation must: be set to
|
|
ename:VK_FALSE by the implementation whenever a
|
|
sname:VkMemoryDedicatedRequirementsKHR structure is included in the
|
|
pname:pNext chain of a call to fname:vkGetImageMemoryRequirements2KHR.
|
|
|
|
If the sname:VkMemoryDedicatedRequirementsKHR structure is included in the
|
|
pname:pNext chain of a fname:vkGetImageMemoryRequirements2KHR call and
|
|
ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT was set in
|
|
sname:VkImageCreateInfo::pname:flags when pname:image was created then the
|
|
implementation must: set both pname:prefersDedicatedAllocation and
|
|
pname:requiresDedicatedAllocation to ename:VK_FALSE.
|
|
|
|
include::../validity/structs/VkMemoryDedicatedRequirementsKHR.txt[]
|
|
|
|
--
|
|
|
|
endif::VK_KHR_dedicated_allocation[]
|
|
|
|
[open,refpage='vkBindBufferMemory',desc='Bind device memory to a buffer object',type='protos']
|
|
--
|
|
|
|
To attach memory to a buffer object, call:
|
|
|
|
include::../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 sname: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_KHX_device_group[]
|
|
|
|
fname:vkBindBufferMemory is equivalent to passing the same parameters
|
|
through slink:VkBindBufferMemoryInfoKHX to flink:vkBindBufferMemory2KHX,
|
|
with pname:deviceIndexCount equal to zero.
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkBindBufferMemory-buffer-01029]]
|
|
pname:buffer must: not already be backed by a memory object
|
|
* [[VUID-vkBindBufferMemory-buffer-01030]]
|
|
pname:buffer must: not have been created with any sparse memory binding
|
|
flags
|
|
* [[VUID-vkBindBufferMemory-memoryOffset-01031]]
|
|
pname:memoryOffset must: be less than the size of pname:memory
|
|
* [[VUID-vkBindBufferMemory-buffer-01032]]
|
|
If pname:buffer was created with the
|
|
ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT or
|
|
ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:memoryOffset must:
|
|
be a multiple of
|
|
sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment
|
|
* [[VUID-vkBindBufferMemory-buffer-01033]]
|
|
If pname:buffer was created with the
|
|
ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT, pname:memoryOffset must: be a
|
|
multiple of
|
|
sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment
|
|
* [[VUID-vkBindBufferMemory-buffer-01034]]
|
|
If pname:buffer was created with the
|
|
ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, pname:memoryOffset must: be a
|
|
multiple of
|
|
sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment
|
|
* [[VUID-vkBindBufferMemory-memory-01035]]
|
|
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
|
|
fname:vkGetBufferMemoryRequirements with pname:buffer
|
|
* [[VUID-vkBindBufferMemory-memoryOffset-01036]]
|
|
pname:memoryOffset must: be an integer multiple of the pname:alignment
|
|
member of the sname:VkMemoryRequirements structure returned from a call
|
|
to fname:vkGetBufferMemoryRequirements with pname:buffer
|
|
* [[VUID-vkBindBufferMemory-size-01037]]
|
|
The pname:size member of the sname:VkMemoryRequirements structure
|
|
returned from a call to fname:vkGetBufferMemoryRequirements with
|
|
pname:buffer must: be less than or equal to the size of pname:memory
|
|
minus pname:memoryOffset
|
|
ifdef::VK_KHR_dedicated_allocation[]
|
|
* [[VUID-vkBindBufferMemory-buffer-01444]]
|
|
If pname:buffer requires a dedicated allocation(as reported by
|
|
flink:vkGetBufferMemoryRequirements2KHR in
|
|
slink:VkMemoryDedicatedRequirementsKHR::requiresDedicatedAllocation for
|
|
pname:image), pname:memory must: have been created with
|
|
slink:VkMemoryDedicatedAllocateInfoKHR::pname:buffer equal to
|
|
pname:buffer and pname:memoryOffset must: be zero
|
|
endif::VK_KHR_dedicated_allocation[]
|
|
ifdef::VK_NV_dedicated_allocation[]
|
|
* [[VUID-vkBindBufferMemory-buffer-01038]]
|
|
If pname:buffer was created with
|
|
slink:VkDedicatedAllocationBufferCreateInfoNV::pname:dedicatedAllocation
|
|
equal to ename:VK_TRUE, pname:memory must: have been created with
|
|
slink:VkDedicatedAllocationMemoryAllocateInfoNV::pname:buffer equal to a
|
|
buffer handle created with identical creation parameters to pname:buffer
|
|
and pname:memoryOffset must: be zero
|
|
ifndef::VK_KHR_dedicated_allocation[]
|
|
* [[VUID-vkBindBufferMemory-buffer-01039]]
|
|
If pname:buffer was not created with
|
|
slink:VkDedicatedAllocationBufferCreateInfoNV::pname:dedicatedAllocation
|
|
equal to ename:VK_TRUE, pname:memory must: not have been allocated
|
|
dedicated for a specific buffer or image
|
|
endif::VK_KHR_dedicated_allocation[]
|
|
endif::VK_NV_dedicated_allocation[]
|
|
****
|
|
|
|
include::../validity/protos/vkBindBufferMemory.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
[open,refpage='vkBindBufferMemory2KHX',desc='Bind device memory to buffer objects',type='protos']
|
|
--
|
|
|
|
To attach memory to buffer objects for one or more buffers at a time, call:
|
|
|
|
include::../api/protos/vkBindBufferMemory2KHX.txt[]
|
|
|
|
* 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 structures of type
|
|
slink:VkBindBufferMemoryInfoKHX, describing buffers and memory to bind.
|
|
|
|
On some implementations, it may: be more efficient to batch memory bindings
|
|
into a single command.
|
|
|
|
include::../validity/protos/vkBindBufferMemory2KHX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBindBufferMemoryInfoKHX',desc='Structure specifying how to bind a buffer to memory',type='structs']
|
|
--
|
|
|
|
sname:VkBindBufferMemoryInfoKHX contains members corresponding to the
|
|
parameters to flink:vkBindBufferMemory, as well as new members to control
|
|
peer memory bindings.
|
|
|
|
The sname:VkBindBufferMemoryInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkBindBufferMemoryInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:buffer is the buffer 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 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.
|
|
* pname:deviceIndexCount is the number of elements in
|
|
pname:pDeviceIndices.
|
|
* pname:pDeviceIndices is a pointer to an array of device indices.
|
|
|
|
If pname:deviceIndexCount is greater than zero, then on device index [eq]#i#
|
|
the buffer is attached to the instance of memory on the physical device with
|
|
device index [eq]#pDeviceIndices[i]#.
|
|
|
|
If pname:deviceIndexCount is zero and the memory comes from a memory heap
|
|
with the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX 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:deviceIndexCount is zero and the memory comes from a memory heap
|
|
without the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX 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-VkBindBufferMemoryInfoKHX-None-01040]]
|
|
All valid usage rules from flink:vkBindBufferMemory apply to the
|
|
identically named members of sname:VkBindBufferMemoryInfoKHX
|
|
* [[VUID-VkBindBufferMemoryInfoKHX-deviceIndexCount-01041]]
|
|
pname:deviceIndexCount must: either be zero or equal to the number of
|
|
physical devices in the logical device
|
|
* [[VUID-VkBindBufferMemoryInfoKHX-pDeviceIndices-01042]]
|
|
All elements of pname:pDeviceIndices must: be valid device indices
|
|
* [[VUID-VkBindBufferMemoryInfoKHX-None-01043]]
|
|
All instances of memory that are bound to must: have been allocated
|
|
****
|
|
|
|
include::../validity/structs/VkBindBufferMemoryInfoKHX.txt[]
|
|
--
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
[open,refpage='vkBindImageMemory',desc='Bind device memory to an image object',type='protos']
|
|
--
|
|
|
|
To attach memory to an image object, call:
|
|
|
|
include::../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 sname: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_KHX_device_group[]
|
|
|
|
fname:vkBindImageMemory is equivalent to passing the same parameters through
|
|
slink:VkBindImageMemoryInfoKHX to flink:vkBindImageMemory2KHX, with
|
|
pname:deviceIndexCount and pname:SFRRectCount equal to zero.
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkBindImageMemory-image-01044]]
|
|
pname:image must: not already be backed by a memory object
|
|
* [[VUID-vkBindImageMemory-image-01045]]
|
|
pname:image must: not have been created with any sparse memory binding
|
|
flags
|
|
* [[VUID-vkBindImageMemory-memoryOffset-01046]]
|
|
pname:memoryOffset must: be less than the size of pname:memory
|
|
* [[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
|
|
fname: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 fname:vkGetImageMemoryRequirements with pname:image
|
|
* [[VUID-vkBindImageMemory-size-01049]]
|
|
The pname:size member of the sname:VkMemoryRequirements structure
|
|
returned from a call to fname:vkGetImageMemoryRequirements with
|
|
pname:image must: be less than or equal to the size of pname:memory
|
|
minus pname:memoryOffset
|
|
ifdef::VK_KHR_dedicated_allocation[]
|
|
* [[VUID-vkBindImageMemory-image-01445]]
|
|
If pname:image requires a dedicated allocation (as reported by
|
|
flink:vkGetImageMemoryRequirements2KHR in
|
|
slink:VkMemoryDedicatedRequirementsKHR::requiresDedicatedAllocation for
|
|
pname:image), pname:memory must: have been created with
|
|
slink:VkMemoryDedicatedAllocateInfoKHR::pname:image equal to pname:image
|
|
and pname:memoryOffset must: be zero
|
|
endif::VK_KHR_dedicated_allocation[]
|
|
ifdef::VK_NV_dedicated_allocation[]
|
|
* [[VUID-vkBindImageMemory-image-01050]]
|
|
If pname:image was created with
|
|
slink:VkDedicatedAllocationImageCreateInfoNV::pname:dedicatedAllocation
|
|
equal to ename:VK_TRUE, pname:memory must: have been created with
|
|
slink:VkDedicatedAllocationMemoryAllocateInfoNV::pname:image equal to an
|
|
image handle created with identical creation parameters to pname:image
|
|
and pname:memoryOffset must: be zero
|
|
ifndef::VK_KHR_dedicated_allocation[]
|
|
* [[VUID-vkBindImageMemory-image-01051]]
|
|
If pname:image was not created with
|
|
slink:VkDedicatedAllocationImageCreateInfoNV::pname:dedicatedAllocation
|
|
equal to ename:VK_TRUE, pname:memory must: not have been allocated
|
|
dedicated for a specific buffer or image
|
|
endif::VK_KHR_dedicated_allocation[]
|
|
endif::VK_NV_dedicated_allocation[]
|
|
****
|
|
|
|
include::../validity/protos/vkBindImageMemory.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
[open,refpage='vkBindImageMemory2KHX',desc='Bind device memory to image objects',type='protos']
|
|
--
|
|
|
|
To attach memory to image objects for one or more images at a time, call:
|
|
|
|
include::../api/protos/vkBindImageMemory2KHX.txt[]
|
|
|
|
* 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 structures of type
|
|
slink:VkBindImageMemoryInfoKHX, describing images and memory to bind.
|
|
|
|
On some implementations, it may: be more efficient to batch memory bindings
|
|
into a single command.
|
|
|
|
include::../validity/protos/vkBindImageMemory2KHX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBindImageMemoryInfoKHX',desc='Structure specifying how to bind an image to memory',type='structs']
|
|
--
|
|
|
|
sname:VkBindImageMemoryInfoKHX contains members corresponding to the
|
|
parameters to flink:vkBindImageMemory, as well as new members to control
|
|
peer memory bindings.
|
|
|
|
The sname:VkBindImageMemoryInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkBindImageMemoryInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:image is the image 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 pname:memory
|
|
which is to be bound to the image.
|
|
If pname:SFRRectCount is zero, 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.
|
|
* pname:deviceIndexCount is the number of elements in
|
|
pname:pDeviceIndices.
|
|
* pname:pDeviceIndices is a pointer to an array of device indices.
|
|
* pname:SFRRectCount is the number of elements in pname:pSFRRects.
|
|
* pname:pSFRRects is a pointer to an array of rectangles describing which
|
|
regions of the image are attached to each instance of memory.
|
|
|
|
If pname:deviceIndexCount is greater than zero, then on device index [eq]#i#
|
|
the image is attached to the instance of 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:SFRRectCount is greater than zero, then pname:pSFRRects is 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 memory
|
|
instance [eq]#j#.
|
|
The blocks of 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 were 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 the image, and the
|
|
block at [eq]#(0,0)# corresponds to memory starting at pname:memoryOffset.
|
|
|
|
If pname:SFRRectCount and pname:deviceIndexCount are zero and the memory
|
|
comes from a memory heap with the
|
|
ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX 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:SFRRectCount and pname:deviceIndexCount are zero and the memory
|
|
comes from a memory heap without the
|
|
ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX 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-VkBindImageMemoryInfoKHX-None-01052]]
|
|
All valid usage rules from flink:vkBindImageMemory apply to the
|
|
identically named members of sname:VkBindImageMemoryInfoKHX
|
|
* [[VUID-VkBindImageMemoryInfoKHX-deviceIndexCount-01053]]
|
|
At least one of pname:deviceIndexCount and pname:SFRRectCount must: be
|
|
zero.
|
|
* [[VUID-VkBindImageMemoryInfoKHX-deviceIndexCount-01054]]
|
|
pname:deviceIndexCount must: either be zero or equal to the number of
|
|
physical devices in the logical device
|
|
* [[VUID-VkBindImageMemoryInfoKHX-pDeviceIndices-01055]]
|
|
All elements of pname:pDeviceIndices must: be valid device indices.
|
|
* [[VUID-VkBindImageMemoryInfoKHX-SFRRectCount-01056]]
|
|
pname:SFRRectCount must: either be zero or equal to the number of
|
|
physical devices in the logical device squared
|
|
* [[VUID-VkBindImageMemoryInfoKHX-SFRRectCount-01057]]
|
|
If pname:SFRRectCount is not zero, then pname:image must: have been
|
|
created with the ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX bit set.
|
|
* [[VUID-VkBindImageMemoryInfoKHX-pSFRRects-01058]]
|
|
All elements of pname:pSFRRects must: be valid rectangles contained
|
|
within the dimensions of the image
|
|
* [[VUID-VkBindImageMemoryInfoKHX-pSFRRects-01059]]
|
|
Elements of pname:pSFRRects that correspond to the same instance of the
|
|
image must: not overlap and their union must: cover the entire image.
|
|
* [[VUID-VkBindImageMemoryInfoKHX-offset-01061]]
|
|
For each element of pname:pSFRRects, pname:offset.x must: be a multiple
|
|
of the sparse image block width
|
|
(sname:VkSparseImageFormatProperties::pname:imageGranularity.width) of
|
|
all non-metadata aspects of the image
|
|
* [[VUID-VkBindImageMemoryInfoKHX-extent-01062]]
|
|
For each element of pname:pSFRRects, pname:extent.width must: either be
|
|
a multiple of the sparse image block width of all non-metadata aspects
|
|
of the image, or else [eq]#(pname:extent.width {plus} pname:offset.x)#
|
|
must: equal the width of the image subresource
|
|
* [[VUID-VkBindImageMemoryInfoKHX-offset-01063]]
|
|
For each element of pname:pSFRRects, pname:offset.y must: be a multiple
|
|
of the sparse image block height
|
|
(sname:VkSparseImageFormatProperties::pname:imageGranularity.height) of
|
|
all non-metadata aspects of the image
|
|
* [[VUID-VkBindImageMemoryInfoKHX-extent-01064]]
|
|
For each element of pname:pSFRRects, pname:extent.height must: either be
|
|
a multiple of the sparse image block height of all non-metadata aspects
|
|
of the image, or else [eq]#(pname:extent.height {plus} pname:offset.y)#
|
|
must: equal the height of the image subresource
|
|
* [[VUID-VkBindImageMemoryInfoKHX-None-01065]]
|
|
All instances of memory that are bound must: have been allocated
|
|
* [[VUID-VkBindImageMemoryInfoKHX-image-01066]]
|
|
If pname:image was created with a valid swapchain handle in
|
|
slink:VkImageSwapchainCreateInfoKHX::pname:swapchain, then the image
|
|
must: be bound to memory from that swapchain (using
|
|
slink:VkBindImageMemorySwapchainInfoKHX).
|
|
****
|
|
|
|
include::../validity/structs/VkBindImageMemoryInfoKHX.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBindImageMemorySwapchainInfoKHX',desc='Structure specifying swapchain image memory to bind to',type='structs']
|
|
--
|
|
|
|
If the pname:pNext list of slink:VkBindImageMemoryInfoKHX includes a
|
|
sname:VkBindImageMemorySwapchainInfoKHX 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:VkBindImageMemorySwapchainInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkBindImageMemorySwapchainInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific 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:pSFRRects members of slink:VkBindImageMemoryInfoKHX.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBindImageMemorySwapchainInfoKHX-swapchain-01067]]
|
|
At least one of pname:swapchain and
|
|
slink:VkBindImageMemoryInfoKHX::pname:memory must: be
|
|
dlink:VK_NULL_HANDLE
|
|
* [[VUID-VkBindImageMemorySwapchainInfoKHX-imageIndex-01068]]
|
|
pname:imageIndex must: be less than the number of images in
|
|
pname:swapchain
|
|
****
|
|
|
|
include::../validity/structs/VkBindImageMemorySwapchainInfoKHX.txt[]
|
|
--
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
|
|
[[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 require such an additional granularity may:
|
|
report a 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
|
|
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::../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 same
|
|
queue family at any given time.
|
|
In order for a different queue family to be able to interpret the memory
|
|
contents of a range or image subresource, the application must: perform a
|
|
<<synchronization-queue-transfers,queue family ownership transfer>>.
|
|
|
|
Upon creation, resources using ename:VK_SHARING_MODE_EXCLUSIVE are not owned
|
|
by any queue family.
|
|
A buffer or image memory barrier is not required to acquire _ownership_ when
|
|
no queue family owns the resource - it is implicitly acquired upon first use
|
|
within a queue.
|
|
|
|
.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_KHR_external_memory[]
|
|
|
|
[[resources-external-sharing]]
|
|
=== External Resource Sharing
|
|
|
|
Resources may 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.
|
|
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_KHR to represent the external
|
|
destination or source respectively.
|
|
|
|
Upon creation, memory objects shared between multiple Vulkan instances or
|
|
other APIs are not owned by any instance or API.
|
|
The first entity to access them implicitly acquires ownership.
|
|
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_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,
|
|
ifndef::VK_KHR_external_memory[]
|
|
or via <<sparsememory-resource-binding,sparse memory bindings>>.
|
|
endif::VK_KHR_external_memory[]
|
|
ifdef::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_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 an opaque, 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_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_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 a 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.
|
|
|
|
Access to resources which alias memory from shaders using variables
|
|
decorated with code:Coherent are not automatically coherent with each other.
|
|
|
|
[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.
|
|
====
|