 |
Parola for Arduino
3.0
Text effects for LED Matrix modular hardware
|
|
Parola for Arduino
3.0
Text effects for LED Matrix modular hardware
|
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.
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.
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.
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.
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.
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.
Each of the selected text effects is implemented as a function. This makes it easy to add new 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:
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.
1.8.14