Polish interface for efficient copy

Since conversion is fallible, using `to_*` is more appropriate.

Backport-Of: 41046d3

Author: 197g

src/images/buffer.rs

@@ -10,7 +10,7 @@ use crate::color::{FromColor, FromPrimitive, Luma, LumaA, Rgb, Rgba};
 use crate::error::{
     ImageResult, ParameterError, ParameterErrorKind, UnsupportedError, UnsupportedErrorKind,
 };
-use crate::flat::{FlatSamples, SampleLayout, View};
+use crate::flat::{FlatSamples, SampleLayout, ViewOfPixel};
 use crate::math::Rect;
 use crate::metadata::cicp::{CicpApplicable, CicpPixelCast, CicpRgb, ColorComponentForCicp};
 use crate::traits::{EncodableLayout, Pixel, PixelWithColorType};
@@ -1238,7 +1238,7 @@ where
         *self.get_pixel(x, y)
     }
 
-    fn as_samples(&self) -> Option<View<&[<Self::Pixel as Pixel>::Subpixel], Self::Pixel>> {
+    fn to_pixel_view(&self) -> Option<ViewOfPixel<'_, Self::Pixel>> {
         let samples = FlatSamples {
             samples: &*self.data,
             layout: self.sample_layout(),
@@ -1292,7 +1292,7 @@ where
 
     fn copy_from_samples(
         &mut self,
-        view: View<&[<Self::Pixel as Pixel>::Subpixel], Self::Pixel>,
+        view: ViewOfPixel<'_, Self::Pixel>,
         x: u32,
         y: u32,
     ) -> ImageResult<()> {

src/images/flat.rs

@@ -1437,7 +1437,7 @@ where
         *P::from_slice(&buffer[..channels])
     }
 
-    fn as_samples(&self) -> Option<View<&[<Self::Pixel as Pixel>::Subpixel], Self::Pixel>> {
+    fn to_pixel_view(&self) -> Option<ViewOfPixel<'_, Self::Pixel>> {
         Some(View {
             inner: FlatSamples {
                 samples: self.inner.samples.as_ref(),
@@ -1481,7 +1481,7 @@ where
         *P::from_slice(&buffer[..channels])
     }
 
-    fn as_samples(&self) -> Option<View<&[<Self::Pixel as Pixel>::Subpixel], Self::Pixel>> {
+    fn to_pixel_view(&self) -> Option<ViewOfPixel<'_, Self::Pixel>> {
         Some(View {
             inner: FlatSamples {
                 samples: self.inner.samples.as_ref(),

src/images/generic_image.rs

@@ -1,5 +1,5 @@
 use crate::error::{ImageError, ImageResult};
-use crate::flat::{View, ViewOfPixel};
+use crate::flat::ViewOfPixel;
 use crate::math::Rect;
 use crate::traits::Pixel;
 use crate::{ImageBuffer, SubImage};
@@ -140,8 +140,17 @@ pub trait GenericImageView {
         ImageBuffer::new(width, height)
     }
 
-    /// If the buffer has a fitting layout, return a view of the samples descriptor.
-    fn as_samples(&self) -> Option<ViewOfPixel<'_, Self::Pixel>> {
+    /// If the buffer has a fitting layout, return a canonical view of the samples.
+    ///
+    /// This is the basis of optimization and by default return `None`. It lets consumers of
+    /// generic images access the sample data through a canonical descriptor of its layout directly
+    /// instead of pixel-by-pixel. This provides more efficient forms of access that the
+    /// [`GenericImageView`] trait itself does not demand from all its implementations.
+    ///
+    /// Implementation of this method should be cheap to call.
+    ///
+    /// If implemented, a [`SubImage`] proxy of this image will provide a sample view as well.
+    fn to_pixel_view(&self) -> Option<ViewOfPixel<'_, Self::Pixel>> {
         None
     }
 }
@@ -254,7 +263,7 @@ pub trait GenericImage: GenericImageView {
     where
         O: GenericImageView<Pixel = Self::Pixel>,
     {
-        if let Some(flat) = other.as_samples() {
+        if let Some(flat) = other.to_pixel_view() {
             return self.copy_from_samples(flat, x, y);
         }
 
@@ -275,7 +284,7 @@ pub trait GenericImage: GenericImageView {
     /// Copy pixels from a regular strided matrix of pixels.
     fn copy_from_samples(
         &mut self,
-        samples: View<&[<Self::Pixel as Pixel>::Subpixel], Self::Pixel>,
+        samples: ViewOfPixel<'_, Self::Pixel>,
         x: u32,
         y: u32,
     ) -> ImageResult<()> {

src/images/sub_image.rs

@@ -1,4 +1,4 @@
-use crate::{flat::View, GenericImage, GenericImageView, ImageBuffer, Pixel};
+use crate::{flat::ViewOfPixel, GenericImage, GenericImageView, ImageBuffer, Pixel};
 use std::ops::{Deref, DerefMut};
 
 /// A View into another image
@@ -209,8 +209,8 @@ where
         self.image.buffer_with_dimensions(width, height)
     }
 
-    fn as_samples(&self) -> Option<View<&'_ [<Self::Pixel as Pixel>::Subpixel], Self::Pixel>> {
-        let inner = self.image.as_samples()?;
+    fn to_pixel_view(&self) -> Option<ViewOfPixel<'_, Self::Pixel>> {
+        let inner = self.image.to_pixel_view()?;
 
         // Now pivot the inner descriptor.
         let mut descriptor = inner.into_inner();