Add some more documentation and methods to Geometry classes

dgl/Geometry.hpp

@@ -30,8 +30,12 @@ template<typename> class Triangle;
 template<typename> class Rectangle;
 
 // -----------------------------------------------------------------------
-// Point
 
+/**
+   DGL Point class.
+
+   This class describes a single point in space, defined by an X and Y value.
+ */
 template<typename T>
 class Point
 {
@@ -62,17 +66,17 @@ public:
     const T& getY() const noexcept;
 
    /**
-      Set X value as @a x.
+      Set X value to @a x.
     */
     void setX(const T& x) noexcept;
 
    /**
-      Set Y value as @a y.
+      Set Y value to @a y.
     */
     void setY(const T& y) noexcept;
 
    /**
-      Set X and Y values as @a x and @a y respectively.
+      Set X and Y values to @a x and @a y respectively.
     */
     void setPos(const T& x, const T& y) noexcept;
 
@@ -96,6 +100,11 @@ public:
     */
     bool isZero() const noexcept;
 
+   /**
+      Return true if point is not (0, 0).
+    */
+    bool isNotZero() const noexcept;
+
     Point<T> operator+(const Point<T>& pos) noexcept;
     Point<T> operator-(const Point<T>& pos) noexcept;
     Point<T>& operator=(const Point<T>& pos) noexcept;
@@ -113,8 +122,12 @@ private:
 };
 
 // -----------------------------------------------------------------------
-// Size
 
+/**
+   DGL Size class.
+
+   This class describes a size, defined by a width and height value.
+ */
 template<typename T>
 class Size
 {
@@ -155,7 +168,7 @@ public:
     void setHeight(const T& height) noexcept;
 
    /**
-      Set size using @a width and @a height.
+      Set size to @a width and @a height.
     */
     void setSize(const T& width, const T& height) noexcept;
 
@@ -176,14 +189,27 @@ public:
 
    /**
       Return true if size is null (0x0).
+      An null size is also invalid.
     */
     bool isNull() const noexcept;
 
    /**
       Return true if size is not null (0x0).
+      A non-null size is still invalid if its width or height is negative.
     */
     bool isNotNull() const noexcept;
 
+   /**
+      Return true if size is valid (width and height are higher than zero).
+    */
+    bool isValid() const noexcept;
+
+   /**
+      Return true if size is invalid (width or height are lower or equal to zero).
+      An invalid size might not be null under some circumstances.
+    */
+    bool isInvalid() const noexcept;
+
     Size<T> operator+(const Size<T>& size) noexcept;
     Size<T> operator-(const Size<T>& size) noexcept;
     Size<T>& operator=(const Size<T>& size) noexcept;
@@ -200,14 +226,18 @@ private:
 };
 
 // -----------------------------------------------------------------------
-// Line
 
+/**
+   DGL Line class.
+
+   This class describes a line, defined by two points.
+ */
 template<typename T>
 class Line
 {
 public:
    /**
-      Constructor for a null line ([0, 0] to [0, 0]).
+      Constructor for a null line ([0,0] to [0,0]).
     */
     Line() noexcept;
 
@@ -217,7 +247,7 @@ public:
     Line(const T& startX, const T& startY, const T& endX, const T& endY) noexcept;
 
    /**
-      Constructor using custom start X, start Y, end pos values.
+      Constructor using custom start X, start Y and end pos values.
     */
     Line(const T& startX, const T& startY, const Point<T>& endPos) noexcept;
 
@@ -267,17 +297,17 @@ public:
     const Point<T>& getEndPos() const noexcept;
 
    /**
-      Set start X value as @a x.
+      Set start X value to @a x.
     */
     void setStartX(const T& x) noexcept;
 
    /**
-      Set start Y value as @a y.
+      Set start Y value to @a y.
     */
     void setStartY(const T& y) noexcept;
 
    /**
-      Set start X and Y values as @a x and @a y respectively.
+      Set start X and Y values to @a x and @a y respectively.
     */
     void setStartPos(const T& x, const T& y) noexcept;
 
@@ -287,17 +317,17 @@ public:
     void setStartPos(const Point<T>& pos) noexcept;
 
    /**
-      Set end X value as @a x.
+      Set end X value to @a x.
     */
     void setEndX(const T& x) noexcept;
 
    /**
-      Set end Y value as @a y.
+      Set end Y value to @a y.
     */
     void setEndY(const T& y) noexcept;
 
    /**
-      Set end X and Y values as @a x and @a y respectively.
+      Set end X and Y values to @a x and @a y respectively.
     */
     void setEndPos(const T& x, const T& y) noexcept;
 
@@ -321,6 +351,16 @@ public:
     */
     void draw();
 
+   /**
+      Return true if line is null (start and end pos are equal).
+    */
+    bool isNull() const noexcept;
+
+   /**
+      Return true if line is not null (start and end pos are different).
+    */
+    bool isNotNull() const noexcept;
+
     Line<T>& operator=(const Line<T>& line) noexcept;
     bool operator==(const Line<T>& line) const noexcept;
     bool operator!=(const Line<T>& line) const noexcept;
@@ -330,8 +370,15 @@ private:
 };
 
 // -----------------------------------------------------------------------
