How the Visuals and The Network Work Together

Table of Contents

• Using Agents to Communication Between Network and Visualization Threads
• GUI Shared Signalers
• Shared Read and Write Locks
• Network Message Agent

Connection between the network and visualization threads of the application can be done in the following ways:

• makVrv::DtAgent subclasses – Agents will archive data into a makVrv::DtMessage which is put on a queue. This queue is processed once a makVrv::DtDe tick call and distributed to the apporpriate agents on the visualization side for processing
• makVrf::DtNetworkMessageInterfaceHandler - Owned by the makVrf::DtVrfConnectionHelper, this agent will be used to send DtSimInterfaceContent messages received from the back-end to the Visualization Thread.</LI?
• Shared Signalers - These classes (makVrf::DtSharedNetworkSignaler) use makVrv::event_signal to queue a boost signal that will be processed in the network thread. The siganlers are tied to a particular network queue, so, each thread can have its own queue (in practice there is only one network thread, so, the visualization thread and the network thread share the same queue)
• Locks - The makVrv::DtReadSettingsLock and makVrv::DtWriteSettingsLock are used to lock settings objects across threads to share data

Using Agents to Communication Between Network and Visualization Threads

Agents are used to communicate from the network thread to the visualization thread. They will use a makVrv::DtMessage object to archive contents of a message to be put onto an agent message interface queue which is processed in the visualization thread every tick. Agents are created from ocdx files:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<!DOCTYPE boost_serialization>
<boost_serialization signature="serialization::archive" version="8">
<myClass class_id="0" tracking_level="1" version="4" object_id="_0">
   <myName>DtAttachableRangeLineTextUpdater</myName>
   <myNamespace></myNamespace>
   <myHeaderFile>"DtAttachableRangeLineTextUpdater.h"</myHeaderFile>
   <myInheritedFlag>1</myInheritedFlag>
   <mySuperClassName>DtAttachableUpdater</mySuperClassName>
   <mySuperClassNamespace>makVrv</mySuperClassNamespace>
   <mySuperClassHeaderFile>vrvCore/DtAttachableUpdater</mySuperClassHeaderFile>
   <myStates class_id="1" tracking_level="0" version="0">
    <count>2</count>
    <item_version>3</item_version>
    <item class_id="2" tracking_level="0" version="3">
      <myName>setComputeToNextPoint</myName>
      <myArguments class_id="3" tracking_level="0" version="0">
        <count>1</count>
        <item_version>2</item_version>
        <item class_id="4" tracking_level="0" version="2">
          <myType>bool</myType>
          <myName>enabled</myName>
        </item>
      </myArguments>
      <myComments></myComments>
      <myVirtualFlag>1</myVirtualFlag>
    </item>
    <item>
      <myName>setParentId</myName>
      <myArguments>
        <count>1</count>
        <item_version>2</item_version>
        <item>
          <myType>makVrv::DtUniqueID</myType>
          <myName>parentId</myName>
        </item>
      </myArguments>
      <myComments></myComments>
      <myVirtualFlag>1</myVirtualFlag>
    </item>
  </myStates>
   <myDllExportMacro></myDllExportMacro>
   <myDllExportHeaderFile></myDllExportHeaderFile>
   <myProxyDllExportMacro></myProxyDllExportMacro>
   <myProxyDllExportHeaderFile></myProxyDllExportHeaderFile>
   <myHeaderCode>
</myHeaderCode>
   <myEncodingCode></myEncodingCode>
   <myIsAbstractFlag>0</myIsAbstractFlag>
</myClass>
</boost_serialization>

As part of the project generation process, the dcgen application willbe used to generate Agent and Class code from the ocdx file. The agent is what is created in network thread to provide API access to calls that will create makVrv::DtMessage to be processed:

      myRangeLineTextUpdaterAgent = DtAttachableRangeLineTextUpdaterAgent::create(mySimulation.sceneInterface(), myDistributeFlag);

The Classes class is the implementation of the agent. This class will be responsible for the creation of the messages. When an Agent class is created, on the visualization size the receiver class needs to be implemented. The ocdx file will specify what this receiver class is called, and, it must contain all the methods that are defined by the agent:

/******************************************************************************
** Copyright (c) 2013 MAK Technologies, Inc.
** All rights reserved.
******************************************************************************/


#pragma once

#include <vrvCore/DtAttachableUpdater.h>
#include <vrvCore/DtDisplayUnitsSettingsManager.h>

