# [−][src]Struct image::flat::FlatSamples

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

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. In particular, it also allows grouping by color planes instead of by pixel, at least for the purpose of a `GenericImageView`.

Note that the strides need not conform to the assumption that constructed indices actually refer inside the underlying buffer but return values of library functions will always guarantee this. To manually make this check use `check_index_validities` and maybe put that inside an assert.

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

## Methods

### `impl<Buffer> FlatSamples<Buffer>`[src]

#### `pub fn strides_cwh(&self) -> (usize, usize, usize)`[src]

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

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

#### `pub fn extents(&self) -> (usize, usize, usize)`[src]

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.

#### `pub fn bounds(&self) -> (u8, u32, u32)`[src]

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.

#### `pub fn as_ref<T>(&self) -> FlatSamples<&[T]> where
Buffer: AsRef<[T]>,` [src]

Get a reference based version.

#### `pub fn as_mut<T>(&mut self) -> FlatSamples<&mut [T]> where
Buffer: AsMut<[T]>,` [src]

Get a mutable reference based version.

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

Copy the data into an owned vector.

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

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.

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

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.

#### `pub fn as_view<P>(&self) -> Result<View<&[P::Subpixel], P>, Error> where
P: Pixel,
Buffer: AsRef<[P::Subpixel]>,` [src]

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.

#### `pub fn as_view_with_mut_samples<P>(
&mut self
) -> Result<View<&mut [P::Subpixel], P>, Error> where
P: Pixel,
Buffer: AsMut<[P::Subpixel]>,` [src]

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.

#### `pub fn as_view_mut<P>(
&mut self
) -> Result<ViewMut<&mut [P::Subpixel], P>, Error> where
P: Pixel,
Buffer: AsMut<[P::Subpixel]>,` [src]

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

#### `pub fn as_slice<T>(&self) -> &[T] where
Buffer: AsRef<[T]>,` [src]

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.

#### `pub fn as_mut_slice<T>(&mut self) -> &mut [T] where
Buffer: AsMut<[T]>,` [src]

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.

#### `pub fn image_slice<T>(&self) -> Option<&[T]> where
Buffer: AsRef<[T]>,` [src]

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.

#### `pub fn image_mut_slice<T>(&mut self) -> Option<&mut [T]> where
Buffer: AsMut<[T]>,` [src]

Mutable portion of the buffer that holds sample values.

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

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.

#### `pub fn min_length(&self) -> Option<usize>`[src]

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

#### `pub fn fits(&self, len: usize) -> bool`[src]

Check if a buffer of length `len` is large enough.

#### `pub fn has_aliased_samples(&self) -> bool`[src]

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.

#### `pub fn is_normal(&self, form: NormalForm) -> bool`[src]

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.

#### `pub fn in_bounds(&self, channel: u8, x: u32, y: u32) -> bool`[src]

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 porperty of course follows.

#### `pub fn index(&self, channel: u8, x: u32, y: u32) -> Option<usize>`[src]

Resolve the index of a particular sample.

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

#### `pub fn index_ignoring_bounds(
&self,
channel: usize,
x: usize,
y: usize
) -> Option<usize>`[src]

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.

#### `pub fn in_bounds_index(&self, channel: u8, x: u32, y: u32) -> usize`[src]

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.

#### `pub fn shrink_to(&mut self, channels: u8, width: u32, height: u32)`[src]

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.

## Trait Implementations

### `impl<Buffer: Clone> Clone for FlatSamples<Buffer>`[src]

#### `fn clone(&self) -> FlatSamples<Buffer>`[src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`1.0.0[src]

Performs copy-assignment from `source`. Read more

### `impl<Buffer> Index<(u8, u32, u32)> for FlatSamples<Buffer> where
Buffer: Index<usize>,` [src]

#### `type Output = Buffer::Output`

The returned type after indexing.

#### `fn index(&self, (c, x, y): (u8, u32, u32)) -> &Self::Output`[src]

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<(u8, u32, u32)> for FlatSamples<Buffer> where
Buffer: IndexMut<usize>,` [src]

#### `fn index_mut(&mut self, (c, x, y): (u8, u32, u32)) -> &mut Self::Output`[src]

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: Debug> Debug for FlatSamples<Buffer>`[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`[src]

Formats the value using the given formatter. Read more

## Auto Trait Implementations

### `impl<Buffer> Send for FlatSamples<Buffer> where
Buffer: Send,`

### `impl<Buffer> Unpin for FlatSamples<Buffer> where
Buffer: Unpin,`

### `impl<Buffer> Sync for FlatSamples<Buffer> where
Buffer: Sync,`

### `impl<Buffer> UnwindSafe for FlatSamples<Buffer> where
Buffer: UnwindSafe,`

### `impl<Buffer> RefUnwindSafe for FlatSamples<Buffer> where
Buffer: RefUnwindSafe,`

## Blanket Implementations

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `fn to_owned(&self) -> T`[src]

Creates owned data from borrowed data, usually by cloning. Read more

#### `fn clone_into(&self, target: &mut T)`[src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into`)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `fn into(self) -> U`[src]

Performs the conversion.

### `impl<T> From<T> for T`[src]

#### `fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `fn borrow_mut(&mut self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `fn type_id(&self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

### `impl<T> SetParameter for T`[src]

#### `fn set<T>(&mut self, value: T) -> <T as Parameter<Self>>::Result where
T: Parameter<Self>,` [src]

Sets `value` as a parameter of `self`.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)