bevy_math/
aspect_ratio.rs

1//! Provides a simple aspect ratio struct to help with calculations.
2
3use crate::Vec2;
4use derive_more::derive::Into;
5use thiserror::Error;
6
7#[cfg(feature = "bevy_reflect")]
8use bevy_reflect::Reflect;
9
10/// An `AspectRatio` is the ratio of width to height.
11#[derive(Copy, Clone, Debug, PartialEq, PartialOrd, Into)]
12#[cfg_attr(
13    feature = "bevy_reflect",
14    derive(Reflect),
15    reflect(Debug, PartialEq, Clone)
16)]
17pub struct AspectRatio(f32);
18
19impl AspectRatio {
20    /// Standard 16:9 aspect ratio
21    pub const SIXTEEN_NINE: Self = Self(16.0 / 9.0);
22    /// Standard 4:3 aspect ratio
23    pub const FOUR_THREE: Self = Self(4.0 / 3.0);
24    /// Standard 21:9 ultrawide aspect ratio
25    pub const ULTRAWIDE: Self = Self(21.0 / 9.0);
26
27    /// Attempts to create a new [`AspectRatio`] from a given width and height.
28    ///
29    /// # Errors
30    ///
31    /// Returns an `Err` with `AspectRatioError` if:
32    /// - Either width or height is zero (`AspectRatioError::Zero`)
33    /// - Either width or height is infinite (`AspectRatioError::Infinite`)
34    /// - Either width or height is NaN (`AspectRatioError::NaN`)
35    #[inline]
36    pub fn try_new(width: f32, height: f32) -> Result<Self, AspectRatioError> {
37        match (width, height) {
38            (w, h) if w == 0.0 || h == 0.0 => Err(AspectRatioError::Zero),
39            (w, h) if w.is_infinite() || h.is_infinite() => Err(AspectRatioError::Infinite),
40            (w, h) if w.is_nan() || h.is_nan() => Err(AspectRatioError::NaN),
41            _ => Ok(Self(width / height)),
42        }
43    }
44
45    /// Attempts to create a new [`AspectRatio`] from a given amount of x pixels and y pixels.
46    #[inline]
47    pub fn try_from_pixels(x: u32, y: u32) -> Result<Self, AspectRatioError> {
48        Self::try_new(x as f32, y as f32)
49    }
50
51    /// Returns the aspect ratio as a f32 value.
52    #[inline]
53    pub const fn ratio(&self) -> f32 {
54        self.0
55    }
56
57    /// Returns the inverse of this aspect ratio (height/width).
58    #[inline]
59    pub const fn inverse(&self) -> Self {
60        Self(1.0 / self.0)
61    }
62
63    /// Returns true if the aspect ratio represents a landscape orientation.
64    #[inline]
65    pub const fn is_landscape(&self) -> bool {
66        self.0 > 1.0
67    }
68
69    /// Returns true if the aspect ratio represents a portrait orientation.
70    #[inline]
71    pub const fn is_portrait(&self) -> bool {
72        self.0 < 1.0
73    }
74
75    /// Returns true if the aspect ratio is exactly square.
76    #[inline]
77    pub const fn is_square(&self) -> bool {
78        self.0 == 1.0
79    }
80}
81
82impl TryFrom<Vec2> for AspectRatio {
83    type Error = AspectRatioError;
84
85    #[inline]
86    fn try_from(value: Vec2) -> Result<Self, Self::Error> {
87        Self::try_new(value.x, value.y)
88    }
89}
90
91/// An Error type for when [`super::AspectRatio`] is provided invalid width or height values
92#[derive(Error, Debug, PartialEq, Eq, Clone, Copy)]
93pub enum AspectRatioError {
94    /// Error due to width or height having zero as a value.
95    #[error("AspectRatio error: width or height is zero")]
96    Zero,
97    /// Error due towidth or height being infinite.
98    #[error("AspectRatio error: width or height is infinite")]
99    Infinite,
100    /// Error due to width or height being Not a Number (NaN).
101    #[error("AspectRatio error: width or height is NaN")]
102    NaN,
103}
bevy_math/aspect_ratio.rs

bevy_math/
aspect_ratio.rs
