makVrv::DtDynamicTerrainWorld Class Reference

Container for dynamic terrain features, change requests, and queries. More...

Inheritance diagram for makVrv::DtDynamicTerrainWorld:

Classes
class	FeatureHandle
	Feature Insertion/Removal/Paging Features represent parts of the terrain which are individually identifiable to the terrain system. More...
class	QueryEndException
	Can be thrown from query callback to remove query. More...
class	QueryHandle
	Queries. More...

Public Member Functions
	DtDynamicTerrainWorld (Config *config=0)
	Default constructor.
virtual	~DtDynamicTerrainWorld ()
	Virtual destructor.
void	setDisabled ()
	Disable the dynamic terrain world.
bool	isDisabled () const
virtual	~Config ()
virtual double	minTileArea () const =0
virtual double	maxTileArea () const =0
virtual FeatureHandle	pageInFeature (const boost::shared_ptr< DtDynamicTerrainFeature > &feature)
	Add a feature to the system.
virtual QueryHandle	queryFeatures (const boost::function< void(const DtDynamicTerrainFeature &)> &callback, DtDynamicTerrainChange *command=0)
	Install a query which will call the supplied callback on matching features as they are paged in.
virtual QueryHandle	queryFeatures (const boost::function< void(const DtDynamicTerrainFeature &)> &callback, DtDynamicTerrainGeometry *geometry)
virtual void	queryCurrentFeatures (const boost::function< void(const DtDynamicTerrainFeature &)> &, DtDynamicTerrainChange *command=0)
virtual void	queryCurrentFeatures (const boost::function< void(const DtDynamicTerrainFeature &)> &, DtDynamicTerrainGeometry *geometry)
Public Member Functions inherited from makVrv::DtVirtualBaseClass
	DtVirtualBaseClass ()
	Do nothing constructor.
virtual	~DtVirtualBaseClass ()
	Virtual do nothing destructor.

Static Public Member Functions
static DtDynamicTerrainWorld &	instance (DtDe &)
	Get rooted singleton from DE.
static void	setInstance (DtDe &de, DtDynamicTerrainWorld *world)
	Set the rooted singleton to a specific object.
static unsigned long long	GetQueryCount ()

Protected Member Functions
virtual QueryHandle	queryFeatures (QueryInfo *query)

Protected Attributes
Impl *	myImpl

Private Member Functions
	DtDynamicTerrainWorld (const DtDynamicTerrainWorld &)
	Non-copyable.
DtDynamicTerrainWorld &	operator= (const DtDynamicTerrainWorld &)
typedef DtDynamicTerrainFeature::RequestHandle	RequestHandle
	Change Requests.
virtual RequestHandle	addChangeRequest (DtDynamicTerrainChange *command)
	Add a change request to the system.
virtual RequestHandle	addChangeRequest (DtDynamicTerrainTimeType time, DtDynamicTerrainChange *command)
	Convenience wrapper around the main addChangeRequest function which adds a time parameter.

Detailed Description

Container for dynamic terrain features, change requests, and queries.

Dynamic terrain features are objects which implement some kind of change that can be made in the terrain. Change requests consist of data (sets of key/value pairs) and geometry and represent some kind of change to the terrain.

When features and change requests are added, the system determines if the change request applies to the features. This is done so that regardless of what order the features and change requests are added in, they will still all be checked against each other. Whether a change request "applies" to a feature is completely up to the implementation of the feature. Features have geometry which must intersect the change request geometry, and then each feature gets a chance to view the request data and decide if it knows how to handle it. If a change request doesn't apply to a feature then they don't interact at all.

All of the change requests that apply to a given feature are collected into an interface and exposed to the feature in DtDynamicTerrainFeature::changeState(). The feature can all of the changes that could possibly have an effect on the feature state and decide what to do given all of the changes (not just the last one). This makes it so the feature does not have to store any state about why it is in a given state, since all the data it needs is presented directly.

In many cases it is necessary to compute data which is easily tracked, but expensive to recompute frequently. A common example is that there may be many change requests which apply to a given feature, but the feature only has a few states and thus cannot use all the change requests available. You could encode a "priority" parameter into the change data and then use the change request with the highest priority. But this requires scanning through all the change requests each time, which is very inefficient. In order to mitigate this, when features are paged in they are given a chance to specify change data keys which will be indexed, and what type and what order to index them on. This will allow features to access these indices in the changeState function.

Queries allow users to ask the system about features which are currently paged in. Queries work just like change requests, but instead of changing the feature state, the features are passed to a user supplied callback.

Member Typedef Documentation

typedef DtDynamicTerrainFeature::RequestHandle makVrv::DtDynamicTerrainWorld::RequestHandle

Change Requests.

