Particle Struct Info - AlbertGBarber/PixelSpork GitHub Wiki

Overview:

A particle is a struct (particlePS) that represents a single moving pixel. A particle has a direction, speed, and can leave a trail that blends cleanly into the background color over the trail length (like waving a flame around, or a comet trail). Particles can be grouped together into a "particle set", which has its own properties. Keep in mind that each particle within a set has its own settings, so you can have sets of particles with varying trails, speeds, colors, etc.

Particles are used in a number of effects. While the effects usually create a set of particles for you, they sometimes give you the option of supplying your own set, which is handy if you're going for a certain look.

This page details both particles and particle sets, listing their settings while also providing working examples. To help manage particles, I have also written a set of helper functions. These can be found on the Particle Utils page.

Particle Trail Options:

Particles can have a number of different trails. The type of trail is set by the particle's trailType. Unless otherwise noted, any effects that use particles should have the trail options below.

trailType (uint8_t):

  • 0 -- No trails.
  • 1 -- One trail facing away from the direction of motion (like a comet).
  • 2 -- Two trails, coming from both sides of the particle.
  • 3 -- One trail facing towards the direction of motion.
  • 4 -- Infinite trails that persist after the particle, and are not faded.

For example, with a trail length of 4, and a body size of 1, the modes will produce: (The trail head is *, - are the trail, particle is moving to the right ->)

  • 0: *
  • 1: ----*
  • 2: ----*----
  • 3: *----
  • 4: *****

Particle Colors:

Particles get their colors from a palette. The particle's color is set by colorIndex, which is an index value of the palette (ie colorIndex 1 would be the color in the 1 index of the palette). In general, particles use the effect's palette for their colors.

The Particle Struct Properties:

Struct properties you must set (in order):

  • uint16_t startPosition -- Initial position of the particle on reset. Positions are generally local to the segment set, ie the a startPosition of 5 will be the fifth pixel in the segment set.

  • bool direction -- The direction of motion. "true" moves the particle positively along the segment set.

  • uint16_t speed -- The update rate of the particle (in ms). (Lower is faster)

  • uint16_t size -- The length of the main body of the particle (min 1).

  • uint8_t trailType -- The type of trail for the particle (see trail options above).

  • uint16_t trailSize -- The length of the trail(s) of the particle (min 1) (will be ignored if the pixel has no a trail).

  • bool bounce -- Sets if the particle wraps to the beginning of the Segment Set once it reaches the end, or if it reverses direction (it bounces). Not used in all effects.

  • uint8_t colorIndex -- All particles use a palette for color, this is the index of the color in the palette

Struct properties set automatically (not inputs):

  • uint16_t position (set to startPosition on creation) -- The current position of the particle in the segment set (local to the segment set!)

  • unsigned long lastUpdateTime (set to 0 on creation) -- The last time the particle was moved (ms).

Struct properties for decaying particles (not inputs), only used for certain effects:

  • uint16_t life (set to 3000 on creation) -- Usually the current life remaining for a particle in ms.

  • uint16_t maxLife (set to life on creation) -- Usually the starting life for a particle in ms.

Particle Creation Example:

To create a particle you must provide a value for all of the inputs listed above:

particlePS myParticle( 0, true, 50, 1, 2, 4, true, 0 );
/*  Creates a particle ,"myParticle" that starts a 0, 
    moving forward (direction is true) at a speed of 50ms.
    It has a body size of 1 and 2 trails of length 4
    It bounces at each end of the segment set, 
    and uses color 0 from whatever palette it's paired with. */

You can also create particles dynamically using malloc: particlePS *p = (particlePS *)malloc(sizeof(particlePS));. Be sure to fill in the particle properties before using it (including those that would normally be set automatically), and free() the particle when you are done with it.

Particle Sets:

A particleSetPS is a struct for holding an array of particles. Effects generally use whole sets, so you will usually manipulate sets rather than individual particles. I have written Particle Utils, which are a set of helper functions for working with particle sets. That being said, most effects build particle sets for you, so you may not ever need to mess with them directly.

Particle sets are composed of two components, a pointer to an array of particle pointers, and the length of the array. Usually it's easier to use the Particle Utils function buildParticleSet() to create a particle set, rather than create it directly. Once it's created you can adjust the particles either individually, or en-mass using helper functions.

The Particle Set Properties and Functions:

Variables:

  • particlePS** particleArr -- The pointer to an array of particle pointers.

  • uint16_t length -- The size of the particle array (number of particles).

  • uint16_t maxLength -- The maximum length of the particle array set. This used for Memory Management and should usually be set to the length when first creating a set.

Functions:

  • particlePS *getParticle( uint16_t index );

    Returns the pointer to a particle at the specified index. Note that the function wraps if your index is too large, so you always get a particle back.

  • void setParticle( particlePS *particle, uint16_t index );

    Sets particle in the array to the passed in particle at the specified index. Note that the function wraps if your index is too large.

Creating a Particle Set Manually:

As stated above, I highly recommend using the Particle Utils buildParticleSet() function to create particle sets because it greatly simplifies the setup.

To create a set manually:

particlePS *particleArr[] = { &particle1, &particle2, etc};
particleSetPS particleSet = {particleArr, SIZE(particleArr), SIZE(particleArr)};
//Creates a particleSetPS named "particleSet" using the particle array. 
//Note that this assumes you have already created your particles. 

//The second SIZE() is used to record the maximum size of the particle array for memory management.
//It should always be the same as the actual size of the array.