mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 23:42:27 +00:00
* feat(gif,image-codecs): add indexed/interlaced GIF, jpeg_progressive_scans, and JP2 decode * chore: update Cargo.lock for craft-image-codecs jp2 dep * fix(image-codecs,svg): deref jp2 ch and re-export resvg from craft_svg::tree::draw
344 lines
15 KiB
Rust
344 lines
15 KiB
Rust
//! Bounded-shape GIF animation writing from full-canvas RGBA8 frames.
|
||
//!
|
||
//! Timing and frame production remain the caller's choice. This module owns the GIF-specific
|
||
//! encoding rules: palette quantization, loop extension, transparency and disposal metadata.
|
||
|
||
use std::io::Write;
|
||
|
||
/// Disposal behavior to write for every frame.
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||
pub enum Disposal {
|
||
/// Leave the encoded disposal method unspecified (`0`).
|
||
Unspecified,
|
||
/// Do not dispose of the current frame (`1`), matching `gif::Frame`'s default.
|
||
Keep,
|
||
/// Restore the logical screen to the background after each frame.
|
||
Background,
|
||
}
|
||
|
||
/// GIF encoding options.
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||
pub struct Options {
|
||
/// Loop indefinitely. `false` uses `gif`'s `Finite(0)` setting (no repeat extension).
|
||
pub loop_forever: bool,
|
||
/// Disposal metadata to attach to each frame.
|
||
pub disposal: Disposal,
|
||
/// `gif` encoder palette quality (`1` is best, `30` is fastest). Default 10.
|
||
pub speed: i32,
|
||
}
|
||
|
||
impl Default for Options {
|
||
fn default() -> Self {
|
||
Self { loop_forever: true, disposal: Disposal::Keep, speed: 10 }
|
||
}
|
||
}
|
||
|
||
/// A full-canvas, straight-alpha RGBA8 frame. Delays are centiseconds, as stored in GIF.
|
||
#[derive(Debug, Clone, Copy)]
|
||
pub struct RgbaFrame<'a> {
|
||
pub pixels: &'a [u8],
|
||
pub delay_cs: u16,
|
||
}
|
||
|
||
/// Why the requested animation could not be encoded.
|
||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||
pub enum Error {
|
||
Dimensions { width: u32, height: u32 },
|
||
InvalidSpeed(i32),
|
||
FrameLength { index: usize, actual: usize, expected: usize },
|
||
PreparedDimensions { actual_width: u16, actual_height: u16, expected_width: u16, expected_height: u16 },
|
||
NoFrames,
|
||
Encode(String),
|
||
}
|
||
|
||
impl std::fmt::Display for Error {
|
||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||
match self {
|
||
Self::Dimensions { width, height } => write!(f, "GIF dimensions {width}x{height} exceed the 65535 px limit"),
|
||
Self::InvalidSpeed(speed) => write!(f, "GIF quantization speed {speed} is outside 1–30"),
|
||
Self::FrameLength { index, actual, expected } => write!(f, "GIF frame {index} has {actual} bytes; expected {expected} RGBA bytes"),
|
||
Self::PreparedDimensions { actual_width, actual_height, expected_width, expected_height } => {
|
||
write!(f, "prepared GIF frame is {actual_width}x{actual_height}; expected {expected_width}x{expected_height}")
|
||
}
|
||
Self::NoFrames => f.write_str("GIF animation has no frames"),
|
||
Self::Encode(message) => write!(f, "GIF encode failed: {message}"),
|
||
}
|
||
}
|
||
}
|
||
|
||
impl std::error::Error for Error {}
|
||
|
||
impl From<gif::EncodingError> for Error {
|
||
fn from(error: gif::EncodingError) -> Self {
|
||
Self::Encode(error.to_string())
|
||
}
|
||
}
|
||
|
||
/// A palette-quantized GIF frame ready for a writer.
|
||
///
|
||
/// Prepare these inside a parallel render batch to keep only indexed frame data in the batch,
|
||
/// rather than retaining every source RGBA buffer until the writer reaches it.
|
||
pub struct PreparedFrame {
|
||
width: u16,
|
||
height: u16,
|
||
frame: gif::Frame<'static>,
|
||
}
|
||
|
||
/// Quantize one owned full-canvas RGBA8 frame using the GIF encoder's speed setting.
|
||
pub fn prepare_frame(width: u32, height: u32, mut pixels: Vec<u8>, speed: i32) -> Result<PreparedFrame, Error> {
|
||
let (width, height) = dimensions(width, height)?;
|
||
if !(1..=30).contains(&speed) {
|
||
return Err(Error::InvalidSpeed(speed));
|
||
}
|
||
let expected = rgba_len(width, height)?;
|
||
if pixels.len() != expected {
|
||
return Err(Error::FrameLength { index: 0, actual: pixels.len(), expected });
|
||
}
|
||
let frame = gif::Frame::from_rgba_speed(width, height, &mut pixels, speed);
|
||
Ok(PreparedFrame { width, height, frame })
|
||
}
|
||
|
||
fn rgba_len(width: u16, height: u16) -> Result<usize, Error> {
|
||
usize::from(width)
|
||
.checked_mul(usize::from(height))
|
||
.and_then(|pixels| pixels.checked_mul(4))
|
||
.ok_or(Error::Dimensions { width: u32::from(width), height: u32::from(height) })
|
||
}
|
||
|
||
fn dimensions(width: u32, height: u32) -> Result<(u16, u16), Error> {
|
||
if width == 0 || height == 0 || width > u32::from(u16::MAX) || height > u32::from(u16::MAX) {
|
||
return Err(Error::Dimensions { width, height });
|
||
}
|
||
Ok((width as u16, height as u16))
|
||
}
|
||
|
||
/// A writer that appends encoded frames to an output incrementally.
|
||
pub struct AnimationWriter<W: Write> {
|
||
encoder: gif::Encoder<W>,
|
||
width: u16,
|
||
height: u16,
|
||
options: Options,
|
||
frames_written: usize,
|
||
}
|
||
|
||
impl<W: Write> AnimationWriter<W> {
|
||
/// Start an animation on `output`; subsequent calls write one frame at a time.
|
||
pub fn new(output: W, width: u32, height: u32, options: Options) -> Result<Self, Error> {
|
||
if width == 0 || height == 0 || width > u32::from(u16::MAX) || height > u32::from(u16::MAX) {
|
||
return Err(Error::Dimensions { width, height });
|
||
}
|
||
if !(1..=30).contains(&options.speed) {
|
||
return Err(Error::InvalidSpeed(options.speed));
|
||
}
|
||
let width = width as u16;
|
||
let height = height as u16;
|
||
let mut encoder = gif::Encoder::new(output, width, height, &[]).map_err(Error::from)?;
|
||
encoder.set_repeat(if options.loop_forever { gif::Repeat::Infinite } else { gif::Repeat::Finite(0) }).map_err(Error::from)?;
|
||
Ok(Self { encoder, width, height, options, frames_written: 0 })
|
||
}
|
||
|
||
/// Encode and append one full-canvas RGBA8 frame.
|
||
pub fn write_frame(&mut self, frame: RgbaFrame<'_>) -> Result<(), Error> {
|
||
let expected = rgba_len(self.width, self.height)?;
|
||
if frame.pixels.len() != expected {
|
||
return Err(Error::FrameLength { index: self.frames_written, actual: frame.pixels.len(), expected });
|
||
}
|
||
let prepared =
|
||
prepare_frame(u32::from(self.width), u32::from(self.height), frame.pixels.to_vec(), self.options.speed).map_err(|error| match error {
|
||
Error::FrameLength { actual, expected, .. } => Error::FrameLength { index: self.frames_written, actual, expected },
|
||
error => error,
|
||
})?;
|
||
self.write_prepared_frame(prepared, frame.delay_cs)
|
||
}
|
||
|
||
/// Append a previously quantized frame without copying its pixel buffer.
|
||
pub fn write_prepared_frame(&mut self, mut prepared: PreparedFrame, delay_cs: u16) -> Result<(), Error> {
|
||
if prepared.width != self.width || prepared.height != self.height {
|
||
return Err(Error::PreparedDimensions {
|
||
actual_width: prepared.width,
|
||
actual_height: prepared.height,
|
||
expected_width: self.width,
|
||
expected_height: self.height,
|
||
});
|
||
}
|
||
prepared.frame.delay = delay_cs;
|
||
prepared.frame.dispose = match self.options.disposal {
|
||
Disposal::Unspecified => gif::DisposalMethod::Any,
|
||
Disposal::Keep => gif::DisposalMethod::Keep,
|
||
Disposal::Background => gif::DisposalMethod::Background,
|
||
};
|
||
self.encoder.write_frame(&prepared.frame).map_err(Error::from)?;
|
||
self.frames_written = self.frames_written.saturating_add(1);
|
||
Ok(())
|
||
}
|
||
|
||
/// Finish the GIF and return the underlying output.
|
||
pub fn finish(self) -> Result<W, Error> {
|
||
self.encoder.into_inner().map_err(Error::from)
|
||
}
|
||
}
|
||
|
||
/// Encode an animation into a complete GIF file.
|
||
///
|
||
/// Every input frame must cover the whole canvas and contain exactly `width * height * 4` bytes.
|
||
/// At most one mutable frame copy is made at a time for the quantizer. This is intentionally a
|
||
/// streaming writer so callers can render and encode frames incrementally.
|
||
pub fn animation(width: u32, height: u32, frames: &[RgbaFrame<'_>], options: Options) -> Result<Vec<u8>, Error> {
|
||
if frames.is_empty() {
|
||
return Err(Error::NoFrames);
|
||
}
|
||
let mut writer = AnimationWriter::new(Vec::new(), width, height, options)?;
|
||
for frame in frames {
|
||
writer.write_frame(*frame)?;
|
||
}
|
||
writer.finish()
|
||
}
|
||
|
||
/// Encode a single pre-quantized indexed-color frame as a GIF89a image.
|
||
///
|
||
/// `palette` holds 1 to 256 RGB triplets; `indices` is `width * height` row-major palette indices.
|
||
/// When `interlaced` is true, rows are reordered into GIF's 4-pass interlaced order before writing.
|
||
pub fn encode_indexed(
|
||
width: u32,
|
||
height: u32,
|
||
palette: &[[u8; 3]],
|
||
indices: &[u8],
|
||
transparent: Option<u8>,
|
||
interlaced: bool,
|
||
) -> Result<Vec<u8>, Error> {
|
||
let (w, h) = dimensions(width, height)?;
|
||
let expected = usize::from(w) * usize::from(h);
|
||
if indices.len() != expected {
|
||
return Err(Error::FrameLength { index: 0, actual: indices.len(), expected });
|
||
}
|
||
if palette.is_empty() || palette.len() > 256 {
|
||
return Err(Error::Encode("GIF palette must hold 1 to 256 entries".into()));
|
||
}
|
||
let flat_palette: Vec<u8> = palette.iter().flat_map(|c| *c).collect();
|
||
let buffer = if interlaced { std::borrow::Cow::Owned(interlace(indices, usize::from(w))) } else { std::borrow::Cow::Borrowed(indices) };
|
||
let mut enc = gif::Encoder::new(Vec::new(), w, h, &flat_palette).map_err(Error::from)?;
|
||
let frame = gif::Frame { width: w, height: h, buffer, transparent, interlaced, ..gif::Frame::default() };
|
||
enc.write_frame(&frame).map_err(Error::from)?;
|
||
enc.into_inner().map_err(Error::from)
|
||
}
|
||
|
||
/// The rows of a `width`-wide image in GIF's interlaced order: every 8th row from 0, every 8th
|
||
/// from 4, every 4th from 2, then every 2nd from 1.
|
||
fn interlace(px: &[u8], width: usize) -> Vec<u8> {
|
||
let rows: Vec<&[u8]> = px.chunks(width.max(1)).collect();
|
||
[(0, 8), (4, 8), (2, 4), (1, 2)]
|
||
.into_iter()
|
||
.flat_map(|(start, step)| rows.iter().skip(start).step_by(step))
|
||
.flat_map(|r| r.iter().copied())
|
||
.collect()
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests {
|
||
#![allow(clippy::unwrap_used)]
|
||
|
||
use super::{Disposal, Options, RgbaFrame, animation, prepare_frame};
|
||
|
||
#[test]
|
||
fn writes_repeat_delays_disposal_and_dimensions() {
|
||
let red = [255, 0, 0, 255];
|
||
let blue = [0, 0, 255, 255];
|
||
let bytes = animation(
|
||
1,
|
||
1,
|
||
&[RgbaFrame { pixels: &red, delay_cs: 4 }, RgbaFrame { pixels: &blue, delay_cs: 7 }],
|
||
Options { loop_forever: false, disposal: Disposal::Background, speed: 10 },
|
||
)
|
||
.unwrap();
|
||
let info = crate::scan(&bytes, 4).unwrap();
|
||
assert_eq!((info.width, info.height), (1, 1));
|
||
assert_eq!(info.loop_count, None);
|
||
assert_eq!(info.frames.iter().map(|f| f.delay_cs).collect::<Vec<_>>(), [4, 7]);
|
||
assert!(info.frames.iter().all(|f| f.disposal == 2));
|
||
}
|
||
|
||
#[test]
|
||
fn default_disposal_matches_gif_frame_default() {
|
||
let bytes = animation(1, 1, &[RgbaFrame { pixels: &[1, 2, 3, 255], delay_cs: 1 }], Options::default()).unwrap();
|
||
let info = crate::scan(&bytes, 1).unwrap();
|
||
assert_eq!(info.frames[0].disposal, 1);
|
||
}
|
||
|
||
#[test]
|
||
fn rejects_dimensions_empty_animation_and_wrong_pixel_lengths() {
|
||
assert!(matches!(animation(0, 1, &[RgbaFrame { pixels: &[0; 4], delay_cs: 1 }], Options::default()), Err(super::Error::Dimensions { .. })));
|
||
assert!(matches!(animation(1, 1, &[], Options::default()), Err(super::Error::NoFrames)));
|
||
assert!(matches!(animation(1, 1, &[RgbaFrame { pixels: &[0; 3], delay_cs: 1 }], Options::default()), Err(super::Error::FrameLength { .. })));
|
||
assert!(matches!(
|
||
animation(1, 1, &[RgbaFrame { pixels: &[0; 4], delay_cs: 1 }], Options { speed: 0, ..Options::default() }),
|
||
Err(super::Error::InvalidSpeed(0))
|
||
));
|
||
assert!(matches!(
|
||
animation(1, 1, &[RgbaFrame { pixels: &[0; 4], delay_cs: 1 }, RgbaFrame { pixels: &[0; 3], delay_cs: 1 }], Options::default()),
|
||
Err(super::Error::FrameLength { index: 1, .. })
|
||
));
|
||
}
|
||
|
||
#[test]
|
||
fn streaming_writer_preserves_empty_output_behavior() {
|
||
let bytes = super::AnimationWriter::new(Vec::new(), 1, 1, Options::default()).unwrap().finish().unwrap();
|
||
assert!(bytes.starts_with(b"GIF89a"));
|
||
assert_eq!(bytes.last(), Some(&b';'));
|
||
}
|
||
|
||
#[cfg(feature = "frames")]
|
||
#[test]
|
||
fn prepared_frames_stream_without_changing_decoded_pixels() {
|
||
let red = vec![255, 0, 0, 255];
|
||
let blue = vec![0, 0, 255, 255];
|
||
let mut writer = super::AnimationWriter::new(Vec::new(), 1, 1, Options::default()).unwrap();
|
||
writer.write_prepared_frame(prepare_frame(1, 1, red, 10).unwrap(), 3).unwrap();
|
||
writer.write_prepared_frame(prepare_frame(1, 1, blue, 10).unwrap(), 5).unwrap();
|
||
let bytes = writer.finish().unwrap();
|
||
let expected = animation(
|
||
1,
|
||
1,
|
||
&[RgbaFrame { pixels: &[255, 0, 0, 255], delay_cs: 3 }, RgbaFrame { pixels: &[0, 0, 255, 255], delay_cs: 5 }],
|
||
Options::default(),
|
||
)
|
||
.unwrap();
|
||
assert_eq!(bytes, expected);
|
||
let decoded = crate::frames::read_frames(&bytes, &crate::frames::FrameLimits::default()).unwrap();
|
||
assert_eq!(decoded.frames[0].rgba, [255, 0, 0, 255]);
|
||
assert_eq!(decoded.frames[1].rgba, [0, 0, 255, 255]);
|
||
assert_eq!(decoded.frames.iter().map(|frame| frame.delay_ms).collect::<Vec<_>>(), [30, 50]);
|
||
}
|
||
|
||
#[test]
|
||
fn rejects_prepared_frames_with_other_dimensions() {
|
||
let prepared = prepare_frame(2, 1, vec![0; 8], 10).unwrap();
|
||
let mut writer = super::AnimationWriter::new(Vec::new(), 1, 1, Options::default()).unwrap();
|
||
assert!(matches!(writer.write_prepared_frame(prepared, 1), Err(super::Error::PreparedDimensions { .. })));
|
||
}
|
||
|
||
#[cfg(feature = "frames")]
|
||
#[test]
|
||
fn encoded_frames_decode_to_the_requested_colors() {
|
||
let red = [255, 0, 0, 255];
|
||
let blue = [0, 0, 255, 255];
|
||
let bytes =
|
||
animation(1, 1, &[RgbaFrame { pixels: &red, delay_cs: 1 }, RgbaFrame { pixels: &blue, delay_cs: 2 }], Options::default()).unwrap();
|
||
let decoded = crate::frames::read_frames(&bytes, &crate::frames::FrameLimits::default()).unwrap();
|
||
assert_eq!(decoded.frames[0].rgba, red);
|
||
assert_eq!(decoded.frames[1].rgba, blue);
|
||
}
|
||
|
||
#[test]
|
||
fn encode_indexed_validates_and_writes_gif() {
|
||
let palette = [[255, 0, 0], [0, 255, 0]];
|
||
let indices = [0u8, 1, 1, 0, 0, 1, 1, 0, 0];
|
||
let bytes = super::encode_indexed(3, 3, &palette, &indices, Some(1), true).unwrap();
|
||
let info = crate::scan(&bytes, 4).unwrap();
|
||
assert_eq!((info.width, info.height), (3, 3));
|
||
assert_eq!(info.frames.len(), 1);
|
||
assert_eq!(info.frames[0].transparent, Some(1));
|
||
assert!(super::encode_indexed(2, 2, &[], &[0; 4], None, false).is_err());
|
||
assert!(super::encode_indexed(2, 2, &palette, &[0; 3], None, false).is_err());
|
||
}
|
||
}
|