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 1365 of file colorutils.cpp.

{
    uint8_t* p1;
    uint8_t* p2;
    uint8_t  changes = 0;
 
    p1 = (uint8_t*)current.entries;
    p2 = (uint8_t*)target.entries;
 
    const uint8_t totalChannels = sizeof(CRGBPalette16);
    for( uint8_t i = 0; i < totalChannels; ++i) {
        // if the values are equal, no changes are needed
        if( p1[i] == p2[i] ) { continue; }
 
        // if the current value is less than the target, increase it by one
        if( p1[i] < p2[i] ) { ++p1[i]; ++changes; }
 
        // if the current value is greater than the target,
        // increase it by one (or two if it's still greater).
        if( p1[i] > p2[i] ) {
            --p1[i]; ++changes;
            if( p1[i] > p2[i] ) { --p1[i]; }
        }
 
        // if we've hit the maximum number of changes, exit
        if( changes >= maxChanges) { break; }
    }
}

References CRGBPalette16::entries.

Referenced by fl::TwinkleFox::draw(), and loop().

Here is the caller graph for this function: