blockworx_kernel/

camera.rs

//! The camera the session owns: where the diagram is shown from, how a
//! framing glides into place, and what the host's own moves — a pan, a
//! wheel notch, a pinch — do to it.
//!
//! The host reads its pointer and reports a [`Move`]; the session applies it,
//! eases a framing a frame at a time on its own clock, and answers the
//! vantage back through the view. Nothing here knows what the viewport is
//! drawn with.

use core::time::Duration;

use blockworx_geom::{Pos2, Rect, Vec2, grid::GRID_SIZE};
use blockworx_paint::{Factor, Move, Vantage, Zoom, ZoomStep};

use crate::session::Session;

/// Whether the view still owes the drawing a fit-to-content framing.
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub enum Refit {
    #[default]
    Idle,
    Owed,
}

/// Whether the user worked the camera themselves this frame — a wheel, a
/// pinch, a drag pan, a zoom step. The undo stack names an entry by the move
/// that made it, and a fit is not a pan.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum CameraWork {
    Worked,
    Idle,
}

/// Whether a framing eases into place or jumps there.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Glide {
    Eased,
    /// A history step snaps: the undo stack pins the camera the step ended
    /// at, and one still easing toward its target would leave the pin and the
    /// view disagreeing for every frame of the ease.
    Snap,
}

/// Largest zoom a *framing* will apply — the navigator focusing one block, or a
/// double-click fitting the level's contents. Small content would otherwise
/// balloon to fill the view, which reads as a jump rather than a fit. Explicit
/// camera rects are not capped: a caller asking for a ten-cell window means
/// it.
const FRAME_MAX_ZOOM: f32 = 2.0;

/// The gutter a double-click fit leaves around the content, in grid cells, so
/// the outermost blocks don't sit against the viewport edge.
const FIT_BORDER_CELLS: f32 = 4.0;

/// The slack the camera framings leave around their rect, as a fraction of the
/// content's size per side — a quarter of the content overall.
const CAMERA_SLACK: f32 = 0.125;

/// Exponential approach rate for an animated view change; higher is snappier.
const VIEW_ANIMATION_RATE: f32 = 16.0;

/// The longest a frame counts for when a framing eases: a frame that stalled
/// moves the camera as far as a tenth of a second would, not as far as the
/// stall.
const LONGEST_EASED_FRAME: Duration = Duration::from_millis(100);

/// How far a span reaching from `lo` to `hi` must move along one axis to sit
/// inside `visible_lo..visible_hi`. Zero when it already does; assumes it
/// fits, so it never has to choose which end to leave outside.
fn overshoot(lo: f32, hi: f32, visible_lo: f32, visible_hi: f32) -> f32 {
    if lo < visible_lo {
        lo - visible_lo
    } else if hi > visible_hi {
        hi - visible_hi
    } else {
        0.0
    }
}

/// The session's camera: where it stands, where it is easing to, the screen
/// it is shown on and the part of that the chrome leaves clear.
#[derive(Clone, Copy, Debug)]
pub(crate) struct Camera {
    pub(crate) vantage: Vantage,
    /// The screen rect the canvas is laid out into.
    pub(crate) viewport: Rect,
    /// The part of the viewport the floating chrome leaves clear, or
    /// [`Rect::NOTHING`] where nothing has measured any.
    pub(crate) safe: Rect,
    /// Where a framing is easing to, while one is.
    target: Option<Vantage>,
    pub(crate) worked: CameraWork,
}

impl Camera {
    pub(crate) fn resting() -> Self {
        Self {
            vantage: Vantage::resting(),
            viewport: Rect::ZERO,
            safe: Rect::NOTHING,
            target: None,
            worked: CameraWork::Idle,
        }
    }

    /// Where a framing centres and sizes itself: the region the chrome left,
    /// or the whole viewport where no chrome has reported any.
    fn framing_rect(&self) -> Rect {
        if self.safe.is_positive() {
            self.safe
        } else {
            self.viewport
        }
    }

    /// The world rect the viewport currently shows.
    pub(crate) fn visible(&self) -> Rect {
        self.vantage.visible(self.viewport)
    }

