Fireworks - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Effect Sample (see here for sample info)

A 1D firework simulation inspired heavily by this effect. Spawns multiple fireworks across the strip that explode into a series of sparks that drift apart. There are a lot of options for adjusting how the fireworks look. It is probably best to start with the inputs guide below, or try out one of the constructor examples.

Firework colors are picked randomly from a palette. The effect can make a random palette for you (stored in the local paletteTemp palette).

All fireworks "burst" initially before fading to their spark color. The burst color is stored as burstColor, which is default to white. See Other Settings below for more info.

By default all a firework's sparks are the same color, but you can set them all to be random (from the palette), using randSparkColors.

In general you can change most variables on the fly except for maxFireworks and maxNumSparks.

Supports color modes for both the main and background colors.

If you have a non-zero background color be sure to set fillBG to true!! Otherwise it will only be filled in when a firework particle touches it.

Note that the effect is 1D only, so fireworks always treat the strip as a 1D line. It didn't make sense to expand the fireworks along segment lines, while making a fully 2D simulation was a bit more than I wanted to take on.

Due to the way the effect is programmed, if two sparks 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 two draw backs:

• 1: Due to the way particle trails are drawn, this forces the background to be re-drawn each update cycle, which may have a performance impact depending on your strip length, update rate, etc.

• 2: 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). This can be used to create some nice effects, (like ocean-ish of lava-ish looking things), but overall I do not recommend using blend for colored backgrounds.

Note that this effect does require three separate arrays:

• A bool array of maxNumFireworks that stores if a firework is active or not.
• A particleSet with a particle array of size maxNumFireworks * (maxNumSparks + 1).
• A CRGB array of size maxNumFireworks * (maxNumSparks + 1) to store the trail color for each particle.

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

• maxNumFireworks -- The maximum number of fireworks that can exist on the strip simultaneously.

• maxNumSparks -- The number of sparks each firework produces.

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

• lifeBase -- The maximum time (in ms) a firework's sparks will live for (asides from a bit or randomness from lifeRange).

• speedDecay -- How fast the sparks slow down. This is a percent of their current speed -> speed = speed - speed * speedDecay.

• speed -- The base spark speed (speed is the update time in ms, so lower rate => higher speed).

• speedRange -- The range added to a spark's base speed. A spark's speed is set when it spawns as speed + random( speedRange ).

• lifeBase sets the maximum spark life. You want to give the sparks time to move, so lifeBase should probably be 2000+ (2 sec). You should also know that the effect adds a random bit of extra life to each spark, set by lifeRange (default 500, ie 0.5 sec) to help add variation.

• speedDecay is the percent the speed decreases each time the spark is drawn. I recommend starting between 5 - 20, and adjusting as needed. A lower value will let the sparks spread out more.

• speed and speedRange do a lot of work in shaping how the firework looks. speed sets how fast the average spark moves, while speedRange sets how different spark speeds are from one another. So you can have low speeds and low ranges to make a slow, clumped up firework, or have high speeds and high range so that the sparks move quick and spread out more. I recommend starting with a speed of 40-60 and a speedRange of 300 - 600. For higher speed ranges, increasing the number of sparks will help "fill out" the firework.

The fade rate of the sparks is proportional to their speed, so faster sparks fade slower. This seems to produce a good look.

Fireworks also have a central "bomb" particle, which doesn't move, and decays quickly. This makes the fireworks look more like an explosion. The settings for this spark all use the "center" in their name. They all have default values, so hopefully you won't need to mess with them (see Other Settings below).

There are some other, secondary variables. You probably won't need to tweak these initially.

A firework 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 fireworks with each update(). This means that how densely your fireworks spawn depends a lot on the effect update rate and how many fireworks you have. Even with quite low percentages, at the default update rate (see below), fireworks will probably spawn quite often.

Note that to help avoid fireworks from spawning very close to either end of the strip, their spawn range is reduced by numLEDs / spawnRangeDiv from each end of the strip. By default, spawnRangeDiv is 10. A higher spawnRangeDiv will expand the spawn area.

Note that unlike other effects, the update rate is preset for you at 5ms, which helps catch each of the spark's updates on time (hopefully!). You see, each spark has its own speed (update rate), but we still want be able to update the effect with a single update() call. I could have ignored the "rate" setting, and just updated all the spark whenever you call update(). However, the sparks are re-drawn every update(), even if they haven't moved, so this becomes problematic, especially when working with multiple effects or segment sets, where you want more control over when you update. Instead I opted to treat the effect as normal, and keep the overall update rate, but default it to a very fast 5ms. Hopefully this default will catch most sparks on time. You are free to change the update rate as needed by setting rateOrig.

FireworksPS fireworks(mainSegments, 5, 3, 10, 100, 2000, 20, 40, 300);
/* Will do a set of fireworks using colors from a randomly generated palette of 5 colors
   There is a maximum of 3 fireworks active at one time.
   Each firework has 10 sparks
   There is a 10% chance a new firework spawns during an update (100/1000)
   The sparks have a maximum life of 2000ms (+ a random(500) from the default life range)
   The spark's speed decays at 20 percent per update
   The fastest particles will update at 40ms, while the slowest will be 40 + 300ms */

