Enum vulkano::image::ImageLayout

#[non_exhaustive]
#[repr(i32)]
pub enum ImageLayout {
    Undefined,
    General,
    ColorAttachmentOptimal,
    DepthStencilAttachmentOptimal,
    DepthStencilReadOnlyOptimal,
    ShaderReadOnlyOptimal,
    TransferSrcOptimal,
    TransferDstOptimal,
    Preinitialized,
    DepthReadOnlyStencilAttachmentOptimal,
    DepthAttachmentStencilReadOnlyOptimal,
    PresentSrc,
}

In-memory layout of the pixel data of an image.

The pixel data of a Vulkan image is arranged in a particular way, which is called its layout. Each image subresource (mipmap level and array layer) in an image can have a different layout, but usually the whole image has its data in the same layout. Layouts are abstract in the sense that the user does not know the specific details of each layout; the device driver is free to implement each layout in the way it sees fit.

The layout of a newly created image is either Undefined or Preinitialized. Every operation that can be performed on an image is only possible with specific layouts, so before the operation is performed, the user must perform a layout transition on the image. This rearranges the pixel data from one layout into another. Layout transitions are performed as part of pipeline barriers in a command buffer.

The General layout is compatible with any operation, so layout transitions are never needed. However, the other layouts, while more restricted, are usually better optimised for a particular type of operation than General, so they are usually preferred.

Vulkan does not keep track of layouts itself, so it is the responsibility of the user to keep track of this information. When performing a layout transition, the previous layout must be specified as well. Some operations allow for different layouts, but require the user to specify which one. Vulkano helps with this by providing sensible defaults, automatically tracking the layout of each image when creating a command buffer, and adding layout transitions where needed.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Undefined

The layout of the data is unknown, and the image is treated as containing no valid data. Transitioning from Undefined will discard any existing pixel data.

General

A general-purpose layout that can be used for any operation. Some operations may only allow General, such as storage images, but many have a more specific layout that is better optimized for that purpose.

ColorAttachmentOptimal

For a color image used as a color or resolve attachment in a framebuffer. Images that are transitioned into this layout must have the color_attachment usage enabled.

DepthStencilAttachmentOptimal

For a depth/stencil image used as a depth/stencil attachment in a framebuffer.

DepthStencilReadOnlyOptimal

For a depth/stencil image used as a read-only depth/stencil attachment in a framebuffer, or as a (combined) sampled image or input attachment in a shader.

ShaderReadOnlyOptimal

For a color image used as a (combined) sampled image or input attachment in a shader. Images that are transitioned into this layout must have the sampled or input_attachment usages enabled.

TransferSrcOptimal

For operations that transfer data from an image (copy, blit).

TransferDstOptimal

For operations that transfer data to an image (copy, blit, clear).

Preinitialized

When creating an image, this specifies that the initial data is going to be directly written to from the CPU. Unlike Undefined, the image is assumed to contain valid data when transitioning from this layout. However, this only works right when the image has linear tiling, optimal tiling gives undefined results.

DepthReadOnlyStencilAttachmentOptimal

A combination of DepthStencilReadOnlyOptimal for the depth aspect of the image, and DepthStencilAttachmentOptimal for the stencil aspect of the image.

DepthAttachmentStencilReadOnlyOptimal

A combination of DepthStencilAttachmentOptimal for the depth aspect of the image, and DepthStencilReadOnlyOptimal for the stencil aspect of the image.

PresentSrc

The layout of images that are held in a swapchain. Images are in this layout when they are acquired from the swapchain, and must be transitioned back into this layout before presenting them.

Trait Implementations

impl Clone for ImageLayout

fn clone(&self) -> ImageLayout

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ImageLayout

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<ImageLayout> for ImageLayout

fn from(val: ImageLayout) -> Self

Converts to this type from the input type.

impl Hash for ImageLayout

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,
    Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq<ImageLayout> for ImageLayout

fn eq(&self, other: &ImageLayout) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<ImageLayout> for ImageLayout

type Error = ()

The type returned in the event of a conversion error.

fn try_from(val: ImageLayout) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for ImageLayout

impl Eq for ImageLayout

impl StructuralEq for ImageLayout

impl StructuralPartialEq for ImageLayout