Struct Frame

pub struct Frame<P: Pixel> { /* private fields */ }

Represents a frame in an image sequence. It encloses an Image and extra metadata about the frame.

Support for paletted images

Frames representing paletted images are currently unsupported. See documentation of ImageSequence for more information.

See Also

• ImageSequence for more information about image sequences.

Implementations

impl<P: Pixel> Frame<P>

pub fn from_image(image: Image<P>) -> Self

Creates a new frame with the given image and default metadata.

pub fn set_delay(&mut self, delay: Duration)

Sets the frame delay to the given duration in place.

pub const fn with_delay(self, delay: Duration) -> Self

Takes this frame and sets the frame delay to the given duration.

pub fn set_disposal(&mut self, disposal: DisposalMethod)

Sets the disposal method for this frame in place.

pub const fn with_disposal(self, disposal: DisposalMethod) -> Self

Takes this frame and sets the disposal method for this frame when transitioning to the next.

pub const fn image(&self) -> &Image<P>

Returns a reference to the image this frame contains.

pub fn map_image<T: Pixel>( self, f: impl FnOnce(Image<P>) -> Image<T>, ) -> Frame<T>

Maps the inner image to the given function.

pub fn image_mut(&mut self) -> &mut Image<P>

Returns a mutable reference to the image this frame contains.

pub fn into_image(self) -> Image<P>

Consumes this frame returning the inner image it represents.

pub const fn delay(&self) -> Duration

Returns the delay duration for this frame.

pub const fn disposal(&self) -> DisposalMethod

Returns the disposal method for this frame.

Methods from Deref<Target = Image<P>>

pub fn encode(&self, encoding: ImageFormat, dest: &mut impl Write) -> Result<()>

Encodes the image with the given encoding and writes it to the given write buffer.

Errors

• An error occured during encoding.

Panics

• No encoder implementation for the given encoding format.

Example

let image = Image::new(100, 100, Rgb::new(255, 0, 0));
let mut out = Vec::new();
image.encode(ImageFormat::Png, &mut out)?;

pub fn save(&self, encoding: ImageFormat, path: impl AsRef<Path>) -> Result<()>

Saves the image with the given encoding to the given path. You can try saving to a memory buffer by using the Self::encode method.

Errors

• An error occured during encoding.

Panics

• No encoder implementation for the given encoding format.

Example

let image = Image::new(100, 100, Rgb::new(255, 0, 0));
image.save(ImageFormat::Png, "out.png")?;

pub fn save_inferred(&self, path: impl AsRef<Path>) -> Result<()>

Saves the image to the given path, inferring the encoding from the path/filename extension.

This is obviously slower than Self::save since this method itself uses it. You should only use this method if the filename is dynamic, or if you do not know the desired encoding before runtime.

See Also

• Self::save for more information on how saving works.

Errors

• Could not infer encoding format.
• An error occured during encoding.

Panics

• No encoder implementation for the given encoding format.

Example

let image = Image::new(100, 100, Rgb::new(255, 0, 0));
image.save_inferred("out.png")?;

pub fn width(&self) -> u32

Returns the width of the image.

pub fn height(&self) -> u32

Returns the height of the image.

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

Returns the nearest pixel coordinates to the center of the image.

This uses integer division which means if an image dimension is not even, then the value is rounded down - e.g. a 5x5 image returns (2, 2), rounded down from (2.5, 2.5).

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

Returns an iterator of slices representing the pixels of the image. Each slice in the Vec is a row. The returned slice should be of Vec<&[P; width]>.

pub fn format(&self) -> ImageFormat

Returns the encoding format of the image. This is nothing more but metadata about the image. When saving the image, you will still have to explicitly specify the encoding format.

pub fn overlay_mode(&self) -> OverlayMode

Returns the overlay mode of the image.

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

Returns the dimensions of the image.

pub fn len(&self) -> u32

Returns the amount of pixels in the image.

pub fn is_empty(&self) -> bool

Returns true if the image contains no pixels.

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

Returns a reference of the pixel at the given coordinates.

pub fn get_pixel(&self, x: u32, y: u32) -> Option<&P>

Returns a reference of the pixel at the given coordinates, but only if it exists.

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

Returns a mutable reference to the pixel at the given coordinates.

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

Sets the pixel at the given coordinates to the given pixel.

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

