Merge pull request #64 from image-rs/byte-buffer-wrappers

Polish byte buffer wrappers for release

Author: Aurelia Molzer

canvas/Cargo.toml

@@ -12,7 +12,7 @@ repository = "https://github.com/image-rs/canvas"
 categories = ["multimedia::images"]
 
 [dependencies]
-image-texel = { path = "../texel", version = "0.4.0" }
+image-texel = { path = "../texel", version = "0.5.0" }
 bytemuck = "1.1"
 
 [dev-dependencies]

texel/Cargo.toml

@@ -1,11 +1,11 @@
 [package]
 name = "image-texel"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2021"
 rust-version = "1.84"
 
 description = "A texel type and allocated buffers suitable for image data."
-authors = ["Aurelia Molzer <[email protected]>"]
+authors = ["Aurelia Molzer <[email protected]>"]
 license = "MIT"
 readme = "Readme.md"
 documentation = "https://docs.rs/image-texel"

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);
@@ -1418,6 +1443,34 @@ impl<P> Clone for AtomicSliceRef<'_, P> {
 
 impl<P> Copy for AtomicSliceRef<'_, P> {}
 
+impl<P> AtomicRef<'_, P> {
+    /// Modify the value stored in the reference.
+    ///
+    /// Note that this does *not* promise to be atomic in the whole value, just that it atomically
+    /// modifies the underlying buffer elements. The bytes of the value may be torn if another
+    /// write happens concurrently to the same element.
+    ///
+    /// However, it is guaranteed that the contents of any other non-aliased value in the buffer is
+    /// not modified even if they share the same atomic unit.
+    pub fn store(self, value: P) {
+        self.texel.store_atomic(self, value);
+    }
+
+    /// Retrieve a value stored in the reference.
+    ///
+    /// Note that this does *not* promise to be atomic in the whole value, just that it atomically
+    /// reads from the underlying buffer. The bytes of the value may be torn if another write
+    /// happens concurrently to the same element.
+    ///
+    /// If no such write occurs concurrently, when all writes are ordered-before or ordered-after
+    /// this load then the value is correct. This needs only hold to writes accessing the bytes
+    /// making up _this value_. Even if another values shares atomic units with this value their
+    /// writes are guaranteed to never modify the bits of this value.
+    pub fn load(self) -> P {
+        self.texel.load_atomic(self)
+    }
+}
+
 impl<P> Clone for AtomicRef<'_, P> {
     fn clone(&self) -> Self {
         AtomicRef { ..*self }
@@ -1430,13 +1483,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 +1565,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 +1586,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 [])
@@ -2084,4 +2162,30 @@ mod tests {
             );
         }
     }
+
+    #[test]
+    fn atomic_memory_move() {
+        const COPY_LEN: usize = 3 * core::mem::size_of::<MaxAtomic>();
+        const TOTAL_LEN: usize = 4 * core::mem::size_of::<MaxAtomic>();
+
+        for offset in 0..4 {
+            let data = [const { MaxAtomic::zero() }; 4];
+            let lhs = atomic_buf::new(&data[..]);
+
+            let data = [const { MaxAtomic::zero() }; 4];
+            let rhs = atomic_buf::new(&data[..]);
+
+            U8.store_atomic_slice(lhs.as_texels(U8).index(0..4), b"helo");
+
+            U8.atomic_memory_move(
+                lhs.as_texels(U8).index(offset..offset + COPY_LEN),
+                rhs.as_texels(U8).index(0..COPY_LEN),
+            );
+
+            let mut buffer = [0x42; TOTAL_LEN];
+            U8.load_atomic_slice(rhs.as_texels(U8), &mut buffer);
+
+            assert_eq!(buffer[..4], b"helo\0\0\0\0"[offset..][..4]);
+        }
+    }
 }

texel/src/image.rs

@@ -10,9 +10,10 @@
 //! advised, probably very common, and the only 'supported' use-case).
 mod atomic;
 mod cell;
-mod data;
 mod raw;
 
+pub mod data;
+
 use core::{fmt, ops};
 
 pub(crate) use self::raw::RawImage;
@@ -26,7 +27,7 @@ use crate::{BufferReuseError, Texel, TexelBuffer};
 pub use crate::stride::{StridedBufferMut, StridedBufferRef};
 pub use atomic::{AtomicImage, AtomicImageRef};
 pub use cell::{CellImage, CellImageRef};
-pub use data::{DataCells, DataMut, DataRef};
+pub use data::{AsCopySource, AsCopyTarget, DataCells, DataMut, DataRef};
 
 /// A container of allocated bytes, parameterized over the layout.
 ///
@@ -582,11 +583,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 +690,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 +924,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 +968,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 +1075,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