14. fastLED调色板

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.

RGB 调色板将 8 位数值（0-255）映射为 RGB 颜色。
您可以创建任何您想要的调色板；我们提供了一些入门调色板：其中包括：ForestColors_p、CloudColors_p、LavaColors_p、OceanColors_p、RainbowColors_p 和 RainbowStripeColors_p。

调色板有占用 768 字节 RAM 的传统 256 条目调色板和轻量级 16 条目调色板。16 条目调色板会自动在条目之间进行插值，以生成完整的 256 元素色彩图，但只占用 48 字节的 RAM。

Basic operation is like this (using the 16-entry variety):

1. Declare your palette storage:

   CRGBPalette16 myPalette;
   

   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:用你自己的 16 种颜色或预设的配色方案填充 myPalette。您可以通过多种方式指定 16 种颜色：

   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.

   即使调色板只有 16 个明确定义的条目，您也可以使用 0-255 的 “索引”。16 个明确的调色板条目将均匀分布在 0-255 范围内，相邻的明确条目之间将采用 RGB 内插值。

   It’s easier to use than it sounds.

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

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:

使用一系列相连的颜色梯度，非常紧凑地定义静态 RGB 调色板。

例如，如果你希望调色板的前 3/4 部分是一个从黑色到红色的缓慢渐变，而调色板的其余 1/4 部分则是一个到白色的快速渐变，那么你只需指定三个点：黑色起点（位于索引 0）、红色中点（位于索引 192）和白色终点（位于索引 255）。看起来是这样的

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.

这种格式专为紧凑型存储而设计。这里的示例调色板仅占用 12 字节的 PROGMEM（闪存）存储空间，在不使用时，SRAM 的占用空间为零。

要使用这些渐变调色板，只需将其分配到 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.

分配时，渐变会扩展为 16 或 256 个调色板条目，具体取决于分配给哪种调色板对象。

• Warning

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

• 警告
  最后一个 "索引 "位置必须是 255！如果不以索引 255 结束，将导致程序挂起或崩溃。

• 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.

警告
在基于 AVR 的 Arduinos 上，这些渐变调色板定义必须存储在 PROGMEM 中。如果使用 DEFINE_GRADIENT_PALETTE 宏，则会自动执行此操作。

Additional notes on FastLED compact palettes:

Normally, in computer graphics, the palette (or “color lookup table”) has 256 entries, each containing a specific 24-bit RGB color. You can then index into the color palette using a simple 8-bit (one byte) value.

A 256-entry color palette takes up 768 bytes of RAM, which on Arduino is quite possibly “too many” bytes.

FastLED does offer traditional 256-element palettes, for setups that can afford the 768-byte cost in RAM.

However, FastLED also offers a compact alternative. FastLED offers palettes that store 16 distinct entries, but can be accessed AS IF they actually have 256 entries; this is accomplished by interpolating

between the 16 explicit entries to create fifteen intermediate palette entries between each pair.

So for example, if you set the first two explicit entries of a compact palette to Green (0,255,0) and Blue (0,0,255), and then retrieved the first sixteen entries from the virtual palette (of 256), you’d get Green, followed by a smooth gradient from green-to-blue, and then Blue.

/// @file    ColorPalette.ino
/// @brief   Demonstrates how to use @ref ColorPalettes
/// @example ColorPalette.ino#include <FastLED.h>#define LED_PIN     6
#define NUM_LEDS    50
#define BRIGHTNESS  64
#define LED_TYPE    WS2811
#define COLOR_ORDER GRB
CRGB leds[NUM_LEDS];#define UPDATES_PER_SECOND 100
/*This example shows several ways to set up and use 'palettes' of colors with FastLED.These compact palettes provide an easy way to re-colorize your animation on the fly, quickly, easily, and with low overhead.USING palettes is MUCH simpler in practice than in theory, so first just run this sketch, and watch the pretty lights as you then read through the code.  Although this sketch has eight (or more) different color schemes, the entire sketch compiles down to about 6.5K on AVR.FastLED provides a few pre-configured color palettes, and makes it extremely easy to make up your own color schemes with palettes.Some notes on the more abstract 'theory and practice' of FastLED compact palettes are at the bottom of this file.本示例展示了使用 FastLED 设置和使用 "调色板 "的几种方法。这些小巧的调色板提供了一种简便的方法，可以快速、轻松、低成本地为动画重新调色。调色板的使用在实践中比理论上要简单得多，所以首先运行这个草图，然后边阅读代码边欣赏漂亮的灯光。 虽然这个草图有八种（或更多）不同的配色方案，但整个草图在 AVR 上的编译长度约为 6.5K。FastLED 提供了一些预配置的调色板，让您可以非常容易地使用调色板制作自己的配色方案。关于 FastLED 紧凑型调色板更抽象的 "理论与实践 "的一些说明，见本文件底部。
*/CRGBPalette16 currentPalette;
TBlendType    currentBlending;extern CRGBPalette16 myRedWhiteBluePalette;
extern const TProgmemPalette16 myRedWhiteBluePalette_p PROGMEM;void setup() {delay( 3000 ); // power-up safety delayFastLED.addLeds<LED_TYPE, LED_PIN, COLOR_ORDER>(leds, NUM_LEDS).setCorrection( TypicalLEDStrip );FastLED.setBrightness(  BRIGHTNESS );currentPalette = RainbowColors_p;currentBlending = LINEARBLEND;
}void loop()
{// ChangePalettePeriodically();static uint8_t startIndex = 0;startIndex = startIndex + 1; /* motion speed */FillLEDsFromPaletteColors( startIndex);FastLED.show();FastLED.delay(1000 / UPDATES_PER_SECOND);
}void FillLEDsFromPaletteColors( uint8_t colorIndex)
{uint8_t brightness = 255;for( int i = 0; i < NUM_LEDS; ++i) {leds[i] = ColorFromPalette( currentPalette, colorIndex, brightness, currentBlending);colorIndex += 3;}
}/*
There are several different palettes of colors demonstrated here.FastLED provides several 'preset' palettes: RainbowColors_p, RainbowStripeColors_p,  OceanColors_p, CloudColors_p, LavaColors_p, ForestColors_p, and PartyColors_p.Additionally, you can manually define your own color palettes, or you can write code that creates color palettes on the fly.  All are shown here.这里展示了几种不同的调色板。FastLED 提供了几种 "预设 "调色板： RainbowColors_p、RainbowStripeColors_p、OceanColors_p、CloudColors_p、LavaColors_p、ForestColors_p 和 PartyColors_p。此外，你还可以手动定义自己的调色板，或者编写代码即时创建调色板。 此处显示了所有调色板。
*/
void ChangePalettePeriodically()
{uint8_t secondHand = (millis() / 1000) % 60;static uint8_t lastSecond = 99;if( lastSecond != secondHand) {lastSecond = secondHand;if( secondHand ==  0)  { currentPalette = RainbowColors_p;         currentBlending = LINEARBLEND; }if( secondHand == 10)  { currentPalette = RainbowStripeColors_p;   currentBlending = NOBLEND;  }if( secondHand == 15)  { currentPalette = RainbowStripeColors_p;   currentBlending = LINEARBLEND; }if( secondHand == 20)  { SetupPurpleAndGreenPalette();             currentBlending = LINEARBLEND; }if( secondHand == 25)  { SetupTotallyRandomPalette();              currentBlending = LINEARBLEND; }if( secondHand == 30)  { SetupBlackAndWhiteStripedPalette();       currentBlending = NOBLEND; }if( secondHand == 35)  { SetupBlackAndWhiteStripedPalette();       currentBlending = LINEARBLEND; }if( secondHand == 40)  { currentPalette = CloudColors_p;           currentBlending = LINEARBLEND; }if( secondHand == 45)  { currentPalette = PartyColors_p;           currentBlending = LINEARBLEND; }if( secondHand == 50)  { currentPalette = myRedWhiteBluePalette_p; currentBlending = NOBLEND;  }if( secondHand == 55)  { currentPalette = myRedWhiteBluePalette_p; currentBlending = LINEARBLEND; }}
}// This function fills the palette with totally random colors.
// 设置完全随机的调色板
void SetupTotallyRandomPalette()
{for( int i = 0; i < 16; ++i) {currentPalette[i] = CHSV( random8(), 255, random8());}
}
/*This function sets up a palette of black and white stripes, using code.  Since the palette is effectively an array of// sixteen CRGB colors, the various fill_* functions can be used to set them up.该函数使用代码设置黑白条纹调色板。 由于调色板实际上是一个由 16 种 CRGB 颜色组成的数组，因此可以使用各种 fill_* 函数来设置它们。*/
void SetupBlackAndWhiteStripedPalette()
{// 'black out' all 16 palette entries...fill_solid( currentPalette, 16, CRGB::Black);// and set every fourth one to white.currentPalette[0] = CRGB::White;currentPalette[4] = CRGB::White;currentPalette[8] = CRGB::White;currentPalette[12] = CRGB::White;}// This function sets up a palette of purple and green stripes.
void SetupPurpleAndGreenPalette()
{CRGB purple = CHSV( HUE_PURPLE, 255, 255);CRGB green  = CHSV( HUE_GREEN, 255, 255);CRGB black  = CRGB::Black;currentPalette = CRGBPalette16(green,  green,  black,  black,purple, purple, black,  black,green,  green,  black,  black,purple, purple, black,  black );
}/*
This example shows how to set up a static color palette which is stored in PROGMEM (flash), which is almost always more plentiful than RAM.  A static PROGMEM palette like this takes up 64 bytes of flash.
本示例展示了如何设置静态调色板，该调色板存储在 PROGMEM（闪存）中，闪存几乎总是比 RAM 更充足。 这样的静态 PROGMEM 调色板占用 64 字节的闪存。
*/
const TProgmemPalette16 myRedWhiteBluePalette_p PROGMEM =
{CRGB::Red,CRGB::Gray, // 'white' is too bright compared to red and blueCRGB::Blue,CRGB::Black,CRGB::Red,CRGB::Gray,CRGB::Blue,CRGB::Black,CRGB::Red,CRGB::Red,CRGB::Gray,CRGB::Gray,CRGB::Blue,CRGB::Blue,CRGB::Black,CRGB::Black
};

关于 FastLED 紧凑型调色板的补充说明：

通常，在计算机图形中，调色板（或 “颜色查找表”）有 256 个条目，每个条目包含一种特定的 24 位 RGB 颜色。 您可以使用简单的 8 位（一个字节）值对调色板进行索引。

256 个条目调色板需要占用 768 字节的 RAM，这在 Arduino 上可能是 "太多 "字节了。

FastLED 提供传统的 256 元素调色板，适用于能够承受 768 字节 RAM 成本的设备。

不过，FastLED 也提供了一种紧凑型替代方案。 FastLED 提供的调色板可存储 16 个不同的条目，但可在实际有 256 个条目的情况下进行访问。

在 16 个显式条目之间进行插值，在每对条目之间创建 15 个中间调色板条目。

因此，举例来说，如果将紧凑型调色板的前两个显式条目设置为绿色（0,255,0）和蓝色（0,0,255），然后从虚拟调色板（256 个条目）中检索前 16 个条目，就会得到绿色，然后是一个从绿色到蓝色的平滑渐变，最后是蓝色。