From ee8a1573204f76b16b9fb711608447aabee55696 Mon Sep 17 00:00:00 2001
From: Vasile Vilvoiu <vasi@vilvoiu.ro>
Date: Wed, 21 Jul 2021 21:14:30 +0300
Subject: Added header file comments for classes and methods.

Renamed all factory methods to ::Build().
---
 src/color-map.hpp | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 4 deletions(-)

(limited to 'src/color-map.hpp')

diff --git a/src/color-map.hpp b/src/color-map.hpp
index 139edaf..f466923 100644
--- a/src/color-map.hpp
+++ b/src/color-map.hpp
@@ -31,6 +31,12 @@ enum class ColorMapType {
     kCustom
 };
 
+/**
+ * Base color map class.
+ *
+ * This maps values in the domain [0..1] to 32bit RGBA colors, based on
+ * various color schemes.
+ */
 class ColorMap {
 protected:
     ColorMap() = default;
@@ -38,16 +44,41 @@ protected:
 public:
     ColorMap(const ColorMap&) = default;
 
-    static std::unique_ptr<ColorMap> FromType(ColorMapType type,
-                                              const sf::Color& bg_color,
-                                              const sf::Color& custom_color);
-
+    /**
+     * Factory method for colormaps.
+     * @param type One of ColorMapType.
+     * @param bg_color Background color (where applicable).
+     * @param custom_color Custom color (where applicable).
+     * @return A new ColorMap object.
+     */
+    static std::unique_ptr<ColorMap> Build(ColorMapType type,
+                                           const sf::Color& bg_color,
+                                           const sf::Color& custom_color);
+
+    /**
+     * Map a window of real values to RGBA colours.
+     * @param input Array of floating point values in the domain [0..1].
+     * @return Array of bytes, 4 for each input value, RGBA format.
+     */
     virtual std::vector<uint8_t> Map(const RealWindow& input) const = 0;
+
+    /**
+     * Create a gradient of the colormap, displaying all possible colors.
+     * @param width Width of the gradient (in pixels).
+     * @return Array of bytes, one for each pixel, RGBA format.
+     */
     std::vector<uint8_t> Gradient(std::size_t width) const;
 
+    /**
+     * @return Copy of this colormap.
+     */
     virtual std::unique_ptr<ColorMap> Copy() const = 0;
 };
 
+/**
+ * Color map that linearly interpolates between a number of specified colors,
+ * based on value landmarks.
+ */
 class InterpolationColorMap : public ColorMap {
 private:
     const std::vector<sf::Color> colors_;
@@ -56,6 +87,14 @@ private:
     std::vector<uint8_t> GetColor(double value) const;
 
 public:
+    /**
+     * Create an interpolation-based colormap.
+     * @param colors Vectors of colors used for interpolation.
+     * @param vals The corresponding value for each color.
+     *
+     * NOTE: First value in "vals" must be 0.0 and last value must be "1.0".
+     *       Thus, the whole [0..1] domain is covered.
+     */
     InterpolationColorMap(const std::vector<sf::Color>& colors, const std::vector<double>& vals);
     InterpolationColorMap() = delete;
 
@@ -63,16 +102,34 @@ public:
     std::unique_ptr<ColorMap> Copy() const override;
 };
 
+/**
+ * Specialization for only two colors.
+ */
 class TwoColorMap : public InterpolationColorMap {
 public:
+    /**
+     * @param c1 First color, corresponding to 0.0.
+     * @param c2 Second color, corresponding to 1.0.
+     */
     TwoColorMap(const sf::Color& c1, const sf::Color& c2);
 };
 
+/**
+ * Specialization for only three colors.
+ */
 class ThreeColorMap : public InterpolationColorMap {
 public:
+    /**
+     * @param c1 First color, corresponding to 0.0.
+     * @param c2 Second color, corresponding to 0.5.
+     * @param c3 Third color, corresponding to 1.0.
+     */
     ThreeColorMap(const sf::Color& c1, const sf::Color& c2, const sf::Color& c3);
 };
 
+/**
+ * Jet colormap, as seen in MATLAB, matplotlib and others.
+ */
 class JetColorMap : public InterpolationColorMap {
 public:
     JetColorMap();
-- 
cgit v1.2.3