Struct ImageRef

Source

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

Expand description

A read-only view of an 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 byte slice for its initialization.

Implementations§

Source §

impl<L> ImageRef<'_, L>

Source

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.

Source §

impl<'data, L> ImageRef<'data, L>

Source

pub fn as_bytes(&self) -> &[u8]
where L: Layout,

Get a reference to those bytes used by the layout.

Source

pub fn as_buf(&self) -> &buf
where L: Layout,

Get a reference to the underlying buffer.

Source

pub fn as_capacity_buf(&self) -> &buf

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

Source

pub fn layout(&self) -> &L

Source

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

Get a view of this image.

Source

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

Check if a call to ImageRef::with_layout would succeed.

Source

pub fn with_layout<M>(self, layout: M) -> Option<ImageRef<'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 ImageRef::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, Matrix, layout::Bytes};
let image = Image::from(Matrix::<[u8; 4]>::with_width_and_height(10, 10));

let reference = image.as_ref();

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

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

Source

pub fn decay<M>(self) -> ImageRef<'data, M>
where M: Decay<L> + Layout,

Decay into a image with less specific layout.

See Image::decay.

Source

pub fn checked_decay<M>(self) -> Option<ImageRef<'data, M>>
where M: Decay<L> + Layout,

Like Self::decaybut returnsNone` rather than panicking. While this is strictly speaking a violation of the trait contract, you may want to handle this yourself.

Source

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 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 [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());

Source

pub fn as_slice(&self) -> &[L::Sample]
where L: SliceLayout,

Get a slice of the individual samples in the layout.

Source

pub fn as_texels(&self, pixel: Texel) -> &[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.

Source

pub fn into_bytes(self) -> &'data [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.

Source

pub fn into_slice(self) -> &'data [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.

Source

pub fn get_texel(&self, coord: Coord) -> Option
where L: Raster,

Retrieve a single texel from a raster image.

Source

pub fn split_layout(&mut self) -> ImageRef<'data, Bytes>
where L: Layout,

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

Source

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.

Source

pub fn into_planes<const N: usize, D>( self, descriptors: [D; N], ) -> Result<[ImageRef<'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::{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));
let image: ImageRef<'_, _> = buffer.as_ref();

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