Add RayTest2d and RayTest3d (bevyengine#11310)

# Objective

Implement a raycast intersection test for bounding volumes

## Solution

- Implement RayTest2d and RayTest3d types

---------

Co-authored-by: Alice Cecile <[email protected]>
Co-authored-by: IQuick 143 <[email protected]>

crates/bevy_math/src/bounding/mod.rs

@@ -59,3 +59,8 @@ mod bounded2d;
 pub use bounded2d::*;
 mod bounded3d;
 pub use bounded3d::*;
+
+mod raytest2d;
+pub use raytest2d::*;
+mod raytest3d;
+pub use raytest3d::*;

crates/bevy_math/src/bounding/raytest2d.rs

@@ -0,0 +1,330 @@
+use super::{Aabb2d, BoundingCircle, IntersectsVolume};
+use crate::{primitives::Direction2d, Ray2d, Vec2};
+
+/// A raycast intersection test for 2D bounding volumes
+#[derive(Debug)]
+pub struct RayTest2d {
+ /// The ray for the test
+ pub ray: Ray2d,
+ /// The maximum distance for the ray
+ pub max: f32,
+ /// The multiplicative inverse direction of the ray
+ direction_recip: Vec2,
+}
+
+impl RayTest2d {
+ /// Construct a [`RayTest2d`] from an origin, [`Direction2d`] and max distance.
+ pub fn new(origin: Vec2, direction: Direction2d, max: f32) -> Self {
+ Self::from_ray(Ray2d { origin, direction }, max)
+ }
+
+ /// Construct a [`RayTest2d`] from a [`Ray2d`] and max distance.
+ pub fn from_ray(ray: Ray2d, max: f32) -> Self {
+ Self {
+ ray,
+ direction_recip: ray.direction.recip(),
+ max,
+ }
+ }
+
+ /// Get the cached multiplicative inverse of the direction of the ray.
+ pub fn direction_recip(&self) -> Vec2 {
+ self.direction_recip
+ }
+
+ /// Get the distance of an intersection with an [`Aabb2d`], if any.
+ pub fn aabb_intersection_at(&self, aabb: &Aabb2d) -> Option<f32> {
+ let (min_x, max_x) = if self.ray.direction.x.is_sign_positive() {
+ (aabb.min.x, aabb.max.x)
+ } else {
+ (aabb.max.x, aabb.min.x)
+ };
+ let (min_y, max_y) = if self.ray.direction.y.is_sign_positive() {
+ (aabb.min.y, aabb.max.y)
+ } else {
+ (aabb.max.y, aabb.min.y)
+ };
+
+ // Calculate the minimum/maximum time for each axis based on how much the direction goes that
+ // way. These values can get arbitrarily large, or even become NaN, which is handled by the
+ // min/max operations below
+ let tmin_x = (min_x - self.ray.origin.x) * self.direction_recip.x;
+ let tmin_y = (min_y - self.ray.origin.y) * self.direction_recip.y;
+ let tmax_x = (max_x - self.ray.origin.x) * self.direction_recip.x;
+ let tmax_y = (max_y - self.ray.origin.y) * self.direction_recip.y;
+
+ // An axis that is not relevant to the ray direction will be NaN. When one of the arguments
+ // to min/max is NaN, the other argument is used.
+ // An axis for which the direction is the wrong way will return an arbitrarily large
+ // negative value.
+ let tmin = tmin_x.max(tmin_y).max(0.);
+ let tmax = tmax_y.min(tmax_x).min(self.max);
+
+ if tmin <= tmax {
+ Some(tmin)
+ } else {
+ None
+ }
+ }
+
+ /// Get the distance of an intersection with a [`BoundingCircle`], if any.
+ pub fn circle_intersection_at(&self, circle: &BoundingCircle) -> Option<f32> {
+ let offset = self.ray.origin - circle.center;
+ let projected = offset.dot(*self.ray.direction);
+ let closest_point = offset - projected * *self.ray.direction;
+ let distance_squared = circle.radius().powi(2) - closest_point.length_squared();
+ if distance_squared < 0. || projected.powi(2).copysign(-projected) < -distance_squared {
+ None
+ } else {
+ let toi = -projected - distance_squared.sqrt();
+ if toi > self.max {
+ None
+ } else {
+ Some(toi.max(0.))
+ }
+ }
+ }
+}
+
+impl IntersectsVolume<Aabb2d> for RayTest2d {
+ fn intersects(&self, volume: &Aabb2d) -> bool {
+ self.aabb_intersection_at(volume).is_some()
+ }
+}
+
+impl IntersectsVolume<BoundingCircle> for RayTest2d {
+ fn intersects(&self, volume: &BoundingCircle) -> bool {
+ self.circle_intersection_at(volume).is_some()
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const EPSILON: f32 = 0.001;
+
+ #[test]
+ fn test_ray_intersection_circle_hits() {
+ for (test, volume, expected_distance) in &[
+ (
+ // Hit the center of a centered bounding circle
+ RayTest2d::new(Vec2::Y * -5., Direction2d::Y, 90.),
+ BoundingCircle::new(Vec2::ZERO, 1.),
+ 4.,
+ ),
+ (
+ // Hit the center of a centered bounding circle, but from the other side
+ RayTest2d::new(Vec2::Y * 5., -Direction2d::Y, 90.),
+ BoundingCircle::new(Vec2::ZERO, 1.),
+ 4.,
+ ),
+ (
+ // Hit the center of an offset circle
+ RayTest2d::new(Vec2::ZERO, Direction2d::Y, 90.),
+ BoundingCircle::new(Vec2::Y * 3., 2.),
+ 1.,
+ ),
+ (
+ // Just barely hit the circle before the max distance
+ RayTest2d::new(Vec2::X, Direction2d::Y, 1.),
+ BoundingCircle::new(Vec2::ONE, 0.01),
+ 0.99,
+ ),
+ (
+ // Hit a circle off-center
+ RayTest2d::new(Vec2::X, Direction2d::Y, 90.),
+ BoundingCircle::new(Vec2::Y * 5., 2.),
+ 3.268,
+ ),
+ (
+ // Barely hit a circle on the side
+ RayTest2d::new(Vec2::X * 0.99999, Direction2d::Y, 90.),
+ BoundingCircle::new(Vec2::Y * 5., 1.),
+ 4.996,
+ ),
+ ] {
+ let case = format!(
+ "Case:\n Test: {:?}\n Volume: {:?}\n Expected distance: {:?}",
+ test, volume, expected_distance
+ );
+ assert!(test.intersects(volume), "{}", case);
+ let actual_distance = test.circle_intersection_at(volume).unwrap();
+ assert!(
+ (actual_distance - expected_distance).abs() < EPSILON,
+ "{}\n Actual distance: {}",
+ case,
+ actual_distance
+ );
+
+ let inverted_ray = RayTest2d::new(test.ray.origin, -test.ray.direction, test.max);
+ assert!(!inverted_ray.intersects(volume), "{}", case);
+ }
+ }
+
+ #[test]
+ fn test_ray_intersection_circle_misses() {
+ for (test, volume) in &[
+ (
+ // The ray doesn't go in the right direction
+ RayTest2d::new(Vec2::ZERO, Direction2d::X, 90.),
+ BoundingCircle::new(Vec2::Y * 2., 1.),
+ ),
+ (
+ // Ray's alignment isn't enough to hit the circle
+ RayTest2d::new(Vec2::ZERO, Direction2d::from_xy(1., 1.).unwrap(), 90.),
+ BoundingCircle::new(Vec2::Y * 2., 1.),
+ ),
+ (
+ // The ray's maximum distance isn't high enough
+ RayTest2d::new(Vec2::ZERO, Direction2d::Y, 0.5),
+ BoundingCircle::new(Vec2::Y * 2., 1.),
+ ),
+ ] {
+ assert!(
+ !test.intersects(volume),
+ "Case:\n Test: {:?}\n Volume: {:?}",
+ test,
+ volume,
+ );
+ }
+ }
+
+ #[test]
+ fn test_ray_intersection_circle_inside() {
+ let volume = BoundingCircle::new(Vec2::splat(0.5), 1.);
+ for origin in &[Vec2::X, Vec2::Y, Vec2::ONE, Vec2::ZERO] {
+ for direction in &[
+ Direction2d::X,
+ Direction2d::Y,
+ -Direction2d::X,
+ -Direction2d::Y,
+ ] {
+ for max in &[0., 1., 900.] {
+ let test = RayTest2d::new(*origin, *direction, *max);
+
+ let case = format!(
+ "Case:\n origin: {:?}\n Direction: {:?}\n Max: {}",
+ origin, direction, max,
+ );
+ assert!(test.intersects(&volume), "{}", case);
+
+ let actual_distance = test.circle_intersection_at(&volume);
+ assert_eq!(actual_distance, Some(0.), "{}", case);
+ }
+ }
+ }
+ }
+
+ #[test]
+ fn test_ray_intersection_aabb_hits() {
+ for (test, volume, expected_distance) in &[
+ (
+ // Hit the center of a centered aabb
+ RayTest2d::new(Vec2::Y * -5., Direction2d::Y, 90.),
+ Aabb2d::new(Vec2::ZERO, Vec2::ONE),
+ 4.,
+ ),
+ (
+ // Hit the center of a centered aabb, but from the other side
+ RayTest2d::new(Vec2::Y * 5., -Direction2d::Y, 90.),
+ Aabb2d::new(Vec2::ZERO, Vec2::ONE),
+ 4.,
+ ),
+ (
+ // Hit the center of an offset aabb
+ RayTest2d::new(Vec2::ZERO, Direction2d::Y, 90.),
+ Aabb2d::new(Vec2::Y * 3., Vec2::splat(2.)),
+ 1.,
+ ),
+ (
+ // Just barely hit the aabb before the max distance
+ RayTest2d::new(Vec2::X, Direction2d::Y, 1.),
+ Aabb2d::new(Vec2::ONE, Vec2::splat(0.01)),
+ 0.99,
+ ),
+ (
+ // Hit an aabb off-center
+ RayTest2d::new(Vec2::X, Direction2d::Y, 90.),
+ Aabb2d::new(Vec2::Y * 5., Vec2::splat(2.)),
+ 3.,
+ ),
+ (
+ // Barely hit an aabb on corner
+ RayTest2d::new(Vec2::X * -0.001, Direction2d::from_xy(1., 1.).unwrap(), 90.),
+ Aabb2d::new(Vec2::Y * 2., Vec2::ONE),
+ 1.414,
+ ),
+ ] {
+ let case = format!(
+ "Case:\n Test: {:?}\n Volume: {:?}\n Expected distance: {:?}",
+ test, volume, expected_distance
+ );
+ assert!(test.intersects(volume), "{}", case);
+ let actual_distance = test.aabb_intersection_at(volume).unwrap();
+ assert!(
+ (actual_distance - expected_distance).abs() < EPSILON,
+ "{}\n Actual distance: {}",
+ case,
+ actual_distance
+ );
+
+ let inverted_ray = RayTest2d::new(test.ray.origin, -test.ray.direction, test.max);
+ assert!(!inverted_ray.intersects(volume), "{}", case);
+ }
+ }
+
+ #[test]
+ fn test_ray_intersection_aabb_misses() {
+ for (test, volume) in &[
+ (
+ // The ray doesn't go in the right direction
+ RayTest2d::new(Vec2::ZERO, Direction2d::X, 90.),
+ Aabb2d::new(Vec2::Y * 2., Vec2::ONE),
+ ),
+ (
+ // Ray's alignment isn't enough to hit the aabb
+ RayTest2d::new(Vec2::ZERO, Direction2d::from_xy(1., 0.99).unwrap(), 90.),
+ Aabb2d::new(Vec2::Y * 2., Vec2::ONE),
+ ),
+ (
+ // The ray's maximum distance isn't high enough
+ RayTest2d::new(Vec2::ZERO, Direction2d::Y, 0.5),
+ Aabb2d::new(Vec2::Y * 2., Vec2::ONE),
+ ),
+ ] {
+ assert!(
+ !test.intersects(volume),
+ "Case:\n Test: {:?}\n Volume: {:?}",
+ test,
+ volume,
+ );
+ }
+ }
+
+ #[test]
+ fn test_ray_intersection_aabb_inside() {
+ let volume = Aabb2d::new(Vec2::splat(0.5), Vec2::ONE);
+ for origin in &[Vec2::X, Vec2::Y, Vec2::ONE, Vec2::ZERO] {
+ for direction in &[
+ Direction2d::X,
+ Direction2d::Y,
+ -Direction2d::X,
+ -Direction2d::Y,
+ ] {
+ for max in &[0., 1., 900.] {
+ let test = RayTest2d::new(*origin, *direction, *max);
+
+ let case = format!(
+ "Case:\n origin: {:?}\n Direction: {:?}\n Max: {}",
+ origin, direction, max,
+ );
+ assert!(test.intersects(&volume), "{}", case);
+
+ let actual_distance = test.aabb_intersection_at(&volume);
+ assert_eq!(actual_distance, Some(0.), "{}", case,);
+ }
+ }
+ }
+ }
+}