pub struct FlatSamples<Buffer> {
    pub samples: Buffer,
    pub layout: SampleLayout,
    pub color_hint: Option<ColorType>,
}
Expand description

A flat buffer over a (multi channel) image.

In contrast to ImageBuffer, this representation of a sample collection is much more lenient in the layout thereof. It also allows grouping by color planes instead of by pixel as long as the strides of each extent are constant. This struct itself has no invariants on the strides but not every possible configuration can be interpreted as a GenericImageView or GenericImage. The methods as_view and as_view_mut construct the actual implementors of these traits and perform necessary checks. To manually perform this and other layout checks use is_normal or has_aliased_samples.

Instances can be constructed not only by hand. The buffer instances returned by library functions such as ImageBuffer::as_flat_samples guarantee that the conversion to a generic image or generic view succeeds. A very different constructor is with_monocolor. It uses a single pixel as the backing storage for an arbitrarily sized read-only raster by mapping each pixel to the same samples by setting some strides to 0.

Fields

samples: Buffer

Underlying linear container holding sample values.

layout: SampleLayout

A repr(C) description of the layout of buffer samples.

color_hint: Option<ColorType>

Supplementary color information.

You may keep this as None in most cases. This is NOT checked in View or other converters. It is intended mainly as a way for types that convert to this buffer type to attach their otherwise static color information. A dynamic image representation could however use this to resolve representational ambiguities such as the order of RGB channels.

Implementations

Get the strides for indexing matrix-like [(c, w, h)].

For a row-major layout with grouped samples, this tuple is strictly increasing.

Get the dimensions (channels, width, height).

The interface is optimized for use with strides_cwh instead. The channel extent will be before width and height.

Tuple of bounds in the order of coordinate inputs.

This function should be used whenever working with image coordinates opposed to buffer coordinates. The only difference compared to extents is the output type.

Get a reference based version.

Get a mutable reference based version.

Copy the data into an owned vector.

Get a reference to a single sample.

This more restrictive than the method based on std::ops::Index but guarantees to properly check all bounds and not panic as long as Buffer::as_ref does not do so.

let flat = RgbImage::new(480, 640).into_flat_samples();

// Get the blue channel at (10, 10).
assert!(flat.get_sample(1, 10, 10).is_some());

// There is no alpha channel.
assert!(flat.get_sample(3, 10, 10).is_none());

For cases where a special buffer does not provide AsRef<[T]>, consider encapsulating bounds checks with min_length in a type similar to View. Then you may use in_bounds_index as a small speedup over the index calculation of this method which relies on index_ignoring_bounds since it can not have a-priori knowledge that the sample coordinate is in fact backed by any memory buffer.

Get a mutable reference to a single sample.

This more restrictive than the method based on std::ops::IndexMut but guarantees to properly check all bounds and not panic as long as Buffer::as_ref does not do so. Contrary to conversion to ViewMut, this does not require that samples are packed since it does not need to convert samples to a color representation.

WARNING: Note that of course samples may alias, so that the mutable reference returned here can in fact modify more than the coordinate in the argument.

let mut flat = RgbImage::new(480, 640).into_flat_samples();

// Assign some new color to the blue channel at (10, 10).
*flat.get_mut_sample(1, 10, 10).unwrap() = 255;

// There is no alpha channel.
assert!(flat.get_mut_sample(3, 10, 10).is_none());

For cases where a special buffer does not provide AsRef<[T]>, consider encapsulating bounds checks with min_length in a type similar to View. Then you may use in_bounds_index as a small speedup over the index calculation of this method which relies on index_ignoring_bounds since it can not have a-priori knowledge that the sample coordinate is in fact backed by any memory buffer.

View this buffer as an image over some type of pixel.

This first ensures that all in-bounds coordinates refer to valid indices in the sample buffer. It also checks that the specified pixel format expects the same number of channels that are present in this buffer. Neither are larger nor a smaller number will be accepted. There is no automatic conversion.

View this buffer but keep mutability at a sample level.

This is similar to as_view but subtly different from as_view_mut. The resulting type can be used as a GenericImage with the same prior invariants needed as for as_view. It can not be used as a mutable GenericImage but does not need channels to be packed in their pixel representation.

This first ensures that all in-bounds coordinates refer to valid indices in the sample buffer. It also checks that the specified pixel format expects the same number of channels that are present in this buffer. Neither are larger nor a smaller number will be accepted. There is no automatic conversion.

WARNING: Note that of course samples may alias, so that the mutable reference returned for one sample can in fact modify other samples as well. Sometimes exactly this is intended.

Interpret this buffer as a mutable image.

To succeed, the pixels in this buffer may not alias each other and the samples of each pixel must be packed (i.e. channel_stride is 1). The number of channels must be consistent with the channel count expected by the pixel format.

