Terrain3D Module System

The easiest way to implement new functionality for the Terrain3D Software is the usage of a Module System.

This project is work in progress. If you might need more functionality or find a bug, please voice it.

The terrain3D Software sits on top of the Equalizer Framework. Reading the EQ documentation is a good starting Point for beginners.

Introduction

To make your life easier a module handling system has been implemented into the Terrain3D Software. It hides complexity from the underlying EQ framework by offering a convenient interface for your own module. The most important idea is to follow the design principles of the EQ programmers and have passive modules. This means that you can bring in your own functionality by overriding methods of the Module Interface. These methods are called by the Module Handler in turn just at the right place within the cascading hierarchy of the EQ framework.

The Module Interface

Concept for class and package relations using UML notation.

Terrain3D Modules are located in a seperate folder each.

Initialization

First of all you need to give your Module an unique name by overriding the getName() method:

string MyModule::getName() {
    return "MyUniqueModuleName";
}

Next step is to decide where to initialize the configuration of your module. There are three different possibilities for that.

Master Node

E.g. the Android Module needs a server listening for clients. Since it is sufficient to start only one server for the whole application, it is initialized in the master node.

string MyModule::initMasterNode() {
    <code here>
}

Node

If you have code that needs to run on every machine of a multi machine setup, you can do the following:

string MyModule::initNode() {
    <code here>
}

Channel

You can use your module's constructor to do the initialization within every EQ channel.

string MyModule::MyModule() {
    <code here>
}

Event Handling

There are several methods available that can be used to react on system events, e.g.:

virtual bool keyPress(int key);

One can manipulate the module's internal state within those methods to be able to react on an event within the manipulation methods for the terrain or the virtual camera.

Window Rendering

There is a special method to be called when something needs to be painted onto the screen using OpenGL^?:

virtual void renderWindow();

Terrain Rendering

You can render any OpenGL^? or GLU Code at the virtual camera's current position:

virtual void renderTerrain() const;

Don't forget to maintain the OpenGL^? stack properly.

Camera Manipulation

Implement the following signatures to manipulate the Terrain3D's camera.

virtual float getHeading();
virtual float getPitch();
virtual float getRoll();

virtual float getTransMoveDir();
virtual float getTransRight();
virtual float getTransUp();

You can calculate this 6 DOF data by implementing:

virtual void updateCameraData();

Synchronisation

The EQ Framework maintains different versions of each Module. You can decide which data needs to be synced over the network by implementing:

#ifdef EQUALIZER
virtual void getInstanceData(co::DataOStream& os) const;
virtual void applyInstanceData(co::DataIStream& is);
#endif

The Module Handler

The module handler holds a reference to all modules available. Instantiation takes place in the constructor individually:

ModuleHandler::ModuleHandler() {
   // Add my module
   MyModule* myModule = new MyModule(this);
   addModule(myModule);
}

Resources

• Your starting point is http://www.equalizergraphics.com/.
• Installing the Terrain3D Software: Terrain3D Installation Tutorial
• Terrain3D Documentation Tutorial
• Programming guidelines