Struct picto::Buffer

pub struct Buffer<P, C, D> where
    P: Pixel<C>,
    C: Channel,  { /* fields omitted */ }

Buffer for an image.

The Buffer is parametrized over three types, the Pixel, the Channel and the Data, and it’s the owner of the Data.

The Pixel is out-of-the-box handled by the palette crate, but it could be any other type behaving like a color.

The Channel is a primitive type from which the Pixel can be read from or written to, this is typically u8.

The Data is the backing storage which contains a serie of Channel in amount equal to Pixel::channels() * width * height.

The most common `Buffer` types are available in the `buffer` module:

• buffer::Luma is an alias for Buffer<color::Luma, u8, Vec<u8>>
• buffer::Lumaa is an alias for Buffer<color::Lumaa, u8, Vec<u8>>
• buffer::Rgb is an alias for Buffer<color::Rgb, u8, Vec<u8>>
• buffer::Rgba is an alias for Buffer<color::Rgba, u8, Vec<u8>>

Notes

The Data can be any type, but most functionality will only be available when that type implements Deref<Target = [Channel]>.

This in practice means that for example you could use a Box<[u8]> as Data and almost everything would work like it were a Vec<u8>.

Implementations

impl<P, C> Buffer<P, C, Vec<C>> where
    P: Pixel<C>,
    C: Channel, 

pub fn new(width: u32, height: u32) -> Self

Create a new Buffer with the requested space allocated and all channels set to 0.

Example

use picto::Buffer;
use picto::color::Rgb;

Buffer::<Rgb, u8, _>::new(1024, 1024);

impl<P, C> Buffer<P, C, Vec<C>> where
    P: Write<C>,
    C: Channel, 

pub fn from_pixel(width: u32, height: u32, pixel: &P) -> Self

Create a new Buffer with the request space allocated and filled with the given pixel.

Example

use picto::Buffer;
use picto::color::Rgb;

Buffer::<Rgb, u8, _>::from_pixel(1024, 1024, &Rgb::new(1.0, 0.0, 0.0));

pub fn from_fn<T, F>(width: u32, height: u32, func: F) -> Self where
    T: Into<P>,
    F: FnMut(u32, u32) -> T, 

Create a new Buffer with the request space allocated and filled with the pixel returned by the given function.

The function takes the coordinates and returns a pixel.

Example

use picto::Buffer;
use picto::color::Rgb;

Buffer::<Rgb, u8, _>::from_fn(1024, 1024, |x, y| {
    let w = (x as f32 + y as f32) / 2048.0;
    Rgb::new(w, w, w)
});

impl<P, C> Buffer<P, C, Vec<C>> where
    P: Write<C> + Mix + Clone,
    C: Channel, 

pub fn from_gradient(
    width: u32,
    height: u32,
    mode: Orientation,
    gradient: Gradient<P>
) -> Self

Create a Buffer from an orientation and a gradient.

Example

use picto::{Buffer, Orientation};
use picto::color::{Rgb, Gradient};

Buffer::<Rgb, u8, _>::from_gradient(1024, 1024, Orientation::Horizontal, Gradient::new(
    vec![Rgb::new(0.0, 0.0, 0.0), Rgb::new(1.0, 1.0, 1.0), Rgb::new(0.0, 0.0, 0.0)]));

impl<P, C, D> Buffer<P, C, D> where
    P: Pixel<C>,
    C: Channel,
    D: Deref<Target = [C]>, 

pub fn from_raw(width: u32, height: u32, data: D) -> Result<Self, ()>

Use an existing container as backing storage for an image Buffer.

The size of the storage is compared against the supplied dimensions and P::channel().

Example

use picto::Buffer;
use picto::color::Rgb;

Buffer::<Rgb, u8, _>::from_raw(2, 2, vec![
    255,   0,   0,
      0, 255,   0,
      0,   0, 255,
    255,   0, 255,
]).unwrap();

impl<P, C, D> Buffer<P, C, D> where
    P: Pixel<C>,
    C: Channel, 

pub fn into_raw(self) -> D

Get the backing storage of the Buffer.

pub fn stride(&self) -> usize

Get the stride.

pub fn region(&self) -> Region

Get the Region of the Buffer.

pub fn dimensions(&self) -> (u32, u32)

Get the dimensions as a tuple containing width and height.

pub fn width(&self) -> u32

Get the width.

pub fn height(&self) -> u32

Get the height.

impl<P, C, D> Buffer<P, C, D> where
    P: Read<C>,
    C: Channel,
    D: Deref<Target = [C]>, 

pub fn get(&self, x: u32, y: u32) -> P

