corundum-framework-gui 0.9.0

//! [`ImagePreview`]: a picture file, decoded off the UI thread and fitted in the space given.

use std::panic::{AssertUnwindSafe, catch_unwind};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::mpsc::{Receiver, Sender, TryRecvError, channel};
use std::time::{Duration, Instant, SystemTime};

use corundum_framework_image::{Error, Image, Limits, Source, thumbnail};

use crate::{icons, tr};

/// The sizes a picture is decoded to, in pixels on its longest side: the space it is drawn
/// in, rounded up to one of these, so a pane resized a little does not decode it again.
const SIZES: [u32; 4] = [256, 512, 1024, 2048];

/// How many decoded pictures are kept.
const KEPT: usize = 8;

/// The most pixels a picture may have, by default: 64 megapixels, a large camera's photo.
const MAX_PIXELS: u64 = 64_000_000;

/// How often the shown file is looked at again for a change, by the worker.
const RECHECK: Duration = Duration::from_secs(2);

/// The icon's size above a message, in points.
const ICON: f32 = 48.0;

/// A file as the worker found it: a file changed on disk is another picture.
#[derive(Clone, PartialEq, Eq, Debug)]
struct Key {
    path: PathBuf,
    modified: Option<SystemTime>,
    size: u64,
}

impl Key {
    /// Stat `path`: on the worker only, as a hung network mount would freeze the UI.
    fn of(path: &Path) -> Key {
        let meta = std::fs::metadata(path).ok();
        Key {
            path: path.to_owned(),
            modified: meta.as_ref().and_then(|m| m.modified().ok()),
            size: meta.map_or(0, |m| m.len()),
        }
    }
}

/// A request to the worker.
struct Request {
    path: PathBuf,
    /// The longest side to decode to.
    longest: u32,
    /// How big a picture may be.
    limits: Limits,
    /// The file as it was when a decode at least this large was kept: if it still is, the
    /// worker says so instead of decoding it again.
    known: Option<Key>,
}

/// What the worker made of a [`Request`].
enum Answer {
    /// The file is as `known` said.
    Unchanged { path: PathBuf, longest: u32 },
    Decoded {
        key: Key,
        longest: u32,
        decoded: Decoded,
    },
}

/// A decode's result, made ready for the UI thread to upload.
enum Decoded {
    Picture(egui::ColorImage),
    Unsupported,
    TooLarge,
    Failed(String),
}

impl Decoded {
    fn of(result: Result<Image, Error>) -> Decoded {
        match result {
            Ok(image) => {
                let size = [image.width as usize, image.height as usize];
                Decoded::Picture(egui::ColorImage::from_rgba_unmultiplied(size, &image.rgba))
            }
            Err(Error::Unsupported) => Decoded::Unsupported,
            Err(Error::TooLarge) => Decoded::TooLarge,
            Err(error) => Decoded::Failed(error.to_string()),
        }
    }
}

/// What a decode left to draw.
enum Outcome {
    Picture(egui::TextureHandle),
    Unsupported,
    TooLarge,
    Failed(String),
}

/// A decoded file, kept.
struct Kept {
    key: Key,
    /// The longest side it was asked to be decoded to.
    longest: u32,
    outcome: Outcome,
    /// When the worker last found the file unchanged.
    checked: Instant,
}

impl Kept {
    /// Whether this serves a request for `longest` pixels: decoded at least that large, or
    /// as large as the picture is.
    fn serves(&self, longest: u32) -> bool {
        match &self.outcome {
            Outcome::Picture(texture) => {
                let [w, h] = texture.size();
                self.longest >= longest || (w.max(h) as u32) < self.longest
            }
            _ => true,
        }
    }
}

/// The worker thread's end: requests out, answers in.
struct Worker {
    requests: Sender<Request>,
    answers: Receiver<Answer>,
    /// Requests sent and not yet answered or passed over. The thread holds a clone for as
    /// long as it runs, which is how the tests see that it ended, and when it is idle.
    pending: Arc<AtomicUsize>,
}

