Pixels

A Pixel represents a single LED. Pixels are used to store color values until they can be sent to an output device.

Creating Pixels

Pixels don’t take any parameters. Pixels are automatically allocated and managed by Sections, so you shouldn’t have to initialize one yourself.

Pixel pixel();

Important

While you can work with Pixels directly, it’s much easier to manage them through a Section. Even if you only need a single Pixel, you should still create a 1x1 Section and use it to control the Pixel.

How Pixels Work

Each Pixel stores two key bits of information: its current_color_ and step_.

current_color_ is the color that the Pixel is set to right now. You can access this color using Pixel::get_color(), Section::get_pixel_color(x, y) or Maestro::get_pixel_color(section, x, y).

step_ is an array used to fade the Pixel to its new color. It stores the amount that each color channel will increment by when calling the Pixel’s update() method. For example, if the Pixel is currently black and you want to set it to white, step_ stores {255, 255, 255}. On update(), the value of step_ is applied to current_color_, changing it to white.

In order to support gradual color transitions (i.e. fading), the Pixel’s parent Section stores a step_count_. step_count_ tracks the number of iterations the Pixel must go through before it reaches its target color. For example, if the Pixel the Pixel is currently black, and you want it to fade to white over 5 frames, you can use:

section.set_step_count(5);
section.set_pixel_color(x, y, ColorPresets::White);

Now instead of storing {255, 255, 255} in step_, the Pixel stores {51, 51, 51}. Note that set_step_count() applies to all Pixels managed by the Section, and will automatically decrement on each update().

Tip

Setting step_count_ to 1 before using set_next_color() will force the color to change immediately. Otherwise, the color will fade.

// Change colors immediately
section.set_step_count(1);
section.set_pixel_color(x, y, ColorPresets::Black);

Calling a Pixel’s update() method triggers an immediate refresh of the Pixel. As long as the step_count_ is greater than 0, the Pixel will step towards its next color. update() is automatically called by the Pixel’s parent Section when it updates.

Performance Options

Disabling Fading

To save on RAM, you can disable fading by enabling the PIXEL_DISABLE_FADING preprocessor directive, which reduces each Pixel’s RAM use from 6 bytes to 3. In the Arduino IDE, add #define PIXEL_DISABLE_FADING to the top of your .ino file. In PlatformIO, add the following to your platformio.ini file:

[common]
build_flags = -D PIXEL_DISABLE_FADING

Enabling Accurate Fading

When fading is enabled, each Pixel calculates a step_ value, which is the difference between its current color and its next color. step_ is not 100% accurate, especially for small changes or long fade intervals.

To rectify this, each Pixel can store its target color in the next_color_ variable, then apply the color at the end of the fade period. This guarantees that the Pixel reaches its target color, but uses an additional 3 bytes of RAM. Accurate fading is disabled by default, but you can enable it by adding the PIXEL_ENABLE_ACCURATE_FADING preprocessor directive. In the Arduino IDE, add #define PIXEL_ENABLE_ACCURATE_FADING to the top of your .ino file. In PlatformIO, add the following to your platformio.ini file:

[common]
build_flags = -D PIXEL_ENABLE_ACCURATE_FADING

Note

Accurate fading requires fading to be enabled.