XmasLights (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)

The goal of this effect is to mimic classic twinkling Christmas lights. Ie, a pattern of repeating colors where lights blink on and off occasionally. I implemented this by using random chance to toggle the state of each pixel during each update cycle, with different probabilities for a pixel turning off vs turning on. By playing around with the two chance values, you can produce a wide variety of twinkling effects with different on/off ratios.

Supports color modes for both the main and background ("off") colors.

The effect is adapted for 2D use, you can change how it draws using segMode (see Inputs Guide below):

For settings that most mimic typical Christmas lights, I recommend a chance ratio of 10 to 1 in favor of pixels turning on. Ex, if your turning on chance is 100, your turning off chance should be 10. (Note that by default the chances are out of 1000).

The exact chance values for a look you like will depend on the size of your strip and your update rate (faster updates will increase the chance of a pixel toggling), but I recommend starting with the first example call below.

The effect uses a pattern and palette for its colors. You can set the length of the pattern colors via colorLength. Ex, for a colorLength of 4, the length of each pattern color will be 4 pixels.

The background color is user controllable, and represents the "off" state of the pixels. Black or white works best for a traditional Christmas effect.

You can also control the initial state of the pixels (all pattern or all background) using bgPrefill. This is important because pixel colors are only filled in as their states change, so if the effect starts as all background, the color pattern will slowly be filled in and visa versa. To accommodate dynamic Color Modes, you can also set all the pixels to be re-drawn each update using fillBg.

• 0 -- The pattern and twinkles will be drawn using segment lines (each line will be a single color).
• 1 -- The pattern and twinkles will be drawn using whole segments (each segment will be a single color).
• 2 -- The pattern and twinkles will be drawn linearly along the segment set (1D).

Note that the effect uses an array of uint8_t's of size (numLines/numSegs/numLEDs)/8 rounded up (based on segMode) to track the state of the pixels. It is allocated dynamically. To prevent memory fragmentation, it is only re-sized if needed. If you plan on changing the segMode during runtime, you should start the array at it's max length (probably segMode 2).

XmasLightsSLSeg xmasLights(mainSegments, cybPnkPal_PS, 0, 1, 100, 10, 0, 100);
/*  Does a set of xmas lights using the colors from the cybPnkPal_PS palette.
    The length of each palette color is 1.
    The background color is black.
    There's is a 10% (100/1000) chance of a pixel turning on
    and a 1% (10/1000) chance of a pixel turning off
    This should produce a more traditional Christmas light effect
    The segMode is 0, so the twinkles will be drawn on segment lines
    The effect updates at a rate of 100ms. */

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

XmasLightsSLSeg xmasLights(mainSegments, pattern, cybPnkPal_PS, CRGB::Red, 4, 100, 100, 0, 100);
/*  Does a set of xmas lights using the colors from the cybPnkPal_PS palette, 
    laid out according to the pattern above. The length of each palette color is 4.
    The background color is red.
    There's is a 10% (100/1000) chance of a pixel turning on
    and a 10% (100/1000) chance of a pixel turing off, for a more "chaotic" effect.
    The segMode is 0, so the twinkles will be drawn on segment lines.
    The effect updates at a rate of 100ms. */

//Constructor with just a palette
XmasLightsSLSeg(SegmentSetPS &SegSet, palettePS &Palette, CRGB BgColor, uint16_t ColorLength, 
                uint16_t OnChance, uint16_t OffChance, uint8_t SegMode, uint16_t Rate);

//Constructor with pattern and palette
XmasLightsSLSeg(SegmentSetPS &SegSet, patternPS &Pattern, palettePS &Palette, CRGB BgColor, uint16_t ColorLength,  
                uint16_t OnChance, uint16_t OffChance, 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.

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

• CRGB* bgColor -- The "off" color of the 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 (min of 1) -- The length of the pattern colors (ex 4, will produce bands of color 4 pixels in length).

• uint16_t onChance -- The chance (out of 1000, see chanceBasis) that an off pixel will turn on.

• uint16_t offChance -- The chance (out of 1000, see chanceBasis) that an on pixel will turn off.

• uint8_t segMode -- Sets if the twinkles will be along segment lines, whole segments, or single LEDs (see segMode's 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 for the "on" pixels, also see common vars colorMode entry for more details.

• uint8_t bgColorMode (default 0) -- The colorMode for the "off" pixels, also see common vars colorMode entry for more details.

• uint16_t chanceBasis (default 1000) -- The pixel on/off toggle probability threshold. A pixel will change if random(spawnBasis) <= (onChance or offChance).

• bool fillBg (default false) -- If true, all the pixels will be re-drawn every update, useful for Color Modes that are dynamic. See common vars fillBg entry for more details.

• bool bgPrefill (default false) -- If true, the background ("off" color) will be pre-filled for the first update(). If false, the color pattern will be pre-filled.

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

  Resets the effect. On the next update, triggers the pixels to be pre-filled it the color pattern or background based on bgPrefill.

• void setPaletteAsPattern();

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

• void setSegMode( uint8_t newSegMode ); 

  Sets the segMode for the effect. Will call setupTwinkleArray(), triggering a reset().

• void setupTwinkleArray(); 

  Dynamically sizes and allocates an array for tracking the pixel's states. You only need to call this if you change the size of the segment set. Will trigger a reset().

• void update();

  Updates the effect.

• uint8_t segMode -- Sets if the twinkles will be along segment lines, whole segments, or single LEDs (see segMode's above). Set using using setSegMode().