Struct ImageMut

Source

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

Expand description

A writeable reference to an image buffer.

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> ImageMut<'_, L>

Source

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

Write to an image, changing the 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_mut for changing the layout type in the process.

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

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.

Source §

impl<'data, L> ImageMut<'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_bytes_mut(&mut self) -> &mut [u8]
where L: Layout,

Get a mutable 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_mut_buf(&mut self) -> &mut buf
where L: Layout,

Get a mutable 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 as_capacity_buf_mut(&mut self) -> &mut buf

Get a mutable reference to the 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 as_mut(&mut self) -> ImageMut<'_, &mut L>

Get a mutable view of this image.

Source

pub fn into_ref(self) -> ImageRef<'data, L>

Convert to a view of this image.

Source

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

Check if a call to ImageMut::with_layout would succeed, without consuming this reference.

Source

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

let reference = image.as_mut();

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) -> ImageMut<'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<ImageMut<'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 as_slice(&self) -> &[L::Sample]
where L: SliceLayout,

Get a slice of the individual samples in the layout.

Source

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

Get a mutable 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 as_mut_texels(&mut self, pixel: Texel) -> &mut [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_mut_slice.

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 mut buffer = Image::new(PlaneMatrices::<_, 2>::from_repeated(mat));

// … some code to initialize those planes.

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

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 into_mut_slice(self) -> &'data mut [L::Sample]
where L: SliceLayout,

Turn into a mutable 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 put_texel(&mut self, coord: Coord, texel: P)
where L: RasterMut,

Put a single texel to a raster image.

Source

pub fn shade(&mut self, f: impl FnMut(u32, u32, &mut P))
where L: RasterMut,

Call a function on each texel of this raster image.

The order of evaluation is not defined although certain layouts may offer more specific guarantees. In general, one can expect that layouts call the function in a cache-efficient manner if they are aware of a better iteration strategy.

Source

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

Split off 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<[ImageMut<'data, D::Plane>; N], IntoPlanesError>
where D: PlaneOf<L>, D::Plane: Relocate,

Split this mutable reference into independent planes.

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

§Examples

A layout describing a matrix array can be split:

use image_texel::image::{Image, ImageMut};
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));
let image: ImageMut<'_, _> = buffer.as_mut();

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

Contrary to a shared buffer, it is not possible to select the same plane twice or for planes to overlap:

use image_texel::image::{Image, ImageMut};
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));
let image: ImageMut<'_, _> = buffer.as_mut();

assert!(image.into_planes([0, 0]).is_err(), "cannot have the same mutable references");