117 lines
5.7 KiB
Plaintext
117 lines
5.7 KiB
Plaintext
// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
VkImageLayout(3)
|
|
================
|
|
|
|
Name
|
|
----
|
|
VkImageLayout - Layout of image and image subresources
|
|
|
|
C Specification
|
|
---------------
|
|
|
|
// refBegin VkImageLayout - Layout of image and image subresources
|
|
|
|
The set of image layouts consists of:
|
|
|
|
include::../api/enums/VkImageLayout.txt[]
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
The type(s) of device access supported by each layout are:
|
|
|
|
* ename:VK_IMAGE_LAYOUT_UNDEFINED: Supports no device access. This layout
|
|
must: only be used as the pname:initialLayout member of
|
|
sname:VkImageCreateInfo or sname:VkAttachmentDescription, or as the pname:oldLayout
|
|
in an image transition. When transitioning out of this layout, the
|
|
contents of the memory are not guaranteed to be preserved.
|
|
* ename:VK_IMAGE_LAYOUT_PREINITIALIZED: Supports no device access. This
|
|
layout must: only be used as the pname:initialLayout member of
|
|
sname:VkImageCreateInfo or sname:VkAttachmentDescription, or as the
|
|
pname:oldLayout in an image transition. When transitioning out of this
|
|
layout, the contents of the memory are preserved. This
|
|
layout is intended to be used as the initial layout for an image whose
|
|
contents are written by the host, and hence the data can: be written to
|
|
memory immediately, without first executing a layout transition.
|
|
Currently, ename:VK_IMAGE_LAYOUT_PREINITIALIZED is only useful with
|
|
ename:VK_IMAGE_TILING_LINEAR images because there is not a standard
|
|
layout defined for ename:VK_IMAGE_TILING_OPTIMAL images.
|
|
* ename:VK_IMAGE_LAYOUT_GENERAL: Supports all types of device access.
|
|
* ename:VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL: must: only be used as a
|
|
color or resolve attachment in a sname:VkFramebuffer. This layout is
|
|
valid only for image subresources of images created with the
|
|
ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL: must: only be
|
|
used as a depth/stencil attachment in a sname:VkFramebuffer. This layout
|
|
is valid only for image subresources of images created with the
|
|
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL: must: only be
|
|
used as a read-only depth/stencil attachment in a sname:VkFramebuffer
|
|
and/or as a read-only image in a shader (which can: be read as a sampled
|
|
image, combined image/sampler and/or input attachment). This layout is
|
|
valid only for image subresources of images created with the
|
|
ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL: must: only be used as a
|
|
read-only image in a shader (which can: be read as a sampled image,
|
|
combined image/sampler and/or input attachment). This layout is valid
|
|
only for image subresources of images created with the
|
|
ename:VK_IMAGE_USAGE_SAMPLED_BIT or
|
|
ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL: must: only be used as a
|
|
source image of a transfer command (see the definition of
|
|
<<synchronization-transfer,ename:VK_PIPELINE_STAGE_TRANSFER_BIT>>).
|
|
This layout is valid only for image subresources of images created with
|
|
the ename:VK_IMAGE_USAGE_TRANSFER_SRC_BIT usage bit enabled.
|
|
* ename:VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL: must: only be used as a
|
|
destination image of a transfer command. This layout is valid only for
|
|
image subresources of images created with the
|
|
ename:VK_IMAGE_USAGE_TRANSFER_DST_BIT usage bit enabled.
|
|
include::../chapters/VK_KHR_swapchain/VkImageLayout_swapchain.txt[]
|
|
|
|
For each mechanism of accessing an image in the API, there is a parameter or
|
|
structure member that controls the image layout used to access the image.
|
|
For transfer commands, this is a parameter to the command (see <<clears>>
|
|
and <<copies>>). For use as a framebuffer attachment, this is a member in
|
|
the substructures of the sname:VkRenderPassCreateInfo (see
|
|
<<renderpass,Render Pass>>). For use in a descriptor set, this is a member
|
|
in the sname:VkDescriptorImageInfo structure (see
|
|
<<descriptorsets-updates>>). At the time that any command buffer command
|
|
accessing an image executes on any queue, the layouts of the image
|
|
subresources that are accessed must: all match the layout specified via the
|
|
API controlling those accesses.
|
|
|
|
The image layout of each image subresource must: be well-defined at each
|
|
point in the image subresource's lifetime. This means that when performing a
|
|
layout transition on the image subresource, the old layout value must:
|
|
either equal the current layout of the image subresource (at the time the
|
|
transition executes), or else be ename:VK_IMAGE_LAYOUT_UNDEFINED (implying
|
|
that the contents of the image subresource need not be preserved). The new
|
|
layout used in a transition mustnot: be ename:VK_IMAGE_LAYOUT_UNDEFINED or
|
|
ename:VK_IMAGE_LAYOUT_PREINITIALIZED.
|
|
|
|
// refEnd VkImageLayout
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
slink:VkAttachmentDescription, slink:VkAttachmentReference, slink:VkDescriptorImageInfo, slink:VkImageCreateInfo, slink:VkImageMemoryBarrier, flink:vkCmdBlitImage, flink:vkCmdClearColorImage, flink:vkCmdClearDepthStencilImage, flink:vkCmdCopyBufferToImage, flink:vkCmdCopyImage, flink:vkCmdCopyImageToBuffer, flink:vkCmdResolveImage
|
|
|
|
|
|
Document Notes
|
|
--------------
|
|
|
|
For more information, see the Vulkan Specification at URL
|
|
|
|
https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#VkImageLayout
|
|
|
|
This page is extracted from the Vulkan Specification.
|
|
Fixes and changes should be made to the Specification,not directly.
|
|
|
|
include::footer.txt[]
|
|
|