Struct canvas::Canvas

pub struct Canvas<P: AsBytes + FromBytes> { /* fields omitted */ }

A 2d matrix of pixels.

The layout describes placement of samples within the memory buffer. An abstraction layer that provides strided access to such pixel data is not intended to be baked into this struct. Instead, it will always store the data in a row-major layout without holes.

There are two levels of control over the allocation behaviour of a Canvas. The direct methods, currently with_width_and_height only, lead to a canvas without intermediate steps but may panic due to an invalid layout. Manually using the intermediate Layout gives custom error handling options and additional offers inspection of the details of the to-be-allocated buffer. A third option is currently not available and depends on support from the Rust standard library, which could also handle allocation failures.

Usage for trusted inputs

Directly allocate your desired layout with with_width_and_height. This may panic when the allocation itself fails or when the allocation for the layout could not described, as the layout would not fit inside the available memory space (i.e. the indices would overflow a usize).

Usage for untrusted inputs

In some cases, for untrusted input such as in image parsing libraries, more control is desired. There is no way to currently catch an allocation failure in stable Rust. Thus, even reasonable bounds can lead to a panic, and this is unpreventable (note: when the try_* methods of Vec become stable this will change). But one still may want to check the required size before allocation.

Firstly, no method will implicitely try to allocate memory and methods that will note the potential panic from allocation failure.

Secondly, an instance of Layout can be constructed in a panic free manner without any allocation and independently from the Canvas instance. By providing it to the with_layout constructor ensures that all potential intermediate failures–except as mentioned before–can be explicitely handled by the caller. Furthermore, some utility methods allow inspection of the eventual allocation size before the reservation of memory.

Restrictions

As previously mentioned, the samples in the internal buffer layout always appear without any holes. Therefore a fast crop operation requires wrapping the abstraction layer provided here into another layer describing the accessible image, independent from the layout of the actual pixel data. This separation of concern–layout vs. acess logic–simplifies the implementation and keeps it agnostic of the desired low-cost operations. Consider that other use cases may require operatios other than crop with constant time. Instead of choosing some consistent by limited set here, the mechanism to achieve it is deferred to an upper layer for further freedom. Other structs may, in the future, provide other pixel layouts.

Methods

impl<P: AsBytes + FromBytes> Canvas<P>

pub fn with_layout(layout: Layout<P>) -> Self

Allocate a canvas with specified layout.

Panics

When allocation of memory fails.

pub fn with_width_and_height(width: usize, height: usize) -> Self where
    P: AsPixel, 

Directly try to allocate a canvas from width and height.

Panics

This panics when the layout described by width and height can not be allocated, for example due to it being an invalid layout. If you want to handle the layout being invalid, consider using Layout::from_width_and_height and Canvas::with_layout.

pub fn from_rec(buffer: Rec<P>, layout: Layout<P>) -> Self

Interpret an existing buffer as a pixel canvas.

The data already contained within the buffer is not modified so that prior initialization can be performed or one array of samples reinterpreted for an image of other sample type. However, the Rec will be logically resized which will zero-initialize missing elements if the current buffer is too short.

Panics

This function will panic if resizing causes a reallocation that fails.

pub fn from_reused_rec(
    buffer: Rec<P>,
    layout: Layout<P>
) -> Result<Self, CanvasReuseError<P>>

Reuse an existing buffer for a pixel canvas.

Similar to from_rec but this function will never reallocate the inner buffer. Instead, it will return the Rec unmodified if the creation fails. See CanvasReuseError for further information on the error and retrieving the buffer.

pub fn as_slice(&self) -> &[P]

pub fn as_mut_slice(&mut self) -> &mut [P]

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

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

pub fn resize(&mut self, layout: Layout<P>)

Resize the buffer for a new image.

Panics

This function will panic if an allocation is necessary but fails.

pub fn reuse(&mut self, layout: Layout<P>) -> Result<(), ReuseError>

Reuse the buffer for a new image layout.

pub fn transmute<Q: AsPixel + AsBytes + FromBytes>(self) -> Canvas<Q>

Reinterpret to another, same size pixel type.

See transmute_to for details.

pub fn transmute_to<Q: AsBytes + FromBytes>(self, pixel: Pixel<Q>) -> Canvas<Q>

Reinterpret to another, same size pixel type.

Panics

Like std::mem::transmute, the size of the two types need to be equal. This ensures that all indices are valid in both directions.

pub fn into_rec(self) -> Rec<P>

impl<P: AsBytes + FromBytes + Copy> Canvas<P>

pub fn map<F, Q>(self, map: F) -> Canvas<Q> where
    F: Fn(P) -> Q,
    Q: AsPixel + AsBytes + FromBytes + Copy, 

Apply a function to all pixel values.

See [map_to] for the details.

Panics

This function will panic if the new layout would be invalid (because the new pixel type requires a larger buffer than can be allocate) or if the reallocation fails.

pub fn map_to<F, Q>(self, map: F, pixel: Pixel<Q>) -> Canvas<Q> where
    F: Fn(P) -> Q,
    Q: AsBytes + FromBytes + Copy, 

Apply a function to all pixel values.

Unlike [transmute_to] there are no restrictions on the pixel types. This will reuse the underlying buffer or resize it if that is not possible.

Panics

This function will panic if the new layout would be invalid (because the new pixel type requires a larger buffer than can be allocate) or if the reallocation fails.

pub fn map_reuse<F, Q>(self, map: F) -> Result<Canvas<Q>, MapReuseError<P, Q>> where
    F: Fn(P) -> Q,
    Q: AsPixel + AsBytes + FromBytes + Copy, 

pub fn map_reuse_to<F, Q>(
    self,
    map: F,
    pixel: Pixel<Q>
) -> Result<Canvas<Q>, MapReuseError<P, Q>> where
    F: Fn(P) -> Q,
    Q: AsBytes + FromBytes + Copy, 

Trait Implementations

impl<P: AsBytes + FromBytes> Clone for Canvas<P>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<P: Debug + AsBytes + FromBytes> Debug for Canvas<P>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<P: AsBytes + FromBytes + AsPixel> Default for Canvas<P>

fn default() -> Self

Returns the "default value" for a type.

impl<P: Eq + AsBytes + FromBytes> Eq for Canvas<P>

impl<P: AsBytes + FromBytes> Index<(usize, usize)> for Canvas<P>

type Output = P

The returned type after indexing.

fn index(&self, (x, y): (usize, usize)) -> &P

Performs the indexing (container[index]) operation.

impl<P: AsBytes + FromBytes> IndexMut<(usize, usize)> for Canvas<P>

fn index_mut(&mut self, (x, y): (usize, usize)) -> &mut P

Performs the mutable indexing (container[index]) operation.

impl<P: PartialEq + AsBytes + FromBytes> PartialEq<Canvas<P>> for Canvas<P>

fn eq(&self, other: &Canvas<P>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Canvas<P>) -> bool

This method tests for !=.

impl<P: AsBytes + FromBytes> StructuralEq for Canvas<P>

impl<P: AsBytes + FromBytes> StructuralPartialEq for Canvas<P>