write_gradient.rs

//! Paints axial, radial and function-based gradients, each into a clipped box.
//!
//! Five panels: a horizontal two-colour gradient, a diagonal one, a radial one
//! whose outer colour is extended to fill the corners, a three-stop gradient
//! built from a stitched function, and a checkerboard whose colour is read from
//! a calculation of both coordinates of the point, the reader asked to filter
//! its sudden colour steps against aliasing. Each is added to the document
//! once, then painted into a rectangle the page clips to.
//!
//! The title and the five labels are held in `Words`, once per language, and
//! `HQF_PDF_LANG` picks which set is drawn.
//!
//! Usage: `cargo run --example write_gradient -- tmp/gradient.pdf [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_gradient -- tmp/degrade.pdf`

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

use hqf_pdf::content::Content;
use hqf_pdf::shading::FunctionBased;
use hqf_pdf::{
    Axial, Calculation, DeviceSpace, Document, Exponential, ExtendEnds, Font, FontHandle, Op, Page,
    Radial, Rgb, Shading, ShadingHandle, Stitching,
};

#[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.
fn default_font() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("fonts")
        .join("DejaVuSans.ttf")
}

/// The words the page is written in, one set per language.
#[derive(Debug)]
struct Words {
    /// The title across the top of the page.
    title: &'static str,
    /// The label under each of the five panels.
    horizontal: &'static str,
    diagonal: &'static str,
    radial: &'static str,
    three_stops: &'static str,
    checkerboard: &'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 {
    title: "Gradients, and a colour read from a function",
    horizontal: "Axial, two colours",
    diagonal: "Axial, on the diagonal",
    radial: "Radial, outer extended",
    three_stops: "Axial, three stops",
    checkerboard: "Function-based: a checkerboard on x and y at once, anti-aliasing asked for",
};

/// The page in French.
const FRENCH: Words = Words {
    title: "Dégradés, et une couleur lue dans une fonction",
    horizontal: "En ligne droite, deux couleurs",
    diagonal: "En ligne droite, en diagonale",
    radial: "En cercle, couleur extérieure prolongée",
    three_stops: "En ligne droite, trois couleurs",
    checkerboard: "Par fonction : un damier en largeur et en hauteur à la fois, anticrénelage demandé",
};

/// 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); 2] =
    [(Language::English, &ENGLISH), (Language::French, &FRENCH)];

/// The width and height of every panel, in points.
const BOX: (f64, f64) = (210.0, 170.0);

/// How many squares the checkerboard is cut into along each of its two axes.
const SQUARES: f64 = 8.0;

/// How much of the colour it lands on a darkened square of the checkerboard
/// keeps.
const SHADED: f64 = 0.45;

/// Paints a gradient into the box at `(x, y)`, sized [`BOX`], and writes a
/// label under it.
fn panel(
    content: &mut Content,
    font: &FontHandle,
    shading: &ShadingHandle,
    x: f64,
    y: f64,
    label: &str,
) -> Result<(), hqf_pdf::Error> {
    content.save_state();
    content.rect(x, y, BOX.0, BOX.1)?.clip().end_path();
    content.draw_shading(shading);
    content.restore_state();

    content.begin_text();
    content.set_font(font, 10.0)?;
    content.text_origin(x, y - 15.0)?;
    content.show_glyphs(&font.glyphs(label));
    content.end_text();
    Ok(())
}

