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
pre-initialized 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.
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
.