Struct pix::Raster

pub struct Raster<P: Pixel> { /* fields omitted */ }

Image arranged as a rectangular array of pixels. Rows are ordered top to bottom, and pixels within rows are left to right.

A Raster can be constructed using one of the with_ methods:

• with_clear
• with_color
• with_raster
• with_pixels
• with_u8_buffer
• with_u16_buffer

Working with byte buffers

To allow interoperability with other crates, images can be created from byte buffers, and converted back again.

use pix::rgb::Rgba8;
use pix::Raster;

let buf = vec![0; 200 * 200 * std::mem::size_of::<Rgba8>()];
let mut raster = Raster::<Rgba8>::with_u8_buffer(200, 200, buf);
// ... manipulate the image
let slice: Box<[u8]> = raster.into();
// A boxed slice can be turned back into Vec
let v: Vec<u8> = slice.into();

Implementations

impl<P: Pixel> Raster<P>

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

Construct a Raster with all pixels set to the default value.

Panics

Panics if width or height is greater than std::i32::MAX.

Examples

use pix::gray::{SGray8, SGraya32};
use pix::matte::Matte8;
use pix::rgb::SRgb16;
use pix::Raster;

let r1 = Raster::<SGray8>::with_clear(20, 20);
let r2 = Raster::<Matte8>::with_clear(64, 64);
let r3 = Raster::<SRgb16>::with_clear(10, 10);
let r4 = Raster::<SGraya32>::with_clear(100, 250);

pub fn with_color(width: u32, height: u32, clr: P) -> Self

Construct a Raster with all pixels set to one color.

Panics

Panics if width or height is greater than std::i32::MAX.

Example

use pix::rgb::SRgb8;
use pix::Raster;

let clr = SRgb8::new(0x40, 0xAA, 0xBB);
let r = Raster::<SRgb8>::with_color(15, 15, clr);

pub fn with_raster<S>(src: &Raster<S>) -> Self where
    S: Pixel,
    P::Chan: From<S::Chan>, 

Construct a Raster with another Raster.

The pixel format can be converted using this method.

• S Pixel format of source Raster.

Convert from SRgb8 to Rgba16

use pix::rgb::{Rgba16, SRgb8};
use pix::Raster;

let mut r0 = Raster::<SRgb8>::with_clear(50, 50);
// load pixels into raster
let r1 = Raster::<Rgba16>::with_raster(&r0);

pub fn with_pixels<B>(width: u32, height: u32, pixels: B) -> Self where
    B: Into<Box<[P]>>, 

Construct a Raster with owned pixel data. You can get ownership of the pixel data back from the Raster as either a Vec<P> or a Box<[P]> by calling into().

• B Owned pixed type (Vec or boxed slice).
• width Width of Raster.
• height Height of Raster.
• pixels Pixel data.

Panics

• If width or height is greater than std::i32::MAX
• If pixels length is not equal to width * height

Example

use pix::ops::Src;
use pix::rgb::Rgb8;
use pix::Raster;

let p = vec![Rgb8::new(255, 0, 255); 16];  // vec of magenta pix
let mut r = Raster::with_pixels(4, 4, p);  // convert to raster
let clr = Rgb8::new(0x00, 0xFF, 0x00);     // green
r.copy_color((2, 0, 1, 3), clr);           // make stripe
let p2 = Into::<Vec<Rgb8>>::into(r);       // back to vec

pub fn with_u8_buffer<B>(width: u32, height: u32, buffer: B) -> Self where
    B: Into<Box<[u8]>>,
    P: Pixel<Chan = Ch8>, 

Construct a Raster from a u8 buffer.

• B Owned pixed type (Vec or boxed slice).
• width Width of Raster.
• height Height of Raster.
• buffer Buffer of pixel data.

Panics

• If width or height is greater than std::i32::MAX
• If buffer length is not equal to width * height * std::mem::size_of::<P>()

pub fn with_u16_buffer<B>(width: u32, height: u32, buffer: B) -> Self where
    B: Into<Box<[u16]>>,
    P: Pixel<Chan = Ch16>, 

Construct a Raster from a u16 buffer.

• B Owned pixed type (Vec or boxed slice).
• width Width of Raster.
• height Height of Raster.
• buffer Buffer of pixel data (in native-endian byte order).

Panics

• If width or height is greater than std::i32::MAX
• If buffer length is not equal to width * height * std::mem::size_of::<P>()

pub fn width(&self) -> u32

Get width of Raster.

pub fn height(&self) -> u32

Get height of Raster.

pub fn clear(&mut self)

Clear all pixels to default value.

pub fn pixel(&self, x: i32, y: i32) -> P

Get one pixel.

pub fn pixel_mut(&mut self, x: i32, y: i32) -> &mut P

Get a mutable pixel.

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

Get a slice of all pixels.

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

Get a mutable slice of all pixels.

pub fn rows<R>(&self, reg: R) -> Rows<P> where
    R: Into<Region>, 

Get an Iterator of rows within a Raster.

• reg Region of the Raster to iterate.

pub fn rows_mut<R>(&mut self, reg: R) -> RowsMut<P> where
    R: Into<Region>, 

Get an Iterator of mutable rows within a Raster.

• reg Region of the Raster to iterate.

pub fn region(&self) -> Region

Get Region of entire Raster.

pub fn intersection<R>(&self, reg: R) -> Region where
    R: Into<Region>, 

Get intersection with a Region.

pub fn copy_color<R>(&mut self, reg: R, clr: P) where
    R: Into<Region>, 

Copy a color to a region of the Raster.

