Detailed Description

Functions to retrieve smooth color data from palettes

Enumerations
enum	TBlendType { NOBLEND =0 , LINEARBLEND =1 , LINEARBLEND_NOWRAP =2 }
	Color interpolation options for palette. More...

Functions
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".

Enumeration Type Documentation

◆ TBlendType

enum TBlendType

Color interpolation options for palette.

Enumerator
NOBLEND	No interpolation between palette entries.
LINEARBLEND	Linear interpolation between palette entries, with wrap-around from end to the beginning again.
LINEARBLEND_NOWRAP	Linear interpolation between palette entries, but no wrap-around.

Definition at line 1984 of file colorutils.h.

Function Documentation

◆ ColorFromPalette() [1/8]

CHSV ColorFromPalette	(	const CHSVPalette16 &	pal,
		uint8_t	index,
		uint8_t	brightness = 255,
		TBlendType	blendType = LINEARBLEND )

Get a color from a palette.

These are the main functions for getting and using palette colors. Regardless of the number of entries in the base palette, this function will interpolate between entries to turn the discrete colors into a smooth gradient.

Parameters

pal	the palette to retrieve the color from
index	the position in the palette to retrieve the color for (0-255)
brightness	optional brightness value to scale the resulting color
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)

Definition at line 1075 of file colorutils.cpp.

◆ ColorFromPalette() [2/8]

CHSV ColorFromPalette	(	const CHSVPalette256 &	pal,
		uint8_t	index,
		uint8_t	brightness = 255,
		TBlendType	blendType = NOBLEND )

Get a color from a palette.

These are the main functions for getting and using palette colors. Regardless of the number of entries in the base palette, this function will interpolate between entries to turn the discrete colors into a smooth gradient.

Parameters

pal	the palette to retrieve the color from
index	the position in the palette to retrieve the color for (0-255)
brightness	optional brightness value to scale the resulting color
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)

Definition at line 1256 of file colorutils.cpp.

◆ ColorFromPalette() [3/8]

CHSV ColorFromPalette	(	const CHSVPalette32 &	pal,
		uint8_t	index,
		uint8_t	brightness = 255,
		TBlendType	blendType = LINEARBLEND )

Get a color from a palette.

These are the main functions for getting and using palette colors. Regardless of the number of entries in the base palette, this function will interpolate between entries to turn the discrete colors into a smooth gradient.

Parameters

pal	the palette to retrieve the color from
index	the position in the palette to retrieve the color for (0-255)
brightness	optional brightness value to scale the resulting color
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)

Definition at line 1163 of file colorutils.cpp.

◆ ColorFromPalette() [4/8]

CRGB ColorFromPalette	(	const CRGBPalette16 &	pal,
		uint8_t	index,
		uint8_t	brightness = 255,
		TBlendType	blendType = LINEARBLEND )

Get a color from a palette.

These are the main functions for getting and using palette colors. Regardless of the number of entries in the base palette, this function will interpolate between entries to turn the discrete colors into a smooth gradient.

Parameters

pal	the palette to retrieve the color from
index	the position in the palette to retrieve the color for (0-255)
brightness	optional brightness value to scale the resulting color
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)

Definition at line 606 of file colorutils.cpp.

◆ ColorFromPalette() [5/8]

CRGB ColorFromPalette	(	const CRGBPalette256 &	pal,
		uint8_t	index,
		uint8_t	brightness = 255,
		TBlendType	blendType = NOBLEND )

Get a color from a palette.

These are the main functions for getting and using palette colors. Regardless of the number of entries in the base palette, this function will interpolate between entries to turn the discrete colors into a smooth gradient.

Parameters

pal	the palette to retrieve the color from
index	the position in the palette to retrieve the color for (0-255)
brightness	optional brightness value to scale the resulting color
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)

Definition at line 1008 of file colorutils.cpp.

◆ ColorFromPalette() [6/8]

CRGB ColorFromPalette	(	const CRGBPalette32 &	pal,
		uint8_t	index,
		uint8_t	brightness = 255,
		TBlendType	blendType = LINEARBLEND )

Get a color from a palette.

These are the main functions for getting and using palette colors. Regardless of the number of entries in the base palette, this function will interpolate between entries to turn the discrete colors into a smooth gradient.

Parameters

pal	the palette to retrieve the color from
index	the position in the palette to retrieve the color for (0-255)
brightness	optional brightness value to scale the resulting color
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)

Definition at line 824 of file colorutils.cpp.

◆ ColorFromPalette() [7/8]

CRGB ColorFromPalette	(	const TProgmemRGBPalette16 &	pal,
		uint8_t	index,
		uint8_t	brightness = 255,
		TBlendType	blendType = LINEARBLEND )

Get a color from a palette.

These are the main functions for getting and using palette colors. Regardless of the number of entries in the base palette, this function will interpolate between entries to turn the discrete colors into a smooth gradient.

Parameters

pal	the palette to retrieve the color from
index	the position in the palette to retrieve the color for (0-255)
brightness	optional brightness value to scale the resulting color
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)

Definition at line 741 of file colorutils.cpp.

◆ ColorFromPalette() [8/8]

CRGB ColorFromPalette	(	const TProgmemRGBPalette32 &	pal,
		uint8_t	index,
		uint8_t	brightness = 255,
		TBlendType	blendType = LINEARBLEND )

Get a color from a palette.

These are the main functions for getting and using palette colors. Regardless of the number of entries in the base palette, this function will interpolate between entries to turn the discrete colors into a smooth gradient.

