Merge pull request #69 from grunt-lucas/2.x/doxygen

Set up doxygen and other basic type structure

.clang-format

@@ -7,3 +7,4 @@ ReflowComments: true
 IndentWidth: 4
 TabWidth: 4
 UseTab: Never
+AllowShortFunctionsOnASingleLine: Empty

.gitignore

@@ -7,6 +7,10 @@
 build/**
 cmake-build-*/**
 
+# Doxygen
+Documentation/html/**
+Documentation/latex/**
+
 # LLVM coverage files
 default.profraw
 testcov.profdata

Documentation/README.md

@@ -0,0 +1 @@
+# Porytiles Doxygen Landing Page

Porytiles-2.x/include/porytiles/Color/Bgr15.h

@@ -1,8 +1,10 @@
 #ifndef PORYTILES_COLOR_BGR15_H
 #define PORYTILES_COLOR_BGR15_H
 
-#include <compare>
 #include <cstdint>
+#include <iostream>
+
+#include "porytiles/Color/Rgba32.h"
 
 namespace porytiles::color {
 
@@ -12,21 +14,21 @@ namespace porytiles::color {
  * @details
  * TODO 2.x : fill in explanation about BGR format, 5 bits per color, top bit unused, etc.
  */
-class Bgr15 {
+class Bgr15 : public Color {
     std::uint16_t bgr;
 
   public:
     /**
-     * @brief Default constructor for Bgr15. Initializes to 0.
+     * @brief Default constructor for Bgr15. Zero initialized, i.e. the color will be black.
      */
-    Bgr15() = default;
+    constexpr explicit Bgr15() : bgr{0} {}
 
     /**
      * @brief Construct a Bgr15 object from a 16-bit BGR value.
      *
      * @param bgr The 16-bit BGR value used to initialize the object.
      */
-    explicit constexpr Bgr15(const std::uint16_t bgr) : bgr{bgr} {}
+    constexpr explicit Bgr15(const std::uint16_t bgr) : bgr{bgr} {}
 
     /**
      * @brief Constructs a Bgr15 object with the given 8-bit RGB color components.
@@ -39,8 +41,7 @@ class Bgr15 {
      * @param green The 8-bit green component of the color.
      * @param blue The 8-bit blue component of the color.
      */
-    explicit constexpr Bgr15(const std::uint8_t red, const std::uint8_t green,
-                             const std::uint8_t blue)
+    explicit Bgr15(const std::uint8_t red, const std::uint8_t green, const std::uint8_t blue)
     {
         bgr = static_cast<std::uint16_t>((blue >> 3 << 10) | (green >> 3 << 5) | red >> 3);
     }
@@ -53,15 +54,15 @@ class Bgr15 {
     [[nodiscard]] std::uint16_t getRawValue() const;
 
     /**
-     * @brief Computes the blue component from the 15-bit BGR color value.
+     * @brief Computes the red component from the 15-bit BGR color value.
      *
      * @details
-     * Extracts the blue color component from the internal 15-bit BGR representation, scales it back
+     * Extracts the red color component from the internal 15-bit BGR representation, scales it back
      * up to an 8-bit value, and returns it.
      *
-     * @return The 8-bit blue component derived from the 15-bit BGR value.
+     * @return The 8-bit red component derived from the 15-bit BGR value.
      */
-    [[nodiscard]] std::uint8_t computeBlueComponent() const;
+    [[nodiscard]] std::uint8_t computeRedComponent() const override;
 
     /**
      * @brief Computes the green component from the 15-bit BGR color value.
@@ -72,28 +73,45 @@ class Bgr15 {
      *
      * @return The 8-bit green component derived from the 15-bit BGR value.
      */
-    [[nodiscard]] std::uint8_t computeGreenComponent() const;
+    [[nodiscard]] std::uint8_t computeGreenComponent() const override;
 
     /**
-     * @brief Computes the red component from the 15-bit BGR color value.
+     * @brief Computes the blue component from the 15-bit BGR color value.
      *
      * @details
-     * Extracts the red color component from the internal 15-bit BGR representation, scales it back
+     * Extracts the blue color component from the internal 15-bit BGR representation, scales it back
      * up to an 8-bit value, and returns it.
      *
-     * @return The 8-bit red component derived from the 15-bit BGR value.
+     * @return The 8-bit blue component derived from the 15-bit BGR value.
      */
-    [[nodiscard]] std::uint8_t computeRedComponent() const;
+    [[nodiscard]] std::uint8_t computeBlueComponent() const override;
 
     /**
-     * @brief Provides a three-way comparison for Bgr15 objects.
+     * @brief Computes the alpha component, which will always be opaque.
+     *
+     * @details
+     * The BGR15 format does not support an alpha channel. Thus, this method will always return an
+     * opaque alpha value for Colors of type Bgr15.
      *
-     * @param other The Bgr15 object to compare with.
-     * @return A std::strong_ordering result indicating the relative order of the objects.
+     * @return The opaque alpha component.
      */
-    std::strong_ordering operator<=>(const Bgr15 &other) const = default;
+    [[nodiscard]] std::uint8_t computeAlphaComponent() const override
+    {
+        return Rgba32::ALPHA_OPAQUE;
+    }
+
+    friend bool operator==(const Bgr15 &lhs, const Bgr15 &rhs)
+    {
+        // TODO 2.x : make this ignore the top bit of the raw value, since that bit is unused
+        return lhs.getRawValue() == rhs.getRawValue();
+    }
+
+    friend bool operator!=(const Bgr15 &lhs, const Bgr15 &rhs)
+    {
+        return !(lhs == rhs);
+    }
 };
 
-} // end namespace porytiles::color
+} // namespace porytiles::color
 
 #endif // PORYTILES_COLOR_BGR15_H

