Skip to main content

alpha2_extensions/animated/
mod.rs

1//! GIF, animated WebP, and APNG, composited frame by frame as each format defines.
2//!
3//! Probing reads only headers and refuses, before allocating, files past the canvas limit,
4//! [`MAX_ANIMATION_FRAMES`], or [`MAX_ANIMATION_PIXELS`]. Opening decodes once to check the file
5//! and keeps what fits the frame budget. A request for an uncached frame decodes forward,
6//! restarting for earlier frames and caching the frames just before the target, so reverse
7//! playback restarts once per budget of frames.
8//!
9//! Extra readers (clips at unrelated times) each get their own decoder but share the file and the
10//! kept frames under one budget.
11
12mod compositor;
13
14use std::collections::BTreeMap;
15use std::io::Cursor;
16use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
17
18use alpha2_time::{MediaTime, TICKS_PER_SECOND};
19
20use alpha2_model::ProviderSource;
21
22use crate::api::{
23    Diagnostic, ExtensionError, Format, FramePixels, MAX_NORMALIZED_DELAY_MS, NORMALIZED_DELAY_MS,
24    ProbeReport, ResourceResolver, Timing, VisualFrame, VisualProvider, VisualSource, premultiply,
25};
26use crate::budget::{
27    DEFAULT_FRAME_BUDGET, MAX_ANIMATION_FRAMES, MAX_ANIMATION_PIXELS, MAX_CANVAS_PIXELS,
28    check_canvas,
29};
30use compositor::{Blend, Compositor, Dispose, PartialFrame};
31
32/// Reads GIF, animated WebP, and APNG. Still files of those formats are left to the host.
33pub struct AnimatedImageProvider;
34
35impl VisualProvider for AnimatedImageProvider {
36    fn name(&self) -> &'static str {
37        "animated-image"
38    }
39
40    fn probe(&self, bytes: &[u8]) -> Option<Result<ProbeReport, ExtensionError>> {
41        let format = sniff(bytes)?;
42        Some(index(format, bytes).map(|index| index.report(format)))
43            .filter(|report| !matches!(report, Ok(report) if report.timing.frame_count() < 2))
44    }
45
46    fn open(
47        &self,
48        bytes: Arc<[u8]>,
49        _source: &ProviderSource,
50        _resolver: &dyn ResourceResolver,
51    ) -> Result<Box<dyn VisualSource>, ExtensionError> {
52        Ok(Box::new(AnimatedSource::open(bytes, DEFAULT_FRAME_BUDGET)?))
53    }
54}
55
56/// The format by signature; APNG and WebP only when they declare animation.
57fn sniff(bytes: &[u8]) -> Option<Format> {
58    if bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a") {
59        return Some(Format::Gif);
60    }
61    if bytes.starts_with(b"\x89PNG\r\n\x1a\n") {
62        return png_is_animated(bytes).then_some(Format::Apng);
63    }
64    if bytes.len() >= 21 && &bytes[..4] == b"RIFF" && &bytes[8..12] == b"WEBP" {
65        // An extended header whose flags byte sets the animation bit.
66        return (&bytes[12..16] == b"VP8X" && bytes[20] & 0x02 != 0).then_some(Format::Webp);
67    }
68    None
69}
70
71/// Whether a PNG has an animation control before its image data. A chunk length that would
72/// overflow the address space (easy on wasm32) ends the walk.
73fn png_is_animated(bytes: &[u8]) -> bool {
74    let mut at = 8_usize;
75    while bytes.len().saturating_sub(at) >= 8 {
76        let length = u32::from_be_bytes([bytes[at], bytes[at + 1], bytes[at + 2], bytes[at + 3]]);
77        let kind = &bytes[at + 4..at + 8];
78        if kind == b"acTL" {
79            return true;
80        }
81        if kind == b"IDAT" {
82            return false;
83        }
84        let Some(next) = usize::try_from(length)
85            .ok()
86            .and_then(|length| at.checked_add(12)?.checked_add(length))
87        else {
88            return false;
89        };
90        at = next;
91    }
92    false
93}
94
95/// What an animation's headers declare.
96struct Index {
97    width: u32,
98    height: u32,
99    loop_count: Option<u32>,
100    frames: Vec<Delay>,
101    /// Pixels of all frame rectangles together.
102    pixels: u64,
103}
104
105impl Index {
106    fn new(width: u32, height: u32) -> Result<Self, ExtensionError> {
107        check_canvas(width, height)?;
108        Ok(Self {
109            width,
110            height,
111            loop_count: None,
112            frames: Vec::new(),
113            pixels: 0,
114        })
115    }
116
117    /// Adds a frame, refusing it past the frame or pixel budget.
118    fn push(&mut self, width: u32, height: u32, delay: Delay) -> Result<(), ExtensionError> {
119        if self.frames.len() == MAX_ANIMATION_FRAMES {
120            return Err(ExtensionError::Budget(format!(
121                "more than {MAX_ANIMATION_FRAMES} frames"
122            )));
123        }
124        let pixels = u64::from(width) * u64::from(height);
125        if pixels > MAX_CANVAS_PIXELS {
126            return Err(ExtensionError::Budget(format!(
127                "a {width}x{height} frame is larger than {MAX_CANVAS_PIXELS} pixels"
128            )));
129        }
130        self.pixels += pixels;
131        if self.pixels > MAX_ANIMATION_PIXELS {
132            return Err(ExtensionError::Budget(format!(
133                "the frames together cover more than {MAX_ANIMATION_PIXELS} pixels"
134            )));
135        }
136        self.frames.push(delay);
137        Ok(())
138    }
139
140    fn report(&self, format: Format) -> ProbeReport {
141        let mut diagnostics = Vec::new();
142        let durations = self
143            .frames
144            .iter()
145            .enumerate()
146            .map(|(frame, delay)| {
147                if delay.ticks <= i64::from(MAX_NORMALIZED_DELAY_MS) * TICKS_PER_MS {
148                    diagnostics.push(Diagnostic::NormalizedDelay {
149                        frame,
150                        declared_ms: delay.ms,
151                    });
152                    i64::from(NORMALIZED_DELAY_MS) * TICKS_PER_MS
153                } else {
154                    delay.ticks
155                }
156            })
157            .collect();
158        ProbeReport {
159            format,
160            width: self.width,
161            height: self.height,
162            timing: Timing::Frames { durations },
163            loop_count: self.loop_count,
164            items: Vec::new(),
165            item: None,
166            color: None,
167            diagnostics,
168        }
169    }
170}
171
172/// Reads an animation's headers without decoding any frame.
173fn index(format: Format, bytes: &[u8]) -> Result<Index, ExtensionError> {
174    let index = match format {
175        Format::Gif => gif_index(bytes)?,
176        Format::Apng => apng_index(bytes)?,
177        Format::Webp => WebpLayout::read(bytes)?.index()?,
178        other => {
179            return Err(ExtensionError::Unsupported(format!(
180                "{other:?} is not an animation"
181            )));
182        }
183    };
184    if index.frames.is_empty() {
185        return Err(ExtensionError::Malformed(
186            "the animation has no frames".into(),
187        ));
188    }
189    Ok(index)
190}
191
192fn gif_index(bytes: &[u8]) -> Result<Index, ExtensionError> {
193    let mut options = gif_options();
194    options.skip_frame_decoding(true);
195    let mut decoder = options.read_info(Cursor::new(bytes)).map_err(malformed)?;
196    let mut index = Index::new(u32::from(decoder.width()), u32::from(decoder.height()))?;
197    while let Some(frame) = decoder.next_frame_info().map_err(malformed)? {
198        let (width, height) = (u32::from(frame.width), u32::from(frame.height));
199        // Hundredths of a second.
200        let delay = Delay {
201            ticks: i64::from(frame.delay) * 10 * TICKS_PER_MS,
202            ms: u32::from(frame.delay) * 10,
203        };
204        index.push(width, height, delay)?;
205    }
206    // The loop extension counts repeats after the first play (0 is forever). Without one, which
207    // the decoder reports as `Finite(0)`, the GIF plays once.
208    index.loop_count = Some(match decoder.repeat() {
209        gif::Repeat::Infinite => 0,
210        gif::Repeat::Finite(count) => u32::from(count) + 1,
211    });
212    Ok(index)
213}
214
215fn apng_index(bytes: &[u8]) -> Result<Index, ExtensionError> {
216    let mut reader = png::Decoder::new(Cursor::new(bytes))
217        .read_info()
218        .map_err(malformed)?;
219    let info = reader.info();
220    let mut index = Index::new(info.width, info.height)?;
221    index.loop_count = info.animation_control.map(|control| control.num_plays);
222    // The default image is a frame when its frame control comes before it.
223    if let Some(control) = info.frame_control {
224        index.push(control.width, control.height, apng_delay(&control))?;
225    }
226    loop {
227        // Skip the image data unread.
228        let control = match reader.next_frame_info() {
229            Ok(control) => *control,
230            Err(png::DecodingError::Parameter(_)) => break,
231            Err(error) => return Err(malformed(error)),
232        };
233        index.push(control.width, control.height, apng_delay(&control))?;
234    }
235    Ok(index)
236}
237
238/// A frame control's delay of `delay_num`/`delay_den` seconds (zero denominator means
239/// hundredths). Denominators dividing 120 000 are exact in ticks; others round to the nearest.
240fn apng_delay(control: &png::FrameControl) -> Delay {
241    let den = if control.delay_den == 0 {
242        100
243    } else {
244        i64::from(control.delay_den)
245    };
246    let num = i64::from(control.delay_num);
247    let rounded = |per_second: i64| (num * per_second + den / 2) / den;
248    Delay {
249        ticks: rounded(TICKS_PER_SECOND),
250        ms: u32::try_from(rounded(1_000)).unwrap_or(u32::MAX),
251    }
252}
253
254#[derive(Clone, Copy)]
255struct Delay {
256    ticks: i64,
257    /// Rounded, for diagnostics.
258    ms: u32,
259}
260
261const TICKS_PER_MS: i64 = TICKS_PER_SECOND / 1_000;
262
263/// An LRU cache of premultiplied canvases within a byte budget.
264struct Kept {
265    /// Canvas and last-use time by frame index.
266    frames: BTreeMap<usize, (Arc<[u8]>, u64)>,
267    by_use: BTreeMap<u64, usize>,
268    clock: u64,
269    frame_bytes: usize,
270    budget: usize,
271}
272
273impl Kept {
274    fn new(frame_bytes: usize, budget: usize) -> Self {
275        Self {
276            frames: BTreeMap::new(),
277            by_use: BTreeMap::new(),
278            clock: 0,
279            frame_bytes,
280            budget,
281        }
282    }
283
284    fn capacity(&self) -> usize {
285        self.budget / self.frame_bytes.max(1)
286    }
287
288    fn bytes(&self) -> usize {
289        self.frames.len() * self.frame_bytes
290    }
291
292    fn contains(&self, index: usize) -> bool {
293        self.frames.contains_key(&index)
294    }
295
296    /// A kept frame, marked as most recently used.
297    fn get(&mut self, index: usize) -> Option<Arc<[u8]>> {
298        self.clock += 1;
299        let (canvas, used) = self.frames.get_mut(&index)?;
300        self.by_use.remove(used);
301        *used = self.clock;
302        self.by_use.insert(self.clock, index);
303        Some(Arc::clone(canvas))
304    }
305
306    /// Keeps a frame, evicting the least recently used when full.
307    fn insert(&mut self, index: usize, canvas: Arc<[u8]>) {
308        if self.capacity() == 0 {
309            return;
310        }
311        if let Some((_, used)) = self.frames.remove(&index) {
312            self.by_use.remove(&used);
313        }
314        while self.frames.len() >= self.capacity() {
315            let Some((_, oldest)) = self.by_use.pop_first() else {
316                break;
317            };
318            self.frames.remove(&oldest);
319        }
320        self.clock += 1;
321        self.frames.insert(index, (canvas, self.clock));
322        self.by_use.insert(self.clock, index);
323    }
324}
325
326/// Decodes every frame once to check the file, keeping the canvases that fit the budget.
327fn decode_whole(
328    format: Format,
329    bytes: &Arc<[u8]>,
330    index: &Index,
331    budget: usize,
332) -> Result<Kept, ExtensionError> {
333    let mut cursor = open_cursor(format, bytes)?;
334    let mut kept = Kept::new(index.width as usize * index.height as usize * 4, budget);
335    for at in 0..index.frames.len() {
336        if !cursor.advance()? {
337            return Err(ExtensionError::Malformed(
338                "the animation ended before a frame it listed".into(),
339            ));
340        }
341        crate::progress::progressed();
342        if at < kept.capacity() {
343            kept.insert(at, premultiplied(cursor.canvas()));
344        }
345    }
346    Ok(kept)
347}
348
349/// What all readers of one open animation share.
350struct Animation {
351    format: Format,
352    bytes: Arc<[u8]>,
353    report: ProbeReport,
354    /// Locked only to look up or keep a frame, never while decoding.
355    frames: Mutex<Kept>,
356}
357
358impl Animation {
359    /// The kept frames. After a reader panics holding the lock, every reader fails, since the
360    /// cache may be half changed.
361    fn kept(&self) -> Result<MutexGuard<'_, Kept>, ExtensionError> {
362        self.frames.lock().map_err(|_| {
363            ExtensionError::Malformed(
364                "another reader of this animation failed while keeping its frames".into(),
365            )
366        })
367    }
368
369    /// Works even after a reader panicked.
370    fn kept_bytes(&self) -> usize {
371        self.frames
372            .lock()
373            .unwrap_or_else(PoisonError::into_inner)
374            .bytes()
375    }
376}
377
378/// One reader of a shared animation, with its own decoder.
379struct AnimatedSource {
380    shared: Arc<Animation>,
381    /// The decoder and the index of the next frame it produces.
382    cursor: Option<(Box<dyn FrameCursor>, usize)>,
383}
384
385impl AnimatedSource {
386    fn open(bytes: Arc<[u8]>, budget: usize) -> Result<Self, ExtensionError> {
387        let format = sniff(&bytes)
388            .ok_or_else(|| ExtensionError::Mismatch("not an animated GIF, WebP, or APNG".into()))?;
389        let index = index(format, &bytes)?;
390        if index.frames.len() < 2 {
391            return Err(ExtensionError::Mismatch(
392                "a still image, which the host's image decoders read".into(),
393            ));
394        }
395        let frames = decode_whole(format, &bytes, &index, budget)?;
396        Ok(Self {
397            shared: Arc::new(Animation {
398                format,
399                bytes,
400                report: index.report(format),
401                frames: Mutex::new(frames),
402            }),
403            cursor: None,
404        })
405    }
406
407    /// A frame's premultiplied canvas. An uncached frame is decoded forward (from the start if
408    /// the decoder is past it), caching the frames just before it so reverse playback rarely
409    /// restarts.
410    fn frame(&mut self, index: usize) -> Result<Arc<[u8]>, ExtensionError> {
411        let shared = Arc::clone(&self.shared);
412        let capacity = {
413            let mut kept = shared.kept()?;
414            if let Some(frame) = kept.get(index) {
415                return Ok(frame);
416            }
417            kept.capacity()
418        };
419        let restart = self.cursor.as_ref().is_none_or(|(_, next)| *next > index);
420        if restart {
421            self.cursor = Some((open_cursor(shared.format, &shared.bytes)?, 0));
422        }
423        let window = (index + 1).saturating_sub(capacity);
424        loop {
425            let (cursor, next) = self.cursor.as_mut().ok_or_else(|| {
426                ExtensionError::Malformed("the animation's decoder is gone".into())
427            })?;
428            if !cursor.advance()? {
429                return Err(ExtensionError::Malformed(
430                    "the animation ended before a frame it listed".into(),
431                ));
432            }
433            crate::progress::progressed();
434            let at = *next;
435            *next += 1;
436            // Every frame on the way is drawn; only those the budget keeps are copied.
437            if at != index && (at < window || shared.kept()?.contains(at)) {
438                continue;
439            }
440            let canvas = premultiplied(cursor.canvas());
441            shared.kept()?.insert(at, Arc::clone(&canvas));
442            if at == index {
443                return Ok(canvas);
444            }
445        }
446    }
447}
448
449impl VisualSource for AnimatedSource {
450    fn report(&self) -> &ProbeReport {
451        &self.shared.report
452    }
453
454    fn render(&mut self, time: MediaTime, _fit: (u32, u32)) -> Result<VisualFrame, ExtensionError> {
455        let (index, start, end) = self.shared.report.timing.frame_at(time);
456        let pixels = self.frame(index)?;
457        Ok(VisualFrame {
458            width: self.shared.report.width,
459            height: self.shared.report.height,
460            pixels: FramePixels::Rgba8(pixels),
461            index,
462            start,
463            end,
464            diagnostics: Vec::new(),
465        })
466    }
467
468    fn resident_bytes(&self) -> usize {
469        let canvas = self.shared.report.width as usize * self.shared.report.height as usize * 4;
470        // The decoder reads the shared file, so it adds only its canvas.
471        self.shared_bytes() + self.cursor.as_ref().map_or(0, |_| canvas)
472    }
473
474    /// A reader with no decoder until it needs an uncached frame.
475    fn reader(&self) -> Option<Box<dyn VisualSource>> {
476        Some(Box::new(Self {
477            shared: Arc::clone(&self.shared),
478            cursor: None,
479        }))
480    }
481
482    fn shared_bytes(&self) -> usize {
483        self.shared.bytes.len() + self.shared.kept_bytes()
484    }
485}
486
487fn premultiplied(canvas: &[u8]) -> Arc<[u8]> {
488    let mut shared = Arc::<[u8]>::from(canvas);
489    if let Some(pixels) = Arc::get_mut(&mut shared) {
490        premultiply(pixels);
491    }
492    shared
493}
494
495trait FrameCursor: Send {
496    /// Draws the next frame; `false` past the last.
497    fn advance(&mut self) -> Result<bool, ExtensionError>;
498    /// The canvas in straight RGBA8 after the last frame drawn.
499    fn canvas(&self) -> &[u8];
500}
501
502/// A decoder at the first frame. It shares the file, so a restart copies nothing.
503fn open_cursor(format: Format, bytes: &Arc<[u8]>) -> Result<Box<dyn FrameCursor>, ExtensionError> {
504    let bytes = Arc::clone(bytes);
505    match format {
506        Format::Gif => Ok(Box::new(GifCursor::new(bytes)?)),
507        Format::Apng => Ok(Box::new(ApngCursor::new(bytes)?)),
508        Format::Webp => Ok(Box::new(WebpCursor::new(bytes)?)),
509        other => Err(ExtensionError::Unsupported(format!(
510            "{other:?} is not an animation"
511        ))),
512    }
513}
514
515/// GIF decoding to RGBA, with frame buffers capped at the largest canvas.
516fn gif_options() -> gif::DecodeOptions {
517    let mut options = gif::DecodeOptions::new();
518    options.set_color_output(gif::ColorOutput::RGBA);
519    options.set_memory_limit(gif::MemoryLimit::Bytes(
520        std::num::NonZeroU64::new(MAX_CANVAS_PIXELS * 4).unwrap_or(std::num::NonZeroU64::MIN),
521    ));
522    options
523}
524
525fn malformed(error: impl std::fmt::Display) -> ExtensionError {
526    ExtensionError::Malformed(error.to_string())
527}
528
529struct GifCursor {
530    decoder: gif::Decoder<Cursor<Arc<[u8]>>>,
531    compositor: Compositor,
532}
533
534impl GifCursor {
535    fn new(bytes: Arc<[u8]>) -> Result<Self, ExtensionError> {
536        let decoder = gif_options()
537            .read_info(Cursor::new(bytes))
538            .map_err(malformed)?;
539        let compositor = Compositor::new(u32::from(decoder.width()), u32::from(decoder.height()))?;
540        Ok(Self {
541            decoder,
542            compositor,
543        })
544    }
545}
546
547impl FrameCursor for GifCursor {
548    fn canvas(&self) -> &[u8] {
549        self.compositor.canvas()
550    }
551
552    fn advance(&mut self) -> Result<bool, ExtensionError> {
553        let Some(frame) = self.decoder.read_next_frame().map_err(malformed)? else {
554            return Ok(false);
555        };
556        let partial = PartialFrame {
557            x: u32::from(frame.left),
558            y: u32::from(frame.top),
559            width: u32::from(frame.width),
560            height: u32::from(frame.height),
561            pixels: frame.buffer.to_vec(),
562            // A transparent index leaves the canvas as it is: GIF draws over.
563            blend: Blend::Over,
564            dispose: match frame.dispose {
565                gif::DisposalMethod::Background => Dispose::Background,
566                gif::DisposalMethod::Previous => Dispose::Previous,
567                _ => Dispose::None,
568            },
569        };
570        self.compositor.draw(&partial)?;
571        Ok(true)
572    }
573}
574
575struct ApngCursor {
576    reader: png::Reader<Cursor<Arc<[u8]>>>,
577    compositor: Compositor,
578    /// The default image is not a frame and has not been skipped yet.
579    skip_default: bool,
580    first: bool,
581    buffer: Vec<u8>,
582}
583
584impl ApngCursor {
585    fn new(bytes: Arc<[u8]>) -> Result<Self, ExtensionError> {
586        let mut decoder = png::Decoder::new(Cursor::new(bytes));
587        decoder.set_transformations(
588            png::Transformations::EXPAND
589                | png::Transformations::STRIP_16
590                | png::Transformations::ALPHA,
591        );
592        let reader = decoder.read_info().map_err(malformed)?;
593        let info = reader.info();
594        let compositor = Compositor::new(info.width, info.height)?;
595        let skip_default = info.frame_control.is_none();
596        let size = reader
597            .output_buffer_size()
598            .ok_or_else(|| ExtensionError::Budget("the PNG is too large".into()))?;
599        Ok(Self {
600            reader,
601            compositor,
602            skip_default,
603            first: true,
604            buffer: vec![0; size],
605        })
606    }
607}
608
609impl FrameCursor for ApngCursor {
610    fn canvas(&self) -> &[u8] {
611        self.compositor.canvas()
612    }
613
614    fn advance(&mut self) -> Result<bool, ExtensionError> {
615        loop {
616            let output = match self.reader.next_frame(&mut self.buffer) {
617                Ok(output) => output,
618                Err(png::DecodingError::Parameter(_)) => return Ok(false),
619                Err(error) => return Err(malformed(error)),
620            };
621            if std::mem::take(&mut self.skip_default) {
622                continue;
623            }
624            let control = self.reader.info().frame_control.ok_or_else(|| {
625                ExtensionError::Malformed("an APNG frame has no frame control".into())
626            })?;
627            let pixels = crate::raster::to_rgba8(
628                &self.buffer[..output.buffer_size()],
629                output.color_type,
630                output.width,
631                output.height,
632                output.line_size,
633            )?;
634            let first = std::mem::take(&mut self.first);
635            let partial = PartialFrame {
636                x: control.x_offset,
637                y: control.y_offset,
638                width: control.width,
639                height: control.height,
640                pixels,
641                blend: match control.blend_op {
642                    png::BlendOp::Over => Blend::Over,
643                    png::BlendOp::Source => Blend::Source,
644                },
645                dispose: match control.dispose_op {
646                    png::DisposeOp::None => Dispose::None,
647                    png::DisposeOp::Background => Dispose::Background,
648                    // The first frame has nothing before it to return to.
649                    png::DisposeOp::Previous if first => Dispose::Background,
650                    png::DisposeOp::Previous => Dispose::Previous,
651                },
652            };
653            self.compositor.draw(&partial)?;
654            return Ok(true);
655        }
656    }
657}
658
659/// An animated WebP composited as libwebp does; `image-webp` decodes each frame's picture.
660struct WebpCursor {
661    bytes: Arc<[u8]>,
662    frames: Vec<WebpFrame>,
663    next: usize,
664    compositor: Compositor,
665}
666
667struct WebpLayout {
668    width: u32,
669    height: u32,
670    /// Plays, 0 for forever.
671    loop_count: Option<u32>,
672    frames: Vec<WebpFrame>,
673}
674
675/// One `ANMF` chunk.
676struct WebpFrame {
677    x: u32,
678    y: u32,
679    width: u32,
680    height: u32,
681    duration_ms: u32,
682    blend: Blend,
683    dispose: Dispose,
684    data: std::ops::Range<usize>,
685}
686
687fn riff_chunks(bytes: &[u8], mut at: usize, end: usize) -> Vec<([u8; 4], std::ops::Range<usize>)> {
688    let mut chunks = Vec::new();
689    while at + 8 <= end {
690        let kind = [bytes[at], bytes[at + 1], bytes[at + 2], bytes[at + 3]];
691        let size = u32::from_le_bytes([bytes[at + 4], bytes[at + 5], bytes[at + 6], bytes[at + 7]])
692            as usize;
693        let start = at + 8;
694        let Some(stop) = start.checked_add(size).filter(|stop| *stop <= end) else {
695            break;
696        };
697        chunks.push((kind, start..stop));
698        at = stop + (size & 1);
699    }
700    chunks
701}
702
703fn le24(bytes: &[u8]) -> u32 {
704    u32::from(bytes[0]) | u32::from(bytes[1]) << 8 | u32::from(bytes[2]) << 16
705}
706
707impl WebpLayout {
708    fn read(bytes: &[u8]) -> Result<Self, ExtensionError> {
709        let end = bytes.len();
710        let chunks = riff_chunks(bytes, 12, end);
711        let header = chunks
712            .iter()
713            .find(|(kind, _)| kind == b"VP8X")
714            .filter(|(_, range)| range.len() >= 10)
715            .ok_or_else(|| ExtensionError::Malformed("the WebP has no extended header".into()))?;
716        let width = le24(&bytes[header.1.start + 4..]) + 1;
717        let height = le24(&bytes[header.1.start + 7..]) + 1;
718        let loop_count = chunks
719            .iter()
720            .find(|(kind, range)| kind == b"ANIM" && range.len() >= 6)
721            .map(|(_, range)| {
722                u32::from(u16::from_le_bytes([
723                    bytes[range.start + 4],
724                    bytes[range.start + 5],
725                ]))
726            });
727        let frames = chunks
728            .iter()
729            .filter(|(kind, range)| kind == b"ANMF" && range.len() >= 16)
730            .map(|(_, range)| {
731                let at = range.start;
732                let flags = bytes[at + 15];
733                WebpFrame {
734                    x: le24(&bytes[at..]) * 2,
735                    y: le24(&bytes[at + 3..]) * 2,
736                    width: le24(&bytes[at + 6..]) + 1,
737                    height: le24(&bytes[at + 9..]) + 1,
738                    duration_ms: le24(&bytes[at + 12..]),
739                    blend: if flags & 0x02 == 0 {
740                        Blend::OverWebp
741                    } else {
742                        Blend::Source
743                    },
744                    dispose: if flags & 0x01 == 0 {
745                        Dispose::None
746                    } else {
747                        Dispose::Background
748                    },
749                    data: at + 16..range.end,
750                }
751            })
752            .collect();
753        Ok(Self {
754            width,
755            height,
756            loop_count,
757            frames,
758        })
759    }
760
761    /// Every frame must lie within the canvas (RFC 9649).
762    fn index(&self) -> Result<Index, ExtensionError> {
763        let mut index = Index::new(self.width, self.height)?;
764        index.loop_count = self.loop_count;
765        for frame in &self.frames {
766            if frame.x + frame.width > self.width || frame.y + frame.height > self.height {
767                return Err(ExtensionError::Malformed(format!(
768                    "a {}x{} frame at ({}, {}) lies outside the {}x{} canvas",
769                    frame.width, frame.height, frame.x, frame.y, self.width, self.height
770                )));
771            }
772            let delay = Delay {
773                ticks: i64::from(frame.duration_ms) * TICKS_PER_MS,
774                ms: frame.duration_ms,
775            };
776            index.push(frame.width, frame.height, delay)?;
777        }
778        Ok(index)
779    }
780}
781
782impl WebpCursor {
783    fn new(bytes: Arc<[u8]>) -> Result<Self, ExtensionError> {
784        let layout = WebpLayout::read(&bytes)?;
785        let compositor = Compositor::new(layout.width, layout.height)?;
786        Ok(Self {
787            bytes,
788            frames: layout.frames,
789            next: 0,
790            compositor,
791        })
792    }
793
794    /// Decodes a frame's picture, rewrapped as a still WebP, to straight RGBA8.
795    fn picture(&self, frame: &WebpFrame) -> Result<Vec<u8>, ExtensionError> {
796        let chunks = riff_chunks(&self.bytes, frame.data.start, frame.data.end);
797        let wanted = |kind: &[u8; 4]| chunks.iter().find(|(chunk, _)| chunk == kind);
798        let alpha = wanted(b"ALPH");
799        let lossy = wanted(b"VP8 ");
800        let lossless = wanted(b"VP8L");
801        let mut body = Vec::new();
802        let mut push = |kind: &[u8; 4], payload: &[u8]| {
803            body.extend_from_slice(kind);
804            body.extend_from_slice(
805                &u32::try_from(payload.len())
806                    .unwrap_or(u32::MAX)
807                    .to_le_bytes(),
808            );
809            body.extend_from_slice(payload);
810            if payload.len() % 2 == 1 {
811                body.push(0);
812            }
813        };
814        match (lossless, lossy) {
815            (Some((_, range)), _) => push(b"VP8L", &self.bytes[range.clone()]),
816            (None, Some((_, range))) => {
817                // A lossy picture with an alpha plane needs an extended header saying so.
818                let mut header = vec![0_u8; 10];
819                if alpha.is_some() {
820                    header[0] = 0x10;
821                }
822                header[4..7].copy_from_slice(&(frame.width - 1).to_le_bytes()[..3]);
823                header[7..10].copy_from_slice(&(frame.height - 1).to_le_bytes()[..3]);
824                push(b"VP8X", &header);
825                if let Some((_, range)) = alpha {
826                    push(b"ALPH", &self.bytes[range.clone()]);
827                }
828                push(b"VP8 ", &self.bytes[range.clone()]);
829            }
830            (None, None) => {
831                return Err(ExtensionError::Malformed(
832                    "a WebP frame has no picture".into(),
833                ));
834            }
835        }
836        let mut file = b"RIFF".to_vec();
837        file.extend_from_slice(
838            &u32::try_from(body.len() + 4)
839                .unwrap_or(u32::MAX)
840                .to_le_bytes(),
841        );
842        file.extend_from_slice(b"WEBP");
843        file.extend_from_slice(&body);
844        let mut decoder = image_webp::WebPDecoder::new(Cursor::new(file)).map_err(malformed)?;
845        // A lossless bitstream carries its own size, which must match the frame rectangle.
846        if decoder.dimensions() != (frame.width, frame.height) {
847            let (width, height) = decoder.dimensions();
848            return Err(ExtensionError::Malformed(format!(
849                "a frame declares {}x{} and its picture is {width}x{height}",
850                frame.width, frame.height
851            )));
852        }
853        let mut buffer =
854            vec![
855                0;
856                decoder
857                    .output_buffer_size()
858                    .ok_or_else(|| ExtensionError::Budget("a WebP frame is too large".into()))?
859            ];
860        decoder.read_image(&mut buffer).map_err(malformed)?;
861        Ok(if decoder.has_alpha() {
862            buffer
863        } else {
864            buffer
865                .as_chunks::<3>()
866                .0
867                .iter()
868                .flat_map(|[red, green, blue]| [*red, *green, *blue, 255])
869                .collect()
870        })
871    }
872}
873
874impl FrameCursor for WebpCursor {
875    fn canvas(&self) -> &[u8] {
876        self.compositor.canvas()
877    }
878
879    fn advance(&mut self) -> Result<bool, ExtensionError> {
880        let Some(frame) = self.frames.get(self.next) else {
881            return Ok(false);
882        };
883        let partial = PartialFrame {
884            x: frame.x,
885            y: frame.y,
886            width: frame.width,
887            height: frame.height,
888            pixels: self.picture(frame)?,
889            blend: frame.blend,
890            dispose: frame.dispose,
891        };
892        self.next += 1;
893        self.compositor.draw(&partial)?;
894        Ok(true)
895    }
896}
897
898#[cfg(test)]
899mod tests;