feat: 3D ray and line primitives added

Engine.Core/Primitives/Line3D.cs

@@ -0,0 +1,114 @@
+using System;
+
+namespace Engine.Core;
+
+/// <summary>
+/// Represents a 3D line segment defined by two endpoints.
+/// </summary>
+/// <param name="from">The starting point of the <see cref="Line3D"/> segment.</param>
+/// <param name="to">The ending point of the <see cref="Line3D"/> segment.</param>
+/// <remarks>
+/// Initializes a new instance of the <see cref="Line3D"/> struct with the specified endpoints.
+/// </remarks>
+[System.Diagnostics.DebuggerDisplay("From: {From.ToString(),nq}, To: {To.ToString(),nq}, Direction: {Direction.ToString(),nq}, Length: {Length}")]
+public readonly struct Line3D(Vector3D from, Vector3D to) : IEquatable<Line3D>
+{
+    /// <summary>
+    /// The starting point of the <see cref="Line3D"/> segment.
+    /// </summary>
+    public readonly Vector3D From = from;
+
+    /// <summary>
+    /// The ending point of the <see cref="Line3D"/> segment.
+    /// </summary>
+    public readonly Vector3D To = to;
+
+    /// <summary>
+    /// The reversed <see cref="Line3D"/> segment.
+    /// </summary>
+    public readonly Line3D Reversed => new(To, From);
+
+    /// <summary>
+    /// The normalized direction <see cref="Vector3D"/> of the <see cref="Line3D"/> segment.
+    /// </summary>
+    public readonly Vector3D Direction => From.FromTo(To).Normalize();
+
+    /// <summary>
+    /// The length of the <see cref="Line3D"/> segment.
+    /// </summary>
+    public readonly float Length => From.FromTo(To).Length();
+
+    /// <summary>
+    /// The squared length of the <see cref="Line3D"/> segment.
+    /// </summary>
+    public readonly float LengthSquared => From.FromTo(To).LengthSquared();
+
+    public static bool operator ==(Line3D left, Line3D right) => left.From == right.From && left.To == right.To;
+    public static bool operator !=(Line3D left, Line3D right) => left.From != right.From || left.To != right.To;
+
+    /// <summary>
+    /// Linearly interpolates between the two endpoints of the <see cref="Line3D"/> segment using parameter 't'.
+    /// </summary>
+    public static Vector3D Lerp(Line3D line, float t)
+        => Vector3D.Lerp(line.From, line.To, t);
+
+    /// <summary>
+    /// Calculates the closest point on the <see cref="Line3D"/> segment to the specified point.
+    /// </summary>
+    public static Vector3D ClosestPointTo(Line3D line, Vector3D point)
+    {
+        Vector3D lineRelativeVector = line.From.FromTo(line.To);
+
+        Vector3D lineDirection = lineRelativeVector.Normalized;
+        Vector3D pointVector = line.From.FromTo(point);
+
+        float dot = lineDirection.Dot(pointVector).Clamp(0f, lineRelativeVector.Magnitude);
+
+        return lineDirection * dot;
+    }
+
+    /// <summary>
+    /// Checks if two <see cref="Line3D"/> segments are approximately equal.
+    /// </summary>
+    /// <param name="left">The first <see cref="Line3D"/>.</param>
+    /// <param name="right">The second <see cref="Line3D"/>.</param>
+    /// <param name="epsilon">The epsilon range.</param>
+    /// <returns><see cref="true"/> if the <see cref="Line3D"/>s are approximately equal; otherwise, <see cref="false"/>.</returns>
+    public static bool ApproximatelyEquals(Line3D left, Line3D right, float epsilon = float.Epsilon)
+        => left.From.ApproximatelyEquals(right.From, epsilon) && left.To.ApproximatelyEquals(right.To, epsilon);
+
+    /// <summary>
+    /// Determines whether the specified object is equal to the current <see cref="Line3D"/>.
+    /// </summary>
+    /// <param name="obj">The object to compare with the current <see cref="Line3D"/>.</param>
+    /// <returns><see cref="true"/> if the specified object is equal to the current <see cref="Line3D"/>; otherwise, <see cref="false"/>.</returns>
+    public override bool Equals(object? obj) => obj is Line3D line3D && this == line3D;
+    public bool Equals(Line3D other) => this == other;
+
+    /// <summary>
+    /// Generates a hash code for the <see cref="Line3D"/>.
+    /// </summary>
+    /// <returns>A hash code for the <see cref="Line3D"/>.</returns>
+    public override int GetHashCode() => System.HashCode.Combine(From, To);
+
+    /// <summary>
+    /// Converts the <see cref="Line3D"/> to its string representation.
+    /// </summary>
+    /// <returns>A string representation of the <see cref="Line3D"/>.</returns>
+    public override string ToString() => $"{nameof(Line3D)}({From}, {To})";
+}
+
+/// <summary>
+/// Provides extension methods for the <see cref="Line3D"/> struct.
+/// </summary>
+public static class Line3DExtensions
+{
+    /// <inheritdoc cref="Line3D.Lerp(Line3D, float)" />
+    public static Vector3D Lerp(this Line3D line, float t) => Line3D.Lerp(line, t);
+
+    /// <inheritdoc cref="Line3D.ClosestPointTo(Line3D, Vector3D)" />
+    public static Vector3D ClosestPointTo(this Line3D line, Vector3D point) => Line3D.ClosestPointTo(line, point);
+
+    /// <inheritdoc cref="Line3D.ApproximatelyEquals(Line3D, Line3D, float)" />
+    public static bool ApproximatelyEquals(this Line3D left, Line3D right, float epsilon = float.Epsilon) => Line3D.ApproximatelyEquals(left, right, epsilon);
+}