write_transparency.rs

//! Shows three things an extended graphics state opens: half-opacity fills that
//! overlap and mix, one colour laid over another in four blend modes, and
//! overlapping letters of one text object knocked out or composited.
//!
//! The opacity panel draws three rectangles, each at half opacity, so the
//! colours show through one another where they overlap. The blend panel lays
//! the same orange square over a blue bar four times, once in each of four
//! modes, so the mode each square is painted in can be read from the colour it
//! leaves. The knockout panel sets the same line twice at half opacity, each
//! letter crossed by a stroke that overlaps it: under `TK true` the text object
//! is painted as one and the overlaps come out as light as the rest, under `TK
//! false` each glyph is composited on its own and the overlaps come out darker.
//! A reader that ignores the flag shows the two lines alike.
//!
//! The second page lays the same square over the same bar in the twelve other
//! blend modes, then strokes a wide line at half opacity across a fill, once
//! read as an opacity and once as a shape: the two look alike on a page, and
//! only a knockout group tells them apart.
//!
//! The five headings are held in `Words`, once per language, and `HQF_PDF_LANG`
//! picks which set is drawn. Each square is labelled with the name the file
//! writes for its blend mode, and each line with the entry its state writes,
//! which are the same in every language.
//!
//! Usage: `cargo run --example write_transparency -- tmp/transparency.pdf
//! [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_transparency --
//! tmp/transparence.pdf`

use std::env;
use std::fs;
use std::path::{Path, PathBuf};

use hqf_pdf::content::Content;
use hqf_pdf::{BlendMode, Document, ExtGState, Font, GStateHandle, Page, Rgb, TextFlow};

#[path = "shared/out.rs"]
mod out;

#[path = "shared/licence.rs"]
mod licence;

#[path = "shared/language.rs"]
mod language;

#[path = "shared/failure.rs"]
mod failure;

use language::Language;

/// The font the example draws with when none is given on the command line: the
/// one committed for the tests, so that the example runs on any machine.
fn default_font() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("fonts")
        .join("DejaVuSans.ttf")
}

/// The left edge the panels line up on.
const X: f64 = 80.0;

/// The line the knockout panel sets twice: each letter followed by a combining
/// stroke that takes no room of its own, so the stroke lies across the letter.
const CROSSED: &str = "O\u{338}O\u{338}O\u{338}O\u{338}";

/// The words the page is written in, one set per language.
///
/// What is not language stays out of it: each square is labelled with the name
/// the file writes for its blend mode, and each crossed line with the entry its
/// state writes.
#[derive(Debug)]
struct Words {
    /// The heading above the opacity panel.
    opacity: &'static str,
    /// The heading above the blend panel.
    blends: &'static str,
    /// The heading above the knockout panel.
    knockout: &'static str,
    /// The heading above the second page's blend panel.
    more_blends: &'static str,
    /// The heading above the stroke panel.
    strokes: &'static str,
}

impl Words {
    /// The words the page is written in, in `language`.
    fn of(language: Language) -> &'static Self {
        language::pick(&WORDS, language)
    }
}

/// The page in English.
const ENGLISH: Words = Words {
    opacity: "Half-opacity fills overlap and mix.",
    blends: "One orange square over a blue bar, in four blend modes.",
    knockout: "Overlapping letters at half opacity: knocked out on the left, composited with one another on the right.",
    more_blends: "The same orange square over the same blue bar, in the twelve other blend modes.",
    strokes: "A wide stroke at half opacity over a fill: an opacity on the left, a shape on the right.",
};

/// The page in French.
const FRENCH: Words = Words {
    opacity: "Des aplats à moitié transparents se chevauchent et se mélangent.",
    blends: "Un carré orange sur une barre bleue, dans quatre modes de fusion.",
    knockout: "Des lettres qui se chevauchent, à moitié transparentes : en défonce à gauche, \
mélangées entre elles à droite.",
    more_blends: "Le même carré orange sur la même barre bleue, dans les douze autres modes de fusion.",
    strokes: "Un trait épais à demi transparent sur un aplat : opacité à gauche, forme à droite.",
};

