Environment Class Reference

#include <Environment.h>

Collaboration diagram for Environment:


Public Member Functions
	Environment (int xSpacing, int zSpacing, int initialXSize, int initialZSize, unsigned environmentId)
virtual	~Environment ()
void	addEntryPoint (gmtl::Vec3f position, gmtl::Vec3f direction)
bool	setTileAtGridPosition (int x, int z, Tile *tile)
Tile *	removeTileAtGridPosition (int x, int z)
unsigned	createEntity (EntityType entType, TransformationData initialTransfInEnv, AbstractEntityCreationCB callback=NULL)
bool	destroyEntity (Entity entity, AbstractEntityDeletionCB callback=NULL)
bool	unregisterEntityCreationCallback (unsigned environmentBasedId)
bool	unregisterEntityDeletionCallback (unsigned environmentBasedId)
void	enlargeEnvironment (int xDirection, int zDirection)
TransformationData	convertWorldToEnvironment (TransformationData worldTransformation)
TransformationData	convertEnvironmentToWorld (TransformationData environmentTransformation)
bool	rayIntersect (gmtl::Vec3f position, gmtl::Vec3f direction, float intDist, Entity *intersectedEntity)
void	setVisible (bool visible)
void	setXPosition (int xPosition)
void	setZPosition (int zPosition)
unsigned short	getId ()
TransformationData	getStartTransformation (unsigned index)
TransformationData	getWorldStartTransformation (unsigned index)
unsigned	getNumberOfStartTransformations ()
int	getXSpacing ()
int	getZSpacing ()
int	getXSize ()
int	getZSize ()
int	getXPosition ()
int	getZPosition ()
TransformationData	getWorldTransformation ()
Tile *	getTileAtGridPosition (int x, int z)
Tile *	getTileAtWorldPosition (float x, float z)
gmtl::Vec3f	getWorldPositionOfTile (Tile *tle)
Entity *	getEntityByEnvironmentBasedId (unsigned envBasedId)
Tile **	getTileGrid ()
const std::vector< Entity * > &	getEntityList ()
void	dump ()
void	dumpTileGrid ()
Public Attributes
SceneGraphAttachment *	sceneGraphAttachment
Private Member Functions
bool	addEntity (Entity *entity)
bool	removeEntity (Entity *entity)
std::string	getGlobalEnvironmentIdPoolName ()
void	setLocalEnvironmentIdPool (IdPool *newlocalPool)
void	updatePosition ()
bool	addNewEntity (Entity *newEntity)
void	removeDeletedEntity (Entity *entity)
unsigned short	getFreeEntityId ()
Private Attributes
unsigned short	environmentId
	ID of the Environment.
TransformationData	envTransformation
	World-Transformation of the Environment.
int	posX
	position and size in spacing-units
int	posZ
int	sizeX
int	sizeZ
int	xSpacing
	minimum size of a tile
int	zSpacing
int	xOffset
	offset information -> used for enlargement or shrink of environment
int	zOffset
std::vector< TransformationData >	entryPoints
	entry points for users in Environment
Tile **	tileGrid
	grid where all Tiles are stored
std::vector< Entity * >	entityList
	list of all Entities positioned inside the Environment
std::map< unsigned short, Entity * >	entityMap
	stores all Entities with EnvironmentBasedID = this->environmentId.xxx
std::map< unsigned, AbstractEntityCreationCB * >	entityCreationCallback
std::map< unsigned, AbstractEntityDeletionCB * >	entityDeletionCallback
SceneGraphInterface *	sgIF
	Pointer to the SceneGraphInterface if existing.
std::string	globalEnvironmentIdPoolName
	name of the globalEnvironmentIdPool
IdPool	globalEnvironmentIdPool
	global IdPool for Environment
IdPool *	localEnvironmentIdPool
	local IdPool for Environment
IdPool *	loadTimeEnvironmentIdPool
	IdPool used at load time.
Friends
class	Entity
class	EntityType
class	SystemCore
class	WorldDatabase
class	WorldDatabaseSyncEvent
class	WorldDatabaseCreateEntityEvent
class	WorldDatabaseDestroyEntityEvent

Constructor & Destructor Documentation

Environment::Environment	(	int	xSpacing,
		int	zSpacing,
		int	initialXSize,
		int	initialZSize,
		unsigned	environmentId
	)

