Turbo-BrainVoyager v3.2

TBV - Plugin Interactions

When the Plugins menu is opened, TBV is interrogating all plugin files (shared libraries with the extension ".dll" on Windows, ".so" on Linux and ".dylib" on Mac OS X) located in the "Plugins_32/64" folder. In each detected plugin library file, TBV calls a few simple C functions that must be defined in the plugin in order to get basic information about the plugin such as its name, a short description of its function, the plugin author and (optionally) a help file. The returned plugin name is used to fill the Plugins menu.

When a specific plugin is selected in the Plugins menu, TBV will create a plugin object by instantiating the defined plugin class; more specifically, the "createPlugin()" C function is called that serves as a factory to create the plugin object; a pointer to that object is returned to TBV and stored so that it can be used subsequently to call predefined methods that must be implemented by the plugin class. In order to enforce a set of known class methods, a plugin class must be derived from the generic "TBVPluginInterface" class defining the interface using virtual functions.

The plugin object is normally destroyed by TBV when the user closes the Plugin dialog typically after real-time processing. The plugin object is also destroyed when the initialization function "initPlugin()" returns "false", e.g. in case that some prerequisites are not met. If "initPlugin()" returns "true", the Plugin dialog is launched which is used to send information from the plugin to the user. Then TBV calls the "executePreRun()" function that can be used for setting up the plugin or to interrogate information from the user. After that function has returned, the plugin "sleeps" until it is called later. After real-time processing has been started, the "executePreStep()" and "executePostStep()" functions will be called once at each time point allowing execution of code for custom data processing/export. Note that the plugin programmer is responsible for keeping processing time within these functions short since TBV will wait until the plugin returns, i.e. until these functions have finished its computations at a given step. After incremental processing is finished, TBV calls the "executePostRun()" function of the active plugin that can be used to do final processing. When the Plugin dialog is closed, the destructor of the plugin object is called that can be used for final clean-up such as releasing any allocated memory. In summary, the following functions are called in a typical real-time session:

When selecting a plugin in the Plugins menu:

TBV calls C-function createPlugin() of the plugin that calls itself "new <PluginClass>" to create plugin object, executes constructor, and returns object pointer (called "pluginObject" below).
TBV calls member function "pluginObject->initPlugin()" allowing plugin to check prerequisites, including successful access of TBV plugin API functions and to check whether the TBV version is appropriate.
TBV calls member function "pluginObject->executePreRun()" allowing plugin to perform setup operations (e.g. allocating memory for later use) and to present dialogs to the user to make specific choices or to enter relevant information (e.g. where to store data).

At each time step after starting real-time processing:

TBV calls member function "pluginObject->executePreStep()". This function allows to access the raw data of a functional volume after all slices have been read into working memory. This allows, for example, to add additional preprocessing operations such as custom spatial smoothing.
TBV calls member function "pluginObject->executePostStep()". This function is called after preprocessing (e.g. motion correction, spatial smoothing) as well as statistical GLM processing has been performed. This implies that beta and contrast maps have been updated for the new functional volume only at this point. Since data has been preprocessed and updated, it is recommended to mainly use this function for custom processing and data export (see example "export" plugin).

After the last volume has been processed:

TBV calls member function "pluginObject->executePostRun()" allowing to do some post-run processing and to inform user about completion of the plugin.

When user closes the Plugin dialog:

TBV deletes the plugin object executing the "delete pluginObject" statement. This results in a call of the plugin destructor that can be used to clean-up any allocated memory.