GitCorner

Code

ossartcraftlightcraft🌐
5a24289898fd
//! Slideshow title screens (Lightroom Classic's Slideshow ▸ Titles panel): an intro shown before
//! the first slide and an ending shown after the last one, each switched on on its own, with a
//! background colour and, centred on it, the identity plate (the one of the Overlays panel: its
//! text or image) or a line of text, at a scale. [`TitleSettings`] is a library preference
//! (`prefs.json`), edited with the `slideshow.titles` command; [`TitleCompose`] draws one screen.
//!
//! **One composer:** a title screen is a slide with no photo: `lightcraft_slideshow::compose`
//! fills it with the title's colour, then the overlay code ([`crate::slide_overlay`]) draws the
//! plate or text with the shared text renderer ([`crate::text`]). Playback, the Settings preview
//! and `slideshow.preview {title}` all go through [`TitleCompose::compose`], so they draw the same
//! pixels.
//!
//! **Timing** is in [`crate::slideshow::Playback`]: each screen stays up for its own duration
//! (default: the slide duration) and fades in and out with the playback fade.
//!
//! **Resolution independence:** the scale is the height of the plate (or of a text line) as a
//! fraction of the slide's shorter side; text wider than the slide is scaled down to fit.
//!
//! **Never crash:** settings are validated by [`TitleSettings::merged`] and clamped by
//! [`TitleSettings::sanitized`]; an unreadable plate image draws the colour alone (and
//! `slideshow.titles` reports it).

use std::sync::Arc;

use lightcraft_raster::Rgba8;
use lightcraft_slideshow::{Layout, Rect, SlideSettings, hex, parse_color};
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value, json};

use crate::export::Anchor;
use crate::slide_overlay::{IdentityPlate, OverlaySettings, PLATE_SIZE_MAX, Placement, RelativeTo, SIZE_MIN, SlideOverlays, TEXT_MAX_CHARS};
pub use crate::slideshow::Title;

/// Widest a title's plate or text may be (fraction of the slide's width): wider is scaled down.
pub const FIT_WIDTH: f64 = 0.9;

/// What a title screen shows on its colour.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum TitleContent {
    /// The colour alone.
    None,
    /// The identity plate of the Overlays panel (its text or image).
    #[default]
    IdentityPlate,
    /// This screen's own text.
    Text,
}

impl TitleContent {
    pub const ALL: [TitleContent; 3] = [TitleContent::None, TitleContent::IdentityPlate, TitleContent::Text];

    pub fn id(self) -> &'static str {
        match self {
            TitleContent::None => "none",
            TitleContent::IdentityPlate => "identityPlate",
            TitleContent::Text => "text",
        }
    }

    fn parse(s: &str) -> Option<TitleContent> {
        TitleContent::ALL.into_iter().find(|c| c.id().eq_ignore_ascii_case(s.trim()))
    }
}

/// One title screen.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct TitleScreen {
    pub enabled: bool,
    /// The screen's background colour.
    pub color: [u8; 3],
    pub content: TitleContent,
    /// The text drawn with [`TitleContent::Text`].
    pub text: String,
    /// Draw the plate or text in [`Self::text_color`] (off: in the identity plate's colour).
    /// An image plate keeps its own colours.
    pub override_color: bool,
    pub text_color: [u8; 3],
    /// Height of the plate (or of a text line), fraction of the slide's shorter side.
    pub scale: f64,
    /// Seconds the screen stays up (`None`: the slide duration).
    pub duration: Option<f64>,
}

impl TitleScreen {
    fn new(text: &str) -> Self {
        TitleScreen {
            enabled: false,
            color: [0, 0, 0],
            content: TitleContent::IdentityPlate,
            text: text.into(),
            override_color: false,
            text_color: [255, 255, 255],
            scale: 0.1,
            duration: None,
        }
    }
}

/// The intro and ending screens.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct TitleSettings {
    pub intro: TitleScreen,
    pub ending: TitleScreen,
}

impl Default for TitleSettings {
    fn default() -> Self {
        TitleSettings { intro: TitleScreen::new("Welcome"), ending: TitleScreen::new("The End") }
    }
}

