Struct image_canvas::Canvas

pub struct Canvas { /* private fields */ }

A byte buffer with dynamic color contents.

Implementations

impl Canvas

pub fn new(layout: CanvasLayout) -> Self

Create a frame by its layout.

Usage

use image_canvas::Canvas;
use image_canvas::layout::{CanvasLayout, SampleParts, Texel};

// Define what type of color we want to store...
let texel = Texel::new_u8(SampleParts::RgbA);
// and which dimensions to use, chooses a stride for us.
let layout = CanvasLayout::with_texel(&texel, 32, 32)?;

let frame = Canvas::new(layout);

pub fn layout(&self) -> &CanvasLayout

Get a reference to the layout of this frame.

pub fn set_layout(&mut self, layout: CanvasLayout)

Overwrite the layout, allocate if necessary, and clear the image.

pub fn set_layout_conservative(&mut self, layout: CanvasLayout)

Overwrite the layout, allocate if necessary, do not clear the image.

pub fn as_bytes(&self) -> &[u8]

Return this image’s pixels as a native endian byte slice.

See also Self::as_bytes_mut.

pub fn as_bytes_mut(&mut self) -> &mut [u8]

Return this image’s pixels as a mutable native endian byte slice.

The exact interpretation of each byte depends on the layout, which also contains a descriptor of the color types used. This method is for purposes of foreign-function interfaces and as a fallback to process bytes regardless of any restrictions placed by the limits of what other methods are offered.

Mind that the library guarantees that the byte slice is actually aligned with an alignment larger than 1. The exact details depend on the underlying platform but are at least 8.

Still, do not write uninitialized bytes to the buffer. This is UB by Rust’s semantics. (Writing into the buffer by syscalls or assembly most likely never counts as writing uninitialized bytes but take this with a grain of salt).

pub fn as_texels<T>(&self, texel: Texel<T>) -> &[T]

Return the bytes making up this image as a slice of arbitrary elements.

pub fn as_texels_mut<T>(&mut self, texel: Texel<T>) -> &mut [T]

Return the bytes making up this image as a slice of arbitrary elements.

pub fn channels_u8(&self) -> Option<ChannelsRef<'_, u8>>

Get the matrix-like channel descriptor if the channels are u8.

Returns Some only when texel is some multiple of u8.

pub fn channels_u16(&self) -> Option<ChannelsRef<'_, u16>>

Get the matrix-like channel descriptor if the channels are u16.

Returns Some only when texel is some multiple of u16.

pub fn channels_f32(&self) -> Option<ChannelsRef<'_, f32>>

Get the matrix-like channel descriptor if the channels are f32.

Returns Some only when texel is some multiple of f32.

pub fn channels_u8_mut(&mut self) -> Option<ChannelsMut<'_, u8>>

Get the matrix-like channel descriptor if the channels are u8.

Returns Some only when texel is some multiple of u8.

pub fn channels_u16_mut(&mut self) -> Option<ChannelsMut<'_, u16>>

Get the matrix-like channel descriptor if the channels are u16.

Returns Some only when texel is some multiple of u16.

pub fn channels_f32_mut(&mut self) -> Option<ChannelsMut<'_, f32>>

Get the matrix-like channel descriptor if the channels are f32.

Returns Some only when texel is some multiple of f32.

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

Return this image’s pixels as a byte vector.

pub fn plane(&self, idx: u8) -> Option<BytePlaneRef<'_>>

Get the untyped descriptor of the texel matrix.

Returns None if the image contains data that can not be described as a single texel plane, e.g. multiple planes or if the plane is not a matrix.

pub fn planes<const N: usize>(&self) -> Option<[BytePlaneRef<'_>; N]>

Get references to multiple planes at the same time.

pub fn plane_mut(&mut self, idx: u8) -> Option<BytePlaneMut<'_>>

Get the untyped, mutable reference to the texel matrix.

Returns None if the image contains data that can not be described as a single texel plane, e.g. multiple planes or if the plane is not a matrix.

pub fn planes_mut<const N: usize>(&mut self) -> Option<[BytePlaneMut<'_>; N]>

Get mutable references to multiple planes at the same time.

This works because planes never overlap. Note that all planes are aligned to the same byte boundary as the complete canvas bytes.

pub fn set_color(&mut self, color: Color) -> Result<(), LayoutError>

Set the color model.

This never changes the physical layout of data and preserves all its bits. It returns an error if the new color is not compatible with the texel’s color channels.

impl Canvas

Conversion related methods.

pub fn convert(&self, into: &mut Self)

Write into another frame, converting color representation between.

Trait Implementations

impl Clone for Canvas

fn clone(&self) -> Canvas

Returns a copy of the value.

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

Performs copy-assignment from source.

impl From<Plane> for Canvas

fn from(plane: Plane) -> Self

Converts to this type from the input type.