Outline of Documentation work

2024-10-18 14:50:20 -04:00
parent 4893233301
commit 6866ba828b
1 changed files with 82 additions and 54 deletions
--- a/include/JGL/JGL.h
+++ b/include/JGL/JGL.h
@@ -65,9 +65,9 @@ namespace JGL {

        /// Plots a series of pixel-points on the screen, in a batch.
        /// @note This is more performant for multiple points than plotting them individually.
-        /// @param color
-        /// @param points
-        /// @param radius
+        /// @param color A 3-or-4 channel color value. @see class Color3, class Color4
+        /// @param points A set of x,y points to render.
+        /// @param radius The size of the point to plot. By default, a single pixel.
        void DrawPoints(const Color4& color, const Vector2* points, int num_points, float radius = 1.f);

        /// Plots a line (segment) on the screen.
@@ -78,91 +78,102 @@ namespace JGL {
        void DrawLine(const Color4& color, const Vector2& A, const Vector2& B, float thickness = 1);
        void DrawLine(const Color4& color, float x1, float y1, float x2, float y2, float thickness = 1);

-        /// Draws a line with a gradient that transitions across it.
-        /// @param color_a
-        /// @param color_b
-        /// @param A
-        /// @param B
-        /// @param thickness
+        /// Draws a line with a color gradient that transitions across it.
+        /// @param color_a A 3-or-4 channel color value. @see class Color3, class Color4
+        /// @param color_b A 3-or-4 channel color value. @see class Color3, class 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 DrawGradientLine(const Color4& color_a, const Color4& color_b, const Vector2& A, const Vector2& B, float thickness = 1);
        void DrawGradientLine(const Color4& color_a, const Color4& color_b, float x, float y, float w, float h, float thickness = 1);

        /// Draws an outline of a rectangle on the screen.
-        /// @param color
-        /// @param pos
-        /// @param size
-        /// @param thickness
+        /// @param color A 3-or-4 channel color value. @see class Color3, class Color4
+        /// @param pos The top-left corner of the rectangle.
+        /// @param size The width and height of the rectangle.
+        /// @param thickness The width at which to render the lines.
        void OutlineRect(const Color4& color, const Vector2& pos, const Vector2& size, float thickness = 1);

        /// Draws an outline of a rectangle with rounded corners onto the screen.
-        /// @param color
-        /// @param pos
-        /// @param size
-        /// @param radius
-        /// @param thickness
+        /// @param color A 3-or-4 channel color value. @see class Color3, class Color4
+        /// @param pos The top-left corner of the rectangle.
+        /// @param size The width and height of the rectangle.
+        /// @param radius The corner-rounding radius (in radians).
+        /// @param thickness The width at which to render the lines.
        void OutlineRoundedRect(const Color4& color, const Vector2& pos, const Vector2& size, float radius = 5, float thickness = 1);

        /// Draws an outline of a rectangle with chamfered corners onto the screen.
-        /// @param color
-        /// @param pos
-        /// @param size
-        /// @param radius
-        /// @param thickness
+        /// @param color A 3-or-4 channel color value. @see class Color3, class Color4
+        /// @param pos The top-left corner of the rectangle.
+        /// @param size The width and height of the rectangle.
+        /// @param radius The corner-rounding radius (in radians).
+        /// @param thickness The width at which to render the lines.
        void OutlineChamferRect(const Color4& color, const Vector2& pos, const Vector2& size, float radius = 5, float thickness = 1);

        /// Draws a filled rectangle on the screen.
-        /// @param color
-        /// @param pos
-        /// @param size
+        /// @param color A 3-or-4 channel color value. @see class Color3, class Color4
+        /// @param pos The top-left corner of the rectangle.
+        /// @param size The width and height of the rectangle.
        /// @see FillRoundedRect, FillGradientRect, FillChamferRect.
        void FillRect(const Color4& color, const Vector2& pos, const Vector2& size);

        /// Draws a filled rectangle where the color transitions across it.
-        /// @param color1
-        /// @param color2
-        /// @param gradient
-        /// @param pos
-        /// @param size
+        /// @param color1 A 3-or-4 channel color value. @see class Color3, class Color4
+        /// @param color2 A 3-or-4 channel color value. @see class Color3, class Color4
+        /// @param gradient See enum Direction
+        /// @param pos The top-left corner of the rectangle.
+        /// @param size The width and height of the rectangle.
        void FillGradientRect(const Color4& color1, const Color4& color2, const Direction& gradient, const Vector2& pos, const Vector2& size);

        /// Draws a filled rectangle with rounded corners on the screen.
-        /// @param color
-        /// @param pos
-        /// @param size
-        /// @param radius
-        /// @param subdivisions
+        /// @param color A 3-or-4 channel color value. @see class Color3, class Color4
+        /// @param pos The top-left corner of the rectangle.
+        /// @param size The width and height of the rectangle.
+        /// @param radius The corner-rounding radius (in radians).
+        /// @param subdivisions The amount of sub-divisions (and calculations) to be performed per-arc rounding corner.
        void FillRoundedRect(const Color4& color, const Vector2& pos, const Vector2& size, float radius = 5, unsigned int subdivisions = 8);

        /// Draws a filled rectangle with chamfered (beveled) corners on the screen.
-        /// @param color
-        /// @param pos
-        /// @param size
-        /// @param radius
+        /// @param color A 3-or-4 channel color value. @see class Color3, class Color4
+        /// @param pos The top-left corner of the rectangle.
+        /// @param size The width and height of the rectangle.
+        /// @param radius The corner-rounding radius (in radians).
        void FillChamferRect(const Color4& color, const Vector2& pos, const Vector2& size, float radius = 5);


-        void DrawRenderTarget(const RenderTarget& render_target, const Vector2& position, float rad_rotation = 0, const Vector2& origin = Vector2(0 , 0),
-                              const Vector2& scale = Vector2(1, 1), const Color4& color = Colors::White, Direction inversion = Direction::None);
-        void DrawRenderTarget(const RenderTarget* render_target, const Vector2& position, float rad_rotation = 0, const Vector2& origin = Vector2(0 , 0),
-                              const Vector2& scale = Vector2(1, 1), const Color4& color = Colors::White, Direction inversion = Direction::None);

-
-        /// Draws a render target to the screen.
-        /// @param render_target
+        /// Draws a render-target (runtime-modifiable texture) to the screen.
+        /// @param render_target A RenderTarget instance to be displayed.
        /// @param position
        /// @param rad_rotation
        /// @param origin
        /// @param scale
        /// @param color
        /// @param inversion
+        void DrawRenderTarget(const RenderTarget& render_target, const Vector2& position, float rad_rotation = 0, const Vector2& origin = Vector2(0 , 0),
+                              const Vector2& scale = Vector2(1, 1), const Color4& color = Colors::White, Direction inversion = Direction::None);
+        void DrawRenderTarget(const RenderTarget* render_target, const Vector2& position, float rad_rotation = 0, const Vector2& origin = Vector2(0 , 0),
+                              const Vector2& scale = Vector2(1, 1), const Color4& color = Colors::White, Direction inversion = Direction::None);
+
+
+        /// Draws a sprite (technically, actually a render target) to the screen.
+        /// @note This similar overload exists because we expect someone will be an idiot and turn all of their sprites into RenderTargets. ~william
+        /// @param render_target A RenderTarget instance to be displayed.
+        /// @param position
+        /// @param rad_rotation
+        /// @param origin
+        /// @param scale
+        /// @param color
+        /// @param inversion
+        /// @see DrawSprite
        void DrawSprite(const RenderTarget& render_target, const Vector2& position, float rad_rotation = 0, const Vector2& origin = Vector2(0 , 0),
                const Vector2& scale = Vector2(1, 1), const Color4& color = Colors::White, Direction inversion = Direction::None);
        void DrawSprite(const RenderTarget* render_target, const Vector2& position, float rad_rotation = 0, const Vector2& origin = Vector2(0 , 0),
                        const Vector2& scale = Vector2(1, 1), const Color4& color = Colors::White, Direction inversion = Direction::None);

        /// Draws a sprite to the screen by passing a G̶L̶u̶i̶n̶t̶ JGL Texture that represents a handle to a loaded texture.
-        /// @param texture
-        /// @param position
+        /// @param texture A texture instance to be displayed.
+        /// @param position The point at which to draw the sprite (from the top-left down).
        /// @param origin The center point around which the image should have all transformations applied to it.
        /// @param scale The scale transformation for the image. X and Y axis are independently-scalable.
        /// @param rad_rotation A float representing the rotation of the sprite where 0 is no rotation and 1 is the maximum rotation (would look the same as 0).
@@ -239,21 +250,32 @@ namespace JGL {
        void FillGradientTriangle(const Color4& a_color, const Color4& b_color, const Color4& c_color, const Triangle2D& tri);

        /// Draws a smooth, curved line segment between two control points, with the curve controlled by the two inner points.
+        /// @param color
+        /// @param controlA
+        /// @param pointA
+        /// @param pointB
+        /// @param controlB
        /// @see J3ML::Algorithm::Bezier
        void DrawCubicBezierCurve(const Color4& color, const Vector2& controlA, const Vector2& pointA, const Vector2& pointB, const Vector2& controlB,
                                  int subdivisions = 10, float thickness = 1);

        /// Draws a series of points where the last point always connects to the first point.
+        /// @param color
+        /// @param points
+        /// @param points_size
+        /// @param thickness
        void OutlinePolygon(const Color4& color, const Vector2* points, int points_size, float thickness = 1);

        /// Draws a text string on the screen with a given point-size and font.
+        /// @param color
+        /// @param text
+        /// @param x
+        /// @param y
+        /// @param scale
+        /// @param size
+        /// @param font
        void DrawString(const Color4& color, const std::string& text, float x, float y, float scale, u32 size, const Font& font);

-        /// TODO Implement the following. These ones are going to be extremely annoying.
-        void FillPolygon(const Color4& color, const std::vector<Vector2>& points);
-        void FillTexturedPolygon();
-
-        void FillTexturedTriangle();

        /// Draws an Arc (section of a circle) to the screen.
        /// @param color
@@ -265,6 +287,12 @@ namespace JGL {
        /// @param thickness
        void DrawArc(const Color4& color, const Vector2& center, float radius, float arc_begin, float arc_end,
                     unsigned int subdivisions, float thickness);
+
+
+        /// TODO Implement the following. These ones are going to be extremely annoying.
+        void FillPolygon(const Color4& color, const std::vector<Vector2>& points);
+        void FillTexturedPolygon();
+        void FillTexturedTriangle();
    }

    /// Drawing functions for primitive 3D Shapes.