VR-Forces 5.0 API Migration Guide

Table of Contents

• Overview
• Threading Overview
• Key API Changes
  • DtVrfObject
  • DtVrfObjectManager
  • DtSimManager and DtSimulationServices
• Simulation Object State
  • State Components
  • Facades
  • Internal State
  • VRF 4 Compatible API
• Object Creation
• Network Connection Changes
• Library Changes

Overview

The changes to VR-Forces 5.0 API are all centered around making VR-Forces sim engine a fully multithreaded application, thereby allowing it to take full advantage of as many CPUs as are available on the hardware. To do this, VRF has added some access limitations between various aspects of the API to help prevent plugin developers from inadvertently writing code that breaks the thread safety.

A compile macro can enable a “VRF4 API” to help migrate existing plugins to VRF 5. See VRF 4 Compatible API

Scenarios from VRF 4.10 will load and run in VRF 5.0.

Threading Overview

VR-Forces 5.0 has a major threading overhaul allowing it to take advantage of many CPUs. This overhaul has requires that some access to data be restricted. See Threading Model for details.

Key API Changes

DtVrfObject

The DtVrfObject class has been split into two classes:

• DtLocalObject: This class is instantiated for all locally simulated objects in a sim engine. It holds all the subcomponents (sensors, controllers, actuators) as well as the vrfInternalState of the object. This class has the tick() function that is called when this local object is ticked each frame. Multiple threads should never access the same DtLocalObject instance at the same time.
• DtSimObject: This class provides read-only access to all the public data for a simulation object and is instantiated on a simulation engine for all known objects, both local and remote. This class is thread safe during a simulation frame and can be accessed by all threads at that time. This is the class used when controllers query the system for lists of simulation objects, for example when searching of objects in an area.

  Note

  A sim engine will have both a DtLocalObject and DtSimObject instance for the same local object which will have different addresses, so a pointer equivalence check will not work to check if two class instances represent the same simulation object.

DtVrfObjectManager

The DtVrfObjectManager class has been split into two classes:

• DtLocalObjectManager: This class owns and manages the list of locally simulated objects (DtLocalObject instances) and ticks them each during the simulation frame. It also handles creation and deletion of local objects. This class is not thread safe.
• DtSimObjectManager: This class maintains the list of all known simulation objects (DtSimObject instances) both local and remote. It provides lookup functions for finding objects. This class is thread safe during the simulation frame.

DtSimManager and DtSimulationServices

DtSimManager still exists as the top level owner to much of the simulation engine, but is no longer passed into DtVrfLocalObjects and their subcomponents. Instead, a new class called DtSimulationServices is passed into many classes. DtSimulationServices gives access to many of the different central managers and services that are needed by simulation components during their tick function, such as the DtSimObjectManager, exercise clock, and many other services. DtSimulationServices is a thread safe API and can be called from all these locations without locks.

The DtSimManager class is not thread safe and gives access to other non-thread safe classes. This is still accessible from the DtCgf class, and should only be used outside of the object tick when other threads are not running.

Simulation Object State

The state data associated with a simulated object is now broken up into distinct pieces:

• External State: State which is viewable by other objects in the simulation. This state is double-buffered.
• Internal State: State which is accessible only to components of the object that owns it. This state is single-buffered.

See Also

vrfLocalObjectStateOverview

State Components

A new system for holding external state data for simulation objects introduced in VRF 5 is known as state components. The set of state data for any given simulation object is composed of a collection of state components. Each state component contains a set of related data elements for a specific purpose.

Example state components:

• DtLocationStateComponent contains position, orientation and other kinematic data for an object.
• DtVrfStateComponent contains VRF specific data elements that apply to all VRF simulated objects, such as label, hasPlan and extended data.
• DtHumanStateComponent contains data specific for human entities, such as character type and animation name.

State components can be accessed using the getStateComponent() and getNextFrameStateComponent() functions on DtSimObject and DtLocalObject, and passing the state component type as a template argument. Functions like DtSimObject::worldPosition() and DtLocalObject::setNextFrameWorldPosition() are convenience methods for calling down into the Location State Component, which is common to all simulated objects.

Facades

DtSimObjectFacade and DtLocalObjectFacade are convenience classes for accessing external state of an object without needing to use the State Components directly. There are different façade classes, each organized around a particular functionality set, which provide access to the data in one or more state components. Each façade has a SimObject and a LocalObject version. Many cases in VRF 4.x where a dynamic_cast was used on a state repository to access external state should be replaced with a facade in VRF 5.0.