impl Default for TitleScreen {
    fn default() -> Self {
        TitleScreen::new("")
    }
}

fn cut(s: &mut String) {
    if let Some((i, _)) = s.char_indices().nth(TEXT_MAX_CHARS) {
        s.truncate(i);
    }
}

const SCREEN_KEYS: &str = "enabled, color, content, text, overrideColor, textColor, scale, duration";

impl TitleScreen {
    fn sanitized(mut self) -> Self {
        cut(&mut self.text);
        self.scale = if self.scale.is_finite() { self.scale.clamp(SIZE_MIN, PLATE_SIZE_MAX) } else { 0.1 };
        self.duration = self.duration.filter(|d| d.is_finite()).map(|d| d.clamp(crate::slideshow::SLIDE_MIN, crate::slideshow::SLIDE_MAX));
        self
    }

    pub fn to_json(&self) -> Value {
        let mut o = Map::new();
        o.insert("enabled".into(), json!(self.enabled));
        o.insert("color".into(), json!(hex(self.color)));
        o.insert("content".into(), json!(self.content.id()));
        o.insert("text".into(), json!(self.text));
        o.insert("overrideColor".into(), json!(self.override_color));
        o.insert("textColor".into(), json!(hex(self.text_color)));
        o.insert("scale".into(), json!(self.scale));
        o.insert("duration".into(), json!(self.duration));
        Value::Object(o)
    }

    fn merge(&mut self, ctx: &str, v: &Value) -> Result<(), String> {
        let obj = v.as_object().ok_or_else(|| format!("`{ctx}` must be an object, not {v}"))?;
        let num = |k: &str, v: &Value| match v.as_f64() {
            Some(x) if x.is_finite() => Ok(x),
            _ => Err(format!("`{ctx}.{k}` must be a finite number, not {v}")),
        };
        let boolean = |k: &str, v: &Value| v.as_bool().ok_or_else(|| format!("`{ctx}.{k}` must be true or false, not {v}"));
        let colour = |k: &str, v: &Value| parse_color(v).ok_or_else(|| format!("`{ctx}.{k}` must be \"#rrggbb\" or [r, g, b] (0–255), not {v}"));
        for (k, v) in obj {
            match k.as_str() {
                "enabled" => self.enabled = boolean(k, v)?,
                "color" => self.color = colour(k, v)?,
                "content" => {
                    self.content = v
                        .as_str()
                        .and_then(TitleContent::parse)
                        .ok_or_else(|| format!("`{ctx}.content` must be \"none\", \"identityPlate\" or \"text\", not {v}"))?
                }
                "text" => {
                    let mut s = v.as_str().ok_or_else(|| format!("`{ctx}.text` must be text, not {v}"))?.to_string();
                    cut(&mut s);
                    self.text = s;
                }
                "overrideColor" => self.override_color = boolean(k, v)?,
                "textColor" => self.text_color = colour(k, v)?,
                "scale" => self.scale = num(k, v)?,
                "duration" => {
                    self.duration = match v {
                        Value::Null => None,
                        _ => Some(num(k, v).map_err(|_| format!("`{ctx}.duration` must be seconds or null (the slide duration), not {v}"))?),
                    }
                }
                _ => return Err(format!("unknown key `{ctx}.{k}` ({SCREEN_KEYS})")),
            }
        }
        Ok(())
    }
}

impl TitleSettings {
    pub fn screen(&self, t: Title) -> &TitleScreen {
        match t {
            Title::Intro => &self.intro,
            Title::Ending => &self.ending,
        }
    }

    /// Every value in range (non-finite numbers take the defaults).
    pub fn sanitized(mut self) -> Self {
        self.intro = self.intro.sanitized();
        self.ending = self.ending.sanitized();
        self
    }

    pub fn to_json(&self) -> Value {
        json!({"intro": self.intro.to_json(), "ending": self.ending.to_json()})
    }

