Pass a DtFomMapper instance to a DtExerciseConn constructor.
Pass the name of a shared library containing a function that creates the desired FOM Mapper to a DtExerciseConn constructor.
Set the fallback FOM Mapper creation function, using DtExerciseConn's static setFomMapperCreator() function.
Allow DtExerciseConn to create an empty FOM Mapper and configure it after the DtExerciseConn constructor returns. (In fact, regardless of how you choose a FOM Mapper, you can always modify or reconfigure it after the DtExerciseConn constructor returns.)

6.8.1 Passing a DtFomMapper Instance

The following DtExerciseConn constructor takes an instance of a DtFomMapper.

DtExerciseConn(const char* execName, const char* federateName, DtFomMapper* mapper = DtRprFomMapper::create(), const char* fedFileName = NULL);

For example, if you create a FOM Mapper subclass called MyFomMapper, you might instruct the DtExerciseConn to use your FOM Mapper as follows:

MyFomMapper mapper();

DtExerciseConn("VR-Link", "MyAppName", &mapper);

Note: The mapper argument has a default value, which is a pointer to a new'ed DtRprFomMapper – a FOM Mapper implemented in VR-Link that maps to the Real-time Platform Reference FOM (RPR FOM). If you omit the FOM Mapper argument, as in the examples in the protocol-independent section, the RPR FOM Mapper is used. For more information, please see 6.8.5 Using Different RPR FOM Versions.

If you pass a value of NULL as the mapper argument to this constructor, VR-Link uses the FOM Mapper creation function last passed to setFomMapperCreator() to create a FOM Mapper. The default is a function that creates a DtEmptyFomMapper.

6.8.2 Passing the Name of A Shared Library

The following DtExerciseConn constructor takes the name of a shared library (DSO or DLL).

DtExerciseConn(const char* execName, const char* federateName,
   const char* dsoName, const char* fedFileName = NULL,
   void* fomMapInitData = NULL);

When you use this constructor, dsoName must be the name of a shared library (DLL or DSO) that contains definitions for the following functions:

DtFomMapper* DtCreateFomMapper(void* usr);

void DtDeleteFomMapper(DtFomMapper* mapper);

DtCreateFomMapper() is called by the DtExerciseConn after it opens the shared library. It should return a pointer to an instance of a DtFomMapper (or a subclass) that you want to use. DtDeleteFomMapper() is a function that will be called from within the DtExerciseConn destructor, which should delete the FOM Mapper instance that you provided.

When you specify the name of your shared library, you can omit the filename extension (.so or .dll) to provide platform independence.

These two function definitions that you provide in a shared library should have C linkage. You can insure this, by wrapping extern "C" {} around your function definitions. For example:

extern "C"
{
   DtFomMapper* DtCreateFomMapper(void* usr)
   {
   return new MyFomMapper();
   }
   void DtDeleteFomMapper(DtFomMapper* mapper)
   {
      delete mapper;
   }
}

You can specify the full path to your shared library within the dsoName argument to the DtExerciseConn constructor, or make sure that it is in your current shared library search path.

The final argument to the DtExerciseConn constructor that takes a shared library name, is a void* that can point to any arbitrary data that is required by the DtCreateFomMapper() function defined in your FOM Mapper shared library. The pointer that is passed to the DtExerciseConn constructor as fomMapInitData will be passed as the usr argument to the DtCreateFomMapper() function defined in your shared library. In the example above, we simply ignored this usr data.

If VR-Link cannot successfully open the specified shared library, or if VR-Link cannot find the symbols DtCreateFomMapper() and DtDeleteFomMapper() within it, DtExerciseConn acts as though you explicitly passed a NULL FOM Mapper: VR-Link uses the function last passed to DtExerciseConn::setFomMapperCreator() to create a FOM Mapper. The default is a function that creates a DtEmptyFomMapper.

For a demonstration of the process of creating a FOM Mapper shared library, please see the myFomMap example under ./examples/extend/myFomMap.

6.8.3 The Fallback FOM Mapper Creation Function

DtExerciseConn has a fallback FOM Mapper creation function that is used when you pass NULL as the mapper argument to the DtExerciseConn constructor, or when an invalid FOM Mapper shared library is passed as the dsoName argument.

