12. Resource Creation
Vulkan supports two primary resource types: buffers and images. Resources are views of memory with associated formatting and dimensionality. Buffers provide access to raw arrays of bytes, whereas images can be multidimensional and may have associated metadata.
12.1. Buffers
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 certain commands, or by directly specifying them as parameters to certain commands.
Buffers are represented by VkBuffer
handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBuffer)
To create buffers, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateBuffer(
VkDevice device,
const VkBufferCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkBuffer* pBuffer);
-
device
is the logical device that creates the buffer object. -
pCreateInfo
is a pointer to a VkBufferCreateInfo structure containing parameters affecting creation of the buffer. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pBuffer
is a pointer to a VkBuffer handle in which the resulting buffer object is returned.
The VkBufferCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBufferCreateInfo {
VkStructureType sType;
const void* pNext;
VkBufferCreateFlags flags;
VkDeviceSize size;
VkBufferUsageFlags usage;
VkSharingMode sharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t* pQueueFamilyIndices;
} VkBufferCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkBufferCreateFlagBits specifying additional parameters of the buffer. -
size
is the size in bytes of the buffer to be created. -
usage
is a bitmask of VkBufferUsageFlagBits specifying allowed usages of the buffer. -
sharingMode
is a VkSharingMode value specifying the sharing mode of the buffer when it will be accessed by multiple queue families. -
queueFamilyIndexCount
is the number of entries in thepQueueFamilyIndices
array. -
pQueueFamilyIndices
is a pointer to an array of queue families that will access this buffer. It is ignored ifsharingMode
is notVK_SHARING_MODE_CONCURRENT
.
Bits which can be set in VkBufferCreateInfo::usage
, specifying
usage behavior of a buffer, are:
// Provided by VK_VERSION_1_0
typedef enum VkBufferUsageFlagBits {
VK_BUFFER_USAGE_TRANSFER_SRC_BIT = 0x00000001,
VK_BUFFER_USAGE_TRANSFER_DST_BIT = 0x00000002,
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT = 0x00000004,
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT = 0x00000008,
VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT = 0x00000010,
VK_BUFFER_USAGE_STORAGE_BUFFER_BIT = 0x00000020,
VK_BUFFER_USAGE_INDEX_BUFFER_BIT = 0x00000040,
VK_BUFFER_USAGE_VERTEX_BUFFER_BIT = 0x00000080,
VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT = 0x00000100,
// Provided by VK_VERSION_1_2
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT = 0x00020000,
} VkBufferUsageFlagBits;
-
VK_BUFFER_USAGE_TRANSFER_SRC_BIT
specifies that the buffer can be used as the source of a transfer command (see the definition ofVK_PIPELINE_STAGE_TRANSFER_BIT
). -
VK_BUFFER_USAGE_TRANSFER_DST_BIT
specifies that the buffer can be used as the destination of a transfer command. -
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT
specifies that the buffer can be used to create aVkBufferView
suitable for occupying aVkDescriptorSet
slot of typeVK_DESCRIPTOR_TYPE_UNIFORM_TEXEL_BUFFER
. -
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT
specifies that the buffer can be used to create aVkBufferView
suitable for occupying aVkDescriptorSet
slot of typeVK_DESCRIPTOR_TYPE_STORAGE_TEXEL_BUFFER
. -
VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT
specifies that the buffer can be used in aVkDescriptorBufferInfo
suitable for occupying aVkDescriptorSet
slot either of typeVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER
orVK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC
. -
VK_BUFFER_USAGE_STORAGE_BUFFER_BIT
specifies that the buffer can be used in aVkDescriptorBufferInfo
suitable for occupying aVkDescriptorSet
slot either of typeVK_DESCRIPTOR_TYPE_STORAGE_BUFFER
orVK_DESCRIPTOR_TYPE_STORAGE_BUFFER_DYNAMIC
. -
VK_BUFFER_USAGE_INDEX_BUFFER_BIT
specifies that the buffer is suitable for passing as thebuffer
parameter to vkCmdBindIndexBuffer. -
VK_BUFFER_USAGE_VERTEX_BUFFER_BIT
specifies that the buffer is suitable for passing as an element of thepBuffers
array to vkCmdBindVertexBuffers. -
VK_BUFFER_USAGE_INDIRECT_BUFFER_BIT
specifies that the buffer is suitable for passing as thebuffer
parameter to vkCmdDrawIndirect, vkCmdDrawIndexedIndirect, or vkCmdDispatchIndirect. -
VK_BUFFER_USAGE_SHADER_DEVICE_ADDRESS_BIT
specifies that the buffer can be used to retrieve a buffer device address via vkGetBufferDeviceAddress and use that address to access the buffer’s memory from a shader.
// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferUsageFlags;
VkBufferUsageFlags
is a bitmask type for setting a mask of zero or
more VkBufferUsageFlagBits.
Bits which can be set in VkBufferCreateInfo::flags
, specifying
additional parameters of a buffer, are:
// Provided by VK_VERSION_1_0
typedef enum VkBufferCreateFlagBits {
VK_BUFFER_CREATE_SPARSE_BINDING_BIT = 0x00000001,
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
VK_BUFFER_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
// Provided by VK_VERSION_1_1
VK_BUFFER_CREATE_PROTECTED_BIT = 0x00000008,
// Provided by VK_VERSION_1_2
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT = 0x00000010,
} VkBufferCreateFlagBits;
-
VK_BUFFER_CREATE_SPARSE_BINDING_BIT
specifies that the buffer will be backed using sparse memory binding. -
VK_BUFFER_CREATE_SPARSE_RESIDENCY_BIT
specifies that the buffer can be partially backed using sparse memory binding. Buffers created with this flag must also be created with theVK_BUFFER_CREATE_SPARSE_BINDING_BIT
flag. -
VK_BUFFER_CREATE_SPARSE_ALIASED_BIT
specifies that the buffer will be backed using sparse memory binding with memory ranges that might also simultaneously be backing another buffer (or another portion of the same buffer). Buffers created with this flag must also be created with theVK_BUFFER_CREATE_SPARSE_BINDING_BIT
flag. -
VK_BUFFER_CREATE_PROTECTED_BIT
specifies that the buffer is a protected buffer. -
VK_BUFFER_CREATE_DEVICE_ADDRESS_CAPTURE_REPLAY_BIT
specifies that the buffer’s address can be saved and reused on a subsequent run (e.g. for trace capture and replay), see VkBufferOpaqueCaptureAddressCreateInfo for more detail.
See Sparse Resource Features and Physical Device Features for details of the sparse memory features supported on a device.
// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferCreateFlags;
VkBufferCreateFlags
is a bitmask type for setting a mask of zero or
more VkBufferCreateFlagBits.
To define a set of external memory handle types that may be used as backing
store for a buffer, add a VkExternalMemoryBufferCreateInfo structure
to the pNext
chain of the VkBufferCreateInfo structure.
The VkExternalMemoryBufferCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryBufferCreateInfo {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlags handleTypes;
} VkExternalMemoryBufferCreateInfo;
Note
A |
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
handleTypes
is zero or a bitmask of VkExternalMemoryHandleTypeFlagBits specifying one or more external memory handle types.
To request a specific device address for a buffer, add a
VkBufferOpaqueCaptureAddressCreateInfo structure to the pNext
chain of the VkBufferCreateInfo structure.
The VkBufferOpaqueCaptureAddressCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkBufferOpaqueCaptureAddressCreateInfo {
VkStructureType sType;
const void* pNext;
uint64_t opaqueCaptureAddress;
} VkBufferOpaqueCaptureAddressCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
opaqueCaptureAddress
is the opaque capture address requested for the buffer.
If opaqueCaptureAddress
is zero, no specific address is requested.
If opaqueCaptureAddress
is not zero, then it should be an address
retrieved from vkGetBufferOpaqueCaptureAddress for an identically
created buffer on the same implementation.
If this structure is not present, it is as if opaqueCaptureAddress
is
zero.
Apps should avoid creating buffers with app-provided addresses and
implementation-provided addresses in the same process, to reduce the
likelihood of VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS
errors.
Note
The expected usage for this is that a trace capture/replay tool will add the
Implementations are expected to separate such buffers in the GPU address
space so normal allocations will avoid using these addresses.
Apps/tools should avoid mixing app-provided and implementation-provided
addresses for buffers created with
|
To destroy a buffer, call:
// Provided by VK_VERSION_1_0
void vkDestroyBuffer(
VkDevice device,
VkBuffer buffer,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that destroys the buffer. -
buffer
is the buffer to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
12.2. Buffer Views
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 using image operations. In order to create a valid buffer view, the buffer must have been created with at least one of the following usage flags:
-
VK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT
-
VK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT
Buffer views are represented by VkBufferView
handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkBufferView)
To create a buffer view, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateBufferView(
VkDevice device,
const VkBufferViewCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkBufferView* pView);
-
device
is the logical device that creates the buffer view. -
pCreateInfo
is a pointer to a VkBufferViewCreateInfo structure containing parameters to be used to create the buffer view. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pView
is a pointer to a VkBufferView handle in which the resulting buffer view object is returned.
The VkBufferViewCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkBufferViewCreateInfo {
VkStructureType sType;
const void* pNext;
VkBufferViewCreateFlags flags;
VkBuffer buffer;
VkFormat format;
VkDeviceSize offset;
VkDeviceSize range;
} VkBufferViewCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
buffer
is a VkBuffer on which the view will be created. -
format
is a VkFormat describing the format of the data elements in the buffer. -
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. -
range
is a size in bytes of the buffer view. Ifrange
is equal toVK_WHOLE_SIZE
, the range fromoffset
to the end of the buffer is used. IfVK_WHOLE_SIZE
is used and the remaining size of the buffer is not a multiple of the texel block size offormat
, the nearest smaller multiple is used.
// Provided by VK_VERSION_1_0
typedef VkFlags VkBufferViewCreateFlags;
VkBufferViewCreateFlags
is a bitmask type for setting a mask, but is
currently reserved for future use.
To destroy a buffer view, call:
// Provided by VK_VERSION_1_0
void vkDestroyBufferView(
VkDevice device,
VkBufferView bufferView,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that destroys the buffer view. -
bufferView
is the buffer view to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
12.2.1. Buffer View Format Features
Valid uses of a VkBufferView may depend on the buffer view’s format features, defined below. Such constraints are documented in the affected valid usage statement.
-
If Vulkan 1.3 is supported or the
extension is supported, then the buffer view’s set of format features is the value of VkFormatProperties3::VK_KHR_format_feature_flags2
bufferFeatures
found by calling vkGetPhysicalDeviceFormatProperties2 on the sameformat
as VkBufferViewCreateInfo::format
.
12.3. Images
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 VkImage
handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImage)
To create images, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateImage(
VkDevice device,
const VkImageCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkImage* pImage);
-
device
is the logical device that creates the image. -
pCreateInfo
is a pointer to a VkImageCreateInfo structure containing parameters to be used to create the image. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pImage
is a pointer to a VkImage handle in which the resulting image object is returned.
The VkImageCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageCreateInfo {
VkStructureType sType;
const void* pNext;
VkImageCreateFlags flags;
VkImageType imageType;
VkFormat format;
VkExtent3D extent;
uint32_t mipLevels;
uint32_t arrayLayers;
VkSampleCountFlagBits samples;
VkImageTiling tiling;
VkImageUsageFlags usage;
VkSharingMode sharingMode;
uint32_t queueFamilyIndexCount;
const uint32_t* pQueueFamilyIndices;
VkImageLayout initialLayout;
} VkImageCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkImageCreateFlagBits describing additional parameters of the image. -
imageType
is a VkImageType value specifying the basic dimensionality of the image. Layers in array textures do not count as a dimension for the purposes of the image type. -
format
is a VkFormat describing the format and type of the texel blocks that will be contained in the image. -
extent
is a VkExtent3D describing the number of data elements in each dimension of the base level. -
mipLevels
describes the number of levels of detail available for minified sampling of the image. -
arrayLayers
is the number of layers in the image. -
samples
is a VkSampleCountFlagBits value specifying the number of samples per texel. -
tiling
is a VkImageTiling value specifying the tiling arrangement of the texel blocks in memory. -
usage
is a bitmask of VkImageUsageFlagBits describing the intended usage of the image. -
sharingMode
is a VkSharingMode value specifying the sharing mode of the image when it will be accessed by multiple queue families. -
queueFamilyIndexCount
is the number of entries in thepQueueFamilyIndices
array. -
pQueueFamilyIndices
is a pointer to an array of queue families that will access this image. It is ignored ifsharingMode
is notVK_SHARING_MODE_CONCURRENT
. -
initialLayout
is a VkImageLayout value specifying the initial VkImageLayout of all image subresources of the image. See Image Layouts.
Images created with tiling
equal to VK_IMAGE_TILING_LINEAR
have
further restrictions on their limits and capabilities compared to images
created with tiling
equal to VK_IMAGE_TILING_OPTIMAL
.
Creation of images with tiling VK_IMAGE_TILING_LINEAR
may not be
supported unless other parameters meet all of the constraints:
-
imageType
isVK_IMAGE_TYPE_2D
-
format
is not a depth/stencil format -
mipLevels
is 1 -
arrayLayers
is 1 -
samples
isVK_SAMPLE_COUNT_1_BIT
-
usage
only includesVK_IMAGE_USAGE_TRANSFER_SRC_BIT
and/orVK_IMAGE_USAGE_TRANSFER_DST_BIT
Images created with one of the formats that require a sampler Y′CBCR conversion, have further restrictions on their limits and capabilities compared to images created with other formats. Creation of images with a format requiring Y′CBCR conversion may not be supported unless other parameters meet all of the constraints:
-
imageType
isVK_IMAGE_TYPE_2D
-
mipLevels
is 1 -
arrayLayers
is 1, unless otherwise indicated by VkImageFormatProperties::maxArrayLayers
, as returned by vkGetPhysicalDeviceImageFormatProperties -
samples
isVK_SAMPLE_COUNT_1_BIT
Implementations may support additional limits and capabilities beyond those listed above.
To determine the set of valid usage
bits for a given format, call
vkGetPhysicalDeviceFormatProperties.
If the size of the resultant image would exceed maxResourceSize
, then
vkCreateImage must fail and return
VK_ERROR_OUT_OF_DEVICE_MEMORY
.
This failure may occur even when all image creation parameters satisfy
their valid usage requirements.
Note
For images created without For images created with |
The VkImageStencilUsageCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkImageStencilUsageCreateInfo {
VkStructureType sType;
const void* pNext;
VkImageUsageFlags stencilUsage;
} VkImageStencilUsageCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
stencilUsage
is a bitmask of VkImageUsageFlagBits describing the intended usage of the stencil aspect of the image.
If the pNext
chain of VkImageCreateInfo includes a
VkImageStencilUsageCreateInfo
structure, then that structure includes
the usage flags specific to the stencil aspect of the image for an image
with a depth-stencil format.
This structure specifies image usages which only apply to the stencil aspect
of a depth/stencil format image.
When this structure is included in the pNext
chain of
VkImageCreateInfo, the stencil aspect of the image must only be used
as specified by stencilUsage
.
When this structure is not included in the pNext
chain of
VkImageCreateInfo, the stencil aspect of an image must only be used
as specified by VkImageCreateInfo::usage
.
Use of other aspects of an image are unaffected by this structure.
This structure can also be included in the pNext
chain of
VkPhysicalDeviceImageFormatInfo2 to query additional capabilities
specific to image creation parameter combinations including a separate set
of usage flags for the stencil aspect of the image using
vkGetPhysicalDeviceImageFormatProperties2.
When this structure is not included in the pNext
chain of
VkPhysicalDeviceImageFormatInfo2
then the implicit value of
stencilUsage
matches that of
VkPhysicalDeviceImageFormatInfo2
::usage
.
To define a set of external memory handle types that may be used as backing
store for an image, add a VkExternalMemoryImageCreateInfo structure to
the pNext
chain of the VkImageCreateInfo structure.
The VkExternalMemoryImageCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkExternalMemoryImageCreateInfo {
VkStructureType sType;
const void* pNext;
VkExternalMemoryHandleTypeFlags handleTypes;
} VkExternalMemoryImageCreateInfo;
Note
A |
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
handleTypes
is zero or a bitmask of VkExternalMemoryHandleTypeFlagBits specifying one or more external memory handle types.
If the pNext
chain of VkImageCreateInfo includes a
VkImageFormatListCreateInfo
structure, then that structure contains a
list of all formats that can be used when creating views of this image.
The VkImageFormatListCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_2
typedef struct VkImageFormatListCreateInfo {
VkStructureType sType;
const void* pNext;
uint32_t viewFormatCount;
const VkFormat* pViewFormats;
} VkImageFormatListCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
viewFormatCount
is the number of entries in thepViewFormats
array. -
pViewFormats
is a pointer to an array of VkFormat values specifying all formats which can be used when creating views of this image.
If viewFormatCount
is zero, pViewFormats
is ignored and the
image is created as if the VkImageFormatListCreateInfo
structure were
not included in the pNext
chain of VkImageCreateInfo.
Bits which can be set in
-
VkImageViewUsageCreateInfo::
usage
-
VkImageStencilUsageCreateInfo::
stencilUsage
-
VkImageCreateInfo::
usage
specify intended usage of an image, and are:
// Provided by VK_VERSION_1_0
typedef enum VkImageUsageFlagBits {
VK_IMAGE_USAGE_TRANSFER_SRC_BIT = 0x00000001,
VK_IMAGE_USAGE_TRANSFER_DST_BIT = 0x00000002,
VK_IMAGE_USAGE_SAMPLED_BIT = 0x00000004,
VK_IMAGE_USAGE_STORAGE_BIT = 0x00000008,
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT = 0x00000010,
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT = 0x00000020,
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT = 0x00000040,
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT = 0x00000080,
} VkImageUsageFlagBits;
-
VK_IMAGE_USAGE_TRANSFER_SRC_BIT
specifies that the image can be used as the source of a transfer command. -
VK_IMAGE_USAGE_TRANSFER_DST_BIT
specifies that the image can be used as the destination of a transfer command. -
VK_IMAGE_USAGE_SAMPLED_BIT
specifies that the image can be used to create aVkImageView
suitable for occupying aVkDescriptorSet
slot either of typeVK_DESCRIPTOR_TYPE_SAMPLED_IMAGE
orVK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
, and be sampled by a shader. -
VK_IMAGE_USAGE_STORAGE_BIT
specifies that the image can be used to create aVkImageView
suitable for occupying aVkDescriptorSet
slot of typeVK_DESCRIPTOR_TYPE_STORAGE_IMAGE
. -
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
specifies that the image can be used to create aVkImageView
suitable for use as a color or resolve attachment in aVkFramebuffer
. -
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
specifies that the image can be used to create aVkImageView
suitable for use as a depth/stencil or depth/stencil resolve attachment in aVkFramebuffer
. -
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
specifies that implementations may support using memory allocations with theVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
to back an image with this usage. This bit can be set for any image that can be used to create aVkImageView
suitable for use as a color, resolve, depth/stencil, or input attachment. -
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
specifies that the image can be used to create aVkImageView
suitable for occupyingVkDescriptorSet
slot of typeVK_DESCRIPTOR_TYPE_INPUT_ATTACHMENT
; be read from a shader as an input attachment; and be used as an input attachment in a framebuffer.
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageUsageFlags;
VkImageUsageFlags
is a bitmask type for setting a mask of zero or more
VkImageUsageFlagBits.
When creating a VkImageView
one of the following
VkImageUsageFlagBits must be set:
-
VK_IMAGE_USAGE_SAMPLED_BIT
-
VK_IMAGE_USAGE_STORAGE_BIT
-
VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
-
VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
-
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
-
VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
Bits which can be set in VkImageCreateInfo::flags
, specifying
additional parameters of an image, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageCreateFlagBits {
VK_IMAGE_CREATE_SPARSE_BINDING_BIT = 0x00000001,
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT = 0x00000002,
VK_IMAGE_CREATE_SPARSE_ALIASED_BIT = 0x00000004,
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT = 0x00000008,
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT = 0x00000010,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_ALIAS_BIT = 0x00000400,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT = 0x00000040,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT = 0x00000020,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT = 0x00000080,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_EXTENDED_USAGE_BIT = 0x00000100,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_PROTECTED_BIT = 0x00000800,
// Provided by VK_VERSION_1_1
VK_IMAGE_CREATE_DISJOINT_BIT = 0x00000200,
} VkImageCreateFlagBits;
-
VK_IMAGE_CREATE_SPARSE_BINDING_BIT
specifies that the image will be backed using sparse memory binding. -
VK_IMAGE_CREATE_SPARSE_RESIDENCY_BIT
specifies that the image can be partially backed using sparse memory binding. Images created with this flag must also be created with theVK_IMAGE_CREATE_SPARSE_BINDING_BIT
flag. -
VK_IMAGE_CREATE_SPARSE_ALIASED_BIT
specifies that the image will be backed using sparse memory binding with memory ranges that might also simultaneously be backing another image (or another portion of the same image). Images created with this flag must also be created with theVK_IMAGE_CREATE_SPARSE_BINDING_BIT
flag. -
VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
specifies that the image can be used to create aVkImageView
with a different format from the image. For multi-planar formats,VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
specifies that aVkImageView
can be created of a plane of the image. -
VK_IMAGE_CREATE_CUBE_COMPATIBLE_BIT
specifies that the image can be used to create aVkImageView
of typeVK_IMAGE_VIEW_TYPE_CUBE
orVK_IMAGE_VIEW_TYPE_CUBE_ARRAY
. -
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT
specifies that the image can be used to create aVkImageView
of typeVK_IMAGE_VIEW_TYPE_2D
orVK_IMAGE_VIEW_TYPE_2D_ARRAY
. -
VK_IMAGE_CREATE_PROTECTED_BIT
specifies that the image is a protected image. -
VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
specifies that the image can be used with a non-zero value of thesplitInstanceBindRegionCount
member of a VkBindImageMemoryDeviceGroupInfo structure passed into vkBindImageMemory2. This flag also has the effect of making the image use the standard sparse image block dimensions. -
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT
specifies that the image having a compressed format can be used to create aVkImageView
with an uncompressed format where each texel in the image view corresponds to a compressed texel block of the image. -
VK_IMAGE_CREATE_EXTENDED_USAGE_BIT
specifies that the image can be created with usage flags that are not supported for the format the image is created with but are supported for at least one format aVkImageView
created from the image can have. -
VK_IMAGE_CREATE_DISJOINT_BIT
specifies that an image with a multi-planar format must have each plane separately bound to memory, rather than having a single memory binding for the whole image; the presence of this bit distinguishes a disjoint image from an image without this bit set. -
VK_IMAGE_CREATE_ALIAS_BIT
specifies that two images created with the same creation parameters and aliased to the same memory can interpret the contents of the memory consistently with each other, subject to the rules described in the Memory Aliasing section. This flag further specifies that each plane of a disjoint image can share an in-memory non-linear representation with single-plane images, and that a single-plane image can share an in-memory non-linear representation with a plane of a multi-planar disjoint image, according to the rules in Compatible formats of planes of multi-planar formats. If thepNext
chain includes a VkExternalMemoryImageCreateInfo structure whosehandleTypes
member is not0
, it is as ifVK_IMAGE_CREATE_ALIAS_BIT
is set.
See Sparse Resource Features and Sparse Physical Device Features for more details.
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageCreateFlags;
VkImageCreateFlags
is a bitmask type for setting a mask of zero or
more VkImageCreateFlagBits.
Possible values of VkImageCreateInfo::imageType
, specifying the
basic dimensionality of an image, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageType {
VK_IMAGE_TYPE_1D = 0,
VK_IMAGE_TYPE_2D = 1,
VK_IMAGE_TYPE_3D = 2,
} VkImageType;
-
VK_IMAGE_TYPE_1D
specifies a one-dimensional image. -
VK_IMAGE_TYPE_2D
specifies a two-dimensional image. -
VK_IMAGE_TYPE_3D
specifies a three-dimensional image.
Possible values of VkImageCreateInfo::tiling
, specifying the
tiling arrangement of texel blocks in an image, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageTiling {
VK_IMAGE_TILING_OPTIMAL = 0,
VK_IMAGE_TILING_LINEAR = 1,
} VkImageTiling;
-
VK_IMAGE_TILING_OPTIMAL
specifies optimal tiling (texels are laid out in an implementation-dependent arrangement, for more efficient memory access). -
VK_IMAGE_TILING_LINEAR
specifies linear tiling (texels are laid out in memory in row-major order, possibly with some padding on each row).
To query the memory layout of an image subresource, call:
// Provided by VK_VERSION_1_0
void vkGetImageSubresourceLayout(
VkDevice device,
VkImage image,
const VkImageSubresource* pSubresource,
VkSubresourceLayout* pLayout);
-
device
is the logical device that owns the image. -
image
is the image whose layout is being queried. -
pSubresource
is a pointer to a VkImageSubresource structure selecting a specific image subresource from the image. -
pLayout
is a pointer to a VkSubresourceLayout structure in which the layout is returned.
The image must be linear. The returned layout is valid for host access.
If the image’s
format is a multi-planar
format, then vkGetImageSubresourceLayout
describes one
plane
of the image.
vkGetImageSubresourceLayout
is invariant for the lifetime of a single
image.
The VkImageSubresource
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageSubresource {
VkImageAspectFlags aspectMask;
uint32_t mipLevel;
uint32_t arrayLayer;
} VkImageSubresource;
-
aspectMask
is a VkImageAspectFlags value selecting the image aspect. -
mipLevel
selects the mipmap level. -
arrayLayer
selects the array layer.
Information about the layout of the image subresource is returned in a
VkSubresourceLayout
structure:
// Provided by VK_VERSION_1_0
typedef struct VkSubresourceLayout {
VkDeviceSize offset;
VkDeviceSize size;
VkDeviceSize rowPitch;
VkDeviceSize arrayPitch;
VkDeviceSize depthPitch;
} VkSubresourceLayout;
-
offset
is the byte offset from the start of the image or the plane where the image subresource begins. -
size
is the size in bytes of the image subresource.size
includes any extra memory that is required based onrowPitch
. -
rowPitch
describes the number of bytes between each row of texels in an image. -
arrayPitch
describes the number of bytes between each array layer of an image. -
depthPitch
describes the number of bytes between each slice of 3D image.
If the image is linear, then rowPitch
,
arrayPitch
and depthPitch
describe the layout of the image
subresource in linear memory.
For uncompressed formats, rowPitch
is the number of bytes between
texels with the same x coordinate in adjacent rows (y coordinates differ by
one).
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).
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:
// (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 rowPitch
is the number of bytes between
compressed texel blocks in adjacent rows.
arrayPitch
is the number of bytes between compressed texel blocks in
adjacent array layers.
depthPitch
is the number of bytes between compressed texel blocks in
adjacent slices of a 3D image.
// (x,y,z,layer) are in compressed texel block coordinates
address(x,y,z,layer) = layer*arrayPitch + z*depthPitch + y*rowPitch + x*compressedTexelBlockByteSize + offset;
The value of arrayPitch
is undefined for images that were not created
as arrays.
depthPitch
is defined only for 3D images.
If the image has a
single-plane
color format
, then the aspectMask
member of VkImageSubresource
must be
VK_IMAGE_ASPECT_COLOR_BIT
.
If the image has a depth/stencil format
, then aspectMask
must be either VK_IMAGE_ASPECT_DEPTH_BIT
or
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 offset
and size
representing the region of memory used for that aspect.
On implementations that store depth and stencil aspects interleaved, the
same offset
and size
are returned and represent the interleaved
memory allocation.
If the image has a multi-planar
format
, then the aspectMask
member of VkImageSubresource
must be
VK_IMAGE_ASPECT_PLANE_0_BIT
, VK_IMAGE_ASPECT_PLANE_1_BIT
, or
(for 3-plane formats only) VK_IMAGE_ASPECT_PLANE_2_BIT
.
Querying each of these image subresource layouts will return a different
offset
and size
representing the region of memory used for that
plane.
If the image is disjoint, then the offset
is relative to the base
address of the plane.
If the image is non-disjoint, then the offset
is relative to the
base address of the image.
To destroy an image, call:
// Provided by VK_VERSION_1_0
void vkDestroyImage(
VkDevice device,
VkImage image,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that destroys the image. -
image
is the image to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
12.3.1. Image Format Features
Valid uses of a VkImage may depend on the image’s format features, defined below. Such constraints are documented in the affected valid usage statement.
-
If the image was created with
VK_IMAGE_TILING_LINEAR
, then its set of format features is the value of VkFormatProperties::linearTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties on the sameformat
as VkImageCreateInfo::format
. -
If the image was created with
VK_IMAGE_TILING_OPTIMAL
, then its set of format features is the value of VkFormatProperties::optimalTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties on the sameformat
as VkImageCreateInfo::format
.
12.3.2. Image Miplevel Sizing
A complete mipmap chain is the full set of miplevels, from the largest miplevel provided, down to the minimum miplevel size.
Conventional Images
For conventional images, the dimensions of each successive miplevel, n+1, are:
-
width
n+1 = max(⌊width
n/2⌋, 1) -
height
n+1 = max(⌊height
n/2⌋, 1) -
depth
n+1 = max(⌊depth
n/2⌋, 1)
where width
n, height
n, and depth
n
are the dimensions of the next larger miplevel, n.
The minimum miplevel size is:
-
1 for one-dimensional images,
-
1x1 for two-dimensional images, and
-
1x1x1 for three-dimensional images.
The number of levels in a complete mipmap chain is:
-
⌊log2(max(
width
0,height
0,depth
0))⌋ + 1
where width
0, height
0, and depth
0
are the dimensions of the largest (most detailed) miplevel, 0
.
12.4. Image Layouts
Images are stored in implementation-dependent opaque layouts in memory.
Each layout has limitations on what kinds of operations are supported for
image subresources using the layout.
At any given time, the data representing an image subresource in memory
exists in a particular layout which is determined by the most recent layout
transition that was performed on that image subresource.
Applications have control over which layout each image subresource uses, and
can transition an image subresource from one layout to another.
Transitions can happen with an image memory barrier, included as part of a
vkCmdPipelineBarrier or a vkCmdWaitEvents command buffer command
(see Image Memory Barriers), or as part of a subpass
dependency within a render pass (see VkSubpassDependency
).
Image layout is per-image subresource.
Separate image subresources of the same image can be in different layouts
at the same time, with the exception that depth and stencil aspects of a
given image subresource can only be in different layouts if the
separateDepthStencilLayouts
feature is enabled.
Note
Each layout may offer optimal performance for a specific usage of image
memory.
For example, an image with a layout of
|
Upon creation, all image subresources of an image are initially in the same
layout, where that layout is selected by the
VkImageCreateInfo
::initialLayout
member.
The initialLayout
must be either VK_IMAGE_LAYOUT_UNDEFINED
or
VK_IMAGE_LAYOUT_PREINITIALIZED
.
If it is 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 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
linear images and for image subresources of
those images which are currently in either the
VK_IMAGE_LAYOUT_PREINITIALIZED
or VK_IMAGE_LAYOUT_GENERAL
layout.
Calling vkGetImageSubresourceLayout for a linear image returns a
subresource layout mapping that is valid for either of those image layouts.
The set of image layouts consists of:
// Provided by VK_VERSION_1_0
typedef enum VkImageLayout {
VK_IMAGE_LAYOUT_UNDEFINED = 0,
VK_IMAGE_LAYOUT_GENERAL = 1,
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL = 2,
VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL = 3,
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL = 4,
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL = 5,
VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL = 6,
VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL = 7,
VK_IMAGE_LAYOUT_PREINITIALIZED = 8,
// Provided by VK_VERSION_1_1
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL = 1000117000,
// Provided by VK_VERSION_1_1
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL = 1000117001,
// Provided by VK_VERSION_1_2
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL = 1000241000,
// Provided by VK_VERSION_1_2
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL = 1000241001,
// Provided by VK_VERSION_1_2
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL = 1000241002,
// Provided by VK_VERSION_1_2
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL = 1000241003,
// Provided by VK_VERSION_1_3
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL = 1000314000,
// Provided by VK_VERSION_1_3
VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL = 1000314001,
} VkImageLayout;
The type(s) of device access supported by each layout are:
-
VK_IMAGE_LAYOUT_UNDEFINED
specifies that the layout is unknown. Image memory cannot be transitioned into this layout. This layout can be used as theinitialLayout
member of VkImageCreateInfo. This layout can be used in place of the current image layout in a layout transition, but doing so will cause the contents of the image’s memory to be undefined. -
VK_IMAGE_LAYOUT_PREINITIALIZED
specifies that an image’s memory is in a defined layout and can be populated by data, but that it has not yet been initialized by the driver. Image memory cannot be transitioned into this layout. This layout can be used as theinitialLayout
member of VkImageCreateInfo. This layout is intended to be used as the initial layout for an image whose contents are written by the host, and hence the data can be written to memory immediately, without first executing a layout transition. Currently,VK_IMAGE_LAYOUT_PREINITIALIZED
is only useful with linear images because there is not a standard layout defined forVK_IMAGE_TILING_OPTIMAL
images. -
VK_IMAGE_LAYOUT_GENERAL
supports all types of device access. -
VK_IMAGE_LAYOUT_ATTACHMENT_OPTIMAL
specifies a layout that must only be used with attachment accesses in the graphics pipeline. -
VK_IMAGE_LAYOUT_READ_ONLY_OPTIMAL
specifies a layout allowing read only access as an attachment, or in shaders as a sampled image, combined image/sampler, or input attachment. -
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
must only be used as a color or resolve attachment in aVkFramebuffer
. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
usage bit enabled. -
VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL
specifies a layout for both the depth and stencil aspects of a depth/stencil format image allowing read and write access as a depth/stencil attachment. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL
andVK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL
. -
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
specifies a layout for both the depth and stencil aspects of a depth/stencil format image allowing read only access as a depth/stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
andVK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
. -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL
specifies a layout for depth/stencil format images allowing read and write access to the stencil aspect as a stencil attachment, and read only access to the depth aspect as a depth attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
andVK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL
. -
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL
specifies a layout for depth/stencil format images allowing read and write access to the depth aspect as a depth attachment, and read only access to the stencil aspect as a stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL
andVK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
. -
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL
specifies a layout for the depth aspect of a depth/stencil format image allowing read and write access as a depth attachment. -
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL
specifies a layout for the depth aspect of a depth/stencil format image allowing read-only access as a depth attachment or in shaders as a sampled image, combined image/sampler, or input attachment. -
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL
specifies a layout for the stencil aspect of a depth/stencil format image allowing read and write access as a stencil attachment. -
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL
specifies a layout for the stencil aspect of a depth/stencil format image allowing read-only access as a stencil attachment or in shaders as a sampled image, combined image/sampler, or input attachment. -
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
specifies a layout allowing read-only access in a shader as a sampled image, combined image/sampler, or input attachment. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_SAMPLED_BIT
orVK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
usage bits enabled. -
VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
must only be used as a source image of a transfer command (see the definition ofVK_PIPELINE_STAGE_TRANSFER_BIT
). This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_TRANSFER_SRC_BIT
usage bit enabled. -
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 theVK_IMAGE_USAGE_TRANSFER_DST_BIT
usage bit enabled.
The layout of each image subresource is not a state of the image subresource
itself, but is rather a property of how the data in memory is organized, and
thus for each mechanism of accessing an image in the API the application
must specify a parameter or structure member that indicates which image
layout the image subresource(s) are considered to be in when the image will
be accessed.
For transfer commands, this is a parameter to the command (see Clear Commands
and Copy Commands).
For use as a framebuffer attachment, this is a member in the substructures
of the VkRenderPassCreateInfo (see Render Pass).
For use in a descriptor set, this is a member in the
VkDescriptorImageInfo
structure (see Descriptor Set Updates).
12.4.1. Image Layout Matching Rules
At the time that any command buffer command accessing an image executes on any queue, the layouts of the image subresources that are accessed must all match exactly the layout specified via the API controlling those accesses, except in case of accesses to an image with a depth/stencil format performed through descriptors referring to only a single aspect of the image, where the following relaxed matching rules apply:
-
Descriptors referring just to the depth aspect of a depth/stencil image only need to match in the image layout of the depth aspect, thus
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
andVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL
are considered to match. -
Descriptors referring just to the stencil aspect of a depth/stencil image only need to match in the image layout of the stencil aspect, thus
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
andVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL
are considered to match.
When performing a layout transition on an image subresource, the old layout
value must either equal the current layout of the image subresource (at the
time the transition executes), or else be 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
VK_IMAGE_LAYOUT_UNDEFINED
or VK_IMAGE_LAYOUT_PREINITIALIZED
.
12.5. Image Views
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 VkImageView
handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkImageView)
VK_REMAINING_ARRAY_LAYERS
is a special constant value used for image
views to indicate that all remaining array layers in an image after the base
layer should be included in the view.
#define VK_REMAINING_ARRAY_LAYERS (~0U)
VK_REMAINING_MIP_LEVELS
is a special constant value used for image
views to indicate that all remaining mipmap levels in an image after the
base level should be included in the view.
#define VK_REMAINING_MIP_LEVELS (~0U)
The types of image views that can be created are:
// Provided by VK_VERSION_1_0
typedef enum VkImageViewType {
VK_IMAGE_VIEW_TYPE_1D = 0,
VK_IMAGE_VIEW_TYPE_2D = 1,
VK_IMAGE_VIEW_TYPE_3D = 2,
VK_IMAGE_VIEW_TYPE_CUBE = 3,
VK_IMAGE_VIEW_TYPE_1D_ARRAY = 4,
VK_IMAGE_VIEW_TYPE_2D_ARRAY = 5,
VK_IMAGE_VIEW_TYPE_CUBE_ARRAY = 6,
} VkImageViewType;
To create an image view, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateImageView(
VkDevice device,
const VkImageViewCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkImageView* pView);
-
device
is the logical device that creates the image view. -
pCreateInfo
is a pointer to aVkImageViewCreateInfo
structure containing parameters to be used to create the image view. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pView
is a pointer to a VkImageView handle in which the resulting image view object is returned.
The VkImageViewCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageViewCreateInfo {
VkStructureType sType;
const void* pNext;
VkImageViewCreateFlags flags;
VkImage image;
VkImageViewType viewType;
VkFormat format;
VkComponentMapping components;
VkImageSubresourceRange subresourceRange;
} VkImageViewCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is a bitmask of VkImageViewCreateFlagBits specifying additional parameters of the image view. -
image
is a VkImage on which the view will be created. -
viewType
is a VkImageViewType value specifying the type of the image view. -
format
is a VkFormat specifying the format and type used to interpret texel blocks of the image. -
components
is a VkComponentMapping structure specifying a remapping of color components (or of depth or stencil components after they have been converted into color components). -
subresourceRange
is a VkImageSubresourceRange structure selecting the set of mipmap levels and array layers to be accessible to the view.
Some of the image
creation parameters are inherited by the view.
In particular, image view creation inherits the implicit parameter
usage
specifying the allowed usages of the image view that, by
default, takes the value of the corresponding usage
parameter
specified in VkImageCreateInfo at image creation time.
The implicit usage
can be overridden by adding a
VkImageViewUsageCreateInfo structure to the pNext
chain, but the
view usage must be a subset of the image usage.
If image
has a depth-stencil format and was created with a
VkImageStencilUsageCreateInfo structure included in the pNext
chain of VkImageCreateInfo, the usage is calculated based on the
subresource.aspectMask
provided:
-
If
aspectMask
includes onlyVK_IMAGE_ASPECT_STENCIL_BIT
, the implicitusage
is equal to VkImageStencilUsageCreateInfo::stencilUsage
. -
If
aspectMask
includes onlyVK_IMAGE_ASPECT_DEPTH_BIT
, the implicitusage
is equal to VkImageCreateInfo::usage
. -
If both aspects are included in
aspectMask
, the implicitusage
is equal to the intersection of VkImageCreateInfo::usage
and VkImageStencilUsageCreateInfo::stencilUsage
.
If image
was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
flag,
and if the format
of the image is not
multi-planar,
format
can be different from the image’s format, but if
image
was created without the
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT
flag and
they are not equal they must be compatible.
Image format compatibility is defined in the
Format Compatibility Classes section.
Views of compatible formats will have the same mapping between texel
coordinates and memory locations irrespective of the format
, with only
the interpretation of the bit pattern changing.
If image
was created with a
multi-planar format, and the
image view’s aspectMask
is one of VK_IMAGE_ASPECT_PLANE_0_BIT
,
VK_IMAGE_ASPECT_PLANE_1_BIT
or VK_IMAGE_ASPECT_PLANE_2_BIT
, the
view’s aspect mask is considered to be equivalent to
VK_IMAGE_ASPECT_COLOR_BIT
when used as a framebuffer attachment.
Note
Values intended to be used with one view format may not be exactly preserved when written or read through a different format. For example, an integer value that happens to have the bit pattern of a floating point denorm or NaN may be flushed or canonicalized when written or read through a view with a floating point format. Similarly, a value written through a signed normalized format that has a bit pattern exactly equal to -2b may be changed to -2b + 1 as described in Conversion from Normalized Fixed-Point to Floating-Point. |
If image
was created with the
VK_IMAGE_CREATE_BLOCK_TEXEL_VIEW_COMPATIBLE_BIT
flag, format
must be compatible with the image’s format as described above; or must
be an uncompressed format, in which case it must be
size-compatible with the image’s format.
In this case, the resulting image view’s texel dimensions equal the
dimensions of the selected mip level divided by the compressed texel block
size and rounded up.
The VkComponentMapping components
member describes a remapping
from components of the image to components of the vector returned by shader
image instructions.
This remapping must be the identity swizzle for storage image descriptors,
input attachment descriptors,
framebuffer attachments, and any VkImageView
used with a combined
image sampler that enables sampler Y′CBCR
conversion.
If the image view is to be used with a sampler which supports
sampler Y′CBCR conversion, an identically
defined object of type VkSamplerYcbcrConversion to that used to
create the sampler must be passed to vkCreateImageView in a
VkSamplerYcbcrConversionInfo included in the pNext
chain of
VkImageViewCreateInfo.
Conversely, if a VkSamplerYcbcrConversion object is passed to
vkCreateImageView, an identically defined
VkSamplerYcbcrConversion object must be used when sampling the image.
If the image has a
multi-planar format
,
subresourceRange.aspectMask
is VK_IMAGE_ASPECT_COLOR_BIT
, and
usage
includes VK_IMAGE_USAGE_SAMPLED_BIT
, then the format
must be identical to the image format
and the sampler to be used with
the image view must enable sampler Y′CBCR
conversion.
If image
was created with the VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
and the image has a
multi-planar format
,
and if subresourceRange.aspectMask
is
VK_IMAGE_ASPECT_PLANE_0_BIT
, VK_IMAGE_ASPECT_PLANE_1_BIT
, or
VK_IMAGE_ASPECT_PLANE_2_BIT
, format
must be
compatible with the corresponding plane of the
image, and the sampler to be used with the image view must not enable
sampler Y′CBCR conversion.
The width
and height
of the single-plane image view must be
derived from the multi-planar image’s dimensions in the manner listed for
plane compatibility for the plane.
Any view of an image plane will have the same mapping between texel coordinates and memory locations as used by the components of the color aspect, subject to the formulae relating texel coordinates to lower-resolution planes as described in Chroma Reconstruction. That is, if an R or B plane has a reduced resolution relative to the G plane of the multi-planar image, the image view operates using the (uplane, vplane) unnormalized coordinates of the reduced-resolution plane, and these coordinates access the same memory locations as the (ucolor, vcolor) unnormalized coordinates of the color aspect for which chroma reconstruction operations operate on the same (uplane, vplane) or (iplane, jplane) coordinates.
Image View Type | Compatible Image Types |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Bits which can be set in VkImageViewCreateInfo::flags
,
specifying additional parameters of an image view, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageViewCreateFlagBits {
} VkImageViewCreateFlagBits;
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageViewCreateFlags;
VkImageViewCreateFlags
is a bitmask type for setting a mask of zero or
more VkImageViewCreateFlagBits.
The set of usages for the created image view can be restricted compared to
the parent image’s usage
flags by adding a
VkImageViewUsageCreateInfo
structure to the pNext
chain of
VkImageViewCreateInfo.
The VkImageViewUsageCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImageViewUsageCreateInfo {
VkStructureType sType;
const void* pNext;
VkImageUsageFlags usage;
} VkImageViewUsageCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
usage
is a bitmask of VkImageUsageFlagBits specifying allowed usages of the image view.
When this structure is chained to VkImageViewCreateInfo the
usage
field overrides the implicit usage
parameter inherited
from image creation time and its value is used instead for the purposes of
determining the valid usage conditions of VkImageViewCreateInfo.
The VkImageSubresourceRange
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkImageSubresourceRange {
VkImageAspectFlags aspectMask;
uint32_t baseMipLevel;
uint32_t levelCount;
uint32_t baseArrayLayer;
uint32_t layerCount;
} VkImageSubresourceRange;
-
aspectMask
is a bitmask of VkImageAspectFlagBits specifying which aspect(s) of the image are included in the view. -
baseMipLevel
is the first mipmap level accessible to the view. -
levelCount
is the number of mipmap levels (starting frombaseMipLevel
) accessible to the view. -
baseArrayLayer
is the first array layer accessible to the view. -
layerCount
is the number of array layers (starting frombaseArrayLayer
) 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 baseMipLevel
or baseArrayLayer
, it can set levelCount
and layerCount
to the special values VK_REMAINING_MIP_LEVELS
and
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 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 layerCount
/ 6, and
image array layer (baseArrayLayer
+ i) is face index
(i mod 6) of cube i / 6.
If the number of layers in the view, whether set explicitly in
layerCount
or implied by VK_REMAINING_ARRAY_LAYERS
, is not a
multiple of 6, the last cube map in the array must not be accessed.
aspectMask
must be only VK_IMAGE_ASPECT_COLOR_BIT
,
VK_IMAGE_ASPECT_DEPTH_BIT
or VK_IMAGE_ASPECT_STENCIL_BIT
if
format
is a color, depth-only or stencil-only format,
respectively, except if format
is a
multi-planar format.
If using a depth/stencil format with both depth and stencil components,
aspectMask
must include at least one of
VK_IMAGE_ASPECT_DEPTH_BIT
and VK_IMAGE_ASPECT_STENCIL_BIT
, and
can include both.
When the VkImageSubresourceRange
structure is used to select a subset
of the slices of a 3D image’s mip level in order to create a 2D or 2D array
image view of a 3D image created with
VK_IMAGE_CREATE_2D_ARRAY_COMPATIBLE_BIT
, baseArrayLayer
and
layerCount
specify the first slice index and the number of slices to
include in the created image view.
Such an image view can be used as a framebuffer attachment that refers only
to the specified range of slices of the selected mip level.
However, any layout transitions performed on such an attachment view during
a render pass instance still apply to the entire subresource referenced
which includes all the slices of the selected mip level.
When using an image view of a depth/stencil image to populate a descriptor
set (e.g. for sampling in the shader, or for use as an input attachment),
the aspectMask
must only include one bit, which selects whether the
image view is used for depth reads (i.e. using a floating-point sampler or
input attachment in the shader) or stencil reads (i.e. using an unsigned
integer sampler or input attachment in the shader).
When an image view of a depth/stencil image is used as a depth/stencil
framebuffer attachment, the aspectMask
is ignored and both depth and
stencil image subresources are used.
When creating a VkImageView
, if sampler
Y′CBCR conversion is enabled in the sampler, the aspectMask
of a
subresourceRange
used by the VkImageView
must be
VK_IMAGE_ASPECT_COLOR_BIT
.
When creating a VkImageView
, if sampler Y′CBCR conversion is not
enabled in the sampler and the image format
is
multi-planar, the image must
have been created with VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT
, and the
aspectMask
of the VkImageView
’s subresourceRange
must be
VK_IMAGE_ASPECT_PLANE_0_BIT
, VK_IMAGE_ASPECT_PLANE_1_BIT
or
VK_IMAGE_ASPECT_PLANE_2_BIT
.
Bits which can be set in an aspect mask to specify aspects of an image for purposes such as identifying a subresource, are:
// Provided by VK_VERSION_1_0
typedef enum VkImageAspectFlagBits {
VK_IMAGE_ASPECT_COLOR_BIT = 0x00000001,
VK_IMAGE_ASPECT_DEPTH_BIT = 0x00000002,
VK_IMAGE_ASPECT_STENCIL_BIT = 0x00000004,
VK_IMAGE_ASPECT_METADATA_BIT = 0x00000008,
// Provided by VK_VERSION_1_1
VK_IMAGE_ASPECT_PLANE_0_BIT = 0x00000010,
// Provided by VK_VERSION_1_1
VK_IMAGE_ASPECT_PLANE_1_BIT = 0x00000020,
// Provided by VK_VERSION_1_1
VK_IMAGE_ASPECT_PLANE_2_BIT = 0x00000040,
// Provided by VK_VERSION_1_3
VK_IMAGE_ASPECT_NONE = 0,
} VkImageAspectFlagBits;
-
VK_IMAGE_ASPECT_NONE
specifies no image aspect, or the image aspect is not applicable. -
VK_IMAGE_ASPECT_COLOR_BIT
specifies the color aspect. -
VK_IMAGE_ASPECT_DEPTH_BIT
specifies the depth aspect. -
VK_IMAGE_ASPECT_STENCIL_BIT
specifies the stencil aspect. -
VK_IMAGE_ASPECT_METADATA_BIT
specifies the metadata aspect used for sparse resource operations. -
VK_IMAGE_ASPECT_PLANE_0_BIT
specifies plane 0 of a multi-planar image format. -
VK_IMAGE_ASPECT_PLANE_1_BIT
specifies plane 1 of a multi-planar image format. -
VK_IMAGE_ASPECT_PLANE_2_BIT
specifies plane 2 of a multi-planar image format.
// Provided by VK_VERSION_1_0
typedef VkFlags VkImageAspectFlags;
VkImageAspectFlags
is a bitmask type for setting a mask of zero or
more VkImageAspectFlagBits.
The VkComponentMapping
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkComponentMapping {
VkComponentSwizzle r;
VkComponentSwizzle g;
VkComponentSwizzle b;
VkComponentSwizzle a;
} VkComponentMapping;
-
r
is a VkComponentSwizzle specifying the component value placed in the R component of the output vector. -
g
is a VkComponentSwizzle specifying the component value placed in the G component of the output vector. -
b
is a VkComponentSwizzle specifying the component value placed in the B component of the output vector. -
a
is a VkComponentSwizzle specifying the component value placed in the A component of the output vector.
Possible values of the members of VkComponentMapping, specifying the component values placed in each component of the output vector, are:
// Provided by VK_VERSION_1_0
typedef enum VkComponentSwizzle {
VK_COMPONENT_SWIZZLE_IDENTITY = 0,
VK_COMPONENT_SWIZZLE_ZERO = 1,
VK_COMPONENT_SWIZZLE_ONE = 2,
VK_COMPONENT_SWIZZLE_R = 3,
VK_COMPONENT_SWIZZLE_G = 4,
VK_COMPONENT_SWIZZLE_B = 5,
VK_COMPONENT_SWIZZLE_A = 6,
} VkComponentSwizzle;
-
VK_COMPONENT_SWIZZLE_IDENTITY
specifies that the component is set to the identity swizzle. -
VK_COMPONENT_SWIZZLE_ZERO
specifies that the component is set to zero. -
VK_COMPONENT_SWIZZLE_ONE
specifies that the component is set to either 1 or 1.0, depending on whether the type of the image view format is integer or floating-point respectively, as determined by the Format Definition section for each VkFormat. -
VK_COMPONENT_SWIZZLE_R
specifies that the component is set to the value of the R component of the image. -
VK_COMPONENT_SWIZZLE_G
specifies that the component is set to the value of the G component of the image. -
VK_COMPONENT_SWIZZLE_B
specifies that the component is set to the value of the B component of the image. -
VK_COMPONENT_SWIZZLE_A
specifies that the component is set to the value of the A component of the image.
Setting the identity swizzle on a component is equivalent to setting the identity mapping on that component. That is:
Component | Identity Mapping |
---|---|
|
|
|
|
|
|
|
|
To destroy an image view, call:
// Provided by VK_VERSION_1_0
void vkDestroyImageView(
VkDevice device,
VkImageView imageView,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that destroys the image view. -
imageView
is the image view to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
12.5.1. Image View Format Features
Valid uses of a VkImageView may depend on the image view’s format features, defined below. Such constraints are documented in the affected valid usage statement.
-
If Vulkan 1.3 is supported or the
extension is supported, and VkImageViewCreateInfo::VK_KHR_format_feature_flags2
image
was created withVK_IMAGE_TILING_LINEAR
, then the image view’s set of format features is the value of VkFormatProperties3::linearTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties2 on the sameformat
as VkImageViewCreateInfo::format
. -
If Vulkan 1.3 is not supported and the
extension is not supported, and VkImageViewCreateInfo::VK_KHR_format_feature_flags2
image
was created withVK_IMAGE_TILING_LINEAR
, then the image view’s set of format features is the union of the value of VkFormatProperties::linearTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties on the sameformat
as VkImageViewCreateInfo::format
, with:-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT
if the format is a depth/stencil format and the image view features also containVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT
. -
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT
if the format is one of the extended storage formats andshaderStorageImageReadWithoutFormat
is enabled on the device. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT
if the format is one of the extended storage formats andshaderStorageImageWriteWithoutFormat
is enabled on the device.
-
-
If Vulkan 1.3 is supported or the
extension is supported, and VkImageViewCreateInfo::VK_KHR_format_feature_flags2
image
was created withVK_IMAGE_TILING_OPTIMAL
, then the image view’s set of format features is the value of VkFormatProperties::optimalTilingFeatures
or VkFormatProperties3::optimalTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties or vkGetPhysicalDeviceImageFormatProperties2 on the sameformat
as VkImageViewCreateInfo::format
. -
If Vulkan 1.3 is not supported and the
extension is not supported, and VkImageViewCreateInfo::VK_KHR_format_feature_flags2
image
was created withVK_IMAGE_TILING_OPTIMAL
, then the image view’s set of format features is the union of the value of VkFormatProperties::optimalTilingFeatures
found by calling vkGetPhysicalDeviceFormatProperties on the sameformat
as VkImageViewCreateInfo::format
, with:-
VK_FORMAT_FEATURE_2_SAMPLED_IMAGE_DEPTH_COMPARISON_BIT
if the format is a depth/stencil format and the image view features also containVK_FORMAT_FEATURE_2_SAMPLED_IMAGE_BIT
. -
VK_FORMAT_FEATURE_2_STORAGE_READ_WITHOUT_FORMAT_BIT
if the format is one of the extended storage formats andshaderStorageImageReadWithoutFormat
is enabled on the device. -
VK_FORMAT_FEATURE_2_STORAGE_WRITE_WITHOUT_FORMAT_BIT
if the format is one of the extended storage formats andshaderStorageImageWriteWithoutFormat
is enabled on the device.
-
12.6. Resource Memory Association
Resources are initially created as virtual allocations with no backing memory. Device memory is allocated separately (see Device Memory) 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 Sparse Resources.
Non-sparse resources must be bound completely and contiguously to a single
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.
In a logical device representing more than one physical device, buffer and image resources exist on all physical devices but can be bound to memory differently on each. Each such replicated resource is an instance of the resource. For sparse resources, each instance can be bound to memory arbitrarily differently. For non-sparse resources, each instance can either be bound to the local or a peer instance of the memory, or for images can be bound to rectangular regions from the local and/or peer instances. When a resource is used in a descriptor set, each physical device interprets the descriptor according to its own instance’s binding to memory.
Note
There are no new copy commands to transfer data between physical devices. Instead, an application can create a resource with a peer mapping and use it as the source or destination of a transfer command executed by a single physical device to copy the data from one physical device to another. |
To determine the memory requirements for a buffer resource, call:
// Provided by VK_VERSION_1_0
void vkGetBufferMemoryRequirements(
VkDevice device,
VkBuffer buffer,
VkMemoryRequirements* pMemoryRequirements);
-
device
is the logical device that owns the buffer. -
buffer
is the buffer to query. -
pMemoryRequirements
is a pointer to a VkMemoryRequirements structure in which the memory requirements of the buffer object are returned.
To determine the memory requirements for an image resource which is not
created with the VK_IMAGE_CREATE_DISJOINT_BIT
flag set, call:
// Provided by VK_VERSION_1_0
void vkGetImageMemoryRequirements(
VkDevice device,
VkImage image,
VkMemoryRequirements* pMemoryRequirements);
-
device
is the logical device that owns the image. -
image
is the image to query. -
pMemoryRequirements
is a pointer to a VkMemoryRequirements structure in which the memory requirements of the image object are returned.
The VkMemoryRequirements
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkMemoryRequirements {
VkDeviceSize size;
VkDeviceSize alignment;
uint32_t memoryTypeBits;
} VkMemoryRequirements;
-
size
is the size, in bytes, of the memory allocation required for the resource. -
alignment
is the alignment, in bytes, of the offset within the allocation required for the resource. -
memoryTypeBits
is a bitmask and contains one bit set for every supported memory type for the resource. Biti
is set if and only if the memory typei
in theVkPhysicalDeviceMemoryProperties
structure for the physical device is supported for the resource.
The implementation guarantees certain properties about the memory requirements returned by vkGetDeviceBufferMemoryRequirements, vkGetDeviceImageMemoryRequirements, vkGetBufferMemoryRequirements and vkGetImageMemoryRequirements:
-
The
memoryTypeBits
member always contains at least one bit set. -
If
buffer
is aVkBuffer
not created with theVK_BUFFER_CREATE_SPARSE_BINDING_BIT
bit set, or ifimage
is linear image, then thememoryTypeBits
member always contains at least one bit set corresponding to aVkMemoryType
with apropertyFlags
that has both theVK_MEMORY_PROPERTY_HOST_VISIBLE_BIT
bit and theVK_MEMORY_PROPERTY_HOST_COHERENT_BIT
bit set. In other words, mappable coherent memory can always be attached to these objects. -
If
buffer
was created with VkExternalMemoryBufferCreateInfo::handleTypes
set to0
orimage
was created with VkExternalMemoryImageCreateInfo::handleTypes
set to0
, thememoryTypeBits
member always contains at least one bit set corresponding to aVkMemoryType
with apropertyFlags
that has theVK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT
bit set. -
The
memoryTypeBits
member is identical for allVkBuffer
objects created with the same value for theflags
andusage
members in the VkBufferCreateInfo structure and thehandleTypes
member of the VkExternalMemoryBufferCreateInfo structure passed to vkCreateBuffer. Further, ifusage1
andusage2
of type VkBufferUsageFlags are such that the bits set inusage2
are a subset of the bits set inusage1
, and they have the sameflags
and VkExternalMemoryBufferCreateInfo::handleTypes
, then the bits set inmemoryTypeBits
returned forusage1
must be a subset of the bits set inmemoryTypeBits
returned forusage2
, for all values offlags
. -
The
alignment
member is a power of two. -
The
alignment
member is identical for allVkBuffer
objects created with the same combination of values for theusage
andflags
members in the VkBufferCreateInfo structure passed to vkCreateBuffer. -
If the
maintenance4
feature is enabled, then thealignment
member is identical for allVkImage
objects created with the same combination of values for theflags
,imageType
,format
,extent
,mipLevels
,arrayLayers
,samples
,tiling
andusage
members in the VkImageCreateInfo structure passed to vkCreateImage. -
The
alignment
member satisfies the buffer descriptor offset alignment requirements associated with theVkBuffer
’susage
:-
If
usage
includedVK_BUFFER_USAGE_UNIFORM_TEXEL_BUFFER_BIT
orVK_BUFFER_USAGE_STORAGE_TEXEL_BUFFER_BIT
,alignment
must be an integer multiple ofVkPhysicalDeviceLimits
::minTexelBufferOffsetAlignment
. -
If
usage
includedVK_BUFFER_USAGE_UNIFORM_BUFFER_BIT
,alignment
must be an integer multiple ofVkPhysicalDeviceLimits
::minUniformBufferOffsetAlignment
. -
If
usage
includedVK_BUFFER_USAGE_STORAGE_BUFFER_BIT
,alignment
must be an integer multiple ofVkPhysicalDeviceLimits
::minStorageBufferOffsetAlignment
.
-
-
For images created with a color format, the
memoryTypeBits
member is identical for allVkImage
objects created with the same combination of values for thetiling
member, theVK_IMAGE_CREATE_SPARSE_BINDING_BIT
bit of theflags
member, theVK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
bit of theflags
member,handleTypes
member of VkExternalMemoryImageCreateInfo, and theVK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
of theusage
member in the VkImageCreateInfo structure passed to vkCreateImage. -
For images created with a depth/stencil format, the
memoryTypeBits
member is identical for allVkImage
objects created with the same combination of values for theformat
member, thetiling
member, theVK_IMAGE_CREATE_SPARSE_BINDING_BIT
bit of theflags
member, theVK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT
bit of theflags
member,handleTypes
member of VkExternalMemoryImageCreateInfo, and theVK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
of theusage
member in the VkImageCreateInfo structure passed to vkCreateImage. -
If the memory requirements are for a
VkImage
, thememoryTypeBits
member must not refer to aVkMemoryType
with apropertyFlags
that has theVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
bit set if theimage
did not haveVK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT
bit set in theusage
member of the VkImageCreateInfo structure passed to vkCreateImage. -
If the memory requirements are for a
VkBuffer
, thememoryTypeBits
member must not refer to aVkMemoryType
with apropertyFlags
that has theVK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT
bit set.NoteThe implication of this requirement is that lazily allocated memory is disallowed for buffers in all cases.
-
The
size
member is identical for allVkBuffer
objects created with the same combination of creation parameters specified in VkBufferCreateInfo and itspNext
chain. -
The
size
member is identical for allVkImage
objects created with the same combination of creation parameters specified in VkImageCreateInfo and itspNext
chain.NoteThis, however, does not imply that they interpret the contents of the bound memory identically with each other. That additional guarantee, however, can be explicitly requested using
VK_IMAGE_CREATE_ALIAS_BIT
. -
If the
maintenance4
feature is enabled, these additional guarantees apply:-
For a
VkBuffer
, thesize
memory requirement is never greater than that of anotherVkBuffer
created with a greater or equalsize
specified in VkBufferCreateInfo, all other creation parameters being identical. -
For a
VkBuffer
, thesize
memory requirement is never greater than the result of aligning VkBufferCreateInfo::size
with thealignment
memory requirement. -
For a VkImage, the
size
memory requirement is never greater than that of another VkImage created with a greater or equal value in each ofextent.width
,extent.height
, andextent.depth
; all other creation parameters being identical. -
The memory requirements returned by vkGetDeviceBufferMemoryRequirements are identical to those that would be returned by vkGetBufferMemoryRequirements2 if it were called with a
VkBuffer
created with the same VkBufferCreateInfo values. -
The memory requirements returned by vkGetDeviceImageMemoryRequirements are identical to those that would be returned by vkGetImageMemoryRequirements2 if it were called with a
VkImage
created with the same VkImageCreateInfo values.
-
To determine the memory requirements for a buffer resource, call:
// Provided by VK_VERSION_1_1
void vkGetBufferMemoryRequirements2(
VkDevice device,
const VkBufferMemoryRequirementsInfo2* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
device
is the logical device that owns the buffer. -
pInfo
is a pointer to a VkBufferMemoryRequirementsInfo2 structure containing parameters required for the memory requirements query. -
pMemoryRequirements
is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.
To determine the memory requirements for a buffer resource without creating an object, call:
// Provided by VK_VERSION_1_3
void vkGetDeviceBufferMemoryRequirements(
VkDevice device,
const VkDeviceBufferMemoryRequirements* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
device
is the logical device intended to own the buffer. -
pInfo
is a pointer to a VkDeviceBufferMemoryRequirements structure containing parameters required for the memory requirements query. -
pMemoryRequirements
is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the buffer object are returned.
The VkBufferMemoryRequirementsInfo2
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBufferMemoryRequirementsInfo2 {
VkStructureType sType;
const void* pNext;
VkBuffer buffer;
} VkBufferMemoryRequirementsInfo2;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
buffer
is the buffer to query.
The VkDeviceBufferMemoryRequirements
structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkDeviceBufferMemoryRequirements {
VkStructureType sType;
const void* pNext;
const VkBufferCreateInfo* pCreateInfo;
} VkDeviceBufferMemoryRequirements;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pCreateInfo
is a pointer to a VkBufferCreateInfo structure containing parameters affecting creation of the buffer to query.
To determine the memory requirements for an image resource, call:
// Provided by VK_VERSION_1_1
void vkGetImageMemoryRequirements2(
VkDevice device,
const VkImageMemoryRequirementsInfo2* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
device
is the logical device that owns the image. -
pInfo
is a pointer to a VkImageMemoryRequirementsInfo2 structure containing parameters required for the memory requirements query. -
pMemoryRequirements
is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the image object are returned.
To determine the memory requirements for an image resource without creating an object, call:
// Provided by VK_VERSION_1_3
void vkGetDeviceImageMemoryRequirements(
VkDevice device,
const VkDeviceImageMemoryRequirements* pInfo,
VkMemoryRequirements2* pMemoryRequirements);
-
device
is the logical device intended to own the image. -
pInfo
is a pointer to a VkDeviceImageMemoryRequirements structure containing parameters required for the memory requirements query. -
pMemoryRequirements
is a pointer to a VkMemoryRequirements2 structure in which the memory requirements of the image object are returned.
The VkImageMemoryRequirementsInfo2
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImageMemoryRequirementsInfo2 {
VkStructureType sType;
const void* pNext;
VkImage image;
} VkImageMemoryRequirementsInfo2;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
image
is the image to query.
The VkDeviceImageMemoryRequirements
structure is defined as:
// Provided by VK_VERSION_1_3
typedef struct VkDeviceImageMemoryRequirements {
VkStructureType sType;
const void* pNext;
const VkImageCreateInfo* pCreateInfo;
VkImageAspectFlagBits planeAspect;
} VkDeviceImageMemoryRequirements;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
pCreateInfo
is a pointer to a VkImageCreateInfo structure containing parameters affecting creation of the image to query. -
planeAspect
is a VkImageAspectFlagBits value specifying the aspect corresponding to the image plane to query. This parameter is ignored unlesspCreateInfo
::flags
hasVK_IMAGE_CREATE_DISJOINT_BIT
set.
To determine the memory requirements for a plane of a disjoint image, add a
VkImagePlaneMemoryRequirementsInfo
structure to the pNext
chain
of the VkImageMemoryRequirementsInfo2
structure.
The VkImagePlaneMemoryRequirementsInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkImagePlaneMemoryRequirementsInfo {
VkStructureType sType;
const void* pNext;
VkImageAspectFlagBits planeAspect;
} VkImagePlaneMemoryRequirementsInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
planeAspect
is a VkImageAspectFlagBits value specifying the aspect corresponding to the image plane to query.
The VkMemoryRequirements2
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkMemoryRequirements2 {
VkStructureType sType;
void* pNext;
VkMemoryRequirements memoryRequirements;
} VkMemoryRequirements2;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
memoryRequirements
is a VkMemoryRequirements structure describing the memory requirements of the resource.
The VkMemoryDedicatedRequirements
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkMemoryDedicatedRequirements {
VkStructureType sType;
void* pNext;
VkBool32 prefersDedicatedAllocation;
VkBool32 requiresDedicatedAllocation;
} VkMemoryDedicatedRequirements;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
prefersDedicatedAllocation
specifies that the implementation would prefer a dedicated allocation for this resource. The application is still free to suballocate the resource but it may get better performance if a dedicated allocation is used. -
requiresDedicatedAllocation
specifies that a dedicated allocation is required for this resource.
To determine the dedicated allocation requirements of a buffer or image
resource, add a VkMemoryDedicatedRequirements structure to the
pNext
chain of the VkMemoryRequirements2 structure passed as the
pMemoryRequirements
parameter of vkGetBufferMemoryRequirements2
or vkGetImageMemoryRequirements2, respectively.
Constraints on the values returned for buffer resources are:
-
requiresDedicatedAllocation
may beVK_TRUE
if thepNext
chain of VkBufferCreateInfo for the call tovkCreateBuffer
used to create the buffer being queried included a VkExternalMemoryBufferCreateInfo structure, and any of the handle types specified in VkExternalMemoryBufferCreateInfo::handleTypes
requires dedicated allocation, as reported by vkGetPhysicalDeviceExternalBufferProperties inVkExternalBufferProperties
::externalMemoryProperties.externalMemoryFeatures
. Otherwise,requiresDedicatedAllocation
will beVK_FALSE
. -
When the implementation sets
requiresDedicatedAllocation
toVK_TRUE
, it must also setprefersDedicatedAllocation
toVK_TRUE
. -
If
VK_BUFFER_CREATE_SPARSE_BINDING_BIT
was set in VkBufferCreateInfo::flags
whenbuffer
was created, then bothprefersDedicatedAllocation
andrequiresDedicatedAllocation
will beVK_FALSE
.
Constraints on the values returned for image resources are:
-
requiresDedicatedAllocation
may beVK_TRUE
if thepNext
chain of VkImageCreateInfo for the call to vkCreateImage used to create the image being queried included a VkExternalMemoryImageCreateInfo structure, and any of the handle types specified in VkExternalMemoryImageCreateInfo::handleTypes
requires dedicated allocation, as reported by vkGetPhysicalDeviceImageFormatProperties2 inVkExternalImageFormatProperties
::externalMemoryProperties.externalMemoryFeatures
. -
requiresDedicatedAllocation
will otherwise beVK_FALSE
-
If
VK_IMAGE_CREATE_SPARSE_BINDING_BIT
was set in VkImageCreateInfo::flags
whenimage
was created, then bothprefersDedicatedAllocation
andrequiresDedicatedAllocation
will beVK_FALSE
.
To attach memory to a buffer object, call:
// Provided by VK_VERSION_1_0
VkResult vkBindBufferMemory(
VkDevice device,
VkBuffer buffer,
VkDeviceMemory memory,
VkDeviceSize memoryOffset);
-
device
is the logical device that owns the buffer and memory. -
buffer
is the buffer to be attached to memory. -
memory
is a VkDeviceMemory object describing the device memory to attach. -
memoryOffset
is the start offset of the region ofmemory
which is to be bound to the buffer. The number of bytes returned in theVkMemoryRequirements
::size
member inmemory
, starting frommemoryOffset
bytes, will be bound to the specified buffer.
vkBindBufferMemory
is equivalent to passing the same parameters
through VkBindBufferMemoryInfo to vkBindBufferMemory2.
To attach memory to buffer objects for one or more buffers at a time, call:
// Provided by VK_VERSION_1_1
VkResult vkBindBufferMemory2(
VkDevice device,
uint32_t bindInfoCount,
const VkBindBufferMemoryInfo* pBindInfos);
-
device
is the logical device that owns the buffers and memory. -
bindInfoCount
is the number of elements inpBindInfos
. -
pBindInfos
is a pointer to an array ofbindInfoCount
VkBindBufferMemoryInfo structures describing buffers and memory to bind.
On some implementations, it may be more efficient to batch memory bindings into a single command.
Note
If |
VkBindBufferMemoryInfo
contains members corresponding to the
parameters of vkBindBufferMemory.
The VkBindBufferMemoryInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindBufferMemoryInfo {
VkStructureType sType;
const void* pNext;
VkBuffer buffer;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
} VkBindBufferMemoryInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
buffer
is the buffer to be attached to memory. -
memory
is a VkDeviceMemory object describing the device memory to attach. -
memoryOffset
is the start offset of the region ofmemory
which is to be bound to the buffer. The number of bytes returned in theVkMemoryRequirements
::size
member inmemory
, starting frommemoryOffset
bytes, will be bound to the specified buffer.
The VkBindBufferMemoryDeviceGroupInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindBufferMemoryDeviceGroupInfo {
VkStructureType sType;
const void* pNext;
uint32_t deviceIndexCount;
const uint32_t* pDeviceIndices;
} VkBindBufferMemoryDeviceGroupInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
deviceIndexCount
is the number of elements inpDeviceIndices
. -
pDeviceIndices
is a pointer to an array of device indices.
If the pNext
chain of VkBindBufferMemoryInfo includes a
VkBindBufferMemoryDeviceGroupInfo
structure, then that structure
determines how memory is bound to buffers across multiple devices in a
device group.
If deviceIndexCount
is greater than zero, then on device index i
the buffer is attached to the instance of memory
on the physical
device with device index pDeviceIndices
[i].
If deviceIndexCount
is zero and memory
comes from a memory heap
with the VK_MEMORY_HEAP_MULTI_INSTANCE_BIT
bit set, then it is as if
pDeviceIndices
contains consecutive indices from zero to the number of
physical devices in the logical device, minus one.
In other words, by default each physical device attaches to its own instance
of memory
.
If deviceIndexCount
is zero and memory
comes from a memory heap
without the VK_MEMORY_HEAP_MULTI_INSTANCE_BIT
bit set, then it is as
if pDeviceIndices
contains an array of zeros.
In other words, by default each physical device attaches to instance zero.
To attach memory to a VkImage
object created without the
VK_IMAGE_CREATE_DISJOINT_BIT
set, call:
// Provided by VK_VERSION_1_0
VkResult vkBindImageMemory(
VkDevice device,
VkImage image,
VkDeviceMemory memory,
VkDeviceSize memoryOffset);
-
device
is the logical device that owns the image and memory. -
image
is the image. -
memory
is the VkDeviceMemory object describing the device memory to attach. -
memoryOffset
is the start offset of the region ofmemory
which is to be bound to the image. The number of bytes returned in theVkMemoryRequirements
::size
member inmemory
, starting frommemoryOffset
bytes, will be bound to the specified image.
vkBindImageMemory
is equivalent to passing the same parameters through
VkBindImageMemoryInfo to vkBindImageMemory2.
To attach memory to image objects for one or more images at a time, call:
// Provided by VK_VERSION_1_1
VkResult vkBindImageMemory2(
VkDevice device,
uint32_t bindInfoCount,
const VkBindImageMemoryInfo* pBindInfos);
-
device
is the logical device that owns the images and memory. -
bindInfoCount
is the number of elements inpBindInfos
. -
pBindInfos
is a pointer to an array of VkBindImageMemoryInfo structures, describing images and memory to bind.
On some implementations, it may be more efficient to batch memory bindings into a single command.
Note
If |
VkBindImageMemoryInfo
contains members corresponding to the parameters
of vkBindImageMemory.
The VkBindImageMemoryInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindImageMemoryInfo {
VkStructureType sType;
const void* pNext;
VkImage image;
VkDeviceMemory memory;
VkDeviceSize memoryOffset;
} VkBindImageMemoryInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
image
is the image to be attached to memory. -
memory
is a VkDeviceMemory object describing the device memory to attach. -
memoryOffset
is the start offset of the region ofmemory
which is to be bound to the image. The number of bytes returned in theVkMemoryRequirements
::size
member inmemory
, starting frommemoryOffset
bytes, will be bound to the specified image.
The VkBindImageMemoryDeviceGroupInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindImageMemoryDeviceGroupInfo {
VkStructureType sType;
const void* pNext;
uint32_t deviceIndexCount;
const uint32_t* pDeviceIndices;
uint32_t splitInstanceBindRegionCount;
const VkRect2D* pSplitInstanceBindRegions;
} VkBindImageMemoryDeviceGroupInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
deviceIndexCount
is the number of elements inpDeviceIndices
. -
pDeviceIndices
is a pointer to an array of device indices. -
splitInstanceBindRegionCount
is the number of elements inpSplitInstanceBindRegions
. -
pSplitInstanceBindRegions
is a pointer to an array of VkRect2D structures describing which regions of the image are attached to each instance of memory.
If the pNext
chain of VkBindImageMemoryInfo includes a
VkBindImageMemoryDeviceGroupInfo
structure, then that structure
determines how memory is bound to images across multiple devices in a device
group.
If deviceIndexCount
is greater than zero, then on device index i
image
is attached to the instance of the memory on the physical device
with device index pDeviceIndices
[i].
Let N be the number of physical devices in the logical device.
If splitInstanceBindRegionCount
is greater than zero, then
pSplitInstanceBindRegions
is a pointer to an array of N2
rectangles, where the image region specified by the rectangle at element
i*N+j in resource instance i is bound to the memory instance
j.
The blocks of the memory that are bound to each sparse image block region
use an offset in memory, relative to memoryOffset
, computed as if the
whole image was being bound to a contiguous range of memory.
In other words, horizontally adjacent image blocks use consecutive blocks of
memory, vertically adjacent image blocks are separated by the number of
bytes per block multiplied by the width in blocks of image
, and the
block at (0,0) corresponds to memory starting at memoryOffset
.
If splitInstanceBindRegionCount
and deviceIndexCount
are zero
and the memory comes from a memory heap with the
VK_MEMORY_HEAP_MULTI_INSTANCE_BIT
bit set, then it is as if
pDeviceIndices
contains consecutive indices from zero to the number of
physical devices in the logical device, minus one.
In other words, by default each physical device attaches to its own instance
of the memory.
If splitInstanceBindRegionCount
and deviceIndexCount
are zero
and the memory comes from a memory heap without the
VK_MEMORY_HEAP_MULTI_INSTANCE_BIT
bit set, then it is as if
pDeviceIndices
contains an array of zeros.
In other words, by default each physical device attaches to instance zero.
In order to bind planes of a disjoint image, add a
VkBindImagePlaneMemoryInfo
structure to the pNext
chain of
VkBindImageMemoryInfo.
The VkBindImagePlaneMemoryInfo
structure is defined as:
// Provided by VK_VERSION_1_1
typedef struct VkBindImagePlaneMemoryInfo {
VkStructureType sType;
const void* pNext;
VkImageAspectFlagBits planeAspect;
} VkBindImagePlaneMemoryInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
planeAspect
is aVkImageAspectFlagBits
value specifying the aspect of the disjoint image plane to bind.
The implementation-dependent limit bufferImageGranularity
specifies a page-like granularity at which
linear and non-linear resources must be placed in adjacent memory locations
to avoid aliasing.
Two resources which do not satisfy this granularity requirement are said to
alias.
bufferImageGranularity
is specified in bytes, and must be a power of
two.
Implementations which do not impose a granularity restriction may report a
bufferImageGranularity
value of one.
Note
Despite its name, |
Given resourceA at the lower memory offset and resourceB at the higher
memory offset in the same VkDeviceMemory
object, where one resource is
linear and the other is non-linear (as defined in the
Glossary), and the following:
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:
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
bufferImageGranularity
.
bufferImageGranularity
may be different than the physical page size
of the memory heap.
This restriction is only needed when a linear resource and a non-linear
resource are adjacent in memory and will be used simultaneously.
The memory ranges of adjacent resources can be closer than
bufferImageGranularity
, provided they meet the 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 bufferImageGranularity
.
Therefore, memory bound to sparse resources naturally satisfies the
bufferImageGranularity
.
12.7. Resource Sharing Mode
Buffer and image objects are created with a sharing mode controlling how they can be accessed from queues. The supported sharing modes are:
// Provided by VK_VERSION_1_0
typedef enum VkSharingMode {
VK_SHARING_MODE_EXCLUSIVE = 0,
VK_SHARING_MODE_CONCURRENT = 1,
} VkSharingMode;
-
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. -
VK_SHARING_MODE_CONCURRENT
specifies that concurrent access to any range or image subresource of the object from multiple queue families is supported.
Note
|
Ranges of buffers and image subresources of image objects created using
VK_SHARING_MODE_EXCLUSIVE
must only be accessed by queues in the
queue family that has ownership of the resource.
Upon creation, such resources are not owned by any queue family; ownership
is implicitly acquired upon first use within a queue.
Once a resource using VK_SHARING_MODE_EXCLUSIVE
is owned by some queue
family, the application must perform a
queue family ownership transfer to make
the memory contents of a range or image subresource accessible to a
different queue family.
Note
Images still require a layout transition from
|
A queue family can take ownership of an image subresource or buffer range
of a resource created with VK_SHARING_MODE_EXCLUSIVE
, without an
ownership transfer, in the same way as for a resource that was just created;
however, taking ownership in this way has the effect that the contents of
the image subresource or buffer range are undefined.
Ranges of buffers and image subresources of image objects created using
VK_SHARING_MODE_CONCURRENT
must only be accessed by queues from the
queue families specified through the queueFamilyIndexCount
and
pQueueFamilyIndices
members of the corresponding create info
structures.
12.7.1. External Resource Sharing
Resources should only be accessed in the Vulkan instance that has exclusive
ownership of their underlying memory.
Only one Vulkan instance has exclusive ownership of a resource’s underlying
memory at a given time, regardless of whether the resource was created using
VK_SHARING_MODE_EXCLUSIVE
or VK_SHARING_MODE_CONCURRENT
.
Applications can transfer ownership of a resource’s underlying memory only
if the memory has been imported from or exported to another instance or
external API using external memory handles.
The semantics for transferring ownership outside of the instance are similar
to those used for transferring ownership of VK_SHARING_MODE_EXCLUSIVE
resources between queues, and is also accomplished using
VkBufferMemoryBarrier or VkImageMemoryBarrier operations.
To make the contents of the underlying memory accessible in the destination
instance or API, applications must
-
Release exclusive ownership from the source instance or API.
-
Ensure the release operation has completed using semaphores or fences.
-
Acquire exclusive ownership in the destination instance or API
Unlike queue ownership transfers, the destination instance or API is not
specified explicitly when releasing ownership, nor is the source instance or
API specified when acquiring ownership.
Instead, the image or memory barrier’s dstQueueFamilyIndex
or
srcQueueFamilyIndex
parameters are set to the reserved queue family
index VK_QUEUE_FAMILY_EXTERNAL
to represent the external destination or source respectively.
Binding a resource to a memory object shared between multiple Vulkan instances or other APIs does not change the ownership of the underlying memory. The first entity to access the resource implicitly acquires ownership. An entity can also implicitly take ownership from another entity in the same way without an explicit ownership transfer. However, taking ownership in this way has the effect that the contents of the underlying memory are undefined.
Accessing a resource backed by memory that is owned by a particular instance
or API has the same semantics as accessing a VK_SHARING_MODE_EXCLUSIVE
resource, with one exception: Implementations must ensure layout
transitions performed on one member of a set of identical subresources of
identical images that alias the same range of an underlying memory object
affect the layout of all the subresources in the set.
As a corollary, writes to any image subresources in such a set must not
make the contents of memory used by other subresources in the set
undefined.
An application can define the content of a subresource of one image by
performing device writes to an identical subresource of another image
provided both images are bound to the same region of external memory.
Applications may also add resources to such a set after the content of the
existing set members has been defined without making the content undefined
by creating a new image with the initial layout
VK_IMAGE_LAYOUT_UNDEFINED
and binding it to the same region of
external memory as the existing images.
Note
Because layout transitions apply to all identical images aliasing the same region of external memory, the actual layout of the memory backing a new image as well as an existing image with defined content will not be undefined. Such an image is not usable until it acquires ownership of its memory from the existing owner. Therefore, the layout specified as part of this transition will be the true initial layout of the image. The undefined layout specified when creating it is a placeholder to simplify valid usage requirements. |
12.8. Memory Aliasing
A range of a VkDeviceMemory
allocation is aliased if it is bound to
multiple resources simultaneously, as described below, via
vkBindImageMemory, vkBindBufferMemory,
via sparse memory bindings, or by binding
the memory to resources in multiple Vulkan instances or external APIs using
external memory handle export and import mechanisms.
Consider two resources, resourceA and resourceB, bound respectively to
memory rangeA and rangeB.
Let paddedRangeA and paddedRangeB be, respectively, rangeA and
rangeB aligned to bufferImageGranularity
.
If the resources are both linear or both non-linear (as defined in the
Glossary), then the resources alias the
memory in the intersection of rangeA and rangeB.
If one resource is linear and the other is non-linear, then the resources
alias the memory in the intersection of paddedRangeA and paddedRangeB.
Applications can alias memory, but use of multiple aliases is subject to several constraints.
Note
Memory aliasing can be useful to reduce the total device memory footprint of an application, if some large resources are used for disjoint periods of time. |
When a non-linear,
non-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 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
VK_IMAGE_LAYOUT_PREINITIALIZED
or VK_IMAGE_LAYOUT_GENERAL
layouts, are host-accessible subresources.
That is, the host has a well-defined addressing scheme to interpret the
contents, and thus the layout of the data in memory can be consistently
interpreted across aliases if each of those aliases is a host-accessible
subresource.
Non-linear images, and linear image subresources in other layouts, are not
host-accessible.
If two aliases are both host-accessible, then they interpret the contents of the memory in consistent ways, and data written to one alias can be read by the other alias.
If two aliases are both images that were created with identical creation
parameters, both were created with the VK_IMAGE_CREATE_ALIAS_BIT
flag
set, and both are bound identically to memory
except for VkBindImageMemoryDeviceGroupInfo::pDeviceIndices
and
VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions
,
then they interpret the contents of the memory in consistent ways, and data
written to one alias can be read by the other alias.
Additionally, if an individual plane of a multi-planar image and a single-plane image alias the same memory, then they also interpret the contents of the memory in consistent ways under the same conditions, but with the following modifications:
-
Both must have been created with the
VK_IMAGE_CREATE_DISJOINT_BIT
flag. -
The single-plane image must have a VkFormat that is equivalent to that of the multi-planar image’s individual plane.
-
The single-plane image and the individual plane of the multi-planar image must be bound identically to memory except for VkBindImageMemoryDeviceGroupInfo::
pDeviceIndices
and VkBindImageMemoryDeviceGroupInfo::pSplitInstanceBindRegions
. -
The
width
andheight
of the single-plane image are derived from the multi-planar image’s dimensions in the manner listed for plane compatibility for the aliased plane. -
All other creation parameters must be identical
Aliases created by binding the same memory to resources in multiple Vulkan instances or external APIs using external memory handle export and import mechanisms interpret the contents of the memory in consistent ways, and data written to one alias can be read by the other alias.
Otherwise, the aliases interpret the contents of the memory differently, and writes via one alias make the contents of memory partially or completely undefined to the other alias. If the first alias is a host-accessible subresource, then the bytes affected are those written by the memory operations according to its addressing scheme. If the first alias is not host-accessible, then the bytes affected are those overlapped by the image subresources that were written. If the second alias is a host-accessible subresource, the affected bytes become undefined. If the second alias is not host-accessible, all sparse image blocks (for sparse partially-resident images) or all image subresources (for non-sparse image and fully resident sparse images) that overlap the affected bytes become undefined.
If any image subresources are made undefined due to writes to an alias,
then each of those image subresources must have its layout transitioned
from VK_IMAGE_LAYOUT_UNDEFINED
to a valid layout before it is used, or
from 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
VK_ATTACHMENT_DESCRIPTION_MAY_ALIAS_BIT
, and
follow the other rules listed in that section.
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. |
12.8.1. Resource Memory Overlap
Applications can safely access a resource concurrently as long as the memory locations do not overlap as defined in Memory Location. This includes aliased resources if such aliasing is well-defined. It also includes access from different queues and/or queue families if such concurrent access is supported by the resource. Transfer commands only access memory locations specified by the range of the transfer command.
Note
The intent is that buffers (or linear images) can be accessed concurrently, even when they share cache lines, but otherwise do not access the same memory range. The concept of a device cache line size is not exposed in the memory model. |