Skip to main content

rayengine_core/
viewport.rs

1//! One viewport contract for cameras, layout, letterboxing and pointer mapping.
2
3use glam::Vec2;
4
5/// Policy for adapting a reference view to a resizable window.
6#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
7pub enum ScaleMode {
8    /// Preserve the reference aspect ratio and visible area, adding bars.
9    #[default]
10    Fit,
11    /// Fit at whole-number scales for pixel art; fractionally shrink if necessary.
12    IntegerFit,
13    /// Fill the window while preserving reference height; width changes with aspect.
14    Expand,
15}
16
17/// A fitted content rectangle measured in logical window coordinates.
18#[derive(Clone, Copy, Debug)]
19pub struct Viewport {
20    /// Top-left corner of the content, excluding letterbox bars.
21    pub origin: Vec2,
22    /// Content dimensions in logical window coordinates.
23    pub size: Vec2,
24    /// Content dimensions in game/UI units.
25    pub logical_size: Vec2,
26    /// Window logical pixels per UI unit.
27    pub scale: f32,
28}
29
30impl Viewport {
31    /// Computes a viewport. Returns `None` for minimized or invalid dimensions.
32    pub fn new(window: Vec2, reference: Vec2, mode: ScaleMode) -> Option<Self> {
33        if !window.is_finite()
34            || !reference.is_finite()
35            || window.min_element() <= 0.0
36            || reference.min_element() <= 0.0
37        {
38            return None;
39        }
40        let fit = (window / reference).min_element();
41        let scale = match mode {
42            ScaleMode::Fit => fit,
43            ScaleMode::IntegerFit if fit >= 1.0 => fit.floor(),
44            ScaleMode::IntegerFit => fit,
45            ScaleMode::Expand => window.y / reference.y,
46        };
47        let logical_size = if mode == ScaleMode::Expand {
48            window / scale
49        } else {
50            reference
51        };
52        let size = logical_size * scale;
53        Some(Self {
54            origin: (window - size) * 0.5,
55            size,
56            logical_size,
57            scale,
58        })
59    }
60
61    /// Aspect ratio seen by the camera and renderer.
62    pub fn aspect(&self) -> f32 {
63        self.logical_size.x / self.logical_size.y
64    }
65
66    /// Converts a pointer to UI units, rejecting points inside the bars.
67    pub fn screen_to_ui(&self, screen: Vec2) -> Option<Vec2> {
68        let local = screen - self.origin;
69        if !local.is_finite()
70            || local.min_element() < 0.0
71            || local.x >= self.size.x
72            || local.y >= self.size.y
73        {
74            None
75        } else {
76            Some(local / self.scale)
77        }
78    }
79
80    /// Converts UI units to logical window coordinates.
81    pub fn ui_to_screen(&self, ui: Vec2) -> Vec2 {
82        self.origin + ui * self.scale
83    }
84
85    /// Target pixel dimensions at the given framebuffer scale, rounded and bounded.
86    pub fn render_size(&self, dpi: Vec2) -> (u32, u32) {
87        let physical = self.size * dpi.max(Vec2::ONE);
88        // Preserve aspect when limiting very large/high-DPI targets.
89        let physical = physical * (8192.0 / physical.max_element()).min(1.0);
90        (
91            physical.x.round().clamp(1.0, 8192.0) as u32,
92            physical.y.round().clamp(1.0, 8192.0) as u32,
93        )
94    }
95}
96
97#[cfg(test)]
98mod tests {
99    use super::*;
100
101    #[test]
102    fn ultrawide_fit_keeps_view_and_pointer_coordinates() {
103        let view = Viewport::new(
104            Vec2::new(2400.0, 900.0),
105            Vec2::new(960.0, 540.0),
106            ScaleMode::Fit,
107        )
108        .unwrap();
109        assert_eq!(view.origin, Vec2::new(400.0, 0.0));
110        assert_eq!(view.logical_size, Vec2::new(960.0, 540.0));
111        assert!(view.screen_to_ui(Vec2::new(100.0, 100.0)).is_none());
112        let ui = Vec2::new(300.0, 120.0);
113        assert!(
114            view.screen_to_ui(view.ui_to_screen(ui))
115                .unwrap()
116                .abs_diff_eq(ui, 0.001)
117        );
118        assert_eq!(view.render_size(Vec2::splat(2.0)), (3200, 1800));
119    }
120
121    #[test]
122    fn integer_scaling_fits_even_a_small_window() {
123        let reference = Vec2::new(320.0, 180.0);
124        let large =
125            Viewport::new(Vec2::new(1000.0, 700.0), reference, ScaleMode::IntegerFit).unwrap();
126        assert_eq!(large.scale, 3.0);
127        let small =
128            Viewport::new(Vec2::new(160.0, 90.0), reference, ScaleMode::IntegerFit).unwrap();
129        assert_eq!(small.scale, 0.5);
130    }
131
132    #[test]
133    fn expand_changes_only_visible_width() {
134        let view = Viewport::new(
135            Vec2::new(2000.0, 1000.0),
136            Vec2::new(960.0, 540.0),
137            ScaleMode::Expand,
138        )
139        .unwrap();
140        assert_eq!(view.logical_size, Vec2::new(1080.0, 540.0));
141        assert_eq!(view.origin, Vec2::ZERO);
142    }
143
144    #[test]
145    fn minimized_and_nonfinite_sizes_are_rejected() {
146        assert!(Viewport::new(Vec2::ZERO, Vec2::ONE, ScaleMode::Fit).is_none());
147        assert!(Viewport::new(Vec2::splat(f32::NAN), Vec2::ONE, ScaleMode::Fit).is_none());
148    }
149
150    #[test]
151    fn target_limit_preserves_camera_aspect_ratio() {
152        let view = Viewport::new(
153            Vec2::new(16000.0, 9000.0),
154            Vec2::new(960.0, 540.0),
155            ScaleMode::Fit,
156        )
157        .unwrap();
158        assert_eq!(view.render_size(Vec2::ONE), (8192, 4608));
159    }
160}