Color Palettes

Detailed Description

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:

   CRGBPalette16 myPalette;

2. Fill myPalette with your own 16 colors, or with a preset color scheme. You can specify your 16 colors a variety of ways:

   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)
   );

   Or you can initiaize your palette with a preset color scheme:

   myPalette = RainbowStripesColors_p;

3. Any time you want to set a pixel to a color from your palette, use ColorFromPalette() as shown:

   uint8_t index = /* any value 0-255 */;
   leds[i] = ColorFromPalette(myPalette, index);

   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.

Topics
	Palette Classes
	Class definitions for color palettes.
	Palette Color Functions
	Functions to retrieve smooth color data from palettes
	Palette Upscaling Functions
	Functions to upscale palettes from one type to another.
	Predefined Color Palettes
	Stock color palettes, only included when used.

Macros
#define	DEFINE_GRADIENT_PALETTE(X)
	Defines a static RGB palette very compactly using a series of connected color gradients.
#define	DECLARE_GRADIENT_PALETTE(X)
	Forward-declaration macro for DEFINE_GRADIENT_PALETTE(X)

Macro Definition Documentation

DECLARE_GRADIENT_PALETTE

#define DECLARE_GRADIENT_PALETTE

(

X

)

Value:

  FL_ALIGN_PROGMEM \
  extern const TProgmemRGBGradientPalette_byte X[] FL_PROGMEM

Forward-declaration macro for DEFINE_GRADIENT_PALETTE(X)

Definition at line 2197 of file colorutils.h.

DEFINE_GRADIENT_PALETTE

#define DEFINE_GRADIENT_PALETTE

(

X

)

Value:

  FL_ALIGN_PROGMEM \
  extern const TProgmemRGBGradientPalette_byte X[] FL_PROGMEM =

Defines a static RGB palette very compactly using a series of connected color gradients.

For example, if you want the first 3/4ths of the palette to be a slow gradient ramping from black to red, and then the remaining 1/4 of the palette to be a quicker ramp to white, you specify just three points: the starting black point (at index 0), the red midpoint (at index 192), and the final white point (at index 255). It looks like this:

index:  0                                    192          255
        |----------r-r-r-rrrrrrrrRrRrRrRrRRRR-|-RRWRWWRWWW-|
color: (0,0,0)                           (255,0,0)    (255,255,255)

Here's how you'd define that gradient palette using this macro:

DEFINE_GRADIENT_PALETTE( black_to_red_to_white_p ) {
     0,    0,   0,   0,  /* at index 0,   black(0,0,0) */
    192, 255,   0,   0,  /* at index 192, red(255,0,0) */
    255, 255, 255, 255   /* at index 255, white(255,255,255) */
};

This format is designed for compact storage. The example palette here takes up just 12 bytes of PROGMEM (flash) storage, and zero bytes of SRAM when not currently in use.

To use one of these gradient palettes, simply assign it into a CRGBPalette16 or a CRGBPalette256, like this:

CRGBPalette16 pal = black_to_red_to_white_p;

When the assignment is made, the gradients are expanded out into either 16 or 256 palette entries, depending on the kind of palette object they're assigned to.

Warning

The last "index" position MUST be 255! Failure to end with index 255 will result in program hangs or crashes.

Warning

At this point, these gradient palette definitions MUST be stored in PROGMEM on AVR-based Arduinos. If you use the DEFINE_GRADIENT_PALETTE macro, this is taken of automatically.

Definition at line 2192 of file colorutils.h.