Streamer (Seg Line) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info)

Moves a set of colored "streamers" along a segment set, similar to Theater Chase, but with more options. The colors transition smoothly by blending, like a set of waves. The effect uses a pattern for colors. You can either input a custom pattern, or the effect can build one for you with a set color streamer lengths and spaces between each streamer.

This effect is adapted for 2D use. The streamer colors will be repeated down segment lines. For a version of this effect for whole segments, see Segment Waves (Seg).

Because blending can take quite a bit of processing power, especially for longer segment sets, you can disable it using the fadeOn setting. If fadeOn is false, the streamers will transition in one step, greatly simplifying the effect at the cost of some smoothness. There is also a "fast" version of this effect, Streamer Fast (Seg Line), which requires less processing power to run, but has a few extra restrictions.

This effect supports color modes for both the streamer and background colors.

Note that if you ever adjust your the effect's segment set during runtime, you must call reset() to prevent crashing.

Patterns work the same as with other effects; they are a pattern of palette array indexes. ie a pattern of {0, 2, 1} would be the first three colors of a palette. However, in this effect, to indicate a background pixel (set it to the bgColor) we use 255 in the pattern. Make sure your palette doesn't have 255 colors (that would be waaaay to big!).

For example, lets say we wanted to do the first two colors of our palette, each as length 4 streamers, with 3 background pixels in between each. We would make a pattern as: {0, 0, 0, 0, 255, 255, 255, 1, 1, 1, 1, 255, 255, 255}.

For simple patterns like the previous example, I have written a few constructors that automate the pattern creation for you, taking the length of the colored streamers, and the length of the background spaces as arguments (see constructor notes below).

Note that while each entry in the pattern is a uint8_t, if you have a lot of colors, with long streamers and spaces, your patterns may be quite large, so watch your memory usage.

Any automatically generated patterns will be allocated dynamically. To avoid memory fragmentation, when you create the effect, you should set your color length and spacing to the maximum values you expect to use, and then call setPatternAsPattern() or setPaletteAsPattern() to resize your streamers and spacing. See Memory Management for more details.

Also, remember that the pattern length is limited to 65,025 (uint16_t max), so make sure your (colorLength + spacing) * <num palette colors> is less than the limit.

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

StreamerSL streamer(mainSegments, pattern, cybPnkPal_PS, 0, 30, 20);
/*  Will do a set of streamers using the first two colors from the cybPnkPal_PS palette, following the pattern above
    The streamer will begin with 1 pixel of color 0, with three spaces after, 
    followed by 2 pixels of color 1, followed by 2 spaces.
    The background is blank (0).
    The streamers will blend using 30 steps, with 20ms between each step. */

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

StreamerSL streamer(mainSegments, pattern, cybPnkPal_PS, 0, 3, 4, 0, 120);
/*  Will do streamers using the first three colors from the cybPnkPal_PS palette, following the pattern above.
    The background is blank (0).
    Each streamer will be length 3, followed by 4 spaces.
    The fade steps are set to zero, so there is no blending (fadeOn will be set false).
    The effect updates at a rate of 120ms. */

StreamerSL streamer(mainSegments, cybPnkPal_PS, CRGB::Red, 3, 4, 10, 40);
/*  Will do streamers using all the colors in cybPnkPal_PS.
    The background is red.
    ach streamer will be length 3, with 4 spaces in between.
    The streamers will blend using 10 steps, with 40ms between each step. */

StreamerSL streamer(mainSegments, CRGB::Blue, CRGB::Red, 2, 2, 0, 140);
/*  Will do blue streamers with length 2 and 2 spaces in between
    The background is red
    The fade steps are set to zero, so there is no blending (fadeOn will be set false).
    The effect updates at a rate of 140ms. */

//Constructor for using a passed in pattern and palette for the streamers
StreamerSL(SegmentSetPS &SegSet, patternPS &Pattern, palettePS &Palette, CRGB BgColor, 
           uint8_t FadeSteps, uint16_t Rate);  

//Constructor for building the streamer pattern from the passed in pattern and the palette, using the passed in colorLength and spacing
StreamerSL(SegmentSetPS &SegSet, patternPS &Pattern, palettePS &Palette, CRGB BgColor, uint16_t ColorLength, 
           uint16_t Spacing, uint8_t FadeSteps, uint16_t Rate);
        
//Constructor for building a streamer using all the colors in the passed in palette, using the colorLength and spacing for each color
StreamerSL(SegmentSetPS &SegSet, palettePS &Palette, CRGB BgColor, uint16_t ColorLength, uint16_t Spacing, 
           uint8_t FadeSteps, uint16_t Rate);

//Constructor for doing a single colored streamer, using colorLength and spacing
StreamerSL(SegmentSetPS &SegSet, CRGB Color, CRGB BgColor, uint16_t ColorLength, uint16_t Spacing, 
           uint8_t FadeSteps, uint16_t Rate);

• 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 Pattern notes in Inputs Guide). Also see patterns. It is a pointer. See common vars pattern entry for more details. If the pattern is created automatically, the effect will use its local pattern variable, patternTemp.

• CRGB color (optional, see constructors) -- Used for making single color streamers. The color will be placed into the effect's local palette, paletteTemp for use. A pattern will be created for the streamer using the effect's local pattern variable, patternTemp.

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

• uint16_t colorLength (optional, see constructors) -- The length of each streamer. Used for automated pattern creation (see Inputs Guide above).

• uint16_t spacing (optional, see constructors) -- The number of pixels between each streamer (will be set to bgColor). Used for automated pattern creation.

• uint8_t fadeSteps -- The number of steps to blend from one streamer color to the next. Passing 0 or 1 will set fadeOn to false (no fading) (see Other Settings below).

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

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

• bool fadeOn (default true) -- If false, streamers will use a single blend step, jumping directly from one color to the next. This requires less processing power, but isn't as smooth. Note that if 1 or 0 are passed as fadeSteps in a constructor, fadeOn will be set to false automatically. If you switch during run time, adjust your update rate to fadeSteps * <your current rate> for smoothness.

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

• void setPatternAsPattern( patternPS &inputPattern, uint16_t colorLength, uint16_t spacing );

  Takes an input pattern and creates a color pattern with streamers of colorLength length and spacing background spaces in-between. A short-hand for turning a short pattern into a full pattern for the effect. See Common Functions for more.

• void setPaletteAsPattern( uint16_t colorLength, uint16_t spacing );

  Like the previous function, but all of the current palette colors will be used for the pattern.

• void reset();

  Restarts the effect from its initial state. If you change your segment set's number of lines or segments you must call this.

• void update();

  Updates the effect.

• uint16_t cycleNum -- Tracks how many patterns we've gone through, resets every pattern length number of cycles (ie once we've gone through the whole pattern).