Module vulkano::image

Image storage (1D, 2D, 3D, arrays, etc.) and image views.

An image is a region of memory whose purpose is to store multi-dimensional data. Its most common use is to store a 2D array of color pixels (in other words an image in everyday language), but it can also be used to store arbitrary data.

The advantage of using an image compared to a buffer is that the memory layout is optimized for locality. When reading a specific pixel of an image, reading the nearby pixels is really fast. Most implementations have hardware dedicated to reading from images if you access them through a sampler.

Properties of an image

TODO

Images and image views

There is a distinction between images and image views. As its name suggests, an image view describes how the GPU must interpret the image.

Transfer and memory operations operate on images themselves, while reading/writing an image operates on image views. You can create multiple image views from the same image.

High-level wrappers

In the vulkano library, images that have memory bound to them are represented by Image. You can create an Image directly by providing a memory allocator and all the info for the image and allocation you want to create. This should satisify most use cases. The more low-level use cases such as importing memory for the image are described below.

You can create an ImageView from any Image.

Low-level information

RawImage is the low-level wrapper around a VkImage, which has no memory bound to it. You can create a RawImage similarly to Image except that you don’t provide any info about the allocation. That way, you can bind memory to it however you wish, including:

• Binding DeviceMemory you allocated yourself, for instance with specific export handle types.
• Binding imported DeviceMemory.

You can create a ResourceMemory from DeviceMemory if you want to bind its own block of memory to an image.

Re-exports

• pub use self::sys::ImageCreateInfo;

Modules

• sampler
  How to retrieve data from a sampled image within a shader.
• sys
  Low-level implementation of images.
• view
  Image views.

Structs

• Image
  A multi-dimensioned storage for texel data.
• ImageAspects
  A set of ImageAspect values.
• ImageCreateFlags
  Flags specifying additional properties of an image.
• ImageDrmFormatModifierInfo
  The image’s DRM format modifier configuration to query in PhysicalDevice::image_format_properties.
• ImageFormatInfo
  The image configuration to query in PhysicalDevice::image_format_properties.
• ImageFormatProperties
  The properties that are supported by a physical device for images of a certain type.
• ImageSubresourceLayers
  One or more subresources of an image, spanning a single mip level, that should be accessed by a command.
• ImageSubresourceRange
  One or more subresources of an image that should be accessed by a command.
• ImageUsage
  Describes how an image is going to be used. This is not just an optimization.
• SampleCounts
  A set of SampleCount values.
• SparseImageFormatFlags
  Flags specifying information about a sparse resource.
• SparseImageFormatInfo
  The image configuration to query in PhysicalDevice::sparse_image_format_properties.
• SparseImageFormatProperties
  The properties that are supported by a physical device for sparse images of a certain type.
• SparseImageMemoryRequirements
  Requirements for binding memory to a sparse image.
• SubresourceLayout
  Describes the memory layout of a single subresource of an image.

Enums

• AllocateImageError
  Error that can happen when allocating a new image.
• ImageAspect
  An individual data type within an image.
• ImageLayout
  In-memory layout of the pixel data of an image.
• ImageMemory
  The type of backing memory that an image can have.
• ImageTiling
  The arrangement of texels or texel blocks in an image.
• ImageType
  The basic dimensionality of an image.
• SampleCount
  The number of samples per texel of an image.

Functions

• max_mip_levels
  Returns the maximum number of mipmap levels for the given image extent.
• mip_level_extent
  Returns the extent of the levelth mipmap level. If level is 0, then it returns extent back unchanged.