VkImageLayout(3)
================

Name
----
VkImageLayout - Specifies what layout an image object (or a sub-range of it) is in.

C Specification
---------------

include::../enums/VkImageLayout.txt[]

Constants
---------

VK_IMAGE_LAYOUT_UNDEFINED::
    The contents of images (or a sub-range of it) in this layout are undefined. +
    This is the layout all images are assumed to be in right after creation, or when their memory
    binding is changed. +
    Any operation performed on an image sub-range in this layout leaves the contents of it undefined.
    Applications need to transition an image sub-range to another layout before being able to perform
    any operations on it that should result in defined contents.

VK_IMAGE_LAYOUT_GENERAL::
    An image (or a sub-range of it) in this layout allows all operations to be performed on the image
    sub-range that is otherwise permitted by the usage flags the image object was created with (see
    elink:VkImageUsageFlags for more detail).

VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL::
    An image (or a sub-range of it) in this layout can only be used as a framebuffer color attachment
    and as such can only be accessed through framebuffer color reads and writes resulting from the
    issuing of draw commands, fname:vkCmdClearAttachments, and through clearing writes resulting from the use of
    the ename:VK_ATTACHMENT_LOAD_OP_CLEAR framebuffer attachment load operation.

VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL::
    An image (or a sub-range of it) in this layout can only be used as a framebuffer depth/stencil
    attachment and as such can only be accessed through framebuffer depth/stencil reads and writes
    resulting from the issuing of draw commands, fname:vkCmdClearAttachments, and through clearing writes resulting from the use of
    the ename:VK_ATTACHMENT_LOAD_OP_CLEAR framebuffer attachment load operation.

VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL::
    An image (or a sub-range of it) in this layout can only be used as a read-only framebuffer
    depth/stencil attachment and as such can only be accessed through framebuffer depth/stencil reads
    resulting from the issuing of draw commands, and through shader reads done via a sampled image
    descriptor, combined image sampler descriptor, or read-only storage image descriptor (see
    elink:VkDescriptorType for more detail).

VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL::
    An image (or a sub-range of it) in this layout can only be used as a read-only shader resource and
    as such can only be accessed by shader reads done via a sampled image descriptor, combined image
    sampler descriptor, or read-only storage image descriptor (see elink:VkDescriptorType for more detail).

VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL::
    An image (or a sub-range of it) in this layout can only be used as the source operand of the
    commands flink:vkCmdCopyImage, flink:vkCmdBlitImage, flink:vkCmdCopyImageToBuffer,
    and flink:vkCmdResolveImage.

VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL::
    An image (or a sub-range of it) in this layout can only be used as the destination operand of the
    commands flink:vkCmdCopyImage, flink:vkCmdBlitImage, flink:vkCmdCopyBufferToImage, flink:vkCmdResolveImage,
    flink:vkCmdClearColorImage, and flink:vkCmdClearDepthStencilImage.

Description
-----------

The constants of this enumeration are used to identify the layout an image object (or a sub-range of it)
is expected to be in at any given time, or used to specify the destination layout an image sub-range
should be transitioned to as the result of an image memory barrier (see slink:VkImageMemoryBarrier for more
details).

Performing any operation on an image sub-range that isn't permitted by the layout the image sub-range is
currently in is undefined.

If any operation tries to read from an image sub-range that isn't in the expected image layout results
in undefined data to be returned as the result of the read.

If any operation tries to write to or perform an atomic operation on an image sub-range that isn't in the
expected image layout results in the contents of the whole image to become undefined, i.e. the whole image
is logically transitioned to the ename:VK_IMAGE_LAYOUT_UNDEFINED layout.

See Also
--------

slink:VkImageMemoryBarrier

include::footer.txt[]