Twinkle 2 (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)

Fades sets of randomly chosen segment lines, segments, or pixels in and out smoothly (like FastLED TwinkleFox). The effect gives you a lot of options to customize how the pixels fade in and out and also how they spawn and group together. The color of the pixels can be set to a single color, chosen randomly, of picked from a palette. See the Inputs Guide below for more details.

This effect is very similar to Twinkle (Seg Line), but aims to give you more options on how the twinkling looks by allowing you to adjust the spawn chance of the twinkles. It also gives you the freedom to adjust all effect settings (except numTwinkles, see below) on the fly, so you can have the effect change over time without resetting.

Supports color modes for both the main and background colors. Note that when drawing along whole segments (segMode 1), the effect excludes color modes 1, 6, 2, 7, 3, 8.

The effect is adapted to work on segment lines and whole segments for 2D use. It can also be set to 1D mode (see segMode's below for more info).

Note that the effect requires an array of Twinkle Stars to function. The twinkles 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.

Note that the effect does require slightly more programming space and ram than Twinkle (Seg Line). The ram needed is in proportion to the number of twinkles.

The effect works by storing a set of twinkles, which are either active or inactive. When active, the twinkles fade up to their target color and then fade out again, setting themselves inactive once fully faded out. Inactive twinkles have a set chance of spawning with each update cycle. The spawn chance is the same for all twinkles. This gives you a lot of freedom in tweaking the twinkle density, and can even serve as a replacement for adjusting the number of twinkles (so you don't need to reset()). However, it does come with some quirks as I'll explain with the settings below:

• numTwinkles -- The maximum number of twinkles that can be active on the strip at one time. Basically sets how dense your twinkles are, although this is also influenced by spawnChance. You can change numTwinkles using setNumTwinkles(), but will reset the effect.

• spawnChance and spawnBasis -- The chance than an inactive twinkle will become active in a given update cycle. If random(spawnBasis) <= spawnChance a twinkle will spawn. By default, spawnBasis is set to 1000 to allow sub 1% probabilities.

  spawnChance is critical because it no only influences how dense your twinkles are, but also how likely they are to spawn together. For instance, 30 twinkles with a 10% spawn chance will probably look similar to 10 with a 50% spawn chance. But the latter set will be more likely to spawn in groups. Note that even a 50% spawn chance will slowly have groups become quite random, while 80% will keep them grouped up, but with a bit of randomness. The grouping is also influenced by the fade in/out ranges (see below). Getting the look you want will probably require some experimentation.

• fadeInSteps and fadeOutSteps -- Min value of 1 for both! These set how many gradient steps are taken to fade a twinkle in and out. Larger values will mean longer fades, with pixels sticking around for longer. By varying the two values you can approximate square waves, triangle waves, etc. Try a fade in step of 1 with a longer fade out step for a "falling rain" type look. I recommend values between 4-10.

• fadeInRange and fadeOutRange -- Whenever a twinkle spawns, its fade in and out steps are calculated as: fadeInSteps + random(fadeInRange) (same for fading out but with the "out" variables). So fadeInSteps sets a minimum number of fade steps while fadeInRange sets a cap on the random number of extra steps added. This can give the twinkles a more varied look and helps to prevent twinkles from grouping up. Setting these to 0 means than all twinkles will fade exactly the same. I recommend a value in proportion to your fade in/out steps, maybe double each a most?

• limitSpawning (default false) -- If true, only one new twinkle will be allowed to spawn each update cycle. This is a kind-of brute force way of completely prevent twinkles from grouping up, but puts a limit on the possible twinkle density. Makes it easier to exactly match the look of Twinkle (Seg Line).

The effect is adapted to work on segment lines or whole segments for 2D use, and on single pixels (1D).

This is controlled by the segMode setting:

• 0 -- Twinkles will be drawn on whole segment lines. Each line will be a solid color.
• 1 -- Twinkles will be drawn on whole segments. Excludes Color Modes 1, 6, 2, 7, 3, 8.
• 2 -- Twinkles will be drawn on individual pixels.

Sets how twinkle colors will be picked.

• 0 -- Twinkle colors are picked randomly from the palette.
• 1 -- Twinkle colors fully random.

Twinkle2SLSeg twinkle2(mainSegments, cybPnkPal_PS, 0, 12, 500, 3, 2, 4, 5, 0, 70);
/*  Will choose 12 segment lines (segMode 0) to fade to/from colors from the cybPnkPal_PS palette 
    The background in blank. 
    There is a 50% chance an inactive line will become active each cycle (500/1000)
    There are 3 fade in and 4 fade out steps with ranges of 2 and 5 respectively
    The effect updates at a rate of 70ms. */

Twinkle2SLSeg twinkle2(mainSegments, CRGB::Red, CRGB::Blue, 0, 3, 1000, 2, 0, 6, 0, 1, 60);
/*  Will choose 3 whole segments (segMode 1) to fade to/from red, using a blue background, 
    There is a 100% chance an inactive segment will become active each cycle (1000/1000)
    There are 2 fade in and 6 fade out steps with ranges of 0 and 0 respectively
    The effect updates at a rate of 60ms. */

//Constructor for a full palette effect
Twinkle2SLSeg(SegmentSetPS &SegSet, palettePS &Palette, CRGB BgColor, uint16_t NumTwinkles, uint16_t SpawnChance, 
              uint8_t FadeInSteps, uint8_t FadeInRange, uint8_t FadeOutSteps, uint8_t FadeOutRange, 
              uint8_t SegMode, uint16_t Rate); 

//Constructor for a using a single color
Twinkle2SLSeg(SegmentSetPS &SegSet, CRGB Color, CRGB BgColor, uint16_t NumTwinkles, uint16_t SpawnChance,
              uint8_t FadeInSteps, uint8_t FadeInRange, uint8_t FadeOutSteps, uint8_t FadeOutRange,
              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) -- A single color for the effect. The color will be placed into the effect's local palette, paletteTemp for use.

• 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 maximum number of random twinkles that can be active at one time. Can be changed later using setNumTwinkles().

• uint8_t fadeInSteps (min of 1) -- The number of blend steps taken to fade twinkles in.

• uint8_t fadeInRange -- The amount of variation for the fade in steps (see Inputs Guide above).

• uint8_t fadeOutSteps (min of 1) -- The number of blend steps taken to fade twinkles out.

• uint8_t fadeOutRange -- The amount of variation for the fade out steps (see Inputs Guide above).

• uint8_t segMode -- Sets if twinkles will be drawn on segment lines, whole segments or individual pixels (See segMode notes above). 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) -- (See randMode 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 limitSpawning (default false) -- Limits the twinkles so that only one new one can become active per update cycle (see Inputs Guide above).

• uint16_t spawnBasis (default 1000) -- The spawn probability threshold. A twinkle will spawn if random(spawnBasis) <= spawnChance. (see Inputs Guide above).

• 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 setSteps( uint8_t newFadeInSteps, uint8_t newFadeOutSteps ); 

  Sets the number of fade in and out steps. You can also set the steps directly as long as you don't set them below 1.

• void setSingleColor( CRGB Color );

  Sets the effect to use a single color for the twinkles. The color will be stored in the effect's local palette, paletteTemp.

• void setNumTwinkles( uint16_t newNumTwinkles);

  Sets the maximum amount of random twinkles that can be active at one time, will restart the effect if the new number is different from the current number.

• void setSegMode( uint8_t newSegMode );

  Sets the segMode (See segMode notes in Inputs Guide) (will reset the effect if the new segMode is different than the current).

• void reset();

  Sets all twinkles to inactive and fills in the background.

• void update();

  Updates the effect.

• uint16_t numTwinkles -- (see Input Guide above) set using setNumTwinkles()

• uint8_t segMode -- (see Input Guide above) set using setSegMode().