Palette Single Cycle - AlbertGBarber/PixelSpork GitHub Wiki

See the Documentation Guide for help understanding each page section.

Utility Cycling Through cybPnkPal_PS Palette on Streamer Effect (palette colors are moving backwards) (see here for Segment layout info)

A utility class that takes an input palette and produces an output palette that shifts the input's colors over time. For example, you could shift all of the inputs palette's colors forward over time, cycling their position in the palette. There a variety of "blend modes" for configuring how the palette colors are shifted. Importantly, the input palette is not modified by this utility, all the color shifts are tracked within the utility. Likewise, the input palette can be changed at will (although the changes will be delayed s the blends are processed).

See Palette Basics for info about palettes.

The utility's blended output palette is stored locally as cyclePalette. Its length and number of colors will be set according to the "blend mode" (see below).

cyclePalette is a pointer, so passing it to effects is a little different than a normal palette:

//Sets an effect's palette to your palette blender's output palette
//Note that this assumes that the effect's "palette" var is a pointer (true in most effects)
yourEffect.palette = yourPaletteSingleCycle.cyclePalette;

You can also pass *yourPaletteSingleCycle.cyclePalette as part of the effect's constructor.

Controls how the input palette's colors will be shifted for the output palette. Set using blendMode. Examples below use a palette of {blue, red, green}.

• 0 -- Cycles the entire palette forward/backward by one step each cycle. ie for direct = true, {blue, red, green} => {green, blue, red} => {red, green, blue}, etc.

• 1 -- Like mode 0, but a random color is inserted at the beginning (end if direct is false) each cycle, (initially starts as the input palette). ie for direct = true, {rand1, red, green} => {rand4, rand1, red} => {rand5, rand4, rand1}, etc, where "rand#" are random colors.

• 2 -- Randomizes the whole palette each cycle for a palette. With 3 random colors: {rand1, rand2, rand3} -> {rand4, rand5, rand6}, etc, where "rand#" are random colors. direct has no effect.

• 3 -- Shuffles the input palette each cycle. ie {blue, red, green} could go to {red, blue, green}, or {blue, green, red}, etc. Note that the same palette order can repeat, the likely-hood depends on the palette length. DO not use this for a palette with only 2 colors!. direct has no effect.

• 4 -- Makes the output palette a single color, cycling through each color in the input palette. ie for direct = true and an input palette of {blue, red, green} the output will be {blue} => {red} => {green} => {blue}, etc.

• 5 -- Same as mode 4, but chooses the next color randomly from the input palette (will not be the current color). direct has no effect.

• 6 -- Same as mode 4, but the next color is chosen completely randomly (not from the palette). direct has no effect.

For blend modes 0, 1, 2, 3 the output palette length will be the same as the input. For modes 4, 5, 6 the output palette length will be 1.

• The blend is always looped, so it will repeat indefinitely.

• You can have the blend pause either at the beginning or end of each palette blend, with a configurable pause time, pauseTime. This is mainly used when looping. When paused, the palettes will not be blended, giving you time to reflect/absorb the current palette (and effect) colors, before cycling to a new palette.

• The blend modes can be changed mid-cycle, along with the input palette, but the new palette will be blended in over time. To force a new palette, you can call reset(). Note that changing the blend mode may change the output palette's length, see "Blend Modes" above. Be aware that this may break some effects if they don't adjust for the palette length changes during updates. This is also true if you change the input palette for blend modes where the input and output palettes are the same length (0, 1, 2, 3). The easiest way to check this is to test your effect.

• Some blend modes have a direction setting (direct), which controls the direction the palette colors are shifted. If direct is true the color will shift forward, so color 0 becomes color 1, etc and visa versa if direct is false.

• You can track what blend stage you're on using cycleNum. This resets every input palette length number of cycles.

• The utility uses an instance of the Palette Blender utility to do the blends, automatically swapping palettes and resetting it in the background for the cycle. The instance is created dynamically as part of the utility's construction. It is public and can be accessed as PB. Some utility settings must be changed in the blender instance directly. I mostly provide pass-through functions for changing these settings, but any missing settings can be accessed like: <your PaletteSingleCycle instance>.PB->someSetting.

• The utility's cyclePalette is pointed to the palette blender instance's blendPalette.

• Any quirks from the Palette Blender will also apply to this utility, see the blender's Other Notes entry.

PaletteSingleCyclePS palSingleCycle(cybPnkPal_PS, 0, true, false, 0, 50, 80);
/*  Cycles through the cybPnkPal_PS palette using blend mode 0.
    The palette will be blended forward (direct is true),
    and will start blending immediately (startPaused is false)
    The pause time between blends is 0.
    Each blend takes 50 steps, with 80ms between each step. */

//Constructor with custom direction setting
PaletteSingleCyclePS(palettePS &InputPalette, uint8_t BlendMode,  bool Direct, bool StartPaused, uint16_t PauseTime, 
                     uint8_t TotalSteps, uint16_t Rate);

• palettePS* inputPalette (optional, see constructors) -- The input palette used for blending. See palettes. It is a pointer. See common vars palette entry for more details.

• uint8_t blendMode -- Sets how the input palette's colors will be shifted (see "Blend Modes" above).

• bool direct -- The direction used for some blend modes, will either cycle the palette backwards or forwards. (true is forwards).

• bool startPaused -- If true, then the blend cycle will start paused, blocking the first blend for pauseTime time. Can be changed later using setStartPaused(). Note that this setting is a member of the Palette Blender instance and not in the utility itself.

• uin16_t pauseTime -- The time (ms) that the utility will pause for between blends. Can be changed later using setPauseTime(). Note that this setting is a member of the Palette Blender instance and not in the utility itself.

• uint8_t totalSteps -- The total number of steps taken to blend between the palettes. Can be changed later using setTotalSteps(). Note that this setting is a member of the Palette Blender instance and not in the utility itself.

• uint16_t* rate -- Update rate (ms). Is a pointer, allowing you to bind it to an external variable. By default it's bound the effect's local variable, rateOrig. See common vars rate entry for more.

• palettePS* cyclePalette -- The output palette for the blend, the length depends on the blend mode (see notes above for more).

• bool active (default true) -- If false, the utility/effect will be disabled (updates() will be ignored). See common vars active entry for more details.

• PaletteBlenderPS* PB -- The Palette Blender instance. (See Other Notes above).

• void reset();

  Restarts the blend cycle (all settings stay the same).

• void switchPalette(); 

  Sets the internal start/end palettes used for the current blend. Should only be called if you manually change the input palette.

• void setTotalSteps( uint8_t newTotalSteps ); 

  Changes the number of blend steps. This setting is local to the utility's Palette Blender instance, see Palette Blender for info.

• void setPauseTime( uint16_t newPauseTime );

  Changes the pause time (ms) between blends. This setting is local to the utility's Palette Blender instance, see Palette Blender for info.

• void setStartPaused( bool newStartPaused ); 

  Changes the startPaused setting in the utility's local Palette Blender instance, see Palette Blender for info.

• void update();

  Updates the utility.

• uint8_t cycleNum -- How many blend cycles the utility has completed. This resets every input palette length number of cycles (all the palette colors have been shifted once).