ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
esp_color_correction.h
Go to the documentation of this file.
1#pragma once
2
5#include "esphome/core/hal.h"
6
7#include <algorithm>
8
9namespace esphome::light {
10
12struct GammaTable {
13 uint16_t lut[256];
14 uint16_t gamma_x100;
15};
16
19inline uint8_t gamma_table_reverse_search(const uint16_t *table, uint16_t target) {
20 uint8_t lo = 0, hi = 255;
21 while (lo < hi) {
22 uint8_t mid = (lo + hi + 1) / 2;
23 if (progmem_read_uint16(&table[mid]) <= target) {
24 lo = mid;
25 } else {
26 hi = mid - 1;
27 }
28 }
29 return lo;
30}
31
33 public:
34 void set_max_brightness(const Color &max_brightness) { this->max_brightness_ = max_brightness; }
35 void set_local_brightness(uint8_t local_brightness) { this->local_brightness_ = local_brightness; }
36#ifdef USE_LIGHT_POWER_ESTIMATION
37 // The current limit's factor, applied after gamma
38 void set_power_brightness(uint8_t power_brightness) { this->power_brightness_ = power_brightness; }
39 uint8_t get_power_brightness() const { return this->power_brightness_; }
40#endif
41 void set_gamma_table(const uint16_t *table) { this->gamma_table_ = table; }
42
43 inline Color color_correct(Color color) const ESPHOME_ALWAYS_INLINE {
44 // corrected = (uncorrected * max_brightness * local_brightness) ^ gamma
45 return Color(this->color_correct_red(color.red), this->color_correct_green(color.green),
46 this->color_correct_blue(color.blue), this->color_correct_white(color.white));
47 }
48 inline uint8_t color_correct_red(uint8_t red) const ESPHOME_ALWAYS_INLINE {
49 return this->color_correct_channel(COLOR_CHANNEL_R, red);
50 }
51 inline uint8_t color_correct_green(uint8_t green) const ESPHOME_ALWAYS_INLINE {
52 return this->color_correct_channel(COLOR_CHANNEL_G, green);
53 }
54 inline uint8_t color_correct_blue(uint8_t blue) const ESPHOME_ALWAYS_INLINE {
55 return this->color_correct_channel(COLOR_CHANNEL_B, blue);
56 }
57 inline uint8_t color_correct_white(uint8_t white) const ESPHOME_ALWAYS_INLINE {
58 return this->color_correct_channel(COLOR_CHANNEL_W, white);
59 }
60 inline uint8_t color_correct_channel(uint8_t channel, uint8_t value) const ESPHOME_ALWAYS_INLINE {
61 return this->limit_(
62 this->gamma_correct_(esp_scale8_twice(value, this->max_brightness_[channel], this->local_brightness_)));
63 }
64
65 inline Color color_uncorrect(Color raw_color) const {
66 // uncorrected = corrected^(1/gamma) / (max_brightness * local_brightness)
67 return Color(this->color_uncorrect_red(raw_color.red), this->color_uncorrect_green(raw_color.green),
68 this->color_uncorrect_blue(raw_color.blue), this->color_uncorrect_white(raw_color.white));
69 }
70 inline uint8_t color_uncorrect_red(uint8_t raw_red) const ESPHOME_ALWAYS_INLINE {
71 return this->color_uncorrect_channel(COLOR_CHANNEL_R, raw_red);
72 }
73 inline uint8_t color_uncorrect_green(uint8_t raw_green) const ESPHOME_ALWAYS_INLINE {
74 return this->color_uncorrect_channel(COLOR_CHANNEL_G, raw_green);
75 }
76 inline uint8_t color_uncorrect_blue(uint8_t raw_blue) const ESPHOME_ALWAYS_INLINE {
77 return this->color_uncorrect_channel(COLOR_CHANNEL_B, raw_blue);
78 }
79 inline uint8_t color_uncorrect_white(uint8_t raw_white) const ESPHOME_ALWAYS_INLINE {
80 return this->color_uncorrect_channel(COLOR_CHANNEL_W, raw_white);
81 }
82 uint8_t color_uncorrect_channel(uint8_t channel, uint8_t raw_value) const;
83
84 protected:
85 // The limit on a gamma-corrected level; rounded up, so a lit channel stays lit
86 inline uint8_t limit_(uint8_t res) const ESPHOME_ALWAYS_INLINE {
87#ifdef USE_LIGHT_POWER_ESTIMATION
88 if (res != 0)
89 res = std::max<uint8_t>(esp_scale8(res, this->power_brightness_), 1);
90#endif
91 return res;
92 }
94 uint8_t gamma_correct_(uint8_t value) const;
96 uint8_t uncorrect_level_(uint8_t value) const;
98 uint8_t gamma_uncorrect_(uint8_t value) const;
99
100 const uint16_t *gamma_table_{nullptr};
101 Color max_brightness_{255, 255, 255, 255};
102 uint8_t local_brightness_{255};
103#ifdef USE_LIGHT_POWER_ESTIMATION
104 uint8_t power_brightness_{255};
105#endif
106};
107
108} // namespace esphome::light
uint8_t gamma_correct_(uint8_t value) const
Forward gamma: read uint16 PROGMEM table, convert to uint8.
void set_power_brightness(uint8_t power_brightness)
uint8_t color_correct_channel(uint8_t channel, uint8_t value) const ESPHOME_ALWAYS_INLINE
uint8_t color_correct_blue(uint8_t blue) const ESPHOME_ALWAYS_INLINE
void set_max_brightness(const Color &max_brightness)
uint8_t color_correct_red(uint8_t red) const ESPHOME_ALWAYS_INLINE
void set_local_brightness(uint8_t local_brightness)
uint8_t color_uncorrect_blue(uint8_t raw_blue) const ESPHOME_ALWAYS_INLINE
Color color_correct(Color color) const ESPHOME_ALWAYS_INLINE
void set_gamma_table(const uint16_t *table)
uint8_t color_uncorrect_white(uint8_t raw_white) const ESPHOME_ALWAYS_INLINE
uint8_t color_uncorrect_channel(uint8_t channel, uint8_t raw_value) const
uint8_t color_uncorrect_red(uint8_t raw_red) const ESPHOME_ALWAYS_INLINE
uint8_t color_uncorrect_green(uint8_t raw_green) const ESPHOME_ALWAYS_INLINE
Color color_uncorrect(Color raw_color) const
uint8_t uncorrect_level_(uint8_t value) const
Reverse gamma and limit for one stored level.
uint8_t color_correct_green(uint8_t green) const ESPHOME_ALWAYS_INLINE
uint8_t limit_(uint8_t res) const ESPHOME_ALWAYS_INLINE
uint8_t gamma_uncorrect_(uint8_t value) const
Reverse gamma: binary search the forward PROGMEM table.
uint8_t color_correct_white(uint8_t white) const ESPHOME_ALWAYS_INLINE
uint8_t gamma_table_reverse_search(const uint16_t *table, uint16_t target)
Binary search a monotonically increasing uint16[256] PROGMEM table.
uint32_t value
Definition hal.cpp:41
uint16_t progmem_read_uint16(const uint16_t *addr)
Definition hal.h:53
uint8_t red
Definition color.h:37
uint8_t white
Definition color.h:49
uint8_t green
Definition color.h:41
uint8_t blue
Definition color.h:45
A gamma curve as codegen emits it into PROGMEM: the lookup table and the gamma it was built from.