Add Conditional (addConditionalSim)

Table of Contents

• Adding a New Conditional Expression Data Class
• Adding a new Conditional Expression Evaluator
• How to Run the Example
  • Usage
• Classes
• Plugin Entry Points

The Add Conditional example demonstrates the following:

• How to create and register a new conditional
• How to create a conditional evaluator to evaluate the new condition

The Add Conditional example adds a new conditional evaulator, MyEvaluator, that will be used to test whether or not the requested entity is facing north (heading of 0 degrees)

To add a new kind of conditional expression to VR-Forces, you must create two new derived classes: a new conditional expression data class (DtSimCondExpr), and a new conditional expression evaluator class (DtEvaluator). The conditional expression data class represents the (optional) data parameters used in your conditional expression (for example, the name of an area to test in the entity-in-area class, DtCeEntInArea). The evaluator class contains an evaluate() member function that performs the test for the given DtSimCondExpr (for example, the DtEvalEntInArea class tests for the entity in area condition for a given DtCeEntInArea object).

Adding a New Conditional Expression Data Class

To add a new kind of conditional expression data class, you must derive a new class from DtSimCondExpr or one of its subclasses. This example derives the class vrfAddConditionalExample::MyConditionalExpression directly from DtSimCondExpr. The new class must provide the member functions described below:

DtSimCondExpr::type()	Returns an integer uniquely identifying the kind of conditional expression. Choose a type that does not conflict with any existing types (existing types are defined in condExprTypes.h).
DtSimCondExpr::clone()	Returns a newly allocated copy of this object.
DtSimCondExpr::netRepSize()	Returns the size of the network representation of the object.
DtSimCondExpr::stringRep()	Returns a string representation for the expression.
DtSimCondExpr::setFromNet()	Sets the member data in the class from a network representation of the class.
DtSimCondExpr::setToNet()	Maps the member data in the class to the network representation for the class.
DtSimCondExpr::creator()	Returns a newly created instance of the class.

The new class must implement the netRepSize(), setToNet(), and setFromNet() member functions to make the conditional expression capable of being sent over the network. For examples and a discussion of how to implement these functions, please see Creating the Network Representation.

After creation of the new DtSimCondExpr class, the new conditional expression class must be registered with the conditional expression factory. Adding it to the factory makes the class available for use any time the new type is encountered (such as when reading from a plan file, or when receiving a plan containing the new expression over the network). For more information about how to register a new conditional expression class with the factory, please see VR-Forces Factories. Registration of the new DtSimCondExpr, in our example done in vrfAddConditionalExample::DtInitializeVrfPlugin, looks like this:

      //Register MyConditionalExpression with the DtCondExprFactory
         cgf->factoryManager()->condExprFactory()->addCreatorFcn( DtCeFacingNorthTypeName, DtCondExprFacingNorthType, MyConditionalExpression::creator);  

where vrfAddConditionalExample::MyConditionalExpression is the new DtSimCondExpr class, vrfAddConditionalExample::DtCondExprFacingNorthType is the new integer returned in implementation of vrfAddConditionalExample::MyConditionalExpression::type(), and vrfAddConditionalExample::DtCeFacingNorthTypeName is the string type which represents vrfAddConditionalExample::MyConditionalExpression in plan files. It must not contain any spaces.

Adding a new Conditional Expression Evaluator

To add a new evaluator class for a new conditional expression, a new class must be derived from DtEvaluator (evaluator.h) or one of its subclasses. This example derives the new evaluator class vrfAddConditionalExample::MyEvaluator directly from DtEvaluator. The new class you must provide the member functions described below.

DtEvaluator::evaluate()	Evaluates the given DtSimCondExpr.
DtEvaluator::clone()	Returns a newly allocated copy of this object.
DtEvaluator::creator()	Returns a newly created instance of the class.

Just as with the new DtSimCondExpr class, the new evaluator class must be registered with the evaluator factory. Care must be taken that it is registered with the same integer type assigned to the new DtSimCondExpr class. In our example:

      //Register MyEvaluator with the DtEvaluatorFactory
         cgf->factoryManager()->evaluatorFactory()->addCreatorFcn( DtCondExprFacingNorthType, MyEvaluator::creator);

