/src/image/src/images/flat.rs

Source
//! 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::math::Rect;
use crate::traits::Pixel;
use crate::{GenericImage, GenericImageView, 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`.
///
/// [`is_normal`]: Self::is_normal
/// [`has_aliased_samples`]: Self::has_aliased_samples
/// [`as_view`]: Self::as_view
/// [`as_view_mut`]: Self::as_view_mut
/// [`with_monocolor`]: Self::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`. On other platforms
    /// where it can surely accommodate `u8::MAX * u32::MAX`, this can never happen.
    #[must_use]
    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`. On other platforms
    /// where it can surely accommodate `u8::MAX * u32::MAX`, this can never happen.
    #[must_use]
    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.
    #[must_use]
    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.
    #[must_use]
    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.
    #[must_use]
    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`.
    #[must_use]
    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.
    #[must_use]
    pub fn fits(&self, len: usize) -> bool {
        self.min_length().is_some_and(|min| len >= min)
    }

    /// 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;
        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.
    #[must_use]
    pub fn has_aliased_samples(&self) -> bool {
        let [min_dim, mid_dim, max_dim] = self.increasing_stride_dims();

        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,
        };

        if max_dim.checked_len().is_none() {
            return true;
        }

        // 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.
    #[must_use]
    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.
    #[must_use]
    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`.
    #[must_use]
    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.
    #[must_use]
    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 (Some(idx_c), Some(idx_x), Some(idx_y)) = (idx_c, idx_x, idx_y) else {
            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.
    ///
    /// Behavior is *unspecified* if the index is out of bounds or this sample layout would require
    /// a buffer larger than `isize::MAX` bytes.
    #[must_use]
    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]>,
    {
        FlatSamples {
            samples: self.samples.as_ref(),
            layout: self.layout,
            color_hint: self.color_hint,
        }
        .into_view()
    }

    /// Convert this descriptor into a readable image.
    ///
    /// An owned version of [`Self::as_view`] that uses the original buffer type.
    ///
    /// FIXME: before exposing this, consider if we want to have strong invariants related to
    /// `AsRef` of `Buffer` or not. If we provide a generic one then we can not rely on the trait to
    /// give us a stable address or anything but its pure interface. It may make it difficult to
    /// introduce efficient code for the relevant case of `Buffer = &[T]`. We could introduce it
    /// specifically for that buffer type.
    pub(crate) fn into_view<P>(self) -> Result<View<Buffer, 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,
            ));
        }

        if !self.layout.fits(self.samples.as_ref().len()) {
            return Err(Error::TooLarge);
        }

        Ok(View {
            inner: self,
            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,
        })
    }

    /// Turn this buffer into a mutable image.
    ///
    /// FIXME: before exposing this, consider if we want to have strong invariants related to
    /// `AsMut` of `Buffer` or not. If we provide a generic one then we can not rely on the trait to
    /// give us a stable address or anything but its pure interface. It may make it difficult to
    /// introduce efficient code for the relevant case of `Buffer = &mut [T]`. We could introduce it
    /// specifically for that buffer type.
    pub(crate) fn into_view_mut<P>(mut self) -> Result<ViewMut<Buffer, 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,
            ));
        }

        if !self.layout.fits(self.samples.as_mut().len()) {
            return Err(Error::TooLarge);
        }

        Ok(ViewMut {
            inner: FlatSamples {
                samples: self.samples,
                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 = self.min_length()?;

        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 = self.min_length()?;

        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,
        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.
    ///
    /// See also [`View::with_monocolor`].
    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>,
}

/// Type alias for a view based on a pixel's channels.
pub type ViewOfPixel<'lt, P> = View<&'lt [<P as Pixel>::Subpixel], 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>,
}

/// Type alias for a mutable view based on a pixel's channels.
pub type ViewMutOfPixel<'lt, P> = ViewMut<&'lt mut [<P as Pixel>::Subpixel], 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
/// reused 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()]
    }

    pub(crate) fn strides_wh(&self) -> (usize, usize) {
        // Note `c` stride must be `1` for a valid `View` so we can ignore it here.
        let (_, w, h) = self.inner.layout.strides_cwh();
        (w, h)
    }

    /// 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,
        })
    }

    /// If the underlying samples are in row-major form and packed pixels, return
    /// an iterator over the rows of the image.
    pub(crate) fn iter_rows(&self) -> Option<impl Iterator<Item = &[P::Subpixel]> + '_> {
        let layout = self.flat().layout;
        let channels = P::CHANNEL_COUNT;
        if layout.channel_stride != 1
            || layout.channels != channels
            || layout.width_stride != channels as usize
        {
            return None;
        }

        let data = self.samples().as_ref();
        let row_len = layout.width as usize * channels as usize;
        let row_stride = layout.height_stride;

        // Note: We do **NOT** assume row_len <= row_stride. Rows may overlap
        // (or even all be the same slice when row_stride == 0). So the usual
        // iter().chunks() strategy does not work here.

        Some((0..layout.height as usize).map(move |y| {
            let start = y * row_stride;
            &data[start..start + row_len]
        }))
    }
}

impl<'buf, P: Pixel> View<&'buf [P::Subpixel], P> {
    /// 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::View, GenericImage, RgbImage, Rgb};
    ///
    /// let gray = Rgb([20, 20, 20]);
    /// let background = View::with_monocolor(&gray, 200, 200);
    ///
    /// let mut image = RgbImage::from_pixel(200, 200, gray);
    /// paint_something(&mut image);
    ///
    /// // Reset the canvas
    /// image.copy_from(&background, 0, 0);
    /// ```
    pub fn with_monocolor(pixel: &'buf P, width: u32, height: u32) -> Self
    where
        P::Subpixel: crate::Primitive,
    {
        // Reuse the validation, in case of `P::channels()` funny business. (View internally prefers
        // using the constant ``CHANNEL_COUNT` where appropriate afterwards to avoid re-executing a
        // potential adversarial trait impl).
        FlatSamples::with_monocolor(pixel, width, height)
            .into_view()
            .unwrap()
    }
}

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);
    }

    /// Copy from, assuming that the source is not a simple view layout.
    pub(crate) fn inner_copy_from<O>(&mut self, other: &O, x: u32, y: u32) -> crate::ImageResult<()>
    where
        O: GenericImageView<Pixel = P>,
        // Note: not necessary for the implementation per-se but this allows the use of
        // `GenericImage`/`GenericImageView` methods and so `test_in_bounds_of`.
        Buffer: AsRef<[P::Subpixel]>,
    {
        // Do bounds checking here so we can use the non-bounds-checking
        // functions to copy pixels.
        let target = Rect::from_image_at(other, x, y);
        target.test_in_bounds_of(self)?;

        if self.image_mut_slice().is_empty() {
            // Apparently this is an empty image but the other is inbounds so it is *also* an empty
            // image. Well, without anything to do let's signal success.
            return Ok(());
        }

        let (c, w, h) = self.inner.layout.strides_cwh();
        // This will be assumed to hold in the following.
        debug_assert_eq!(
            c, 1,
            "Precondition for a `ViewMut`, each Pixel is a slice of channels"
        );

        if w == usize::from(P::CHANNEL_COUNT) {
            let layout = self.inner.layout;
            let buffer = self.image_mut_slice();

            // Edge case: if we have a height of `1` then its height stride may be zero without
            // violating the aliasing requirements. We will instead always use the whole slice in
            // that case. Avoids the potential panic.
            let row_len = if layout.height <= 1 { buffer.len() } else { h };
            let rows = buffer.chunks_exact_mut(row_len);

            // `ViewMut` has an actual invariant on its buffer size (even though it is generic) that
            // is enforced by construction.
            assert!(
                // Since we verified `test_in_bounds_of´ and the target rectangle is a trustworthy
                // value, not a generic interface, the addition on the right hand does not overflow
                // `u32` as it still fits into our own height.
                rows.len() >= (target.y + target.height) as usize,
                "ViewMut buffer inconsistent with its layout"
            );

            for (k, row) in rows
                .skip(target.y as usize)
                .take(target.height as usize)
                .enumerate()
            {
                // Adjust the row according to the target region.
                let row = &mut row[target.x as usize * usize::from(P::CHANNEL_COUNT)..];
                let row = &mut row[..target.width as usize * usize::from(P::CHANNEL_COUNT)];
                let chunks = row.chunks_exact_mut(usize::from(P::CHANNEL_COUNT));

                for (i, out_pix) in (0..target.width).zip(chunks) {
                    let p = other.get_pixel(i, k as u32);
                    *P::from_slice_mut(out_pix) = p;
                }
            }

            return Ok(());
        }

        let layout = self.inner.layout;
        let samples = self.image_mut_slice();

        for k in 0..target.height {
            for i in 0..target.width {
                let p = other.get_pixel(i, k);
                let idx = layout.in_bounds_index(0, i + x, k + y);
                let channels = &mut samples[idx..][..usize::from(P::CHANNEL_COUNT)];
                *P::from_slice_mut(channels) = p;
            }
        }

        Ok(())
    }

    pub(crate) fn inner_copy_from_samples(
        &mut self,
        other: ViewOfPixel<'_, P>,
        x: u32,
        y: u32,
    ) -> crate::ImageResult<()>
    where
        // Note: not necessary for the implementation per-se but this allows the use of
        // `GenericImage`/`GenericImageView` methods and so `test_in_bounds_of`.
        Buffer: AsRef<[P::Subpixel]>,
    {
        let target = Rect::from_image_at(&other, x, y);
        target.test_in_bounds_of(self)?;

        let in_layout = other.inner.layout;
        let in_samples = other.image_slice();

        let out_layout = self.inner.layout;
        let out_samples = self.image_mut_slice();

        // Check if we can make use of batch copies, row-by-row.
        if in_layout.width_stride == usize::from(P::CHANNEL_COUNT)
            && out_layout.width_stride == usize::from(P::CHANNEL_COUNT)
        {
            // See `inner_copy_from` where we have the same trick (chunks_exact_mut with 0 stride is
            // not allowed).
            let rows = out_samples.chunks_exact_mut({
                if out_layout.height <= 1 {
                    out_samples.len()
                } else {
                    out_layout.height_stride
                }
            });

            let row_samples = target.width as usize * usize::from(P::CHANNEL_COUNT);
            for (k, orow) in rows
                .skip(target.y as usize)
                .take(target.height as usize)
                .enumerate()
            {
                let orow = &mut orow[target.x as usize * usize::from(P::CHANNEL_COUNT)..];
                let irow = &in_samples[k * in_layout.height_stride..];
                orow[..row_samples].copy_from_slice(&irow[..row_samples]);
            }

            return Ok(());
        }

        for k in 0..target.height {
            for i in 0..target.width {
                let iidx = in_layout.in_bounds_index(0, i, k);
                let oidx = out_layout.in_bounds_index(0, i + x, k + y);
                out_samples[oidx..][..usize::from(P::CHANNEL_COUNT)]
                    .copy_from_slice(&in_samples[iidx..][..usize::from(P::CHANNEL_COUNT)]);
            }
        }

        Ok(())
    }
}

