Images are stored in implementation-dependent opaque layouts in memory.
Implementations may support several opaque layouts, and the layout used at
any given time is determined by the VkImageLayout
state of the image
subresource.
Each layout has limitations on what kinds of operations are supported for
image subresources using the layout.
Applications have control over which layout each image subresource uses, and
can transition an image subresource from one layout to another.
Transitions can happen with an image memory barrier, included as part of a
vkCmdPipelineBarrier
or a vkCmdWaitEvents
command buffer command
(see Section 6.5.6, “Image Memory Barriers”), or as part of a subpass
dependency within a render pass (see VkSubpassDependency
).
The image layout state is per-image subresource, and separate image
subresources of the same image can be in different layouts at the same time
with one exception - depth and stencil aspects of a given image subresource
must always be in the same layout.
![]() | Note |
---|---|
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 images created with
VK_IMAGE_TILING_LINEAR
tiling 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:
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, VK_IMAGE_LAYOUT_PRESENT_SRC_KHR = 1000001002, } VkImageLayout;
The type(s) of device access supported by each layout are:
VK_IMAGE_LAYOUT_UNDEFINED
: Supports no device access.
This layout must only be used as the initialLayout
member of
VkImageCreateInfo
or VkAttachmentDescription
, or as the
oldLayout
in an image transition.
When transitioning out of this layout, the contents of the memory are
not guaranteed to be preserved.
VK_IMAGE_LAYOUT_PREINITIALIZED
: Supports no device access.
This layout must only be used as the initialLayout
member of
VkImageCreateInfo
or VkAttachmentDescription
, or as the
oldLayout
in an image transition.
When transitioning out of this layout, the contents of the memory are
preserved.
This layout is intended to be used as the initial layout for an image
whose contents are written by the host, and hence the data can be
written to memory immediately, without first executing a layout
transition.
Currently, VK_IMAGE_LAYOUT_PREINITIALIZED
is only useful with
VK_IMAGE_TILING_LINEAR
images because there is not a standard
layout defined for VK_IMAGE_TILING_OPTIMAL
images.
VK_IMAGE_LAYOUT_GENERAL
: Supports all types of device access.
VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL
: must only be used as a
color or resolve attachment in a VkFramebuffer
.
This layout is valid only for image subresources of images created with
the VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT
usage bit enabled.
VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL
: must only be
used as a depth/stencil attachment in a VkFramebuffer
.
This layout is valid only for image subresources of images created with
the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
usage bit enabled.
VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
: must only be
used as a read-only depth/stencil attachment in a VkFramebuffer
and/or as a read-only image in a shader (which can be read as a sampled
image, combined image/sampler and/or input attachment).
This layout is valid only for image subresources of images created with
the VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
usage bit enabled.
Only image subresources of images created with
VK_IMAGE_USAGE_SAMPLED_BIT
can be used as sampled image or
combined image/sampler in a shader.
Similarly, only image subresources of images created with
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
can be used as input
attachments.
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
: must only be used as a
read-only image in a shader (which can be read as a sampled image,
combined image/sampler and/or input attachment).
This layout is valid only for image subresources of images created with
the VK_IMAGE_USAGE_SAMPLED_BIT
or
VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT
usage bit enabled.
VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL
: must only be used as a
source image of a transfer command (see the definition of
VK_PIPELINE_STAGE_TRANSFER_BIT
).
This layout is valid only for image subresources of images created with
the VK_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
the VK_IMAGE_USAGE_TRANSFER_DST_BIT
usage bit enabled.
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
: must only be used for presenting
a swapchain image for display.
A swapchain’s image must be transitioned to this layout before calling
vkQueuePresentKHR
, and must be transitioned away from this layout
after calling vkAcquireNextImageKHR
.
For each mechanism of accessing an image in the API, there is a parameter or
structure member that controls the image layout used to access the image.
For transfer commands, this is a parameter to the command (see Chapter 17, Clear Commands
and Chapter 18, 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 Section 13.2.4, “Descriptor Set Updates”).
At the time that any command buffer command accessing an image executes on
any queue, the layouts of the image subresources that are accessed must all
match the layout specified via the API controlling those accesses.
The image layout of each image subresource must be well-defined at each
point in the image subresource’s lifetime.
This means that when performing a layout transition on the image
subresource, the old layout value must either equal the current layout of
the image subresource (at the time the transition executes), or else be
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
.