/// The page in Dutch.
const DUTCH: Words = Words {
    opacity: "Vullingen op halve dekking overlappen en mengen.",
    blends: "Eén oranje vierkant over een blauwe balk, in vier overvloeimodi.",
    knockout: "Overlappende letters op halve dekking: links uitgespaard, rechts met elkaar samengesteld.",
    more_blends: "Hetzelfde oranje vierkant over dezelfde blauwe balk, in de twaalf andere overvloeimodi.",
    strokes: "Een brede lijn op halve dekking over een vulling: links een dekking, rechts een vorm.",
};

/// The page in Portuguese.
const PORTUGUESE: Words = Words {
    opacity: "Preenchimentos a meia opacidade sobrepõem-se e misturam-se.",
    blends: "Um quadrado laranja sobre uma barra azul, em quatro modos de mistura.",
    knockout: "Letras sobrepostas a meia opacidade: excluídas à esquerda, compostas entre si à direita.",
    more_blends: "O mesmo quadrado laranja sobre a mesma barra azul, nos outros doze modos de mistura.",
    strokes: "Traço largo semiopaco sobre um fundo: uma opacidade à esquerda, uma forma à direita.",
};

/// The page in Italian.
const ITALIAN: Words = Words {
    opacity: "Riempimenti a metà opacità si sovrappongono e si mescolano.",
    blends: "Un quadrato arancione su una barra blu, in quattro metodi di fusione.",
    knockout: "Lettere sovrapposte a metà opacità: escluse a sinistra, composte tra loro a destra.",
    more_blends: "Lo stesso quadrato arancione sulla stessa barra blu, negli altri dodici metodi di fusione.",
    strokes: "Un tratto largo a metà opacità su un riempimento: un’opacità a sinistra, una forma a destra.",
};

/// The page in Spanish.
const SPANISH: Words = Words {
    opacity: "Rellenos a media opacidad se superponen y se mezclan.",
    blends: "Un cuadrado naranja sobre una barra azul, en cuatro modos de fusión.",
    knockout: "Letras superpuestas a media opacidad: excluidas a la izquierda, compuestas entre sí a la derecha.",
    more_blends: "El mismo cuadrado naranja sobre la misma barra azul, en los otros doce modos de fusión.",
    strokes: "Trazo ancho semiopaco sobre un relleno: una opacidad a la izquierda, una forma a la derecha.",
};

/// The page in German.
const GERMAN: Words = Words {
    opacity: "Halbdeckende Flächen überlappen und mischen sich.",
    blends: "Ein orangefarbenes Quadrat über einem blauen Balken, in vier Mischmodi.",
    knockout: "Überlappende Buchstaben mit halber Deckkraft: links ausgespart, rechts miteinander verrechnet.",
    more_blends: "Dasselbe orangefarbene Quadrat über demselben blauen Balken, in den zwölf anderen Mischmodi.",
    strokes: "Ein breiter Strich mit halber Deckkraft über einer Fläche: links eine Deckkraft, rechts eine Form.",
};

/// Every language the example is written in. A language is added by writing its
/// own set of words and naming it here.
static WORDS: [(Language, &Words); 7] = [
    (Language::English, &ENGLISH),
    (Language::French, &FRENCH),
    (Language::German, &GERMAN),
    (Language::Spanish, &SPANISH),
    (Language::Italian, &ITALIAN),
    (Language::Portuguese, &PORTUGUESE),
    (Language::Dutch, &DUTCH),
];

fn main() -> std::process::ExitCode {
    failure::reported(run())
}