Overlays the pixel at the given coordinates with the given pixel according to the overlay mode.

pub fn overlay_pixel_with_mode( &mut self, x: u32, y: u32, pixel: P, mode: OverlayMode, )

Overlays the pixel at the given coordinates with the given pixel according to the specified overlay mode.

If the pixel is out of bounds, nothing occurs: the method will fail silently. This is expected, use Self::set_pixel if you want this to panic, or to use a custom overlay mode use Self::pixel_mut.

pub fn overlay_pixel_with_alpha( &mut self, x: u32, y: u32, pixel: P, mode: OverlayMode, alpha: u8, )

Overlays the pixel at the given coordinates with the given alpha intensity. This does not regard the overlay mode, since this is usually used for anti-aliasing.

If the pixel is out of bounds, nothing occurs: this method will fail silently. This is expected, use Self::set_pixel if you want this to panic, or to use a custom overlay mode use Self::pixel_mut.

pub fn invert(&mut self)

Inverts this image in place.

Equivalent to:

image.map_in_place(|_x, _y, pixel| *pixel = !*pixel);

pub fn brighten(&mut self, amount: P::Subpixel)

where P::Subpixel: SaturatingAdd + Copy,

Brightens the image by increasing all pixels by the specified amount of subpixels in place. See Self::darken to darken the image, since this usually does not take any negative values.

A subpixel is a value of a pixel’s component, for example in RGB, each subpixel is a value of either R, G, or B.

For anything with alpha, alpha is not brightened.

pub fn darken(&mut self, amount: P::Subpixel)

where P::Subpixel: SaturatingSub + Copy,

Darkens the image by decreasing all pixels by the specified amount of subpixels in place. See Self::brighten to brighten the image, since this usually does not take any negative values.

A subpixel is a value of a pixel’s component, for example in RGB, each subpixel is a value of either R, G, or B.

For anything with alpha, alpha is not brightened.

pub fn hue_rotate(&mut self, degrees: i32)

where P: TrueColor,

Hue rotates the image by the specified amount of degrees in place.

The hue is a standard angle degree, that is a value between 0 and 360, although values below and above will be wrapped using the modulo operator.

For anything with alpha, alpha is not rotated.

pub fn set_data(&mut self, data: Vec<P>)

Sets the data of this image to the new data. This is used a lot internally, but should rarely be used by you.

Panics

• Panics if the data is malformed.

pub fn map_in_place(&mut self, f: impl Fn(u32, u32, &mut P))

Similar to Self::map_pixels_with_coords, but this maps the pixels in place.

This means that the output pixel type must be the same.

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

Iterates over each row of pixels in the image.

pub fn set_format(&mut self, format: ImageFormat)

Sets the encoding format of this image. Note that when saving the file, an encoding format will still have to be explicitly specified. This is more or less image metadata.

pub fn crop(&mut self, x1: u32, y1: u32, x2: u32, y2: u32)

Crops this image in place to the given bounding box.

Panics

• The width or height of the bounding box is less than 1.

pub fn mirror(&mut self)

Mirrors, or flips this image horizontally (about the y-axis) in place.

pub fn flip(&mut self)

Flips this image vertically (about the x-axis) in place.

pub fn rotate_90(&mut self)

Rotates this image by 90 degrees clockwise, or 270 degrees counterclockwise, in place.

See Also

• Self::rotate for a version that can take any arbitrary amount of degrees
• Self::rotated for the above method which does operate in-place - useful for method chaining

pub fn rotate_180(&mut self)

Rotates this image by 180 degrees in place.

See Also

• Self::rotate for a version that can take any arbitrary amount of degrees
• Self::rotated for the above method which does operate in-place - useful for method chaining

pub fn rotate_270(&mut self)

Rotates this image by 270 degrees clockwise, or 90 degrees counterclockwise, in place.

See Also

• Self::rotate for a version that can take any arbitrary amount of degrees
• Self::rotated for the above method which does operate in-place - useful for method chaining

pub fn rotate(&mut self, degrees: i32)

Rotates this image in place about its center. There are optimized rotating algorithms for 90, 180, and 270 degree rotations (clockwise).

As mentioned, the argument is specified in degrees.

See Also

• Self::rotated for this method which does operate in-place - useful for method chaining

