adafruit / Adafruit_Seesaw

Arduino library driver for seesaw multi-use chip
93 stars 64 forks source link

Missing documentation on Neopixel setBrightness function #78

Open jgdye opened 1 year ago

jgdye commented 1 year ago

The setBrightness member function in the seesaw_neopixel.cpp file is missing documentation (that is referenced in comments in other sections). Looking at it it looks like it's using a similar but not quite identical technique to the Adafruit_Neopixel library, which has the following documentation:

/*!
  @brief   Adjust output brightness. Does not immediately affect what's
           currently displayed on the LEDs. The next call to show() will
           refresh the LEDs at this level.
  @param   b  Brightness setting, 0=minimum (off), 255=brightest.
  @note    This was intended for one-time use in one's setup() function,
           not as an animation effect in itself. Because of the way this
           library "pre-multiplies" LED colors in RAM, changing the
           brightness is often a "lossy" operation -- what you write to
           pixels isn't necessary the same as what you'll read back.
           Repeated brightness changes using this function exacerbate the
           problem. Smart programs therefore treat the strip as a
           write-only resource, maintaining their own state to render each
           frame of an animation, not relying on read-modify-write.
*/
void Adafruit_NeoPixel::setBrightness(uint8_t b) {
  // Stored brightness value is different than what's passed.
  // This simplifies the actual scaling math later, allowing a fast
  // 8x8-bit multiply and taking the MSB. 'brightness' is a uint8_t,
  // adding 1 here may (intentionally) roll over...so 0 = max brightness
  // (color values are interpreted literally; no scaling), 1 = min
  // brightness (off), 255 = just below max brightness.
  uint8_t newBrightness = b + 1;

In particular, it looks like you don't do the b+1 part, so it would end up with 1=off, brightness increasing to 255, then 0 as the max brightness, and you don't seem to do the rescaling on brightness change.