Files
AniCraft/crates/engine/src/anim.rs

455 lines
19 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 PNG and animated WebP export (ADR 0063): full colour and real alpha, for the web
//! and chat apps, where an animated GIF has 256 colours and 1-bit transparency.
//!
//! Both formats share one pipeline. Frames render in parallel, a batch at a time (memory stays
//! bounded), as GIF export does. A frame identical to the one before it is merged into that
//! frame's delay. Every other frame is cut down to the rectangle that changed since the frame
//! before and compressed in parallel as an image of its own (a PNG, or a lossless WebP); the
//! compressed data is then put into one file in order, by hand, chunk by chunk:
//!
//! * **APNG** (the APNG specification): `IHDR`, `acTL`, then per frame an `fcTL` (its region,
//! delay, dispose op none, blend op) and its `IDAT` / `fdAT` data. Delays are exact fractions
//! of the document's frame rate (2 frames at 29.97 fps: 200/2997 s). A region whose changed
//! pixels are all opaque blends *over* the frame before, with its unchanged pixels left
//! transparent (they compress to almost nothing); otherwise it replaces (*source*).
//! * **WebP** (the WebP container specification): `VP8X`, `ANIM`, then an `ANMF` per frame
//! wrapping its `VP8L` (lossless) bitstream. Regions start on even pixels, as the format
//! needs, and replace what was there (no blending: the decoders' blend rounds opaque pixels).
//! Durations are whole milliseconds; each is rounded from the exact time the frame starts, so
//! the error never adds up and the running time is exact to the millisecond.
//!
//! A delay longer than one frame header can hold goes on, after the frame, as frames that
//! change nothing (one transparent pixel blended over), so timing is never cut short.
use crate::params::*;
use crate::{EngineError, Result, Session};
use anicraft_render::{View, render};
use rayon::prelude::*;
use serde_json::{Value, json};
use std::path::PathBuf;
/// The two animated formats.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Kind {
Apng,
Webp,
}
impl Kind {
fn name(self) -> &'static str {
match self {
Kind::Apng => "animated PNG",
Kind::Webp => "animated WebP",
}
}
}
/// Largest animation made (frames × pixels), as for GIF: time stays bounded.
pub const MAX_ANIM_PIXELS: u64 = 600 * 1280 * 720;
/// WebP canvases and frames are at most 16384 px per side.
pub const MAX_WEBP_EDGE: u32 = 16_384;
/// Pixels rendered at once (a batch of frames), so memory stays bounded at any size.
const BATCH_PIXELS: u64 = 32 * 1024 * 1024;
/// Most plays a loop count says (both formats store it in 16 bits for WebP's sake).
pub const MAX_PLAYS: u32 = anicraft_doc::publish::MAX_PLAYS;
/// Longest WebP frame duration (24 bits of milliseconds).
const MAX_WEBP_MS: u64 = 0xFF_FFFF;
/// A rectangle of the canvas, in pixels.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Rect {
pub x: u32,
pub y: u32,
pub w: u32,
pub h: u32,
}
/// One frame, compressed: the region it covers, whether it blends over what is there (else it
/// replaces it), and its image data (PNG `IDAT` data, or a raw `VP8L` payload).
struct Encoded {
rect: Rect,
over: bool,
data: Vec<u8>,
}
/// The frame rate as a fraction `p / q` frames per second: 24 → 24/1, 29.97 → 2997/100,
/// 23.976 → 2997/125. Rates no small fraction matches are taken to a thousandth.
pub fn fps_ratio(fps: f32) -> (u64, u64) {
let fps = if fps.is_finite() && fps > 0.0 { f64::from(fps) } else { 24.0 };
for q in 1..=1001u64 {
let p = (fps * q as f64).round();
if p >= 1.0 && (p / q as f64 - fps).abs() <= fps * 1e-6 {
return (p as u64, q);
}
}
let p = ((fps * 1000.0).round() as u64).max(1);
let g = gcd(p, 1000);
(p / g, 1000 / g)
}
fn gcd(mut a: u64, mut b: u64) -> u64 {
while b != 0 {
(a, b) = (b, a % b);
}
a.max(1)
}
/// When frame `t` (from the first exported) starts, in whole milliseconds, rounded from the
/// exact time at `p / q` fps.
pub fn start_ms(t: u64, (p, q): (u64, u64)) -> u64 {
let p = u128::from(p.max(1));
((2 * u128::from(t) * 1000 * u128::from(q) + p) / (2 * p)) as u64
}
/// The APNG delays (numerator, denominator in seconds) of a frame shown from frame `start` for
/// `count` frames: one exact fraction, or more when it is longer than one `fcTL` holds.
pub fn apng_delays(start: u64, count: u64, (p, q): (u64, u64)) -> Vec<(u16, u16)> {
let mut out = Vec::new();
if let Ok(den) = u16::try_from(p) {
// `count` frames last count·q/p s; pieces of at most 65535/q frames always fit.
let most = (u64::from(u16::MAX) / q.max(1)).max(1);
let mut left = count;
while left > 0 {
let m = left.min(most);
let (num, g) = (m * q, gcd(m * q, p));
out.push((u16::try_from(num / g).unwrap_or(u16::MAX), u16::try_from(u64::from(den) / g).unwrap_or(den)));
left -= m;
}
} else {
// A rate with a huge denominator: milliseconds, rounded from each frame's start.
let mut ms = start_ms(start + count, (p, q)) - start_ms(start, (p, q));
while ms > 0 {
let m = ms.min(u64::from(u16::MAX));
out.push((m as u16, 1000));
ms -= m;
}
}
if out.is_empty() {
out.push((0, 1));
}
out
}
/// The WebP durations (milliseconds) of a frame shown from frame `start` for `count` frames:
/// one, or more when it is longer than one `ANMF` holds.
pub fn webp_durations(start: u64, count: u64, ratio: (u64, u64)) -> Vec<u32> {
let mut ms = start_ms(start + count, ratio).saturating_sub(start_ms(start, ratio));
let mut out = Vec::new();
loop {
let m = ms.min(MAX_WEBP_MS);
out.push(m as u32);
ms -= m;
if ms == 0 {
return out;
}
}
}
/// The smallest rectangle holding every pixel where RGBA8 images `a` and `b` (`w` × `h`) differ,
/// or `None` when they are the same.
pub fn changed(a: &[u8], b: &[u8], w: u32, h: u32) -> Option<Rect> {
let stride = w as usize * 4;
let (mut x0, mut y0, mut x1, mut y1) = (u32::MAX, u32::MAX, 0u32, 0u32);
for y in 0..h {
let at = y as usize * stride;
let (Some(ra), Some(rb)) = (a.get(at..at + stride), b.get(at..at + stride)) else { break };
if ra == rb {
continue;
}
let (pa, pb) = (ra.as_chunks::<4>().0, rb.as_chunks::<4>().0);
let first = pa.iter().zip(pb).position(|(u, v)| u != v).unwrap_or(0) as u32;
let last = pa.iter().zip(pb).rposition(|(u, v)| u != v).unwrap_or(0) as u32;
x0 = x0.min(first);
x1 = x1.max(last);
y0 = y0.min(y);
y1 = y;
}
(y0 != u32::MAX).then(|| Rect { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 })
}
/// Rectangle `r` of RGBA8 image `px` (`w` wide).
fn crop(px: &[u8], w: u32, r: Rect) -> Vec<u8> {
let stride = w as usize * 4;
let mut out = Vec::with_capacity(r.w as usize * r.h as usize * 4);
for y in r.y..r.y + r.h {
let at = y as usize * stride + r.x as usize * 4;
if let Some(row) = px.get(at..at + r.w as usize * 4) {
out.extend_from_slice(row);
}
}
out
}
/// What frame `cur` writes after frame `before` (none: it is the first, and covers the canvas):
/// the region, whether it blends over, and its pixels.
fn region(kind: Kind, before: Option<&[u8]>, cur: &[u8], w: u32, h: u32) -> (Rect, bool, Vec<u8>) {
let full = Rect { x: 0, y: 0, w, h };
let Some(before) = before else { return (full, false, cur.to_vec()) };
let mut r = changed(before, cur, w, h).unwrap_or(full);
match kind {
Kind::Webp => {
// Frame offsets are stored halved: the region starts on an even pixel.
let (ex, ey) = (r.x & !1, r.y & !1);
r = Rect { x: ex, y: ey, w: r.w + (r.x - ex), h: r.h + (r.y - ey) };
(r, false, crop(cur, w, r))
}
Kind::Apng => {
let (old, new) = (crop(before, w, r), crop(cur, w, r));
let (po, pn) = (old.as_chunks::<4>().0, new.as_chunks::<4>().0);
if po.iter().zip(pn).all(|(o, n)| o == n || n[3] == 255) {
// Every changed pixel is opaque: blend over, unchanged pixels transparent.
let mut px = Vec::with_capacity(new.len());
for (o, n) in po.iter().zip(pn) {
px.extend_from_slice(if o == n { &[0, 0, 0, 0] } else { n });
}
(r, true, px)
} else {
(r, false, new)
}
}
}
}
/// A standalone PNG's image data: its `IDAT` chunks' contents, joined.
fn idat(png: &[u8]) -> Result<Vec<u8>> {
let mut out = Vec::new();
let mut at = 8usize;
while let Some(head) = png.get(at..at + 8) {
let len = u32::from_be_bytes([head[0], head[1], head[2], head[3]]) as usize;
let data = png.get(at + 8..at + 8 + len).ok_or_else(|| EngineError::Format("the PNG encoder wrote a short chunk".into()))?;
if &head[4..8] == b"IDAT" {
out.extend_from_slice(data);
}
at += 12 + len;
}
Ok(out)
}
/// A RIFF file's first chunk named `id`, payload only; craft-webp owns container framing.
fn riff_chunk<'a>(riff: &'a [u8], id: &[u8; 4]) -> Option<&'a [u8]> {
let mut at = 12usize;
while let Some(head) = riff.get(at..at + 8) {
let len = u32::from_le_bytes([head[4], head[5], head[6], head[7]]) as usize;
let whole = 8 + len + (len & 1);
if &head[0..4] == id {
return riff.get(at + 8..at + 8 + len);
}
at += whole;
}
None
}
/// Compresses `px` (`w` × `h` RGBA8) as one frame's data.
fn compress(kind: Kind, px: &[u8], w: u32, h: u32) -> Result<Vec<u8>> {
let fail = |e: String| EngineError::Format(format!("{} frame: {e}", kind.name()));
let img = craft_image_codecs::Image::from_u8(w, h, craft_image_codecs::ChannelLayout::Rgba, px.to_vec())
.map_err(|e| fail(e.to_string()))?;
match kind {
Kind::Apng => {
let opts = craft_image_codecs::EncodeOptions {
png_compression: craft_image_codecs::PngCompression::Best,
..Default::default()
};
let buf = craft_image_codecs::encode(&img, craft_image_codecs::Format::Png, &opts).map_err(|e| fail(e.to_string()))?;
idat(&buf)
}
Kind::Webp => {
let opts = craft_image_codecs::EncodeOptions { webp_lossless: true, ..Default::default() };
let buf = craft_image_codecs::encode(&img, craft_image_codecs::Format::WebP, &opts).map_err(|e| fail(e.to_string()))?;
riff_chunk(&buf, b"VP8L").map(<[u8]>::to_vec).ok_or_else(|| fail("the WebP encoder wrote no lossless image".into()))
}
}
}
fn encode(kind: Kind, before: Option<&[u8]>, cur: &[u8], w: u32, h: u32) -> Result<Encoded> {
let (rect, over, px) = region(kind, before, cur, w, h);
Ok(Encoded { rect, over, data: compress(kind, &px, rect.w, rect.h)? })
}
/// A frame that changes nothing (one transparent pixel blended over the top-left corner): how
/// a delay too long for one frame header goes on.
fn still(kind: Kind) -> Result<Encoded> {
Ok(Encoded { rect: Rect { x: 0, y: 0, w: 1, h: 1 }, over: true, data: compress(kind, &[0, 0, 0, 0], 1, 1)? })
}
// ----- the files ---------------------------------------------------------------------------
/// The shared container owns PNG chunks, CRCs and APNG sequence validation.
/// Frame selection, compression and exact rational timing remain AniCraft policy.
fn apng_file(w: u32, h: u32, plays: u32, frames: &[(&Encoded, (u16, u16))]) -> Result<Vec<u8>> {
use craft_apng_container::apng::Frame;
// Bound the output by the already-compressed payloads plus exact framing.
// Pixel/frame budgets are enforced before rendering, unchanged by this adapter.
let budget = frames
.iter()
.enumerate()
.try_fold(65usize, |size, (index, (f, _))| size.checked_add(50 + if index == 0 { 0 } else { 4 }).and_then(|n| n.checked_add(f.data.len())))
.ok_or_else(|| EngineError::Format("animated PNG output size overflow".into()))?;
let frames: Vec<_> = frames
.iter()
.map(|(f, (num, den))| Frame {
width: f.rect.w,
height: f.rect.h,
x: f.rect.x,
y: f.rect.y,
delay_num: *num,
delay_den: *den,
over: f.over,
data: &f.data,
})
.collect();
craft_apng_container::apng::encode(w, h, plays, &frames, budget).map_err(|e| EngineError::Format(e.to_string()))
}
/// The animated WebP container is shared; frame selection, delta rectangles and timing
/// remain application policy. `Encoded::data` is a raw VP8L payload, not a RIFF chunk.
fn webp_file(w: u32, h: u32, plays: u32, alpha: bool, background: [u8; 4], frames: &[(&Encoded, u32)]) -> Result<Vec<u8>> {
use craft_webp::anim::{AnimFrame, AnimOptions, Payload};
let frames: Vec<_> = frames
.iter()
.map(|(f, ms)| AnimFrame {
x: f.rect.x,
y: f.rect.y,
width: f.rect.w,
height: f.rect.h,
duration_ms: *ms,
blend: f.over,
dispose_to_background: false,
payload: Payload::Lossless { vp8l: &f.data },
})
.collect();
let [r, g, b, a] = background;
let opts = AnimOptions { loop_count: u16::try_from(plays).unwrap_or(u16::MAX), background_bgra: [b, g, r, a], alpha, ..Default::default() };
craft_webp::anim::animation(w, h, &frames, &opts).map_err(|e| EngineError::Format(e.to_string()))
}
// ----- the command -------------------------------------------------------------------------
/// How many times it plays: `loop` true (or absent) forever (0), false once, or a count.
pub(crate) fn plays(p: &Value) -> Result<u32> {
match p.get("loop") {
None | Some(Value::Null) | Some(Value::Bool(true)) => Ok(0),
Some(Value::Bool(false)) => Ok(1),
Some(v) => v
.as_u64()
.and_then(|n| u32::try_from(n).ok())
.filter(|n| *n <= MAX_PLAYS)
.ok_or_else(|| EngineError::Param(format!("param 'loop' must be true (forever), false (once) or how many times it plays (0 is forever, at most {MAX_PLAYS})"))),
}
}
/// `file.export_apng` and `file.export_webp`.
pub fn export(s: &mut Session, p: &Value, kind: Kind) -> Result<Value> {
let path = PathBuf::from(str_req(p, "path")?);
// The whole movie: every scene in order.
let last = s.doc.frame_count().saturating_sub(1);
let from = opt_u32(p, "from")?.unwrap_or(0).min(last);
let to = opt_u32(p, "to")?.unwrap_or(last).min(last);
if to < from {
return Err(EngineError::Param("'to' must not be before 'from'".into()));
}
let scale = crate::cmds_file::scale_param(p)?;
let plays = plays(p)?;
let background = opt_bool(p, "background")?.unwrap_or(false);
let mut view = View::stage(&s.doc, scale);
if !background {
view.background = None;
}
let (w, h) = (view.width.max(1), view.height.max(1));
if kind == Kind::Webp && (w > MAX_WEBP_EDGE || h > MAX_WEBP_EDGE) {
return Err(EngineError::Param(format!("WebP frames are at most {MAX_WEBP_EDGE} px per side; lower 'scale'")));
}
let n = u64::from(to - from) + 1;
if n * u64::from(w) * u64::from(h) > MAX_ANIM_PIXELS {
return Err(EngineError::Param(format!("that {} would be too large ({n} frames at {w}×{h}); lower 'scale' or the frame range", kind.name())));
}
let doc = &s.doc;
let job = s.job.as_deref();
let started = web_time::Instant::now();
let batch = (BATCH_PIXELS / (u64::from(w) * u64::from(h))).clamp(2, 16) as usize;
// Each distinct frame: its first frame (from 0) and how many frames it shows for.
let mut shown: Vec<(u64, u64)> = Vec::new();
let mut encoded: Vec<Encoded> = Vec::new();
let mut prev: Option<Vec<u8>> = None;
let frames: Vec<u32> = (from..=to).collect();
for (b, chunk) in frames.chunks(batch).enumerate() {
let images: Vec<Vec<u8>> = chunk
.par_iter()
.map(|&f| {
let (pm, _) = render(&anicraft_doc::evaluate(doc, f), &view)?;
crate::publish::tick(job, 1)?;
Ok(pm.to_rgba8())
})
.collect::<Result<_>>()?;
// A frame like the one before it only lengthens that frame's delay.
let mut fresh: Vec<usize> = Vec::new();
let mut last_seen: Option<&[u8]> = prev.as_deref();
for (i, img) in images.iter().enumerate() {
match shown.last_mut() {
Some((_, count)) if last_seen == Some(img.as_slice()) => *count += 1,
_ => {
shown.push(((b * batch + i) as u64, 1));
fresh.push(i);
}
}
last_seen = Some(img.as_slice());
}
let made = (0..fresh.len())
.into_par_iter()
.map(|k| {
let cur = fresh.get(k).and_then(|&i| images.get(i)).ok_or_else(|| EngineError::Format("lost a frame".into()))?;
let before = match k.checked_sub(1) {
None => prev.as_deref(),
Some(j) => fresh.get(j).and_then(|&i| images.get(i)).map(Vec::as_slice),
};
encode(kind, before, cur, w, h)
})
.collect::<Result<Vec<_>>>()?;
encoded.extend(made);
if let Some(&i) = fresh.last() {
prev = images.into_iter().nth(i);
}
}
let ratio = fps_ratio(doc.stage.fps);
let pad = still(kind)?;
let bytes = match kind {
Kind::Apng => {
let mut list: Vec<(&Encoded, (u16, u16))> = Vec::new();
for (e, &(start, count)) in encoded.iter().zip(&shown) {
for (k, d) in apng_delays(start, count, ratio).into_iter().enumerate() {
list.push((if k == 0 { e } else { &pad }, d));
}
}
apng_file(w, h, plays, &list)?
}
Kind::Webp => {
let mut list: Vec<(&Encoded, u32)> = Vec::new();
for (e, &(start, count)) in encoded.iter().zip(&shown) {
for (k, d) in webp_durations(start, count, ratio).into_iter().enumerate() {
list.push((if k == 0 { e } else { &pad }, d));
}
}
let padded = list.len() > encoded.len();
let c = s.doc.stage.background.sanitized();
let q = |v: f32| (v * 255.0).round() as u8;
let bg = if background { [q(c.r), q(c.g), q(c.b), 255] } else { [0; 4] };
webp_file(w, h, plays, !background || padded, bg, &list)?
}
};
crate::vfs::write(&path, &bytes)?;
Ok(json!({
"written": path.display().to_string(),
"frames": n,
"stored_frames": encoded.len(),
"bytes": bytes.len(),
"width": w,
"height": h,
"loop": plays,
"ms": started.elapsed().as_millis() as u64,
}))
}
#[cfg(test)]
#[path = "anim_tests.rs"]
mod tests;