kui_native/
decode.rs

1//! The runner's image decoder (backlog F138): the `image` crate the
2//! wallpaper behind a `Tinted` window already links (`ground.rs`), behind
3//! two functions, so an app that ships a photo or an animated GIF needs no
4//! decoder of its own.
5//!
6//! [`decode_image`] turns PNG, JPEG, WebP or GIF bytes into straight RGBA,
7//! the shape `Core::add_image`, `update_image` and `Launcher::icon` take.
8//! [`decode_animation`] keeps every frame of an animated GIF, PNG (APNG) or
9//! WebP with the time it shows for, and [`Animation::at`] says which frame
10//! a moment of the frame clock shows and when the next is due — what a
11//! view hands to `update_image` and `Ui::request_frame_at`, so a GIF plays
12//! with no thread and no frame owed between its changes.
13
14use std::io::Cursor;
15
16use image::{AnimationDecoder, ImageDecoder, ImageFormat};
17
18/// Decoded pixels: `width` by `height`, four bytes each (RGBA), row by row
19/// from the top left, alpha not premultiplied.
20#[derive(Clone, Debug, PartialEq, Eq)]
21pub struct Pixels {
22    pub width: u32,
23    pub height: u32,
24    pub rgba: Vec<u8>,
25}
26
27/// Every frame of an animated image, each the whole canvas (the
28/// file's own partial frames already composited, as a browser shows
29/// them), with how long each shows.
30#[derive(Clone, Debug, PartialEq)]
31pub struct Animation {
32    pub width: u32,
33    pub height: u32,
34    pub frames: Vec<AnimationFrame>,
35    /// How many times the whole sequence plays; `None` for ever, which is
36    /// what most GIFs say.
37    pub loops: Option<u32>,
38}
39
40/// One frame of an [`Animation`]: `width * height * 4` bytes of RGBA, and
41/// the seconds it shows for.
42#[derive(Clone, Debug, PartialEq)]
43pub struct AnimationFrame {
44    pub rgba: Vec<u8>,
45    pub delay: f64,
46}
47
48/// Which frame of an [`Animation`] a moment shows, from [`Animation::at`].
49#[derive(Clone, Copy, Debug, PartialEq)]
50pub struct Showing {
51    /// The frame's index in [`Animation::frames`].
52    pub index: usize,
53    /// Seconds after the start when the next frame is due; infinity once
54    /// a finite animation has played out, or for a single frame.
55    pub next: f64,
56}
57
58/// The shortest delay a GIF frame is shown for as written: browsers show
59/// a frame that says 0 or 10 ms for 100 ms, and GIFs are made for that.
60const GIF_FLOOR: f64 = 0.011;
61const GIF_SLOW: f64 = 0.1;
62
63fn format_of(bytes: &[u8]) -> Result<ImageFormat, String> {
64    let format = image::guess_format(bytes)
65        .map_err(|_| "not an image kui decodes: PNG, JPEG, WebP or GIF".to_string())?;
66    match format {
67        ImageFormat::Png | ImageFormat::Jpeg | ImageFormat::WebP | ImageFormat::Gif => Ok(format),
68        other => Err(format!(
69            "{other:?} is not a format kui decodes: PNG, JPEG, WebP or GIF"
70        )),
71    }
72}
73
74/// Decodes PNG, JPEG, WebP or GIF bytes to straight RGBA — an animated
75/// file's first frame. A failure names the format it could not read, or
76/// that the bytes are none of the four.
77pub fn decode_image(bytes: &[u8]) -> Result<Pixels, String> {
78    let format = format_of(bytes)?;
79    let img = image::load_from_memory_with_format(bytes, format)
80        .map_err(|e| format!("decoding a {format:?}: {e}"))?
81        .into_rgba8();
82    Ok(Pixels {
83        width: img.width(),
84        height: img.height(),
85        rgba: img.into_raw(),
86    })
87}
88
89/// Decodes every frame of an animated GIF, PNG (APNG) or WebP, each the
90/// whole canvas with its delay; a still image — a JPEG, a PNG with one
91/// frame — is one frame that shows for ever. A GIF frame that asks for
92/// 10 ms or less shows for 100 ms, as browsers show it.
93pub fn decode_animation(bytes: &[u8]) -> Result<Animation, String> {
94    let format = format_of(bytes)?;
95    let err = |e: image::ImageError| format!("decoding a {format:?}: {e}");
96    let (width, height, loops, frames) = match format {
97        ImageFormat::Gif => {
98            let d = image::codecs::gif::GifDecoder::new(Cursor::new(bytes)).map_err(err)?;
99            let (w, h) = d.dimensions();
100            let loops = loops_of(d.loop_count());
101            (w, h, loops, d.into_frames().collect_frames().map_err(err)?)
102        }
103        ImageFormat::Png => {
104            let d = image::codecs::png::PngDecoder::new(Cursor::new(bytes)).map_err(err)?;
105            if !d.is_apng().map_err(err)? {
106                return still(bytes);
107            }
108            let (w, h) = d.dimensions();
109            let a = d.apng().map_err(err)?;
110            let loops = loops_of(a.loop_count());
111            (w, h, loops, a.into_frames().collect_frames().map_err(err)?)
112        }
113        ImageFormat::WebP => {
114            let d = image::codecs::webp::WebPDecoder::new(Cursor::new(bytes)).map_err(err)?;
115            if !d.has_animation() {
116                return still(bytes);
117            }
118            let (w, h) = d.dimensions();
119            let loops = loops_of(d.loop_count());
120            (w, h, loops, d.into_frames().collect_frames().map_err(err)?)
121        }
122        _ => return still(bytes),
123    };
124    let gif = format == ImageFormat::Gif;
125    let mut out: Vec<AnimationFrame> = Vec::with_capacity(frames.len());
126    for f in frames {
127        let (num, den) = f.delay().numer_denom_ms();
128        let mut delay = f64::from(num) / f64::from(den.max(1)) / 1000.0;
129        if gif && delay < GIF_FLOOR {
130            delay = GIF_SLOW;
131        }
132        let (left, top) = (f.left(), f.top());
133        let buf = f.into_buffer();
134        let rgba = if (buf.width(), buf.height(), left, top) == (width, height, 0, 0) {
135            buf.into_raw()
136        } else {
137            // A decoder that hands back the changed rectangle alone: laid
138            // over the frame before it, which is what "not disposed" means.
139            let mut canvas = out
140                .last()
141                .map(|p| p.rgba.clone())
142                .unwrap_or_else(|| vec![0; width as usize * height as usize * 4]);
143            blit(&mut canvas, width, height, &buf, left, top);
144            canvas
145        };
146        out.push(AnimationFrame { rgba, delay });
147    }
148    if out.is_empty() {
149        return Err(format!("a {format:?} with no frames"));
150    }
151    Ok(Animation {
152        width,
153        height,
154        frames: out,
155        loops,
156    })
157}
158
159fn still(bytes: &[u8]) -> Result<Animation, String> {
160    let p = decode_image(bytes)?;
161    Ok(Animation {
162        width: p.width,
163        height: p.height,
164        frames: vec![AnimationFrame {
165            rgba: p.rgba,
166            delay: f64::INFINITY,
167        }],
168        loops: Some(1),
169    })
170}
171
172fn loops_of(count: image::metadata::LoopCount) -> Option<u32> {
173    match count {
174        image::metadata::LoopCount::Infinite => None,
175        image::metadata::LoopCount::Finite(n) => Some(n.get()),
176    }
177}
178
179fn blit(canvas: &mut [u8], w: u32, h: u32, src: &image::RgbaImage, left: u32, top: u32) {
180    for (y, row) in src.rows().enumerate() {
181        let cy = top as usize + y;
182        if cy >= h as usize {
183            break;
184        }
185        for (x, px) in row.enumerate() {
186            let cx = left as usize + x;
187            if cx >= w as usize {
188                break;
189            }
190            if px.0[3] != 0 {
191                let at = (cy * w as usize + cx) * 4;
192                canvas[at..at + 4].copy_from_slice(&px.0);
193            }
194        }
195    }
196}
197
198impl Animation {
199    /// The seconds one pass through every frame takes; infinity when a
200    /// frame shows for ever.
201    pub fn duration(&self) -> f64 {
202        self.frames.iter().map(|f| f.delay).sum()
203    }
204
205    /// The frame `elapsed` seconds after the animation started shows, and
206    /// when the next is due, in the same seconds: with the frame clock,
207    /// `at(ui.now() - started)`, then `update_image` when the index moved
208    /// and `request_frame_at(started + next)`. Before the start is the
209    /// first frame; after a finite animation has played out, the last,
210    /// with nothing due.
211    pub fn at(&self, elapsed: f64) -> Showing {
212        let last = self.frames.len().saturating_sub(1);
213        let total = self.duration();
214        if self.frames.len() < 2 || !total.is_finite() || total <= 0.0 {
215            return Showing {
216                index: 0,
217                next: f64::INFINITY,
218            };
219        }
220        let elapsed = elapsed.max(0.0);
221        let pass = (elapsed / total).floor();
222        if let Some(n) = self.loops
223            && pass >= f64::from(n)
224        {
225            return Showing {
226                index: last,
227                next: f64::INFINITY,
228            };
229        }
230        let mut t = pass * total;
231        for (i, f) in self.frames.iter().enumerate() {
232            t += f.delay;
233            if elapsed < t {
234                return Showing { index: i, next: t };
235            }
236        }
237        Showing {
238            index: last,
239            next: (pass + 1.0) * total + self.frames[0].delay,
240        }
241    }
242}
243
244#[cfg(test)]
245mod tests {
246    use super::*;
247    use gif::Repeat;
248    use image::{Rgba, RgbaImage};
249
250    /// A 4x2 GIF of three frames, red, green, then a 2x1 blue patch over
251    /// the green at (1, 1), at 50, 100 and 0 ms; `repeat` is its loop count.
252    fn gif(repeat: gif::Repeat) -> Vec<u8> {
253        let mut out = Vec::new();
254        {
255            let mut enc = gif::Encoder::new(&mut out, 4, 2, &[]).unwrap();
256            enc.set_repeat(repeat).unwrap();
257            let mut frame = |w: u16, h: u16, left: u16, top: u16, c: [u8; 4], cs: u16| {
258                let mut px: Vec<u8> = c.repeat(usize::from(w * h));
259                let mut f = gif::Frame::from_rgba(w, h, &mut px);
260                (f.left, f.top, f.delay) = (left, top, cs);
261                enc.write_frame(&f).unwrap();
262            };
263            frame(4, 2, 0, 0, [255, 0, 0, 255], 5);
264            frame(4, 2, 0, 0, [0, 255, 0, 255], 10);
265            frame(2, 1, 1, 1, [0, 0, 255, 255], 0);
266        }
267        out
268    }
269
270    fn png() -> Vec<u8> {
271        let img = RgbaImage::from_fn(3, 2, |x, y| Rgba([x as u8 * 80, y as u8 * 100, 7, 200]));
272        let mut out = Cursor::new(Vec::new());
273        img.write_to(&mut out, ImageFormat::Png).unwrap();
274        out.into_inner()
275    }
276
277    #[test]
278    fn a_png_decodes_to_straight_rgba() {
279        let p = decode_image(&png()).unwrap();
280        assert_eq!((p.width, p.height), (3, 2));
281        assert_eq!(p.rgba.len(), 3 * 2 * 4);
282        assert_eq!(&p.rgba[4..8], &[80, 0, 7, 200], "not premultiplied");
283    }
284
285    #[test]
286    fn a_gif_decodes_to_its_first_frame_and_to_every_frame() {
287        let bytes = gif(Repeat::Infinite);
288        let first = decode_image(&bytes).unwrap();
289        assert_eq!((first.width, first.height), (4, 2));
290        assert_eq!(&first.rgba[..4], &[255, 0, 0, 255]);
291        let a = decode_animation(&bytes).unwrap();
292        assert_eq!(a.frames.len(), 3);
293        assert_eq!(a.loops, None);
294        let delays: Vec<f64> = a.frames.iter().map(|f| f.delay).collect();
295        assert_eq!(delays, vec![0.05, 0.1, 0.1], "a 0 ms frame shows for 100");
296        for f in &a.frames {
297            assert_eq!(f.rgba.len(), 4 * 2 * 4, "each frame the whole canvas");
298        }
299        let third = &a.frames[2].rgba;
300        assert_eq!(
301            &third[..4],
302            &[0, 255, 0, 255],
303            "the green kept under the patch"
304        );
305        assert_eq!(&third[(4 + 1) * 4..(4 + 1) * 4 + 4], &[0, 0, 255, 255]);
306    }
307
308    #[test]
309    fn at_walks_the_frames_and_loops() {
310        let a = decode_animation(&gif(Repeat::Infinite)).unwrap();
311        let near = |s: Showing, i: usize, next: f64| s.index == i && (s.next - next).abs() < 1e-9;
312        assert!(near(a.at(0.0), 0, 0.05));
313        assert!(near(a.at(0.07), 1, 0.15));
314        assert!(near(a.at(0.2), 2, 0.25));
315        assert!(near(a.at(0.26), 0, 0.30), "{:?}", a.at(0.26));
316        assert!(near(a.at(-1.0), 0, 0.05), "before the start");
317    }
318
319    #[test]
320    fn a_finite_gif_rests_on_its_last_frame() {
321        let a = decode_animation(&gif(Repeat::Finite(1))).unwrap();
322        assert_eq!(a.loops, Some(1));
323        assert_eq!(a.at(0.1).index, 1);
324        let end = a.at(0.3);
325        assert_eq!(end.index, 2);
326        assert!(end.next.is_infinite());
327    }
328
329    #[test]
330    fn a_still_is_one_frame_for_ever() {
331        let a = decode_animation(&png()).unwrap();
332        assert_eq!(a.frames.len(), 1);
333        let s = a.at(100.0);
334        assert_eq!(s.index, 0);
335        assert!(s.next.is_infinite());
336    }
337
338    #[test]
339    fn what_is_not_an_image_is_named() {
340        let e = decode_image(b"hello, world").unwrap_err();
341        assert!(e.contains("PNG, JPEG, WebP or GIF"), "{e}");
342        let mut cut = png();
343        cut.truncate(40);
344        let e = decode_image(&cut).unwrap_err();
345        assert!(e.contains("decoding a Png"), "{e}");
346    }
347}
kui_native/decode.rs

kui_native/
decode.rs
