Interface which abstracts the concept of a individually identifiable "thing" in the terrain.

This is the object which must be implemented in order to add new kinds of terrain to the dynamic terrain system. While features are generally dynamic (that is, they have something about them that can be changed through this interface) they do not have to be and features which do not respond to changes can be added in order to found during querying.

The terrain world deciding the change the state of a feature causes it to call the changeState function on the feature and pass in a history interface which allows the feature to view the history time line of events (change requests) which are currently affecting this feature. This is generally allows the feature to view every piece of data it needs in order to faithfully reconstruct the terrain from whatever state it is in. The ordering of this history is the only thing the terrain world uses the change request times for.

Features respond to a combination of a command (DtDynamicTerrainChange) and a geometry (DtDynamicTerrainGeometry). DtDynamicTerranCommand is an interface into a key/value dictionary, the keys are strings and values can be strings, doubles, ints, or bools. The terrain world (DtDynamicTerrainWorld, which manages the features) never actually calls any of the command member functions, only the features themselves. In this way drivers (writers of code that inserts change requests or code that inserts features) only need to agree amongst themselves about what the commands mean. This allows the features to respond to a wide varied of commands. Simple features like switch nodes and DOF nodes can respond to direct commands (i.e. state=1 or rotation=90) or they can use configuration to respond to higher levels commands (i.e. damage=true or state=open), or (and most importantly for the simulation) they can respond to generic events (i.e. event=explosion,force=50 or event=ditch,width=10).

The geometry object is allows feature implementations which can construct terrain dynamically to access the geometry of the request (i.e. to create an odd shaped ditch) which features which don't have those abilities can ignore it. A null geometry pointer is considered to match all other geometries.

Features are added to the terrain world when terrain is paged in and the terrain world takes ownership of them. Features are removed from the terrain world when the terrain is paged out by calling functions in the handles returned by the terrain world when the feature was added.

There does not have to be a one to one relationship between features and whatever objects implement the terrain dynamics. Features are designed such that each one can represent a very small or very large part of the terrain. They can represent something like a single switch node, in which case a terrain may add many thousands of features, or a single feature can be used to encapsulate an entire terrain layer.

Inheritance diagram for makVrv::DtDynamicTerrainFeature:

[legend]

Classes
class	RequestHandle

Public Member Functions
	DtDynamicTerrainFeature ()

virtual	~DtDynamicTerrainFeature ()

virtual bool	matches (const DtDynamicTerrainChange &, bool useOriginalGeometry=false) const =0

virtual bool	matches (const DtDynamicTerrainGeometry &, bool useOriginalGeometry=false) const =0

virtual const DtDynamicTerrainGeometry *	geometry () const =0

virtual const DtDynamicTerrainGeometry *	originalGeometry () const

virtual boost::optional< DtString >	featureAttribute (const DtString &key) const

virtual bool	isInDefaultState () const =0

virtual bool	lastStateWasDefaultState () const =0

virtual void	changeState (const DtDynamicTerrainChanges &history)=0

virtual void	iterateCommands (const boost::function< void(const DtDynamicTerrainChange &)> &callback) const

virtual void	iterateCommands (const boost::function< void(const DtDynamicTerrainChange &)> &callback, const DtString &key) const

void	changed ()

bool	pageOut ()

void	changes (const boost::function< void(const DtDynamicTerrainChanges &)> &callback) const

RequestHandle	addChangeRequest (DtDynamicTerrainChange *change)

RequestHandle	addChangeRequest (double time, DtDynamicTerrainChange *change)

virtual	~Link ()

RequestInfo &	request ()

DtDynamicTerrainFeature &	feature ()

	RequestInfo (DtDynamicTerrainChange *command)

virtual	~RequestInfo ()

const DtDynamicTerrainChange &	command () const

void	pageOut ()


virtual DtString	description () const =0

virtual const DtDynamicTerrainFeature *	parentFeature () const

Public Member Functions inherited from makVrv::DtDisconnectable
	DtDisconnectable ()

virtual	~DtDisconnectable ()

virtual boost::signalslib::connection	addDisconnectFunction (const boost::function< void()> &callback)

