• Basics
  • Introduction
  • Prerequisites
  • Data flow model
  • Execution sequence and module states

Basics

Introduction

This documentation describes how to integrate new application modules into COVISE. There is also a section describing how to write plugins for the VR renderer. The programming functionality to interface and communicate with COVISE is explained in detail.

Currently, each COVISE module is realized as an operating system process. Future versions may allow to create modules which are modeled as subroutines or threads in a single process environment.

Prerequisites

To create new COVISE modules, the COVISE development distribution with all the necessary header files and libraries has to be installed on the target platform. For UNIX and similar systems, this includes also a set of scripts for Bourne Shell compatible shells to set up your compile environment, especially the environment variables necessary for compiling COVISE. Start a bash by typing bash (if this is not your default shell), change to the COVISE top level directory and type source .covise.sh. If your current working directory is not the COVISE top level directory and if your home directory does not contain the covise top level directory then you have to pass the location of this directory as a parameter to this script.

When compiling modules, COVISE automatically creates different directories for platform-specific parts like object files and executables: object files are generated in the objects_$ARCHSUFFIX subdirectory of your source ($COVISEDIR) directory, while binaries are put in $COVISEDIR/$ARCHSUFFIX/bin, where $ARCHSUFFIX is a platform identifier. Refer to $COVISEDIR/README-ARCHSUFFIX.txt for a full list. Here are some examples:

ARCH	Platform
rhel6	RedHat Enterprise Linux 6.x or compatible (CentOS, Scientific Linux)
win32	Microsoft Windows using the Visual Studio 2003 compiler
lion	Apple Mac OS X 10.7 (x86_64)

Table 1: Architecture suffixes

If you want to put your enhancements into a different directory, you can set the environment variable $COVISEDESTDIR to a directory where the added binaries should go. You should also add this directory to your $COVISE_PATH environment variable.

If you are going to develop COVISE modules, you might want to switch on “developer features” in the Mapeditor settings dialog. This will enable you to restart a module from its context menu or add an option to start a module in a debugger to the context menu of modules in the module library.

There are following requirements before starting to program:

• A CMakeLists.txt file used by CMake to generate a Makefile or compile instructions for other build environments: examples are available with the example modules, which reside in $COVISEDIR/src/application/Examples. You can also use the template in $COVISEDIR/src/template/module as a starting point.

• A directory for the source code of the module is required.

• The Hello module in $COVISEDIR/src/application/Examples/Hello defines the complete basic structure of a module. It is recommended to copy this module source code as the base for own developments.

For users of the make build system having sourced the .covise.sh setup file, compiling the module is as simple as typing make in the module source directory.

COVISE has an object-oriented architecture requiring static initialization of multiple classes. For proper initialization, the main body of each module has to be written in C++. Nevertheless it is possible to integrate FORTRAN and C routines into an application module.

Each module is executed as a separate operating system process. Modules communicate in general using TCP/IP socket connections. This applies within a machine as well as between machines. Data exchange is handled differently. Within a machine pointers to shared memory are used to avoid copying of data objects. Between machines data objects are exchanged via TCP/IP socket connections. All this is handled transparently for the application programmer. The COVISE API (Application Programming Interface) is accessible through several libraries, which have to be linked to each new module. This happens automatically, if you specify covise_add_module as done in the CMakeLists.txt for the module template.

The main COVISE library is called libcoCore.so (.sl on HP, .dll/.lib on Windows, .dylib on Mac OS X). It is used for data management, message communication, starting processes, etc.

The Application library, called libcoAppl.so, contains the basic functionality to write application programs. It hides the details of packing and receiving COVISE messages and provides a framework for structuring application modules.

The library libcoApi.so builds on these libraries and provides the Application Programming Interface, which makes programming of applications easier and less error-prone. Whenever possible, programmers are recommended to use the higher level API functions instead of the direct COVISE calls provided with the Application library.

Data flow model

COVISE sessions are organized as a collection of modules, which are connected in a strictly unidirectional data flow network.

A typical data flow network is shown in the next figure. Data and control flows from top to bottom. Loops are not allowed, nevertheless, there are possibilities to send feedback messages from later to earlier modules in the processing chain.

Figure: Module and Dataflow network

Execution sequence and module states

The sequence of states a COVISE module can have is shown in the following figure.

Figure: Module execution scheme

• param: Every change of a module parameter submits a message to the module. The param subroutine reacts on these change messages.

• compute: COVISE tells the module to read its input data and create output data. Only within this routine data objects in shared memory can be read or new data objects in shared memory can be created.

• sockData: The user can register open network sockets to be monitored. Whenever data on one of these sockets arrives, sockData is called.

It is important to note that several commands are only allowed when COVISE is in the appropriate state. Due to performance reasons these states are not generally checked, thus calling functions during illegal states may result in module crashes.

Next