This is similar to an ImageBuffer except it is a temporary view that is not normalized as strongly. To get an owning version, consider copying the data into an ImageBuffer. This provides many more operations, is possibly faster (if not you may want to open an issue) is generally polished. You can also try to convert this buffer inline, see ImageBuffer::from_raw.

View the samples as a slice.

The slice is not limited to the region of the image and not all sample indices are valid indices into this buffer. See image_mut_slice as an alternative.

View the samples as a slice.

The slice is not limited to the region of the image and not all sample indices are valid indices into this buffer. See image_mut_slice as an alternative.

Return the portion of the buffer that holds sample values.

This may fail when the coordinates in this image are either out-of-bounds of the underlying buffer or can not be represented. Note that the slice may have holes that do not correspond to any sample in the image represented by it.

Mutable portion of the buffer that holds sample values.

Move the data into an image buffer.

This does not convert the sample layout. The buffer needs to be in packed row-major form before calling this function. In case of an error, returns the buffer again so that it does not release any allocation.

Get the minimum length of a buffer such that all in-bounds samples have valid indices.

This method will allow zero strides, allowing compact representations of monochrome images. To check that no aliasing occurs, try check_alias_invariants. For compact images (no aliasing and no unindexed samples) this is width*height*channels. But for both of the other cases, the reasoning is slightly more involved.

Explanation

Note that there is a difference between min_length and the index of the sample ’one-past-the-end`. This is due to strides that may be larger than the dimension below.

Example with holes

Let’s look at an example of a grayscale image with

  • width_stride = 1
  • width = 2
  • height_stride = 3
  • height = 2
| x x   | x x m | $
 min_length m ^
                  ^ one-past-the-end $

The difference is also extreme for empty images with large strides. The one-past-the-end sample index is still as large as the largest of these strides while min_length = 0.

Example with aliasing

The concept gets even more important when you allow samples to alias each other. Here we have the buffer of a small grayscale image where this is the case, this time we will first show the buffer and then the individual rows below.

  • width_stride = 1
  • width = 3
  • height_stride = 2
  • height = 2
 1 2 3 4 5 m
|1 2 3| row one
    |3 4 5| row two
           ^ m min_length
         ^ ??? one-past-the-end

This time ‘one-past-the-end’ is not even simply the largest stride times the extent of its dimension. That still points inside the image because height*height_stride = 4 but also index_of(1, 2) = 4.

Check if a buffer of length len is large enough.

If there are any samples aliasing each other.

If this is not the case, it would always be safe to allow mutable access to two different samples at the same time. Otherwise, this operation would need additional checks. When one dimension overflows usize with its stride we also consider this aliasing.

Check if a buffer fulfills the requirements of a normal form.

Certain conversions have preconditions on the structure of the sample buffer that are not captured (by design) by the type system. These are then checked before the conversion. Such checks can all be done in constant time and will not inspect the buffer content. You can perform these checks yourself when the conversion is not required at this moment but maybe still performed later.

Check that the pixel and the channel index are in bounds.

An in-bound coordinate does not yet guarantee that the corresponding calculation of a buffer index does not overflow. However, if such a buffer large enough to hold all samples actually exists in memory, this property of course follows.

Resolve the index of a particular sample.

None if the index is outside the bounds or does not fit into a usize.

Get the theoretical position of sample (x, y, channel).

The ‘check’ is for overflow during index calculation, not that it is contained in the image. Two samples may return the same index, even when one of them is out of bounds. This happens when all strides are 0, i.e. the image is an arbitrarily large monochrome image.

Get an index provided it is inbouds.

Assumes that the image is backed by some sufficiently large buffer. Then computation can not overflow as we could represent the maximum coordinate. Since overflow is defined either way, this method can not be unsafe.

Shrink the image to the minimum of current and given extents.

This does not modify the strides, so that the resulting sample buffer may have holes created by the shrinking operation. Shrinking could also lead to an non-aliasing image when samples had aliased each other before.

Create a monocolor image from a single pixel.

This can be used as a very cheap source of a GenericImageView with an arbitrary number of pixels of a single color, without any dynamic allocation.

Examples
use image::{flat::FlatSamples, GenericImage, RgbImage, Rgb};

let background = Rgb([20, 20, 20]);
let bg = FlatSamples::with_monocolor(&background, 200, 200);;

let mut image = RgbImage::new(200, 200);
paint_something(&mut image);

// Reset the canvas
image.copy_from(&bg.as_view().unwrap(), 0, 0);

Trait Implementations

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more

Return a reference to a single sample at specified coordinates.

Panics

When the coordinates are out of bounds or the index calculation fails.

The returned type after indexing.

Return a mutable reference to a single sample at specified coordinates.

Panics

When the coordinates are out of bounds or the index calculation fails.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The alignment of pointer.
The type for initializers.
Initializes a with the given initializer. Read more
Dereferences the given pointer. Read more
Mutably dereferences the given pointer. Read more
Drops the object pointed to by the given pointer. Read more
The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.