impl<'buf, Subpixel> FlatSamples<&'buf [Subpixel]>

fn with_monocolor<P>(pixel: &'buf P, width: u32, height: u32) -> Self
where
    P: Pixel<Subpixel = Subpixel>,
    Subpixel: crate::Primitive

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

# fn paint_something<T>(_: T) {}
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);

impl<Buffer> FlatSamples<Buffer>

fn strides_cwh(self: &Self) -> (usize, usize, usize)

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

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

fn extents(self: &Self) -> (usize, usize, usize)

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.

fn bounds(self: &Self) -> (u8, u32, u32)

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.

fn as_ref<T>(self: &Self) -> FlatSamples<&[T]>
where
    Buffer: AsRef<[T]>

Get a reference based version.

fn as_mut<T>(self: &mut Self) -> FlatSamples<&mut [T]>
where
    Buffer: AsMut<[T]>

Get a mutable reference based version.

fn to_vec<T>(self: &Self) -> FlatSamples<Vec<T>>
where
    T: Clone,
    Buffer: AsRef<[T]>

Copy the data into an owned vector.

fn get_sample<T>(self: &Self, channel: u8, x: u32, y: u32) -> Option<&T>
where
    Buffer: AsRef<[T]>

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.

# use image::{RgbImage};
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.

fn get_mut_sample<T>(self: &mut Self, channel: u8, x: u32, y: u32) -> Option<&mut T>
where
    Buffer: AsMut<[T]>

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.

# use image::{RgbImage};
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.

fn as_view<P>(self: &Self) -> Result<View<&[<P as >::Subpixel], P>, Error>
where
    P: Pixel,
    Buffer: AsRef<[<P as >::Subpixel]>

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.

fn as_view_with_mut_samples<P>(self: &mut Self) -> Result<View<&mut [<P as >::Subpixel], P>, Error>
where
    P: Pixel,
    Buffer: AsMut<[<P as >::Subpixel]>

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.

fn as_view_mut<P>(self: &mut Self) -> Result<ViewMut<&mut [<P as >::Subpixel], P>, Error>
where
    P: Pixel,
    Buffer: AsMut<[<P as >::Subpixel]>

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.

fn as_slice<T>(self: &Self) -> &[T]
where
    Buffer: AsRef<[T]>

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.

fn as_mut_slice<T>(self: &mut Self) -> &mut [T]
where
    Buffer: AsMut<[T]>

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.

fn image_slice<T>(self: &Self) -> Option<&[T]>
where
    Buffer: AsRef<[T]>

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.

fn image_mut_slice<T>(self: &mut Self) -> Option<&mut [T]>
where
    Buffer: AsMut<[T]>

Mutable portion of the buffer that holds sample values.

fn try_into_buffer<P>(self: Self) -> Result<ImageBuffer<P, Buffer>, (Error, Self)>
where
    P: Pixel + 'static,
    <P as >::Subpixel: 'static,
    Buffer: Deref<Target = [<P as >::Subpixel]>

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.

fn min_length(self: &Self) -> Option<usize>

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.

fn fits(self: &Self, len: usize) -> bool

Check if a buffer of length len is large enough.

fn has_aliased_samples(self: &Self) -> bool

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.

fn is_normal(self: &Self, form: NormalForm) -> bool

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.

fn in_bounds(self: &Self, channel: u8, x: u32, y: u32) -> bool

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.

fn index(self: &Self, channel: u8, x: u32, y: u32) -> Option<usize>

Resolve the index of a particular sample.

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

fn index_ignoring_bounds(self: &Self, channel: usize, x: usize, y: usize) -> Option<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.

fn in_bounds_index(self: &Self, channel: u8, x: u32, y: u32) -> usize

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.

fn shrink_to(self: &mut Self, channels: u8, width: u32, height: u32)

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.

impl<Buffer> Freeze for FlatSamples<Buffer>

impl<Buffer> Index for FlatSamples<Buffer>

fn index(self: &Self, (c, x, y): (u8, u32, u32)) -> &<Self as >::Output

Return a reference to a single sample at specified coordinates.

Panics

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

impl<Buffer> IndexMut for FlatSamples<Buffer>

fn index_mut(self: &mut Self, (c, x, y): (u8, u32, u32)) -> &mut <Self as >::Output

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

Panics

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

impl<Buffer> RefUnwindSafe for FlatSamples<Buffer>

impl<Buffer> Send for FlatSamples<Buffer>

impl<Buffer> Sync for FlatSamples<Buffer>

impl<Buffer> Unpin for FlatSamples<Buffer>

impl<Buffer> UnwindSafe for FlatSamples<Buffer>

impl<Buffer: $crate::clone::Clone> Clone for FlatSamples<Buffer>

fn clone(self: &Self) -> FlatSamples<Buffer>

impl<Buffer: $crate::fmt::Debug> Debug for FlatSamples<Buffer>

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

impl<T> Any for FlatSamples<Buffer>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for FlatSamples<Buffer>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for FlatSamples<Buffer>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for FlatSamples<Buffer>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for FlatSamples<Buffer>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Pointable for FlatSamples<Buffer>

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

unsafe fn drop(ptr: usize)

impl<T> ToOwned for FlatSamples<Buffer>

fn to_owned(self: &Self) -> T

fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for FlatSamples<Buffer>

fn into(self: Self) -> U

Calls U::from(self).

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

impl<T, U> TryFrom for FlatSamples<Buffer>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for FlatSamples<Buffer>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>