-
-
Notifications
You must be signed in to change notification settings - Fork 0
XmasLights (Seg Line or Seg)
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 varsbgColor
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 usingsetSegMode()
. -
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 varsrate
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 varsshowNow
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 callsetupTwinkleArray()
, triggering areset()
. -
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 usingsetSegMode()
.
- Overview
- Wiring LEDs and Prerequisites
- Code Examples:
- Commonly Used Variables and More
- Class Documentation Guide
- Segment Basics
- Advanced Segment Usage
- Segment Class Specs:
- Segment Drawing Functions
- Effect Basics
- Effects Advanced
- Color Modes
- Commonly Used Variables and More
- Pointers
- Temporary Effects
- Effect Utility Classes
- Effect Samples
- Documentation Notes
Show/Hide Effects
- Breath
- Breath Eye Seg Line
- Color Melt Seg Line
- Color Mode Fill Seg Line or Seg
- Color Wipe Seg
- Color Wipe Seg Line or Seg
- Cross-Fade Cycle
- Dissolve Seg Line
- Draw Pattern Seg Line or Seg
- Edge Burst Seg Line
- Fairy Lights Seg Line or Seg
- Fire2012 Seg
- Fire2012 Seg Line
- Fireflies Seg Line
- Fireworks
- Glimmer Seg Line
- Gradient Cycle Seg Line
- Gradient Cycle Fast Seg Line
- Larson Scanner Seg Line
- Lava
- Noise16
- Noise Seg Line
- Noise Gradient Seg Line
- Noise Waves Seg Line
- Pacifica
- Pacifica Hue Seg Line
- Particles Seg Line
- Pattern Shifter Seg Line
- Pattern Shifter Seg
- Plasma Seg Line
- Police Strobe Seg Line or Seg
- Pride With Pal Seg Line
- Pride With Pal 2 Seg Line
- Rainbow Cycle
- Rainbow Cycle Seg Line or Seg
- Rainbow Fonts Seg Line
- Rain Seg
- Rain Seg Line
- Rolling Waves Seg Line
- Rolling Waves Fast Seg Line
- Scanner Seg Line
- Segment Waves Seg
- Segment Waves Fast Seg
- Shifting Sea Seg Line
- Shimmer Seg Line
- Soft Twinkle Seg Line
- Streamer Seg Line
- Streamer Fast Seg Line
- Strobe Seg Line or Seg
- Theater Chase Seg Line
- Twinkle Seg Line
- Twinkle Fast Seg Line
- Twinkle 2 Seg Line or Seg
- Xmas Lights Seg Line or Seg