Glimmer (Seg Line) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info)

Description:

This effect fades a random group of pixels in and out between a color and the background, choosing different pixels for each fade. This is similar to the Twinkle series of effects, but use groups of pixels instead of fading them individually. The colors can be picked randomly from a palette, or be set to a single color.

The amount each pixel fades is randomized to between fadeMin and fadeMax (defaulted to 30 and 255), but all pixels fade together, so that their fades end at the same time. This helps produce a more varied, shimmery look, although the overall effect is quite subtle.

The effect is adapted for 2D use, with each "glimmer" being extended along segment lines. The effect can be made 1D using lineMode (see below).

Supports Color Modes for both the glimmer and background colors.

You can change most settings on the fly, with the exception to the number of fading pixels, numGlims, and the twoPixelSets setting, which must be changed via function calls.

Note that the effect creates one uint16_t array and two uint8_t arrays. These arrays are allocated dynamically, so, to avoid memory fragmentation, when you create the effect, you should set numGlims to the maximum value you expect to use. See Memory Management for more details. Note that when fading two sets of pixels (see below), the lengths of the arrays will be numGlims * 2; one length for each set of pixels.

Two Pixel Sets:

The effect can be set so that one or two sets of pixels are fading in/out at any one time. With one set, the pixels are faded in then out before choosing a new set, while with two sets, one set is faded in while the other is faded out.

This is controlled by the twoPixelSets setting:

true -- Two sets of pixels will be fading at once, with one set fading in while the other is fading out.
false -- Only one set of pixels will be faded at a time, with the set being fully faded in then out before a new set is picked.

Line Mode:

The lineMode (bool) setting controls if the glimmering pixels are draws in 2D along segment lines, or in 1D as individual pixels.

true (default) -- The effect will use whole segment lines for fading.
false -- The effect will use individual pixels for fading, which is useful for using multi-segment color modes, while still only glimmering individual pixels.

Example Calls:

GlimmerSL glimmer(mainSegments, 8, cybPnkPal_PS, 0, true, 10, 50);
/*  Will choose 8 pixels to cycle to/from colors from the cybPnkPal_PS palette
    with a blank background.
    Two sets of pixels will be faded in/out at one time, 
    going through 10 fade steps, with 50ms between each step. */

GlimmerSL glimmer(mainSegments, 10, CRGB::Blue, CRGB::Red, false, 20, 20, 150, 60);
/*  Will choose 10 pixels to to cycle to/from CRGB::Red to CRGB::Blue (red is the background).
    One set of pixels will be faded in then out before a new set is chosen.
    The range of the fades will be between 20 and 150, 
    with 20 fade steps, with 60ms between each step. */

Constructor Definitions:

//Constructor with palette, using default fade in and out values
GlimmerSL(SegmentSetPS &SegSet, uint16_t NumGlims, palettePS &Palette, CRGB BgColor, bool TwoPixelSets, 
          uint8_t FadeSteps, uint16_t Rate);

//Constructor with palette and setting maximum fade in and out values
GlimmerSL(SegmentSetPS &SegSet, uint16_t NumGlims, palettePS &Palette, CRGB BgColor, bool TwoPixelSets, 
          uint8_t FadeSteps, uint8_t FadeMin, uint8_t FadeMax, uint16_t Rate);

//Constructor with single color, using default fade in and out values
GlimmerSL(SegmentSetPS &SegSet, uint16_t NumGlims, CRGB Color, CRGB BgColor, bool TwoPixelSets, 
          uint8_t FadeSteps, uint16_t Rate);

//Constructor with single color and setting maximum fade in and out values
GlimmerSL(SegmentSetPS &SegSet, uint16_t NumGlims, CRGB Color, CRGB BgColor, bool TwoPixelSets,
          uint8_t FadeSteps, uint8_t FadeMin, uint8_t FadeMax, uint16_t Rate);

Constructor Inputs:

SegmentSetPS* segSet -- The Segment Set the effect will draw on. See common vars segSet entry for more details.
uint16_t numGlims -- The number of random pixels chosen for fading for each cycle, can be set later using setNumGlims().
palettePS* palette (optional, see constructors) -- The set of colors the effect will use. The colors of the fading pixels will be picked randomly from the palette, changing after each fade. See palettes. It is a pointer. See common vars palette entry for more details.
CRGB Color (optional, see constructors) -- A single color the pixels will be faded towards. The color will be placed into the effect's local palette, paletteTemp for use.
CRGB* bgColor -- The color used for background pixels. Is a pointer, allowing you to bind it to an external color. By default it's bound the effect's local, bgColorOrig color. See common vars bgColor entry for more details.
bool twoPixelSets -- Controls if one or two sets of pixels will be fading in/out at once (see notes in Intro), can be set later using setTwoSets().
uint8_t fadeMin (optional, max 255, default 30) -- The minimum amount that a pixel will fade by. Higher means that pixels will be faded further to the glimmer colors.
uint8_t fadeMax (optional, max 255, default 255) -- The maximum amount that a pixel will fade by. Higher means that pixels will be faded further to the glimmer colors.
uint8_t fadeSteps -- The number of steps to fade a pixel (one step every update cycle).
uint16_t* rate -- Update rate (ms). Is a pointer, allowing you to bind it to an external variable. By default it's bound the effect's local variable, rateOrig. See common vars rate entry for more.

Other Settings:

uint8_t colorMode (default 0) -- The colorMode used for the glimmering pixels, also see common vars colorMode entry for more details.
uint8_t bgColorMode (default 0) -- The colorMode used for the background pixels, also see common vars colorMode entry for more details.
bool lineMode (default true) -- If true, glimmers will be drawn along segment lines (2D), if false, glimmers will be drawn on individual pixels (1D), (see notes in Intro).
bool fillBg (default false) -- If true, then all pixels will be re-colored with each update(), rather than just drawing those that have changed. See common vars fillBg entry for more details.
bool showNow (default true) -- Controls if the effect "draws" during each update cycle by calling FastLED.show(). Common to all effects. See common vars showNow entry for more details.

Class Functions:

```
void setNumGlims( uint16_t newNumGlims );
```
Changes the number of pixels fading, will reset the effect if the new number is different from the current.
```
void setTwoSets( bool newSetting );
```
Changes the twoPixelSets setting (see intro notes), if different, it will reset the effect.
```
void reset(); 
```
Resets the effect, restarting it. Fills in the background to clear any existing glimmering pixels.
```
void update();
```
Updates the effect.

Reference Vars:

uint8_t step -- Tracks the fade step we're on, max value is fadeSteps, is reset once a fade is finished.
bool twoPixelSets -- See notes in Intro, set using setTwoSets().
uint16_t numGlims -- The number of glimmering pixels, set using setNumGlims().

Flags:

bool fadeIn -- Is true when the glimmering pixels are fading in, false when they are fading out. Not useful when fading two sets because it is toggled mid-update.