Effect Fader - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Description:

A utility class for fading effects in and out, like when a song fades out at its end. Useful for smoothly transitioning between effects. Uses the effects' segment set brightness value to do the fading.

Requires an effect set to function.

Note that this utility will fades effects either in or out once, and must be manually reset once finished. For a more automated version, see Effect Set Fader.

Also note that due to the way the segment set brightness works, this utility may not work well with any effects that need to read or add LED colors from the FastLED leds array (See previous link for more).

Setup:

To setup the utility, you'll first need an effect set and an array of effects.

For Example:

EffectBasePS *effArray[1] = {nullptr};
EffectSetPS effectSet(effArray, SIZE(effArray), 0, 10000); //(run time 1000ms)

You'll need to populate this set with an effect yourself.

You'll then create the Fader utility:

EffectSetFaderPS setFader(effectSet, true, 3000); //(run time 3000ms)

The Fader instance, setFader, is setup to fade the effects from 0 to 100% over 3000ms.

When you update you effectSet, also call setFader.update() to update the Fader.

Once the effect is faded in, the Fader will be "done", and needs to be reset() to restart.

Notes:

  • The Fader works by changing the brightness of the effect(s) segment set(s). It's fine to have multiple effects that share segment sets; the Fader is coded to only set the brightness for a segment set once per cycle.

  • Effects will either be brightened up from the Fader's minimum brightness (see below) or darkened towards it.

  • The Fader assumes that the supplied segments are already set to the normal brightness (whatever you set that to be). You do not need to pre-adjust them to the fade starting point, the Fader handles all the busy work.

  • The Fader records the initial brightness of the segment sets during the first update() call. You can use resetBrightness() to restore the segment sets to the initial brightness.

  • DO NOT update() if the Effect Set is empty; the segment set brightness's will be default to 255, and fading in will not work.

  • If you change the segment set's brightness while the Fader is running, the Fader may either not finish, or finish early.

  • DO NOT change with the Fader's runTime or fade direction (direct), while the fade is running.

Example Calls:

//(see setup guide above, but for reference)
EffectFaderPS effectFader(effectSet, false, 2000)
//Will create a Fader to fade out all the effects in the effectSet (direction is false), 
//taking 2000ms for the fades.

Constructor Definitions:

EffectFaderPS(EffectSetPS &EffectSet, bool Direct, uint16_t RunTime);

Constructor Inputs:

  • EffectSetPS* effectSet -- The effect set that the Fader will operate on.

  • bool direct -- The direction of the fade (true is fading in, false out). Change this only once a fade is done or not yet started

  • uint16_t runTime -- The time (ms) taken to fade in/out. Changing this will only be reflected when you reset().

Other Settings:

  • uint16_t* rate (default 60) -- The utility's 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, which is defaulted to 60. See common vars rate entry for more.

  • uint8_t minBrightness (default 5, max 255) -- The minimum brightness the fade will reach or start from. (255 is fully bright).

Class Functions:

  • void reset();

    Restarts the Fader.

  • void reset( EffectSetPS &EffectSet, bool newDirect);

    Resets the Fader with a new Effect Set and direction.

  • void resetBrightness();

    Resets the effect(s) segment set(s) to their original brightness setting(s) (as recorded during the first Fader update()).

  • void update();

    Updates the utility.

Flags:

  • bool done (default false) -- Set true if a fade has finished.

  • bool started (default false) -- Set true if a fade has started.