Dissolve (Seg Line) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info)

Morphs the segment set from one color to the next by setting each segment line at random, one at a time. Colors can be chosen using a palette and pattern, or selected randomly. Includes various options for color selection (see modes below). You can also automatically insert a background color (default black) between each dissolve, or at the end of a color pattern.

Once a dissolve is finished, the effect can be set to pause for a period using the pauseTime setting.

The effect is adapted to work on segment lines for 2D use. (see Inputs Guide below).

You can use colorModes, but they don't make much sense unless you are shifting the gradient, or using colorModes 5 or 6.

!!Warning, this effect uses dynamic memory allocation to store a bool for each LED in your Segment Set, so be aware of your memory usage.

The effect is adapted to work on segment lines for 2D use, controlled via the lineMode setting.

lineMode's (bool):

• true (default): Whole segment lines will be dissolved, rather than each pixel.
• false: Individual pixels will be dissolved (only really useful when using certain color modes).

lineMode is set using setLineMode().

The effect can be accelerated to set more lines/pixels at once by adjusting spawnRateInc. By default we start by spawning one segment line at a time, increasing the number every spawnRateInc ms, so the spawning steadily accelerates. This helps keep the spawning consistent, since we're picking repeatedly at random. Setting spawnRateInc close-ish (up to double?) to the update rate looks the best.

Once a certain threshold has been met, setAllThreshold (default of 1/10 of the number of lines in the segment set remaining), all the remaining lines are set. This prevents us from getting stuck looking for the last line. This may sound weird, but in practice it looks quite good.