See Also

SimObject and LocalObject Facade Classes

Internal State

Internal state is data that is private to a particular simulation object and cannot be safely accessed by other simulation objects directly. For example:

• Contacts list
• Current targets

This data is stored in the DtVrfObjectStateRepository class and subclasses. This structure has not changed from VRF 4.x, but it now holds only internal state and is accessed using DtLocalObject::internalState().

In VRF 4.x, sensors, actuators and controllers hold internal state local to their function in process state repositories. This remains unchanged in VRF 5.

VRF 4 Compatible API

To make upgrading sim engine plugins to VRF 4 easier, VR-Forces now has a preprocessor flag that allows the use of a set of functions that exist in the VRF 4 API but have been removed in VRF 5. By default, these functions are not available, and will cause a compile error if used. To enable them, define the ALLOW_VRF4API macro to 1. This can be done for a whole project, or on a file-by-file basis. The VRF4 API does not cover the complete set of changes between VRF 4 and 5, so some changes are still needed.

Note

When using the VRF 4 API, the distinction between current frame and next frame state data can become unclear, since most accessors will return current frame data, and setters will alter the next frame data. This means that any code that sets some state data, such as location, and then immediately retrieves the same state will have a change in behavior between VRF 4 and VRF 5 because data is not copied from next frame to current frame until the end of the frame in VRF 5.

Key API calls enabled with ALLOW_VRF4API:

• DtVrfObject is typedefed to DtLocalObject.
• DtVrfObjectManager is typedefed to DtLocalObjectManager.
• DtLocalObject::vrfState() calls DtLocalObject::internalState()
• All functions within DtVrfObjectStateRepository that return and set external state in VRF4 are available, can call into the external state of the simulation object.

Object Creation

To protect from threading errors, the creation and deletion of one simulation object by another has been altered. All these operations are now performed using DtCreateObjectServiceInterface from DtSimulationServices. DtCreateObjectServiceInterface::createAndInitVrfObject() is not able to return a pointer to the newly created DtLocalObject anymore, as this accessing one DtLocalObject from within another would violate the threading boundry. Instead, it returns a DtCreateObjectHandle instance which contains the DtUUID and marking text of the new object. This object can be looked up in the DtSimObjectManager, but is not valid to use until the following frame.

Any state that needs to be set in the newly created object from the creating object must now be done using the DtVrfLocalObjectCreateInformation class as an argument into DtCreateObjectServiceInterface::createAndInitVrfObject().

Example:

// This example function is assumed to be in a DtSimComponent subclass.
void createSubObject(const DtObjectType& t)
{
   DtVrfLocalObjectCreateInformation createInfo;
   createInfo.setForceType(entity()->forceType());
   createInfo.setObjectType(t);
   createInfo.setPosition(entity()->worldPosition());
   createInfo.setOrientation(entity()->topographicOrientation());
   DtPlatformLocalObjectFacade platformFacade(entity());
   if (platformFacade.isUsable())
   {
     createInfo.setWorldVelocity(myPlatformLocalObjectFacade.worldVelocity());
   }

   simulationServices()->createObjectService()->createLocalObject(createInfo);
}

Network Connection Changes

Data transfer between the simulation state and the simulation network (DIS, HLA, etc) has been reworked in VRF 5 to separate the network send and receive events into separate threads from the simulation computations. This required changes to the classes involved.

• The DtLocalObject no longer owns the DtSimObjectNetInterface. These are now owned by DtVrlinkNetworkInterface.
• DtSimComponent subclasses can no longer access publishers and reflected objects directly. Instead, they set and examine state data on DtSimObject and DtLocalObject instances.
• DtSimObjectNetInterface subclasses no longer can access data direction from a DtLocalObject (formerly DtVrfObject). Instead, they access data from the DtStateData system using the DtStateComponent classes. The example Add State Component (addStateComponentSim) includes a custom DtSimObjectNetInterface subclass.

These network classes are now used in both the VRF Sim Engine as well as VRF GUI.

Library Changes

Some libraries have changed names in VRF 5.0:

• vrfCore<protocol> has changed to vrfSimCore
• Many libraries that had separate versions based on network protocol in VRF 4.x now have only a single version used for all protocols in VRF 5:
  • makRadio
  • vrfcgf
  • vrfcontrol
  • vrfmodel
  • vrfMsgTransport
  • vrfobjcore
  • vrfplanmgr

[Home] [Top of Page]