2.3 - Creating a Plug-in

Table of Contents

• 2.3.1 Loading Plug-ins

When you create a back-end plug-in, you must include vrfPluginExtension.h in the plug-in module.

The vrfPluginExtension.h header file contains a description of the entry points available to plug-ins for initialization and cleanup.

Use the following plug-in callbacks when you create a plug-in. At least one of these callbacks must be present in a plug-in for it to be loaded:

extern "C" {
   // Implement this plugin routine in order to place your object
   // subclasses into the factory.  This method
   // should be used for assigning controller, main objects
   // (DtVrfObjectManager subclasses, and so on), actuators
   // sensors. This function should be implemented if you wish to
   // override or replace functionality
   // that is defined by default within the system.
   DT_VRF_DLL_PLUGIN bool DtInitializeVrfPlugin(DtCgf* cgf,DtVrfPluginInformation&)
   {
      return true;
   }

   // Implement this call if you want to get access to those objects
   // created by the DtCgf.  This is called as the last step of the
   // DtCgf init() method  This function should be implemented if
   // you want to work with objects that have been created from the
   // factory as part of the DtCgf init() method call (for example,
   // DtVrfObjectManager)
   DT_VRF_DLL_PLUGIN bool DtPostInitializeVrfPlugin(DtCgf* cgf, DtVrfPluginInformation&)
   {
      return true;
   }
}

The DtVrfPluginInformation parameter supplied to these entry points allows you to identify your plug-in. This information is recorded to the plug-in's log file and vrfSim.log file as each plug-in is loaded and initially used. This structure has the following information:

typedef struct _DtVrfPluginInformation 
{ 
   DtString    pluginName; 
   DtString    pluginVersion;
   DtString    pluginDescription;
   DtString    pluginCreator;
   DtString    pluginCreatorEmail;
   DtString    pluginContactWebPage;
   DtString    pluginContactMailingAddress;
   DtString    pluginContactPhone;
   DtString    vrfCurrentVersion;
} DtVrfPluginInformation;

Note

Filling in this structure is optional. If it is not filled in, the plug-in will still load and be used.

The following entry point is optional and should be used only if the plug-in needs to clean up memory when it is unloaded:

extern "C" {
   // Implement this method to be notified when the plugin is about to be
   // unloaded so that you can clean up statically allocated memory
   DT_VRF_DLL_PLUGIN void DtUnloadVrfPlugin()
   {
   }
} 

The following example is a plug-in for vrfSim. The plug-in overrides the normal behavior of an actuator.

#include "vrfPluginExtension.h"
#include "myActuator.h"

#include "cgf.h"
#include "factoryMgr.h"
#include "compTypes.h"

extern "C" {

   DT_VRF_DLL_PLUGIN bool DtInitializeVrfPlugin(DtCgf* cgf,
      DtVrfPluginInformation& info)
   {
      cgf->factoryManager()->componentFactory()->addCreatorFcn(DtAutomotiveActuatorType, MyActuatorComponent::creator);
 
      info.pluginName = "Add Actuator";
      info.pluginVersion = "1.00";
      info.pluginCreator = "MAK Technologies";
      info.pluginCreatorEmail = "sales@mak.com";
      info.pluginContactWebPage = "www.mak.com";
      info.pluginContactMailingAddress = "68 Moulton Street - Cambridge,
         MA 02138";
      info.pluginContactPhone = "(617) 876 8085";

      return true;
   }
}

This example:

• Registers a create function for a derived kind of automotive actuator.
• Fills out information associated with the plug-in (to be displayed in the console when the plug-in is loaded).

The DtCgf class is passed in to the plug-in through the DtInitializeVrfPlugin entry point. In this function, you can register the creation functions for the classes you want to override. You can also register callback functions on important events, such as opening and closing scenarios. For details, please see cgf.h.

2.3.1 Loading Plug-ins

Plug-in libraries are placed in the ./bin directory. By default, vrfSim does not load any plug-ins. You can specify which plug-ins to load on the command line or in an xml file in the ./plugins directory. The preferred way to configure loading of plug-ins is through the Plugins dialog box in the front-end. For details, please see "Managing Plug-ins", in VR-Forces Users Guide.

Many of the examples included with VR-Forces are plug-ins. Please see VR-Forces Examples for the complete list of examples.

[<< Using the DtCgf Class] [Home] [Top of Page] [Customizing or Extending the Simulation Engine >>]