Segment Set Class Notes - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Description:

This page contains the raw technical specs for segment sets for reference.

For a full description and tutorial of segment sets, see segment basics and advanced segment usage.

Constructor Definition:

SegmentSetPS(CRGB *Leds, uint16_t LedArrSize, SegmentPS **SegArr, uint16_t NumSegs);

Constructor Inputs:

CRGB leds -- The CRGB for storing color data for each LED. This is a FastLED thing. Should be the same array as used in FastLED.addLeds<Pixel Type, Data Pin>(leds, num of leds) in your code.
uint16_t ledArrSize -- The length of the Leds array. Usually NUM_LEDS if you're copying an example.
Segment segArr -- Pointer to the array of segments pointers that make up the segment set.
uint16_t numSegs -- How many segments are in the segment set (should be the length of the segArr).

Class Functions:

Note, these functions deal with the nitty-gritty of managing segments. With the exception of the direction getting/setting functions, and maybe setbrightness(), using these functions should be uncommon. Instead you should try to use the segment drawing functions here if possible.

You use these functions as you would any other class function, for example:

//Sets the direction of all the segments in the segment set to false
yourSegmentSet.setAllSegDirection( false );

Common Function Inputs:

segNum is a segment's position in the segment set segment array.
secNum is a section's position in a segment's section array.

Jump To Functions for:

Segment Direction Setting and Getting Functions:

```
bool getSegDirection( uint16_t segNum );
```
Returns the direction of the specified segment (bool).

void setSegDirection( uint16_t segNum, bool direct );

Sets the direction of the specified segment.

```
void flipSegDirects( void );
```
Flips the direction of all the segments in the segment set, ie all segments with direct = true become false, and visa versa.
```
void setAllSegDirection( bool direct );
```
Sets all the segments in the segment set to the specified direction.
```
void setSegDirectionEvery( uint8_t freq, bool direction, bool startAtFirst );
```
Sets the direction of every freq segment, starting with the first segment startAtFirst is true, skipping it if not.
```
void flipSegDirectionEvery( uint8_t freq, bool startAtFirst );
```
Flips the direction of every freq segment, starting with the first segment startAtFirst is true, skipping it if not.

Functions for Getting and Setting Segment Vars:

```
void setBrightness( uint8_t newBrightness );
```
Changes the segment set brightness (see brightness in reference vars below).
```
void resetGradVals( void );
```
Resets the color mode gradient length variables to their defaults.
```
uint16_t getTotalSegLength( uint16_t segNum );
```
Returns the totalLength of the specified segment, ie the total number of LEDs in the Segment.
```
uint16_t getTotalNumSec( uint16_t segNum );
```
Returns the total number of sections in the specified segment.
```
Segment getSegPtr( uint16_t segNum );
```
Returns a pointer to the specified segment object. Return type is a Segment.

Functions for Setting Reference Vars:

These functions set the core segment set reference values. They are called automatically when the segment set is created or when a segment is changed via setSegment(). If you ever change any of a segment's properties that are calculated by the functions below (mainly changing the segment's length by swapping around sections), you should call the relevant functions to re-calculate them. Also see the Changing Segments section on the "Advanced Segment Usage" page.

```
void calcSetVars(); 
```
Re-calculates all the the Segment Set's reference vars by calling the functions below ( setNumLines(), setNumLeds(), and setProgLengthArr() ).
```
void setNumLines();
```
Re-calculates the number of lines in the segment set. You only need to call this if you change what segments or segment sections are in the segment set.
```
void setNumLeds();
```
Re-calculates the number of LEDs in the segment set (taking account of any "single" sections). You only need to call this if you change what segments or segment sections are in the segment set.
```
void setProgLengthArr(); 
```
Fills in the segProgLengths array, see Reference Vars below.

Functions for Replacing Whole Segments:

```
void setSegment(SegmentPS &newSegment, uint16_t segNum);
```
Sets the segment in the set at segNum to the passed in newSegment. Also re-calculates the core segment set reference vars. See Changing Segments section on the "Advanced Segment Usage" page for more.

Functions for Getting Pixel Locations:

