Breath Eye (Seg Line) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info)

Similar to the Breath effect, but instead of using a single uniform color for the whole segment set, the breath radiates out from a central segment line. This creates something akin to a robotic glowing eye that fades in and out. The are some specific settings for the "eye", but otherwise, the effect is largely identical to Breath.

Overall:

• You control how large the eye grows, including options for randomly varying it for each breath.
• You can set the eye's center position, including options for randomly setting it for each breath.
• The effect follows a pattern/palette of colors.
• The effect will cycle through the colors with each "breath".
• There are also options for using a single color, picking the color randomly, or following the rainbow.

Note that the effect uses segment lines, so the eye will be 2d for a set with multiple segments.

The effect is not compatible with Color Modes.

##Input Notes:

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.

The eye is made of a center point and two "arms" sprouting from each side. The two arms fade to the background at their ends, while the center eye is fully bright (up to the current breath value). You can set the center point's location with eyePos, the center point size with eyeCenterSize (the actual center size will be double the value), and the arm length with eyeHalfSize.

The eyePos can be set to be chosen randomly after every fade, making the eye jump around. When not chosen randomly, it will be defaulted to the center line of the longest segment. The centerEyeSize will be defaulted to 1/8 the eyeHalfSize (see init() in the code), which seemed to look good in my tests.

Note that the total size of the eye is eyeHalfSize * 2. The eye arms always start from the eye center position, with the central eye area being drawn on top of the arms.

You can also opt to have the eye size chosen randomly for each breath by:

• Setting randEyeSize true.
• Setting a maximum size for the eye, eyeHalfSizeMax (defaulted to eyeHalfSize during construction). The eyes will have a random size from eyeHalfSize to eyeHalfSizeMax.

Note that if the eye runs off the end of the segment set, it can be either set to cut off, or wrap around, which is controlled by the wrap setting (tru for wrapping).

By default, the eye arms dim quickly in a non-linear fashion. This makes the eye "head / center" brighter and standout more, which, in my opinion, looks better then just using a linear fade. You can control the linearity of the arm fades using the dimPow setting. A default of 80 is used in this effect. dimPow is borrowed from the particle based effects; you can read the dimPow notes in Particle Utils) for more.

randMode sets how the eye colors are chosen.

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

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.

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

BreathEyeSL breathEye(mainSegments, pattern, cybPnkPal_PS, 0, 10, true, true, 10, 50);
/* Does a breathing cycle using the colors from the cybPnkPal_PS palette, following the pattern above
   The background is blank
   The eyeHalfSize is 10 (total eye size is 20), the eye wraps, 
   and the eye position will be set randomly for each cycle.
   The breathFreq is 10, the effect updates at 50ms */

BreathEyeSL breathEye(mainSegments, cybPnkPal_PS, 0, 8, true, false, 5, 50);
/* Does a breathing cycle using the colors from the cybPnkPal_PS palette in order
   The background is blank
   The eyeHalfSize is 8 (total eye size is 16), the eye wraps.
   The eye position will be fixed (defaulting to the center point of the longest segment),
   The breathFreq is 5, the effect updates at 50ms */

BreathEyeSL breathEye(mainSegments, CRGB::Red, CRGB::Blue, 200, 10, false, true, 5, 50);
/* Does a breathing cycle in red only
   The background is blue
   The maximum fade amount is capped at 200
   The eyeHalfSize is 10 (total eye size is 20), the eye does not wrap, 
   and the eye position will be set randomly for each cycle.
   The breathFreq is 5, the effect updates at 50ms */

BreathEyeSL breathEye(mainSegments, 0, 25, 5, true, true, 10, 50);
/* Does a breathing cycle using a rainbow
   The background is blank
   The rainbow hue advances 25 steps with each breath
   The eyeHalfSize is 5 (total eye size is 10), the eye wraps, 
   and the eye position will be set randomly for each cycle.
   The breathFreq is 10, the effect updates at 50ms */

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

//Constructor for using palette as pattern
BreathEyeSL(SegmentSetPS &SegSet, palettePS &Palette, CRGB BgColor, uint16_t EyeHalfSize, bool Wrap, 
            bool RandEyePos, uint8_t BreathFreq, uint16_t Rate);

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

//Constructor for rainbow mode
BreathEyeSL(SegmentSetPS &SegSet, CRGB BgColor, uint8_t HueRate, uint16_t EyeHalfSize, bool Wrap, bool RandEyePos,
            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.

• uint16_t eyeHalfSize -- How long each arm of the eye is (see Input Notes above).

• bool wrap` -- If true, the eye wraps around at each end of the segment set. If false, it is cut off at each end.

• bool randEyePos -- If true, the eye position will chosen randomly each cycle. If false, the eye will default to the center line of the segment set.

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

• uint16_t eyePos -- The center position of the eye, defaulted to the center line of the longest segment. (Will change randomly if randEyePos is true).

• uint16_t eyeHalfSizeMax (default to eyeHalfSize) -- The upper limit of the eyeHalfSize when using a random eye size (See Input Notes above).

• uint16_t eyeCenterSize (default 1/8 of the eyeHalfSize) -- The size of the center eye portion (See Input Notes above).

• bool randEyeSize -- If true then the eye size will be randomized between eyeHalfSize and eyeHalfSizeMax for each cycle (See Input Notes above).

• int8_t dimPow (default 80, min -127, max 127) -- Adjusts the rate of dimming for the trails (see "Eye Arm Fading" above).

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

• 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 breathFreqOrig -- The default target of the effect's breathFreq pointer variable. Will be set to the passed in breathFreq from the constructor. (see breathFreq notes 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) -- HSV saturation value for rainbow mode. See Common Vars "sat and hue" entry for more.

• uint8_t val (default 255) -- HSV "value" value for rainbow mode. 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. Does not have a capped value.