virtual bool	callDisconnectFunctions ()

Static Public Member Functions
static unsigned long long	GetObjectCount ()

static unsigned long long	GetObjectCount ()

static bool	Create (const boost::shared_ptr< DtDynamicTerrainFeature > &featureInfo, const boost::shared_ptr< RequestInfo > &reqInfo)

static unsigned long long	GetObjectCount ()

Protected Member Functions
virtual void	removeTerrainChange (const DtDynamicTerrainChange &change)


void	indexDoubleAscending (const DtString &key)

void	indexDoubleDescending (const DtString &key)

void	indexIntAscending (const DtString &key)

void	indexIntDescending (const DtString &key)

void	indexStringAscending (const DtString &key)

void	indexStringDescending (const DtString &key)

void	setupIndex (const DtString &key, DtDynamicTerrainIndex *index)

Private Types
typedef boost::signalslib::signal < void(const DtDynamicTerrainFeature &)>	Signal

typedef boost::signalslib::signal< >	ChangeSignal

typedef std::map< RequestInfo *, boost::shared_ptr< Link > >	LinkInfoMap

typedef tbb::spin_rw_mutex	Mutex

typedef std::map< DtString, DtDynamicTerrainIndex * >	IndexMap

typedef std::list < boost::shared_ptr< Link > >	LinkList

typedef tbb::spin_mutex	Mutex

Private Member Functions
	Link (const boost::shared_ptr< DtDynamicTerrainFeature > &featureInfo, const boost::shared_ptr< RequestInfo > &reqInfo)

void	makeLinkToFeature (const boost::shared_ptr< Link > &link)

void	breakLinkToFeature (LinkList::iterator i)


bool	makeLinkToRequest (const boost::shared_ptr< Link > &link)

virtual void	breakLinkToRequest (LinkInfoMap::iterator)

Private Attributes
ChangeSignal	myChangeSignal

Signal	myPageOutSignal

Mutex	myMutex

LinkInfoMap	myLinkMap

IndexMap	myIndices

const boost::shared_ptr < RequestInfo >	myRequestInfo

const boost::shared_ptr < DtDynamicTerrainFeature >	myFeatureInfo

boost::scoped_ptr < DtDynamicTerrainChange >	myCommand

Mutex	myLinkToFeaturesMutex

LinkList	myLinksToFeatures

Friends
class	Link

typedef boost::function< void(const DtDynamicTerrainFeature &)>	Callback

typedef boost::function< void(const DtDynamicTerrainFeature &, const DtDynamicTerrainChanges &)>	ChangeCallback

virtual boost::signalslib::connection	connectToChangeSignal (const ChangeCallback &callback) const

virtual boost::signalslib::connection	connectToPageOutSignal (const Callback &callback) const

Additional Inherited Members
Protected Types inherited from makVrv::DtDisconnectable
enum	State { NotUsed, InUse, Disconnected }

typedef tbb::spin_mutex	Mutex

Protected Attributes inherited from makVrv::DtDisconnectable
Mutex	myMutex

State	myDisconnectedState

boost::signalslib::signal< void()>	myDisconnectSignal

Member Typedef Documentation

typedef boost::function<void (const DtDynamicTerrainFeature&)> makVrv::DtDynamicTerrainFeature::Callback

Signal notification. The functions can be used to install callbacks which are called when events happen. These changes will be called from inside the call that makes the change.

typedef boost::function<void (const DtDynamicTerrainFeature&, const DtDynamicTerrainChanges&)> makVrv::DtDynamicTerrainFeature::ChangeCallback

Signal notification. The functions can be used to install callbacks which are called when events happen. These changes will be called from inside the call that makes the change.

typedef boost::signalslib::signal<void (const DtDynamicTerrainFeature&)> makVrv::DtDynamicTerrainFeature::Signal

private

typedef boost::signalslib::signal< > makVrv::DtDynamicTerrainFeature::ChangeSignal

private

typedef std::map<RequestInfo*, boost::shared_ptr<Link> > makVrv::DtDynamicTerrainFeature::LinkInfoMap

private

