Range Line (rangeLine)

Table of Contents

• Adding a New Tactical Graphic Object
• How to Run the Example
  • Usage
• Plugin Entry Points

The Range Line example demonstrates the following:

• How to build a plugin module for the VR-Forces Gui
• How to add a new visualizer
• How to add an attachable updater
• How to create a new visualizer definition set for a new displayable object
• How to add a new object to the create menu
• How to modify an intervisibility symbol to add a new visualizer to it

Adding a New Tactical Graphic Object

The Range Line example demonstrates how to add a new visual definition to show a line of range between two points.

The Range Line is added as a new tactical graphic object. It will also show how to install a subclass of the vertex visualizer to add information next to a vertex (in this case, the range to the previous or next point).

This example also replaces the vertex used by the entity intervisibility fan to show the distance from the origin to the outer edge of this fan. The distance label will be shown close to the origin of the fan. If you try and attach this fan to an entity it is possible the entity will occlude the label

Reference this example in order to see how to replace existing visualizers and to add a new visualizer concept to the front-end.

How to Run the Example

Usage

In the Launcher, click the Plug-ins button to bring up the Plug-ins Selection dialog. Enable the plugin.

To view the new behavior:

1. Start VR-Forces GUI and SIM.
2. Create a new scneario - e.g. EntityLevel on Ground_DB II terrain.
3. Click on to open the Tactical Graphics tab.
4. You should observe a new Range Line object added to the list of the available objects.
5. Select and create a Range Line object - similarly to how the routes are created.
6. A Range Line object will be created on the terrain.

Plugin Entry Points

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

//\file rangeLine.cxx

//This file defines the generic DT_DLL_VRF_PLUGIN_EXPORT_MACRO.  Use that macro when
//you want to export symbols.
#include <vrfGuiCore/vrfGuiExportPlugin.h>

#include "rangeLineVisualizer.h"

#include <vrfGuiCore/vrfModelSetManager.h>
#include <vrfGuiCore/scenarioSignaler.h>
#include <vrfGuiCore/entityMapperKey.h>

#include <vrfobjparam/modelSetEntry.h>
#include <vrfutil/rwNLengthStringVector.h>
#include <vrvCore/DtSharedSettingsManager.h>
#include <vrvCore/DtIntervisibilityVertexVisualizer.h>
#include <vrvVrl/DtSharedSimulationSettings.h>
#include <vrvVrl/DtEntityTypeMapper.h>
#include <vrvCore/DtWriteSettingsLock.h>
#include <vrvCore/DtBuiltInSchemas.h>
#include <vrvCore/DtStateVisualizerFactory.h>
#include <vrvCore/DtVisualizerDefinitionSet.h>
#include <vrvCore/DtElementDefinitionManager.h>
#include <vrvCore/DtElementDefinition.h>
#include <vrvCore/DtVisualizerSchema.h>
#include <vrvCore/DtVisualizerAttribute.h>
#include <vrvCore/DtVisualizerDefinition.h>
#include <vrvCore/DtVisualizerAttributeFactory.h>
#include <vrvUtil/DtUnicode.h>

using namespace makVrf;
using namespace makVrv;

static DtUnicode theRangeLineDefinition = DtUnicode::fromAscii("Range_Line");
static DtUnicode theRangeVertexDefinition = DtUnicode::fromAscii("RangedVertex");
static DtUnicode theRangeVertexIVDefinition = DtUnicode::fromAscii("RangedIVVertex");

static const DtEntityMapperKey theRangeLineType(-1, 17,1,0,12,0,0,0);   // Range line type

// Because the create menu is recreated with each new scenario, need to manipulate the menu here after it
// has been loaded.  If the range line item is not present, add it
void DtCreateMenuConfigurationLoaded(DtDe* de)
{
   if (!DtVrfModelSetManager::instance(*de).exactModelSetEntry(theRangeLineType))
   {
      // Put this into its own category for easy finding
      DtRwNLengthStringVector cats("categories");

      cats.add("Distance");
      DtModelSetEntry* entry = DtVrfModelSetManager::instance(*de).addModelSetEntry("Range Line", theRangeLineType, cats);

      // After added, add an icon for it
      entry->setMenuIcon("$(DATA_DIR)/images/overlays/small/line.png");
   }
}

void disableHATLinesFor(DtDe& de, DtVisualizerDefinitionSet& set)
{
   std::vector<DtVisualizerDefinition*> defs;

   set.findVisualizerDefinitions(DtBuiltInSchemas::theDtHATLineSchema().name(), defs);

   if (defs.size())
   {
      // Now that we have it, change the vertex visualizer set used to our ranged vertex visualizer set by
      // first disabling the HAT lines so they do not occlude the range
      DtVisualizerAttributeBool* setValue = dynamic_cast<DtVisualizerAttributeBool*>(
         defs[0]->findOrCreateLocalAttribute("enabled"));

      // Could not find, so create one
      if (!setValue)
      {
         setValue = 
            dynamic_cast<DtVisualizerAttributeBool*>(
            DtVisualizerAttributeFactory::instance(de).create(DtVisualizerAttributeBool::theTypeInfo().className));
         setValue->setValue(false);
         defs[0]->setAttribute("enabled", std::auto_ptr<DtVisualizerAttribute>(setValue));
      }
      else
      {
         *setValue = false;
      }
   }
}

