Color Modes - AlbertGBarber/PixelSpork GitHub Wiki

Jump to:

• Color Modes List.
• Segment Set Gradient Length Settings.
• Setting an Effect's Color Mode.
• Custom Gradients.
• Gradient Length Limits.
• Shifting Gradients Over Time.

Color modes are a special setting included in many effects. They replace the effect's colors with either a rainbow or custom gradient. See the images and gifs below for an example of the different color modes. You can also try out the modes yourself in the Color Modes code example.

Before continuing, you should be familiar with Segment Sets.

While color modes change the colors of an effect, how the color mode gradient is displayed depends both on the effect's segment set and what color mode is chosen. Most color modes work best with a 2D segment set.

The rainbow/custom gradient can be set to extend across the effect's segment set in four directions:

• Linearly across all the LEDs in the segment set, so that the rainbow gradient starts at the first LED and ends at the last.

• Radially, so that each whole segment is a single color from the rainbow gradient.

• Linearly, but using segment lines, so that each line is a single color.

• With time (4D?), so that the whole segment set is a single color, but that color cycles through the rainbow over time.

The images and gifs below show the four gradient types above, as applied to the 2D Disk segment set from the rings segment example. Please note that these show the whole gradient. When you use a color mode with an effect, the gradient is used for the effect's colors. In other words, whenever the effect colors an LED, it will use the color from the gradient in place the normal color.

Also note that the gradients in these images look a lot better in real life, the simulation cannot capture their transitions smoothly.

Color Modes 1 to 4 on a 2D Disk Segment Set
Linearly Across all LEDs (Rings Spiral Inward Clockwise)	Radial Gradient	Linearly Across Segment Lines	Gradient Varying with Time (gif)

Note that color modes work best for segment sets with multiple segments because you have more options for 2D gradients. For segment sets with a single segment, you can really only use a linear or time-based gradient (radial and gradients along segment lines will look the same as time based or linear gradients).

The gradient type is set in each effect using colorMode (or bgColorMode for the background pixels), while the length of the gradient and other variables are set in each segment set. Although this helps minimize the number of variables in each effect, it does mean that if multiple effects share the same segment set, their settings will overlap. You can always create a duplicate segment set with its own settings if needed!

To re-iterate: While the Color Mode is set in per effect, the Color Mode's gradient settings are controlled from within the effect's Segment Set, and will be shared between all effects using the Segment Set.

• gradLenVal -- The gradient length for linear gradients. Defaults to the number of LEDs in the segment set.

• gradSegVal -- The gradient length for radial gradients. Defaults to the number of segments in the segment set.

• gradLineVal -- The gradient length for linear segment lines gradients. Defaults to the length of the number of lines in the segment set (ie the length of the longest segment).

The defaults of each of these settings are set so that one whole rainbow fits across the segment set. You can reset to the default lengths at anytime by calling: yourSegmentSet.resetGradVals();.

Gradients can have any positive length you wish, up to 65535. For example, lets say your segment set has 50 LEDs, but you set its gradLenVal to 100. This means that only half the rainbow gradient would be shown. On the other hand, setting gradLenVal to 25 would make two rainbows. However, note that there are only a limited number of unique colors in any rainbow/gradient, increasing you gradient length past this limit will "stretch" out the gradient. See Gradient Limits below for more info.

For gradient lengths greater than the default lengths stated above, you can change the visible portion of the gradient using gradOffset (see Shifting Gradients Over Time below).

You can also change the rainbow's HSV saturation and value via the sat and val in the segment set. Both are defaulted to 255, producing a fully bright rainbow.

• *offsetRate and offsetRateOrig (default 30ms) -- offsetRate is the speed, in ms, at which the time-based gradient changes color. Note that offset rate is a pointer, by default it is bound to offsetRateOrig. Note that 256 steps will be used for the rainbow/gradient.

yourSegmentSet.gradLineVal = 50;    //Changes the gradLenVal (the gradient length for the linear gradient) to 50
yourSegmentSet.offsetRateOrig = 60; //Changes the offsetRate for the time-based gradient to 60ms

For a full list of gradient settings, see the Segment Set class wiki page.

There are 10 different Color Modes in total (5 unique modes doubled up for both rainbow and custom gradients). Each effect can use any color mode (if supported), although, as stated above, the length of each color mode gradient is tied to the effect's segment set.

Note that the modes come in pairs. Each pair does the same type of gradient, but the larger mode value will use the segment set's custom gradient palette for the colors (more on that below).

• 0 (default) -- No gradient is used; the effect uses colors as normal.

• 1 or 6 -- The rainbow/gradient is spread across all LEDs in the segment set. Uses the set's gradLenVal for length (defaults to the Segment Set's numLeds value).

