Rebuilding the VR-Forces Application

Table of Contents

• The DtVrfApp Class
  • Overriding DtVrfCreator
  • Subclassing DtVrfApp
• Building the VR-Forces Application for Windows
• Building the VR-Forces Application for Linux

The VRF sim engine is the VR-Forces application that responds to control messages sent by a tool such as the VR-Forces GUI by making appropriate calls to the VR-Forces Simulation API (that is, DtCgf.) The top-level sim engine code is fairly simple, in the sense that it does not add a lot of code to what is provided by the VR-Forces API.

However, it is very powerful because it incorporates the full functionality of the VR-Forces toolkit. It represents a self-contained CGF simulation engine, ready to be controlled by a remote control application, such as VRF GUI. It accepts command-line options for setting modes and parameters, and it is configurable, because its capabilities and behavior are driven by the object parameter database and other files.

Many VR-Forces developers need an application that works just like sim engine (keeps its command-line options, and ability to be driven by a remote VR-Forces GUI), but that replaces some default dynamics model with custom code, adds the capability to perform additional tasks, supports some new kind of sensor, and so on. While plug-ins provide a flexible way to deploy extensions to the sim engine, there may be cases in which you need to extend the sim engine application. For example, you may need to extend the DtCgf class directly. Therefore, we provide source code and project files or makefiles for this application in ./appsrc/vrfSimUser. You can edit vrfSimUser's main.cxx file, use the VR-Forces Simulation API to modify its behavior, and rebuild it.

Note

When you build a VR-Forces application, you must build it against the version of VR-Link that your version of VR-Forces was built against. Please see the VR-Forces Release Notes for your version of VR-Forces, to find out which version of VR-Link to use.

The DtVrfApp Class

In main.cxx, all of the functionality of the vrfSim application is encapsulated in the DtVrfApp class. The main() function just instantiates DtVrfApp, calls init() on it, and then executes mainLoop(). The application's functionality was put into a class, as opposed to directly in main(), so that other applications (like the VR-Forces examples) could inherit this functionality without duplicating code. DtVrfApp is not really a part of the VR-Forces simulation engine. It is a class that uses the VR-Forces simulation engine through the VR-Forces Simulation API.

When you modify or extend the vrfSim application, we recommend that you avoid making modifications to vrfApp.cxx or vrfApp.h, so that you do not have to merge your changes into future versions of these files when you upgrade. In most cases, you should be able to just obtain a pointer to the DtVrfApp's DtCgf object (using its cgf() member function from within main()), and configure it appropriately using DtCgf's member functions, managers, or factories.

Most of the VR-Forces API examples take this approach. For example, if you wanted to add a custom dynamics model for ground vehicles, such as the one in the addActuator example, you could do this by adding the following line to main.cxx to register the new subclass of DtActuatorComponent with the VR-Forces simulation engine:

app->cgf()->factoryManager()->componentFactory()->addCreatorFcn(
   DtAutomotiveActuatorType, MyActuatorComponent::creator);

Overriding DtVrfCreator

When your application needs to configure DtVrfCreator, as described in The VR-Forces Creator, (for example, when you need to register a custom subclass of a class like DtVrfObjectManager), you can pass your DtVrfCreator pointer to DtVrfApp::init(), which will pass it on to DtCgf::init(), as follows:

int main()
{
   DtVrfApp app(argc, argv);

   // Instantiate a default creator
   DtDefaultVrfCreator creator;

   // Register the creator for your MyObjManager class
   creator.setObjectManagerCreator(MyObjManager::create);
   app.init(&creator);
... 
}

Subclassing DtVrfApp

When you need to change the behavior of DtVrfApp in a custom application (for example to add or remove command-line options), we recommend subclassing DtVrfApp and overriding the relevant functions.

Note

If you are embedding VR-Forces functionality in a larger application, you usually will not want to use DtVrfApp, since it represents an application that does nothing but execute a VR-Forces simulation engine, and therefore implements a simple main loop for you. Instead, instantiate the classes that you need explicitly within your application, for example, DtCgf, DtCgfDispatcher, DtBatchManager, and so on. See vrfEmbeddingVRForcesinaThirdPartyApplication for more information.

Building the VR-Forces Application for Windows

Please review the prerequisites for building VR-Forces in Prerequisites for Building VR-Forces Applications and Plugins.

The sample project files create the release and debug executables vrfSimUser.exe and vrfSimUserDebug.exe. This naming convention ensures that you do not inadvertently overwrite the executables supplied by MAK. The files are placed in the ./bin directory.

The ./appsrc/vrfSimUser directory contains MS VC++ project files. The project file contains release and debug configurations. The projects are:

• vrfSimUserDIS - projects that build the DIS version of the VR-Forces back-end and front-end
• vrfSimUserHLA13, vrfSimUserHLA1516, and vrfSimUserHLA1516e - projects that build the HLA versions of the VR-Forces back-end.

The sample projects enable you to add additional features using the VR-Forces toolkit. You can extend the existing VR-Forces simulation back-end. You can also use the sample project as a starting point for building your own application that uses components of the VR-Forces toolkit.

Note

In order to run HLA versions, you need to have your computer configured to find the proper RTI DLLs. Refer to "Installing an RTI", in VR-Forces Users Guide.

Building the VR-Forces Application for Linux

To build VR-Forces for Linux, you must have VR-Link. If you building an HLA application, you must also have a supported RTI.

Before building the VR-Forces application, set the following environment variabls:

• QTDIR. Set to the location of the Qt libraries.
• MAK_VRLDIR. Set to the location of your VR-Link installation. Be sure to use the version of VR-Link specified in VR-Forces Release Notes for your version of VR-Forces. The VR-Link tree must have a symbolic link to the RTI tree as described in "Compiling for a Particular Simulation Standard Under UNIX" in VR-Link Developers Guide.
• MAK_RTIDIR (HLA builds only). Set to the location of your RTI installation.

You must be in the ./appsrc/vrfSimUser directory to build vrfSimUser. By default, make will build all the VR-Forces configurations. You can prevent certain configurations from being built by specifying NO_DIS=1, NO_HLA1516=1 or NO_HLA13=1 on your command line.

Follow a comparable process to build vrfGui.

Note

VR-Forces applications must run from the proper ./bin directory. The files can be copied to their correct ./bin directories automatically by using the "install" target on the make line.