```
int16_t getSecLength( uint16_t segNum, uint8_t secNum );
```
Returns the length of the specified section in the specified segment. Will return 1 if the section is "single". Works for both continuous and mixed sections. Return type is int16_t.
```
uint16_t getSecStartPixel( uint16_t segNum, uint8_t secNum );
```
Returns the physical address of the first pixel in the specified section in the specified segment. (ie getSecStartPixel(0, 0) would return the address of the first pixel of the first section in the first segment in the segment set). (ONLY works for segments with continuous type sections!).
```
uint16_t getSecMixPixel( uint16_t segNum, uint8_t secNum, uint16_t pixelNum );
```
Returns the physical address of the specified pixel in a mixed section. (ONLY works for segments with mixed type sections!).
```
uint16_t getSecContArrPtr( uint16_t segNum );
```
Returns a pointer to the segment's secContPtr section array, returns null if there isn't one. Return type is segmentSecCont.
```
segmentSecMix getSecMixArrPtr( uint16_t segNum );
```
Returns a pointer to the segment's secMixPtr section array, returns null if there isn't one. Return type is segmentSecMix.

Functions for Handling "single" Segments: (See advanced segment usage)

```
bool getSegHasSingle( uint16_t segNum );
```
Returns true if the segment has any "single" sections.

bool getSecIsSingle( uint16_t segNum, uint8_t secNum );

Returns true if the specified section is "single".

```
int16_t getSecTrueLength( uint16_t segNum, uint8_t secNum );
```
Returns the real length of the section, ignoring if the segment is "single". Return type is int16_t.

Other Settings:

Color Mode Settings:

bool runOffset (default false) -- If true, then the gradOffset will be shifted over time at the offsetRate.
bool offsetDirect (default true) -- Sets the direction of any color mode gradients. True means the gradient starts at the beginnign of the segment set and moves towards the end, false is the opposite.
uint8_t val (default 255) -- HSV value for any color mode rainbows.
uint8_t sat (default 255) -- HSV saturation for any color mode rainbows.
uint8_t offsetStep (default 3) -- The number of steps gradOffset is increased by when it updates. Larger values make your gradient move faster.
uint16_t offsetRateOrig (default 30) -- The default target of the segment set's offsetRate pointer variable.
uint16_t offsetRate (default bound to offsetRateOrig) -- The speed in ms that gradient's move at (effects modes 4, 5, 9, 10 directly). Is a pointer. See pointers for more details.
uint16_t gradOffset (default 0) -- Offsets the starting step of any color mode gradients. Will change over time if runOffset is true.
uint16_t gradOffsetMax (default 256) -- The maximum value of gradOffset (+ 1), ie the number of gradient steps. ONLY APPLIES for custom gradients, rainbows are locked to 256 steps.
uint16_t gradLenVal (defaults to numLeds) -- The gradient length for linear color mode gradients.
uint16_t gradSegVal (defaults to numSegs) -- The gradient length for radial color mode gradients.
uint16_t gradLineVal (defaults to numLines) -- The gradient length for linear segment line color mode gradients.
palettePS gradPalette (defaults to the pre-built purple/green segDefaultPal_PS palette) -- The palette used for custom color mode gradients. See palettes. It is a pointer.

Brightness:

uint8_t brightness (default 255) -- Brightness of the segment set. Is set relative to the brightness the FastLED global brightness value (set by FastLED.setBrightness() ). At 255, the segment set's brightness is the same as the global brightness, at 127 it's half as bright, at 0, it's off. DO NOT use this in effects, it is meant as a set-up once type of control. Note that effect faders will change this value during fades (but should reset to the original value once finished). For more notes see advanced segment usage.

Reference Vars:

uint16_t segNumMaxNumLines -- The segment array index of the longest segment in the set. (ie the 0th segment in the array).
uint16_t numLines -- The length of the longest segment in the set. Set using setNumLines() or calcSetVars().
uint16_t numLeds -- The total number of pixels in the segment set (treating "single" sections as one pixel). Set using setNumLeds() or calcSetVars().
uint16_t segProgLengths -- Any array containing the combined lengths of all previous segments up to the current segment, arranged in segment order. For example, if we have 4 segments in the set, each with length 10, then the segProgLengths array would be {0, 10, 20, 30}. This is useful for calculating a pixel's location is relative to the whole segment set. Note that the array is allocated dynamically, and must be re-calc'd if you change any of the segments using setProgLengthArr() or calcSetVars(). It will be re-sized if the number of segment increases.
uint16_t offsetUpdateTime -- The last time (in ms) the gradOffset value was automatically updated.