Color Wipe (Seg) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info)

Description:

An effect that colors one segment pixel in after another until all segments in a set are colored. This effect is similar to Color Wipe (Seg Line or Seg), but instead of wiping whole lines or segments, it wipes each pixel of each segment in order. ie for a set with five segments, the first would be wiped one pixel at a time, then the second segment, etc.

Wipes have a direction, either starting from the first or last segment pixel. This can be set to alternate with each wipe. Likewise, you can set the wipe to start at either the first or last segment.

The effect uses a pattern and palette for colors and various styles to display them:

`style`'s (uint8_t):

0 -- The colors alternate with each segment. Ie if you have 4 segments, each will be a different color from the pattern.
1 -- The colors alternates with each segment pixel.
2 -- The colors alternate with each segment line.

Note that the colors are set based on the number of segments and pixel's wiped, not by using the segment and pixel numbers directly. This prevents wipes from being the same for different wipe directions.

The effect is compatible with colorModes. They will override the style setting.

Once all the wipes are finished, the "done" flag will be set, and the effect is is over until it is reset, or the effect can be set to loop, automatically resetting, see below for more info.

The effect's background color is default to blank (0). You can change this by setting bgColorOrig.

You can adjust most of the effect variables on the fly, but changing the segWipeDir will only take effect once a wipe loops.

Inputs Guide and Notes:

Looping:

To keep wiping continuously, you can set the wipes to loop, which will automatically reset the effect repeatedly. The number of full wipes completed is stored in loopCount.

There are a various of options for configuring how the wipe loops, allowing you to change the wipe direction, wipe a background color, etc when looping. You can configure these options all at once using setUpLoop(), or you can set them individually.

The loop options give you a lot of flexibility in creating different effects, I encourage you to play with them! If you can't setup exactly what you want, you can always create multiple ColorWipes, and invoke them manually, swapping/resetting them out as they are "done".

The Loop Options:

bool looped -- Sets if the wipes loop or not. Looping wipes automatically restart every time a wipe is finished. The other variables are only relevant if the wipe is looping, because they modify subsequent loops.
bool bgLoop -- If true, then the background color (default 0) will be used as the color wipe every other loop. Ie, we wipe a color and then wipe off, looping.
bool shiftPatLoop -- If true, the pattern will be shifted by 1 with every loop, changing the colors of each segment / line with each wipe (this is done with an offset, it does not change the existing pattern)
bool patShiftDir -- Sets the direction the pattern shifts in, forwards (true) or backwards (false).
bool altWipeDirLoop -- If true, then the wipe direction will be flipped every loop (note that this modifies the original startingDirect value)
bool bgAltLoop -- Only used if altWipeDirLoop is true.
- If true, the the wipe direction will only swap on colored wipes, not on background ones.
- Ie colored wipe->background wipe->(wipe direction flips)->colored wipe->background wipe->(flip)->etc.
- If false, then the wipe direction will flip every loop.
- Ie colored wipe->(wipe direction flips)->background wipe->(wipe direction flips)->colored wipe->etc.
bool altSegWipeDirLoop -- If true, then the segment set direction will be flipped every loop. This is different than flipping the wipe direction, since it makes the first wipe start at the opposite end of the segment set, rather than having the wipe just move in the opposite direction.

Example Calls:

ColorWipeSeg colorWipeSeg(mainSegments, cybPnkPal_PS, 0, false, false, true, 60);
/* Will do a color wipe along the set's segments using colors from the cybPnkPal_PS palette
  (A pattern will be generated to match the palette)
  The style is 0, each segment will alternate colors according to the pattern.
  Alternate is false, so the wipes will all wipe in the same direction.
  The wipe direction is false, while the segWipeDir is true so wipes will go from the first to last segment, 
  starting at the end of each segment
  The effect updates at 60ms 
  Hint: try colorWipeSeg.setUpLoop(true, false, true, false, false, false, false),
        to continuously wipe the segments in new colors.*/

uint8_t pattern_arr = {0, 2, 1};
patternPS pattern = {pattern_arr, SIZE(pattern_arr), SIZE(pattern_arr)};

