VR-Forces Developer's Guide
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
VR-Forces 5.2 API Migration Guide

Table of Contents

The API Migration Guide is written for developer's to understand what changes to the API are most likely to affect any previous plugins or remote control applications they may have developped.

While the VR-Forces API undergoes many changes that may not be listed here, most are unlikely to affect existing code.

Addendums to this Guide may also be posted to the MAK Knowledge Base after release.

Changes that might affect scenarios or simulation model sets rather than code are documented in the separate VR-Forces Migration Guide.

DtObjectType Removal

The class DtObjectType (which was a subclass of DtEntityType that added the notion of a superType), has been removed. If you have code that references this class, replace that class with DtEntityType. If you have used the constructor that takes the super type as an argument, simply remove it.

// Previous code
DtObjectType oldRouteType(DtObjectTypeIndividual,
DtLinearObjectKind, 0, 0, DtLinearObjectCategoryRoute,
DtLinearObjectRouteSubcategoryAggregateFormation, 0, 0);
// 5.2 code
DtEntityType newRouteType(DtLinearObjectKind, 0, 0, DtLinearObjectCategoryRoute,
DtLinearObjectRouteSubcategoryAggregateFormation, 0, 0);
// Create a new object type from an existing DtEntityType object.
// Previous code
DtObjectType oldEntityType(DtObjectTypeIndividual, entityType);
// New code. This is just making a copy. You can just use entityType as is if a copy is not required.
DtEntityType newEntityType(entityType);

If you have used the superType() in any conditional statements to determine if an object is an aggregate, this check can be substituted for kind() == 11.

// Previous code
if(objectType.superType() == DtObjectTypePseudoAggregate) // DtObjectTypePseudoAggregate == 3
{
DtInfo << "This is an aggregate." << std::endl;
}
// 5.2 code
if(objectType.kind() == DtAggregateKindMilitaryHierarchy) // DtAggregateKindMilitaryHierarchy == 11
{
DtInfo << "This is an aggregate." << std::endl;
}

Merging of Location and Point Tasks

Previously there were many tasks which were duplicated to support handling both a location and a simulation object. For example, DtMoveToLocationTask moved to a location and DtMoveToTask moved to a waypoint. These tasks have been merged into a single task and associated code for the old task has been removed. These tasks, when merged, have changed to use the new DtRwLocationReference class which can contain either a vector location or a uuid of an object to reference.

For scenario loading this should have no visible effect. Scenarios, when loaded or imported, will have their tasks automatically changed to the new tasks. When saved the scenario will contain only the new tasks.

Tasks Replaced

Location Reference Added to Scripted Tasks

The following scripted tasks have been changed from location/waypoint versions to using a location reference entry widget. While the Location version of the tasks have been depreceted, in order to support their editing in current plan dialogs the UI still exists. Newly created tasks will show the location reference entry widget

Controllers Removed

The DtRotaryWingMoveToLocationController, DtMissileTrackEntityController, DtGroundMoveToLocationController, DtFixedWingMoveToLocation, DtDisaggregatedMoveToLocation, and DtSurfaceEntityMoveToLocationController have been removed and functionality they had needed have been moved into the base controller class. If you have subclassed any of these controllers you can now subclass their parent controllers to add your overridden functionality.

Task Dialogs Removed

The DtTaskLaseLocation, DtReleaseBombOnLocation, DtTaskMoveToDestination, DtTaskFFE, DtTaskFFL, DtTaskMoveToLocation have all been removed.

Deprecation of Joystick Controls

Most joystick controls in VR-Forces have been deprecated. Some minimal controls have been maintained. Other controls that were previously supported have been moved to an example. This example is not supported, but is provided as a basis for plugin developer's who wish to create their own joystick plugins.

The DtBallisticGunJoy, DtBallisticGunJoyController, DtFixedWingJoyFlightController, DtGroundJoyTurretController, DtRotaryWingJoyDeviceControllerDescriptor, and DtRotaryWingJoyFlightController sim components have been moved to the new example.

Resource Management Changes

Previously, resources in VR-Forces were of three types: Integer, Real or Munition. For 5.2 this has been collapsed into a single concept of a resource that has a DIS enumeration, a current amount and a full amount. No longer will resources be referenced by a string name nor differentiate between a type. There is only a single type of resource, and that is the DtSimResource.

  1. There is still a DtSimResourceManager. This will contain a list of resource lists (see "location" below) and is the main interface to an objects resources
  2. Each system will provide a set of resource defaults to the entity that uses the system. These resources will be rolled up when the entity is created based on all the systems that are included. If multiple systems provide the same resource, those resources will become inclusive of each other.
  3. The entity can then (via the SOE) add, change amounts, or remove resources that are provided to it. Once a resource is added, it will remain regardless of whether or not the systems the entity uses change. If a resource is added, it becomes part of the entity's resource system. If the underlying system were to change the provided amount, the entity's amount will remain the same. A resource may also be removed, even if one more included systems add this resource.
  4. When systems are added the entity will be given new resources. When systems are removed, those resoures will be removed. The SOE will always reflect the current state of the entity's resources given the systems it uses.

  5. Resources, now, can also be in multiple "locations" in the resource manager. This answers the question of "how can an entity that is a fuel provider also consume fuel?". There are two default locations defined for resources – Unspecified and Cargo. These locations are defined in the VR-Forces enumarations file:

    <enum uid="1000000" name="VR-Forces Resource Bins" footnote="Enumerated Types for VR-Forces resource bins."> <enumrow value="0" description="Unspecified"> <enumrow value="1" description="Cargo"> </enum>