class DtAttachableRangeLineTextUpdater : public makVrv::DtAttachableUpdater
{
public:
   DtAttachableRangeLineTextUpdater( makVrv::DtDe& de, makVrv::DtUniqueID id );

   virtual ~DtAttachableRangeLineTextUpdater();

   virtual void update(double);

   virtual void setComputeToNextPoint(bool);
   
   virtual void setParentId(makVrv::DtUniqueID);

protected:
   virtual double calculateRange();

protected:
   bool myComputeToNextPoint;
   makVrv::DtUniqueID myParentId;
   double myLastRange;
   int mySourceIndex;
   bool myStopChecking;
   makVrv::DtDisplayUnitsConverter::DistanceUnits myDistanceUnits;
};

The code will then receive the data from the network thread such that is can be processed in the visualization thread:

/******************************************************************************
** Copyright (c) 2013 MAK Technologies, Inc.
** All rights reserved.
******************************************************************************/


#include "DtAttachableRangeLineTextUpdater.h"
#include <vrfGuiCore/vrfStateViewCollectionManager.h>
#include <vrfGuiCore/vrfDisplayUnitsSettingsManager.h>
#include <vrvCore/DtDe.h>
#include <vrvCore/DtSceneObject.h>
#include <vrvCore/DtWidgetLabel.h>
#include <vrvCore/DtProjectedWidgetModel.h>
#include <vrvCore/DtSelectionManager.h>
#include <vrvCore/DtAgentUpdateResolver.h>
#include <vrvCore/DtDeSharedState.h>
#include <vrvUtil/DtCoordinateSystem.h>
#include <matrix/geodeticCoord.h>
#include <matrix/coordTransform.h>
#include <matrix/topoCoord.h>
#include <makArchives/DtDisplayUnitsSettingsRecord.h>

using namespace makVrv;
using namespace makVrf;
using namespace makArchives;

#define DtALMOST(x, y, e) (((x)<=((y)+(e))) && ((x)>=((y)-(e))))

DtAttachableRangeLineTextUpdater::DtAttachableRangeLineTextUpdater( DtDe& de, DtUniqueID id )
: DtAttachableUpdater( de, id )
, myComputeToNextPoint(false)
, myParentId(0)
, myLastRange(0)
, mySourceIndex(-1)
, myStopChecking(false)
, myDistanceUnits(DtDisplayUnitsSettingsRecord::UnitsMeters)
{
}

DtAttachableRangeLineTextUpdater::~DtAttachableRangeLineTextUpdater()
{
   if (myDe.destructing())
   {
      mySceneObject = 0;
   }
}

void DtAttachableRangeLineTextUpdater::setComputeToNextPoint(bool b)
{
   myComputeToNextPoint = b;
}

void DtAttachableRangeLineTextUpdater::update(double simTime)
{
   // call down to base class to position the text
   DtAttachableUpdater::update( simTime );

   if ( ! mySceneObject )
   {
      return;
   }

   double range = calculateRange();
   DtDisplayUnitsSettingsRecord::DistanceUnits curUnits = DtVrfDisplayUnitsSettingsManager::instance(myDe).currentDistanceUnits();

   if ((range == myLastRange) && (myDistanceUnits == curUnits))
   {
      return;
   }

   myLastRange = range;
   myDistanceUnits = curUnits;

   // Iterate over scene object models to find the widget label.
   DtSceneObject::ModelList::iterator i = mySceneObject->models().begin();
   DtSceneObject::ModelList::iterator e = mySceneObject->models().end();
   for ( ; i != e; ++i )
   {
      DtProjectedWidgetModel* textModel = dynamic_cast<DtProjectedWidgetModel*>( i->model );
      if ( textModel )
      {
         // get the widgets
         std::vector<DtWidget*>& widgets = textModel->widgets();
         if ( widgets.size() > 0 )
         {
            DtWidgetLabel* widgetLabel = dynamic_cast<DtWidgetLabel*>( widgets[0] );
            if ( widgetLabel )
            {
               if (range < 0)
               {
                  widgetLabel->setText(DtUnicode::fromAscii(""));
               }
               else
               {
                  DtVrfDisplayUnitsSettingsManager& mgr = DtVrfDisplayUnitsSettingsManager::instance(myDe);
                  std::string altData = mgr.convertDistanceUnitNativeToDisplayString( range );
                  DtUnicode altNotation = mgr.currentDistanceUnitNotation();

                  DtUnicode label = DtUnicode::fromAscii( altData );
                  label += DtUnicode::fromAscii(" ");
                  label += altNotation;

                  widgetLabel->setText( label );
               }
            }
         }
      }
   }
}

