color.hpp

Go to the documentation of this file.

// sbl/components/display/color.hpp — RGB color types and utilities
//
// Pure math operations on 8-bit RGB colors. No hardware dependencies.
// Designed for LED feedback on embedded instruments — every function
// is ISR-safe and branchless where practical.
//
// Rgb:              Simple {r, g, b} aggregate. Layout-compatible with RgbLedState.
// GAMMA8[256]:      Perceptual gamma correction LUT (gamma 2.8).
// gamma_correct():  Apply GAMMA8 to an Rgb color.
// rgb_lerp():       Linear interpolation between two colors.
// rgb_scale():      Scale a color by brightness (0-255).
// gradient():       Evaluate a multi-stop color gradient at a position.
//
// Source: Gamma table from Adafruit LED Tricks guide (gamma 2.8).
//
// Usage:
//   using sbl::components::display::Rgb;
//   constexpr Rgb red{255, 0, 0};
//   Rgb dimmed = rgb_scale(red, 128);               // half brightness
//   Rgb mixed  = rgb_lerp(red, {0,0,255}, 128);     // purple
//   Rgb out    = gamma_correct(mixed);               // perceptually correct PWM
 
#pragma once
 
#include <cstdint>
 
namespace sbl {
namespace components {
namespace display {
 
/// Simple 8-bit RGB color triple. Aggregate — constexpr constructible.
struct Rgb {
    uint8_t r;
    uint8_t g;
    uint8_t b;
};
 
/// Gamma correction LUT (gamma 2.8). Maps perceived-linear 0-255 to PWM duty.
/// Without correction, PWM 128 appears ~78% as bright as 255 (not 50%).
inline constexpr uint8_t GAMMA8[256] = {
      0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,
      0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  1,  1,  1,  1,
      1,  1,  1,  1,  1,  1,  1,  1,  1,  2,  2,  2,  2,  2,  2,  2,
      2,  3,  3,  3,  3,  3,  3,  3,  4,  4,  4,  4,  4,  5,  5,  5,
      5,  6,  6,  6,  6,  7,  7,  7,  7,  8,  8,  8,  9,  9,  9, 10,
     10, 10, 11, 11, 11, 12, 12, 13, 13, 13, 14, 14, 15, 15, 16, 16,
     17, 17, 18, 18, 19, 19, 20, 20, 21, 21, 22, 22, 23, 24, 24, 25,
     25, 26, 27, 27, 28, 29, 29, 30, 31, 32, 32, 33, 34, 35, 35, 36,
     37, 38, 39, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 50,
     51, 52, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 66, 67, 68,
     69, 70, 72, 73, 74, 75, 77, 78, 79, 81, 82, 83, 85, 86, 87, 89,
     90, 92, 93, 95, 96, 98, 99,101,102,104,105,107,109,110,112,114,
    115,117,119,120,122,124,126,127,129,131,133,135,137,138,140,142,
    144,146,148,150,152,154,156,158,160,162,164,167,169,171,173,175,
    177,180,182,184,186,189,191,193,196,198,200,203,205,208,210,213,
    215,218,220,223,225,228,231,233,236,239,241,244,247,249,252,255,
};
 
/// Apply gamma correction to an RGB color.
inline Rgb gamma_correct(const Rgb& c) {
    return {GAMMA8[c.r], GAMMA8[c.g], GAMMA8[c.b]};
}
 
/// Linear interpolation between two colors. t=0 → a, t=255 → b.
inline Rgb rgb_lerp(const Rgb& a, const Rgb& b, uint8_t t) {
    auto mix = [](uint8_t x, uint8_t y, uint8_t t) -> uint8_t {
        return static_cast<uint8_t>(x + ((static_cast<int16_t>(y) - x) * t) / 255);
    };
    return {mix(a.r, b.r, t), mix(a.g, b.g, t), mix(a.b, b.b, t)};
}
 
/// Scale a color by brightness (0-255). 255 = full, 128 ≈ half, 0 = off.
inline Rgb rgb_scale(const Rgb& c, uint8_t brightness) {
    return {
        static_cast<uint8_t>((static_cast<uint16_t>(c.r) * brightness) >> 8),
        static_cast<uint8_t>((static_cast<uint16_t>(c.g) * brightness) >> 8),
        static_cast<uint8_t>((static_cast<uint16_t>(c.b) * brightness) >> 8),
    };
}
 
/**
 * @brief Evaluate a multi-stop color gradient at a position.
 *
 * Divides the 0-65535 range into (n_stops - 1) equal segments and
 * interpolates between adjacent stops. Endpoints are exact.
 *
 * @param stops     Array of color stops (at least 2).
 * @param n_stops   Number of stops (2-16).
 * @param position  Position in gradient (0 = first stop, 65535 = last stop).
 *
 * Example:
 *   constexpr Rgb stops[] = {{0,0,255}, {0,255,0}, {255,0,0}};
 *   Rgb c = gradient(stops, 3, 32768);  // midpoint → green
 */
inline Rgb gradient(const Rgb* stops, uint8_t n_stops, uint16_t position) {
    if (n_stops < 2) return stops[0];
 
    uint8_t segments = n_stops - 1;
    uint32_t scaled = static_cast<uint32_t>(position) * segments;
    uint8_t seg = static_cast<uint8_t>(scaled >> 16);
    if (seg >= segments) seg = segments - 1;
 
    // Fractional position within segment, mapped to 0-255
    uint8_t frac = static_cast<uint8_t>((scaled - (static_cast<uint32_t>(seg) << 16)) >> 8);
    return rgb_lerp(stops[seg], stops[seg + 1], frac);
}
 
} // namespace display
} // namespace components
} // namespace sbl