A driver accessory is an interface for executing code when a driver starts.

An accessory is registered with the display engine and can support any driver class that it knows how to interface with. This example accessory installs itself into DtVrlinkDriver objects and prints out the entity state repositories of entities as they are discovered.

When the exampleAccessoryPlugin gets loaded, it's passed a DtDe (display engine). At that point we connect the post initialize signal (which will get emitted after the display engine has been initialized) to the function we want to call, loadAccessory.

      // The accessory must be created after the DE's initialization is
      // finished, to make sure all the objects it uses exist.
      de.signal_postInitialize.connect(boost::bind(
         &loadAccessory, &de));

When loadAccessory gets called after the display engine is initialized we add our accessory. In this case, it prints out something when entities are discovered.

void loadAccessory(DtDe* de)
{
   // We're done with the signal, so disconnect from it
   de->signal_postInitialize.disconnect(boost::bind(
      &loadAccessory, de));
   // Add the print accessory to the accessory manager. It will get the option
   // to install itself into any DtDriver objects that are created.
   DtAccessoryManager::instance(*de).addAccessory(new DtPrintAccessory());
}

An accessory has three pure virtual methods that need to be implemented. When it's time to install accessories, the display engine goes through its list of accessors and tries to install each one on every driver. The accessory has a method, isCompatible() that determines if the accessory can be installed on the driver. If so, then it's installed. Later, the accessories are uninstalled from the driver.

      bool DtPrintAccessory::isCompatible(DtDriver* driver)
      {
         // This accessory is compatible with any DtVrlinkDriver
         DtVrlinkDriver* dd = dynamic_cast<DtVrlinkDriver*>(driver);
         if(dd)
         {
            return true;
         }
         return false;

Once deemed compatible, the display engine gives the driver to the accessory, which installs itself. From there the accessory can do what it wants. Here, we connect to a signal on the VR-Link driver which causes a DtPrintVisualizer to get created.

      void DtPrintAccessory::install(DtDriver* driver)
      {
         //std::cout << "Accessory install" << std::endl;
         DtVrlinkDriver* vld = dynamic_cast<DtVrlinkDriver*>(driver);
         if(vld)
         {
            vld->signal_simulationCreated.connect(
               boost::bind(&DtPrintAccessory::slot_onSimCreated, this, _1));
         }

      void DtPrintAccessory::slot_onSimConnected(DtConnection* connection)
      {
         DtVrlinkConnection* vrlCon = dynamic_cast<DtVrlinkConnection*>(connection);
         if(vrlCon)
         {
            DtPrintVisualizer* vis = new DtPrintVisualizer(*vrlCon);
            // Register the print visualizer instance with the sim connection
            // This passes memory management responsibility to the connection
            vrlCon->registerInstance("DtPrintVisualizer", vis);
         }

Building the Example

VR-Vantage includes pre-built versions of the example plug-in. To build it yourself, follow the instructions at Building VR-Vantage Examples, Applications, and Plug-ins.

Running the Example

This example is a plug-in. You can run it by running ./bin/exampleAccessory_stealth.bat (on Windows) or ./bin/exampleAccessory_stealth.sh (on Linux). For more information about running examples, please see Running Applications and Examples.

Example Source Files

exampleAccessoryPlugin.cxx

/******************************************************************************
** Copyright (c) 2009 MAK Technologies, Inc.
** All rights reserved.
******************************************************************************/
/******************************************************************************
** $RCSfile: exampleAccessoryPlugin.cxx,v $ $Revision: 1.3 $ $State: Exp $
******************************************************************************/
#include "exampleAccessoryPlugin.h"
#include <vrvCore/DtDe.h>
#include <vrvCore/DtAccessoryManager.h>
#include <boost/bind.hpp>
// Define export macro for vrvVrl includes
#define DL_DLL_IGCONVRLINK DT_DLL_EXAMPLEACCESSORY
// Define the protocol specific macros to compile for DIS
#define DT_PROTOCOL_NAMESPACE vrvDis
#define DtDIS 1
#include "DtPrintAccessory.h"
#include <vrvVrl/DtVrlinkEntityStateListener.h>
#include <vrvVrl/DtVrlinkEntityStateListener.inl>
using namespace makVrv;
using namespace makVrv::DT_PROTOCOL_NAMESPACE;
#undef DT_PROTOCOL_NAMESPACE
#undef DtDIS
void loadAccessory(DtDe* de)
{
   // We're done with the signal, so disconnect from it
   de->signal_postInitialize.disconnect(boost::bind(
      &loadAccessory, de));
   // Add the print accessory to the accessory manager. It will get the option
   // to install itself into any DtDriver objects that are created.
   DtAccessoryManager::instance(*de).addAccessory(new DtPrintAccessory());
}
void init(DtDe& de)
{
   // Ensure that init only gets called once
   // (not strictly necessary here, but this is good practice in general)
   DT_DE_INIT_ONCE(de);
   // We only want to create the accessory if we're running in master mode:
   if (de.isInMasterMode())
   {
      // The accessory must be created after the DE's initialization is
      // finished, to make sure all the objects it uses exist.
      de.signal_postInitialize.connect(boost::bind(
         &loadAccessory, &de));
   }
}
bool initDeModule(makVrv::DtDe* de)
{
   // Setup the plug-in. Normally, the init function and functionality
   // should be in its own library.
   init(*de);
   return true;
}

DtPrintAccessory.h

/******************************************************************************
** Copyright (c) 2009 MAK Technologies, Inc.
** All rights reserved.
******************************************************************************/
/******************************************************************************
** $RCSfile: DtPrintAccessory.h,v $ $Revision: 1.1 $ $State: Exp $
******************************************************************************/
#ifndef DtPrintAccessory_H_
#define DtPrintAccessory_H_
#include "exampleAccessory.h"
#include <vrvCore/DtBaseAccessory.h>
namespace makVrv
{
   class DtConnection;
   namespace DT_PROTOCOL_NAMESPACE
   {
      class DtPrintAccessory : public DtBaseAccessory
      {
      public:
         DtPrintAccessory();
         virtual ~DtPrintAccessory();
         virtual bool isCompatible(DtDriver* driver);
         virtual void install(DtDriver* driver);
         virtual void uninstall(DtDriver* baseConn);
      protected:
         virtual void slot_onSimCreated(DtConnection* connection);
         virtual void slot_onSimConnected(DtConnection* connection);
         virtual void slot_onSimAboutToBeDisconnected(DtConnection* connection);
      };
   }
}
#include "DtPrintAccessory.inl"
#endif

DtPrintVisualizer.h

/******************************************************************************
** Copyright (c) 2009 MAK Technologies, Inc.
** All rights reserved.
******************************************************************************/
/******************************************************************************
** $RCSfile: DtPrintVisualizer.h,v $ $Revision: 1.1 $ $State: Exp $
******************************************************************************/
#ifndef DtPrintVisualizer_h_
#define DtPrintVisualizer_h_
#include <vrvUtil/DtVirtualBaseClass.h>
#include <vrvVrl/DtVrlinkConnection.h>
#include <vrvVrl/DtVrlinkEntityStateListener.h>
class DtPrintVisualizer : public makVrv::DtVirtualBaseClass
{
public:
   DtPrintVisualizer(makVrv::DT_PROTOCOL_NAMESPACE::DtVrlinkConnection& connection);
   ~DtPrintVisualizer();
protected:
   virtual void slot_entityDiscovered(
      makVrv::DT_PROTOCOL_NAMESPACE::DtVrlinkEntityStateListener& listener);
   makVrv::DT_PROTOCOL_NAMESPACE::DtVrlinkConnection& myConnection;
};
#include "DtPrintVisualizer.inl"
#endif