Initial doxygen-zie of CRBG

1 files changed, 91 insertions, 76 deletions

diff --git a/pixeltypes.h b/pixeltypes.h
index 89225ae1..5c7682f5 100644
--- a/pixeltypes.h
+++ b/pixeltypes.h
@@ -38,18 +38,18 @@ struct CHSV {
 		uint8_t raw[3];
 	};
 
-    // default values are UNITIALIZED
+    /// default values are UNITIALIZED
     inline CHSV() __attribute__((always_inline))
     {
     }
 
-    // allow construction from H, S, V
+    /// allow construction from H, S, V
     inline CHSV( uint8_t ih, uint8_t is, uint8_t iv) __attribute__((always_inline))
         : h(ih), s(is), v(iv)
     {
     }
 
-    // allow copy construction
+    /// allow copy construction
     inline CHSV(const CHSV& rhs) __attribute__((always_inline))
     {
         h = rhs.h;
@@ -106,11 +106,13 @@ struct CRGB {
 		uint8_t raw[3];
 	};
 
+  /// Array access operator to index into the crgb object
 	inline uint8_t& operator[] (uint8_t x) __attribute__((always_inline))
     {
         return raw[x];
     }
 
+    /// Array access operator to index into the crgb object
     inline const uint8_t& operator[] (uint8_t x) const __attribute__((always_inline))
     {
         return raw[x];
@@ -121,31 +123,33 @@ struct CRGB {
     {
     }
 
-    // allow construction from R, G, B
+    /// allow construction from R, G, B
     inline CRGB( uint8_t ir, uint8_t ig, uint8_t ib)  __attribute__((always_inline))
         : r(ir), g(ig), b(ib)
     {
     }
 
-    // allow construction from 32-bit (really 24-bit) bit 0xRRGGBB color code
+    /// allow construction from 32-bit (really 24-bit) bit 0xRRGGBB color code
     inline CRGB( uint32_t colorcode)  __attribute__((always_inline))
     : r((colorcode >> 16) & 0xFF), g((colorcode >> 8) & 0xFF), b((colorcode >> 0) & 0xFF)
     {
     }
 
+    /// allow construction from a LEDColorCorrection enum
     inline CRGB( LEDColorCorrection colorcode) __attribute__((always_inline))
     : r((colorcode >> 16) & 0xFF), g((colorcode >> 8) & 0xFF), b((colorcode >> 0) & 0xFF)
     {
 
     }
 
+    /// allow construction from a ColorTemperature enum
     inline CRGB( ColorTemperature colorcode) __attribute__((always_inline))
     : r((colorcode >> 16) & 0xFF), g((colorcode >> 8) & 0xFF), b((colorcode >> 0) & 0xFF)
     {
 
     }
 
-    // allow copy construction
+    /// allow copy construction
 	inline CRGB(const CRGB& rhs) __attribute__((always_inline))
     {
         r = rhs.r;
@@ -153,13 +157,13 @@ struct CRGB {
         b = rhs.b;
     }
 
-    // allow construction from HSV color
+    /// allow construction from HSV color
 	inline CRGB(const CHSV& rhs) __attribute__((always_inline))
     {
         hsv2rgb_rainbow( rhs, *this);
     }
 
-    // allow assignment from one RGB struct to another
+    /// allow assignment from one RGB struct to another
 	inline CRGB& operator= (const CRGB& rhs) __attribute__((always_inline))
     {
         r = rhs.r;
@@ -168,7 +172,7 @@ struct CRGB {
         return *this;
     }
 
-    // allow assignment from 32-bit (really 24-bit) 0xRRGGBB color code
+    /// allow assignment from 32-bit (really 24-bit) 0xRRGGBB color code
 	inline CRGB& operator= (const uint32_t colorcode) __attribute__((always_inline))
     {
         r = (colorcode >> 16) & 0xFF;
@@ -177,7 +181,7 @@ struct CRGB {
         return *this;
     }
 
-    // allow assignment from R, G, and B
+    /// allow assignment from R, G, and B
 	inline CRGB& setRGB (uint8_t nr, uint8_t ng, uint8_t nb) __attribute__((always_inline))
     {
         r = nr;
@@ -186,28 +190,28 @@ struct CRGB {
         return *this;
     }
 
-    // allow assignment from H, S, and V
+    /// allow assignment from H, S, and V
 	inline CRGB& setHSV (uint8_t hue, uint8_t sat, uint8_t val) __attribute__((always_inline))
     {
         hsv2rgb_rainbow( CHSV(hue, sat, val), *this);
         return *this;
     }
 
-    // allow assignment from just a Hue, saturation and value automatically at max.
+    /// allow assignment from just a Hue, saturation and value automatically at max.
 	inline CRGB& setHue (uint8_t hue) __attribute__((always_inline))
     {
         hsv2rgb_rainbow( CHSV(hue, 255, 255), *this);
         return *this;
     }
 
-    // allow assignment from HSV color
+    /// allow assignment from HSV color
 	inline CRGB& operator= (const CHSV& rhs) __attribute__((always_inline))
     {
         hsv2rgb_rainbow( rhs, *this);
         return *this;
     }
 
-    // allow assignment from 32-bit (really 24-bit) 0xRRGGBB color code
+    /// allow assignment from 32-bit (really 24-bit) 0xRRGGBB color code
 	inline CRGB& setColorCode (uint32_t colorcode) __attribute__((always_inline))
     {
         r = (colorcode >> 16) & 0xFF;
@@ -217,7 +221,7 @@ struct CRGB {
     }
 
 
-    // add one RGB to another, saturating at 0xFF for each channel
+    /// add one RGB to another, saturating at 0xFF for each channel
     inline CRGB& operator+= (const CRGB& rhs )
     {
         r = qadd8( r, rhs.r);
@@ -226,10 +230,10 @@ struct CRGB {
         return *this;
     }
 
-    // add a contstant to each channel, saturating at 0xFF
-    // this is NOT an operator+= overload because the compiler
-    // can't usefully decide when it's being passed a 32-bit
-    // constant (e.g. CRGB::Red) and an 8-bit one (CRGB::Blue)
+    /// add a contstant to each channel, saturating at 0xFF
+    /// this is NOT an operator+= overload because the compiler
+    /// can't usefully decide when it's being passed a 32-bit
+    /// constant (e.g. CRGB::Red) and an 8-bit one (CRGB::Blue)
     inline CRGB& addToRGB (uint8_t d )
     {
         r = qadd8( r, d);
@@ -238,7 +242,7 @@ struct CRGB {
         return *this;
     }
 
-    // subtract one RGB from another, saturating at 0x00 for each channel
+    /// subtract one RGB from another, saturating at 0x00 for each channel
     inline CRGB& operator-= (const CRGB& rhs )
     {
         r = qsub8( r, rhs.r);
@@ -247,10 +251,10 @@ struct CRGB {
         return *this;
     }
 
-    // subtract a constant from each channel, saturating at 0x00
-    // this is NOT an operator+= overload because the compiler
-    // can't usefully decide when it's being passed a 32-bit
-    // constant (e.g. CRGB::Red) and an 8-bit one (CRGB::Blue)
+    /// subtract a constant from each channel, saturating at 0x00
+    /// this is NOT an operator+= overload because the compiler
+    /// can't usefully decide when it's being passed a 32-bit
+    /// constant (e.g. CRGB::Red) and an 8-bit one (CRGB::Blue)
     inline CRGB& subtractFromRGB(uint8_t d )
     {
         r = qsub8( r, d);
@@ -259,14 +263,14 @@ struct CRGB {
         return *this;
     }
 
-    // subtract a constant of '1' from each channel, saturating at 0x00
+    /// subtract a constant of '1' from each channel, saturating at 0x00
     inline CRGB& operator-- ()  __attribute__((always_inline))
     {
         subtractFromRGB(1);
         return *this;
     }
 
-    // subtract a constant of '1' from each channel, saturating at 0x00
+    /// subtract a constant of '1' from each channel, saturating at 0x00
     inline CRGB operator-- (int )  __attribute__((always_inline))
     {
         CRGB retval(*this);
@@ -274,14 +278,14 @@ struct CRGB {
         return retval;
     }
 
-    // add a constant of '1' from each channel, saturating at 0xFF
+    /// add a constant of '1' from each channel, saturating at 0xFF
     inline CRGB& operator++ ()  __attribute__((always_inline))
     {
         addToRGB(1);
         return *this;
     }
 
-    // add a constant of '1' from each channel, saturating at 0xFF
+    /// add a constant of '1' from each channel, saturating at 0xFF
     inline CRGB operator++ (int )  __attribute__((always_inline))
     {
         CRGB retval(*this);
@@ -289,7 +293,7 @@ struct CRGB {
         return retval;
     }
 
-    // divide each of the channels by a constant
+    /// divide each of the channels by a constant
     inline CRGB& operator/= (uint8_t d )
     {
         r /= d;
@@ -298,7 +302,7 @@ struct CRGB {
         return *this;
     }
 
-    // right shift each of the channels by a constant
+    /// right shift each of the channels by a constant
     inline CRGB& operator>>= (uint8_t d)
     {
       r >>= d;
@@ -307,8 +311,8 @@ struct CRGB {
       return *this;
     }
 
-    // multiply each of the channels by a constant,
-    // saturating each channel at 0xFF
+    /// multiply each of the channels by a constant,
+    /// saturating each channel at 0xFF
     inline CRGB& operator*= (uint8_t d )
     {
         r = qmul8( r, d);
@@ -317,44 +321,44 @@ struct CRGB {
         return *this;
     }
 
-    // scale down a RGB to N 256ths of it's current brightness, using
-    // 'video' dimming rules, which means that unless the scale factor is ZERO
-    // each channel is guaranteed NOT to dim down to zero.  If it's already
-    // nonzero, it'll stay nonzero, even if that means the hue shifts a little
-    // at low brightness levels.
+    /// scale down a RGB to N 256ths of it's current brightness, using
+    /// 'video' dimming rules, which means that unless the scale factor is ZERO
+    /// each channel is guaranteed NOT to dim down to zero.  If it's already
+    /// nonzero, it'll stay nonzero, even if that means the hue shifts a little
+    /// at low brightness levels.
     inline CRGB& nscale8_video (uint8_t scaledown )
     {
         nscale8x3_video( r, g, b, scaledown);
         return *this;
     }
 
-    // %= is a synonym for nscale8_video.  Think of it is scaling down
-    // by "a percentage"
+    /// %= is a synonym for nscale8_video.  Think of it is scaling down
+    /// by "a percentage"
     inline CRGB& operator%= (uint8_t scaledown )
     {
         nscale8x3_video( r, g, b, scaledown);
         return *this;
     }
 
-    // fadeLightBy is a synonym for nscale8_video( ..., 255-fadefactor)
+    /// fadeLightBy is a synonym for nscale8_video( ..., 255-fadefactor)
     inline CRGB& fadeLightBy (uint8_t fadefactor )
     {
         nscale8x3_video( r, g, b, 255 - fadefactor);
         return *this;
     }
 
-    // scale down a RGB to N 256ths of it's current brightness, using
-    // 'plain math' dimming rules, which means that if the low light levels
-    // may dim all the way to 100% black.
+    /// scale down a RGB to N 256ths of it's current brightness, using
+    /// 'plain math' dimming rules, which means that if the low light levels
+    /// may dim all the way to 100% black.
     inline CRGB& nscale8 (uint8_t scaledown )
     {
         nscale8x3( r, g, b, scaledown);
         return *this;
     }
 
-    // scale down a RGB to N 256ths of it's current brightness, using
-    // 'plain math' dimming rules, which means that if the low light levels
-    // may dim all the way to 100% black.
+    /// scale down a RGB to N 256ths of it's current brightness, using
+    /// 'plain math' dimming rules, which means that if the low light levels
+    /// may dim all the way to 100% black.
     inline CRGB& nscale8 (const CRGB & scaledown )
     {
         r = ::scale8(r, scaledown.r);
@@ -363,6 +367,7 @@ struct CRGB {
         return *this;
     }
 
+    /// return a CRGB object that is a scaled down version of this object
     inline CRGB scale8 (const CRGB & scaledown ) const
     {
         CRGB out;
@@ -372,14 +377,14 @@ struct CRGB {
         return out;
     }
 
-    // fadeToBlackBy is a synonym for nscale8( ..., 255-fadefactor)
+    /// fadeToBlackBy is a synonym for nscale8( ..., 255-fadefactor)
     inline CRGB& fadeToBlackBy (uint8_t fadefactor )
     {
         nscale8x3( r, g, b, 255 - fadefactor);
         return *this;
     }
 
-    // "or" operator brings each channel up to the higher of the two values
+    /// "or" operator brings each channel up to the higher of the two values
     inline CRGB& operator|= (const CRGB& rhs )
     {
         if( rhs.r > r) r = rhs.r;
@@ -387,6 +392,8 @@ struct CRGB {
         if( rhs.b > b) b = rhs.b;
         return *this;
     }
+
+    /// "or" operator brings each channel up to the higher of the two values
     inline CRGB& operator|= (uint8_t d )
     {
         if( d > r) r = d;
@@ -395,7 +402,7 @@ struct CRGB {
         return *this;
     }
 
-    // "and" operator brings each channel down to the lower of the two values
+    /// "and" operator brings each channel down to the lower of the two values
     inline CRGB& operator&= (const CRGB& rhs )
     {
         if( rhs.r < r) r = rhs.r;
@@ -403,6 +410,8 @@ struct CRGB {
         if( rhs.b < b) b = rhs.b;
         return *this;
     }
+
+    /// "and" operator brings each channel down to the lower of the two values
     inline CRGB& operator&= (uint8_t d )
     {
         if( d < r) r = d;
@@ -411,13 +420,13 @@ struct CRGB {
         return *this;
     }
 
-    // this allows testing a CRGB for zero-ness
+    /// this allows testing a CRGB for zero-ness
     inline operator bool() const __attribute__((always_inline))
     {
         return r || g || b;
     }
 
-    // invert each channel
+    /// invert each channel
     inline CRGB operator- ()
     {
         CRGB retval;
@@ -437,6 +446,8 @@ struct CRGB {
     }
 #endif
 
+    /// Get the 'luma' of a CRGB object - aka roughly how much light the
+    /// CRGB pixel is putting out (from 0 to 255).
     inline uint8_t getLuma ( )  const {
         //Y' = 0.2126 R' + 0.7152 G' + 0.0722 B'
         //     54            183       18 (!)
@@ -448,6 +459,7 @@ struct CRGB {
         return luma;
     }
 
+    /// Get the average of the R, G, and B values
     inline uint8_t getAverageLight( )  const {
         const uint8_t eightysix = 86;
         uint8_t avg = scale8_LEAVING_R1_DIRTY( r, eightysix) + \
@@ -457,6 +469,7 @@ struct CRGB {
         return avg;
     }
 
+    /// maximize the brightness of this CRGB object
     inline void maximizeBrightness( uint8_t limit = 255 )  {
         uint8_t max = red;
         if( green > max) max = green;
@@ -467,6 +480,7 @@ struct CRGB {
         blue =  (blue  * factor) / 256;
     }
 
+    /// return a new CRGB object after performing a linear interpolation between this object and the passed in object
     inline CRGB lerp8( CRGB & other, fract8 frac)
     {
       CRGB ret;
@@ -478,6 +492,7 @@ struct CRGB {
       return ret;
     }
 
+    /// return a new CRGB object after performing a linear interpolation between this object and the passed in object
     inline CRGB lerp16( CRGB & other, fract16 frac)
     {
       CRGB ret;
@@ -489,37 +504,37 @@ struct CRGB {
       return ret;
     }
 
-    // getParity returns 0 or 1, depending on the
-    // lowest bit of the sum of the color components.
+    /// getParity returns 0 or 1, depending on the
+    /// lowest bit of the sum of the color components.
     inline uint8_t getParity()
     {
         uint8_t sum = r + g + b;
         return (sum & 0x01);
     }
 
-    // setParity adjusts the color in the smallest
-    // way possible so that the parity of the color
-    // is now the desired value.  This allows you to
-    // 'hide' one bit of information in the color.
-    //
-    // Ideally, we find one color channel which already
-    // has data in it, and modify just that channel by one.
-    // We don't want to light up a channel that's black
-    // if we can avoid it, and if the pixel is 'grayscale',
-    // (meaning that R==G==B), we modify all three channels
-    // at once, to preserve the neutral hue.
-    //
-    // There's no such thing as a free lunch; in many cases
-    // this 'hidden bit' may actually be visible, but this
-    // code makes reasonable efforts to hide it as much
-    // as is reasonably possible.
-    //
-    // Also, an effort is made to have make it such that
-    // repeatedly setting the parity to different values
-    // will not cause the color to 'drift'.  Toggling
-    // the parity twice should generally result in the
-    // original color again.
-    //
+    /// setParity adjusts the color in the smallest
+    /// way possible so that the parity of the color
+    /// is now the desired value.  This allows you to
+    /// 'hide' one bit of information in the color.
+    ///
+    /// Ideally, we find one color channel which already
+    /// has data in it, and modify just that channel by one.
+    /// We don't want to light up a channel that's black
+    /// if we can avoid it, and if the pixel is 'grayscale',
+    /// (meaning that R==G==B), we modify all three channels
+    /// at once, to preserve the neutral hue.
+    ///
+    /// There's no such thing as a free lunch; in many cases
+    /// this 'hidden bit' may actually be visible, but this
+    /// code makes reasonable efforts to hide it as much
+    /// as is reasonably possible.
+    ///
+    /// Also, an effort is made to have make it such that
+    /// repeatedly setting the parity to different values
+    /// will not cause the color to 'drift'.  Toggling
+    /// the parity twice should generally result in the
+    /// original color again.
+    ///
     inline void setParity( uint8_t parity)
     {
         uint8_t curparity = getParity();