• 2 or 7 -- The rainbow/gradient is spread across all segments in the set (each segment will be a single color). Uses the set's gradSegVal for length (defaults to the Segment Set's numSegs value).

• 3 or 8 -- The rainbow/gradient is spread across all segment lines in the set (each segment line will be a single color). Uses the set's gradLineVal for length (defaults to the Segment Set's numLines value).

• 4 or 9 -- A single color that cycles through the rainbow or gradient at the segment set's offsetRate. Note that, by default, 256 steps are used for the rainbow/gradient.

• 5 or 10 -- Same as mode 4 & 9, but the direction of the gradient is reversed.

To set the color mode for an effect, you change its colorMode variable:

yourEffect.colorMode = 1; //Change the colorMode to 1

Some effects also have a bgColorMode setting. This is exactly the same as the colorMode, but is applied to the effect's background pixels.

Each effect's wiki page will state if it supports color modes.

You also have the option of using a palette to create a custom gradient. Like with the gradient lengths, the gradient palette, gradPalette, is part of the segment set. Similar to other effect palettes, gradPalette is a pointer, by default, it is bound to the pre-built green/purple segDefaultPal_PS palette.

Gradient lengths (gradLenVal, gradLineVal, gradSegVal) apply just as they do for rainbow gradients, with gradient transitioning through the whole palette across the gradient length.

Note that using custom gradients is slightly more computationally heavy than using rainbow gradients.

In Pixel Spork and FastLED, a rainbow contains a maximum of 256 unique colors, so extending the gradient lengths past 255 will start to "stretch out" the rainbow into areas where its colors don't change. For example, setting gradLenVal to 510 (double 255) will stretch each rainbow color to occupy two pixels.

Custom gradients can have more than 256 unique colors depending on how many colors their palettes have and how different the colors are. By default, custom gradients are given 256 gradient steps, just like rainbows. These are spread equally between all the colors in the palette, so each color will have a gradient of 256 / (number of colors in the palette) steps. In my experience, 20+ gradient steps per color looks fine, so 256 should be enough for palettes with up to 13 colors (13 ~= 256/20). You can change the number of gradient steps by adjusting the segment set's gradOffsetMax (default 256) setting. This only applies to custom gradients!

Note that this doesn't apply to the time-based color modes: 4, 5, 9, 10.

Each segment set has a gradOffset variable (default value of 0). This sets a constant offset for rainbows and gradients by changing what gradient step each pixel is on. For rainbows there are 256 gradient steps, while the number of steps for custom gradients is set by gradOffsetMax (default 256) (see Gradient Limits above). For example, to shift a gradient half-way along your segment set, you would set gradOffset to 128 (256/2) for rainbows or gradOffsetMax/2 for custom gradients. This changes the first pixel to have a gradient step of 128, the next pixel, 129, etc. The gradient steps cycle back to 0 once they hit the final step, which causes the gradient to wrap.

By itself, gradOffset is only marginally useful. However, by varying it with time, you can create a flashy moving rainbow/gradient. Helpfully, this is already built into Pixel Spork.

Setting runOffset in your segment set to true will set your gradient to move at the segment set's offsetRate (see notes in overview ). By default, the gradient will move positively along your segment set, this can be changed by setting offsetDirect = false in the segment set (true is positive, false is negative).

The gradients are updated whenever an effect is updated (if it's using a color mode other than 0). This is great because you get cool shifting rainbows for very little extra code, but you can only shift gradients at the same rate as your effect updates. Most of the time that's fine, but occasionally you might want to speed up your gradients using the Segment Offset Cycler utility.

Check out the gif below to see the color modes 1-4 in motion as applied to the 2D Disk segment set from the rings segment example. Note that the gradients in these images look a lot better in real life, the simulation cannot capture their transitions smoothly.

Color Modes 1 to 4 in Motion on a 2D Disk Segment Set
Color Mode 1	Color Mode 2	Color Mode 3	Color Mode 4

To increase gradient speed you can:

• Change offsetStep (default 3, min 1, max 255) -- offsetStep controls how many steps gradOffset is increased by when it updates. Larger values make your gradient move faster. While a step value greater than 1 does make your gradient more "coarse", it divides the number of steps needed to cycle through the gradient (so at 3, the number of steps is 256/3 = 85). This greatly increases how quickly a gradient cycles, which makes it easier to pair up with typical effect update rates. In practice, at low step values the extra "coarseness" isn't noticeable.

• Use the Segment Offset Cycler utility class -- A utility class whose sole purpose is to update the gradOffset of either a single or group of segment sets at a set rate. This is more heavy-handed than just changing the offsetStep, but gives you finer control, and allows you to control multiple segment sets together.

For a full list of gradient settings, see the Segment Set Class wiki page.