Adding a Module

In order to extend Voreen and integrate your own functionality, we recommend to add your own module, in which you organize all your classes. Modules are located in the directory named "modules". Each module folder contains all files that belong to the module, as well as a special module class, which is derived from VoreenModule. This class is responsible for registering the module resources at run time, such that the Voreen framework can access them. In fact, most processors and data readers and writers are part of a module named base, of which the sources are located in modules/base.

In the following paragraphs, we describe how to create a new module named TestModule, which contains a simple image processor performing a gray scale conversion. On how to write a processor, please refer to the Adding a Processor tutorial.

Test Module
To just try it out, you can download the described test module with a brief explanation on how to activate it.


0. Generate the Module Directory

All files you want to include with the module should (since version 3.0) be located in the "modules/test"

1. Write the Module Class

The TestModule class is responsible for registering all classes contained in the module at run time. In our example it looks as follows:


modules/test/testmodule.h
#ifndef VRN_TESTMODULE_H
#define VRN_TESTMODULE_H

#include "voreen/core/voreenmodule.h"

namespace voreen {

class TestModule : public VoreenModule {

public:
    TestModule();

    virtual std::string getDescription() const { 
        return "My first test module."; 
    }

};

} // namespace

#endif // VRN_TESTMODULE_H

modules/test/testmodule.cpp
#include "testmodule.h"
#include "processors/testprocessor.h"

namespace voreen {

TestModule::TestModule() 
    : VoreenModule()
{
    // module name to be used in the GUI
    setName("Test");
    
    // module description file
    setXMLFileName("test/testmodule.xml");

    // each module processor needs to be registered
    addProcessor(new TestProcessor());

    // adds the module source glsl dir to the shader search path
    addShaderPath(getModulesPath("test/processors/glsl"));
}

} // namespace

2. Generate the Module Project Files

NOTE: This part has slightly changed since version 2.5.

Generate the files test_common.pri, which specifies the module availability macro and the module class, and test_core.pri, which references the remaining modul files contained in modules/test.


modules/test/test_common.pri
# module availability macro
DEFINES += VRN_MODULE_TEST

# name of the module class
VRN_MODULE_CLASSES += TestModule

# module class header and source file.
VRN_MODULE_CLASS_HEADERS += test/testmodule.h
VRN_MODULE_CLASS_SOURCES += test/testmodule.cpp

modules/test/test_core.pri
# processor sources
SOURCES += $/test/processors/testprocessor.cpp

# processor headers
HEADERS += $/test/processors/testprocessor.h

# shaders
SHADER_SOURCES += $/test/processors/glsl/test.frag

3. Activate the Module

To activate the module, add the following line to config.txt

VRN_MODULES += test 

4. Rebuild the Project

Regenerate the project files and rebuild the project. See Build Instructions for further details.