fn run() -> Result<(), Box<dyn std::error::Error>> {
    let language = Language::from_environment()?;
    let words = Words::of(language);

    let mut args = env::args().skip(1);
    // A named file is written as named; the default one carries the language,
    // so the two languages do not overwrite each other in `tmp/`.
    let out = args
        .next()
        .unwrap_or_else(|| language.file_name(&out::default_path("transparency")));
    let font_path = args.next().map_or_else(default_font, PathBuf::from);

    let font = Font::parse(fs::read(&font_path)?)?;
    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    let handle = doc.add_font(font);

    // The states the three panels apply, added once and shared.
    let half = doc.add_ext_gstate(ExtGState::new().fill_alpha(0.5));
    let modes = [
        ("Normal", BlendMode::Normal),
        ("Multiply", BlendMode::Multiply),
        ("Screen", BlendMode::Screen),
        ("Difference", BlendMode::Difference),
    ];
    let blends: Vec<(&str, GStateHandle)> = modes
        .into_iter()
        .map(|(label, mode)| (label, doc.add_ext_gstate(ExtGState::new().blend_mode(mode))))
        .collect();
    let knockouts = [
        (
            "TK true",
            doc.add_ext_gstate(ExtGState::new().fill_alpha(0.5).text_knockout(true)),
        ),
        (
            "TK false",
            doc.add_ext_gstate(ExtGState::new().fill_alpha(0.5).text_knockout(false)),
        ),
    ];

    let mut c = Content::new();

    // The opacity panel: three overlapping rectangles, each at half opacity.
    heading(&mut c, &handle, 720.0, words.opacity, X)?;
    let colors = [
        (0.0, Rgb::new(0.85, 0.15, 0.15)),
        (30.0, Rgb::new(0.15, 0.65, 0.20)),
        (60.0, Rgb::new(0.15, 0.30, 0.85)),
    ];
    for (offset, color) in colors {
        c.save_state().set_ext_gstate(&half).set_fill(color)?;
        c.rect(X + offset, 590.0, 90.0, 90.0)?.fill();
        c.restore_state();
    }

    // The blend panel: an orange square over a blue bar, once per mode.
    heading(&mut c, &handle, 520.0, words.blends, X)?;
    let square = 80.0;
    let gap = 20.0;
    let mut left = X;
    for (label, state) in &blends {
        c.set_fill(Rgb::new(0.15, 0.35, 0.80))?
            .rect(left, 380.0, square, square)?
            .fill();
        c.save_state()
            .set_ext_gstate(state)
            .set_fill(Rgb::new(0.95, 0.55, 0.10))?;
        c.rect(left + 20.0, 360.0, square, square)?.fill();
        c.restore_state();
        heading(&mut c, &handle, 350.0, label, left)?;
        left += square + gap;
    }

    // The knockout panel: the crossed line twice, the state applied before the
    // text object opens, since a text object reads the flag as it begins.
    heading(&mut c, &handle, 300.0, words.knockout, X)?;
    let crossed = TextFlow::new(&handle, 48.0).color(Rgb::new(0.15, 0.30, 0.85));
    let lines = crossed.break_lines(CROSSED, 200.0);
    let mut left = X;
    for (label, state) in &knockouts {
        c.save_state().set_ext_gstate(state);
        c.begin_text();
        crossed.draw(&mut c, &lines, left, 280.0, 200.0)?;
        c.end_text();
        c.restore_state();
        heading(&mut c, &handle, 210.0, label, left)?;
        left += 200.0;
    }

    let mut page = Page::a4();
    page.content = c.into_bytes();
    doc.add_page(page)?;

    let mut page = Page::a4();
    page.content = second_page(&mut doc, &handle, words)?.into_bytes();
    doc.add_page(page)?;

    let bytes = doc.to_bytes()?;
    if let Some(parent) = Path::new(&out).parent() {
        fs::create_dir_all(parent)?;
    }
    fs::write(&out, &bytes)?;
    println!("wrote {out}: {} bytes", bytes.len());
    Ok(())
}