Change requests are added to the terrain to cause the contained features to change state depending on the data in the change request. Change requests are composed of three pieces of data:

• A geometry. Used to limit the change request in space.
• A command. Commands are key/value dictionary interfaces which contain all the non-spatial data needed to fulfill the change request. These objects are passed to the features and can include anything that the features objects can parse.

Constructor & Destructor Documentation

makVrv::DtDynamicTerrainWorld::DtDynamicTerrainWorld

(

Config *

config = 0

)

Default constructor.

virtual makVrv::DtDynamicTerrainWorld::~DtDynamicTerrainWorld ( )

virtual

Virtual destructor.

makVrv::DtDynamicTerrainWorld::DtDynamicTerrainWorld ( const DtDynamicTerrainWorld &  )

private

Non-copyable.

virtual makVrv::DtDynamicTerrainWorld::~Config ( )

virtual

Member Function Documentation

static DtDynamicTerrainWorld& makVrv::DtDynamicTerrainWorld::instance ( DtDe &  )

static

Get rooted singleton from DE.

static void makVrv::DtDynamicTerrainWorld::setInstance ( DtDe &  de, DtDynamicTerrainWorld *  world  )

static

Set the rooted singleton to a specific object.

static unsigned long long makVrv::DtDynamicTerrainWorld::GetQueryCount ( )

static

virtual FeatureHandle makVrv::DtDynamicTerrainWorld::pageInFeature ( const boost::shared_ptr< DtDynamicTerrainFeature > &  feature )

virtual

Add a feature to the system.

Assumes ownership of feature object. Feature will be destroyed on page out.

Parameters

feature

Feature to add.

Return values

Handle

object for removing this request.

virtual RequestHandle makVrv::DtDynamicTerrainWorld::addChangeRequest ( DtDynamicTerrainChange *  command )

virtual

Add a change request to the system.

Parameters

command	Command which describes this change. Takes ownership.
geometry	Only change features which match this geometry. Takes ownership.

Return values

Handle

object for removing this request.

virtual RequestHandle makVrv::DtDynamicTerrainWorld::addChangeRequest ( DtDynamicTerrainTimeType  time, DtDynamicTerrainChange *  command  )

virtual

Convenience wrapper around the main addChangeRequest function which adds a time parameter.

Parameters

time	The value of this parameter is added to the change data under the key "terrain_time".

virtual QueryHandle makVrv::DtDynamicTerrainWorld::queryFeatures ( const boost::function< void(const DtDynamicTerrainFeature &)> &  callback, DtDynamicTerrainChange *  command = 0  )

virtual

Install a query which will call the supplied callback on matching features as they are paged in.

Callbacks can then be installed on the feature itself to monitor it for changes and page out. The callback may be called from multiple threads. It is only safe to access the objects supplied to the callback during the execution of the callback.

Parameters

callback	callback object to be called on each feature.
geometry	Only features which match this geometry will be used. Takes ownership.
command	Only features which match this command will be used. Takes ownership.
retval	Handle object for managing this query.

virtual QueryHandle makVrv::DtDynamicTerrainWorld::queryFeatures ( const boost::function< void(const DtDynamicTerrainFeature &)> &  callback, DtDynamicTerrainGeometry *  geometry  )

virtual

virtual void makVrv::DtDynamicTerrainWorld::queryCurrentFeatures ( const boost::function< void(const DtDynamicTerrainFeature &)> &  , DtDynamicTerrainChange *  command = 0  )

virtual

virtual void makVrv::DtDynamicTerrainWorld::queryCurrentFeatures ( const boost::function< void(const DtDynamicTerrainFeature &)> &  , DtDynamicTerrainGeometry *  geometry  )

virtual

void makVrv::DtDynamicTerrainWorld::setDisabled

(

)

Disable the dynamic terrain world.

After this function is called, all features, queries, and change requests will be deleted when added and empty handles will be returned. You cannot reenable the system afterwards as it cannot get itself into a valid state. The purpose of this feature is debugging, to remove as many side effects of the dynamic terrain system as possible.

bool makVrv::DtDynamicTerrainWorld::isDisabled

(

)

const

virtual QueryHandle makVrv::DtDynamicTerrainWorld::queryFeatures ( QueryInfo *  query )

protectedvirtual

DtDynamicTerrainWorld& makVrv::DtDynamicTerrainWorld::operator= ( const DtDynamicTerrainWorld &  )

private

virtual double makVrv::DtDynamicTerrainWorld::minTileArea ( ) const

pure virtual

virtual double makVrv::DtDynamicTerrainWorld::maxTileArea ( ) const

pure virtual

Member Data Documentation

Impl* makVrv::DtDynamicTerrainWorld::myImpl

protected

---

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

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