Struct vulkano::image::attachment::AttachmentImage
source · [−]pub struct AttachmentImage<A = PotentialDedicatedAllocation<StandardMemoryPoolAlloc>> { /* private fields */ }
Expand description
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
sourceimpl AttachmentImage
impl AttachmentImage
sourcepub fn new(
device: Arc<Device>,
dimensions: [u32; 2],
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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.
sourcepub fn input_attachment(
device: Arc<Device>,
dimensions: [u32; 2],
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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
.
sourcepub fn multisampled(
device: Arc<Device>,
dimensions: [u32; 2],
samples: SampleCount,
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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.
sourcepub fn multisampled_input_attachment(
device: Arc<Device>,
dimensions: [u32; 2],
samples: SampleCount,
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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
.
sourcepub fn with_usage(
device: Arc<Device>,
dimensions: [u32; 2],
format: Format,
usage: ImageUsage
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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.
sourcepub fn multisampled_with_usage(
device: Arc<Device>,
dimensions: [u32; 2],
samples: SampleCount,
format: Format,
usage: ImageUsage
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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.
sourcepub 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>
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.
sourcepub fn sampled(
device: Arc<Device>,
dimensions: [u32; 2],
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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
.
sourcepub fn sampled_input_attachment(
device: Arc<Device>,
dimensions: [u32; 2],
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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
.
sourcepub fn sampled_multisampled(
device: Arc<Device>,
dimensions: [u32; 2],
samples: SampleCount,
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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
.
sourcepub fn sampled_multisampled_input_attachment(
device: Arc<Device>,
dimensions: [u32; 2],
samples: SampleCount,
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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
.
sourcepub fn transient(
device: Arc<Device>,
dimensions: [u32; 2],
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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
.
sourcepub fn transient_input_attachment(
device: Arc<Device>,
dimensions: [u32; 2],
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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
.
sourcepub fn transient_multisampled(
device: Arc<Device>,
dimensions: [u32; 2],
samples: SampleCount,
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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
.
sourcepub fn transient_multisampled_input_attachment(
device: Arc<Device>,
dimensions: [u32; 2],
samples: SampleCount,
format: Format
) -> Result<Arc<AttachmentImage>, ImageCreationError>
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>
sourcepub fn export_posix_fd(&self) -> Result<File, DeviceMemoryError>
pub fn export_posix_fd(&self) -> Result<File, DeviceMemoryError>
Exports posix file descriptor for the allocated memory
requires khr_external_memory_fd
and khr_external_memory
extensions to be loaded.
sourcepub fn mem_size(&self) -> DeviceSize
pub fn mem_size(&self) -> DeviceSize
Return the size of the allocated memory (used for e.g. with cuda)
Trait Implementations
sourceimpl<A: Debug> Debug for AttachmentImage<A>
impl<A: Debug> Debug for AttachmentImage<A>
sourceimpl<A> DeviceOwned for AttachmentImage<A>
impl<A> DeviceOwned for AttachmentImage<A>
sourceimpl<A> Hash for AttachmentImage<A>where
A: MemoryPoolAlloc,
impl<A> Hash for AttachmentImage<A>where
A: MemoryPoolAlloc,
sourceimpl<A> ImageAccess for AttachmentImage<A>where
A: MemoryPoolAlloc,
impl<A> ImageAccess for AttachmentImage<A>where
A: MemoryPoolAlloc,
sourcefn inner(&self) -> ImageInner<'_>
fn inner(&self) -> ImageInner<'_>
sourcefn initial_layout_requirement(&self) -> ImageLayout
fn initial_layout_requirement(&self) -> ImageLayout
sourcefn final_layout_requirement(&self) -> ImageLayout
fn final_layout_requirement(&self) -> ImageLayout
sourcefn descriptor_layouts(&self) -> Option<ImageDescriptorLayouts>
fn descriptor_layouts(&self) -> Option<ImageDescriptorLayouts>
ImageDescriptorLayouts
structure specifying the image layout to use
in descriptors of various kinds. Read moresourceunsafe fn layout_initialized(&self)
unsafe fn layout_initialized(&self)
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. Read morefn is_layout_initialized(&self) -> bool
sourcefn dimensions(&self) -> ImageDimensions
fn dimensions(&self) -> ImageDimensions
sourcefn format_features(&self) -> &FormatFeatures
fn format_features(&self) -> &FormatFeatures
sourcefn mip_levels(&self) -> u32
fn mip_levels(&self) -> u32
sourcefn samples(&self) -> SampleCount
fn samples(&self) -> SampleCount
sourcefn usage(&self) -> &ImageUsage
fn usage(&self) -> &ImageUsage
sourcefn stencil_usage(&self) -> &ImageUsage
fn stencil_usage(&self) -> &ImageUsage
sourcefn subresource_layers(&self) -> ImageSubresourceLayers
fn subresource_layers(&self) -> ImageSubresourceLayers
ImageSubresourceLayers
covering the first mip level of the image. All aspects
of the image are selected, or plane0
if the image is multi-planar. Read moresourcefn subresource_range(&self) -> ImageSubresourceRange
fn subresource_range(&self) -> ImageSubresourceRange
ImageSubresourceRange
covering the whole image. If the image is multi-planar,
only the color
aspect is selected. Read morefn initial_layout(&self) -> ImageLayout
sourceunsafe fn forced_undefined_initial_layout(
self,
preinitialized: bool
) -> Arc<ImageAccessFromUndefinedLayout<Self>>where
Self: Sized,
unsafe fn forced_undefined_initial_layout(
self,
preinitialized: bool
) -> Arc<ImageAccessFromUndefinedLayout<Self>>where
Self: Sized,
ImageAccess
and returns an identical ImageAccess
but whose initial
layout requirement is either Undefined
or Preinitialized
. Read moresourceimpl<P, A> ImageContent<P> for AttachmentImage<A>where
A: MemoryPoolAlloc,
impl<P, A> ImageContent<P> for AttachmentImage<A>where
A: MemoryPoolAlloc,
sourcefn matches_format(&self) -> bool
fn matches_format(&self) -> bool
P
match the format of the image.