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