Implement stub documentation & small refactors on J2D namespace

include/JGL/JGL.h

@@ -13,6 +13,7 @@
 #include <J3ML/Geometry/Sphere.h>
 #include <J3ML/Geometry/Capsule.h>
 #include <J3ML/Geometry/TriangleMesh.h>
+
 // OpenGL Wrapper for rendering 2D graphics primitives in both a 2D and 3D context
 namespace JGL {
 
@@ -56,42 +57,83 @@ namespace JGL {
     void UnloadFont(int font_index);
     // TODO: implement correct coloring
 
+    /// Drawing functions for primitive 2D Shapes.
+    /// Each function is overloaded with Color3 and Color4 for optional transparency.
     namespace J2D {
+
+        /// Open a 2-D rendering context with the underlying graphics system (In this case & by default OpenGL).
+        /// @note This call may not strictly be necessary on some setups, but is provided to keep the API constant.
+        /// It is recommended to always open a JGL 2D context to render your content, then close when completed.
+        /// This keeps our code from, say, clobbering the OpenGL rendering context driving 3D content in between our calls.
         void Begin();
+        /// Closes a 2-D rendering context with the underlying graphics system (In this case & by default OpenGL).
+        /// @see Begin().
         void End();
+
+        /// Plots a single pixel on the screen.
+        /// @param color  A 3-or-4 channel color value. @see classes Color3, Color4
+        /// @param coordinates The pixel-point on-screen at which to plot the pixel.
+        void DrawPixel(const Color3& color, const Vector2& coordinates);
+        void DrawPixel(const Color3& color, float x, float y);
         void DrawPixel(const Color4& color, const Vector2& coordinates);
         void DrawPixel(const Color4& color, float x, float y);
+
+        /// Plots a line (segment) on the screen.
+        /// @param color A 3-or-4 channel color value. @see classes Color3, Color4.
+        /// @param A The starting point of the line segment.
+        /// @param B The end point of the line segment.
+        /// @param thickness The width at which to render the line.
+        void DrawLine(const Color3& color, const Vector2& A, const Vector2& B, float thickness = 1);
+        void DrawLine(const Color3 &color, float x, float y, float w, float h, float thickness = 1);
         void DrawLine(const Color4& color, const Vector2& A, const Vector2& B, float thickness = 1);
-        void DrawLine(const Color4& color, float x, float y, float w, float h, float thickness = 1);
-        void DrawCubicBezierCurve();
-        void OutlineCircle(const Color4& color, const Vector2& center, float radius, int subdivisions, float thickness = 1);
-        void FillCircle(const Color4& color, const Vector2& center, float radius, int subdivisions);
+        void DrawLine(const Color4& color, float x1, float y1, float x2, float y2, float thickness = 1);
+
+        /// Draws an outline of a rectangle on the screen.
+        void OutlineRect(const Color4& color, const Vector2& pos, const Vector2& size, float thickness = 1);
+        void OutlineRect(const Color3& color, const Vector2& pos, const Vector2& size, float thickness = 1);
+
+        /// Draws a filled rectangle on the screen.
+        void FillRect(const Color4& color, const Vector2& pos, const Vector2& size);
+        void FillRect(const Color3& color, const Vector2& pos, const Vector2& size);
+
+
+        /// Draws an outline of a rectangle with rounded corners on the screen.
+        void OutlineRoundedRect(const Color4& color, const Vector2& pos, const Vector2& size, float radius = 5, float thickness = 1);
+
+        /// Draws a filled rectangle with rounded corners on the screen.
+        void FillRoundedRect(const Color4 &color, const Vector2 &pos, const Vector2 &size, float radius = 5, unsigned int subdivisions = 10);
+        void FillRoundedRect(const Color3& color, const Vector2& pos, const Vector2& size, float radius = 5, unsigned int subdivisions = 10);
+
+        /// Draws an outline of a circle on the screen.
+        void OutlineCircle(const Color4& color, const Vector2& center, float radius, unsigned int subdivisions = 16, float thickness = 1);
+        void OutlineCircle(const Color3& color, const Vector2& center, float radius, unsigned int subdivisions = 16, float thickness = 1);
+
+        /// Draws a filled circle on the screen.
+        void FillCircle(const Color4& color, const Vector2& center, float radius, unsigned int subdivisions = 16);
+        void FillCircle(const Color3& color, const Vector2& center, float radius, unsigned int subdivisions = 16);
+
+        /// Draws an outline of a triangle on the screen.
         void OutlineTriangle(const Color4& color, const Triangle2D& tri, float thickness = 1);
+        void OutlineTriangle(const Color3& color, const Triangle2D& tri, float thickness = 1);
+        // TODO: Implement an overload that simply takes 3 Vector3's
+
+        /// Draws a filled triangle on the screen.
         void FillTriangle(const Color4& color, const Triangle2D &tri);
+        void FillTriangle(const Color3& color, const Triangle2D& tri);
+        // TODO: Implement an overload that simply takes 3 Vector3's
+
+        /// Draws a text string on the screen with a given point-size and font.
+        void DrawString(const Color3& color, std::string text, float x, float y, float scale, u32 size, unsigned int font_index);
+
+        // TODO: Implement the following:
         void FillTexturedTriangle();
         void FillTexturedPolygon();
         void DrawSprite();
         void DrawPartialSprite();
-        void DrawString(const Color3& color, std::string text, float x, float y, float scale, u32 size, unsigned int font_index);
-        void FillRect(const Color4& color, const Vector2& pos, const Vector2& size);
-        void OutlineRect       ( const Color4& color, const Vector2& pos, const Vector2& size, float thickness = 1);
-        void RoundedFillRect  (const Color4 &color, const Vector2 &pos, const Vector2 &size, float radius, unsigned int subdivisions);
-        void OutlineRoundedRect(const Color4& color, const Vector2& pos, const Vector2& size, float radius, float thickness = 1);
+        void DrawCubicBezierCurve();
         void OutlinePolygon    (const Color4& color, std::vector<Vector2> points);
         void FillPolygon       (const Color4& color, std::vector<Vector2> points, float thickness = 1);
         void GradientFillRect  ();
-
-        void FillRect(const Color3& color, const Vector2& pos, const Vector2& size);
-        void OutlineRect(const Color3& color, const Vector2& pos, const Vector2& size, float thickness = 1);
-        void DrawLine(const Color3& color, const Vector2& A, const Vector2& B, float thickness = 1);
-        void DrawLine(const Color3& color, float x, float y, float w, float h, float thickness = 1);
-        void DrawPixel(const Color3& color, const Vector2& coordinates);
-        void DrawPixel(const Color3& color, float x, float y);
-        void OutlineCircle(const Color3& color, const Vector2& center, float radius, int subdivisions, float thickness = 1);
-        void FillCircle(const Color3& color, const Vector2& center, float radius, int subdivisions);
-        void OutlineTriangle(const Color3& color, const Triangle2D& tri, float thickness = 1);
-        void FillTriangle(const Color3& color, const Triangle2D& tri);
-        void RoundedFillRect(const Color3& color, const Vector2& pos, const Vector2& size, float radius, unsigned int subdivisions);
     }
     namespace J3D {
         void Begin();