Skip to main content

clairlune_render/
frame.rs

1//! Frame compositing: the baked background plus animated elements at time `t`.
2//! Particles snap to the cell grid (exact palette, small GIF diffs); sprites use
3//! integer nearest-neighbour scaling.
4//!
5//! The activity, character and prop art come through [`SceneArt`], so the same
6//! code plays live scenes (built-in art) and saved ones (their own copy).
7//!
8//! Every draw records the rectangle it writes, so [`IncrementalFrame`] can make
9//! the next frame from the last one by restoring and redrawing only those
10//! rectangles (the live wallpaper, PLAN.md section 5.3), and report what changed.
11
12use crate::IndexedImage;
13use crate::art::{BuiltinArt, SceneArt};
14use crate::atlas::GlyphAtlas;
15use crate::clock::{Clock, LoopScript, loop_track};
16use crate::palette::{IndexedPalette, LEVELS, ink_level};
17use clairlune_scene::anim::state_at;
18use clairlune_scene::graph::CHARACTER_BOX;
19use clairlune_scene::particles::{Preset, preset_particles};
20use clairlune_scene::{SceneGraph, SpriteInstance, SpriteKind};
21use clairlune_sprites::Frame;
22
23/// Composites one frame at `t_ms` over a baked background (live clock).
24pub fn render_frame(
25    background: &IndexedImage,
26    graph: &SceneGraph,
27    atlas: &GlyphAtlas,
28    palette: &IndexedPalette,
29    t_ms: u64,
30) -> IndexedImage {
31    render_frame_clocked(background, graph, atlas, palette, t_ms, Clock::Live)
32}
33
34/// Like [`render_frame`], with an explicit character clock: `Clock::Loop` makes
35/// the character follow the activity's loop script for a seamless GIF.
36pub fn render_frame_clocked(
37    background: &IndexedImage,
38    graph: &SceneGraph,
39    atlas: &GlyphAtlas,
40    palette: &IndexedPalette,
41    t_ms: u64,
42    clock: Clock,
43) -> IndexedImage {
44    let art = BuiltinArt::for_graph(graph);
45    render_frame_with_art(background, graph, atlas, palette, t_ms, clock, &art)
46}
47
48/// Composites one frame with the given art (built-in, or a saved scene's).
49pub fn render_frame_with_art(
50    background: &IndexedImage,
51    graph: &SceneGraph,
52    atlas: &GlyphAtlas,
53    palette: &IndexedPalette,
54    t_ms: u64,
55    clock: Clock,
56    art: &dyn SceneArt,
57) -> IndexedImage {
58    let mut img = background.clone();
59    let mut drawn = Vec::new();
60    compose(
61        &mut img, &mut drawn, graph, atlas, palette, t_ms, clock, art,
62    );
63    img
64}
65
66/// A rectangle of pixels, inside the image it belongs to.
67#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
68pub struct PixelRect {
69    pub x: u32,
70    pub y: u32,
71    pub w: u32,
72    pub h: u32,
73}
74
75impl PixelRect {
76    /// `[x0, x1) x [y0, y1)` clipped to a `width x height` image; `None` when
77    /// nothing is left.
78    fn clipped(x0: i32, y0: i32, x1: i32, y1: i32, width: u32, height: u32) -> Option<Self> {
79        let (x0, y0) = (x0.max(0), y0.max(0));
80        let (x1, y1) = (x1.min(width as i32), y1.min(height as i32));
81        (x1 > x0 && y1 > y0).then(|| PixelRect {
82            x: x0 as u32,
83            y: y0 as u32,
84            w: (x1 - x0) as u32,
85            h: (y1 - y0) as u32,
86        })
87    }
88
89    pub fn contains(&self, x: u32, y: u32) -> bool {
90        x >= self.x && x < self.x + self.w && y >= self.y && y < self.y + self.h
91    }
92}
93
94/// A frame kept between calls: each new time redraws only what the last
95/// frame and this one draw over the background. The image always equals
96/// [`render_frame_with_art`] at the last time given.
97#[derive(Clone, Debug)]
98pub struct IncrementalFrame {
99    image: IndexedImage,
100    /// What the frame drew over the background (restored before the next).
101    drawn: Vec<PixelRect>,
102}
103
104impl IncrementalFrame {
105    /// Starts as the bare background (nothing drawn yet).
106    pub fn new(background: &IndexedImage) -> Self {
107        IncrementalFrame {
108            image: background.clone(),
109            drawn: Vec::new(),
110        }
111    }
112
113    pub fn image(&self) -> &IndexedImage {
114        &self.image
115    }
116
117    /// Moves to `t_ms` and returns the rectangles whose pixels may have
118    /// changed (sorted, without repeats): the only ones a copy of the last
119    /// frame needs, such as a GPU texture.
120    #[allow(clippy::too_many_arguments)]
121    pub fn advance(
122        &mut self,
123        background: &IndexedImage,
124        graph: &SceneGraph,
125        atlas: &GlyphAtlas,
126        palette: &IndexedPalette,
127        t_ms: u64,
128        clock: Clock,
129        art: &dyn SceneArt,
130    ) -> Vec<PixelRect> {
131        debug_assert_eq!(
132            (background.width, background.height),
133            (self.image.width, self.image.height)
134        );
135        let w = self.image.width as usize;
136        for r in &self.drawn {
137            for y in r.y..r.y + r.h {
138                let a = y as usize * w + r.x as usize;
139                let b = a + r.w as usize;
140                self.image.pixels[a..b].copy_from_slice(&background.pixels[a..b]);
141            }
142        }
143        let mut drawn = Vec::with_capacity(self.drawn.len());
144        compose(
145            &mut self.image,
146            &mut drawn,
147            graph,
148            atlas,
149            palette,
150            t_ms,
151            clock,
152            art,
153        );
154        let mut changed: Vec<PixelRect> = self.drawn.iter().chain(&drawn).copied().collect();
155        changed.sort_unstable();
156        changed.dedup();
157        self.drawn = drawn;
158        changed
159    }
160}
161
162/// Draws the animated elements at `t_ms` over `img` (the background, or a
163/// frame restored to it) and records each rectangle written in `drawn`.
164#[allow(clippy::too_many_arguments)]
165fn compose(
166    img: &mut IndexedImage,
167    drawn: &mut Vec<PixelRect>,
168    graph: &SceneGraph,
169    atlas: &GlyphAtlas,
170    palette: &IndexedPalette,
171    t_ms: u64,
172    clock: Clock,
173    art: &dyn SceneArt,
174) {
175    for (col, row, p) in graph.particles_at(t_ms) {
176        draw_particle(
177            img, drawn, graph, atlas, col, row, p.glyph, p.level, p.ink, false,
178        );
179    }
180    for sprite in graph.sprites_at(t_ms) {
181        if sprite.kind == SpriteKind::Character {
182            let sprite = match (clock, graph.character) {
183                (Clock::Loop(loop_ms), Some(track)) => loop_track(track, loop_ms).at(t_ms),
184                _ => sprite,
185            };
186            if let Some(pose) = character_pose(graph, art, &sprite, t_ms, clock) {
187                // Effects go on top as an overlay (only the glyph's own pixels),
188                // so steam over a mug or sparkles over the hat stay visible.
189                draw_pose(img, drawn, &pose, palette);
190                draw_effects(img, drawn, graph, art, atlas, &pose, t_ms);
191            }
192            continue;
193        }
194        draw_sprite(img, drawn, &sprite, art, palette);
195    }
196}
197
198/// Draws a particle glyph in ember colour, or ink colour when `ink` (faint
199/// wisps such as steam). Normally it replaces its whole cell (background band,
200/// then the glyph); with `overlay` only the glyph's pixels are written.
201#[allow(clippy::too_many_arguments)]
202fn draw_particle(
203    img: &mut IndexedImage,
204    drawn: &mut Vec<PixelRect>,
205    graph: &SceneGraph,
206    atlas: &GlyphAtlas,
207    col: u32,
208    row: u32,
209    glyph: u8,
210    level: u8,
211    ink: bool,
212    overlay: bool,
213) {
214    let g = &graph.grid;
215    let shade =
216        ((u32::from(level.min(LEVELS)) * 255 + u32::from(LEVELS) / 2) / u32::from(LEVELS)) as u8;
217    let mask = atlas.mask(glyph);
218    let (x0, y0) = (g.origin_x + col * g.cell_w, g.origin_y + row * g.cell_h);
219    // Cells lie inside the image (the grid is laid out within it).
220    drawn.push(PixelRect {
221        x: x0,
222        y: y0,
223        w: g.cell_w,
224        h: g.cell_h,
225    });
226    let w = img.width as usize;
227    for my in 0..g.cell_h {
228        let y = y0 + my;
229        let rt = graph.lighting.row_terms(y);
230        for mx in 0..g.cell_w {
231            let x = x0 + mx;
232            let band = graph.lighting.band_in_row(&rt, x);
233            let lvl = ink_level(mask[(my * g.cell_w + mx) as usize], shade);
234            if overlay && lvl == 0 {
235                continue; // overlay: leave whatever is under the glyph
236            }
237            img.pixels[y as usize * w + x as usize] = match (lvl > 0, ink) {
238                (false, _) => band,
239                (true, false) => IndexedPalette::ember(band, lvl),
240                (true, true) => IndexedPalette::ink(band, lvl),
241            };
242        }
243    }
244}
245
246/// The still-frame time used for stills, thumbnails and the static wallpaper:
247/// the first moment at or after the scene's ember-based hero time (50 ms steps,
248/// up to 10 s) when the character shows the first frame of its activity's start
249/// state, so a still never catches a blink or a mid-gesture. Independent of the
250/// Buddy toggle, so toggling it keeps the same moment.
251pub fn hero_time(graph: &SceneGraph) -> u64 {
252    hero_time_with_art(graph, &BuiltinArt::for_graph(graph))
253}
254
255/// [`hero_time`] with the given art.
256pub fn hero_time_with_art(graph: &SceneGraph, art: &dyn SceneArt) -> u64 {
257    let base = graph.t_hero_ms;
258    let (Some(a), Some(_)) = (art.activity(), graph.character) else {
259        return base;
260    };
261    let character = art.character();
262    for k in 0..200u64 {
263        let t = base + k * 50;
264        let st = state_at(a, graph.seed, t, &|s| character.one_shot_ms(&a.id, s));
265        if st.state != a.animation.start {
266            continue;
267        }
268        let looping = a.animation.states.get(&st.state).is_some_and(|d| d.looping);
269        if let Some(anim) = character.animation(&a.id, &st.state)
270            && anim.frame_index_at(t - st.since_ms, looping) == 0
271        {
272            return t;
273        }
274    }
275    base
276}
277
278/// The character's current frame and where it sits on screen: the art's origin
279/// (feet row, body centre) aligned inside the layout box, mirrored when it faces
280/// left. All character art comes through `Character`.
281struct Pose<'a> {
282    frame: &'a Frame,
283    state: String,
284    /// Screen pixel of the origin pixel's top-left corner.
285    x0: i32,
286    y0: i32,
287    sc: i32,
288    mirror: bool,
289}
290
291impl Pose<'_> {
292    /// Screen position of the centre of frame pixel `(col, row)`.
293    fn screen(&self, col: i32, row: i32) -> (i32, i32) {
294        let (ox, oy) = self.frame.origin();
295        let dx = (col - ox) * if self.mirror { -1 } else { 1 };
296        (
297            self.x0 + dx * self.sc + self.sc / 2,
298            self.y0 + (row - oy) * self.sc + self.sc / 2,
299        )
300    }
301}
302
303/// Picks the frame for the activity state at `t` (state machine when live, the
304/// loop script when looping) and places it.
305fn character_pose<'a>(
306    graph: &SceneGraph,
307    art: &'a dyn SceneArt,
308    s: &SpriteInstance,
309    t_ms: u64,
310    clock: Clock,
311) -> Option<Pose<'a>> {
312    let character = art.character();
313    let (anim, state, elapsed, looping) = match (art.activity(), clock) {
314        (Some(a), Clock::Loop(loop_ms)) => {
315            let script = LoopScript::new(a, character, loop_ms);
316            let (state, elapsed) = script.at(t_ms);
317            (
318                character.animation(&a.id, state),
319                state.to_string(),
320                elapsed,
321                true,
322            )
323        }
324        (Some(a), Clock::Live) => {
325            let st = state_at(a, graph.seed, t_ms, &|state| {
326                character.one_shot_ms(&a.id, state)
327            });
328            let looping = a.animation.states.get(&st.state).is_some_and(|d| d.looping);
329            (
330                character.animation(&a.id, &st.state),
331                st.state.clone(),
332                t_ms - st.since_ms,
333                looping,
334            )
335        }
336        (None, _) => (
337            character.animation("", "idle"),
338            "idle".to_string(),
339            t_ms,
340            true,
341        ),
342    };
343    let frame = anim?.frame_at(elapsed, looping);
344    let sc = s.scale as i32;
345    Some(Pose {
346        frame,
347        state,
348        x0: s.x + (CHARACTER_BOX.0 as i32 / 2) * sc,
349        y0: s.y + (CHARACTER_BOX.1 as i32 - 1) * sc,
350        sc,
351        mirror: s.mirror,
352    })
353}
354
355/// The activity's `[[effects]]` for the current state, at their anchors on the
356/// current frame. Particles snap to cells like the embers.
357fn draw_effects(
358    img: &mut IndexedImage,
359    drawn: &mut Vec<PixelRect>,
360    graph: &SceneGraph,
361    art: &dyn SceneArt,
362    atlas: &GlyphAtlas,
363    pose: &Pose,
364    t_ms: u64,
365) {
366    let Some(a) = art.activity() else {
367        return;
368    };
369    let g = &graph.grid;
370    let dir = if pose.mirror { -1.0 } else { 1.0 };
371    for (i, e) in a.effects.iter().enumerate() {
372        if !e.active_in(&pose.state) {
373            continue;
374        }
375        let (Some(&(ax, ay)), Some(preset)) =
376            (pose.frame.anchors.get(&e.at), Preset::from_id(&e.preset))
377        else {
378            continue;
379        };
380        let (cx, cy) = pose.screen(ax, ay);
381        let seed = graph.seed.wrapping_add(i as u64 + 1);
382        for p in preset_particles(preset, seed, t_ms) {
383            let x = f64::from(cx) + p.dx * dir * f64::from(pose.sc);
384            let y = f64::from(cy) + p.dy * f64::from(pose.sc);
385            let col = ((x - f64::from(g.origin_x)) / f64::from(g.cell_w)).floor();
386            let row = ((y - f64::from(g.origin_y)) / f64::from(g.cell_h)).floor();
387            if col < 0.0 || row < 0.0 || col >= f64::from(g.cols) || row >= f64::from(g.rows) {
388                continue;
389            }
390            draw_particle(
391                img,
392                drawn,
393                graph,
394                atlas,
395                col as u32,
396                row as u32,
397                p.glyph,
398                p.level,
399                preset == Preset::Steam,
400                true,
401            );
402        }
403    }
404}
405
406fn draw_pose(
407    img: &mut IndexedImage,
408    drawn: &mut Vec<PixelRect>,
409    pose: &Pose,
410    palette: &IndexedPalette,
411) {
412    let f = pose.frame;
413    let (ox, oy) = f.origin();
414    let (x0, y0, sc, s) = (pose.x0, pose.y0, pose.sc, pose);
415    let (w, h) = (img.width as i32, img.height as i32);
416    // The frame's box on screen (mirroring flips it around the origin).
417    let (fw, fh) = (f.width as i32, f.height as i32);
418    let (left, right) = if s.mirror {
419        (x0 - (fw - 1 - ox) * sc, x0 + (ox + 1) * sc)
420    } else {
421        (x0 - ox * sc, x0 + (fw - ox) * sc)
422    };
423    if let Some(r) = PixelRect::clipped(
424        left,
425        y0 - oy * sc,
426        right,
427        y0 + (fh - oy) * sc,
428        img.width,
429        img.height,
430    ) {
431        drawn.push(r);
432    }
433    for row in 0..f.height {
434        for col in 0..f.width {
435            let Some(rgb) = f.pixel(col, row) else {
436                continue;
437            };
438            let idx = palette
439                .sprite_index(rgb)
440                .expect("character colour in palette");
441            let dx = (col as i32 - ox) * if s.mirror { -1 } else { 1 };
442            let px = x0 + dx * sc;
443            let py = y0 + (row as i32 - oy) * sc;
444            for y in py.max(0)..(py + sc).min(h) {
445                let line = (y * w) as usize;
446                for x in px.max(0)..(px + sc).min(w) {
447                    img.pixels[line + x as usize] = idx;
448                }
449            }
450        }
451    }
452}
453
454fn draw_sprite(
455    img: &mut IndexedImage,
456    drawn: &mut Vec<PixelRect>,
457    s: &SpriteInstance,
458    art: &dyn SceneArt,
459    palette: &IndexedPalette,
460) {
461    let Some(map) = art.prop(s.kind) else {
462        return;
463    };
464    let (w, h) = (img.width as i32, img.height as i32);
465    let scale = s.scale as i32;
466    let (mw, mh) = (map.width(), map.height());
467    if let Some(r) = PixelRect::clipped(
468        s.x,
469        s.y,
470        s.x + mw as i32 * scale,
471        s.y + mh as i32 * scale,
472        img.width,
473        img.height,
474    ) {
475        drawn.push(r);
476    }
477    for my in 0..mh {
478        for mx in 0..mw {
479            let sx = if s.mirror { mw - 1 - mx } else { mx };
480            let Some(rgb) = map.pixel(sx, my) else {
481                continue;
482            };
483            let idx = palette.sprite_index(rgb).expect("sprite colour in palette");
484            let px = s.x + mx as i32 * scale;
485            let py = s.y + my as i32 * scale;
486            for y in py.max(0)..(py + scale).min(h) {
487                let line = (y * w) as usize;
488                for x in px.max(0)..(px + scale).min(w) {
489                    img.pixels[line + x as usize] = idx;
490                }
491            }
492        }
493    }
494}