Adding a Processor

• Contents

  • 1. Important Processor Functions
  • 2. Integration into Voreen
  • 3. Processor Examples

Important Processor Functions

In this section we will introduce the most important functions used by each Voreen processor.

Pure Virtual Functions

A basic Voreen processor has five pure virtual functions which have to be implemented by the developer. Two of them are inherited by VoreenSerializableObject which is the base class of most objects in Voreen and the other three pure virtual functions are defined in the Processor class itself.

The function should return the type name of the concrete subclass as string. Necessary due to the lack of code reflection in C++.

This function is a virtual constructor. It is supposed to return an instance of the concrete subclass i.e. a Processor pointer in our case.

It returns the general category the processor belongs to. This method is not intended to be re-implemented by each subclass, but is rather defined by the more concrete base classes, such as VolumeRaycaster or ImageProcessor. The category is used in the VoreenVE GUI to group processors of same categories.

This method should call Processor::setDescription(std::string desc) with a parameter string describing the functionality of the processor and containing a user manual if the usage is not intuitive. The string is shown to the user in the VoreenVE GUI. It is possible to use html code for highlighting important information or embedding links to websites in the description.

This function contains the main functionality of the processor. If the processor is initialized, ready and invalid during network evaluation, the process function will be called by the network evaluator. All image/volume rendering or data processing should be done here. Some examples of this function can be found in the section Processor Examples.

Frequently Used Functions

The following Processor functions are frequently used and an understanding of their functionality is quite important to avoid Voreen concept based implementation errors and should accelerate the debugging process.

A newly created processor has not been initialized yet. During the first evaluation of the processor this function will be called by the evaluator. Since it will only be called once in the lifetime of the processor, all stuff that has to be done once, e.g. loading shaders, should be done here. The superclass' function must be called as first statement when it is overwritten, since property and processor widget initializations are done in it. All OpenGL initializations must be done here, instead of the constructor, because normally during the constructor call no OpenGL-context is available!

If the initialization fails an exception is thrown and the processor is flagged as not initialized as being shown in the network editor. Since this function will only be called once, a non initialized processor is a critical error and the loaded network will not work properly.

The processor will be deinitialized before the destructor of the processor will be called. Like the destructor cleans up everything that has been done in the constructor, deinitialize should clean up everything that has been done in the initialize function. The superclass' function must be called as last statement when it is overwritten. All OpenGL deinitializations must be done here, instead of the destructor, since normally no OpenGL-context is available during destruction!

The process function of a processor will only be called, if the processor has been initialized, i.e. initialize() has been called successfully, and the processor is ready. The default implementation checks, if all ports of the processor are connected and the inports have valid data. If a port of a processor is optional and don't have to be connected, this function must be overwritten. A non ready processor will be highlighted in the network editor. Being not ready is a not critical error. The network will not be evaluated properly if a processor is not ready, but instead of a failed initialization it can become ready by adding e.g. port connections. 

The invalidate function is defined in the PropertyOwner class, but since it is mostly used by processors the common values are defined in the Processor class. The process function of a processor is only called, if the invalidation level of the processor is invalid e.g. greater zero. A processor normally becomes invalid trough property value changes or if inports get new data. Depending on the invalidation level, different actions could be triggered as been seen by the enum definitions. It is possible to define new invalidation levels by the developer. If the invalidate function of a processor is called, a new network evaluation will be scheduled,  thereby the evaluator can call the process function of the processor. The invalidation level will be automatically set back to valid by the evaluator after the process method has been performed.

If a processor has ports or properties they have to be added in the constructor via the specific add functions. Otherwise they will not be shown in the VoreenVE GUI and will not be handled correctly by internal processes. The remove functions are normally not used, since ports and properties of a processor are not intended to be dynamic, although it would be possible.

To be continued...

Integration into Voreen

Assuming our new processor has been already implemented, we can integrate it as described here.

Processor Examples

In this section we want to introduce a few simple processor examples which should help developers during their first implementations. All examples can be found in the current Voreen release within the module "SampleModule".   

Sample Processor

