Streamer Fast (Seg Line) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info)

Similar to Streamer (Seg Line), but runs faster with some restrictions.

Moves a set of colored "streamers" along the segment set. 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 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 Fast (Seg).

To make the effect "fast", it only ever calculates the color of the first pixel, then for each subsequent pixel, it copies the color of the next segment in line. This means it's only doing one color calculation per update, the rest is just copying what's already there.

However, this does lead to the following restrictions:

1. The streamers do not blend as the shift across the segment set.
2. Changing the palette on the fly will have a delayed effect on the colors. The existing colors will shift off the segments as new ones shift on. This prevents this effect from playing well with most Palette Utility Classes.
3. The same restrictions as (2) apply to changing the pattern and most other effect settings.
4. Changing the direction of the effect may break it temporarily.
5. This effect is not compatible with Color Modes for either the streamers or the background.
6. The effect should not be run alongside other effects on the same Segment Set due to it copying colors from LEDs.
7. This effect does not play well with the Effect Set Fader utility.

Otherwise, the effect works the same as Streamer (Seg Line), and most of the inputs are identical.

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.

randMode controls how pattern colors are chosen. For randMode's other than 0, colors are chosen at random as they enter the first pixel, and are then shifted across the segment set.

randMode (default 0) (uint8_t):

• 0 -- Colors will be chosen in order from the pattern (not random).
• 1 -- Colors will be chosen completely at random.
• 2 -- Colors will be chosen at random from the pattern, but the same color won't be repeated in a row. (won't pick spaces).
• 3 -- Colors will be chosen randomly from the pattern (allowing repeats). (won't pick spaces).

uint8_t pattern_arr = {0, 255, 255, 255, 1, 1, 255, 255};
patternPS pattern = {pattern_arr, SIZE(pattern_arr), SIZE(pattern_arr)};
    
StreamerPS streamerFast(mainSegments, pattern, cybPnkPal_PS, 0, 120);
/*  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 effect updates at a rate of 120ms */

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

StreamerPS streamerFast(mainSegments, pattern, cybPnkPal_PS, 0, 3, 4, 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 effect updates at a rate of 120ms */

StreamerPS streamerFast(mainSegments, cybPnkPal_PS, CRGB::Red, 3, 4, 120);
/*  Will do streamers using all the colors in cybPnkPal_PS.
    The background is red.
    each streamer will be length 3, with 4 spaces in between.
    The streamers will update at a 120ms rate */

StreamerPS streamerFast(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 effect updates at a rate of 140ms. */

//Constructor for using the passed in pattern and palette for the streamer
StreamerFastSL(SegmentSetPS &SegSet, patternPS &Pattern, palettePS &Palette, CRGB BgColor, uint16_t Rate);

//Constructor for building the streamer pattern from the passed in pattern and the palette, using the passed in colorLength and spacing
StreamerFastSL(SegmentSetPS &SegSet, patternPS &Pattern, palettePS &Palette, CRGB BgColor, uint16_t ColorLength, 
               uint16_t Spacing, 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
StreamerFastSL(SegmentSetPS &SegSet, palettePS &Palette, CRGB BgColor, uint16_t ColorLength, 
               uint16_t Spacing, uint16_t Rate);

//Constructor for doing a single colored streamer, using colorLength and spacing
StreamerFastSL(SegmentSetPS &SegSet, CRGB Color, CRGB BgColor, uint16_t ColorLength,
               uint16_t Spacing, 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 streamers 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.

• 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 randMode (default 0) -- (See randMode notes in Input's Guide above).

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

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

• bool initFillDone -- Indicates if the strip has been pre-filled with the effect's streamers, which happens during the first update cycle. Set true once the first update cycle has been finished.