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