Porytiles-2.x/include/porytiles/Color/Color.h

@@ -0,0 +1,107 @@
+#ifndef PORYTILES_COLOR_COLOR_H
+#define PORYTILES_COLOR_COLOR_H
+
+#include <cstdint>
+#include <iostream>
+
+namespace porytiles::color {
+
+/**
+ * @brief An abstract representation of a color from the perspective of the Porytiles library.
+ *
+ * @details
+ * The Porytiles library is color implementation agnostic. That is, it only needs a color to conform
+ * to this simple interface. The underlying color implementation is irrelevant, as most color
+ * representations can be converted into red, green, and blue channels via a simple formula.
+ * Porytiles provides a few Color implementations that may be useful, but users of the Porytiles
+ * library may also implement their own if they have a specific use-case.
+ */
+class Color {
+  public:
+    virtual ~Color() = default;
+
+    /**
+     * @brief Computes the red component of the color.
+     *
+     * @return The red component as an 8-bit unsigned integer.
+     */
+    [[nodiscard]] virtual std::uint8_t computeRedComponent() const = 0;
+
+    /**
+     * @brief Computes the green component of the color.
+     *
+     * @return The green component as an 8-bit unsigned integer.
+     */
+    [[nodiscard]] virtual std::uint8_t computeGreenComponent() const = 0;
+
+    /**
+     * @brief Computes the blue component of the color.
+     *
+     * @return The blue component as an 8-bit unsigned integer.
+     */
+    [[nodiscard]] virtual std::uint8_t computeBlueComponent() const = 0;
+
+    /**
+     * @brief Computes the alpha component of the color.
+     *
+     * @return The alpha component as an 8-bit unsigned integer.
+     */
+    [[nodiscard]] virtual std::uint8_t computeAlphaComponent() const = 0;
+
+    /**
+     * @brief Converts the Color to a JASC-PAL formatted string.
+     *
+     * @details
+     * This method converts the red, green, and blue components of the Color object into a
+     * space-separated string format commonly used in JASC-PAL color palette files.
+     *
+     * @return A string representation of the color in JASC-PAL format.
+     */
+    [[nodiscard]] virtual std::string toJascString() const
+    {
+        return std::to_string(computeRedComponent()) + " " +
+               std::to_string(computeGreenComponent()) + " " +
+               std::to_string(computeBlueComponent());
+    }
+
+    /**
+     * @brief Compares two Color objects for equality.
+     *
+     * @param lhs The left-hand side Color object for comparison.
+     * @param rhs The right-hand side Color object for comparison.
+     * @return True if the Color objects are equal in terms of red, green, blue, and alpha
+     * components; otherwise, false.
+     */
+    friend bool operator==(const Color &lhs, const Color &rhs)
+    {
+        const auto leftRed = lhs.computeRedComponent();
+        const auto leftGreen = lhs.computeGreenComponent();
+        const auto leftBlue = lhs.computeBlueComponent();
+        const auto leftAlpha = lhs.computeAlphaComponent();
+
+        const auto rightRed = rhs.computeRedComponent();
+        const auto rightGreen = rhs.computeGreenComponent();
+        const auto rightBlue = rhs.computeBlueComponent();
+        const auto rightAlpha = rhs.computeAlphaComponent();
+
+        return leftRed == rightRed && leftGreen == rightGreen && leftBlue == rightBlue &&
+               leftAlpha == rightAlpha;
+    }
+
+    /**
+     * @brief Compares two Color objects for inequality.
+     *
+     * @param lhs The left-hand side Color object for comparison.
+     * @param rhs The right-hand side Color object for comparison.
+     * @return True if the Color objects are not equal in terms of red, green, blue, and alpha
+     * components; otherwise, false.
+     */
+    friend bool operator!=(const Color &lhs, const Color &rhs)
+    {
+        return !(lhs == rhs);
+    }
+};
+
+} // namespace porytiles::color
+
+#endif // PORYTILES_COLOR_COLOR_H

Porytiles-2.x/include/porytiles/Color/ColorConverters.h

@@ -6,8 +6,20 @@
 
 namespace porytiles::color {
 
+/**
+ * @brief Converts an Rgba32 color to a 15-bit Bgr15 color.
+ *
+ * @param rgba The Rgba32 color object to convert.
+ * @return The converted Bgr15 color.
+ */
 Bgr15 rgbaToBgr(const Rgba32 &rgba);
 
+/**
+ * @brief Converts a Bgr15 color to an Rgba32 color.
+ *
+ * @param bgr The Bgr15 color object to convert.
+ * @return The converted Rgba32 color.
+ */
 Rgba32 bgrToRgba(const Bgr15 &bgr);
 
 } // namespace porytiles::color

Porytiles-2.x/include/porytiles/Color/NamespaceDoc.h

@@ -0,0 +1,10 @@
+#ifndef PORYTILES_COLOR_NAMESPACE_H
+#define PORYTILES_COLOR_NAMESPACE_H
+
+/**
+ * @brief Color related code.
+ */
+namespace porytiles::color {
+}
+
+#endif //PORYTILES_COLOR_NAMESPACE_H