    /// These settings with the keys `p` names changed, validated and clamped; a wrong type or an
    /// unknown key is an error and nothing changes.
    pub fn merged(&self, p: &Value) -> Result<Self, String> {
        let Some(obj) = p.as_object() else { return Err("parameters must be an object".into()) };
        let mut s = self.clone();
        for (k, v) in obj {
            match k.as_str() {
                "intro" => s.intro.merge(k, v)?,
                "ending" => s.ending.merge(k, v)?,
                _ => return Err(format!("unknown setting `{k}` (intro, ending)")),
            }
        }
        Ok(s.sanitized())
    }

    /// How long each screen that is on stays up, given the slide duration (for
    /// [`crate::slideshow::Playback::with_titles`]): (intro, ending).
    pub fn durations(&self, slide: f64) -> (Option<f64>, Option<f64>) {
        let d = |s: &TitleScreen| s.enabled.then(|| s.duration.unwrap_or(slide));
        (d(&self.intro), d(&self.ending))
    }

    /// Problems worth telling the user about: a screen showing an identity plate image that
    /// can't be read, or one with nothing to show.
    pub fn warnings(&self, overlays: &OverlaySettings) -> Vec<String> {
        let mut out = Vec::new();
        let plate = &overlays.identity_plate;
        for t in Title::ALL {
            let s = self.screen(t);
            if !s.enabled {
                continue;
            }
            match s.content {
                TitleContent::IdentityPlate if !plate.image.trim().is_empty() && crate::export::watermark_logo(plate.image.trim()).is_none() => {
                    out.push(format!("{} screen: identity plate image {} can't be read; only the colour shows", t.id(), plate.image.trim()))
                }
                TitleContent::IdentityPlate if plate.image.trim().is_empty() && plate.text.trim().is_empty() => {
                    out.push(format!("{} screen: the identity plate has no text or image; only the colour shows", t.id()))
                }
                TitleContent::Text if s.text.trim().is_empty() => out.push(format!("{} screen: no text; only the colour shows", t.id())),
                _ => {}
            }
        }
        out
    }
}

/// How to draw one title screen at a size: its colour and its plate or text, resolved from the
/// library's settings (no session needed, so it runs on a render worker).
#[derive(Clone, Debug)]
pub struct TitleCompose {
    pub title: Title,
    /// The screen as a slide: its colour as the backdrop, nothing else.
    pub settings: SlideSettings,
    /// The plate or text, as a centred identity plate (`None`: the colour alone).
    pub overlays: Option<Arc<SlideOverlays>>,
    pub width: usize,
    pub height: usize,
}

impl TitleCompose {
    /// Screen `title` of `titles` at `width × height` (a bigger one is drawn at the composer's
    /// [`lightcraft_slideshow::MAX_SIDE`]),
    /// with `overlays`' identity plate when the screen shows it.
    pub fn new(titles: &TitleSettings, overlays: &OverlaySettings, title: Title, width: usize, height: usize) -> Self {
        let s = titles.screen(title).clone().sanitized();
        let settings = SlideSettings { backdrop_color: s.color, ..SlideSettings::default() }.sanitized();
        let plate = &overlays.identity_plate;
        let centre = Placement { anchor: Anchor::Center, offset_x: 0.0, offset_y: 0.0, relative_to: RelativeTo::Slide };
        let colour = |own: [u8; 3]| if s.override_color { s.text_color } else { own };
        let shown = match s.content {
            TitleContent::None => None,
            TitleContent::IdentityPlate => Some(IdentityPlate {
                enabled: true,
                text: plate.text.clone(),
                image: plate.image.clone(),
                size: s.scale,
                color: colour(plate.color),
                opacity: plate.opacity,
                place: centre,
                behind: false,
            }),
            TitleContent::Text => Some(IdentityPlate {
                enabled: true,
                text: s.text.clone(),
                image: String::new(),
                size: s.scale,
                color: colour(plate.color),
                opacity: 1.0,
                place: centre,
                behind: false,
            }),
        };
        let mut compose = TitleCompose { title, settings, overlays: None, width, height };
        if let Some(p) = shown.filter(|p| !p.text.trim().is_empty() || !p.image.trim().is_empty()) {
            let resolved =
                |p: IdentityPlate| Arc::new(SlideOverlays::resolve(&OverlaySettings { identity_plate: p, ..OverlaySettings::default() }, None));
            compose.overlays = Some(resolved(p.clone()));
            // a long text (or a wide logo) at a large scale: shrink it to fit the slide's width
            if let Some(b) = compose.plate_box() {
                let max = FIT_WIDTH * compose.layout().slide.width();
                if b.width() > max && b.width() > 0.0 {
                    let size = (p.size * max / b.width()).max(SIZE_MIN);
                    compose.overlays = Some(resolved(IdentityPlate { size, ..p }));
                }
            }
        }
        compose
    }

