Files
craft-libs/crates/webp/src/anim.rs

292 lines
14 KiB
Rust
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Animated WebP writing: the `VP8X`, `ANIM` and `ANMF` chunks around frames another encoder
//! made ([`animation`]), and, with feature `vp8`, whole lossy animations from RGBA frames through
//! `craft-video`'s VP8 encoder ([`lossy_animation`]).
use crate::{Error, MAX_CANVAS, MAX_VP8_DIMENSION, chunk};
/// The encoded picture of one frame.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Payload<'a> {
/// A VP8 key frame and, optionally, an alpha plane of one byte a pixel (stored uncompressed).
Lossy { vp8: &'a [u8], alpha: Option<&'a [u8]> },
/// A VP8L (lossless) bitstream, signature byte included.
Lossless { vp8l: &'a [u8] },
}
/// One frame of an animation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AnimFrame<'a> {
/// Position on the canvas; both must be even.
pub x: u32,
pub y: u32,
pub width: u32,
pub height: u32,
/// How long the frame is shown, in milliseconds (below 2^24).
pub duration_ms: u32,
/// Alpha-blend onto the canvas (false: replace the frame's rectangle).
pub blend: bool,
/// Clear the frame's rectangle to the background before the next frame.
pub dispose_to_background: bool,
pub payload: Payload<'a>,
}
/// Animation-wide settings.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct AnimOptions<'a> {
/// Times to play: 0 loops forever.
pub loop_count: u16,
/// Background colour as stored in the file: blue, green, red, alpha. A hint players may ignore.
pub background_bgra: [u8; 4],
/// Set the alpha flag even when no lossy frame carries an alpha plane (lossless frames with alpha).
pub alpha: bool,
pub icc: Option<&'a [u8]>,
pub exif: Option<&'a [u8]>,
pub xmp: Option<&'a [u8]>,
}
fn u24(out: &mut Vec<u8>, v: u32) {
out.extend_from_slice(&v.to_le_bytes()[..3]);
}
/// Writes an animated WebP of a `width × height` canvas with these frames, in order.
pub fn animation(width: u32, height: u32, frames: &[AnimFrame], opts: &AnimOptions) -> Result<Vec<u8>, Error> {
if width == 0 || height == 0 || width > MAX_CANVAS || height > MAX_CANVAS || u64::from(width) * u64::from(height) > u64::from(u32::MAX) {
return Err(Error::Encode("the canvas is 1 to 2^24 pixels a side and at most 2^32 pixels"));
}
if frames.is_empty() {
return Err(Error::Encode("an animation needs a frame"));
}
// Determine the header flag before writing, without retaining another full animation.
let any_alpha = opts.alpha || frames.iter().any(|f| matches!(f.payload, Payload::Lossy { alpha: Some(_), .. }));
let mut body = b"WEBP".to_vec();
let flags = [(opts.icc.is_some(), 0x20u8), (any_alpha, 0x10), (opts.exif.is_some(), 0x08), (opts.xmp.is_some(), 0x04), (true, 0x02)]
.iter()
.filter(|(on, _)| *on)
.fold(0, |f, (_, bit)| f | bit);
let mut vp8x = vec![flags, 0, 0, 0];
u24(&mut vp8x, width - 1);
u24(&mut vp8x, height - 1);
chunk(&mut body, b"VP8X", &vp8x)?;
if let Some(icc) = opts.icc {
chunk(&mut body, b"ICCP", icc)?;
}
let mut anim = opts.background_bgra.to_vec();
anim.extend_from_slice(&opts.loop_count.to_le_bytes());
chunk(&mut body, b"ANIM", &anim)?;
for f in frames {
if f.width == 0 || f.height == 0 || f.x % 2 != 0 || f.y % 2 != 0 {
return Err(Error::Encode("a frame is empty or not at an even position"));
}
if f.x.checked_add(f.width).is_none_or(|r| r > width) || f.y.checked_add(f.height).is_none_or(|b| b > height) {
return Err(Error::Encode("a frame reaches past the canvas"));
}
if f.duration_ms >= 1 << 24 {
return Err(Error::Encode("a frame duration is 2^24 ms or more"));
}
let mut frame_body = Vec::new();
u24(&mut frame_body, f.x / 2);
u24(&mut frame_body, f.y / 2);
u24(&mut frame_body, f.width - 1);
u24(&mut frame_body, f.height - 1);
u24(&mut frame_body, f.duration_ms);
// Bit 1: do not blend; bit 0: dispose to the background.
frame_body.push(u8::from(!f.blend) << 1 | u8::from(f.dispose_to_background));
match f.payload {
Payload::Lossy { vp8, alpha } => {
if f.width > MAX_VP8_DIMENSION || f.height > MAX_VP8_DIMENSION {
return Err(Error::Encode("a lossy frame is at most 16383 pixels a side"));
}
if let Some(a) = alpha {
if a.len() as u64 != u64::from(f.width) * u64::from(f.height) {
return Err(Error::Encode("an alpha plane does not match its frame"));
}
let mut alph = Vec::with_capacity(a.len() + 1);
// Header byte: no pre-processing, no filtering, no compression.
alph.push(0);
alph.extend_from_slice(a);
chunk(&mut frame_body, b"ALPH", &alph)?;
}
chunk(&mut frame_body, b"VP8 ", vp8)?;
}
Payload::Lossless { vp8l } => chunk(&mut frame_body, b"VP8L", vp8l)?,
}
chunk(&mut body, b"ANMF", &frame_body)?;
}
if let Some(exif) = opts.exif {
chunk(&mut body, b"EXIF", exif)?;
}
if let Some(xmp) = opts.xmp {
chunk(&mut body, b"XMP ", xmp)?;
}
let size = u32::try_from(body.len()).map_err(|_| Error::Encode("the file is larger than 4 GiB"))?;
let mut out = Vec::with_capacity(body.len() + 8);
out.extend_from_slice(b"RIFF");
out.extend_from_slice(&size.to_le_bytes());
out.extend_from_slice(&body);
Ok(out)
}
/// Writes a lossy animated WebP of full-canvas RGBA8 frames (`width × height × 4` bytes each,
/// straight alpha) with these durations, each frame a VP8 key frame at `quality` (0–100). A frame
/// whose pixels are all opaque gets no alpha plane. Frames replace the canvas (no blending).
#[cfg(feature = "vp8")]
pub fn lossy_animation(width: u32, height: u32, frames: &[(&[u8], u32)], quality: u8, opts: &AnimOptions) -> Result<Vec<u8>, Error> {
use craft_video::vp8::{Vp8Error, Vp8Params, encode_rgba};
let params = Vp8Params { quality, loop_filter: None };
let mut encoded = Vec::with_capacity(frames.len());
for (rgba, duration_ms) in frames {
let vp8 = encode_rgba(rgba, width, height, &params)
.map_err(|e| match e {
Vp8Error::Size(..) => Error::Encode("a lossy frame is 1 to 16383 pixels a side"),
Vp8Error::Buffer(..) => Error::Encode("a frame is not width × height × 4 bytes of RGBA"),
Vp8Error::PartitionTooLarge(_) => Error::Encode("a lossy frame's first partition is over the 19-bit limit"),
})?
.data;
let alpha: Vec<u8> = rgba.iter().skip(3).step_by(4).copied().collect();
let alpha = (!alpha.iter().all(|&a| a == 255)).then_some(alpha);
encoded.push((vp8, alpha, *duration_ms));
}
let list: Vec<AnimFrame> = encoded
.iter()
.map(|(vp8, alpha, duration_ms)| AnimFrame {
x: 0,
y: 0,
width,
height,
duration_ms: *duration_ms,
blend: false,
dispose_to_background: false,
payload: Payload::Lossy { vp8, alpha: alpha.as_deref() },
})
.collect();
animation(width, height, &list, opts)
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use image::{AnimationDecoder, ExtendedColorType, ImageEncoder, codecs::webp::WebPDecoder, codecs::webp::WebPEncoder};
use super::*;
use crate::scan;
/// The `VP8L` chunk payload of a lossless still of one colour, written by `image`.
fn vp8l(w: u32, h: u32, rgba: [u8; 4]) -> Vec<u8> {
let mut file = Vec::new();
WebPEncoder::new_lossless(&mut file).write_image(&rgba.repeat((w * h) as usize), w, h, ExtendedColorType::Rgba8).unwrap();
let at = file.windows(4).position(|c| c == b"VP8L").unwrap();
let size = u32::from_le_bytes(file[at + 4..at + 8].try_into().unwrap()) as usize;
file[at + 8..at + 8 + size].to_vec()
}
fn frame(payload: Payload<'_>, x: u32, y: u32, w: u32, h: u32, ms: u32) -> AnimFrame<'_> {
AnimFrame { x, y, width: w, height: h, duration_ms: ms, blend: false, dispose_to_background: false, payload }
}
#[test]
fn lossless_frames_round_trip_through_scan_and_a_decoder() {
let (red, green) = (vp8l(4, 2, [255, 0, 0, 255]), vp8l(2, 2, [0, 255, 0, 128]));
let frames = [frame(Payload::Lossless { vp8l: &red }, 0, 0, 4, 2, 40), frame(Payload::Lossless { vp8l: &green }, 2, 0, 2, 2, 120)];
let mut opts = AnimOptions { loop_count: 3, alpha: true, ..AnimOptions::default() };
opts.xmp = Some(b"<x/>");
let file = animation(4, 2, &frames, &opts).unwrap();
let info = scan(&file, 10).unwrap();
assert!(info.is_animation() && info.complete && info.alpha);
assert_eq!((info.width, info.height, info.loop_count), (4, 2, Some(3)));
assert_eq!(info.frames.iter().map(|f| (f.x, f.width, f.duration_ms, f.blend)).collect::<Vec<_>>(), [(0, 4, 40, false), (2, 2, 120, false)]);
// The `image` crate composites it: the second frame replaces the right half.
let d = WebPDecoder::new(std::io::Cursor::new(&file)).unwrap();
let decoded: Vec<_> = d.into_frames().collect::<Result<_, _>>().unwrap();
assert_eq!(decoded.len(), 2);
assert_eq!(decoded[0].buffer().get_pixel(3, 1).0, [255, 0, 0, 255]);
assert_eq!(decoded[1].buffer().get_pixel(3, 1).0, [0, 255, 0, 128]);
assert_eq!(decoded[1].buffer().get_pixel(0, 0).0, [255, 0, 0, 255]);
assert_eq!(decoded[1].delay().numer_denom_ms(), (120, 1));
}
#[test]
fn frame_flags_and_chunk_order() {
let px = vp8l(2, 2, [1, 2, 3, 255]);
let mut f = frame(Payload::Lossless { vp8l: &px }, 0, 0, 2, 2, 10);
f.blend = true;
f.dispose_to_background = true;
let file =
animation(2, 2, &[f], &AnimOptions { icc: Some(b"icc"), exif: Some(b"e"), background_bgra: [1, 2, 3, 4], ..AnimOptions::default() })
.unwrap();
let info = scan(&file, 10).unwrap();
assert_eq!((info.frames[0].blend, info.frames[0].dispose_to_background, info.alpha, info.animated), (true, true, false, true));
let mut at = 12;
let mut seen = Vec::new();
while at < file.len() {
let size = u32::from_le_bytes(file[at + 4..at + 8].try_into().unwrap()) as usize;
seen.push(String::from_utf8_lossy(&file[at..at + 4]).into_owned());
at += 8 + size + (size & 1);
}
assert_eq!(seen, ["VP8X", "ICCP", "ANIM", "ANMF", "EXIF"]);
// ICC, EXIF and animation flags; the background colour and loop count in ANIM.
assert_eq!(file[20], 0x20 | 0x08 | 0x02);
let anim = file.windows(4).position(|c| c == b"ANIM").unwrap();
assert_eq!(&file[anim + 8..anim + 14], &[1, 2, 3, 4, 0, 0]);
}
#[test]
fn lossy_container_keeps_alpha_payload_padding_and_xmp() {
// Container-only fixture: the writer must not reinterpret an encoder's VP8 bytes.
let vp8 = [11, 22, 33];
let alpha = [128];
let f = frame(Payload::Lossy { vp8: &vp8, alpha: Some(&alpha) }, 0, 0, 1, 1, 17);
let file = animation(1, 1, &[f], &AnimOptions { xmp: Some(b"xmp"), ..Default::default() }).unwrap();
let info = scan(&file, 10).unwrap();
assert!(info.alpha && info.complete);
assert_eq!(info.frames[0].duration_ms, 17);
let at = file.windows(4).position(|c| c == b"ANMF").unwrap();
let payload = at + 8 + 16;
assert_eq!(&file[payload..payload + 10], &[b'A', b'L', b'P', b'H', 2, 0, 0, 0, 0, 128]);
assert_eq!(&file[payload + 10..payload + 22], &[b'V', b'P', b'8', b' ', 3, 0, 0, 0, 11, 22, 33, 0]);
assert_eq!(&file[file.len() - 12..], &[b'X', b'M', b'P', b' ', 3, 0, 0, 0, b'x', b'm', b'p', 0]);
}
#[test]
fn what_does_not_fit_is_refused() {
let px = vp8l(2, 2, [0; 4]);
let ok = frame(Payload::Lossless { vp8l: &px }, 0, 0, 2, 2, 10);
let o = AnimOptions::default();
assert!(animation(2, 2, &[ok], &o).is_ok());
assert!(animation(2, 2, &[], &o).is_err());
assert!(animation(0, 2, &[ok], &o).is_err());
assert!(animation(MAX_CANVAS + 1, 1, &[ok], &o).is_err());
assert!(animation(2, 2, &[AnimFrame { x: 1, ..ok }], &o).is_err());
assert!(animation(2, 2, &[AnimFrame { x: 2, ..ok }], &o).is_err());
assert!(animation(2, 2, &[AnimFrame { width: 0, ..ok }], &o).is_err());
assert!(animation(2, 2, &[AnimFrame { duration_ms: (1 << 24) - 1, ..ok }], &o).is_ok());
assert!(animation(2, 2, &[AnimFrame { duration_ms: 1 << 24, ..ok }], &o).is_err());
let lossy = AnimFrame { payload: Payload::Lossy { vp8: &[0; 10], alpha: Some(&[0; 3]) }, ..ok };
assert!(animation(2, 2, &[lossy], &o).is_err());
let wide = AnimFrame { width: MAX_VP8_DIMENSION + 1, payload: Payload::Lossy { vp8: &[0; 10], alpha: None }, ..ok };
assert!(animation(MAX_VP8_DIMENSION + 1, 2, &[wide], &o).is_err());
}
#[cfg(feature = "vp8")]
#[test]
fn lossy_animations_decode_with_their_colours_alpha_and_timing() {
let (w, h) = (24u32, 16u32);
let solid = |c: [u8; 4]| c.repeat((w * h) as usize);
let (red, half_blue) = (solid([220, 30, 30, 255]), solid([30, 30, 220, 128]));
let file = lossy_animation(w, h, &[(&red, 100), (&half_blue, 50)], 90, &AnimOptions::default()).unwrap();
let info = scan(&file, 10).unwrap();
assert!(info.is_animation() && info.alpha && info.complete);
assert_eq!(info.frames.iter().map(|f| f.duration_ms).collect::<Vec<_>>(), [100, 50]);
let d = WebPDecoder::new(std::io::Cursor::new(&file)).unwrap();
let decoded: Vec<_> = d.into_frames().collect::<Result<_, _>>().unwrap();
assert_eq!(decoded.len(), 2);
let close = |a: [u8; 4], b: [u8; 4]| a.iter().zip(b).all(|(x, y)| x.abs_diff(y) <= 6);
assert!(close(decoded[0].buffer().get_pixel(5, 5).0, [220, 30, 30, 255]), "{:?}", decoded[0].buffer().get_pixel(5, 5));
assert!(close(decoded[1].buffer().get_pixel(5, 5).0, [30, 30, 220, 128]), "{:?}", decoded[1].buffer().get_pixel(5, 5));
// An opaque frame carries no alpha plane; a buffer of the wrong size is refused.
let opaque = lossy_animation(w, h, &[(&red, 10), (&red, 10)], 50, &AnimOptions::default()).unwrap();
assert!(!scan(&opaque, 10).unwrap().alpha);
assert!(lossy_animation(w, h, &[(&red[..10], 10)], 50, &AnimOptions::default()).is_err());
}
}