Get the Pixel at the given coordinates.

Panics

Requires that x < self.width() and y < self.height(), otherwise it will panic.

pub fn readable(&self, region: Builder) -> Read<'_, P, C>

Get a read-only of the given region.

Passing Default::default() as region will create a view on the whole Buffer.

Panics

Requires that x + width <= self.width() and y + height <= self.height(), otherwise it will panic.

pub fn pixels(&self) -> Pixels<'_, P, C>

Get an immutable Iterator over the pixels.

pub fn convert<PO, CO>(&self) -> Buffer<PO, CO, Vec<CO>> where
    P: Into<PO>,
    PO: Write<CO>,
    CO: Channel, 

Convert the Buffer to another Buffer with different channel and pixel type.

Example

use picto::read;
use picto::Region;
use picto::color::{Rgb, Lumaa};

let image = read::from_path::<Rgb, u8, _>("tests/boat.xyz").unwrap();

// Convert the `Buffer` from Rgb to grayscale with alpha.
image.convert::<Lumaa, u8>();

pub fn convert_with<PO, CO, F>(&self, func: F) -> Buffer<PO, CO, Vec<CO>> where
    F: FnMut(P) -> PO,
    PO: Write<CO>,
    CO: Channel, 

Convert the Buffer to another Buffer with a closure handling the conversion.

Example

use picto::read;
use picto::Region;
use picto::color::{Rgb, Srgb};

let image = read::from_path::<Rgb, u8, _>("tests/rainbow.png").unwrap();

// Conver the `Buffer` to the sRGB color space.
image.convert_with::<Rgb, f32, _>(|p| Srgb::new(p.red, p.green, p.blue).into());

impl<P, C, D> Buffer<P, C, D> where
    P: Write<C>,
    C: Channel,
    D: DerefMut<Target = [C]>, 

pub fn set(&mut self, x: u32, y: u32, pixel: &P)

Set the Pixel at the given coordinates.

Panics

Requires that x < self.width() and y < self.height(), otherwise it will panic.

pub fn writable(&mut self, region: Builder) -> Write<'_, P, C>

Get a write-only view of the given region.

Passing Default::default() as region will create a view on the whole Buffer.

Panics

Requires that x + width <= self.width() and y + height <= self.height(), otherwise it will panic.

pub fn fill(&mut self, pixel: &P)

Fill the buffer with the given pixel.

Example

use picto::read;
use picto::color::Rgb;

let mut image = read::from_path::<Rgb, u8, _>("tests/boat.xyz").unwrap();
image.fill(&Rgb::new(1.0, 1.0, 1.0));

impl<P, C, D> Buffer<P, C, D> where
    P: Write<C> + Read<C>,
    C: Channel,
    D: DerefMut<Target = [C]>, 

pub fn view(&mut self, region: Builder) -> View<'_, P, C>

Get a view of the given region.

Passing Default::default() as region will create a view on the whole Buffer.

Panics

Requires that x + width <= self.width() and y + height <= self.height(), otherwise it will panic.

Example

use picto::read;
use picto::Region;
use picto::color::Rgba;

let mut image = read::from_path::<Rgba, u8, _>("tests/boat.xyz").unwrap();
let mut view  = image.view(Region::new().x(10).y(10).width(20).height(30));

for (_, _, mut px) in view.pixels_mut() {
    // Get the current value.
    let p = px.get();

    // Make it opaque.
    px.set(&Rgba { alpha: 0.5, .. p });
}

pub fn pixels_mut(&mut self) -> PixelsMut<'_, P, C>

Get a mutable Iterator over the pixels.

Example

use picto::read;
use picto::color::{IntoColor, Hue, RgbHue, Rgb};

let mut image = read::from_path::<Rgb, u8, _>("tests/boat.xyz").unwrap();

for (x, y, mut px) in image.pixels_mut() {
    // Get the pixel value.
    let p = px.get();

    // Convert to HSL and shift the hue.
    let p = p.into_hsl().shift_hue(RgbHue::from_radians(90.0));

    // Set the pixel value.
    px.set(&p.into());
}

Trait Implementations

impl<PI, CI, DI, PO, CO> Bytes<PO, CO> for Buffer<PI, CI, DI> where
    PI: Read<CI>,
    PI: Into<PO>,
    CI: Channel,
    DI: Deref<Target = [CI]>,
    PO: Write<CO> + Write<u8>,
    CO: Channel, 

fn bytes(&self) -> Cow<'_, [u8]>

Convert Self to a byte slice.

impl<P: Clone, C: Clone, D: Clone> Clone for Buffer<P, C, D> where
    P: Pixel<C>,
    C: Channel, 