Constructor initializes the Environment. It sets the ID, the spacing and the size of the Environment. It also initializes the Pointer to the SceneGraphInterface and the globalEnvironmentIdPool used for Entity-IDs inside the environment.

Parameters:

	xSpacing	horizontal size of an element in the Tile-grid
	ySpacing	vertical size of an element in the Tile-grid
	initialXSize	initial horizontal size of the Environment in spacing-coordinates
	initialZSize	initial vertical size of the Environment in spacing-coordinates
	environmentId	ID of the Environment

Environment::~Environment ( ) [virtual]

Destructor deletes all Entities and Tiles in the Environment. The destructor removes all Entities from the Environment and also deletes this Entities. It also deletes all Tiles inside the Tile-grid. At last it removes itself from the SceneGraphInterface.

Member Function Documentation

bool Environment::addEntity ( Entity * entity ) [private]

Adds the passed Entity to the Environment. The method can be used to add an already existing Entity to the Environment which was originally created in another Environment. It sets the Environment-pointer of the passed Entity, adds the Entity to the list of local Entities. NOTE: The method does not remove the Entity from another Environment neither correct the Transformation of the passed Entity.

Parameters:

entity

Entity to add to the Environment

Returns:: true if no error occured

void Environment::addEntryPoint	(	gmtl::Vec3f	position,
		gmtl::Vec3f	direction
	)

Adds an entry-point to the Environment. The position has to be passed in environment coordinates. The passed view direction defines the initial orientation of the user when he enters the environment at this point.

Parameters:

	position	position of the entry point in environment coordinates
	direction	view direction for this entry point

bool Environment::addNewEntity ( Entity * newEntity ) [private]

Adds the passed Entity to the Environment. The method can be used to add a new but already created Entity to the Environment. It sets the Environment-pointer of the passed Entity, adds the Entity to the list of local Entities and attaches the Entity to the SceneGraph. NOTE: The method does not remove the Entity from another Environment neither correct the Transformation of the passed Entity. It should only be used to initially add existing Entities to an Environment as it is done by the WorldDatabaseCreateEntityEvent

Parameters:

entity

Entity to add to the Environment

Returns:: true if no error occured

TransformationData Environment::convertEnvironmentToWorld ( TransformationData environmentTransformation )

Converts the passed Transformation from Environment coordinates to world coordinates.

Parameters:

environmentTransformation

Transformation in Environment coordinates

Returns:: passed Transformation in world coordinates

TransformationData Environment::convertWorldToEnvironment ( TransformationData worldTransformation )

Converts the passed Transformation from world coordinates to Environment coordinates.

Parameters:

worldTransformation

Transformation in world coordinates

Returns:: passed Transformation in Environment coordinates

unsigned Environment::createEntity	(	EntityType *	entType,
		TransformationData	initialTransfInEnv,
		AbstractEntityCreationCB *	callback = `NULL`
	)

Creates and adds a new Entity to the Environment. The method creates a new Entity of the passed EntityType and adds it to the Environment. If the new Entity could be added the method sends an WorldDatabaseCreateEntityEvent to all other hosts which adds the new Entity also on this hosts. This method should always be used when a new Entity is added to an Environment.

Parameters:

	entType	EntityType of which a new instance should be created
	initialTransfInEnv	initial Entity-Transformation in Environment- coordinates

Returns:: new Entity in Environment, NULL if an error occured

bool Environment::destroyEntity	(	Entity *	entity,
		AbstractEntityDeletionCB *	callback = `NULL`
	)

Todo:: document

void Environment::dump ( )

Dumps the Environment including the Tile Grid and all entities.

void Environment::dumpTileGrid ( )

Dumps the Tile Grid of the Environment.

void Environment::enlargeEnvironment	(	int	xDirection,
		int	zDirection
	)

Allows to enlarge the Environment. The method enlarges the Tile-Grid of the Environment in both directions according to the passed parameters. The parameters are in spacing-coordinates. If the parameters are negative values then the Environment is enlarged in the negative direction (left or up). If the Environment is enlarged in negative direction then the coordinates of the Tiles in the Environment change so that the Tile in the upper left corner is at Position (0,0). NOTE: The method just enlarges the Environment but does not check if the enlarged environment overlaps with another environment. It also can not adopt Tiles from other Environments.

Parameters:

	xDirection	number of Tiles added in horizontal direction
	zDirection	number of Tiles added in vertical direction