// 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 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])
    }

    fn to_pixel_view(&self) -> Option<ViewOfPixel<'_, Self::Pixel>> {
        Some(View {
            inner: FlatSamples {
                samples: self.inner.samples.as_ref(),
                layout: self.inner.layout,
                color_hint: None,
            },
            phantom: PhantomData,
        })
    }
}

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 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])
    }

    fn to_pixel_view(&self) -> Option<ViewOfPixel<'_, Self::Pixel>> {
        Some(View {
            inner: FlatSamples {
                samples: self.inner.samples.as_ref(),
                layout: self.inner.layout,
                color_hint: None,
            },
            phantom: PhantomData,
        })
    }
}

impl<Buffer, P: Pixel> GenericImage for ViewMut<Buffer, P>
where
    Buffer: AsMut<[P::Subpixel]> + AsRef<[P::Subpixel]>,
{
    fn put_pixel(&mut self, x: u32, y: u32, pixel: 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]) = pixel;
    }

    fn copy_from<O>(&mut self, other: &O, x: u32, y: u32) -> crate::ImageResult<()>
    where
        O: GenericImageView<Pixel = Self::Pixel>,
    {
        if let Some(flat) = other.to_pixel_view() {
            return self.inner_copy_from_samples(flat, x, y);
        }

        self.inner_copy_from(other, x, y)
    }
}

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 (={pixel_channels}) does not agree with the layout (={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::color::{LumaA, Rgb};
    use crate::images::buffer::GrayAlphaImage;

    #[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));
            for i in 0..9 {
                view.put_pixel(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:?}"));
    }

    #[test]
    fn copy_buffer_like_view() {
        let src = View::with_monocolor(&LumaA([0xffu8, 0xfe]), 2, 3);

        let mut buffer = FlatSamples {
            samples: [0; 12],
            layout: SampleLayout {
                channels: 2,
                channel_stride: 1,
                width: 2,
                width_stride: 2,
                height: 3,
                height_stride: 4,
            },
            color_hint: None,
        };

        let mut view = buffer
            .as_view_mut::<LumaA<u8>>()
            .expect("This should be a valid mutable buffer");

        view.copy_from(&src, 0, 0)
            .expect("image fits into the target");

        assert_eq!(buffer.samples.as_chunks::<2>().0, [[0xff, 0xfe]; 6],);
    }

    #[test]
    fn copy_heightstride_view() {
        let src = View::with_monocolor(&LumaA([0xffu8, 0xfe]), 2, 3);

        // Each row has capacity for 5 channels, of which 4 are used.
        let mut buffer = FlatSamples {
            samples: [0; 15],
            layout: SampleLayout {
                channels: 2,
                channel_stride: 1,
                width: 2,
                width_stride: 2,
                height: 3,
                height_stride: 5,
            },
            color_hint: None,
        };

        let mut view = buffer
            .as_view_mut::<LumaA<u8>>()
            .expect("This should be a valid mutable buffer");

        view.copy_from(&src, 0, 0)
            .expect("image fits into the target");

        assert_eq!(
            buffer.samples.as_chunks::<5>().0,
            [[0xff, 0xfe, 0xff, 0xfe, 0]; 3],
        );
    }

    #[test]
    fn copy_widthstride_view() {
        let src = View::with_monocolor(&LumaA([0xffu8, 0xfe]), 2, 3);

        // Each row has capacity for 5 channels, of which 4 are used.
        let mut buffer = FlatSamples {
            samples: [0; 18],
            layout: SampleLayout {
                channels: 2,
                channel_stride: 1,
                width: 2,
                width_stride: 3,
                height: 3,
                height_stride: 6,
            },
            color_hint: None,
        };

        let mut view = buffer
            .as_view_mut::<LumaA<u8>>()
            .expect("This should be a valid mutable buffer");

        view.copy_from(&src, 0, 0)
            .expect("image fits into the target");

        assert_eq!(
            buffer.samples.as_chunks::<6>().0,
            [[0xff, 0xfe, 0, 0xff, 0xfe, 0]; 3],
        );
    }

    #[test]
    fn copy_column_major_view() {
        let src = View::with_monocolor(&LumaA([0xffu8, 0xfe]), 1, 3);

        // Each row has capacity for 5 channels, of which 4 are used.
        let mut buffer = FlatSamples {
            samples: [0; 14],
            layout: SampleLayout {
                channels: 2,
                channel_stride: 1,
                width: 2,
                width_stride: 8,
                height: 3,
                height_stride: 2,
            },
            color_hint: None,
        };

        let mut view = buffer
            .as_view_mut::<LumaA<u8>>()
            .expect("This should be a valid mutable buffer");

        view.copy_from(&src, 0, 0)
            .expect("image fits into the target");

        // First column, i.e. first 3 pixels, affected.
        assert_eq!(
            view.image_slice()[0..6].as_chunks::<2>().0,
            [[0xff, 0xfe]; 3],
        );
        // Everything else unchanged.
        assert_eq!(view.image_slice()[6..], [0; 8]);

        view.copy_from(&src, 1, 0)
            .expect("image fits into the target");

        assert_eq!(view.image_slice()[6..8], [0, 0]);
        assert_eq!(
            view.image_slice()[8..].as_chunks::<2>().0,
            [[0xff, 0xfe]; 3],
        );
    }
}

Coverage Report

Created: 2026-06-10 07:53