Difference between revisions of "CalVR Plugins"

Revision as of 09:50, 28 February 2012

Overview

In CalVR, new applications are added in the form of plugins. These plugin modules implement a virtual base class in the CalVR core and compile into a separate shared library. At runtime, this library is loaded and the plugin receives callbacks from the CalVR core through the implemented virtual functions.

Plugin Development

It is recommended to build the doxygen documentation for the CalVR core for use during plugin development. You can turn this on with a flag in the ccmake config.

Adding a new Plugin for CalVR

Create a new directory named <YourPluginName>. Each source code directory must have a file "CMakeLists.txt".
For your plugin, use (CVRPlugins Dir)/calit2/ModelLoader/CMakeLists.txt as an example.
Change the LIB_NAME variable to be set to <YourPluginName> and replace the source and header files with those for your plugin.
If you need compile against other libraries, add entries for them with INCLUDE_DIRECTORIES and TARGET_LINK_LIBRARIES options.

In order for cmake to generate a makefile for the new plugin, we need to add an entries to the "CMakeLists.txt" in the parent directory.

Under the parent directory, e.g., (CVRPlugins Dir)/calit2/CmakeLists.txt, add the following lines:

OPTION(PLUGIN_YOURPLUGINNAME "YourPluginName" OFF)

IF(PLUGIN_YOURPLUGINNAME)
 ADD_SUBDIRECTORY(YourPluginName)
ENDIF(PLUGIN_YOURPLUGINNAME)

Go to the root CVRPlugins directory and run:

ccmake .

Type 'c' to configure the project again.
You should now see an option to build your new plugin. Set this option to ON, re-configure, then type 'g' to generate the new makefiles.
You can now build your plugin by typing make.

Now we need to modify the CalVR Config File to turn on the new plugin. Now run CalVR, in the terminal we should see the init message of the new plugin.

The Plugin Base Class

Your plugin project will need to have a class the inherits from the CalVR plugin base class. This is the CVRPlugin class defined in:

#include <kernel/CVRPlugin.h>

The class may implement any needed virtual functions in this class to receive calls from the CalVR core during runtime.
There are doxygen comments for these functions, but I will note them here as well:

virtual bool init()

Called once right after the plugin is created. A return of true means the init went ok and false means there was some failure and the plugin should be unloaded. This is a good place to do one time setup operations like creating menus or a base scene graph structure.

virtual void preFrame()

Called once each frame right before the scene is rendered. This is where things like scene graph changes could take place and affect the current frame.

virtual void postFrame()

Called once each frame after rendering and buffer swap (for double buffered rendering). This call may have a situational use. Implement it if you feel you need it.

virtual bool processEvent(InteractionEvent * event)

Function that allow the plugin to use events generated by the CalVR core. These events are things like button presses, keyboard presses, valuators, etc. See doxygen or below for more on the InterationEvent class types. If true is returned the event is consumed, otherwise it continues through the event pipeline.

virtual void message(int type, char * & data, bool collaborative = false)

Called when the plugin is sent a message from another plugin or a collaborative session. TODO: create and link to message passing documentation

virtual int getPriority()

Returns a priority value for this plugin. This function is called once when the plugin is loaded. It is used to order all loaded plugins. A plugin with a higher priority gets function calls and events before lower priority plugins. The default is 50. This value really SHOULD NOT BE CHANGED unless you have a good reason to do so. This is designed to allow you to be able to enforce a relative order of plugin execution or event handling.

All plugins must also include a macro in the main .cpp file:

CVRPLUGIN(PluginName)

Where PluginName is the name of the class implementing the CVRPlugin class. This creates a small function that is used as an interface into the plugin shared library.

Using the Config File

For info on the config file itself, see CalVR Config File.
To access values from the config file you must first include the ConfigManager class.

#include <config/ConfigManager.h>

This class provides static functions that return values listed in the config file. An example would be something like:

int myInt = ConfigManager::getInt("size","Plugin.MyPlugin.MyTag",100);

The ConfigManager looks for the given attribute "size" in the given tag search path "Plugin.MyPlugin.MyTag". If the tag/attribute is not found, the default value is returned, in this case 100. Optionally, you can include a bool pointer as a final argument in the function call. The bool value is filled with true if the tag/attribute is found and false otherwise. If this tag/attribute appears more than once in the config structure, the first one found is returned.
There is a different function call for each type of value you wish to find, bool/int/float/etc. See the doxygen comments or header files for more info.