Pattern Functions - AlbertGBarber/PixelSpork GitHub Wiki

Jump to Functions for:

Intro:

This page lists a series of utility functions for working with Patterns. While Patterns are fairly simple, I recommend using these functions for manipulating them, rather than doing it manually. These functions are stored under the namespace, patternUtilsPS.

An example of using the namespace to call the getPatternVal() function:

patternUtilsPS::getPatternVal( myPattern, 0); //returns the pattern value at the 0th index in "myPattern"

The namespace mainly includes functions for getting and setting Pattern values.

You can also find these functions in "paletteUtilsPS.h" and "paletteUtilsPS.cpp".

Note that when getting and setting values, Patterns wrap. So if you ask for a value at an index that is greater than the Patterns's length, the code will wrap back to the start of the Pattern (using mod) so that some value is always returned. This helps prevent crashes.. For example, if I have a Pattern with 3 values, and I ask for a 4th, the code wraps the request back to the start of the Pattern, so I'd actually get the 1st value back. If I asked for a 5th, I'd get the 2nd, etc.

Functions for Getting Pattern Values:

These functions return a value from a Pattern.

```
uint8_t getPatternVal(patternPS &pattern, uint16_t index);
```
Returns the value of a Pattern at the specified index. Note that Patterns wrap, see the intro for more.
```
uint8_t *getValPtr(patternPS &pattern, uint16_t index);
```
Returns a pointer to the value of a Pattern at the specified index. Allows you to bind an external value to the Pattern value. If the Pattern value changes, the external value will too, as they are consider to be the same.

uint8_t getRandVal(patternPS &pattern);

Returns a random value from the Pattern.

```
uint8_t getShuffleVal(patternPS &pattern, uint8_t currentPatternVal, bool allowSpaces = false);
```
Returns a random value from the Pattern that is different from the current value you're using, currentPatternVal. Ex, your effect is using a Pattern value of 3 (which corresponds to a Palette color or something), it can ask this function for a random Pattern value other than 3. Note that works by looping through the Pattern from a random starting index until if finds a new value. The functions optionally allows spaces (pattern val 255) to be returned if the pattern has them. This is controlled by allowSpaces, and is default false (no spaces). DO NOT use this with a Pattern that has a single value, as it will loop through all of the Pattern and then just spit back out the currentPatternVal, wasting time.

Functions for Changing Patterns:

These functions change part of a Pattern, ranging from a single value to shuffling the whole Pattern.

void setVal(patternPS &pattern, uint8_t val, uint16_t index);

Sets the Pattern value at the index to val.

```
void shuffle(patternPS &pattern);
```
Randomizes the order of the Pattern.
```
void reverse(patternPS &pattern);
```
Reverses the order of the Pattern.