Using the DtCgf Class

Table of Contents

• Calling the DtCgf Constructor
• Initializing A DtCgf
• DtCgf Member Functions
  • Functions for Managing Scenarios
  • Functions for Running a Scenario
  • Functions for Managing Objects

The following example is a minimal VR-Forces application.

This example can execute whatever arbitrarily complex scenario is described by foo.scn, and will act as a full-fledged CGF participating in an HLA federation.

Example DT-1

#include <vl/exerciseConn.h>
#include <vrfcgf/cgf.h>

int main()
{
   DtCgf cgf(DtSimulationAddress(1, 3001));
   DtExerciseConn exConn("VR-Link", "Minimal");
   cgf.init(&exConn);

   cgf.loadScenario("foo.scn");
   cgf.run();
   while (1)
   {
      cgf.tick();
   }
}

This example:

1. Creates and initializes an instance of DtCgf.
2. Uses its loadScenario() function to instruct it to load a VR-Forces scenario.
3. Calls its run() function to tell it to start advancing simulation time.
4. Calls tick() periodically.

The tick() member function is where DtCgf does its real work - performing the operations required for a single simulation frame. Here, information about remotely simulated objects is gathered, sensor input is computed, tasks and behaviors are executed, vehicle dynamics are calculated, and current state is sent to other simulations. Every VR-Forces application needs to tick DtCgf once per simulation frame.

Calling the DtCgf Constructor

DtCgf's constructor expects a DtSimulationAddress as an argument. The simulation address is an identifier used to distinguish a VR-Forces application from other simulations that may be playing in the same exercise. We need to be able to identify a particular VR-Forces application so that VR-Forces remote control applications like vrfGui can address a specific simulation engine when it asks for a new object to be created. Simulation addresses are also used in a scenario’s object map file to indicate which simulation engine is responsible for simulating each object in the scenario.

DtSimulationAddress is a VR-Link class (defined in hostStructs.h) that consists of a site ID and an application ID, both integers.

The second, optional, argument to the DtCgf constructor is a session ID. Passing a value other than the default is required only when you have multiple VR-Forces applications in the same exercise, and they are using different terrains. Please see "VR-Forces Sessions", in VR-Forces Users Guide for a discussion of how to use session IDs. Please see VR-Forces Sessions, for information about how session IDs are implemented in the VR-Forces API.

Initializing A DtCgf

Before you can use an instance of DtCgf, you must call its init() function. The init() function requires a pointer to a DtExerciseConn - the VR-Link class that represents an application's connection to a DIS or HLA exercise. DtCgf and its child classes use the DtExerciseConn for all communication with other simulations in the exercise.

DtExerciseConn has several constructors, and a variety of constructor arguments, whose use depends on whether you are building a DIS or HLA application. Please see VR-Link documentation for details. In Example DT-1, we passed the name of an HLA federation execution (VR-Link), and a name for the federate (Minimal).

The second, optional, argument to init() is a pointer to a DtVrfCreator (defined in vrfCreator.h). An instance of DtVrfCreator is used by DtCgf to create instances of the various classes that it needs. If you are not customizing the simulation engine (adding custom vehicle dynamics code, new messages or tasks, and so on), then you can just pass the default value of NULL, which is an indication to the DtCgf that it should use the default creator. Please see The VR-Forces Creator, for more information about DtVrfCreator.

DtCgf Member Functions

This section describes some of the important DtCgf member functions.

The ./examples directory has two examples of using DtCgf. The simpleCGF example shows how to create a scenario programmatically. The simplePlan example shows how to create a plan programmatically.

Functions for Managing Scenarios

DtCgf has scenario management functions, such as loadScenario(), closeScenario(), newScenario(), and saveScenario(). Calling saveScenario() for example, causes your application to save a scenario file, along with an order of battle file, a plan file, and an object map file that contain information about the objects that your application is simulating.

These functions apply only to the local VR-Forces simulation engine. Other VR-Forces applications in your exercise are not affected when you call these functions. If you are using multiple simulation engines to simulate a scenario, an external application must coordinate them (usually through the remote control API). Please see The VR-Forces Remote Control API, for more information.

Functions for Running a Scenario

A VR-Forces simulation engine is always either in a running or paused state of execution. Calling run() and pause() toggles between these states. When in paused mode, very little happens during DtCgf's tick(). Time does not advance, and therefore simulation does not need to occur.

Calling rewind() causes the DtCgf to reinitialize to the state dictated by the scenario file you have loaded (or restart from a blank slate if you were not working from an existing scenario.)

Functions for Managing Objects

DtCgf contains functions that instruct the simulation engine to create, delete, or task various simulation objects. For example, when the vrfSim application gets a message from a vrfGui application indicating that a user has created an entity from the GUI, it calls DtCgf::createEntity(). Similarly if you want to programmatically create a locally simulated entity, you can call createEntity() from within your application. (Modifying an entity's state is typically done through the entity object itself rather than through the DtCgf. Please see Tasks, Sets, Commands, and Reports for details.)

[<< Getting Started with the VR-Forces Simulation API] [Home] [Top of Page] [Creating a Plug-in >>]