Add Glitter - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Utility Drawing White Glitter On Top Of Color Mode Fill Effect (mode 3) (see here for segment layout info)

A utility effect that lights up random pixels to add "glitter" to an existing effect. The utility is specifically built to run on the same segment set as another effect and includes several mechanisms to help sync the effects.

The utility only supports one color for the glitter, but the color is a pointer, so you can bind it externally (see Constructor Inputs for more).

Supports color modes for the glitter colors.

Warning! The utility never removes any glitter, it assumes that the partnered effect will wipe any old glittering pixels out when it updates (you many need to turn on fillBg in your effect). This may clash with various "fast" effects, and any effects that rely on reading or adding pixel colors. Test any effects before assuming it works.

Note that the utility uses an uint16_t array sized to the number of glitter particles, glitterNum. It is allocated dynamically, so, to avoid memory fragmentation, when you create the effect, you should set glitterNum to the maximum value you expect to use. See Memory Management for more details.

There are two glitter modes that set how the glitter pixels are drawn:

glitterMode (uint8_t):

• 0 -- All the glitter pixels get new locations each update.
• 1 -- The glitter pixels are replaced one by one with new locations at each update, so that one pixel turns off and a new one turns on.

The utility has two rates: the glitterRate and the overall update rate. The glitterRate controls how often the glittering pixels change, while the rate sets how often the glitter pixels are re-drawn. In practice, you bind your effect's update rate and the utility's rate to be the same, so that the effect and the utility draw at the same time, preventing them from over-writing each other. Meanwhile, you use glitterRate to control the look of the glitter.

For example, lets say have an effect that updates every 100ms, and we want to add glitter, spawning it every 1000ms. The utility's rate would be 100ms, the same as the effect's, so that the glitter would be re-drawn in sync with the effect. Meanwhile, our glitterRate would be 1000ms, controlling how often the glitter pixels change location.

Note that the utility assumes that the glitter spawn rate is slower or equal to the effect's update rate. If glitterRate is the faster, then it will keep filling the segment set with glitter.

Both glitterRate and rate are pointers like in other effects, so you can bind them externally. See common vars rate entry for more.

Note that while the glitter spawning and drawing parts of the utility update independently, it may be helpful to make it a multiple of your effect's rate. For example, if your effect's rate is 80, glitter rates could be 160, 240, 320, etc. See common vars showNow entry for more details. This can help limit extra time spent writing to the LEDs.

Like a normal effect, the utility does call a show() function to draw the glittering pixels. To prevent the glitter from being written over, it should be drawn after any other effects sharing the segment set. This means that the utility should be always be updated AFTER your effects. You should also set the other effect's showNow variable to false to reduce redundant drawing.

In other words your update setup should be similar to:

yourEffect.update();//<---- with showNow = false;
glitter.update(); //<---- showNow = true, so the pixels are displayed.

//Since the utility needs an effect to work with, we'll use a basic Rainbow Cycle effect for this example
RainbowCyclePS rainbowCycle(mainSegments, 30, true, 80); 
//Will draw rainbows of length 30, moving towards the end of the segment set, at 80ms

//Create the glitter utility
AddGlitterPS addGlitter(mainSegments, CRGB::White, 10, 0, 800, 80);
/*  Will drawn 10 white glitter pixels on the segment set every 80ms.
    Glitter mode 0 is used, so the pixels all be set on/off at once.
    New glitter locations will be set every 800ms. */
    
//Some setup code (put in Arduino setup() function)
addGlitter.rate = rainbowCycle.rate; //bind the utility rate pointer to the effect's so they sync
rainbowCycle.showNow = false; //We'll show() using just the glitter utility.
    
//The update functions (put in the Arduino loop() function)
rainbowCycle.update();
glitter.update();

AddGlitterPS(SegmentSetPS &SegSet, CRGB GlitterColor, uint16_t GlitterNum, uint8_t GlitterMode, 
             uint16_t GlitterRate, uint16_t Rate);

• SegmentSetPS* segSet -- The Segment Set the effect will draw on. See common vars segSet entry for more details.

• CRGB* glitterColor -- The color used for glitter pixels. Is a pointer, allowing you to bind it to an external color. By default it's bound the effect's local, glitterColorOrig color. See common vars bgColor entry for more details, as it behaves the same way.

• uint16_t numGlitter -- How many glitter pixels there are. Can be changed later using setGlitterNum().

• uint8_t glitterMode -- How the glitter pixels will be turned on/off (see Glitter Modes above).

• uint16_t* glitterRate -- 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, glitterRateOrig. (See link in the rate entry for more binding info, as it behaves the same way).

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

• bool active (default true) -- If false, the utility/effect will be disabled (updates() will be ignored). See common vars active entry for more details.

• 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. Particularly important for this utility (see Updating and Showing in intro).

• void setGlitterNum( uint16_t newNum ); 

  Sets the number of glitter pixels, will wipe out the current set.

• void update();

  Updates the effect.

• uint16_t glitterNum -- The number of glitter pixels, use setGlitterNum() to set.