Using the DtTerrainInterface Class

Table of Contents

• Loading a Terrain using the VR-Forces Terrain Library
• Terrain Intersection Tests
• Coordinate Systems
• Adding a DtTerrainPassThroughLayer
• Terrain Surface (Soil Type)
• Terrain Capabilities
• Terrain File Locations

The DtTerrainInterface class (terrainInterface.h) contains the representation of terrain skin and terrain features.

The terrain skin consists of the geometry of the terrain (typically represented as polygons) and its surface characteristics (that is, soil type). Terrain features include natural and man-made items such as trees, rivers, roads, buildings, and so on. Terrain features are represented as a vector network, comprised of points, lines, and areas.

The DtTerrainInterface class uses a pointer to a DtTerrainImplementation to manage the specifics of how each terrain type operates. The DtTerrainInterface maintains a factory of implementation types and chooses the correct type during the terrain loading process. Additionally DtTerrainPassThroughLayers are also terrain implementations, but they pass the calls to an underlying DtTerrainImplementation. Any number of pass through layers can be added on to of a loaded terrain to modify the terrain implementations.

Additionally after a terrain is loaded the DtTerrainCapabilities can be accessed from the terrain interface. This provide information about the terrain that was loaded.

Loading a Terrain using the VR-Forces Terrain Library

Loading a terrain using the VR-Forces Terrain Library is a simple process. From the DtTerrainInterface class you call the loadTerrain() method.

   DtTerrainInterface terrainInterface;

   terrainInterface.init();
   if (!terrainInterface.loadTerrain("terrainName"))
   {
      DtInfo("Could not load terrain file %s", "terrainName");
      return 1;
   }

Once the terrain is loaded, the interface will handle the inner workings of the terrain type and you can move on to performing intersections and line of sight tests.

Terrain Intersection Tests

The DtTerrainInterface class has an interface that lets you query for information about the terrain data. One of the most common queries made to the terrain database is for a terrain intersection. Terrain intersections can be used in ground entity models to determine how to position and orient simulation objects on the terrain surface.

The following example shows how to query the terrain database for an intersection with the terrain surface, returning the location of the intersection only:

   // Set up chord for intersection test. Query starts at p1 and ends at p2.
   DtPoint p1(2200, 2200, 10000);
   DtPoint p2(2200, 2200, -10000);
   DtChord chord(p1, p2);
   DtPoint isectPoint;
   double intersectionTime;
   // Calculate intersection with the terrain skin
   if (terrainInterface->intersect(chord, isectPoint, intersectionTime))
   {
      DtInfo("Intersected terrain at location %s\n", isectPoint.string());
   }

You can make more complex queries to the terrain interface, requesting such information as the list of all intersections a given chord makes with the terrain, surface type information at the point of intersection, and intersections with features in the vector network. For more details about terrain intersections, please see Querying the Terrain Interface.

Coordinate Systems

A DtTerrainInterface has a coordinate system, which defines the origin and type of coordinates being used in the database that was loaded. The Coordinate_System class (coordSystem.h) represents the coordinate system for the database. The Coordinate_System class provides methods for transforming a coordinate between the local coordinate system (the coordinate system used in the database) and the geocentric coordinate system. The derived types of Coordinate_System classes include:

• DtGeodeticCoordinateSystemDMS and DtGeodeticCoordinateSystemDDD - Geodetic coordinates (latitude, longitude, altitude)
• UTM_Coordinate_System - Universal Transverse Mercator
• lambertConformalProjection - Lambert Conformal Conical.

The DtTerrainInterface class has methods for setting and retrieving the coordinate system used in the database. It also has methods for transforming from its current coordinate system to any other coordinate system, performing the necessary transformations on loaded terrain data as appropriate.

Adding a DtTerrainPassThroughLayer

Terrain pass through layers can be added to the stack of terrain implementations by calling addTerrainPassThroughLayer() on the DtTerrainInterface class. This will instantiate a new pass through layer on the top of the terrain implementation stack. By doing this you now can intercept terrain calls as they are being made to the terrain implementation and modify them if the need arises.

An example pass through is the DtIntersectTimerPassThroughLayer class. This class times the intersect calls as they are being made and reports the average times when asked.

The following code adds the DtIntersectTimerPassThrough.

   DtTerrainInterface terrainInterface;
   terrainInterface.init();
   terrainInterface.loadTerrain("someTerrain");
   terrainInterface.addTerrainPassThroughLayer("timer");

Terrain Surface (Soil Type)

When querying for an intersection with the terrain a chord terrain intersection record can be returned. One of the important aspects of this record is the DtSurface, which holds the characteristics of a surface, including its color and the nature of the surface. A DtSurface has the following attributes:

• DtColor - RGB color.
• ::DtMedium - Enum {Ground,AboveGround,UnderGround,WaterSurface,AboveWater,UnderWater,UnspecifiedMedium}
• DtEnvState - environmental state, for example, dry, icy, wet.
• DtSoilType - for example, paved road, swamp, muddy, and so on.
• DtRoughnessSoilType - derived from soil type and used in modeling ground vehicle behavior (moving factor efficiency).

Color is an RGB value associated with the surface. This color is used when drawing the terrain database in a graphical display.

The medium, environmental state, and soil type attributes are represented by a set of enumerated types defined in the DtSurface class. Please see surface.h for the complete set of enumerations.

The DtRoughnessSoilType is a classification of terrain surface that is suitable for use in simulators that need to model the effects of soil type on ground vehicle behavior. It is derived from the soil type parameter. (Soil types are automatically mapped to roughness soil types in the DtSurface class.)

Note

VR-Forces uses DtRoughnessSoilType in its ground vehicle model. DtRoughnessSoilType gets mapped to a set of soil-list parameters (acceleration, stopping factor, and max-speed) in an entry in the object parameter database.

DtSurfaces are stored in a DtSurfaceManager, a member of the DtTerrainInterface. Individual triangles and polygons just hold a reference to a DtSurface in the DtSurfaceManager.

Terrain Capabilities

After loading a terrain into the terrain interface the DtTerrainCapabilities class is filled out and available from the DtTerrainInterface::TerrainCapabilities() method. The capabilities class contains a list of key value pairs that describe the pertinent information about the terrain.

The most important item that is found in the terrain capabilities class is whether the terrain supports preloading. This is useful with paged terrains and is discussed later in SynchronousandAsynchronousCallswithPagedTerrains.

Terrain File Locations

One of the import aspects of the terrain interface is to set up the file locations that the interface will use when locating configuration files and terrain data. The DtAppPathResolver class can be used before the creation of the DtTerrainInterface class to change the default locations of these files. Since VRF 5.0 the terrain subsystem is interested in the following directories:

• SharedData: This directory it the top folder of all the files shared by MAK softwares. Like the terrain folder.
• terrainData: This directory is under the shareData and contain sub folders like: navData, scenes, Terrain and TerrainConfiguration.
• data. The data directory usually contains the bulk data such as terrain polygon data and models.
• userData: The userData directory contains data that is expected to be written to by users
• appData: The appData directory contains data that is expected to not be changed by users and contains the ModelDefinitions files.

All of these directories can be referenced in file locations by using $(SHARED_DATA_DIR), $(DATA_DIR), $(USER_DIR), $(APP_DIR) in file names and data files. For example you can load a terrain by specifying $(SHARED_DATA_DIR).mtf , instead of having to specify the path directly.