FastLED 3.9.7
Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Enumerations | Functions
colorutils.h File Reference

Detailed Description

Utility functions for color fill, palettes, blending, and more.

Definition in file colorutils.h.

#include "FastLED.h"
#include "pixeltypes.h"
#include "fastled_progmem.h"
#include "fl/xymap.h"

Go to the source code of this file.

Classes

union  TRGBGradientPaletteEntryUnion
 Struct for digesting gradient pointer data into its components. More...
 
class  CHSVPalette16
 HSV color palette with 16 discrete values. More...
 
class  CHSVPalette256
 HSV color palette with 256 discrete values. More...
 
class  CRGBPalette16
 RGB color palette with 16 discrete values. More...
 
class  CHSVPalette32
 HSV color palette with 32 discrete values. More...
 
class  CRGBPalette32
 RGB color palette with 32 discrete values. More...
 
class  CRGBPalette256
 RGB color palette with 256 discrete values. More...
 

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)
 
#define TProgmemPalette16   TProgmemRGBPalette16
 Alias for TProgmemRGBPalette16.
 
#define TProgmemPalette32   TProgmemRGBPalette32
 Alias for TProgmemRGBPalette32.
 
#define saccum87   int16_t
 ANSI: signed short _Accum.
 
#define fill_gradient_HSV   fill_gradient
 Convenience synonym.
 

Typedefs

typedef uint32_t TProgmemRGBPalette16[16]
 CRGBPalette16 entries stored in PROGMEM memory.
 
typedef uint32_t TProgmemHSVPalette16[16]
 CHSVPalette16 entries stored in PROGMEM memory.
 
typedef uint32_t TProgmemRGBPalette32[32]
 CRGBPalette32 entries stored in PROGMEM memory.
 
typedef uint32_t TProgmemHSVPalette32[32]
 CHSVPalette32 entries stored in PROGMEM memory.
 
typedef const uint8_t TProgmemRGBGradientPalette_byte
 Byte of an RGB gradient, stored in PROGMEM memory.
 
typedef const TProgmemRGBGradientPalette_byte * TProgmemRGBGradientPalette_bytes
 Pointer to bytes of an RGB gradient, stored in PROGMEM memory.
 
typedef TProgmemRGBGradientPalette_bytes TProgmemRGBGradientPaletteRef
 Alias of TProgmemRGBGradientPalette_bytes.
 
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 TDynamicRGBGradientPaletteRef
 Alias of TDynamicRGBGradientPalette_bytes.
 

Enumerations

enum  TGradientDirectionCode { FORWARD_HUES , BACKWARD_HUES , SHORTEST_HUES , LONGEST_HUES }
 Hue direction for calculating fill gradients. More...
 
enum  TBlendType { NOBLEND =0 , LINEARBLEND =1 , LINEARBLEND_NOWRAP =2 }
 Color interpolation options for palette. More...
 

Functions

void fill_solid (struct CRGB *targetArray, int numToFill, const struct CRGB &color)
 Fill a range of LEDs with a solid color.
 
void fill_solid (struct CHSV *targetArray, int numToFill, const struct CHSV &color)
 Fill a range of LEDs with a solid color.
 
void fill_rainbow (struct CRGB *targetArray, int numToFill, uint8_t initialhue, uint8_t deltahue=5)
 Fill a range of LEDs with a rainbow of colors.
 
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.
 
void fill_rainbow_circular (struct CRGB *targetArray, int numToFill, uint8_t initialhue, bool reversed=false)
 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.
 
void fill_rainbow_circular (struct CHSV *targetArray, int numToFill, uint8_t initialhue, bool reversed=false)
 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.
 
template<typename T >
void fill_gradient (T *targetArray, uint16_t startpos, CHSV startcolor, uint16_t endpos, CHSV endcolor, TGradientDirectionCode directionCode=SHORTEST_HUES)
 Fill a range of LEDs with a smooth HSV gradient between two HSV colors.
 
template<typename T >
void fill_gradient (T *targetArray, uint16_t numLeds, const CHSV &c1, const CHSV &c2, TGradientDirectionCode directionCode=SHORTEST_HUES)
 Fill a range of LEDs with a smooth HSV gradient between two HSV colors.
 
