Common Effect Variables and Functions - AlbertGBarber/PixelSpork GitHub Wiki

Common Variables and Functions:

While each effect and utility is different, there are some frequently repeated settings and functions, which I will group together here (rather than repeating them on every wiki page). Using common variable names should also help you understand an effect faster.

Jump To Common:

Common Variables:

  • SegmentSet *segSet -- Every effect (and a few utilities) has a segSet pointer variable. It is bound to the Segment Set supplied during the effect's construction. In general, you won't need to interact with this variable unless you want to replace the effect's Segment Set, or need to access the Segment Set via the effect, which should be uncommon. Below are some example interactions.

    Note that segSet is a pointer so any changes made to the Segment Set will be shared with any other effects also using the Segment Set.

    //Set a property of an effect's segment set to some hypothetical variable, "x"
yourEffect.segSet->someSegmentSetProperty = x;
//Change the Segment Set your effect is using
//(note that you may need to reset() an effect if you change its segment set, check the effect's wiki page!)
yourEffect.segSet = &newSegmentSet;

  • bool showNow (default true) -- All effects have this setting (and any utility classes that draw directly). If false, then the effect will be updated as normal, but it will skip displaying the physical pixels (the color data is still written to FastLED's led color buffer array, but it does not call FastLED show()). Useful for limiting writes if you have multiple simultaneous effects. For more info on multiple effects, see here.

  • uint16_t *rate and rateOrig -- rate sets the effect's update interval in ms. Every effect and utility has a rate. Note that the rate is a pointer, so that you can tie it to an external variable. By default it is bound to the effect's local variable, rateOrig, which is set during effect construction. The binding is explained in more detail in this pointer examples.

  • palettePS *palette -- This is the set of colors that an effect will use when drawing. See palettes for more info. Note that the effect palette is almost always a pointer. Usually a palette is either supplied by you as part of the constructor, or is automatically assembled by the effect. In the former case, the effect's palette pointer will bound to your input palette, like in this pointer example. If the palette is created by the effect, the palette pointer will be bound to the effect's local palette, paletteTemp.

  • patternPS *pattern -- Is a pattern used for drawing the palette colors. See patterns for more info. Note that the effect pattern is almost always a pointer, and is treated just like palettes above, ie the pointer is either bound to a pattern you supply, or to a local patternTemp.

  • CRGB bgColor and bgColorOrig -- bgColor is the background color for an effect. Note that the bgColor is usually a pointer. This allows you to bind it to an external color variable, such as one in a palette. By default it's pointed to the color variable, bgColorOrig, in the effect. bgColorOrig is set during the effect's creation to the CRGB BgColor in the effect's constructor.

    They are bound like so:

    bgColorOrig = BgColor; //Set bgColorOrig to the CRGB BgColor supplied in the effect's constructor   
bgColor = &bgColorOrig; //Bind the bgColor pointer to bgColorOrig

    To change the bgColor, you can either change the bgColorOrig:

    yourEffect.bgColorOrig = newColor;

    Or change where it points to:

    yourEffect.bgColor = &newColor;

    Hint: you can use the "getColorPtr()" and "splitPalettePtr()" functions in Palette Utils to use one color from a palette for the background and the rest for the effect colors.

  • uint8_t colorMode and bgColorMode (default 0) -- Sets the Color Mode that will be used with either the drawn or background pixels. A lot of effects have these settings. The default of 0 means the effects will just use colors as they normally would (from a palette, chosen at random, etc). These settings are rarely included in an effect's constructor, so you'll have to set them separately.

  • bool fillBg (usually default false) -- Some effects only modify a small number of pixels at a time. This is helpful for keeping the program fast, but in some cases, particularly when using an animated background via a Color Mode, you want to re-draw all the pixels. Setting this true will fill in all the pixels every update cycle. Note that for large amounts of pixels, this may decrease performance.

  • uint8_t randMode (or similar, default 0) -- Sometimes an effect will have multiple ways for choosing colors, which will usually be selected by a mode value. The effect wiki page will have a list of the modes, but usually 0 will draw the effect as normal, 1 will use completely random colors, and 2/3 will pick colors from the palette at random (if there is one).

  • uint16_t pauseTime and bool paused (default 0 (ms) and false) -- Mostly used in Utility Classes. Will pause the effect for pauseTime milliseconds (ms) after the effect has finished some action, at which point the paused flag will be set true. For example, the Palette Blender utility has an optional pauseTime that starts once it has finished blending from one palette to the next, once the pause time is over, the blender will start blending to the next palette.

  • bool active (default true) -- Currently only used in utility classes. If false, the utility will be entirely blocked from updating. This is handy for quickly "switching off" utility classes. Note that this is not the same as the showNow from above. showNow allows effects to update, but blocks them from drawing, while active skips the update altogether.

  • uint16_t or uint8_t numCycles (or similar) -- This is usually a reference variable that tracks how many update cycles an effect has completed.

  • uint8_t sat and val (both default 255) -- These variables are used in effects with rainbow modes, but can also be found in Segment Sets for tuning Color Modes. They set the HSV "value" and "saturation" for the effect's rainbow colors. Both are always defaulted to 255, creating a typical rainbow.

Common Functions:

  • SIZE( <an array> );

    This a macro (not a real function) used to determine an array's length automatically at compile time. It is commonly used when creating structs, such as palettes, patterns, etc. Using SIZE() makes our code easier to adjust in the future. For example, lets say we were creating a palette:

    CRGB rgbPal_arr[] = { CRGB::Red, CRGB::Green, CRGB::Blue }; //create an array of CRGB colors
palettePS rgbPalette = { rgbPal_arr, SIZE(rgbPal_arr) }; //Create the palette using the CRGB array and the array's length

    The palettePS struct takes an array of colors and the array's length as inputs. To prevent bugs, the length input should always equal the number of colors in the color array. However, lets say, that instead of using SIZE(), we used "3", for the length input. This is correct for the example above, but in the future, if we ever edit our code and change the number of palette colors, we must remember to update the length as well. A mismatch would not be caught by the compiler, it's entirely on you to change it. On the other hand, SIZE() places and changes the length automatically, removing any human error.

  • void setPaletteAsPattern();

    Only featured in effects that use patterns. Sets the effect pattern to match the current effect palette. For example, for a palette length 5, the pattern would be {0, 1, 2, 3, 4}, which is each color in the palette in order. The pattern is usually stored in the effect's patternTemp pattern variable (see pattern var notes above). Note that patternTemp will be allocated dynamically, re-sizing only if the current pattern isn't big enough to match the palette. This is only relevant if you plan to change palettes during runtime, and helps prevent memory fragmentation. You can read more about that here.

  • void setPatternAsPattern(patternPS &inputPattern, uint16_t colorLength, uint16_t spacing);

    Featured in some pattern-based effects. It serves as a shorthand for making a longer pattern out of a smaller input pattern. Uses an input pattern to shape the effect's pattern with set color length and usually a spacing. The spacing value is usually 255. An example should make this more clear:

    Example using a pattern of {0, 2, 1} in our input pattern:

    void setPatternAsPattern(inputPattern, 2, 3);

    Results in an effect pattern of { 0, 0, 255, 255, 255, 2, 2, 255, 255, 255, 1, 1 }. This is the values from the pattern, repeated colorLength (2) number of times with spaces (marked as 255) of length spacing (3) between each pattern value. Spaces are usually set to the effect's background color.

    The pattern is usually stored in the effect's patternTemp pattern variable. Note that patternTemp will be allocated dynamically, re-sizing only if the current pattern isn't big enough to match the output pattern. This is only relevant if you plan to change patterns during runtime, and helps prevent memory fragmentation. You can read more about that here.

    Finally, remember that the pattern length is limited to 65,025 (uint16_t max), so make sure your (colorLength + spacing) * <num palette colors> is less than the limit.

  • void reset();

    Usually calling this function restarts the effect from the beginning.

A Common Struct:

Unlike in many newer programming languages, arrays in C simply consist of the array itself, and don't store any extra information, such as the array's length. This makes passing the arrays to functions and classes somewhat annoying because you need to pass the array and its length as separate arguments.

In Pixel Spork, rather than using arrays directly, I typically use a struct consisting of a pointer to the array, and the array's length.

A generic setup is shown below:

struct myStruct {
  uint8_t *structArr; //pointer to an array of uint8_t's 
  uint8_t myArrayLength; //The array's length
} ;

The struct can be passed to functions and classes, giving them access to the array and its length in one package. Note that I use a pointer to target the array, which keeps memory low by keeping the struct small (only storing the array's address) and ensures that there's only one copy of the array for the whole program, rather than a new copy for each struct.

You'll see this kind of structure repeated numerous times for palettes, patterns, etc.

To create an instance of the struct you would:

uint8_t myArray[] = { 1, 2, 3 }; //Create an array of uint8_t's
myStruct newStruct = { myArray, SIZE(myArray) } //Create the struct using the array and its length

Where the first line creates an array of uint8_t's, and the second creates the struct, newStruct, by tying the struct's structArr to myArray's address and setting the length equal to the array's length.

Note that we are using the SIZE() macro to automatically set the array length.

Warning: if you need to create a struct before you've created the array, use nullptr for the array's address and 0 for its length, ie { nullptr, 0 }. This will help prevent and catch bugs.

Usually access to the struct's members will be provided by helper functions, but you can access them directly like:

myStruct.structArr[0] = 5; //set the value of the 0th array member to 0
uint8_t len = myStruct.length; //Store the struct's length in "len"

Note that some structs will also include an additional maxLength variable. This is used to help manage memory. You shouldn't ever need to interact with it.

⚠️ **GitHub.com Fallback** ⚠️