    /// Stand exactly here. Any framing still easing is abandoned: what is
    /// asked for *is* the framing now, and letting the old one finish would
    /// walk the camera off it.
    pub(crate) fn stand_at(&mut self, vantage: Vantage) {
        self.vantage = vantage;
        self.target = None;
    }

    /// Frame `content` to fill the view, snapping immediately. Used for an
    /// authored camera rect and for layer changes: the block path changed
    /// underneath, so animating across unrelated content is jarring rather
    /// than helpful.
    pub(crate) fn fit_to_rect(&mut self, content: Rect) {
        self.frame_rect(
            content.expand2(content.size() * CAMERA_SLACK),
            Zoom::max_value(),
            Glide::Snap,
        );
    }

    /// Fit the level's whole contents in view — the double-click gesture. Unlike
    /// an authored camera rect this leaves a fixed `FIT_BORDER_CELLS` gutter
    /// (so nothing sits against the edge) and is capped at `FRAME_MAX_ZOOM`
    /// (so a nearly empty level doesn't leap to a huge magnification).
    pub(crate) fn fit_content(&mut self, content: Rect) {
        self.frame_rect(
            content.expand(FIT_BORDER_CELLS * GRID_SIZE),
            Zoom::new(FRAME_MAX_ZOOM),
            Glide::Snap,
        );
    }

    /// Frame a single subject — a block picked from the navigator, the region
    /// an undo just changed — capping the zoom so a small one doesn't blow up
    /// to fill the whole view.
    pub(crate) fn focus_on(&mut self, content: Rect, glide: Glide) {
        self.frame_rect(
            content.expand2(content.size() * CAMERA_SLACK),
            Zoom::new(FRAME_MAX_ZOOM),
            glide,
        );
    }

    /// Bring `content` into view with the gentlest move that reaches it:
    /// nothing at all when it is already visible, otherwise a pan — the zoom
    /// is only touched for content that cannot fit at this one. What a paste
    /// lands is content the viewer has never seen, so the alternative to this
    /// is content that arrives off-screen and reads as having not arrived.
    pub(crate) fn bring_into_view(&mut self, content: Rect, glide: Glide) {
        if !content.is_positive() || !self.viewport.is_positive() {
            return;
        }
        let visible = self.visible();
        if visible.contains_rect(content) {
            return;
        }
        let fits = |r: Rect| r.width() <= visible.width() && r.height() <= visible.height();
        let gutter = content.expand(FIT_BORDER_CELLS * GRID_SIZE);
        let target = if fits(gutter) { gutter } else { content };
        if !fits(target) {
            self.focus_on(content, glide);
            return;
        }
        let shift = Vec2::new(
            overshoot(target.min.x, target.max.x, visible.min.x, visible.max.x),
            overshoot(target.min.y, target.max.y, visible.min.y, visible.max.y),
        );
        let panned = Vantage {
            zoom: self.vantage.zoom,
            translation: self.vantage.translation - shift * self.vantage.zoom.get(),
        };
        self.glide_to(panned, glide);
    }

    fn frame_rect(&mut self, content: Rect, max_zoom: Zoom, glide: Glide) {
        if !content.is_positive() || !self.viewport.is_positive() {
            return;
        }
        // Not the viewport itself: the chrome floats over it, and framing
        // against the raw rect lands the model under the tool cluster.
        let framed = Vantage::framing(self.framing_rect(), self.viewport.min, content, max_zoom);
        self.glide_to(framed, glide);
    }

    fn glide_to(&mut self, vantage: Vantage, glide: Glide) {
        match glide {
            Glide::Eased => self.target = Some(vantage),
            Glide::Snap => self.stand_at(vantage),
        }
    }

