Struct Surface

Source

pub struct Surface<'s, S: AsRef<[P]> + AsMut<[P]>, P: Copy + Clone + Sized + Default> { /* private fields */ }

Expand description

A Surface is a pixel buffer, a size, and some underlying data describing how to blit it to a given destination Surface.

§Type aliases

There are type aliases for surface of common buffer and pixel types. Consider using them!

use blittle::{Rgba8Surface, Size};

let _ = Rgba8Surface::new(Size::new(512, 512));

Sometimes, you will need to use a buffer that isn’t a vec or is an uncommon pixel type. In those cases, see below:

§Generics

A Surface has a lifetime and two generics: Surface<'s, S, P>.

The lifetime is only relevant if the buffer is a reference, e.g. &mut [[u8; 3]]
S is the type of underlying pixel buffer. This could be, for example, a vec, or a mutable slice.
P is the type of pixel. S must be a buffer with elements of type P.

So, Rgba8Surface is a type alias for: Surface<'s, Vec<[u8; 4]>, [u8; 4]>

use blittle::{Size, Surface};

let _ = Surface::<'_, Vec<[u8; 4]>, [u8; 4]>::new(Size::new(512, 512));

Implementations§

Source §

impl<'s> Surface<'s, &'s mut [Zrgb], Zrgb>

Source

pub fn from_softbuffer<D: HasDisplayHandle, W: HasWindowHandle>( buffer: &'s mut Buffer<'_, D, W>, ) -> Self

Available on crate feature softbuffer only.

Convert a softbuffer Buffer to a surface.

The underlying pixel buffer is a mutable reference to buffer.

Source §

impl<'s, S: AsRef<[Zrgb]> + AsMut<[Zrgb]>> Surface<'s, S, Zrgb>

Source

pub fn blit_to_softbuffer<D: HasDisplayHandle, W: HasWindowHandle>( &self, buffer: &'s mut Buffer<'_, D, W>, ) -> Result<(), Error>

Available on crate feature softbuffer only.

Blit to a softbuffer Buffer.

Source §

impl<P: Copy + Clone + Sized + Default> Surface<'_, Vec, P>

Source

pub fn new(size: Size) -> Self

Available on crate feature std only.

Get a new surface.

The position defaults to (0, 0). The underlying pixel buffer is set to the pixel’s default value (i.e. [0, 0, 0]), length size.width * size.height.

Source

pub fn new_filled(size: Size, color: P) -> Self

Available on crate feature std only.

Get a new surface with color color.

The position defaults to (0, 0). The underlying pixel buffer is set to vec![color; size.width * size.height].

Source §

impl<'s, P: Copy + Clone + Sized + Default> Surface<'s, &'s mut [P], P>

Source

