From 9439952a9403a97e32c6670597334a079c857fbd Mon Sep 17 00:00:00 2001 From: Liam Gallagher Date: Thu, 9 Mar 2023 10:40:25 +1300 Subject: [PATCH] Method docs --- crates/bevy_math/src/rect.rs | 328 +++++------------------------------ 1 file changed, 43 insertions(+), 285 deletions(-) diff --git a/crates/bevy_math/src/rect.rs b/crates/bevy_math/src/rect.rs index 83d264f6e7cf1..a3432f4d872eb 100644 --- a/crates/bevy_math/src/rect.rs +++ b/crates/bevy_math/src/rect.rs @@ -5,7 +5,7 @@ macro_rules! create_rect_type { /// A rectangle defined by two opposite corners. /// /// The rectangle is axis aligned, and defined by its minimum and maximum coordinates, - /// stored in `Rect::min` and `Rect::max`, respectively. The minimum/maximum invariant <- TODO: Set `Rect` based on name + #[doc = concat!(" stored in `", stringify!($type_name), "::min` and `", stringify!($type_name), "::max`, respectively. The minimum/maximum invariant")] /// must be upheld by the user when directly assigning the fields, otherwise some methods /// produce invalid results. It is generally recommended to use one of the constructor /// methods instead, which will ensure this invariant is met, unless you already have @@ -21,11 +21,19 @@ macro_rules! create_rect_type { } impl $type_name { + /// Create a new rectangle from two corner points. + /// + /// The two points do not need to be the minimum and/or maximum corners. + /// They only need to be two opposite corners. #[inline] pub fn new(x0: $num_type, y0: $num_type, x1: $num_type, y1: $num_type) -> Self { Self::from_corners(<$vec_type>::new(x0, y0), <$vec_type>::new(x1, y1)) } + /// Create a new rectangle from two corner points. + /// + /// The two points do not need to be the minimum and/or maximum corners. + /// They only need to be two opposite corners. #[inline] pub fn from_corners(p0: $vec_type, p1: $vec_type) -> Self { Self { @@ -34,6 +42,11 @@ macro_rules! create_rect_type { } } + /// Create a new rectangle from its center and size. + /// + /// # Panics + /// + /// This method panics if any of the components of the size is negative. #[inline] pub fn from_center_size(origin: $vec_type, size: $vec_type) -> Self { assert!(size.cmpge(<$vec_type>::ZERO).all()); @@ -41,6 +54,11 @@ macro_rules! create_rect_type { Self::from_center_half_size(origin, half_size) } + /// Create a new rectangle from its center and half-size. + /// + /// # Panics + /// + /// This method panics if any of the components of the half-size is negative. #[inline] pub fn from_center_half_size(origin: $vec_type, half_size: $vec_type) -> Self { assert!(half_size.cmpge(<$vec_type>::ZERO).all()); @@ -50,41 +68,51 @@ macro_rules! create_rect_type { } } + /// Check if the rectangle is empty. #[inline] pub fn is_empty(&self) -> bool { self.min.cmpge(self.max).any() } + /// Rectangle width (max.x - min.x). #[inline] pub fn width(&self) -> $num_type { self.max.x - self.min.x } + /// Rectangle height (max.y - min.y). #[inline] pub fn height(&self) -> $num_type { self.max.y - self.min.y } + /// Rectangle size. #[inline] pub fn size(&self) -> $vec_type { self.max - self.min } + /// Rectangle half-size. #[inline] pub fn half_size(&self) -> $vec_type { self.size() / 2 as $num_type } + /// The center point of the rectangle. #[inline] pub fn center(&self) -> $vec_type { (self.min + self.max) / 2 as $num_type } + /// Check if a point lies within this rectangle, inclusive of its edges. #[inline] pub fn contains(&self, point: $vec_type) -> bool { (point.cmpge(self.min) & point.cmple(self.max)).all() } + /// Build a new rectangle formed of the union of this rectangle and another rectangle. + /// + /// The union is the smallest rectangle enclosing both rectangles. #[inline] pub fn union(&self, other: Self) -> Self { Self { @@ -93,6 +121,10 @@ macro_rules! create_rect_type { } } + /// Build a new rectangle formed of the union of this rectangle and a point. + /// + /// The union is the smallest rectangle enclosing both the rectangle and the point. If the + /// point is already inside the rectangle, this method returns a copy of the rectangle. #[inline] pub fn union_point(&self, other: $vec_type) -> Self { Self { @@ -101,6 +133,11 @@ macro_rules! create_rect_type { } } + /// Build a new rectangle formed of the intersection of this rectangle and another rectangle. + /// + /// The intersection is the largest rectangle enclosed in both rectangles. If the intersection + #[doc = concat!(" is empty, this method returns an empty rectangle ([`", stringify!($type_name), "::is_empty()`] returns `true`), but")] + #[doc = concat!(" the actual values of [`", stringify!($type_name), "::min`] and [`", stringify!($type_name), "::max`] are implementation-dependent.")] #[inline] pub fn intersect(&self, other: Self) -> Self { let mut r = Self { @@ -113,6 +150,11 @@ macro_rules! create_rect_type { r } + /// Create a new rectangle with a constant inset. + /// + /// The inset is the extra border on all sides. A positive inset produces a larger rectangle, + /// while a negative inset is allowed and produces a smaller rectangle. If the inset is negative + /// and its absolute value is larger than the rectangle half-size, the created rectangle is empty. #[inline] pub fn inset(&self, inset: $num_type) -> Self { let mut r = Self { @@ -132,290 +174,6 @@ create_rect_type!(Rect, Vec2, f32); create_rect_type!(IRect, IVec2, i32); create_rect_type!(URect, UVec2, u32); -impl Rect { - // /// Create a new rectangle from two corner points. - // /// - // /// The two points do not need to be the minimum and/or maximum corners. - // /// They only need to be two opposite corners. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::Rect; - // /// let r = Rect::new(0., 4., 10., 6.); // w=10 h=2 - // /// let r = Rect::new(2., 3., 5., -1.); // w=3 h=4 - // /// ``` - // #[inline] - // pub fn new(x0: f32, y0: f32, x1: f32, y1: f32) -> Self { - // Self::from_corners(Vec2::new(x0, y0), Vec2::new(x1, y1)) - // } - - // /// Create a new rectangle from two corner points. - // /// - // /// The two points do not need to be the minimum and/or maximum corners. - // /// They only need to be two opposite corners. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// // Unit rect from [0,0] to [1,1] - // /// let r = Rect::from_corners(Vec2::ZERO, Vec2::ONE); // w=1 h=1 - // /// // Same; the points do not need to be ordered - // /// let r = Rect::from_corners(Vec2::ONE, Vec2::ZERO); // w=1 h=1 - // /// ``` - // #[inline] - // pub fn from_corners(p0: Vec2, p1: Vec2) -> Self { - // Rect { - // min: p0.min(p1), - // max: p0.max(p1), - // } - // } - - // /// Create a new rectangle from its center and size. - // /// - // /// # Panics - // /// - // /// This method panics if any of the components of the size is negative. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// let r = Rect::from_center_size(Vec2::ZERO, Vec2::ONE); // w=1 h=1 - // /// assert!(r.min.abs_diff_eq(Vec2::splat(-0.5), 1e-5)); - // /// assert!(r.max.abs_diff_eq(Vec2::splat(0.5), 1e-5)); - // /// ``` - // #[inline] - // pub fn from_center_size(origin: Vec2, size: Vec2) -> Self { - // assert!(size.cmpge(Vec2::ZERO).all()); - // let half_size = size / 2.; - // Self::from_center_half_size(origin, half_size) - // } - - // /// Create a new rectangle from its center and half-size. - // /// - // /// # Panics - // /// - // /// This method panics if any of the components of the half-size is negative. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// let r = Rect::from_center_half_size(Vec2::ZERO, Vec2::ONE); // w=2 h=2 - // /// assert!(r.min.abs_diff_eq(Vec2::splat(-1.), 1e-5)); - // /// assert!(r.max.abs_diff_eq(Vec2::splat(1.), 1e-5)); - // /// ``` - // #[inline] - // pub fn from_center_half_size(origin: Vec2, half_size: Vec2) -> Self { - // assert!(half_size.cmpge(Vec2::ZERO).all()); - // Self { - // min: origin - half_size, - // max: origin + half_size, - // } - // } - - // /// Check if the rectangle is empty. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// let r = Rect::from_corners(Vec2::ZERO, Vec2::new(0., 1.)); // w=0 h=1 - // /// assert!(r.is_empty()); - // /// ``` - // #[inline] - // pub fn is_empty(&self) -> bool { - // self.min.cmpge(self.max).any() - // } - - // /// Rectangle width (max.x - min.x). - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::Rect; - // /// let r = Rect::new(0., 0., 5., 1.); // w=5 h=1 - // /// assert!((r.width() - 5.).abs() <= 1e-5); - // /// ``` - // #[inline] - // pub fn width(&self) -> f32 { - // self.max.x - self.min.x - // } - - // /// Rectangle height (max.y - min.y). - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::Rect; - // /// let r = Rect::new(0., 0., 5., 1.); // w=5 h=1 - // /// assert!((r.height() - 1.).abs() <= 1e-5); - // /// ``` - // #[inline] - // pub fn height(&self) -> f32 { - // self.max.y - self.min.y - // } - - // /// Rectangle size. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// let r = Rect::new(0., 0., 5., 1.); // w=5 h=1 - // /// assert!(r.size().abs_diff_eq(Vec2::new(5., 1.), 1e-5)); - // /// ``` - // #[inline] - // pub fn size(&self) -> Vec2 { - // self.max - self.min - // } - - // /// Rectangle half-size. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// let r = Rect::new(0., 0., 5., 1.); // w=5 h=1 - // /// assert!(r.half_size().abs_diff_eq(Vec2::new(2.5, 0.5), 1e-5)); - // /// ``` - // #[inline] - // pub fn half_size(&self) -> Vec2 { - // self.size() * 0.5 - // } - - // /// The center point of the rectangle. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// let r = Rect::new(0., 0., 5., 1.); // w=5 h=1 - // /// assert!(r.center().abs_diff_eq(Vec2::new(2.5, 0.5), 1e-5)); - // /// ``` - // #[inline] - // pub fn center(&self) -> Vec2 { - // (self.min + self.max) * 0.5 - // } - - // /// Check if a point lies within this rectangle, inclusive of its edges. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::Rect; - // /// let r = Rect::new(0., 0., 5., 1.); // w=5 h=1 - // /// assert!(r.contains(r.center())); - // /// assert!(r.contains(r.min)); - // /// assert!(r.contains(r.max)); - // /// ``` - // #[inline] - // pub fn contains(&self, point: Vec2) -> bool { - // (point.cmpge(self.min) & point.cmple(self.max)).all() - // } - - // /// Build a new rectangle formed of the union of this rectangle and another rectangle. - // /// - // /// The union is the smallest rectangle enclosing both rectangles. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// let r1 = Rect::new(0., 0., 5., 1.); // w=5 h=1 - // /// let r2 = Rect::new(1., -1., 3., 3.); // w=2 h=4 - // /// let r = r1.union(r2); - // /// assert!(r.min.abs_diff_eq(Vec2::new(0., -1.), 1e-5)); - // /// assert!(r.max.abs_diff_eq(Vec2::new(5., 3.), 1e-5)); - // /// ``` - // #[inline] - // pub fn union(&self, other: Rect) -> Rect { - // Rect { - // min: self.min.min(other.min), - // max: self.max.max(other.max), - // } - // } - - // /// Build a new rectangle formed of the union of this rectangle and a point. - // /// - // /// The union is the smallest rectangle enclosing both the rectangle and the point. If the - // /// point is already inside the rectangle, this method returns a copy of the rectangle. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// let r = Rect::new(0., 0., 5., 1.); // w=5 h=1 - // /// let u = r.union_point(Vec2::new(3., 6.)); - // /// assert!(u.min.abs_diff_eq(Vec2::ZERO, 1e-5)); - // /// assert!(u.max.abs_diff_eq(Vec2::new(5., 6.), 1e-5)); - // /// ``` - // #[inline] - // pub fn union_point(&self, other: Vec2) -> Rect { - // Rect { - // min: self.min.min(other), - // max: self.max.max(other), - // } - // } - - // /// Build a new rectangle formed of the intersection of this rectangle and another rectangle. - // /// - // /// The intersection is the largest rectangle enclosed in both rectangles. If the intersection - // /// is empty, this method returns an empty rectangle ([`Rect::is_empty()`] returns `true`), but - // /// the actual values of [`Rect::min`] and [`Rect::max`] are implementation-dependent. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// let r1 = Rect::new(0., 0., 5., 1.); // w=5 h=1 - // /// let r2 = Rect::new(1., -1., 3., 3.); // w=2 h=4 - // /// let r = r1.intersect(r2); - // /// assert!(r.min.abs_diff_eq(Vec2::new(1., 0.), 1e-5)); - // /// assert!(r.max.abs_diff_eq(Vec2::new(3., 1.), 1e-5)); - // /// ``` - // #[inline] - // pub fn intersect(&self, other: Rect) -> Rect { - // let mut r = Rect { - // min: self.min.max(other.min), - // max: self.max.min(other.max), - // }; - // // Collapse min over max to enforce invariants and ensure e.g. width() or - // // height() never return a negative value. - // r.min = r.min.min(r.max); - // r - // } - - // /// Create a new rectangle with a constant inset. - // /// - // /// The inset is the extra border on all sides. A positive inset produces a larger rectangle, - // /// while a negative inset is allowed and produces a smaller rectangle. If the inset is negative - // /// and its absolute value is larger than the rectangle half-size, the created rectangle is empty. - // /// - // /// # Examples - // /// - // /// ```rust - // /// # use bevy_math::{Rect, Vec2}; - // /// let r = Rect::new(0., 0., 5., 1.); // w=5 h=1 - // /// let r2 = r.inset(3.); // w=11 h=7 - // /// assert!(r2.min.abs_diff_eq(Vec2::splat(-3.), 1e-5)); - // /// assert!(r2.max.abs_diff_eq(Vec2::new(8., 4.), 1e-5)); - // /// ``` - // #[inline] - // pub fn inset(&self, inset: f32) -> Rect { - // let mut r = Rect { - // min: self.min - inset, - // max: self.max + inset, - // }; - // // Collapse min over max to enforce invariants and ensure e.g. width() or - // // height() never return a negative value. - // r.min = r.min.min(r.max); - // r - // } -} - #[cfg(test)] mod tests { use super::*;