DtTerrainInterface Class Reference

DtTerrainInterface allows access to common terrain calls without having to know the terrain implementation. More...

Classes
struct	OceanLayer
	Global ocean layer info; used in conjunction with the polygon data. More...

Public Types
typedef std::map< std::string, std::string >	TerrainSettings
typedef MAKVRinTerra::DtPathFinder	DtPathFinder

Public Member Functions
	DtTerrainInterface ()
	Constructor.
virtual	~DtTerrainInterface ()
	Destructor.
virtual bool	init ()
	Virtual initialization.
virtual void	tick ()
	Cleans up finished async server jobs, and checks for path finder removal.
virtual bool	isSameTerrain (const DtFilename &) const
	Returns true if this terrain is the same terrain as is currently open.
virtual void	addTerrainImplementation (const DtString &implementationName, DtTerrainImplementationCreatorFcn creatorFcn)
	Add a terrain implementation type to the set of terrain implementations that can be used by this interface.
virtual bool	loadTerrain (const DtString &filename, const TerrainSettings &settings=TerrainSettings())
	Settings will be merged into existing – not replace.
virtual bool	loadTerrain (const DtString &filename, MAKVRinTerra::DtFeatureLoader &featureLoader, const TerrainSettings &settings=TerrainSettings())
	Settings will be merged into existing – not replace.
virtual bool	unloadTerrain ()
virtual bool	terrainIsLoaded ()
virtual DtString	loadedFilename () const
virtual const Coordinate_System *	coordinateSystem () const
virtual Coordinate_System *	coordinateSystem ()
virtual std::auto_ptr < MAKVRinTerra::DtObstacleFeatureSet >	obstacles (const std::string &type) const
	Returns a DtObstacleFeatureSet configured using the provided type.
virtual std::auto_ptr < MAKVRinTerra::DtObstacleFeatureSet >	obstacles (MAKVRinTerra::DtObstacleFeatureSetAdapter::Config config)
	Returns a DtObstacleFeatureSet configured using the provided type and parameters.
