2614 lines
124 KiB
Plaintext
2614 lines
124 KiB
Plaintext
// Copyright (c) 2015-2017 The Khronos Group Inc.
|
|
// Copyright notice at https://www.khronos.org/registry/speccopyright.html
|
|
|
|
[[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
|
|
|
|
// refBegin VkBuffer Opaque handle to a buffer object
|
|
|
|
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[]
|
|
|
|
// refEnd VkBuffer
|
|
|
|
// refBegin vkCreateBuffer Create a new buffer object
|
|
|
|
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[]
|
|
|
|
// refBegin VkBufferCreateInfo Structure specifying the parameters of a newly created buffer object
|
|
|
|
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 describing additional parameters of the buffer.
|
|
See elink:VkBufferCreateFlagBits below for a description of the
|
|
supported bits.
|
|
* pname:size is the size in bytes of the buffer to be created.
|
|
* pname:usage is a bitmask describing the allowed usages of the buffer.
|
|
See elink:VkBufferUsageFlagBits below for a description of the supported
|
|
bits.
|
|
* pname:sharingMode is the sharing mode of the buffer when it will be
|
|
accessed by multiple queue families, see elink:VkSharingMode in the
|
|
<<resources-sharing,Resource Sharing>> section below for supported
|
|
values.
|
|
* 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).
|
|
|
|
Bits which can: be set in pname:usage are:
|
|
|
|
// refBegin VkBufferUsageFlagBits Bitmask specifying allowed usage of a buffer
|
|
include::../api/enums/VkBufferUsageFlagBits.txt[]
|
|
|
|
* ename:VK_BUFFER_USAGE_TRANSFER_SRC_BIT indicates 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 indicates that the buffer can: be
|
|
used as the destination of a transfer command.
|
|
* ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT indicates 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 indicates 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 indicates 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 indicates 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 indicates that the buffer is
|
|
suitable for passing as the pname:buffer parameter to
|
|
fname:vkCmdBindIndexBuffer.
|
|
* ename:VK_BUFFER_USAGE_VERTEX_BUFFER_BIT indicates 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 indicates 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[]
|
|
|
|
Any combination of bits can: be specified for pname:usage, but at least one
|
|
of the bits must: be set in order to create a valid buffer.
|
|
|
|
Bits which can: be set in pname:flags are:
|
|
|
|
// refBegin VkBufferCreateFlagBits Bitmask specifying additional parameters of a buffer
|
|
include::../api/enums/VkBufferCreateFlagBits.txt[]
|
|
|
|
These bits have the following meanings:
|
|
|
|
* ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT indicates that the buffer will
|
|
be backed using sparse memory binding.
|
|
* ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT indicates 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 indicates that the buffer will
|
|
be backed using sparse memory binding with memory ranges that might also
|
|
simultaneously be backing another buffer (or another portion of the same
|
|
buffer).
|
|
Buffers created with this flag must: also be created with the
|
|
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT flag.
|
|
|
|
See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and
|
|
<<features-features,Physical Device Features>> for details of the sparse
|
|
memory features supported on a device.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBufferCreateInfo-size-00912]] pname:size must: be greater than `0`
|
|
* [[VUID-VkBufferCreateInfo-sharingMode-00913]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT,
|
|
pname:pQueueFamilyIndices must: be a pointer to an array of
|
|
pname:queueFamilyIndexCount basetype:uint32_t values
|
|
* [[VUID-VkBufferCreateInfo-sharingMode-00914]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT,
|
|
pname:queueFamilyIndexCount must: be greater than `1`
|
|
* [[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_KHX_external_memory+VK_NV_dedicated_allocation[]
|
|
* [[VUID-VkBufferCreateInfo-handleTypes-00919]] If any of the handle types specified in
|
|
sname:VkExternalMemoryImageCreateInfoKHX::pname:handleTypes requires
|
|
dedicated allocation, as reported by
|
|
flink:vkGetPhysicalDeviceExternalBufferPropertiesKHX in
|
|
sname:VkExternalBufferPropertiesKHX::pname:externalMemoryProperties::pname:externalMemoryFeatures,
|
|
the pname:pNext chain must: contain an instance of
|
|
sname:VkDedicatedAllocationBufferCreateInfoNV with its
|
|
pname:dedicatedAllocation field set to ename:VK_TRUE.
|
|
endif::VK_KHX_external_memory+VK_NV_dedicated_allocation[]
|
|
ifdef::VK_KHX_external_memory[]
|
|
* [[VUID-VkBufferCreateInfo-pNext-00920]] If the pname:pNext extension contains an instance of
|
|
slink:VkExternalMemoryBufferCreateInfoKHX, its pname:handleTypes member
|
|
must: only contain bits that are also in
|
|
slink:VkExternalBufferPropertiesKHX::pname:externalMemoryProperties.pname:compatibleHandleTypes,
|
|
as returned by flink:vkGetPhysicalDeviceExternalBufferPropertiesKHX with
|
|
pname:pExternalBufferInfo->pname:handleType equal to any one of the
|
|
handle types specified in
|
|
slink:VkExternalMemoryBufferCreateInfoKHX::pname:handleTypes
|
|
endif::VK_KHX_external_memory[]
|
|
****
|
|
|
|
include::../validity/structs/VkBufferCreateInfo.txt[]
|
|
|
|
ifdef::VK_NV_dedicated_allocation[]
|
|
|
|
// refBegin VkDedicatedAllocationBufferCreateInfoNV Specify that a buffer is bound to a dedicated memory resource
|
|
|
|
If the pname:pNext list includes a
|
|
sname:VkDedicatedAllocationBufferCreateInfoNV structure, then that structure
|
|
includes an enable controlling whether the buffer will have a dedicated
|
|
memory allocation bound to it.
|
|
|
|
The sname:VkDedicatedAllocationBufferCreateInfoNV structure is defined as:
|
|
|
|
include::../api/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:dedicatedAllocation indicates whether the buffer will have a
|
|
dedicated allocation bound to it.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkDedicatedAllocationBufferCreateInfoNV-dedicatedAllocation-00921]] If pname:dedicatedAllocation is ename:VK_TRUE,
|
|
sname:VkBufferCreateInfo::pname:flags must: not include
|
|
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT,
|
|
ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT, or
|
|
ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT
|
|
****
|
|
|
|
include::../validity/structs/VkDedicatedAllocationBufferCreateInfoNV.txt[]
|
|
|
|
endif::VK_NV_dedicated_allocation[]
|
|
|
|
ifdef::VK_KHX_external_memory[]
|
|
|
|
// refBegin VkExternalMemoryBufferCreateInfoKHX Specify that a buffer may be backed by external memory
|
|
|
|
To define a set of external memory handle types that may: be used as backing
|
|
store for a buffer, add a slink:VkExternalMemoryBufferCreateInfoKHX
|
|
structure to the pname:pNext chain of the slink:VkBufferCreateInfo
|
|
structure.
|
|
The sname:VkExternalMemoryBufferCreateInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkExternalMemoryBufferCreateInfoKHX.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:VkExternalMemoryHandleTypeFlagBitsKHX specifying one or more
|
|
external memory handle types.
|
|
|
|
include::../validity/structs/VkExternalMemoryBufferCreateInfoKHX.txt[]
|
|
|
|
endif::VK_KHX_external_memory[]
|
|
|
|
// refBegin vkDestroyBuffer Destroy a buffer object
|
|
|
|
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
|
|
|
|
// refBegin VkBufferView Opaque handle to a buffer view object
|
|
|
|
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[]
|
|
|
|
// refEnd VkBufferView
|
|
|
|
// refBegin vkCreateBufferView Create a new buffer view object
|
|
|
|
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[]
|
|
|
|
// refBegin VkBufferViewCreateInfo Structure specifying parameters of a newly created buffer view
|
|
|
|
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-00927]] If pname:range is not equal to ename:VK_WHOLE_SIZE:
|
|
** [[VUID-VkBufferViewCreateInfo-range-00928]] pname:range must: be greater than `0`
|
|
** [[VUID-VkBufferViewCreateInfo-range-00929]] pname:range must: be a multiple of the element size of pname:format
|
|
** [[VUID-VkBufferViewCreateInfo-range-00930]] 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]] 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[]
|
|
|
|
// refBegin vkDestroyBufferView Destroy a buffer view object
|
|
|
|
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
|
|
|
|
// refBegin VkImage Opaque handle to a image object
|
|
|
|
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[]
|
|
|
|
// refEnd VkImage
|
|
|
|
// refBegin vkCreateImage Create a new image object
|
|
|
|
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[]
|
|
|
|
// refBegin VkImageCreateInfo Structure specifying the parameters of a newly created image object
|
|
|
|
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 describing additional parameters of the image.
|
|
See elink:VkImageCreateFlagBits below for a description of the supported
|
|
bits.
|
|
* pname:imageType is a elink:VkImageType specifying the basic
|
|
dimensionality of the image, as described below.
|
|
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 specifying the tiling arrangement
|
|
of the data elements in memory, as described below.
|
|
* pname:usage is a bitmask describing the intended usage of the image.
|
|
See elink:VkImageUsageFlagBits below for a description of the supported
|
|
bits.
|
|
* pname:sharingMode is the sharing mode of the image when it will be
|
|
accessed by multiple queue families, and must: be one of the values
|
|
described for elink:VkSharingMode in the <<resources-sharing,Resource
|
|
Sharing>> section below.
|
|
* 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 selects the initial elink:VkImageLayout state 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:type, pname:tiling, pname:usage, and pname:flags,
|
|
call
|
|
ifdef::VK_KHR_get_physical_device_properties2[]
|
|
flink:vkGetPhysicalDeviceImageFormatProperties2KHR.
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
ifndef::VK_KHR_get_physical_device_properties2[]
|
|
flink:vkGetPhysicalDeviceImageFormatProperties.
|
|
endif::VK_KHR_get_physical_device_properties2[]
|
|
The return value indicates whether that combination of image settings is
|
|
supported.
|
|
On success, the sname:VkImageFormatProperties output parameter indicates the
|
|
set of valid pname:samples bits and the limits for pname:extent,
|
|
pname:mipLevels, and pname:arrayLayers.
|
|
|
|
To determine the set of valid pname:usage bits for a given format, call
|
|
flink:vkGetPhysicalDeviceFormatProperties.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageCreateInfo-format-00940]] The combination of pname:format, pname:type, pname:tiling, pname:usage,
|
|
and pname:flags must: be supported, as indicated by a VK_SUCCESS return
|
|
value from fname:vkGetPhysicalDeviceImageFormatProperties invoked with
|
|
the same values passed to the corresponding parameters.
|
|
* [[VUID-VkImageCreateInfo-sharingMode-00941]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT,
|
|
pname:pQueueFamilyIndices must: be a pointer to an array of
|
|
pname:queueFamilyIndexCount basetype:uint32_t values
|
|
* [[VUID-VkImageCreateInfo-sharingMode-00942]] If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT,
|
|
pname:queueFamilyIndexCount must: be greater than `1`
|
|
* [[VUID-VkImageCreateInfo-format-00943]] pname:format must: not be ename:VK_FORMAT_UNDEFINED
|
|
* [[VUID-VkImageCreateInfo-extent-00944]] pname:extent::pname:width must: be greater than `0`.
|
|
* [[VUID-VkImageCreateInfo-extent-00945]] pname:extent::pname:height must: be greater than `0`.
|
|
* [[VUID-VkImageCreateInfo-extent-00946]] pname:extent::pname:depth must: be greater than `0`.
|
|
* [[VUID-VkImageCreateInfo-mipLevels-00947]] pname:mipLevels must: be greater than `0`
|
|
* [[VUID-VkImageCreateInfo-arrayLayers-00948]] pname:arrayLayers must: be greater than `0`
|
|
* [[VUID-VkImageCreateInfo-flags-00949]] If pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT,
|
|
pname:imageType must: be ename:VK_IMAGE_TYPE_2D
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageCreateInfo-flags-00950]] If pname:flags contains
|
|
ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR, pname:imageType must:
|
|
be ename:VK_IMAGE_TYPE_3D
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageCreateInfo-imageType-00951]] If pname:imageType is ename:VK_IMAGE_TYPE_1D, pname:extent.width must:
|
|
be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxImageDimension1D, or
|
|
sname:VkImageFormatProperties::pname:maxExtent.width (as returned by
|
|
fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
|
|
pname:type, pname:tiling, pname:usage, and pname:flags equal to those in
|
|
this structure) - whichever is higher
|
|
* [[VUID-VkImageCreateInfo-imageType-00952]] If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags does not
|
|
contain ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width
|
|
and pname:extent.height must: be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxImageDimension2D, or
|
|
sname:VkImageFormatProperties::pname:maxExtent.width/height (as returned
|
|
by fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
|
|
pname:type, pname:tiling, pname:usage, and pname:flags equal to those in
|
|
this structure) - whichever is higher
|
|
* [[VUID-VkImageCreateInfo-imageType-00953]] If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags contains
|
|
ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width and
|
|
pname:extent.height must: be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxImageDimensionCube, or
|
|
sname:VkImageFormatProperties::pname:maxExtent.width/height (as returned
|
|
by fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
|
|
pname:type, pname:tiling, pname:usage, and pname:flags equal to those in
|
|
this structure) - whichever is higher
|
|
* [[VUID-VkImageCreateInfo-imageType-00954]] If pname:imageType is ename:VK_IMAGE_TYPE_2D and pname:flags contains
|
|
ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT, pname:extent.width and
|
|
pname:extent.height must: be equal and pname:arrayLayers must: be
|
|
greater than or equal to 6
|
|
* [[VUID-VkImageCreateInfo-imageType-00955]] If pname:imageType is ename:VK_IMAGE_TYPE_3D, pname:extent.width,
|
|
pname:extent.height and pname:extent.depth must: be less than or equal
|
|
to sname:VkPhysicalDeviceLimits::pname:maxImageDimension3D, or
|
|
sname:VkImageFormatProperties::pname:maxExtent.width/height/depth (as
|
|
returned by fname:vkGetPhysicalDeviceImageFormatProperties with
|
|
pname:format, pname:type, 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} + 1#.
|
|
* [[VUID-VkImageCreateInfo-extent-00959]] If any of pname:extent.width, pname:extent.height, or pname:extent.depth
|
|
are greater than the equivalently named members of
|
|
sname:VkPhysicalDeviceLimits::pname:maxImageDimension3D, pname:mipLevels
|
|
must: be less than or equal to
|
|
sname:VkImageFormatProperties::pname:maxMipLevels (as returned by
|
|
fname:vkGetPhysicalDeviceImageFormatProperties with pname:format,
|
|
pname:type, 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:type, 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:type, pname:tiling, pname:usage, and pname:flags equal to those in
|
|
this structure
|
|
* [[VUID-VkImageCreateInfo-usage-00968]] If the <<features-features-shaderStorageImageMultisample,multisampled
|
|
storage images>> feature is not enabled, and pname:usage contains
|
|
ename:VK_IMAGE_USAGE_STORAGE_BIT, pname:samples must: be
|
|
ename:VK_SAMPLE_COUNT_1_BIT
|
|
* [[VUID-VkImageCreateInfo-flags-00969]] If the <<features-features-sparseBinding,sparse bindings>> feature is
|
|
not enabled, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT
|
|
* [[VUID-VkImageCreateInfo-imageType-00970]] If pname:imageType is ename:VK_IMAGE_TYPE_1D, pname:flags must: not
|
|
contain ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
|
|
* [[VUID-VkImageCreateInfo-imageType-00971]] If the <<features-features-sparseResidencyImage2D,sparse residency for
|
|
2D images>> feature is not enabled, and pname:imageType is
|
|
ename:VK_IMAGE_TYPE_2D, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
|
|
* [[VUID-VkImageCreateInfo-imageType-00972]] If the <<features-features-sparseResidencyImage3D,sparse residency for
|
|
3D images>> feature is not enabled, and pname:imageType is
|
|
ename:VK_IMAGE_TYPE_3D, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
|
|
* [[VUID-VkImageCreateInfo-imageType-00973]] If the <<features-features-sparseResidency2Samples,sparse residency for
|
|
images with 2 samples>> feature is not enabled, pname:imageType is
|
|
ename:VK_IMAGE_TYPE_2D, and pname:samples is
|
|
ename:VK_SAMPLE_COUNT_2_BIT, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
|
|
* [[VUID-VkImageCreateInfo-imageType-00974]] If the <<features-features-sparseResidency4Samples,sparse residency for
|
|
images with 4 samples>> feature is not enabled, pname:imageType is
|
|
ename:VK_IMAGE_TYPE_2D, and pname:samples is
|
|
ename:VK_SAMPLE_COUNT_4_BIT, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
|
|
* [[VUID-VkImageCreateInfo-imageType-00975]] If the <<features-features-sparseResidency8Samples,sparse residency for
|
|
images with 8 samples>> feature is not enabled, pname:imageType is
|
|
ename:VK_IMAGE_TYPE_2D, and pname:samples is
|
|
ename:VK_SAMPLE_COUNT_8_BIT, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
|
|
* [[VUID-VkImageCreateInfo-imageType-00976]] If the <<features-features-sparseResidency16Samples,sparse residency for
|
|
images with 16 samples>> feature is not enabled, pname:imageType is
|
|
ename:VK_IMAGE_TYPE_2D, and pname:samples is
|
|
ename:VK_SAMPLE_COUNT_16_BIT, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00977]] If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, pname:format must: be a
|
|
format that has at least one supported feature bit present in the value
|
|
of sname:VkFormatProperties::pname:linearTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageCreateInfo-tiling-00978]] If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, and
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT, pname:usage must: not contain
|
|
ename:VK_IMAGE_USAGE_SAMPLED_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00979]] If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, and
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT, pname:usage must: not contain
|
|
ename:VK_IMAGE_USAGE_STORAGE_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00980]] If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, and
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, pname:usage must: not
|
|
contain ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00981]] If pname:tiling is ename:VK_IMAGE_TILING_LINEAR, and
|
|
sname:VkFormatProperties::pname:linearTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, pname:usage must:
|
|
not contain ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00982]] If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, pname:format must: be
|
|
a format that has at least one supported feature bit present in the
|
|
value of sname:VkFormatProperties::pname:optimalTilingFeatures returned
|
|
by fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageCreateInfo-tiling-00983]] If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT, pname:usage must: not contain
|
|
ename:VK_IMAGE_USAGE_SAMPLED_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00984]] If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT, pname:usage must: not contain
|
|
ename:VK_IMAGE_USAGE_STORAGE_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00985]] If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT, pname:usage must: not
|
|
contain ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
|
|
* [[VUID-VkImageCreateInfo-tiling-00986]] If pname:tiling is ename:VK_IMAGE_TILING_OPTIMAL, and
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures (as returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format) does not include
|
|
ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT, pname:usage must:
|
|
not contain ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
|
|
* [[VUID-VkImageCreateInfo-flags-00987]] If pname:flags contains ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT or
|
|
ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT, it must: also contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT
|
|
ifdef::VK_NV_external_memory+VK_KHX_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:VkExternalMemoryImageCreateInfoKHX.
|
|
endif::VK_NV_external_memory+VK_KHX_external_memory[]
|
|
ifdef::VK_KHX_external_memory+VK_NV_dedicated_allocation[]
|
|
* [[VUID-VkImageCreateInfo-pNext-00989]] If the pname:pNext chain contains an instance of
|
|
sname:VkExternalMemoryImageCreateInfoKHX, and any of the handle types
|
|
specified in sname:VkExternalMemoryImageCreateInfoKHX::pname:handleTypes
|
|
require a dedicated allocation, as reported by
|
|
flink:vkGetPhysicalDeviceImageFormatProperties2KHR in
|
|
sname:VkExternalImageFormatPropertiesKHX::pname:externalMemoryProperties::pname:externalMemoryFeatures,
|
|
the pname:pNext chain must: contain an instance of
|
|
sname:VkDedicatedAllocationImageCreateInfoNV with its
|
|
pname:dedicatedAllocation field set to ename:VK_TRUE.
|
|
endif::VK_KHX_external_memory+VK_NV_dedicated_allocation[]
|
|
ifdef::VK_KHX_external_memory[]
|
|
* [[VUID-VkImageCreateInfo-pNext-00990]] If the pname:pNext chain contains an instance of
|
|
slink:VkExternalMemoryImageCreateInfoKHX, its pname:handleTypes member
|
|
must: only contain bits that are also in
|
|
slink:VkExternalImageFormatPropertiesKHX::pname:externalMemoryProperties::pname:compatibleHandleTypes,
|
|
as returned by flink:vkGetPhysicalDeviceImageFormatProperties2KHR with
|
|
pname:format, pname:type, pname:tiling, pname:usage, and pname:flags
|
|
equal to those in this structure, and with an instance of
|
|
slink:VkPhysicalDeviceExternalImageFormatInfoKHX in the pname:pNext
|
|
chain, with a pname:handleType equal to any one of the handle types
|
|
specified in slink:VkExternalMemoryImageCreateInfoKHX::pname:handleTypes
|
|
endif::VK_KHX_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:type, pname:tiling, pname:usage, and
|
|
pname:flags equal to those in this structure, and with
|
|
pname:externalHandleType equal to any one of the handle types specified
|
|
in slink:VkExternalMemoryImageCreateInfoNV::pname:handleTypes
|
|
endif::VK_NV_external_memory+VK_NV_external_memory_capabilities[]
|
|
ifdef::VK_KHX_device_group[]
|
|
* [[VUID-VkImageCreateInfo-flags-00992]] If pname:flags contains ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX, then
|
|
pname:mipLevels must: be one, pname:arrayLayers must: be one,
|
|
pname:imageType must: be ename:VK_IMAGE_TYPE_2D, and pname:tiling must:
|
|
be ename:VK_IMAGE_TILING_OPTIMAL.
|
|
endif::VK_KHX_device_group[]
|
|
* [[VUID-VkImageCreateInfo-initialLayout-00993]] pname:initialLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or
|
|
ename:VK_IMAGE_LAYOUT_PREINITIALIZED.
|
|
****
|
|
|
|
include::../validity/structs/VkImageCreateInfo.txt[]
|
|
|
|
ifdef::VK_NV_dedicated_allocation[]
|
|
|
|
// refBegin VkDedicatedAllocationImageCreateInfoNV Specify that an image is bound to a dedicated memory resource
|
|
|
|
If the pname:pNext list includes a
|
|
sname:VkDedicatedAllocationImageCreateInfoNV structure, then that structure
|
|
includes an enable controlling whether the image will have a dedicated
|
|
memory allocation bound to it.
|
|
|
|
The sname:VkDedicatedAllocationImageCreateInfoNV structure is defined as:
|
|
|
|
include::../api/structs/VkDedicatedAllocationImageCreateInfoNV.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:dedicatedAllocation indicates whether the image will have a
|
|
dedicated allocation bound to it.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Using a dedicated allocation for color and depth/stencil attachments or
|
|
other large images may: improve performance on some devices.
|
|
====
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkDedicatedAllocationImageCreateInfoNV-dedicatedAllocation-00994]] If pname:dedicatedAllocation is ename:VK_TRUE,
|
|
sname:VkImageCreateInfo::pname:flags must: not include
|
|
ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT,
|
|
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or
|
|
ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT
|
|
****
|
|
|
|
include::../validity/structs/VkDedicatedAllocationImageCreateInfoNV.txt[]
|
|
|
|
endif::VK_NV_dedicated_allocation[]
|
|
|
|
ifdef::VK_KHX_external_memory[]
|
|
|
|
// refBegin VkExternalMemoryImageCreateInfoKHX Specify that an image may be backed by external memory
|
|
|
|
To define a set of external memory handle types that may: be used as backing
|
|
store for an image, add a slink:VkExternalMemoryImageCreateInfoKHX structure
|
|
to the pname:pNext chain of the slink:VkImageCreateInfo structure.
|
|
The sname:VkExternalMemoryImageCreateInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkExternalMemoryImageCreateInfoKHX.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:VkExternalMemoryHandleTypeFlagBitsKHX specifying one or more
|
|
external memory handle types.
|
|
|
|
include::../validity/structs/VkExternalMemoryImageCreateInfoKHX.txt[]
|
|
|
|
endif::VK_KHX_external_memory[]
|
|
|
|
ifdef::VK_NV_external_memory[]
|
|
|
|
// refBegin VkExternalMemoryImageCreateInfoNV Specify that an image may be backed by external memory
|
|
|
|
If the pname:pNext list includes a sname:VkExternalMemoryImageCreateInfoNV
|
|
structure, then that structure defines a set of external memory handle types
|
|
that may: be used as backing store for the image.
|
|
|
|
The sname:VkExternalMemoryImageCreateInfoNV structure is defined as:
|
|
|
|
include::../api/structs/VkExternalMemoryImageCreateInfoNV.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:handleTypes is a bitmask of
|
|
elink:VkExternalMemoryHandleTypeFlagBitsNV specifying one or more
|
|
external memory handle types.
|
|
|
|
include::../validity/structs/VkExternalMemoryImageCreateInfoNV.txt[]
|
|
|
|
endif::VK_NV_external_memory[]
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
// refBegin VkImageSwapchainCreateInfoKHX Specify that an image will be bound to swapchain memory
|
|
|
|
If the pname:pNext list of slink:VkImageCreateInfo includes a
|
|
sname:VkImageSwapchainCreateInfoKHX structure, then that structure includes
|
|
a swapchain handle indicating that the image will be bound to memory from
|
|
that swapchain.
|
|
|
|
The sname:VkImageSwapchainCreateInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkImageSwapchainCreateInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:swapchain is dlink:VK_NULL_HANDLE or a handle of a swapchain that
|
|
the image will be bound to.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageSwapchainCreateInfoKHX-swapchain-00995]] If pname:swapchain is not dlink:VK_NULL_HANDLE, the fields of
|
|
slink:VkImageCreateInfo must: match the
|
|
<<swapchain-wsi-image-create-info, implied image creation parameters>>
|
|
of the swapchain
|
|
****
|
|
|
|
include::../validity/structs/VkImageSwapchainCreateInfoKHX.txt[]
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
// refBegin VkImageUsageFlagBits Bitmask specifying intended usage of an image
|
|
|
|
The intended usage of an image is specified by the bitmask
|
|
slink:VkImageCreateInfo::pname:usage.
|
|
Bits which can: be set include:
|
|
|
|
include::../api/enums/VkImageUsageFlagBits.txt[]
|
|
|
|
These bits have the following meanings:
|
|
|
|
* ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT indicates that the image can: be
|
|
used as the source of a transfer command.
|
|
* ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT indicates that the image can: be
|
|
used as the destination of a transfer command.
|
|
* ename:VK_IMAGE_USAGE_SAMPLED_BIT indicates 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 indicates 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 indicates 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 indicates 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 indicates 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 indicates 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.
|
|
|
|
// refEnd VkImageUsageFlagBits
|
|
|
|
// refBegin VkImageCreateFlagBits Bitmask specifying additional parameters of an image
|
|
|
|
Additional parameters of an image are specified by
|
|
slink:VkImageCreateInfo::pname:flags.
|
|
Bits which can: be set include:
|
|
|
|
include::../api/enums/VkImageCreateFlagBits.txt[]
|
|
|
|
These bits have the following meanings:
|
|
|
|
* ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT indicates that the image will
|
|
be backed using sparse memory binding.
|
|
* ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT indicates 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 indicates 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 indicates that the image can:
|
|
be used to create a sname:VkImageView with a different format from the
|
|
image.
|
|
* ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT indicates that the image can:
|
|
be used to create a sname:VkImageView of type
|
|
ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY.
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR indicates that the
|
|
image can: be used to create a sname:VkImageView of type
|
|
ename:VK_IMAGE_VIEW_TYPE_2D or ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY.
|
|
endif::VK_KHR_maintenance1[]
|
|
ifdef::VK_KHX_device_group[]
|
|
* ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX indicates that the image can: be
|
|
used with a non-zero value of the pname:SFRRectCount member of the
|
|
slink:VkBindImageMemoryInfoKHX structure passed into
|
|
flink:vkBindImageMemory2KHX.
|
|
This flag also has the effect of making the image use the standard
|
|
sparse image block dimensions.
|
|
endif::VK_KHX_device_group[]
|
|
|
|
If any of the bits ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT,
|
|
ename:VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, or
|
|
ename:VK_IMAGE_CREATE_SPARSE_ALIASED_BIT are set,
|
|
ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT must: not also be set.
|
|
|
|
See <<sparsememory-sparseresourcefeatures,Sparse Resource Features>> and
|
|
<<sparsememory-physicalfeatures,Sparse Physical Device Features>> for more
|
|
details.
|
|
|
|
// refEnd VkImageCreateFlagBits
|
|
|
|
// refBegin VkImageType Specifies the type of an image object
|
|
|
|
The basic dimensionality of an image is specified by
|
|
slink:VkImageCreateInfo::pname:imageType, which must: be one of the values
|
|
|
|
include::../api/enums/VkImageType.txt[]
|
|
|
|
These values specify one-, two-, or three-dimensional images, respectively.
|
|
|
|
// refEnd VkImageType
|
|
|
|
// refBegin VkImageTiling Specifies the tiling arrangement of data in an image
|
|
|
|
The tiling arrangement of data elements in an image is specified by
|
|
slink:VkImageCreateInfo::pname:tiling, which must: be one of the values
|
|
|
|
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),
|
|
and 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).
|
|
|
|
// refEnd VkImageTiling
|
|
|
|
// refBegin vkGetImageSubresourceLayout Retrieve information about an image subresource
|
|
|
|
To query the host access layout of an image subresource, for an image
|
|
created with linear tiling, call:
|
|
|
|
include::../api/protos/vkGetImageSubresourceLayout.txt[]
|
|
|
|
* pname:device is the logical device that owns the image.
|
|
* pname:image is the image whose layout is being queried.
|
|
* pname:pSubresource is a pointer to a slink:VkImageSubresource structure
|
|
selecting a specific image for the image subresource.
|
|
* pname:pLayout points to a slink:VkSubresourceLayout structure in which
|
|
the layout is returned.
|
|
|
|
flink:vkGetImageSubresourceLayout is invariant for the lifetime of a single
|
|
image.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkGetImageSubresourceLayout-image-00996]] pname:image must: have been created with pname:tiling equal to
|
|
ename:VK_IMAGE_TILING_LINEAR
|
|
* [[VUID-vkGetImageSubresourceLayout-aspectMask-00997]] The pname:aspectMask member of pname:pSubresource must: only have a
|
|
single bit set
|
|
****
|
|
|
|
include::../validity/protos/vkGetImageSubresourceLayout.txt[]
|
|
|
|
// refBegin VkImageSubresource Structure specifying a image subresource
|
|
|
|
The sname:VkImageSubresource structure is defined as:
|
|
|
|
include::../api/structs/VkImageSubresource.txt[]
|
|
|
|
* pname:aspectMask is a elink:VkImageAspectFlags selecting the image
|
|
_aspect_.
|
|
* pname:mipLevel selects the mipmap level.
|
|
* pname:arrayLayer selects the array layer.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageSubresource-mipLevel-00998]] pname:mipLevel must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when the image was created
|
|
* [[VUID-VkImageSubresource-arrayLayer-00999]] pname:arrayLayer must: be less than the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when the image was created
|
|
****
|
|
|
|
include::../validity/structs/VkImageSubresource.txt[]
|
|
|
|
// refBegin VkSubresourceLayout Structure specifying subresource layout
|
|
|
|
Information about the layout of the image subresource is returned in a
|
|
sname:VkSubresourceLayout structure:
|
|
|
|
include::../api/structs/VkSubresourceLayout.txt[]
|
|
|
|
* pname:offset is the byte offset from the start of the image where the
|
|
image subresource begins.
|
|
* pname:size is the size in bytes of the image subresource.
|
|
pname:size includes any extra memory that is required based on
|
|
pname:rowPitch.
|
|
* pname:rowPitch describes the number of bytes between each row of texels
|
|
in an image.
|
|
* pname:arrayPitch describes the number of bytes between each array layer
|
|
of an image.
|
|
* pname:depthPitch describes the number of bytes between each slice of 3D
|
|
image.
|
|
|
|
For images created with linear tiling, pname:rowPitch, pname:arrayPitch and
|
|
pname:depthPitch describe the layout of the image subresource in linear
|
|
memory.
|
|
For uncompressed formats, pname:rowPitch is the number of bytes between
|
|
texels with the same x coordinate in adjacent rows (y coordinates differ by
|
|
one).
|
|
pname:arrayPitch is the number of bytes between texels with the same x and y
|
|
coordinate in adjacent array layers of the image (array layer values differ
|
|
by one).
|
|
pname:depthPitch is the number of bytes between texels with the same x and y
|
|
coordinate in adjacent slices of a 3D image (z coordinates differ by one).
|
|
Expressed as an addressing formula, the starting byte of a texel in the
|
|
image subresource has address:
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
// (x,y,z,layer) are in texel coordinates
|
|
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*elementSize + offset
|
|
---------------------------------------------------
|
|
|
|
For compressed formats, the pname:rowPitch is the number of bytes between
|
|
compressed texel blocks in adjacent rows.
|
|
pname:arrayPitch is the number of bytes between compressed texel blocks in
|
|
adjacent array layers.
|
|
pname:depthPitch is the number of bytes between compressed texel blocks in
|
|
adjacent slices of a 3D image.
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
// (x,y,z,layer) are in compressed texel block coordinates
|
|
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset;
|
|
---------------------------------------------------
|
|
|
|
pname:arrayPitch is undefined for images that were not created as arrays.
|
|
pname:depthPitch is defined only for 3D images.
|
|
|
|
For color formats, the pname:aspectMask member of sname:VkImageSubresource
|
|
must: be ename:VK_IMAGE_ASPECT_COLOR_BIT.
|
|
For depth/stencil formats, pname:aspectMask must: be either
|
|
ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT.
|
|
On implementations that store depth and stencil aspects separately, querying
|
|
each of these image subresource layouts will return a different pname:offset
|
|
and pname:size representing the region of memory used for that aspect.
|
|
On implementations that store depth and stencil aspects interleaved, the
|
|
same pname:offset and pname:size are returned and represent the interleaved
|
|
memory allocation.
|
|
|
|
include::../validity/structs/VkSubresourceLayout.txt[]
|
|
|
|
// refBegin vkDestroyImage Destroy an image object
|
|
|
|
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.
|
|
Implementations may: support several opaque layouts, and the layout used at
|
|
any given time is determined by the elink:VkImageLayout state of the image
|
|
subresource.
|
|
Each layout has limitations on what kinds of operations are supported for
|
|
image subresources using the layout.
|
|
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 state 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.
|
|
|
|
// refBegin VkImageLayout Layout of image and image subresources
|
|
|
|
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: Supports no 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: Supports no device access.
|
|
This layout must: only be used as the pname:initialLayout member of
|
|
sname:VkImageCreateInfo or sname:VkAttachmentDescription, or as the
|
|
pname:oldLayout in an image transition.
|
|
When transitioning out of this layout, the contents of the memory are
|
|
preserved.
|
|
This layout is intended to be used as the initial layout for an image
|
|
whose contents are written by the host, and hence the data can: be
|
|
written to memory immediately, without first executing a layout
|
|
transition.
|
|
Currently, ename:VK_IMAGE_LAYOUT_PREINITIALIZED is only useful with
|
|
ename:VK_IMAGE_TILING_LINEAR images because there is not a standard
|
|
layout defined for ename:VK_IMAGE_TILING_OPTIMAL images.
|
|
* ename:VK_IMAGE_LAYOUT_GENERAL: Supports all types of device access.
|
|
* ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL: must: only be used as a
|
|
color or resolve attachment in a sname:VkFramebuffer.
|
|
This layout is valid only for image subresources of images created with
|
|
the ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL: must: only be
|
|
used as a depth/stencil attachment in a sname:VkFramebuffer.
|
|
This layout is valid only for image subresources of images created with
|
|
the ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL: must: only be
|
|
used as a read-only depth/stencil attachment in a sname:VkFramebuffer
|
|
and/or as a read-only image in a shader (which can: be read as a sampled
|
|
image, combined image/sampler and/or input attachment).
|
|
This layout is valid only for image subresources of images created with
|
|
the ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled.
|
|
Only image subresources of images created with
|
|
ename:VK_IMAGE_USAGE_SAMPLED_BIT can: be used as sampled image or
|
|
combined image/sampler in a shader.
|
|
Similarly, only image subresources of images created with
|
|
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT can: be used as input
|
|
attachments.
|
|
* ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL: must: only be used as a
|
|
read-only image in a shader (which can: be read as a sampled image,
|
|
combined image/sampler and/or input attachment).
|
|
This layout is valid only for image subresources of images created with
|
|
the ename:VK_IMAGE_USAGE_SAMPLED_BIT or
|
|
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL: must: only be used as a
|
|
source image of a transfer command (see the definition of
|
|
<<synchronization-pipeline-stages-transfer,
|
|
ename:VK_PIPELINE_STAGE_TRANSFER_BIT>>).
|
|
This layout is valid only for image subresources of images created with
|
|
the ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL: must: only be used as a
|
|
destination image of a transfer command.
|
|
This layout is valid only for image subresources of images created with
|
|
the ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled.
|
|
ifdef::VK_KHR_swapchain[]
|
|
* ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR: must: only be used for presenting
|
|
a presentable image for display.
|
|
A swapchain's image must: be transitioned to this layout before calling
|
|
flink:vkQueuePresentKHR, and must: be transitioned away from this layout
|
|
after calling flink:vkAcquireNextImageKHR.
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR: is valid only for shared
|
|
presentable images, and must: be used for any usage the image supports.
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
endif::VK_KHR_swapchain[]
|
|
|
|
For each mechanism of accessing an image in the API, there is a parameter or
|
|
structure member that controls the image layout used to access the image.
|
|
For transfer commands, this is a parameter to the command (see <<clears>>
|
|
and <<copies>>).
|
|
For use as a framebuffer attachment, this is a member in the substructures
|
|
of the sname:VkRenderPassCreateInfo (see <<renderpass,Render Pass>>).
|
|
For use in a descriptor set, this is a member in the
|
|
sname:VkDescriptorImageInfo structure (see <<descriptorsets-updates>>).
|
|
At the time that any command buffer command accessing an image executes on
|
|
any queue, the layouts of the image subresources that are accessed must: all
|
|
match the layout specified via the API controlling those accesses.
|
|
|
|
The image layout of each image subresource must: be well-defined at each
|
|
point in the image subresource's lifetime.
|
|
This means that when performing a layout transition on the image
|
|
subresource, the old layout value must: either equal the current layout of
|
|
the image subresource (at the time the transition executes), or else be
|
|
ename:VK_IMAGE_LAYOUT_UNDEFINED (implying that the contents of the image
|
|
subresource need not be preserved).
|
|
The new layout used in a transition must: not be
|
|
ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED.
|
|
|
|
// refEnd VkImageLayout
|
|
|
|
|
|
[[resources-image-views]]
|
|
== Image Views
|
|
|
|
// refBegin VkImageView Opaque handle to a image view object
|
|
|
|
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[]
|
|
|
|
// refEnd VkImageView
|
|
|
|
// refBegin VkImageViewType Image view types
|
|
|
|
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,table below>>.
|
|
This table also shows which SPIR-V OpTypeImage Dim and Arrayed parameters
|
|
correspond to each image view type.
|
|
|
|
// refEnd VkImageViewType
|
|
|
|
// refBegin vkCreateImageView Create an image view from an existing image
|
|
|
|
To create an image view, call:
|
|
|
|
include::../api/protos/vkCreateImageView.txt[]
|
|
|
|
* pname:device is the logical device that creates the image view.
|
|
* pname:pCreateInfo is a pointer to an instance of the
|
|
sname:VkImageViewCreateInfo structure containing parameters to be used
|
|
to create the image view.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pView points to a sname:VkImageView handle in which the resulting
|
|
image view object is returned.
|
|
|
|
Some of the image creation parameters are inherited by the view.
|
|
The remaining parameters are contained in the pname:pCreateInfo.
|
|
|
|
include::../validity/protos/vkCreateImageView.txt[]
|
|
|
|
// refBegin VkImageViewCreateInfo Structure specifying parameters of a newly created image view
|
|
|
|
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 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 specifies a remapping of color components (or of depth
|
|
or stencil components after they have been converted into color
|
|
components).
|
|
See slink:VkComponentMapping.
|
|
* pname:subresourceRange is a slink:VkImageSubresourceRange selecting the
|
|
set of mipmap levels and array layers to be accessible to the view.
|
|
|
|
If pname:image was created with the ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
|
|
flag, pname:format can: be different from the image's format, but if they
|
|
are not equal they must: be _compatible_.
|
|
Image format compatibility is defined in the
|
|
<<features-formats-compatibility-classes,Format Compatibility Classes>>
|
|
section.
|
|
|
|
[[resources-image-views-compatibility]]
|
|
.Image and image view parameter compatibility requirements
|
|
[cols="15%h,35%,50%",options="header"]
|
|
|====
|
|
| Dim, Arrayed, MS | Image parameters | View parameters
|
|
| | pname:imageType = ci.pname:imageType +
|
|
pname:width = ci.pname:extent.width +
|
|
pname:height = ci.pname:extent.height +
|
|
pname:depth = ci.pname:extent.depth +
|
|
pname:arrayLayers = ci.pname:arrayLayers +
|
|
pname:samples = ci.pname:samples +
|
|
pname:flags = ci.pname:flags +
|
|
where ci is the slink:VkImageCreateInfo used to create pname:image.
|
|
ifdef::VK_KHR_maintenance1[]
|
|
| pname:baseArrayLayer, pname:layerCount, and pname:levelCount
|
|
endif::VK_KHR_maintenance1[]
|
|
ifndef::VK_KHR_maintenance1[]
|
|
| pname:baseArrayLayer and pname:layerCount
|
|
endif::VK_KHR_maintenance1[]
|
|
are members of the pname:subresourceRange member.
|
|
| 1D, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_1D +
|
|
pname:width {geq} 1 +
|
|
pname:height = 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples = 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_1D +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 1
|
|
| 1D, 1, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_1D +
|
|
pname:width {geq} 1 +
|
|
pname:height = 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples = 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_1D_ARRAY +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount {geq} 1
|
|
| 2D, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples = 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 1
|
|
| 2D, 1, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples = 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount {geq} 1
|
|
| 2D, 0, 1 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples > 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 1
|
|
| 2D, 1, 1 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 1 +
|
|
pname:samples > 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount {geq} 1
|
|
| CUBE, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height = pname:width +
|
|
pname:depth = 1 +
|
|
pname:arrayLayers {geq} 6 +
|
|
pname:samples = 1 +
|
|
pname:flags includes ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_CUBE +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 6
|
|
| CUBE, 1, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_2D +
|
|
pname:width {geq} 1 +
|
|
pname:height = width +
|
|
pname:depth = 1 +
|
|
_N_ {geq} 1 +
|
|
pname:arrayLayers {geq} 6 {times} _N_ +
|
|
pname:samples = 1 +
|
|
pname:flags includes ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount = 6 {times} _N_, _N_ {geq} 1
|
|
| 3D, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_3D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth {geq} 1 +
|
|
pname:arrayLayers = 1 +
|
|
pname:samples = 1 |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_3D +
|
|
pname:baseArrayLayer = 0 +
|
|
pname:layerCount = 1
|
|
ifdef::VK_KHR_maintenance1[]
|
|
| 3D, 0, 0 |
|
|
pname:imageType = ename:VK_IMAGE_TYPE_3D +
|
|
pname:width {geq} 1 +
|
|
pname:height {geq} 1 +
|
|
pname:depth {geq} 1 +
|
|
pname:arrayLayers = 1 +
|
|
pname:samples = 1 +
|
|
pname:flags includes ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT +
|
|
pname:flags does not include VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and 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 VK_IMAGE_CREATE_SPARSE_BINDING_BIT, VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT, and VK_IMAGE_CREATE_SPARSE_ALIASED_BIT |
|
|
pname:viewType = ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY +
|
|
pname:levelCount = 1 +
|
|
pname:baseArrayLayer {geq} 0 +
|
|
pname:layerCount {geq} 1
|
|
endif::VK_KHR_maintenance1[]
|
|
|====
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageViewCreateInfo-image-01003]] If pname:image was not created with
|
|
ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT then pname:viewType must: not
|
|
be ename:VK_IMAGE_VIEW_TYPE_CUBE or ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
|
|
* [[VUID-VkImageViewCreateInfo-viewType-01004]] If the <<features-features-imageCubeArray,image cubemap arrays>> feature
|
|
is not enabled, pname:viewType must: not be
|
|
ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01005]] If pname:image was created with ename:VK_IMAGE_TYPE_3D but without
|
|
ename:VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT_KHR set then
|
|
pname:viewType must: not be ename:VK_IMAGE_VIEW_TYPE_2D or
|
|
ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY
|
|
endif::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageViewCreateInfo-image-01006]] If pname:image was created with ename:VK_IMAGE_TILING_LINEAR,
|
|
pname:format must: be format that has at least one supported feature bit
|
|
present in the value of
|
|
sname:VkFormatProperties::pname:linearTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties with the same value of
|
|
pname:format
|
|
* [[VUID-VkImageViewCreateInfo-image-01007]] pname:image must: have been created with a pname:usage value containing
|
|
at least one of ename:VK_IMAGE_USAGE_SAMPLED_BIT,
|
|
ename:VK_IMAGE_USAGE_STORAGE_BIT,
|
|
ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT,
|
|
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT, or
|
|
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
|
|
* [[VUID-VkImageViewCreateInfo-image-01008]] If pname:image was created with ename:VK_IMAGE_TILING_LINEAR and
|
|
pname:usage containing 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 containing 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 containing 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 containing
|
|
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 containing 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 containing 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 containing 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 containing
|
|
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-01017]] pname:subresourceRange must: be a valid image subresource range for
|
|
pname:image (see <<resources-image-views>>)
|
|
* [[VUID-VkImageViewCreateInfo-image-01018]] If pname:image was created with the
|
|
ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be
|
|
compatible with the pname:format used to create pname:image, as defined
|
|
in <<features-formats-compatibility-classes,Format Compatibility
|
|
Classes>>
|
|
* [[VUID-VkImageViewCreateInfo-image-01019]] If pname:image was not created with the
|
|
ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT flag, pname:format must: be
|
|
identical to the pname:format used to create pname:image
|
|
* [[VUID-VkImageViewCreateInfo-image-01020]] If pname:image is non-sparse then it must: be bound completely and
|
|
contiguously to a single sname:VkDeviceMemory object
|
|
* [[VUID-VkImageViewCreateInfo-subResourceRange-01021]] pname:subResourceRange and pname:viewType must: be compatible with the
|
|
image, as described in the
|
|
<<resources-image-views-compatibility,compatibility table>>
|
|
****
|
|
|
|
include::../validity/structs/VkImageViewCreateInfo.txt[]
|
|
|
|
// refBegin VkImageSubresourceRange Structure specifying a image subresource range
|
|
|
|
The sname:VkImageSubresourceRange structure is defined as:
|
|
|
|
include::../api/structs/VkImageSubresourceRange.txt[]
|
|
|
|
* pname:aspectMask is a bitmask indicating which aspect(s) of the image
|
|
are included in the view.
|
|
See elink:VkImageAspectFlagBits.
|
|
* 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 _pname:baseArrayLayer + i_ is face index _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 is a bitmask indicating the format being used.
|
|
Bits which may: be set include:
|
|
|
|
// refBegin VkImageAspectFlagBits Bitmask specifying which aspects of an image are included in a view
|
|
include::../api/enums/VkImageAspectFlagBits.txt[]
|
|
|
|
The mask must: be only ename:VK_IMAGE_ASPECT_COLOR_BIT,
|
|
ename:VK_IMAGE_ASPECT_DEPTH_BIT or ename:VK_IMAGE_ASPECT_STENCIL_BIT if
|
|
pname:format is a color, depth-only or stencil-only format, respectively.
|
|
If using a depth/stencil format with both depth and stencil components,
|
|
pname:aspectMask must: include at least one of
|
|
ename:VK_IMAGE_ASPECT_DEPTH_BIT and ename:VK_IMAGE_ASPECT_STENCIL_BIT, and
|
|
can: include both.
|
|
|
|
When using an imageView of a depth/stencil image to populate a descriptor
|
|
set (e.g. for sampling in the shader, or for use as an input attachment),
|
|
the pname:aspectMask must: only include one bit and selects whether the
|
|
imageView is used for depth reads (i.e. using a floating-point sampler or
|
|
input attachment in the shader) or stencil reads (i.e. using an unsigned
|
|
integer sampler or input attachment in the shader).
|
|
When an imageView of a depth/stencil image is used as a depth/stencil
|
|
framebuffer attachment, the pname:aspectMask is ignored and both depth and
|
|
stencil image subresources are used.
|
|
|
|
The pname:components member is of type slink:VkComponentMapping, and
|
|
describes a remapping from components of the image to components of the
|
|
vector returned by shader image instructions.
|
|
This remapping must: be identity for storage image descriptors, input
|
|
attachment descriptors, and framebuffer attachments.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkImageSubresourceRange-levelCount-01022]] If pname:levelCount is not ename:VK_REMAINING_MIP_LEVELS,
|
|
[eq]#pname:levelCount# must: be non-zero and [eq]#(pname:baseMipLevel
|
|
{plus} pname:levelCount)# must: be less than or equal to the
|
|
pname:mipLevels specified in slink:VkImageCreateInfo when the image was
|
|
created
|
|
ifndef::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageSubresourceRange-layerCount-01023]] If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS,
|
|
[eq]#pname:layerCount# must: be non-zero and [eq]#(pname:baseArrayLayer
|
|
+ pname:layerCount)# must: be less than or equal to the
|
|
pname:arrayLayers specified in slink:VkImageCreateInfo when the image
|
|
was created
|
|
endif::VK_KHR_maintenance1[]
|
|
ifdef::VK_KHR_maintenance1[]
|
|
* [[VUID-VkImageSubresourceRange-imageType-01024]] If the pname:imageType specified in slink:VkImageCreateInfo when the
|
|
image was created was ename:VK_IMAGE_TYPE_3D and the image view is
|
|
created with the pname:viewType of slink:VkImageViewCreateInfo set to
|
|
ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY then pname:layerCount must: be
|
|
ename:VK_REMAINING_ARRAY_LAYERS, or [eq]#pname:layerCount# must: be
|
|
non-zero and [eq]#(pname:baseArrayLayer + pname:layerCount)# must: be
|
|
less than or equal to the pname:extent.depth specified in
|
|
slink:VkImageCreateInfo when the image was created
|
|
* [[VUID-VkImageSubresourceRange-imageType-01025]] If the pname:imageType specified in slink:VkImageCreateInfo when the
|
|
image was created was not ename:VK_IMAGE_TYPE_3D or the image view is
|
|
not created with the pname:viewType of slink:VkImageViewCreateInfo set
|
|
to ename:VK_IMAGE_VIEW_TYPE_2D_ARRAY then pname:layerCount must: be
|
|
ename:VK_REMAINING_ARRAY_LAYERS, or [eq]#pname:layerCount# must: be
|
|
non-zero and [eq]#(pname:baseArrayLayer + pname:layerCount)# must: be
|
|
less than or equal to the pname:arrayLayers specified in
|
|
slink:VkImageCreateInfo when the image was created
|
|
endif::VK_KHR_maintenance1[]
|
|
|
|
|
|
****
|
|
|
|
include::../validity/structs/VkImageSubresourceRange.txt[]
|
|
|
|
// refBegin VkComponentMapping Structure specifying a color component mapping
|
|
|
|
The sname:VkComponentMapping structure is defined as:
|
|
|
|
include::../api/structs/VkComponentMapping.txt[]
|
|
|
|
* pname:r determines the component value placed in the R component of the
|
|
output vector.
|
|
* pname:g determines the component value placed in the G component of the
|
|
output vector.
|
|
* pname:b determines the component value placed in the B component of the
|
|
output vector.
|
|
* pname:a determines the component value placed in the A component of the
|
|
output vector.
|
|
|
|
Each of pname:r, pname:g, pname:b, and pname:a is one of the values:
|
|
|
|
// refBegin VkComponentSwizzle Specify how a component is swizzled
|
|
include::../api/enums/VkComponentSwizzle.txt[]
|
|
|
|
* ename:VK_COMPONENT_SWIZZLE_IDENTITY: the component is set to the
|
|
identity swizzle.
|
|
* ename:VK_COMPONENT_SWIZZLE_ZERO: the component is set to zero.
|
|
* ename:VK_COMPONENT_SWIZZLE_ONE: 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: the component is set to the value of the R
|
|
component of the image.
|
|
* ename:VK_COMPONENT_SWIZZLE_G: the component is set to the value of the G
|
|
component of the image.
|
|
* ename:VK_COMPONENT_SWIZZLE_B: the component is set to the value of the B
|
|
component of the image.
|
|
* ename:VK_COMPONENT_SWIZZLE_A: 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
|
|
|====
|
|
|
|
include::../validity/structs/VkComponentMapping.txt[]
|
|
|
|
// refBegin vkDestroyImageView Destroy an image view object
|
|
|
|
To destroy an image view, call:
|
|
|
|
include::../api/protos/vkDestroyImageView.txt[]
|
|
|
|
* pname:device is the logical device that destroys the image view.
|
|
* pname:imageView is the image view to destroy.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkDestroyImageView-imageView-01026]] All submitted commands that refer to pname:imageView must: have
|
|
completed execution
|
|
* [[VUID-vkDestroyImageView-imageView-01027]] If sname:VkAllocationCallbacks were provided when pname:imageView was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* [[VUID-vkDestroyImageView-imageView-01028]] If no sname:VkAllocationCallbacks were provided when pname:imageView was
|
|
created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyImageView.txt[]
|
|
|
|
|
|
[[resources-association]]
|
|
== Resource Memory Association
|
|
|
|
Resources are initially created as _virtual allocations_ with no backing
|
|
memory.
|
|
Device memory is allocated separately (see <<memory-device>>) and then
|
|
associated with the resource.
|
|
This association is done differently for sparse and non-sparse resources.
|
|
|
|
Resources created with any of the sparse creation flags are considered
|
|
sparse resources.
|
|
Resources created without these flags are non-sparse.
|
|
The details on resource memory association for sparse resources is described
|
|
in <<sparsememory>>.
|
|
|
|
Non-sparse resources must: be bound completely and contiguously to a single
|
|
sname:VkDeviceMemory object before the resource is passed as a parameter to
|
|
any of the following operations:
|
|
|
|
* creating image or buffer views
|
|
* updating descriptor sets
|
|
* recording commands in a command buffer
|
|
|
|
Once bound, the memory binding is immutable for the lifetime of the
|
|
resource.
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
In a logical device representing more than one physical device, buffer and
|
|
image resources exist on all physical devices but can: be bound to memory
|
|
differently on each.
|
|
Each such replicated resource is an _instance_ of the resource.
|
|
For sparse resources, each instance can: be bound to memory arbitrarily
|
|
differently.
|
|
For non-sparse resources, each instance can: either be bound to the local or
|
|
a peer instance of the memory, or for images can: be bound to rectangular
|
|
regions from the local and/or peer instances.
|
|
When a resource is used in a descriptor set, each physical device interprets
|
|
the descriptor according to its own instance's binding to memory.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
There are no new copy commands to transfer data between physical devices.
|
|
Instead, an application can: create a resource with a peer mapping and use
|
|
it as the source or destination of a transfer command executed by a single
|
|
physical device to copy the data from one physical device to another.
|
|
====
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
// refBegin vkGetBufferMemoryRequirements Returns the memory requirements for specified Vulkan object
|
|
|
|
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[]
|
|
|
|
// refBegin vkGetImageMemoryRequirements Returns the memory requirements for specified Vulkan object
|
|
|
|
To determine the memory requirements for an image resource, call:
|
|
|
|
include::../api/protos/vkGetImageMemoryRequirements.txt[]
|
|
|
|
* pname:device is the logical device that owns the image.
|
|
* pname:image is the image to query.
|
|
* pname:pMemoryRequirements points to an instance of the
|
|
slink:VkMemoryRequirements structure in which the memory requirements of
|
|
the image object are returned.
|
|
|
|
include::../validity/protos/vkGetImageMemoryRequirements.txt[]
|
|
|
|
// refBegin VkMemoryRequirements Structure specifying memory requirements
|
|
|
|
The sname:VkMemoryRequirements structure is defined as:
|
|
|
|
include::../api/structs/VkMemoryRequirements.txt[]
|
|
|
|
* pname:size is the size, in bytes, of the memory allocation required: for
|
|
the resource.
|
|
* pname:alignment is the alignment, in bytes, of the offset within the
|
|
allocation required: for the resource.
|
|
* pname:memoryTypeBits is a bitmask and contains one bit set for every
|
|
supported memory type for the resource.
|
|
Bit `i` is set if and only if the memory type `i` in the
|
|
sname:VkPhysicalDeviceMemoryProperties structure for the physical device
|
|
is supported for the resource.
|
|
|
|
include::../validity/structs/VkMemoryRequirements.txt[]
|
|
|
|
The implementation guarantees certain properties about the memory
|
|
requirements returned by flink:vkGetBufferMemoryRequirements and
|
|
flink:vkGetImageMemoryRequirements:
|
|
|
|
* The pname:memoryTypeBits member always contains at least one bit set.
|
|
* If pname:buffer is a sname:VkBuffer not created with the
|
|
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT bit set, or if pname:image is
|
|
a sname:VkImage that was created with a ename:VK_IMAGE_TILING_LINEAR
|
|
value in the pname:tiling member of the sname:VkImageCreateInfo
|
|
structure passed to fname:vkCreateImage, then the pname:memoryTypeBits
|
|
member always contains at least one bit set corresponding to a
|
|
sname:VkMemoryType with a pname:propertyFlags that has both the
|
|
ename:VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT bit and the
|
|
ename:VK_MEMORY_PROPERTY_HOST_COHERENT_BIT bit set.
|
|
In other words, mappable coherent memory can: always be attached to
|
|
these objects.
|
|
* The 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 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 pname:flags, then the bits set in
|
|
pname:memoryTypeBits returned for code:usage1 must: be a subset of the
|
|
bits set in pname:memoryTypeBits returned for code:usage2, for all
|
|
values of pname:flags.
|
|
* The pname:alignment member is a power of two.
|
|
* The pname:alignment member is identical for all sname:VkBuffer objects
|
|
created with the same combination of values for the pname:usage and
|
|
pname:flags members in the sname:VkBufferCreateInfo structure passed to
|
|
fname:vkCreateBuffer.
|
|
* For images created with a color format, the pname:memoryTypeBits member
|
|
is identical for all sname:VkImage objects created with the same
|
|
combination of values for the pname:tiling member, the
|
|
ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the pname:flags member,
|
|
ifdef::VK_KHX_device_group[]
|
|
the ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX bit of the pname:flags
|
|
member,
|
|
endif::VK_KHX_device_group[]
|
|
and the ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT of the pname:usage
|
|
member in the sname:VkImageCreateInfo structure passed to
|
|
fname:vkCreateImage.
|
|
* For images created with a depth/stencil format, the pname:memoryTypeBits
|
|
member is identical for all sname:VkImage objects created with the same
|
|
combination of values for the pname:format member, the pname:tiling
|
|
member, the ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the
|
|
pname:flags member,
|
|
ifdef::VK_KHX_device_group[]
|
|
the ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX bit of the pname:flags
|
|
member,
|
|
endif::VK_KHX_device_group[]
|
|
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.
|
|
====
|
|
--
|
|
|
|
// refBegin vkBindBufferMemory Bind device memory to a buffer object
|
|
|
|
To attach memory to a buffer object, call:
|
|
|
|
include::../api/protos/vkBindBufferMemory.txt[]
|
|
|
|
* pname:device is the logical device that owns the buffer and memory.
|
|
* pname:buffer is the buffer to be attached to memory.
|
|
* pname:memory is a sname:VkDeviceMemory object describing the device
|
|
memory to attach.
|
|
* pname:memoryOffset is the start offset of the region of pname:memory
|
|
which is to be bound to the buffer.
|
|
The number of bytes returned in the
|
|
sname:VkMemoryRequirements::pname:size member in pname:memory, starting
|
|
from pname:memoryOffset bytes, will be bound to the specified buffer.
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
fname:vkBindBufferMemory is equivalent to passing the same parameters
|
|
through slink:VkBindBufferMemoryInfoKHX to flink:vkBindBufferMemory2KHX,
|
|
with pname:deviceIndexCount equal to zero.
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkBindBufferMemory-buffer-01029]] pname:buffer must: not already be backed by a memory object
|
|
* [[VUID-vkBindBufferMemory-buffer-01030]] pname:buffer must: not have been created with any sparse memory binding
|
|
flags
|
|
* [[VUID-vkBindBufferMemory-memoryOffset-01031]] pname:memoryOffset must: be less than the size of pname:memory
|
|
* [[VUID-vkBindBufferMemory-buffer-01032]] If pname:buffer was created with the
|
|
ename:VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT or
|
|
ename:VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT, pname:memoryOffset must:
|
|
be a multiple of
|
|
sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment
|
|
* [[VUID-vkBindBufferMemory-buffer-01033]] If pname:buffer was created with the
|
|
ename:VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT, pname:memoryOffset must: be a
|
|
multiple of
|
|
sname:VkPhysicalDeviceLimits::pname:minUniformBufferOffsetAlignment
|
|
* [[VUID-vkBindBufferMemory-buffer-01034]] If pname:buffer was created with the
|
|
ename:VK_BUFFER_USAGE_STORAGE_BUFFER_BIT, pname:memoryOffset must: be a
|
|
multiple of
|
|
sname:VkPhysicalDeviceLimits::pname:minStorageBufferOffsetAlignment
|
|
* [[VUID-vkBindBufferMemory-memory-01035]] pname:memory must: have been allocated using one of the memory types
|
|
allowed in the pname:memoryTypeBits member of the
|
|
sname:VkMemoryRequirements structure returned from a call to
|
|
fname:vkGetBufferMemoryRequirements with pname:buffer
|
|
* [[VUID-vkBindBufferMemory-memoryOffset-01036]] pname:memoryOffset must: be an integer multiple of the pname:alignment
|
|
member of the sname:VkMemoryRequirements structure returned from a call
|
|
to fname:vkGetBufferMemoryRequirements with pname:buffer
|
|
* [[VUID-vkBindBufferMemory-size-01037]] The pname:size member of the sname:VkMemoryRequirements structure
|
|
returned from a call to fname:vkGetBufferMemoryRequirements with
|
|
pname:buffer must: be less than or equal to the size of pname:memory
|
|
minus pname:memoryOffset
|
|
ifdef::VK_NV_dedicated_allocation[]
|
|
* [[VUID-vkBindBufferMemory-buffer-01038]] If pname:buffer was created with
|
|
sname:VkDedicatedAllocationBufferCreateInfoNV::pname:dedicatedAllocation
|
|
equal to ename:VK_TRUE, pname:memory must: have been created with
|
|
sname:VkDedicatedAllocationMemoryAllocateInfoNV::pname:buffer equal to
|
|
pname:buffer and pname:memoryOffset must: be zero
|
|
* [[VUID-vkBindBufferMemory-buffer-01039]] If pname:buffer was not created with
|
|
sname:VkDedicatedAllocationBufferCreateInfoNV::pname:dedicatedAllocation
|
|
equal to ename:VK_TRUE, pname:memory must: not have been allocated
|
|
dedicated for a specific buffer or image
|
|
endif::VK_NV_dedicated_allocation[]
|
|
****
|
|
|
|
include::../validity/protos/vkBindBufferMemory.txt[]
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
// refBegin vkBindBufferMemory2KHX Bind device memory to buffer objects
|
|
|
|
To attach memory to buffer objects for one or more buffers at a time, call:
|
|
|
|
include::../api/protos/vkBindBufferMemory2KHX.txt[]
|
|
|
|
* pname:device is the logical device that owns the buffers and memory.
|
|
* pname:bindInfoCount is the number of elements in pname:pBindInfos.
|
|
* pname:pBindInfos is a pointer to an array of structures of type
|
|
slink:VkBindBufferMemoryInfoKHX, describing buffers and memory to bind.
|
|
|
|
On some implementations, it may: be more efficient to batch memory bindings
|
|
into a single command.
|
|
|
|
include::../validity/protos/vkBindBufferMemory2KHX.txt[]
|
|
|
|
// refBegin VkBindBufferMemoryInfoKHX Structure specifying how to bind a buffer to memory
|
|
|
|
sname:VkBindBufferMemoryInfoKHX contains members corresponding to the
|
|
parameters to flink:vkBindBufferMemory, as well as new members to control
|
|
peer memory bindings.
|
|
|
|
The sname:VkBindBufferMemoryInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkBindBufferMemoryInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:buffer is the buffer to be attached to memory.
|
|
* pname:memory is a sname:VkDeviceMemory object describing the device
|
|
memory to attach.
|
|
* pname:memoryOffset is the start offset of the region of pname:memory
|
|
which is to be bound to the buffer.
|
|
The number of bytes returned in the
|
|
sname:VkMemoryRequirements::pname:size member in pname:memory, starting
|
|
from pname:memoryOffset bytes, will be bound to the specified buffer.
|
|
* pname:deviceIndexCount is the number of elements in
|
|
pname:pDeviceIndices.
|
|
* pname:pDeviceIndices is a pointer to an array of device indices.
|
|
|
|
If pname:deviceIndexCount is greater than zero, then on device index [eq]#i#
|
|
the buffer is attached to the instance of memory on the physical device with
|
|
device index [eq]#pDeviceIndices[i]#.
|
|
|
|
If pname:deviceIndexCount is zero and the memory comes from a memory heap
|
|
with the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX bit set, then it is as
|
|
if pname:pDeviceIndices contains consecutive indices from zero to the number
|
|
of physical devices in the logical device, minus one.
|
|
In other words, by default each physical device attaches to its own instance
|
|
of the memory.
|
|
|
|
If pname:deviceIndexCount is zero and the memory comes from a memory heap
|
|
without the ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX bit set, then it is
|
|
as if pname:pDeviceIndices contains an array of zeros.
|
|
In other words, by default each physical device attaches to instance zero.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBindBufferMemoryInfoKHX-None-01040]] All valid usage rules from flink:vkBindBufferMemory apply to the
|
|
identically named members of sname:VkBindBufferMemoryInfoKHX
|
|
* [[VUID-VkBindBufferMemoryInfoKHX-deviceIndexCount-01041]] pname:deviceIndexCount must: either be zero or equal to the number of
|
|
physical devices in the logical device
|
|
* [[VUID-VkBindBufferMemoryInfoKHX-pDeviceIndices-01042]] All elements of pname:pDeviceIndices must: be valid device indices
|
|
* [[VUID-VkBindBufferMemoryInfoKHX-None-01043]] All instances of memory that are bound to must: have been allocated
|
|
****
|
|
|
|
include::../validity/structs/VkBindBufferMemoryInfoKHX.txt[]
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
// refBegin vkBindImageMemory Bind device memory to an image object
|
|
|
|
To attach memory to an image object, call:
|
|
|
|
include::../api/protos/vkBindImageMemory.txt[]
|
|
|
|
* pname:device is the logical device that owns the image and memory.
|
|
* pname:image is the image.
|
|
* pname:memory is the sname:VkDeviceMemory object describing the device
|
|
memory to attach.
|
|
* pname:memoryOffset is the start offset of the region of pname:memory
|
|
which is to be bound to the image.
|
|
The number of bytes returned in the
|
|
sname:VkMemoryRequirements::pname:size member in pname:memory, starting
|
|
from pname:memoryOffset bytes, will be bound to the specified image.
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
fname:vkBindImageMemory is equivalent to passing the same parameters through
|
|
slink:VkBindImageMemoryInfoKHX to flink:vkBindImageMemory2KHX, with
|
|
pname:deviceIndexCount and pname:SFRRectCount equal to zero.
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkBindImageMemory-image-01044]] pname:image must: not already be backed by a memory object
|
|
* [[VUID-vkBindImageMemory-image-01045]] pname:image must: not have been created with any sparse memory binding
|
|
flags
|
|
* [[VUID-vkBindImageMemory-memoryOffset-01046]] pname:memoryOffset must: be less than the size of pname:memory
|
|
* [[VUID-vkBindImageMemory-memory-01047]] pname:memory must: have been allocated using one of the memory types
|
|
allowed in the pname:memoryTypeBits member of the
|
|
sname:VkMemoryRequirements structure returned from a call to
|
|
fname:vkGetImageMemoryRequirements with pname:image
|
|
* [[VUID-vkBindImageMemory-memoryOffset-01048]] pname:memoryOffset must: be an integer multiple of the pname:alignment
|
|
member of the sname:VkMemoryRequirements structure returned from a call
|
|
to fname:vkGetImageMemoryRequirements with pname:image
|
|
* [[VUID-vkBindImageMemory-size-01049]] The pname:size member of the sname:VkMemoryRequirements structure
|
|
returned from a call to fname:vkGetImageMemoryRequirements with
|
|
pname:image must: be less than or equal to the size of pname:memory
|
|
minus pname:memoryOffset
|
|
ifdef::VK_NV_dedicated_allocation[]
|
|
* [[VUID-vkBindImageMemory-image-01050]] If pname:image was created with
|
|
sname:VkDedicatedAllocationImageCreateInfoNV::pname:dedicatedAllocation
|
|
equal to ename:VK_TRUE, pname:memory must: have been created with
|
|
sname:VkDedicatedAllocationMemoryAllocateInfoNV::pname:image equal to
|
|
pname:image and pname:memoryOffset must: be zero
|
|
* [[VUID-vkBindImageMemory-image-01051]] If pname:image was not created with
|
|
sname:VkDedicatedAllocationImageCreateInfoNV::pname:dedicatedAllocation
|
|
equal to ename:VK_TRUE, pname:memory must: not have been allocated
|
|
dedicated for a specific buffer or image
|
|
endif::VK_NV_dedicated_allocation[]
|
|
****
|
|
|
|
include::../validity/protos/vkBindImageMemory.txt[]
|
|
|
|
ifdef::VK_KHX_device_group[]
|
|
|
|
// refBegin vkBindImageMemory2KHX Bind device memory to image objects
|
|
|
|
To attach memory to image objects for one or more images at a time, call:
|
|
|
|
include::../api/protos/vkBindImageMemory2KHX.txt[]
|
|
|
|
* pname:device is the logical device that owns the images and memory.
|
|
* pname:bindInfoCount is the number of elements in pname:pBindInfos.
|
|
* pname:pBindInfos is a pointer to an array of structures of type
|
|
slink:VkBindImageMemoryInfoKHX, describing images and memory to bind.
|
|
|
|
On some implementations, it may: be more efficient to batch memory bindings
|
|
into a single command.
|
|
|
|
include::../validity/protos/vkBindImageMemory2KHX.txt[]
|
|
|
|
// refBegin VkBindImageMemoryInfoKHX Structure specifying how to bind an image to memory
|
|
|
|
sname:VkBindImageMemoryInfoKHX contains members corresponding to the
|
|
parameters to flink:vkBindImageMemory, as well as new members to control
|
|
peer memory bindings.
|
|
|
|
The sname:VkBindImageMemoryInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkBindImageMemoryInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:image is the image to be attached to memory.
|
|
* pname:memory is a sname:VkDeviceMemory object describing the device
|
|
memory to attach.
|
|
* pname:memoryOffset is the start offset of the region of pname:memory
|
|
which is to be bound to the image.
|
|
If pname:SFRRectCount is zero, the number of bytes returned in the
|
|
sname:VkMemoryRequirements::pname:size member in pname:memory, starting
|
|
from pname:memoryOffset bytes, will be bound to the specified image.
|
|
* pname:deviceIndexCount is the number of elements in
|
|
pname:pDeviceIndices.
|
|
* pname:pDeviceIndices is a pointer to an array of device indices.
|
|
* pname:SFRRectCount is the number of elements in pname:pSFRRects.
|
|
* pname:pSFRRects is a pointer to an array of rectangles describing which
|
|
regions of the image are attached to each instance of memory.
|
|
|
|
If pname:deviceIndexCount is greater than zero, then on device index [eq]#i#
|
|
the image is attached to the instance of memory on the physical device with
|
|
device index [eq]#pDeviceIndices[i]#.
|
|
|
|
Let [eq]#N# be the number of physical devices in the logical device.
|
|
If pname:SFRRectCount is greater than zero, then pname:pSFRRects is an array
|
|
of [eq]#N^2^# rectangles, where the image region specified by the rectangle
|
|
at element [eq]#i*N+j# in resource instance [eq]#i# is bound to memory
|
|
instance [eq]#j#.
|
|
The blocks of memory that are bound to each sparse image block region use an
|
|
offset in memory, relative to pname:memoryOffset, computed as if the whole
|
|
image were being bound to a contiguous range of memory.
|
|
In other words, horizontally adjacent image blocks use consecutive blocks of
|
|
memory, vertically adjacent image blocks are separated by the number of
|
|
bytes per block multiplied by the width in blocks of the image, and the
|
|
block at [eq]#(0,0)# corresponds to memory starting at pname:memoryOffset.
|
|
|
|
If pname:SFRRectCount and pname:deviceIndexCount are zero and the memory
|
|
comes from a memory heap with the
|
|
ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX bit set, then it is as if
|
|
pname:pDeviceIndices contains consecutive indices from zero to the number of
|
|
physical devices in the logical device, minus one.
|
|
In other words, by default each physical device attaches to its own instance
|
|
of the memory.
|
|
|
|
If pname:SFRRectCount and pname:deviceIndexCount are zero and the memory
|
|
comes from a memory heap without the
|
|
ename:VK_MEMORY_HEAP_MULTI_INSTANCE_BIT_KHX bit set, then it is as if
|
|
pname:pDeviceIndices contains an array of zeros.
|
|
In other words, by default each physical device attaches to instance zero.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBindImageMemoryInfoKHX-None-01052]] All valid usage rules from flink:vkBindImageMemory apply to the
|
|
identically named members of sname:VkBindImageMemoryInfoKHX
|
|
* [[VUID-VkBindImageMemoryInfoKHX-deviceIndexCount-01053]] At least one of pname:deviceIndexCount and pname:SFRRectCount must: be
|
|
zero.
|
|
* [[VUID-VkBindImageMemoryInfoKHX-deviceIndexCount-01054]] pname:deviceIndexCount must: either be zero or equal to the number of
|
|
physical devices in the logical device
|
|
* [[VUID-VkBindImageMemoryInfoKHX-pDeviceIndices-01055]] All elements of pname:pDeviceIndices must: be valid device indices.
|
|
* [[VUID-VkBindImageMemoryInfoKHX-SFRRectCount-01056]] pname:SFRRectCount must: either be zero or equal to the number of
|
|
physical devices in the logical device squared
|
|
* [[VUID-VkBindImageMemoryInfoKHX-SFRRectCount-01057]] If pname:SFRRectCount is not zero, then pname:image must: have been
|
|
created with the ename:VK_IMAGE_CREATE_BIND_SFR_BIT_KHX bit set.
|
|
* [[VUID-VkBindImageMemoryInfoKHX-pSFRRects-01058]] All elements of pname:pSFRRects must: be valid rectangles contained
|
|
within the dimensions of the image
|
|
* [[VUID-VkBindImageMemoryInfoKHX-pSFRRects-01059]] Elements of pname:pSFRRects that correspond to the same instance of the
|
|
image must: not overlap and their union must: cover the entire image.
|
|
* [[VUID-VkBindImageMemoryInfoKHX-pSFRRects-01060]] For each element of pname:pSFRRects:
|
|
** [[VUID-VkBindImageMemoryInfoKHX-offset-01061]] pname:offset.x must: be a multiple of the sparse image block width
|
|
(sname:VkSparseImageFormatProperties::pname:imageGranularity.width) of
|
|
all non-metadata aspects of the image
|
|
** [[VUID-VkBindImageMemoryInfoKHX-extent-01062]] pname:extent.width 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-VkBindImageMemoryInfoKHX-offset-01063]] pname:offset.y must: be a multiple of the sparse image block height
|
|
(sname:VkSparseImageFormatProperties::pname:imageGranularity.height) of
|
|
all non-metadata aspects of the image
|
|
** [[VUID-VkBindImageMemoryInfoKHX-extent-01064]] pname:extent.height 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 height of the
|
|
image subresource
|
|
* [[VUID-VkBindImageMemoryInfoKHX-None-01065]] All instances of memory that are bound must: have been allocated
|
|
* [[VUID-VkBindImageMemoryInfoKHX-image-01066]] If pname:image was created with a valid swapchain handle in
|
|
slink:VkImageSwapchainCreateInfoKHX::pname:swapchain, then the image
|
|
must: be bound to memory from that swapchain (using
|
|
slink:VkBindImageMemorySwapchainInfoKHX).
|
|
****
|
|
|
|
include::../validity/structs/VkBindImageMemoryInfoKHX.txt[]
|
|
|
|
// refBegin VkBindImageMemorySwapchainInfoKHX Structure specifying swapchain image memory to bind to
|
|
|
|
If the pname:pNext list of slink:VkBindImageMemoryInfoKHX includes a
|
|
sname:VkBindImageMemorySwapchainInfoKHX structure, then that structure
|
|
includes a swapchain handle and image index indicating that the image will
|
|
be bound to memory from that swapchain.
|
|
|
|
The sname:VkBindImageMemorySwapchainInfoKHX structure is defined as:
|
|
|
|
include::../api/structs/VkBindImageMemorySwapchainInfoKHX.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:swapchain is dlink:VK_NULL_HANDLE or a swapchain handle.
|
|
* pname:imageIndex is an image index within pname:swapchain.
|
|
|
|
If pname:swapchain is not `NULL`, the pname:swapchain and pname:imageIndex
|
|
are used to determine the memory that the image is bound to, instead of
|
|
pname:memory and pname:memoryOffset.
|
|
|
|
Memory can: be bound to a swapchain and use the pname:pDeviceIndices or
|
|
pname:pSFRRects members of slink:VkBindImageMemoryInfoKHX.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkBindImageMemorySwapchainInfoKHX-swapchain-01067]] At least one of pname:swapchain and
|
|
slink:VkBindImageMemoryInfoKHX::pname:memory must: be
|
|
dlink:VK_NULL_HANDLE
|
|
* [[VUID-VkBindImageMemorySwapchainInfoKHX-imageIndex-01068]] pname:imageIndex must: be less than the number of images in
|
|
pname:swapchain
|
|
****
|
|
|
|
include::../validity/structs/VkBindImageMemorySwapchainInfoKHX.txt[]
|
|
|
|
endif::VK_KHX_device_group[]
|
|
|
|
|
|
[[resources-bufferimagegranularity,Buffer-Image Granularity]]
|
|
.Buffer-Image Granularity
|
|
There is an implementation-dependent limit, pname:bufferImageGranularity,
|
|
which specifies a page-like granularity at which linear and non-linear
|
|
resources must: be placed in adjacent memory locations to avoid aliasing.
|
|
Two resources which do not satisfy this granularity requirement are said to
|
|
<<resources-memory-aliasing,alias>>.
|
|
pname:bufferImageGranularity is specified in bytes, and must: be a power of
|
|
two.
|
|
Implementations which do not require such an additional granularity may:
|
|
report a value of one.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Despite its name, pname:bufferImageGranularity is really a granularity
|
|
between "linear" and "non-linear" resources.
|
|
====
|
|
|
|
Given resourceA at the lower memory offset and resourceB at the higher
|
|
memory offset in the same sname:VkDeviceMemory object, where one resource
|
|
linear and the other is non-linear (as defined in the
|
|
<<glossary-linear-resource,glossary>>), and the following:
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
resourceA.end = resourceA.memoryOffset + resourceA.size - 1
|
|
resourceA.endPage = resourceA.end & ~(bufferImageGranularity-1)
|
|
resourceB.start = resourceB.memoryOffset
|
|
resourceB.startPage = resourceB.start & ~(bufferImageGranularity-1)
|
|
---------------------------------------------------
|
|
|
|
The following property must: hold:
|
|
|
|
[source,c]
|
|
---------------------------------------------------
|
|
resourceA.endPage < resourceB.startPage
|
|
---------------------------------------------------
|
|
|
|
That is, the end of the first resource (A) and the beginning of the second
|
|
resource (B) must: be on separate "`pages`" of size
|
|
pname:bufferImageGranularity.
|
|
pname:bufferImageGranularity may: be different than the physical page size
|
|
of the memory heap.
|
|
This restriction is only needed when a linear resource and a non-linear
|
|
resource are adjacent in memory and will be used simultaneously.
|
|
The memory ranges of adjacent resources can: be closer than
|
|
pname:bufferImageGranularity, provided they meet the pname:alignment
|
|
requirement for the objects in question.
|
|
|
|
Sparse block size in bytes and sparse image and buffer memory alignments
|
|
must: all be multiples of the pname:bufferImageGranularity.
|
|
Therefore, memory bound to sparse resources naturally satisfies the
|
|
pname:bufferImageGranularity.
|
|
|
|
[[resources-sharing]]
|
|
== Resource Sharing Mode
|
|
|
|
// refBegin VkSharingMode Buffer and image sharing modes
|
|
|
|
Buffer and image objects are created with a _sharing mode_ controlling how
|
|
they can: be accessed from queues.
|
|
The supported sharing modes are:
|
|
|
|
include::../api/enums/VkSharingMode.txt[]
|
|
|
|
* ename:VK_SHARING_MODE_EXCLUSIVE specifies that access to any range or
|
|
image subresource of the object will be exclusive to a single queue
|
|
family at a time.
|
|
* ename:VK_SHARING_MODE_CONCURRENT specifies that concurrent access to any
|
|
range or image subresource of the object from multiple queue families is
|
|
supported.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
ename:VK_SHARING_MODE_CONCURRENT may: result in lower performance access to
|
|
the buffer or image than ename:VK_SHARING_MODE_EXCLUSIVE.
|
|
====
|
|
|
|
Ranges of buffers and image subresources of image objects created using
|
|
ename:VK_SHARING_MODE_EXCLUSIVE must: only be accessed by queues in the same
|
|
queue family at any given time.
|
|
In order for a different queue family to be able to interpret the memory
|
|
contents of a range or image subresource, the application must: perform a
|
|
<<synchronization-queue-transfers,queue family ownership transfer>>.
|
|
|
|
Upon creation, resources using ename:VK_SHARING_MODE_EXCLUSIVE are not owned
|
|
by any queue family.
|
|
A buffer or image memory barrier is not required to acquire _ownership_ when
|
|
no queue family owns the resource - it is implicitly acquired upon first use
|
|
within a queue.
|
|
|
|
.Note
|
|
[NOTE]
|
|
====
|
|
Images still require a <<resources-image-layouts, layout transition>> from
|
|
ename:VK_IMAGE_LAYOUT_UNDEFINED or ename:VK_IMAGE_LAYOUT_PREINITIALIZED
|
|
before being used on the first queue.
|
|
====
|
|
|
|
A queue family can: take ownership of an image subresource or buffer range
|
|
of a resource created with ename:VK_SHARING_MODE_EXCLUSIVE, without an
|
|
ownership transfer, in the same way as for a resource that was just created;
|
|
however, taking ownership in this way has the effect that the contents of
|
|
the image subresource or buffer range are undefined.
|
|
|
|
Ranges of buffers and image subresources of image objects created using
|
|
ename:VK_SHARING_MODE_CONCURRENT must: only be accessed by queues from the
|
|
queue families specified through the pname:queueFamilyIndexCount and
|
|
pname:pQueueFamilyIndices members of the corresponding create info
|
|
structures.
|
|
|
|
// refEnd VkSharingMode
|
|
|
|
|
|
ifdef::VK_KHX_external_memory[]
|
|
|
|
[[resources-external-sharing]]
|
|
=== External Resource Sharing
|
|
|
|
Resources may only be accessed in the Vulkan instance that has exclusive
|
|
ownership of their underlying memory.
|
|
Only one Vulkan instance has exclusive ownership of a resource 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_KHX to represent the external
|
|
destination or source respectively.
|
|
|
|
Upon creation, memory objects shared between multiple Vulkan instances or
|
|
other APIs are not owned by any instance or API.
|
|
The first entity to access them implicitly acquires ownership.
|
|
Accessing a resource backed by memory that is owned by a particular instance
|
|
or API has the same semantics as accessing a ename:VK_SHARING_MODE_EXCLUSIVE
|
|
resource, with one exception: Implementations must: ensure layout
|
|
transitions performed on one member of a set of identical subresources of
|
|
identical images that alias the same range of an underlying memory object
|
|
affect the layout of all the subresources in the set.
|
|
|
|
endif::VK_KHX_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_KHX_external_memory[]
|
|
or via <<sparsememory-resource-binding,sparse memory bindings>>.
|
|
endif::VK_KHX_external_memory[]
|
|
ifdef::VK_KHX_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_KHX_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.
|
|
|
|
If either of two aliases is not host-accessible, then 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.
|
|
====
|