Struct vulkano::image::attachment::AttachmentImage

pub struct AttachmentImage<A = PotentialDedicatedAllocation<StdMemoryPoolAlloc>> { /* private fields */ }

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 performance.

Implementations

impl AttachmentImage

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

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.

pub fn input_attachment(
    device: Arc<Device>,
    dimensions: [u32; 2],
    format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>

Same as new, but creates an image that can be used as an input attachment.

Note: This function is just a convenient shortcut for with_usage.

pub fn multisampled(
    device: Arc<Device>,
    dimensions: [u32; 2],
    samples: SampleCount,
    format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>

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.

pub fn multisampled_input_attachment(
    device: Arc<Device>,
    dimensions: [u32; 2],
    samples: SampleCount,
    format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>

Same as multisampled, but creates an image that can be used as an input attachment.

Note: This function is just a convenient shortcut for multisampled_with_usage.

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

Same as new, but lets you specify additional usages.

The color_attachment or depth_stencil_attachment usages are automatically added based on the format of the usage. Therefore the usage parameter allows you specify usages in addition to these two.

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

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.

pub fn multisampled_with_usage_with_layers(
    device: Arc<Device>,
    dimensions: [u32; 2],
    array_layers: u32,
    samples: SampleCount,
    format: Format,
    usage: ImageUsage
) -> Result<Arc<AttachmentImage>, ImageCreationError>

Same as multisampled_with_usage, but creates an image with multiple layers.

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

pub fn sampled(
    device: Arc<Device>,
    dimensions: [u32; 2],
    format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>

Same as new, except that the image can later be sampled.

Note: This function is just a convenient shortcut for with_usage.

pub fn sampled_input_attachment(
    device: Arc<Device>,
    dimensions: [u32; 2],
    format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>

Same as sampled, except that the image can be used as an input attachment.

Note: This function is just a convenient shortcut for with_usage.

pub fn sampled_multisampled(
    device: Arc<Device>,
    dimensions: [u32; 2],
    samples: SampleCount,
    format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>

Same as sampled, 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.

Note: This function is just a convenient shortcut for multisampled_with_usage.

pub fn sampled_multisampled_input_attachment(
    device: Arc<Device>,
    dimensions: [u32; 2],
    samples: SampleCount,
    format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>

Same as sampled_multisampled, but creates an image that can be used as an input attachment.

Note: This function is just a convenient shortcut for multisampled_with_usage.

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

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.

Note: This function is just a convenient shortcut for with_usage.

pub fn transient_input_attachment(
    device: Arc<Device>,
    dimensions: [u32; 2],
    format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>

Same as transient, except that the image can be used as an input attachment.

Note: This function is just a convenient shortcut for with_usage.

pub fn transient_multisampled(
    device: Arc<Device>,
    dimensions: [u32; 2],
    samples: SampleCount,
    format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>

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.

Note: This function is just a convenient shortcut for multisampled_with_usage.

pub fn transient_multisampled_input_attachment(
    device: Arc<Device>,
    dimensions: [u32; 2],
    samples: SampleCount,
    format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>

Same as transient_multisampled, but creates an image that can be used as an input attachment.

Note: This function is just a convenient shortcut for multisampled_with_usage.

pub fn new_with_exportable_fd(
    device: Arc<Device>,
    dimensions: [u32; 2],
    array_layers: u32,
    format: Format,
    base_usage: ImageUsage,
    samples: SampleCount
) -> Result<Arc<AttachmentImage>, ImageCreationError>

pub fn export_posix_fd(&self) -> Result<File, DeviceMemoryAllocError>

Exports posix file descriptor for the allocated memory requires khr_external_memory_fd and khr_external_memory extensions to be loaded. Only works on Linux.

pub fn mem_size(&self) -> DeviceSize

Return the size of the allocated memory (used for e.g. with cuda)

Trait Implementations

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

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

Formats the value using the given formatter.

impl<A> Hash for AttachmentImage<A> where
    A: MemoryPoolAlloc, 

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, 

Feeds a slice of this type into the given Hasher.

impl<A> ImageAccess for AttachmentImage<A> where
    A: MemoryPoolAlloc, 

fn inner(&self) -> ImageInner<'_>

Returns the inner unsafe image object used by this image.

fn initial_layout_requirement(&self) -> ImageLayout

Returns the layout that the image has when it is first used in a primary command buffer.

fn final_layout_requirement(&self) -> ImageLayout

Returns the layout that the image must be returned to before the end of the command buffer.

fn descriptor_layouts(&self) -> Option<ImageDescriptorLayouts>

Returns an ImageDescriptorLayouts structure specifying the image layout to use in descriptors of various kinds.

fn conflict_key(&self) -> u64

Returns a key that uniquely identifies the memory content of the image. Two ranges that potentially overlap in memory must return the same key.

fn try_gpu_lock(
    &self,
    _: bool,
    uninitialized_safe: bool,
    expected_layout: ImageLayout
) -> Result<(), AccessError>

Locks the resource for usage on the GPU. Returns an error if the lock can’t be acquired.

unsafe fn increase_gpu_lock(&self)

Locks the resource for usage on the GPU. Supposes that the resource is already locked, and simply increases the lock by one.

unsafe fn unlock(&self, new_layout: Option<ImageLayout>)

Unlocks the resource previously acquired with try_gpu_lock or increase_gpu_lock.

unsafe fn layout_initialized(&self)

When images are created their memory layout is initially Undefined or Preinitialized. This method allows the image memory barrier creation process to signal when an image has been transitioned out of its initial Undefined or Preinitialized state. This allows vulkano to avoid creating unnecessary image memory barriers between future uses of the image.

fn is_layout_initialized(&self) -> bool

fn current_mip_levels_access(&self) -> Range<u32>

Returns the current mip level that is accessed by the gpu

fn current_array_layers_access(&self) -> Range<u32>

Returns the current array layer that is accessed by the gpu

fn format(&self) -> Format

Returns the format of this image.

fn mip_levels(&self) -> u32

Returns the number of mipmap levels of this image.

fn samples(&self) -> SampleCount

Returns the number of samples of this image.

fn dimensions(&self) -> ImageDimensions

Returns the dimensions of the image.

fn format_features(&self) -> &FormatFeatures

Returns the features supported by the image’s format.

unsafe fn initial_layout(&self) -> ImageLayout

unsafe fn forced_undefined_initial_layout(
    self,
    preinitialized: bool
) -> Arc<ImageAccessFromUndefinedLayout<Self>> where
    Self: Sized, 

Wraps around this ImageAccess and returns an identical ImageAccess but whose initial layout requirement is either Undefined or Preinitialized.

impl<A> ImageClearValue<ClearValue> for AttachmentImage<A> where
    A: MemoryPoolAlloc, 

fn decode(&self, value: ClearValue) -> Option<ClearValue>

impl<P, A> ImageContent<P> for AttachmentImage<A> where
    A: MemoryPoolAlloc, 

fn matches_format(&self) -> bool

Checks whether pixels of type P match the format of the image.

impl<A> PartialEq<AttachmentImage<A>> for AttachmentImage<A> where
    A: MemoryPoolAlloc, 

fn eq(&self, other: &Self) -> 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 !=.

impl<A> Eq for AttachmentImage<A> where
    A: MemoryPoolAlloc,