    fn layout(&self) -> Layout {
        lightcraft_slideshow::layout(&self.settings, 1.0, self.width, self.height)
    }

    /// Where the plate or text is on the screen (`None`: nothing is drawn but the colour).
    pub fn plate_box(&self) -> Option<Rect> {
        let o = self.overlays.as_ref()?;
        o.boxes(&self.layout()).into_iter().next().map(|(_, r)| r)
    }

    /// What makes the screen's pixels differ (for render keys).
    pub fn key(&self) -> u64 {
        use std::hash::{Hash, Hasher};
        let mut h = std::collections::hash_map::DefaultHasher::new();
        "title".hash(&mut h);
        self.title.hash(&mut h);
        self.settings.pixel_key().hash(&mut h);
        self.overlays.as_ref().map(|o| o.key()).hash(&mut h);
        (self.width, self.height).hash(&mut h);
        h.finish()
    }

    /// The screen's pixels.
    pub fn compose(&self) -> Rgba8 {
        let empty = Rgba8::new(0, 0);
        let (mut img, l) = lightcraft_slideshow::compose_with(&empty, None, &self.settings, self.width, self.height, &mut |_, _| {});
        if let Some(o) = &self.overlays {
            o.draw_front(&mut img, &l);
        }
        img
    }

    /// [`Self::compose`] as a render result (for a frontend's render queue): request `request_id`,
    /// under this screen's key. Title screens show no photo (`photo` is 0).
    pub fn result(&self, request_id: u64) -> crate::media::RenderResult {
        let image = self.compose();
        let histogram = lightcraft_raster::Histogram::of_srgb8(&image);
        crate::media::RenderResult {
            request_id,
            source_key: None,
            photo: lightcraft_catalog::PhotoId(0),
            level: crate::media::SourceLevel::Preview,
            key: self.key(),
            rendered: Ok(lightcraft_pipeline::Rendered { image, histogram, deep: None }),
            loaded: None,
            quick: None,
            display: None,
            gpu_fallback: None,
            frame: None,
        }
    }
}

