-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcolorutils.h
2225 lines (1979 loc) · 82.1 KB
/
colorutils.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#ifndef __INC_COLORUTILS_H
#define __INC_COLORUTILS_H
/// @file colorutils.h
/// Utility functions for color fill, palettes, blending, and more
#include "PicoLED.h"
#include "pixeltypes.h"
#define FL_PGM_READ_BYTE_NEAR(x) (*((const uint8_t*)(x)))
#define FL_PGM_READ_WORD_NEAR(x) (*((const uint16_t*)(x)))
#define FL_PGM_READ_DWORD_NEAR(x) (*((const uint32_t*)(x)))
/// @defgroup ColorUtils Color Utility Functions
/// A variety of functions for working with color, palettes, and leds
/// @{
/// @defgroup ColorFills Color Fill Functions
/// Functions for filling LED arrays with colors and gradients
/// @{
/// Fill a range of LEDs with a solid color.
/// @param targetArray a pointer to the LED array to fill
/// @param numToFill the number of LEDs to fill in the array
/// @param color the color to fill with
void fill_solid( struct CRGB * targetArray, int numToFill,
const struct CRGB& color);
/// @copydoc fill_solid()
void fill_solid( struct CHSV* targetArray, int numToFill,
const struct CHSV& color);
/// Fill a range of LEDs with a rainbow of colors.
/// The colors making up the rainbow are at full saturation and full
/// value (brightness).
/// @param targetArray a pointer to the LED array to fill
/// @param numToFill the number of LEDs to fill in the array
/// @param initialhue the starting hue for the rainbow
/// @param deltahue how many hue values to advance for each LED
void fill_rainbow( struct CRGB * targetArray, int numToFill,
uint8_t initialhue,
uint8_t deltahue = 5);
/// @copydoc fill_rainbow()
void fill_rainbow( struct CHSV * targetArray, int numToFill,
uint8_t initialhue,
uint8_t deltahue = 5);
/// Fill a range of LEDs with a rainbow of colors, so that the hues
/// are continuous between the end of the strip and the beginning.
/// The colors making up the rainbow are at full saturation and full
/// value (brightness).
/// @param targetArray a pointer to the LED array to fill
/// @param numToFill the number of LEDs to fill in the array
/// @param initialhue the starting hue for the rainbow
/// @param reversed whether to progress through the rainbow hues backwards
void fill_rainbow_circular(struct CRGB* targetArray, int numToFill,
uint8_t initialhue, bool reversed=false);
/// @copydoc fill_rainbow_circular()
void fill_rainbow_circular(struct CHSV* targetArray, int numToFill,
uint8_t initialhue, bool reversed=false);
/// Hue direction for calculating fill gradients.
/// Since "hue" is a value around a color wheel, there are always two directions
/// to sweep from one hue to another.
typedef enum {
FORWARD_HUES, ///< Hue always goes clockwise around the color wheel
BACKWARD_HUES, ///< Hue always goes counter-clockwise around the color wheel
SHORTEST_HUES, ///< Hue goes whichever way is shortest
LONGEST_HUES ///< Hue goes whichever way is longest
} TGradientDirectionCode;
/// ANSI: signed short _Accum. 8 bits int, 7 bits fraction
/// @see accum88
#define saccum87 int16_t
/// Fill a range of LEDs with a smooth HSV gradient between two HSV colors.
/// This function can write the gradient colors either:
///
/// 1. Into an array of CRGBs (e.g., an leds[] array, or a CRGB palette)
/// 2. Into an array of CHSVs (e.g. a CHSV palette).
///
/// In the case of writing into a CRGB array, the gradient is
/// computed in HSV space, and then HSV values are converted to RGB
/// as they're written into the CRGB array.
/// @param targetArray a pointer to the color array to fill
/// @param startpos the starting position in the array
/// @param startcolor the starting color for the gradient
/// @param endpos the ending position in the array
/// @param endcolor the end color for the gradient
/// @param directionCode the direction to travel around the color wheel
template <typename T>
void fill_gradient( T* targetArray,
uint16_t startpos, CHSV startcolor,
uint16_t endpos, CHSV endcolor,
TGradientDirectionCode directionCode = SHORTEST_HUES )
{
// if the points are in the wrong order, straighten them
if( endpos < startpos ) {
uint16_t t = endpos;
CHSV tc = endcolor;
endcolor = startcolor;
endpos = startpos;
startpos = t;
startcolor = tc;
}
// If we're fading toward black (val=0) or white (sat=0),
// then set the endhue to the starthue.
// This lets us ramp smoothly to black or white, regardless
// of what 'hue' was set in the endcolor (since it doesn't matter)
if( endcolor.value == 0 || endcolor.saturation == 0) {
endcolor.hue = startcolor.hue;
}
// Similarly, if we're fading in from black (val=0) or white (sat=0)
// then set the starthue to the endhue.
// This lets us ramp smoothly up from black or white, regardless
// of what 'hue' was set in the startcolor (since it doesn't matter)
if( startcolor.value == 0 || startcolor.saturation == 0) {
startcolor.hue = endcolor.hue;
}
saccum87 huedistance87;
saccum87 satdistance87;
saccum87 valdistance87;
satdistance87 = (endcolor.sat - startcolor.sat) << 7;
valdistance87 = (endcolor.val - startcolor.val) << 7;
uint8_t huedelta8 = endcolor.hue - startcolor.hue;
if( directionCode == SHORTEST_HUES ) {
directionCode = FORWARD_HUES;
if( huedelta8 > 127) {
directionCode = BACKWARD_HUES;
}
}
if( directionCode == LONGEST_HUES ) {
directionCode = FORWARD_HUES;
if( huedelta8 < 128) {
directionCode = BACKWARD_HUES;
}
}
if( directionCode == FORWARD_HUES) {
huedistance87 = huedelta8 << 7;
}
else /* directionCode == BACKWARD_HUES */
{
huedistance87 = (uint8_t)(256 - huedelta8) << 7;
huedistance87 = -huedistance87;
}
uint16_t pixeldistance = endpos - startpos;
int16_t divisor = pixeldistance ? pixeldistance : 1;
saccum87 huedelta87 = huedistance87 / divisor;
saccum87 satdelta87 = satdistance87 / divisor;
saccum87 valdelta87 = valdistance87 / divisor;
huedelta87 *= 2;
satdelta87 *= 2;
valdelta87 *= 2;
accum88 hue88 = startcolor.hue << 8;
accum88 sat88 = startcolor.sat << 8;
accum88 val88 = startcolor.val << 8;
for( uint16_t i = startpos; i <= endpos; ++i) {
targetArray[i] = CHSV( hue88 >> 8, sat88 >> 8, val88 >> 8);
hue88 += huedelta87;
sat88 += satdelta87;
val88 += valdelta87;
}
}
/// Fill a range of LEDs with a smooth HSV gradient between two HSV colors.
/// @see fill_gradient()
/// @param targetArray a pointer to the color array to fill
/// @param numLeds the number of LEDs to fill
/// @param c1 the starting color in the gradient
/// @param c2 the end color for the gradient
/// @param directionCode the direction to travel around the color wheel
template <typename T>
void fill_gradient( T* targetArray, uint16_t numLeds, const CHSV& c1, const CHSV& c2,
TGradientDirectionCode directionCode = SHORTEST_HUES )
{
uint16_t last = numLeds - 1;
fill_gradient( targetArray, 0, c1, last, c2, directionCode);
}
/// Fill a range of LEDs with a smooth HSV gradient between three HSV colors.
/// @see fill_gradient()
/// @param targetArray a pointer to the color array to fill
/// @param numLeds the number of LEDs to fill
/// @param c1 the starting color in the gradient
/// @param c2 the middle color for the gradient
/// @param c3 the end color for the gradient
/// @param directionCode the direction to travel around the color wheel
template <typename T>
void fill_gradient( T* targetArray, uint16_t numLeds,
const CHSV& c1, const CHSV& c2, const CHSV& c3,
TGradientDirectionCode directionCode = SHORTEST_HUES )
{
uint16_t half = (numLeds / 2);
uint16_t last = numLeds - 1;
fill_gradient( targetArray, 0, c1, half, c2, directionCode);
fill_gradient( targetArray, half, c2, last, c3, directionCode);
}
/// Fill a range of LEDs with a smooth HSV gradient between four HSV colors.
/// @see fill_gradient()
/// @param targetArray a pointer to the color array to fill
/// @param numLeds the number of LEDs to fill
/// @param c1 the starting color in the gradient
/// @param c2 the first middle color for the gradient
/// @param c3 the second middle color for the gradient
/// @param c4 the end color for the gradient
/// @param directionCode the direction to travel around the color wheel
template <typename T>
void fill_gradient( T* targetArray, uint16_t numLeds,
const CHSV& c1, const CHSV& c2, const CHSV& c3, const CHSV& c4,
TGradientDirectionCode directionCode = SHORTEST_HUES )
{
uint16_t onethird = (numLeds / 3);
uint16_t twothirds = ((numLeds * 2) / 3);
uint16_t last = numLeds - 1;
fill_gradient( targetArray, 0, c1, onethird, c2, directionCode);
fill_gradient( targetArray, onethird, c2, twothirds, c3, directionCode);
fill_gradient( targetArray, twothirds, c3, last, c4, directionCode);
}
/// Convenience synonym
#define fill_gradient_HSV fill_gradient
/// Fill a range of LEDs with a smooth RGB gradient between two RGB colors.
/// Unlike HSV, there is no "color wheel" in RGB space, and therefore there's only one
/// "direction" for the gradient to go. This means there's no TGradientDirectionCode
/// parameter for direction.
/// @param leds a pointer to the LED array to fill
/// @param startpos the starting position in the array
/// @param startcolor the starting color for the gradient
/// @param endpos the ending position in the array
/// @param endcolor the end color for the gradient
void fill_gradient_RGB( CRGB* leds,
uint16_t startpos, CRGB startcolor,
uint16_t endpos, CRGB endcolor );
/// Fill a range of LEDs with a smooth RGB gradient between two RGB colors.
/// @see fill_gradient_RGB()
/// @param leds a pointer to the LED array to fill
/// @param numLeds the number of LEDs to fill
/// @param c1 the starting color in the gradient
/// @param c2 the end color for the gradient
void fill_gradient_RGB( CRGB* leds, uint16_t numLeds, const CRGB& c1, const CRGB& c2);
/// Fill a range of LEDs with a smooth RGB gradient between three RGB colors.
/// @see fill_gradient_RGB()
/// @param leds a pointer to the LED array to fill
/// @param numLeds the number of LEDs to fill
/// @param c1 the starting color in the gradient
/// @param c2 the middle color for the gradient
/// @param c3 the end color for the gradient
void fill_gradient_RGB( CRGB* leds, uint16_t numLeds, const CRGB& c1, const CRGB& c2, const CRGB& c3);
/// Fill a range of LEDs with a smooth RGB gradient between four RGB colors.
/// @see fill_gradient_RGB()
/// @param leds a pointer to the LED array to fill
/// @param numLeds the number of LEDs to fill
/// @param c1 the starting color in the gradient
/// @param c2 the first middle color for the gradient
/// @param c3 the second middle color for the gradient
/// @param c4 the end color for the gradient
void fill_gradient_RGB( CRGB* leds, uint16_t numLeds, const CRGB& c1, const CRGB& c2, const CRGB& c3, const CRGB& c4);
/// @} ColorFills
/// @defgroup ColorFades Color Fade Functions
/// Functions for fading LED arrays
/// @{
/// Reduce the brightness of an array of pixels all at once.
/// Guaranteed to never fade all the way to black.
/// @param leds a pointer to the LED array to fade
/// @param num_leds the number of LEDs to fade
/// @param fadeBy how much to fade each LED
void fadeLightBy( CRGB* leds, uint16_t num_leds, uint8_t fadeBy);
/// @copydoc fadeLightBy()
void fade_video( CRGB* leds, uint16_t num_leds, uint8_t fadeBy);
/// Scale the brightness of an array of pixels all at once.
/// Guaranteed to never fade all the way to black.
/// @param leds a pointer to the LED array to scale
/// @param num_leds the number of LEDs to scale
/// @param scale how much to scale each LED
void nscale8_video( CRGB* leds, uint16_t num_leds, uint8_t scale);
/// Reduce the brightness of an array of pixels all at once.
/// This function will eventually fade all the way to black.
/// @param leds a pointer to the LED array to fade
/// @param num_leds the number of LEDs to fade
/// @param fadeBy how much to fade each LED
void fadeToBlackBy( CRGB* leds, uint16_t num_leds, uint8_t fadeBy);
/// @copydoc fadeToBlackBy()
void fade_raw( CRGB* leds, uint16_t num_leds, uint8_t fadeBy);
/// Scale the brightness of an array of pixels all at once.
/// This function will eventually fade all the way to black, even
/// if "scale" is not zero.
/// @param leds a pointer to the LED array to scale
/// @param num_leds the number of LEDs to scale
/// @param scale how much to scale each LED
void nscale8( CRGB* leds, uint16_t num_leds, uint8_t scale);
/// Reduce the brightness of an array of pixels as thought it were seen through
/// a transparent filter with the specified color.
/// For example, if the colormask if CRGB(200, 100, 50), then the pixels' red will
/// be faded to 200/256ths, their green to 100/256ths, and their blue to 50/256ths.
/// This particular example will give a "hot fade" look, with white fading to yellow,
/// then red, then black. You can also use colormasks like CRGB::Blue to zero out the
/// red and green elements, leaving blue (largely) the same.
/// @param leds a pointer to the LED array to fade
/// @param numLeds the number of LEDs to fade
/// @param colormask the color mask to fade with
void fadeUsingColor( CRGB* leds, uint16_t numLeds, const CRGB& colormask);
/// @} ColorFades
/// @defgroup ColorBlends Color Blending Functions
/// Functions for blending colors together
/// @{
/// Computes a new color blended some fraction of the way between two other colors.
/// @param p1 the first color to blend
/// @param p2 the second color to blend
/// @param amountOfP2 the fraction of p2 to blend into p1
CRGB blend( const CRGB& p1, const CRGB& p2, fract8 amountOfP2 );
/// @copydoc blend(const CRGB&, const CRGB&, fract8)
/// @param directionCode the direction to travel around the color wheel
CHSV blend( const CHSV& p1, const CHSV& p2, fract8 amountOfP2,
TGradientDirectionCode directionCode = SHORTEST_HUES );
/// Computes a new blended array of colors, each some fraction of the way between
/// corresponding elements of two source arrays of colors.
/// Useful for blending palettes.
/// @param src1 the first array of colors to blend
/// @param src2 the second array of colors to blend
/// @param dest the destination array for the colors
/// @param count the number of LEDs to blend
/// @param amountOfsrc2 the fraction of src2 to blend into src1
CRGB* blend( const CRGB* src1, const CRGB* src2, CRGB* dest,
uint16_t count, fract8 amountOfsrc2 );
/// @copydoc blend(const CRGB*, const CRGB*, CRGB*, uint16_t, fract8)
/// @param directionCode the direction to travel around the color wheel
CHSV* blend( const CHSV* src1, const CHSV* src2, CHSV* dest,
uint16_t count, fract8 amountOfsrc2,
TGradientDirectionCode directionCode = SHORTEST_HUES );
/// Destructively modifies one color, blending in a given fraction of an overlay color
/// @param existing the color to modify
/// @param overlay the color to blend into existing
/// @param amountOfOverlay the fraction of overlay to blend into existing
CRGB& nblend( CRGB& existing, const CRGB& overlay, fract8 amountOfOverlay );
/// @copydoc nblend(CRGB&, const CRGB&, fract8)
/// @param directionCode the direction to travel around the color wheel
CHSV& nblend( CHSV& existing, const CHSV& overlay, fract8 amountOfOverlay,
TGradientDirectionCode directionCode = SHORTEST_HUES );
/// Destructively blends a given fraction of a color array into an existing color array
/// @param existing the color array to modify
/// @param overlay the color array to blend into existing
/// @param count the number of colors to process
/// @param amountOfOverlay the fraction of overlay to blend into existing
void nblend( CRGB* existing, CRGB* overlay, uint16_t count, fract8 amountOfOverlay);
/// @copydoc nblend(CRGB*, CRGB*, uint16_t, fract8)
/// @param directionCode the direction to travel around the color wheel
void nblend( CHSV* existing, CHSV* overlay, uint16_t count, fract8 amountOfOverlay,
TGradientDirectionCode directionCode = SHORTEST_HUES);
/// @} ColorBlends
/// @defgroup ColorBlurs Color Blurring Functions
/// Functions for blurring colors
/// @{
/// One-dimensional blur filter.
/// Spreads light to 2 line neighbors.
/// * 0 = no spread at all
/// * 64 = moderate spreading
/// * 172 = maximum smooth, even spreading
/// * 173..255 = wider spreading, but increasing flicker
///
/// Total light is NOT entirely conserved, so many repeated
/// calls to 'blur' will also result in the light fading,
/// eventually all the way to black; this is by design so that
/// it can be used to (slowly) clear the LEDs to black.
/// @param leds a pointer to the LED array to blur
/// @param numLeds the number of LEDs to blur
/// @param blur_amount the amount of blur to apply
void blur1d( CRGB* leds, uint16_t numLeds, fract8 blur_amount);
/// Two-dimensional blur filter.
/// Spreads light to 8 XY neighbors.
/// * 0 = no spread at all
/// * 64 = moderate spreading
/// * 172 = maximum smooth, even spreading
/// * 173..255 = wider spreading, but increasing flicker
///
/// Total light is NOT entirely conserved, so many repeated
/// calls to 'blur' will also result in the light fading,
/// eventually all the way to black; this is by design so that
/// it can be used to (slowly) clear the LEDs to black.
/// @param leds a pointer to the LED array to blur
/// @param width the width of the matrix
/// @param height the height of the matrix
/// @param blur_amount the amount of blur to apply
void blur2d( CRGB* leds, uint8_t width, uint8_t height, fract8 blur_amount);
/// Perform a blur1d() on every row of a rectangular matrix
/// @see blur1d()
/// @param leds a pointer to the LED array to blur
/// @param width the width of the matrix
/// @param height the height of the matrix
/// @param blur_amount the amount of blur to apply
void blurRows( CRGB* leds, uint8_t width, uint8_t height, fract8 blur_amount);
/// Perform a blur1d() on every column of a rectangular matrix
/// @copydetails blurRows()
void blurColumns(CRGB* leds, uint8_t width, uint8_t height, fract8 blur_amount);
/// @} ColorBlurs
/// @addtogroup ColorFills
/// @{
/// Approximates a "black body radiation" spectrum for
/// a given "heat" level. This is useful for animations of "fire".
/// Heat is specified as an arbitrary scale from 0 (cool) to 255 (hot).
/// This is NOT a chromatically correct "black body radiation"
/// spectrum, but it's surprisingly close, and it's fast and small.
CRGB HeatColor( uint8_t temperature);
/// @} ColorFills
/// @} ColorUtils
/// @defgroup ColorPalettes Color Palettes
/// Functions and class definitions for color palettes.
///
/// RGB palettes map an 8-bit value (0-255) to an RGB color.
///
/// You can create any color palette you wish; a couple of starters
/// are provided: ForestColors_p, CloudColors_p, LavaColors_p, OceanColors_p,
/// RainbowColors_p, and RainbowStripeColors_p.
///
/// Palettes come in the traditional 256-entry variety, which take
/// up 768 bytes of RAM, and lightweight 16-entry varieties. The 16-entry
/// variety automatically interpolates between its entries to produce
/// a full 256-element color map, but at a cost of only 48 bytes of RAM.
///
/// Basic operation is like this (using the 16-entry variety):
///
/// 1. Declare your palette storage:
/// @code{.cpp}
/// CRGBPalette16 myPalette;
/// @endcode
///
/// 2. Fill `myPalette` with your own 16 colors, or with a preset color scheme.
/// You can specify your 16 colors a variety of ways:
/// @code{.cpp}
/// CRGBPalette16 myPalette(
/// CRGB::Black,
/// CRGB::Black,
/// CRGB::Red,
/// CRGB::Yellow,
/// CRGB::Green,
/// CRGB::Blue,
/// CRGB::Purple,
/// CRGB::Black,
///
/// 0x100000,
/// 0x200000,
/// 0x400000,
/// 0x800000,
///
/// CHSV( 30,255,255),
/// CHSV( 50,255,255),
/// CHSV( 70,255,255),
/// CHSV( 90,255,255)
/// );
/// @endcode
///
/// Or you can initiaize your palette with a preset color scheme:
/// @code{.cpp}
/// myPalette = RainbowStripesColors_p;
/// @endcode
///
/// 3. Any time you want to set a pixel to a color from your palette, use
/// `ColorFromPalette()` as shown:
///
/// @code{.cpp}
/// uint8_t index = /* any value 0-255 */;
/// leds[i] = ColorFromPalette(myPalette, index);
/// @endcode
///
/// Even though your palette has only 16 explicily defined entries, you
/// can use an "index" from 0-255. The 16 explicit palette entries will
/// be spread evenly across the 0-255 range, and the intermedate values
/// will be RGB-interpolated between adjacent explicit entries.
///
/// It's easier to use than it sounds.
///
/// @{
/// @defgroup PaletteClasses Palette Classes
/// Class definitions for color palettes.
/// @todo For documentation purposes it would be nice to reorder these
/// definitions by type and in ascending number of entries.
///
/// @{
class CRGBPalette16;
class CRGBPalette32;
class CRGBPalette256;
class CHSVPalette16;
class CHSVPalette32;
class CHSVPalette256;
typedef uint32_t TProgmemRGBPalette16[16]; ///< CRGBPalette16 entries stored in PROGMEM memory
typedef uint32_t TProgmemHSVPalette16[16]; ///< CHSVPalette16 entries stored in PROGMEM memory
/// Alias for TProgmemRGBPalette16
#define TProgmemPalette16 TProgmemRGBPalette16
typedef uint32_t TProgmemRGBPalette32[32]; ///< CRGBPalette32 entries stored in PROGMEM memory
typedef uint32_t TProgmemHSVPalette32[32]; ///< CHSVPalette32 entries stored in PROGMEM memory
/// Alias for TProgmemRGBPalette32
#define TProgmemPalette32 TProgmemRGBPalette32
/// Byte of an RGB gradient, stored in PROGMEM memory
typedef const uint8_t TProgmemRGBGradientPalette_byte;
/// Pointer to bytes of an RGB gradient, stored in PROGMEM memory
/// @see DEFINE_GRADIENT_PALETTE
/// @see DECLARE_GRADIENT_PALETTE
typedef const TProgmemRGBGradientPalette_byte *TProgmemRGBGradientPalette_bytes;
/// Alias of ::TProgmemRGBGradientPalette_bytes
typedef TProgmemRGBGradientPalette_bytes TProgmemRGBGradientPalettePtr;
/// Struct for digesting gradient pointer data into its components.
/// This is used when loading a gradient stored in PROGMEM or on
/// the heap into a palette. The pointer is dereferenced and interpreted as
/// this struct, so the component parts can be addressed and copied by name.
typedef union {
struct {
uint8_t index; ///< index of the color entry in the gradient
uint8_t r; ///< CRGB::red channel value of the color entry
uint8_t g; ///< CRGB::green channel value of the color entry
uint8_t b; ///< CRGB::blue channel value of the color entry
};
uint32_t dword; ///< values as a packed 32-bit double word
uint8_t bytes[4]; ///< values as an array
} TRGBGradientPaletteEntryUnion;
typedef uint8_t TDynamicRGBGradientPalette_byte; ///< Byte of an RGB gradient entry, stored in dynamic (heap) memory
typedef const TDynamicRGBGradientPalette_byte *TDynamicRGBGradientPalette_bytes; ///< Pointer to bytes of an RGB gradient, stored in dynamic (heap) memory
typedef TDynamicRGBGradientPalette_bytes TDynamicRGBGradientPalettePtr; ///< Alias of ::TDynamicRGBGradientPalette_bytes
/// @}
/// @defgroup PaletteUpscale Palette Upscaling Functions
/// Functions to upscale palettes from one type to another.
/// @{
/// Convert a 16-entry palette to a 256-entry palette
/// @param srcpal16 the source palette to upscale
/// @param destpal256 the destination palette for the upscaled data
void UpscalePalette(const struct CRGBPalette16& srcpal16, struct CRGBPalette256& destpal256);
/// @copydoc UpscalePalette(const struct CRGBPalette16&, struct CRGBPalette256&)
void UpscalePalette(const struct CHSVPalette16& srcpal16, struct CHSVPalette256& destpal256);
/// Convert a 16-entry palette to a 32-entry palette
/// @param srcpal16 the source palette to upscale
/// @param destpal32 the destination palette for the upscaled data
void UpscalePalette(const struct CRGBPalette16& srcpal16, struct CRGBPalette32& destpal32);
/// @copydoc UpscalePalette(const struct CRGBPalette16&, struct CRGBPalette32&)
void UpscalePalette(const struct CHSVPalette16& srcpal16, struct CHSVPalette32& destpal32);
/// Convert a 32-entry palette to a 256-entry palette
/// @param srcpal32 the source palette to upscale
/// @param destpal256 the destination palette for the upscaled data
void UpscalePalette(const struct CRGBPalette32& srcpal32, struct CRGBPalette256& destpal256);
/// @copydoc UpscalePalette(const struct CRGBPalette32&, struct CRGBPalette256&)
void UpscalePalette(const struct CHSVPalette32& srcpal32, struct CHSVPalette256& destpal256);
/// @} PaletteUpscale
/// @addtogroup PaletteClasses
/// @{
/// HSV color palette with 16 discrete values
class CHSVPalette16 {
public:
CHSV entries[16]; ///< the color entries that make up the palette
/// @copydoc CHSV::CHSV()
CHSVPalette16() {};
/// Create palette from 16 CHSV values
CHSVPalette16( const CHSV& c00,const CHSV& c01,const CHSV& c02,const CHSV& c03,
const CHSV& c04,const CHSV& c05,const CHSV& c06,const CHSV& c07,
const CHSV& c08,const CHSV& c09,const CHSV& c10,const CHSV& c11,
const CHSV& c12,const CHSV& c13,const CHSV& c14,const CHSV& c15 )
{
entries[0]=c00; entries[1]=c01; entries[2]=c02; entries[3]=c03;
entries[4]=c04; entries[5]=c05; entries[6]=c06; entries[7]=c07;
entries[8]=c08; entries[9]=c09; entries[10]=c10; entries[11]=c11;
entries[12]=c12; entries[13]=c13; entries[14]=c14; entries[15]=c15;
};
/// Copy constructor
CHSVPalette16( const CHSVPalette16& rhs)
{
memmove8( (void *) &(entries[0]), &(rhs.entries[0]), sizeof( entries));
}
/// @copydoc CHSVPalette16(const CHSVPalette16& rhs)
CHSVPalette16& operator=( const CHSVPalette16& rhs)
{
memmove8( (void *) &(entries[0]), &(rhs.entries[0]), sizeof( entries));
return *this;
}
/// Create palette from palette stored in PROGMEM
CHSVPalette16( const TProgmemHSVPalette16& rhs)
{
for( uint8_t i = 0; i < 16; ++i) {
CRGB xyz = FL_PGM_READ_DWORD_NEAR( rhs + i);
entries[i].hue = xyz.red;
entries[i].sat = xyz.green;
entries[i].val = xyz.blue;
}
}
/// @copydoc CHSVPalette16(const TProgmemHSVPalette16&)
CHSVPalette16& operator=( const TProgmemHSVPalette16& rhs)
{
for( uint8_t i = 0; i < 16; ++i) {
CRGB xyz = FL_PGM_READ_DWORD_NEAR( rhs + i);
entries[i].hue = xyz.red;
entries[i].sat = xyz.green;
entries[i].val = xyz.blue;
}
return *this;
}
/// Array access operator to index into the gradient entries
/// @param x the index to retrieve
/// @returns reference to an entry in the palette's color array
/// @note This does not perform any interpolation like ColorFromPalette(),
/// it accesses the underlying entries that make up the gradient. Beware
/// of bounds issues!
inline CHSV& operator[] (uint8_t x) __attribute__((always_inline))
{
return entries[x];
}
/// @copydoc operator[]
inline const CHSV& operator[] (uint8_t x) const __attribute__((always_inline))
{
return entries[x];
}
/// @copydoc operator[]
inline CHSV& operator[] (int x) __attribute__((always_inline))
{
return entries[(uint8_t)x];
}
/// @copydoc operator[]
inline const CHSV& operator[] (int x) const __attribute__((always_inline))
{
return entries[(uint8_t)x];
}
/// Get the underlying pointer to the CHSV entries making up the palette
operator CHSV*()
{
return &(entries[0]);
}
/// Check if two palettes have the same color entries
bool operator==( const CHSVPalette16 &rhs) const
{
const uint8_t* p = (const uint8_t*)(&(this->entries[0]));
const uint8_t* q = (const uint8_t*)(&(rhs.entries[0]));
if( p == q) return true;
for( uint8_t i = 0; i < (sizeof( entries)); ++i) {
if( *p != *q) return false;
++p;
++q;
}
return true;
}
/// Check if two palettes do not have the same color entries
bool operator!=( const CHSVPalette16 &rhs) const
{
return !( *this == rhs);
}
/// Create palette filled with one color
/// @param c1 the color to fill the palette with
CHSVPalette16( const CHSV& c1)
{
fill_solid( &(entries[0]), 16, c1);
}
/// Create palette with a gradient from one color to another
/// @param c1 the starting color for the gradient
/// @param c2 the end color for the gradient
CHSVPalette16( const CHSV& c1, const CHSV& c2)
{
fill_gradient( &(entries[0]), 16, c1, c2);
}
/// Create palette with three-color gradient
/// @param c1 the starting color for the gradient
/// @param c2 the middle color for the gradient
/// @param c3 the end color for the gradient
CHSVPalette16( const CHSV& c1, const CHSV& c2, const CHSV& c3)
{
fill_gradient( &(entries[0]), 16, c1, c2, c3);
}
/// Create palette with four-color gradient
/// @param c1 the starting color for the gradient
/// @param c2 the first middle color for the gradient
/// @param c3 the second middle color for the gradient
/// @param c4 the end color for the gradient
CHSVPalette16( const CHSV& c1, const CHSV& c2, const CHSV& c3, const CHSV& c4)
{
fill_gradient( &(entries[0]), 16, c1, c2, c3, c4);
}
};
/// HSV color palette with 256 discrete values
class CHSVPalette256 {
public:
CHSV entries[256]; ///< @copydoc CHSVPalette16::entries
/// @copydoc CHSVPalette16::CHSVPalette16()
CHSVPalette256() {};
/// @copydoc CHSVPalette16::CHSVPalette16(const CHSV&, const CHSV&, const CHSV&, const CHSV&,
/// const CHSV&, const CHSV&, const CHSV&, const CHSV&,
/// const CHSV&, const CHSV&, const CHSV&, const CHSV&,
/// const CHSV&, const CHSV&, const CHSV&, const CHSV&)
CHSVPalette256( const CHSV& c00,const CHSV& c01,const CHSV& c02,const CHSV& c03,
const CHSV& c04,const CHSV& c05,const CHSV& c06,const CHSV& c07,
const CHSV& c08,const CHSV& c09,const CHSV& c10,const CHSV& c11,
const CHSV& c12,const CHSV& c13,const CHSV& c14,const CHSV& c15 )
{
CHSVPalette16 p16(c00,c01,c02,c03,c04,c05,c06,c07,
c08,c09,c10,c11,c12,c13,c14,c15);
*this = p16;
};
/// Copy constructor
CHSVPalette256( const CHSVPalette256& rhs)
{
memmove8( (void *) &(entries[0]), &(rhs.entries[0]), sizeof( entries));
}
/// @copydoc CHSVPalette256( const CHSVPalette256&)
CHSVPalette256& operator=( const CHSVPalette256& rhs)
{
memmove8( (void *) &(entries[0]), &(rhs.entries[0]), sizeof( entries));
return *this;
}
/// Create upscaled palette from 16-entry palette
CHSVPalette256( const CHSVPalette16& rhs16)
{
UpscalePalette( rhs16, *this);
}
/// @copydoc CHSVPalette256( const CHSVPalette16&)
CHSVPalette256& operator=( const CHSVPalette16& rhs16)
{
UpscalePalette( rhs16, *this);
return *this;
}
/// @copydoc CHSVPalette16::CHSVPalette16(const TProgmemHSVPalette16&)
CHSVPalette256( const TProgmemRGBPalette16& rhs)
{
CHSVPalette16 p16(rhs);
*this = p16;
}
/// @copydoc CHSVPalette16::CHSVPalette16(const TProgmemHSVPalette16&)
CHSVPalette256& operator=( const TProgmemRGBPalette16& rhs)
{
CHSVPalette16 p16(rhs);
*this = p16;
return *this;
}
/// @copydoc CHSVPalette16::operator[]
inline CHSV& operator[] (uint8_t x) __attribute__((always_inline))
{
return entries[x];
}
/// @copydoc operator[]
inline const CHSV& operator[] (uint8_t x) const __attribute__((always_inline))
{
return entries[x];
}
/// @copydoc operator[]
inline CHSV& operator[] (int x) __attribute__((always_inline))
{
return entries[(uint8_t)x];
}
/// @copydoc operator[]
inline const CHSV& operator[] (int x) const __attribute__((always_inline))
{
return entries[(uint8_t)x];
}
/// Get the underlying pointer to the CHSV entries making up the palette
operator CHSV*()
{
return &(entries[0]);
}
/// @copydoc CHSVPalette16::operator==
bool operator==( const CHSVPalette256 &rhs) const
{
const uint8_t* p = (const uint8_t*)(&(this->entries[0]));
const uint8_t* q = (const uint8_t*)(&(rhs.entries[0]));
if( p == q) return true;
for( uint16_t i = 0; i < (sizeof( entries)); ++i) {
if( *p != *q) return false;
++p;
++q;
}
return true;
}
/// @copydoc CHSVPalette16::operator!=
bool operator!=( const CHSVPalette256 &rhs) const
{
return !( *this == rhs);
}
/// @copydoc CHSVPalette16::CHSVPalette16(const CHSV&)
CHSVPalette256( const CHSV& c1)
{
fill_solid( &(entries[0]), 256, c1);
}
/// @copydoc CHSVPalette16::CHSVPalette16(const CHSV&, const CHSV&)
CHSVPalette256( const CHSV& c1, const CHSV& c2)
{
fill_gradient( &(entries[0]), 256, c1, c2);
}
/// @copydoc CHSVPalette16::CHSVPalette16(const CHSV&, const CHSV&, const CHSV&)
CHSVPalette256( const CHSV& c1, const CHSV& c2, const CHSV& c3)
{
fill_gradient( &(entries[0]), 256, c1, c2, c3);
}
/// @copydoc CHSVPalette16::CHSVPalette16(const CHSV&, const CHSV&, const CHSV&, const CHSV&)
CHSVPalette256( const CHSV& c1, const CHSV& c2, const CHSV& c3, const CHSV& c4)
{
fill_gradient( &(entries[0]), 256, c1, c2, c3, c4);
}
};
/// RGB color palette with 16 discrete values
class CRGBPalette16 {
public:
CRGB entries[16]; ///< @copydoc CHSVPalette16::entries
/// @copydoc CRGB::CRGB()
CRGBPalette16() {};
/// Create palette from 16 CRGB values
CRGBPalette16( const CRGB& c00,const CRGB& c01,const CRGB& c02,const CRGB& c03,
const CRGB& c04,const CRGB& c05,const CRGB& c06,const CRGB& c07,
const CRGB& c08,const CRGB& c09,const CRGB& c10,const CRGB& c11,
const CRGB& c12,const CRGB& c13,const CRGB& c14,const CRGB& c15 )
{
entries[0]=c00; entries[1]=c01; entries[2]=c02; entries[3]=c03;
entries[4]=c04; entries[5]=c05; entries[6]=c06; entries[7]=c07;
entries[8]=c08; entries[9]=c09; entries[10]=c10; entries[11]=c11;
entries[12]=c12; entries[13]=c13; entries[14]=c14; entries[15]=c15;
};
/// Copy constructor
CRGBPalette16( const CRGBPalette16& rhs)
{
memmove8( (void *) &(entries[0]), &(rhs.entries[0]), sizeof( entries));
}
/// Create palette from array of CRGB colors
CRGBPalette16( const CRGB rhs[16])
{
memmove8( (void *) &(entries[0]), &(rhs[0]), sizeof( entries));
}
/// @copydoc CRGBPalette16(const CRGBPalette16&)
CRGBPalette16& operator=( const CRGBPalette16& rhs)
{
memmove8( (void *) &(entries[0]), &(rhs.entries[0]), sizeof( entries));
return *this;
}
/// Create palette from array of CRGB colors
CRGBPalette16& operator=( const CRGB rhs[16])
{
memmove8( (void *) &(entries[0]), &(rhs[0]), sizeof( entries));
return *this;
}
/// Create palette from CHSV palette
CRGBPalette16( const CHSVPalette16& rhs)
{
for( uint8_t i = 0; i < 16; ++i) {
entries[i] = rhs.entries[i]; // implicit HSV-to-RGB conversion
}
}
/// Create palette from array of CHSV colors
CRGBPalette16( const CHSV rhs[16])
{
for( uint8_t i = 0; i < 16; ++i) {
entries[i] = rhs[i]; // implicit HSV-to-RGB conversion
}
}
/// @copydoc CRGBPalette16(const CHSVPalette16&)
CRGBPalette16& operator=( const CHSVPalette16& rhs)
{
for( uint8_t i = 0; i < 16; ++i) {
entries[i] = rhs.entries[i]; // implicit HSV-to-RGB conversion
}
return *this;
}
/// Create palette from array of CHSV colors
CRGBPalette16& operator=( const CHSV rhs[16])
{
for( uint8_t i = 0; i < 16; ++i) {
entries[i] = rhs[i]; // implicit HSV-to-RGB conversion
}
return *this;
}
/// Create palette from palette stored in PROGMEM
CRGBPalette16( const TProgmemRGBPalette16& rhs)
{
for( uint8_t i = 0; i < 16; ++i) {
entries[i] = FL_PGM_READ_DWORD_NEAR( rhs + i);
}
}
/// @copydoc CRGBPalette16(const TProgmemRGBPalette16&)
CRGBPalette16& operator=( const TProgmemRGBPalette16& rhs)
{
for( uint8_t i = 0; i < 16; ++i) {
entries[i] = FL_PGM_READ_DWORD_NEAR( rhs + i);
}
return *this;
}
/// @copydoc CHSVPalette16::operator==
bool operator==( const CRGBPalette16 &rhs) const
{
const uint8_t* p = (const uint8_t*)(&(this->entries[0]));
const uint8_t* q = (const uint8_t*)(&(rhs.entries[0]));
if( p == q) return true;
for( uint8_t i = 0; i < (sizeof( entries)); ++i) {