template<typename T >
void fill_gradient (T *targetArray, uint16_t numLeds, const CHSV &c1, const CHSV &c2, const CHSV &c3, TGradientDirectionCode directionCode=SHORTEST_HUES)
 Fill a range of LEDs with a smooth HSV gradient between three HSV colors.
 
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)
 Fill a range of LEDs with a smooth HSV gradient between four HSV colors.
 
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.
 
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 two RGB colors.
 
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 three RGB colors.
 
void fill_gradient_RGB (CRGB *leds, uint16_t numLeds, const CRGB &c1, const CRGB &c2, const CRGB &c3, const CRGB &c4)
 Fill a range of LEDs with a smooth RGB gradient between four RGB colors.
 
void fadeLightBy (CRGB *leds, uint16_t num_leds, uint8_t fadeBy)
 Reduce the brightness of an array of pixels all at once.
 
void fade_video (CRGB *leds, uint16_t num_leds, uint8_t fadeBy)
 Reduce the brightness of an array of pixels all at once.
 
void nscale8_video (CRGB *leds, uint16_t num_leds, uint8_t scale)
 Scale the brightness of an array of pixels all at once.
 
void fadeToBlackBy (CRGB *leds, uint16_t num_leds, uint8_t fadeBy)
 Reduce the brightness of an array of pixels all at once.
 
void fade_raw (CRGB *leds, uint16_t num_leds, uint8_t fadeBy)
 Reduce the brightness of an array of pixels all at once.
 
void nscale8 (CRGB *leds, uint16_t num_leds, uint8_t scale)
 Scale the brightness of an array of pixels all at once.
 
void fadeUsingColor (CRGB *leds, uint16_t numLeds, const CRGB &colormask)
 Reduce the brightness of an array of pixels as thought it were seen through a transparent filter with the specified color.
 
CRGB blend (const CRGB &p1, const CRGB &p2, fract8 amountOfP2)
 Computes a new color blended some fraction of the way between two other colors.
 
CHSV blend (const CHSV &p1, const CHSV &p2, fract8 amountOfP2, TGradientDirectionCode directionCode=SHORTEST_HUES)
 Computes a new color blended some fraction of the way between two other colors.
 
CRGB * blend (const CRGB *src1, const CRGB *src2, CRGB *dest, uint16_t count, fract8 amountOfsrc2)
 Computes a new blended array of colors, each some fraction of the way between corresponding elements of two source arrays of colors.
 
