impl SampleLayout

fn row_major_packed(channels: u8, width: u32, height: u32) -> Self

Describe a row-major image packed in all directions.

The resulting will surely be NormalForm::RowMajorPacked. It can therefore be converted to safely to an ImageBuffer with a large enough underlying buffer.

# use image::flat::{NormalForm, SampleLayout};
let layout = SampleLayout::row_major_packed(3, 640, 480);
assert!(layout.is_normal(NormalForm::RowMajorPacked));

Panics

On platforms where usize has the same size as u32 this panics when the resulting stride in the height direction would be larger than usize::MAX. On other platforms where it can surely accommodate `u8::MAX * u32::MAX, this can never happen.

fn column_major_packed(channels: u8, width: u32, height: u32) -> Self

Describe a column-major image packed in all directions.

The resulting will surely be NormalForm::ColumnMajorPacked. This is not particularly useful for conversion but can be used to describe such a buffer without pitfalls.

# use image::flat::{NormalForm, SampleLayout};
let layout = SampleLayout::column_major_packed(3, 640, 480);
assert!(layout.is_normal(NormalForm::ColumnMajorPacked));

Panics

On platforms where usize has the same size as u32 this panics when the resulting stride in the width direction would be larger than usize::MAX. On other platforms where it can surely accommodate `u8::MAX * u32::MAX, this can never happen.

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 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 (channel, x, y).

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, c: 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.

Behavior is unspecified if the index is out of bounds or this sample layout would require a buffer larger than isize::MAX bytes.

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 Clone for SampleLayout

fn clone(self: &Self) -> SampleLayout

impl Copy for SampleLayout

impl Debug for SampleLayout

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

impl Eq for SampleLayout

impl Freeze for SampleLayout

impl Hash for SampleLayout

fn hash<__H: $crate::hash::Hasher>(self: &Self, state: &mut __H)

impl PartialEq for SampleLayout

fn eq(self: &Self, other: &SampleLayout) -> bool

impl RefUnwindSafe for SampleLayout

impl Send for SampleLayout

impl StructuralPartialEq for SampleLayout

impl Sync for SampleLayout

impl Unpin for SampleLayout

impl UnwindSafe for SampleLayout

impl<T> Any for SampleLayout

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for SampleLayout

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

impl<T> BorrowMut for SampleLayout

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

impl<T> CloneToUninit for SampleLayout

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

impl<T> From for SampleLayout

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Pointable for SampleLayout

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 SampleLayout

fn to_owned(self: &Self) -> T

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

impl<T, U> Into for SampleLayout

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 SampleLayout

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

impl<T, U> TryInto for SampleLayout

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