665bfac0b339
gif_anim.rs
//! Animated GIFs: probed as movies and decoded whole into 8-bit frames.
//!
//! A GIF gives every frame its own delay, in hundredths of a second. The footage gets the frame
//! rate that every delay is a whole number of frames at (100 / the greatest common divisor of the
//! delays), so uneven timing is kept exactly; [`Anim::frame_at`] looks the frame up by time.
//! Animated WebP ([`crate::webp_anim`]) shares [`Anim`] and this decode path.
use effectcraft_project::{AlphaMode, Footage, FootageKind};
use effectcraft_time::{FrameRate, Tick};
use image::DynamicImage;
use crate::{MediaError, Result};
/// The `Footage::codec` of an animated GIF.
pub(crate) const CODEC: &str = "GIF";
/// Decoded frames of one GIF or animated WebP are kept as 8-bit RGBA, up to this many bytes (less
/// in a browser tab, whose wasm32 heap is 4 GiB at most and shared with everything else).
#[cfg(not(target_arch = "wasm32"))]
pub(crate) const MAX_BYTES: usize = 1 << 30;
#[cfg(target_arch = "wasm32")]
pub(crate) const MAX_BYTES: usize = 256 << 20;
/// Frames read from a GIF's or animated WebP's headers when probing.
pub(crate) const MAX_FRAMES: usize = 100_000;
/// Frames kept when decoding a GIF or animated WebP: all of them. Only [`MAX_BYTES`] and the
/// canvas budget bound decoding, as before the shared frame readers; [`MAX_FRAMES`] bounds probing.
pub(crate) const DECODE_FRAMES: usize = usize::MAX;
/// Whether `f` is an animated GIF or WebP imported by [`probe`] or [`crate::webp_anim::probe`]:
/// its frames come from an [`Anim`].
pub(crate) fn is_animated(f: &Footage) -> bool {
f.kind == FootageKind::Video && (f.codec == CODEC || f.codec == crate::webp_anim::CODEC)
}
/// The delay of a frame in hundredths of a second. Browsers show the 0 and 1 that many encoders
/// write for "as fast as possible" as 10, and so do we.
fn delay_cs(raw: u32) -> u32 {
if raw < 2 { 10 } else { raw }
}
pub(crate) fn gcd(a: u32, b: u32) -> u32 {
if b == 0 { a } else { gcd(b, a % b) }
}
/// Describe an animated GIF as a movie. `None` for a GIF with fewer than two frames (a still) or
/// one whose headers can't be read. A damaged tail keeps the frames before it.
pub(crate) fn probe(path: &str, bytes: &[u8]) -> Option<Footage> {
let info = craft_gif::scan(bytes, MAX_FRAMES)?;
let (width, height) = (u32::from(info.width), u32::from(info.height));
let delays: Vec<u32> = info.frames.iter().map(|f| delay_cs(u32::from(f.delay_cs))).collect();
if delays.len() < 2 || width == 0 || height == 0 {
return None;
}
let step = delays.iter().fold(0, |g, &d| gcd(g, d)).max(1);
let total: i64 = delays.iter().map(|&d| i64::from(d)).sum();
Some(Footage {
path: path.to_string(),
kind: FootageKind::Video,
width,
height,
frame_rate: FrameRate::new(100, i64::from(step)),
duration: Tick::from_units(total, 100),
has_video: true,
has_audio: false,
alpha: AlphaMode::Straight,
codec: CODEC.to_string(),
..Default::default()
})
}
/// Every frame of a GIF or animated WebP, composited onto the full canvas.
pub(crate) struct Anim {
frames: Vec<DynamicImage>,
/// When each frame starts (ascending, one per frame).
starts: Vec<Tick>,
}
impl Anim {
/// Frames and the times they start at (one each, ascending); `None` when there are none.
pub(crate) fn new(frames: Vec<DynamicImage>, starts: Vec<Tick>) -> Option<Anim> {
(!frames.is_empty() && frames.len() == starts.len()).then_some(Anim { frames, starts })
}
/// Decode all frames of a GIF or animated WebP. A damaged tail keeps the frames before it.
pub(crate) fn load(bytes: &[u8]) -> Result<Anim> {
if crate::webp_anim::is_webp(bytes) {
return crate::webp_anim::load(bytes);
}
// The frame reader scans every image descriptor before it checks the canvas: refuse a
// logical screen too large to hold first, as the former decoder did.
if let Some(&[w0, w1, h0, h1]) = bytes.get(6..10).filter(|_| bytes.starts_with(b"GIF8")) {
let (w, h) = (u16::from_le_bytes([w0, w1]), u16::from_le_bytes([h0, h1]));
if u64::from(w) * u64::from(h) * 4 > MAX_BYTES as u64 {
return Err(MediaError::Unsupported(format!("GIF canvas of {w}×{h} is too large to hold in memory")));
}
}
let mut limits = craft_gif::frames::FrameLimits::default();
limits.max_frames = DECODE_FRAMES;
limits.max_bytes = MAX_BYTES as u64;
limits.max_canvas_bytes = MAX_BYTES as u64;
limits.max_decode_bytes = Some(MAX_BYTES as u64);
let decoded = craft_gif::frames::read_frames(bytes, &limits).map_err(|e| match e {
craft_gif::frames::FrameError::Malformed(m) => MediaError::Decode(format!("GIF: {m}")),
craft_gif::frames::FrameError::LimitExceeded(m)
if m.contains("cannot hold") || m.contains("decode-allocation limit") || m.to_ascii_lowercase().contains("memory limit") =>
{
MediaError::Unsupported("GIF is too large to hold in memory".into())
}
craft_gif::frames::FrameError::LimitExceeded(m) if m.contains("canvas is over") => {
MediaError::Unsupported("GIF canvas is too large to hold in memory".into())
}
craft_gif::frames::FrameError::LimitExceeded(m) => MediaError::Unsupported(format!("GIF: {m}")),
})?;
if matches!(&decoded.stop, craft_gif::frames::Stop::ByteLimit | craft_gif::frames::Stop::FrameLimit) {
return Err(MediaError::Unsupported("GIF is too large to hold in memory".into()));
}
if let craft_gif::frames::Stop::Damaged(ref e) = decoded.stop {
log::warn!("media: GIF stops after {} frames: {e}", decoded.frames.len());
}
let mut frames = Vec::with_capacity(decoded.frames.len());
let mut starts = Vec::with_capacity(decoded.frames.len());
let mut at = 0i64;
for frame in decoded.frames {
let cs = delay_cs(frame.delay_ms / 10);
let image = image::RgbaImage::from_raw(decoded.width, decoded.height, frame.rgba)
.ok_or_else(|| MediaError::Decode("GIF: invalid decoded frame dimensions".into()))?;
starts.push(Tick::from_units(at, 100));
at = at.saturating_add(i64::from(cs));
frames.push(DynamicImage::ImageRgba8(image));
}
Anim::new(frames, starts).ok_or_else(|| MediaError::Decode("GIF: no frames".into()))
}
/// How many frames were decoded.
#[cfg(test)]
pub(crate) fn len(&self) -> usize {
self.frames.len()
}
/// The frame shown at source time `t` (the first one before the start, the last one past the
/// end).
pub(crate) fn frame_at(&self, t: Tick) -> Option<&DynamicImage> {
let i = self.starts.partition_point(|&s| s <= t).saturating_sub(1);
self.frames.get(i).or(self.frames.last())
}
}
#[cfg(test)]
mod tests {
use std::io::Cursor;
use effectcraft_project::{Footage, FootageKind};
use effectcraft_time::{FrameRate, Tick};
use image::AnimationDecoder;
use super::MAX_FRAMES;
use crate::{MediaPool, probe_bytes};
/// A 2×2 GIF with one solid-colour frame per `(rgb, delay)`.
fn gif(frames: &[([u8; 3], u16)]) -> Vec<u8> {
let mut out = Vec::new();
{
let mut enc = gif::Encoder::new(&mut out, 2, 2, &[]).unwrap();
for (rgb, delay) in frames {
let mut f = gif::Frame::from_rgb(2, 2, &rgb.repeat(4));
f.delay = *delay;
enc.write_frame(&f).unwrap();
}
}
out
}
/// Preserve the old consumer path as a test oracle while the frame API is shared.
fn legacy_gif_frames(bytes: &[u8]) -> Vec<image::RgbaImage> {
image::codecs::gif::GifDecoder::new(Cursor::new(bytes)).unwrap().into_frames().map(|frame| frame.unwrap().into_buffer()).collect()
}
fn legacy_gif_frames_until_error(bytes: &[u8]) -> Vec<image::RgbaImage> {
image::codecs::gif::GifDecoder::new(Cursor::new(bytes)).unwrap().into_frames().map_while(|frame| frame.ok()).map(|frame| frame.into_buffer()).collect()
}
const RED: [u8; 3] = [255, 0, 0];
const GREEN: [u8; 3] = [0, 255, 0];
const BLUE: [u8; 3] = [0, 0, 255];
fn colour_at(pool: &MediaPool, f: &Footage, seconds: f64) -> [f32; 3] {
let img = pool.frame_at(f, Tick::from_seconds_f64(seconds)).unwrap();
let p = img.data[0];
[p[0], p[1], p[2]]
}
#[test]
fn an_animated_gif_is_a_movie_with_the_files_timing() {
let bytes = gif(&[(RED, 5), (GREEN, 10), (BLUE, 5)]);
let f = probe_bytes("a.gif", bytes.clone().into()).unwrap();
assert_eq!(f.kind, FootageKind::Video);
assert!(f.has_video && !f.has_audio);
assert_eq!((f.width, f.height), (2, 2));
// Delays of 5, 10 and 5 hundredths: 20 frames a second, 0.2 s in all.
assert_eq!(f.frame_rate, FrameRate::new(20, 1));
assert_eq!(f.duration, Tick::from_units(20, 100));
let pool = MediaPool::new();
pool.add_bytes("a.gif", bytes.into());
assert_eq!(colour_at(&pool, &f, 0.01), [1.0, 0.0, 0.0]);
assert_eq!(colour_at(&pool, &f, 0.06), [0.0, 1.0, 0.0]);
assert_eq!(colour_at(&pool, &f, 0.14), [0.0, 1.0, 0.0]);
assert_eq!(colour_at(&pool, &f, 0.17), [0.0, 0.0, 1.0]);
// Past the end it holds the last frame.
assert_eq!(colour_at(&pool, &f, 5.0), [0.0, 0.0, 1.0]);
}
#[test]
fn a_frame_far_larger_than_the_canvas_is_refused_before_it_is_allocated() {
// A 1×1 canvas and a 20000×20000 frame (1.6 GB of RGBA); the data itself is not there.
let mut bytes = b"GIF89a".to_vec();
// (a two-entry global colour table, so the frame gets as far as its buffer)
bytes.extend([1, 0, 1, 0, 0x80, 0, 0, 0, 0, 0, 255, 255, 255]);
bytes.extend([0x2c, 0, 0, 0, 0, 0x20, 0x4e, 0x20, 0x4e, 0, 2, 0]);
let e = crate::gif_anim::Anim::load(&bytes).err().expect("refused").to_string();
assert!(e.to_lowercase().contains("memory"), "{e}");
}
#[test]
fn a_zero_delay_is_ten_hundredths_like_in_browsers() {
let f = probe_bytes("a.gif", gif(&[(RED, 0), (GREEN, 1)]).into()).unwrap();
assert_eq!(f.frame_rate, FrameRate::new(10, 1));
assert_eq!(f.duration, Tick::from_units(20, 100));
}
#[test]
fn shared_gif_frames_match_legacy_compositing_and_disposal() {
let mut bytes = Vec::new();
{
let palette = [255, 0, 0, 0, 255, 0, 0, 0, 255, 0, 0, 0];
let mut enc = gif::Encoder::new(&mut bytes, 3, 2, &palette).unwrap();
let first = gif::Frame {
width: 3,
height: 2,
buffer: vec![0; 6].into(), // red background
delay: 5,
dispose: gif::DisposalMethod::Keep,
..gif::Frame::default()
};
enc.write_frame(&first).unwrap();
let second = gif::Frame {
left: 1,
width: 1,
height: 1,
buffer: vec![1].into(), // green patch
delay: 7,
dispose: gif::DisposalMethod::Background,
..gif::Frame::default()
};
enc.write_frame(&second).unwrap();
let third = gif::Frame {
left: 2,
width: 1,
height: 1,
buffer: vec![2].into(), // blue patch after disposal
delay: 9,
dispose: gif::DisposalMethod::Previous,
..gif::Frame::default()
};
enc.write_frame(&third).unwrap();
let fourth = gif::Frame {
width: 1,
height: 1,
buffer: vec![3].into(), // black patch after restoring the previous canvas
delay: 11,
..gif::Frame::default()
};
enc.write_frame(&fourth).unwrap();
}
let expected = legacy_gif_frames(&bytes);
let actual = super::Anim::load(&bytes).unwrap();
assert_eq!(actual.frames.len(), expected.len());
for (frame, old) in actual.frames.iter().zip(expected) {
assert_eq!(frame.to_rgba8(), old);
}
assert_eq!(actual.starts, vec![Tick::from_units(0, 100), Tick::from_units(5, 100), Tick::from_units(12, 100), Tick::from_units(21, 100)]);
}
#[test]
fn a_single_frame_gif_stays_a_still() {
let f = probe_bytes("a.gif", gif(&[(RED, 10)]).into()).unwrap();
assert_eq!(f.kind, FootageKind::Still);
}
#[test]
fn a_damaged_gif_is_an_error_not_a_panic() {
let mut bytes = gif(&[(RED, 5), (GREEN, 5)]);
bytes.truncate(20);
let pool = MediaPool::new();
pool.add_bytes("a.gif", bytes.clone().into());
let f = Footage {
path: "a.gif".into(),
kind: FootageKind::Video,
codec: "GIF".into(),
has_video: true,
width: 2,
height: 2,
duration: Tick::from_units(10, 100),
frame_rate: FrameRate::new(20, 1),
..Default::default()
};
assert!(pool.frame_at(&f, Tick::ZERO).is_err());
let _ = probe_bytes("a.gif", bytes.into());
}
#[test]
fn a_damaged_gif_tail_keeps_frames_already_decoded() {
let mut bytes = gif(&[(RED, 5), (GREEN, 5), (BLUE, 5)]);
let info = craft_gif::scan(&bytes, MAX_FRAMES).unwrap();
assert_eq!(info.frames.len(), 3);
bytes.truncate(info.frames[1].offset);
let legacy = legacy_gif_frames_until_error(&bytes);
assert_eq!(legacy.len(), 1);
let actual = super::Anim::load(&bytes).unwrap();
assert_eq!(actual.frames.len(), legacy.len());
assert_eq!(actual.frames[0].to_rgba8(), legacy[0]);
}
#[test]
fn a_huge_canvas_is_refused_before_decoding() {
// A 65535×65535 logical screen (16 GiB of RGBA) holding one 1×1 frame.
let mut out = Vec::new();
{
let mut enc = gif::Encoder::new(&mut out, u16::MAX, u16::MAX, &[]).unwrap();
for _ in 0..2 {
enc.write_frame(&gif::Frame::from_rgb(1, 1, &RED)).unwrap();
}
}
let e = super::Anim::load(&out).err().unwrap();
assert!(e.to_string().contains("GIF canvas of 65535×65535 is too large"), "{e}");
}
/// A 1×1 GIF of `n` frames.
fn tiny_gif(n: usize) -> Vec<u8> {
let mut out = Vec::new();
{
let mut enc = gif::Encoder::new(&mut out, 1, 1, &[]).unwrap();
let frame = gif::Frame::from_rgb(1, 1, &RED);
for _ in 0..n {
enc.write_frame(&frame).unwrap();
}
}
out
}
#[test]
fn decoding_keeps_every_frame_past_the_probe_frame_count() {
// 1×1 frames fit the byte budget however many there are: the frame count refuses none.
for n in [MAX_FRAMES, MAX_FRAMES + 1] {
let anim = super::Anim::load(&tiny_gif(n)).unwrap();
assert_eq!(anim.len(), n);
}
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.