feat: Add Ray2 class to be used in raytracing/casting

packages/flame/lib/geometry.dart

@@ -2,6 +2,7 @@ export 'src/geometry/circle_component.dart';
 export 'src/geometry/line.dart';
 export 'src/geometry/line_segment.dart';
 export 'src/geometry/polygon_component.dart';
+export 'src/geometry/ray2.dart';
 export 'src/geometry/rectangle_component.dart';
 export 'src/geometry/shape_component.dart';
 export 'src/geometry/shape_intersections.dart';

packages/flame/lib/src/extensions/double.dart

@@ -0,0 +1,15 @@
+export 'dart:ui' show Color;
+
+extension DoubleExtension on double {
+ /// Converts +-[infinity] to +-[maxFinite].
+ /// If it is already a finite value, that is returned.
+ double toFinite() {
+ if (this == double.infinity) {
+ return double.maxFinite;
+ } else if (this == -double.infinity) {
+ return -double.maxFinite;
+ } else {
+ return this;
+ }
+ }
+}

packages/flame/lib/src/geometry/ray2.dart

@@ -0,0 +1,129 @@
+import 'dart:math';
+
+import 'package:flame/geometry.dart';
+import 'package:flame/src/extensions/double.dart';
+import 'package:meta/meta.dart';
+import 'package:vector_math/vector_math_64.dart';
+
+/// A ray in the 2d plane.
+///
+/// The [direction] should be normalized.
+class Ray2 {
+ Ray2(this.origin, Vector2 direction) {
+ this.direction = direction;
+ }
+
+ Ray2.zero() : this(Vector2.zero(), Vector2(1, 0));
+
+ Vector2 origin;
+ final Vector2 _direction = Vector2.zero();
+ Vector2 get direction => _direction;
+ set direction(Vector2 direction) {
+ assert(
+ (direction.length2 - 1).abs() < 0.000001,
+ 'direction must be normalized',
+ );
+ _direction.setFrom(direction);
+ directionInvX = (1 / direction.x).toFinite();
+ directionInvY = (1 / direction.y).toFinite();
+ }
+
+ // These are the inverse of the direction (the normal), they are used to avoid
+ // a division in [intersectsWithAabb2], since a ray will usually be tried
+ // against many bounding boxes it's good to pre-calculate it, which is done
+ // in the direction setter.
+ @visibleForTesting
+ late double directionInvX;
+ @visibleForTesting
+ late double directionInvY;
+
+ /// Whether the ray intersects the [box] or not.
+ ///
+ /// Rays that originate on the edge of the [box] are considered to be
+ /// intersecting with the box no matter what direction they have.
+ // This uses the Branchless Ray/Bounding box intersection method by Tavian,
+ // but since +-infinity is replaced by +-maxFinite for directionInvX and
+ // directionInvY, rays that originate on an edge will always be considered to
+ // intersect with the aabb, no matter what direction they have.
+ // https://tavianator.com/2011/ray_box.html
+ // https://tavianator.com/2015/ray_box_nan.html
+ bool intersectsWithAabb2(Aabb2 box) {
+ final tx1 = (box.min.x - origin.x) * directionInvX;
+ final tx2 = (box.max.x - origin.x) * directionInvX;
+
+ final ty1 = (box.min.y - origin.y) * directionInvY;
+ final ty2 = (box.max.y - origin.y) * directionInvY;
+
+ final tMin = max(min(tx1, tx2), min(ty1, ty2));
+ final tMax = min(max(tx1, tx2), max(ty1, ty2));
+
+ return tMax >= max(tMin, 0);
+ }
+
+ /// Gives the point at a certain length along the ray.
+ Vector2 point(double length, {Vector2? out}) {
+ return ((out?..setFrom(origin)) ?? origin.clone())
+ ..addScaled(direction, length);
+ }
+
+ static final Vector2 _v1 = Vector2.zero();
+ static final Vector2 _v2 = Vector2.zero();
+ static final Vector2 _v3 = Vector2.zero();
+ static final Vector2 _v4 = Vector2.zero();
+
+ /// Returns where (length wise) on the ray that the ray intersects the
+ /// [LineSegment] or null if there is no intersection.
+ ///
+ /// A ray that is parallel and overlapping with the [segment] is considered to
+ /// not intersect.
+ double? lineSegmentIntersection(LineSegment segment) {
+ _v1
+ ..setFrom(origin)
+ ..sub(segment.from);
+ _v2
+ ..setFrom(segment.to)
+ ..sub(segment.from);
+ _v3.setValues(-direction.y, direction.x);
+
+ final dot = _v2.dot(_v3);
+
+ if (dot == 0) {
+ // ray is parallel to line
+ if (segment.containsPoint(origin)) {
+ return 0;
+ } else {
+ final closestPoint = origin.distanceToSquared(segment.to) <
+ origin.distanceToSquared(segment.from)
+ ? segment.to
+ : segment.from;
+ _v4
+ ..setFrom(closestPoint)
+ ..sub(origin);
+ if (_v4.x.sign == direction.x.sign && _v4.y.sign == direction.y.sign) {
+ return _v4.length;
+ }
+ }
+ }
+
+ final t1 = _v2.cross(_v1) / dot;
+ final t2 = _v1.dot(_v3) / dot;
+ if (t1 >= 0 && t2 >= 0 && t2 <= 1) {
+ return t1;
+ }
+ return null;
+ }
+
+ /// Deep clones the object, i.e. both [origin] and [direction] are cloned into
+ /// a new [Ray2] object.
+ Ray2 clone() => Ray2(origin.clone(), direction.clone());
+
+ /// Sets the values by copying them from [other].
+ void setFrom(Ray2 other) {
+ setWith(origin: other.origin, direction: other.direction);
+ }
+
+ void setWith({required Vector2 origin, required Vector2 direction}) {
+ this.origin.setFrom(origin);
+ this.direction = direction;
+ }
+}

packages/flame/test/extensions/double_test.dart

@@ -0,0 +1,19 @@
+import 'package:flame/src/extensions/double.dart';
+import 'package:test/test.dart';
+
+void main() {
+ group('toFinite', () {
+ test('Properly converts infinite values to maxFinite', () {
+ const infinity = double.infinity;
+ expect(infinity.toFinite(), double.maxFinite);
+ const negativeInfinity = -double.infinity;
+ expect(negativeInfinity.toFinite(), -double.maxFinite);
+ });
+
+ test('Does not convert already finite value', () {
+ expect(0.0.toFinite(), 0.0);
+ expect(double.maxFinite.toFinite(), double.maxFinite);
+ expect((-double.maxFinite).toFinite(), -double.maxFinite);
+ });
+ });
+}