DtVisualizerDefinition* createRangeVertexDefinition(DtDe& de, DtElementDefinition* curDef, const DtUnicode& newDef)
{
   DtElementDefinitionTypeManager& typeMgr = DtElementDefinitionTypeManager::instance(de);
   DtElementDefinitionManager* manager = typeMgr.findElementManager(DtElementDefinitionTypeManager::TacticalGraphics);
   DtElementDefinition* rangeVertexDef = manager->createElementDefinition(newDef, curDef);

   if (rangeVertexDef)
   {
      // For the 2D model set, find and disable the current vertex visualizer as we are going to replace it
      DtVisualizerDefinitionSet& set = rangeVertexDef->visualizerDefinitionSet(makVrv::DtModelSetId::Icons2D);

      disableHATLinesFor(de, set);

      // And, finally, add the new ranged vertex definition

      DtVisualizerDefinition* rangeDefinition = set.createVisualizerDefinition(
         DtRangeLineTextVisualizer::theRangeLineTextSchema().name());

      // Set up the minimal values to make sure the visualizer will work after being added
      DtVisualizerAttributeString* attr = 
         dynamic_cast<DtVisualizerAttributeString*>(
         DtVisualizerAttributeFactory::instance(de).create(DtVisualizerAttributeString::theTypeInfo().className));
      attr->setValue(DtUnicode::fromAscii("Main Object"));
      rangeDefinition->setAttribute("parent", std::auto_ptr<DtVisualizerAttribute>(attr));

      attr = 
         dynamic_cast<DtVisualizerAttributeString*>(
         DtVisualizerAttributeFactory::instance(de).create(DtVisualizerAttributeString::theTypeInfo().className));
      attr->setValue(DtUnicode::fromAscii("DtRangeLineTextVisualizer"));
      rangeDefinition->setAttribute("type", std::auto_ptr<DtVisualizerAttribute>(attr));

      attr = 
         dynamic_cast<DtVisualizerAttributeString*>(
         DtVisualizerAttributeFactory::instance(de).create(DtVisualizerAttributeString::theTypeInfo().className));
      attr->setValue(DtUnicode::fromAscii("main_model"));
      rangeDefinition->setAttribute("visualtype", std::auto_ptr<DtVisualizerAttribute>(attr));

      return rangeDefinition;
   }

   return 0;
}