impl Worker {
    /// Start the thread. It takes the newest request it has, passing over older ones, and
    /// ends when the [`ImagePreview`] is dropped.
    fn spawn(ctx: egui::Context) -> Worker {
        let (requests, inbox) = channel::<Request>();
        let (outbox, answers) = channel::<Answer>();
        let pending = Arc::new(AtomicUsize::new(0));
        let count = pending.clone();
        std::thread::Builder::new()
            .name("image preview".into())
            .spawn(move || {
                while let Ok(mut request) = inbox.recv() {
                    let mut taken = 1;
                    while let Ok(newer) = inbox.try_recv() {
                        request = newer;
                        taken += 1;
                    }
                    let sent = outbox.send(answer(request));
                    count.fetch_sub(taken, Ordering::SeqCst);
                    if sent.is_err() {
                        break;
                    }
                    ctx.request_repaint();
                }
            })
            .expect("spawn the image preview's thread");
        Worker {
            requests,
            answers,
            pending,
        }
    }
}

/// The worker's answer to `request`: the file looked at, and decoded unless it is as known.
fn answer(request: Request) -> Answer {
    let Request {
        path,
        longest,
        limits,
        known,
    } = request;
    let key = Key::of(&path);
    if known.as_ref() == Some(&key) {
        return Answer::Unchanged { path, longest };
    }
    // The decoder guards itself, but a panic elsewhere (the resizer, say) would end the
    // thread, and the next frame would start another to decode the file again: it fails
    // instead, once, like a broken file.
    let decoded = catch_unwind(AssertUnwindSafe(|| {
        Decoded::of(decode(&key.path, longest, &limits))
    }))
    .unwrap_or_else(|_| Decoded::Failed("the image preview panicked".into()));
    Answer::Decoded {
        key,
        longest,
        decoded,
    }
}

/// Decode the picture at `path` to `longest` pixels on its longest side.
fn decode(path: &Path, longest: u32, limits: &Limits) -> Result<Image, Error> {
    #[cfg(test)]
    if path.file_name() == Some(std::ffi::OsStr::new(PANIC_NAME)) {
        PANICS.fetch_add(1, Ordering::SeqCst);
        panic!("a test's panic in the image preview's worker");
    }
    thumbnail(Source::Path(path), longest, limits)
}

/// A file name the worker panics on, past the decoder's own guard, for a test.
#[cfg(test)]
pub(super) const PANIC_NAME: &str = "corundum-preview-panics.png";

/// How many times the worker panicked on [`PANIC_NAME`].
#[cfg(test)]
static PANICS: AtomicUsize = AtomicUsize::new(0);

/// How many times the worker panicked on [`PANIC_NAME`], for a test.
#[cfg(test)]
pub(super) fn panics() -> usize {
    PANICS.load(Ordering::SeqCst)
}

/// A picture file in the detail pane: decoded on a worker thread to the size it is drawn
/// at (2048 pixels at most on its longest side), with a spinner meanwhile, and fitted in
/// the space given, its aspect kept and never drawn larger than its pixels.
///
/// The last pictures shown are kept, by path, modified time and size, so going back to
/// one is instant. The UI thread never touches the file: the worker looks at it when it is
/// picked again, and every couple of seconds while it is shown, and decodes it again if it
/// changed. A file the decoder does not know (HEIC, say) shows the file icon and says so;
/// one too large or broken says why.
///
/// A picture over its [`Limits`] is too large: by default, over 64 megapixels. Peak memory
/// while one is decoded is two of its buffers at a time (the decoded one and the copy an
/// orientation, the RGBA conversion or the colour conversion makes), some 8 to 16 bytes a
/// pixel: up to about 1 GB at 64 megapixels, where the 200 of [`Limits::default`] would
/// take over 3. A failed allocation ends the app rather than failing the decode, so on a
/// phone keep this low; [`ImagePreview::with_limits`] sets another bound.
///
/// Make one and keep it across frames; the thread it starts ends when it is dropped.
pub struct ImagePreview {
    /// Started on the first frame that needs it.
    worker: Option<Worker>,
    /// The path and size of the last request sent, until it is answered, so a frame asks
    /// again only for something new.
    asked: Option<(PathBuf, u32)>,
    /// The path drawn in the last frame.
    current: Option<PathBuf>,
    /// The decoded files, one per path, the most recently shown last.
    kept: Vec<Kept>,
    /// How often the shown file is looked at again for a change.
    recheck: Duration,
    /// How big a picture may be.
    limits: Limits,
}