FireworksPS fireworks(mainSegments, cybPnkPal_PS, 3, 20, 100, 4000, 5, 40, 500);
// Big fireworks with long lasting sparks
/* Will do a set of fireworks using colors from the cybPnkPal_PS palette
   There is a maximum of 3 fireworks active at one time.
   Each firework has 20 sparks
   There is a 10% chance a new firework spawns during an update (100/1000)
   The sparks have a maximum life of 4000ms (+ a random(500) from the default life range)
   The spark's speed decays at 5 percent per update
   The fastest particles will update at 40ms, while the slowest will be 40 + 500ms */

FireworksPS fireworks(mainSegments, CRGB(CRGB::White), 5, 4, 500, 2000, 10, 80, 80);
/* Small, but fast fireworks on a shifting background
   fireworks.bgColorMode = 6; //Put in Arduino setup()
   fireworks.fillBG = true; //Put in Arduino setup()
   Will do a set of fireworks using white as the color
   There is a maximum of 5 fireworks active at one time.
   Each firework has 4 sparks
   There is a 50% chance a new firework spawns during an update (500/1000)
   The sparks have a maximum life of 2000ms (+ a random(500) from the default life range)
   The spark's speed decays at 10 percent per update
   The fastest particles will update at 80ms, while the slowest will be 80 + 80ms
   !!If using a pre-built FastLED color you need to pass them as CRGB( *color code* ) -> ex CRGB(CRGB::Blue)*/

//Constructor for fireworks using a palette
FireworksPS(SegmentSetPS &SegSet, palettePS &Palette, uint8_t MaxNumFireworks, uint8_t MaxNumSparks, uint16_t SpawnChance, 
            uint16_t LifeBase, uint8_t SpeedDecay, uint16_t Speed, uint16_t SpeedRange);

//Constructor for fireworks using a palette of random colors
FireworksPS(SegmentSetPS &SegSet, uint16_t numColors, uint8_t MaxNumFireworks, uint8_t MaxNumSparks, uint16_t SpawnChance, 
            uint16_t LifeBase, uint8_t SpeedDecay, uint16_t Speed, uint16_t SpeedRange);

//Constructor for fireworks of a single color
//!!If using a pre-built FastLED color you need to pass it as CRGB( *color code* ) -> ex CRGB(CRGB::Blue)
FireworksPS(SegmentSetPS &SegSet, CRGB Color, uint8_t MaxNumFireworks, uint8_t MaxNumSparks, uint16_t SpawnChance,
            uint16_t LifeBase, uint8_t SpeedDecay, uint16_t Speed, uint16_t SpeedRange);

• 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 -- The number of randomly chosen colors for fireworks. 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 fireworks. The color will be placed into the effect's local palette, paletteTemp for use. If using a pre-built FastLED color you need to pass is as CRGB( color code ) -> ex CRGB(CRGB::Blue).

• uint8_t maxNumFireworks -- The maximum number of simultaneous fireworks that can be active at one time. Can be set later using setupFireworks().

• uint8_t maxNumSparks -- The number of sparks spawned per firework. Can be set later using setupFireworks().

• uint16_t spawnChance -- The likely-hood of a firework spawning (percent out of 100, larger is more likely).

• uint16_t lifeBase -- The longest time a spark can exist (in ms).

• uint8_t speedDecay -- The percent a spark's speed is reduced by per update cycle (out of 100).

• uint16_t speed -- The base spark speed (speed is the update time in ms, so lower rate => higher speed).

• uint16_t speedRange -- The cap for the slowest speed for the sparks ( speed is rate + random(speedRange) ) (ms).

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

• uint16_t lifeRange (default 500 (ms) -- Added to the lifeBase as random(lifeRange) to set the maximum spark life. Adds a bit of variation so not all the sparks decay at the same time at lower caps.

• uint16_t size (default 1) -- The size of the sparks, only change this for big fireworks.

• uint16_t sizeRange (default 0) -- A random factor for setting the spark sizes. Spark sizes are calculated as size + random(sizeRange).

• uint16_t centerLife (default lifeBase/10 + 100) -- How long the central "bomb" particle lives for in ms.

• uint16_t centerSize (default 3) -- How large the center "bomb" burst particle is.

• bool blend (default false) -- Causes sparks to add their colors to the strip, rather than set them directly. See explanation in intro for more.

• bool randSparkColors (default false) -- If true, each individual spark will have its own color picked from the palette.

• uint8_t burstBlendLimit (default 100) -- The number of steps (out of 255) to blend from the burst color to the spark color.

• CRGB* burstColor (default bound to burstColOrig, which is white) -- The color of the initial firework burst. Like bgColor, it's a pointer, allowing you to bind it to an external color. By default it's bound the effect's local, burstColOrig color. See common vars bgColor entry for more details.

• uint8_t spawnRangeDiv (default 10) -- Sets what range of the strip fireworks spawn in: from numLEDs / spawnRangeDiv to ( numLEDs - (numLEDs / spawnRangeDiv) ).

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

• uint16_t* rate -- Update rate (ms). Defaulted to 5ms (see Update note in Inputs Guide). 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.

• 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 setupFireworks(uint8_t maxFireworks, uint8_t maxSparks);

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

• void update();

  Updates the effect.

• uint8_t maxNumFireworks -- See constructor inputs above. Can be set later using setupFireworks().

• uint8_t maxNumSparks -- See constructor inputs above. Can be set later using setupFireworks().