Section Struct Notes - AlbertGBarber/PixelSpork GitHub Wiki

Description:

Sections are structs that store the locations of groups of pixels. Multiple sections can be arranged to form a segment, and then multiple segments can be arranged to form a segment set.

This page contains the raw technical specs for sections for reference.

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

There are two types of section: continuous (segmentSecCont), and mixed (segmentSecMix). A segment can only use one type of section. Both section types store pixel locations, but in slightly different ways, allowing you to optimize your segments for speed, memory usage, and readability.

The maximum number of pixels (length) in either section is 32,767.

Note that sections are stored in program memory, and so cannot be changed once a program is running.

Continuous Sections:

Continuous sections should be used to represent unbroken lengths of pixels. For example, if you wanted to split a LED strip into halves, you would use two continuous sections, one for each half.

Continuous sections are a struct containing a starting pixel (uint16_t startPixel), a length (int6_t length), and a bool for "single" sections (defaulted to false, see advanced segment usage).

The start pixel is where the section starts, and the length is how long the section is.

For example:

const PROGMEM segmentSecCont mySec = {0, 20};

Creates a continuous section named mySec starting at LED 0, and running for 20 LEDS, ending at LED 19. The bool for the "single" section setting optional, and will default to false if omitted.

Because sections are stored in programming memory, accessing their variables is more involved than with other structs. I recommend using the pre-built segment drawing, segment, or segment set functions for data access.

Continuous section lengths can be negative to cover cases where a length of LEDs is physically facing the wrong way from the rest of the segment (yes, I've run into this! Check out my infinity dodecahedron). To create a "reversed" section, set the start pixel to the end of the section, and use a negative length value. IE a section starting at LED 19, with a length of -20 would end at LED 0.

Mixed Sections:

Mixed sections are used to store a length of non-continuous pixels. For example, if you wanted to group LEDs 1, 5, 8, and 9 into a section, you would use a mixed section.

Mixed sections are a struct containing an pointer to an array of LED locations (uint16_t* pixArr), a length (uint16_t length), and a bool for "single" sections (see advanced segment usage).

The array of LED locations contains the physical positions of the LEDs arranged in whatever order you want. The section's length is the length of the LED array.

For example:

const PROGMEM uint16_t mySecMix_arr[] = {0, 2, 1};
const PROGMEM segmentSecMix mySec = { mySecMix_arr, SIZE(mySecMix_arr) }; //SIZE() gets the length of the array (3)

Creates a mixed section, mySec, of length 3, containing LEDs 0, 2, and 1 in that order. The first line creates the array of LED locations, while the second creates the mixed section using the array and its length. Note that we use the SIZE() macro to automatically get the length of the array.

For this section, the first LED is 0, the next is 2, and 1 is last.