impl Default for ImagePreview {
    fn default() -> ImagePreview {
        ImagePreview {
            worker: None,
            asked: None,
            current: None,
            kept: Vec::new(),
            recheck: RECHECK,
            limits: Limits::default().with_max_pixels(MAX_PIXELS),
        }
    }
}

impl ImagePreview {
    /// An empty preview; its thread starts on the first frame that needs it.
    pub fn new() -> ImagePreview {
        ImagePreview::default()
    }

    /// This preview with `limits` on the pictures it decodes, instead of the default:
    /// [`Limits::default`] with 64 megapixels at most.
    pub fn with_limits(self, limits: Limits) -> ImagePreview {
        ImagePreview { limits, ..self }
    }

    /// Draw `path` in the space `ui` has left.
    pub fn ui(&mut self, ui: &mut egui::Ui, path: &Path) {
        self.receive(ui.ctx());
        let area = ui.available_rect_before_wrap();
        ui.allocate_rect(area, egui::Sense::hover());
        let ppp = ui.ctx().pixels_per_point();
        let max_side = ui.ctx().input(|i| i.max_texture_side) as u32;
        let longest = target(area.size(), ppp).min(max_side.max(1));
        let picked = self.current.as_deref() != Some(path);
        if picked {
            self.current = Some(path.to_owned());
        }

        let Some(at) = self.kept.iter().position(|k| k.key.path == path) else {
            self.ask(ui.ctx(), path, longest, None);
            egui::Spinner::new().paint_at(
                ui,
                egui::Rect::from_center_size(area.center(), egui::vec2(32.0, 32.0)),
            );
            return;
        };
        let kept = self.kept.remove(at);
        self.kept.push(kept);
        let kept = &self.kept[self.kept.len() - 1];
        if !kept.serves(longest) {
            // The smaller decode is drawn until the larger one comes.
            self.ask(ui.ctx(), path, longest, None);
        } else if picked || kept.checked.elapsed() >= self.recheck {
            let known = Some(kept.key.clone());
            self.ask(ui.ctx(), path, longest, known);
        }
        ui.ctx().request_repaint_after(self.recheck);
        self.draw(ui, area, self.kept.len() - 1);
    }

    /// Draw the kept decode at `at` in `area`.
    fn draw(&self, ui: &mut egui::Ui, area: egui::Rect, at: usize) {
        let message = match &self.kept[at].outcome {
            Outcome::Picture(texture) => {
                let ppp = ui.ctx().pixels_per_point();
                let full = texture.size_vec2() / ppp;
                let scale = (area.width() / full.x).min(area.height() / full.y).min(1.0);
                let shown = egui::Rect::from_center_size(area.center(), full * scale);
                let uv = egui::Rect::from_min_max(egui::pos2(0.0, 0.0), egui::pos2(1.0, 1.0));
                ui.painter()
                    .image(texture.id(), shown, uv, egui::Color32::WHITE);
                return;
            }
            Outcome::Unsupported => tr!(ui, "corundum-preview-unsupported"),
            Outcome::TooLarge => tr!(ui, "corundum-preview-too-large"),
            Outcome::Failed(reason) => tr!(ui, "corundum-preview-failed", reason = reason.as_str()),
        };
        let mut inner = ui.new_child(
            egui::UiBuilder::new()
                .max_rect(area)
                .layout(egui::Layout::top_down(egui::Align::Center)),
        );
        inner.add_space((area.height() / 2.0 - ICON).max(0.0));
        inner.add(icons::image(&inner, icons::file(), ICON));
        inner.add(egui::Label::new(message).wrap());
    }