Entity * Environment::getEntityByEnvironmentBasedId ( unsigned envBasedId )

Returns the Entity with the passed environmentBasedId. The method first checks if the Entity is originally created in this Environment. If so it checks if the Entity can be found in the EntityMap. If it is not in the EntityMap the method searches through all Entities which are currently inside the Environment and checks if the passed id matches. If no matching Entity was found the method returns NULL. NOTE: If the method returns an Entity then this Entity must not reside inside this Environment. It could also be that the Entity was originally created in this Environment but has moved to another Environment.

Parameters:

envBasedId

environmentBasedId of the searched Entity

Returns:: Entity with the passed environmentBasedId if it is found in this Environment

const std::vector< Entity * > & Environment::getEntityList ( )

Returns a pointer to the Entity-list. WARNING: the method returns a pointer to the list so every change also changes data in the Environment!!!

Returns:: pointer to Entity-list

unsigned short Environment::getFreeEntityId ( ) [private]

Returns the next a Entity ID in this Environment from the local id pool.

Returns:: free Entity ID

std::string Environment::getGlobalEnvironmentIdPoolName ( ) [private]

Returns the name of the globalEnvironmentIdPool.

Returns:: name of the globalEnvironmentIdPool

unsigned short Environment::getId ( )

Returns the Id of the Environment

Returns:: Id of the Environment

unsigned Environment::getNumberOfStartTransformations ( )

Provides the number of available start transformations.

Returns:: number of start transformations for environment

TransformationData Environment::getStartTransformation ( unsigned index )

Returns the Transformation of the entry point with the passed index. The returned Transformation is in Environment coordinates.

Returns:: Transformation of an entry point in Environment coordinates

Tile * Environment::getTileAtGridPosition	(	int	x,
		int	z
	)

Returns the Tile which is positioned at the passed coordinates. The coordinates are interpreted as coordinates in the Tile Grid.

Parameters:

x,z

position in the Tile Grid

Returns:: Tile which is located at the position of the Tile Grid

Tile * Environment::getTileAtWorldPosition	(	float	x,
		float	z
	)

Returns the Tile which is positioned at the passed world coordinates. It first calculates if the world position lies within the Environment and if so it calculates the matching position in the Tile Grid and returns the Tile positioned there. If the world position is not inside this Environment then the method returns NULL.

Parameters:

x,z

world position of the searched Tile

Returns:: Tile at the world position if in this Environment, NULL otherwise

Tile ** Environment::getTileGrid ( )

Returns a the pointer to the Tile-Grid. WARNING: the method returns the pointer so every change also changes data in the Environment!!!

Returns:: the pointer to the Tile Grid

gmtl::Vec3f Environment::getWorldPositionOfTile ( Tile * tle )

Returns the position of a Tile from the current Environment in world coordinates. It therefore tries to find the Tile in the Tile-Grid and then calculates it's position in world coordinates. If the Tile could not be found in the Tile Grid the method prints a Warning and returns the Vector (0,0,0).

Parameters:

tle

Tile from which the world position is requested

Returns:: world position of the Tile if found, otherwise (0,0,0)

TransformationData Environment::getWorldStartTransformation ( unsigned index )

Returns the Transformation of the entry point with the passed index. The returned Transformation is in World coordinates.

Returns:: Transformation of an entry point in World coordinates

TransformationData Environment::getWorldTransformation ( )

Returns the Transformation of the Environment in world coordinates. The orientation is always the identity rotation, the position is generated out of the horizontal position of the Environment in spacing coordinates multiplied with the horizontal spacing.

Returns:: Transformation of the Environment in world coordinates.

int Environment::getXPosition ( )

Returns the horizontal position of the Environment in the world in spacing coordinates.

Returns:: horizontal position of the Environment in spacing coordinates

int Environment::getXSize ( )

Returns the horizontal size of the Environment in spacing coordinates.

Returns:: horizontal size of the Environment in spacing coordinates

int Environment::getXSpacing ( )

Returns the horizontal spacing. The spacing is the size of one Element in the Tile grid. A Tile always has to have a size which is an integer multiple of the spacing.

Returns:: horizontal spacing of the Tile grid.

int Environment::getZPosition ( )

Returns the vertical position of the Environment in the world in spacing coordinates.

Returns:: vertical position of the Environment in spacing coordinates

int Environment::getZSize ( )

Returns the vertical size of the Environment in spacing coordinates.

