Pattern Shifter (Seg Line) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info and here for the Shift Pattern used)

You must understand shift patterns to use this effect! This effect is really only useful for segment set with multiple segments (2D).

An effect that moves a shift pattern along segment lines, from one segment line to another. Shift patterns are manually created, and are used to draw more complex patterns like arrows, text?, flags, etc. Also see Pattern Shifter (Seg) for an alternate, orthogonal, version of this effect.

This effect moves a shift pattern from one segment line to another, wrapping at the last segment line. Ie if you had a pattern where and single segment line was lit up, it would be shifted from one segment line to the next as the effect runs. (This doesn't change the pattern, all the movement is local to the effect). For this effect, patterns can be longer (have more segment lines) than the segment set. The pattern will cycle across the segments lines as the effect runs. However, your pattern "rows" must be the same length as the number of segments in the segment set, ie for a set with 5 segments, your pattern "rows" should be length 5, anything extra will not be drawn.

For example, if I have an 4x4 matrix, arranged into 4 segment rows, and use the following pattern:

uint16_t basicPattern_arr[(6 + 2) * 3] = { //<--(<<how long each "row"is>>) * <<number of rows>>
    0, 2,    0, 255, 0, 255, 0, 0
    2, 5,   255, 0, 255, 0,  0, 0
    5, 6,    0,  0,  0,  0,  0, 0 // <-- This row will be drawn even though we only have 4 segment lines, 
//                                        it will cycle on as the pattern moves across the segment lines.
//                          [-^^-]   <-- These columns will NOT be drawn because our segment set only has 4 segments.
};

The above pattern uses 5 segment lines (note the line start/end points for each "row"), and is 6 segments long (the length of each pattern row). Although our matrix only has 4 segment lines (columns), the 5 line pattern will be drawn as the pattern is shifted across the segment lines. However, the extra 2 end entries in each pattern row will not be drawn because our matrix only has 4 rows, and the pattern is NOT shifted along the segments.

Patterns will be colored using the effect's palette. The background color will be draw on any pattern indexes with the value 255.

Warning, while you can change the color values of a pattern during runtime, you should avoid changing the row/column dimensions. You can change the pattern using the setShiftPattern() function.

Supports Color Modes for both the main and background colors.

The shift pattern can be set to repeat, which will draw the pattern as many times as possible along the segment set, so that the pattern seamlessly loops.

EX, for a segment set with 10 lines:

• If you repeat along segment lines, a pattern that is 5 lines long will be draw twice (10/5) (offset so the patterns don't overlap).

You can change the repeating using the setRepeat( bool newRepeat ) function.

Note that the effect has a segSet pointer like other effects, but the effect doesn't take a segment set as an input. Instead it gets its segSet from the shift pattern (see shift patterns for more detail). In other words, the effect's segSet pointer is bound to the shift pattern's segSet pointer. (Usually a shift pattern is intended to work with a specific segment set, so it made sense to include the segment set in the pattern itself). This info is only relevant if you plan on changing the segment set. If you do so, you should change the shift pattern's segSet rather than the effect's.

/*  Note that I cannot provide a universal shift pattern for all segment sets.
    See the Shift Pattern wiki page for how to create one.

    A super basic pattern for a segment set with a single segment (one strip)
    This pattern is just two dots separated by a space. */

uint16_t patternSegs = mainSegments.numSegs;

uint16_t basicPattern_arr[(1 + 2) * 3] = { <--(<<how long each "row" is>>) * <<number of rows>>
    0, 1,   0,   //segment line 0, dot 1
    1, 2,   255, //segment line 1, space
    2, 3,   0,   //segment line 2, dot 2
};
shiftPatternPS basicPattern(mainSegments, patternSegs, basicPattern_arr, SIZE(basicPattern_arr));

PatternShifterSL patternShifterSL(basicPattern, cybPnkPal_PS, 0, false, 100);
/*  Will shift the "basicPattern" across its segment set using colors from the cybPnkPal_PS palette
    The background is blank
    The pattern is not repeated
    The effect updates at 100ms */

PatternShifterSL(shiftPatternPS &ShiftPattern, palettePS &Palette, CRGB BgColor, bool Repeat, uint16_t Rate);

• shiftPatternPS* shiftPattern -- The input shift pattern. You can change the shift pattern later using setShiftPattern().

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

• 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 repeat -- Sets if the pattern "rows" are to be repeated along the segment lines.

• 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 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 setShiftPattern( shiftPatternPS *newShiftPattern ); 

  Sets the effect's shift pattern.

• void setRepeat( bool newRepeat ); 

  Sets if the shift pattern will be repeated along the segment set lines.

• void reset();

  Restarts the effect from its initial state.

• void update();

  Updates the effect.

• uint16_t cycleNum -- How many times the pattern has be shifted, resets every time the pattern has been cycled across the whole segment set.

• bool repeat -- (see constructor inputs above), set using setRepeat().

• shiftPatternPS* shiftPattern (sorta) -- While you can change the values of a pattern, you should avoid changing the row/column dimensions. Use setShiftPattern() to change to a new pattern.