Fairy Lights (Seg Line or Seg) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info) (Shown in 1D)
Mode 0	Mode 1	Mode 2

Fills in a set number of random segment lines, segments, or single pixels one at a time before turning them off in sequence. There a multiple sequence modes for turning the pixels on/off. Overall, the effect is meant to be similar to some classic fairy light twinkle modes. The color of the twinkles can be set to a single color, chosen randomly, or picked from a palette.

Supports color modes for both the main and background colors.

tMode sets the on/off sequence for the pixels.

• 0: Turns one twinkle on after another and then resets them all at once.
• 1: Turns on each twinkle one at a time, then off one at a time.
• 2: Each cycle, a new twinkle is turned on while an old is turned off (first on first off).

Note that you can have the effect prefill a set of pixels on the first update using the prefill setting, causing the effect to act as if a full cycle had been completed and we're ready to turn off the pixels. See "Other Settings" below.

randModes sets how each twinkle color will be set.

• 0: Picks colors from the palette
• 1: Picks colors at random

The effect is adapted to work on segment lines, whole segments for 2D use, or on single pixels (1D). This is controlled by segMode:

• 0: Twinkles will be drawn on segment lines.
• 1: Twinkles will be drawn on whole segments.
• 2: Twinkles will be drawn on individual pixels.

segmode can be changed during runtime using setSegMode( uint8_t newSegMode );.

When drawing on segment lines (segMode 0), for segment sets with varying segment lengths, you may see "artifacts" where twinkles are not fully turned off. This happens because of overlapping segment lines. Thankfully you can fix this by setting fillBG to true, which forces all the twinkles to be re-drawn each update cycle. Note that if you turn fillBG off, make sure to also turn off reDrawAll (see Other Settings below for more info).

Requires an uint16_t array and CRGB array of length numTwinkles to work, make sure you have the memory for them. These are allocated dynamically, so, to avoid memory fragmentation, when you create the effect, you should set numTwinkles to the maximum value you expect to use. See Memory Management for more details.

FairyLightsSLSeg fairyLights(mainSegments, cybPnkPal_PS, 0, 20, 2, 2, 80);
fairyLights.prefill = true; //place in Arduino setup() function
/*  Will choose 20 pixels (segMode 2) each cycle to set to colors 
    from the cybPnkPal_PS palette,
    with a black background.
    Each cycle, a new pixel will be turned on, while an old is turned off (tMode 2), 
    with 80ms in between each cycle. */

FairyLightsSLSeg fairyLights(mainSegments, CRGB::Red, CRGB::Blue, 10, 1, 0, 100);
/*  Will choose 10 lines (segMode 0) to set to red before resetting, using a blue background, 
    The lines will be turned on one at a time, and then off one at a time (tMode 1),
    with 100ms between each cycle. */

FairyLightsSLSeg fairyLights(mainSegments, 5, 0, 0, 1, 150);
/*  Will choose 5 segments (segMode 1) to cycle to/from to random colors 
    (no input color/palette, so randMode = 1).
    The background is black. 
    Each segment will be turned on one at a time, before resetting them all at once (tMode 0), 
    with 150ms between each cycle.
    (for this effect, make sure your segment set has multiple segments) */

//Palette based constructor
FairyLightsSLSeg(SegmentSetPS &SegSet, palettePS &Palette, CRGB BgColor, uin16_t NumTwinkles,
                 uint8_t Tmode, uint8_t SegMode, uint16_t Rate);

//Single color constructor
FairyLightsSLSeg(SegmentSetPS &SegSet, CRGB Color, CRGB BgColor, uint16_t NumTwinkles, uint8_t Tmode,
                 uint8_t SegMode, uint16_t Rate);

//Random colors constructor
FairyLightsSLSeg(SegmentSetPS &SegSet, CRGB BgColor, uint16_t NumTwinkles, uint8_t Tmode, 
                 uint8_t SegMode, 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.

• CRGB color (optional, see constructors) -- For the single color constructor, sets the color that the twinkles will be. Note that the effect will create a local palette, paletteTemp for the color.

• 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 numTwinkles -- The number of random twinkles chosen for twinkling. Can be later adjusted by calling setNumTwinkles().

• uint8_t tMode -- The twinkling mode for the effect (see intro for notes).

• uint8_t segMode -- Sets if twinkles will be drawn on segment lines, whole segments or individual pixels (See segMode notes in intro). Can be changed later using setSegMode().

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

• uint8_t randMode (default 0) -- sets how colors will be picked. (See notes in intro)

• bool fillBg (default false) -- If true, then all pixels will be re-colored with each update(), rather than just drawing those that have changed. See common vars fillBg entry for more details.

• bool reDrawAll (default false) -- If true, the effect will re-draw all the twinkles each cycle, but does not re-draw the whole background. You need this if you want change the number of twinkles during runtime. It is automatically set true if fillBG is true.

• bool prefill (default false) -- If true, the effect pre-draws a full set of twinkles on the first update, as if a full cycle had been completed and we're ready to turn off the pixels. Won't work for tMode 0 since all the pixels will be immediately turned off. (Which is fine, since that's what the mode does).

• 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 setSingleColor( CRGB color ); 

  Sets the effect to use a single color for the twinkles, will restart the effect. Uses the local palette, paletteTemp for the color.

• void setNumTwinkles( utin16_t newNumTwinkles );

  Changes the number of twinkles, re-spawns them, and calls reset() to clear out any existing pixels.

• void setSegMode( uint8_t newSegMode ) ;

  Sets if twinkles will be drawn on segment lines, whole segments or individual pixels (See segMode notes above) (will reset() the current set of twinkles).

• void reset();

  Restarts the effect by clearing our any existing pixels and spawning a new set. (will also trigger prefill if set)

• void update();

  Updates the effect.

• uint16_t cycleNum -- How many twinkles have been drawn (resets once numTwinkles updates have been done).

• uint16_t numTwinkles -- The amount of random twinkles chosen for twinkling, set using setNumTwinkles().

• uint8_t segMode -- (see intro notes), set using setSegMode().

• bool turnOff -- Tracks if we're turning the twinkles on or off, depending on the tmode. (true is turning off)