• reg Region within self. It can be a Region struct, tuple of (x, y, width, height) or the unit type (). Using () has the same result as Raster::region().
• clr Source Pixel color.

Copy a color to a rectangle region

use pix::rgb::SRgb8;
use pix::Raster;

let mut r = Raster::with_clear(100, 100);
let clr = SRgb8::new(0xDD, 0x96, 0x70);
r.copy_color((20, 40, 25, 50), clr);

pub fn copy_raster<R0, R1>(&mut self, to: R0, src: &Raster<P>, from: R1) where
    R0: Into<Region>,
    R1: Into<Region>, 

Copy from a source Raster.

• to Region within self (destination).
• src Source Raster.
• from Region within source Raster.

to / from can be Region structs, tuples of (x, y, width, height) or the unit type (). Using () has the same result as Raster::region().

*------------+      *-------------+
|            |      |    *------+ |
| *------+   |      |    |      | |
| |      |   |      |    | from | |
| |  to  |   | <--- |    +------+ |
| +------+   |      |             |
|            |      |     src     |
|    self    |      +-------------+
+------------+

The copied Region is clamped to the smaller of to and from in both X and Y dimensions. Also, to and from are clipped to their respective Raster dimensions.

Copy part of one Raster to another

use pix::rgb::SRgb8;
use pix::Raster;

let mut r0 = Raster::with_clear(100, 100);
let r1 = Raster::with_color(5, 5, SRgb8::new(80, 0, 80));
// ... load image data
r0.copy_raster((40, 40, 5, 5), &r1, ());

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

Get view of pixels as a u8 slice.

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

Get view of pixels as a mutable u8 slice.

impl<P> Raster<P> where
    P: Pixel<Alpha = Premultiplied, Gamma = Linear>, 

pub fn composite_color<R, O>(&mut self, reg: R, clr: P, op: O) where
    R: Into<Region>,
    O: Blend, 

Composite a source color to a region of the Raster.

• reg Region within self. It can be a Region struct, tuple of (x, y, width, height) or the unit type (). Using () has the same result as Raster::region().
• clr Source Pixel color.
• op Compositing operation.

Example

use pix::ops::SrcOver;
use pix::bgr::Bgra8p;
use pix::Raster;

let mut r = Raster::with_color(100, 100, Bgra8p::new(99, 0, 99, 255));
let clr = Bgra8p::new(200, 200, 0, 128);
r.composite_color((20, 40, 25, 50), clr, SrcOver);

pub fn composite_matte<R0, R1, M, O>(
    &mut self,
    to: R0,
    src: &Raster<M>,
    from: R1,
    clr: P,
    op: O
) where
    R0: Into<Region>,
    R1: Into<Region>,
    M: Pixel<Chan = P::Chan, Model = Matte, Gamma = P::Gamma>,
    O: Blend, 

Composite from a matte Raster and color.

• to Region within self (destination).
• src Source Raster matte.
• from Region within source Raster.
• clr Color to apply to the matte.
• op Compositing operation.

to / from can be Region structs, tuples of (x, y, width, height) or the unit type (). Using () has the same result as Raster::region().

Example

use pix::matte::Matte8;
use pix::ops::SrcOver;
use pix::rgb::Rgba8p;
use pix::Raster;

let mut r0 = Raster::with_clear(100, 100);
let r1 = Raster::with_color(10, 10, Matte8::new(37));
// ... load image data
let clr = Rgba8p::new(50, 100, 150, 200);
r0.composite_matte((30, 50, 10, 10), &r1, (), clr, SrcOver);

pub fn composite_raster<R0, R1, O>(
    &mut self,
    to: R0,
    src: &Raster<P>,
    from: R1,
    op: O
) where
    R0: Into<Region>,
    R1: Into<Region>,
    O: Blend, 

Composite from a source Raster.

• to Region within self (destination).
• src Source Raster.
• from Region within source Raster.
• op Compositing operation.

to / from can be Region structs, tuples of (x, y, width, height) or the unit type (). Using () has the same result as Raster::region().

*------------+      *-------------+
|            |      |    *------+ |
| *------+   |      |    |      | |
| |      |   |      |    | from | |
| |  to  |   | <--- |    +------+ |
| +------+   |      |             |
|            |      |     src     |
|    self    |      +-------------+
+------------+

The composited Region is clamped to the smaller of to and from in both X and Y dimensions. Also, to and from are clipped to their respective Raster dimensions.

Blend one Raster onto another

use pix::ops::SrcOver;
use pix::rgb::Rgba8p;
use pix::Raster;

let mut r0 = Raster::with_clear(100, 100);
let r1 = Raster::with_color(5, 5, Rgba8p::new(80, 0, 80, 200));
// ... load image data
r0.composite_raster((40, 40, 5, 5), &r1, (), SrcOver);

Trait Implementations

impl<P: Pixel> From<Raster<P>> for Box<[P]>

fn from(raster: Raster<P>) -> Self

Get internal pixel data as boxed slice.

impl<P: Pixel> From<Raster<P>> for Vec<P>

fn from(raster: Raster<P>) -> Self

Get internal pixel data as Vec of pixels.

impl<P> From<Raster<P>> for Box<[u8]> where
    P: Pixel<Chan = Ch8>, 

fn from(raster: Raster<P>) -> Self

Get internal pixel data as boxed slice of u8.

impl<P> From<Raster<P>> for Box<[u16]> where
    P: Pixel<Chan = Ch16>, 

fn from(raster: Raster<P>) -> Self

Get internal pixel data as boxed slice of u16.