virtual std::auto_ptr < MAKVRinTerra::DtPathFeatureSet >	paths (const std::string &type) const
virtual std::auto_ptr < MAKVRinTerra::DtFeatureSet >	allFeatures (const std::string &type=std::string(), bool readDirectly=false) const
virtual double	terrainHeightAboveSeaLevel (const DtPoint &databaseLocation, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Returns the height above sea level for the topmost terrain intersection at databaseLocation.
virtual bool	terrainHeightAndIntersection (const DtVector &localLocation, double &height, DtChordIntersectionRecord &record, DtIntersectionRecord::DtIntersectionType irtFlag=DtIntersectionRecord::INT_ALL_DATA, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Returns whether there is a terrain intersection and if so sets height and record from the topmost terrain intersection point.
virtual bool	closestIntersection (const DtVector &localLocation, DtPoint &intersectionPoint, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Similar to the terrainHeight functions above.
virtual bool	closestIntersection (double lat, double lon, DtPoint &intersectionPoint, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Same as above function, but accepts location in lat/lon.
virtual bool	closestIntersection (const DtVector &localLocation, DtChordIntersectionRecord &record, DtIntersectionRecord::DtIntersectionType irtFlag=DtIntersectionRecord::INT_ALL_DATA, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Same as above function, but returns the entire intersection record, and not just the intersection point.
virtual bool	closestIntersection (double lat, double lon, DtChordIntersectionRecord &record, DtIntersectionRecord::DtIntersectionType irtFlag=DtIntersectionRecord::INT_ALL_DATA, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Same as above function, but accepts location in lat/lon.
virtual bool	closestIntersection (const std::list< DtVector > &localLocationList, DtChordIntersectRecordList &recordList, int &numIntersections, DtIntersectionRecord::DtIntersectionType irtFlag=DtIntersectionRecord::INT_ALL_DATA, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Returns complete intersection information about the closest terrain intersection point for each location in the list in Database Coordinates.
virtual bool	intersect (const DtChord &chord, DtPoint &intersectionPoint, double &intersectionTime, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Calculates the first terrain intersection point along a chord given in Database Coordinates.
virtual bool	intersect (const DtChord &chord, DtChordIntersectionRecord &record, DtIntersectionRecord::DtIntersectionType irtFlag=DtIntersectionRecord::INT_ALL_DATA, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Returns complete intersection information about the first terrain intersection point along a chord given in Database Coordinates.
virtual bool	intersect (const DtSphere &sphere, DtSphereIntersectionRecord &record, DtIntersectionRecord::DtIntersectionType irtFlag=DtIntersectionRecord::INT_ALL_DATA, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Sphere intersection test.
virtual bool	allIntersectsAlongChord (const DtChord &chord, DtChordIntersectRecordList &intList, DtIntersectionRecord::DtIntersectionType irtFlag=DtIntersectionRecord::INT_ALL_DATA, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Computes the list of all intersections of a chord (in Database Coordinates) with the terrain database.
virtual bool	allIntersectsAlongChordDebug (const DtChord &chord, DtChordIntersectRecordList &intList, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Same as allIntersectsAlongChord, but prints debug info about all surfaces found.
virtual bool	intersectList (const std::list< DtChord > &chordList, DtChordIntersectRecordList &recordList, int &numTerrainIntersections, DtIntersectionRecord::DtIntersectionType irtFlag=DtIntersectionRecord::INT_ALL_DATA, bool *dataAvailable=0, bool overrideBlockingAssert=false) const
	Returns complete intersection information about the first terrain intersection points along each of a list of DtChords given in Database Coordinates.
virtual void	preloadTerrainAreas (const DtTerrainPagingGeometryList &preloadGeometry)
	Specifies a list of terrain areas that should be preloaded by the terrain implementation, in the case of a paging or streaming terrain source.
virtual const DtTerrainCapabilities *	terrainCapabilities () const
virtual bool	addTerrainPassThroughLayer (const DtString &layerType)
	Adds a pass though layer registered with the specified type to the currently loaded terrain implementation.
virtual void	setIntersectDataLoadExpireTime (const double &expireTime)
	Set the default expiration time for data load requests generated by intersect calls that require data that has not been loaded (paged-in).
virtual void	expireDataLoadRequestsBeforeTime (const double &currentTime)
virtual void	setDataPath (const std::string &)
	Sets the path to find for the data directory.
virtual std::string	dataPath () const
virtual void	setUserDataPath (const std::string &)
	Sets the path to find for the data directory.
virtual std::string	userDataPath () const
virtual void	trianglesInArea (DtTriangleCallbackFcn func, DtTriangleCallbackFinalizeFcn finalize, DtTerrainProcessPolygonsBox &box, void *usr) const
	Calls the function in the first argument on each triangle in the area specified by the box.
virtual boost::shared_ptr < DtAsyncJobMapEntry >	makePathAsync (const DtPoint &localStart, const DtPoint &localDestination, const std::string &type, const double &maxSearchRadius, const double &startProximityThreshold, DtPathFinder::DtWeightFactorsListPtr weightFactors=DtPathFinder::DtWeightFactorsListPtr(new DtPathFinder::DtWeightFactorsList))
	Register asynchronous path finding task.
virtual bool	onPathFeature (const DtPoint &location, const DtString &type, double buffer=0.5)
	returns whether the given point is within "offset" distance of any edge on the path graph.
virtual boost::shared_ptr < DtAsyncJobMapEntry >	addAsyncJob (DtAsyncJob *job)
	Add an user defined async job type to the job queue.
MAKVRinTerra::DtProj::CPtr	localProj () const
	Returns the local DtProj object for the current terrain.
MAKVRinTerra::DtFeaturesDebugger &	debugger () const
MAKVRinTerra::DtQuery	findQuery (const std::string &name) const
const double	topoDistance (const DtPoint &start, const DtPoint &end, const MAKVRinTerra::DtProj &localProj)
MAKVRinTerra::DtClosestPathFeatureFinder	closestFeatureOnNetwork (const std::string &type, const DtPoint &startingLocation, const double &searchRadius, bool *dataAvailable=NULL)
	Finds the closest feature on the feature network to startingLocation.
void	breakUpChord (const MAKVRinTerra::DtProj &, const DtChord &chord, std::vector< DtChord > &chords) const
void	breakUpChord (const DtChord &chord, std::vector< DtChord > &chords) const
virtual boost::shared_ptr < DtTerrainInterfaceConfig >	config () const
virtual bool	terrainHeightUnderWater (const DtVector &databaseLocation, double &groundHeight, DtSurface &groundSurface, DtVector &groundNormal, double &waterHeight, DtSurface::DtMedium &topSurfaceMedium, bool *dataAvailable=0, bool overrideBlockingAssert=false)
	This function gets the ground and water (if it exists) surfaces at the given location.
virtual bool	terrainHeightUnderWaterDebug (const DtVector &databaseLocation, double &groundHeight, DtSurface &groundSurface, DtVector &groundNormal, double &waterHeight, DtSurface::DtMedium &topSurfaceMedium, bool debug, bool *dataAvailable=0, bool overrideBlockingAssert=false)
	Performs the computations for terrainHeightUnderWater.
virtual void	setAssertOnBlockingTerrainCalls (bool assertBlock)
	Determines if an exception should be thrown if a blocking terrain call is made.
virtual bool	assertOnBlockingTerrainCalls () const
	Determines if an exception should be thrown if a blocking terrain call is made.

Static Public Member Functions
static void	setModelDefinitionFilePath (const DtString &fullFilePath)
static DtString	modelDefinitionFilePath ()

Protected Member Functions
virtual bool	nonPolygonalWaterHeight (const DtVector &localLocation, double &height) const
	Function to return the water level defined for water regions that aren't defined with surface water polygons.
virtual double	defaultWaterDepth (const DtVector &localLocation) const
	Defines the default water depth when floor and surface levels are not defined in the database.
virtual double	defaultSurfaceElevation (const DtVector &localLocation) const
	Defines the elevation of the terrain surface when there is no data.
virtual DtSurface::DtMedium	mediumForUnspecPolygonsUnderWater () const
	Defines what to do in terrainHeightUnderWater when a polygon with medium "unspecified" is encountered below a water surface.
virtual double	landAboveWaterMinimumSeparation () const
	This function returns a constant threshold value that determines how far an unspecified-medium polygon has to be above a water surface for it to be considered above-sea-level land.
void	insertNonPolyWaterIntoIntersectionList (DtChordIntersectionRecord &waterInterx, DtChordIntersectRecordList &intrxList) const
	Insert the given intersection record into the intersection list based on intersection time order.
virtual DtChordIntersectionRecord	blankSurfaceIntersectionRecord (const DtVector &localLocation, const double height) const
	Creates a chord intersection record corresponding to a surface with unspecified soil type (and medium).
virtual bool	nonPolygonalWaterIntersect (const DtChord &chord, DtChordIntersectionRecord &waterInterxRecord) const
	If there is non-polygonal water, this function computes an intersection record for the chord with this water.
virtual DtPathFinder::Path	makePath (const DtPoint &localStart, const DtPoint &localDestination, const std::string &type, const double &maxSearchRadius, const double &startProximityThreshold, boost::function< bool()> cancelCheck, DtPathFinder::ReturnCode &result, DtPathFinder::DtWeightFactorsListPtr weightFactors=DtPathFinder::DtWeightFactorsListPtr(new DtPathFinder::DtWeightFactorsList)) const
	Make a path from start to destination on features configured using the provided type.
virtual void	loadConfigurationFile (const DtFilename &filename)

Protected Attributes
DtTerrainImplementation *	myTerrainImpl
bool	myTerrainIsLoaded
	Status publisher needs to keep track of when terrain is loaded and unloaded.
DtTerrainImplementationManager *	myTerrainImplManager
DtConsoleCommandManager *	myConsoleCommandManager
std::list< DtConsoleCommand * >	myCommandList
DtString	myLoadedFilename
	The last filename that was passed to loadTerrain()
DtString	myUnresolvedFilename
double	myLastFileTime
	Needed in case file is saved with same name and then reloaded.
TerrainSettings	mySettings
boost::scoped_ptr < MAKVRinTerra::DtFeatureContext >	myFeatureContext
MAKVRinTerra::DtProj::CPtr	myProjObject
DtAsyncJobServer	myAsyncJobServer
	Manages asynchronous path planning tasks.
boost::shared_ptr < DtTerrainInterfaceConfig >	myConfig
DtFilename	myConfigFilename
OceanLayer	myGlobalOceanLayer

Static Protected Attributes
static DtString	theModelDefinitionFilePath
static double	theTerrainPagingMaxHeight

Detailed Description

DtTerrainInterface allows access to common terrain calls without having to know the terrain implementation.

Additional terrain implementations can be added as well.

Synchronous and asynchronous calls with paged terrains

The terrain intersection functions in this class will by default block if the requested data needs to be paged in. In general making a blocking call from any tick-based function will cause a long delay resulting in a long frame which will most likely cause very undesirable effects on the simulation. In order to make an asynchronous call a bool pointer called "dataAvailable" must be specified. If the data for the requested location(s) has already been paged in and the result is immediately available, dataAvailble will be set to true and the results returned will reflect the contents of the terrain database. Otherwise, the terrain intersection call will cause the terrain implementation to queue the loading of the corresponding terrain page and the call will return immediately and set dataAvailable to false. In this case, the return value of the function should not be used and it does not reflect the terrain database. For most terrain implementations the cost of making terrain intersections on unavailable databases pages should be minimal and its expected that callers can poll for the data by making repeated intersection calls.

Member Typedef Documentation

typedef std::map<std::string, std::string> DtTerrainInterface::TerrainSettings

typedef MAKVRinTerra::DtPathFinder DtTerrainInterface::DtPathFinder

Constructor & Destructor Documentation

DtTerrainInterface::DtTerrainInterface

(

)

Constructor.

virtual DtTerrainInterface::~DtTerrainInterface ( )

virtual

Destructor.

Member Function Documentation

virtual bool DtTerrainInterface::init ( )

virtual

Virtual initialization.

Call this after construction, and before calling any other members on the class. Creates the terrain implementation manager

virtual void DtTerrainInterface::tick ( )

virtual

Cleans up finished async server jobs, and checks for path finder removal.

virtual bool DtTerrainInterface::isSameTerrain ( const DtFilename &  ) const

virtual

Returns true if this terrain is the same terrain as is currently open.

virtual void DtTerrainInterface::addTerrainImplementation ( const DtString &  implementationName, DtTerrainImplementationCreatorFcn  creatorFcn  )

virtual

Add a terrain implementation type to the set of terrain implementations that can be used by this interface.

virtual bool DtTerrainInterface::loadTerrain ( const DtString &  filename, const TerrainSettings &  settings = TerrainSettings()  )

virtual

Settings will be merged into existing – not replace.

virtual bool DtTerrainInterface::loadTerrain ( const DtString &  filename, MAKVRinTerra::DtFeatureLoader &  featureLoader, const TerrainSettings &  settings = TerrainSettings()  )

virtual

Settings will be merged into existing – not replace.

virtual bool DtTerrainInterface::unloadTerrain ( )

virtual

virtual bool DtTerrainInterface::terrainIsLoaded ( )

virtual

virtual DtString DtTerrainInterface::loadedFilename ( ) const

virtual

Returns

The last filename that was passed to loadTerrain() and successfully loaded.

virtual const Coordinate_System* DtTerrainInterface::coordinateSystem ( ) const

virtual

virtual Coordinate_System* DtTerrainInterface::coordinateSystem ( )

virtual

virtual std::auto_ptr<MAKVRinTerra::DtObstacleFeatureSet> DtTerrainInterface::obstacles ( const std::string &  type ) const

virtual

Returns a DtObstacleFeatureSet configured using the provided type.

See appData/settings/featureconfig.txt for types.

virtual std::auto_ptr<MAKVRinTerra::DtObstacleFeatureSet> DtTerrainInterface::obstacles ( MAKVRinTerra::DtObstacleFeatureSetAdapter::Config  config )

virtual

Returns a DtObstacleFeatureSet configured using the provided type and parameters.

See appData/settings/featureconfig.txt for types.

virtual std::auto_ptr<MAKVRinTerra::DtPathFeatureSet> DtTerrainInterface::paths ( const std::string &  type ) const

virtual

virtual std::auto_ptr<MAKVRinTerra::DtFeatureSet> DtTerrainInterface::allFeatures ( const std::string &  type = std::string(), bool  readDirectly = false  ) const

virtual

virtual double DtTerrainInterface::terrainHeightAboveSeaLevel ( const DtPoint &  databaseLocation, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Returns the height above sea level for the topmost terrain intersection at databaseLocation.

Parameters

Input
databaseLocation	the location to test
Output
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false and zero will be returned.
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

terrainHeight (or zero if the terrain is not yet available)

virtual bool DtTerrainInterface::terrainHeightAndIntersection ( const DtVector &  localLocation, double &  height, DtChordIntersectionRecord &  record, DtIntersectionRecord::DtIntersectionType  irtFlag = DtIntersectionRecord::INT_ALL_DATA, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Returns whether there is a terrain intersection and if so sets height and record from the topmost terrain intersection point.

Parameters

Input
localLocation	the location to test
irtFlag	specifies which data should be calculated and returned for each intersection point
Output
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false, height will be set to zero, and the record will not reflect any results.
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	a terrain intersection was found
false	if dataAvailable was specified and returns true, then the database does not have an intersection at localLocation. Otherwise false indicates that the data is not yet available.

virtual bool DtTerrainInterface::terrainHeightUnderWater ( const DtVector &  databaseLocation, double &  groundHeight, DtSurface &  groundSurface, DtVector &  groundNormal, double &  waterHeight, DtSurface::DtMedium &  topSurfaceMedium, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  )

virtual

This function gets the ground and water (if it exists) surfaces at the given location.

It provides the ground height, the surface structure for the ground, the normal of that surface, the height of the water surface, and a flag indicating whether there is actually water.

Note

1 - These functions to NOT intersect vector or geometric feature data - they are intended for finding the "ground" height. 2 - These functions determine the topmost terrain surfaces. Thus if there are multiple levels of terrain, the highest intersection point will be returned as the height. In order to get the closest intersection points with terrain (and possibly features data, use the closestIntersection() functions below. 3 - This function will make assumptions about "unspecified" surfaces, and will synthesize terrain heights if the location is off the known terrain, using default heights and water depths in the database or the code. Thus it will always return a ground surface.

If there is water defined in the terrain that is not part of the polygonal terrain, Cases:

• Terrain not yet available: dataAvailable flag and function return value are both false. Other data is just default.
• No terrain or non-poly water found: a default value for water level and bottom level is used.
• Terrain polygon only found, of medium type "unspecified": The elevation of this polygon is used as the water surface height, and a default depth is used to synthesize a sea floor of type "ground". This is different from the terrainHeight functions, which return the unspecified-type polygon as an unspecified surface–in this function, it is presumed to be water. Ground entities are not expected to query for sea surface height.
• Terrain polygon only found, of type "ground": This is returned as the ground level, and isWater is set to false.
• Terrain polygon only found, of type "water surface": This provides the sea surface height, and a default depth is used to generate a sea floor ground polygon.
• Multiple terrain polygons found: If the top one is water, that is the water level; the next ground one, if any, is the sea floor. If the top one is ground, that is the ground surface, and isWater is false.
• non-Poly water only: This provides the sea surface, and a default depth provides the sea floor.
• non-Poly water and an unspecified polygon: Treat the unspecified polygon as ground if it is higher. If the unspecified poly is lower, treat it as water or ground depending on mediumForUnspecPolygonsUnderWater(). Non-poly water otherwise acts as a water polygon added to the ground terrain polygons found along a vertical chord at the location; water surface polygons are ignored.

Parameters

Output
groundHeight	The height of the ground at the location, either under a water surface or as the top surface.
groundSurface	The surface (structure) of the ground.
waterHeight	The height of the water surface at the location. NOT VALID IF TOP SURFACE IS GROUND.
topSurfaceMedium	The medium (see surface.h) of the top surface. This returns one of three values: Ground, WaterSurface, or UnspecifiedMedium. If Ground, then the waterHeight parameter is not changed; it's value is not meaningful. If UnspecifiedMedium, then the calling code can interpret this as it needs to. For example, if this function finds only an unspecified surface, it will return its height in waterHeight as if it were water, and synthesize a bottom surface for groundHeight. The calling code could choose to treat the unspecified surface as ground though.
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" in the class documentation for DtTerrainInterface for information on how to specify that this function be blocking or non-blocking. If the terrain data is not yet paged in, dataAvailable will be set to false.
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the data availability

Return values

true	All source terrain was available, so the output parameter values are valid. Note that the query may be outside the region of source data, but the function will still return true, with default values in the parameters.
false	If some source data for the location was not yet available, i.e. not paged in.

virtual bool DtTerrainInterface::terrainHeightUnderWaterDebug ( const DtVector &  databaseLocation, double &  groundHeight, DtSurface &  groundSurface, DtVector &  groundNormal, double &  waterHeight, DtSurface::DtMedium &  topSurfaceMedium, bool  debug, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  )

virtual

Performs the computations for terrainHeightUnderWater.

If debug is true, dumps information about the surfaces it finds to the Warn simulation console.

virtual bool DtTerrainInterface::closestIntersection ( const DtVector &  localLocation, DtPoint &  intersectionPoint, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Similar to the terrainHeight functions above.

Function to determine the closest intersection to a specified location, either in local (DB) coordinates or in lat/lon. The closest intersection is defined as the closest intersection in the down or up direction from location. Thus if there are multiple terrain levels, it will not necessarily return an intersection with the topmost as the terrainHeight functions do.

Note

Unlike the terrainHeight functions, if the vectorNetworkRecord and vectorNetworkIntersectionRecord are non-NULL, it will compute an intersection with the vector network and return the best intersection as defined by the metrics in the vectorNetworkRecord.

Return Values: True if any intersection, vector data or terrain, is found. If a vector data intersection is found, then the vecNetworkIntersectionRecord is set appropriately. If at least one terrain intersection is found, the intersectionPoint parameter is set to the closest intersection point.

Parameters

Input
localLocation	the location to test
Output
intersectionPoint	the point of intersection, left unchanged if dataAvailable is set to false.
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false, intersectionPoint will not be modified and false will be returned.
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	a terrain intersection was found
false	if dataAvailable was specified and returns true, then the database does not have an intersection at localLocation. Otherwise false indicates that the data is not yet available.

virtual bool DtTerrainInterface::closestIntersection ( double  lat, double  lon, DtPoint &  intersectionPoint, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Same as above function, but accepts location in lat/lon.

Parameters

Input
lat	the latitude to test
lon	the longitude to test
Output
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false, intersectionPoint will not be modified and false will be returned.
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	a terrain intersection was found
false	if dataAvailable was specified and returns true, then the database does not have an intersection at localLocation. Otherwise false indicates that the data is not yet available.

virtual bool DtTerrainInterface::closestIntersection ( const DtVector &  localLocation, DtChordIntersectionRecord &  record, DtIntersectionRecord::DtIntersectionType  irtFlag = DtIntersectionRecord::INT_ALL_DATA, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Same as above function, but returns the entire intersection record, and not just the intersection point.

Parameters

Input
localLocation	the location to test
irtFlag	specifies which data should be calculated and returned for each intersection point
Output
record	the result of the terrain intersection
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false, record will not be modified and false will be returned.
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	a terrain intersection was found
false	if dataAvailable was specified and returns true, then the database does not have an intersection at localLocation. Otherwise false indicates that the data is not yet available.

virtual bool DtTerrainInterface::closestIntersection ( double  lat, double  lon, DtChordIntersectionRecord &  record, DtIntersectionRecord::DtIntersectionType  irtFlag = DtIntersectionRecord::INT_ALL_DATA, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Same as above function, but accepts location in lat/lon.

Parameters

Input
lat	the latitude to test
lon	the longitude to test
irtFlag	specifies which data should be calculated and returned for each intersection point
Output
record	the result of the terrain intersection
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false, intersectionPoint will not be modified and false will be returned.
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	a terrain intersection was found
false	if dataAvailable was specified and returns true, then the database does not have an intersection at localLocation. Otherwise false indicates that the data is not yet available.

virtual bool DtTerrainInterface::closestIntersection ( const std::list< DtVector > &  localLocationList, DtChordIntersectRecordList &  recordList, int &  numIntersections, DtIntersectionRecord::DtIntersectionType  irtFlag = DtIntersectionRecord::INT_ALL_DATA, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Returns complete intersection information about the closest terrain intersection point for each location in the list in Database Coordinates.

Parameters

Input
localLocationList	list of locations to test
irtFlag	specifies which data should be calculated and returned for each intersection point
Output
recordList	a DtChordIntersectionRecordList (one record for each localLocation).
numIntersections	set to the number of intersections that occur for the list of locations.
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false, recordList will not represent any intersections and numIntersections will be set to 0.
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	any chord intersects the terrain
false	if dataAvailable was specified and returns true, then none of the chords intersect the terrain. Otherwise false indicates that the data is not yet available.

virtual bool DtTerrainInterface::intersect ( const DtChord &  chord, DtPoint &  intersectionPoint, double &  intersectionTime, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Calculates the first terrain intersection point along a chord given in Database Coordinates.

Parameters

Input
chord	the chord to test
Output
intersectionPoint	location of the intersection or left unchanged if there's no intersection or the data is not yet available (see dataAvailable).
intersectionTime	time of the intersection along the input chord or left unchanged if there's no intersection or the data is not yet available (see dataAvailable).
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false, and intersectionPoint and intersectionTime will be left unchanged.
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	if the chord intersects the terrain
false	if dataAvailable was specified and returns true, then the chord does not intersect the terrain. Otherwise false indicates that the data is not yet available.

virtual bool DtTerrainInterface::intersect ( const DtChord &  chord, DtChordIntersectionRecord &  record, DtIntersectionRecord::DtIntersectionType  irtFlag = DtIntersectionRecord::INT_ALL_DATA, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Returns complete intersection information about the first terrain intersection point along a chord given in Database Coordinates.

The irtFlag value specifies which data should be calculated and returned for each intersection point.

Parameters

Input
chord	the chord to test
irtFlag	specifies which data should be calculated and returned for each intersection point
Output
record	the result of the terrain intersection
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false, record will not reflect any terrain intersections
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	if the chord intersects the terrain
false	if dataAvailable was specified and returns true, then the chord does not intersect the terrain. Otherwise false indicates that the data is not yet available.

virtual bool DtTerrainInterface::intersect ( const DtSphere &  sphere, DtSphereIntersectionRecord &  record, DtIntersectionRecord::DtIntersectionType  irtFlag = DtIntersectionRecord::INT_ALL_DATA, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Sphere intersection test.

Parameters

Input
sphere	the sphere to test
irtFlag	specifies which data should be calculated and returned for each intersection point
Output
record	the result of the terrain intersection
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false, record will not reflect any terrain intersections
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	if the sphere intersects with any terrain polygons
false	if dataAvailable was specified and returns true, then the sphere does not intersect the terrain. Otherwise false indicates that the data is not yet available.

virtual bool DtTerrainInterface::allIntersectsAlongChord ( const DtChord &  chord, DtChordIntersectRecordList &  intList, DtIntersectionRecord::DtIntersectionType  irtFlag = DtIntersectionRecord::INT_ALL_DATA, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Computes the list of all intersections of a chord (in Database Coordinates) with the terrain database.

Parameters

Input
chord	the chord to test
irtFlag	specifies which data should be calculated and returned for each intersection point

Note

that passing an irtFlag value of INT_EXISTS will probably never return more than one intersection.

Parameters

Output
intList	the result of the terrain intersection
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false and intList will not reflect any terrain intersections
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	if the chord intersects the terrain
false	if dataAvailable was specified and returns true, then the chord does not intersect the terrain. Otherwise false indicates that the data is not yet available.

virtual bool DtTerrainInterface::allIntersectsAlongChordDebug ( const DtChord &  chord, DtChordIntersectRecordList &  intList, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Same as allIntersectsAlongChord, but prints debug info about all surfaces found.

Prints to sim console at "warn" notify level. Always gets all data from intersections.

virtual bool DtTerrainInterface::intersectList ( const std::list< DtChord > &  chordList, DtChordIntersectRecordList &  recordList, int &  numTerrainIntersections, DtIntersectionRecord::DtIntersectionType  irtFlag = DtIntersectionRecord::INT_ALL_DATA, bool *  dataAvailable = 0, bool  overrideBlockingAssert = false  ) const

virtual

Returns complete intersection information about the first terrain intersection points along each of a list of DtChords given in Database Coordinates.

The returned record list is a DtChordIntersectionRecordList (one record for each chord).

Parameters

Input
chordList	the chords to test
irtFlag	specifies which data should be calculated and returned for each intersection point
Output
numTerrainIntersections	number of chords that intersected with the terrain
numVectorNetworkIntersections	number of chords that intersected with the vector network
dataAvailable	Please see "Synchronous and asynchronous calls with paged terrains" for information on how to specify that this function be blocking or non-blocking. If the data is not yet paged in, dataAvailable will be set to false, numTerrainIntersections and numVectorNetworkIntersections will be set to zero and the recordList will not reflect any intersections.
overrideBlockingAssert	when set to true this parameter will prevent an assertion from being thrown when the terrain implementation has myAssertOnBlockingTerrainCalls set to true. This should only be done when the call is being made from outside the main simulation thread and a blocking call would not cause a a problem.

Returns

result of the terrain intersection or data availability

Return values

true	if any chord intersected the terrain (or vector network if specified)
false	if dataAvailable was specified and returns true, then the chord does not intersect the terrain. Otherwise false indicates that the data is not yet available.

virtual void DtTerrainInterface::preloadTerrainAreas ( const DtTerrainPagingGeometryList &  preloadGeometry )

virtual

Specifies a list of terrain areas that should be preloaded by the terrain implementation, in the case of a paging or streaming terrain source.

The typical use of this is to specify parts of the terrain that are expected to be needed in the near future.

The terrain may not be loaded immediately upon making this call, and there is no guarantee that the terrain areas will be available for intersection immediately after making this call.

Parameters

preloadGeometry

A list of the geometric areas that should be preloaded. They can be specified using any of the subclasses of DtTerrainPagingGeometry.

Note

The geometry set with this call completely replaces any geometry previously set using this call.

This call may be a noop depending on what type of terrain is loaded.

virtual const DtTerrainCapabilities* DtTerrainInterface::terrainCapabilities ( ) const

virtual

Returns

A class which describes the capabilities of the currently loaded terrain. This provides a guide on particular features of the terrain implementation that are supported or not supported, and should guide the user of the DtTerrainInterface API when interacting with this terrain. If no terrain is loaded, this will return a null pointer.

virtual bool DtTerrainInterface::addTerrainPassThroughLayer ( const DtString &  layerType )

virtual

Adds a pass though layer registered with the specified type to the currently loaded terrain implementation.

This is typically a debugging or analysis activity.

virtual void DtTerrainInterface::setAssertOnBlockingTerrainCalls ( bool  assertBlock )

virtual

Determines if an exception should be thrown if a blocking terrain call is made.

This can help to track down blocking terrain calls which are causing problems with a running simulation. Note that calling the blocking form of any terrain intersection function will cause an assertion; it is not necessary for the call to actually block and even non-paging implementations will assert. This is done to make it easier to find potential problems regardless of the particular terrain or location being used.

virtual bool DtTerrainInterface::assertOnBlockingTerrainCalls ( ) const

virtual

Determines if an exception should be thrown if a blocking terrain call is made.

This can help to track down blocking terrain calls which are causing problems with a running simulation. Note that calling the blocking form of any terrain intersection function will cause an assertion; it is not necessary for the call to actually block and even non-paging implementations will assert. This is done to make it easier to find potential problems regardless of the particular terrain or location being used.

virtual void DtTerrainInterface::setIntersectDataLoadExpireTime ( const double &  expireTime )

virtual

Set the default expiration time for data load requests generated by intersect calls that require data that has not been loaded (paged-in).

Parameters

expireTime

The expiration time to be assigned to data load requests generated by intersect calls on the terrain implementation.

virtual void DtTerrainInterface::expireDataLoadRequestsBeforeTime ( const double &  currentTime )

virtual

virtual void DtTerrainInterface::setDataPath ( const std::string &  )

virtual

Sets the path to find for the data directory.

For terrains being loaded, will substitute DataDirectory for the dataPath (default to ../data) and UserDataDirectory to the user data path (default to ../userData)

virtual std::string DtTerrainInterface::dataPath ( ) const

virtual

virtual void DtTerrainInterface::setUserDataPath ( const std::string &  )

virtual

Sets the path to find for the data directory.

For terrains being loaded, will substitute DataDirectory for the dataPath (default to ../data) and UserDataDirectory to the user data path (default to ../userData)

virtual std::string DtTerrainInterface::userDataPath ( ) const

virtual

virtual void DtTerrainInterface::trianglesInArea ( DtTriangleCallbackFcn  func, DtTriangleCallbackFinalizeFcn  finalize, DtTerrainProcessPolygonsBox &  box, void *  usr  ) const

virtual

Calls the function in the first argument on each triangle in the area specified by the box.

Once all of the triangles have been processed, it calls the finalize function to signify it has completed.

Parameters

func	Function that will handle a single terrain triangle
finalize	Function that will handle when this function is completed
box	The area (in local coordinates) in which to get terrain triangles from
usr	The object that owns both the first and second argument of this function

static void DtTerrainInterface::setModelDefinitionFilePath ( const DtString &  fullFilePath )

static

static DtString DtTerrainInterface::modelDefinitionFilePath ( )

static

virtual boost::shared_ptr<DtAsyncJobMapEntry> DtTerrainInterface::makePathAsync ( const DtPoint &  localStart, const DtPoint &  localDestination, const std::string &  type, const double &  maxSearchRadius, const double &  startProximityThreshold, DtPathFinder::DtWeightFactorsListPtr  weightFactors = DtPathFinder::DtWeightFactorsListPtr(new DtPathFinder::DtWeightFactorsList)  )

virtual

Register asynchronous path finding task.

Once token's status is "complete", result can be used. See makePath.

virtual bool DtTerrainInterface::onPathFeature ( const DtPoint &  location, const DtString &  type, double  buffer = 0.5  )

virtual

returns whether the given point is within "offset" distance of any edge on the path graph.

virtual boost::shared_ptr<DtAsyncJobMapEntry> DtTerrainInterface::addAsyncJob ( DtAsyncJob *  job )

virtual

Add an user defined async job type to the job queue.

Parameters

job	Pointer to job object, should be initialized with operator new (tbb::task::allocate_root()).

MAKVRinTerra::DtProj::CPtr DtTerrainInterface::localProj

(

)

const

Returns the local DtProj object for the current terrain.

MAKVRinTerra::DtFeaturesDebugger& DtTerrainInterface::debugger

(

)

const

MAKVRinTerra::DtQuery DtTerrainInterface::findQuery

(

const std::string &

name

)

const

const double DtTerrainInterface::topoDistance	(	const DtPoint &	start,
		const DtPoint &	end,
		const MAKVRinTerra::DtProj &	localProj
	)

MAKVRinTerra::DtClosestPathFeatureFinder DtTerrainInterface::closestFeatureOnNetwork	(	const std::string &	type,
		const DtPoint &	startingLocation,
		const double &	searchRadius,
		bool *	dataAvailable = NULL
	)

Finds the closest feature on the feature network to startingLocation.

Returns false if no features are found.

Parameters

startingLocation	location in local to which the closest feature on the feature network is found.
searchRadius	The radius used to load in features
dataAvailable	If NULL, function will block for up to 20 seconds, and return false if the data is not loaded. Otherwise, being feature loading, but do not block. If the features are not fully loaded, it will find the closest feature using whichever features are loaded.

void DtTerrainInterface::breakUpChord	(	const MAKVRinTerra::DtProj &	,
		const DtChord &	chord,
		std::vector< DtChord > &	chords
	)		const

void DtTerrainInterface::breakUpChord	(	const DtChord &	chord,
		std::vector< DtChord > &	chords
	)		const

virtual boost::shared_ptr<DtTerrainInterfaceConfig> DtTerrainInterface::config ( ) const

virtual

virtual bool DtTerrainInterface::nonPolygonalWaterHeight ( const DtVector &  localLocation, double &  height  ) const

protectedvirtual

Function to return the water level defined for water regions that aren't defined with surface water polygons.

If this database has water defined this way, terrainCapabilities()->hasNonPolygonalWaterRegions() will return true.

Parameters

Height

The height of the water is returned in the height parameter.

Returns

Boolean indicating the success of the request.

Return values

True	If there is non-polygonal water at this location.
False	If there is no non-polygonal water at this location.

virtual double DtTerrainInterface::defaultWaterDepth ( const DtVector &  localLocation ) const

protectedvirtual

Defines the default water depth when floor and surface levels are not defined in the database.

The location argument is provided for future extension.

virtual double DtTerrainInterface::defaultSurfaceElevation ( const DtVector &  localLocation ) const

protectedvirtual

Defines the elevation of the terrain surface when there is no data.

The location argument is provided for future extension.

virtual DtSurface::DtMedium DtTerrainInterface::mediumForUnspecPolygonsUnderWater ( ) const

protectedvirtual

Defines what to do in terrainHeightUnderWater when a polygon with medium "unspecified" is encountered below a water surface.

If a database uses "unspecified" for all ground and water surfaces, then it is appropriate for this function to return WaterSurface. I.e. the unspecified polygons below non-poly water are redundant and ignored. (Unspecified polygons above water are still treated as ground; "above" means landAboveWaterMinimumSeparation() above the water surface.)

However, if a database uses "unspecified" for ground polygons, including the sea floor, then this function should return a Ground, signifying that the unspecified polygons below water are ground.

Returns

Ground or WaterSurface.

virtual double DtTerrainInterface::landAboveWaterMinimumSeparation ( ) const

protectedvirtual

This function returns a constant threshold value that determines how far an unspecified-medium polygon has to be above a water surface for it to be considered above-sea-level land.

If the unspecified polygon is below this threshold, it is considered "below" and will be classified according to mediumForUnspecPolygonsUnderWater().

This value could be very tiny, but on a curved-earth terrain with unspecified-medium polygons being used (redundantly) as the sea surface, e.g. alongside non-polygonal sea-level data, the polygons will be tangent to the curved earth and may stick up above sea level at their edges.

void DtTerrainInterface::insertNonPolyWaterIntoIntersectionList ( DtChordIntersectionRecord &  waterInterx, DtChordIntersectRecordList &  intrxList  ) const

protected

Insert the given intersection record into the intersection list based on intersection time order.

virtual DtChordIntersectionRecord DtTerrainInterface::blankSurfaceIntersectionRecord ( const DtVector &  localLocation, const double  height  ) const

protectedvirtual

Creates a chord intersection record corresponding to a surface with unspecified soil type (and medium).

This is used in terrainHeightAndIntersection and closestIntersection. The surface intersection is set at a point on a vertical line through the localLocation, at the given altitude. The normal of the surface is set to point up. The "time" in the intersection record is set to 0.5.

virtual bool DtTerrainInterface::nonPolygonalWaterIntersect ( const DtChord &  chord, DtChordIntersectionRecord &  waterInterxRecord  ) const

protectedvirtual

If there is non-polygonal water, this function computes an intersection record for the chord with this water.

The chord is in local (database) coordinates.

Returns

True if there was an intersection with non-poly water.

virtual DtPathFinder::Path DtTerrainInterface::makePath ( const DtPoint &  localStart, const DtPoint &  localDestination, const std::string &  type, const double &  maxSearchRadius, const double &  startProximityThreshold, boost::function< bool()>  cancelCheck, DtPathFinder::ReturnCode &  result, DtPathFinder::DtWeightFactorsListPtr  weightFactors = DtPathFinder::DtWeightFactorsListPtr(new DtPathFinder::DtWeightFactorsList)  ) const

protectedvirtual

Make a path from start to destination on features configured using the provided type.

See appData/settings/featureconfig.txt for types.

Parameters

localStart	Start point in local
localDestination	Destination point in local
type	Type of features to path plan on, for example "MAK_ROAD"
maxSearchradius	A vertex more than this distance from the destination will not cause more feature data to be paged in.
cancelCheck	A function that returns true when the task should be canceled.
result	The return status of the make path call.
weightFactors	List of modifications to edge weights based on DtQueries

virtual void DtTerrainInterface::loadConfigurationFile ( const DtFilename &  filename )

protectedvirtual

Member Data Documentation

DtTerrainImplementation* DtTerrainInterface::myTerrainImpl

protected

bool DtTerrainInterface::myTerrainIsLoaded

protected

Status publisher needs to keep track of when terrain is loaded and unloaded.

DtTerrainImplementationManager* DtTerrainInterface::myTerrainImplManager

protected

DtConsoleCommandManager* DtTerrainInterface::myConsoleCommandManager

protected

std::list<DtConsoleCommand*> DtTerrainInterface::myCommandList

protected

DtString DtTerrainInterface::myLoadedFilename

protected

The last filename that was passed to loadTerrain()

DtString DtTerrainInterface::myUnresolvedFilename

protected

double DtTerrainInterface::myLastFileTime

protected

Needed in case file is saved with same name and then reloaded.

TerrainSettings DtTerrainInterface::mySettings

protected

DtString DtTerrainInterface::theModelDefinitionFilePath

staticprotected

double DtTerrainInterface::theTerrainPagingMaxHeight

staticprotected

boost::scoped_ptr<MAKVRinTerra::DtFeatureContext> DtTerrainInterface::myFeatureContext

protected

MAKVRinTerra::DtProj::CPtr DtTerrainInterface::myProjObject

protected

DtAsyncJobServer DtTerrainInterface::myAsyncJobServer

protected

Manages asynchronous path planning tasks.

boost::shared_ptr<DtTerrainInterfaceConfig> DtTerrainInterface::myConfig

protected

DtFilename DtTerrainInterface::myConfigFilename

protected

OceanLayer DtTerrainInterface::myGlobalOceanLayer

protected

---

The documentation for this class was generated from the following file:

• /exports/nfedora7-1/nightly/docs/vrforcesDevelopment.tot/include/terrainInterface/terrainInterface.h