Skip to main content

alpha2_extensions/lottie/
mod.rs

1//! Lottie JSON and dotLottie, evaluated by velato and rasterized with tiny-skia at the shown size.
2//!
3//! An animation is evaluated at whole frames. velato only reads the document [`normalize`]
4//! produces, which reports unsupported features and refuses input that would panic or recurse or
5//! expand without bound.
6
7mod device;
8mod normalize;
9
10use std::cell::{Cell, RefCell};
11use std::collections::HashMap;
12use std::io::{Cursor, Read, Seek, SeekFrom};
13use std::rc::Rc;
14use std::sync::Arc;
15
16use alpha2_time::{FrameRate, MediaTime};
17use base64::Engine as _;
18use kurbo::{Affine, PathEl, Shape};
19use peniko::{BlendMode as PenikoBlend, Brush, Compose, Extend, GradientKind, Mix};
20use resvg::tiny_skia::{
21    self, BlendMode, Color, FillRule, GradientStop, IntRect, IntSize, LineCap, LineJoin,
22    LinearGradient, Mask, Paint, PathBuilder, PathStroker, Pixmap, PixmapPaint, Point,
23    RadialGradient, Shader, SpreadMode, Stroke, StrokeDash, SweepGradient, Transform,
24};
25use serde_json::Value;
26use velato::model::ImageAsset;
27use velato::{Composition, RenderSink, Renderer};
28
29use alpha2_model::{MAX_LOTTIE_DOCUMENT_BYTES, ProviderSource};
30
31use crate::api::{
32    Diagnostic, ExtensionError, Format, FramePixels, ProbeReport, ResourceResolver, Timing,
33    VisualFrame, VisualProvider, VisualSource,
34};
35use crate::budget::{check_canvas, check_document_size, check_image_pixels};
36
37/// Most frames an animation may span.
38const MAX_LOTTIE_FRAMES: f64 = 100_000.0;
39/// Most bytes a dotLottie package unpacks to, all files together. Each JSON file is also held to
40/// [`MAX_LOTTIE_DOCUMENT_BYTES`].
41const MAX_LOTTIE_BYTES: u64 = 256 * 1024 * 1024;
42/// Most files a dotLottie package holds.
43const MAX_DOTLOTTIE_FILES: usize = 1_024;
44/// Most bytes of a dotLottie central directory: a kibibyte per allowed file.
45const MAX_DOTLOTTIE_DIRECTORY_BYTES: u64 = 1_024 * 1_024;
46
47/// Reads Lottie JSON and dotLottie packages.
48pub struct LottieProvider;
49
50impl VisualProvider for LottieProvider {
51    fn name(&self) -> &'static str {
52        "lottie"
53    }
54
55    fn probe(&self, bytes: &[u8]) -> Option<Result<ProbeReport, ExtensionError>> {
56        let size = check_document_size(
57            &ProviderSource::Lottie { animation: None },
58            bytes,
59            bytes.len() as u64,
60        );
61        if is_zip(bytes) {
62            return Some(
63                size.and_then(|()| Package::read(bytes))
64                    .and_then(|package| package.probe()),
65            );
66        }
67        if is_json_object(bytes)
68            && let Err(error) = size
69        {
70            return Some(Err(error));
71        }
72        let json = parse_lottie(bytes)?;
73        Some(inspect(json, Format::Lottie).map(|(report, _)| report))
74    }
75
76    fn open(
77        &self,
78        bytes: Arc<[u8]>,
79        source: &ProviderSource,
80        resolver: &dyn ResourceResolver,
81    ) -> Result<Box<dyn VisualSource>, ExtensionError> {
82        Ok(Box::new(LottieSource::open(&bytes, source, resolver)?))
83    }
84}
85
86impl LottieSource {
87    fn open(
88        bytes: &[u8],
89        source: &ProviderSource,
90        resolver: &dyn ResourceResolver,
91    ) -> Result<Self, ExtensionError> {
92        let item = match source {
93            ProviderSource::Lottie { animation } => animation.as_deref(),
94            _ => return Err(ExtensionError::Mismatch("not a Lottie source".into())),
95        };
96        check_document_size(source, bytes, bytes.len() as u64)?;
97        let (json, package, format) = if is_zip(bytes) {
98            let package = Package::read(bytes)?;
99            (package.animation(item)?, Some(package), Format::DotLottie)
100        } else {
101            if item.is_some() {
102                return Err(ExtensionError::Mismatch(
103                    "a Lottie JSON file holds one animation".into(),
104                ));
105            }
106            let json = parse_lottie(bytes)
107                .ok_or_else(|| ExtensionError::Mismatch("not a Lottie animation".into()))?;
108            (json, None, Format::Lottie)
109        };
110        let (mut report, sanitized) = inspect(json, format)?;
111        if let Some(package) = &package {
112            report.items.clone_from(&package.ids);
113            report.item = Some(item.unwrap_or(&package.ids[0]).to_owned());
114        }
115        // The parsed document is many times the file size, so drop it before velato parses.
116        let text = serde_json::to_vec(&sanitized)
117            .map_err(|error| ExtensionError::Malformed(error.to_string()))?;
118        drop(sanitized);
119        let composition = Composition::from_slice(&text)
120            .map_err(|error| ExtensionError::Malformed(format!("{error:?}")))?;
121        drop(text);
122        // Check decoded asset size from headers first; oversized assets are reported missing.
123        let assets = composition
124            .images
125            .iter()
126            .map(|(id, asset)| Ok((id, asset, image_bytes(asset, package.as_ref(), resolver)?)))
127            .collect::<Result<Vec<_>, ExtensionError>>()?;
128        check_image_pixels(
129            assets
130                .iter()
131                .filter_map(|(_, _, bytes)| crate::raster::png_size(bytes.as_deref()?))
132                .filter(|(width, height)| check_canvas(*width, *height).is_ok())
133                .map(|(width, height)| u64::from(width) * u64::from(height))
134                .fold(0, u64::saturating_add),
135        )?;
136        let mut images = HashMap::new();
137        for (id, asset, bytes) in assets {
138            match bytes.and_then(|bytes| decode_image(&bytes)) {
139                Some(pixmap) => {
140                    images.insert(id.clone(), pixmap);
141                }
142                None => report.diagnostics.push(Diagnostic::MissingImage {
143                    href: format!(
144                        "{}{}",
145                        asset.directory.clone().unwrap_or_default(),
146                        short(&asset.file_name)
147                    ),
148                }),
149            }
150        }
151        Ok(Self {
152            composition,
153            renderer: Renderer::new(),
154            images,
155            report,
156            last: None,
157        })
158    }
159}
160
161fn is_zip(bytes: &[u8]) -> bool {
162    bytes.starts_with(b"PK\x03\x04")
163}
164
165fn is_json_object(bytes: &[u8]) -> bool {
166    bytes.iter().find(|byte| !byte.is_ascii_whitespace()) == Some(&b'{')
167}
168
169/// A Lottie document: a JSON root with canvas, rate, frame span, and layers.
170fn parse_lottie(bytes: &[u8]) -> Option<Value> {
171    if !is_json_object(bytes) {
172        return None;
173    }
174    let json: Value = serde_json::from_slice(bytes).ok()?;
175    let root = json.as_object()?;
176    ["w", "h", "fr", "ip", "op"]
177        .iter()
178        .all(|key| root.get(*key).is_some_and(Value::is_number))
179        .then_some(())
180        .filter(|()| root.get("layers").is_some_and(Value::is_array))
181        .map(|()| json)
182}
183
184/// Refuses, from the end record, a central directory with too many files or bytes before the ZIP
185/// reader indexes it (an archive of empty files indexes to several times its size).
186///
187/// Reads the same end record (and ZIP64 record) the ZIP reader starts from. If the reader falls
188/// back to an earlier record, the file count is still checked after reading.
189fn check_directory(bytes: &[u8]) -> Result<(), ExtensionError> {
190    const END: &[u8] = b"PK\x05\x06";
191    const END64_LOCATOR: &[u8] = b"PK\x06\x07";
192    const END64: &[u8] = b"PK\x06\x06";
193    let malformed = |what: &str| ExtensionError::Malformed(format!("dotLottie: {what}"));
194    let field = |at: usize, size: usize| {
195        bytes.get(at..at + size).map(|field| {
196            field
197                .iter()
198                .rev()
199                .fold(0_u64, |value, byte| value << 8 | u64::from(*byte))
200        })
201    };
202    let from = bytes.len().saturating_sub(22 + usize::from(u16::MAX));
203    let end = (from..bytes.len().saturating_sub(21))
204        .rev()
205        .find(|&at| {
206            bytes[at..].starts_with(END)
207                && field(at + 20, 2)
208                    .is_some_and(|comment| at as u64 + 22 + comment <= bytes.len() as u64)
209        })
210        .ok_or_else(|| malformed("no end of central directory record"))?;
211    let (mut files, mut size) = (field(end + 10, 2), field(end + 12, 4));
212    let zip64 =
213        files == Some(u64::from(u16::MAX)) || field(end + 16, 4) == Some(u64::from(u32::MAX));
214    if zip64
215        && let Some(locator) = end.checked_sub(20)
216        && bytes[locator..].starts_with(END64_LOCATOR)
217    {
218        let at = field(locator + 8, 8)
219            .and_then(|at| usize::try_from(at).ok())
220            .filter(|&at| at < locator)
221            .and_then(|start| {
222                bytes[start..locator]
223                    .windows(END64.len())
224                    .position(|window| window == END64)
225                    .map(|found| start + found)
226            })
227            .ok_or_else(|| malformed("no ZIP64 end of central directory record"))?;
228        (files, size) = (field(at + 32, 8), field(at + 40, 8));
229    }
230    let (Some(files), Some(size)) = (files, size) else {
231        return Err(malformed("the end of central directory record is cut off"));
232    };
233    if files > MAX_DOTLOTTIE_FILES as u64 {
234        return Err(ExtensionError::Budget(format!(
235            "the dotLottie package holds more than {MAX_DOTLOTTIE_FILES} files"
236        )));
237    }
238    if size > MAX_DOTLOTTIE_DIRECTORY_BYTES {
239        return Err(ExtensionError::Budget(format!(
240            "the dotLottie package's central directory takes more than \
241             {MAX_DOTLOTTIE_DIRECTORY_BYTES} bytes"
242        )));
243    }
244    Ok(())
245}
246
247/// Extra bytes, beyond twice the package, the ZIP reader may read while finding the directory.
248const MAX_DIRECTORY_SEARCH: u64 = 4 * 1_024 * 1_024;
249
250/// A package's bytes with a read budget, so the ZIP reader's record search stays linear
251/// whatever its strategy. A valid package needs one pass; running out ends the search.
252struct Metered<'a> {
253    bytes: Cursor<&'a [u8]>,
254    left: Rc<Cell<u64>>,
255}
256
257impl Read for Metered<'_> {
258    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
259        let left = self.left.get();
260        if left == 0 {
261            return Err(std::io::Error::other("the search for a directory is over"));
262        }
263        let take = usize::try_from(left).map_or(buf.len(), |left| left.min(buf.len()));
264        let read = self.bytes.read(&mut buf[..take])?;
265        // Charge empty reads too, so the search cannot loop for free.
266        self.left.set(left.saturating_sub((read as u64).max(1)));
267        Ok(read)
268    }
269}
270
271impl Seek for Metered<'_> {
272    fn seek(&mut self, to: SeekFrom) -> std::io::Result<u64> {
273        self.bytes.seek(to)
274    }
275}
276
277/// A dotLottie package. Files are unpacked only when read (manifest, the shown animation, and
278/// its images).
279struct Package<'a> {
280    ids: Vec<String>,
281    archive: RefCell<zip::ZipArchive<Metered<'a>>>,
282    /// Archive index by file name without a leading `/`.
283    names: HashMap<String, usize>,
284    /// Bytes unpacked so far, all files together.
285    unpacked: Cell<u64>,
286}
287
288impl<'a> Package<'a> {
289    fn read(bytes: &'a [u8]) -> Result<Self, ExtensionError> {
290        check_directory(bytes)?;
291        let left = Rc::new(Cell::new(
292            MAX_DIRECTORY_SEARCH.saturating_add((bytes.len() as u64).saturating_mul(2)),
293        ));
294        let metered = Metered {
295            bytes: Cursor::new(bytes),
296            left: Rc::clone(&left),
297        };
298        let archive = zip::ZipArchive::new(metered).map_err(|error| {
299            if left.get() == 0 {
300                ExtensionError::Malformed(
301                    "dotLottie: no end of central directory record describes a directory".into(),
302                )
303            } else {
304                ExtensionError::Malformed(format!("dotLottie: {error}"))
305            }
306        })?;
307        // File reads are budgeted separately in `Self::file`.
308        left.set(u64::MAX);
309        if archive.len() > MAX_DOTLOTTIE_FILES {
310            return Err(ExtensionError::Budget(format!(
311                "the dotLottie package holds more than {MAX_DOTLOTTIE_FILES} files"
312            )));
313        }
314        let mut names = HashMap::new();
315        for (index, name) in archive.file_names().enumerate() {
316            let name =
317                name.map_err(|error| ExtensionError::Malformed(format!("dotLottie: {error}")))?;
318            if !name.ends_with('/') {
319                names.insert(name.trim_start_matches('/').to_owned(), index);
320            }
321        }
322        let package = Self {
323            ids: Vec::new(),
324            archive: RefCell::new(archive),
325            names,
326            unpacked: Cell::new(0),
327        };
328        let manifest: Value = serde_json::from_slice(
329            &package
330                .file("manifest.json", Some(MAX_LOTTIE_DOCUMENT_BYTES))?
331                .ok_or_else(|| ExtensionError::Malformed("dotLottie: no manifest.json".into()))?,
332        )
333        .map_err(|error| ExtensionError::Malformed(format!("dotLottie: {error}")))?;
334        let ids = manifest
335            .get("animations")
336            .and_then(Value::as_array)
337            .map(|animations| {
338                animations
339                    .iter()
340                    .filter_map(|animation| animation.get("id")?.as_str().map(str::to_owned))
341                    .collect::<Vec<_>>()
342            })
343            .unwrap_or_default();
344        if ids.is_empty() {
345            return Err(ExtensionError::Malformed(
346                "dotLottie: the manifest lists no animation".into(),
347            ));
348        }
349        Ok(Self { ids, ..package })
350    }
351
352    /// A file's unpacked bytes, or `None` if absent. All reads share one budget, and a JSON
353    /// document is also held to `document` bytes.
354    ///
355    /// Declared sizes are only trusted to refuse early; budgets count actual unpacked bytes. A
356    /// file that unpacks past its declared size is malformed.
357    fn file(&self, name: &str, document: Option<usize>) -> Result<Option<Vec<u8>>, ExtensionError> {
358        let Some(&index) = self.names.get(name) else {
359            return Ok(None);
360        };
361        let malformed = |error: &dyn std::fmt::Display| {
362            ExtensionError::Malformed(format!("dotLottie: {error}"))
363        };
364        let total = self.unpacked.get();
365        let left = MAX_LOTTIE_BYTES - total;
366        let (within, too_large) = match document {
367            Some(most) if (most as u64) < left => (
368                most as u64,
369                format!(
370                    "the dotLottie package's {name} unpacks to more than the {most} bytes a \
371                     provider reads"
372                ),
373            ),
374            _ => (left, "the dotLottie package unpacks past 256 MB".to_owned()),
375        };
376        let too_large = || ExtensionError::Budget(too_large.clone());
377        let mut archive = self.archive.borrow_mut();
378        let mut file = archive.by_index(index).map_err(|error| malformed(&error))?;
379        if file.size() > within {
380            return Err(too_large());
381        }
382        let mut contents = Vec::new();
383        let read = file
384            .by_ref()
385            .take(within + 1)
386            .read_to_end(&mut contents)
387            .map_err(|error| malformed(&error))? as u64;
388        if read > within {
389            return Err(too_large());
390        }
391        self.unpacked.set(total + read);
392        Ok(Some(contents))
393    }
394
395    /// An animation's JSON, under `a/` (version 2) or `animations/` (version 1).
396    fn animation(&self, id: Option<&str>) -> Result<Value, ExtensionError> {
397        let id = match id {
398            Some(id) if self.ids.iter().any(|known| known == id) => id,
399            Some(id) => {
400                return Err(ExtensionError::Mismatch(format!(
401                    "the dotLottie package has no animation {id}"
402                )));
403            }
404            None => &self.ids[0],
405        };
406        let bytes = self
407            .first_file(
408                &[format!("a/{id}.json"), format!("animations/{id}.json")],
409                Some(MAX_LOTTIE_DOCUMENT_BYTES),
410            )?
411            .ok_or_else(|| {
412                ExtensionError::Malformed(format!("dotLottie: animation {id} has no file"))
413            })?;
414        parse_lottie(&bytes).ok_or_else(|| {
415            ExtensionError::Malformed(format!("dotLottie: animation {id} is not Lottie"))
416        })
417    }
418
419    /// Describes the package by its first animation that opens, reporting earlier ones that do
420    /// not. Fails with the first error when none opens.
421    fn probe(&self) -> Result<ProbeReport, ExtensionError> {
422        let mut unreadable = Vec::new();
423        let mut first = None;
424        for id in &self.ids {
425            match self
426                .animation(Some(id))
427                .and_then(|json| inspect(json, Format::DotLottie))
428            {
429                Ok((report, _)) => {
430                    unreadable.extend(report.diagnostics);
431                    return Ok(ProbeReport {
432                        items: self.ids.clone(),
433                        item: Some(id.clone()),
434                        diagnostics: unreadable,
435                        ..report
436                    });
437                }
438                Err(error) => {
439                    unreadable.push(Diagnostic::UnreadableItem {
440                        item: id.clone(),
441                        reason: error.to_string(),
442                    });
443                    first.get_or_insert(error);
444                }
445            }
446        }
447        Err(first.unwrap_or_else(|| {
448            ExtensionError::Malformed("dotLottie: the manifest lists no animation".into())
449        }))
450    }
451
452    /// An image by its path, or under `i/` (version 2) or `images/` (version 1).
453    fn image(&self, name: &str) -> Result<Option<Vec<u8>>, ExtensionError> {
454        let name = name.trim_start_matches('/');
455        self.first_file(
456            &[
457                name.to_owned(),
458                format!("i/{name}"),
459                format!("images/{name}"),
460            ],
461            None,
462        )
463    }
464
465    /// The first of `paths` the package holds, unpacked by [`Self::file`].
466    fn first_file(
467        &self,
468        paths: &[String],
469        document: Option<usize>,
470    ) -> Result<Option<Vec<u8>>, ExtensionError> {
471        for path in paths {
472            if let Some(bytes) = self.file(path, document)? {
473                return Ok(Some(bytes));
474            }
475        }
476        Ok(None)
477    }
478}
479
480/// The animation's report and its normalized JSON.
481fn inspect(json: Value, format: Format) -> Result<(ProbeReport, Value), ExtensionError> {
482    let root = json
483        .as_object()
484        .ok_or_else(|| ExtensionError::Malformed("the animation is not an object".into()))?;
485    let number = |key: &str| root.get(key).and_then(Value::as_f64).unwrap_or(0.0);
486    let (width, height) = (number("w"), number("h"));
487    let (rate, first, last) = (number("fr"), number("ip"), number("op"));
488    if !(width >= 1.0 && height >= 1.0 && rate > 0.0 && last > first)
489        || last - first > MAX_LOTTIE_FRAMES
490    {
491        return Err(ExtensionError::Malformed(
492            "the animation has no canvas, rate, or frames".into(),
493        ));
494    }
495    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
496    let (width, height, frames) = (
497        width.round() as u32,
498        height.round() as u32,
499        (last - first).ceil() as usize,
500    );
501    check_canvas(width, height)?;
502    let (diagnostics, sanitized) = normalize::normalize(json)?;
503    Ok((
504        ProbeReport {
505            format,
506            width,
507            height,
508            timing: Timing::Rate {
509                rate: rational_rate(rate).ok_or_else(|| {
510                    ExtensionError::Malformed(format!("the frame rate {rate} is not usable"))
511                })?,
512                frames,
513            },
514            loop_count: None,
515            items: Vec::new(),
516            item: None,
517            color: None,
518            diagnostics,
519        },
520        sanitized,
521    ))
522}
523
524/// A Lottie rate as a rational: NTSC and whole rates exactly, others to a thousandth.
525fn rational_rate(rate: f64) -> Option<FrameRate> {
526    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
527    let (num, den) = [24_u32, 30, 48, 60, 120]
528        .into_iter()
529        .find(|base| (rate - f64::from(*base) * 1_000.0 / 1_001.0).abs() < 0.005)
530        .map(|base| (base * 1_000, 1_001))
531        .or_else(|| ((rate - rate.round()).abs() < 0.005).then(|| (rate.round() as u32, 1)))
532        .unwrap_or_else(|| ((rate * 1_000.0).round() as u32, 1_000));
533    FrameRate::new(num, den).ok()
534}
535
536/// An image asset's bytes from a data URL, package file, or resource. A package file that fails
537/// to unpack fails the package.
538fn image_bytes(
539    asset: &ImageAsset,
540    package: Option<&Package>,
541    resolver: &dyn ResourceResolver,
542) -> Result<Option<Vec<u8>>, ExtensionError> {
543    if let Some(data) = asset.file_name.strip_prefix("data:") {
544        return Ok(data.split_once(";base64,").and_then(|(_, encoded)| {
545            base64::engine::general_purpose::STANDARD
546                .decode(encoded)
547                .ok()
548        }));
549    }
550    let name = format!(
551        "{}{}",
552        asset.directory.clone().unwrap_or_default(),
553        asset.file_name
554    );
555    if let Some(package) = package {
556        for candidate in [&name, &asset.file_name] {
557            if let Some(bytes) = package.image(candidate)? {
558                return Ok(Some(bytes));
559            }
560        }
561    }
562    Ok(resolver.bytes(&name).ok().map(|bytes| bytes.to_vec()))
563}
564
565/// A PNG image asset as a premultiplied pixmap; other formats are reported missing.
566fn decode_image(bytes: &[u8]) -> Option<Pixmap> {
567    let (width, height, mut pixels) = crate::raster::decode_png(bytes).ok()?;
568    crate::api::premultiply(&mut pixels);
569    Pixmap::from_vec(pixels, IntSize::from_wh(width, height)?)
570}
571
572fn short(name: &str) -> String {
573    if name.starts_with("data:") {
574        "an embedded image".into()
575    } else {
576        name.to_owned()
577    }
578}
579
580/// An open Lottie animation; PNG assets are decoded once at open.
581struct LottieSource {
582    composition: Composition,
583    renderer: Renderer,
584    images: HashMap<String, Pixmap>,
585    report: ProbeReport,
586    last: Option<VisualFrame>,
587}
588
589impl VisualSource for LottieSource {
590    fn report(&self) -> &ProbeReport {
591        &self.report
592    }
593
594    fn render(&mut self, time: MediaTime, fit: (u32, u32)) -> Result<VisualFrame, ExtensionError> {
595        let (index, start, end) = self.report.timing.frame_at(time);
596        let (width, height) = fitted(self.report.width, self.report.height, fit);
597        if let Some(last) = self
598            .last
599            .as_ref()
600            .filter(|last| last.index == index && (last.width, last.height) == (width, height))
601        {
602            return Ok(last.clone());
603        }
604        let mut sink = SkiaSink::new(width, height, &self.images)?;
605        #[allow(clippy::cast_precision_loss)]
606        let frame = self.composition.frames.start + index as f64;
607        let transform = Affine::scale_non_uniform(
608            f64::from(width) / f64::from(self.report.width),
609            f64::from(height) / f64::from(self.report.height),
610        );
611        self.renderer
612            .append(&self.composition, frame, transform, 1.0, &mut sink);
613        let frame = VisualFrame {
614            width,
615            height,
616            pixels: FramePixels::Rgba8(sink.finish().into()),
617            index,
618            start,
619            end,
620            diagnostics: Vec::new(),
621        };
622        self.last = Some(frame.clone());
623        Ok(frame)
624    }
625
626    fn resident_bytes(&self) -> usize {
627        self.images
628            .values()
629            .map(|image| image.data().len())
630            .sum::<usize>()
631            + self.last.as_ref().map_or(0, |last| last.pixels.byte_len())
632    }
633}
634
635/// The largest whole-pixel canvas size that fits in `fit` keeping aspect; the canvas if empty.
636fn fitted(width: u32, height: u32, fit: (u32, u32)) -> (u32, u32) {
637    if fit.0 == 0 || fit.1 == 0 {
638        return (width, height);
639    }
640    let scale = (f64::from(fit.0) / f64::from(width)).min(f64::from(fit.1) / f64::from(height));
641    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
642    (
643        (f64::from(width) * scale)
644            .round()
645            .clamp(1.0, f64::from(fit.0)) as u32,
646        (f64::from(height) * scale)
647            .round()
648            .clamp(1.0, f64::from(fit.1)) as u32,
649    )
650}
651
652/// Draws velato's scene with tiny-skia; layers are pixmaps composited on pop.
653///
654/// A layer is composited only within its clip and, for normal blending, only where it was drawn
655/// on, so masks and mattes cost what they cover. An unclipped, opaque, normal layer pushed onto
656/// an empty layer (velato's per-frame canvas clip) is drawn straight onto it.
657struct SkiaSink<'a> {
658    width: u32,
659    height: u32,
660    layers: Vec<Layer>,
661    images: &'a HashMap<String, Pixmap>,
662    /// An all-255 mask for a clip covering the canvas, built once a frame.
663    covering: Option<Rc<Mask>>,
664    /// Cleared pixmaps of popped layers, for reuse.
665    pool: Vec<Pixmap>,
666    #[cfg(test)]
667    whole: bool,
668    #[cfg(test)]
669    composited: u64,
670    #[cfg(test)]
671    allocated: usize,
672}
673
674struct Layer {
675    /// `None` for a layer drawn straight onto the one below.
676    pixmap: Option<Pixmap>,
677    blend: BlendMode,
678    alpha: f32,
679    clip: Option<Rc<Mask>>,
680    /// The canvas area the clip lets through; `None` for none.
681    bounds: Option<IntRect>,
682    /// The area drawn on so far; `None` while nothing has been.
683    dirty: Option<IntRect>,
684}
685
686impl<'a> SkiaSink<'a> {
687    fn new(
688        width: u32,
689        height: u32,
690        images: &'a HashMap<String, Pixmap>,
691    ) -> Result<Self, ExtensionError> {
692        let pixmap = Pixmap::new(width, height).ok_or_else(|| {
693            ExtensionError::Budget(format!("cannot rasterize at {width}x{height}"))
694        })?;
695        Ok(Self {
696            width,
697            height,
698            layers: vec![Layer {
699                pixmap: Some(pixmap),
700                blend: BlendMode::SourceOver,
701                alpha: 1.0,
702                clip: None,
703                bounds: IntRect::from_xywh(0, 0, width, height),
704                dirty: None,
705            }],
706            images,
707            covering: None,
708            pool: Vec::new(),
709            #[cfg(test)]
710            whole: false,
711            #[cfg(test)]
712            composited: 0,
713            #[cfg(test)]
714            allocated: 0,
715        })
716    }
717
718    fn finish(mut self) -> Vec<u8> {
719        while self.layers.len() > 1 {
720            self.pop_layer();
721        }
722        self.layers
723            .pop()
724            .and_then(|layer| layer.pixmap)
725            .map_or_else(Vec::new, Pixmap::take)
726    }
727
728    /// Composites every layer whole in tests, as the reference for bounded compositing.
729    #[allow(clippy::unused_self)]
730    fn whole(&self) -> bool {
731        #[cfg(test)]
732        return self.whole;
733        #[cfg(not(test))]
734        false
735    }
736
737    /// The last layer with its own pixmap.
738    fn target(&mut self) -> Option<&mut Layer> {
739        self.layers
740            .iter_mut()
741            .rev()
742            .find(|layer| layer.pixmap.is_some())
743    }
744
745    /// The target pixmap, marking `bounds` (device pixels, `None` for all) as drawn on.
746    fn draw_on(&mut self, bounds: Option<IntRect>) -> &mut Pixmap {
747        let canvas = IntRect::from_xywh(0, 0, self.width, self.height);
748        let layer = self.target().expect("the canvas is a layer");
749        layer.dirty = match (layer.dirty, bounds.or(canvas)) {
750            (Some(dirty), Some(bounds)) => union(dirty, bounds),
751            (dirty, bounds) => dirty.or(bounds),
752        };
753        layer.pixmap.as_mut().expect("a layer with a pixmap")
754    }
755
756    /// Device pixels a path in `bounds` can touch through `transform`, plus a two-pixel margin
757    /// for antialiasing.
758    fn reach(&self, bounds: tiny_skia::Rect, transform: Transform) -> Option<IntRect> {
759        let device = PathBuilder::from_rect(bounds)
760            .transform(transform)?
761            .bounds();
762        // Sides are at most 16384: exact in f32.
763        #[allow(clippy::cast_precision_loss)]
764        let (width, height) = (self.width as f32, self.height as f32);
765        #[allow(clippy::cast_possible_truncation)]
766        IntRect::from_ltrb(
767            device.left().floor().max(-2.0) as i32 - 2,
768            device.top().floor().max(-2.0) as i32 - 2,
769            device.right().ceil().min(width) as i32 + 2,
770            device.bottom().ceil().min(height) as i32 + 2,
771        )?
772        .intersect(&IntRect::from_xywh(0, 0, self.width, self.height)?)
773    }
774
775    fn push(&mut self, blend: BlendMode, alpha: f32, affine: Affine, shape: &impl Shape) {
776        let transform = skia_transform(affine);
777        let path = path_of(shape);
778        let canvas = IntRect::from_xywh(0, 0, self.width, self.height);
779        // Where the clip is, as the mask rasterizes it.
780        let device = path
781            .clone()
782            .map(|path| path.transform(transform).map(|path| path.bounds()));
783        // Sides are at most 16384: exact in f32.
784        #[allow(clippy::cast_precision_loss)]
785        let (width, height) = (self.width as f32, self.height as f32);
786        let clips_nothing = shape.as_rect().is_some()
787            && transform.kx == 0.0
788            && transform.ky == 0.0
789            && matches!(device, Some(Some(bounds)) if bounds.left() <= 0.0
790                && bounds.top() <= 0.0
791                && bounds.right() >= width
792                && bounds.bottom() >= height);
793        #[allow(clippy::float_cmp)]
794        let opaque = alpha == 1.0;
795        if clips_nothing
796            && blend == BlendMode::SourceOver
797            && opaque
798            && !self.whole()
799            && self.target().is_some_and(|layer| layer.dirty.is_none())
800        {
801            self.layers.push(Layer {
802                pixmap: None,
803                blend,
804                alpha,
805                clip: None,
806                bounds: None,
807                dirty: None,
808            });
809            return;
810        }
811        let bounds = match &path {
812            // No clip: the whole layer.
813            None => canvas,
814            _ if self.whole() => canvas,
815            // Every pixel the mask can cover.
816            Some(path) => self.reach(path.bounds(), transform),
817        };
818        let clip = if clips_nothing && !self.whole() {
819            if self.covering.is_none() {
820                self.covering = IntSize::from_wh(self.width, self.height)
821                    .and_then(|size| {
822                        let coverage = vec![255; size.width() as usize * size.height() as usize];
823                        Mask::from_vec(coverage, size)
824                    })
825                    .map(Rc::new);
826            }
827            self.covering.clone()
828        } else {
829            path.and_then(|path| {
830                let mut mask = Mask::new(self.width, self.height)?;
831                if device::within(shape, affine, 0.0, (self.width, self.height)) {
832                    mask.fill_path(&path, FillRule::Winding, true, transform);
833                } else if let Some(far) =
834                    device::fill_path(shape, affine, (self.width, self.height))
835                {
836                    mask.fill_path(&far, FillRule::Winding, true, Transform::identity());
837                }
838                Some(Rc::new(mask))
839            })
840        };
841        let pooled = if self.whole() { None } else { self.pool.pop() };
842        #[cfg(test)]
843        if pooled.is_none() {
844            self.allocated += 1;
845        }
846        let Some(pixmap) = pooled.or_else(|| Pixmap::new(self.width, self.height)) else {
847            return;
848        };
849        self.layers.push(Layer {
850            pixmap: Some(pixmap),
851            blend,
852            alpha,
853            clip,
854            bounds,
855            dirty: None,
856        });
857    }
858}
859
860impl SkiaSink<'_> {
861    /// Fills a `shape` that reaches too far for tiny-skia by clipping it to the canvas first
862    /// ([`device`]) and moving the shader to match.
863    fn fill_far(&mut self, shape: &impl Shape, transform: Affine, mut paint: Paint<'_>) {
864        let Some(path) = device::fill_path(shape, transform, (self.width, self.height)) else {
865            return;
866        };
867        paint.shader.transform(skia_transform(transform));
868        let bounds = self.reach(path.bounds(), Transform::identity());
869        self.draw_on(bounds).fill_path(
870            &path,
871            &paint,
872            FillRule::Winding,
873            Transform::identity(),
874            None,
875        );
876    }
877
878    /// Composites a popped layer onto the one below within `bounds`, matching `draw_pixmap`.
879    fn composite(&mut self, pixmap: &Pixmap, layer: &Layer, bounds: IntRect) {
880        #[cfg(test)]
881        {
882            self.composited += u64::from(bounds.width()) * u64::from(bounds.height());
883        }
884        let paint = Paint {
885            shader: tiny_skia::Pattern::new(
886                pixmap.as_ref(),
887                SpreadMode::Pad,
888                tiny_skia::FilterQuality::Nearest,
889                layer.alpha,
890                Transform::identity(),
891            ),
892            blend_mode: layer.blend,
893            anti_alias: false,
894            ..Paint::default()
895        };
896        self.draw_on(Some(bounds)).fill_rect(
897            bounds.to_rect(),
898            &paint,
899            Transform::identity(),
900            layer.clip.as_deref(),
901        );
902    }
903}
904
905fn union(a: IntRect, b: IntRect) -> Option<IntRect> {
906    IntRect::from_ltrb(
907        a.left().min(b.left()),
908        a.top().min(b.top()),
909        a.right().max(b.right()),
910        a.bottom().max(b.bottom()),
911    )
912}
913
914impl RenderSink for SkiaSink<'_> {
915    fn push_layer(
916        &mut self,
917        blend: impl Into<PenikoBlend>,
918        alpha: f32,
919        transform: Affine,
920        shape: &impl Shape,
921    ) {
922        self.push(blend_mode(blend.into()), alpha, transform, shape);
923    }
924
925    fn push_clip_layer(&mut self, transform: Affine, shape: &impl Shape) {
926        self.push(BlendMode::SourceOver, 1.0, transform, shape);
927    }
928
929    fn pop_layer(&mut self) {
930        if self.layers.len() < 2 {
931            return;
932        }
933        let Some(layer) = self.layers.pop() else {
934            return;
935        };
936        let mut layer = layer;
937        let Some(mut pixmap) = layer.pixmap.take() else {
938            return;
939        };
940        // Outside the clip and (for normal blending) the drawn area, compositing changes nothing.
941        let bounds = layer.bounds.and_then(|bounds| match layer.blend {
942            BlendMode::SourceOver if !self.whole() => layer.dirty?.intersect(&bounds),
943            _ => Some(bounds),
944        });
945        if let Some(bounds) = bounds {
946            self.composite(&pixmap, &layer, bounds);
947        }
948        // Clear only the drawn area so the pixmap can be reused.
949        if let Some(dirty) = layer.dirty {
950            let at = |value: i32| usize::try_from(value).unwrap_or(0);
951            let stride = pixmap.width() as usize * 4;
952            let (left, right) = (at(dirty.left()) * 4, at(dirty.right()) * 4);
953            for row in pixmap
954                .data_mut()
955                .chunks_exact_mut(stride)
956                .skip(at(dirty.top()))
957                .take(dirty.height() as usize)
958            {
959                row[left..right].fill(0);
960            }
961        }
962        self.pool.push(pixmap);
963    }
964    fn draw(
965        &mut self,
966        stroke: Option<&kurbo::Stroke>,
967        transform: Affine,
968        brush: &Brush,
969        shape: &impl Shape,
970    ) {
971        let Some(path) = path_of(shape) else {
972            return;
973        };
974        let Some(shader) = shader_of(brush) else {
975            return;
976        };
977        let paint = Paint {
978            shader,
979            anti_alias: true,
980            ..Paint::default()
981        };
982        let affine = transform;
983        let transform = skia_transform(affine);
984        match stroke {
985            // tiny-skia draws a stroke of no width as a hairline; Lottie,
986            // like SVG, draws nothing.
987            Some(stroke) if stroke.width.is_nan() || stroke.width <= 0.0 => {}
988            Some(stroke) => {
989                let style = Stroke {
990                    #[allow(clippy::cast_possible_truncation)]
991                    width: stroke.width as f32,
992                    #[allow(clippy::cast_possible_truncation)]
993                    miter_limit: stroke.miter_limit as f32,
994                    line_cap: match stroke.start_cap {
995                        kurbo::Cap::Butt => LineCap::Butt,
996                        kurbo::Cap::Round => LineCap::Round,
997                        kurbo::Cap::Square => LineCap::Square,
998                    },
999                    line_join: match stroke.join {
1000                        kurbo::Join::Bevel => LineJoin::Bevel,
1001                        kurbo::Join::Miter => LineJoin::Miter,
1002                        kurbo::Join::Round => LineJoin::Round,
1003                    },
1004                    #[allow(clippy::cast_possible_truncation)]
1005                    dash: (!stroke.dash_pattern.is_empty())
1006                        .then(|| {
1007                            StrokeDash::new(
1008                                stroke
1009                                    .dash_pattern
1010                                    .iter()
1011                                    .map(|value| *value as f32)
1012                                    .collect(),
1013                                stroke.dash_offset as f32,
1014                            )
1015                        })
1016                        .flatten(),
1017                };
1018                // Half the width times the miter limit (at least sqrt(2) for square caps), plus a
1019                // full width for outline flattening.
1020                let reach = style.width / 2.0 * style.miter_limit.max(std::f32::consts::SQRT_2)
1021                    + style.width;
1022                if !device::within(shape, affine, f64::from(reach), (self.width, self.height)) {
1023                    // Stroke to an outline as tiny-skia would, then fill it within the canvas.
1024                    let scale = PathStroker::compute_resolution_scale(&transform);
1025                    let dashed = match &style.dash {
1026                        Some(dash) => path.dash(dash, scale),
1027                        None => Some(path),
1028                    };
1029                    if let Some(outline) = dashed.and_then(|path| path.stroke(&style, scale)) {
1030                        self.fill_far(&device::kurbo_path(&outline), affine, paint);
1031                    }
1032                    return;
1033                }
1034                let bounds = tiny_skia::Rect::from_ltrb(
1035                    path.bounds().left() - reach,
1036                    path.bounds().top() - reach,
1037                    path.bounds().right() + reach,
1038                    path.bounds().bottom() + reach,
1039                )
1040                .and_then(|bounds| self.reach(bounds, transform));
1041                self.draw_on(bounds)
1042                    .stroke_path(&path, &paint, &style, transform, None);
1043            }
1044            None if !device::within(shape, affine, 0.0, (self.width, self.height)) => {
1045                self.fill_far(shape, affine, paint);
1046            }
1047            None => {
1048                let bounds = self.reach(path.bounds(), transform);
1049                self.draw_on(bounds)
1050                    .fill_path(&path, &paint, FillRule::Winding, transform, None);
1051            }
1052        }
1053    }
1054
1055    fn draw_image(&mut self, image: &ImageAsset, transform: Affine, alpha: f64) {
1056        let Some(pixmap) = self.images.get(&image.id) else {
1057            return;
1058        };
1059        // Fit and center the picture in the asset's authored size; velato clips to that size.
1060        let picture = (f64::from(pixmap.width()), f64::from(pixmap.height()));
1061        let transform = match image.width.zip(image.height) {
1062            Some((width, height)) if width > 0.0 && height > 0.0 && (width, height) != picture => {
1063                let scale = (width / picture.0).min(height / picture.1);
1064                transform
1065                    * Affine::translate((
1066                        (width - picture.0 * scale) / 2.0,
1067                        (height - picture.1 * scale) / 2.0,
1068                    ))
1069                    * Affine::scale(scale)
1070            }
1071            _ => transform,
1072        };
1073        let paint = PixmapPaint {
1074            #[allow(clippy::cast_possible_truncation)]
1075            opacity: alpha as f32,
1076            blend_mode: BlendMode::SourceOver,
1077            quality: tiny_skia::FilterQuality::Bilinear,
1078        };
1079        let picture = kurbo::Rect::new(0.0, 0.0, picture.0, picture.1);
1080        if !device::within(&picture, transform, 0.0, (self.width, self.height)) {
1081            // A rectangle filled with the picture, as tiny-skia draws one.
1082            let paint = Paint {
1083                shader: tiny_skia::Pattern::new(
1084                    pixmap.as_ref(),
1085                    SpreadMode::Pad,
1086                    paint.quality,
1087                    paint.opacity,
1088                    Transform::identity(),
1089                ),
1090                blend_mode: paint.blend_mode,
1091                anti_alias: false,
1092                ..Paint::default()
1093            };
1094            self.fill_far(&picture, transform, paint);
1095            return;
1096        }
1097        let transform = skia_transform(transform);
1098        let bounds = IntRect::from_xywh(0, 0, pixmap.width(), pixmap.height())
1099            .and_then(|picture| self.reach(picture.to_rect(), transform));
1100        self.draw_on(bounds)
1101            .draw_pixmap(0, 0, pixmap.as_ref(), &paint, transform, None);
1102    }
1103}
1104
1105fn skia_transform(affine: Affine) -> Transform {
1106    #[allow(clippy::cast_possible_truncation)]
1107    let [sx, ky, kx, sy, tx, ty] = affine.as_coeffs().map(|value| value as f32);
1108    Transform::from_row(sx, ky, kx, sy, tx, ty)
1109}
1110
1111/// A kurbo shape as a tiny-skia path, flattened to a tenth of a unit.
1112fn path_of(shape: &impl Shape) -> Option<tiny_skia::Path> {
1113    let mut builder = PathBuilder::new();
1114    #[allow(clippy::cast_possible_truncation)]
1115    let point = |p: kurbo::Point| (p.x as f32, p.y as f32);
1116    for element in shape.path_elements(0.1) {
1117        match element {
1118            PathEl::MoveTo(p) => {
1119                let (x, y) = point(p);
1120                builder.move_to(x, y);
1121            }
1122            PathEl::LineTo(p) => {
1123                let (x, y) = point(p);
1124                builder.line_to(x, y);
1125            }
1126            PathEl::QuadTo(p1, p2) => {
1127                let ((x1, y1), (x, y)) = (point(p1), point(p2));
1128                builder.quad_to(x1, y1, x, y);
1129            }
1130            PathEl::CurveTo(p1, p2, p3) => {
1131                let ((x1, y1), (x2, y2), (x, y)) = (point(p1), point(p2), point(p3));
1132                builder.cubic_to(x1, y1, x2, y2, x, y);
1133            }
1134            PathEl::ClosePath => builder.close(),
1135        }
1136    }
1137    builder.finish()
1138}
1139
1140fn shader_of(brush: &Brush) -> Option<Shader<'static>> {
1141    let color = |components: [f32; 4]| {
1142        Color::from_rgba(
1143            components[0].clamp(0.0, 1.0),
1144            components[1].clamp(0.0, 1.0),
1145            components[2].clamp(0.0, 1.0),
1146            components[3].clamp(0.0, 1.0),
1147        )
1148    };
1149    match brush {
1150        Brush::Solid(solid) => color(solid.components).map(Shader::SolidColor),
1151        Brush::Gradient(gradient) => {
1152            let stops = gradient
1153                .stops
1154                .iter()
1155                .filter_map(|stop| {
1156                    let srgb = stop.color.to_alpha_color::<peniko::color::Srgb>();
1157                    color(srgb.components).map(|c| GradientStop::new(stop.offset, c))
1158                })
1159                .collect::<Vec<_>>();
1160            let mode = match gradient.extend {
1161                Extend::Pad => SpreadMode::Pad,
1162                Extend::Repeat => SpreadMode::Repeat,
1163                Extend::Reflect => SpreadMode::Reflect,
1164            };
1165            #[allow(clippy::cast_possible_truncation)]
1166            let point = |p: kurbo::Point| Point::from_xy(p.x as f32, p.y as f32);
1167            match &gradient.kind {
1168                GradientKind::Linear(linear) => LinearGradient::new(
1169                    point(linear.start),
1170                    point(linear.end),
1171                    stops,
1172                    mode,
1173                    Transform::identity(),
1174                ),
1175                GradientKind::Radial(radial) => RadialGradient::new(
1176                    point(radial.start_center),
1177                    radial.start_radius,
1178                    point(radial.end_center),
1179                    radial.end_radius,
1180                    stops,
1181                    mode,
1182                    Transform::identity(),
1183                ),
1184                GradientKind::Sweep(sweep) => SweepGradient::new(
1185                    point(sweep.center),
1186                    sweep.start_angle.to_degrees(),
1187                    sweep.end_angle.to_degrees(),
1188                    stops,
1189                    mode,
1190                    Transform::identity(),
1191                ),
1192            }
1193        }
1194        Brush::Image(_) => None,
1195    }
1196}
1197
1198/// A peniko blend as tiny-skia draws it: a separable or non-separable mix
1199/// over the backdrop, otherwise the Porter-Duff composition.
1200fn blend_mode(blend: PenikoBlend) -> BlendMode {
1201    match blend.mix {
1202        Mix::Multiply => BlendMode::Multiply,
1203        Mix::Screen => BlendMode::Screen,
1204        Mix::Overlay => BlendMode::Overlay,
1205        Mix::Darken => BlendMode::Darken,
1206        Mix::Lighten => BlendMode::Lighten,
1207        Mix::ColorDodge => BlendMode::ColorDodge,
1208        Mix::ColorBurn => BlendMode::ColorBurn,
1209        Mix::HardLight => BlendMode::HardLight,
1210        Mix::SoftLight => BlendMode::SoftLight,
1211        Mix::Difference => BlendMode::Difference,
1212        Mix::Exclusion => BlendMode::Exclusion,
1213        Mix::Hue => BlendMode::Hue,
1214        Mix::Saturation => BlendMode::Saturation,
1215        Mix::Color => BlendMode::Color,
1216        Mix::Luminosity => BlendMode::Luminosity,
1217        Mix::Normal => match blend.compose {
1218            Compose::Clear => BlendMode::Clear,
1219            Compose::Copy => BlendMode::Source,
1220            Compose::Dest => BlendMode::Destination,
1221            Compose::DestOver => BlendMode::DestinationOver,
1222            Compose::SrcIn => BlendMode::SourceIn,
1223            Compose::DestIn => BlendMode::DestinationIn,
1224            Compose::SrcOut => BlendMode::SourceOut,
1225            Compose::DestOut => BlendMode::DestinationOut,
1226            Compose::SrcAtop => BlendMode::SourceAtop,
1227            Compose::DestAtop => BlendMode::DestinationAtop,
1228            Compose::Xor => BlendMode::Xor,
1229            Compose::Plus | Compose::PlusLighter => BlendMode::Plus,
1230            Compose::SrcOver => BlendMode::SourceOver,
1231        },
1232    }
1233}
1234
1235#[cfg(test)]
1236mod tests;