Trait image::ImageDecoder

pub trait ImageDecoder<'a>: Sized {
    type Reader: Read + 'a;

    // Required methods
    fn dimensions(&self) -> (u32, u32);
    fn color_type(&self) -> ColorType;
    fn into_reader(self) -> ImageResult<Self::Reader>;

    // Provided methods
    fn original_color_type(&self) -> ExtendedColorType { ... }
    fn icc_profile(&mut self) -> Option<Vec<u8>> { ... }
    fn total_bytes(&self) -> u64 { ... }
    fn scanline_bytes(&self) -> u64 { ... }
    fn read_image(self, buf: &mut [u8]) -> ImageResult<()> { ... }
    fn read_image_with_progress<F: Fn(Progress)>(
        self,
        buf: &mut [u8],
        progress_callback: F
    ) -> ImageResult<()> { ... }
    fn set_limits(&mut self, limits: Limits) -> ImageResult<()> { ... }
}

The trait that all decoders implement

Required Associated Types

type Reader: Read + 'a

The type of reader produced by into_reader.

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 into_reader(self) -> ImageResult<Self::Reader>

Returns a reader that can be used to obtain the bytes of the image. For the best performance, always try to read at least scanline_bytes from the reader at a time. Reading fewer bytes will cause the reader to perform internal buffering.

Provided Methods

fn original_color_type(&self) -> ExtendedColorType

Returns the color type of the image file before decoding

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

Returns the ICC color profile embedded in the image

For formats that don’t support embedded profiles this function will always return None. This feature is currently only supported for the JPEG, PNG, and AVIF formats.

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 scanline_bytes(&self) -> u64

Returns the minimum number of bytes that can be efficiently read from this decoder. This may be as few as 1 or as many as total_bytes().

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

Returns all the bytes in the image.

This function takes a slice of bytes and writes the pixel data of the image into it. Although not required, for certain color types callers may want to pass buffers which are aligned to 2 or 4 byte boundaries to the slice can be cast to a u16 or u32. To accommodate such casts, the returned contents will always be in native endian.

Panics

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

Examples

use zerocopy::{AsBytes, FromBytes};
fn read_16bit_image(decoder: impl ImageDecoder) -> Vec<16> {
    let mut buf: Vec<u16> = vec![0; decoder.total_bytes()/2];
    decoder.read_image(buf.as_bytes());
    buf
}

fn read_image_with_progress<F: Fn(Progress)>( self, buf: &mut [u8], progress_callback: F ) -> ImageResult<()>

Same as read_image but periodically calls the provided callback to give updates on loading progress.

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

Set decoding limits for this decoder. 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.

Implementors

impl<'a, R: 'a + Read> ImageDecoder<'a> for PngDecoder<R>

type Reader = PngReader<R>