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 clock;
17pub mod encode;
18pub mod frame;
19pub mod gif_export;
20pub mod palette;
21
22pub use atlas::GlyphAtlas;
23pub use bake::bake_static;
24pub use clock::Clock;
25pub use encode::{encode_png, save_png, to_rgba};
26pub use frame::{hero_time, render_frame, render_frame_clocked};
27pub use gif_export::{GifError, GifStats, Smoothness, encode_gif, frame_delays, valid_loop_ms};
28pub use palette::IndexedPalette;
29
30use clairlune_scene::activity::builtin_catalog;
31use clairlune_scene::{BuildError, BuildOptions, SceneGraph, SceneRecipe, build};
32use clairlune_sprites::{Character, builtin_character};
33use std::time::Instant;
34
35/// An image of palette indices, row-major.
36#[derive(Clone, Debug, PartialEq, Eq)]
37pub struct IndexedImage {
38    pub width: u32,
39    pub height: u32,
40    pub pixels: Vec<u8>,
41}
42
43impl IndexedImage {
44    pub fn new(width: u32, height: u32) -> Self {
45        Self {
46            width,
47            height,
48            pixels: vec![0; width as usize * height as usize],
49        }
50    }
51}
52
53/// A rendered still frame with everything needed to encode or inspect it.
54#[derive(Clone, Debug)]
55pub struct Still {
56    pub image: IndexedImage,
57    pub palette: IndexedPalette,
58    pub graph: SceneGraph,
59    /// The animation time that was rendered.
60    pub t_ms: u64,
61}
62
63/// Renders a recipe to a still frame at `t_ms`, or at the hero time when `None`.
64pub fn render_still(
65    recipe: &SceneRecipe,
66    opts: &BuildOptions,
67    t_ms: Option<u64>,
68) -> Result<Still, BuildError> {
69    let started = Instant::now();
70    let graph = build(recipe, opts)?;
71    if opts.buddy
72        && graph.character.is_some()
73        && let Some(a) = graph
74            .activity
75            .as_deref()
76            .and_then(|id| builtin_catalog().get(id))
77        && builtin_character()
78            .animation(&a.id, &a.animation.start)
79            .is_some_and(|an| an.name == "placeholder")
80    {
81        tracing::warn!(target: "clairlune_render", activity = %a.id, "no drawn art for this activity; drawing the placeholder character");
82    }
83    let atlas = GlyphAtlas::for_grid(&graph.grid);
84    let palette = IndexedPalette::new(&graph.family);
85    let background = bake_static(&graph, &atlas);
86    let t = t_ms.unwrap_or_else(|| hero_time(&graph));
87    let image = render_frame(&background, &graph, &atlas, &palette, t);
88    tracing::info!(
89        target: "clairlune_render",
90        seed = recipe.seed,
91        recipe_hash = %recipe.hash_hex(),
92        width = opts.width,
93        height = opts.height,
94        theme = opts.theme.as_str(),
95        buddy = opts.buddy,
96        t_ms = t,
97        palette = palette.len(),
98        elapsed_ms = started.elapsed().as_secs_f64() * 1e3,
99        "still rendered"
100    );
101    Ok(Still {
102        image,
103        palette,
104        graph,
105        t_ms: t,
106    })
107}