Extending State Repositories

The State Repository Extension example demonstrates how to install a state respository extension to an existing state repository.

It does so by creating a subclass of the DtVrfStateRepositoryUserExtension class in order to provide additional functionality to an existing state repository.

Instances of DerivedSRUserExtension are an example of an extension to a base state repository class. It provides a way to extend an entity's state information independent at a lower level in the state repository hierarchy. All entities in VR-Forces have at a minimum a DtVrfObjectStateRepository, which can be extended in this way. By extending a state repository through the DtVrfStateRepostioryUserExtension class, you don't have to extend multiple leaf-level state repository classes to add the same kind of extension to different kinds of entities (e.g. ground vehicles and air entities, both of which have different derived state repository classes).

For example, suppose you want to extend all types of entities and objects in VR-Forces (fixed-wing, rotary-wing, ground, and so on) with a new kind of identifier. Rather than extending each type of state repository to include the new identifier, you just need to create a single derived kind of DtVrfStateRepositoryUserExtension class. This allows you to write the extension once, and configure it as part of a variety of different kinds of entities, control objects, or overlay objects. The alternative to this approach would be to subclass each kind of state repository separately, extending each class in exactly the same way.

A state repository extension object (DtVrfStateRepositoryUserExtension) can be initialized from a parameter database, and then saved/restored as part of an entity's state in an order of battle file.

This example of a user-defined state repository extensions class contains a single new data member, myTag (a new kind of identifier). The myTag member variable is a readable, writeable string (DtRwString). myTag is registered with the name "my-tag" in this class' constructor.

Like the DtVrfObjectStateRepository classes, classes derived from DtVrfStateRepository- UserExtension are readable and writeable. Any DtReaderWriter data members you add to your derived DtVrfStateRepositoryUserExtension will be saved to an order of battle file along with the rest of an object's DtVrfObjectStateRepository data.

The class returns a new type string "my-state-repository-user-extension". This is the key that gets registered with the factory so VR-Forces will know how to create an instance of this class when it encounters it in a parameter database file. The configuration of an instance of this type of state repository extension in a parameter database file (an .ope file) would look something like this:

 
(state-repository-extension-type  "my-state-repository-user-extension") 
(user-extension    
     (my-tag "some-useful-info") 
   )

At runtime, you can access the state repository extension through the entity's state repository member, e.g.

 
DtVrfObject* entity;
DtVrfStateRepositoryUserExtension* extendedState;
. . .
extendedState = entity->vrfState()->userExtension();

To extend state repositories at the base level:

Create a class derived from DtVrfStateRepositoryUserExtension. In your derived class, you must provide a copy constructor and a clone() member function.
Register any readable/writeable data member with the parent registry in the constructor.
Ensure that a type() method returns a unique string. It is used to register the class with the factory.
Provide a static create() function that returns a new instance of this class on the heap. This will be registered with the factory for this type of class and used to create this object.
In "main" (in most cases, the initialization function in plugin.cxx), register the creator with the factory that creates this type of object. When VR-Forces encounters this type in a object parameter database entry, it calls your class's create function to create an instance of that type. e.g. (from DtInitializeVrfPlugin),:
```
 cgf->factoryManager()->stateRepositoryUserExtensionFactory()-> addCreatorFcn("default-vrf-state-repository-user-extension", DerivedSRUserExtension::create);
```
Configure the appropriate object parameter database files with the new type of extension. Set the value of the state-repository-extension-type variable to the string returned by the new class's type() function. In the case of this example, the string is set to "my-state-repository-user-extension".
```
(M1A2
  (parameter-type "ground-vehicle-param")
  (object-type 1 (1 1 225 1 1 3 -1))
  . . .
  (state-repository-extension-type "my-state-repository-user-extension")
)
```
If desired, initial values can be configured for the readable/writeable data members of a derived DtVrfStateRepositoryUserExtension by adding a user-extension parameter entry to an entity's OPE file. In our example, the "my-tag" data could be initialized in an OPE file as follows:
```
(state-repository-extension-type "my-state-repository-user-extension")
(user-extension
   (my-tag "some-initial-value")
)
```
Access the extension as needed in your code. You can obtain a pointer to the variable through the object's state repository. Use dynamic_cast to determine the correct type.
Save and restore new data to the order of battle file. All DtReaderWriter member data in your user extension is saved and restored as part of the entity state in the order of battle file as part of a scenario. For instance, in our example, the "my-tag" string would be listed under the OOB entry for any entity with the example extended SR.

How to Run the Example

This example demonstrates how extend the entity state repository at the at the DtVrfObjectStateRepository level.

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:

Start VR-Forces GUI and SIM.
Create a new scenario - e.g. EntityLevel SMS on Ground_DB II terrain.
Create a new entity (e.g. a M1A2).
Save the scenario.
In the back-end console, you will see a number of messages indicating that that a derived state repository extension has been created.
You can also confirm that the extension to the state repository has been created by opening the order of battle file (.oob) in your saved scenario. Search for the parameter named 'user-extension'. It will contain a single member named 'my-tag', with a value of USE-DEFAULT.

Classes

DerivedSRUserExtension

This subclass of DtVrfStateRepositoryUserExtension provides extra data to the base state repository.

Plugin Entry Points

/*******************************************************************************
** Copyright (c) 2014 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
#include "vrfcgf/vrfPluginExtension.h"
#include <vrfcgf/factoryManager.h>
#include <vrfobjparam/vrfStateRepositoryUserExtensionFactory.h>
#include "derivedSRUserExt.h"
#include "vrfcgf/cgf.h"
extern "C" {
   DT_VRF_DLL_PLUGIN void DtPluginInformation(DtVrfPluginInformation& info)
   {
      info.pluginName = "extendStateRepository";
      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)
   {
      // The string "my-state-repository-user-extension" is the argument 
      // returned by our example's type() function and would need to be inserted
      // into the (state-repository-extension-type) argument of any .OPE file 
      // that is desired to use the extended state repository   
      cgf->factoryManager()->stateRepositoryUserExtensionFactory()->
         addCreatorFcn("my-state-repository-user-extension", 
         DerivedSRUserExtension::create);
      
      // The "default-vrf-state-repository-user-extension" is the extension 
      // string used in all .ope files.  We are registering our create() 
      // function with this string in order that our example will work by 
      // default with all extant entities.
      //
      // In practice, when you actually use an extended state repository, you 
      // should change the name to something unique 
      // (i.e. my-tank-moving-repository) and register the creator with that 
      // name.  You would then modify the .ope file(s) you want to associate
      // this new object with and specify that name.  This would be placed in  
      // (state-repository-extension-type "default-vrf-state-repository-user-extension")
      cgf->factoryManager()->stateRepositoryUserExtensionFactory()->
         addCreatorFcn("default-vrf-state-repository-user-extension", 
         DerivedSRUserExtension::create);
      
      return true;
   }
}

Table of Contents

Extending State Repositories

How to Run the Example

Usage

Classes

Plugin Entry Points