Implement Sphere documentation

include/J3ML/Geometry/Sphere.h

@@ -1,5 +1,15 @@
-#pragma once
+/// Josh's 3D Math Library
+/// A C++20 Library for 3D Math, Computer Graphics, and Scientific Computing.
+/// Developed and Maintained by Josh O'Leary @ Redacted Software.
+/// Special Thanks to William Tomasine II and Maxine Hayes.
+/// (c) 2024 Redacted Software
+/// This work is dedicated to the public domain.
 
+/// @file Sphere.hpp
+/// @desc The Sphere geometry object.
+/// @edit 2024-07-06
+
+#pragma once
 
 
 #include <J3ML/Geometry.h>
@@ -15,15 +25,38 @@ namespace J3ML::Geometry
     using J3ML::LinearAlgebra::Matrix4x4;
 
     // A mathematical representation of a 3-dimensional sphere
-    class Sphere : public Shape
+    class Sphere
     {
-    public:
-        Vector3 Position;
-        float Radius;
-    public:
+    public: // Properties
+        Vector3 Position; // The center point of this sphere.
+        float Radius; /// The radius of this sphere.
+    public: // Constructors
+
+        /// The default constructor does not initialize any members of this class.
+        /** This means that the values of the members pos and r are undefined after creating a new Sphere using this
+            default constructor. Remember to assign to them before use.
+            @see pos, r. */
         Sphere() {}
+        /// Constructs a sphere with a given position and radius.
+        /** @param radius A value > 0 constructs a sphere with positive volume. A value of <= 0 is valid, and constructs a degenerate sphere.
+            @see pos, r, IsFinite(), IsDegenerate() */
         Sphere(const Vector3& pos, float radius) : Position(pos), Radius(radius) {}
 
+        /// Constructs a sphere that passes through the given two points.
+        /** The constructed sphere will be the minimal sphere that encloses the given two points. The center point of this
+            sphere will lie midway between pointA and pointB, and the radius will be half the distance between pointA and
+            pointB. Both input points are assumed to be finite. */
+        Sphere(const Vector3 &pointA, const Vector3 &pointB);
+
+        /// Constructs a sphere that passes through the given three points.
+        /** @note The resulting sphere may not be the minimal enclosing sphere for the three points! */
+        Sphere(const Vector3 &pointA, const Vector3 &pointB, const Vector3 &pointC);
+
+        /// Constructs a sphere that passes through the given four points.
+        /** @note The resulting sphere may not be the minimal enclosing sphere for the four points! */
+        Sphere(const Vector3 &pointA, const Vector3 &pointB, const Vector3 &pointC, const Vector3 &pointD);
+
+    public:
         /// Generates a random point on the surface of this sphere
         /** The points are distributed uniformly.
             This function uses the rejection method to generate a uniform distribution of points on the surface.
@@ -58,8 +91,15 @@ namespace J3ML::Geometry
         Vector3 ExtremePoint(const Vector3 &direction, float &projectionDistance) const;
 
 
+        Vector3 Centroid() const { return Position; }
+        Vector3 CenterPos() const { return Centroid(); }
+
+        /// Translates this Sphere in world space.
+        /** @param offset The amount of displacement to apply to this Sphere, in world space coordinates.
+            @see Transform(). */
         void Translate(const Vector3& offset);
 
+
         void Transform(const Matrix3x3& transform);
 
         void Transform(const Matrix4x4& transform);