diff options
Diffstat (limited to 'vendor/image/src/flat.rs')
| -rw-r--r-- | vendor/image/src/flat.rs | 1735 |
1 files changed, 1735 insertions, 0 deletions
diff --git a/vendor/image/src/flat.rs b/vendor/image/src/flat.rs new file mode 100644 index 0000000..24a14d1 --- /dev/null +++ b/vendor/image/src/flat.rs @@ -0,0 +1,1735 @@ +//! Image representations for ffi. +//! +//! # Usage +//! +//! Imagine you want to offer a very simple ffi interface: The caller provides an image buffer and +//! your program creates a thumbnail from it and dumps that image as `png`. This module is designed +//! to help you transition from raw memory data to Rust representation. +//! +//! ```no_run +//! use std::ptr; +//! use std::slice; +//! use image::Rgb; +//! use image::flat::{FlatSamples, SampleLayout}; +//! use image::imageops::thumbnail; +//! +//! #[no_mangle] +//! pub extern "C" fn store_rgb8_compressed( +//! data: *const u8, len: usize, +//! layout: *const SampleLayout +//! ) +//! -> bool +//! { +//! let samples = unsafe { slice::from_raw_parts(data, len) }; +//! let layout = unsafe { ptr::read(layout) }; +//! +//! let buffer = FlatSamples { +//! samples, +//! layout, +//! color_hint: None, +//! }; +//! +//! let view = match buffer.as_view::<Rgb<u8>>() { +//! Err(_) => return false, // Invalid layout. +//! Ok(view) => view, +//! }; +//! +//! thumbnail(&view, 64, 64) +//! .save("output.png") +//! .map(|_| true) +//! .unwrap_or_else(|_| false) +//! } +//! ``` +//! +use std::marker::PhantomData; +use std::ops::{Deref, Index, IndexMut}; +use std::{cmp, error, fmt}; + +use num_traits::Zero; + +use crate::color::ColorType; +use crate::error::{ + DecodingError, ImageError, ImageFormatHint, ParameterError, ParameterErrorKind, + UnsupportedError, UnsupportedErrorKind, +}; +use crate::image::{GenericImage, GenericImageView}; +use crate::traits::Pixel; +use crate::ImageBuffer; + +/// 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. It also allows grouping by color planes instead of by pixel as long as +/// the strides of each extent are constant. This struct itself has no invariants on the strides +/// but not every possible configuration can be interpreted as a [`GenericImageView`] or +/// [`GenericImage`]. The methods [`as_view`] and [`as_view_mut`] construct the actual implementors +/// of these traits and perform necessary checks. To manually perform this and other layout checks +/// use [`is_normal`] or [`has_aliased_samples`]. +/// +/// Instances can be constructed not only by hand. The buffer instances returned by library +/// functions such as [`ImageBuffer::as_flat_samples`] guarantee that the conversion to a generic +/// image or generic view succeeds. A very different constructor is [`with_monocolor`]. It uses a +/// single pixel as the backing storage for an arbitrarily sized read-only raster by mapping each +/// pixel to the same samples by setting some strides to `0`. +/// +/// [`GenericImage`]: ../trait.GenericImage.html +/// [`GenericImageView`]: ../trait.GenericImageView.html +/// [`ImageBuffer::as_flat_samples`]: ../struct.ImageBuffer.html#method.as_flat_samples +/// [`is_normal`]: #method.is_normal +/// [`has_aliased_samples`]: #method.has_aliased_samples +/// [`as_view`]: #method.as_view +/// [`as_view_mut`]: #method.as_view_mut +/// [`with_monocolor`]: #method.with_monocolor +#[derive(Clone, Debug)] +pub struct FlatSamples<Buffer> { + /// Underlying linear container holding sample values. + pub samples: Buffer, + + /// A `repr(C)` description of the layout of buffer samples. + pub layout: SampleLayout, + + /// 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. + pub color_hint: Option<ColorType>, +} + +/// A ffi compatible description of a sample buffer. +#[repr(C)] +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub struct SampleLayout { + /// The number of channels in the color representation of the image. + pub channels: u8, + + /// Add this to an index to get to the sample in the next channel. + pub channel_stride: usize, + + /// The width of the represented image. + pub width: u32, + + /// Add this to an index to get to the next sample in x-direction. + pub width_stride: usize, + + /// The height of the represented image. + pub height: u32, + + /// Add this to an index to get to the next sample in y-direction. + pub height_stride: usize, +} + +/// Helper struct for an unnamed (stride, length) pair. +#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)] +struct Dim(usize, usize); + +impl SampleLayout { + /// 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_value()`. On other platforms + /// where it can surely accommodate `u8::max_value() * u32::max_value(), this can never happen. + pub fn row_major_packed(channels: u8, width: u32, height: u32) -> Self { + let height_stride = (channels as usize).checked_mul(width as usize).expect( + "Row major packed image can not be described because it does not fit into memory", + ); + SampleLayout { + channels, + channel_stride: 1, + width, + width_stride: channels as usize, + height, + height_stride, + } + } + + /// 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_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 { + let width_stride = (channels as usize).checked_mul(height as usize).expect( + "Column major packed image can not be described because it does not fit into memory", + ); + SampleLayout { + channels, + channel_stride: 1, + height, + height_stride: channels as usize, + width, + width_stride, + } + } + + /// 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 strides_cwh(&self) -> (usize, usize, usize) { + (self.channel_stride, self.width_stride, self.height_stride) + } + + /// 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 extents(&self) -> (usize, usize, usize) { + ( + self.channels as usize, + self.width as usize, + self.height as usize, + ) + } + + /// 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 bounds(&self) -> (u8, u32, u32) { + (self.channels, self.width, self.height) + } + + /// 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` + /// + /// ```text + /// | 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` + /// + /// ```text + /// 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 min_length(&self) -> Option<usize> { + if self.width == 0 || self.height == 0 || self.channels == 0 { + return Some(0); + } + + self.index(self.channels - 1, self.width - 1, self.height - 1) + .and_then(|idx| idx.checked_add(1)) + } + + /// Check if a buffer of length `len` is large enough. + pub fn fits(&self, len: usize) -> bool { + self.min_length().map(|min| len >= min).unwrap_or(false) + } + + /// The extents of this array, in order of increasing strides. + fn increasing_stride_dims(&self) -> [Dim; 3] { + // Order extents by strides, then check that each is less equal than the next stride. + let mut grouped: [Dim; 3] = [ + Dim(self.channel_stride, self.channels as usize), + Dim(self.width_stride, self.width as usize), + Dim(self.height_stride, self.height as usize), + ]; + + grouped.sort(); + + let (min_dim, mid_dim, max_dim) = (grouped[0], grouped[1], grouped[2]); + assert!(min_dim.stride() <= mid_dim.stride() && mid_dim.stride() <= max_dim.stride()); + + grouped + } + + /// 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 has_aliased_samples(&self) -> bool { + let grouped = self.increasing_stride_dims(); + let (min_dim, mid_dim, max_dim) = (grouped[0], grouped[1], grouped[2]); + + let min_size = match min_dim.checked_len() { + None => return true, + Some(size) => size, + }; + + let mid_size = match mid_dim.checked_len() { + None => return true, + Some(size) => size, + }; + + match max_dim.checked_len() { + None => return true, + Some(_) => (), // Only want to know this didn't overflow. + }; + + // Each higher dimension must walk over all of one lower dimension. + min_size > mid_dim.stride() || mid_size > max_dim.stride() + } + + /// 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 is_normal(&self, form: NormalForm) -> bool { + if self.has_aliased_samples() { + return false; + } + + if form >= NormalForm::PixelPacked && self.channel_stride != 1 { + return false; + } + + if form >= NormalForm::ImagePacked { + // has aliased already checked for overflows. + let grouped = self.increasing_stride_dims(); + let (min_dim, mid_dim, max_dim) = (grouped[0], grouped[1], grouped[2]); + + if 1 != min_dim.stride() { + return false; + } + + if min_dim.len() != mid_dim.stride() { + return false; + } + + if mid_dim.len() != max_dim.stride() { + return false; + } + } + + if form >= NormalForm::RowMajorPacked { + if self.width_stride != self.channels as usize { + return false; + } + + if self.width as usize * self.width_stride != self.height_stride { + return false; + } + } + + if form >= NormalForm::ColumnMajorPacked { + if self.height_stride != self.channels as usize { + return false; + } + + if self.height as usize * self.height_stride != self.width_stride { + return false; + } + } + + true + } + + /// 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 in_bounds(&self, channel: u8, x: u32, y: u32) -> bool { + channel < self.channels && x < self.width && y < self.height + } + + /// 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(&self, channel: u8, x: u32, y: u32) -> Option<usize> { + if !self.in_bounds(channel, x, y) { + return None; + } + + self.index_ignoring_bounds(channel as usize, x as usize, y as 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 index_ignoring_bounds(&self, channel: usize, x: usize, y: usize) -> Option<usize> { + let idx_c = channel.checked_mul(self.channel_stride); + let idx_x = x.checked_mul(self.width_stride); + let idx_y = y.checked_mul(self.height_stride); + + let (idx_c, idx_x, idx_y) = match (idx_c, idx_x, idx_y) { + (Some(idx_c), Some(idx_x), Some(idx_y)) => (idx_c, idx_x, idx_y), + _ => return None, + }; + + Some(0usize) + .and_then(|b| b.checked_add(idx_c)) + .and_then(|b| b.checked_add(idx_x)) + .and_then(|b| b.checked_add(idx_y)) + } + + /// 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 in_bounds_index(&self, c: u8, x: u32, y: u32) -> usize { + let (c_stride, x_stride, y_stride) = self.strides_cwh(); + (y as usize * y_stride) + (x as usize * x_stride) + (c as usize * c_stride) + } + + /// 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. + pub fn shrink_to(&mut self, channels: u8, width: u32, height: u32) { + self.channels = self.channels.min(channels); + self.width = self.width.min(width); + self.height = self.height.min(height); + } +} + +impl Dim { + fn stride(self) -> usize { + self.0 + } + + /// Length of this dimension in memory. + fn checked_len(self) -> Option<usize> { + self.0.checked_mul(self.1) + } + + fn len(self) -> usize { + self.0 * self.1 + } +} + +impl<Buffer> FlatSamples<Buffer> { + /// 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 strides_cwh(&self) -> (usize, usize, usize) { + self.layout.strides_cwh() + } + + /// 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 extents(&self) -> (usize, usize, usize) { + self.layout.extents() + } + + /// 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 bounds(&self) -> (u8, u32, u32) { + self.layout.bounds() + } + + /// Get a reference based version. + pub fn as_ref<T>(&self) -> FlatSamples<&[T]> + where + Buffer: AsRef<[T]>, + { + FlatSamples { + samples: self.samples.as_ref(), + layout: self.layout, + color_hint: self.color_hint, + } + } + + /// Get a mutable reference based version. + pub fn as_mut<T>(&mut self) -> FlatSamples<&mut [T]> + where + Buffer: AsMut<[T]>, + { + FlatSamples { + samples: self.samples.as_mut(), + layout: self.layout, + color_hint: self.color_hint, + } + } + + /// Copy the data into an owned vector. + pub fn to_vec<T>(&self) -> FlatSamples<Vec<T>> + where + T: Clone, + Buffer: AsRef<[T]>, + { + FlatSamples { + samples: self.samples.as_ref().to_vec(), + layout: self.layout, + color_hint: self.color_hint, + } + } + + /// 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. + /// + /// ``` + /// # use image::{RgbImage}; + /// 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_sample<T>(&self, channel: u8, x: u32, y: u32) -> Option<&T> + where + Buffer: AsRef<[T]>, + { + self.index(channel, x, y) + .and_then(|idx| self.samples.as_ref().get(idx)) + } + + /// 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. + /// + /// ``` + /// # use image::{RgbImage}; + /// 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 get_mut_sample<T>(&mut self, channel: u8, x: u32, y: u32) -> Option<&mut T> + where + Buffer: AsMut<[T]>, + { + match self.index(channel, x, y) { + None => None, + Some(idx) => self.samples.as_mut().get_mut(idx), + } + } + + /// 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<P>(&self) -> Result<View<&[P::Subpixel], P>, Error> + where + P: Pixel, + Buffer: AsRef<[P::Subpixel]>, + { + if self.layout.channels != P::CHANNEL_COUNT { + return Err(Error::ChannelCountMismatch( + self.layout.channels, + P::CHANNEL_COUNT, + )); + } + + let as_ref = self.samples.as_ref(); + if !self.layout.fits(as_ref.len()) { + return Err(Error::TooLarge); + } + + Ok(View { + inner: FlatSamples { + samples: as_ref, + layout: self.layout, + color_hint: self.color_hint, + }, + phantom: PhantomData, + }) + } + + /// 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_with_mut_samples<P>(&mut self) -> Result<View<&mut [P::Subpixel], P>, Error> + where + P: Pixel, + Buffer: AsMut<[P::Subpixel]>, + { + if self.layout.channels != P::CHANNEL_COUNT { + return Err(Error::ChannelCountMismatch( + self.layout.channels, + P::CHANNEL_COUNT, + )); + } + + let as_mut = self.samples.as_mut(); + if !self.layout.fits(as_mut.len()) { + return Err(Error::TooLarge); + } + + Ok(View { + inner: FlatSamples { + samples: as_mut, + layout: self.layout, + color_hint: self.color_hint, + }, + phantom: PhantomData, + }) + } + + /// 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_view_mut<P>(&mut self) -> Result<ViewMut<&mut [P::Subpixel], P>, Error> + where + P: Pixel, + Buffer: AsMut<[P::Subpixel]>, + { + if !self.layout.is_normal(NormalForm::PixelPacked) { + return Err(Error::NormalFormRequired(NormalForm::PixelPacked)); + } + + if self.layout.channels != P::CHANNEL_COUNT { + return Err(Error::ChannelCountMismatch( + self.layout.channels, + P::CHANNEL_COUNT, + )); + } + + let as_mut = self.samples.as_mut(); + if !self.layout.fits(as_mut.len()) { + return Err(Error::TooLarge); + } + + Ok(ViewMut { + inner: FlatSamples { + samples: as_mut, + layout: self.layout, + color_hint: self.color_hint, + }, + phantom: PhantomData, + }) + } + + /// 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_slice<T>(&self) -> &[T] + where + Buffer: AsRef<[T]>, + { + self.samples.as_ref() + } + + /// 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]>, + { + self.samples.as_mut() + } + + /// 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_slice<T>(&self) -> Option<&[T]> + where + Buffer: AsRef<[T]>, + { + let min_length = match self.min_length() { + None => return None, + Some(index) => index, + }; + + let slice = self.samples.as_ref(); + if slice.len() < min_length { + return None; + } + + Some(&slice[..min_length]) + } + + /// Mutable portion of the buffer that holds sample values. + pub fn image_mut_slice<T>(&mut self) -> Option<&mut [T]> + where + Buffer: AsMut<[T]>, + { + let min_length = match self.min_length() { + None => return None, + Some(index) => index, + }; + + let slice = self.samples.as_mut(); + if slice.len() < min_length { + return None; + } + + Some(&mut slice[..min_length]) + } + + /// 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 try_into_buffer<P>(self) -> Result<ImageBuffer<P, Buffer>, (Error, Self)> + where + P: Pixel + 'static, + P::Subpixel: 'static, + Buffer: Deref<Target = [P::Subpixel]>, + { + if !self.is_normal(NormalForm::RowMajorPacked) { + return Err((Error::NormalFormRequired(NormalForm::RowMajorPacked), self)); + } + + if self.layout.channels != P::CHANNEL_COUNT { + return Err(( + Error::ChannelCountMismatch(self.layout.channels, P::CHANNEL_COUNT), + self, + )); + } + + if !self.fits(self.samples.deref().len()) { + return Err((Error::TooLarge, self)); + } + + Ok( + ImageBuffer::from_raw(self.layout.width, self.layout.height, self.samples) + .unwrap_or_else(|| { + panic!("Preconditions should have been ensured before conversion") + }), + ) + } + + /// 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` + /// + /// ```text + /// | 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` + /// + /// ```text + /// 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 min_length(&self) -> Option<usize> { + self.layout.min_length() + } + + /// Check if a buffer of length `len` is large enough. + pub fn fits(&self, len: usize) -> bool { + self.layout.fits(len) + } + + /// 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 has_aliased_samples(&self) -> bool { + self.layout.has_aliased_samples() + } + + /// 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 is_normal(&self, form: NormalForm) -> bool { + self.layout.is_normal(form) + } + + /// 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 in_bounds(&self, channel: u8, x: u32, y: u32) -> bool { + self.layout.in_bounds(channel, x, y) + } + + /// 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(&self, channel: u8, x: u32, y: u32) -> Option<usize> { + self.layout.index(channel, x, y) + } + + /// 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 index_ignoring_bounds(&self, channel: usize, x: usize, y: usize) -> Option<usize> { + self.layout.index_ignoring_bounds(channel, x, y) + } + + /// 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 in_bounds_index(&self, channel: u8, x: u32, y: u32) -> usize { + self.layout.in_bounds_index(channel, x, y) + } + + /// 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. + pub fn shrink_to(&mut self, channels: u8, width: u32, height: u32) { + self.layout.shrink_to(channels, width, height) + } +} + +impl<'buf, Subpixel> FlatSamples<&'buf [Subpixel]> { + /// Create a monocolor image from a single pixel. + /// + /// This can be used as a very cheap source of a `GenericImageView` with an arbitrary number of + /// pixels of a single color, without any dynamic allocation. + /// + /// ## Examples + /// + /// ``` + /// # fn paint_something<T>(_: T) {} + /// use image::{flat::FlatSamples, GenericImage, RgbImage, Rgb}; + /// + /// let background = Rgb([20, 20, 20]); + /// let bg = FlatSamples::with_monocolor(&background, 200, 200);; + /// + /// let mut image = RgbImage::new(200, 200); + /// paint_something(&mut image); + /// + /// // Reset the canvas + /// image.copy_from(&bg.as_view().unwrap(), 0, 0); + /// ``` + pub fn with_monocolor<P>(pixel: &'buf P, width: u32, height: u32) -> Self + where + P: Pixel<Subpixel = Subpixel>, + Subpixel: crate::Primitive, + { + FlatSamples { + samples: pixel.channels(), + layout: SampleLayout { + channels: P::CHANNEL_COUNT, + channel_stride: 1, + width, + width_stride: 0, + height, + height_stride: 0, + }, + + // TODO this value is never set. It should be set in all places where the Pixel type implements PixelWithColorType + color_hint: None, + } + } +} + +/// A flat buffer that can be used as an image view. +/// +/// This is a nearly trivial wrapper around a buffer but at least sanitizes by checking the buffer +/// length first and constraining the pixel type. +/// +/// Note that this does not eliminate panics as the `AsRef<[T]>` implementation of `Buffer` may be +/// unreliable, i.e. return different buffers at different times. This of course is a non-issue for +/// all common collections where the bounds check once must be enough. +/// +/// # Inner invariants +/// +/// * For all indices inside bounds, the corresponding index is valid in the buffer +/// * `P::channel_count()` agrees with `self.inner.layout.channels` +/// +#[derive(Clone, Debug)] +pub struct View<Buffer, P: Pixel> +where + Buffer: AsRef<[P::Subpixel]>, +{ + inner: FlatSamples<Buffer>, + phantom: PhantomData<P>, +} + +/// A mutable owning version of a flat buffer. +/// +/// While this wraps a buffer similar to `ImageBuffer`, this is mostly intended as a utility. The +/// library endorsed normalized representation is still `ImageBuffer`. Also, the implementation of +/// `AsMut<[P::Subpixel]>` must always yield the same buffer. Therefore there is no public way to +/// construct this with an owning buffer. +/// +/// # Inner invariants +/// +/// * For all indices inside bounds, the corresponding index is valid in the buffer +/// * There is no aliasing of samples +/// * The samples are packed, i.e. `self.inner.layout.sample_stride == 1` +/// * `P::channel_count()` agrees with `self.inner.layout.channels` +/// +#[derive(Clone, Debug)] +pub struct ViewMut<Buffer, P: Pixel> +where + Buffer: AsMut<[P::Subpixel]>, +{ + inner: FlatSamples<Buffer>, + phantom: PhantomData<P>, +} + +/// Denotes invalid flat sample buffers when trying to convert to stricter types. +/// +/// The biggest use case being `ImageBuffer` which expects closely packed +/// samples in a row major matrix representation. But this error type may be +/// resused for other import functions. A more versatile user may also try to +/// correct the underlying representation depending on the error variant. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum Error { + /// The represented image was too large. + /// + /// The optional value denotes a possibly accepted maximal bound. + TooLarge, + + /// The represented image can not use this representation. + /// + /// Has an additional value of the normalized form that would be accepted. + NormalFormRequired(NormalForm), + + /// The color format did not match the channel count. + /// + /// In some cases you might be able to fix this by lowering the reported pixel count of the + /// buffer without touching the strides. + /// + /// In very special circumstances you *may* do the opposite. This is **VERY** dangerous but not + /// directly memory unsafe although that will likely alias pixels. One scenario is when you + /// want to construct an `Rgba` image but have only 3 bytes per pixel and for some reason don't + /// care about the value of the alpha channel even though you need `Rgba`. + ChannelCountMismatch(u8, u8), + + /// Deprecated - ChannelCountMismatch is used instead + WrongColor(ColorType), +} + +/// Different normal forms of buffers. +/// +/// A normal form is an unaliased buffer with some additional constraints. The `ÌmageBuffer` uses +/// row major form with packed samples. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum NormalForm { + /// No pixel aliases another. + /// + /// Unaliased also guarantees that all index calculations in the image bounds using + /// `dim_index*dim_stride` (such as `x*width_stride + y*height_stride`) do not overflow. + Unaliased, + + /// At least pixels are packed. + /// + /// Images of these types can wrap `[T]`-slices into the standard color types. This is a + /// precondition for `GenericImage` which requires by-reference access to pixels. + PixelPacked, + + /// All samples are packed. + /// + /// This is orthogonal to `PixelPacked`. It requires that there are no holes in the image but + /// it is not necessary that the pixel samples themselves are adjacent. An example of this + /// behaviour is a planar image layout. + ImagePacked, + + /// The samples are in row-major form and all samples are packed. + /// + /// In addition to `PixelPacked` and `ImagePacked` this also asserts that the pixel matrix is + /// in row-major form. + RowMajorPacked, + + /// The samples are in column-major form and all samples are packed. + /// + /// In addition to `PixelPacked` and `ImagePacked` this also asserts that the pixel matrix is + /// in column-major form. + ColumnMajorPacked, +} + +impl<Buffer, P: Pixel> View<Buffer, P> +where + Buffer: AsRef<[P::Subpixel]>, +{ + /// Take out the sample buffer. + /// + /// Gives up the normalization invariants on the buffer format. + pub fn into_inner(self) -> FlatSamples<Buffer> { + self.inner + } + + /// Get a reference on the inner sample descriptor. + /// + /// There is no mutable counterpart as modifying the buffer format, including strides and + /// lengths, could invalidate the accessibility invariants of the `View`. It is not specified + /// if the inner buffer is the same as the buffer of the image from which this view was + /// created. It might have been truncated as an optimization. + pub fn flat(&self) -> &FlatSamples<Buffer> { + &self.inner + } + + /// Get a reference on the inner buffer. + /// + /// There is no mutable counter part since it is not intended to allow you to reassign the + /// buffer or otherwise change its size or properties. + pub fn samples(&self) -> &Buffer { + &self.inner.samples + } + + /// Get a reference to a selected subpixel if it is in-bounds. + /// + /// This method will return `None` when the sample is out-of-bounds. All errors that could + /// occur due to overflow have been eliminated while construction the `View`. + pub fn get_sample(&self, channel: u8, x: u32, y: u32) -> Option<&P::Subpixel> { + if !self.inner.in_bounds(channel, x, y) { + return None; + } + + let index = self.inner.in_bounds_index(channel, x, y); + // Should always be `Some(_)` but checking is more costly. + self.samples().as_ref().get(index) + } + + /// Get a mutable reference to a selected subpixel if it is in-bounds. + /// + /// This is relevant only when constructed with `FlatSamples::as_view_with_mut_samples`. This + /// method will return `None` when the sample is out-of-bounds. All errors that could occur due + /// to overflow have been eliminated while construction the `View`. + /// + /// **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. + pub fn get_mut_sample(&mut self, channel: u8, x: u32, y: u32) -> Option<&mut P::Subpixel> + where + Buffer: AsMut<[P::Subpixel]>, + { + if !self.inner.in_bounds(channel, x, y) { + return None; + } + + let index = self.inner.in_bounds_index(channel, x, y); + // Should always be `Some(_)` but checking is more costly. + self.inner.samples.as_mut().get_mut(index) + } + + /// Get the minimum length of a buffer such that all in-bounds samples have valid indices. + /// + /// See `FlatSamples::min_length`. This method will always succeed. + pub fn min_length(&self) -> usize { + self.inner.min_length().unwrap() + } + + /// Return the portion of the buffer that holds sample values. + /// + /// While this can not fail–the validity of all coordinates has been validated during the + /// conversion from `FlatSamples`–the resulting slice may still contain holes. + pub fn image_slice(&self) -> &[P::Subpixel] { + &self.samples().as_ref()[..self.min_length()] + } + + /// Return the mutable portion of the buffer that holds sample values. + /// + /// This is relevant only when constructed with `FlatSamples::as_view_with_mut_samples`. While + /// this can not fail–the validity of all coordinates has been validated during the conversion + /// from `FlatSamples`–the resulting slice may still contain holes. + pub fn image_mut_slice(&mut self) -> &mut [P::Subpixel] + where + Buffer: AsMut<[P::Subpixel]>, + { + let min_length = self.min_length(); + &mut self.inner.samples.as_mut()[..min_length] + } + + /// Shrink the inner image. + /// + /// The new dimensions will be the minimum of the previous dimensions. Since the set of + /// in-bounds pixels afterwards is a subset of the current ones, this is allowed on a `View`. + /// Note that you can not change the number of channels as an intrinsic property of `P`. + pub fn shrink_to(&mut self, width: u32, height: u32) { + let channels = self.inner.layout.channels; + self.inner.shrink_to(channels, width, height) + } + + /// Try to convert this into an image with mutable pixels. + /// + /// The resulting image implements `GenericImage` in addition to `GenericImageView`. While this + /// has mutable samples, it does not enforce that pixel can not alias and that samples are + /// packed enough for a mutable pixel reference. This is slightly cheaper than the chain + /// `self.into_inner().as_view_mut()` and keeps the `View` alive on failure. + /// + /// ``` + /// # use image::RgbImage; + /// # use image::Rgb; + /// let mut buffer = RgbImage::new(480, 640).into_flat_samples(); + /// let view = buffer.as_view_with_mut_samples::<Rgb<u8>>().unwrap(); + /// + /// // Inspect some pixels, … + /// + /// // Doesn't fail because it was originally an `RgbImage`. + /// let view_mut = view.try_upgrade().unwrap(); + /// ``` + pub fn try_upgrade(self) -> Result<ViewMut<Buffer, P>, (Error, Self)> + where + Buffer: AsMut<[P::Subpixel]>, + { + if !self.inner.is_normal(NormalForm::PixelPacked) { + return Err((Error::NormalFormRequired(NormalForm::PixelPacked), self)); + } + + // No length check or channel count check required, all the same. + Ok(ViewMut { + inner: self.inner, + phantom: PhantomData, + }) + } +} + +impl<Buffer, P: Pixel> ViewMut<Buffer, P> +where + Buffer: AsMut<[P::Subpixel]>, +{ + /// Take out the sample buffer. + /// + /// Gives up the normalization invariants on the buffer format. + pub fn into_inner(self) -> FlatSamples<Buffer> { + self.inner + } + + /// Get a reference on the sample buffer descriptor. + /// + /// There is no mutable counterpart as modifying the buffer format, including strides and + /// lengths, could invalidate the accessibility invariants of the `View`. It is not specified + /// if the inner buffer is the same as the buffer of the image from which this view was + /// created. It might have been truncated as an optimization. + pub fn flat(&self) -> &FlatSamples<Buffer> { + &self.inner + } + + /// Get a reference on the inner buffer. + /// + /// There is no mutable counter part since it is not intended to allow you to reassign the + /// buffer or otherwise change its size or properties. However, its contents can be accessed + /// mutable through a slice with `image_mut_slice`. + pub fn samples(&self) -> &Buffer { + &self.inner.samples + } + + /// Get the minimum length of a buffer such that all in-bounds samples have valid indices. + /// + /// See `FlatSamples::min_length`. This method will always succeed. + pub fn min_length(&self) -> usize { + self.inner.min_length().unwrap() + } + + /// Get a reference to a selected subpixel. + /// + /// This method will return `None` when the sample is out-of-bounds. All errors that could + /// occur due to overflow have been eliminated while construction the `View`. + pub fn get_sample(&self, channel: u8, x: u32, y: u32) -> Option<&P::Subpixel> + where + Buffer: AsRef<[P::Subpixel]>, + { + if !self.inner.in_bounds(channel, x, y) { + return None; + } + + let index = self.inner.in_bounds_index(channel, x, y); + // Should always be `Some(_)` but checking is more costly. + self.samples().as_ref().get(index) + } + + /// Get a mutable reference to a selected sample. + /// + /// This method will return `None` when the sample is out-of-bounds. All errors that could + /// occur due to overflow have been eliminated while construction the `View`. + pub fn get_mut_sample(&mut self, channel: u8, x: u32, y: u32) -> Option<&mut P::Subpixel> { + if !self.inner.in_bounds(channel, x, y) { + return None; + } + + let index = self.inner.in_bounds_index(channel, x, y); + // Should always be `Some(_)` but checking is more costly. + self.inner.samples.as_mut().get_mut(index) + } + + /// Return the portion of the buffer that holds sample values. + /// + /// While this can not fail–the validity of all coordinates has been validated during the + /// conversion from `FlatSamples`–the resulting slice may still contain holes. + pub fn image_slice(&self) -> &[P::Subpixel] + where + Buffer: AsRef<[P::Subpixel]>, + { + &self.inner.samples.as_ref()[..self.min_length()] + } + + /// Return the mutable buffer that holds sample values. + pub fn image_mut_slice(&mut self) -> &mut [P::Subpixel] { + let length = self.min_length(); + &mut self.inner.samples.as_mut()[..length] + } + + /// Shrink the inner image. + /// + /// The new dimensions will be the minimum of the previous dimensions. Since the set of + /// in-bounds pixels afterwards is a subset of the current ones, this is allowed on a `View`. + /// Note that you can not change the number of channels as an intrinsic property of `P`. + pub fn shrink_to(&mut self, width: u32, height: u32) { + let channels = self.inner.layout.channels; + self.inner.shrink_to(channels, width, height) + } +} + +// The out-of-bounds panic for single sample access similar to `slice::index`. +#[inline(never)] +#[cold] +fn panic_cwh_out_of_bounds( + (c, x, y): (u8, u32, u32), + bounds: (u8, u32, u32), + strides: (usize, usize, usize), +) -> ! { + panic!( + "Sample coordinates {:?} out of sample matrix bounds {:?} with strides {:?}", + (c, x, y), + bounds, + strides + ) +} + +// The out-of-bounds panic for pixel access similar to `slice::index`. +#[inline(never)] +#[cold] +fn panic_pixel_out_of_bounds((x, y): (u32, u32), bounds: (u32, u32)) -> ! { + panic!("Image index {:?} out of bounds {:?}", (x, y), bounds) +} + +impl<Buffer> Index<(u8, u32, u32)> for FlatSamples<Buffer> +where + Buffer: Index<usize>, +{ + type Output = Buffer::Output; + + /// Return a reference to a single sample at specified coordinates. + /// + /// # Panics + /// + /// When the coordinates are out of bounds or the index calculation fails. + fn index(&self, (c, x, y): (u8, u32, u32)) -> &Self::Output { + let bounds = self.bounds(); + let strides = self.strides_cwh(); + let index = self + .index(c, x, y) + .unwrap_or_else(|| panic_cwh_out_of_bounds((c, x, y), bounds, strides)); + &self.samples[index] + } +} + +impl<Buffer> IndexMut<(u8, u32, u32)> for FlatSamples<Buffer> +where + Buffer: IndexMut<usize>, +{ + /// Return a mutable reference to a single sample at specified coordinates. + /// + /// # Panics + /// + /// When the coordinates are out of bounds or the index calculation fails. + fn index_mut(&mut self, (c, x, y): (u8, u32, u32)) -> &mut Self::Output { + let bounds = self.bounds(); + let strides = self.strides_cwh(); + let index = self + .index(c, x, y) + .unwrap_or_else(|| panic_cwh_out_of_bounds((c, x, y), bounds, strides)); + &mut self.samples[index] + } +} + +impl<Buffer, P: Pixel> GenericImageView for View<Buffer, P> +where + Buffer: AsRef<[P::Subpixel]>, +{ + type Pixel = P; + + fn dimensions(&self) -> (u32, u32) { + (self.inner.layout.width, self.inner.layout.height) + } + + fn bounds(&self) -> (u32, u32, u32, u32) { + let (w, h) = self.dimensions(); + (0, w, 0, h) + } + + fn in_bounds(&self, x: u32, y: u32) -> bool { + let (w, h) = self.dimensions(); + x < w && y < h + } + + fn get_pixel(&self, x: u32, y: u32) -> Self::Pixel { + if !self.inner.in_bounds(0, x, y) { + panic_pixel_out_of_bounds((x, y), self.dimensions()) + } + + let image = self.inner.samples.as_ref(); + let base_index = self.inner.in_bounds_index(0, x, y); + let channels = P::CHANNEL_COUNT as usize; + + let mut buffer = [Zero::zero(); 256]; + buffer + .iter_mut() + .enumerate() + .take(channels) + .for_each(|(c, to)| { + let index = base_index + c * self.inner.layout.channel_stride; + *to = image[index]; + }); + + *P::from_slice(&buffer[..channels]) + } +} + +impl<Buffer, P: Pixel> GenericImageView for ViewMut<Buffer, P> +where + Buffer: AsMut<[P::Subpixel]> + AsRef<[P::Subpixel]>, +{ + type Pixel = P; + + fn dimensions(&self) -> (u32, u32) { + (self.inner.layout.width, self.inner.layout.height) + } + + fn bounds(&self) -> (u32, u32, u32, u32) { + let (w, h) = self.dimensions(); + (0, w, 0, h) + } + + fn in_bounds(&self, x: u32, y: u32) -> bool { + let (w, h) = self.dimensions(); + x < w && y < h + } + + fn get_pixel(&self, x: u32, y: u32) -> Self::Pixel { + if !self.inner.in_bounds(0, x, y) { + panic_pixel_out_of_bounds((x, y), self.dimensions()) + } + + let image = self.inner.samples.as_ref(); + let base_index = self.inner.in_bounds_index(0, x, y); + let channels = P::CHANNEL_COUNT as usize; + + let mut buffer = [Zero::zero(); 256]; + buffer + .iter_mut() + .enumerate() + .take(channels) + .for_each(|(c, to)| { + let index = base_index + c * self.inner.layout.channel_stride; + *to = image[index]; + }); + + *P::from_slice(&buffer[..channels]) + } +} + +impl<Buffer, P: Pixel> GenericImage for ViewMut<Buffer, P> +where + Buffer: AsMut<[P::Subpixel]> + AsRef<[P::Subpixel]>, +{ + fn get_pixel_mut(&mut self, x: u32, y: u32) -> &mut Self::Pixel { + if !self.inner.in_bounds(0, x, y) { + panic_pixel_out_of_bounds((x, y), self.dimensions()) + } + + let base_index = self.inner.in_bounds_index(0, x, y); + let channel_count = <P as Pixel>::CHANNEL_COUNT as usize; + let pixel_range = base_index..base_index + channel_count; + P::from_slice_mut(&mut self.inner.samples.as_mut()[pixel_range]) + } + + #[allow(deprecated)] + fn put_pixel(&mut self, x: u32, y: u32, pixel: Self::Pixel) { + *self.get_pixel_mut(x, y) = pixel; + } + + #[allow(deprecated)] + fn blend_pixel(&mut self, x: u32, y: u32, pixel: Self::Pixel) { + self.get_pixel_mut(x, y).blend(&pixel); + } +} + +impl From<Error> for ImageError { + fn from(error: Error) -> ImageError { + #[derive(Debug)] + struct NormalFormRequiredError(NormalForm); + impl fmt::Display for NormalFormRequiredError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "Required sample buffer in normal form {:?}", self.0) + } + } + impl error::Error for NormalFormRequiredError {} + + match error { + Error::TooLarge => ImageError::Parameter(ParameterError::from_kind( + ParameterErrorKind::DimensionMismatch, + )), + Error::NormalFormRequired(form) => ImageError::Decoding(DecodingError::new( + ImageFormatHint::Unknown, + NormalFormRequiredError(form), + )), + Error::ChannelCountMismatch(_lc, _pc) => ImageError::Parameter( + ParameterError::from_kind(ParameterErrorKind::DimensionMismatch), + ), + Error::WrongColor(color) => { + ImageError::Unsupported(UnsupportedError::from_format_and_kind( + ImageFormatHint::Unknown, + UnsupportedErrorKind::Color(color.into()), + )) + } + } + } +} + +impl fmt::Display for Error { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + match self { + Error::TooLarge => write!(f, "The layout is too large"), + Error::NormalFormRequired(form) => write!( + f, + "The layout needs to {}", + match form { + NormalForm::ColumnMajorPacked => "be packed and in column major form", + NormalForm::ImagePacked => "be fully packed", + NormalForm::PixelPacked => "have packed pixels", + NormalForm::RowMajorPacked => "be packed and in row major form", + NormalForm::Unaliased => "not have any aliasing channels", + } + ), + Error::ChannelCountMismatch(layout_channels, pixel_channels) => write!( + f, + "The channel count of the chosen pixel (={}) does agree with the layout (={})", + pixel_channels, layout_channels + ), + Error::WrongColor(color) => write!( + f, + "The chosen color type does not match the hint {:?}", + color + ), + } + } +} + +impl error::Error for Error {} + +impl PartialOrd for NormalForm { + /// Compares the logical preconditions. + /// + /// `a < b` if the normal form `a` has less preconditions than `b`. + fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> { + match (*self, *other) { + (NormalForm::Unaliased, NormalForm::Unaliased) => Some(cmp::Ordering::Equal), + (NormalForm::PixelPacked, NormalForm::PixelPacked) => Some(cmp::Ordering::Equal), + (NormalForm::ImagePacked, NormalForm::ImagePacked) => Some(cmp::Ordering::Equal), + (NormalForm::RowMajorPacked, NormalForm::RowMajorPacked) => Some(cmp::Ordering::Equal), + (NormalForm::ColumnMajorPacked, NormalForm::ColumnMajorPacked) => { + Some(cmp::Ordering::Equal) + } + + (NormalForm::Unaliased, _) => Some(cmp::Ordering::Less), + (_, NormalForm::Unaliased) => Some(cmp::Ordering::Greater), + + (NormalForm::PixelPacked, NormalForm::ColumnMajorPacked) => Some(cmp::Ordering::Less), + (NormalForm::PixelPacked, NormalForm::RowMajorPacked) => Some(cmp::Ordering::Less), + (NormalForm::RowMajorPacked, NormalForm::PixelPacked) => Some(cmp::Ordering::Greater), + (NormalForm::ColumnMajorPacked, NormalForm::PixelPacked) => { + Some(cmp::Ordering::Greater) + } + + (NormalForm::ImagePacked, NormalForm::ColumnMajorPacked) => Some(cmp::Ordering::Less), + (NormalForm::ImagePacked, NormalForm::RowMajorPacked) => Some(cmp::Ordering::Less), + (NormalForm::RowMajorPacked, NormalForm::ImagePacked) => Some(cmp::Ordering::Greater), + (NormalForm::ColumnMajorPacked, NormalForm::ImagePacked) => { + Some(cmp::Ordering::Greater) + } + + (NormalForm::ImagePacked, NormalForm::PixelPacked) => None, + (NormalForm::PixelPacked, NormalForm::ImagePacked) => None, + (NormalForm::RowMajorPacked, NormalForm::ColumnMajorPacked) => None, + (NormalForm::ColumnMajorPacked, NormalForm::RowMajorPacked) => None, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::buffer_::GrayAlphaImage; + use crate::color::{LumaA, Rgb}; + + #[test] + fn aliasing_view() { + let buffer = FlatSamples { + samples: &[42], + layout: SampleLayout { + channels: 3, + channel_stride: 0, + width: 100, + width_stride: 0, + height: 100, + height_stride: 0, + }, + color_hint: None, + }; + + let view = buffer.as_view::<Rgb<u8>>().expect("This is a valid view"); + let pixel_count = view + .pixels() + .inspect(|pixel| assert!(pixel.2 == Rgb([42, 42, 42]))) + .count(); + assert_eq!(pixel_count, 100 * 100); + } + + #[test] + fn mutable_view() { + let mut buffer = FlatSamples { + samples: [0; 18], + layout: SampleLayout { + channels: 2, + channel_stride: 1, + width: 3, + width_stride: 2, + height: 3, + height_stride: 6, + }, + color_hint: None, + }; + + { + let mut view = buffer + .as_view_mut::<LumaA<u16>>() + .expect("This should be a valid mutable buffer"); + assert_eq!(view.dimensions(), (3, 3)); + #[allow(deprecated)] + for i in 0..9 { + *view.get_pixel_mut(i % 3, i / 3) = LumaA([2 * i as u16, 2 * i as u16 + 1]); + } + } + + buffer + .samples + .iter() + .enumerate() + .for_each(|(idx, sample)| assert_eq!(idx, *sample as usize)); + } + + #[test] + fn normal_forms() { + assert!(FlatSamples { + samples: [0u8; 0], + layout: SampleLayout { + channels: 2, + channel_stride: 1, + width: 3, + width_stride: 9, + height: 3, + height_stride: 28, + }, + color_hint: None, + } + .is_normal(NormalForm::PixelPacked)); + + assert!(FlatSamples { + samples: [0u8; 0], + layout: SampleLayout { + channels: 2, + channel_stride: 8, + width: 4, + width_stride: 1, + height: 2, + height_stride: 4, + }, + color_hint: None, + } + .is_normal(NormalForm::ImagePacked)); + + assert!(FlatSamples { + samples: [0u8; 0], + layout: SampleLayout { + channels: 2, + channel_stride: 1, + width: 4, + width_stride: 2, + height: 2, + height_stride: 8, + }, + color_hint: None, + } + .is_normal(NormalForm::RowMajorPacked)); + + assert!(FlatSamples { + samples: [0u8; 0], + layout: SampleLayout { + channels: 2, + channel_stride: 1, + width: 4, + width_stride: 4, + height: 2, + height_stride: 2, + }, + color_hint: None, + } + .is_normal(NormalForm::ColumnMajorPacked)); + } + + #[test] + fn image_buffer_conversion() { + let expected_layout = SampleLayout { + channels: 2, + channel_stride: 1, + width: 4, + width_stride: 2, + height: 2, + height_stride: 8, + }; + + let initial = GrayAlphaImage::new(expected_layout.width, expected_layout.height); + let buffer = initial.into_flat_samples(); + + assert_eq!(buffer.layout, expected_layout); + + let _: GrayAlphaImage = buffer.try_into_buffer().unwrap_or_else(|(error, _)| { + panic!("Expected buffer to be convertible but {:?}", error) + }); + } +} |