/// The gradient that paints a checkerboard into the box at `(x, y)`, sized
/// [`BOX`], its colour read from a calculation of both coordinates of the point
/// at once: red grows across the box, green grows up it, and every other square
/// of the [`SQUARES`] by [`SQUARES`] board keeps only [`SHADED`] of the colour
/// it lands on. The reader is asked to filter the sudden steps between squares
/// against aliasing.
fn checkerboard(x: f64, y: f64) -> Result<Shading, hqf_pdf::Error> {
    Ok(Shading::from(
        FunctionBased::new(
            [[0.0, 1.0], [0.0, 1.0]],
            [BOX.0, 0.0, 0.0, BOX.1, x, y],
            DeviceSpace::Rgb,
            Calculation::new(
                [[0.0, 1.0], [0.0, 1.0]],
                [[0.0, 1.0]; 3],
                vec![
                    Op::Integer(2),
                    Op::Copy,
                    Op::Real(SQUARES),
                    Op::Multiply,
                    Op::Floor,
                    Op::Exchange,
                    Op::Real(SQUARES),
                    Op::Multiply,
                    Op::Floor,
                    Op::Add,
                    Op::ToInteger,
                    Op::Integer(2),
                    Op::Modulo,
                    Op::Integer(0),
                    Op::NotEqual,
                    Op::Integer(3),
                    Op::Integer(1),
                    Op::Roll,
                    Op::Real(0.2),
                    Op::Integer(4),
                    Op::Integer(3),
                    Op::Roll,
                    Op::If(vec![
                        Op::Real(SHADED),
                        Op::Multiply,
                        Op::Integer(3),
                        Op::Integer(1),
                        Op::Roll,
                        Op::Real(SHADED),
                        Op::Multiply,
                        Op::Integer(3),
                        Op::Integer(1),
                        Op::Roll,
                        Op::Real(SHADED),
                        Op::Multiply,
                        Op::Integer(3),
                        Op::Integer(1),
                        Op::Roll,
                    ]),
                ],
            ),
        )?
        .anti_alias(true),
    ))
}

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("gradient")));
    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);

    // Left column x, right column x, then the foot of each of the three rows.
    let (left, right, top, middle, bottom) = (70.0, 315.0, 560.0, 320.0, 100.0);

    // A horizontal two-colour gradient across the top-left box.
    let horizontal = doc.add_shading(&Shading::from(Axial::rgb(
        (left, top),
        (left + BOX.0, top),
        Rgb::new(0.85, 0.12, 0.12),
        Rgb::new(0.12, 0.2, 0.8),
    )))?;

    // A diagonal two-colour gradient across the top-right box.
    let diagonal = doc.add_shading(&Shading::from(Axial::rgb(
        (right, middle + BOX.1),
        (right + BOX.0, top + BOX.1),
        Rgb::new(0.95, 0.8, 0.1),
        Rgb::new(0.1, 0.55, 0.2),
    )))?;

    // A radial gradient in the middle-left box, its outer colour extended so it
    // reaches the corners.
    let radial = doc.add_shading(&Shading::from(
        Radial::rgb(
            (left + BOX.0 / 2.0, middle + BOX.1 / 2.0, 0.0),
            (left + BOX.0 / 2.0, middle + BOX.1 / 2.0, BOX.0 / 2.0),
            Rgb::new(1.0, 1.0, 1.0),
            Rgb::new(0.1, 0.15, 0.45),
        )
        .extend(ExtendEnds {
            before: false,
            after: true,
        }),
    ))?;

    // A three-stop gradient in the middle-right box, from a stitched function:
    // red to green over the first half, green to blue over the second.
    let rainbow_function = Stitching::new(
        [0.0, 1.0],
        vec![
            Exponential::new([0.0, 1.0], 1.0)
                .endpoints(vec![0.85, 0.12, 0.12], vec![0.12, 0.6, 0.2])
                .into(),
            Exponential::new([0.0, 1.0], 1.0)
                .endpoints(vec![0.12, 0.6, 0.2], vec![0.12, 0.2, 0.8])
                .into(),
        ],
        vec![0.5],
        vec![[0.0, 1.0], [0.0, 1.0]],
    );
    let rainbow = doc.add_shading(&Shading::from(Axial::new(
        (right, middle),
        (right + BOX.0, middle),
        DeviceSpace::Rgb,
        rainbow_function,
    )?))?;

    // A checkerboard across the bottom-left box.
    let board = doc.add_shading(&checkerboard(left, bottom)?)?;

    let mut content = Content::new();

    content.begin_text();
    content.set_font(&handle, 18.0)?;
    content.text_origin(left, 770.0)?;
    content.show_glyphs(&handle.glyphs(words.title));
    content.end_text();

    panel(
        &mut content,
        &handle,
        &horizontal,
        left,
        top,
        words.horizontal,
    )?;
    panel(&mut content, &handle, &diagonal, right, top, words.diagonal)?;
    panel(&mut content, &handle, &radial, left, middle, words.radial)?;
    panel(
        &mut content,
        &handle,
        &rainbow,
        right,
        middle,
        words.three_stops,
    )?;
    panel(
        &mut content,
        &handle,
        &board,
        left,
        bottom,
        words.checkerboard,
    )?;

    let mut page = Page::a4();
    page.content = content.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(())
}

#[cfg(test)]
mod tests {
    use super::{WORDS, 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:?}"
        );
    }
}