Struct vulkano::image::attachment::AttachmentImage

pub struct AttachmentImage<F = Format, A = StdMemoryPoolAlloc> { /* fields omitted */ }

ImageAccess whose purpose is to be used as a framebuffer attachment.

The image is always two-dimensional and has only one mipmap, but it can have any kind of format. Trying to use a format that the backend doesn't support for rendering will result in an error being returned when creating the image. Once you have an AttachmentImage, you are guaranteed that you will be able to draw on it.

The template parameter of AttachmentImage is a type that describes the format of the image.

Regular vs transient

Calling AttachmentImage::new will create a regular image, while calling AttachmentImage::transient will create a transient image. Transient image are only relevant for images that serve as attachments, so AttachmentImage is the only type of image in vulkano that provides a shortcut for this.

A transient image is a special kind of image whose content is undefined outside of render passes. Once you finish drawing, reading from it will returned undefined data (which can be either valid or garbage, depending on the implementation).

This gives a hint to the Vulkan implementation that it is possible for the image's content to live exclusively in some cache memory, and that no real memory has to be allocated for it.

In other words, if you are going to read from the image after drawing to it, use a regular image. If you don't need to read from it (for example if it's some kind of intermediary color, or a depth buffer that is only used once) then use a transient image as it may improve performances.

Methods

impl<F> AttachmentImage<F>

fn new(
    device: Arc<Device>,
    dimensions: [u32; 2],
    format: F
) -> Result<Arc<AttachmentImage<F>>, ImageCreationError> where
    F: FormatDesc, 

Creates a new image with the given dimensions and format.

Returns an error if the dimensions are too large or if the backend doesn't support this format as a framebuffer attachment.

fn multisampled(
    device: Arc<Device>,
    dimensions: [u32; 2],
    samples: u32,
    format: F
) -> Result<Arc<AttachmentImage<F>>, ImageCreationError> where
    F: FormatDesc, 

Same as new, but creates a multisampled image.

Note: You can also use this function and pass 1 for the number of samples if you want a regular image.

fn with_usage(
    device: Arc<Device>,
    dimensions: [u32; 2],
    format: F,
    usage: ImageUsage
) -> Result<Arc<AttachmentImage<F>>, ImageCreationError> where
    F: FormatDesc, 

Same as new, but lets you specify additional usages.

fn multisampled_with_usage(
    device: Arc<Device>,
    dimensions: [u32; 2],
    samples: u32,
    format: F,
    usage: ImageUsage
) -> Result<Arc<AttachmentImage<F>>, ImageCreationError> where
    F: FormatDesc, 

Same as with_usage, but creates a multisampled image.

Note: You can also use this function and pass 1 for the number of samples if you want a regular image.

fn transient(
    device: Arc<Device>,
    dimensions: [u32; 2],
    format: F
) -> Result<Arc<AttachmentImage<F>>, ImageCreationError> where
    F: FormatDesc, 

Same as new, except that the image will be transient.

A transient image is special because its content is undefined outside of a render pass. This means that the implementation has the possibility to not allocate any memory for it.

fn transient_multisampled(
    device: Arc<Device>,
    dimensions: [u32; 2],
    samples: u32,
    format: F
) -> Result<Arc<AttachmentImage<F>>, ImageCreationError> where
    F: FormatDesc, 

Same as transient, but creates a multisampled image.

Note: You can also use this function and pass 1 for the number of samples if you want a regular image.

impl<F, A> AttachmentImage<F, A>

fn dimensions(&self) -> [u32; 2]

Returns the dimensions of the image.

Trait Implementations

impl<F: Debug, A: Debug> Debug for AttachmentImage<F, A>

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.