C Specification
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_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL = 1000117000,
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL = 1000117001,
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR = 1000001002,
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR = 1000111000,
VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV = 1000164003,
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT = 1000218000,
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL_KHR = 1000241000,
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR = 1000241001,
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL_KHR = 1000241002,
VK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL_KHR = 1000241003,
VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL,
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL,
VK_IMAGE_LAYOUT_MAX_ENUM = 0x7FFFFFFF
} VkImageLayout;
Description
The type(s) of device access supported by each layout are:
-
VK_IMAGE_LAYOUT_UNDEFINED
does not support device access. This layout must only be used as theinitialLayout
member ofVkImageCreateInfo
orVkAttachmentDescription
, or as theoldLayout
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
does not support device access. This layout must only be used as theinitialLayout
member ofVkImageCreateInfo
orVkAttachmentDescription
, or as theoldLayout
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 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_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_KHR
andVK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL_KHR
. -
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. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR
andVK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL_KHR
. -
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. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_READ_ONLY_OPTIMAL_KHR
andVK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL_KHR
. -
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. It is equivalent toVK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL_KHR
andVK_IMAGE_LAYOUT_STENCIL_READ_ONLY_OPTIMAL_KHR
. -
VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL_KHR
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_KHR
specifies a layout for the depth aspect of a depth/stencil format image allowing read-only access as a depth attachment or in shaders. -
VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL_KHR
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_KHR
specifies a layout for the stencil aspect of a depth/stencil format image allowing read-only access as a stencil attachment or in shaders. -
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 theVK_IMAGE_USAGE_SAMPLED_BIT
orVK_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 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. -
VK_IMAGE_LAYOUT_PRESENT_SRC_KHR
must only be used for presenting a presentable image for display. A swapchain’s image must be transitioned to this layout before calling vkQueuePresentKHR, and must be transitioned away from this layout after calling vkAcquireNextImageKHR. -
VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR
is valid only for shared presentable images, and must be used for any usage the image supports. -
VK_IMAGE_LAYOUT_SHADING_RATE_OPTIMAL_NV
must only be used as a read-only shading-rate-image. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_SHADING_RATE_IMAGE_BIT_NV
usage bit enabled. -
VK_IMAGE_LAYOUT_FRAGMENT_DENSITY_MAP_OPTIMAL_EXT
must only be used as a fragment density map attachment in aVkRenderPass
. This layout is valid only for image subresources of images created with theVK_IMAGE_USAGE_FRAGMENT_DENSITY_MAP_BIT_EXT
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 https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#clears
and https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#copies).
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 https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#descriptorsets-updates).
See Also
VkAttachmentDescription, VkAttachmentDescription2KHR, VkAttachmentDescriptionStencilLayoutKHR, VkAttachmentReference, VkAttachmentReference2KHR, VkAttachmentReferenceStencilLayoutKHR, VkDescriptorImageInfo, VkImageCreateInfo, VkImageMemoryBarrier, vkCmdBindShadingRateImageNV, vkCmdBlitImage, vkCmdClearColorImage, vkCmdClearDepthStencilImage, vkCmdCopyBufferToImage, vkCmdCopyImage, vkCmdCopyImageToBuffer, vkCmdResolveImage
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.
Copyright
Copyright (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.