Skip to main content

clairlune_render/
lib.rs

1//! Rendering for Clairlune: glyph atlas, indexed palette, static bake, frame
2//! compositing and PNG export.
3//!
4//! Every pixel is a palette index. Colours are looked up, never blended at
5//! render time, so a scene has at most 255 colours (index 255 is reserved for GIF
6//! transparency) and the still PNG, GIF frames and the live renderer can match
7//! exactly (PLAN.md section 4.5).
8
9/// Compiles the README example as a doctest so it can't go stale.
10#[cfg(doctest)]
11#[doc = include_str!("../README.md")]
12struct ReadmeDoctests;
13
14pub mod atlas;
15pub mod bake;
16pub mod encode;
17pub mod frame;
18pub mod palette;
19
20pub use atlas::GlyphAtlas;
21pub use bake::bake_static;
22pub use encode::{encode_png, save_png, to_rgba};
23pub use frame::{hero_time, render_frame};
24pub use palette::IndexedPalette;
25
26use clairlune_scene::activity::builtin_catalog;
27use clairlune_scene::{BuildError, BuildOptions, SceneGraph, SceneRecipe, build};
28use clairlune_sprites::{Character, builtin_character};
29use std::time::Instant;
30
31/// An image of palette indices, row-major.
32#[derive(Clone, Debug, PartialEq, Eq)]
33pub struct IndexedImage {
34    pub width: u32,
35    pub height: u32,
36    pub pixels: Vec<u8>,
37}
38
39impl IndexedImage {
40    pub fn new(width: u32, height: u32) -> Self {
41        Self {
42            width,
43            height,
44            pixels: vec![0; width as usize * height as usize],
45        }
46    }
47}
48
49/// A rendered still frame with everything needed to encode or inspect it.
50#[derive(Clone, Debug)]
51pub struct Still {
52    pub image: IndexedImage,
53    pub palette: IndexedPalette,
54    pub graph: SceneGraph,
55    /// The animation time that was rendered.
56    pub t_ms: u64,
57}
58
59/// Renders a recipe to a still frame at `t_ms`, or at the hero time when `None`.
60pub fn render_still(
61    recipe: &SceneRecipe,
62    opts: &BuildOptions,
63    t_ms: Option<u64>,
64) -> Result<Still, BuildError> {
65    let started = Instant::now();
66    let graph = build(recipe, opts)?;
67    if opts.buddy
68        && graph.character.is_some()
69        && let Some(a) = graph
70            .activity
71            .as_deref()
72            .and_then(|id| builtin_catalog().get(id))
73        && builtin_character()
74            .animation(&a.id, &a.animation.start)
75            .is_some_and(|an| an.name == "placeholder")
76    {
77        tracing::warn!(target: "clairlune_render", activity = %a.id, "no drawn art for this activity; drawing the placeholder character");
78    }
79    let atlas = GlyphAtlas::for_grid(&graph.grid);
80    let palette = IndexedPalette::new(&graph.family);
81    let background = bake_static(&graph, &atlas);
82    let t = t_ms.unwrap_or_else(|| hero_time(&graph));
83    let image = render_frame(&background, &graph, &atlas, &palette, t);
84    tracing::info!(
85        target: "clairlune_render",
86        seed = recipe.seed,
87        recipe_hash = %recipe.hash_hex(),
88        width = opts.width,
89        height = opts.height,
90        theme = opts.theme.as_str(),
91        buddy = opts.buddy,
92        t_ms = t,
93        palette = palette.len(),
94        elapsed_ms = started.elapsed().as_secs_f64() * 1e3,
95        "still rendered"
96    );
97    Ok(Still {
98        image,
99        palette,
100        graph,
101        t_ms: t,
102    })
103}