Struct CellImageRef 

pub struct CellImageRef<'buf, Layout = &'buf Bytes> { /* private fields */ }

A partial view of an atomic image.

Note that this requires its underlying buffer to be highly aligned! For that reason it is not possible to take a reference at an arbitrary number of bytes. Values of this type are created by calling CellImage::as_ref or CellImage::checked_to_ref.

Implementations

impl<'data, L> CellImageRef<'data, L>

pub fn as_cell_buf(&self) -> &cell_buf

where L: Layout,

Get a reference to the underlying buffer.

pub fn as_capacity_cell_buf(&self) -> &cell_buf

Get a reference to the complete underlying buffer, ignoring the layout.

pub fn layout(&self) -> &L

pub fn as_ref(&self) -> CellImageRef<'_, &L>

Get a view of this image.

pub fn fits(&self, other: &impl Layout) -> bool

Check if a call to CellImageRef::checked_with_layout would succeed.

pub fn checked_with_layout<M>(self, layout: M) -> Option<CellImageRef<'data, M>>

where M: Layout,

Change this view to a different layout.

This returns Some if the layout fits the underlying data, and None otherwise. Use CellImageRef::fits to check this property in a separate call. Note that the new layout need not be related to the old layout in any other way.

Usage

use image_texel::{image::CellImage, layout::Matrix, layout::Bytes};

let layout = Matrix::<[u8; 4]>::width_and_height(10, 10).unwrap();
let image = CellImage::new(layout);

let reference = image.as_ref();

let as_bytes = reference.checked_with_layout(Bytes(400))?;
assert!(matches!(as_bytes.layout(), Bytes(400)));

// But not if we request too much.
assert!(as_bytes.checked_with_layout(Bytes(500)).is_none());

pub fn decay<M>(self) -> CellImageRef<'data, M>

where M: Decay<L> + Layout,

Decay into a image with less specific layout.

See CellImage::decay.

pub fn checked_decay<M>(self) -> Option<CellImageRef<'data, M>>

where M: Decay<L> + Layout,

Decay into a image with less specific layout.

See CellImage::checked_decay.

pub fn into_owned(self) -> Image<L>

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::{CellImage, Image};
use image_texel::layout::{PlaneMatrices, Matrix};
use image_texel::texels::U8;

let matrix = Matrix::from_width_height(U8, 8, 8).unwrap();
let buffer = CellImage::new(PlaneMatrices::<_, 2>::from_repeated(matrix));

// … some code to initialize those planes.

let [plane1] = buffer.as_ref().into_planes([1]).unwrap();
let clone_of: Image<_> = plane1.clone().into_owned();

assert!(clone_of.as_bytes() == plane1.as_cell_buf());

pub fn as_slice(&self) -> &Cell<[L::Sample]>

where L: SliceLayout,

Get a slice of the individual samples in the layout.

pub fn as_texels<P>(&self, pixel: Texel<P>) -> &Cell<[P]>

where L: Layout,

View this buffer as a slice of pixels.

This reinterprets the bytes of the buffer. It can be used to view the buffer as any kind of pixel, regardless of its association with the layout. Use it with care.

An alternative way to get a slice of texels when a layout has an inherent texel type is Self::as_slice.

pub fn into_bytes(self) -> Vec<u8>

where L: Layout,

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, and the ImageMut need not stay alive.

pub fn into_slice(self) -> &'data Cell<[L::Sample]>

where L: SliceLayout,

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, and the ImageMut need not stay alive.

pub fn into_texels<P>(self, pixel: Texel<P>) -> &'data Cell<[P]>

where L: Layout,

View this buffer as a slice of pixels.

This reinterprets the bytes of the buffer. It can be used to view the buffer as any kind of pixel, regardless of its association with the layout. Use it with care.

An alternative way to get a slice of texels when a layout has an inherent texel type is Self::as_texels.

pub fn split_layout(&mut self) -> CellImageRef<'data, Bytes>

where L: Layout,

Split off all unused bytes at the tail of the layout.

pub fn truncate_layout(self) -> Self

where L: Layout,

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 into_planes<const N: usize, D>( self, descriptors: [D; N], ) -> Result<[CellImageRef<'data, D::Plane>; N], IntoPlanesError>

where D: PlaneOf<L>, D::Plane: Relocate,

Split this reference into independent planes.

If any plane fails their indexing operation or would not be aligned to the required alignment or any plane layouts would overlap, an error is returned. The planes are returned in the order of the descriptors.

FIXME: the layout type is not what we want. For instance, with PlaneMatrices we get a plane type of Relocated<Matrix<_>> but when we relocate that to 0 then we would really prefer having a simple Matrix<_> as the layout type.

Examples

A layout describing a matrix array can be split:

use image_texel::image::{CellImage, CellImageRef};
use image_texel::layout::{PlaneMatrices, Matrix};
use image_texel::texels::U8;

let mat = Matrix::from_width_height(U8, 8, 8).unwrap();
let buffer = CellImage::new(PlaneMatrices::<_, 2>::from_repeated(mat));
let image: CellImageRef<'_, _> = buffer.as_ref();

let [p0, p1] = buffer.as_ref().into_planes([0, 1]).unwrap();

You may select the same plane twice:

impl<L> CellImageRef<'_, L>

pub fn assign<E>( &mut self, data: AsCopySource<'_, E>, ) -> Result<(), BufferReuseError>

where E: LayoutEngine<Layout = L>, L: Layout,

Write to this image, modifying the view of layout in the process.

Returns an error and keeps the current layout unchanged if the allocated buffer does not fit the new data’s layout. Otherwise copies data and assigns the layout to the image buffer.

See AsCopySource::write_to_cell_image for changing the layout type in the process.

pub fn as_source(&self) -> AsCopySource<'_, RangeEngine<L>>

where L: Clone + Layout,

An adapter reading from the data as one contiguous chunk.

See RangeEngine for more explanations.

pub fn as_target(&mut self) -> AsCopyTarget<'_, RangeEngine<L>>

where L: Clone + Layout,

An adapter writing to this buffer in one contiguous chunk.

See RangeEngine for more explanations.

Trait Implementations

impl<'buf, Layout: Clone> Clone for CellImageRef<'buf, Layout>

fn clone(&self) -> CellImageRef<'buf, Layout>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'buf, Layout: Eq> Eq for CellImageRef<'buf, Layout>

impl<'buf, Layout: PartialEq> PartialEq for CellImageRef<'buf, Layout>

fn eq(&self, other: &CellImageRef<'buf, Layout>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'buf, Layout> StructuralPartialEq for CellImageRef<'buf, Layout>