You can set the fallback FOM Mapper creation function by using DtExerciseConn's static setFomMapperCreator() member function before creating a DtExerciseConn instance. A FOM Mapper creation function has the same prototype as the DtCreateFomMapper() function shown above. The default fallback function is DtEmptyFomMapper::create() – which creates an instance of DtEmptyFomMapper (defined in emptyFomMapper.h). A DtEmptyFomMapper is a clean slate – a FOM Mapper that contains no mappings between VR-Link classes and FOM classes.

6.8.4 Configuring a FOM Mapper After Constructing a DtExerciseConn

A DtFomMapper can be configured using its mutator functions after the DtExerciseConn constructor returns. You can use this capability to add a few extra mappings to a FOM Mapper that has been passed to the DtExerciseConn, or constructed from a shared library.

If you want to, you can do all of your FOM configuration after the DtExerciseConn constructor returns. Pass NULL as the mapper argument to the DtExerciseConn constructor and start with the default DtEmptyFomMapper that gets created (assuming that you have not set the fallback FOM Mapper creation function to something other than DtEmptyFomMapper::create()).

6.8.5 Using Different RPR FOM Versions

VR-Link contains built-in support for the RPR FOM. It uses a class called DtRprFomMapper (defined in rprFomMapper.h) – a DtFomMapper that self-registers mappings for RPR FOM classes, attributes and parameters.

The DtRprFomMapper constructor takes an optional version argument that indicates which version of the RPR FOM you want to use. For currently supported versions, please see VR-Link Release Notes.

For example, to tell VR-Link to use a FOM Mapper configured for RPR FOM version 2.0, draft 17, do the following:

DtExerciseConn conn("VR-Link", "MyAppName", new DtRprFomMapper(2.0017));

Because DtRprFomMapper contains information about all RPR FOM classes, attributes, and parameters, using it within your application can make your executable fairly large. To help alleviate this problem, we have created an alternate FOM Mapper called DtSimpleRprFomMapper (defined in simRprFomMap.h). DtSimpleRprFomMapper has mappings for only a subset of the RPR FOM, those classes that are needed by VR-Link's examples and other MAK products such as the MAK Data Logger and VR-Forces:

BaseEntity and all of its many subclasses
EmbeddedSystem.EmitterSystem
EmitterBeam and its subclasses
WeaponFire
MunitionDetonation
Collision
ViewControl
LgrControl.

If you are using only these classes, passing an instance of DtSimpleRprFomMapper to your DtExerciseConn constructor instead of the default DtRprFomMapper will significantly reduce executable size.

If you are using just a few additional classes, you can create a DtSimpleRprFomMapper, and manually add mappings for the other classes that you need.

6.8.6 Deriving Your Own DtFomMapper

One way that you might configure your DtFomMapper, is to create a subclass of DtFomMapper that self-registers the desired mapping information, and tell the DtExerciseConn to use an instance of your subclass. (For more information, please see 6.8 - Choosing a DtFomMapper.) This is a way to group your configuration code all in one place. In fact, this is how VR-Link uses the DtRprFomMapper class for the RPR FOM.

When you create a DtFomMapper subclass, you should usually derive from DtEmptyFomMapper, rather than directly from DtFomMapper. DtEmptyFomMapper initializes all factories and lists for you, so that you only need to add mappings within your subclass.

Because we wanted to allow the possibility of creating a DtFomMapper before a DtExerciseConn (and passing the DtFomMapper to the DtExerciseConn), the DtFomMapper constructor does not take a DtExerciseConn as an argument. However, a DtFomMapper needs a DtExerciseConn in order to fully initialize itself.

For this reason, the DtFomMapper constructor does very little. Most initialization occurs within the virtual init() function, which is called by the DtExerciseConn constructor after it has read the FED file. The DtExerciseConn passes a pointer to itself to init(), so that it is available to the DtFomMapper during its real initialization work.

In your derived DtFomMappers, you must break things up this way as well. Your constructor should be basically empty. All of your registration of mapping code belongs in your implementation of the virtual init() function. From within your init() function, call down to the base class's (usually DtEmptyFomMapper's) version of init(). Then perform your specific initialization, such as addition of encoders, decoders, and class mappings. For an example, please see ./examples/myFomMap.

[<< Attribute and Parameter Encoding and Decoding] [Home] [Top of Page] [VR-Link FOM Mapping and Extension Examples >>]