double DtAttachableRangeLineTextUpdater::calculateRange()
{
   AttachedPoint* point = *( myAttachedPoints.begin() );
   ObjectAttachedPoint* attachedPoint = (ObjectAttachedPoint*) point;
   DtSceneObject* pointSceneObject = attachedPoint->sceneObject();
   DtVector vertexPosition;

   pointSceneObject->getPosition( 0, vertexPosition );

   DtVector linePosition;

   // Now find or index on the parent
   DtAgentUpdateResolverInterface* resolver = myDe.agentManager().findUpdater( myParentId );
   if( resolver )
   {
      DtSceneObject* sceneObject = resolver->castObjectTypeFromUpdater<DtSceneObject>( "DtSceneObject" );  
      if ( sceneObject )
      {
         // The scene object will contain all the points.  Iterate until we find ourselves
         int pointCount = sceneObject->transforms().size();
         if (!myStopChecking)
         {
            int i;

            for (i = 0; i < pointCount; i++)
            {
               sceneObject->getPosition(i, linePosition);

               if (linePosition == vertexPosition)
               {
                  mySourceIndex = i;
                  myStopChecking = true;
               }
               else if (DtALMOST(linePosition.x(), vertexPosition.x(), 0.00001) &&
                   DtALMOST(linePosition.y(), vertexPosition.y(), 0.00001) &&
                   DtALMOST(linePosition.z(), vertexPosition.z(), 0.00001))
               {
                  mySourceIndex = i;
                  break;
               }
            }
         }

         if (mySourceIndex != -1)
         {
            if ((mySourceIndex == 0) && !myComputeToNextPoint)
            {
               return -1;
            }
            else if ((mySourceIndex == (pointCount - 1)) && myComputeToNextPoint)
            {
               return -1;
            }
            else
            {
               if (myComputeToNextPoint)
               {
                  sceneObject->getPosition(mySourceIndex + 1, linePosition);
               }
               else
               {
                  sceneObject->getPosition(mySourceIndex - 1, linePosition);
               }

               // Convert points to geocentric and use the topographic transforms to get a topographic
               // distance.  This should be truer than a straight line distance
               myDe.sharedState().coordinateSystem().localToNetPos(vertexPosition, vertexPosition);
               myDe.sharedState().coordinateSystem().localToNetPos(linePosition, linePosition);

               DtGeodeticCoord geod;
               DtCoordTransform geocToTopo;

               geod.setGeocentric(vertexPosition);
               DtGeocToTopoTransform(geod.lat(), geod.lon(), &geocToTopo);

               geocToTopo.coordTrans(linePosition, linePosition);

               // Now simply return the distance of the resultant vector
               return sqrt(linePosition.magnitudeSquared());
            }
         }
      }
   }

   return -1;
}

void DtAttachableRangeLineTextUpdater::setParentId(DtUniqueID id)
{
   // If this id is itself a vertex then go up the chain to find the parent.  This will handle the intervisibility case
   if (DtSelectionManager::instance(myDe).objectIsVertex(id))
   {
      id = DtSelectionManager::instance(myDe).parentId(id);
   }

   // Convert this to an id of a display object so we can get the line object that represents it for the
   // vertex positions
   id = DtVrfStateViewCollectionManager::instance(myDe).displayIdFromSimId(id, makVrv::DtModelSetId::Icons2D);

   myParentId = id;
}

GUI Shared Signalers

Shared signalers are used to communicate from the visualization thread to the network thread. These use a variation of a boost signal (makVrv::event_signal) to add signals to a queue that can be processed in the network thread. This is how the visualization thread can communicate with the network thread to perform an action. One of the main signalers in use is the makVrf::DtSharedNetworkSignaler. This signaler is used to communicate with the makVrf::DtVrfConnectionHelper to perform operations on the network.

         DtSharedNetworkSignaler::instance(DtSharedSettingsManager::instance(myDe)).signal_sendMessageToObject((DtVrfObjectMessage*)m.clone(), addr);

The Network Callback Manager example shows how to create and use an event signaler:

/******************************************************************************
** Copyright (c) 2022 MAK Technologies, Inc.
** All rights reserved.
******************************************************************************/

