Various utilities for getting an owning buffer

Author: 197g

texel/src/buf.rs

@@ -8,6 +8,7 @@ use alloc::rc::Rc;
 use alloc::sync::Arc;
 use alloc::vec::Vec;
 
+use crate::rec::TexelBuffer;
 use crate::texel::{constants::MAX, AtomicPart, MaxAligned, MaxAtomic, MaxCell, Texel, MAX_ALIGN};
 
 /// Allocates and manages raw bytes.
@@ -1017,6 +1018,12 @@ impl cmp::PartialEq<[u8]> for cell_buf {
     }
 }
 
+impl cmp::PartialEq<cell_buf> for [u8] {
+    fn eq(&self, other: &cell_buf) -> bool {
+        crate::texels::U8.cell_bytes_eq(other.0.as_slice_of_cells(), self)
+    }
+}
+
 impl cmp::Eq for cell_buf {}
 
 impl cmp::PartialEq for CellBuffer {
@@ -1370,6 +1377,24 @@ impl<'lt, P> AtomicSliceRef<'lt, P> {
         self.texel.load_atomic_slice(*self, data);
     }
 
+    /// Read all values into a newly allocated vector.
+    pub fn to_vec(&self) -> Vec<P> {
+        // FIXME: avoid zero-initializing. Might need a bit more unsafe code that extends a vector
+        // of Texel<P> from that atomic.
+        let mut fresh: Vec<P> = (0..self.len()).map(|_| self.texel.zeroed()).collect();
+        self.write_to_slice(&mut fresh);
+        fresh
+    }
+
+    /// Read all values into a newly allocated texel buffer.
+    pub fn to_texel_buffer(&self) -> TexelBuffer<P> {
+        // FIXME: avoid zero-initializing. Might need a bit more unsafe code that extends a vector
+        // of Texel<P> from that atomic.
+        let mut fresh = TexelBuffer::new_for_texel(self.texel, self.len());
+        self.write_to_slice(&mut fresh);
+        fresh
+    }
+
     #[track_caller]
     pub fn split_at(self, at: usize) -> (Self, Self) {
         let left = self.index(..at);
@@ -1430,13 +1455,21 @@ impl<P> Copy for AtomicRef<'_, P> {}
 ///
 /// Note this type also has the invariant that the identified range fits into memory for the given
 /// texel type.
-#[derive(Clone, Copy, Debug)]
+#[derive(Debug)]
 pub struct TexelRange<T> {
     texel: Texel<T>,
     start_per_align: usize,
     end_per_align: usize,
 }
 
+impl<T> Clone for TexelRange<T> {
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+
+impl<T> Copy for TexelRange<T> {}
+
 impl<T> TexelRange<T> {
     /// Create a new range from a texel type and a range (in units of `T`).
     pub fn new(texel: Texel<T>, range: ops::Range<usize>) -> Option<Self> {
@@ -1504,14 +1537,19 @@ impl<T> TexelRange<T> {
             end_per_align: end_byte / texel.align(),
         })
     }
+
+    /// Intrinsically, all ranges represent an aligned range of bytes.
+    fn aligned_byte_range(self) -> ops::Range<usize> {
+        let scale = self.texel.align();
+        scale * self.start_per_align..scale * self.end_per_align
+    }
 }
 
 impl<T> core::ops::Index<TexelRange<T>> for buf {
     type Output = [T];
 
     fn index(&self, index: TexelRange<T>) -> &Self::Output {
-        let scale = index.texel.align();
-        let bytes = &self.0[scale * index.start_per_align..scale * index.end_per_align];
+        let bytes = &self.0[index.aligned_byte_range()];
         let slice = index.texel.try_to_slice(bytes);
         // We just multiplied the indices by the alignment..
         slice.expect("byte indices validly aligned")
@@ -1520,14 +1558,26 @@ impl<T> core::ops::Index<TexelRange<T>> for buf {
 
 impl<T> core::ops::IndexMut<TexelRange<T>> for buf {
     fn index_mut(&mut self, index: TexelRange<T>) -> &mut Self::Output {
-        let scale = index.texel.align();
-        let bytes = &mut self.0[scale * index.start_per_align..scale * index.end_per_align];
+        let bytes = &mut self.0[index.aligned_byte_range()];
         let slice = index.texel.try_to_slice_mut(bytes);
         // We just multiplied the indices by the alignment..
         slice.expect("byte indices validly aligned")
     }
 }
 
+impl<T> core::ops::Index<TexelRange<T>> for cell_buf {
+    type Output = [cell::Cell<T>];
+
+    fn index(&self, index: TexelRange<T>) -> &Self::Output {
+        let bytes = &self.0.as_slice_of_cells()[index.aligned_byte_range()];
+        let slice = index.texel.try_to_cell(bytes);
+        // We just multiplied the indices by the alignment..
+        slice
+            .expect("byte indices validly aligned")
+            .as_slice_of_cells()
+    }
+}
+
 impl Default for &'_ cell_buf {
     fn default() -> Self {
         cell_buf::new(&mut [])

texel/src/image.rs

@@ -582,11 +582,37 @@ impl<'data, L> ImageRef<'data, L> {
     }
 
     /// Copy all bytes to a newly allocated image.
-    pub fn to_owned(&self) -> Image<L>
-    where
-        L: Layout + Clone,
-    {
-        Image::with_bytes(self.inner.layout().clone(), self.inner.as_bytes())
+    ///
+    /// Note this will allocate a buffer according to the capacity length of this reference, not
+    /// merely the layout. When this is not the intention, consider calling [`Self::split_layout`]
+    /// or [`Self::truncate_layout`] respectively.
+    ///
+    /// # Examples
+    ///
+    /// Here we make an independent copy of the second plane of a composite image.
+    ///
+    /// ```
+    /// use image_texel::image::{Image, ImageRef};
+    /// use image_texel::layout::{PlaneMatrices, Matrix};
+    /// use image_texel::texels::U8;
+    ///
+    /// let mat = Matrix::from_width_height(U8, 8, 8).unwrap();
+    /// let buffer = Image::new(PlaneMatrices::<_, 2>::from_repeated(mat));
+    ///
+    /// // … some code to initialize those planes.
+    /// # let mut buffer = buffer;
+    /// # buffer.as_mut().into_planes([1]).unwrap()[0]
+    /// #     .as_capacity_buf_mut()[..8].copy_from_slice(b"not zero");
+    /// # let buffer = buffer;
+    ///
+    /// let [p1] = buffer.as_ref().into_planes([1]).unwrap();
+    /// let clone_of: Image<_> = p1.into_owned();
+    ///
+    /// let [p1] = buffer.as_ref().into_planes([1]).unwrap();
+    /// assert_eq!(clone_of.as_bytes(), p1.as_bytes());
+    /// ```
+    pub fn into_owned(self) -> Image<L> {
+        self.inner.into_owned().into()
     }
 
     /// Get a slice of the individual samples in the layout.
@@ -663,6 +689,18 @@ impl<'data, L> ImageRef<'data, L> {
         RawImage::from_buffer(Bytes(next.len()), next).into()
     }
 
+    /// Remove all past-the-layout bytes.
+    ///
+    /// This is a utility to combine with pipelining. It is equivalent to calling
+    /// [`Self::split_layout`] and discarding that result.
+    pub fn truncate_layout(mut self) -> Self
+    where
+        L: Layout,
+    {
+        let _ = self.split_layout();
+        self
+    }
+
     /// Split this reference into independent planes.
     ///
     /// If any plane fails their indexing operation or would not be aligned to the required
@@ -885,14 +923,6 @@ impl<'data, L> ImageMut<'data, L> {
         Some(self.inner.checked_decay()?.into())
     }
 
-    /// Copy the bytes and layout to an owned container.
-    pub fn to_owned(&self) -> Image<L>
-    where
-        L: Layout + Clone,
-    {
-        Image::with_bytes(self.inner.layout().clone(), self.inner.as_bytes())
-    }
-
     /// Get a slice of the individual samples in the layout.
     pub fn as_slice(&self) -> &[L::Sample]
     where
@@ -937,6 +967,38 @@ impl<'data, L> ImageMut<'data, L> {
         pixel.cast_mut_buf(self.inner.as_mut_buf())
     }
 
+    /// Copy all bytes to a newly allocated image.
+    ///
+    /// Note this will allocate a buffer according to the capacity length of this reference, not
+    /// merely the layout. When this is not the intention, consider calling [`Self::split_layout`]
+    /// or [`Self::truncate_layout`] respectively.
+    ///
+    /// # Examples
+    ///
+    /// Here we make an independent copy of the second plane of a composite image.
+    ///
+    /// ```
+    /// use image_texel::image::{Image, ImageRef};
+    /// use image_texel::layout::{PlaneMatrices, Matrix};
+    /// use image_texel::texels::U8;
+    ///
+    /// let mat = Matrix::from_width_height(U8, 8, 8).unwrap();
+    /// let mut buffer = Image::new(PlaneMatrices::<_, 2>::from_repeated(mat));
+    ///
+    /// // … some code to initialize those planes.
+    /// # buffer.as_mut().into_planes([1]).unwrap()[0]
+    /// #     .as_capacity_buf_mut()[..8].copy_from_slice(b"not zero");
+    ///
+    /// let [p1] = buffer.as_mut().into_planes([1]).unwrap();
+    /// let clone_of: Image<_> = p1.into_owned();
+    ///
+    /// let [p1] = buffer.as_ref().into_planes([1]).unwrap();
+    /// assert_eq!(clone_of.as_bytes(), p1.as_bytes());
+    /// ```
+    pub fn into_owned(self) -> Image<L> {
+        self.inner.into_owned().into()
+    }
+
     /// Turn into a slice of the individual samples in the layout.
     ///
     /// This preserves the lifetime with which the layout is borrowed from the underlying image,
@@ -1012,6 +1074,18 @@ impl<'data, L> ImageMut<'data, L> {
         RawImage::from_buffer(Bytes(next.len()), next).into()
     }
 
+    /// Remove all past-the-layout bytes.
+    ///
+    /// This is a utility to combine with pipelining. It is equivalent to calling
+    /// [`Self::split_layout`] and discarding that result.
+    pub fn truncate_layout(mut self) -> Self
+    where
+        L: Layout,
+    {
+        let _ = self.split_layout();
+        self
+    }
+
     /// Split this mutable reference into independent planes.
     ///
     /// If any plane fails their indexing operation or would not be aligned to the required

texel/src/image/atomic.rs

@@ -2,7 +2,7 @@
 //!
 //! Re-exported at its super `image` module.
 use crate::buf::{atomic_buf, AtomicBuffer, AtomicSliceRef};
-use crate::image::{raw::RawImage, IntoPlanesError};
+use crate::image::{raw::RawImage, Image, IntoPlanesError};
 use crate::layout::{Bytes, Decay, Layout, Mend, PlaneOf, Relocate, SliceLayout, Take, TryMend};
 use crate::texel::{constants::U8, MAX_ALIGN};
 use crate::{BufferReuseError, Texel, TexelBuffer};
@@ -146,6 +146,36 @@ impl<L: Layout> AtomicImage<L> {
         Some(self.inner.checked_decay()?.into())
     }
 
+    /// Copy all bytes to a newly allocated image.
+    ///
+    /// Note this will allocate a buffer according to the capacity length of this reference, not
+    /// merely the layout. When this is not the intention, consider calling [`Self::split_layout`]
+    /// or [`Self::truncate_layout`] respectively.
+    ///
+    /// # Examples
+    ///
+    /// Here we make an independent copy of a pixel matrix image.
+    ///
+    /// ```
+    /// use image_texel::image::{AtomicImage, Image};
+    /// use image_texel::layout::{PlaneMatrices, Matrix};
+    /// use image_texel::texels::U8;
+    ///
+    /// let matrix = Matrix::from_width_height(U8, 8, 8).unwrap();
+    /// let buffer = AtomicImage::new(matrix);
+    ///
+    /// // … some code to initialize those planes.
+    /// # let data = buffer.as_texels(U8).index(0..8);
+    /// # U8.store_atomic_slice(data, b"not zero");
+    ///
+    /// let clone_of: Image<_> = buffer.clone().into_owned();
+    ///
+    /// assert!(clone_of.as_bytes() == buffer.as_texels(U8).to_vec());
+    /// ```
+    pub fn into_owned(self) -> Image<L> {
+        self.inner.into_owned().into()
+    }
+
     /// Move the bytes into a new image.
     ///
     /// Afterwards, `self` will refer to an empty but unique new buffer.
@@ -438,6 +468,38 @@ impl<'data, L> AtomicImageRef<'data, L> {
         Some(self.inner.checked_decay()?.into())
     }
 
+    /// Copy all bytes to a newly allocated image.
+    ///
+    /// Note this will allocate a buffer according to the capacity length of this reference, not
+    /// merely the layout. When this is not the intention, consider calling [`Self::split_layout`]
+    /// or [`Self::truncate_layout`] respectively.
+    ///
+    /// # Examples
+    ///
+    /// Here we make an independent copy of a pixel matrix image.
+    ///
+    /// ```
+    /// use image_texel::image::{AtomicImage, Image};
+    /// use image_texel::layout::{PlaneMatrices, Matrix};
+    /// use image_texel::texels::U8;
+    ///
+    /// let matrix = Matrix::from_width_height(U8, 8, 8).unwrap();
+    /// let buffer = AtomicImage::new(PlaneMatrices::<_, 2>::from_repeated(matrix));
+    ///
+    /// // … some code to initialize those planes.
+    /// # let [plane] = buffer.as_ref().into_planes([1]).unwrap();
+    /// # let data = buffer.as_texels(U8).index(0..8);
+    /// # U8.store_atomic_slice(data, b"not zero");
+    ///
+    /// let [plane1] = buffer.as_ref().into_planes([1]).unwrap();
+    /// let clone_of: Image<_> = plane1.clone().into_owned();
+    ///
+    /// assert!(clone_of.as_bytes() == plane1.as_texels(U8).to_vec());
+    /// ```
+    pub fn into_owned(self) -> Image<L> {
+        self.inner.into_owned().into()
+    }
+
     /// Get a slice of the individual samples in the layout.
     pub fn as_slice(&self) -> AtomicSliceRef<'_, L::Sample>
     where
@@ -473,11 +535,7 @@ impl<'data, L> AtomicImageRef<'data, L> {
         let (buffer, layout) = self.inner.into_parts();
         let len = layout.byte_len();
 
-        // FIXME: avoid zero-initializing. Might need a bit more unsafe code that extends a vector
-        // of Texel<P> from that atomic.
-        let mut target = alloc::vec![0; len];
-        U8.load_atomic_slice(buffer.as_texels(U8).truncate_bytes(len), &mut target);
-        target
+        buffer.as_texels(U8).truncate_bytes(len).to_vec()
     }
 
     /// Turn into a slice of the individual samples in the layout.
@@ -548,6 +606,18 @@ impl<'data, L> AtomicImageRef<'data, L> {
         RawImage::from_buffer(Bytes(next.len()), next).into()
     }
 
+    /// Remove all past-the-layout bytes.
+    ///
+    /// This is a utility to combine with pipelining. It is equivalent to calling
+    /// [`Self::split_layout`] and discarding that result.
+    pub fn truncate_layout(mut self) -> Self
+    where
+        L: Layout,
+    {
+        let _ = self.split_layout();
+        self
+    }
+
     /// Split this reference into independent planes.
     ///
     /// If any plane fails their indexing operation or would not be aligned to the required