Code Documentation
Enable the html code documentation by executing doxygen. First of all install doxygen and graphviz:
sudo apt-get install graphviz doxygen
Build the documentation from within the project directory:
cd build && cmake .. && make doc
The overall system is similar to normal game engines. The processing loop consists of three different major components:
- (Input) event grabbing / event extraction from input devices
- Event processing
- Image rendering
The image below displays the involved components. An input handler grabs input events from keyboard or the gaming controllers and the currently running application processes these events an generates an image. The render component now transfers the image to the LED matrix or the computer monitor.
To support different types of animations and games, the engine organizes all available applications in a stack. The application at the top is the currently running and all other apps are paused in the meanwhile. New apps are launched from within the currently running app by placing them on top of the stack. An example of this process is shown in the figure below. The red arrow indicates the currently active application.
With this stack design in mind, each application has the following life cycle:
Due to performance reasons and to simplify the implementation of applications even more, it is possible to specify a color mode for each application. The supported modes are:
- RGB image buffer: The application has to generate a normal color image, that can directly be rendered.
- Indexed image buffer with palette: The application has to specify a color palette, that maps indices to RGB colors. Instead of generating an RGB image, the application can now store indices in an indexed image. In this case, the image buffer can directly be used as storage for e.g. a game field, where the indices correspond to objects. Due to the color palette, the image is automatically converted to RGB before rendering.
An input handler has to be specified before starting the engine. In each processing loop, the engines queries new input events from the input handler. The input handler extracts these events from the keyboard or from the game controllers. A debouncer implementation converts the extracted event data into a representation that allows the distinction between single key pressing and key holding.
In the current implementation, only a single input handler can be active at a time. Even though the implementations supports multiple players, all of them have to use the same kind of input device.
The used architecture strongly couples the rendering and the overall control engine. Therefore, the main engine is actually the base class for the rendering class. The base class has a virtual drawing function, that has to be implemented by all display implementations. The base class handles now the actual main loop of the control engine and passes all rendering calls to the sub class. Therefore, the rendering class is usually called "controller".
Basic applications implement the following functions:
- Initialize: Initialize the application, and reset everything to start. Here, the application has to specify the color mode that should be used for rendering. If the application uses the indexed color mode, it must update the color palette from its base class to the required color values (m_colorPalette).
- ProcessInput: The function gets a list of all input events that occurred since the last function call. The application can now update its state.
- Draw: Draw the current state of your application to the provided frame buffer.
- An application can indicate the end of its execution by setting the member variable m_hasFinished to true.
- To save some processing time, the application can skip its rendering cycle by setting m_requiresRedraw to false. This feature can be useful if the display only changes a few times a second and a redraw every few milliseconds is not necessary.