    /// Advance a framing in progress by one frame that took `dt`, easing
    /// toward the target with a frame-rate-independent exponential approach.
    /// Answers whether it is still under way — a host that draws on demand
    /// asks for another frame while it is.
    pub(crate) fn ease(&mut self, dt: Duration) -> bool {
        let Some(target) = self.target else {
            return false;
        };
        let dt = dt.min(LONGEST_EASED_FRAME).as_secs_f32();
        let t = 1.0 - (-VIEW_ANIMATION_RATE * dt).exp();
        let zoom = self.vantage.zoom.get() + (target.zoom.get() - self.vantage.zoom.get()) * t;
        let translation =
            self.vantage.translation + (target.translation - self.vantage.translation) * t;
        self.vantage = Vantage {
            zoom: Zoom::new(zoom),
            translation,
        };
        if (zoom - target.zoom.get()).abs() < 1e-3
            && (translation - target.translation).length() < 0.5
        {
            self.stand_at(target);
            return false;
        }
        true
    }

    /// What the host's pointer did to the camera. Manual control, so it
    /// cancels a framing in progress and names the undo entry.
    pub(crate) fn moved(&mut self, moved: Move) {
        match moved {
            Move::Pan(delta) => {
                self.target = None;
                self.vantage.translation += delta;
                self.worked = CameraWork::Worked;
            }
            Move::Zoom { factor, anchor } => self.zoom_about(factor, anchor),
        }
    }

    fn zoom_about(&mut self, factor: Factor, anchor: Pos2) {
        self.target = None;
        self.worked = CameraWork::Worked;
        self.vantage = self.vantage.zoomed_about(self.viewport.min, anchor, factor);
    }

    /// One keyboard zoom step, about `anchor` (the pointer) or the viewport
    /// center when the pointer is elsewhere.
    pub(crate) fn zoom_step(&mut self, step: ZoomStep, anchor: Option<Pos2>) {
        if !self.viewport.is_positive() {
            return;
        }
        let anchor = anchor
            .filter(|p| self.viewport.contains(*p))
            .unwrap_or_else(|| self.viewport.center());
        self.zoom_about(step.factor(), anchor);
    }
}

impl Session {
    pub fn vantage(&self) -> Vantage {
        self.camera.vantage
    }

    pub fn viewport(&self) -> Rect {
        self.camera.viewport
    }

    /// The screen rect the canvas is laid out in — told whenever it changes.
    pub fn set_viewport(&mut self, viewport: Rect) {
        self.camera.viewport = viewport;
    }

    /// The part of the viewport the floating chrome leaves clear, measured by
    /// whoever draws the chrome. Every framing centres in this rather than in
    /// the raw viewport, so nothing lands under a pill.
    pub fn set_safe_region(&mut self, safe: Rect) {
        self.camera.safe = safe;
    }

    /// The world rect the viewport currently shows.
    pub fn visible_world(&self) -> Rect {
        self.camera.visible()
    }

    /// A screen position under the camera — where a tool carried off the
    /// cluster was dropped.
    pub fn screen_to_world(&self, screen: Pos2) -> Pos2 {
        self.vantage()
            .screen_to_world(self.camera.viewport.min, screen)
    }

    /// What the host's pointer did to the camera this frame, applied in the
    /// order it happened.
    pub fn moves(&mut self, moves: &[Move]) {
        for &moved in moves {
            self.camera.moved(moved);
        }
    }

    /// Put the camera exactly here — what a history step restores.
    pub fn stand_at(&mut self, vantage: Vantage) {
        self.camera.stand_at(vantage);
    }

    /// Frame this world rect, snapping — an authored camera rect.
    pub fn fit_to_rect(&mut self, content: Rect) {
        self.camera.fit_to_rect(content);
    }

    /// Frame the level's contents, the way the owed fit is taken once the
    /// diagram has been measured.
    pub fn fit_content(&mut self, content: Rect) {
        self.camera.fit_content(content);
    }

    pub(crate) fn focus_on(&mut self, content: Rect, glide: Glide) {
        self.camera.focus_on(content, glide);
    }

    pub(crate) fn bring_into_view(&mut self, content: Rect, glide: Glide) {
        self.camera.bring_into_view(content, glide);
    }