where vrfAddConditionalExample::MyEvaluator is the new DtEvaluator class, and vrfAddConditionalExample::DtCondExprFacingNorthType is the integer type registed with the conditional factory and returned in the implementation of vrfAddConditionalExample::MyConditionalExpression::type().

The evaluate() function is where the conditional expression test to be performed is implemented. The evaluate() function takes a DtSimCondExpr* as one of its arguments. If new DtEvaluator class has been properly registered with the evaluator factory using the same integer type as the new DtSimCondExpr, the incoming base DtSimCondExpr* may be safely downcast to vrfAddConditionalExample::myConditionalExpression, the new derived class type.

Note again that the new DtEvaluator class and the new DtSimCondExpr must be registered with the factory using the same integer type. In our example, we set this to be a constant, vrfAddConditionalExample::DtCondExprFacingNorthType, in addConditional/addConditionalSim/conditionalExpression.h. Failure to maintain a consistent and unique integer type will result in undefined behavior.

Once the new DtSimCondExpr and DtEvaluator subclasses are created and registered, the new expression can be used in VR-Forces. VR-Forces takes care of creating and configuring the new conditional expression and its corresponding evaluator whenever it encounters them (such as when reading in plan files, or when receiving plans over the network).

Since this example is loaded as a plugin, it can be used in conjunctio nwith the released VR-Forces application

How to Run the Example

This example demonstrates how to add a new kind of conditional test that can be used within a conditional expression.

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 EntityLevel scneario (any terrain can be used - e.g. Ground_DB II).
3. Create a new M1A2. By default, it will be facing north.
4. Create a second M1A2.
5. Set the heading of the second M1A2 to 90 degrees (facing east).
6. Create a new plan for the first entity. Add an 'If' expression with the new 'Facing North' condition.
7. In the 'Then' clause, give the entity a move-to-location task.
8. Create a similar new plan for the second entity (same 'If/Then' statement).
9. View the plan windows for each entity.
10. Hit play.
11. Observe that the first M1A2 (that was facing north by default) moves, while the second entity (not facing north) remains stationary.

Classes

MyConditionalExpression	The subclass of DtSimCondExpr that is used to communicate the new conditional.
MyEvaluator	The subclass of DtEvaluator that evaluates the MyConditionalExpression.
MySearch	Used by MyEvaluator to test the MyConditionalExpression for truth.

Plugin Entry Points

/*******************************************************************************
** Copyright (c) 2003 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
/*******************************************************************************
** $RCSfile: plugin.cxx,v $ $Revision: 1.1 $ $State: Exp $
*******************************************************************************/

//VR-Forces includes
#include "vrfcgf/vrfPluginExtension.h"
#include "conditionalExpression.h"
#include "northEvaluator.h"

//VR-Forces includes
#include "vrfcgf/cgf.h"
#include "vrfcgf/factoryManager.h"


namespace vrfAddConditionalExample
{
   extern "C" {

   DT_VRF_DLL_PLUGIN void DtPluginInformation(DtVrfPluginInformation& info)
   {
      info.pluginName = "addConditional Sim";
      info.pluginDescription = "This is an example of how to add a condition to the back-end.";
      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";
   }

   DT_VRF_DLL_PLUGIN bool DtInitializeVrfPlugin(DtCgf* cgf)
   {
         //[register conditional with factory]
      //Register MyConditionalExpression with the DtCondExprFactory
         cgf->factoryManager()->condExprFactory()->addCreatorFcn( DtCeFacingNorthTypeName, DtCondExprFacingNorthType, MyConditionalExpression::creator);  
         //[register conditional with factory]

         //[register evaluator with factory]
      //Register MyEvaluator with the DtEvaluatorFactory
         cgf->factoryManager()->evaluatorFactory()->addCreatorFcn( DtCondExprFacingNorthType, MyEvaluator::creator);
         //[register evaluator with factory]

      return true;
   }
   }
}