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