typedef tbb::spin_rw_mutex makVrv::DtDynamicTerrainFeature::Mutex

private

typedef std::map<DtString, DtDynamicTerrainIndex*> makVrv::DtDynamicTerrainFeature::IndexMap

private

typedef std::list<boost::shared_ptr<Link> > makVrv::DtDynamicTerrainFeature::LinkList

private

typedef tbb::spin_mutex makVrv::DtDynamicTerrainFeature::Mutex

private

Constructor & Destructor Documentation

makVrv::DtDynamicTerrainFeature::DtDynamicTerrainFeature ( )

Default Constructor.

virtual makVrv::DtDynamicTerrainFeature::~DtDynamicTerrainFeature ( )

virtual

Virtual destructor.

virtual makVrv::DtDynamicTerrainFeature::~Link ( )

virtual

virtual makVrv::DtDynamicTerrainFeature::~RequestInfo ( )

virtual

Member Function Documentation

static unsigned long long makVrv::DtDynamicTerrainFeature::GetObjectCount ( )

static

virtual bool makVrv::DtDynamicTerrainFeature::matches	(	const DtDynamicTerrainChange &	,
		bool	useOriginalGeometry = `false`
	)		const

pure virtual

Matching functions. Allow for arbitrary matching against requests, queries, and spatial index subspaces. Setting useOriginalGeometry will match against the geometry without any changes made by this system (i.e. uses the original geometry obtained from the parser).

Implemented in makVrv::DtOsgEarthDynamicTerrainFeature, DtEntityTerrainGeometryHandle::DynamicFeature, makVrv::DtSwitchTerrainFeature, and DtDynamicTerrainGeometryHandle::DynamicFeature.

virtual bool makVrv::DtDynamicTerrainFeature::matches	(	const DtDynamicTerrainGeometry &	,
		bool	useOriginalGeometry = `false`
	)		const

pure virtual

Implemented in makVrv::DtOsgEarthDynamicTerrainFeature, DtEntityTerrainGeometryHandle::DynamicFeature, makVrv::DtSwitchTerrainFeature, and DtDynamicTerrainGeometryHandle::DynamicFeature.

virtual const DtDynamicTerrainGeometry* makVrv::DtDynamicTerrainFeature::geometry ( ) const

pure virtual

Geometry which represents this feature.

Implemented in makVrv::DtOsgEarthDynamicTerrainFeature, DtEntityTerrainGeometryHandle::DynamicFeature, makVrv::DtSwitchTerrainFeature, and DtDynamicTerrainGeometryHandle::DynamicFeature.

virtual const DtDynamicTerrainGeometry* makVrv::DtDynamicTerrainFeature::originalGeometry ( ) const

virtual

Unprocessed geometry.

Reimplemented in DtEntityTerrainGeometryHandle::DynamicFeature, makVrv::DtSwitchTerrainFeature, and DtDynamicTerrainGeometryHandle::DynamicFeature.

virtual boost::optional<DtString> makVrv::DtDynamicTerrainFeature::featureAttribute ( const DtString & key ) const

virtual

Access attribute values encoded into features.

virtual bool makVrv::DtDynamicTerrainFeature::isInDefaultState ( ) const

pure virtual

Is this feature in it's default (i.e. unchanged) state?

Implemented in makVrv::DtOsgEarthDynamicTerrainFeature, DtEntityTerrainGeometryHandle::DynamicFeature, makVrv::DtSwitchTerrainFeature, and DtDynamicTerrainGeometryHandle::DynamicFeature.

virtual bool makVrv::DtDynamicTerrainFeature::lastStateWasDefaultState ( ) const

pure virtual

Was the previous state the feature was in immediately before the current state the default state?

Implemented in makVrv::DtOsgEarthDynamicTerrainFeature, DtEntityTerrainGeometryHandle::DynamicFeature, makVrv::DtSwitchTerrainFeature, and DtDynamicTerrainGeometryHandle::DynamicFeature.

virtual void makVrv::DtDynamicTerrainFeature::changeState ( const DtDynamicTerrainChanges & history )

pure virtual

