2.7.1 The Application Control Flow

This section looks at the control flow from top to bottom.

Drivers decide what needs to get drawn based on application business logic. For example, a DIS or HLA driver puts objects in the scene based on information it gets from remote simulation applications over the network; an input driver controls the location of the eyepoint based on user input.

Drivers communicate with both local and remote objects in the VR-Vantage Rendering System through the Control Interface (agents, proxies and other higher-level Control Interface objects).

If you want to extend the capabilities of the GUI API, you will need to work at the level of the Rendering System. For example, if you want to incorporate a new OSG nodekit, or if you want to generate geometry procedurally rather than loading and positioning existing 3D models or effects, you will need to subclass Rendering System objects. (You will also have to provide agents if you want applications working at the Control Interface level to be able to control your new objects.)

2.7.2 Displays, Windows, and Channels

A DtDe's DtDisplay is the Rendering System layer object that manages the display engine's system of windows and channels. (Each display engine can own one or more windows, and can be configured to render one or more 2D or 3D channels into each window. As in most visual systems, a channel is a rendering of the scene from a particular point of view). You can get to a DtDe's DtDisplay by calling displayEngine->display().

The DtDisplay owns a DtWindowManager, which manages a list of DtWindows. Each DtWindow, owns a DtChannelManager, which manages the list of DtChannels that are associated with a particular window. However, all of these classes are part of the Rendering System layer, which means that if you use these classes, you will only be able to access and control windows and channels that are owned and rendered by the display engine that is local to your application.

To control displays, windows, and channels independently of whether they are owned locally or by an external display engine application, use the corresponding Control Interface classes: DtDisplayProxy, DtWindowProxy, and DtChannelProxy. Get a pointer to the DtDisplayProxy object associated with each display using DtDe's findDisplay() or findDisplayByIndex() functions. Once you have the DtDisplayProxy, you can use it to get pointers to window and channel proxies. For more detail about displays, windows, and channels, please see 5.1.1 Channels, Windows, and Displays. For information about proxies, please see 5.2.1 Proxies.

2.7.3 Terrain and Environment

The Control Interface class DtScene manages the terrain and environment. It delegates much of its work to the DtTerrain and DtEnvironment classes. DtTerrain further delegates to:

DtTerrainPatch to manage each "patch" of terrain
DtFeatureLayer to manage layers of point features that are overlaid on top of the terrain
DtForest to manage trees.

All of these classes exist in the Control Interface layer. They command the Rendering System classes DtSkyObject, DtTerrainPatchObject, and DtForestObject through their respective agents: DtSkyObjectAgent, DtTerrainPatchObjectAgent, and DtForestObjectAgent. For details about agents, please see 5.2.2 Distributed Objects and Agents.

The DtDe will automatically create a DtScene for you when it is initialized. Use displayEngine->scene() to get a pointer to the DtScene, and use its members to access and manipulate the DtTerrain and DtEnvironment.

2.7.4 Entities and Props

The main components of any 3D scene are the terrain and environment discussed in previous sections, and entities and props. Props are static objects such as buildings or Jersey barriers (like the props that are placed on a stage for a play). Entities are moving objects such as vehicles, missiles, and human characters (the actors in the play).

DtEntityFacade is the main Control Interface level class used to add an entity to the scene and to control its location and state. It uses another Control Interface level class called DtTrailEffect to manage attached effects. DtEntityFacade commands Rendering System classes such as DtSceneObject, DtArticulatedModel, and DtEffectModel through their respective agents. As shown in the example in vrvRoadmaptoVRVantageToolkitClasses, you can create an instance of DtEntityFacade for each entity that you want to add to the scene, then call its member functions (or members of objects that are owned by DtEntityFacade) to position the object and set additional state.

