Fireflies (Seg Line) - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info) (Shown in 1D)

A 1D simulation of fireflies: a set of twinkling particles moving in random patterns across the strip. You have options for the number of particles, how fast they move, how long the live for and how often they spawn. Firefly colors can be set to a single color or picked randomly from a palette. You also have the option of having the constructor make a random palette for you.

In general you can change most variables on the fly except for maxNumFireflies.

Supports color modes for both the main and background colors.

By default the background color is black (0). If you set a non-zero background color be sure to set fillBg to true, otherwise each pixel will only be filled after a firefly touches it.

The effect is adapted to work on segment lines for 2D use. Note that the firefly simulation is 1D, using a 2D segment set will cause each firefly to drawn on a whole segment line (which still looks neat, but is not the same as a full 2D set of fireflies).

Due to the way the effect is programmed, if two flies meet each other, by default one will overwrite the other. You can adjust this behavior by turning on blend, which will add particle colors together as they pass by each other.

However this does have one draw back:

• 1: For colored backgrounds, the particles colors are added to the background colors. This will, in most cases significantly change the particle colors. For example, blue particles running on a red background will appear purple (blue + red = purple). Overall I do not recommend using blend for colored backgrounds.

• 2: Using blend on segment sets with lines of unequal length may look weird, because pixels may be added to many times where multiple lines converge/overlap.

Note that this effect does require three separate arrays:

• A particle set with a particle array of size maxNumFireflies.
• A CRGB array of size maxNumFireflies to store the trail color for each particle.
• A uint16_t array of size maxNumFireflies to store the previous particle locations.

These are allocated dynamically, so, to avoid memory fragmentation, when you create the effect, you should set maxNumFireflies to the maximum value you expect to use. See Memory Management for more details.

To get a good variety of fireflies you want to add a good amount of range for each firefly's settings. Fireflies rely on the FastLED noise functions for their movement. The functions produce a noise output based on a few inputs, however, same inputs => same outputs, so two fireflies with the same settings, we look and move exactly the same. To prevent this fireflies are always spawned with a set of random values based on a set of range settings, but using small ranges, will result in similar looking flies.

• spawnChance -- How likely an inactive firefly is to spawn each update cycle (a percent out of 100).

• lifeBase -- The minimum time (in ms) a firefly will live for.

• lifeRange -- Sets the maximum possible amount added to lifeBase. The overall firefly life is calculated as lifeBase + random(lifeRange).

• speedBase -- The slowest speed a particle will move (this is a multiplier, see more below).

• speedRange -- Sets the maximum possible amount added to speedBase. The overall firefly speed is calculated as speedBase + random(speedRange).

lifeBaseis used to set minimum limit on all the fireflies life, but you still want to give them time to move. So lifeBaseshould probably be 2000+ (2 sec), while the range should be a bit larger than the base, ie 3000ish. A larger life range will help give your fireflies more variation.

speedBase and speedRange do most of the work in separating fireflies. They work by multiplying the noise input, placing the fireflies on different noise paths. So the "speed" isn't a time, but more like a scale of motion. A "good" speed and range vary a lot depending on how large your segment set is. I recommend starting with a speed of 10 and a range of 8. Make sure your range is at a good portion of your base speed, if you set it too low, fireflies will tend to move together.

There are some other, secondary variables listed in the Other Settings section below, but you probably won't need to tweak these initially.

A firefly will spawn if random(spawnBasis) <= spawnChance. spawnBasis is default to 1000, so you can go down to sub 1% percentages. Note that the effect tries to spawn any inactive firefly with each update(). This means that how densely your fireflies spawn depends a lot on the effect update rate and how many fireflies you have. Even with quite low percentages, fireflies will probably spawn quite often.

Fireflies fade in and out as they spawn and de-spawn. The percentage of their life that they spend fading is controlled by fadeThresh, defaulted to 50 out of 255. See the "Other Settings" entry below for more details.

By default, the fireflies vary their brightness randomly to "flicker". You can disable this by setting flicker to false.

FirefliesSL fireflies(mainSegments, CRGB(222, 144, 9), 15, 50, 2000, 3000, 8, 6, 80);
/* Will do a set of fireflies using a yellow-orange color
   There are a maximum of 15 fireflies active at one time, and each has a 5 percent chance of spawning per cycle (50/1000)
   The fireflies have a base life of 2000ms, with a range of 3000ms (for a max life of 5000ms)
   The fireflies have a base speed of 8, with a range of 6 (for a max speed of 14)
   The effect updates at 80ms
   !!When using a single color constructor, if you use a pre-build FastLED color make sure you pass in as
   CRGB(*colorCode*), ex CRGB(CRGB::Red)
   Otherwise the compiler will get confused and call the random palette constructor */