-// Circle
 
+/**
+   DGL Circle class.
+
+   This class describes a circle, defined by position, size and a minimum of 3 segments.
+
+   TODO: report if circle starts at top-left, bottom-right or center.
+         and size grows from which point?
+ */
 template<typename T>
 class Circle
 {
@@ -372,17 +419,17 @@ public:
     const Point<T>& getPos() const noexcept;
 
    /**
-      Set X value as @a x.
+      Set X value to @a x.
     */
     void setX(const T& x) noexcept;
 
    /**
-      Set Y value as @a y.
+      Set Y value to @a y.
     */
     void setY(const T& y) noexcept;
 
    /**
-      Set X and Y values as @a x and @a y respectively.
+      Set X and Y values to @a x and @a y respectively.
     */
     void setPos(const T& x, const T& y) noexcept;
 
@@ -435,12 +482,16 @@ private:
     // cached values
     float fTheta, fCos, fSin;
 
-    void _draw(const bool isOutline);
+    void _draw(const bool outline);
 };
 
 // -----------------------------------------------------------------------
-// Triangle
 
+/**
+   DGL Triangle class.
+
+   This class describes a triangle, defined by 3 points.
+ */
 template<typename T>
 class Triangle
 {
@@ -475,6 +526,29 @@ public:
     */
     void drawOutline();
 
+   /**
+      Return true if triangle is null (all its points are equal).
+      An null triangle is also invalid.
+    */
+    bool isNull() const noexcept;
+
+   /**
+      Return true if triangle is not null (one its points is different from the others).
+      A non-null triangle is still invalid if two of its points are equal.
+    */
+    bool isNotNull() const noexcept;
+
+   /**
+      Return true if triangle is valid (all its points are different).
+    */
+    bool isValid() const noexcept;
+
+   /**
+      Return true if triangle is invalid (one or two of its points are equal).
+      An invalid triangle might not be null under some circumstances.
+    */
+    bool isInvalid() const noexcept;
+
     Triangle<T>& operator=(const Triangle<T>& tri) noexcept;
     bool operator==(const Triangle<T>& tri) const noexcept;
     bool operator!=(const Triangle<T>& tri) const noexcept;
@@ -482,12 +556,16 @@ public:
 private:
     Point<T> fPos1, fPos2, fPos3;
 
-    void _draw(const bool isOutline);
+    void _draw(const bool outline);
 };
 
 // -----------------------------------------------------------------------
-// Rectangle
 
+/**
+   DGL Rectangle class.
+
+   This class describes a rectangle, defined by a starting point and a size.
+ */
 template<typename T>
 class Rectangle
 {
@@ -662,7 +740,7 @@ private:
     Point<T> fPos;
     Size<T>  fSize;
 
-    void _draw(const bool isOutline);
+    void _draw(const bool outline);
 };
 
 // -----------------------------------------------------------------------

dgl/src/Geometry.cpp

@@ -98,6 +98,12 @@ bool Point<T>::isZero() const noexcept
     return fX == 0 && fY == 0;
 }
 
+template<typename T>
+bool Point<T>::isNotZero() const noexcept
+{
+    return fX != 0 || fY != 0;
+}
+
 template<typename T>
 Point<T> Point<T>::operator+(const Point<T>& pos) noexcept
 {
@@ -228,6 +234,17 @@ bool Size<T>::isNotNull() const noexcept
     return fWidth != 0 || fHeight != 0;
 }
 
+template<typename T>
+bool Size<T>::isValid() const noexcept
+{
+    return fWidth > 1 && fHeight > 1;
+}
+
+template<typename T>
+bool Size<T>::isInvalid() const noexcept
+{
+    return fWidth <= 0 || fHeight <= 0;
+}
 
 template<typename T>
 Size<T> Size<T>::operator+(const Size<T>& size) noexcept
@@ -427,16 +444,30 @@ void Line<T>::moveBy(const Point<T>& pos) noexcept
 template<typename T>
 void Line<T>::draw()
 {
+    DISTRHO_SAFE_ASSERT_RETURN(fPosStart != fPosEnd,);
+
     glBegin(GL_LINES);
 
     {
-        glVertex2i(fPosStart.fX, fPosStart.fY);
-        glVertex2i(fPosEnd.fX, fPosEnd.fY);
+        glVertex2d(fPosStart.fX, fPosStart.fY);
+        glVertex2d(fPosEnd.fX, fPosEnd.fY);
     }
 
     glEnd();
 }
 