The SampleProcessor is a spartan version of a Voreen processor. It just implements all pure virtual functions inherited from the base classes. The processor can be tested in the workspace "SampleProcessor_workspace.vws" in the SampleModule. The image above is showing this workspace. In the workspace a TextSource provides the text "Hello World!". The SampleProcessor simply adds the prefix "Simon says:" to its front. The other three processors (Background, TextOverlay and Canvas) only produce a visible output. The Canvas shows the original text on the top and the modified text on the bottom. The user can change the orignial text and prefix by modifying the StringProperties on the right-hand side. We will now have a closer look into the implementation details.

sampleprocessor.h

The first part of the header is simple basic c++. We check, if the processor has been already defined and add all needed headers. It should be mentioned, that all Voreen processors are defined and implemented in the voreen namespace.

After all includes have been set we can start the class definition. All Voreen processors should inherit from the processor base class. The VRN_CORE_API macro is needed for DLL inports and exports under windows. This macro has no effect under Linux.

The constructor of a processor should have no parameter! All parameters the processor needs should be handed to it via ports and properties.  

Here we define all pure virtual functions of the base classes. More information on this functions were presented in the section Pure Virtual Functions.

Last but not least we have to add the class members to our processor. In our case they are two ports for the in- and output of the text and a property to modify the prefix by the user.

sampleprocessor.cpp

Like in sampleprocessor.h only basic c++ at the beginning of the cpp file.

The constructor of each implemented processor in Voreen looks nearly the same. Fist we call the base class constructor and initialize its members. In the function body itself we have to add the ports and properties by calling the specific add functions. It is needed to get a proper internal handling of ports and properties belonging to the processor. 

These four functions are always implemented in this way. Beside name changes nothing more has to be done.

This is the implementation of the "main" processor function. First we get our needed parameters from the inports and properties. Then we process them, e.g. combining both strings. Afterwards we fill our outports and the SampleProcessor is ready to use.

Sample Render Processor

After introducing the first simple processor we now want to make it a little bit more complex. This time we will render images via a GLSL shader in the SampleRenderProcessor. The processor and the according workspace "SampleRenderProcessor_workspace.vws" from the SampleModule are illustrated in the image above. The SampleRenderProcessor gets an image and modifies the saturation of the colors. The saturation can be manipulated by the user via a FloatProperty on the right-hand side. A saturation of zero equals a black-white image as shown in the Canvas. The colorful tooltip shows the original image in the ImageSource outport to validate the proper work of the SampleRenderProcessor.  

samplerenderprocessor.h

We include all needed headers and set the namespace to voreen.

Here we are defining the constructor and implementing inline the four simple pure virtual functions of the base classes. Since our processor should render images and use RenderPorts it inherits from RenderProcessor. RenderProcessor is a subclass of Processor implementing specific functions for handling render targets internal.

These two functions are new and were not used in the first example. They overwrite the basic implementation of the function in RenderProcessor or rather in Processor. They are used to load and free the needed shader.

The three first members are, except for the type, the same as in the SampleProcessor. The fourth is a shader object used to handle shaders in the process() function.

samplerenderprocessor.cpp

Simply including headers and setting the namespace.

The constructor is nearly the same as the one of the SampleProcessor. We want to point out again the inheritance of the RenderProcessor, which causes the call of RenderProcessor instead Processor constructor.

These are the implementations of the overwrite functions. The ShaderManager (ShdrMgr) is a singleton class handling all shaders. In the initialize function we load the used pair of vertex and fragment shader. The vertex shader is simply the one used in the OpenGL pipeline and the fragment shader will be shown later on. The function generateHeader() is implemented in RenderProcessor and sets the default shader headers i.e. shader parameters. Deinitialize simply frees the loaded shaders. 

Other than all other ports RenderPorts don't have a getData or setData function. To set the data of a render outport we have to activate its render target. After the rendering we have to deactivate it again. To get the data (image) of the inport, we have to bind its internal textures (see line 8). After everything is done, we can check for OpenGL errors appeared during the rendering with the LGL_ERROR macro.

sample.frag

In the first part of the fragment shader we include Voreen shader libraries (a.k.a. modules). They offer some basic functions and defines which are frequently used. Next we define all uniforms being needed for our shader.

The main shader function simply gets the texture color of the actual position and modifies it by the user-defined saturation.