All MotionSampler plugins need to follow some basic conventions which allow them to be loaded dynamically.
The first step in programming a plugin is to define the symbols which MotionSampler will look for when it tries to load it. In order to do so, your plugin must include the headers PDLPlugin.h and PDLModuleID.h. Both of these headers are included indirectly by each of the headers PDLSource.h, PDLFilter.h, and PDLSink.h, so most plugins simply include one of these headers.
| Although a plugin may contain more than one module, each module must be of the same basic type: source, filter, or sink. |
The header PDLPlugin.h defines the macro PDLDeclarePluginID() which makes it easy to create the symbol which MotionSampler uses to verify plugin compatibility. The macro expects an argument which must be one of PDL_SOURCE_ID, PDL_FILTER_ID, or PDL_SINK_ID, which are all defined in PDLModuleID.h. A plugin declares its type and version just by using this macro which must be placed outside any of the plugin's functions.
PDLDeclarePluginID() declares a character pointer named PDLPluginIDString which points to the constant string defined by its argument. Each time a new version of MotionSampler is released, the version numbers contained in PDL_SOURCE_ID, PDL_FILTER_ID, and PDL_SINK_ID are changed. This prevents you from loading old plugins which have become incompatible with the new base classes. Old modules at least have to be recompiled and sometimes have to be changed to become usable with a new release.
In addition to using PDLDeclarePluginID(), a plugin must also create an entry point function which MotionSampler can locate. The entry function, which is the plugin's equivalent to a program's main(), must be called PDLInitializePlugin(). The prototype for this function is in PDLPlugin.h and appears as follows:
extern "C" void PDLInitializePlugin(void* catalog);
Notice that this declaration uses the C++ mechanism for specifying C style linkage. This prevents the compiler from using C++ name mangling in the function's link symbol. Name mangling is not always consistent between C++ compilers and could prevent MotionSampler from finding the mangled symbols if there are differences between the compiler used to build MotionSampler and the one used to build plugins. Using C linkage prevents this by making the link symbol more predictable.
The following example shows a basic plugin implementation that does nothing useful. However, if it is compiled into a DSO with a name that ends in .f.so, it will be successfully loaded and MotionSampler will call the function PDLInitializePlugin() during program start-up.
#include <PDLFilter.h>
PDLDeclarePluginID(PDL_FILTER_ID);
void
PDLInitializePlugin(void* catalog)
{
}