Struct imagequant::Image

pub struct Image<'pixels> { /* private fields */ }

Describes image dimensions and pixels for the library

Create one using Attributes::new_image().

All images are internally in the RGBA format.

Implementations

impl<'pixels> Image<'pixels>

pub fn new<VecRGBA>(
    attr: &Attributes,
    pixels: VecRGBA,
    width: usize,
    height: usize,
    gamma: f64
) -> Result<Self, Error> where
    VecRGBA: Into<Box<[RGBA]>>, 

Makes an image from RGBA pixels.

See the rgb and bytemuck crates for making [RGBA] slices from [u8] slices.

The pixels argument can be Vec<RGBA>, or Box<[RGBA]> or &[RGBA].

If you want to supply RGB or ARGB pixels, convert them to RGBA first, or use Image::new_fn to supply your own pixel-swapping function.

Use 0. for gamma if the image is sRGB (most images are).

pub fn new_borrowed(
    attr: &Attributes,
    pixels: &'pixels [RGBA],
    width: usize,
    height: usize,
    gamma: f64
) -> Result<Self, Error>

Describe dimensions of a slice of RGBA pixels.

Same as Image::new, except it doesn’t copy the pixels, but holds a temporary reference instead.

If you want to supply RGB or ARGB pixels, use Image::new_fn to supply your own pixel-swapping function.

See the rgb and bytemuck crates for making [RGBA] slices from [u8] slices.

Use 0. for gamma if the image is sRGB (most images are).

pub unsafe fn new_fn<F: 'pixels + Fn(&mut [MaybeUninit<RGBA>], usize) + Send + Sync>(
    attr: &Attributes,
    convert_row_fn: F,
    width: usize,
    height: usize,
    gamma: f64
) -> Result<Self, Error>

Generate rows on demand using a callback function.

The callback function should be cheap (e.g. just byte-swap pixels). The parameters are: line of RGBA pixels (slice’s len is equal to image width), and row number (0-indexed). The callback will be called multiple times per row. May be called from multiple threads at once.

Use 0. for gamma if the image is sRGB (most images are).

Safety

This function is marked as unsafe, because the callback function MUST initialize the entire row (call write on every MaybeUninit pixel).

pub fn set_importance_map(
    &mut self,
    map: impl Into<Box<[u8]>>
) -> Result<(), Error>

Set which pixels are more important (and more likely to get a palette entry)

The map must be width×height pixels large. Higher numbers = more important.

pub fn set_background(&mut self, background: Image<'pixels>) -> Result<(), Error>

Remap pixels assuming they will be displayed on this background. This is designed for GIF’s “keep” mode.

Pixels that match the background color will be made transparent if there’s a fully transparent color available in the palette.

The background image’s pixels must outlive this image.

pub fn add_fixed_color(&mut self, color: RGBA) -> Result<(), Error>

Reserves a color in the output palette created from this image. It behaves as if the given color was used in the image and was very important.

The RGB values are assumed to have the same gamma as the image.

It must be called before the image is quantized.

Returns error if more than 256 colors are added. If image is quantized to fewer colors than the number of fixed colors added, then excess fixed colors will be ignored.

pub fn width(&self) -> usize

Width of the image in pixels

pub fn height(&self) -> usize

Height of the image in pixels

pub fn new_stride_borrowed(
    attr: &Attributes,
    pixels: &'pixels [RGBA],
    width: usize,
    height: usize,
    stride: usize,
    gamma: f64
) -> Result<Self, Error>

Stride is in pixels. Allows defining regions of larger images or images with padding without copying. The stride is in pixels.

Otherwise the same as Image::new_borrowed.

pub fn new_stride<VecRGBA>(
    attr: &Attributes,
    pixels: VecRGBA,
    width: usize,
    height: usize,
    stride: usize,
    gamma: f64
) -> Result<Image<'static>, Error> where
    VecRGBA: Into<Box<[RGBA]>>, 

Create new image by copying pixels to an internal buffer, so that it makes a self-contained type.

The pixels argument can be Vec<RGBA>, or Box<[RGBA]> or &[RGBA].

Otherwise the same as Image::new_stride_borrowed.