Effect Documentation Notes - AlbertGBarber/PixelSpork GitHub Wiki

Intro:

This is a guide to understanding the wiki's documentation for effects, utilities, and other classes. Whenever you go to an effect/utility/etc's wiki page you'll be presented with the sections below. Each section explains a different part of the class, giving you all the information you need to use it.

Class Description:

This is a general description of the effect/utility/etc, and will usually include any additional notes or gotchas you should be aware of.

Inputs Guide:

This section is used in more complex effects to explain how the effect settings influence the effect's output. I generally include this section if I feel that understanding the settings is critical to controlling the effect.

Example Calls:

This section will list a declaration(s) of the effect class in real, usable code. The intent is that you can copy-and-paste this code to test the effect without having to read/understand all the inputs. I usually include an example for each unique constructor, as well as a brief description of the arguments, and how they will influence the final effect.

For example, with Rainbow Cycle, an example call is:

RainbowCyclePS rainbowCycle(mainSegments, 30, true, 80); 
//Will draw rainbows of length 30, moving towards the end of the SegmentSet (direct is true), at 80ms

Place this code before the Arduino setup() function; it creates an instance of RainbowCyclePS called rainbowCycle. You can then update the effect by calling rainbowCycle.update(); in the Arduino loop().

The commented description below the example gives you information about how the effect will look, specifically about what each input is doing. The text should be in the same order as the inputs so you can match the inputs up to what they do. In the rainbowCycle example above, the text follows the constructor inputs, stating the length, direction, and update rate (30, true, 80). Hopefully this helps you if you want to tweak the effect's inputs.

Note that I always use mainSegments as the Segment Set for the example calls. In my code, and the library code examples, mainSegments is always a 1D Segment Set that arranges the LEDs to replicate how they are physically connected. ie:

//NUM_LEDs is the total number of LEDs in your strip
const PROGMEM segmentSecCont mainSec[] = { {0, NUM_LEDs} }; //Create a single segment section containing all the LEDs in the strip in order
SegmentPS mainSegment = { mainSec, SIZE(mainSec), true }; //Create a segment for the single section
SegmentPS *main_arr[] = { &mainSegment }; //Create the segment array for the single segment
SegmentSetPS mainSegments( leds, NUM_LEDs, main_arr, SIZE(main_arr) ); //Final segment set definition, leds is your FastLED led array.

Also note that if the effect requires a palette, the built-in cybPnkPal_PS palette will be used (see built-in palettes), but you are free to substitute your own. The same is true for any patterns, with a default example pattern of {0, 2, 1} being used.

Constructor Definitions:

This section lists all the possible class constructors for the effect.

Effects can have a lot of variables that influence how the effect looks, but sometimes you just want to fire up something quickly, without going though all the inputs, or not all the inputs are required for a certain effect mode. So, I try to provide a few constructors with a range of complexities. Each constructor will have a note describing it.

Using Rainbow Cycle as an example again, I include two constructors, one omitting the length argument (defaulting it to 255):

//Using a default rainbow length of 255:
RainbowCyclePS(SegmentSetPS &SegSet, bool Direct, uint16_t Rate);
        
//Adding length as an input:
RainbowCyclePS(SegmentSetPS &SegSet, uint16_t Length, bool Direct, uint16_t Rate);  

Usually any omitted variables will have some default value, or be set automatically in some other way, which will be indicated in the following sections.

Constructor Inputs:

This section lists all the possible constructor arguments along with a description of what the argument does. An argument tagged with (optional) means that it isn't needed in at least one constructor.

Most constructor arguments are also variables within the effect, which you are usually free to adjust after the effect is created. While I don't explicitly state what arguments are effect variables, it is usually fairly obvious; there will probably be functions for adjusting anything that isn't an effect variable.

For example, using the rainbowCycle instance from the Example Calls above, you could add rainbowCycle.direct = false; to your Arduino setup() or loop() to reverse the rainbow's movement direction.

Other Settings:

This section lists any other effect variables that are not included in the constructors. They will have a default value listed, along with a short description of their purpose. Usually these are lower priority variables, that you may only need to change in specific circumstances. They can usually be changed freely while the effect is running unless otherwise noted.

Class Functions:

This section lists the functions you can call after the effect has been created, along with a short description of what the function does. Usually they change a single or set of effect variables to change the effect.

For example, the Rainbow Cycle has a function: setLength(uint16_t newLength), which changes the rainbow's length.

Using the rainbowCycle instance from the Example Calls above, you could add rainbowCycle.setLength(30); to your Arduino setup() or loop() to reverse the rainbow's length to 30 from 255.

Reference Vars (read-only):

This section lists public read-only variables that may be useful for monitoring the effect. Some of these variables may be repeated from the Constructor Inputs, they are the same variable.

DO NOT change these variables directly. Doing so may cause your program to crash.

If a variable is adjustable, it will have an accompanying function to change it.

Flags (read-only):

This section lists public variables that are set by the effect after certain actions have been done. These are more common for Effect Utility Classes. For example, an EffectFaderPS will set its done flag to true once it has finished a fade.

These should not be set manually unless you know what you're doing.

Final Note:

While I always try to fully explain an effect/utility/etc class, some classes can be very complicated. If you are finding an class hard to understand, I encourage you to look at the class's code in the library files. The code should be fully commented, and may help you understand how the it works. Each class is stored in its own labeled folder within the library files (effects are in the "Effects" folder, Segment Sets in the "Segment_Stuff" folder, etc).