pub fn resize(&mut self, width: u32, height: u32, algorithm: ResizeAlgorithm)

Resizes this image in place to the given dimensions using the given resizing algorithm in place.

width and height must be greater than 0, otherwise this method will panic. You should validate user input before calling this method.

Panics

• width or height is zero.

Example

let mut image = Image::new(256, 256, Rgb::white());
assert_eq!(image.dimensions(), (256, 256));

image.resize(64, 64, ResizeAlgorithm::Lanczos3);
assert_eq!(image.dimensions(), (64, 64));

pub fn draw(&mut self, entity: &impl Draw<P>)

Draws an object or shape onto this image.

Example

let mut image = Image::new(256, 256, Rgb::white());
let rectangle = Rectangle::at(64, 64)
    .with_size(128, 128)
    .with_fill(Rgb::black());

image.draw(&rectangle);

pub fn paste(&mut self, x: u32, y: u32, image: &Self)

Pastes the given image onto this image at the given x and y coordinates. This is a shorthand for using the Self::draw method with crate::Paste.

Example

let mut image = Image::new(256, 256, Rgb::white());
let overlay_image = Image::open("overlay.png")?;

image.paste(64, 64, &overlay_image);

pub fn paste_with_mask( &mut self, x: u32, y: u32, image: &Self, mask: &Image<BitPixel>, )

Pastes the given image onto this image at the given x and y coordinates, masked with the given masking image.

Currently, only BitPixel images are supported for the masking image.

This is a shorthand for using the Self::draw method with crate::Paste.

Example

let mut image = Image::new(256, 256, Rgb::white());
let overlay_image = Image::open("overlay.png")?;

let (w, h) = overlay_image.dimensions();
let mut mask = Image::new(w, h, BitPixel::off());
mask.draw(&Ellipse::from_bounding_box(0, 0, w, h).with_fill(BitPixel::on()));

image.paste_with_mask(64, 64, &overlay_image, &mask);

pub fn mask_alpha(&mut self, mask: &Image<L>)

where P: Alpha,

Masks the alpha values of this image with the luminance values of the given single-channel L image.

If you want to mask using the alpha values of the image instead of providing an L image, you can split the bands of the image and extract the alpha band.

This masking image must have the same dimensions as this image. If it doesn’t, you will receive a panic.

Panics

• The masking image has different dimensions from this image.

pub fn palette(&self) -> Option<&[P::Color]>

Returns the palette associated with this image as a slice. If there is no palette, this returns None.

pub fn palette_mut(&mut self) -> Option<&mut [P::Color]>

Returns the palette associated with this image as a mutable slice. If there is no palette, this returns None.

pub unsafe fn palette_unchecked(&self) -> &[P::Color]

Returns the palette associated with this image as a slice. You must uphold the guarantee that the image is paletted, otherwise this will result in undefined behaviour.

Safety

• The image must always be paletted.

See Also

• Self::palette - A safe, checked alternative to this method.

pub unsafe fn palette_mut_unchecked(&mut self) -> &mut [P::Color]

Returns the palette associated with this image as a mutable slice. You must uphold the guarantee that the image is paletted, otherwise this will result in undefined behaviour.

Safety

• The image must always be paletted.

See Also

• Self::palette_mut - A safe, checked alternative to this method.

Trait Implementations

impl<P: Clone + Pixel> Clone for Frame<P>

fn clone(&self) -> Frame<P>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<P: Pixel> Deref for Frame<P>

type Target = Image<P>

The resulting type after dereferencing.

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

Dereferences the value.

impl<P: Pixel> DerefMut for Frame<P>

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

Mutably dereferences the value.

impl<'a, P: Pixel> From<&'a Frame<P>> for EncoderMetadata<P>

fn from(metadata: &'a Frame<P>) -> Self

Converts to this type from the input type.

impl<P: Pixel> From<Frame<P>> for Image<P>

fn from(frame: Frame<P>) -> Self

Converts to this type from the input type.

impl<P: Pixel> From<Image<P>> for Frame<P>

fn from(image: Image<P>) -> Self

Converts to this type from the input type.

impl<P: Pixel> FromIterator<Frame<P>> for ImageSequence<P>

fn from_iter<T>(iter: T) -> Self

where T: IntoIterator<Item = Frame<P>>,

Creates a value from an iterator.