Particle Utils - AlbertGBarber/PixelSpork GitHub Wiki

Jump to:

Intro:

Particle Utils are a set of helper functions for working with particles and particle sets. They are contained under the namespace, "particleUtilsPS".

The helper functions are intended to simplify creating sets of particles and adjusting them. It also includes various functions for randomizing aspects of a set.

To call a particle util function you would do:

particleUtilsPS::setParticleSetSpeed( yourParticleSet, 0, 50, 0 ):
//Sets the speed first (0th) particle in your particle set to 50
//(with a randomness range of 0, more on that later)

The Functions:

Note that the mostly functions use the particle settings as inputs. So that an input, speed, corresponds to the particle setting, speed. See the particles page for all particle settings.

Functions for Creating Particle Sets:

```
particleSetPS buildParticleSet( uint16_t numParticles, uint16_t maxPosition, uint8_t direction, 
                                uint16_t baseSpeed, uint16_t speedRange, uint16_t size, uint16_t sizeRange, 
                                uint8_t trailType, uint8_t trailSize, uint8_t trailRange, uint8_t bounce, 
                                uint8_t colorIndex, bool randColor );
```
Fills in a given particle set with particles using the passed in options, while randomizing their settings.

Example usage:

To build a particle set, you'll need a variable to store the set, and then use the buildParticleSet() function to fill it in. The function must be called during runtime, either in the setup() or loop() functions, however, if you create your set variable there, it will be local to the functions (so you wouldn't be able to use it outside of the loop or setup). To make the set easy to use, you'll need to create it globally (above the Arduino setup() function) and then fill it in later. Since the set is a struct, it's a little more complicated to create than a typical variable, follow the example code below to create it.
```
uint16_t numParticles = 3; //The number of particles in your set

//create a global particle set variable, make sure set the size to numParticles
//(so you can pass it to a ParticleSL effect, and have it size its internal arrays correctly)
//(don't ask about the double numParticles, just do it.....)
particleSetPS mySet = {nullptr, numParticles, numParticles}; //above the Arduino setup function

//Build the particle set using the build function
mySet = particleSetPS::buildParticleSet( numParticles, etc... ); //in the Arduino setup/loop functions
```
Function inputs:
- uint16_t numParticles -- How many particles the set will have.
- uint8_t direction -- The particle's direction of motion. Passing "2" will choose a random direction for each particle.
- uint16_t maxPosition -- The maximum position of a particle, local to the segment set. The particle's positions will be chosen randomly up to maxPosition.
- uint16_t baseSpeed -- The speed of the particles.
- uint16_t speedRange -- A random factor added to each particle's base speed, ie speed = baseSpeed + random(speedRange).
- uint16_t size -- The size of the particle's bodies (not trails), min of 1.
- uint16_t sizeRange -- A random factor added to each particle's base size, ie size = size + random(sizeRange).
- uint8_t trailType -- The trail type for the particles, a value > 4 (the highest trail type) the trails will be chosen randomly from the first three trail types (0, 1, 2). (see setTrailRand() for configuring a custom set or random trails).
- uint8_t trailSize -- The length of the particle trails, min of 1.
- uint8_t trailRange -- A random factor added to each particle's trail size, ie trailSize = trailSize + random(trailSize).
- uint8_t bounce -- The "bounce" setting for the particles. Passing "2" will choose a random "bounce" for each particle.
- uint8_t colorIndex -- The color index for the particles (from your palette).
- uint8_t randColor -- If true, each particle will be set to a index, randomized up to the colorIndex setting value. In other words, if yuo want to randomize the particle colors, pass your palette's length as the colorIndex.
Finally, note that the particles are created using dynamic memory. Once you have finished with the particles, you must call freeParticleSet() to release their memory. See Memory Management for more details.

Functions for Randomizing Particle Sets and Particles:

void randomizeParticleSet(particleSetPS &particleSet, uint16_t maxPosition, uint8_t direction, 
                          uint16_t baseSpeed, uint16_t speedRange, uint16_t size, uint16_t sizeRange, 
                          uint8_t trailType, uint8_t trailSize, uint8_t trailRange, uint8_t bounce, 
                          uint8_t colorIndex, bool randColor);

Randomizes the particles in a particle set according to the passed in settings. The settings are the same as for buildParticleSet() above, so I won't relist them here.

void randomizeParticle(particleSetPS &particleSet, uint16_t partNum, uint16_t maxPosition, uint8_t direction, 
                       uint16_t baseSpeed, uint16_t speedRange, uint16_t size, uint16_t sizeRange, 
                       uint8_t trailType, uint8_t trailSize, uint8_t trailRange, uint8_t bounce,
                       uint8_t colorIndex, bool randColor);

Randomizes a particle in a particle set according to the passed in settings. The settings are the same as for buildParticleSet() above, so I won't relist them here. partNum is the particle's index in the particle set.

Functions for Changing Particle Settings in Sets:

```
void setParticleSetProp( particleSetPS &particleSet, uint8_t propNum, uint16_t opt1, uint16_t opt2, uint16_t opt3 );
```
A shorthand way of changing a setting for all the particles in a set, by calling one of the functions below.

propNum specifies the setting changed being changed:
- 0 -- The start positions of the particle (randomizes them).
- 1 -- The directions of the particles.
- 2 -- The speeds of the particles.
- 3 -- The size of the particles.
- 4 -- The trail types of the particles.
- 5 -- The particle's trail lengths.
- 6 -- The bounce property of the particles.
- 7 -- The palette color index of the particles (pass the palette length as opt2 to choose randomly from the palette).
The inputs opt1, opt2, and otp3 are used as the inputs for the setParticleSet() type functions in the same order as they appear in those functions. So check those functions for exact explanations of their inputs. Set any unused opt's to 0.

For example: setParticleSetProp(particleSet, 0, 100, 0, 0). Calls setParticleSetPositions() using 100 as the "max" value. opt2 and opt3 are not used.

Another example: setParticleSetProp(particleSet, 4, 1, 5, 2). Calls setParticleSetTrails() using 1 (opt1) as the trailType, 5 (opt2) as the trailSize, and 2 (opt3) as the range.
```
void setParticleSetStartPos( particleSetPS &particleSet, uint16_t partNum, uint16_t position, bool rand );
```
Sets a particle's (partNum) startPosition to the passed in value. If rand is true, the start position will be chosen randomly up to the passed in position. (generally use the segment set length as the position for rand). Note that to reset the particle's position to the new start position, you'll need to call resetParticle().
```
void setParticleSetDirection( particleSetPS &particleSet, uint16_t partNum, uint8_t direction );
```
Sets a particle's (partNum) direction to the passed in direction. To set the direction randomly, pass in a value >= 2.
```
void setParticleSetSpeed( particleSetPS &particleSet, uint16_t partNum, uint16_t baseSpeed, uint16_t range );
```
Sets a particle's (partNum) speed to the passed in baseSpeed (ms). The speed is varied by the random factor, range, ie speed = baseSpeed + random(range).
```
void setParticleSetSize( particleSetPS &particleSet, uint16_t partNum, uint16_t size, uint16_t range );
```
Sets a particle's (partNum) size to the passed in size. The speed is varied by the random factor, range, ie size = size + random(range).
```
void setParticleSetTrailType( particleSetPS &particleSet, uint16_t partNum, uint8_t trailType ); 
```
Sets the type of a particle's (partNum) trail. Passing in a trailType > 4 (the highest trail type) will force the trail to be chosen randomly from the first three trail types (0, 1, 2). If you want a specific set of trail types chosen randomly, use setParticleSetTrailRand().
```
void setParticleSetTrailSize( particleSetPS &particleSet, uint16_t partNum, uint8_t trailSize, uint8_t range ); 
```
Sets the length of a particle's (partNum) trail. The trailSize is varied by the random factor, range, ie trailSize = trailSize + random(range).
```
void setParticleSetBounce( particleSetPS &particleSet, uint16_t partNum, uint8_t bounce ); 
```
Sets a particle's (partNum) bounce behavior on the passed in bounce value. To set the bounce randomly, pass in a value >= 2.
```
void setParticleSetColor( particleSetPS &particleSet, uint16_t partNum, uint8_t colorIndex, bool randColor ); 
```
Sets a particle's (partNum) colorIndex to the passed in value. If you want the color to be randomly picked from a palette, pass in the palette's length as colorIndex and randColor as true.