Note, I know it would be better to remove the chance of picking a line that's already dissolved, but that would require more memory to track the dissolved lines' locations (an array of uint16_t's vs an array of bools). Since the current effect seems to work, albeit with a bit of manual tweaking, I see no reason to change it.

You can increase the starting number of lines set at once (maxNumSpawnBase), which will accelerate the dissolving, and may be good on longer segment sets.

Using the bgMode setting, you can configure the effect to dissolve to a "blank" color, either between every colored dissolve, or at the end of a full pattern of colors.

The blank color is default to black, but can be set using via the effects *bgColor pointer, or bgColorOrig (the default target of the bgColor pointer).

The modes work by inserting "blanks" into the effect's dissolve color pattern; they are indicated by a value of 255. You can also use the blank marker in your own patterns (as opposed to those generated automatically by the effect, see constructors below).

For example, a pattern of { 0, 1, 2, 255, 3 } would dissolve through palette colors 0, 1, 2, then a blank, and then to color 3 before repeating.

bgMode's (uint8_t):

• 0: No blanks (ex: {0, 1, 2, 3, 4}, where the values are palette indexes).
• 1: One blank added to the end of the pattern (ex: {0, 1, 2, 3, 4, 255}).
• 2: A blank is added after each color (ex: {0, 255, 1, 255, 2, 255, 3, 255, 4, 255}).

You can change the bgMode using the setBgMode() function. Note that this will rewrite the effect's local color pattern (patternTemp) and tell the effect to use it. Changing the bgMode while the effect is running may have weird effects. You can call resetPixelArray() to reset the effect.

You can opt to have the dissolve colors chosen at random in various combinations using the randMode setting. Note that there is some interplay between randMode and bgMode which you should be aware of (see "Background and Random Color Behavior" below).

randMode's (uint8_t):

• 0: Each dissolve is a solid color following the pattern (not random).
• 1: Each dissolve is a set of randomly chosen colors (dif color for each pixel).
• 2: Each dissolve is a set of random colors chosen from the pattern (dif color for each pixel).
• 3: Each dissolve is a solid color chosen at random.
• 4: Each dissolve is a solid color chosen randomly from the pattern.
• 5: Each dissolve is a solid color chosen randomly from the pattern, but a "blank" dissolve is done between each color (see "Inserting Background Dissolves" below). By default, the same dissolve color won't repeat after a blank, but you can allow repeats by setting randMode5AllowRepeats to true (making the colors chosen at random). Note that bgMode should be set to 0 for this mode.

You should be able switch freely between randMode's on the fly (the random modes will set up a random palette/pattern as a fallback).

There is some interplay between the random and background modes, as both modify what colors are shown when. The background behavior for each random mode is listed below.

For randMode:

• 0: The background mode works as described above.

• 1: The background mode is ignored. There will be no blank dissolves.

• 2: The blank color can be chosen from the pattern, but the effect will not cycle to fully blank. (Note the more blanks in your pattern, the more likely a pixel will be dissolve to blank. So be careful when using randMode 2 and bgMode 2).

• 3: The background mode works as described above, however, for bgMode 1, the number of dissolves before the blank is set by randMode3CycleLen. Ie, if randMode3CycleLen is 3, then the effect will dissolve through 3 random colors before the blank color. randMode3CycleLen is defaulted to the input pattern length, or can specified in some constructors.

• 4: Each dissolve is a random color from the pattern, with the blank color being a possible choice.

• 5: The background mode is ignored. A blank dissolve always happens between random colors.

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

DissolveSL dissolve(mainSegments, pattern, cybPnkPal_PS, 0, 150, 70);
/* Will dissolve colors from the cybPnkPal_PS palette, following the pattern above using randMode 0 (see above) 
   with the number of lines set on one cycle increasing every 150ms with the effect updating every 70ms. */

DissolveSL dissolve(mainSegments, cybPnkPal_PS, 0, 2, 100, 100);
/* Will dissolve colors using from the cybPnkPal_PS palette in order, 
   using randMode 0 (not random) and bgMode 2 (see Inputs Guide above), so there will be a blank dissolve between colors. 
   The number of lines set on one cycle increases every 100ms with the effect updating every 100ms. */

DissolveSL dissolve(mainSegments, cybPnkPal_PS, 4, 0, 100, 100);
/* Will dissolve using colors from the cybPnkPal_PS using randMode 4 and bgMode 0 (see Inputs Guide above) 
   with the number of lines set on one cycle increasing every 100ms with the effect updating every 100ms. */

DissolveSL dissolve(mainSegments, 3, 0, 3, 150, 70);
/* Will dissolve using random colors set according to randMode 3
   (use randMode 2 or 3 with this constructor)
   The bgMode is 0 (no blanks), with a "randMode3CycleLen" of 3, although this is ignored (see Inputs Guide above)
   The number of lines set on one cycle increases every 150ms with the effect updating every 70ms. */

//constructor for pattern
DissolveSL(SegmentSetPS &SegSet, patternPS &Pattern, palettePS &Palette, uint8_t RandMode, 
           uint16_t SpawnRateInc, uint16_t Rate);

//constructor for palette as pattern
DissolveSL(SegmentSetPS &SegSet, palettePS &Palette, uint8_t RandMode, uint8_t BgMode, uint16_t SpawnRateInc, uint16_t Rate);

//constructor for randomly chosen colors (should only use randMode 2 or 3 with this constructor)
//note that RandMode3CycleLen is only relevant for bgMode 1 and randMode 3. 
//it controls how many colors are cycled before the background color is used. 
//(see intro bgMode section for more)
DissolveSL(SegmentSetPS &SegSet, uint8_t RandMode, uint8_t BgMode, uint16_t RandMode3CycleLen, 
           uint16_t SpawnRateInc, 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 patterns. It is a pointer. See common vars pattern entry for more details.

• uint8_t randMode -- The randMode that will be used for the dissolves (see intro above).

• uint8_t bgMode -- Controls if "blank" spaces are added to the shift pattern. See "Inserting Background Dissolves" in Inputs Guide above. Can be changed later using setBgMode().

• uint16_t randMode3CycleLen (optional, see constructors, default to pattern length if not used) -- Only relevant when using bgMode 1 and randMode 3. Sets how many colors are cycled through before the background color is used. (See "Inserting Background Dissolves" in Inputs Guide above)

• uint16_t spawnRateInc -- The rate increase at which the total number of lines that are set each cycle (ms). Setting this close-ish (up to double?) to the update rate looks the best.

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

• CRGB* bgColor (default 0, black) -- 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.

• uint8_t colorMode (default 0) -- The colorMode use for the effect, also see common vars colorMode entry for more details.

• uint16_t setAllThreshold (defaults to 1/10th of the segment set length) -- The number of segment lines that will be set randomly before any remaining lines are force set at once. This is a fail safe so that you don't get stuck with one line that is never randomly picked, preventing the dissolve from ending.

• uint16_t pauseTime (default 0ms) -- The length of time the effect will wait between dissolves. If the pause time is active, it is indicated with the paused flag.

• uint8_t maxNumSpawnBase (default 1) -- The starting value of the number of segment lines set in one cycle. Higher numbers may work better for longer segment set lengths.

• bool randMode5AllowRepeats (default false) -- Only used in randMode 5. If true, then dissolve colors from the pattern can repeat between blanks. If false, a new color will always be chosen.

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

  Sets the effect pattern to match the current effect palette. See Common Functions for more.

• void setBgMode(bool newBgMode);

  Sets the bgMode to control "blank" pattern spaces. See "Inserting Background Dissolves" in Inputs Guide above.

• void resetPixelArray();

  Resets the dissolved state of the segment lines, effectively restarting the current dissolve.

• void setLineMode( bool newLineMode );

  Sets the lineMode (See lineMode notes in intro), also restarts the dissolve, and sets the setAllThreshold to 1/10 the numLines.

• void update();

  Updates the effect.

• uint16_t dissolveCount -- The number of dissolves we've done (does not reset automatically).

• uint16_t numCycles -- How many dissolves we've finished (resets when we've gone through the whole pattern).

• uint8_t bgMode -- (see constructor vars above). Set using setBgMode().

• bool lineMode (default true) -- (See Line Mode notes in intro). Set using setLineMode().

• bool paused -- While true, the effect is paused. Note that the effect is not re-drawn while paused.