| Parola for Arduino 3.0 Text effects for LED Matrix modular hardware

Parola Library

## The Library

The Parola library is implemented using the MD_MAX72xx library for hardware control. The library implements functions to simplify the implementation of text special effects on the LED matrix.

- Text left, right or center justification in the display
- Text scrolling, appearance and disappearance effects
- Control display parameters and animation speed
- Support for hardware SPI interface
- Multiple virtual displays (zones) in each string of LED modules
- User defined fonts and/or individual characters substitutions

### External Dependencies

- Parola uses the MD_MAX72xx library for hardware level control primitives. The latest copy of this library can be found here.

## Display Zones

A matrix display can be treated as a single contiguous set of modules or it can be split into multiple 'virtual' displays (zones). Prior to version 2.0 of the library, each display was effectively a single zone.

A zone is a contiguous subset of one or more display modules (LED matrices) that has all the attributes of a display - animation, speed, font, spacing, etc. This allows complex displays to be created. For example, one part can show relatively static text while a different one has animation and movement.

For backward compatibility, all the methods from version 1 remain. If the new library is compiled with older user source code, the library defaults to using a single zone for the whole display. Zone-aware functions have an added parameter to specify the zone to which the method invocation applies. Methods invoked without specifying a zone (such as set*()) usually have their effect applied to all zones.

### More Information

- Parola A to Z - Multi Zone Displays
- Parola A to Z - Double Height Displays

## Fonts

The standard MD_MAX72xx library font can be substituted with a user font definition conforming to the font encoding rules in the MD_MAX72XX documentation. New fonts can be designed with the the MD_MAX72xx font builder.

Each zone can have its own substituted font. The default font can be reselected for the zone by specifying a nullptr font table pointer.

### More Information

- Parola A to Z - Defining Fonts
- Parola A to Z - Managing Fonts

## User Characters

Individual characters can be substituted for user character definitions. These can be added and deleted to individual zones as required.

The character data is the same format as a single character from the font definition file, and is held in a local lookup table that is parsed before loading the defined font character. If a character is specified with a code the same as an existing character, the existing data will be substituted for the new data.

ASCII 0 character ('\0') cannot be substituted as this denotes the end of string character for C++ and cannot be used in an actual string.

The library only retains a pointer to the user data definition, so the data must remain in scope. Also, any changes to the data storage in the calling program will be reflected by the library the next time the character is used.

### More Information

- Parola A to Z - Defining Fonts
- Parola A to Z - Managing Fonts

## Sprite Text Effect

The PA_SPRITE text effect requires additional information, as it extends the functionality of the library to include fully customizable, user defined, animated bitmaps to wipe text on and off the LED matrix display.

Each frame is defined by a sequence of numbers that encode the columns of the bitmap. The least significant bit is at the top of the bitmap. If the sprite has a front and rear, the bitmap should be defined for the sprite moving to the right. The library will mirror reverse the image when it moves left. The sprites are essentially defined in the same way as the character font and the same tools can be used to define the data for the sprite bitmap.

A sprite has at least one frame. If more than one frame is required, a similar definition is created for each frame of the animation, and a data table constructed defining the animated sprite. To ensure smooth animations, remember that once the last frame is reached, it will loop back to the first, so avoid discontinuities between the two ends of the data table.

The library is given the sprite definition setSpriteData() method and the text effect is specified using the effect id PA_SPRITE.

### More Information

- Parola A to Z - Sprite Text Effects

## Conditional Compilation Switches

The library allows the run time code to be tailored through the use of compilation switches. The compile options start with ENA_ and are documented in the section related to the main header file MD_Parola.h.

NOTE: Compile switches must be edited in the library header file. Arduino header file 'mashing' during compilation makes the setting of these switches from user code completely unreliable.

## Implementing New Text Effects

Each of the selected text effects is implemented as a function. This makes it easy to add new effects:

- Choose a name for the effect and add it to the textEffect_t enumerated type.
- Clone an existing method and modify it according to the guidelines below.
- Add the function prototype for the new effect to the MD_PZone class definition in the MD_Parola.h file.
- Modify the zoneAnimate() method in MD_PZone.cpp to invoke the new method.

### New Text Effects

The effects functions are implemented as finite state machines that are called with the frequency set by the setSpeed() method. The class variable _fsmState holds the state from the last invocation of an effect method.

An effect method can work in one of 2 ways:

- Additive: where the animation frames are incrementally built up to the initial display. With this method, the function will need to use the getFirstChar() and getNextChar() methods to build up the displayed text, column by column.
- Subtractive: where the final displayed text is placed in the buffer using the commonPrint() method and the elements that are not visible at that stage of the animation are removed.

Which algorithm is used depends on the type animation and what is convenient for the coder. Examples of both are found in the supplied library text effects.

Each effect method is implemented in 2 parts. One part implements the text move IN to the display (method parameter bIn is true) and the other when the text is moving OUT of the display (bIn false). Because the IN and OUT effects can be different for a display cycle, the method must not assume that the first part was ever called. The first phase should always end with the text in its display position (depending on the alignment specified) and the second phase should assume the text is in that position when called. Text position parameters are held in the class variables _limitLeft and _limitRight found in the library header file.

The first phase starts with _fsmState set to INITIALISE and ends when the state is set to PAUSE within the effect method. The second phase starts with a PAUSE state and ends when the state is set to END by the method. Aside from the INITIALISE state (set by the displayReset() method), all other state changes are under the control of the effect functions. Delays between frames and the pause between IN and OUT are handled outside of the effect method.

### More Information

- Parola A to Z - Text Animation
- Parola A to Z - Managing Animation

## Coding Tips

- The MD_MAX72XX library sets the origin for the LED matrix at the top right of the display. This makes the leftmost text column a higher column number that the far right column. Sometimes this is not intuitive when coding and is worth remembering. Rows are numbered from top to bottom, 0-7.
- Ensure that a new effect is tested in combination with other effects to make sure that transitions are smooth and the IN and OUT effects combine well. Common errors are misaligned entry compared to exit, with causes a small jump in the text position when the effects are combined.
- Display update times grow proportionally with the number of modules in a display, so some timing parameters may need to adapt. Hardware SPI runs approximately 10 times faster and the delay increase is not appreciable with up to 12 modules. For the arbitrary pin outs, using shiftout(), a 6 module chain updates in approximately 14ms on an Uno, while a 12 module display takes around 25ms. Most of the time taken is to physically update the display, as animating frames takes about 1-2ms to update in the MD_MAX72XX display buffers.