ColorWipeSeg colorWipeSeg(mainSegments, cybPnkPal_PS, pattern, 1, true, true, true, 60);
/* Will do a color wipe along the set's segments,
   using colors from cybPnkPal_PS palette, according to pattern.
   The style is 1, each segment pixel will alternate colors according to the pattern.
   Alternate is true, so the wipes will alternate wipe directions for each segment.
   Both the wipe direction and segWipeDir are true.
   So wipes will go from the first to last segment, with the first wipe starting at the end the first segment
   and then alternating starting points after that.
   The effect updates at 60ms */

ColorWipeSeg colorWipeSeg(mainSegments, CRGB(CRGB::Red), 2, false, false, false, 60);
/* Will do a color wipe along the set's segments using CRGB::Red as the only color.
   The style is 2, each segment line will alternate colors according to the pattern.
   (although this doesn't matter since the color is just red)
   Alternate is false, so the wipes will all wipe in the same direction.
   Both the wipe direction and segWipeDir are false.
   So wipes will go from the last to first segment, starting at the end of each segment
   The effect updates at 60ms */

Constructor Definitions:

//Constructor using pattern and palette
ColorWipeSeg(SegmentSetPS &SegSet, palettePS &Palette, patternPS &Pattern, uint8_t Style, bool Alternate, 
             bool WipeDirect, bool SegWipeDir, uint16_t Rate);

//Constructor using palette alone
ColorWipeSeg(SegmentSetPS &SegSet, palettePS &Palette, uint8_t Style, bool Alternate, bool WipeDirect, 
             bool SegWipeDir, uint16_t Rate);

//Constructor for a single color wipe
ColorWipeSeg(SegmentSetPS &SegSet, CRGB WipeColor, uint8_t Style, bool Alternate, bool WipeDirect, 
             bool SegWipeDir, uint16_t Rate);

Constructor Inputs:

SegmentSetPS* segSet -- The Segment Set the effect will draw on. See common vars segSet entry for more details.
palettePS* palette (optional, see constructors) -- The set of colors the effect will use. See palettes. It is a pointer. See common vars palette entry for more details.
patternPS* pattern (optional, see constructors) -- The color pattern the effect will use. See patterns. It is a pointer. See common vars pattern entry for more details.
CRGB color (optional, see constructors) -- A single color for all the wipes. The color will be placed in the effect's local palette, paletteTemp. The local pattern, patternTemp, will be set to match the palette (ie a single entry for the single color).
uint8_t style -- How the colors are displayed for the wipe(s) (see notes in intro above).
bool alternate -- If true, wipes will alternate directions (ie if one wipe is going forward, the next will reverse).
bool wipeDirect -- The direction of the first wipe, true is forward.
bool segWipeDir -- The order the segments are wiped in, true is first to last.
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 use for the effect, 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.
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 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.
For loop settings see Loop Options in intro.

Class Functions:

```
void setPaletteAsPattern();
```
Sets the effect pattern to match the current effect palette. See Common Functions for more.

void setUpLoop(looped, bgLoop, shiftPatLoop, patShiftDir, altWipeDirLoop, bgAltLoop, altSegWipeDirLoop)

A quick way of setting all the loop variables (see intro for notes on loops).

```
void reset();
```
Resets the effect vars, restarting the wipes.
```
void resetLoop();
```
Resets the current loop, will switch to the next loop, only relevant when looping (you shouldn't need to call this).
```
void update();
```
Updates the effect.

Reference Vars:

uint16_t loopCount -- How many full wipe cycles we've done, ie how many cycles where we've wiped all the segments, useful for tracking wipes when looping
uint16_t pixelCount -- How many pixels have been wiped so far (resets when looped).
uint16_t segWipeCount -- How many segments have been wiped so far (resets when looped).
uint16_t patOffset -- The current offset of the pattern. Used to shift the pattern colors. Only used when looping.

Flags:

bool done -- Set true when the wipe cycle is finished. Not set if we're looping.