pub fn new(size: Size, buffer: &'s mut [P]) -> Result<Self, Error>

Get a new surface from a mutable slice.

The position defaults to (0, 0). The underlying pixel buffer is set to the pixel’s default value (i.e. [0, 0, 0]), length size.width * size.height.

Returns an error if size.width * size.height != buffer.len()

Source §

impl<S: AsRef<[P]> + AsMut<[P]>, P: Copy + Clone + Sized + Default> Surface<'_, S, P>

Source

pub fn blit<B: AsRef<[P]> + AsMut<[P]>>( &self, other: &mut Surface<'_, B, P>, ) -> Result<(), Error>

Blit onto other.

There are three constraints for blitting to other.

other must have the same pixel type as self. For example, you can’t blit an Rgba8Surface onto an L8Surface. However, other can have a different buffer type. For example, you can blit Surface<'_, Vec<u8>, u8> onto Surface<'s, &'s mut[u8], u8>
You must call Self::set_position before blitting. This is because Self::set_position not only sets the position, but also defines the region in which pixels in src actually overlap with dst. If you have called Self::set_position for one destination, and you are blitting to a different destination, you must call Self::set_position again.
Having called Self::set_position, some pixels of src must overlap with dst.

For example, this returns an error:

use blittle::*;

let mut src = Rgb8Surface::new(Size::new(512, 512));
let mut dst = Rgb8Surface::new(Size::new(1920, 1080));
// This works. Some, or all, of src is within dst.
src.set_position(PositionI::new(100, 100), &dst).unwrap();
src.blit(&mut dst).unwrap();

// Set a new destination.
let mut dst = Rgb8Surface::new(Size::new(64, 64));
// The position of `src` is obsolete, and is out of bounds.
assert!(src.blit(&mut dst).is_err());

Source

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

Fill the surface with color.

Source

pub const fn set_position<B: AsRef<[P]> + AsMut<[P]>>( &mut self, position: PositionI, destination: &Surface<'_, B, P>, ) -> Result<RectU, Error>

Set the top-left position of the surface, relative to the surface it will blit to destination.

destination must be of the same pixel type and can be of a different buffer type. For example, if self is of type Surface<'_, Vec<[u8; 4]>, [u8; 4]>>:

self can set its position relative to a Surface<'s, &'s mut [u8], [u8; 4]>>
self can’t set its position relative to a Surface<'_, Vec<[u8; 3]>, [u8; 3]>>

This will also set the region of pixels of self.buffer that otherlap with destination.buffer.

Returns an error if the clipped blitting area is not within destination.

Source

pub const fn get_position(&self) -> Option<PositionU>

Returns the top-left position of self relative to a destination surface, or None if Self::set_position hasn’t been called.

Source

pub const fn set_area( &mut self, area: Option<RectI>, ) -> Result<Option<RectU>, Error>

Set an area within the pixel buffer to blit.

You must call Self::set_position before calling this.

If area is None, then the entirety of this surface will blit (this is the default behavior).

If area is out of bounds of self’s underlying buffer, this will return an error. Otherwise, this returns a RectU describing the clipped area (i.e. which pixels within the area overlap with dst).

use blittle::*;

let mut src = Rgb8Surface::new(Size::new(512, 512));
let dst = Rgb8Surface::new(Size::new(1920, 1080));
// Set the position.
src.set_position(PositionI::new(0, 0), &dst).unwrap();
// Blit only the pixels in this region.
src.set_area(Some(RectI { position: PositionI::new(1, 3), size: Size::new(60, 80)})).unwrap();
// Reset the area. Now, all pixels will blit.
src.set_area(None).unwrap();
// Invalid area.
assert!(src.set_area(Some(RectI { position: PositionI::new(-2000, -2000), size: Size::new(60, 80)})).is_err());

Source

pub fn rows(&self) -> impl Iterator<Item = &[P]>

Iterate through the pixel buffer per-row, top to bottom.

Source

pub fn rows_mut(&mut self) -> impl Iterator<Item = &mut [P]>

Iterate through the pixel buffer per-row, top to bottom.

Source

pub fn get_pixel_checked(&self, position: PositionU) -> Result<P, Error>

Returns the color of the pixel at position.

Returns an error if position is out of bounds.

use blittle::*;

let src = Rgb8Surface::new(Size::new(64, 64));
// Get the pixel at this position.
let _ = src.get_pixel_checked(PositionU::new(3, 15));
// This position is out of bounds.
assert!(src.get_pixel_checked(PositionU::new(102, 15)).is_err());

Source

pub fn get_pixel_unchecked(&self, position: PositionU) -> P

Returns the color of the pixel at position.

use blittle::*;

let src = Rgb8Surface::new(Size::new(64, 64));
let _ = src.get_pixel_unchecked(PositionU::new(3, 15));

Source

pub fn set_pixel_checked( &mut self, position: PositionU, color: P, ) -> Result<(), Error>

Set the color of the pixel at position.

Returns an error if position is out of bounds.

use blittle::*;

let mut src = Rgb8Surface::new(Size::new(64, 64));
// Set the pixel at this position.
src.set_pixel_checked(PositionU::new(3, 15), [50, 0, 220]).unwrap();
// This pixel is out of bounds.
assert!(src.set_pixel_checked(PositionU::new(120, 15), [50, 0, 220]).is_err());

Source

pub fn set_pixel_unchecked(&mut self, position: PositionU, color: P)

Set the color of the pixel at position.

use blittle::*;

let mut src = Rgb8Surface::new(Size::new(64, 64));
src.set_pixel_unchecked(PositionU::new(3, 15), [50, 0, 220]);

Source

pub const fn get_index(&self, x: usize, y: usize) -> usize

Convert (x, y) coordinates into an index value within the underlying pixel buffer.

Source

pub const fn reset(&mut self)

Unset all internal data related to blitting to the destination surface.

This function can be a useful safeguard when blitting to multiple surfaces.

Source

pub const fn get_size(&self) -> Size

Returns the size of the surface.

Source

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

Returns the underlying pixel buffer.

Source

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

Returns the underlying mutable pixel buffer.

Source §

impl<S: AsRef<[P]> + AsMut<[P]>, P: Copy + Clone + Sized + Default + Zeroable + Pod> Surface<'_, S, P>

Source

pub fn bytes(&self) -> &[u8] ⓘ

Available on crate feature bytes only.

Returns the underlying mutable buffer as bytes.

Source

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

Available on crate feature bytes only.

Returns the underlying mutable buffer as bytes.

Trait Implementations§

Source §

impl<'s, S: Clone + AsRef<[P]> + AsMut<[P]>, P: Clone + Copy + Clone + Sized + Default> Clone for Surface<'s, S, P>

Source §

fn clone(&self) -> Surface<'s, S, P>

Returns a duplicate of the value. Read more

1.0.0 · Source§

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

Performs copy-assignment from source. Read more

Source §