impl crate::Session {
    /// Title screen `title` at `width × height` with the library's titles and identity plate.
    pub fn title_compose(&self, title: Title, width: usize, height: usize) -> Arc<TitleCompose> {
        Arc::new(TitleCompose::new(&self.slide_titles, &self.slide_overlays, title, width, height))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn at(img: &Rgba8, x: usize, y: usize) -> [u8; 3] {
        let p = img.get(x, y);
        [p[0], p[1], p[2]]
    }

    /// The bounding box of the pixels that differ from `bg` (x0, y0, x1, y1).
    fn ink(img: &Rgba8, bg: [u8; 3]) -> Option<(usize, usize, usize, usize)> {
        let mut b: Option<(usize, usize, usize, usize)> = None;
        for y in 0..img.height {
            for x in 0..img.width {
                let c = at(img, x, y);
                if c.iter().zip(bg).any(|(a, b)| a.abs_diff(b) > 40) {
                    b = Some(match b {
                        None => (x, y, x + 1, y + 1),
                        Some((x0, y0, x1, y1)) => (x0.min(x), y0.min(y), x1.max(x + 1), y1.max(y + 1)),
                    });
                }
            }
        }
        b
    }

    fn text_titles(scale: f64) -> TitleSettings {
        TitleSettings::default()
            .merged(&json!({"intro": {"enabled": true, "color": "#203040", "content": "text", "text": "Holiday", "overrideColor": true, "textColor": "#ffcc00", "scale": scale}}))
            .unwrap()
    }

    #[test]
    fn a_text_title_is_centred_in_its_colours_and_scales_with_the_slide() {
        let o = OverlaySettings::default();
        let t = text_titles(0.2);
        let mut boxes = Vec::new();
        for (w, h) in [(400, 250), (800, 500)] {
            let c = TitleCompose::new(&t, &o, Title::Intro, w, h);
            let img = c.compose();
            assert_eq!((img.width, img.height), (w, h));
            assert_eq!(at(&img, 2, 2), [0x20, 0x30, 0x40], "the title's colour");
            let (x0, y0, x1, y1) = ink(&img, [0x20, 0x30, 0x40]).expect("the text is drawn");
            // centred (glyph ink sits inside the line box, so allow some slack vertically)
            let (cx, cy) = ((x0 + x1) as f64 / 2.0, (y0 + y1) as f64 / 2.0);
            assert!((cx - w as f64 / 2.0).abs() < w as f64 * 0.03, "centred across: {cx} of {w}");
            assert!((cy - h as f64 / 2.0).abs() < h as f64 * 0.06, "centred down: {cy} of {h}");
            let mid = at(&img, (x0..x1).find(|x| at(&img, *x, (y0 + y1) / 2) != [0x20, 0x30, 0x40]).unwrap_or(x0), (y0 + y1) / 2);
            assert!(mid[0] > 150 && mid[2] < 120, "drawn in the text colour: {mid:?}");
            boxes.push(((x1 - x0) as f64 / w as f64, (y1 - y0) as f64 / h as f64));
            let b = c.plate_box().unwrap();
            assert!((b.height() - 0.2 * h as f64).abs() < 2.0, "the scale is the line height: {b:?}");
        }
        let ((w1, h1), (w2, h2)) = (boxes[0], boxes[1]);
        assert!((w1 - w2).abs() < 0.02 && (h1 - h2).abs() < 0.02, "proportional at two sizes: {boxes:?}");
        // a bigger scale draws bigger text
        let big = ink(&TitleCompose::new(&text_titles(0.3), &o, Title::Intro, 800, 500).compose(), [0x20, 0x30, 0x40]).unwrap();
        assert!((big.2 - big.0) as f64 / 800.0 > w2 * 1.3);
    }

    #[test]
    fn the_identity_plate_shows_in_its_own_colour_unless_overridden() {
        let o = OverlaySettings::default()
            .merged(&json!({"identityPlate": {"text": "Studio", "color": "#00ff00", "opacity": 1, "anchor": "topLeft"}}))
            .unwrap();
        assert!(!o.identity_plate.enabled, "the overlay plate itself may be off");
        let t = TitleSettings::default().merged(&json!({"ending": {"enabled": true, "color": "#000000", "scale": 0.15}})).unwrap();
        let img = TitleCompose::new(&t, &o, Title::Ending, 600, 400).compose();
        let (x0, y0, x1, y1) = ink(&img, [0, 0, 0]).expect("the plate is drawn");
        assert!(x0 > 100 && x1 < 500 && y0 > 120 && y1 < 280, "centred, not at the overlay's anchor: {:?}", (x0, y0, x1, y1));
        let greens = (y0..y1).flat_map(|y| (x0..x1).map(move |x| (x, y))).filter(|&(x, y)| {
            let c = at(&img, x, y);
            c[1] > 200 && c[0] < 60
        });
        assert!(greens.count() > 100, "in the plate's colour");
        let over = t.merged(&json!({"ending": {"overrideColor": true, "textColor": "#ff0000"}})).unwrap();
        let img = TitleCompose::new(&over, &o, Title::Ending, 600, 400).compose();
        let reds = img.data.iter().filter(|p| p[0] > 200 && p[1] < 60).count();
        assert!(reds > 100, "overridden");
        // the colour alone
        let none = t.merged(&json!({"ending": {"content": "none", "color": "#123456"}})).unwrap();
        let c = TitleCompose::new(&none, &o, Title::Ending, 64, 40);
        assert!(c.plate_box().is_none());
        assert!(c.compose().data.iter().all(|p| p[..3] == [0x12, 0x34, 0x56]));
    }

    #[test]
    fn a_missing_plate_image_draws_the_colour_and_is_reported() {
        let o = OverlaySettings::default().merged(&json!({"identityPlate": {"image": "/no/such/logo.png"}})).unwrap();
        let t = TitleSettings::default().merged(&json!({"intro": {"enabled": true, "color": "#336699"}})).unwrap();
        let c = TitleCompose::new(&t, &o, Title::Intro, 120, 80);
        assert!(c.compose().data.iter().all(|p| p[..3] == [0x33, 0x66, 0x99]));
        let w = t.warnings(&o);
        assert!(w.iter().any(|w| w.contains("intro") && w.contains("can't be read")), "{w:?}");
        let t = t.merged(&json!({"intro": {"content": "text", "text": "  "}})).unwrap();
        assert!(t.warnings(&o).iter().any(|w| w.contains("no text")));
    }

    #[test]
    fn long_text_is_scaled_down_to_fit_the_width() {
        let t = TitleSettings::default()
            .merged(&json!({"intro": {"enabled": true, "content": "text", "text": "A very long title that would never fit across", "scale": 0.5}}))
            .unwrap();
        let c = TitleCompose::new(&t, &OverlaySettings::default(), Title::Intro, 800, 450);
        let b = c.plate_box().unwrap();
        assert!(b.width() <= 800.0 * FIT_WIDTH + 2.0 && b.x0 >= 0.0, "{b:?}");
    }

    #[test]
    fn settings_are_validated_clamped_and_round_trip() {
        let d = TitleSettings::default();
        assert!(!d.intro.enabled && !d.ending.enabled, "off by default");
        assert_eq!(d.durations(4.0), (None, None));
        for bad in [
            json!({"intro": {"enabled": 1}}),
            json!({"intro": {"color": "#12"}}),
            json!({"ending": {"content": "video"}}),
            json!({"ending": {"scale": "big"}}),
            json!({"ending": {"duration": "long"}}),
            json!({"intro": {"sparkle": true}}),
            json!({"intro": []}),
            json!({"credits": {}}),
            json!({"INTRO": {}}),
            json!([1]),
        ] {
            assert!(d.merged(&bad).is_err(), "{bad}");
        }
        let s = d
            .merged(&json!({"intro": {"enabled": true, "scale": 9, "duration": 1e9}, "ending": {"enabled": true, "scale": -1, "duration": 0}}))
            .unwrap();
        assert_eq!((s.intro.scale, s.ending.scale), (PLATE_SIZE_MAX, SIZE_MIN));
        assert_eq!((s.intro.duration, s.ending.duration), (Some(crate::slideshow::SLIDE_MAX), Some(crate::slideshow::SLIDE_MIN)));
        assert_eq!(s.durations(4.0), (Some(crate::slideshow::SLIDE_MAX), Some(crate::slideshow::SLIDE_MIN)));
        let s = s.merged(&json!({"intro": {"duration": null}})).unwrap();
        assert_eq!(s.durations(4.0).0, Some(4.0), "null: the slide duration");
        assert_eq!(d.merged(&s.to_json()).unwrap(), s, "the JSON form reads back");
        let back: TitleSettings = serde_json::from_str(&serde_json::to_string(&s).unwrap()).unwrap();
        assert_eq!(back, s);
        let partial: TitleSettings = serde_json::from_str(r#"{"ending": {"enabled": true}}"#).unwrap();
        assert!(partial.ending.enabled && !partial.intro.enabled);
        // NaN / ∞ from a hand-edited file
        let s = TitleSettings { intro: TitleScreen { scale: f64::NAN, duration: Some(f64::INFINITY), ..d.intro.clone() }, ..d.clone() }.sanitized();
        assert_eq!((s.intro.scale, s.intro.duration), (0.1, None));
        // any size composes
        for (w, h) in [(0, 0), (1, 100_000), (usize::MAX, 3)] {
            let c = TitleCompose::new(&text_titles(0.5), &OverlaySettings::default(), Title::Intro, w, h);
            let img = c.compose();
            assert!(img.width >= 1 && img.height >= 1 && img.width <= lightcraft_slideshow::MAX_SIDE);
        }
    }
}