2140 lines
96 KiB
Plaintext
2140 lines
96 KiB
Plaintext
// Copyright (c) 2015-2016 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
|
|
****
|
|
* 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-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.
|
|
|
|
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
|
|
****
|
|
* pname:size must: be greater than `0`
|
|
* 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
|
|
* If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT,
|
|
pname:queueFamilyIndexCount must: be greater than `1`
|
|
* If the <<features-features-sparseBinding,sparse bindings>> feature is
|
|
not enabled, pname:flags must: not contain
|
|
ename:VK_BUFFER_CREATE_SPARSE_BINDING_BIT
|
|
* If the <<features-features-sparseResidencyBuffer,sparse buffer
|
|
residency>> feature is not enabled, pname:flags must: not contain
|
|
ename:VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT
|
|
* If the <<features-features-sparseResidencyAliased,sparse aliased
|
|
residency>> feature is not enabled, pname:flags must: not contain
|
|
ename:VK_BUFFER_CREATE_SPARSE_ALIASED_BIT
|
|
* 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
|
|
****
|
|
|
|
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
|
|
****
|
|
* 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[]
|
|
|
|
// 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
|
|
****
|
|
* All submitted commands that refer to pname:buffer, either directly or
|
|
via a sname:VkBufferView, must: have completed execution
|
|
* If sname:VkAllocationCallbacks were provided when pname:buffer was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* 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
|
|
****
|
|
* pname:offset must: be less than the size of pname:buffer
|
|
* pname:offset must: be a multiple of
|
|
sname:VkPhysicalDeviceLimits::pname:minTexelBufferOffsetAlignment
|
|
* If pname:range is not equal to ename:VK_WHOLE_SIZE:
|
|
** pname:range must: be greater than `0`
|
|
** pname:range must: be a multiple of the element size of pname:format
|
|
** pname:range divided by the element size of pname:format, must: be
|
|
less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxTexelBufferElements
|
|
** the sum of pname:offset and pname:range must: be less than or equal to
|
|
the size of pname:buffer
|
|
* 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
|
|
* 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
|
|
* 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
|
|
****
|
|
|
|
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
|
|
****
|
|
* All submitted commands that refer to pname:bufferView must: have
|
|
completed execution
|
|
* If sname:VkAllocationCallbacks were provided when pname:bufferView was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* 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
|
|
****
|
|
* 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>>.
|
|
pname:initialLayout must: be ename:VK_IMAGE_LAYOUT_UNDEFINED or
|
|
ename:VK_IMAGE_LAYOUT_PREINITIALIZED.
|
|
|
|
Valid limits for the image pname:extent, pname:mipLevels, pname:arrayLayers
|
|
and pname:samples members are queried with the
|
|
flink:vkGetPhysicalDeviceImageFormatProperties command.
|
|
|
|
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 determine the specific capabilities of an implementation, query the valid
|
|
pname:usage bits by calling flink:vkGetPhysicalDeviceFormatProperties and
|
|
the valid limits for pname:mipLevels and pname:arrayLayers by calling
|
|
flink:vkGetPhysicalDeviceImageFormatProperties.
|
|
|
|
.Valid Usage
|
|
****
|
|
* 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
|
|
* If pname:sharingMode is ename:VK_SHARING_MODE_CONCURRENT,
|
|
pname:queueFamilyIndexCount must: be greater than `1`
|
|
* pname:format must: not be ename:VK_FORMAT_UNDEFINED
|
|
* The pname:width, pname:height, and pname:depth members of pname:extent
|
|
must: all be greater than `0`
|
|
* pname:mipLevels must: be greater than `0`
|
|
* pname:arrayLayers must: be greater than `0`
|
|
* If pname:flags contains ename:VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT,
|
|
pname:imageType must be ename:VK_IMAGE_TYPE_2D
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* If pname:imageType is ename:VK_IMAGE_TYPE_1D, both pname:extent.height
|
|
and pname:extent.depth must: be `1`
|
|
* If pname:imageType is ename:VK_IMAGE_TYPE_2D, pname:extent.depth must:
|
|
be `1`
|
|
* 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#.
|
|
* 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)
|
|
* 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)
|
|
* 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`
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* If the <<features-features-textureCompressionETC2,ETC2 texture
|
|
compression>> feature is not enabled, pname:format must: not be
|
|
ename:VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK,
|
|
ename:VK_FORMAT_EAC_R11_UNORM_BLOCK,
|
|
ename:VK_FORMAT_EAC_R11_SNORM_BLOCK,
|
|
ename:VK_FORMAT_EAC_R11G11_UNORM_BLOCK, or
|
|
ename:VK_FORMAT_EAC_R11G11_SNORM_BLOCK
|
|
* If the <<features-features-textureCompressionASTC_LDR,ASTC LDR texture
|
|
compression>> feature is not enabled, pname:format must: not be
|
|
ename:VK_FORMAT_ASTC_4x4_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_4x4_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_5x4_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_5x4_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_5x5_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_5x5_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_6x5_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_6x5_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_6x6_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_6x6_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x5_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x5_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x6_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x6_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x8_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x8_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x5_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x5_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x6_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x6_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x8_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x8_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x10_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x10_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_12x10_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_12x10_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_12x12_UNORM_BLOCK, or
|
|
ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK
|
|
* If the <<features-features-textureCompressionBC,BC texture compression>>
|
|
feature is not enabled, pname:format must: not be
|
|
ename:VK_FORMAT_BC1_RGB_UNORM_BLOCK, ename:VK_FORMAT_BC1_RGB_SRGB_BLOCK,
|
|
ename:VK_FORMAT_BC1_RGBA_UNORM_BLOCK,
|
|
ename:VK_FORMAT_BC1_RGBA_SRGB_BLOCK, ename:VK_FORMAT_BC2_UNORM_BLOCK,
|
|
ename:VK_FORMAT_BC2_SRGB_BLOCK, ename:VK_FORMAT_BC3_UNORM_BLOCK,
|
|
ename:VK_FORMAT_BC3_SRGB_BLOCK, ename:VK_FORMAT_BC4_UNORM_BLOCK,
|
|
ename:VK_FORMAT_BC4_SNORM_BLOCK, ename:VK_FORMAT_BC5_UNORM_BLOCK,
|
|
ename:VK_FORMAT_BC5_SNORM_BLOCK, ename:VK_FORMAT_BC6H_UFLOAT_BLOCK,
|
|
ename:VK_FORMAT_BC6H_SFLOAT_BLOCK, ename:VK_FORMAT_BC7_UNORM_BLOCK, or
|
|
ename:VK_FORMAT_BC7_SRGB_BLOCK
|
|
* 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
|
|
* If the <<features-features-sparseBinding,sparse bindings>> feature is
|
|
not enabled, pname:flags must: not contain
|
|
ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
****
|
|
|
|
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
|
|
****
|
|
* 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_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.
|
|
The types must: all be compatible with each other and the other image
|
|
creation parameters, as reported by
|
|
flink:vkGetPhysicalDeviceExternalImageFormatPropertiesNV.
|
|
|
|
include::../validity/structs/VkExternalMemoryImageCreateInfoNV.txt[]
|
|
|
|
endif::VK_NV_external_memory[]
|
|
|
|
// 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.
|
|
|
|
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
|
|
****
|
|
* pname:image must: have been created with pname:tiling equal to
|
|
ename:VK_IMAGE_TILING_LINEAR
|
|
* 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
|
|
****
|
|
* pname:mipLevel must: be less than the pname:mipLevels specified in
|
|
slink:VkImageCreateInfo when the image was created
|
|
* 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
|
|
****
|
|
* All submitted commands that refer to pname:image, either directly or via
|
|
a sname:VkImageView, must: have completed execution
|
|
* If sname:VkAllocationCallbacks were provided when pname:image was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* 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-barrier>>), 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-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 swapchain 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.
|
|
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 +
|
|
where ci is the slink:VkImageCreateInfo used to create pname:image.
|
|
| pname:baseArrayLayer and pname:layerCount 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_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_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_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_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_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_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_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_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_VIEW_TYPE_3D +
|
|
pname:baseArrayLayer = 0 +
|
|
pname:layerCount = 1
|
|
|====
|
|
|
|
.Valid Usage
|
|
****
|
|
* 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
|
|
* If the <<features-features-imageCubeArray,image cubemap arrays>> feature
|
|
is not enabled, pname:viewType must: not be
|
|
ename:VK_IMAGE_VIEW_TYPE_CUBE_ARRAY
|
|
* If the <<features-features-textureCompressionETC2,ETC2 texture
|
|
compression>> feature is not enabled, pname:format must: not be
|
|
ename:VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ETC2_R8G8B8_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ETC2_R8G8B8A1_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ETC2_R8G8B8A1_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ETC2_R8G8B8A8_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ETC2_R8G8B8A8_SRGB_BLOCK,
|
|
ename:VK_FORMAT_EAC_R11_UNORM_BLOCK,
|
|
ename:VK_FORMAT_EAC_R11_SNORM_BLOCK,
|
|
ename:VK_FORMAT_EAC_R11G11_UNORM_BLOCK, or
|
|
ename:VK_FORMAT_EAC_R11G11_SNORM_BLOCK
|
|
* If the <<features-features-textureCompressionASTC_LDR,ASTC LDR texture
|
|
compression>> feature is not enabled, pname:format must: not be
|
|
ename:VK_FORMAT_ASTC_4x4_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_4x4_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_5x4_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_5x4_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_5x5_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_5x5_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_6x5_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_6x5_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_6x6_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_6x6_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x5_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x5_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x6_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x6_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x8_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_8x8_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x5_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x5_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x6_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x6_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x8_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x8_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x10_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_10x10_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_12x10_UNORM_BLOCK,
|
|
ename:VK_FORMAT_ASTC_12x10_SRGB_BLOCK,
|
|
ename:VK_FORMAT_ASTC_12x12_UNORM_BLOCK, or
|
|
ename:VK_FORMAT_ASTC_12x12_SRGB_BLOCK
|
|
* If the <<features-features-textureCompressionBC,BC texture compression>>
|
|
feature is not enabled, pname:format must: not be
|
|
ename:VK_FORMAT_BC1_RGB_UNORM_BLOCK, ename:VK_FORMAT_BC1_RGB_SRGB_BLOCK,
|
|
ename:VK_FORMAT_BC1_RGBA_UNORM_BLOCK,
|
|
ename:VK_FORMAT_BC1_RGBA_SRGB_BLOCK, ename:VK_FORMAT_BC2_UNORM_BLOCK,
|
|
ename:VK_FORMAT_BC2_SRGB_BLOCK, ename:VK_FORMAT_BC3_UNORM_BLOCK,
|
|
ename:VK_FORMAT_BC3_SRGB_BLOCK, ename:VK_FORMAT_BC4_UNORM_BLOCK,
|
|
ename:VK_FORMAT_BC4_SNORM_BLOCK, ename:VK_FORMAT_BC5_UNORM_BLOCK,
|
|
ename:VK_FORMAT_BC5_SNORM_BLOCK, ename:VK_FORMAT_BC6H_UFLOAT_BLOCK,
|
|
ename:VK_FORMAT_BC6H_SFLOAT_BLOCK, ename:VK_FORMAT_BC7_UNORM_BLOCK, or
|
|
ename:VK_FORMAT_BC7_SRGB_BLOCK
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* pname:subresourceRange must: be a valid image subresource range for
|
|
pname:image (see <<resources-image-views>>)
|
|
* 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>>
|
|
* 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
|
|
* 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
|
|
****
|
|
* If pname:levelCount is not ename:VK_REMAINING_MIP_LEVELS,
|
|
[eq]#(pname:baseMipLevel + pname:levelCount)# must: be less than or
|
|
equal to the pname:mipLevels specified in slink:VkImageCreateInfo when
|
|
the image was created
|
|
* If pname:layerCount is not ename:VK_REMAINING_ARRAY_LAYERS,
|
|
[eq]#(pname:baseArrayLayer + pname:layerCount)# must: be less than or
|
|
equal to the pname:arrayLayers specified in slink:VkImageCreateInfo when
|
|
the image was created
|
|
****
|
|
|
|
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
|
|
****
|
|
* All submitted commands that refer to pname:imageView must: have
|
|
completed execution
|
|
* If sname:VkAllocationCallbacks were provided when pname:imageView was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* 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.
|
|
|
|
// 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 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.
|
|
* The pname:memoryTypeBits member is identical for all sname:VkImage
|
|
objects created with the same combination of values for the pname:tiling
|
|
member and the ename:VK_IMAGE_CREATE_SPARSE_BINDING_BIT bit of the
|
|
pname:flags member 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.
|
|
* pname:memory is a sname:VkDeviceMemory object describing the device
|
|
memory to attach.
|
|
* pname:memoryOffset is the start offset of the region of pname:memory
|
|
which is to be bound to the buffer.
|
|
The number of bytes returned in the
|
|
sname:VkMemoryRequirements::pname:size member in pname:memory, starting
|
|
from pname:memoryOffset bytes, will be bound to the specified buffer.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:buffer must: not already be backed by a memory object
|
|
* pname:buffer must: not have been created with any sparse memory binding
|
|
flags
|
|
* pname:memoryOffset must: be less than the size of pname:memory
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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
|
|
* 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[]
|
|
* 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
|
|
* 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[]
|
|
|
|
// 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 a sname:VkDeviceMemory object describing the device
|
|
memory to attach.
|
|
* pname:memoryOffset is the start offset of the region of pname:memory
|
|
which is to be bound to the image.
|
|
The number of bytes returned in the
|
|
sname:VkMemoryRequirements::pname:size member in pname:memory, starting
|
|
from pname:memoryOffset bytes, will be bound to the specified image.
|
|
|
|
.Valid Usage
|
|
****
|
|
* pname:image must: not already be backed by a memory object
|
|
* pname:image must: not have been created with any sparse memory binding
|
|
flags
|
|
* pname:memoryOffset must: be less than the size of pname:memory
|
|
* 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
|
|
* 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
|
|
* 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[]
|
|
* 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
|
|
* 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[]
|
|
|
|
[[resources-bufferimagegranularity,Buffer-Image Granularity]]
|
|
.Buffer-Image Granularity
|
|
There is an implementation-dependent limit, pname:bufferImageGranularity,
|
|
which specifies a page-like granularity at which buffer, linear image and
|
|
optimal image 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>>.
|
|
Linear image resource are images created with ename:VK_IMAGE_TILING_LINEAR
|
|
and optimal image resources are those created with
|
|
ename:VK_IMAGE_TILING_OPTIMAL.
|
|
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
|
|
====
|
|
pname:bufferImageGranularity is really a granularity between "linear"
|
|
resources, including buffers and images with linear tiling, vs.
|
|
"optimal" resources, i.e. images with optimal tiling.
|
|
It would have been better named "linearOptimalGranularity".
|
|
====
|
|
|
|
Given resourceA at the lower memory offset and resourceB at the higher
|
|
memory offset in the same sname:VkDeviceMemory object, where one of the
|
|
resources is a buffer or a linear image and the other is an optimal image,
|
|
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 buffer or a linear image is at
|
|
adjacent memory location with an optimal image and both will be used
|
|
simultaneously.
|
|
Adjacent buffers' or adjacent images' memory ranges 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: transfer
|
|
exclusive ownership of the range or image subresource between the source and
|
|
destination queue families with the following sequence of operations:
|
|
|
|
. Release exclusive ownership from the source queue family to the
|
|
destination queue family.
|
|
. Use semaphores to ensure proper execution control for the ownership
|
|
transfer.
|
|
. Acquire exclusive ownership for the destination queue family from the
|
|
source queue family.
|
|
|
|
To release exclusive ownership of a range of a buffer or image subresource
|
|
of an image object, the application must: execute a buffer or image memory
|
|
barrier, respectively (see slink:VkBufferMemoryBarrier and
|
|
slink:VkImageMemoryBarrier) on a queue from the source queue family.
|
|
The pname:srcQueueFamilyIndex parameter of the barrier must: be set to the
|
|
source queue family index, and the pname:dstQueueFamilyIndex parameter to
|
|
the destination queue family index.
|
|
|
|
To acquire exclusive ownership, the application must: execute the same
|
|
buffer or image memory barrier (i.e. an identically defined instance of the
|
|
slink:VkBufferMemoryBarrier or slink:VkImageMemoryBarrier structure that was
|
|
used for the exclusive ownership release) on a queue from the destination
|
|
queue family.
|
|
|
|
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.
|
|
However, 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.
|
|
This layout transition can: either be accomplished by an image memory
|
|
barrier or by use in a render pass instance.
|
|
|
|
Once a queue family has used a range or image subresource of an
|
|
ename:VK_SHARING_MODE_EXCLUSIVE resource, its contents are undefined to
|
|
other queue families unless ownership is transferred.
|
|
The contents may: also become undefined for other reasons, e.g. as a result
|
|
of writes to an image subresource that aliases the same memory.
|
|
A queue family can: take ownership of a range or image subresource without
|
|
an ownership transfer in the same way as for a resource that was just
|
|
created, however doing so means any contents written by other queue families
|
|
or via incompatible aliases are undefined.
|
|
|
|
// refEnd VkSharingMode
|
|
|
|
|
|
[[resources-memory-aliasing]]
|
|
== Memory Aliasing
|
|
|
|
A range of a sname:VkDeviceMemory allocation is _aliased_ if it is bound to
|
|
multiple resources simultaneously, via flink:vkBindImageMemory,
|
|
flink:vkBindBufferMemory, or via <<sparsememory-resource-binding,sparse
|
|
memory bindings>>.
|
|
A memory range aliased between two images or two buffers is defined to be
|
|
the intersection of the memory ranges bound to the two resources.
|
|
A memory range aliased between two resources where one is a buffer or a
|
|
linear image, and the other is an optimal image, is defined to be the
|
|
intersection of the memory ranges bound to the two resources, where each
|
|
range is first padded to be aligned to the pname:bufferImageGranularity.
|
|
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.
|
|
Opaque 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 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.
|
|
====
|