//\brief Contains DtExampleEventSignaler class.
//An event signaler is a class that is used to signal boost style signals from
//the gui thread to the networking thread

#pragma once

#include <vrfGuiCore/vrfGuiCore.h>
#include <vrvUtil/event_signal.h>
#include <vrvUtil/DtVirtualBaseClass.h>
#include <vrvUtil/signalslib.h>

namespace makVrv
{
   class DtDe;
   class DtSharedSettingsManager;
}

class DtExampleEventSignaler : public makVrv::DtVirtualBaseClass
{
public:

   //Get an instance of the simulation settings automatically from the
   //settings manager. this will return a different signaler depending
   //on what thread this function is called from.
   static DtExampleEventSignaler& instance(const makVrv::DtSharedSettingsManager&);

   //Get an instance of the simulation settings from the event queue 
   //interface. This will return the same signaler independent of the thread.
   static DtExampleEventSignaler& instance(makVrv::DtEventQueueInterface&);

   //Find an instance of the signaler, for an interface, if one does not
   //exist it will not be created.
   //\retval NULL if the instance does not exist.
   static DtExampleEventSignaler* findInstance(
      makVrv::DtEventQueueInterface*);

   //DTOR
   virtual ~DtExampleEventSignaler();

   //@name Signals

   //\brief Signal to send a pdu from the network thread
   makVrv::event_signal<void ()> signal_sendPdu;

protected:
   DtExampleEventSignaler(makVrv::DtEventQueueInterface& eqi);

private:
   DtExampleEventSignaler(const DtExampleEventSignaler&);
   DtExampleEventSignaler& operator=(const DtExampleEventSignaler&);
};

The visualization thread uses this event signaler to post a signal to the network thread:

   DtExampleEventSignaler::instance(DtSharedSettingsManager::instance(myDe)).signal_sendPdu();

The network thread accessory then connects to that signal to process the contents during the network thread tick:

      DtExampleEventSignaler::instance(connection->settingsManager()).signal_sendPdu.connect(
         boost::bind(&DtNetworkCallbackManagerAccessory::slot_onSendPdu, this, connection));

void DtNetworkCallbackManagerAccessory::slot_onSendPdu(makVrv::DtVrlinkBaseConnection* connection)
{
   makVrv::DT_PROTOCOL_NAMESPACE::DtVrlinkConnection* vrlCon = dynamic_cast<makVrv::DT_PROTOCOL_NAMESPACE::DtVrlinkConnection*>
      (connection);

   if(vrlCon)
   {
      DtCommentInteraction testPdu;

      std::string message = "Sent from " + myName;

      testPdu.setComment(message.c_str(), message.length() + 1);

#if DtHLA
      //Needed in HLA to receive interactions sent by us
      vrlCon->exerciseConn()->setReflecting();
#endif
      vrlCon->exerciseConn()->sendStamped(testPdu);
   }
}

If event signals send parameters as part of the signal, you need to make sure these parameters can be placed on the stack. Sending temporary variables in the event signal will cause a crash when that signal goes out of scope.

Shared Read and Write Locks

Shared settings (subclasses of makVrv::DtSharedSettings) are used to communicate data in a shared, thread safeway from one thread to another. These, in conjunction with signalers, can be used to store complex data that can be written to in on thread and accessed in another. One example of this is the makVrf::DtSharedVrfVrlApplicationSettings class. This class stores data that is used between the visualization and network thread. These settings classes, in conjunction with event signalers, can be used to indicate when the status of a shared value has changed. For example, the way that the visualization thread and the network thread synchronize on start up is by this class. The setApplicationInitialized method is used to indication when the visualization thread has been initialized and the network thread can continue operation. Once the visualation thread is ready, it will get a makVrv::DtWriteSettingsLock on the application settings:

      {
      makVrv::DtWriteSettingsLock<DtSharedVrfVrlApplicationSettings> settings(DtSharedSettingsManager::instance(de()));
      settings->setGumballsDirectory(de().dePathConfiguration().dataPath() + "/images/icons/");
      settings->setApplicationInitialized(true);
      }

The network thread, each tick, checks to see if this variable has been set. If it has been, it will continue on with network processing:

            makVrv::DtReadSettingsLock<DtSharedVrfVrlApplicationSettings> settings(makVrv::DtSharedSettingsManager::instance(myAgentManager.de()));

            if (settings->applicationInitialized())
            {
               start = true;
            }