/// The second page: the twelve other blend modes, four to a row, and a wide
/// stroke at half opacity read two ways.
fn second_page(
    doc: &mut Document,
    handle: &hqf_pdf::FontHandle,
    words: &Words,
) -> Result<Content, Box<dyn std::error::Error>> {
    let modes = [
        ("Overlay", BlendMode::Overlay),
        ("Darken", BlendMode::Darken),
        ("Lighten", BlendMode::Lighten),
        ("ColorDodge", BlendMode::ColorDodge),
        ("ColorBurn", BlendMode::ColorBurn),
        ("HardLight", BlendMode::HardLight),
        ("SoftLight", BlendMode::SoftLight),
        ("Exclusion", BlendMode::Exclusion),
        ("Hue", BlendMode::Hue),
        ("Saturation", BlendMode::Saturation),
        ("Color", BlendMode::Color),
        ("Luminosity", BlendMode::Luminosity),
    ];
    let strokes = [
        ("CA 0.5", ExtGState::new().stroke_alpha(0.5)),
        (
            "CA 0.5 AIS true",
            ExtGState::new().stroke_alpha(0.5).alpha_is_shape(true),
        ),
    ];

    let mut c = Content::new();
    heading(&mut c, handle, 780.0, words.more_blends, X)?;
    let square = 80.0;
    let gap = 20.0;
    let mut bottom = 640.0;
    for row in modes.chunks(4) {
        let mut left = X;
        for (label, mode) in row {
            let state = doc.add_ext_gstate(ExtGState::new().blend_mode(*mode));
            c.set_fill(Rgb::new(0.15, 0.35, 0.80))?
                .rect(left, bottom + 20.0, square, square)?
                .fill();
            c.save_state()
                .set_ext_gstate(&state)
                .set_fill(Rgb::new(0.95, 0.55, 0.10))?;
            c.rect(left + 20.0, bottom, square, square)?.fill();
            c.restore_state();
            heading(&mut c, handle, bottom - 10.0, label, left)?;
            left += square + gap;
        }
        bottom -= 150.0;
    }

    heading(&mut c, handle, 260.0, words.strokes, X)?;
    let mut left = X;
    for (label, state) in strokes {
        let state = doc.add_ext_gstate(state);
        c.set_fill(Rgb::new(0.15, 0.35, 0.80))?
            .rect(left, 130.0, 160.0, 90.0)?
            .fill();
        c.save_state()
            .set_ext_gstate(&state)
            .set_stroke(Rgb::new(0.95, 0.55, 0.10))?
            .set_line_width(24.0)?;
        c.move_to(left - 10.0, 110.0)?
            .line_to(left + 170.0, 240.0)?
            .stroke();
        c.restore_state();
        heading(&mut c, handle, 95.0, label, left)?;
        left += 220.0;
    }
    Ok(c)
}

/// Sets a one-line label with its baseline at `top`, left edge at `left`.
fn heading(
    c: &mut Content,
    handle: &hqf_pdf::FontHandle,
    top: f64,
    label: &str,
    left: f64,
) -> Result<(), Box<dyn std::error::Error>> {
    let flow = TextFlow::new(handle, 8.0);
    let lines = flow.break_lines(label, 400.0);
    c.begin_text();
    flow.draw(c, &lines, left, top, 400.0)?;
    c.end_text();
    Ok(())
}

#[cfg(test)]
mod tests {
    use hqf_pdf::{Document, Font, TextFlow};

    use super::{WORDS, default_font, language};

    /// The lines two languages are allowed to write the same way. There are
    /// none: every word is a word of the language it is written in.
    const SPARED: [&str; 0] = [];

    #[test]
    fn every_language_draws_the_page_in_its_own_words() {
        let untranslated = language::untranslated_lines(&WORDS, &SPARED);

        assert!(
            untranslated.is_empty(),
            "the page says these in more than one language: {untranslated:?}"
        );
    }

    /// A heading of the second page that wrapped would set its second line over
    /// the panel under it.
    #[test]
    fn every_heading_of_the_second_page_takes_one_line() {
        let mut doc = Document::new();
        let font = Font::parse(std::fs::read(default_font()).expect("the committed font is there"))
            .expect("the committed font parses");
        let handle = doc.add_font(font);
        let flow = TextFlow::new(&handle, 8.0);

        for (_, words) in WORDS {
            for line in [words.more_blends, words.strokes] {
                assert_eq!(flow.break_lines(line, 400.0).len(), 1, "{line:?} wraps");
            }
        }
    }
}