Polish decay based interfaces

In particular we expect these to be infallible by default, the check on
length is redundant if implementations perform according to the trait
requirements. Thus, we design the APIs around returning a definitive
result.

This allow using decay as an unobstructive mechanism for 'do not care
about layout' through the fact that everything decays to `Bytes`.

Author: 197g

texel/src/image.rs

@@ -247,6 +247,16 @@ impl<L: Layout> Image<L> {
         self.inner.decay().into()
     }
 
+    /// Like [`Self::decay`]` but returns `None` rather than panicking. While this is strictly
+    /// speaking a violation of the trait contract, you may want to handle this yourself.
+    pub fn checked_decay<M>(self) -> Option<Image<M>>
+    where
+        M: Decay<L>,
+        M: Layout,
+    {
+        Some(self.inner.checked_decay()?.into())
+    }
+
     /// Move the buffer into a new image.
     pub fn take(&mut self) -> Image<L>
     where
@@ -550,7 +560,20 @@ impl<'data, L> ImageRef<'data, L> {
     /// Decay into a image with less specific layout.
     ///
     /// See [`Image::decay`].
-    pub fn decay<M>(self) -> Option<ImageRef<'data, M>>
+    pub fn decay<M>(self) -> ImageRef<'data, M>
+    where
+        M: Decay<L>,
+        M: Layout,
+    {
+        self.inner
+            .checked_decay()
+            .unwrap_or_else(decay_failed)
+            .into()
+    }
+
+    /// Like [`Self::decay`]` but returns `None` rather than panicking. While this is strictly
+    /// speaking a violation of the trait contract, you may want to handle this yourself.
+    pub fn checked_decay<M>(self) -> Option<ImageRef<'data, M>>
     where
         M: Decay<L>,
         M: Layout,
@@ -828,7 +851,20 @@ impl<'data, L> ImageMut<'data, L> {
     /// Decay into a image with less specific layout.
     ///
     /// See [`Image::decay`].
-    pub fn decay<M>(self) -> Option<ImageMut<'data, M>>
+    pub fn decay<M>(self) -> ImageMut<'data, M>
+    where
+        M: Decay<L>,
+        M: Layout,
+    {
+        self.inner
+            .checked_decay()
+            .unwrap_or_else(decay_failed)
+            .into()
+    }
+
+    /// Like [`Self::decay`]` but returns `None` rather than panicking. While this is strictly
+    /// speaking a violation of the trait contract, you may want to handle this yourself.
+    pub fn checked_decay<M>(self) -> Option<ImageMut<'data, M>>
     where
         M: Decay<L>,
         M: Layout,
@@ -1072,6 +1108,15 @@ impl<'data, L> ImageMut<'data, L> {
     }
 }
 
+fn decay_failed<T>() -> T {
+    #[cold]
+    fn decay_failed_inner() -> ! {
+        panic!("decayed layout is incompatible with the original layout");
+    }
+
+    decay_failed_inner()
+}
+
 impl IntoPlanesError {
     pub(crate) fn from_array<L, Buffer, const N: usize>(
         items: [(Option<L>, Buffer); N],

texel/src/image/atomic.rs

@@ -112,6 +112,19 @@ impl<L: Layout> AtomicImage<L> {
     /// ```
     ///
     /// [`Decay`]: ../layout/trait.Decay.html
+    pub fn decay<M>(self) -> AtomicImage<M>
+    where
+        M: Decay<L>,
+        M: Layout,
+    {
+        self.inner
+            .checked_decay()
+            .unwrap_or_else(super::decay_failed)
+            .into()
+    }
+
+    /// Like [`Self::decay`]` but returns `None` rather than panicking. While this is strictly
+    /// speaking a violation of the trait contract, you may want to handle this yourself.
     pub fn checked_decay<M>(self) -> Option<AtomicImage<M>>
     where
         M: Decay<L>,
@@ -374,6 +387,20 @@ impl<'data, L> AtomicImageRef<'data, L> {
         Some(self.inner.try_reinterpret(layout).ok()?.into())
     }
 
+    /// Decay into a image with less specific layout.
+    ///
+    /// See [`AtomicImage::decay`].
+    pub fn decay<M>(self) -> AtomicImageRef<'data, M>
+    where
+        M: Decay<L>,
+        M: Layout,
+    {
+        self.inner
+            .checked_decay()
+            .unwrap_or_else(super::decay_failed)
+            .into()
+    }
+
     /// Decay into a image with less specific layout.
     ///
     /// See [`AtomicImage::checked_decay`].

texel/src/image/cell.rs

@@ -81,7 +81,7 @@ impl<L: Layout> CellImage<L> {
     /// let image: CellImage<layout::Matrix<u8>> = CellImage::new(matrix);
     ///
     /// // to turn hide the `u8` type but keep width, height, texel layout
-    /// let as_bytes: CellImage<layout::MatrixBytes> = image.clone().checked_decay().unwrap();
+    /// let as_bytes: CellImage<layout::MatrixBytes> = image.clone().decay();
     /// assert_eq!(as_bytes.layout().width(), 400);
     /// assert_eq!(as_bytes.layout().height(), 400);
     /// ```
@@ -97,11 +97,24 @@ impl<L: Layout> CellImage<L> {
     /// let matrix = Matrix::<u8>::width_and_height(400, 400).unwrap();
     ///
     /// // Can always decay to a byte buffer.
-    /// let bytes: CellImage = CellImage::new(matrix).checked_decay().unwrap();
+    /// let bytes: CellImage = CellImage::new(matrix).decay();
     /// let _: &layout::Bytes = bytes.layout();
     /// ```
     ///
     /// [`Decay`]: ../layout/trait.Decay.html
+    pub fn decay<M>(self) -> CellImage<M>
+    where
+        M: Decay<L>,
+        M: Layout,
+    {
+        self.inner
+            .checked_decay()
+            .unwrap_or_else(super::decay_failed)
+            .into()
+    }
+
+    /// Like [`Self::decay`]` but returns `None` rather than panicking. While this is strictly
+    /// speaking a violation of the trait contract, you may want to handle this yourself.
     pub fn checked_decay<M>(self) -> Option<CellImage<M>>
     where
         M: Decay<L>,
@@ -357,6 +370,20 @@ impl<'data, L> CellImageRef<'data, L> {
         Some(self.inner.try_reinterpret(layout).ok()?.into())
     }
 
+    /// Decay into a image with less specific layout.
+    ///
+    /// See [`CellImage::decay`].
+    pub fn decay<M>(self) -> CellImageRef<'data, M>
+    where
+        M: Decay<L>,
+        M: Layout,
+    {
+        self.inner
+            .checked_decay()
+            .unwrap_or_else(super::decay_failed)
+            .into()
+    }
+
     /// Decay into a image with less specific layout.
     ///
     /// See [`CellImage::checked_decay`].

texel/src/image/unaligned.rs

@@ -8,7 +8,9 @@
 //! Design issues:
 //! - Many methods completely disregard some of the layouts. When we write into an `Image` for
 //!   instance, we treat it just as a container for bytes under the _input_ layout. We do not
-//!   interact with the target's layout at all.
+//!   interact with the target's layout at all. In these cases we request a `Bytes` layout as an
+//!   explicit opt-in. You can [`decay`][`Image::decay`] all buffer types to conveniently do so at
+//!   the call site.
 //! - Atomic inputs are probably valuable but we can not command users to use our own atomic type.
 //!   Since atomic sizes must not mix, these kinds of buffers require different copy methods for
 //!   each single kind of underlying atomic! Not providing these however risks users doing unsound
@@ -21,7 +23,6 @@
 //!   `Image` by interpreting it as `Image<Relocated<Plane>>`. This however is still wrong. When we
 //!   write of course the aliasing of other planes is not considered. And we never read the
 //!   relocation offset, again just disregarding any existing layout data. This is a big trap.
-//!
 //! - To expand, of course it is also improper to expect that the input buffer contains enough data
 //!   for the whole image, instead it is probably just that single plane. This messes with the
 //!   expectations and types involved in the 'copy engine' implementation detail. What is missing
@@ -32,7 +33,6 @@
 //! - Do we stack strategies, and how? In particular when copying an array of planes each of which
 //!   are matrices we want to copy everything row-by-row but right now this would require a
 //!   specialized engine for `impl Planar<impl MatrixLayout>` instead of being able to compose.
-//!
 //! - Think of blitting. When we write multiple planes, the input data can contain them completely
 //!   unaligned but this can not be expressed with properly planar layouts. We not a 'packed
 //!   planes' type or so that does not implement `PlaneOf` in terms of `Relocated<T>`.
@@ -507,7 +507,7 @@ impl<E: LayoutEngine> AsCopySource<'_, E> {
     ///
     /// Reallocates the image buffer when necessary to ensure that the allocated buffer fits the
     /// new data's layout.
-    pub fn write_to_image(mut self, buffer: Image<impl Layout>) -> Image<E::Layout> {
+    pub fn write_to_image(mut self, buffer: Image<Bytes>) -> Image<E::Layout> {
         let mut buffer = buffer.with_layout(self.engine.consume_layout());
         self.engine_to_buf_at(buffer.as_capacity_buf_mut());
         buffer
@@ -519,7 +519,7 @@ impl<E: LayoutEngine> AsCopySource<'_, E> {
     /// reference to the target buffer that is using the data's layout. Otherwise, returns `None`.
     pub fn write_to_mut<'data>(
         mut self,
-        buffer: ImageMut<'data, impl Layout>,
+        buffer: ImageMut<'data, Bytes>,
     ) -> Option<ImageMut<'data, E::Layout>> {
         let mut buffer = buffer.with_layout(self.engine.consume_layout())?;
         self.engine_to_buf_at(buffer.as_mut_buf());
@@ -531,7 +531,7 @@ impl<E: LayoutEngine> AsCopySource<'_, E> {
     /// Fails when allocated buffer does not fits the new data's layout.
     pub fn write_to_cell_image(
         mut self,
-        buffer: CellImage<impl Layout>,
+        buffer: CellImage<Bytes>,
     ) -> Option<CellImage<E::Layout>>
     where
         E::Layout: Clone + Layout,
@@ -547,7 +547,7 @@ impl<E: LayoutEngine> AsCopySource<'_, E> {
     /// reference to the target buffer that is using the data's layout. Otherwise, returns `None`.
     pub fn write_to_cell_ref<'data>(
         mut self,
-        buffer: CellImageRef<'data, impl Layout>,
+        buffer: CellImageRef<'data, Bytes>,
     ) -> Option<CellImageRef<'data, E::Layout>> {
         let buffer = buffer.checked_with_layout(self.engine.consume_layout())?;
         self.engine_to_buf_at(buffer.as_cell_buf());
@@ -559,7 +559,7 @@ impl<E: LayoutEngine> AsCopySource<'_, E> {
     /// Fails when allocated buffer does not fits the new data's layout.
     pub fn write_to_atomic_image(
         mut self,
-        buffer: AtomicImage<impl Layout>,
+        buffer: AtomicImage<Bytes>,
     ) -> Option<AtomicImage<E::Layout>>
     where
         E::Layout: Clone + Layout,
@@ -575,7 +575,7 @@ impl<E: LayoutEngine> AsCopySource<'_, E> {
     /// reference to the target buffer that is using the data's layout. Otherwise, returns `None`.
     pub fn write_to_atomic_ref<'data>(
         mut self,
-        buffer: AtomicImageRef<'data, impl Layout>,
+        buffer: AtomicImageRef<'data, Bytes>,
     ) -> Option<AtomicImageRef<'data, E::Layout>>
     where
         E::Layout: Clone + Layout,
@@ -615,23 +615,23 @@ impl<E: LayoutEngine> AsCopyTarget<'_, E> {
     ///
     /// This reads data up to our layout. It does not interpret the data with the layout of
     /// the argument buffer.
-    pub fn read_from_ref(&mut self, buffer: ImageRef<'_, impl Layout>) {
+    pub fn read_from_ref(&mut self, buffer: ImageRef<'_, Bytes>) {
         self.engine_from_buf_at(buffer.as_buf());
     }
 
     /// Read out data from a borrowed buffer.
     ///
     /// This reads data up to our layout. It does not interpret the data with the layout of
     /// the argument buffer.
-    pub fn read_from_cell_ref(&mut self, buffer: CellImageRef<'_, impl Layout>) {
+    pub fn read_from_cell_ref(&mut self, buffer: CellImageRef<'_, Bytes>) {
         self.engine_from_buf_at(buffer.as_cell_buf());
     }
 
     /// Read out data from a borrowed buffer.
     ///
     /// This reads data up to our layout. It does not interpret the data with the layout of
     /// the argument buffer.
-    pub fn read_from_atomic_ref(&mut self, buffer: CellImageRef<'_, impl Layout>) {
+    pub fn read_from_atomic_ref(&mut self, buffer: CellImageRef<'_, Bytes>) {
         self.engine_from_buf_at(buffer.as_cell_buf());
     }
 }

texel/src/layout.rs

@@ -92,7 +92,9 @@ impl dyn Layout + '_ {
 ///
 /// In general, a layout `L` should implement `Decay<T>` if any image with layouts of type `T` is
 /// also valid for some layout of type `L`. A common example would be if a crate strictly adds more
-/// information to a predefined layout, then it should also decay to that layout.
+/// information to a predefined layout, then it should also decay to that layout. It is invalid to
+/// decay to a layout that somehow expands outside the initial layout, you must weaken the buffer
+/// required.
 ///
 /// Also note that this trait is not reflexive, in contrast to `From` and `Into` which are. This
 /// avoids collisions in impls. In particular, it allows adding blanket impls of the form

texel/tests/data_transfer.rs

@@ -30,7 +30,7 @@ fn planar_io() {
     let target = Image::new(layout.clone());
 
     let data = DataRef::with_layout_at(input.data, input.layout, 0).unwrap();
-    let reinterpreted = data.as_source().write_to_image(target);
+    let reinterpreted = data.as_source().write_to_image(target.decay());
 
     // Layout must match, as must the bytes within the layout.
     assert_eq!(*reinterpreted.layout(), input.layout);
@@ -45,11 +45,11 @@ fn planar_io() {
     assert_ne!(small.as_buf().as_bytes(), input.data);
     assert_ne!(post.as_buf().as_bytes(), input.data);
 
-    assert!(data.as_source().write_to_mut(small).is_none());
+    assert!(data.as_source().write_to_mut(small.decay()).is_none());
 
     let post = data
         .as_source()
-        .write_to_mut(post)
+        .write_to_mut(post.decay())
         .expect("that plane was large enough");
     // Modify that other independent plane for good measure.
     pre.as_mut_buf().fill(0);