+template<typename T>
+bool Line<T>::isNull() const noexcept
+{
+    return fPosStart == fPosEnd;
+}
+
+template<typename T>
+bool Line<T>::isNotNull() const noexcept
+{
+    return fPosStart != fPosEnd;
+}
+
 template<typename T>
 Line<T>& Line<T>::operator=(const Line<T>& line) noexcept
 {
@@ -620,14 +651,13 @@ bool Circle<T>::operator!=(const Circle<T>& cir) const noexcept
 }
 
 template<typename T>
-void Circle<T>::_draw(const bool isOutline)
+void Circle<T>::_draw(const bool outline)
 {
-    if (fNumSegments < 3 || fSize <= 0.0f)
-        return;
+    DISTRHO_SAFE_ASSERT_RETURN(fNumSegments >= 3 && fSize > 0.0f,);
 
-    float t, x = fSize, y = 0;
+    float t, x = fSize, y = 0.0f;
 
-    glBegin(isOutline ? GL_LINE_LOOP : GL_POLYGON);
+    glBegin(outline ? GL_LINE_LOOP : GL_POLYGON);
 
     for (uint i=0; i<fNumSegments; ++i)
     {
@@ -680,6 +710,30 @@ void Triangle<T>::drawOutline()
     _draw(true);
 }
 
+template<typename T>
+bool Triangle<T>::isNull() const noexcept
+{
+    return fPos1 == fPos2 && fPos1 == fPos3;
+}
+
+template<typename T>
+bool Triangle<T>::isNotNull() const noexcept
+{
+    return fPos1 != fPos2 || fPos1 != fPos3;
+}
+
+template<typename T>
+bool Triangle<T>::isValid() const noexcept
+{
+    return fPos1 != fPos2 && fPos1 != fPos3;
+}
+
+template<typename T>
+bool Triangle<T>::isInvalid() const noexcept
+{
+    return fPos1 == fPos2 || fPos1 == fPos3;
+}
+
 template<typename T>
 Triangle<T>& Triangle<T>::operator=(const Triangle<T>& tri) noexcept
 {
@@ -702,14 +756,16 @@ bool Triangle<T>::operator!=(const Triangle<T>& tri) const noexcept
 }
 
 template<typename T>
-void Triangle<T>::_draw(const bool isOutline)
+void Triangle<T>::_draw(const bool outline)
 {
-    glBegin(isOutline ? GL_LINE_LOOP : GL_TRIANGLES);
+    DISTRHO_SAFE_ASSERT_RETURN(fPos1 != fPos2 && fPos1 != fPos3,);
+
+    glBegin(outline ? GL_LINE_LOOP : GL_TRIANGLES);
 
     {
-        glVertex2i(fPos1.fX, fPos1.fY);
-        glVertex2i(fPos2.fX, fPos2.fY);
-        glVertex2i(fPos3.fX, fPos3.fY);
+        glVertex2d(fPos1.fX, fPos1.fY);
+        glVertex2d(fPos2.fX, fPos2.fY);
+        glVertex2d(fPos3.fX, fPos3.fY);
     }
 
     glEnd();
@@ -943,22 +999,24 @@ bool Rectangle<T>::operator!=(const Rectangle<T>& rect) const noexcept
 }
 
 template<typename T>
-void Rectangle<T>::_draw(const bool isOutline)
+void Rectangle<T>::_draw(const bool outline)
 {
-    glBegin(isOutline ? GL_LINE_LOOP : GL_QUADS);
+    DISTRHO_SAFE_ASSERT_RETURN(fSize.isValid(),);
+
+    glBegin(outline ? GL_LINE_LOOP : GL_QUADS);
 
     {
         glTexCoord2f(0.0f, 0.0f);
-        glVertex2i(fPos.fX, fPos.fY);
+        glVertex2d(fPos.fX, fPos.fY);
 
         glTexCoord2f(1.0f, 0.0f);
-        glVertex2i(fPos.fX+fSize.fWidth, fPos.fY);
+        glVertex2d(fPos.fX+fSize.fWidth, fPos.fY);
 
         glTexCoord2f(1.0f, 1.0f);
-        glVertex2i(fPos.fX+fSize.fWidth, fPos.fY+fSize.fHeight);
+        glVertex2d(fPos.fX+fSize.fWidth, fPos.fY+fSize.fHeight);
 
         glTexCoord2f(0.0f, 1.0f);
-        glVertex2i(fPos.fX, fPos.fY+fSize.fHeight);
+        glVertex2d(fPos.fX, fPos.fY+fSize.fHeight);
     }
 
     glEnd();