Twinkle Star Struct Info - AlbertGBarber/PixelSpork GitHub Wiki

Overview:

A Twinkle Star (twinkleStarPS) is a struct that represents a single fading pixel. The struct holds various info about the twinkle, including its location, the color it will fade to, how many steps it takes to fade in and out, etc. Currently, Twinkles are used in the Twinkle 2 effect. That effect creates Twinkles for you, so there's not much reason to read this page unless you are interested in creating your own effect using Twinkles.

Twinkles are usually grouped in to a Twinkle Set (see below).

This page details both Twinkles and Twinkle sets, listing their settings while also providing working examples.

The Twinkle Star Struct Properties:

Struct properties you must set (in order):

uint16_t location -- The location of the twinkle local to the segment set (not the pixel's physical address).
CRGB color -- The color that the twinkle will fade to.
uint8_t fadeInSteps -- The number of blend steps the twinkle will use to fade to its color.
uint8_t fadeOutSteps -- The number of blend steps the twinkle will use to fade from its color to a background color.

Struct properties set automatically (not inputs):

uint16_t stepNum (set to 0 on creation) -- The current blend step of the twinkle.
bool active (set to false on creation) -- Tracks if the twinkle is "active". An active twinkle is currently fading in/out. An inactive twinkle has faded out and is waiting to be active again.

Twinkle Creation Example:

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

twinkleStarPS myTwinkle( 0, CRGB::Red, 5, 4 );
/*  Creates a twinkle, "myTwinkle" with a location of 0.
    The twinkle's color is red.
    It had 5 fade in steps and 4 fade out steps. */

You can also create twinkles dynamically using malloc: twinkleStarPS *t = (twinkleStarPS *)malloc(sizeof(struct twinkleStarPS)). Be sure to fill in the twinkle properties before using it (including those that would normally be set automatically), and free() the twinkle when you are done with it.

Twinkle Sets:

A twinkleSetPS is a struct for holding an array of twinkles. Effects generally use whole sets.

Twinkle sets are composed of two components, a pointer to an array of twinkle pointers, the current length of the array, and the maximum length of the array.

Because twinkle sets are usually allocated with dynamic memory, the maximum length is used to track the overall memory size of the set, so that it can be re-sized without having to reallocate the memory. See Memory Management for more details. The current length of the array represents the number of particles an effect is currently interacting with.

You can manipulate twinkle sets as you would any other struct, for example:

<<yourTwinkleSet>>.twinkleArr[0]->color = CRGB::Red; //Sets the color of the first twinkle in the set to red.
uint16_t length = <<yourTwinkleSet>>.length; //Gets the length of your twinkle set.

The Twinkle Set Properties and Functions:

Variables:

twinkleStarPS** twinkleArr -- The pointer to an array of twinkle pointers.
uint16_t length -- The current size of the twinkle array (number of twinkles).
uint16_t maxLength -- The maximum length of the twinkle array set. This used for Memory Management and should usually be set to the length when first creating a set.

Functions:

```
void setTwinkle( twinkleStarPS *twinkle, uint16_t index ); 
```
Sets twinkle in the array to the passed in twinkle at the specified index.
```
void reset();
```
Sets all twinkles to be inactive and their fade stepNum to 0 (doesn't touch their location b/c there's no "neutral" location).
```
void deleteTwinkleSet();
```
Frees the memory of the twinkle set by freeing all the twinkles and the twinkle array. Should only be use if the twinkle set was dynamically allocated (ie using malloc() or "new")

Creating a Twinkle Set:

To create a set manually:

twinklePS *twinkleArr[] = { &twinkle1, &twinkle2, etc };
twinkleSetPS twinkleSet = {twinkleArr, SIZE(twinkleArr), SIZE(twinkleArr)};
//Creates a twinkleSetPS named "twinkleSet" using the twinkle array. 
//Note that this assumes you have already created your twinkles. 

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

To create a set dynamically:

//Make a array of twinkles and a twinkleSet 
twinkleStarPS twinkleSet = {nullptr, 0, 0}; //Must init structs w/ pointers set to null for safety
twinkleStarPS **twinkleArr = nullptr;

//Allocate memory for the twinkles and the set
//numTwinkles is the number of twinkles your set will have
uint16_t numTwinkles = 5;
twinkleArr = (twinkleStarPS **)malloc(numTwinkles * sizeof(twinkleStarPS *));
twinkleSet = {twinkleArr, numTwinkles, numTwinkles};

//Create the individual twinkles and put them in our set
for( uint16_t i = 0; i < numTwinkles; i++ ) {
        twinkleStarPS *t = (twinkleStarPS *)malloc(sizeof(struct twinkleStarPS));
        twinkleSet.setTwinkle(t, i);
        
        //Because our twinkles are created dynamically, they don't have any properties
        //so we'll set some for each one (these will probably be set again when the twinkle spawns)
        twinkleSet.twinkleArr[i]->location = 0;
        twinkleSet.twinkleArr[i]->color = CRGB::Red;
        twinkleSet.twinkleArr[i]->fadeInSteps = 5;
        twinkleSet.twinkleArr[i]->fadeOutSteps = 5;   
}

twinkleSet->reset(); //sets all the twinkles to inactive and their blend step to 0.

//Remember to call twinkleSet.deleteTwinkleSet(); once you are finished with it!!!