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>.

Methods

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

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

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

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

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]>

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

fn into_raw(self) -> D

Get the backing storage of the Buffer.

fn region(&self) -> Region

Get the Region of the Buffer.

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

Get the dimensions as a tuple containing width and height.

fn width(&self) -> u32

Get the width.

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]>

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.

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.

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

Get an immutable Iterator over the pixels.

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

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]>

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.

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.

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]>

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

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<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: PartialEq, C: PartialEq, D: PartialEq> PartialEq for Buffer<P, C, D> where P: Pixel<C>, C: Channel

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

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

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

This method tests for !=.

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

fn fmt(&self, __arg_0: &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

The method called to dereference a 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

The method called to mutably dereference a value

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<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, 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> 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, 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> 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, 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.