General Utils - AlbertGBarber/PixelSpork GitHub Wiki

Jump to:

Intro:

This page lists various functions for that don't fit into another category. It mainly consists of functions that work with both Palettes and Patterns at the same time. These functions are stored under the namespace, generalUtilsPS. You may find the functions useful for automated Pattern creation, but most effects are already capable of creating the Patterns they need so........

An example of using the namespace to call setPaletteAsPattern():

generalUtilsPS::setPaletteAsPattern( myPattern, myPalette); //Sets "myPattern" to match "myPalette"

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

Functions for Matching Patterns to Palettes:

These functions take a Pattern, Palette, and possibly a few other variables as inputs, and re-write the Pattern to follow the Pattern. For example, the most basic function, setPaletteAsPattern(patternPS &pattern, palettePS &palette), copies the Palette to the Pattern one-for-one so that we get a Pattern with each of the Palette colors in order. For example, if we have a Palette with 5 colors, the resulting Pattern will be { 0, 1, 2, 3, 4 }, which is each of the Palette's indexes in order.

Note that, for all these functions, if the input pattern isn't long enough, a new pattern array will be created for the Pattern (see Pattern Basics ). The functions will ONLY re-size the pattern array if needs to be larger, or if alwaysResizeObj_PS is true (see Effects Advanced ), other wise they will just adjust the Pattern's length. This helps prevent memory fragmentation (see the previous link for more). If the pattern is re-sized, its new length will be recorded in the pattern's length and maxLength properties.

If your Pattern has been re-sized, once you are done with the Pattern, you must free the Pattern's patternArr memory by calling free(pattern.patternArr). Otherwise you may end up with a memory leak!

```
void setPaletteAsPattern( patternPS &pattern, palettePS &palette );
```
Sets the Pattern to match the passed in Palette one-for-one. For example, for Palette of length 5, the output Pattern would be {0, 1, 2, 3, 4}. All the colors in the Palette in order. Will re-size the Pattern if needed (see section intro).
```
void setPaletteAsPattern( patternPS &pattern, palettePS &palette, uint16_t colorLength );
```
Sets the Pattern to match the passed in Palette, with each Pattern color being colorLength in length. For example, for Palette of length 5, and using a colorLength of 2, the output Pattern would be {0, 0, 1, 1, 2, 2, 3, 3, 4, 4}. All the colors in the Palette in order, in colorLength lengths. Note, remember that the pattern length is limited to 65,025 (uint16_t max), so make sure your (colorLength) * <num palette colors> is less than the limit.
```
void setPaletteAsPattern( patternPS &pattern, palettePS &palette, uint16_t colorLength, uint16_t spacing );
```
Sets the Pattern to match the passed in Palette, with each Pattern color being colorLength in length, and with spacing spaces in between. Note that the space values are set to 255, which lets them be recognized as background pixels by various effects (should be noted on the effect's wiki page if so). For example, for a Palette of length 3, a colorLength of 2, and spacing of 1, the Pattern would be {0, 0, 255, 1, 1, 255, 2, 2, 255}. Note, remember that the pattern length is limited to 65,025 (uint16_t max), so make sure your (colorLength + spacing) * <num palette colors> is less than the limit.

Other Functions:

```
void resizePattern(patternPS &pattern, uint16_t sizeNeeded);
```
This function re-sizes Patterns. It checks that the length of the passed-in Pattern's is greater or equal to sizeNeeded, if so, then the Pattern's length is set to sizeNeeded, hiding the extra length rather than re-sizing the whole Pattern (this helps prevent memory fragmentation). If the Pattern is not large enough, then the function creates a new pattern array of the appropriate size while also setting the Pattern's length and maxLength variables. Note that the new array is created dynamically, while freeing the old array's memory, essentially deleting the old array. Also note that if alwaysResizeObj_PS is true ( a global setting), then the Pattern will always be re-sized, see the previous link for more. Finally, if your Pattern has been re-sized, once you are done with the Pattern, you must free the Pattern's patternArr memory by calling free(pattern.patternArr). Otherwise you may end up with a memory leak!
```
void setPatternAsPattern(patternPS &outputPattern, patternPS &inputPattern, uint16_t colorLength, 
                         uint16_t spacing);
```
Serves as a shorthand for making a longer pattern out of a smaller input pattern. Takes an input and blank output Pattern, and shapes the output Pattern to match the input with a set colorLength and spacing. Note that the space values are set to 255, which lets them be recognized as background pixels by various effects (should be noted on the effect's wiki page if so). For example, consider an input Pattern {1, 2, 4}, using a colorLength of 2, and a spacing of 1. The output Pattern would be {1, 1, 255, 2, 2, 255, 4, 4, 255}. Note, if the pattern is not large enough to store the palette pattern, it will be re-sized dynamically, see resizePattern() above. Also, remember that the pattern length is limited to 65,025 (uint16_t max), so make sure your (colorLength + spacing) * <num palette colors> is less than the limit.