use crate::animation::Frames;
use crate::color::{ColorType, ExtendedColorType};
use crate::error::ImageResult;
use crate::metadata::Orientation;
/// The trait that all decoders implement
pub trait ImageDecoder {
/// Returns a tuple containing the width and height of the image
fn dimensions(&self) -> (u32, u32);
/// Returns the color type of the image data produced by this decoder
fn color_type(&self) -> ColorType;
/// Returns the color type of the image file before decoding
fn original_color_type(&self) -> ExtendedColorType {
self.color_type().into()
}
/// 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 icc_profile(&mut self) -> ImageResult>> {
Ok(None)
}
/// Returns the raw [Exif](https://en.wikipedia.org/wiki/Exif) chunk, if it is present.
/// A third-party crate such as [`kamadak-exif`](https://docs.rs/kamadak-exif/) is required to actually parse it.
///
/// For formats that don't support embedded profiles this function should always return `Ok(None)`.
fn exif_metadata(&mut self) -> ImageResult >> {
Ok(None)
}
/// Returns the raw [XMP](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform) chunk, if it is present.
/// A third-party crate such as [`roxmltree`](https://docs.rs/roxmltree/) is required to actually parse it.
///
/// For formats that don't support embedded profiles this function should always return `Ok(None)`.
fn xmp_metadata(&mut self) -> ImageResult >> {
Ok(None)
}
/// Returns the raw [IPTC](https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model) chunk, if it is present.
///
/// For formats that don't support embedded profiles this function should always return `Ok(None)`.
fn iptc_metadata(&mut self) -> ImageResult >> {
Ok(None)
}
/// 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 orientation(&mut self) -> ImageResult {
Ok(self
.exif_metadata()?
.and_then(|chunk| Orientation::from_exif_chunk(&chunk))
.unwrap_or(Orientation::NoTransforms))
}
/// 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 total_bytes(&self) -> u64 {
let dimensions = self.dimensions();
let total_pixels = u64::from(dimensions.0) * u64::from(dimensions.1);
let bytes_per_pixel = u64::from(self.color_type().bytes_per_pixel());
total_pixels.saturating_mul(bytes_per_pixel)
}
/// 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
///
/// ```
/// # use image::ImageDecoder;
/// fn read_16bit_image(decoder: impl ImageDecoder) -> Vec {
/// let mut buf: Vec = vec![0; (decoder.total_bytes() / 2) as usize];
/// decoder.read_image(bytemuck::cast_slice_mut(&mut buf));
/// buf
/// }
/// ```
fn read_image(self, buf: &mut [u8]) -> ImageResult<()>
where
Self: Sized;
/// 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.
///
/// [`Limits`]: ./io/struct.Limits.html
/// [`Limits::check_support`]: ./io/struct.Limits.html#method.check_support
/// [`Limits::check_dimensions`]: ./io/struct.Limits.html#method.check_dimensions
fn set_limits(&mut self, limits: crate::Limits) -> ImageResult<()> {
limits.check_support(&crate::LimitSupport::default())?;
let (width, height) = self.dimensions();
limits.check_dimensions(width, height)?;
Ok(())
}
/// 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...
/// ```ignore
/// fn read_image_boxed(self: Box, buf: &mut [u8]) -> ImageResult<()> {
/// (*self).read_image(buf)
/// }
/// ```
fn read_image_boxed(self: Box, buf: &mut [u8]) -> ImageResult<()>;
}
#[deny(clippy::missing_trait_methods)]
impl ImageDecoder for Box {
fn dimensions(&self) -> (u32, u32) {
(**self).dimensions()
}
fn color_type(&self) -> ColorType {
(**self).color_type()
}
fn original_color_type(&self) -> ExtendedColorType {
(**self).original_color_type()
}
fn icc_profile(&mut self) -> ImageResult>> {
(**self).icc_profile()
}
fn exif_metadata(&mut self) -> ImageResult >> {
(**self).exif_metadata()
}
fn xmp_metadata(&mut self) -> ImageResult >> {
(**self).xmp_metadata()
}
fn iptc_metadata(&mut self) -> ImageResult >> {
(**self).iptc_metadata()
}
fn orientation(&mut self) -> ImageResult {
(**self).orientation()
}
fn total_bytes(&self) -> u64 {
(**self).total_bytes()
}
fn read_image(self, buf: &mut [u8]) -> ImageResult<()>
where
Self: Sized,
{
T::read_image_boxed(self, buf)
}
fn read_image_boxed(self: Box, buf: &mut [u8]) -> ImageResult<()> {
T::read_image_boxed(*self, buf)
}
fn set_limits(&mut self, limits: crate::Limits) -> ImageResult<()> {
(**self).set_limits(limits)
}
}
/// Specialized image decoding not be supported by all formats
pub trait ImageDecoderRect: ImageDecoder {
/// Decode a rectangular section of the image.
///
/// This function takes a slice of bytes and writes the pixel data of the image into it.
/// The rectangle is specified by the x and y coordinates of the top left corner, the width
/// and height of the rectangle, and the row pitch of the buffer. The row pitch is the number
/// of bytes between the start of one row and the start of the next row. The row pitch must be
/// at least as large as the width of the rectangle in bytes.
fn read_rect(
&mut self,
x: u32,
y: u32,
width: u32,
height: u32,
buf: &mut [u8],
row_pitch: usize,
) -> ImageResult<()>;
}
/// `AnimationDecoder` trait
pub trait AnimationDecoder<'a> {
/// Consume the decoder producing a series of frames.
fn into_frames(self) -> Frames<'a>;
}
#[cfg(test)]
mod tests {
use super::{ColorType, ImageDecoder, ImageResult};
#[test]
fn total_bytes_overflow() {
struct D;
impl ImageDecoder for D {
fn color_type(&self) -> ColorType {
ColorType::Rgb8
}
fn dimensions(&self) -> (u32, u32) {
(0xffff_ffff, 0xffff_ffff)
}
fn read_image(self, _buf: &mut [u8]) -> ImageResult<()> {
unimplemented!()
}
fn read_image_boxed(self: Box, buf: &mut [u8]) -> ImageResult<()> {
(*self).read_image(buf)
}
}
assert_eq!(D.total_bytes(), u64::MAX);
let v: ImageResult> = crate::io::free_functions::decoder_to_vec(D);
assert!(v.is_err());
}
}