CHSV * blend (const CHSV *src1, const CHSV *src2, CHSV *dest, uint16_t count, fract8 amountOfsrc2, 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.
 
CRGB & nblend (CRGB &existing, const CRGB &overlay, fract8 amountOfOverlay)
 Destructively modifies one color, blending in a given fraction of an overlay color.
 
CHSV & nblend (CHSV &existing, const CHSV &overlay, fract8 amountOfOverlay, TGradientDirectionCode directionCode=SHORTEST_HUES)
 Destructively modifies one color, blending in a given fraction of an overlay color.
 
void nblend (CRGB *existing, CRGB *overlay, uint16_t count, fract8 amountOfOverlay)
 Destructively blends a given fraction of a color array into an existing color array.
 
void nblend (CHSV *existing, CHSV *overlay, uint16_t count, fract8 amountOfOverlay, TGradientDirectionCode directionCode=SHORTEST_HUES)
 Destructively blends a given fraction of a color array into an existing color array.
 
void blur1d (CRGB *leds, uint16_t numLeds, fract8 blur_amount)
 One-dimensional blur filter.
 
void blur2d (CRGB *leds, uint8_t width, uint8_t height, fract8 blur_amount, const fl::XYMap &xymap)
 Two-dimensional blur filter.
 
void blurRows (CRGB *leds, uint8_t width, uint8_t height, fract8 blur_amount, const fl::XYMap &xymap)
 Perform a blur1d() on every row of a rectangular matrix.
 
void blurColumns (CRGB *leds, uint8_t width, uint8_t height, fract8 blur_amount, const fl::XYMap &xymap)
 Perform a blur1d() on every column of a rectangular matrix.
 
CRGB HeatColor (uint8_t temperature)
 Approximates a "black body radiation" spectrum for a given "heat" level.
 
void UpscalePalette (const class CRGBPalette16 &srcpal16, class CRGBPalette256 &destpal256)
 Convert a 16-entry palette to a 256-entry palette.
 
void UpscalePalette (const class CHSVPalette16 &srcpal16, class CHSVPalette256 &destpal256)
 Convert a 16-entry palette to a 256-entry palette.
 
void UpscalePalette (const class CRGBPalette16 &srcpal16, class CRGBPalette32 &destpal32)
 Convert a 16-entry palette to a 32-entry palette.
 
void UpscalePalette (const class CHSVPalette16 &srcpal16, class CHSVPalette32 &destpal32)
 Convert a 16-entry palette to a 32-entry palette.
 
void UpscalePalette (const class CRGBPalette32 &srcpal32, class CRGBPalette256 &destpal256)
 Convert a 32-entry palette to a 256-entry palette.
 
void UpscalePalette (const class CHSVPalette32 &srcpal32, class CHSVPalette256 &destpal256)
 Convert a 32-entry palette to a 256-entry palette.
 
CRGB ColorFromPalette (const CRGBPalette16 &pal, uint8_t index, uint8_t brightness=255, TBlendType blendType=LINEARBLEND)
 Get a color from a palette.
 
CRGB ColorFromPaletteExtended (const CRGBPalette16 &pal, uint16_t index, uint8_t brightness, TBlendType blendType)
 Same as ColorFromPalette, but with uint16_t index to give greater precision.
 
CRGB ColorFromPaletteExtended (const CRGBPalette32 &pal, uint16_t index, uint8_t brightness, TBlendType blendType)
 Same as ColorFromPalette, but higher precision.
 
CRGB ColorFromPalette (const TProgmemRGBPalette16 &pal, uint8_t index, uint8_t brightness=255, TBlendType blendType=LINEARBLEND)
 Get a color from a palette.
 
CRGB ColorFromPalette (const CRGBPalette256 &pal, uint8_t index, uint8_t brightness=255, TBlendType blendType=NOBLEND)
 Get a color from a palette.
 
CRGB ColorFromPaletteExtended (const CRGBPalette256 &pal, uint16_t index, uint8_t brightness, TBlendType blendType)
 
CHSV ColorFromPalette (const CHSVPalette16 &pal, uint8_t index, uint8_t brightness=255, TBlendType blendType=LINEARBLEND)
 Get a color from a palette.
 
CHSV ColorFromPalette (const CHSVPalette256 &pal, uint8_t index, uint8_t brightness=255, TBlendType blendType=NOBLEND)
 Get a color from a palette.
 
CRGB ColorFromPalette (const CRGBPalette32 &pal, uint8_t index, uint8_t brightness=255, TBlendType blendType=LINEARBLEND)
 Get a color from a palette.
 
CRGB ColorFromPalette (const TProgmemRGBPalette32 &pal, uint8_t index, uint8_t brightness=255, TBlendType blendType=LINEARBLEND)
 Get a color from a palette.
 
CHSV ColorFromPalette (const CHSVPalette32 &pal, uint8_t index, uint8_t brightness=255, TBlendType blendType=LINEARBLEND)
 Get a color from a palette.
 
template<typename PALETTE >
void fill_palette (CRGB *L, uint16_t N, uint8_t startIndex, uint8_t incIndex, const PALETTE &pal, uint8_t brightness=255, TBlendType blendType=LINEARBLEND)
 Fill a range of LEDs with a sequence of entries from a palette.
 
template<typename PALETTE >
void fill_palette_circular (CRGB *L, uint16_t N, uint8_t startIndex, const PALETTE &pal, uint8_t brightness=255, TBlendType blendType=LINEARBLEND, bool reversed=false)
 Fill a range of LEDs with a sequence of entries from a palette, so that the entire palette smoothly covers the range of LEDs.
 
template<typename PALETTE >
void map_data_into_colors_through_palette (uint8_t *dataArray, uint16_t dataCount, CRGB *targetColorArray, const PALETTE &pal, uint8_t brightness=255, uint8_t opacity=255, TBlendType blendType=LINEARBLEND)
 Maps an array of palette color indexes into an array of LED colors.
 
void nblendPaletteTowardPalette (CRGBPalette16 &currentPalette, CRGBPalette16 &targetPalette, uint8_t maxChanges=24)
 Alter one palette by making it slightly more like a "target palette".
 
uint8_t applyGamma_video (uint8_t brightness, float gamma)
 Applies a gamma adjustment to a color channel.
 
CRGB applyGamma_video (const CRGB &orig, float gamma)
 Applies a gamma adjustment to a color.
 
CRGB applyGamma_video (const CRGB &orig, float gammaR, float gammaG, float gammaB)
 Applies a gamma adjustment to a color.
 
CRGB & napplyGamma_video (CRGB &rgb, float gamma)
 Destructively applies a gamma adjustment to a color.
 
CRGB & napplyGamma_video (CRGB &rgb, float gammaR, float gammaG, float gammaB)
 Destructively applies a gamma adjustment to a color.
 
void napplyGamma_video (CRGB *rgbarray, uint16_t count, float gamma)
 Destructively applies a gamma adjustment to a color array.
 
void napplyGamma_video (CRGB *rgbarray, uint16_t count, float gammaR, float gammaG, float gammaB)
 Destructively applies a gamma adjustment to a color array.
 

Macro Definition Documentation

◆ DECLARE_GRADIENT_PALETTE

#define DECLARE_GRADIENT_PALETTE ( X)
Value:
FL_ALIGN_PROGMEM \
extern const ::TProgmemRGBGradientPalette_byte X[] FL_PROGMEM
FL_PROGMEM
#define FL_PROGMEM
PROGMEM keyword for storage.
Definition fastled_progmem.h:45

Forward-declaration macro for DEFINE_GRADIENT_PALETTE(X)

Definition at line 71 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) */
};
DEFINE_GRADIENT_PALETTE
#define DEFINE_GRADIENT_PALETTE(X)
Defines a static RGB palette very compactly using a series of connected color gradients.
Definition colorutils.h:66

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;
CRGBPalette16
RGB color palette with 16 discrete values.
Definition colorutils.h:997

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.

