Struct SampleLayout

#[repr(C)]
pub struct SampleLayout {
    pub channels: u8,
    pub channel_stride: usize,
    pub width: u32,
    pub width_stride: usize,
    pub height: u32,
    pub height_stride: usize,
}

A ffi compatible description of a sample buffer.

Fields

channels: u8

The number of channels in the color representation of the image.

channel_stride: usize

Add this to an index to get to the sample in the next channel.

width: u32

The width of the represented image.

width_stride: usize

Add this to an index to get to the next sample in x-direction.

height: u32

The height of the represented image.

height_stride: usize

Add this to an index to get to the next sample in y-direction.

Implementations

impl SampleLayout

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

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_value(). On other platforms where it can surely accommodate `u8::max_value() * u32::max_value(), this can never happen.

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

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_value(). On other platforms where it can surely accommodate `u8::max_value() * u32::max_value(), this can never happen.

pub fn strides_cwh(&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.

pub fn extents(&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.

pub fn bounds(&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.

pub fn min_length(&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.

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

Check if a buffer of length len is large enough.

pub fn has_aliased_samples(&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.

pub fn is_normal(&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.

pub fn in_bounds(&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.

pub fn index(&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.

pub fn index_ignoring_bounds( &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.

pub fn in_bounds_index(&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.

pub fn shrink_to(&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.

Trait Implementations

impl Clone for SampleLayout

fn clone(&self) -> SampleLayout

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SampleLayout

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

Formats the value using the given formatter.

impl Hash for SampleLayout

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

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for SampleLayout

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

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for SampleLayout

impl Eq for SampleLayout

impl StructuralPartialEq for SampleLayout