There is no limit to the number of locations available, and, new locations can be added in code. If there is no enumeration for it, it will show up on the GUI as "VR-Forces Resource Location <number>".

  1. The set resource command will take a bin as well as a resource type. If the resource does not exist in the entity, the resource will be added to the entity's available resources. This is a mechanism that can be used to add new resources.
  2. If an entity inherits from a parent, its resources will be inclusive of the parent's resources and systems, plus whatever resources it is given from additional systems and additional resources that are added. This is also rolled up at runtime, so, if a parent entity is given a new resource, all newly created child entities will receive that resource (and the opposite true for removal).
  3. If an entity is saved into a scenario and its systems or parent change their resources, it will not affect the resources the of the saved entity.

For details on how to upgrade an existing SMS to use the new resources, please see the main VR-Forces Migration Guide (as opposed to this API Migration Guide).

Ground Vehicle Movement

The ground vehicle movement system has changed extensively. This has resulted in new movement tasks that have replaced the old ones, and in some cases may produce different results. Existing Lua scripts, plugins, and remote-control applications that issue movement tasks to ground vehicles may need to be updated. Please see the user’s level VR-Forces Migration Guide for details on which 5.2 ground vehicle movement tasks should replace existing 5.1.1 tasks.

Sim Terrain Intersection API Changes

Most terrain intersection functions in DtPhysicalWorld and DtAttachedTerrain and some other related classes have been modified to use a new style API that allows for specifcation of new options, specified in DtTerrainIntersectOptions class. The DtTerrainInterface API did not change significantly, since it already had the new-style API allongside the old API.

Upgrading terrain API calls:

See Also
Example terrain intersection usage in MyActuatorComponent::tick() in the Modify Sim Component (modifySimComponent) example.

The new DtTerrainCategoryMask option allows terrain intersections to run against only a subset of the terrain, which can greatly improve terrain paging speed by avoiding page-in of data sources that are not required for paricular intersections. It is highly suggested that you pass only the most restrictive mask applicable to your intersection call for best performance.

See Also
DtTerrainIntersectOptions::terrainCategoryMask()

Terrain Change Notifications Refactor

The notification system for the terrain changes has been refactored. Clients can register a callback function through the function DtTerrainInterface::addTerrainChangeNotificationCallback(). The callback will be invoked when changes in the terrain occur - i.e. caused by craters, switch nodes, destructible buildings, etc.

Callback functions for processing terrain changes should follow this function signature.

void terrainChangeNotification(const DtTerrainChangeNotificationInfo& terrainChangeInfo, void* usr)
{
}

To register the callback:

cgf->simulationServices()->physicalWorld()->terrainInterface()->addTerrainChangeNotificationCallback(terainChangeNotification, nullptr);

Although the previous mechanism for terrain change notifications (using DtTerrainInterface::queryDynamicTerrainFeatures()) is still available, it is recommended to use the new mechanism instead, as it returns a smaller area containing the location of the terrain change, as opposed to the queryDynamicTerrainFeatures() which returns the entire terrain tile containing the changed area.

Plugin Entry Point Change

Sim Plugin

The DtInitializeVrfSettings entry point for sim engine plugins has been changed to pass in a pointer to the DtCgf. The prototype of the entry point has changed from:

DtInitializeVrfSettings(DtApplicationSettings& settings)

to:

DtInitializeVrfSettings(DtCgf* cgf, DtApplicationSettings& settings)

GUI Plugin

The initializeCommandLineArguments function in GUI plugins has changed to take a makVrv::DtVrvCommandLineProcessor from a makVrf::DtVrfGuiCommandLineParser. This allows the entry point to be used for either a GUI plugin or a Simulation Object Editor plugin. Please dynamically cast to either a DtVrfGuiCommandLineParser or DtSimulationObjectEditorCommandLineParser to get the correct class. See interfacemanipulation for more information.

Removal of GUI State View

DtStateView, DtSimEntry and all references to data in the simData() and DtVrfStateViewCollectionManager have been removed and replaced with the DtVrfGuiSimObjectManager. Objects in the GUI can now be referenced in much the same manner as they are in the back-end. There is no longer a need for update rates or forcing updates. You can retrieve a DtSimObject in the GUI from the DtVrfGuiSimObjectManager and use the API in the GUI to reference object data in much the same way you do in the sim engine.

For more information please reference:

C++ and Boost

VR-Forces is now using version 1.84.0 of the Boost libraries.

Boost smart pointers have been replaced with the equivalent C++ smart pointers.

std::auto_ptr is not longer used.

Rewind Functions and Callbacks

The rewind functions have been replaced by rollback functions.

Removed:

Replaced:

Remote Control API Changes

In the DtRemoteEnvironmentController, the visibility accessor functions setVisibility() and visibility() have been replaced by setVisibilityAndObscurant() and visibilityAndObscurant(). These set and retrieve both the visibility and the obscurant at the same time. Visibility and obscurant are corelated environmental parameters and must to be set together.

AIEnabled State Property

The AIEnabled state property has been renamed AutonomousActionsEnabled. Any plugins that referenced this property should be updated to reference the new property name.

Internal and External State Properties

State properties can now be either internal or external. As a result, the state-data section of the OPE and sysdef files in any Simulation Model Sets may be renamed to external-state-data, though the state-data name will work as an alias for this. It is recommended that any unpublished state properties be moved to a new internal-state-data section, as internal properties have better performance. Published state properties must be in external-state-data. Please see the Developer’s Guide section on State and Parameter Properties for more information on state properties.

[Home]

Document ID: Generated on Thu Oct 23 22:29:17 EDT 2025 from SVN revision 280951
Copyright © 2005-2024 MAK Technologies. All Rights Reserved (www.mak.com)