Network Message Agent

The Network Message Interface Handler is an agent class used in the network thread to wrap protocol independent DtSimInterfaceContent messages and pass them to the main thread. The makVrf::DtNetworkMessageInterface base class is used to wrap an number of protocol messages in a protocol independent way so the visualization thread can be notified of them. The messageInterfaces.h class contains the majority of these interfaces with makVrf::DtSimMessageInterface and makVrf::DtVrfObjectMessageInterface being most commonly used. The makVrf::DtNetworkMessageInterfaceHandler is the main thread representation of this agent. The messageReceived message will be called on the visual side and then pass it to the makVrf::DtGuiThreadNetworkCallbackManager. Once received, the makVrf::DtGuiThreadNetworkCallbackManager will use the name() method to figure out, by callbacks registered, what method to call

      networkInterfaceMessageSignal(DtSimMessageInterface::theName()).connect(
         boost::bind(&DtGuiThreadNetworkCallbackManager::processSimMessageCallback, this, _1));
      networkInterfaceMessageSignal(DtVrfObjectMessageInterface::theName()).connect(
         boost::bind(&DtGuiThreadNetworkCallbackManager::processVrfObjectMessageInterfaceCallback, this, _1));

When this message is received from the agent, methods that were registered to be called when an interface message of a certain type is received will be executed

      CONNECT_FOR_SIM_MESSAGE(DtSensorDataMessageType,
         boost::bind(&DtVrfSensorInfoManager::processSensorData, this, _1));

   void DtVrfSensorInfoManager::processSensorData(DtSimMessage* msg)
   {
      DtIfSensorData& s = *(static_cast<DtIfSensorData*>(
         static_cast<DtSimInterfaceMessage*>(msg)->interfaceContent()));

         DISCONNECT_FOR_SIM_MESSAGE(DtSensorDataMessageType,
          boost::bind(&DtVrfSensorInfoManager::processSensorData, this, _1));

The following convenience macros (in guiThreadNetworkManager.h) are available:

#define CONNECT_FOR_SIM_MESSAGE(_type, _function) makVrf::DtGuiThreadNetworkCallbackManager::instance(myDe).simMessageSignal(_type).connect(_function);
#define DISCONNECT_FOR_SIM_MESSAGE(_type, _function) makVrf::DtGuiThreadNetworkCallbackManager::instance(myDe).simMessageSignal(_type).disconnect(_function);

#define CONNECT_FOR_OBJECT_MESSAGE(_type, _function) makVrf::DtGuiThreadNetworkCallbackManager::instance(myDe).objectMessageSignal(_type).connect(_function);
#define DISCONNECT_FOR_OBJECT_MESSAGE(_type, _function) makVrf::DtGuiThreadNetworkCallbackManager::instance(myDe).objectMessageSignal(_type).disconnect(_function);

#define CONNECT_FOR_COMMENT_INTERACTION(_function) makVrf::DtGuiThreadNetworkCallbackManager::instance(myDe).networkInterfaceMessageSignal(DtCommentInteractionInterface::theName()).connect(_function);
#define DISCONNECT_FOR_COMMENT_INTERACTION(_function) makVrf::DtGuiThreadNetworkCallbackManager::instance(myDe).networkInterfaceMessageSignal(DtCommentInteractionInterface::theName()).disconnect(_function);

#define CONNECT_FOR_INFLUENCE_INTERACTION(_function) makVrf::DtGuiThreadNetworkCallbackManager::instance(myDe).networkInterfaceMessageSignal(DtInfluenceInteractionInterface::theName()).connect(_function);
#define DISCONNECT_FOR_INFLUENCE_INTERACTION(_function) makVrf::DtGuiThreadNetworkCallbackManager::instance(myDe).networkInterfaceMessageSignal(DtInfluenceInteractionInterface::theName()).disconnect(_function);

#define CONNECT_FOR_RADIO_MESSAGE(_type, _function) makVrf::DtGuiThreadNetworkCallbackManager::instance(myDe).radioMessageSignal(_type).connect(_function);
#define DISCONNECT_FOR_RADIO_MESSAGE(_type, _function) makVrf::DtGuiThreadNetworkCallbackManager::instance(myDe).radioMessageSignal(_type).disconnect(_function);

Also see The Network Callback Manager see Display Metrics for an example of how to connect to a radio message