pub struct Canvas { /* private fields */ }Expand description
A byte buffer with dynamic color contents.
Implementations§
Source§impl Canvas
impl Canvas
Sourcepub fn new(layout: CanvasLayout) -> Self
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);Sourcepub fn layout(&self) -> &CanvasLayout
pub fn layout(&self) -> &CanvasLayout
Get a reference to the layout of this frame.
Sourcepub fn set_layout(&mut self, layout: CanvasLayout)
pub fn set_layout(&mut self, layout: CanvasLayout)
Overwrite the layout, allocate if necessary, and clear the image.
Sourcepub fn set_layout_conservative(&mut self, layout: CanvasLayout)
pub fn set_layout_conservative(&mut self, layout: CanvasLayout)
Overwrite the layout, allocate if necessary, do not clear the image.
Sourcepub fn as_bytes(&self) -> &[u8]
pub fn as_bytes(&self) -> &[u8]
Return this image’s pixels as a native endian byte slice.
See also Self::as_bytes_mut.
Sourcepub fn as_bytes_mut(&mut self) -> &mut [u8]
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).
Sourcepub fn as_texels<T>(&self, texel: Texel<T>) -> &[T]
pub fn as_texels<T>(&self, texel: Texel<T>) -> &[T]
Return the bytes making up this image as a slice of arbitrary elements.
Sourcepub fn as_texels_mut<T>(&mut self, texel: Texel<T>) -> &mut [T]
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.
Sourcepub fn channels_u8(&self) -> Option<ChannelsRef<'_, u8>>
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.
Sourcepub fn channels_u16(&self) -> Option<ChannelsRef<'_, u16>>
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.
Sourcepub fn channels_f32(&self) -> Option<ChannelsRef<'_, f32>>
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.
Sourcepub fn channels_u8_mut(&mut self) -> Option<ChannelsMut<'_, u8>>
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.
Sourcepub fn channels_u16_mut(&mut self) -> Option<ChannelsMut<'_, u16>>
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.
Sourcepub fn channels_f32_mut(&mut self) -> Option<ChannelsMut<'_, f32>>
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.
Sourcepub fn into_bytes(self) -> Vec<u8>
pub fn into_bytes(self) -> Vec<u8>
Return this image’s pixels as a byte vector.
Sourcepub fn plane(&self, idx: u8) -> Option<BytePlaneRef<'_>>
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.
Sourcepub fn planes<const N: usize>(&self) -> Option<[BytePlaneRef<'_>; N]>
pub fn planes<const N: usize>(&self) -> Option<[BytePlaneRef<'_>; N]>
Get references to multiple planes at the same time.
Sourcepub fn plane_mut(&mut self, idx: u8) -> Option<BytePlaneMut<'_>>
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.
Sourcepub fn planes_mut<const N: usize>(&mut self) -> Option<[BytePlaneMut<'_>; N]>
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.
Source§impl Canvas
Conversion related methods.
impl Canvas
Conversion related methods.
Sourcepub fn convert(&self, into: &mut Self) -> Result<(), ConversionError>
pub fn convert(&self, into: &mut Self) -> Result<(), ConversionError>
Write into another frame, converting color representation between.
§Design notes
The intention is that we can convert between any canvases through some common connection color space. In debug builds we assert that the conversion ran to completion. However, consider this a bit finicky. We want to represent canvases that have not yet had their conversion implemented, for instance certain planar combinations, or certain ICC profile combinations if we get around to it.