TProgmemRGBGradientPalette_byte must remain in the global namespace.

Definition at line 66 of file colorutils.h.

◆ TProgmemPalette16

#define TProgmemPalette16   TProgmemRGBPalette16

Alias for TProgmemRGBPalette16.

Examples
ColorPalette.ino.

Definition at line 79 of file colorutils.h.

◆ TProgmemPalette32

#define TProgmemPalette32   TProgmemRGBPalette32

Alias for TProgmemRGBPalette32.

Definition at line 83 of file colorutils.h.

Typedef Documentation

◆ TProgmemHSVPalette16

typedef uint32_t TProgmemHSVPalette16[16]

CHSVPalette16 entries stored in PROGMEM memory.

Definition at line 77 of file colorutils.h.

◆ TProgmemHSVPalette32

typedef uint32_t TProgmemHSVPalette32[32]

CHSVPalette32 entries stored in PROGMEM memory.

Definition at line 81 of file colorutils.h.

◆ TProgmemRGBGradientPalette_byte

typedef const uint8_t TProgmemRGBGradientPalette_byte

Byte of an RGB gradient, stored in PROGMEM memory.

Definition at line 86 of file colorutils.h.

◆ TProgmemRGBGradientPalette_bytes

typedef const TProgmemRGBGradientPalette_byte* TProgmemRGBGradientPalette_bytes

Pointer to bytes of an RGB gradient, stored in PROGMEM memory.

See also
DEFINE_GRADIENT_PALETTE
DECLARE_GRADIENT_PALETTE

Definition at line 90 of file colorutils.h.

◆ TProgmemRGBGradientPaletteRef

typedef TProgmemRGBGradientPalette_bytes TProgmemRGBGradientPaletteRef

Alias of TProgmemRGBGradientPalette_bytes.

Definition at line 92 of file colorutils.h.

◆ TProgmemRGBPalette16

typedef uint32_t TProgmemRGBPalette16[16]

CRGBPalette16 entries stored in PROGMEM memory.

Definition at line 76 of file colorutils.h.

◆ TProgmemRGBPalette32

typedef uint32_t TProgmemRGBPalette32[32]

CRGBPalette32 entries stored in PROGMEM memory.

Definition at line 80 of file colorutils.h.