FirefliesSL fireflies(mainSegments, cybPnkPal_PS, 5, 200, 3000, 4000, 6, 14, 70);
/* Will do a set of fireflies using colors from the cybPnkPal_PS palette
   There are a maximum of 5 fireflies active at one time, and each has a 20 percent chance of spawning per cycle (200/1000)
   The fireflies have a base life of 3000ms, with a range of 4000ms (for a max life of 7000ms)
   The fireflies have a base speed of 6, with a range of 14 (for a max speed of 20)
   The effect updates at 70ms */

FirefliesSL fireflies(mainSegments, 2, 20, 50, 3000, 3000, 4, 5, 80);
/* Will do a set of fireflies using a random palette of 2 colors
   There are a maximum of 20 fireflies active at one time, and each has a 5 percent chance of spawning per cycle (50/1000)
   The fireflies have a base life of 3000ms, with a range of 3000ms (for a max life of 6000ms)
   The fireflies have a base speed of 4, with a range of 5 (for a max speed of 9)
   The effect updates at 80ms */

//Constructor for effect with palette
FirefliesSL(SegmentSetPS &SegSet, palettePS &Palette, uint16_t MaxNumFireflies, uint16_t SpawnChance, 
            uint16_t LifeBase, uint16_t LifeRange, uint16_t SpeedBase, uint16_t SpeedRange, uint16_t Rate);

//Constructor for effect with palette of random colors
FirefliesSL(SegmentSetPS &SegSet, uint8_t numColors, uint16_t MaxNumFireflies, uint16_t SpawnChance, 
            uint16_t LifeBase, uint16_t LifeRange, uint16_t SpeedBase, uint16_t SpeedRange, uint16_t Rate);

//constructor for effect with single color
//!!If using pre-build FastLED colors you need to pass them as CRGB( *color code* ) -> ex CRGB(CRGB::Blue)
FirefliesSL(SegmentSetPS &SegSet, CRGB Color, uint16_t MaxNumFireflies, uint16_t SpawnChance, uint16_t LifeBase, 
            uint16_t LifeRange, uint16_t SpeedBase, uint16_t SpeedRange, 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.

• uint8_t numColors (optional, see constructors) -- The number of randomly chosen colors for fireflies. The colors will be placed into the effect's local palette, paletteTemp for use.

• CRGB color (optional, see constructors) -- A single color for all the fireflies. The color will be placed into the effect's local palette, paletteTemp for use.

• uint16_t maxNumFireflies -- The maximum number of simultaneous fireflies that can be active at one time. Can be adjusted later using setupFireflies().

• uint16_t spawnChance -- How likely an inactive firefly is to spawn each update cycle (a percent out of spawnBasis: 1000 by default).

• uint16_t lifeBase -- The minimum time (in ms) a firefly will live for.

• uint16_t lifeRange -- Sets the maximum possible amount added to lifeBase (ms). The overall firefly life is calculated as lifeBase + random(lifeRange).

• uint16_t speedBase -- The slowest speed a particle will move (this is a multiplier, see Inputs Guide above) (ms).

• uint16_t speedRange -- Sets the maximum possible amount added to speedBase(ms). The overall firefly speed is calculated as speedBase + random(speedRange).

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

• CRGB* bgColor (default 0, off) -- 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.

• bool blend (default false) -- Causes sparks to add their colors to the strip, rather than set them. See explanation of this in more detail above in the Intro.

• bool flicker (default true) -- Turns the firefly brightness flicker on or off.

• uint8_t fadeThresh (default 50) -- The number of steps (out of 255) for the fireflies to fade in and out. The fireflies spend 255 steps in total fading in, staying at a peak color, then fading out. The value of fadeThresh sets how many steps they spend fading. Note that setting it to 255 will only do a fade in, and then the fireflies will disappear instantly. 128 will cause them to fade in then out with no pause at the peak.

• uint16_t spawnBasis (default 1000) -- The spawn probability threshold. A firefly will spawn if random(spawnBasis) <= spawnChance.

• 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 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 setupFireflies( uint16_t maxNumFireflies );

  Creates the data structures for a set of fireflies. You should call this if you ever want to change maxNumFireflies. Will also clear any active fireflies from the segment set by filling in the background.

• void update();

  Updates the effect.

• uint16_t maxNumFireflies -- The maximum number of fireflies that can be active at any one time, call setupFireflies() to change.