Functions for More Trail Mode Control:

```
void setTrailRand( particleSetPS &particleSet, uint16_t partNum, bool noTrails, //
                  bool oneTrail, bool twoTrail, bool revTrail, bool infTrail ); 
```
Sets the type of a particle's (partNum) trail randomly according to the passed in flags. Each flag allows a trail type to be chosen randomly.

Flags:
- noTrails -- trail type 0
- oneTrail -- trail type 1
- twoTrail -- trail type 2
- revTrail -- trail type 3
- infTrail -- trail type 4
Example: setTrailRand( yourSet, 0, true, false, false, false, true ), would set the trail of particle 0 randomly to either trail type 0 or 4.

void setAllTrailRand( particleSetPS &particleSet, bool noTrails, //
                     bool oneTrail, bool twoTrail, bool revTrail, bool infTrail );

Calls the above setTrailRand() for all particles in the particle set, randomizing all their trails.

Functions for Getting Particle Colors:

```
CRGB getTrailColor( CRGB &color, CRGB &targetColor, uint8_t step, uint8_t totalSteps, int8_t dimPow ); 
```
Used in effects to calculate trail colors. Returns a color, blended towards the targetColor by the ratio steps / totalSteps. step == totalSteps is fully blended. Note that the function offset totalSteps by 1, so we never actually reach full blend. This was done to keep trail lengths consistent, because if we allow a full blend, the final trail color will be the targetColor, effectively shortening the trail.

dimPow (int8_t):

The blending is made non-linear using the dimPow adjustment. This allows you to adjust brightness of the trail vs the body of the particle, making the particles "pop" more. A dimPow of 0 will produce a normal linear gradient, but for more shimmery waves we can dial the brightness down. dimPow of 80 gives a good effect, and is the default in most effects. dimPow has a range of -128 to 128, negative values of dimPow decrease the blending (but seems to bug-out below -80). Negative values work well if your effect uses a colored background because it makes your particles standout more.

Functions for Deleting or Resetting Particles:

```
void resetParticle( particlePS *particle ); 
```
Resets a particle back to its starting position and sets its update time to 0.
```
void resetParticle( particleSetPS &particleSet, uint16_t partNum ); 
```
Resets a particle in a particle set back to its starting position and sets its update time to 0.
```
void resetParticleSet( particleSetPS &particleSet ); 
```
Resets all the particles in a particle set to their starting positions and sets their update times to 0.
```
void freeParticle( particleSetPS &particleSet, uint16_t partNum ); 
```
Frees the pointer to a particle in a particle set to free its memory. Should only be used if the particles was generated dynamically! You will probably only need to call this if you generated a particle set using buildParticleSet() above. Effects will handle the deletion of any particle sets they create.
```
void freeParticleSet( particleSetPS &particleSet ); 
```
Frees all the pointers in a particle set, ie the pointer to the particle array and all the pointers in the array, to free all a particle set's memory. Call when you're finished with a particle set that was created using buildParticleSet(). Effects will handle the deletion of any particle sets they create.
```
void freeAllParticles( particleSetPS &particleSet ); 
```
Like frees all the particles pointers like freeParticleSet(), but frees all particles up to the maxLength of the set's particle array. You probably won't need to ever use this, unless you're in deep with particles.

Other Functions:

```
bool getDirectStep( bool direction ); 
```
Used by effects to get direction multipliers based on a boolean input. Returns either 1 or -1. Uses the convention that true is forward (1) and false is backwards (-1).