improve example

examples/Apa102HD/Apa102HD.ino

@@ -1,48 +1,73 @@
 /// @file    Apa102HD.ino
 /// @brief   Example showing how to use the APA102HD gamma correction.
+///
+///          We will draw a linear ramp between APA102HD which does it's
+///          own gamma correction at the driver level, and the software
+///          version of gamma correction, which used to be the status quo.
+///
+///          Why do we love gamma correction? It produces a better picture
+///          that matches how our eye sees light. It's the standard lighting
+///          method for your monitor or TVs for example and gives these
+///          devices the range to produce very bright and very dim lights.
 /// @example Apa102HD.ino
 
 #include <Arduino.h>
 #include <FastLED.h>
+#include <lib8tion.h>
 
-#define NUM_LEDS  20
+#define NUM_LEDS  256
+// uint8_t DATA_PIN, uint8_t CLOCK_PIN,
+#define STRIP_0_DATA_PIN 1
+#define STRIP_0_CLOCK_PIN 2
+#define STRIP_1_DATA_PIN 3
+#define STRIP_1_CLOCK_PIN 4
 
-static bool gamma_function_hit = false;
 CRGB leds_hd[NUM_LEDS] = {0};  // HD mode implies gamma.
 CRGB leds[NUM_LEDS] = {0};     // Software gamma mode.
 
-
-uint8_t gamma8(uint8_t x) {
-    return uint8_t((uint16_t(x) * x) >> 8);
-}
-
-CRGB gammaCorrect(CRGB c) {
-    c.r = gamma8(c.r);
-    c.g = gamma8(c.g);
-    c.b = gamma8(c.b);
-    return c;
+// This is the regular gamma correction function that we used to have
+// to do. It's used here to showcase the difference between APA102HD
+// mode which does the gamma correction for you.
+CRGB software_gamma(const CRGB& in) {
+    CRGB out;
+    // dim8_raw are the old gamma correction functions.
+    out.r = dim8_raw(in.r);
+    out.g = dim8_raw(in.g);
+    out.b = dim8_raw(in.b);
+    return out;
 }
 
 void setup() {
     delay(500); // power-up safety delay
-    FastLED.addLeds<APA102HD, 1, 2, RGB>(leds_hd, NUM_LEDS);
-    FastLED.addLeds<APA102, 3, 4, RGB>(leds, NUM_LEDS);
-    FastLED.addLeds<DOTSTARHD, 1, 2, RGB>(leds_hd, NUM_LEDS);  // compile test.
+    // Two strips of LEDs, one in HD mode, one in software gamma mode.
+    FastLED.addLeds<APA102HD, STRIP_0_DATA_PIN, STRIP_0_CLOCK_PIN, RGB>(leds_hd, NUM_LEDS);
+    FastLED.addLeds<APA102,   STRIP_1_DATA_PIN, STRIP_1_CLOCK_PIN, RGB>(leds, NUM_LEDS);
+}
+
+uint8_t wrap_8bit(int i) {
+    // Module % operator here wraps a large "i" so that it is
+    // always in [0, 255] range when returned. For example, if
+    // "i" is 256, then this will return 0. If "i" is 257
+    // then this will return 1. No matter how big the "i" is, the
+    // output range will always be [0, 255]
+    return i % 256;
 }
 
 void loop() {
-    uint32_t now = millis();
-    uint32_t t = now / 100;
+    // Draw a a linear ramp of brightnesses, showcasing the difference
+    // between the two gamma correction modes. APA102HD should have far
+    // greater range of brightnesses. Gamma correction mode in software
+    // will have about 25% of the dimmest lights truncated to 0 brightness!
     for (int i = 0; i < NUM_LEDS; i++) {
-        uint8_t brightness = sin8(t + i);
-        CRGB c(brightness, brightness, brightness);
-        leds_hd[i] = c;
-        leds[i] = gammaCorrect(c);
-    }
-    FastLED.show();
-    delay(8);
-    if (!gamma_function_hit) {
-        Serial.println("gamma function not hit");
+        // Make sure the i value is always in 8 bit range.
+        uint8_t brightness = wrap_8bit(i);
+        CRGB c(brightness, brightness, brightness);  // Just make a shade of white.
+        leds_hd[i] = c;  // The APA102HD leds are set to ungamma corrected values.
+        CRGB c_gamma_corrected = software_gamma(c);
+        leds[i] = c_gamma_corrected;  // Set the software gamma corrected
+                                      // values to the other strip.
     }
+    FastLED.show();  // All leds are now written out.
+    delay(8);  // Wait 8 milliseconds until the next frame.
 }