Trait ImageDecoder

pub trait ImageDecoder {
    // Required methods
    fn dimensions(&self) -> (u32, u32);
    fn color_type(&self) -> ColorType;
    fn read_image(self, buf: &mut [u8]) -> ImageResult<()>
       where Self: Sized;
    fn read_image_boxed(self: Box<Self>, buf: &mut [u8]) -> ImageResult<()>;

    // Provided methods
    fn original_color_type(&self) -> ExtendedColorType { ... }
    fn icc_profile(&mut self) -> ImageResult<Option<Vec<u8>>> { ... }
    fn exif_metadata(&mut self) -> ImageResult<Option<Vec<u8>>> { ... }
    fn orientation(&mut self) -> ImageResult<Orientation> { ... }
    fn total_bytes(&self) -> u64 { ... }
    fn set_limits(&mut self, limits: Limits) -> ImageResult<()> { ... }
}

The trait that all decoders implement

Required Methods

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

Returns a tuple containing the width and height of the image

fn color_type(&self) -> ColorType

Returns the color type of the image data produced by this decoder

fn read_image(self, buf: &mut [u8]) -> ImageResult<()>

where Self: Sized,

Returns all the bytes in the image.

This function takes a slice of bytes and writes the pixel data of the image into it. buf does not need to be aligned to any byte boundaries. However, alignment to 2 or 4 byte boundaries may result in small performance improvements for certain decoder implementations.

The returned pixel data will always be in native endian. This allows [u16] and [f32] slices to be cast to [u8] and used for this method.

Panics

This function panics if buf.len() != self.total_bytes().

Examples

fn read_16bit_image(decoder: impl ImageDecoder) -> Vec<u16> {
    let mut buf: Vec<u16> = vec![0; (decoder.total_bytes() / 2) as usize];
    decoder.read_image(bytemuck::cast_slice_mut(&mut buf));
    buf
}

fn read_image_boxed(self: Box<Self>, buf: &mut [u8]) -> ImageResult<()>

Use read_image instead; this method is an implementation detail needed so the trait can be object safe.

Note to implementors: This method should be implemented by calling read_image on the boxed decoder…

fn read_image_boxed(self: Box<Self>, buf: &mut [u8]) -> ImageResult<()> {
    (*self).read_image(buf)
}

Provided Methods

fn original_color_type(&self) -> ExtendedColorType

Returns the color type of the image file before decoding

fn icc_profile(&mut self) -> ImageResult<Option<Vec<u8>>>

Returns the ICC color profile embedded in the image, or Ok(None) if the image does not have one.

For formats that don’t support embedded profiles this function should always return Ok(None).

fn exif_metadata(&mut self) -> ImageResult<Option<Vec<u8>>>

Returns the raw Exif chunk, if it is present. A third-party crate such as kamadak-exif is required to actually parse it.

For formats that don’t support embedded profiles this function should always return Ok(None).

fn orientation(&mut self) -> ImageResult<Orientation>

Returns the orientation of the image.

This is usually obtained from the Exif metadata, if present. Formats that don’t support indicating orientation in their image metadata will return Ok(Orientation::NoTransforms).

fn total_bytes(&self) -> u64

Returns the total number of bytes in the decoded image.

This is the size of the buffer that must be passed to read_image or read_image_with_progress. The returned value may exceed usize::MAX, in which case it isn’t actually possible to construct a buffer to decode all the image data into. If, however, the size does not fit in a u64 then u64::MAX is returned.

fn set_limits(&mut self, limits: Limits) -> ImageResult<()>

Set the decoder to have the specified limits. See Limits for the different kinds of limits that is possible to set.

Note to implementors: make sure you call Limits::check_support so that decoding fails if any unsupported strict limits are set. Also make sure you call Limits::check_dimensions to check the max_image_width and max_image_height limits.

Note: By default, no limits are defined. This may be changed in future major version increases.

Implementations on Foreign Types

impl<T: ?Sized + ImageDecoder> ImageDecoder for Box<T>

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

fn color_type(&self) -> ColorType

fn original_color_type(&self) -> ExtendedColorType

fn icc_profile(&mut self) -> ImageResult<Option<Vec<u8>>>

fn exif_metadata(&mut self) -> ImageResult<Option<Vec<u8>>>

fn orientation(&mut self) -> ImageResult<Orientation>

fn total_bytes(&self) -> u64

fn read_image(self, buf: &mut [u8]) -> ImageResult<()>

where Self: Sized,

fn read_image_boxed(self: Box<Self>, buf: &mut [u8]) -> ImageResult<()>

fn set_limits(&mut self, limits: Limits) -> ImageResult<()>

Implementors

impl<R: BufRead + Seek> ImageDecoder for JpegDecoder<R>

impl<R: BufRead + Seek> ImageDecoder for PngDecoder<R>