fn clone(&self) -> Buffer<P, C, D>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<P, C> ComponentWise for Buffer<P, C, Vec<C>> where
    P: ComponentWise,
    P: Read<C> + Write<C>,
    C: Channel, 

type Scalar = P::Scalar

The scalar type for color components.

fn component_wise<F>(&self, other: &Self, f: F) -> Self where
    F: FnMut(Self::Scalar, Self::Scalar) -> Self::Scalar, 

Perform a binary operation on this and an other color.

fn component_wise_self<F>(&self, f: F) -> Self where
    F: FnMut(Self::Scalar) -> Self::Scalar, 

Perform a unary operation on this color.

impl<P: Debug, C: Debug, D: Debug> Debug for Buffer<P, C, D> where
    P: Pixel<C>,
    C: Channel, 

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

Formats the value using the given formatter.

impl<P, C, D> Deref for Buffer<P, C, D> where
    P: Pixel<C>,
    C: Channel,
    D: Deref<Target = [C]>, 

type Target = D::Target

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<P, C, D> DerefMut for Buffer<P, C, D> where
    P: Pixel<C>,
    C: Channel,
    D: DerefMut<Target = [C]>, 

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'a, P, C, D> From<&'a Buffer<P, C, D>> for Read<'a, P, C> where
    P: Read<C>,
    C: Channel,
    D: Deref<Target = [C]>, 

fn from(value: &'a Buffer<P, C, D>) -> Read<'a, P, C>

Performs the conversion.

impl<'a, P, C, D> From<&'a mut Buffer<P, C, D>> for Write<'a, P, C> where
    P: Write<C>,
    C: Channel,
    D: DerefMut<Target = [C]>, 

fn from(value: &'a mut Buffer<P, C, D>) -> Write<'a, P, C>

Performs the conversion.

impl<'a, P, C, D> From<&'a mut Buffer<P, C, D>> for View<'a, P, C> where
    P: Write<C> + Read<C>,
    C: Channel,
    D: DerefMut<Target = [C]>, 

fn from(value: &'a mut Buffer<P, C, D>) -> View<'a, P, C>

Performs the conversion.

impl<PI, CI, DI, PO, CO> Into<PO, CO> for Buffer<PI, CI, DI> where
    PI: Read<CI>,
    CI: Channel,
    DI: Deref<Target = [CI]>,
    PO: Write<CO>,
    PO: From<PI>,
    CO: Channel, 

fn into(self) -> Buffer<PO, CO, Vec<CO>>

Convert Self into a Buffer.

impl<P, C> Limited for Buffer<P, C, Vec<C>> where
    P: Limited,
    P: Read<C> + Write<C>,
    C: Channel, 

fn is_valid(&self) -> bool

Check if the color’s components are within the expected ranges.

fn clamp(&self) -> Self

Return a new color where the components has been clamped to the nearest valid values.

fn clamp_self(&mut self)

Clamp the color’s components to the nearest valid values.

impl<P, C> Mix for Buffer<P, C, Vec<C>> where
    P: Mix,
    P: Read<C> + Write<C>,
    C: Channel, 

type Scalar = P::Scalar

The type of the mixing factor.

fn mix(&self, other: &Self, factor: Self::Scalar) -> Self

Mix the color with an other color, by factor.

impl<P: PartialEq, C: PartialEq, D: PartialEq> PartialEq<Buffer<P, C, D>> for Buffer<P, C, D> where
    P: Pixel<C>,
    C: Channel, 

fn eq(&self, other: &Buffer<P, C, D>) -> bool

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

fn ne(&self, other: &Buffer<P, C, D>) -> bool

This method tests for !=.

impl<P, C> Saturate for Buffer<P, C, Vec<C>> where
    P: Saturate,
    P: Read<C> + Write<C>,
    C: Channel, 

type Scalar = P::Scalar

The type of the (de)saturation factor.

fn saturate(&self, amount: Self::Scalar) -> Self

Increase the saturation by factor.

fn desaturate(&self, factor: Self::Scalar) -> Self

Decrease the saturation by factor.

impl<P, C> Shade for Buffer<P, C, Vec<C>> where
    P: Shade,
    P: Read<C> + Write<C>,
    C: Channel, 

type Scalar = P::Scalar

The type of the lighten/darken amount.

fn lighten(&self, amount: Self::Scalar) -> Self

Lighten the color by amount.

fn darken(&self, amount: Self::Scalar) -> Self

Darken the color by amount.

impl<P, C, D> StructuralPartialEq for Buffer<P, C, D> where
    P: Pixel<C>,
    C: Channel,