#[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, }
Expand description

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

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 accomodate `u8::max_value() * u32::max_value(), this can never happen.

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 accomodate `u8::max_value() * u32::max_value(), this can never happen.

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 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 porperty 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 (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.

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.

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

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

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

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

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.