Called by the dynamic terrain system in order to notify a feature that it should change its state. The history is an interface into the all of the terrain state changes. This function may be called concurrently from multiple threads.

Parameters

history History interface.

Implemented in makVrv::DtOsgEarthDynamicTerrainFeature, DtEntityTerrainGeometryHandle::DynamicFeature, makVrv::DtSwitchTerrainFeature, and DtDynamicTerrainGeometryHandle::DynamicFeature.

virtual boost::signalslib::connection makVrv::DtDynamicTerrainFeature::connectToChangeSignal ( const ChangeCallback & callback ) const

virtual

Call callback when feature state is changed. Called immediately after changeState is called. This function may be called concurrently from multiple threads.

Parameters

callback function object to be called.

Return values

Connection object which can be used to disconnect the connection.

virtual boost::signalslib::connection makVrv::DtDynamicTerrainFeature::connectToPageOutSignal ( const Callback & callback ) const

virtual

Call callback when feature is removed. The callback will only be called once.

Parameters

callback function object to be called.

Return values

Connection object which can be used to disconnect the connection.

virtual DtString makVrv::DtDynamicTerrainFeature::description ( ) const

pure virtual

Feature description functions Allows feature to describe itself (for a gui mostly). These can all be called from query callbacks. None of the values returned by these functions have any meaning besides informational.

A description of what is in the feature, how it is setup, configuration, etc.

Implemented in makVrv::DtOsgEarthDynamicTerrainFeature, DtEntityTerrainGeometryHandle::DynamicFeature, makVrv::DtSwitchTerrainFeature, and DtDynamicTerrainGeometryHandle::DynamicFeature.

virtual const DtDynamicTerrainFeature* makVrv::DtDynamicTerrainFeature::parentFeature ( ) const

virtual

Feature description functions Allows feature to describe itself (for a gui mostly). These can all be called from query callbacks. None of the values returned by these functions have any meaning besides informational.

A description of what is in the feature, how it is setup, configuration, etc.

Reimplemented in makVrv::DtSwitchTerrainFeature.

virtual void makVrv::DtDynamicTerrainFeature::iterateCommands ( const boost::function< void(const DtDynamicTerrainChange &)> & callback ) const

virtual

Call the supplied callback on commands which represent the commands a feature can respond to.

This function is designed to be called from a query callback. The purpose of this function is supply a gui or other introspective tool with commands to issue (possibly modified) to this feature or to the terrain. A feature should create commands which they could respond to and would cause them to set themselves to the state they are in now. If there is some command a feature can respond to, outputting it in this function will allow a gui to do things like automatically create a menu with all the possibilities. The commands know the types of the attributes they contain, so the gui will know how to edit the values correctly in order to let the user change the commands before they are issued.

Reimplemented in makVrv::DtOsgEarthDynamicTerrainFeature, DtEntityTerrainGeometryHandle::DynamicFeature, and DtDynamicTerrainGeometryHandle::DynamicFeature.

virtual void makVrv::DtDynamicTerrainFeature::iterateCommands	(	const boost::function< void(const DtDynamicTerrainChange &)> &	callback,
		const DtString &	key
	)		const

virtual

Reimplemented in makVrv::DtSwitchTerrainFeature.

void makVrv::DtDynamicTerrainFeature::changed ( )

Calls changeState and all attached query callbacks.

bool makVrv::DtDynamicTerrainFeature::pageOut ( )

Remove all change requests links and remove feature from dynamic terrain world.

Return values

true	if feature was paged out in this call, false otherwise.

void makVrv::DtDynamicTerrainFeature::changes ( const boost::function< void(const DtDynamicTerrainChanges &)> & callback ) const

Calls supplied callback on this features DtDynamicTerrainChanges interface. Use this function to observer the current state of a feature.

RequestHandle makVrv::DtDynamicTerrainFeature::addChangeRequest ( DtDynamicTerrainChange * change )

Add a change request directly to this feature.

RequestHandle makVrv::DtDynamicTerrainFeature::addChangeRequest	(	double	time,
		DtDynamicTerrainChange *	change
	)

void makVrv::DtDynamicTerrainFeature::indexDoubleAscending ( const DtString & key )

protected