Creating a Plug-in

Table of Contents

• Loading Plug-ins

A plug-in lets you extend VR-Forces without rebuilding the entire application.

You can extend much of the VRF sim engine application through plug-ins. Through the plug-in interface you have access to:

• Vehicle dynamics
• Control objects
• Sensors
• Controllers
• Weapons systems
• Radios
• Terrain representation
• Coordinate conversions
• Network messages
• Tasks
• Plans.

When you create a sim engine 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)
   {
      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)
   {
      return true;
   }
   
   // Implement this call to supply identifying information for your 
   // plugin.
   DT_VRF_DLL_PLUGIN void DtPluginInformation(DtVrfPluginInformation& info)
   {
      // Optionally fill in plugin information
   }
}

The DtVrfPluginInformation parameter supplied to DtPluginInformation 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 the sim engine. 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)
   {
      cgf->factoryManager()->componentFactory()->addCreatorFcn(DtAutomotiveActuatorType, MyActuatorComponent::creator);

      return true;
   }
   
   DT_VRF_DLL_PLUGIN void DtPluginInformation(DtVrfPluginInformation& info)
   { 
      info.pluginName = "Add Actuator";
      info.pluginVersion = "1.00";
      info.pluginCreator = "MAK Technologies";
      info.pluginCreatorEmail = "sales@mak.com";
      info.pluginContactWebPage = "www.mak.com";
      info.pluginContactMailingAddress = "10 Fawcett Street, Cambridge, MA 02138";
      info.pluginContactPhone = "(617) 876 8085";
   }
}

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.

Loading Plug-ins

Plug-in libraries are placed in the ./bin directory. By default, the sim engine 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 VRF GUI, or in the VRF Launcher. 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.