// Since the intervisibility dictionary is not created until the first post tick, we must connect to a post tick and finish the setup
// here
void setupRangeLine(DtDe* de)
{
   // Only going to add this new visualizer set to the range line, so, for the range line, create it as a
   // child of the existing route visualizer, turn off the existing vertex visualizer and add the new vertex visualizer which is
   // the range of the line -- which does not include height above terrain.  Since this is only currently being supported in 2D (model set 5) this is
   // the only changes that will be made to the visualizer definition

   // For the mapped types, add the new type into the tactical graphic mapper to map to
   // what will be the new range route definition
   {
      DtWriteSettingsLock<DtSharedSimulationSettings> settings(DtSharedSettingsManager::instance(*de));

      const DtEntityTypeMapper::NameList* names = settings->tacticalGraphicsMapper().findMappings(theRangeLineType);

      if (names)
      {
         settings->tacticalGraphicsMapper().removeMappings(theRangeLineType);
      }

      settings->tacticalGraphicsMapper().addMapping(theRangeLineType, theRangeLineDefinition);
   }

   // Add the creator into the factory for the range line text visualizer
   DtStateVisualizerFactory::instance(*de).addStateVisualizerCreator(*de, new DtRangeLineTextVisualizerCreator);

   // First, get the tactical graphic manager
   DtElementDefinitionTypeManager& typeMgr = DtElementDefinitionTypeManager::instance(*de);
   DtElementDefinitionManager* manager = typeMgr.findElementManager(DtElementDefinitionTypeManager::TacticalGraphics);

   // First make sure the definition is not already there.  If it is not, then add it
   if (!manager->findElementDefinition(theRangeLineDefinition))
   {
      DtElementDefinition* curDef = manager->findElementDefinition(DtUnicode::fromAscii("Route"));

      if (curDef)
      {
         // Create the route definition as part of the parent
         DtElementDefinition* rangeLineDef = manager->createElementDefinition(theRangeLineDefinition, curDef);

         if (rangeLineDef)
         {
            std::vector<makVrv::DtModelSetId> sets = {makVrv::DtModelSetId::Models3D, makVrv::DtModelSetId::ModelsColorized, makVrv::DtModelSetId::Icons2D};
            for(auto i : sets)
            {
               // For each model set
               DtVisualizerDefinitionSet& set = rangeLineDef->visualizerDefinitionSet(i);

               std::vector<DtVisualizerDefinition*> defs;

               set.findVisualizerDefinitions(DtBuiltInSchemas::theDtShapeVertexSchema().name(), defs);

               if (defs.size())
               {
                  DtVisualizerDefinition* childDef = set.createVisualizerDefinition(defs[0]);

                  if (childDef)
                  {
                     // Now that we have it, change the vertex visualizer set used to our ranged vertex visualizer set
                     DtVisualizerAttributeString* setValue = dynamic_cast<DtVisualizerAttributeString*>(
                        childDef->findOrCreateLocalAttribute("vertexelementdefinition"));

                     if (setValue)
                     {
                        *setValue = theRangeVertexDefinition;
                     }               
                  }
               }
            }
         }
      }
   }

   // Now see if we need to add the ranged vertex definition.  This will be a child of the existing Vertex definition
   // that will turn off the hat line visualizer and add the range line visualizer for 2D only
   if (!manager->findElementDefinition(theRangeVertexDefinition))
   {
      DtElementDefinition* curDef = manager->findElementDefinition(DtUnicode::fromAscii("Vertex"));

      if (curDef)
      {
         createRangeVertexDefinition(*de, curDef, theRangeVertexDefinition);
      }

      curDef = manager->findElementDefinition(DtUnicode::fromAscii("IntervisibilityVertex"));

      if (curDef)
      {
         DtVisualizerDefinition* ivVertexDef = createRangeVertexDefinition(*de, curDef, theRangeVertexIVDefinition);

         // Since the only definition for the entity fan is at the origin for a vertex, compute the range as from this
         // point to the next
         if (ivVertexDef)
         {
            // Now that we have it, change the vertex visualizer set used to our ranged vertex visualizer set by
            // first disabling the HAT lines so they do not occlude the range
            DtVisualizerAttributeBool* setValue = dynamic_cast<DtVisualizerAttributeBool*>(
               ivVertexDef->findOrCreateLocalAttribute("computeToNextPoint"));

            // Could not find, so create one
            if (!setValue)
            {
               setValue = 
                  dynamic_cast<DtVisualizerAttributeBool*>(
                  DtVisualizerAttributeFactory::instance(*de).create(DtVisualizerAttributeBool::theTypeInfo().className));
               setValue->setValue(true);
               ivVertexDef->setAttribute("computeToNextPoint", std::auto_ptr<DtVisualizerAttribute>(setValue));
            }
            else
            {
               *setValue = true;
            }
         }
      }
   }

   DtElementDefinition* fanDef = manager->findElementDefinition(DtUnicode::fromAscii("IntervisibilityEntityFan"));

   if (fanDef)
   {
      // For the 2D model set, find and disable the current vertex visualizer as we are going to replace it
      DtVisualizerDefinitionSet& set = fanDef->visualizerDefinitionSet(makVrv::DtModelSetId::Icons2D);

      disableHATLinesFor(*de, set);

      std::vector<DtVisualizerDefinition*> defs;

      set.findVisualizerDefinitions(DtIntervisibilityVertexVisualizer::theTypeInfo().schema.name(), defs);

      if (defs.size())
      {
         // Now that we have it, change the vertex visualizer set used to our ranged vertex visualizer set
         DtVisualizerAttributeString* setValue = dynamic_cast<DtVisualizerAttributeString*>(
            defs[0]->findOrCreateLocalAttribute("vertexelementdefinition"));

         if (setValue)
         {
            *setValue = theRangeVertexIVDefinition;
         }               
      }
   }
}

//Now that the application has been initialized the new route line and visualizer can be added to our range line.  This needs to be done
//here to make sure that any new additions are properly added to the communication thread
void postInitDeModule(DtDe& de)
{
   //Because the create menu is now populated by a settings file that is part of
   //each simulation model set, setup a signal connection to be made to remove
   //the create menu item from the model set as it is loaded
   DtScenarioSignaler::instance(de).signal_postLoadModelSetFiles.connect
      (boost::bind(&DtCreateMenuConfigurationLoaded, &de));

   // Connect to the scenario manager's visuals modified signal to set up the range line visuals
   DtScenarioSignaler::instance(de).signal_postLoadVisuals.connect(boost::bind(&setupRangeLine, &de));
}

//This function is called by our plugin structure to make changes to the front end.  This method will add a connection to
//be called when the create menu is loaded.  At that point a new item will be added for the range line
bool initDeModule(DtDe* de)
{
   return true;
}

//This function is also called by our plugin structure and prints out information about this plugin
//to the logs. It's a good indicator that the plugin loaded if you are looking at the logs. 
void DtPluginInformation(DtVrfPluginInformation& info)
{
   info.pluginName = "Range Line";
   info.pluginDescription = "This example shows how to create a new object from scratch and create a new visualizer and updater";
   info.pluginVersion = "1.00";
   info.pluginCreator = "MAK Technologies";
   info.pluginCreatorEmail = "sales@mak.com";
   info.pluginContactWebPage = "www.mak.com";
   info.pluginContactMailingAddress = "10 Fawcett Street, Suite 204, Cambridge, MA 02138 USA";
   info.pluginContactPhone = "(617) 876 8085";
}