Returns:: vertical size of the Environment in spacing coordinates

int Environment::getZSpacing ( )

Returns the vertical spacing. The spacing is the size of one Element in the Tile grid. A Tile always has to have a size which is an integer multiple of the spacing.

Returns:: vertical spacing of the Tile grid.

bool Environment::rayIntersect	(	gmtl::Vec3f	position,
		gmtl::Vec3f	direction,
		float *	intDist,
		Entity **	intersectedEntity
	)

Does a ray intersection test with all Entities in the Environment and returns the Entity which is closest to the passed position and hit by the ray and the distance from the passed position to the Entity. The return value indicates if the ray hit an Entity or not.
Note: coordinates are world-coordinates.

Parameters:

	position	start position of the ray
	direction	direction of the ray
	intDist	pointer where to write the calculated distance to
	intersectedEntity	pointer where to write the resulting Entity to

Returns:: true if an Entity was hit, false otherwise

void Environment::removeDeletedEntity ( Entity * entity ) [private]

Removes an Entity from the EntityMap. The method is called by the destructor of an Entity which unregisters itself from the Environment before it enters the happy hunting ground.

Parameters:

entity

Entity which should be removed.

bool Environment::removeEntity ( Entity * entity ) [private]

Removes an Entity from the Environment. The method removes the passed Entity from the entityList and removes its graphical representation from the SceneGraph. The Entity-object itself is not deleted.

Parameters:

entity

Entity that should be removed from the Environment

Returns:: true if the Entity could be removed

Tile * Environment::removeTileAtGridPosition	(	int	x,
		int	z
	)

Removes a Tile at the passed position. The method removes the Tile-entries in the Tile Grid and removes the graphical representation of the Tile from the SceneGraph. The passed positions arguments are the coordinates of the Tile in the Tile-Grid (in spacing coordinates). The Tile itself is not deleted and returned by the method. NOTE: When calling this method by hand the Tile is only removed in the local copy of the Environment. When a multi-user application is used then be sure to also call this method on all other hosts (e.g. by sending an Event).

Parameters:

x,z

position of the Tile in the Tile-Grid

Returns:: Tile that is removed, NULL if not found

void Environment::setLocalEnvironmentIdPool ( IdPool * newlocalPool ) [private]

Sets the localEnvironmentIdPool.

Parameters:

newlocalPool

pointer to the new localEnvironmentIdPool

bool Environment::setTileAtGridPosition	(	int	x,
		int	z,
		Tile *	tile
	)

Sets the passed Tile to the passed position. The method is called by the WorldDatabase when the Environment is loaded. The passed position is in spacing-coordinates. The method searches for other Tiles in the Tile grid and deletes the passed Tile if it conflicts with another Tile. Otherwise it adds the Tile to the tile-grid and adds the Tile to the tile-grid and adds the Tile to the SceneGraph. NOTE: When calling this method by hand the Tile is only added in the local copy of the Environment. When a multi-user application is used then be sure to also call this method on all other hosts (e.g. by sending an Event).

Parameters:

	x,z	position of the new Tile in the Environment in spacing coord.
	tile	the Tile that sould be entered

Returns:: true, if the Tile could be added

void Environment::setVisible ( bool visible )

Shows or hides the graphical representation of the Environment

Parameters:

visible

true when the environment should be displayed.

void Environment::setXPosition ( int xPosition )

Sets the horizontal position of the Environment in spacing coordinates. The passed position is used as the upper left corner of the Environment. All Tiles and Entities in this Environment are transformed as well. NOTE: Be careful when moving the Environment during runtime to not overlap another Environment!

Parameters:

xPosition

new horizontal position of the Environment

void Environment::setZPosition ( int zPosition )

Sets the vertical position of the Environment in spacing coordinates. The passed position is used as the upper left corner of the Environment. All Tiles and Entities in this Environment are transformed as well. NOTE: Be careful when moving the Environment during runtime to not overlap another Environment!

Parameters:

zPosition

new vertical position of the Environment

bool Environment::unregisterEntityCreationCallback ( unsigned environmentBasedId )

Todo:: document

bool Environment::unregisterEntityDeletionCallback ( unsigned environmentBasedId )

Todo:: document

void Environment::updatePosition ( ) [private]

Updates the Environment Transformation. The method is called when the position of the Environment is changed. It updates the TransformationData which stores the Environment transformation.