Struct image::flat::SampleLayout
source · #[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§
source§impl SampleLayout
impl SampleLayout
sourcepub fn row_major_packed(channels: u8, width: u32, height: u32) -> Self
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.
sourcepub fn column_major_packed(channels: u8, width: u32, height: u32) -> Self
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.
sourcepub fn strides_cwh(&self) -> (usize, usize, usize)
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.
sourcepub fn extents(&self) -> (usize, usize, usize)
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.
sourcepub fn bounds(&self) -> (u8, u32, u32)
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.
sourcepub fn min_length(&self) -> Option<usize>
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
.
sourcepub fn has_aliased_samples(&self) -> bool
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.
sourcepub fn is_normal(&self, form: NormalForm) -> bool
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.
sourcepub fn in_bounds(&self, channel: u8, x: u32, y: u32) -> bool
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.
sourcepub fn index(&self, channel: u8, x: u32, y: u32) -> Option<usize>
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
.
sourcepub fn index_ignoring_bounds(
&self,
channel: usize,
x: usize,
y: usize
) -> Option<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.
sourcepub fn in_bounds_index(&self, c: u8, x: u32, y: u32) -> usize
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.
sourcepub fn shrink_to(&mut self, channels: u8, width: u32, height: u32)
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§
source§impl Clone for SampleLayout
impl Clone for SampleLayout
source§fn clone(&self) -> SampleLayout
fn clone(&self) -> SampleLayout
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for SampleLayout
impl Debug for SampleLayout
source§impl Hash for SampleLayout
impl Hash for SampleLayout
source§impl PartialEq<SampleLayout> for SampleLayout
impl PartialEq<SampleLayout> for SampleLayout
source§fn eq(&self, other: &SampleLayout) -> bool
fn eq(&self, other: &SampleLayout) -> bool
self
and other
values to be equal, and is used
by ==
.