webp_animation/
lib.rs

1//! # Overview
2//!
3//! This crate provides a high-level Rust wrapper for decoding and encoding
4//! [WebP](https://en.wikipedia.org/wiki/WebP) animations.
5//! Underlying WebP format processing is handled by C-based
6//! [libwebp](https://developers.google.com/speed/webp/docs/container-api) library by Google,
7//! which is interfaced through Rust [libwebp-sys2](https://crates.io/crates/libwebp-sys2)
8//! crate
9//!
10//! # Usage
11//! Have a look at [`Decoder`] and [`Encoder`] for use-case specific examples.
12
13use std::fmt::{self, Display};
14
15mod decoder;
16mod encoder;
17mod encoder_config;
18mod frame;
19mod webp_data;
20
21pub use decoder::*;
22pub use encoder::*;
23pub use encoder_config::*;
24pub use frame::*;
25pub use webp_data::*;
26
27pub mod prelude {
28    // general
29    pub use crate::ColorMode;
30
31    // decoder
32    pub use crate::{Decoder, DecoderOptions};
33
34    // encoder
35    pub use crate::{Encoder, EncoderOptions, EncodingConfig, EncodingType, LossyEncodingConfig};
36}
37
38/// Color Mode that configures the output type of [`Decoder`] [`Frame`]'s
39#[derive(Copy, Clone, PartialEq, Debug)]
40pub enum ColorMode {
41    /// Rgb (red, green, blue) -no alpha
42    Rgb,
43    /// Rgba (red, green, blue, alpha)
44    Rgba,
45    /// Bgra (blue, green, red, alpha)
46    Bgra,
47    // Bgr (blue, green, red) - no alpha
48    Bgr,
49}
50
51impl ColorMode {
52    /// Return the pixel bytesize for the color mode
53    pub fn size(&self) -> usize {
54        match self {
55            Self::Rgb | Self::Bgr => 3,
56            Self::Rgba | Self::Bgra => 4,
57        }
58    }
59}
60
61/// Error type produced by `webp_animation` code
62#[derive(Debug, PartialEq)]
63pub enum Error {
64    /// Initializing webp options failed, internal (memory allocation?) failure
65    OptionsInitFailed,
66
67    /// Decoder init failed, input contains wrong bytes
68    DecodeFailed,
69
70    /// Decoder could not get metadata of webp stream. Corrupt data?
71    DecoderGetInfoFailed,
72
73    /// Webp stream contains too large canvas. For now, size is limited to 3840 * 2160 pixels
74    /// See `MAX_CANVAS_SIZE` variable from code
75    TooLargeCanvas(u32, u32, usize),
76
77    /// Encoder create failed. Wrong options combination?
78    EncoderCreateFailed,
79
80    /// Data input buffer size did not match encoder metadata (width * height * 4)
81    BufferSizeFailed(usize, usize),
82
83    /// Raw data could not be converted into webp frame by underlying libwebp library
84    PictureImportFailed,
85
86    /// Frame could not be added to webp stream by underlying libwebp library
87    EncoderAddFailed,
88
89    /// Underlying data is in different color mode
90    WrongColorMode(ColorMode, ColorMode),
91
92    /// Timestamp must be higher value than previous frame timestamp
93    TimestampMustBeHigherThanPrevious(i32, i32),
94
95    /// Timestamp must be higher or equal to the previous frame timestamp
96    TimestampMustBeEqualOrHigherThanPrevious(i32, i32),
97
98    /// Encoder webp assembly failed
99    EncoderAssmebleFailed,
100
101    /// Supplied dimensions must be positive
102    DimensionsMustbePositive,
103
104    /// No frames have been supplied to encoder
105    NoFramesAdded,
106
107    /// Supplied zero-sized buffer where bytes where expected
108    ZeroSizeBuffer,
109
110    /// Encoder config validation failed
111    InvalidEncodingConfig,
112}
113
114impl Display for Error {
115    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
116        match self {
117            Error::OptionsInitFailed => write!(f, "OptionsInitFailed: Initializing webp options failed, internal (memory allocation?) failure"),
118            Error::DecodeFailed => write!(f, "DecodeFailed: Could not decode input bytes, possibly malformed data"),
119            Error::DecoderGetInfoFailed => write!(f, "DecoderGetInfoFailed: Decoder could not get metadata of webp stream. Corrupt data?"),
120            Error::TooLargeCanvas(width, height, max_size) => write!(f, "TooLargeCanvas: Decodable canvas is too large ({} x {} = {} pixels). For now, size is limited to 3840 * 2160 = {} pixels", width, height, width * height, max_size),
121            Error::EncoderCreateFailed => write!(f, "EncoderCreateFailed: Encoder create failed. Wrong options combination?"),
122            Error::BufferSizeFailed(expected, received) => write!(f, "BufferSizeFailed: Expected (width * height * 4 = {}) bytes as input buffer, got {} bytes", expected, received),
123            Error::PictureImportFailed => write!(f, "PictureImportFailed: Raw data could not be converted into webp frame by underlying libwebp library"),
124            Error::EncoderAddFailed => write!(f, "EncoderAddFailed: Frame could not be added to webp stream by underlying libwebp library"),
125            Error::WrongColorMode(requested, expected) => write!(f, "WrongColorMode: Requested image in {:?} format but underlying is stored as {:?}", expected, requested),
126            Error::TimestampMustBeHigherThanPrevious(requested, previous) => write!(f, "TimestampMustBeHigherThanPrevious: Supplied timestamp (got {}) must be higher than {}", requested, previous),
127            Error::TimestampMustBeEqualOrHigherThanPrevious(requested, previous) => write!(f, "TimestampMustBeEqualOrHigherThanPrevious: Supplied timestamp (got {}) must be higher or equal to {}", requested, previous),
128            Error::EncoderAssmebleFailed => write!(f, "EncoderAssmebleFailed: Encoder webp assembly failed"),
129            Error::DimensionsMustbePositive => write!(f, "DimensionsMustbePositive: Supplied dimensions must be positive"),
130            Error::NoFramesAdded => write!(f, "NoFramesAdded: No frames have been added yet"),
131            Error::ZeroSizeBuffer => write!(f, "ZeroSizeBuffer: Buffer contains no data"),
132            Error::InvalidEncodingConfig => write!(f, "InvalidEncodingConfig: encoding configuration validation failed")
133        }
134    }
135}
136
137impl std::error::Error for Error {}
webp_animation/lib.rs

webp_animation/
lib.rs
