Segment Waves Fast (Seg) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info)

Similar to Segment Waves (Seg), but runs faster with some restrictions.

Moves a set of color waves across whole segments over time. 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 wave lengths and spaces between each wave. There is also a constructor for using a single wave color only.

This effect is adapted for 2D use. The wave colors will be drawn and move along whole segments. For a version of this effect for segment lines, see Streamer Fast (Seg Line).

To make the effect "fast", it only ever calculates the color of the first segment, then for each subsequent segment, 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 waves do not blend as the shift across the segments.
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 waves 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 Segment Waves (Seg), 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 waves, 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 (see constructor notes below). I have also included a shortcut for making a single wave (a wave of length 1, with only one wave active on the segment set a once) that sets the spacing automatically. All the pattern colors will still be used. You can trigger this with any of the constructors with a waveThickness input, just pass in 0, and a single wave pattern will be built for you.

Note that while each entry in the pattern is a uint8_t, if you have a lot of colors, with long waves 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 wave length and spacing to the maximum values you expect to use, and then call setPatternAsPattern() or setPaletteAsPattern() to resize your waves 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 (waveLength + 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 segment, and are then shifted across the segments.

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)};

SegWavesFast segWavesFast(mainSegments, pattern, cybPnkPal_PS, 0, true, 120);
/*  Will do a set of waves using pattern above, with colors from the cybPnkPal_PS palette.
    The background is blank (0).
    The waves will begin with 1 pixel of color 0, with three spaces after, 
    followed by 2 pixels of color 1, followed by 2 spaces
    The waves will move from the last segment to the first
    The waves will update at a 120ms rate */

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

SegWavesFast segWavesFast(mainSegments, pattern, cybPnkPal_PS, 0, 3, 4, false, 120);
/*  Will do a wave using the first three colors of the cybPnkPal_PS palette 
    (following the pattern)
    The background is blank (0).
    Each wave will be length 3, followed by 4 spaces.
    The waves will move from the first to last segment.
    The effect updates at a rate of 120ms */

SegWavesFast segWavesFast(mainSegments, cybPnkPal_PS, CRGB::Red, 0, 0, true, 120);
/*  Will do a waves using all the colors in the cybPnkPal_PS palette,
    because the passed in waveThickness is 0, the effect will be configured as to create a pattern of single waves
    (wave thickness of 1, with spacing such that there's only one wave on the segment sets at one time)
    (the 0 spacing input will be ignored)
    The background is red.
    The waves will move from the last segment to the first
    The waves will update at a 120ms rate */

SegWavesFast segWavesFast(mainSegments, CRGB::Blue, CRGB::Red, 2, 3, true, 140);
/*  Will do a blue waves with length 2 and 3 spaces in between
    The background is red.
    The waves will move from the last segment to the first
    The effect updates at a rate of 140ms */

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

//Constructor for building the wave pattern from the passed in pattern and the palette,
//using the passed in waveThickness and spacing
SegWavesFast(SegmentSetPS &SegSet, patternPS &Pattern, palettePS &Palette, CRGB BgColor, uint16_t WaveThickness, 
             uint16_t Spacing, bool Direct, uint16_t Rate);

//Constructor for building a wave using all the colors in the passed in palette, 
//using the waveThickness and spacing for each color
SegWavesFast(SegmentSetPS &SegSet, palettePS &Palette, CRGB BgColor, uint16_t WaveThickness, uint16_t Spacing, 
             bool Direct, uint16_t Rate);

//Constructor for doing a single colored wave, using waveThickness and spacing
SegWavesFast(SegmentSetPS &SegSet, CRGB Color, CRGB BgColor, uint16_t WaveThickness, uint16_t Spacing,
             bool Direct, 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 a single color wave. The color will be placed into the effect's local palette, paletteTemp for use. A pattern will be created for the waves 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 waveThickness (optional, see constructors) -- The length of a wave. Used for automated pattern creation. Passing 0 will create a pattern of single length waves (see Inputs Guide above).

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

• bool direct -- The direction the waves move. If true, the waves will move from the last to first segment, if false, the reverse.

• 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 waves 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 makeSingleWave(); 

  Creates a wave pattern such that there's a single wave of length 1 active on the segment set at one time. All the pattern colors will still be used.

• void reset();

  Restarts the effect from its initial state.

• void resetSegColors(); 

  Only needs to be called if you change the number of segments in your segment set. Re-creates the segColors array, which used for the random modes.

• 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 waves, which happens during the first update cycle. Set true once the first update cycle has been finished.