Struct ril::Image

source · [−]

pub struct Image<P: Pixel = Dynamic> {
    pub data: Vec<P>,
    /* private fields */
}

Expand description

A high-level image representation.

This represents a static, single-frame image. See [ImageSequence] for information on opening animated or multi-frame images.

Fields

data: Vec

A 1-dimensional vector of pixels representing all pixels in the image. This is shaped according to the image’s width and height to form the image.

This data is a low-level, raw representation of the image. You can see the various pixel mapping functions, or use the [pixels] method directly for higher level representations of the data.

Implementations

source

impl<P: Pixel> Image

source

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

Creates a new image with the given width and height, with all pixels being set intially to fill.

Both the width and height must be non-zero.

Panics

width or height is zero.

source

pub fn from_fn(width: u32, height: u32, f: impl Fn(u32, u32) -> P) -> Self

Creates a new image with the given width and height. The pixels are then resolved through then given callback function which takes two parameters - the x and y coordinates of a pixel - and returns a pixel.

source

pub fn from_pixels(width: u32, pixels: impl AsRef<[P]>) -> Self

Creates a new image shaped with the given width and a 1-dimensional sequence of pixels which will be shaped according to the width.

Panics

The length of the pixels is not a multiple of the width.

source

pub fn decode_from_bytes(format: ImageFormat, bytes: impl Read) -> Result<Self>

Decodes an image with the explicitly given image encoding from the raw byte stream.

Errors

DecodingError: The image could not be decoded, maybe it is corrupt.

source

pub fn decode_inferred_from_bytes(bytes: impl Read) -> Result<Self>

Decodes an image from the given read stream of bytes, inferring its encoding.

Errors

DecodingError: The image could not be decoded, maybe it is corrupt.
UnknownEncodingFormat: Could not infer the encoding from the image. Try explicitly specifying it.

Panics

No decoder implementation for the given encoding format.

source

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Opens a file from the given path and decodes it into an image.

The encoding of the image is automatically inferred. You can explicitly pass in an encoding by using the [decode_from_bytes] method.

Errors

todo!()

source

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.

source

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 [encode] method.

Errors

An error occured during encoding.

Panics

No encoder implementation for the given encoding format.

source

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

source

pub const fn width(&self) -> u32

Returns the width of the image.

source

pub const fn height(&self) -> u32

Returns the height of the image.

source

pub const 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).

source

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

Returns a Vec 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]>.

source

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

source

pub const fn overlay_mode(&self) -> OverlayMode

Returns the overlay mode of the image.

source

pub const fn with_overlay_mode(self, mode: OverlayMode) -> Self

Returns the same image with its overlay mode set to the given value.

source

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

Returns the dimensions of the image.

source

pub const fn len(&self) -> u32

Returns the amount of pixels in the image.

source

pub const fn is_empty(&self) -> bool

Returns true if the image contains no pixels.

source

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

Returns a reference of the pixel at the given coordinates.

source

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.

source

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

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

source

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

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

source

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.

source

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. This is expected, use [set_pixel] if you want this to panic, or to use a custom overlay mode use [pixel_mut].

source

pub fn invert(&mut self)

Inverts this image in place.

source

pub fn inverted(self) -> Self

Takes this image and inverts it. Useful for method chaining.

source

pub fn map_data<T: Pixel>(self, f: impl FnOnce(Vec) -> Vec<T>) -> Image<T>

Returns the image replaced with the given data. It is up to you to make sure the data is the correct size.

The function should take the current image data and return the new data.

Note

This resets the background color back to the default.

source

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

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

source

pub fn map_pixels<T: Pixel>(self, f: impl Fn(P) -> T) -> Image<T>

Returns the image with each pixel in the image mapped to the given function.

The function should take the pixel and return another pixel.

source

pub fn map_pixels_with_coords<T: Pixel>(
self,
f: impl Fn(u32, u32, P) -> T
) -> Image<T>

Returns the image with the each pixel in the image mapped to the given function, with the function taking additional data of the pixel.

The function should take the x and y coordinates followed by the pixel and return the new pixel.

source

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

Similar to [map_pixels_with_coords], but this maps the pixels in place.

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

source

pub fn map_rows<I, T: Pixel>(self, f: impl Fn(u32, &[P]) -> I) -> Image<T> where
I: IntoIterator<Item = T>,

Returns the image with each row of pixels represented as a slice mapped to the given function.

The function should take the y coordinate followed by the row of pixels (represented as a slice) and return an Iterator of pixels.

source

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

Iterates over each row of pixels in the image.

source

pub fn convert<T: Pixel + From>(self) -> Image<T>

Converts the image into an image with the given pixel type.

source

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.

source

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.

source

pub fn cropped(self, x1: u32, y1: u32, x2: u32, y2: u32) -> Self

Takes this image and crops it to the given box. Useful for method chaining.

source

pub fn mirror(&mut self)

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

source

pub fn mirrored(self) -> Self

Takes this image and flips it horizontally (about the y-axis). Useful for method chaining.

source

pub fn flip(&mut self)

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

source

pub fn flipped(self) -> Self

Takes this image and flips it vertically, or about the x-axis. Useful for method chaining.

source

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.

Panics

width or height is zero.

source

pub fn resized(self, width: u32, height: u32, algorithm: ResizeAlgorithm) -> Self

Takes this image and resizes this image to the given dimensions using the given resizing algorithm. Useful for method chaining.

Panics

width or height is zero.

source

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

Draws an object or shape onto this image.

source

pub fn with(self, entity: &impl Draw) -> Self

Takes this image, draws the given object or shape onto it, and returns it. Useful for method chaining and drawing multiple objects at once.

source

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 [draw] method with [Paste].

source

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 [draw] method with [Paste].

source

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.