The DtProp class is used to create and manipulate props. Like DtEntityFacade, you can create an instance of DtProp for each prop you want to add to the scene (although it often makes sense to let a DtTerrain's DtFeatureLayer manage DtProps for you). DtProps command Rendering System classes such as DtSceneObject and DtModel through their respective agents.

2.7.5 Observers and Observer Attachment

DtObserver is a Control Interface level class that represents an observer - that is, an eyepoint into the virtual world. Through a DtObserver, you can control the location of the corresponding DtObserverObject that exists in the Rendering System. In order to associate a DtObserver with a channel, just make sure the DtObserver's name matches the observer name specified by your channel's configuration:

// Channel config initialized elsewhere.
DtChannelConfiguration channelConfig = getChannelConfigFromSomewhere();
DtObserverConfiguration configuration(channelConfig.observerName());
DtObserver* observer = new DtObserver(de, de.agentManager(), configuration); 

You can call DtObserver's member functions directly to set observer location and other state. However, we recommend using one of two higher-level classes to call DtObserver functions on your behalf: DtAttachManager or DtObserverController. Use DtAttachManager to perform attachment-related operations, so that other parts of the system are notified when attachment changes. DtObserverController implements a higher-level navigation interface on top of DtObserver. It lets you perform operations like "move left" and "pitch up", calculating resulting changes to the observer and calling DtObserver functions for you.

2.7.6 Drivers

In the previous pages, we described how the control logic of your application can use Control Interface classes to control objects in the Rendering System. Control Interface classes like DtEntityFacade and DtScene do not "decide" what to draw - the code that uses those classes does. In the example in vrvRoadmaptoVRVantageToolkitClasses, it was the application code itself that decided that the application should load makland_fast.mtf, and that it should add an F16 model to the scene. As that example showed, the Toolkit does not require you to put your control logic in any particular place. You can instantiate classes like DtEntityFacade, or access the DtDe's DtScene object from anywhere in your application - in main(), in your GUI code, and so on. However, we recommend that you organize your control logic into objects called drivers.

Application logic is in the drivers. Drivers are implemented as subclasses of the DtDriver class. If the Rendering System objects are like the actors and props on a stage, then a driver is like the director of the play. Drivers direct the action by communicating their intent to the actors (Rendering System objects) through their agents (or other Control Interface classes).

Putting your control logic into drivers has the following benefits:

Drivers are automatically "ticked" every time the DtDe is ticked, so that you do not have to worry about making sure your logic is executed at the right time.
You can start and stop drivers through the GUI. This means you have run-time control over the execution of your control logic if you put it into a driver.
DtDrivers automatically find out when external display engines connect or disconnect from your application and provide a place to put logic that needs to be executed when those events occur. In other words, since you are the one deciding what goes in the scene, it is your responsibility to ensure that late-joining display engines find out what you have already put in the scene before it joined. And the DtDriver class helps you to meet that responsibility,

The VR-Forces front-end has plenty of application-level logic built in. DtDrivers hold that logic, for example:

The DtInputDriver is responsible for processing mouse and keyboard input, and making calls to objects like the DtObserverController or DtAttachManager based on the control input received from the user.
The DtDisDriver, DtHla13Driver, DtHla1516Driver, and DtHla1516eDriver "drive" the contents of the scene based on information received from the network through their respective simulation protocols.
The DtSceneDriver makes sure that a new scene is created when a DtDe is initialized, and can populate a scene based on information in a saved scene file.

If your application is a flight simulator with an integrated visual/simulation configuration, you might create a "SimulationDriver" that drives a DtEntityFacade and the eyepoint based on the state of your ownship simulation object as it is computed each frame.

If you want to add support for a new simulation networking protocol, you would probably create a new kind of DtDriver for your protocol. And if you wanted to extend the set of DIS PDUs or HLA FOM attributes that cause updates to the scene, you would probably derive from our existing protocol drivers. The exampleFomMapper example shows how to extend drivers to listen for attributes in a modified FOM.

For more information about drivers, please see 6 - Drivers.

[<< Threading in the GUI API] [Home] [Top of Page]