Parameters

pal	the palette to retrieve the color from
index	the position in the palette to retrieve the color for (0-255)
brightness	optional brightness value to scale the resulting color
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)

Definition at line 919 of file colorutils.cpp.

◆ ColorFromPaletteExtended() [1/3]

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.

Author: https://github.com/generalelectrix

See also: https://github.com/FastLED/FastLED/pull/202; https://wokwi.com/projects/285170662915441160; https://wokwi.com/projects/407831886158110721

Definition at line 695 of file colorutils.cpp.

◆ ColorFromPaletteExtended() [2/3]

CRGB ColorFromPaletteExtended	(	const CRGBPalette256 &	pal,
		uint16_t	index,
		uint8_t	brightness,
		TBlendType	blendType )

Definition at line 1027 of file colorutils.cpp.

◆ ColorFromPaletteExtended() [3/3]

CRGB ColorFromPaletteExtended	(	const CRGBPalette32 &	pal,
		uint16_t	index,
		uint8_t	brightness,
		TBlendType	blendType )

Same as ColorFromPalette, but higher precision.

Will eventually become the default.

Author: https://github.com/generalelectrix

See also: https://github.com/FastLED/FastLED/pull/202#issuecomment-631333384; https://wokwi.com/projects/285170662915441160

Definition at line 561 of file colorutils.cpp.

◆ fill_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 Parameters

PALETTE the type of the palette used (auto-deduced)

Parameters

L	pointer to the LED array to fill
N	number of LEDs to fill in the array
startIndex	the starting color index in the palette
incIndex	how much to increment the palette color index per LED
pal	the color palette to pull colors from
brightness	brightness value used to scale the resulting color
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)

Definition at line 2087 of file colorutils.h.

◆ fill_palette_circular()

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 Parameters

PALETTE the type of the palette used (auto-deduced)

Parameters

L	pointer to the LED array to fill
N	number of LEDs to fill in the array
startIndex	the starting color index in the palette
pal	the color palette to pull colors from
brightness	brightness value used to scale the resulting color
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)
reversed	whether to progress through the palette backwards

Definition at line 2110 of file colorutils.h.

◆ map_data_into_colors_through_palette()

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.

This function provides an easy way to create lightweight color patterns that can be deployed using any palette.

Parameters

dataArray	the source array, containing color indexes for the palette
dataCount	the number of data elements in the array
targetColorArray	the LED array to store the resulting colors into. Must be at least as long as `dataCount`.
pal	the color palette to pull colors from
brightness	optional brightness value used to scale the resulting color
opacity	optional opacity value for the new color. If this is 255 (default), the new colors will be written to the array directly. Otherwise the existing LED data will be scaled down using `CRGB::nscale8_video()` and then new colors will be added on top. A higher value means that the new colors will be more visible.
blendType	whether to take the palette entries directly (NOBLEND) or blend linearly between palette entries (LINEARBLEND)

Definition at line 2145 of file colorutils.h.

◆ nblendPaletteTowardPalette()

void nblendPaletteTowardPalette	(	CRGBPalette16 &	currentPalette,
		CRGBPalette16 &	targetPalette,
		uint8_t	maxChanges = 24 )

Alter one palette by making it slightly more like a "target palette".

Used for palette cross-fades.

It does this by comparing each of the R, G, and B channels of each entry in the current palette to the corresponding entry in the target palette and making small adjustments:

If the CRGB::red channel is too low, it will be increased.
If the CRGB::red channel is too high, it will be slightly reduced.

...and so on and so forth for the CRGB::green and CRGB::blue channels.

Additionally, there are two significant visual improvements to this algorithm implemented here. First is this:

When increasing a channel, it is stepped up by ONE.
When decreasing a channel, it is stepped down by TWO.

Due to the way the eye perceives light, and the way colors are represented in RGB, this produces a more uniform apparent brightness when cross-fading between most palette colors.

The second visual tweak is limiting the number of changes that will be made to the palette at once. If all the palette entries are changed at once, it can give a muddled appearance. However, if only a few palette entries are changed at once, you get a visually smoother transition: in the middle of the cross-fade your current palette will actually contain some colors from the old palette, a few blended colors, and some colors from the new palette.

Parameters

currentPalette	the palette to modify
targetPalette	the palette to move towards
maxChanges	the maximum number of possible palette changes to make to the color channels per call. The limit is 48 (16 color entries times 3 channels each). The default is 24, meaning that only half of the palette entries can be changed per call.

Warning: The palette passed as currentPalette will be modified! Be sure to make a copy beforehand if needed.

Todo: Shouldn't the targetPalette be const?

Definition at line 1327 of file colorutils.cpp.

Detailed Description

Enumerations

Functions

Enumeration Type Documentation

◆ TBlendType

Function Documentation

◆ ColorFromPalette() [1/8]

◆ ColorFromPalette() [2/8]

◆ ColorFromPalette() [3/8]

◆ ColorFromPalette() [4/8]

◆ ColorFromPalette() [5/8]

◆ ColorFromPalette() [6/8]

◆ ColorFromPalette() [7/8]

◆ ColorFromPalette() [8/8]

◆ ColorFromPaletteExtended() [1/3]

◆ ColorFromPaletteExtended() [2/3]

◆ ColorFromPaletteExtended() [3/3]

◆ fill_palette()

◆ fill_palette_circular()

◆ map_data_into_colors_through_palette()

◆ nblendPaletteTowardPalette()