Utility Classes Basics - AlbertGBarber/PixelSpork GitHub Wiki

Note that all the utilities discussed on this page are class based, if you are looking for standalone utility functions, general utils, color utils, math utils, segment functions, pattern functions, or palette functions are where to look.

Jump To:

• Intro and Types of Utility Classes
• Creating Utility Classes
• Updating Utilities
• Using Utilities

Utility classes are helpers for your effects or overall program. They usually serve to enhance or manage some aspect of your effects. For example, the Palette Cycle utility allows you to smoothly blend between a set of palettes, changing your effect's colors over time.

While they are not effects themselves, utility classes behave very similarly, they even inherit from the same base effect class (this allows you to use them as part of an Effect Set). Like effects, all utilities have have an update() function, an update rate, and are created using a class constructor.

However, most utilities do not draw anything, so they don't require a Segment Set, and will ignore the showNow setting (but use active instead, see "Updating Utilities" below for more).

Utility classes usually fall into one of the following categories:

• Palette utility classes: These utilities usually take single or multiple palettes and change them over time, outputting a new palette. For example, a Palette Blender takes two palettes and creates a new palette that shifts from one palette to the next over a set time period.

• Effect Utilities: These utilities help manage and control effects. For example, Effect Sets group multiple effects together allowing you to update and control them all at once.

• Rate Utilities: These utilities help control effect update rates. For example, Rate Randomizer, produces a random output rate that changes at set intervals. Useful for adding some variation to effects!

• Drawing Utilities: These are basically full on effects, but they are either intended to be used along side effects, or are designed for testing effects or segment sets. For example, Add Glitter adds random sparkles to other effects, while Segment Set Check helps you visually check your segment set layout. Note that, unlike other utilities, these do require a Segment Set for drawing and use the showNow setting.

• Other/General Utilities: Anything that doesn't fit into the above categories. Probably modifies a specific effect or segment set variable.

Note that each utility is explained in detail on it's own wiki page; listed in the slide-bar on the right-hand side of this wiki page, organized into the sub-categories: Palette Utility Classes, Effect Utility Classes, Drawing and General Utility Classes, and Update Rate Utility Classes.

You create a utility class instance in much the same way as you would an effect.

Lets run through a quick example:

Note that this example mirrors the effect example in effect basics, so if you've read that, you can skip this.

Lets create a Palette Blender utility to constantly blend between random palettes over time:

//Create two palettes with random colors, one with 3 colors and one with 2
CRGB palette1_arr[] = { colorUtilsPS::randColor(), colorUtilsPS::randColor(), colorUtilsPS::randColor()};
palettePS palette1 = {palette1_arr, SIZE(palette1_arr)};

CRGB palette2_arr[] = { colorUtilsPS::randColor(), colorUtilsPS::randColor()};
palettePS palette2 = {palette2_arr, SIZE(palette2_arr)};

PaletteBlenderPS paletteCycle1(palette1, palette2, true, 50, 100);

//Put in the Arduino Setup() function
paletteCycle1.randomize = true;

After creating two random palettes, we create a PaletteBlenderPS instance named paletteCycle1. The instance name can be anything you like. The arguments in brackets, (palette1, palette2, true, 50, 100), specify the options for the utility, including what palettes it will use, how quickly the it updates, and etc. The number and types of arguments correspond to one of the utility's constructors (utilities can have multiple constructors with different sets of options for different situations). The final line of the setup is explained after the constructor explanation below.

You can have as many instances of an utility as you like (as long as you have enough memory). They would all be unique from one another, having their own settings, and being updated independently. For example, you could have two PaletteBlenderPS utilities, called PB1 and PB2. Both instances would operate independently, having no attachment to one another.

In the example above, we were using this constructor from PaletteBlenderPS:

PaletteBlenderPS(palettePS &StartPalette, palettePS &EndPalette, bool looped, uint8_t TotalSteps, uint16_t Rate);

You can match up the arguments with those in the example above, so our paletteCycle1 will blend from palette1 to palette2 using 50 blend steps with a 100ms wait between each step. It is set to loop, so once it the blend has finished, the utility will reset, blending back from palette2 to palette1 (and then will reset again, etc).

In the final line of the above example, we set paletteCycle1's randomize setting to true, which will randomize the palette colors after each blend. Since this needs to be executed during runtime, we need to place it in the Arduino Setup() function (it could also go in the Loop() function, but we only need to set it once). Changing some utility settings may require a function call, or changing a pointer address. This is the same as for effects, which you can read about here.

Each utility is explained in detail on its own wiki page, including what the utility does, its constructors, settings, etc. It also includes pre-filled constructor examples to help get you started.

All utilities have an update() function.

Using the above example, to update our paletteCycle1, we would call:

paletteCycle1.update();

Note that the utility updates at its update rate (100ms in our example). This means that whenever we call update() the utility checks if 100ms have passed since the previous update. If so, then the utility updates, if not, then the update is skipped.

Note that, because utilities do not draw (unless otherwise noted), they ignore the showNow setting. In place of showNow, utility classes have the active boolean setting. If false, the utility will be entirely blocked from updating. This is handy for quickly "switching off" utility classes.

There are some additional tricks when working with multiple utilities and effects, read about them on the Effects Advanced page.

Utilities generally come in two flavors; either they produce some variable or object, which you can use in effects, or they perform some action, such as adding glitter to you effects, updating a set of effects, etc.

For utilities that perform an action, using them is usually as simple as updating (update()) them.

For utilities that produce a specific variable or object, you'll need to use their object in your effects. For example, PaletteBlenderPS, produces a new palette, blendPalette, that is the blended result of the two input palettes.

To use this new palette in an effect (assuming the effect uses a palette) we would:

<yourEffect>.palette = &paletteCycle1.blendPalette;

Note that I'm assuming the effect's palette is a pointer, as is usually the case.

Each utility's wiki page will tell you what it produces, and how to use it.