e4f86d11fe8a
gif_export.rs
//! Animated GIF of the deck (the Export… dialog; `file.export` with format `gif`).
//!
//! One frame per slide, drawn by the slide renderer and shown for `secondsPerSlide`. Every frame
//! gets its own 256-colour palette (exact when the slide has 256 colours or fewer, NeuQuant
//! otherwise), so a photo on one slide doesn't steal colours from the next. Transitions and
//! build animations are not animated: a slide appears as it looks when its builds have finished.
//!
//! All parameters are hostile: sizes, delays and slide lists are checked against fixed bounds, and
//! the total number of pixels encoded is capped, so a request can't exhaust memory or run for
//! hours.
use deckcraft_model::Presentation;
use serde_json::Value;
use crate::cmd::bad;
use crate::{EngineError, Result};
const CMD: &str = "file.export";
/// Size presets, by frame width in pixels (16:9 slides: 640×360, 960×540, 1280×720, 1920×1080).
pub const SIZE_PRESETS: [(&str, u32); 4] = [("small", 640), ("medium", 960), ("large", 1280), ("extraLarge", 1920)];
/// Frame width when none is given (the `medium` preset).
pub const DEFAULT_WIDTH: u32 = 960;
pub const MIN_WIDTH: u32 = 16;
pub const MAX_WIDTH: u32 = 3840;
/// Longest frame side: a very tall slide is scaled down to fit.
pub const MAX_SIDE: u32 = 3840;
pub const DEFAULT_SECONDS: f64 = 5.0;
/// GIF delays are in hundredths of a second; viewers treat delays under 0.02 s as 0.1 s anyway.
pub const MIN_SECONDS: f64 = 0.1;
pub const MAX_SECONDS: f64 = 600.0;
pub const MAX_FRAMES: usize = 500;
/// Cap on frames × width × height (≈ 96 Full HD frames or 480 frames at 960×540).
pub const MAX_TOTAL_PIXELS: u64 = 200_000_000;
/// NeuQuant sampling: 1 is slowest and best, 30 fastest; 10 is the usual balance.
const QUANTIZER_SPEED: i32 = 10;
/// What to export.
#[derive(Clone, Debug, PartialEq)]
pub struct GifOptions {
/// Frame width in pixels; the height follows the slide's aspect ratio.
pub width: u32,
pub seconds_per_slide: f64,
/// Loop forever (`true`) or play once.
pub loop_forever: bool,
/// Slide indices in play order (default: all).
pub slides: Option<Vec<usize>>,
/// Hidden slides are left out unless this is set.
pub include_hidden: bool,
}
impl Default for GifOptions {
fn default() -> Self {
GifOptions { width: DEFAULT_WIDTH, seconds_per_slide: DEFAULT_SECONDS, loop_forever: true, slides: None, include_hidden: false }
}
}
/// An encoded GIF and what is in it.
#[derive(Clone, Debug)]
pub struct GifOutput {
pub bytes: Vec<u8>,
pub frames: usize,
pub width: u32,
pub height: u32,
/// Per-frame delay in hundredths of a second, as written.
pub delay_cs: u16,
}
fn width_value(v: &Value) -> Result<u32> {
let err =
|| bad(CMD, format!("`width` must be a whole number of pixels from {MIN_WIDTH} to {MAX_WIDTH}, or one of small, medium, large, extraLarge"));
match v {
Value::String(s) => SIZE_PRESETS.iter().find(|(k, _)| k.eq_ignore_ascii_case(s.trim())).map(|(_, w)| *w).ok_or_else(err),
Value::Number(n) => n.as_u64().and_then(|w| u32::try_from(w).ok()).filter(|w| (MIN_WIDTH..=MAX_WIDTH).contains(w)).ok_or_else(err),
_ => Err(err()),
}
}
/// Check a per-slide duration (NaN, infinities and out-of-range values are errors).
pub fn check_seconds(s: f64) -> Result<f64> {
if (MIN_SECONDS..=MAX_SECONDS).contains(&s) {
Ok(s)
} else {
Err(bad(CMD, format!("`secondsPerSlide` must be from {MIN_SECONDS} to {MAX_SECONDS}")))
}
}
/// Present and not `null`.
fn given<'a>(p: &'a Value, key: &str) -> Option<&'a Value> {
p.get(key).filter(|v| !v.is_null())
}
impl GifOptions {
/// Read `{width?: px | small|medium|large|extraLarge, secondsPerSlide?, loop?: bool |
/// forever|once, slides?: [index], includeHidden?}`. Absent or `null` values take their
/// defaults; anything else that is out of range or of the wrong type is an error.
pub fn from_params(p: &Value) -> Result<Self> {
let mut o = GifOptions::default();
if let Some(v) = given(p, "width") {
o.width = width_value(v)?;
}
if let Some(v) = given(p, "secondsPerSlide") {
let s = v.as_f64().ok_or_else(|| bad(CMD, "`secondsPerSlide` must be a number"))?;
o.seconds_per_slide = check_seconds(s)?;
}
if let Some(v) = given(p, "loop") {
o.loop_forever = match v {
Value::Bool(b) => *b,
Value::String(s) if s.eq_ignore_ascii_case("forever") => true,
Value::String(s) if s.eq_ignore_ascii_case("once") => false,
_ => return Err(bad(CMD, "`loop` must be true (forever), false (once), \"forever\" or \"once\"")),
};
}
if let Some(v) = given(p, "slides") {
let a = v.as_array().ok_or_else(|| bad(CMD, "`slides` must be a list of slide indices"))?;
if a.is_empty() {
return Err(bad(CMD, "`slides` is empty"));
}
if a.len() > MAX_FRAMES {
return Err(bad(CMD, format!("a GIF can have at most {MAX_FRAMES} slides")));
}
let list = a
.iter()
.map(|x| x.as_u64().and_then(|i| usize::try_from(i).ok()))
.collect::<Option<Vec<usize>>>()
.ok_or_else(|| bad(CMD, "`slides` must be a list of slide indices (0, 1, 2…)"))?;
o.slides = Some(list);
}
if let Some(v) = given(p, "includeHidden") {
o.include_hidden = v.as_bool().ok_or_else(|| bad(CMD, "`includeHidden` must be true or false"))?;
}
Ok(o)
}
/// The slides that become frames, in order: the chosen ones (or all), without hidden slides
/// unless `include_hidden`.
pub fn frames(&self, doc: &Presentation) -> Result<Vec<usize>> {
let n = doc.slides.len();
let chosen: Vec<usize> = match &self.slides {
Some(list) => {
if let Some(i) = list.iter().find(|i| **i >= n) {
return Err(bad(CMD, format!("no slide {i} (the presentation has {n})")));
}
list.clone()
}
None => (0..n).collect(),
};
let frames: Vec<usize> = chosen.into_iter().filter(|i| self.include_hidden || doc.slides.get(*i).is_some_and(|s| !s.hidden)).collect();
if frames.is_empty() {
return Err(bad(CMD, "no slides to export (they are all hidden, or the presentation is empty)"));
}
if frames.len() > MAX_FRAMES {
return Err(bad(CMD, format!("a GIF can have at most {MAX_FRAMES} slides; choose a range")));
}
Ok(frames)
}
/// Delay per frame in hundredths of a second.
pub fn delay_cs(&self) -> Result<u16> {
let s = check_seconds(self.seconds_per_slide)?;
// In range by `check_seconds`: 10..=60_000.
Ok((s * 100.0).round().clamp(1.0, f64::from(u16::MAX)) as u16)
}
}
/// Frame size for a slide of `doc`'s size at `width` px: the height follows the aspect ratio and
/// no side exceeds [`MAX_SIDE`].
pub fn frame_size(doc: &Presentation, width: u32) -> (u32, u32) {
let (sw, sh) = (doc.slide_size.width, doc.slide_size.height);
let aspect = if sw.is_finite() && sh.is_finite() && sw > 0.0 && sh > 0.0 { sh / sw } else { 9.0 / 16.0 };
let w = f64::from(width.clamp(MIN_WIDTH, MAX_WIDTH));
let mut h = w * aspect;
let mut w2 = w;
if h > f64::from(MAX_SIDE) {
w2 = w * f64::from(MAX_SIDE) / h;
h = f64::from(MAX_SIDE);
}
let side = |v: f64| if v.is_finite() { v.round().clamp(1.0, f64::from(MAX_SIDE)) as u32 } else { 1 };
(side(w2), side(h))
}
/// Straight RGBA of a premultiplied render composited onto white (GIF has no partial alpha, and
/// fully transparent pixels would otherwise become see-through).
fn on_white(img: &deckcraft_render::Image, w: u32, h: u32) -> Vec<u8> {
let len = (w as usize).saturating_mul(h as usize).saturating_mul(4);
if img.width != w || img.height != h || img.pixels.len() != len {
log::error!("GIF export: a slide rendered at {}×{} instead of {w}×{h}; writing a blank frame", img.width, img.height);
return vec![255; len];
}
let mut px = img.pixels.clone();
for p in px.as_chunks_mut::<4>().0 {
let back = 255 - p[3];
p[0] = p[0].saturating_add(back);
p[1] = p[1].saturating_add(back);
p[2] = p[2].saturating_add(back);
p[3] = 255;
}
px
}
/// Render and encode the GIF.
pub fn encode(doc: &Presentation, opts: &GifOptions) -> Result<GifOutput> {
use image::codecs::gif::{GifEncoder, Repeat};
let frames = opts.frames(doc)?;
let delay_cs = opts.delay_cs()?;
let (w, h) = frame_size(doc, opts.width);
let total = (frames.len() as u64).saturating_mul(u64::from(w)).saturating_mul(u64::from(h));
if total > MAX_TOTAL_PIXELS {
return Err(bad(CMD, format!("{} slides at {w}×{h} is too large for a GIF; choose a smaller size or fewer slides", frames.len())));
}
let scale = f64::from(w) / doc.slide_size.width;
let scale = if scale.is_finite() && scale > 0.0 { scale } else { 1.0 };
let enc_err = |e: image::ImageError| EngineError::Other(format!("GIF encoding failed: {e}"));
let mut bytes = Vec::new();
{
let mut enc = GifEncoder::new_with_speed(&mut bytes, QUANTIZER_SPEED);
// No repeat block at all means "play once"; a repeat count of 0 means "forever".
if opts.loop_forever {
enc.set_repeat(Repeat::Infinite).map_err(enc_err)?;
}
for i in &frames {
let img = deckcraft_render::render_slide(doc, *i, &deckcraft_render::RenderOpts { scale, size: Some((w, h)), ..Default::default() });
let buffer = image::RgbaImage::from_raw(w, h, on_white(&img, w, h))
.ok_or_else(|| EngineError::Other(format!("GIF export: slide {i} has no pixels")))?;
let delay = image::Delay::from_numer_denom_ms(u32::from(delay_cs) * 10, 1);
enc.encode_frame(image::Frame::from_parts(buffer, 0, 0, delay)).map_err(enc_err)?;
}
}
Ok(GifOutput { bytes, frames: frames.len(), width: w, height: h, delay_cs })
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
use image::AnimationDecoder;
use serde_json::json;
use super::*;
use crate::Session;
const COLOURS: [(&str, [u8; 3]); 4] =
[("#E02020", [0xE0, 0x20, 0x20]), ("#20A040", [0x20, 0xA0, 0x40]), ("#2040E0", [0x20, 0x40, 0xE0]), ("#F0C000", [0xF0, 0xC0, 0x00])];
/// Four blank slides with solid backgrounds (red, green, blue, yellow); slide 2 (blue) hidden.
fn deck() -> Session {
let mut s = Session::new();
s.execute("file.new", &json!({"blank": true})).unwrap();
while s.doc().unwrap().doc.slides.len() < COLOURS.len() {
s.execute("slide.new", &json!({})).unwrap();
}
for (i, (hex, _)) in COLOURS.iter().enumerate() {
s.execute("design.background", &json!({"color": hex, "index": i})).unwrap();
}
s.execute("slide.hide", &json!({"index": 2, "hidden": true})).unwrap();
s
}
fn temp(name: &str) -> std::path::PathBuf {
let dir = std::env::temp_dir().join(format!("deckcraft-gif-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
dir.join(name)
}
fn decode(bytes: &[u8]) -> (image::metadata::LoopCount, Vec<image::Frame>) {
let dec = image::codecs::gif::GifDecoder::new(std::io::Cursor::new(bytes)).unwrap();
let count = dec.loop_count();
(count, dec.into_frames().collect_frames().unwrap())
}
/// The NETSCAPE2.0 application block's loop count, if the GIF has one.
fn netscape_loops(bytes: &[u8]) -> Option<u16> {
let tag = b"NETSCAPE2.0";
let at = bytes.windows(tag.len()).position(|w| w == tag)?;
// NETSCAPE2.0, sub-block size 3, id 1, loop count (little endian).
let b = bytes.get(at + tag.len()..at + tag.len() + 4)?;
Some(u16::from_le_bytes([b[2], b[3]]))
}
fn close(a: [u8; 4], b: [u8; 3]) -> bool {
(0..3).all(|k| (i32::from(a[k]) - i32::from(b[k])).abs() <= 12) && a[3] == 255
}
#[test]
fn exports_one_frame_per_visible_slide() {
let mut s = deck();
let path = temp("deck.gif");
let r = s.execute("file.export", &json!({"path": path.to_string_lossy(), "width": 320, "secondsPerSlide": 1.5})).unwrap();
assert_eq!(r["frames"], 3, "{r}");
let bytes = std::fs::read(&path).unwrap();
assert!(bytes.starts_with(b"GIF89a"));
assert_eq!(netscape_loops(&bytes), Some(0), "loops forever by default");
let (count, frames) = decode(&bytes);
assert!(matches!(count, image::metadata::LoopCount::Infinite));
assert_eq!(frames.len(), 3, "the hidden slide is skipped");
// Slides are 16:9: 320×180.
let expected = [COLOURS[0].1, COLOURS[1].1, COLOURS[3].1];
for (f, want) in frames.iter().zip(expected) {
assert_eq!((f.buffer().width(), f.buffer().height()), (320, 180));
assert_eq!(f.delay().numer_denom_ms(), (1500, 1));
let px = f.buffer().get_pixel(160, 90).0;
assert!(close(px, want), "frame colour {px:?}, expected {want:?}");
}
assert_eq!((r["width"].as_u64(), r["height"].as_u64()), (Some(320), Some(180)));
let _ = std::fs::remove_file(&path);
}
#[test]
fn presets_ranges_hidden_slides_and_play_once() {
let s = deck();
let doc = &s.doc().unwrap().doc;
let o = GifOptions::from_params(&json!({"width": "small", "loop": false, "slides": [3, 2, 1], "includeHidden": true})).unwrap();
let out = encode(doc, &o).unwrap();
assert_eq!((out.frames, out.width, out.height, out.delay_cs), (3, 640, 360, 500));
assert_eq!(netscape_loops(&out.bytes), None, "play once: no repeat block");
let (_, frames) = decode(&out.bytes);
let want = [COLOURS[3].1, COLOURS[2].1, COLOURS[1].1];
for (f, w) in frames.iter().zip(want) {
assert!(close(f.buffer().get_pixel(320, 180).0, w));
assert_eq!(f.delay().numer_denom_ms(), (5000, 1), "5 seconds by default");
}
// A range that holds only the hidden slide has nothing to export.
let o = GifOptions::from_params(&json!({"slides": [2]})).unwrap();
assert!(encode(doc, &o).is_err());
for (preset, w) in SIZE_PRESETS {
assert_eq!(GifOptions::from_params(&json!({"width": preset})).unwrap().width, w);
}
assert_eq!(
GifOptions::from_params(&json!({"width": "Large", "loop": "once"})).unwrap(),
GifOptions { width: 1280, loop_forever: false, ..Default::default() }
);
assert_eq!(GifOptions::from_params(&json!({"width": null, "secondsPerSlide": null})).unwrap(), GifOptions::default());
}
#[test]
fn hostile_params_are_errors_not_panics() {
for p in [
json!({"width": 0}),
json!({"width": 15}),
json!({"width": 3841}),
json!({"width": -5}),
json!({"width": 1e308}),
json!({"width": 640.5}),
json!({"width": "huge"}),
json!({"width": [640]}),
json!({"secondsPerSlide": 0}),
json!({"secondsPerSlide": 0.05}),
json!({"secondsPerSlide": -1}),
json!({"secondsPerSlide": 601}),
json!({"secondsPerSlide": 1e308}),
json!({"secondsPerSlide": "5"}),
json!({"loop": 1}),
json!({"loop": "twice"}),
json!({"slides": []}),
json!({"slides": [-1]}),
json!({"slides": [0.5]}),
json!({"slides": "1-3"}),
json!({"slides": vec![0; MAX_FRAMES + 1]}),
json!({"includeHidden": "yes"}),
] {
assert!(GifOptions::from_params(&p).is_err(), "{p}");
}
for v in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, f64::MIN_POSITIVE, 1e-300] {
assert!(check_seconds(v).is_err(), "{v}");
let o = GifOptions { seconds_per_slide: v, ..Default::default() };
assert!(o.delay_cs().is_err(), "{v}");
}
assert_eq!(GifOptions { seconds_per_slide: 600.0, ..Default::default() }.delay_cs().unwrap(), 60_000);
assert_eq!(GifOptions { seconds_per_slide: 0.1, ..Default::default() }.delay_cs().unwrap(), 10);
// Through the command too: errors, the presentation untouched, no file written.
let mut s = deck();
let path = temp("hostile.gif");
for p in [
json!({"width": 99999}),
json!({"secondsPerSlide": -3}),
json!({"slides": [0, 99]}),
json!({"slides": [18446744073709551615u64]}),
json!({"slides": [2]}),
] {
let mut p = p;
p["path"] = json!(path.to_string_lossy());
assert!(s.execute("file.export", &p).is_err(), "{p}");
}
assert!(!path.exists());
assert_eq!(s.doc().unwrap().doc.slides.len(), 4);
}
#[test]
fn sizes_are_bounded() {
let mut s = deck();
// A very tall slide is scaled down so no side exceeds MAX_SIDE.
s.execute("design.slideSize", &json!({"w": 100.0, "h": 4000.0, "scale": "none"})).unwrap();
let doc = &s.doc().unwrap().doc;
let (w, h) = frame_size(doc, MAX_WIDTH);
assert!(w >= 1 && h <= MAX_SIDE && w <= MAX_WIDTH, "{w}×{h}");
// The total pixel budget stops huge requests before anything is rendered.
let mut big = Presentation::clone(doc);
big.slide_size = deckcraft_geom::Size::new(960.0, 540.0);
let slide = big.slides[0].clone();
big.slides = vec![slide; 200];
let o = GifOptions { width: MAX_WIDTH, ..Default::default() };
let e = encode(&big, &o).unwrap_err().to_string();
assert!(e.contains("too large"), "{e}");
// A degenerate slide size falls back to 16:9 rather than dividing by zero.
let mut odd = Presentation::clone(doc);
odd.slide_size = deckcraft_geom::Size::new(0.0, f64::NAN);
assert_eq!(frame_size(&odd, 640), (640, 360));
}
#[test]
fn gif_is_also_a_save_format_and_inferred_from_the_path() {
let s = deck();
let bytes = crate::cmd::file::save_bytes(&s.doc().unwrap().doc, "gif").unwrap();
assert!(bytes.starts_with(b"GIF89a"));
assert_eq!(crate::cmd::file::format_for_path("Talk.GIF"), "gif");
let bytes = crate::cmd::file::gif_bytes(&s.doc().unwrap().doc, &json!({"width": 64, "slides": [0]})).unwrap();
assert_eq!(decode(&bytes).1.len(), 1);
}
}
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.