OpenMASK plugins

The aim of the plugins is to have the simplest main program, which can be extended without having to recompile it.

The main purpose of a OpenMASK plugin is to add new features through new object classes (simulated objects, visual objects, animators, extensions,...) which are registered in factories and are available for the end user.

As plugins are dynamic libraries, they can be use as libraries or as plugins.

Loading plugins

Adding the loading of plugins to an application is very easy. An class PluginsLoader is made to help the user. He just have to add the following line after creating the controller:

  OM::PluginsLoader::getInstance().init( controller ) ;

Configuring plugins

In the configuration file, the plugins are defined in the user parameters of the controller.

#OpenMASK3

root
{
  Class Controller
  UserParams
  {
    Plugins [ ["${OMK_HOME}/lib" "OMKAddOn"] ]
    ...
  }
  ...
}

The Plugins field is a set of plugin definitions. Each definition is a set of one to three strings. The strings define in the order its path, its name and its configuration file. Only the first is necessary, the two others are optional.

If the name is empty the path must include the complete path with the name. To find the complete path based on a path plus a name, the loader concats path and name like this (see also Plugin constructor):

• for Windows in debug : {path}/debug/{name}_d.dll
• for Windows in release : {path}/release/{name}.dll
• for Linux in debug : {path}/lib{name}.so
• for Linux in release : {path}/release/lib{name}.so

The two followings parameters load the same plugin (for Windows in debug mode):

Plugins [ ["${OMK_HOME}/lib" "OMKAddOn"] ]

Plugins [ ["${OMK_HOME}/lib/debug/OMKAddOn_d.dll"] ]

Note: The parameter loader understands ${OMK_HOME} as the environment variable OMK_HOME. This is the best way to be platform independent. The first writing is better because it is also plaform independent.

If the plugin needs more informations to be initialised, the user can add a configuration string to the plugin parameters, it will be passed as a parameter to the initialisation function of the plugin. The use is to give the path of a configuration file. To do that, the third parameter of the set must be set like this:

Plugins [ ["${OMK_HOME}/lib" "OMKAddOn" "../theConfiguration.cfg"] ]

or

Plugins [ ["${OMK_HOME}/lib/debug/OMKAddOn_d.dll" "" "../theConfiguration.cfg"] ]

Don't forget to add the "" for the second parameter.

Creating plugins

A OpenMASK plugin is dynamic library with three external functions.

• to initialise after loading the plugin
• to finish before unloading the plugin
• to get informations about the plugin

All these stuffs are managed by Plugin class.

The basic OpenMASK plugin which adds some objects classes in their factory is very easy to write.

You can see OMKPluginAddOn.cpp source file which is use as the interface of the AddOn plugin.

Plugins list

The list of available plugins

• AddOn plugin
  This plugin is a basic set of add-ons (simulated objects, extensions, animators,...) for OpenMASK.
• Interaction plugin
  This plugin is a set of extensions to add interaction between simulated object.

---