    /// Send the worker a request for `path` at `longest` pixels, unless that is the one
    /// still unanswered.
    fn ask(&mut self, ctx: &egui::Context, path: &Path, longest: u32, known: Option<Key>) {
        if self
            .asked
            .as_ref()
            .is_some_and(|(p, l)| p == path && *l == longest)
        {
            return;
        }
        let worker = self
            .worker
            .get_or_insert_with(|| Worker::spawn(ctx.clone()));
        worker.pending.fetch_add(1, Ordering::SeqCst);
        let request = Request {
            path: path.to_owned(),
            longest,
            limits: self.limits,
            known,
        };
        if worker.requests.send(request).is_err() {
            // The thread is gone (it panicked): start another on the next frame.
            self.worker = None;
            self.asked = None;
            return;
        }
        self.asked = Some((path.to_owned(), longest));
    }

    /// Keep what the worker has finished; whether it is shown is the frame's to decide.
    fn receive(&mut self, ctx: &egui::Context) {
        let Some(worker) = &self.worker else {
            return;
        };
        loop {
            match worker.answers.try_recv() {
                Ok(Answer::Unchanged { path, longest }) => {
                    answered(&mut self.asked, &path, longest);
                    if let Some(kept) = self.kept.iter_mut().find(|k| k.key.path == path) {
                        kept.checked = Instant::now();
                    }
                }
                Ok(Answer::Decoded {
                    key,
                    longest,
                    decoded,
                }) => {
                    answered(&mut self.asked, &key.path, longest);
                    let outcome = match decoded {
                        Decoded::Picture(pixels) => Outcome::Picture(ctx.load_texture(
                            format!("corundum-preview {}", key.path.display()),
                            pixels,
                            egui::TextureOptions::LINEAR,
                        )),
                        Decoded::Unsupported => Outcome::Unsupported,
                        Decoded::TooLarge => Outcome::TooLarge,
                        Decoded::Failed(reason) => Outcome::Failed(reason),
                    };
                    self.kept.retain(|k| k.key.path != key.path);
                    self.kept.push(Kept {
                        key,
                        longest,
                        outcome,
                        checked: Instant::now(),
                    });
                    if self.kept.len() > KEPT {
                        self.kept.remove(0);
                    }
                }
                Err(TryRecvError::Empty) => break,
                Err(TryRecvError::Disconnected) => {
                    self.worker = None;
                    self.asked = None;
                    break;
                }
            }
        }
    }

    /// The limits on the pictures decoded, for a test.
    #[cfg(test)]
    pub(super) fn limits(&self) -> Limits {
        self.limits
    }

    /// How often the shown file is looked at again, for a test.
    #[cfg(test)]
    pub(super) fn set_recheck(&mut self, recheck: Duration) {
        self.recheck = recheck;
    }

    /// Something the worker thread holds while it runs.
    #[cfg(test)]
    pub(super) fn thread_token(&self) -> Option<std::sync::Weak<AtomicUsize>> {
        self.worker.as_ref().map(|w| Arc::downgrade(&w.pending))
    }

    /// Whether the worker has nothing left to do.
    #[cfg(test)]
    pub(super) fn idle(&self) -> bool {
        self.worker
            .as_ref()
            .is_none_or(|w| w.pending.load(Ordering::SeqCst) == 0)
    }
}

/// Forget the request for `path` at `longest` as unanswered, if it was the last sent.
fn answered(asked: &mut Option<(PathBuf, u32)>, path: &Path, longest: u32) {
    if asked
        .as_ref()
        .is_some_and(|(p, l)| p == path && *l == longest)
    {
        *asked = None;
    }
}

/// The longest side to decode to for a `size`-point space at `ppp` pixels per point: the
/// first of [`SIZES`] at least that large, or the largest.
pub(super) fn target(size: egui::Vec2, ppp: f32) -> u32 {
    let wanted = (size.x.max(size.y) * ppp).ceil().max(0.0) as u32;
    SIZES
        .into_iter()
        .find(|&s| s >= wanted)
        .unwrap_or(SIZES[SIZES.len() - 1])
}