Breath - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info)

Classic breathing/heartbeat effect. The segment set slowly fades between a main color and a background color. The effect cycles through colors following a pattern/palette. There a options for a single color, random colors, a rainbow mode.

The breathing is based on code by ldirko, found here.

The effect is not compatible with Color Modes.

The speed of the breathing is set by breathFreq. Like the effect update rate, it is pointer so you can bind it externally. By default the breathFreq will be bound to the effect's local breathFreqOrig. See common vars rate entry for more.

I recommend a breathFreq between 5 and 20 (higher is slower).

Your update rate should not be too much more than your breathing freq, or the effect will look choppy.

You can also control how far the breath fades using maxBreath (default 255). Lower values will mimic more of a pulse kind of look by preventing the breath from fading all the way to the background. Note that this works best when using a single color, otherwise the effect will look "jumpy" as colors will change without fully fading.

In rainbow mode (randMode 4), the effect cycles through colors following the rainbow. hueRate (default 20) sets how many steps the rainbow hue is incremented by with each breath, controlling how fast the effect cycles through the rainbow.

• 0: Colors will be chosen in order from the pattern (not random).
• 1: Colors will be chosen completely at random.
• 2: Colors will be chosen randomly from the pattern (not allowing repeats).
• 3: Colors will be chosen randomly from the pattern (allowing repeats).
• 4: Colors will be from the rainbow (the hue is offset by hueRate each time a color is chosen).

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

BreathPS breath(mainSegments, pattern, cybPnkPal_PS, 0, 10, 50);
/* Does a breathing cycle using the colors from the cybPnkPal_PS palette, 
   following the pattern above
   The background is blank
   The breathFreq is 10, the effect updates at 50ms */

BreathPS breath(mainSegments, cybPnkPal_PS, 0, 5, 50);
/* Does a breathing cycle using the colors from the cybPnkPal_PS palette in order
   The background is blank
   The breathFreq is 5, the effect updates at 50ms */

BreathPS breath(mainSegments, CRGB::Red, CRGB::Blue, 200, 5, 50);
/* Does a breathing cycle in red only
   The background is blue
   The maximum fade amount is capped at 200
   The breathFreq is 5, the effect updates at 50ms */

BreathPS breath(mainSegments, 0, 25, 10, 50);
/* Does a breathing cycle using a rainbow
   The background is blank
   The rainbow hue advances 25 steps with each breath
   (the hueRate is how the rainbow's color changes with each breath, out of 255)
   The breathFreq is 10, the effect updates at 50ms */

//Constructor for using a pattern and palette
BreathPS( SegmentSetPS &SegSet, patternPS &Pattern, palettePS &Palette, CRGB BgColor, uint8_t BreathFreq, uint16_t Rate );

//Constructor for using palette as pattern
BreathPS( SegmentSetPS &SegSet, palettePS &Palette, CRGB BgColor, uint8_t BreathFreq, uint16_t Rate );

//Constructor for a single color breath (pass in 0 as the color to trigger randMode 2, fully random)
BreathPS( SegmentSetPS &SegSet, CRGB color, CRGB BgColor, uint8_t MaxBreath, uint8_t BreathFreq, uint16_t Rate ); 

//Constructor for rainbow mode
BreathPS( SegmentSetPS &SegSet, CRGB BgColor, uint8_t HueRate, uint8_t BreathFreq, 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 color (optional, see constructors) -- Sets a single color for the breathing. Note that the color will be placed in the effect's local palette,paletteTemp. If you pass in 0 as the color then the effect will switch to randMode 1 (full random).

• CRGB* bgColor -- The color that the breaths will fade to (usually blank). 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 maxBreath (optional, default 255) -- How far the breath color will fade towards the background. Only used as a constructor input when creating a single color breath. Using less than 255 with multiple colors causes the colors to jump with each breath. Must be greater than minBreath (default 60, see other settings below).

• uint8_t hueRate (optional, default 20) -- Only used for the rainbow mode: randMode 4. Sets how many steps the rainbow hue is incremented by with each breath, controlling how fast the effect cycles through the rainbow.

• uint8_t* breathFreq -- The speed of the breathing, between 5 and 20 works well (higher is slower). Like the effect update rate, it is a pointer, by default it's bound to the effect's local variable, breathFreqOrig.

• 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 randMode (default 0, unless set by a constructor) -- see randMode notes in intro.

• uint8_t minBreath (default 60, min 0) -- The maximum amount (out of 255) that the breath colors will fade from the background. At 0 the breaths will start fully at the breathing color. 60 was taken from the original code by ldirko. Must be less than maxBreath (see constructors above).

• uint8_t breathEndOffset (default 5) -- The brightness threshold difference from maxBreath for changing breath colors, shouldn't need to change this, see comments in update() function in the code.

• uint8_t sat (default 255) -- The HSV saturation of the rainbow mode (randMode 4). See Common Vars "sat and hue" entry for more.

• uint8_t val (default 255) -- The HSV "value" value of the rainbow mode (randMode 4). See Common Vars "sat and hue" entry for more.

• 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 vars for more.

• void reset();

  Restarts the effect. Note that the effect may start mid breath after resetting.

• void update();

  Updates the effect.

• uint16_t breathCount -- The number of breath cycles we've gone through. Must be reset manually by calling reset().