4448 lines
201 KiB
Plaintext
4448 lines
201 KiB
Plaintext
// Copyright (c) 2015-2018 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 valid 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_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
* [[VUID-VkBufferCreateInfo-sharingMode-01391]]
|
|
If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element
|
|
of pname:pQueueFamilyIndices must: be unique and must: be less than
|
|
pname:pQueueFamilyPropertyCount returned by
|
|
flink:vkGetPhysicalDeviceQueueFamilyProperties for the
|
|
pname:physicalDevice that was used to create pname:device
|
|
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
* [[VUID-VkBufferCreateInfo-sharingMode-01419]]
|
|
If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element
|
|
of pname:pQueueFamilyIndices must: be unique and must: be less than
|
|
pname:pQueueFamilyPropertyCount returned by either
|
|
flink:vkGetPhysicalDeviceQueueFamilyProperties or
|
|
flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the
|
|
pname:physicalDevice that was used to create pname:device
|
|
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
* [[VUID-VkBufferCreateInfo-flags-00915]]
|
|
If the <<features-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_VERSION_1_1,VK_KHR_external_memory[]
|
|
* [[VUID-VkBufferCreateInfo-pNext-00920]]
|
|
If the pname:pNext chain contains an instance of
|
|
slink:VkExternalMemoryBufferCreateInfo, its pname:handleTypes member
|
|
must: only contain bits that are also in
|
|
slink:VkExternalBufferProperties::pname:externalMemoryProperties.pname:compatibleHandleTypes,
|
|
as returned by flink:vkGetPhysicalDeviceExternalBufferProperties with
|
|
pname:pExternalBufferInfo\->pname:handleType equal to any one of the
|
|
handle types specified in
|
|
slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-VkBufferCreateInfo-flags-01887]]
|
|
If the protected memory feature is not enabled, pname:flags must: not
|
|
contain ename:VK_BUFFER_CREATE_PROTECTED_BIT
|
|
* [[VUID-VkBufferCreateInfo-None-01888]]
|
|
If any of the bits ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT,
|
|
ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or
|
|
ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT are set,
|
|
ename:VK_BUFFER_CREATE_PROTECTED_BIT must: not also be set
|
|
endif::VK_VERSION_1_1[]
|
|
ifdef::VK_NV_dedicated_allocation[]
|
|
* [[VUID-VkBufferCreateInfo-pNext-01571]]
|
|
If the pname:pNext chain contains an instance of
|
|
slink:VkDedicatedAllocationBufferCreateInfoNV, and the
|
|
pname:dedicatedAllocation member of the chained structure is
|
|
ename:VK_TRUE, then pname:flags must: not include
|
|
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT,
|
|
ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or
|
|
ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT
|
|
endif::VK_NV_dedicated_allocation[]
|
|
****
|
|
|
|
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='VkBufferUsageFlags',desc='Bitmask of VkBufferUsageFlagBits',type='enums']
|
|
--
|
|
include::../api/flags/VkBufferUsageFlags.txt[]
|
|
|
|
sname:VkBufferUsageFlags is a bitmask type for setting a mask of zero or
|
|
more slink:VkBufferUsageFlagBits.
|
|
--
|
|
|
|
[open,refpage='VkBufferCreateFlagBits',desc='Bitmask specifying additional parameters of a buffer',type='enums']
|
|
--
|
|
|
|
Bits which can: be set in slink:VkBufferCreateInfo::pname:flags, specifying
|
|
additional parameters of a buffer, are:
|
|
|
|
include::../api/enums/VkBufferCreateFlagBits.txt[]
|
|
|
|
* ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT specifies that the buffer will
|
|
be backed using sparse memory binding.
|
|
* ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT specifies that the buffer
|
|
can: be partially backed using sparse memory binding.
|
|
Buffers created with this flag must: also be created with the
|
|
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag.
|
|
* ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT specifies that the buffer will
|
|
be backed using sparse memory binding with memory ranges that might also
|
|
simultaneously be backing another buffer (or another portion of the same
|
|
buffer).
|
|
Buffers created with this flag must: also be created with the
|
|
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag.
|
|
ifdef::VK_VERSION_1_1[]
|
|
* ename:VK_BUFFER_CREATE_PROTECTED_BIT specifies that the buffer is a
|
|
protected buffer.
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and
|
|
<<features-features,Physical Device Features>> for details of the sparse
|
|
memory features supported on a device.
|
|
|
|
--
|
|
|
|
[open,refpage='VkBufferCreateFlags',desc='Bitmask of VkBufferCreateFlagBits',type='enums']
|
|
--
|
|
include::../api/flags/VkBufferCreateFlags.txt[]
|
|
|
|
sname:VkBufferCreateFlags is a bitmask type for setting a mask of zero or
|
|
more slink:VkBufferCreateFlagBits.
|
|
--
|
|
|
|
ifdef::VK_NV_dedicated_allocation[]
|
|
|
|
[open,refpage='VkDedicatedAllocationBufferCreateInfoNV',desc='Specify that a buffer is bound to a dedicated memory resource',type='structs']
|
|
--
|
|
|
|
If the pname:pNext chain includes a
|
|
sname:VkDedicatedAllocationBufferCreateInfoNV structure, then that structure
|
|
includes an enable controlling whether the buffer will have a dedicated
|
|
memory allocation bound to it.
|
|
|
|
The sname:VkDedicatedAllocationBufferCreateInfoNV structure is defined as:
|
|
|
|
include::../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 specifies whether the buffer will have a
|
|
dedicated allocation bound to it.
|
|
|
|
include::../validity/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[]
|
|
--
|
|
|
|
endif::VK_NV_dedicated_allocation[]
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
|
|
[open,refpage='VkExternalMemoryBufferCreateInfo',desc='Specify that a buffer may be backed by external memory',type='structs']
|
|
--
|
|
|
|
To define a set of external memory handle types that may: be used as backing
|
|
store for a buffer, add a slink:VkExternalMemoryBufferCreateInfo structure
|
|
to the pname:pNext chain of the slink:VkBufferCreateInfo structure.
|
|
The sname:VkExternalMemoryBufferCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkExternalMemoryBufferCreateInfo.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkExternalMemoryBufferCreateInfoKHR.txt[]
|
|
endif::VK_KHR_external_memory[]
|
|
|
|
* 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:VkExternalMemoryHandleTypeFlagBits specifying one or more external
|
|
memory handle types.
|
|
|
|
include::../validity/structs/VkExternalMemoryBufferCreateInfo.txt[]
|
|
--
|
|
|
|
endif::VK_VERSION_1_1,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='VkBufferViewCreateFlags',desc='Reserved for future use',type='enums']
|
|
--
|
|
include::../api/flags/VkBufferViewCreateFlags.txt[]
|
|
|
|
sname:VkBufferViewCreateFlags is a bitmask type for setting a mask, but is
|
|
currently reserved for future use.
|
|
--
|
|
|
|
[open,refpage='vkDestroyBufferView',desc='Destroy a buffer view object',type='protos']
|
|
--
|
|
|
|
To destroy a buffer view, call:
|
|
|
|
include::../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_VERSION_1_1,VK_KHR_external_memory_capabilities[]
|
|
slink:VkExternalMemoryImageCreateInfo::pname:handleTypes
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory_capabilities[]
|
|
and pname:flags, call
|
|
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
flink:vkGetPhysicalDeviceImageFormatProperties2.
|
|
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
flink:vkGetPhysicalDeviceImageFormatProperties.
|
|
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
The return value specifies whether that combination of image settings is
|
|
supported.
|
|
On success, the sname:VkImageFormatProperties output parameter specifies the
|
|
set of valid pname:samples bits and the limits for pname:extent,
|
|
pname:mipLevels, pname:arrayLayers, and pname:maxResourceSize.
|
|
Even if
|
|
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
flink:vkGetPhysicalDeviceImageFormatProperties2.
|
|
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
ifndef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
flink:vkGetPhysicalDeviceImageFormatProperties.
|
|
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
returns success and the parameters to vkCreateImage are all within the
|
|
returned limits, fname:vkCreateImage must: fail and return
|
|
ename:VK_ERROR_OUT_OF_DEVICE_MEMORY if the resulting size of the image would
|
|
be larger than pname:maxResourceSize.
|
|
|
|
To determine the set of valid pname:usage bits for a given format, call
|
|
flink:vkGetPhysicalDeviceFormatProperties.
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
For images created without ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a
|
|
pname:usage bit is valid if it is supported for the format the image is
|
|
created with.
|
|
|
|
For images created with ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT a
|
|
pname:usage bit is valid if it is supported for at least one of the formats
|
|
a sname:VkImageView created from the image can: have (see
|
|
<<resources-image-views,Image Views>> for more detail).
|
|
====
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
|
|
.Valid Usage
|
|
****
|
|
ifndef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
* [[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.
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
* [[VUID-VkImageCreateInfo-pNext-01889]]
|
|
If the pname:pNext chain does not contain an instance of
|
|
slink:VkExternalFormatANDROID, or if pname:format is not
|
|
ename:VK_FORMAT_UNDEFINED, 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.
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
* [[VUID-VkImageCreateInfo-sharingMode-00941]]
|
|
If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT,
|
|
pname:pQueueFamilyIndices must: be a valid pointer to an array of
|
|
pname:queueFamilyIndexCount 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_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
* [[VUID-VkImageCreateInfo-sharingMode-01392]]
|
|
If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element
|
|
of pname:pQueueFamilyIndices must: be unique and must: be less than
|
|
pname:pQueueFamilyPropertyCount returned by
|
|
flink:vkGetPhysicalDeviceQueueFamilyProperties for the
|
|
pname:physicalDevice that was used to create pname:device
|
|
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
* [[VUID-VkImageCreateInfo-sharingMode-01420]]
|
|
If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT, each element
|
|
of pname:pQueueFamilyIndices must: be unique and must: be less than
|
|
pname:pQueueFamilyPropertyCount returned by either
|
|
flink:vkGetPhysicalDeviceQueueFamilyProperties or
|
|
flink:vkGetPhysicalDeviceQueueFamilyProperties2 for the
|
|
pname:physicalDevice that was used to create pname:device
|
|
endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[]
|
|
* [[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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageCreateInfo-flags-00950]]
|
|
If pname:flags contains ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT,
|
|
pname:imageType must: be ename:VK_IMAGE_TYPE_3D
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageCreateInfo-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/pname: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/pname: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/pname:height/pname: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]]
|
|
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-flags-01924]]
|
|
If the <<features-features-sparseResidencyAliased,sparse aliased
|
|
residency>> feature is not enabled, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_ALIASED_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-flags-00987]]
|
|
If pname:flags contains ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or
|
|
ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, it must: also contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT
|
|
* [[VUID-VkImageCreateInfo-None-01925]]
|
|
If any of the bits ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT,
|
|
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or
|
|
ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set,
|
|
ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT must: not also be set
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-VkImageCreateInfo-flags-01890]]
|
|
If the protected memory feature is not enabled, pname:flags must: not
|
|
contain ename:VK_IMAGE_CREATE_PROTECTED_BIT.
|
|
* [[VUID-VkImageCreateInfo-None-01891]]
|
|
If any of the bits ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT,
|
|
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or
|
|
ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set,
|
|
ename:VK_IMAGE_CREATE_PROTECTED_BIT must: not also be set.
|
|
endif::VK_VERSION_1_1[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
ifdef::VK_NV_external_memory[]
|
|
* [[VUID-VkImageCreateInfo-pNext-00988]]
|
|
If the pname:pNext chain contains an instance of
|
|
slink:VkExternalMemoryImageCreateInfoNV, it must: not contain an
|
|
instance of slink:VkExternalMemoryImageCreateInfo.
|
|
endif::VK_NV_external_memory[]
|
|
* [[VUID-VkImageCreateInfo-pNext-00990]]
|
|
If the pname:pNext chain contains an instance of
|
|
slink:VkExternalMemoryImageCreateInfo, its pname:handleTypes member
|
|
must: only contain bits that are also in
|
|
slink:VkExternalImageFormatProperties::pname:externalMemoryProperties::pname:compatibleHandleTypes,
|
|
as returned by flink:vkGetPhysicalDeviceImageFormatProperties2 with
|
|
pname:format, pname:imageType, pname:tiling, pname:usage, and
|
|
pname:flags equal to those in this structure, and with an instance of
|
|
slink:VkPhysicalDeviceExternalImageFormatInfo in the pname:pNext chain,
|
|
with a pname:handleType equal to any one of the handle types specified
|
|
in slink:VkExternalMemoryImageCreateInfo::pname:handleTypes
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
ifdef::VK_NV_external_memory+VK_NV_external_memory_capabilities[]
|
|
* [[VUID-VkImageCreateInfo-pNext-00991]]
|
|
If the pname:pNext chain 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_VERSION_1_1,VK_KHR_device_group[]
|
|
* [[VUID-VkImageCreateInfo-physicalDeviceCount-01421]]
|
|
If the logical device was created with
|
|
slink:VkDeviceGroupDeviceCreateInfo::pname:physicalDeviceCount equal to
|
|
1, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
|
|
* [[VUID-VkImageCreateInfo-flags-00992]]
|
|
If pname:flags contains
|
|
ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT, then
|
|
pname:mipLevels must: be one, pname:arrayLayers must: be one,
|
|
pname:imageType must: be ename:VK_IMAGE_TYPE_2D, and pname:tiling must:
|
|
be ename:VK_IMAGE_TILING_OPTIMAL
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
* [[VUID-VkImageCreateInfo-flags-01572]]
|
|
If pname:flags contains
|
|
ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then pname:format
|
|
must: be a <<appendix-compressedtex-bc,block-compressed image format>>,
|
|
an <<appendix-compressedtex-etc2, ETC compressed image format>>, or an
|
|
<<appendix-compressedtex-astc, ASTC compressed image format>>.
|
|
* [[VUID-VkImageCreateInfo-flags-01573]]
|
|
If pname:flags contains
|
|
ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT, then pname:flags
|
|
must: also contain ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
* [[VUID-VkImageCreateInfo-initialLayout-00993]]
|
|
pname:initialLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or
|
|
ename:VK_IMAGE_LAYOUT_PREINITIALIZED.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[]
|
|
* [[VUID-VkImageCreateInfo-pNext-01443]]
|
|
If the pname:pNext chain includes a
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[slink:VkExternalMemoryImageCreateInfo]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
ifdef::VK_NV_external_memory[or]
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
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_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageCreateInfo-format-01574]]
|
|
If the image pname:format is one of those listed in
|
|
<<features-formats-requiring-sampler-ycbcr-conversion>>:
|
|
** pname:mipLevels must: be 1
|
|
** pname:samples must be ename:VK_SAMPLE_COUNT_1_BIT
|
|
** pname:imageType must: be ename:VK_IMAGE_TYPE_2D
|
|
** pname:arrayLayers must: be 1
|
|
* [[VUID-VkImageCreateInfo-tiling-01575]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, pname:format is a
|
|
_multi-planar_ format, and
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include ename:VK_FORMAT_FEATURE_DISJOINT_BIT,
|
|
pname:flags must: not contain ename:VK_IMAGE_CREATE_DISJOINT_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-01576]]
|
|
If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, pname:format is a
|
|
_multi-planar_ format, and
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include ename:VK_FORMAT_FEATURE_DISJOINT_BIT,
|
|
pname:flags must: not contain ename:VK_IMAGE_CREATE_DISJOINT_BIT
|
|
* [[VUID-VkImageCreateInfo-format-01577]]
|
|
If pname:format is not a _multi-planar_ format, and pname:flags does not
|
|
include ename:VK_IMAGE_CREATE_ALIAS_BIT, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_DISJOINT_BIT
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_EXT_sample_locations[]
|
|
* [[VUID-VkImageCreateInfo-flags-01533]]
|
|
If pname:flags contains
|
|
ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT
|
|
pname:format must: be a depth or depth/stencil format
|
|
endif::VK_EXT_sample_locations[]
|
|
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
* [[VUID-VkImageCreateInfo-pNext-01892]]
|
|
If the pname:pNext chain includes a
|
|
slink:VkExternalMemoryImageCreateInfo structure whose pname:handleTypes
|
|
member includes
|
|
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID:
|
|
** pname:imageType must: be ename:VK_IMAGE_TYPE_2D
|
|
** pname:mipLevels must: either be `1` or equal to
|
|
[eq]#{lfloor}log~2~(max(pname:extent.width, pname:extent.height,
|
|
pname:extent.depth)){rfloor} {plus} 1#.
|
|
** If pname:format is not ename:VK_FORMAT_UNDEFINED, then pname:format,
|
|
pname:imageType, pname:tiling, pname:usage, pname:flags,
|
|
pname:mipLevels, and pname:samples must: be supported with
|
|
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
|
|
external memory handle types according to
|
|
flink:vkGetPhysicalDeviceImageFormatProperties2
|
|
** If pname:format is ename:VK_FORMAT_UNDEFINED, then the pname:pNext
|
|
chain must: include a slink:VkExternalFormatANDROID structure whose
|
|
pname:externalFormat member is not `0`
|
|
* [[VUID-VkImageCreateInfo-pNext-01893]]
|
|
If the pname:pNext chain includes a slink:VkExternalFormatANDROID
|
|
structure whose pname:externalFormat member is not `0`:
|
|
** pname:format must: be ename:VK_FORMAT_UNDEFINED
|
|
** pname:flags must: not include ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
|
|
** pname:usage must: not include any usages except
|
|
pname:VK_IMAGE_USAGE_SAMPLED_BIT
|
|
** pname:tiling must: be ename:VK_IMAGE_TILING_OPTIMAL
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
****
|
|
|
|
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 chain includes a
|
|
sname:VkDedicatedAllocationImageCreateInfoNV structure, then that structure
|
|
includes an enable controlling whether the image will have a dedicated
|
|
memory allocation bound to it.
|
|
|
|
The sname:VkDedicatedAllocationImageCreateInfoNV structure is defined as:
|
|
|
|
include::../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 specifies whether the image will have a
|
|
dedicated allocation bound to it.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Using a dedicated allocation for color and depth/stencil attachments or
|
|
other large images may: improve performance on some devices.
|
|
====
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkDedicatedAllocationImageCreateInfoNV-dedicatedAllocation-00994]]
|
|
If pname:dedicatedAllocation is ename:VK_TRUE,
|
|
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_VERSION_1_1,VK_KHR_external_memory[]
|
|
|
|
[open,refpage='VkExternalMemoryImageCreateInfo',desc='Specify that an image may be backed by external memory',type='structs']
|
|
--
|
|
|
|
To define a set of external memory handle types that may: be used as backing
|
|
store for an image, add a slink:VkExternalMemoryImageCreateInfo structure to
|
|
the pname:pNext chain of the slink:VkImageCreateInfo structure.
|
|
The sname:VkExternalMemoryImageCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkExternalMemoryImageCreateInfo.txt[]
|
|
|
|
ifdef::VK_KHR_external_memory[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkExternalMemoryImageCreateInfoKHR.txt[]
|
|
endif::VK_KHR_external_memory[]
|
|
|
|
* 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:VkExternalMemoryHandleTypeFlagBits specifying one or more external
|
|
memory handle types.
|
|
|
|
include::../validity/structs/VkExternalMemoryImageCreateInfo.txt[]
|
|
--
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
|
|
ifdef::VK_NV_external_memory[]
|
|
|
|
[open,refpage='VkExternalMemoryImageCreateInfoNV',desc='Specify that an image may be backed by external memory',type='structs']
|
|
--
|
|
|
|
If the pname:pNext chain includes a sname:VkExternalMemoryImageCreateInfoNV
|
|
structure, then that structure defines a set of external memory handle types
|
|
that may: be used as backing store for the image.
|
|
|
|
The sname:VkExternalMemoryImageCreateInfoNV structure is defined as:
|
|
|
|
include::../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_ANDROID_external_memory_android_hardware_buffer[]
|
|
[open,refpage='VkExternalFormatANDROID',desc='Structure containing an Android hardware buffer external format',type='structs']
|
|
--
|
|
|
|
To create an image with an
|
|
<<memory-external-android-hardware-buffer-external-formats,external
|
|
format>>, include an instance of sname:VkExternalFormatANDROID in the
|
|
pname:pNext chain of sname:VkImageCreateInfo.
|
|
sname:VkExternalFormatANDROID is defined as:
|
|
|
|
include::../api/structs/VkExternalFormatANDROID.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:externalFormat is an implementation-defined identifier for the
|
|
external format
|
|
|
|
If pname:externalFormat is zero, the effect is as if the
|
|
sname:VkExternalFormatANDROID structure was not present.
|
|
Otherwise, the image will have the specified external format, and
|
|
sname:VkImageCreateInfo::pname:format must: be ename:VK_FORMAT_UNDEFINED.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkExternalFormatANDROID-externalFormat-01894]]
|
|
pname:externalFormat must: be `0` or a value returned in the
|
|
pname:externalFormat member of
|
|
slink:VkAndroidHardwareBufferFormatPropertiesANDROID by an earlier call
|
|
to flink:vkGetAndroidHardwareBufferPropertiesANDROID
|
|
****
|
|
|
|
include::../validity/structs/VkExternalFormatANDROID.txt[]
|
|
|
|
--
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
ifdef::VK_KHR_swapchain[]
|
|
|
|
[open,refpage='VkImageSwapchainCreateInfoKHR',desc='Specify that an image will be bound to swapchain memory',type='structs']
|
|
--
|
|
|
|
If the pname:pNext chain of slink:VkImageCreateInfo includes a
|
|
sname:VkImageSwapchainCreateInfoKHR structure, then that structure includes
|
|
a swapchain handle indicating that the image will be bound to memory from
|
|
that swapchain.
|
|
|
|
The sname:VkImageSwapchainCreateInfoKHR structure is defined as:
|
|
|
|
include::../api/structs/VkImageSwapchainCreateInfoKHR.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-VkImageSwapchainCreateInfoKHR-swapchain-00995]]
|
|
If pname:swapchain is not dlink:VK_NULL_HANDLE, the fields of
|
|
slink:VkImageCreateInfo must: match the
|
|
<<swapchain-wsi-image-create-info, implied image creation parameters>>
|
|
of the swapchain
|
|
****
|
|
|
|
include::../validity/structs/VkImageSwapchainCreateInfoKHR.txt[]
|
|
--
|
|
|
|
endif::VK_KHR_swapchain[]
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
|
|
ifdef::VK_KHR_image_format_list[]
|
|
|
|
[open,refpage='VkImageFormatListCreateInfoKHR',desc='Specify that an image can: be used with a particular set of formats',type='structs']
|
|
--
|
|
|
|
If the pname:pNext list of slink:VkImageCreateInfo includes a
|
|
sname:VkImageFormatListCreateInfoKHR structure, then that structure contains
|
|
a list of all formats that can: be used when creating views of this image.
|
|
|
|
The sname:VkImageFormatListCreateInfoKHR structure is defined as:
|
|
|
|
include::../api/structs/VkImageFormatListCreateInfoKHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:viewFormatCount is the number of entries in the pname:pViewFormats
|
|
array.
|
|
* pname:pViewFormats is an array which lists of all formats which can: be
|
|
used when creating views of this image.
|
|
|
|
If pname:viewFormatCount is zero, pname:pViewFormats is ignored and the
|
|
image is created as if the sname:VkImageFormatListCreateInfoKHR structure
|
|
were not included in the pname:pNext list of slink:VkImageCreateInfo.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageFormatListCreateInfoKHR-viewFormatCount-01578]]
|
|
If pname:viewFormatCount is not `0`, all of the formats in the
|
|
pname:pViewFormats array must: be compatible with the format specified
|
|
in the pname:format field of sname:VkImageCreateInfo, as described in
|
|
the <<resources-image-views-compatibility,compatibility table>>.
|
|
* [[VUID-VkImageFormatListCreateInfoKHR-flags-01579]]
|
|
If sname:VkImageCreateInfo::pname:flags does not contain
|
|
ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT, pname:viewFormatCount must: be
|
|
`0` or `1`.
|
|
* [[VUID-VkImageFormatListCreateInfoKHR-viewFormatCount-01580]]
|
|
If pname:viewFormatCount is not `0`,
|
|
sname:VkImageCreateInfo::pname:format must: be in pname:pViewFormats.
|
|
****
|
|
|
|
include::../validity/structs/VkImageFormatListCreateInfoKHR.txt[]
|
|
--
|
|
|
|
endif::VK_KHR_image_format_list[]
|
|
|
|
[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='VkImageUsageFlags',desc='Bitmask of VkImageUsageFlagBits',type='enums']
|
|
--
|
|
include::../api/flags/VkImageUsageFlags.txt[]
|
|
|
|
sname:VkImageUsageFlags is a bitmask type for setting a mask of zero or more
|
|
slink:VkImageUsageFlagBits.
|
|
--
|
|
|
|
[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.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
For <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar>>
|
|
formats, ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT specifies that a
|
|
sname:VkImageView can be created of a _plane_ of the image.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT specifies that the image can:
|
|
be used to create a sname:VkImageView of type
|
|
ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT specifies that the image
|
|
can: be used to create a sname:VkImageView of type
|
|
ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
ifdef::VK_VERSION_1_1[]
|
|
* ename:VK_IMAGE_CREATE_PROTECTED_BIT specifies that the image is a
|
|
protected image.
|
|
endif::VK_VERSION_1_1[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
* ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT specifies that the
|
|
image can: be used with a non-zero value of the
|
|
pname:splitInstanceBindRegionCount member of a
|
|
slink:VkBindImageMemoryDeviceGroupInfo structure passed into
|
|
flink:vkBindImageMemory2.
|
|
This flag also has the effect of making the image use the standard
|
|
sparse image block dimensions.
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
* ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT specifies that the
|
|
image having a compressed format can: be used to create a
|
|
sname:VkImageView with an uncompressed format where each texel in the
|
|
image view corresponds to a compressed texel block of the image.
|
|
* ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT specifies that the image can:
|
|
be created with usage flags that are not supported for the format the
|
|
image is created with but are supported for at least one format a
|
|
sname:VkImageView created from the image can: have.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* ename:VK_IMAGE_CREATE_DISJOINT_BIT specifies that an image with a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>> must: have each plane separately bound to memory, rather than
|
|
having a single memory binding for the whole image; the presence of this
|
|
bit distinguishes a _disjoint image_ from an image without this bit set.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
* ename:VK_IMAGE_CREATE_ALIAS_BIT specifies that two images created with
|
|
the same creation parameters and aliased to the same memory can:
|
|
interpret the contents of the memory consistently with each other,
|
|
subject to the rules described in the <<resources-memory-aliasing,Memory
|
|
Aliasing>> section.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
This flag further specifies that each plane of a _disjoint_ image can:
|
|
share an in-memory non-linear representation with single-plane images,
|
|
and that a single-plane image can: share an in-memory non-linear
|
|
representation with a plane of a multi-planar disjoint image, according
|
|
to the rules in <<features-formats-compatible-planes>>.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[]
|
|
If the pname:pNext chain includes a
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[slink:VkExternalMemoryImageCreateInfo]
|
|
// @Jon: logic needs to incorporate VK_VERSION_1_1
|
|
ifdef::VK_KHR_external_memory+VK_NV_external_memory[or]
|
|
ifdef::VK_NV_external_memory[slink:VkExternalMemoryImageCreateInfoNV]
|
|
structure whose pname:handleTypes member is not `0`, it is as if
|
|
ename:VK_IMAGE_CREATE_ALIAS_BIT is set.
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory,VK_NV_external_memory[]
|
|
endif::VK_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
ifdef::VK_EXT_sample_locations[]
|
|
* ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT
|
|
specifies that an image with a depth or depth/stencil format can: be
|
|
used with custom sample locations when used as a depth/stencil
|
|
attachment.
|
|
endif::VK_EXT_sample_locations[]
|
|
|
|
See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and
|
|
<<sparsememory-physicalfeatures,Sparse Physical Device Features>> for more
|
|
details.
|
|
|
|
--
|
|
|
|
[open,refpage='VkImageCreateFlags',desc='Bitmask of VkImageCreateFlagBits',type='enums']
|
|
--
|
|
include::../api/flags/VkImageCreateFlags.txt[]
|
|
|
|
sname:VkImageCreateFlags is a bitmask type for setting a mask of zero or
|
|
more slink:VkImageCreateFlagBits.
|
|
--
|
|
|
|
[open,refpage='VkImageType',desc='Specifies the type of an image object',type='enums']
|
|
--
|
|
|
|
Possible values of slink:VkImageCreateInfo::pname:imageType, specifying the
|
|
basic dimensionality of an image, are:
|
|
|
|
include::../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.
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
If the elink:VkFormat of pname:image is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar format>>,
|
|
fname:vkGetImageSubresourceLayout describes one plane of the image.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
flink:vkGetImageSubresourceLayout is invariant for the lifetime of a single
|
|
image.
|
|
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
However, the subresource layout of images in Android hardware buffer
|
|
external memory is not known until the image has been bound to memory, so
|
|
calling fname:vkGetImageSubresourceLayout for such an image before it has
|
|
been bound will result in undefined behavior.
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
|
|
.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
|
|
* [[VUID-vkGetImageSubresourceLayout-mipLevel-01716]]
|
|
The pname:mipLevel member of pname:pSubresource must: be less than the
|
|
pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* [[VUID-vkGetImageSubresourceLayout-arrayLayer-01717]]
|
|
The pname:arrayLayer member of pname:pSubresource must: be less than the
|
|
pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkGetImageSubresourceLayout-format-01581]]
|
|
If the pname:format of pname:image is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>> with two planes, the pname:aspectMask member of
|
|
pname:pSubresource must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT or
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT
|
|
* [[VUID-vkGetImageSubresourceLayout-format-01582]]
|
|
If the pname:format of pname:image is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
format>> with three planes, the pname:aspectMask member of
|
|
pname:pSubresource must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT,
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
* [[VUID-vkGetImageSubresourceLayout-image-01895]]
|
|
If pname:image was created with the
|
|
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
|
|
external memory handle type, then pname:image must: be bound to memory.
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
****
|
|
|
|
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.
|
|
|
|
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
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
_single-plane_
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
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.
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
For <<features-formats-requiring-sampler-ycbcr-conversion,multi-planar
|
|
formats>>, the pname:aspectMask member of sname:VkImageSubresource must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
(for 3-plane formats only) ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
|
|
Querying each of these image subresource layouts will return a different
|
|
pname:offset and pname:size representing the region of memory used for that
|
|
plane.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
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 a 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.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
* ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL: must:
|
|
only be used as a depth/stencil attachment in a sname:VkFramebuffer,
|
|
where the depth aspect is read-only, 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) where only the depth aspect is accessed.
|
|
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 a 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_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL: must:
|
|
only be used as a depth/stencil attachment in a sname:VkFramebuffer,
|
|
where the stencil aspect is read-only, 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) where only the stencil aspect is accessed.
|
|
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 a 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.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
* 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[]
|
|
|
|
The layout of each image subresource is not a state of the image subresource
|
|
itself, but is rather a property of how the data in memory is organized, and
|
|
thus for each mechanism of accessing an image in the API the application
|
|
must: specify a parameter or structure member that indicates which image
|
|
layout the image subresource(s) are considered to be in when the image will
|
|
be accessed.
|
|
For transfer commands, this is a parameter to the command (see <<clears>>
|
|
and <<copies>>).
|
|
For use as a framebuffer attachment, this is a member in the substructures
|
|
of the 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.
|
|
|
|
When performing a layout transition on an image subresource, the old layout
|
|
value must: either equal the current layout of the image subresource (at the
|
|
time the transition executes), or else be ename:VK_IMAGE_LAYOUT_UNDEFINED
|
|
(implying that the contents of the image subresource need not be preserved).
|
|
The new layout used in a transition must: not be
|
|
ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED.
|
|
|
|
ifdef::VK_EXT_sample_locations[]
|
|
|
|
The image layout of each image subresource of a depth/stencil image created
|
|
with ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT is
|
|
dependent on the last sample locations used to render to the image
|
|
subresource as a depth/stencil attachment, thus applications must: provide
|
|
the same sample locations that were last used to render to the given image
|
|
subresource whenever a layout transition of the image subresource happens,
|
|
otherwise the contents of the depth aspect of the image subresource become
|
|
undefined.
|
|
|
|
In addition, depth reads from a depth/stencil attachment referring to an
|
|
image subresource range of a depth/stencil image created with
|
|
ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using
|
|
different sample locations than what have been last used to perform depth
|
|
writes to the image subresources of the same image subresource range produce
|
|
undefined results.
|
|
|
|
Similarly, depth writes to a depth/stencil attachment referring to an image
|
|
subresource range of a depth/stencil image created with
|
|
ename:VK_IMAGE_CREATE_SAMPLE_LOCATIONS_COMPATIBLE_DEPTH_BIT_EXT using
|
|
different sample locations than what have been last used to perform depth
|
|
writes to the image subresources of the same image subresource range make
|
|
the contents of the depth aspect of those image subresources undefined.
|
|
|
|
endif::VK_EXT_sample_locations[]
|
|
|
|
--
|
|
|
|
|
|
[[resources-image-views]]
|
|
== Image Views
|
|
|
|
[open,refpage='VkImageView',desc='Opaque handle to 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.
|
|
In particular, image view creation inherits the implicit parameter
|
|
pname:usage specifying the allowed usages of the image view that, by
|
|
default, takes the value of the corresponding pname:usage parameter
|
|
specified in sname:VkImageCreateInfo at image creation time.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
This implicit parameter can: be overriden by chaining a
|
|
slink:VkImageViewUsageCreateInfo structure through the pname:pNext member to
|
|
sname:VkImageViewCreateInfo as described later in this section.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
|
|
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,
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
and if the pname:format of the image is not
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar>>,
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:format can: be different from the image's format, but if
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
pname:image was created without the
|
|
ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag and
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
they are not equal they must: be _compatible_.
|
|
Image format compatibility is defined in the
|
|
<<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.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Values intended to be used with one view format may: not be exactly
|
|
preserved when written or read through a different format.
|
|
For example, an integer value that happens to have the bit pattern of a
|
|
floating point denorm or NaN may: be flushed or canonicalized when written
|
|
or read through a view with a floating point format.
|
|
Similarly, a value written through a signed normalized format that has a bit
|
|
pattern exactly equal to [eq]#-2^b^# may: be changed to [eq]#-2^b^ {plus} 1#
|
|
as described in <<fundamentals-fixedfpconv,Conversion from Normalized
|
|
Fixed-Point to Floating-Point>>.
|
|
====
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
If pname:image was created with the
|
|
ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format
|
|
must: be _compatible_ with the image's format as described above, or must:
|
|
be an uncompressed format in which case it must: be _size-compatible_ with
|
|
the image's format, as defined for
|
|
<<copies-images-format-size-compatibility, copying data between images>> In
|
|
this case the resulting image view's texel dimensions equal the dimensions
|
|
of the selected mip level divided by the compressed texel block size and
|
|
rounded up.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
If the image view is to be used with a sampler which supports
|
|
<<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>>, an _identically
|
|
defined object_ of type slink:VkSamplerYcbcrConversion to that used to
|
|
create the sampler must: be passed to flink:vkCreateImageView in a
|
|
slink:VkSamplerYcbcrConversionInfo added to the pname:pNext chain of
|
|
slink:VkImageViewCreateInfo.
|
|
|
|
If the image has a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar>>
|
|
pname:format and pname:subresourceRange.aspectMask is
|
|
ename:VK_IMAGE_ASPECT_COLOR_BIT, pname:format must: be identical to the
|
|
image pname:format, and the sampler to be used with the image view must:
|
|
enable <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>>.
|
|
|
|
If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
|
|
and the image has a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar>>
|
|
pname:format, and if pname:subresourceRange.aspectMask is
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT, pname:format must: be
|
|
<<features-formats-compatible-planes,compatible>> with the corresponding
|
|
plane of the image, and the sampler to be used with the image view must: not
|
|
enable <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~ conversion>>.
|
|
The pname:width and pname:height of the single-plane image view must: be
|
|
derived from the multi-planar image's dimensions in the manner listed for
|
|
<<features-formats-compatible-planes,plane compatibility>> for the plane.
|
|
|
|
Any view of an image plane will have the same mapping between texel
|
|
coordinates and memory locations as used by the channels of the color
|
|
aspect, subject to the formulae relating texel coordinates to
|
|
lower-resolution planes as described in <<textures-chroma-reconstruction,
|
|
Chroma Reconstruction>>.
|
|
That is, if an R or B plane has a reduced resolution relative to the G plane
|
|
of the multi-planar image, the image view operates using the (_u~plane~_,
|
|
_v~plane~_) unnormalized coordinates of the reduced-resolution plane, and
|
|
these coordinates access the same memory locations as the (_u~color~_,
|
|
_v~color~_) unnormalized coordinates of the color aspect for which chroma
|
|
reconstruction operations operate on the same (_u~plane~_, _v~plane~_) or
|
|
(_i~plane~_, _j~plane~_) coordinates.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
[[resources-image-views-compatibility]]
|
|
.Image 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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
| pname:baseArrayLayer, pname:layerCount, and pname:levelCount
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
| pname:baseArrayLayer and pname:layerCount
|
|
endif::VK_VERSION_1_1,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_VERSION_1_1,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_VERSION_1_1,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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01005]]
|
|
If pname:image was created with ename:VK_IMAGE_TYPE_3D but without
|
|
ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set then pname:viewType
|
|
must: not be ename:VK_IMAGE_VIEW_TYPE_2D or
|
|
ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY
|
|
endif::VK_VERSION_1_1,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.baseMipLevel must: be less than the
|
|
pname:mipLevels specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* [[VUID-VkImageViewCreateInfo-subresourceRange-01718]]
|
|
If pname:subresourceRange.levelCount is not
|
|
ename:VK_REMAINING_MIP_LEVELS, [eq]#pname:subresourceRange.baseMipLevel
|
|
{plus} pname:subresourceRange.levelCount# must: be less than or equal to
|
|
the pname:mipLevels specified in slink:VkImageCreateInfo when
|
|
pname:image was created
|
|
ifndef::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageViewCreateInfo-subresourceRange-01480]]
|
|
pname:subresourceRange.baseArrayLayer must: be less than the
|
|
pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
* [[VUID-VkImageViewCreateInfo-subresourceRange-01719]]
|
|
If pname:subresourceRange.layerCount is not
|
|
ename:VK_REMAINING_ARRAY_LAYERS,
|
|
[eq]#pname:subresourceRange.baseArrayLayer {plus}
|
|
pname:subresourceRange.layerCount# must: be less than or equal to the
|
|
pname:arrayLayers specified in slink:VkImageCreateInfo when pname:image
|
|
was created
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01482]]
|
|
If pname:image is not a 3D image created with
|
|
ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT set, or pname:viewType is
|
|
not ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY,
|
|
pname:subresourceRange::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 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 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 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_VERSION_1_1,VK_KHR_maintenance1[]
|
|
// The VU below comes in 3 alternate versions when the two extensions
|
|
// are enabled, or only one is.
|
|
* [[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>>
|
|
// The nested ifdefs are there in anticipation of the hoped-for day when the
|
|
// VU extractor and validation layers can handle VU with imbedded
|
|
// conditionals.
|
|
//
|
|
// If VK_VERSION_1_1,VK_KHR_maintenance2 and NOT VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01759]]
|
|
If pname:image was created with the
|
|
ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, but without the
|
|
ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format
|
|
must: be compatible with the pname:format used to create pname:image, as
|
|
defined in <<features-formats-compatibility-classes,Format Compatibility
|
|
Classes>>
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
// If NOT VK_VERSION_1_1,VK_KHR_maintenance2 and VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion
|
|
ifndef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01760]]
|
|
If pname:image was created with the
|
|
ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, and if the pname:format
|
|
of the pname:image is not a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar>>
|
|
format, pname:format must: be compatible with the pname:format used to
|
|
create pname:image, as defined in
|
|
<<features-formats-compatibility-classes,Format Compatibility Classes>>
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
// If VK_VERSION_1_1,VK_KHR_maintenance2 and VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01761]]
|
|
If pname:image was created with the
|
|
ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag,
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
but without the ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT
|
|
flag,
|
|
// endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
// ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
and if the pname:format of the pname:image is not a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar>>
|
|
format,
|
|
// endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:format must: be compatible with the pname:format used to create
|
|
pname:image, as defined in
|
|
<<features-formats-compatibility-classes,Format Compatibility Classes>>
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01583]]
|
|
If pname:image was created with the
|
|
ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, pname:format
|
|
must: be compatible with, or must: be an uncompressed format that is
|
|
size-compatible with, the pname:format used to create pname:image.
|
|
* [[VUID-VkImageViewCreateInfo-image-01584]]
|
|
If pname:image was created with the
|
|
ename:VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT flag, the
|
|
pname:levelCount and pname:layerCount members of pname:subresourceRange
|
|
must: both be `1`.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
ifdef::VK_KHR_image_format_list[]
|
|
* [[VUID-VkImageViewCreateInfo-pNext-01585]]
|
|
If a sname:VkImageFormatListCreateInfoKHR structure was included in the
|
|
pname:pNext chain of the sname:VkImageCreateInfo struct used when
|
|
creating pname:image and the pname:viewFormatCount field of
|
|
sname:VkImageFormatListCreateInfoKHR is not zero then pname:format must:
|
|
be one of the formats in
|
|
sname:VkImageFormatListCreateInfoKHR::pname:pViewFormats.
|
|
endif::VK_KHR_image_format_list[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01586]]
|
|
If pname:image was created with the
|
|
ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, if the pname:format of
|
|
the pname:image is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar>>
|
|
format, and if pname:subresourceRange.aspectMask is one of
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT, then pname:format must: be compatible
|
|
with the elink:VkFormat for the plane of the pname:image pname:format
|
|
indicated by pname:subresourceRange.aspectMask, as defined in
|
|
<<features-formats-compatible-planes>>
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
// The VU below comes in an alternate version when the extension is
|
|
// enabled.
|
|
* [[VUID-VkImageViewCreateInfo-image-01019]]
|
|
If pname:image was not created with the
|
|
ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be
|
|
identical to the pname:format used to create pname:image
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
// The nested ifdefs are there in anticipation of the hoped-for day when the
|
|
// VU extractor and validation layers can handle VU with imbedded
|
|
// conditionals.
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01762]]
|
|
If pname:image was not created with the
|
|
ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag,
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
or if the pname:format of the pname:image is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar>>
|
|
format and if pname:subresourceRange.aspectMask is
|
|
ename:VK_IMAGE_ASPECT_COLOR_BIT,
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
pname:format must: be identical to the pname:format used to create
|
|
pname:image
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[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>>
|
|
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01896]]
|
|
If pname:image has an
|
|
<<memory-external-android-hardware-buffer-external-formats,external
|
|
format>>:
|
|
** pname:format must: be ename:VK_FORMAT_UNDEFINED
|
|
** The pname:pNext chain must: contain an instance of
|
|
slink:VkSamplerYcbcrConversionInfo with a pname:conversion object
|
|
created with the same external format as pname:image
|
|
** All members of pname:components must: be
|
|
ename:VK_COMPONENT_SWIZZLE_IDENTITY
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
****
|
|
|
|
include::../validity/structs/VkImageViewCreateInfo.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageViewCreateFlags',desc='Reserved for future use',type='enums']
|
|
--
|
|
include::../api/flags/VkImageViewCreateFlags.txt[]
|
|
|
|
sname:VkImageViewCreateFlags is a bitmask type for setting a mask, but is
|
|
currently reserved for future use.
|
|
--
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
|
|
[open,refpage='VkImageViewUsageCreateInfo',desc='Specify the intended usage of an image view',type='structs']
|
|
--
|
|
|
|
The set of usages for the created image view can: be restricted compared to
|
|
the parent image's pname:usage flags by chaining a
|
|
sname:VkImageViewUsageCreateInfo structure through the pname:pNext member to
|
|
sname:VkImageViewCreateInfo.
|
|
|
|
The sname:VkImageViewUsageCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkImageViewUsageCreateInfo.txt[]
|
|
|
|
ifdef::VK_KHR_maintenance2[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkImageViewUsageCreateInfoKHR.txt[]
|
|
endif::VK_KHR_maintenance2[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:usage is a bitmask describing the allowed usages of the image
|
|
view.
|
|
See elink:VkImageUsageFlagBits for a description of the supported bits.
|
|
|
|
When this structure is chained to sname:VkImageViewCreateInfo the
|
|
pname:usage field overrides the implicit pname:usage parameter inherited
|
|
from image creation time and its value is used instead for the purposes of
|
|
determining the valid usage conditions of slink:VkImageViewCreateInfo.
|
|
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageViewUsageCreateInfo-usage-01587]]
|
|
pname:usage must: not include any set bits that were not set in the
|
|
pname:usage member of the slink:VkImageCreateInfo structure used to
|
|
create the image this image view is created from.
|
|
****
|
|
|
|
include::../validity/structs/VkImageViewUsageCreateInfo.txt[]
|
|
|
|
--
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance2[]
|
|
|
|
[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,
|
|
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
respectively.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
respectively, except if pname:format is a
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar format>>.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
If using a depth/stencil format with both depth and stencil components,
|
|
pname:aspectMask must: include at least one of
|
|
ename:VK_IMAGE_ASPECT_DEPTH_BIT and ename:VK_IMAGE_ASPECT_STENCIL_BIT, and
|
|
can: include both.
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
When the sname:VkImageSubresourceRange structure is used to select a subset
|
|
of the slices of a 3D image's mip level in order to create a 2D or 2D array
|
|
image view of a 3D image created with
|
|
ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT, pname:baseArrayLayer and
|
|
pname:layerCount specify the first slice index and the number of slices to
|
|
include in the created image view.
|
|
Such an image view can: be used as a framebuffer attachment that refers only
|
|
to the specified range of slices of the selected mip level.
|
|
However, any layout transitions performed on such an attachment view during
|
|
a render pass instance still apply to the entire subresource referenced
|
|
which includes all the slices of the selected mip level.
|
|
endif::VK_VERSION_1_1,VK_KHR_maintenance1[]
|
|
|
|
When using an 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,
|
|
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
and framebuffer attachments.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
framebuffer attachments, and any sname:VkImageView used with a combined
|
|
image sampler that enables <<samplers-YCbCr-conversion,sampler Y'C~B~C~R~
|
|
conversion>>.
|
|
|
|
When creating a sname:VkImageView, if <<samplers-YCbCr-conversion,sampler
|
|
Y'C~B~C~R~ conversion>> is enabled in the sampler, the pname:aspectMask of a
|
|
pname:subresourceRange used by the sname:VkImageView must: be
|
|
ename:VK_IMAGE_ASPECT_COLOR_BIT.
|
|
|
|
When creating a sname:VkImageView, if sampler Y'C~B~C~R~ conversion is not
|
|
enabled in the sampler and the image pname:format is
|
|
<<features-formats-requiring-sampler-ycbcr-conversion,multi-planar>>, the
|
|
image must: have been created with ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT,
|
|
and the pname:aspectMask of the sname:VkImageView's pname:subresourceRange
|
|
must: be ename:VK_IMAGE_ASPECT_PLANE_0_BIT,
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT or ename:VK_IMAGE_ASPECT_PLANE_2_BIT.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageSubresourceRange-levelCount-01720]]
|
|
If pname:levelCount is not ename:VK_REMAINING_MIP_LEVELS, it must: be
|
|
greater than `0`
|
|
* [[VUID-VkImageSubresourceRange-layerCount-01721]]
|
|
If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS, it must: be
|
|
greater than `0`
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkImageSubresourceRange-aspectMask-01670]]
|
|
If pname:aspectMask includes ename:VK_IMAGE_ASPECT_COLOR_BIT, then it
|
|
must: not include any of ename:VK_IMAGE_ASPECT_PLANE_0_BIT,
|
|
ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or ename:VK_IMAGE_ASPECT_PLANE_2_BIT
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
****
|
|
|
|
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='VkImageAspectFlags',desc='Bitmask of VkImageAspectFlagBits',type='enums']
|
|
--
|
|
include::../api/flags/VkImageAspectFlags.txt[]
|
|
|
|
sname:VkImageAspectFlags is a bitmask type for setting a mask of zero or
|
|
more slink:VkImageAspectFlagBits.
|
|
--
|
|
|
|
[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_VERSION_1_1,VK_KHR_device_group[]
|
|
|
|
In a logical device representing more than one physical device, buffer and
|
|
image resources exist on all physical devices but can: be bound to memory
|
|
differently on each.
|
|
Each such replicated resource is an _instance_ of the resource.
|
|
For sparse resources, each instance can: be bound to memory arbitrarily
|
|
differently.
|
|
For non-sparse resources, each instance can: either be bound to the local or
|
|
a peer instance of the memory, or for images can: be bound to rectangular
|
|
regions from the local and/or peer instances.
|
|
When a resource is used in a descriptor set, each physical device interprets
|
|
the descriptor according to its own instance's binding to memory.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
There are no new copy commands to transfer data between physical devices.
|
|
Instead, an application can: create a resource with a peer mapping and use
|
|
it as the source or destination of a transfer command executed by a single
|
|
physical device to copy the data from one physical device to another.
|
|
====
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
|
|
[open,refpage='vkGetBufferMemoryRequirements',desc='Returns the memory requirements for specified Vulkan object',type='protos']
|
|
--
|
|
|
|
To determine the memory requirements for a buffer resource, call:
|
|
|
|
include::../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']
|
|
--
|
|
|
|
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
To determine the memory requirements for an image resource, call:
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
To determine the memory requirements for an image resource which is not
|
|
created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT flag set, call:
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
include::../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.
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkGetImageMemoryRequirements-image-01588]]
|
|
pname:image must: not have been created with the
|
|
ename:VK_IMAGE_CREATE_DISJOINT_BIT flag set
|
|
****
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
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[]
|
|
--
|
|
|
|
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
The precise size of images that will be bound to external Android hardware
|
|
buffer memory is unknown until the memory has been imported or allocated, so
|
|
calling flink:vkGetImageMemoryRequirements with such an image before it has
|
|
been bound to memory will result in undefined behavior.
|
|
When importing Android hardware buffer memory, the pname:allocationSize can:
|
|
be determined by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID.
|
|
When allocating new memory for an image that can: be exported to a Android
|
|
hardware buffer, the memory's pname:allocationSize must: be zero; the actual
|
|
size will be determined by the dedicated image's parameters.
|
|
After the memory has been allocated, the amount of space allocated from the
|
|
memory's heap can: be obtained by getting the image's memory requirements or
|
|
by calling flink:vkGetAndroidHardwareBufferPropertiesANDROID with the
|
|
Android hardware buffer exported from the memory.
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
|
|
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_VERSION_1_1,VK_KHR_external_memory[]
|
|
* If pname:buffer was created with
|
|
slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes set to `0` or
|
|
pname:image was created with
|
|
slink:VkExternalMemoryImageCreateInfo::pname:handleTypes set to `0`, the
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
ifndef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
* The
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
pname:memoryTypeBits member always contains at least one bit set
|
|
corresponding to a sname:VkMemoryType with a pname:propertyFlags that
|
|
has the ename:VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT bit set.
|
|
* The pname:memoryTypeBits member is identical for all sname:VkBuffer
|
|
objects created with the same value for the pname:flags and pname:usage
|
|
members in the sname:VkBufferCreateInfo structure
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
and the pname:handleTypes member of the
|
|
slink:VkExternalMemoryBufferCreateInfo structure
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
passed to 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_VERSION_1_1,VK_KHR_external_memory[]
|
|
pname:flags and
|
|
slink:VkExternalMemoryBufferCreateInfo::pname:handleTypes,
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
ifndef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
pname:flags,
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
then the bits set in pname:memoryTypeBits returned for code:usage1 must:
|
|
be a subset of the bits set in pname:memoryTypeBits returned for
|
|
code:usage2, for all values of pname:flags.
|
|
* The pname:alignment member is a power of two.
|
|
* The pname:alignment member is identical for all sname:VkBuffer objects
|
|
created with the same combination of values for the pname:usage and
|
|
pname:flags members in the 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_VERSION_1_1,VK_KHR_device_group[]
|
|
the ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit of the
|
|
pname:flags member,
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
pname:handleTypes member of slink:VkExternalMemoryImageCreateInfo,
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage
|
|
member in the 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_VERSION_1_1,VK_KHR_device_group[]
|
|
the ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit of the
|
|
pname:flags member,
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
pname:handleTypes member of slink:VkExternalMemoryImageCreateInfo,
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage
|
|
member in the 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_VERSION_1_1,VK_KHR_get_memory_requirements2[]
|
|
|
|
[open,refpage='vkGetBufferMemoryRequirements2',desc='Returns the memory requirements for specified Vulkan object',type='protos']
|
|
--
|
|
|
|
To determine the memory requirements for a buffer resource, call:
|
|
|
|
ifdef::VK_VERSION_1_1[]
|
|
include::../api/protos/vkGetBufferMemoryRequirements2.txt[]
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
ifdef::VK_VERSION_1_1+VK_KHR_get_memory_requirements2[or the equivalent command]
|
|
|
|
ifdef::VK_KHR_get_memory_requirements2[]
|
|
include::../api/protos/vkGetBufferMemoryRequirements2KHR.txt[]
|
|
endif::VK_KHR_get_memory_requirements2[]
|
|
|
|
* pname:device is the logical device that owns the buffer.
|
|
* pname:pInfo is a pointer to an instance of the
|
|
sname:VkBufferMemoryRequirementsInfo2 structure containing parameters
|
|
required for the memory requirements query.
|
|
* pname:pMemoryRequirements points to an instance of the
|
|
slink:VkMemoryRequirements2 structure in which the memory requirements
|
|
of the buffer object are returned.
|
|
|
|
include::../validity/protos/vkGetBufferMemoryRequirements2.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBufferMemoryRequirementsInfo2',desc='(None)',type='structs']
|
|
--
|
|
The sname:VkBufferMemoryRequirementsInfo2 structure is defined as:
|
|
|
|
include::../api/structs/VkBufferMemoryRequirementsInfo2.txt[]
|
|
|
|
ifdef::VK_KHR_get_memory_requirements2[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkBufferMemoryRequirementsInfo2KHR.txt[]
|
|
endif::VK_KHR_get_memory_requirements2[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:buffer is the buffer to query.
|
|
|
|
include::../validity/structs/VkBufferMemoryRequirementsInfo2.txt[]
|
|
--
|
|
|
|
[open,refpage='vkGetImageMemoryRequirements2',desc='Returns the memory requirements for specified Vulkan object',type='protos']
|
|
--
|
|
|
|
To determine the memory requirements for an image resource, call:
|
|
|
|
ifdef::VK_VERSION_1_1[]
|
|
include::../api/protos/vkGetImageMemoryRequirements2.txt[]
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
ifdef::VK_VERSION_1_1+VK_KHR_get_memory_requirements2[or the equivalent command]
|
|
|
|
ifdef::VK_KHR_get_memory_requirements2[]
|
|
include::../api/protos/vkGetImageMemoryRequirements2KHR.txt[]
|
|
endif::VK_KHR_get_memory_requirements2[]
|
|
|
|
* pname:device is the logical device that owns the image.
|
|
* pname:pInfo is a pointer to an instance of the
|
|
sname:VkImageMemoryRequirementsInfo2 structure containing parameters
|
|
required for the memory requirements query.
|
|
* pname:pMemoryRequirements points to an instance of the
|
|
slink:VkMemoryRequirements2 structure in which the memory requirements
|
|
of the image object are returned.
|
|
|
|
include::../validity/protos/vkGetImageMemoryRequirements2.txt[]
|
|
--
|
|
|
|
[open,refpage='VkImageMemoryRequirementsInfo2',desc='(None)',type='structs']
|
|
--
|
|
The sname:VkImageMemoryRequirementsInfo2 structure is defined as:
|
|
|
|
include::../api/structs/VkImageMemoryRequirementsInfo2.txt[]
|
|
|
|
ifdef::VK_KHR_get_memory_requirements2[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkImageMemoryRequirementsInfo2KHR.txt[]
|
|
endif::VK_KHR_get_memory_requirements2[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:image is the image to query.
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageMemoryRequirementsInfo2-image-01589]]
|
|
If pname:image was created with a _multi-planar_ format and the
|
|
ename:VK_IMAGE_CREATE_DISJOINT_BIT flag, there must: be a
|
|
slink:VkImagePlaneMemoryRequirementsInfo in the pname:pNext chain of the
|
|
slink:VkImageMemoryRequirementsInfo2 structure
|
|
* [[VUID-VkImageMemoryRequirementsInfo2-image-01590]]
|
|
If pname:image was not created with the
|
|
ename:VK_IMAGE_CREATE_DISJOINT_BIT flag, there must: not be a
|
|
slink:VkImagePlaneMemoryRequirementsInfo in the pname:pNext chain of the
|
|
slink:VkImageMemoryRequirementsInfo2 structure
|
|
* [[VUID-VkImageMemoryRequirementsInfo2-image-01591]]
|
|
If pname:image was created with a single-plane format, there must: not
|
|
be a slink:VkImagePlaneMemoryRequirementsInfo in the pname:pNext chain
|
|
of the slink:VkImageMemoryRequirementsInfo2 structure
|
|
ifdef::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
* [[VUID-VkImageMemoryRequirementsInfo2-image-01897]]
|
|
If pname:image was created with the
|
|
ename:VK_EXTERNAL_MEMORY_HANDLE_TYPE_ANDROID_HARDWARE_BUFFER_BIT_ANDROID
|
|
external memory handle type, then pname:image must: be bound to memory.
|
|
endif::VK_ANDROID_external_memory_android_hardware_buffer[]
|
|
****
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
include::../validity/structs/VkImageMemoryRequirementsInfo2.txt[]
|
|
--
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
[open,refpage='VkImagePlaneMemoryRequirementsInfo',desc='Structure specifying image plane for memory requirements',type='structs']
|
|
--
|
|
|
|
To determine the memory requirements for a plane of a disjoint image, add a
|
|
sname:VkImagePlaneMemoryRequirementsInfo to the pname:pNext chain of the
|
|
sname:VkImageMemoryRequirementsInfo2 structure.
|
|
|
|
The sname:VkImagePlaneMemoryRequirementsInfo structure is defined as:
|
|
|
|
include::../api/structs/VkImagePlaneMemoryRequirementsInfo.txt[]
|
|
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkImagePlaneMemoryRequirementsInfoKHR.txt[]
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:planeAspect is the aspect corresponding to the image plane to
|
|
query.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImagePlaneMemoryRequirementsInfo-planeAspect-01592]]
|
|
pname:planeAspect must: be an aspect that exists in the format; that is,
|
|
for a two-plane image pname:planeAspect must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT,
|
|
and for a three-plane image pname:planeAspect must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT
|
|
****
|
|
|
|
include::../validity/structs/VkImagePlaneMemoryRequirementsInfo.txt[]
|
|
--
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
[open,refpage='VkMemoryRequirements2',desc='Structure specifying memory requirements',type='structs']
|
|
--
|
|
|
|
The sname:VkMemoryRequirements2 structure is defined as:
|
|
|
|
include::../api/structs/VkMemoryRequirements2.txt[]
|
|
|
|
ifdef::VK_KHR_get_memory_requirements2[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkMemoryRequirements2KHR.txt[]
|
|
endif::VK_KHR_get_memory_requirements2[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:memoryRequirements is a structure of type
|
|
slink:VkMemoryRequirements describing the memory requirements of the
|
|
resource.
|
|
|
|
include::../validity/structs/VkMemoryRequirements2.txt[]
|
|
--
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_get_memory_requirements2[]
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
|
|
[open,refpage='VkMemoryDedicatedRequirements',desc='Structure describing dedicated allocation requirements of buffer and image resources',type='structs']
|
|
--
|
|
|
|
To determine the dedicated allocation requirements of a buffer or image
|
|
resource, add a slink:VkMemoryDedicatedRequirements structure to the
|
|
pname:pNext chain of the slink:VkMemoryRequirements2 structure passed as the
|
|
pname:pMemoryRequirements parameter of fname:vkGetBufferMemoryRequirements2
|
|
or fname:vkGetImageMemoryRequirements2.
|
|
|
|
The sname:VkMemoryDedicatedRequirements structure is defined as:
|
|
|
|
include::../api/structs/VkMemoryDedicatedRequirements.txt[]
|
|
|
|
ifdef::VK_KHR_dedicated_allocation[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkMemoryDedicatedRequirementsKHR.txt[]
|
|
endif::VK_KHR_dedicated_allocation[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:prefersDedicatedAllocation specifies that the implementation would
|
|
prefer a dedicated allocation for this resource.
|
|
The application is still free to suballocate the resource but it may:
|
|
get better performance if a dedicated allocation is used.
|
|
* pname:requiresDedicatedAllocation specifies that a dedicated allocation
|
|
is required for this resource.
|
|
|
|
When the implementation sets pname:requiresDedicatedAllocation to
|
|
ename:VK_TRUE, it must: also set pname:prefersDedicatedAllocation to
|
|
ename:VK_TRUE.
|
|
|
|
If the sname:VkMemoryDedicatedRequirements structure is included in the
|
|
pname:pNext chain of the slink:VkMemoryRequirements2 structure passed as the
|
|
pname:pMemoryRequirements parameter of a
|
|
fname:vkGetBufferMemoryRequirements2 call, pname:requiresDedicatedAllocation
|
|
may: be ename:VK_TRUE under one of the following conditions:
|
|
|
|
ifndef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
* none
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
* The pname:pNext chain of sname:VkBufferCreateInfo for the call to
|
|
fname:vkCreateBuffer used to create the buffer being queried contained
|
|
an instance of sname:VkExternalMemoryBufferCreateInfo, and any of the
|
|
handle types specified in
|
|
sname:VkExternalMemoryBufferCreateInfo::pname:handleTypes requires
|
|
dedicated allocation, as reported by
|
|
flink:vkGetPhysicalDeviceExternalBufferProperties in
|
|
sname:VkExternalBufferProperties::pname:externalMemoryProperties::pname:externalMemoryFeatures,
|
|
the pname:requiresDedicatedAllocation field will be set to
|
|
ename:VK_TRUE.
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
|
|
In all other cases, pname:requiresDedicatedAllocation must: be set to
|
|
ename:VK_FALSE by the implementation whenever a
|
|
sname:VkMemoryDedicatedRequirements structure is included in the pname:pNext
|
|
chain of the sname:VkMemoryRequirements2 structure passed to a call to
|
|
fname:vkGetBufferMemoryRequirements2.
|
|
|
|
If the sname:VkMemoryDedicatedRequirements structure is included in the
|
|
pname:pNext chain of the sname:VkMemoryRequirements2 structure passed as the
|
|
pname:pMemoryRequirements parameter of a
|
|
fname:vkGetBufferMemoryRequirements2 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:VkMemoryDedicatedRequirements structure is included in the
|
|
pname:pNext chain of the sname:VkMemoryRequirements2 structure passed as the
|
|
pname:pMemoryRequirements parameter of a fname:vkGetImageMemoryRequirements2
|
|
call, pname:requiresDedicatedAllocation may: be ename:VK_TRUE under one of
|
|
the following conditions:
|
|
|
|
ifndef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
* none
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
* The pname:pNext chain of sname:VkImageCreateInfo for the call to
|
|
fname:vkCreateImage used to create the image being queried contained an
|
|
instance of sname:VkExternalMemoryImageCreateInfo, and any of the handle
|
|
types specified in
|
|
sname:VkExternalMemoryImageCreateInfo::pname:handleTypes requires
|
|
dedicated allocation, as reported by
|
|
flink:vkGetPhysicalDeviceImageFormatProperties2 in
|
|
sname:VkExternalImageFormatProperties::pname:externalMemoryProperties::pname:externalMemoryFeatures,
|
|
the pname:requiresDedicatedAllocation field will be set to
|
|
ename:VK_TRUE.
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
|
|
In all other cases, pname:requiresDedicatedAllocation must: be set to
|
|
ename:VK_FALSE by the implementation whenever a
|
|
sname:VkMemoryDedicatedRequirements structure is included in the pname:pNext
|
|
chain of the sname:VkMemoryRequirements2 structure passed to a call to
|
|
fname:vkGetImageMemoryRequirements2.
|
|
|
|
If the sname:VkMemoryDedicatedRequirements structure is included in the
|
|
pname:pNext chain of the sname:VkMemoryRequirements2 structure passed as the
|
|
pname:pMemoryRequirements parameter of a fname:vkGetImageMemoryRequirements2
|
|
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/VkMemoryDedicatedRequirements.txt[]
|
|
|
|
--
|
|
|
|
endif::VK_VERSION_1_1,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_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
|
|
fname:vkBindBufferMemory is equivalent to passing the same parameters
|
|
through slink:VkBindBufferMemoryInfo to flink:vkBindBufferMemory2.
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[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_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
* [[VUID-vkBindBufferMemory-buffer-01444]]
|
|
If pname:buffer requires a dedicated allocation(as reported by
|
|
flink:vkGetBufferMemoryRequirements2 in
|
|
slink:VkMemoryDedicatedRequirements::requiresDedicatedAllocation for
|
|
pname:buffer), pname:memory must: have been created with
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:buffer equal to pname:buffer
|
|
* [[VUID-vkBindBufferMemory-memory-01508]]
|
|
If the sname:VkMemoryAllocateInfo provided when pname:memory was
|
|
allocated included an instance of slink:VkMemoryDedicatedAllocateInfo in
|
|
its pname:pNext chain, and
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:buffer was not
|
|
ename:VK_NULL_HANDLE, then pname:buffer must: equal
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:buffer, and
|
|
pname:memoryOffset must: be zero.
|
|
endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkBindBufferMemory-None-01898]]
|
|
If buffer was created with the ename:VK_BUFFER_CREATE_PROTECTED_BIT bit
|
|
set, the buffer must: be bound to a memory object allocated with a
|
|
memory type that reports ename:VK_MEMORY_PROPERTY_PROTECTED_BIT
|
|
* [[VUID-vkBindBufferMemory-None-01899]]
|
|
If buffer was created with the ename:VK_BUFFER_CREATE_PROTECTED_BIT bit
|
|
not set, the buffer must: not be bound to a memory object created with a
|
|
memory type that reports ename:VK_MEMORY_PROPERTY_PROTECTED_BIT
|
|
endif::VK_VERSION_1_1[]
|
|
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_VERSION_1_1,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_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
endif::VK_NV_dedicated_allocation[]
|
|
****
|
|
|
|
include::../validity/protos/vkBindBufferMemory.txt[]
|
|
--
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
|
|
[open,refpage='vkBindBufferMemory2',desc='Bind device memory to buffer objects',type='protos']
|
|
--
|
|
|
|
To attach memory to buffer objects for one or more buffers at a time, call:
|
|
|
|
ifdef::VK_VERSION_1_1[]
|
|
include::../api/protos/vkBindBufferMemory2.txt[]
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
ifdef::VK_VERSION_1_1+VK_KHR_bind_memory2[or the equivalent command]
|
|
|
|
ifdef::VK_KHR_bind_memory2[]
|
|
include::../api/protos/vkBindBufferMemory2KHR.txt[]
|
|
endif::VK_KHR_bind_memory2[]
|
|
|
|
* pname:device is the logical device that owns the buffers and memory.
|
|
* pname:bindInfoCount is the number of elements in pname:pBindInfos.
|
|
* pname:pBindInfos is a pointer to an array of structures of type
|
|
slink:VkBindBufferMemoryInfo, 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/vkBindBufferMemory2.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBindBufferMemoryInfo',desc='Structure specifying how to bind a buffer to memory',type='structs']
|
|
--
|
|
|
|
sname:VkBindBufferMemoryInfo contains members corresponding to the
|
|
parameters of flink:vkBindBufferMemory.
|
|
|
|
The sname:VkBindBufferMemoryInfo structure is defined as:
|
|
|
|
include::../api/structs/VkBindBufferMemoryInfo.txt[]
|
|
|
|
ifdef::VK_KHR_bind_memory2[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkBindBufferMemoryInfoKHR.txt[]
|
|
endif::VK_KHR_bind_memory2[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to 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.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBindBufferMemoryInfo-buffer-01593]]
|
|
pname:buffer must: not already be backed by a memory object
|
|
* [[VUID-VkBindBufferMemoryInfo-buffer-01594]]
|
|
pname:buffer must: not have been created with any sparse memory binding
|
|
flags
|
|
* [[VUID-VkBindBufferMemoryInfo-memoryOffset-01595]]
|
|
pname:memoryOffset must: be less than the size of pname:memory
|
|
* [[VUID-VkBindBufferMemoryInfo-buffer-01596]]
|
|
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-VkBindBufferMemoryInfo-buffer-01597]]
|
|
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-VkBindBufferMemoryInfo-buffer-01598]]
|
|
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-VkBindBufferMemoryInfo-memory-01599]]
|
|
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-VkBindBufferMemoryInfo-memoryOffset-01600]]
|
|
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-VkBindBufferMemoryInfo-size-01601]]
|
|
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_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
* [[VUID-VkBindBufferMemoryInfo-buffer-01602]]
|
|
If pname:buffer requires a dedicated allocation(as reported by
|
|
flink:vkGetBufferMemoryRequirements2 in
|
|
slink:VkMemoryDedicatedRequirements::requiresDedicatedAllocation for
|
|
pname:buffer), pname:memory must: have been created with
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:buffer equal to pname:buffer
|
|
and pname:memoryOffset must: be zero
|
|
* [[VUID-VkBindBufferMemoryInfo-memory-01900]]
|
|
If the sname:VkMemoryAllocateInfo provided when pname:memory was
|
|
allocated included an instance of slink:VkMemoryDedicatedAllocateInfo in
|
|
its pname:pNext chain, and
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:buffer was not
|
|
ename:VK_NULL_HANDLE, then pname:buffer must: equal
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:buffer and pname:memoryOffset
|
|
must: be zero.
|
|
endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
ifdef::VK_NV_dedicated_allocation[]
|
|
* [[VUID-VkBindBufferMemoryInfo-buffer-01603]]
|
|
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
|
|
pname:buffer and pname:memoryOffset must: be zero
|
|
ifndef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
* [[VUID-VkBindBufferMemoryInfo-buffer-01604]]
|
|
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_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
endif::VK_NV_dedicated_allocation[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
* [[VUID-VkBindBufferMemoryInfo-pNext-01605]]
|
|
If the pname:pNext chain includes
|
|
slink:VkBindBufferMemoryDeviceGroupInfo, all instances of pname:memory
|
|
specified by
|
|
slink:VkBindBufferMemoryDeviceGroupInfo::pname:pDeviceIndices must: have
|
|
been allocated
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
****
|
|
|
|
include::../validity/structs/VkBindBufferMemoryInfo.txt[]
|
|
|
|
--
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
|
|
[open,refpage='VkBindBufferMemoryDeviceGroupInfo',desc='Structure specifying device within a group to bind to',type='structs']
|
|
--
|
|
|
|
include::../api/structs/VkBindBufferMemoryDeviceGroupInfo.txt[]
|
|
|
|
// @Jon: this conditional needs to be enhanced for 1.1 / bind_memory_2
|
|
ifdef::VK_KHR_device_group+VK_KHR_bind_memory2[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkBindBufferMemoryDeviceGroupInfoKHR.txt[]
|
|
endif::VK_KHR_device_group+VK_KHR_bind_memory2[]
|
|
|
|
If the pname:pNext list of slink:VkBindBufferMemoryInfo includes a
|
|
sname:VkBindBufferMemoryDeviceGroupInfo structure, then that structure
|
|
determines how memory is bound to buffers across multiple devices in a
|
|
device group.
|
|
|
|
The sname:VkBindBufferMemoryDeviceGroupInfo structure is defined as:
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* 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 pname:memory on the physical
|
|
device with device index [eq]#pDeviceIndices[i]#.
|
|
|
|
If pname:deviceIndexCount is zero and pname:memory comes from a memory heap
|
|
with the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if
|
|
pname:pDeviceIndices contains consecutive indices from zero to the number of
|
|
physical devices in the logical device, minus one.
|
|
In other words, by default each physical device attaches to its own instance
|
|
of pname:memory.
|
|
|
|
If pname:deviceIndexCount is zero and pname:memory comes from a memory heap
|
|
without the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as
|
|
if pname:pDeviceIndices contains an array of zeros.
|
|
In other words, by default each physical device attaches to instance zero.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBindBufferMemoryDeviceGroupInfo-deviceIndexCount-01606]]
|
|
pname:deviceIndexCount must: either be zero or equal to the number of
|
|
physical devices in the logical device
|
|
* [[VUID-VkBindBufferMemoryDeviceGroupInfo-pDeviceIndices-01607]]
|
|
All elements of pname:pDeviceIndices must: be valid device indices
|
|
****
|
|
|
|
include::../validity/structs/VkBindBufferMemoryDeviceGroupInfo.txt[]
|
|
--
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
endif::VK_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
|
|
[open,refpage='vkBindImageMemory',desc='Bind device memory to an image object',type='protos']
|
|
--
|
|
|
|
|
|
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
To attach memory to an image object, call:
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
To attach memory to a sname:VkImage object created without the
|
|
ename:VK_IMAGE_CREATE_DISJOINT_BIT set, call:
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
include::../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_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
|
|
fname:vkBindImageMemory is equivalent to passing the same parameters through
|
|
slink:VkBindImageMemoryInfo to flink:vkBindImageMemory2.
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
|
|
.Valid Usage
|
|
****
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkBindImageMemory-image-01608]]
|
|
pname:image must: not have been created with the
|
|
ename:VK_IMAGE_CREATE_DISJOINT_BIT set.
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-vkBindImageMemory-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_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
* [[VUID-vkBindImageMemory-image-01445]]
|
|
If pname:image requires a dedicated allocation (as reported by
|
|
flink:vkGetImageMemoryRequirements2 in
|
|
slink:VkMemoryDedicatedRequirements::requiresDedicatedAllocation for
|
|
pname:image), pname:memory must: have been created with
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:image equal to pname:image
|
|
* [[VUID-vkBindImageMemory-memory-01509]]
|
|
If the sname:VkMemoryAllocateInfo provided when pname:memory was
|
|
allocated included an instance of slink:VkMemoryDedicatedAllocateInfo in
|
|
its pname:pNext chain, and
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:image was not
|
|
ename:VK_NULL_HANDLE, then pname:image must: equal
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:image and pname:memoryOffset
|
|
must: be zero.
|
|
endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
ifdef::VK_VERSION_1_1[]
|
|
* [[VUID-vkBindImageMemory-None-01901]]
|
|
If image was created with the ename:VK_IMAGE_CREATE_PROTECTED_BIT bit
|
|
set, the image must: be bound to a memory object allocated with a memory
|
|
type that reports ename:VK_MEMORY_PROPERTY_PROTECTED_BIT
|
|
* [[VUID-vkBindImageMemory-None-01902]]
|
|
If image was created with the ename:VK_IMAGE_CREATE_PROTECTED_BIT bit
|
|
not set, the image must: not be bound to a memory object created with a
|
|
memory type that reports ename:VK_MEMORY_PROPERTY_PROTECTED_BIT
|
|
endif::VK_VERSION_1_1[]
|
|
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_VERSION_1_1,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_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
endif::VK_NV_dedicated_allocation[]
|
|
****
|
|
|
|
include::../validity/protos/vkBindImageMemory.txt[]
|
|
--
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
[open,refpage='vkBindImageMemory2',desc='Bind device memory to image objects',type='protos']
|
|
--
|
|
|
|
To attach memory to image objects for one or more images at a time, call:
|
|
|
|
ifdef::VK_VERSION_1_1[]
|
|
include::../api/protos/vkBindImageMemory2.txt[]
|
|
endif::VK_VERSION_1_1[]
|
|
|
|
ifdef::VK_VERSION_1_1+VK_KHR_bind_memory2[or the equivalent command]
|
|
|
|
ifdef::VK_KHR_bind_memory2[]
|
|
include::../api/protos/vkBindImageMemory2KHR.txt[]
|
|
endif::VK_KHR_bind_memory2[]
|
|
|
|
* pname:device is the logical device that owns the images and memory.
|
|
* pname:bindInfoCount is the number of elements in pname:pBindInfos.
|
|
* pname:pBindInfos is a pointer to an array of structures of type
|
|
slink:VkBindImageMemoryInfo, 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/vkBindImageMemory2.txt[]
|
|
--
|
|
|
|
[open,refpage='VkBindImageMemoryInfo',desc='Structure specifying how to bind an image to memory',type='structs']
|
|
--
|
|
|
|
sname:VkBindImageMemoryInfo contains members corresponding to the parameters
|
|
of flink:vkBindImageMemory.
|
|
|
|
The sname:VkBindImageMemoryInfo structure is defined as:
|
|
|
|
include::../api/structs/VkBindImageMemoryInfo.txt[]
|
|
|
|
ifdef::VK_KHR_bind_memory2[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkBindImageMemoryInfoKHR.txt[]
|
|
endif::VK_KHR_bind_memory2[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to 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.
|
|
The number of bytes returned in the
|
|
sname:VkMemoryRequirements::pname:size member in pname:memory, starting
|
|
from pname:memoryOffset bytes, will be bound to the specified image.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBindImageMemoryInfo-image-01609]]
|
|
pname:image must: not already be backed by a memory object
|
|
* [[VUID-VkBindImageMemoryInfo-image-01610]]
|
|
pname:image must: not have been created with any sparse memory binding
|
|
flags
|
|
* [[VUID-VkBindImageMemoryInfo-memoryOffset-01611]]
|
|
pname:memoryOffset must: be less than the size of pname:memory
|
|
ifndef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBindImageMemoryInfo-memory-01612]]
|
|
pname:memory must: have been allocated using one of the memory types
|
|
allowed in the pname:memoryTypeBits member of the
|
|
slink:VkMemoryRequirements structure returned from a call to
|
|
flink:vkGetImageMemoryRequirements with pname:image
|
|
* [[VUID-VkBindImageMemoryInfo-memoryOffset-01613]]
|
|
pname:memoryOffset must: be an integer multiple of the pname:alignment
|
|
member of the slink:VkMemoryRequirements structure returned from a call
|
|
to flink:vkGetImageMemoryRequirements with pname:image
|
|
* [[VUID-VkBindImageMemoryInfo-memory-01614]]
|
|
The difference of the size of pname:memory and pname:memoryOffset must:
|
|
be greater than or equal to the pname:size member of the
|
|
slink:VkMemoryRequirements structure returned from a call to
|
|
flink:vkGetImageMemoryRequirements with the same pname:image
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01615]]
|
|
If the pname:pNext chain does not include an instance of the
|
|
slink:VkBindImagePlaneMemoryInfo structure, pname:memory must: have been
|
|
allocated using one of the memory types allowed in the
|
|
pname:memoryTypeBits member of the slink:VkMemoryRequirements structure
|
|
returned from a call to flink:vkGetImageMemoryRequirements2 with
|
|
pname:image
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01616]]
|
|
If the pname:pNext chain does not include an instance of the
|
|
slink:VkBindImagePlaneMemoryInfo structure, pname:memoryOffset must: be
|
|
an integer multiple of the pname:alignment member of the
|
|
slink:VkMemoryRequirements structure returned from a call to
|
|
flink:vkGetImageMemoryRequirements2 with pname:image
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01617]]
|
|
If the pname:pNext chain does not include an instance of the
|
|
slink:VkBindImagePlaneMemoryInfo structure, the difference of the size
|
|
of pname:memory and pname:memoryOffset must: be greater than or equal to
|
|
the pname:size member of the slink:VkMemoryRequirements structure
|
|
returned from a call to flink:vkGetImageMemoryRequirements2 with the
|
|
same pname:image
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01618]]
|
|
If the pname:pNext chain includes an instance of the
|
|
slink:VkBindImagePlaneMemoryInfo structure, pname:image must: have been
|
|
created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT bit set.
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01619]]
|
|
If the pname:pNext chain includes an instance of the
|
|
slink:VkBindImagePlaneMemoryInfo structure, pname:memory must: have been
|
|
allocated using one of the memory types allowed in the
|
|
pname:memoryTypeBits member of the slink:VkMemoryRequirements structure
|
|
returned from a call to flink:vkGetImageMemoryRequirements2 with
|
|
pname:image and the correct pname:planeAspect for this plane in the
|
|
slink:VkImagePlaneMemoryRequirementsInfo structure attached to the
|
|
slink:VkImageMemoryRequirementsInfo2's pname:pNext chain
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01620]]
|
|
If the pname:pNext chain includes an instance of the
|
|
slink:VkBindImagePlaneMemoryInfo structure, pname:memoryOffset must: be
|
|
an integer multiple of the pname:alignment member of the
|
|
slink:VkMemoryRequirements structure returned from a call to
|
|
flink:vkGetImageMemoryRequirements2 with pname:image and the correct
|
|
pname:planeAspect for this plane in the
|
|
slink:VkImagePlaneMemoryRequirementsInfo structure attached to the
|
|
slink:VkImageMemoryRequirementsInfo2's pname:pNext chain
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01621]]
|
|
If the pname:pNext chain includes an instance of the
|
|
slink:VkBindImagePlaneMemoryInfo structure, the difference of the size
|
|
of pname:memory and pname:memoryOffset must: be greater than or equal to
|
|
the pname:size member of the slink:VkMemoryRequirements structure
|
|
returned from a call to flink:vkGetImageMemoryRequirements2 with the
|
|
same pname:image and the correct pname:planeAspect for this plane in the
|
|
slink:VkImagePlaneMemoryRequirementsInfo structure attached to the
|
|
slink:VkImageMemoryRequirementsInfo2's pname:pNext chain
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
* [[VUID-VkBindImageMemoryInfo-image-01622]]
|
|
If pname:image requires a dedicated allocation (as reported by
|
|
flink:vkGetImageMemoryRequirements2 in
|
|
slink:VkMemoryDedicatedRequirements::requiresDedicatedAllocation for
|
|
pname:image), pname:memory must: have been created with
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:image equal to pname:image
|
|
and pname:memoryOffset must: be zero
|
|
* [[VUID-VkBindImageMemoryInfo-memory-01903]]
|
|
If the sname:VkMemoryAllocateInfo provided when pname:memory was
|
|
allocated included an instance of slink:VkMemoryDedicatedAllocateInfo in
|
|
its pname:pNext chain, and
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:image was not
|
|
ename:VK_NULL_HANDLE, then pname:image must: equal
|
|
slink:VkMemoryDedicatedAllocateInfo::pname:image and pname:memoryOffset
|
|
must: be zero.
|
|
endif::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
ifdef::VK_NV_dedicated_allocation[]
|
|
* [[VUID-VkBindImageMemoryInfo-image-01623]]
|
|
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
|
|
pname:image and pname:memoryOffset must: be zero
|
|
ifndef::VK_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
* [[VUID-VkBindImageMemoryInfo-image-01624]]
|
|
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_VERSION_1_1,VK_KHR_dedicated_allocation[]
|
|
endif::VK_NV_dedicated_allocation[]
|
|
ifndef::VK_VERSION_1_1+VK_KHR_swapchain[]
|
|
ifndef::VK_KHR_device_group+VK_KHR_swapchain[]
|
|
* [[VUID-VkBindImageMemoryInfo-memory-01625]]
|
|
pname:memory must: be a valid dname:VkDeviceMemory handle
|
|
endif::VK_KHR_device_group+VK_KHR_swapchain[]
|
|
endif::VK_VERSION_1_1+VK_KHR_swapchain[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01626]]
|
|
If the pname:pNext chain includes
|
|
slink:VkBindImageMemoryDeviceGroupInfo, all instances of pname:memory
|
|
specified by
|
|
slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices must: have
|
|
been allocated
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01627]]
|
|
If the pname:pNext chain includes
|
|
slink:VkBindImageMemoryDeviceGroupInfo, and
|
|
slink:VkBindImageMemoryDeviceGroupInfo::pname:splitInstanceBindRegionCount
|
|
is not zero, then pname:image must: have been created with the
|
|
ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT bit set
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01628]]
|
|
If the pname:pNext chain includes
|
|
slink:VkBindImageMemoryDeviceGroupInfo, all elements of
|
|
slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions
|
|
must: be valid rectangles contained within the dimensions of pname:image
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01629]]
|
|
If the pname:pNext chain includes
|
|
slink:VkBindImageMemoryDeviceGroupInfo, the union of the areas of all
|
|
elements of
|
|
slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions
|
|
that correspond to the same instance of pname:image must: cover the
|
|
entire image.
|
|
ifdef::VK_KHR_swapchain[]
|
|
* [[VUID-VkBindImageMemoryInfo-image-01630]]
|
|
If pname:image was created with a valid swapchain handle in
|
|
slink:VkImageSwapchainCreateInfoKHR::pname:swapchain, then the
|
|
pname:pNext chain must: include a valid instance of
|
|
slink:VkBindImageMemorySwapchainInfoKHR
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01631]]
|
|
If the pname:pNext chain includes an instance of
|
|
slink:VkBindImageMemorySwapchainInfoKHR, pname:memory must: be
|
|
dlink:VK_NULL_HANDLE
|
|
* [[VUID-VkBindImageMemoryInfo-pNext-01632]]
|
|
If the pname:pNext chain does not include an instance of
|
|
slink:VkBindImageMemorySwapchainInfoKHR, pname:memory must: be a valid
|
|
dname:VkDeviceMemory handle
|
|
endif::VK_KHR_swapchain[]
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
****
|
|
|
|
include::../validity/structs/VkBindImageMemoryInfo.txt[]
|
|
|
|
--
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
|
|
[open,refpage='VkBindImageMemoryDeviceGroupInfo',desc='Structure specifying device within a group to bind to',type='structs']
|
|
--
|
|
|
|
include::../api/structs/VkBindImageMemoryDeviceGroupInfo.txt[]
|
|
|
|
// @Jon: this conditional needs to be enhanced for 1.1 / bind_memory_2
|
|
ifdef::VK_KHR_device_group+VK_KHR_bind_memory2[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkBindImageMemoryDeviceGroupInfoKHR.txt[]
|
|
endif::VK_KHR_device_group+VK_KHR_bind_memory2[]
|
|
|
|
If the pname:pNext list of slink:VkBindImageMemoryInfo includes a
|
|
sname:VkBindImageMemoryDeviceGroupInfo structure, then that structure
|
|
determines how memory is bound to images across multiple devices in a device
|
|
group.
|
|
|
|
The sname:VkBindImageMemoryDeviceGroupInfo structure is defined as:
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:deviceIndexCount is the number of elements in
|
|
pname:pDeviceIndices.
|
|
* pname:pDeviceIndices is a pointer to an array of device indices.
|
|
* pname:splitInstanceBindRegionCount is the number of elements in
|
|
pname:pSplitInstanceBindRegions.
|
|
* pname:pSplitInstanceBindRegions is a pointer to an array of 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#
|
|
pname:image is attached to the instance of the memory on the physical device
|
|
with device index [eq]#pDeviceIndices[i]#.
|
|
|
|
Let [eq]#N# be the number of physical devices in the logical device.
|
|
If pname:splitInstanceBindRegionCount is greater than zero, then
|
|
pname:pSplitInstanceBindRegions is an array of [eq]#N^2^# rectangles, where
|
|
the image region specified by the rectangle at element [eq]#i*N+j# in
|
|
resource instance [eq]#i# is bound to the memory instance [eq]#j#.
|
|
The blocks of the memory that are bound to each sparse image block region
|
|
use an offset in memory, relative to pname:memoryOffset, computed as if the
|
|
whole image 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 pname:image, and the
|
|
block at [eq]#(0,0)# corresponds to memory starting at pname:memoryOffset.
|
|
|
|
If pname:splitInstanceBindRegionCount and pname:deviceIndexCount are zero
|
|
and the memory comes from a memory heap with the
|
|
ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if
|
|
pname:pDeviceIndices contains consecutive indices from zero to the number of
|
|
physical devices in the logical device, minus one.
|
|
In other words, by default each physical device attaches to its own instance
|
|
of the memory.
|
|
|
|
If pname:splitInstanceBindRegionCount and pname:deviceIndexCount are zero
|
|
and the memory comes from a memory heap without the
|
|
ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT bit set, then it is as if
|
|
pname:pDeviceIndices contains an array of zeros.
|
|
In other words, by default each physical device attaches to instance zero.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBindImageMemoryDeviceGroupInfo-deviceIndexCount-01633]]
|
|
At least one of pname:deviceIndexCount and
|
|
pname:splitInstanceBindRegionCount must: be zero.
|
|
* [[VUID-VkBindImageMemoryDeviceGroupInfo-deviceIndexCount-01634]]
|
|
pname:deviceIndexCount must: either be zero or equal to the number of
|
|
physical devices in the logical device
|
|
* [[VUID-VkBindImageMemoryDeviceGroupInfo-pDeviceIndices-01635]]
|
|
All elements of pname:pDeviceIndices must: be valid device indices.
|
|
* [[VUID-VkBindImageMemoryDeviceGroupInfo-splitInstanceBindRegionCount-01636]]
|
|
pname:splitInstanceBindRegionCount must: either be zero or equal to the
|
|
number of physical devices in the logical device squared
|
|
* [[VUID-VkBindImageMemoryDeviceGroupInfo-pSplitInstanceBindRegions-01637]]
|
|
Elements of pname:pSplitInstanceBindRegions that correspond to the same
|
|
instance of an image must: not overlap.
|
|
* [[VUID-VkBindImageMemoryDeviceGroupInfo-offset-01638]]
|
|
The pname:offset.x member of any element of
|
|
pname:pSplitInstanceBindRegions must: be a multiple of the sparse image
|
|
block width
|
|
(sname:VkSparseImageFormatProperties::pname:imageGranularity.width) of
|
|
all non-metadata aspects of the image
|
|
* [[VUID-VkBindImageMemoryDeviceGroupInfo-offset-01639]]
|
|
The pname:offset.y member of any element of
|
|
pname:pSplitInstanceBindRegions must: be a multiple of the sparse image
|
|
block height
|
|
(sname:VkSparseImageFormatProperties::pname:imageGranularity.height) of
|
|
all non-metadata aspects of the image
|
|
* [[VUID-VkBindImageMemoryDeviceGroupInfo-extent-01640]]
|
|
The pname:extent.width member of any element of
|
|
pname:pSplitInstanceBindRegions must: either be a multiple of the sparse
|
|
image block width of all non-metadata aspects of the image, or else
|
|
pname:extent.width + pname:offset.x must: equal the width of the image
|
|
subresource
|
|
* [[VUID-VkBindImageMemoryDeviceGroupInfo-extent-01641]]
|
|
The pname:extent.height member of any element of
|
|
pname:pSplitInstanceBindRegions must: either be a multiple of the sparse
|
|
image block height of all non-metadata aspects of the image, or else
|
|
pname:extent.height +
|
|
pname:offset.y must: equal the width of the image subresource
|
|
****
|
|
|
|
include::../validity/structs/VkBindImageMemoryDeviceGroupInfo.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHR_swapchain[]
|
|
[open,refpage='VkBindImageMemorySwapchainInfoKHR',desc='Structure specifying swapchain image memory to bind to',type='structs']
|
|
--
|
|
|
|
If the pname:pNext chain of slink:VkBindImageMemoryInfo includes a
|
|
sname:VkBindImageMemorySwapchainInfoKHR structure, then that structure
|
|
includes a swapchain handle and image index indicating that the image will
|
|
be bound to memory from that swapchain.
|
|
|
|
The sname:VkBindImageMemorySwapchainInfoKHR structure is defined as:
|
|
|
|
include::../api/structs/VkBindImageMemorySwapchainInfoKHR.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:pSplitInstanceBindRegions members of
|
|
slink:VkBindImageMemoryDeviceGroupInfo.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBindImageMemorySwapchainInfoKHR-imageIndex-01644]]
|
|
pname:imageIndex must: be less than the number of images in
|
|
pname:swapchain
|
|
****
|
|
|
|
include::../validity/structs/VkBindImageMemorySwapchainInfoKHR.txt[]
|
|
--
|
|
|
|
endif::VK_KHR_swapchain[]
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
[open,refpage='VkBindImagePlaneMemoryInfo',desc='Structure specifying how to bind an image plane to memory',type='structs']
|
|
--
|
|
|
|
In order to bind _planes_ of a _disjoint image_, include a
|
|
sname:VkBindImagePlaneMemoryInfo structure in the pname:pNext chain of
|
|
slink:VkBindImageMemoryInfo.
|
|
|
|
The sname:VkBindImagePlaneMemoryInfo structure is defined as:
|
|
|
|
include::../api/structs/VkBindImagePlaneMemoryInfo.txt[]
|
|
|
|
ifdef::VK_KHR_sampler_ycbcr_conversion[]
|
|
or the equivalent
|
|
|
|
include::../api/structs/VkBindImagePlaneMemoryInfoKHR.txt[]
|
|
endif::VK_KHR_sampler_ycbcr_conversion[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:planeAspect is the aspect of the disjoint image plane to bind.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBindImagePlaneMemoryInfo-planeAspect-01642]]
|
|
pname:planeAspect must: be a single valid plane aspect for the image
|
|
format (that is, pname:planeAspect must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT or ename:VK_IMAGE_ASPECT_PLANE_1_BIT
|
|
for "`etext:_2PLANE`" formats and pname:planeAspect must: be
|
|
ename:VK_IMAGE_ASPECT_PLANE_0_BIT, ename:VK_IMAGE_ASPECT_PLANE_1_BIT, or
|
|
ename:VK_IMAGE_ASPECT_PLANE_2_BIT for "`etext:_3PLANE`" formats)
|
|
* [[VUID-VkBindImagePlaneMemoryInfo-None-01643]]
|
|
A single call to flink:vkBindImageMemory2 must: bind all or none of the
|
|
planes of an image (i.e. bindings to all planes of an image must: be
|
|
made in a single flink:vkBindImageMemory2 call), as separate bindings
|
|
****
|
|
|
|
include::../validity/structs/VkBindImagePlaneMemoryInfo.txt[]
|
|
--
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
endif::VK_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
|
|
|
|
[[resources-bufferimagegranularity,Buffer-Image Granularity]]
|
|
.Buffer-Image Granularity
|
|
There is an implementation-dependent limit, pname:bufferImageGranularity,
|
|
which specifies a page-like granularity at which linear and non-linear
|
|
resources must: be placed in adjacent memory locations to avoid aliasing.
|
|
Two resources which do not satisfy this granularity requirement are said to
|
|
<<resources-memory-aliasing,alias>>.
|
|
pname:bufferImageGranularity is specified in bytes, and must: be a power of
|
|
two.
|
|
Implementations which do not impose a granularity restriction may: report a
|
|
pname:bufferImageGranularity value of one.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Despite its name, pname:bufferImageGranularity is really a granularity
|
|
between "`linear`" and "`non-linear`" resources.
|
|
====
|
|
|
|
Given resourceA at the lower memory offset and resourceB at the higher
|
|
memory offset in the same sname:VkDeviceMemory object, where one resource is
|
|
linear and the other is non-linear (as defined in the
|
|
<<glossary-linear-resource,Glossary>>), and the following:
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
resourceA.end = resourceA.memoryOffset + resourceA.size - 1
|
|
resourceA.endPage = resourceA.end & ~(bufferImageGranularity-1)
|
|
resourceB.start = resourceB.memoryOffset
|
|
resourceB.startPage = resourceB.start & ~(bufferImageGranularity-1)
|
|
---------------------------------------------------
|
|
|
|
The following property must: hold:
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
resourceA.endPage < resourceB.startPage
|
|
---------------------------------------------------
|
|
|
|
That is, the end of the first resource (A) and the beginning of the second
|
|
resource (B) must: be on separate "`pages`" of size
|
|
pname:bufferImageGranularity.
|
|
pname:bufferImageGranularity may: be different than the physical page size
|
|
of the memory heap.
|
|
This restriction is only needed when a linear resource and a non-linear
|
|
resource are adjacent in memory and will be used simultaneously.
|
|
The memory ranges of adjacent resources can: be closer than
|
|
pname:bufferImageGranularity, provided they meet the pname:alignment
|
|
requirement for the objects in question.
|
|
|
|
Sparse block size in bytes and sparse image and buffer memory alignments
|
|
must: all be multiples of the pname:bufferImageGranularity.
|
|
Therefore, memory bound to sparse resources naturally satisfies the
|
|
pname:bufferImageGranularity.
|
|
|
|
[[resources-sharing]]
|
|
== Resource Sharing Mode
|
|
|
|
[open,refpage='VkSharingMode',desc='Buffer and image sharing modes',type='enums']
|
|
--
|
|
|
|
Buffer and image objects are created with a _sharing mode_ controlling how
|
|
they can: be accessed from queues.
|
|
The supported sharing modes are:
|
|
|
|
include::../api/enums/VkSharingMode.txt[]
|
|
|
|
* ename:VK_SHARING_MODE_EXCLUSIVE specifies that access to any range or
|
|
image subresource of the object will be exclusive to a single queue
|
|
family at a time.
|
|
* ename:VK_SHARING_MODE_CONCURRENT specifies that concurrent access to any
|
|
range or image subresource of the object from multiple queue families is
|
|
supported.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
ename:VK_SHARING_MODE_CONCURRENT may: result in lower performance access to
|
|
the buffer or image than ename:VK_SHARING_MODE_EXCLUSIVE.
|
|
====
|
|
|
|
Ranges of buffers and image subresources of image objects created using
|
|
ename:VK_SHARING_MODE_EXCLUSIVE must: only be accessed by queues in the
|
|
queue family that has _ownership_ of the resource.
|
|
Upon creation, such resources are not owned by any queue family; ownership
|
|
is implicitly acquired upon first use within a queue.
|
|
Once a resource using ename:VK_SHARING_MODE_EXCLUSIVE is owned by some queue
|
|
family, the application must: perform a
|
|
<<synchronization-queue-transfers,queue family ownership transfer>> to make
|
|
the memory contents of a range or image subresource accessible to a
|
|
different queue family.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Images still require a <<resources-image-layouts, layout transition>> from
|
|
ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED
|
|
before being used on the first queue.
|
|
====
|
|
|
|
A queue family can: take ownership of an image subresource or buffer range
|
|
of a resource created with ename:VK_SHARING_MODE_EXCLUSIVE, without an
|
|
ownership transfer, in the same way as for a resource that was just created;
|
|
however, taking ownership in this way has the effect that the contents of
|
|
the image subresource or buffer range are undefined.
|
|
|
|
Ranges of buffers and image subresources of image objects created using
|
|
ename:VK_SHARING_MODE_CONCURRENT must: only be accessed by queues from the
|
|
queue families specified through the pname:queueFamilyIndexCount and
|
|
pname:pQueueFamilyIndices members of the corresponding create info
|
|
structures.
|
|
|
|
--
|
|
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
|
|
[[resources-external-sharing]]
|
|
=== External Resource Sharing
|
|
|
|
Resources should: only be accessed in the Vulkan instance that has exclusive
|
|
ownership of their underlying memory.
|
|
Only one Vulkan instance has exclusive ownership of a resource's underlying
|
|
memory at a given time, regardless of whether the resource was created using
|
|
ename:VK_SHARING_MODE_EXCLUSIVE or ename:VK_SHARING_MODE_CONCURRENT.
|
|
Applications can transfer ownership of a resource's underlying memory only
|
|
if the memory has been imported from or exported to another instance or
|
|
external API using external memory handles.
|
|
The semantics for transferring ownership outside of the instance are similar
|
|
to those used for transferring ownership of ename:VK_SHARING_MODE_EXCLUSIVE
|
|
resources between queues, and is also accomplished using
|
|
slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier operations.
|
|
Applications must:
|
|
|
|
. Release exclusive ownership from the source instance or API.
|
|
. Ensure the release operation has completed using semaphores or fences.
|
|
. Acquire exclusive ownership in the destination instance or API
|
|
|
|
Unlike queue ownership transfers, the destination instance or API is not
|
|
specified explicitly when releasing ownership, nor is the source instance or
|
|
API specified when acquiring ownership.
|
|
Instead, the image or memory barrier's pname:dstQueueFamilyIndex or
|
|
pname:srcQueueFamilyIndex parameters are set to the reserved queue family
|
|
index ename:VK_QUEUE_FAMILY_EXTERNAL
|
|
ifdef::VK_EXT_queue_family_foreign[]
|
|
or ename:VK_QUEUE_FAMILY_FOREIGN_EXT
|
|
endif::VK_EXT_queue_family_foreign[]
|
|
to represent the external destination or source respectively.
|
|
|
|
Binding a resource to a memory object shared between multiple Vulkan
|
|
instances or other APIs does not change the ownership of the underlying
|
|
memory.
|
|
The first entity to access the resource implicitly acquires ownership.
|
|
Accessing a resource backed by memory that is owned by a particular instance
|
|
or API has the same semantics as accessing a ename:VK_SHARING_MODE_EXCLUSIVE
|
|
resource, with one exception: Implementations must: ensure layout
|
|
transitions performed on one member of a set of identical subresources of
|
|
identical images that alias the same range of an underlying memory object
|
|
affect the layout of all the subresources in the set.
|
|
|
|
As a corollary, writes to any image subresources in such a set must: not
|
|
make the contents of memory used by other subresources in the set undefined.
|
|
An application can: define the content of a subresource of one image by
|
|
performing device writes to an identical subresource of another image
|
|
provided both images are bound to the same region of external memory.
|
|
Applications may: also add resources to such a set after the content of the
|
|
existing set members has been defined without making the content undefined
|
|
by creating a new image with the initial layout
|
|
ename:VK_IMAGE_LAYOUT_UNDEFINED and binding it to the same region of
|
|
external memory as the existing images.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Because layout transitions apply to all identical images aliasing the same
|
|
region of external memory, the actual layout of the memory backing a new
|
|
image as well as an existing image with defined content will not be
|
|
undefined.
|
|
Such an image is not usable until it acquires ownership of its memory from
|
|
the existing owner.
|
|
Therefore, the layout specified as part of this transition will be the true
|
|
initial layout of the image.
|
|
The undefined layout specified when creating it is a placeholder to simplify
|
|
valid usage requirements.
|
|
====
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
|
|
|
|
[[resources-memory-aliasing]]
|
|
== Memory Aliasing
|
|
|
|
A range of a sname:VkDeviceMemory allocation is _aliased_ if it is bound to
|
|
multiple resources simultaneously, as described below, via
|
|
flink:vkBindImageMemory, flink:vkBindBufferMemory,
|
|
ifndef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
or via <<sparsememory-resource-binding,sparse memory bindings>>.
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
via <<sparsememory-resource-binding,sparse memory bindings>>, or by binding
|
|
the memory to resources in multiple Vulkan instances or external APIs using
|
|
external memory handle export and import mechanisms.
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
|
|
Consider two resources, resource~A~ and resource~B~, bound respectively to
|
|
memory range~A~ and range~B~.
|
|
Let paddedRange~A~ and paddedRange~B~ be, respectively, range~A~ and
|
|
range~B~ aligned to pname:bufferImageGranularity.
|
|
If the resources are both linear or both non-linear (as defined in the
|
|
<<glossary-linear-resource,Glossary>>), then the resources _alias_ the
|
|
memory in the intersection of range~A~ and range~B~.
|
|
If one resource is linear and the other is non-linear, then the resources
|
|
_alias_ the memory in the intersection of paddedRange~A~ and paddedRange~B~.
|
|
|
|
Applications can: alias memory, but use of multiple aliases is subject to
|
|
several constraints.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Memory aliasing can: be useful to reduce the total device memory footprint
|
|
of an application, if some large resources are used for disjoint periods of
|
|
time.
|
|
====
|
|
|
|
When 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_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
[[resources-memory-aliasing-consistency]]
|
|
If two aliases are both images that were created with identical creation
|
|
parameters, both were created with the ename:VK_IMAGE_CREATE_ALIAS_BIT flag
|
|
set, and both are bound identically to memory
|
|
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
except for slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices and
|
|
slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions,
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
then they interpret the contents of the memory in consistent ways, and data
|
|
written to one alias can: be read by the other alias.
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
[[resources-memory-aliasing-consistency-planes]]
|
|
Additionally, if an invididual plane of a multi-planar image and a
|
|
single-plane image alias the same memory, then they also interpret the
|
|
contents of the memory in consistent ways under the same conditions, but
|
|
with the following modifications:
|
|
|
|
* Both must: have been created with the ename:VK_IMAGE_CREATE_DISJOINT_BIT
|
|
flag.
|
|
* The single-plane image must: have an elink:VkFormat that is
|
|
<<features-formats-compatible-planes,equivalent>> to that of the
|
|
multi-planar image's individual plane.
|
|
* The single-plane image and the individual plane of the multi-planar
|
|
image must: be bound identically to memory
|
|
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
except for slink:VkBindImageMemoryDeviceGroupInfo::pname:pDeviceIndices
|
|
and
|
|
slink:VkBindImageMemoryDeviceGroupInfo::pname:pSplitInstanceBindRegions.
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
* The pname:width and pname:height of the single-plane image are derived
|
|
from the multi-planar image's dimensions in the manner listed for
|
|
<<features-formats-compatible-planes,plane compatibility>> for the
|
|
aliased plane.
|
|
* All other creation parameters must: be identical
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_sampler_ycbcr_conversion[]
|
|
endif::VK_VERSION_1_1,VK_KHR_bind_memory2[]
|
|
|
|
ifdef::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
Aliases created by binding the same memory to resources in multiple Vulkan
|
|
instances or external APIs using external memory handle export and import
|
|
mechanisms interpret the contents of the memory in consistent ways, and data
|
|
written to one alias can: be read by the other alias.
|
|
endif::VK_VERSION_1_1,VK_KHR_external_memory[]
|
|
|
|
Otherwise, the aliases interpret the contents of the memory differently, and
|
|
writes via one alias make the contents of memory partially or completely
|
|
undefined to the other alias.
|
|
If the first alias is a host-accessible subresource, then the bytes affected
|
|
are those written by the memory operations according to its addressing
|
|
scheme.
|
|
If the first alias is not host-accessible, then the bytes affected are those
|
|
overlapped by the image subresources that were written.
|
|
If the second alias is a host-accessible subresource, the affected bytes
|
|
become undefined.
|
|
If the second alias is 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.
|
|
====
|