    pub(crate) fn zoom_step(&mut self, step: ZoomStep, anchor: Option<Pos2>) {
        self.camera.zoom_step(step, anchor);
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// One 60 Hz frame.
    const FRAME: Duration = Duration::from_micros(16_667);
    use blockworx_geom::pos2;

    /// A camera whose viewport has been laid out — what every framing and
    /// zoom below is measured against.
    fn viewing(viewport: Rect) -> Camera {
        Camera {
            viewport,
            ..Camera::resting()
        }
    }

    /// Zooming about a point leaves the world under it where it was — that is
    /// what "zoom about the cursor" means, and what the wheel, pinch, and the
    /// keyboard steps all share.
    #[test]
    fn a_zoom_step_holds_the_world_under_its_anchor() {
        let mut camera = viewing(Rect::from_min_size(
            pos2(30.0, 20.0),
            Vec2::new(800.0, 600.0),
        ));
        camera.vantage.translation = Vec2::new(17.0, -9.0);
        let anchor = pos2(240.0, 380.0);
        let origin = camera.viewport.min;
        let before = camera.vantage.screen_to_world(origin, anchor);

        camera.zoom_step(ZoomStep::In, Some(anchor));
        assert!(
            camera.vantage.zoom > Zoom::unity(),
            "zooming in should raise the zoom"
        );
        let after = camera.vantage.screen_to_world(origin, anchor);
        assert!(
            before.distance(after) < 0.01,
            "the world under the cursor moved: {before:?} -> {after:?}"
        );

        // Out again returns to where it started (the step factors are inverses).
        camera.zoom_step(ZoomStep::Out, Some(anchor));
        assert!(
            (camera.vantage.zoom.get() - 1.0).abs() < 1e-5,
            "{:?}",
            camera.vantage.zoom
        );
        assert_eq!(
            camera.worked,
            CameraWork::Worked,
            "a step is the user's move"
        );
    }

    /// With the pointer off the canvas the step falls back to the viewport
    /// center, so a keyboard zoom always has an anchor.
    #[test]
    fn a_zoom_step_without_a_pointer_uses_the_viewport_center() {
        let mut camera = viewing(Rect::from_min_size(pos2(0.0, 0.0), Vec2::new(800.0, 600.0)));
        let origin = camera.viewport.min;
        let center = camera.viewport.center();
        let before = camera.vantage.screen_to_world(origin, center);
        // A pointer outside the canvas is ignored, like no pointer at all.
        camera.zoom_step(ZoomStep::In, Some(pos2(-50.0, -50.0)));
        assert!(before.distance(camera.vantage.screen_to_world(origin, center)) < 0.01);
    }

    /// The three answers [`Camera::bring_into_view`] gives, in the order it
    /// prefers them: nothing at all, a pan, and — only for content that
    /// cannot fit at this zoom — a reframing.
    #[test]
    fn bringing_content_into_view_moves_as_little_as_it_can() {
        let settled = |camera: &mut Camera| {
            if let Some(target) = camera.target.take() {
                camera.vantage = target;
            }
            camera.visible()
        };
        let mut camera = viewing(Rect::from_min_size(Pos2::ZERO, Vec2::new(800.0, 600.0)));
        let visible = camera.visible();
        assert!(
            visible.width() > 0.0 && visible.height() > 0.0,
            "precondition: the view shows something to be outside of",
        );

        let inside = Rect::from_min_size(pos2(100.0, 100.0), Vec2::splat(50.0));
        assert!(visible.contains_rect(inside), "precondition: already shown");
        camera.bring_into_view(inside, Glide::Eased);
        assert!(
            camera.target.is_none(),
            "content already in view moved the camera",
        );

        let beside = Rect::from_min_size(pos2(900.0, 100.0), Vec2::splat(50.0));
        assert!(
            !visible.contains_rect(beside) && beside.width() < visible.width(),
            "precondition: outside the view, and small enough to pan to",
        );
        let zoom_before = camera.vantage.zoom;
        camera.bring_into_view(beside, Glide::Eased);
        assert_eq!(
            camera.target.expect("the camera moves").zoom,
            zoom_before,
            "a pan must not touch the zoom",
        );
        assert!(settled(&mut camera).contains_rect(beside));

        let mut camera = viewing(Rect::from_min_size(Pos2::ZERO, Vec2::new(800.0, 600.0)));
        let huge = Rect::from_min_size(pos2(400.0, 0.0), Vec2::new(2000.0, 300.0));
        assert!(
            huge.width() > camera.visible().width(),
            "precondition: no pan can hold this at the current zoom",
        );
        camera.bring_into_view(huge, Glide::Eased);
        assert!(
            camera.target.expect("the camera moves").zoom < camera.vantage.zoom,
            "content too wide for the view must be zoomed out to",
        );
        assert!(settled(&mut camera).contains_rect(huge));
    }

    /// A double-click fit keeps a [`FIT_BORDER_CELLS`] gutter around the
    /// content and never magnifies past [`FRAME_MAX_ZOOM`].
    #[test]
    fn a_content_fit_leaves_a_border_and_caps_the_zoom() {
        let mut camera = viewing(Rect::from_min_size(Pos2::ZERO, Vec2::new(800.0, 600.0)));
        // Wide content: the fit is bound by the content, not the cap, so the
        // gutter is what decides where its edges land.
        let content = Rect::from_min_size(pos2(100.0, 100.0), Vec2::new(1600.0, 400.0));
        camera.fit_content(content);
        let zoom = camera.vantage.zoom.get();
        assert!(zoom < FRAME_MAX_ZOOM, "the cap should not bind here");
        let origin = camera.viewport.min;
        let left = camera.vantage.world_to_screen(origin, content.min).x;
        let right = camera.vantage.world_to_screen(origin, content.max).x;
        let gutter = FIT_BORDER_CELLS * GRID_SIZE * zoom;
        assert!(
            left - camera.viewport.left() >= gutter - 0.5,
            "content starts {left} with only {} of gutter",
            left - camera.viewport.left()
        );
        assert!(camera.viewport.right() - right >= gutter - 0.5);

        // A nearly empty level would fit at a huge zoom; the cap holds it.
        camera.fit_content(Rect::from_min_size(pos2(0.0, 0.0), Vec2::new(10.0, 10.0)));
        assert_eq!(camera.vantage.zoom, Zoom::new(FRAME_MAX_ZOOM));
    }

    #[test]
    fn focus_zoom_caps_small_content_but_fit_zooms_in_further() {
        let viewport = Vec2::new(800.0, 600.0);
        let tiny = Vec2::new(10.0, 10.0);
        let focus_cap = Zoom::new(FRAME_MAX_ZOOM);
        // A tiny block would fit at a huge zoom; focus_on caps it.
        assert_eq!(Zoom::framing(viewport, tiny, focus_cap), focus_cap);
        // fit_to_rect's higher cap lets the same block zoom in further.
        assert!(Zoom::framing(viewport, tiny, Zoom::max_value()) > focus_cap);
    }

    #[test]
    fn frame_zoom_clamps_huge_content_to_the_floor() {
        let viewport = Vec2::new(800.0, 600.0);
        let huge = Vec2::new(100_000.0, 100_000.0);
        assert_eq!(
            Zoom::framing(viewport, huge, Zoom::max_value()),
            Zoom::min_value()
        );
    }

    /// An eased framing glides toward its target one frame at a time and
    /// lands on it exactly; a pan mid-flight abandons it.
    #[test]
    fn an_eased_framing_lands_and_a_pan_abandons_it() {
        let mut camera = viewing(Rect::from_min_size(Pos2::ZERO, Vec2::new(800.0, 600.0)));
        let subject = Rect::from_min_size(pos2(2000.0, 2000.0), Vec2::new(100.0, 100.0));
        camera.focus_on(subject, Glide::Eased);
        let target = camera.target.expect("an eased framing has a target");
        assert!(camera.ease(FRAME), "one frame does not reach it");
        assert_ne!(camera.vantage, target);
        let mut frames = 1;
        while camera.ease(FRAME) {
            frames += 1;
            assert!(frames < 600, "the framing never lands");
        }
        assert_eq!(camera.vantage, target, "the landing is exact");

        camera.focus_on(
            Rect::from_min_size(Pos2::ZERO, Vec2::splat(10.0)),
            Glide::Eased,
        );
        camera.moved(Move::Pan(Vec2::new(5.0, 0.0)));
        assert!(
            !camera.ease(FRAME),
            "the pan should have abandoned the framing"
        );
        assert_eq!(camera.worked, CameraWork::Worked);
    }
}