this is the interface class for managing global terrain used in ParaEngine. More...

#include <GlobalTerrain.h>

Inheritance diagram for ParaTerrain::CGlobalTerrain:

Public Member Functions
virtual int	GetAttributeClassID ()
	attribute class ID should be identical, unless one knows how overriding rules work. More...

virtual const char *	GetAttributeClassName ()
	a static string, describing the attribute class object's name

virtual const char *	GetAttributeClassDescription ()
	a static string, describing the attribute class object

virtual int	InstallFields (CAttributeClass *pClass, bool bOverride)
	this class should be implemented if one wants to add new attribute. More...

virtual IAttributeFields *	GetChildAttributeObject (const std::string &sName)
	get attribute by child object. More...

virtual int	GetChildAttributeObjectCount (int nColumnIndex=0)
	get the number of child objects (row count) in the given column. More...

virtual int	GetChildAttributeColumnCount ()
	we support multi-dimensional child object. More...

virtual IAttributeFields *	GetChildAttributeObject (int nRowIndex, int nColumnIndex=0)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, IsModified_s, bool *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, TerrainRenderingEnabled_s, bool *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, EnableTerrainRendering_s, bool)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, IsTerrainEngineEnabled_s, bool *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, EnableTerrainEngine_s, bool)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, IsVerbose_s, bool *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetVerbose_s, bool)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, IsEditor_s, bool *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetEditor_s, bool)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, GetTessellateMethod_s, int *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetTessellateMethod_s, int)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, UseNormals_s, bool *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetUseNormals_s, bool)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, GetTextureMaskWidth_s, int *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetTextureMaskWidth_s, int)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, GetDefaultHeight_s, float *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetDefaultHeight_s, float)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, IsGeoMipmapTerrain_s, bool *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetGeoMipmapTerrain_s, bool)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, IsEditorMode_s, bool *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetEditorMode_s, bool)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, IsSlopeCollision_s, bool *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetSlopeCollision_s, bool)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetBlockSelectionTexture_s, const char *)

	ATTRIBUTE_METHOD1 (CGlobalTerrain, SetBlockDamageTexture_s, const char *)

IAttributeFields *	GetAttributeObjectAt (float x, float y)
	get the attribute object associated with the terrain tile that contains the given point. More...

bool	IsVerbose ()
	Specifies whether or not Demeter should output diagnostic information at runtime. More...

void	SetVerbose (bool bEnable)

void	SetEditor (bool isEditor)
	This makes memory usage much higher but makes dynamically editing the terrain easier for applications such as terrain editors. More...

bool	IsEditor ()
	brief Indicates whether or not SetEditor(true) has been called.

void	SetTessellateMethod (int method)
	This setting determines which algorithm Demeter uses to simplify terrain blocks. More...

int	GetTessellateMethod ()
	Gets the current tessellation heuristic method.

void	SetUseNormals (bool bUseNormals)
	Turning this option on will make Demeter use more memory and will slow rendering slightly on most hardware. More...

bool	UseNormals ()
	Indicates whether or not normals are on as set by calling SetUseNormals().

void	SetBlockDamageTexture (const char *textureName)
	used to render damaged texture. More...

void	SetBlockSelectionTexture (const char *textureName)
	used to render selection texture. More...

void	Cleanup ()
	clean up the global terrain

void	InitDeviceObjects ()
	this function currently does nothing

void	RestoreDeviceObjects ()

void	DeleteDeviceObjects ()
	must call this function when device is lost.

void	InvalidateDeviceObjects ()
	must call this function when device is invalid.

Settings *	GetSettings ()
	get the settings object to set and get terrain global parameters. More...

void	GetBoundingBox (ParaEngine::CShapeBox *BBox)
	Get the bounding box from the last tessellation result. More...

void	GetBoundingBoxes (vector< ParaEngine::CShapeAABB > &boxes, const Matrix4 *modelView, const ParaEngine::CShapeFrustum &frustum, int nMaxBoxesNum=1024, int nSmallestBoxStride=4)
	Get the bounding boxes for a given view frustum. More...

void	SetCameraPosition (float x, float y)
	Set the camera position, so that terrain tiles around it are automatically loaded. More...

void	Update (bool bForceUpdate=false)
	should be called when the camera moves to re-tessellate the terrain and rebuild the terrain buffer. More...

void	Render ()
	Render last scene assuming that the camera has not moved. More...

float	GetElevation (float x, float y)
	Automatically rebuild the terrain buffer and the render the terrain. More...

DWORD	GetRegionValue (const string &sLayerName, float x, float y)
	get value of a given terrain region layer More...

void	SetVertexElevation (float x, float y, float fHeight)
	Set elevation at the nearest vertex to the specified point. More...

float	GetVertexElevation (float x, float y)
	Returns the height of the vertex closest to the specified point. More...

float	GetLowestVisibleHeight ()
	Get the height of the lowest visible terrain point. More...

float	IntersectRay (float startX, float startY, float startZ, float dirX, float dirY, float dirZ, float &intersectX, float &intersectY, float &intersectZ, float fMaxDistance=999999999.0f)
	This method makes use of the terrain's quad tree to optimize the ray-tracing. More...

void	GetNormal (float x, float y, float &normalX, float &normalY, float &normalZ)
	Returns the surface normal of the terrain at the specified point. More...

void	CreateSingleTerrain (const char sHeightmapfile, float fTerrainSize, float fElevscale, int bSwapvertical, const char sMainTextureFile, const char *sCommonTextureFile, int nMaxBlockSize, float fDetailThreshold)
	Create and set the single tile based global terrain from height map and texture files. More...

void	CreateTerrain (const char *sConfigFileName)
	create a terrain from a configuration file. More...

void	Paint (ParaEngine::TextureEntity *detailTexture, float brushRadius, float brushIntensity, float maxIntensity, bool erase, float x, float y)
	paint on the specified location of the global terrain. More...

void	Flatten (float x, float y, float radius, int flatten_op, float elevation, float factor)
	Flatten the terrain both up and down to the specified elevation, using using the tightness parameter to determine how much the altered points are allowed to deviate from the specified elevation. More...

void	DigCircleFlat (float x, float y, float radius, float fFlatPercentage=0.7f, float factor=0.5f)
	flatten a land centered at x,y, with a specified radius. More...

void	GaussianHill (float x, float y, float radius, float hscale, float standard_deviation=0.1f, float smooth_factor=0.5f)

void	Spherical (float x, float y, float radius, float offset)
	offset in a spherical region More...

void	RadialScale (float x, float y, float scale_factor, float min_dist, float max_dist, float smooth_factor=0.5f, int frequency=1)
	Note: terrain data should be in normalized space with height in the range [0,1]. More...

void	Roughen_Smooth (float x, float y, float radius, bool roughen=false, bool big_grid=false, float factor=0.5f)
	square filter for sharpening and smoothing. More...

void	Ramp (float x1, float y1, float x2, float y2, float radius, float borderpercentage=0.5f, float factor=1.0f)
	create a ramp (inclined slope) from (x1,y1) to (x2,y2). More...

void	AddHeightField (float x, float y, const char *filename, int nSmoothPixels=7)
	Add rectangular height field from file to the current terrain. More...

void	MergeHeightField (float x, float y, const char *filename, int mergeOperation=0, float weight1=1.0, float weight2=1.0, int nSmoothPixels=7)
	merge a rectangular height field from file to the current terrain. More...

void	UpdateHoles (float x, float y)
	Update all holes in the terrain tile that contains the input point. More...

bool	IsHole (float x, float y)
	Whether the terrain contains a hole at the specified location. More...

void	SetHole (float x, float y, bool bIsHold)
	set a new terrain hole at the specified location. More...

string	GetOnloadScript (float x, float y)
	get the on load script which created all objects on this terrain tile which contains the point x,y in global coordinate system

void	SetContentModified (float x, float y, bool bIsModified=true, DWORD dwModifiedBits=16)
	set the content of the terrain modified. More...

void	SetAllLoadedModified (bool bIsModified=true, DWORD dwModifiedBits=16)
	set all loaded terrain tile content modified. More...

string	GetTerrainElevFile (float x, float y)
	get the height map file name for the terrain tile that contains the point (x,y)

void	SaveTerrain (bool bHeightMap, bool bTextures)
	save modified terrain to disk. More...

bool	IsModified ()
	return true, if the terrain is modified and should be saved. More...

void	EnableLighting (bool bEnable)
	Enable both global and local lighting. More...

bool	IsTerrainEngineEnabled () const
	enable/disable global real world terrain engine. More...

void	EnableTerrainEngine (bool val)

bool	TerrainRenderingEnabled ()
	true if terrain is rendered. More...

void	EnableTerrainRendering (bool bEnable)
	specify whether to whether terrain. More...

bool	GetHeightmapOf (float fCenterX, float fCenterY, float fSize, TTerrain *pOut)
	get the height map of a given square region in the global terrain. More...

bool	SetHeightmapOf (float fCenterX, float fCenterY, float fSize, TTerrain *pIn)
	set the height map of a given square region in the global terrain. More...

void	SnapPointToVertexGrid (float x, float y, float vertex_x, float vertex_y)
	snap any 2D point on the height map to a vertex position on the height map. More...

float	GetVertexSpacing () const
	Returns the number of real units between vertices in the terrain's mesh. More...

int	GetTextureCount (float x, float y)
	get the total number of textures in the texture set of the terrain tile specified by a world position (x,y) One can get each of the textures by calling GetTexture() function.

void	GetTexturesInCell (float x, float y, std::vector< int > &indices)
	get all texture indices in the cell specified by point(x,y) GetTextureCount() returns all textures used by the entire terrain tile (i.e. More...

bool	RemoveTextureInCell (float x, float y, int nIndex)
	remove the given texture in the cell specified by the point(x,y). More...

TextureEntity *	GetTexture (float x, float y, int nIndex)
	get the terrain detailed texture by index. More...

bool	ReplaceTexture (float x, float y, int nIndex, TextureEntity *TextureAsset)
	replace the texture at the given index. More...

Terrain *	GetTerrainAtPoint (float x, float y)
	get the terrain at point no matter it is single or latticed. More...

int	GetMaxTileCacheSize ()
	set how many terrain tile(including height fields, etc) are cached in memory. More...

void	SetMaxTileCacheSize (int nNum)
	Get how many terrain tile(including height fields, etc) are cached in memory. More...

void	SetEnablePathEncoding (bool bEnable)
	set whether we will encode terrain related files. More...

bool	GetEnablePathEncoding ()
	get whether we will encode terrain related files. More...

void	SetTextureMaskWidth (int nWidth)
	get the default texture mask file resolution. More...

int	GetTextureMaskWidth ()

void	SwitheTerrainLodStyle (bool useGeoMipmap)

float	GetDefaultHeight () const
	the default terrain height, normally it is 0

void	SetDefaultHeight (float val)

const Vector3 &	GetMatTerrainEye () const

const Vector3 &	GetTerrainRenderOffset () const

void	SetGeoMipmapTerrain (bool enable)

bool	IsGeoMipmapTerrain ()

void	SetEditorMode (bool enable)

bool	IsEditorMode ()

void	SetSlopeCollision (bool enable)

bool	IsSlopeCollision ()

void	SetSlopeMeshVisible (bool)

bool	IsSlopeMeshVisible ()

void	SetWaypointRegionVisible (bool enable)

bool	IsWaypointRegionVisible ()

void	PaintTerrainData (float x, float y, float radius, unsigned int data, unsigned int dataMask, unsigned int bitOffset)

uint32	GetTerrainData (float x, float y, uint32 dataMask, uint8 bitOffset)

void	SetVisibleDataMask (uint32 mask, uint8 bitOffset)

bool	IsWalkable (float x, float y, Vector3 &oNormal) const

Public Member Functions inherited from ParaEngine::IAttributeFields
	ATTRIBUTE_METHOD1 (IAttributeFields, GetName_s, const char **)

	ATTRIBUTE_METHOD1 (IAttributeFields, SetName_s, const char *)

	ATTRIBUTE_METHOD (IAttributeFields, PrintObject_s)

	ATTRIBUTE_METHOD (IAttributeFields, AddRef_s)

	ATTRIBUTE_METHOD1 (IAttributeFields, GetRefCount_s, int *)

	ATTRIBUTE_METHOD1 (IAttributeFields, SetTime_s, int)

	ATTRIBUTE_METHOD1 (IAttributeFields, GetTime_s, int *)

	ATTRIBUTE_METHOD (IAttributeFields, Release_s)

virtual const std::string &	GetIdentifier ()

virtual void	SetIdentifier (const std::string &sID)

virtual void	SetModified (bool bModified)
	set whether any field has been modified. More...

virtual bool	ValidateFields ()
	validate all fields and return true if validation passed. More...

virtual string	GetValidationMessage ()
	get the recent validation message due to the most recent call to ValidateFields()

virtual bool	ResetField (int nFieldID)
	Reset the field to its initial or default value. More...

virtual bool	InvokeEditor (int nFieldID, const std::string &sParameters)
	Invoke an (external) editor for a given field. More...

virtual bool	AddChildAttributeObject (IAttributeFields *pChild, int nRowIndex=-1, int nColumnIndex=0)
	add child object. More...

virtual void *	QueryObjectByName (const std::string &sObjectType)
	convert to object of a given type. More...

virtual void *	QueryObject (int nObjectType)
	convert to object of a given type. More...

virtual int	GetTime ()
	get the current local time in case it is animated in milli seconds frames. More...

virtual void	SetTime (int nTime)

virtual CDynamicAttributeField *	GetDynamicField (const std::string &sName)
	Get a dynamic field with a given name. More...

virtual CDynamicAttributeField *	GetDynamicField (int nIndex)
	Get a dynamic field with a given index. More...

virtual const char *	GetDynamicFieldNameByIndex (int nIndex)
	get field name by index

virtual int	GetDynamicFieldCount ()
	how many dynamic field this object currently have. More...

virtual int	SetDynamicField (const std::string &sName, const CVariable &value)
	set a dynamic field with a given name. More...

virtual int	AddDynamicField (const std::string &sName, ATTRIBUTE_FIELDTYPE dwType)
	add dynamic field and return field index

virtual void	RemoveAllDynamicFields ()
	remove all dynamic fields

virtual int	SaveDynamicFieldsToString (std::string &output)
	save only text dynamic fields to fieldname = value text strings. More...

virtual int	LoadDynamicFieldsFromString (const std::string &input)
	load only text dynamic fields from string More...

CAttributeClass *	GetAttributeClass ()
	get the main attribute class object. More...

void	PrintObject ()
	print the content of this object to a text file at temp/doc/[ClassName].txt. More...

Public Member Functions inherited from ParaEngine::IObject
virtual void	Clone (IObject *obj) const
	Clone the object's contains to a pointer. More...

virtual IObject *	Clone () const
	Clone the object's contains and return a pointer to the newly created object. More...

virtual bool	Equals (const IObject *obj) const
	Compare the object with another object. More...

virtual const IType *	GetType () const

virtual std::string	ToString () const

WeakPtr_type &	GetWeakReference ()
	get weak reference object. More...

virtual int	ProcessObjectEvent (const ObjectEvent &event)
	this function is only used to backward compatibility of ParaObject:AddEvent() function. More...

Public Member Functions inherited from ParaEngine::CRefCounted
void	addref () const
	add reference count of the object. More...

bool	delref () const
	decrease reference count of the object. More...

int	GetRefCount () const
	get the reference count

virtual int	Release ()

CRefCounted *	AddToAutoReleasePool ()
	addref and releases the ownership sometime soon automatically (usually at the end of the current frame). More...

Static Public Attributes
static const float	g_fTerrainInvisibleHeight = FLOAT_POS_INFINITY

Additional Inherited Members
Public Types inherited from ParaEngine::IAttributeFields
typedef ParaEngine::weak_ptr< IObject, IAttributeFields >	WeakPtr_type

Public Types inherited from ParaEngine::IObject
typedef ParaEngine::weak_ptr< IObject >	WeakPtr_type

Static Public Member Functions inherited from ParaEngine::IAttributeFields
static HRESULT	GetAttributeClassID_s (IAttributeFields cls, int p1)

static HRESULT	GetAttributeClassName_s (IAttributeFields cls, const char *p1)

static bool	OpenWithDefaultEditor (const char *sFilename, bool bWaitOnReturn=false)
	Open a given file with the default registered editor in the game engine. More...

Protected Member Functions inherited from ParaEngine::IAttributeFields
virtual CAttributeClass *	CreateAttributeClass ()
	initialize fields

virtual CDynamicAttributesSet *	GetDynamicAttributes (bool bCreateIfNotExist=false)

Protected Attributes inherited from ParaEngine::IObject
WeakPtr_type	m_weak_reference

Protected Attributes inherited from ParaEngine::CRefCounted
int	m_refcount

Detailed Description

this is the interface class for managing global terrain used in ParaEngine.

A global terrain can either be single or latticed. The latter will load terrain as tiles automatically when they are potentially visible. a global terrain's world coordinate (x,y) is defined as below: x>=0, y>=0. A single terrain usually has less than 512*512 vertices and is suitable for terrain size smaller than 2000*2000meters. A latticed terrain has no theoretical upper limit of terrain size. each terrain tile may be 500*500meters(or 128*128 elevation vertices) and there may be any number of tiles. For example, if 64*64 tiles are available on hard disk, then the total terrain size will be 32000*32000 meters Internally, terrain tile is dynamically loaded into a sorted map. So there is a upper limit as for the total number of tiles loaded concurrently. But in most cases, only the 9 tiles around the camera position need to be loaded for rendering. One can specify however tiles should be cached in memory. By default it is set to 16.

Member Function Documentation

§ AddHeightField()

void CGlobalTerrain::AddHeightField	(	float	x,
		float	y,
		const char *	filename,
		int	nSmoothPixels = `7`
	)

Add rectangular height field from file to the current terrain.

Parameters

x	center of the rect in world unit
y	center of the rect in world unit
filename	: the raw elevation or gray scale image file that contains the height field.
nSmoothPixels	the number of pixels to smooth from the edge of the height field. if this is 0, the original height field will be loaded unmodified. if it is greater than 0, the loaded height field will be smoothed for nSmoothPixels from the edge, where the edge is always 0.

§ CreateSingleTerrain()

void CGlobalTerrain::CreateSingleTerrain	(	const char *	sHeightmapfile,
		float	fTerrainSize,
		float	fElevscale,
		int	bSwapvertical,
		const char *	sMainTextureFile,
		const char *	sCommonTextureFile,
		int	nMaxBlockSize,
		float	fDetailThreshold
	)

Create and set the single tile based global terrain from height map and texture files.

this function can be called multiple times, in which cases previously loaded single terrain will be discarded.

Parameters

sHeightmapfile	the height map used to create the terrain. It must be sized to 22...2 pixels for both height and width. so usually it is 10241024, 2048*2048, etc.
fTerrainSize	the actual terrain size in the game
bSwapvertical	if one want to swap the height map data vertically.
sMainTextureFile	texture to be mapped to entire terrain
sCommonTextureFile	texture to be tiles to the entire terrain to add some details.
nMaxBlockSize	When doing LOD with the height map, the max block size must be smaller than this one. This will be (nMaxBlockSize*nMaxBlockSize) sized region on the height map.
fDetailThreshold	we will use a LOD block to approximate the terrain at its location, if the block is smaller than fDetailThreshold pixels when projected to the 2D screen.

§ CreateTerrain()

void CGlobalTerrain::CreateTerrain ( const char * sConfigFileName )

create a terrain from a configuration file.

There are two kind of configuration files. the first line of the configuration file decides which configuration to use.

Configuration file for a single terrain. The file specification can be found at Terrain.h
Configuration file for a lattice based terrain. The file specification can be found at Terrain.h The first line always contains "type = lattice"

create latticed terrain

create single terrain

§ DigCircleFlat()

void CGlobalTerrain::DigCircleFlat	(	float	x,
		float	y,
		float	radius,
		float	fFlatPercentage = `0.7f`,
		float	factor = `0.5f`
	)

flatten a land centered at x,y, with a specified radius.

Algorithm: (1) flatten a circle with radius same as fFlatPercentage*radius (2) smooth the entire region twice.

Parameters

x	center of the circle in world unit
y	center of the circle in world unit
radius	radius of the inner circle in world unit
fFlatPercentage	value is between [0,1]. fFlatPercentage*radius is the actual radius that got flattened.
factor	value is between [0,1]. 1 means fully transformed; 0 means nothing is changed

§ EnableLighting()

void CGlobalTerrain::EnableLighting ( bool bEnable )

Enable both global and local lighting.

Turn off lighting will greatly improve performance, such as on slower computers

§ EnableTerrainRendering()

void CGlobalTerrain::EnableTerrainRendering ( bool bEnable )

specify whether to whether terrain.

Parameters

bEnable

§ Flatten()

void CGlobalTerrain::Flatten	(	float	x,
		float	y,
		float	radius,
		int	flatten_op,
		float	elevation,
		float	factor
	)

Flatten the terrain both up and down to the specified elevation, using using the tightness parameter to determine how much the altered points are allowed to deviate from the specified elevation.

Parameters

x	center of the circle in world unit
y	center of the circle in world unit
radius	radius of the inner circle in world unit
flatten_op	enum FlattenOperation{ Fill_Op=0, //Flatten the terrain up to the specified elevation ShaveTop_Op=1, //Flatten the terrain down to the specified elevation Flatten_Op=2, //Flatten the terrain up and down to the specified elevation };
elevation	the desired height
factor	value is between [0,1]. 1 means fully transformed; 0 means nothing is changed

§ GetAttributeClassID()

virtual int ParaTerrain::CGlobalTerrain::GetAttributeClassID ( )

inlinevirtual

attribute class ID should be identical, unless one knows how overriding rules work.

Reimplemented from ParaEngine::IAttributeFields.

§ GetAttributeObjectAt()

IAttributeFields * CGlobalTerrain::GetAttributeObjectAt	(	float	x,
		float	y
	)

get the attribute object associated with the terrain tile that contains the given point.

Parameters

x	in world unit
y	in world unit

Returns

§ GetBoundingBox()

void CGlobalTerrain::GetBoundingBox ( ParaEngine::CShapeBox * BBox )

Get the bounding box from the last tessellation result.

The returned box is always in world coordinate. please note: the box is bounding box of all smallest boxes in the terrain quads which are in the detailed ranged. The detailed range is usually set 30 meters from current eye position in the ground (xz) plane. This bounding box is usually used as the terrain's shadow receiver's bounding box.

§ GetBoundingBoxes()

void CGlobalTerrain::GetBoundingBoxes	(	vector< ParaEngine::CShapeAABB > &	boxes,
		const Matrix4 *	modelView,
		const ParaEngine::CShapeFrustum &	frustum,
		int	nMaxBoxesNum = `1024`,
		int	nSmallestBoxStride = `4`
	)

Get the bounding boxes for a given view frustum.

The returned boxes are always in world coordinate with render origin applied and transform by modelView

Parameters

boxes	[in\|out]
modelView	if not null, all returned boxes will be transformed by it, before testing with the frustum
frustum	the view frustum to test against.
nMaxBoxesNum	maximum number of boxes returned. Since it internally uses a breadth first traversal of the terrain quad tree, larger boxes will return when there are more boxes in the frustum than nMaxBoxesNum
nSmallestBoxStride	what is the stride size of the smallest boxes returned.

§ GetChildAttributeColumnCount()

int CGlobalTerrain::GetChildAttributeColumnCount ( )

virtual

we support multi-dimensional child object.

by default objects have only one column.

Reimplemented from ParaEngine::IAttributeFields.

§ GetChildAttributeObject()

IAttributeFields * CGlobalTerrain::GetChildAttributeObject ( const std::string & sName )

virtual

get attribute by child object.

used to iterate across the attribute field hierarchy.

Reimplemented from ParaEngine::IAttributeFields.

§ GetChildAttributeObjectCount()

int CGlobalTerrain::GetChildAttributeObjectCount ( int nColumnIndex = 0 )

virtual

get the number of child objects (row count) in the given column.

please note different columns can have different row count.

Reimplemented from ParaEngine::IAttributeFields.

§ GetElevation()

float CGlobalTerrain::GetElevation	(	float	x,
		float	y
	)

Automatically rebuild the terrain buffer and the render the terrain.

Internally it calls Update() and Render(). get elevation at the world position.

§ GetEnablePathEncoding()

bool ParaTerrain::CGlobalTerrain::GetEnablePathEncoding ( )

inline

get whether we will encode terrain related files.

default to true. By enabling path encoding, terrain related files like "worlddir/worldfile.txt" will be saved as "%WORLD%/worldfile.txt", thus even the entire world directory changes, the world files can still be found using path variables. Path encoding needs to be disabled when you are creating a template world.

§ GetHeightmapOf()

bool CGlobalTerrain::GetHeightmapOf	(	float	fCenterX,
		float	fCenterY,
		float	fSize,
		TTerrain *	pOut
	)

get the height map of a given square region in the global terrain.

The resolution of the obtained height map is determined by the pOut parameter.

Parameters

fCenterX	global world position of the center of the square region.
fCenterY	global world position of the center of the square region.
fSize	width or height of the square region.
pOut	[in\|out] the height map is to be filled with height map of the terrain in the specified region.

Returns: true if succeed.

§ GetLowestVisibleHeight()

float CGlobalTerrain::GetLowestVisibleHeight ( )

Get the height of the lowest visible terrain point.

This may be used to render the ocean

§ GetMaxTileCacheSize()

int CGlobalTerrain::GetMaxTileCacheSize ( )

set how many terrain tile(including height fields, etc) are cached in memory.

The actual cached tile number may be smaller or larger than this value, since we ensure that a tile that is very recently used is never removed from cache. the default value is 18. The smallest value is 18, the largest value is 4000

§ GetNormal()

void CGlobalTerrain::GetNormal	(	float	x,
		float	y,
		float &	normalX,
		float &	normalY,
		float &	normalZ
	)

Returns the surface normal of the terrain at the specified point.

Parameters

x	The x location of the point on the Terrain's surface in world units.
y	The y location of the point on the Terrain's surface in world units.
normalX	Gets filled with the surface normal x component
normalY	Gets filled with the surface normal y component
normalZ	Gets filled with the surface normal z component

§ GetRegionValue()

DWORD CGlobalTerrain::GetRegionValue	(	const string &	sLayerName,
		float	x,
		float	y
	)

get value of a given terrain region layer

Parameters

x	The x location of the point on the Terrain's surface in world units.
y	The y location of the point on the Terrain's surface in world units.

§ GetSettings()

Settings * CGlobalTerrain::GetSettings ( )

get the settings object to set and get terrain global parameters.

Such as normal, etc.

§ GetTerrainAtPoint()

Terrain * CGlobalTerrain::GetTerrainAtPoint	(	float	x,
		float	y
	)

get the terrain at point no matter it is single or latticed.

Return NULL if there is no terrain object at the position.

§ GetTexture()

TextureEntity * CGlobalTerrain::GetTexture	(	float	x,
		float	y,
		int	nIndex
	)

get the terrain detailed texture by index.

Please note that each terrain tile contains its own texture set. the total number of textures can be returned by GetTextureCount().

Parameters

nIndex this should be smaller than the total number of textures in the texture set. see GetTextureCount(). there are two reserved negative index for the common and main textures -1: common texture, which is repeated several times over each terrain tile surface. -2: main texture, which is chopped and mapped to the entire terrain surface.

Returns: : The texture entity object is returned. The returned object may be invalid if nIndex is invalid.

§ GetTexturesInCell()

void CGlobalTerrain::GetTexturesInCell	(	float	x,
		float	y,
		std::vector< int > &	indices
	)

get all texture indices in the cell specified by point(x,y) GetTextureCount() returns all textures used by the entire terrain tile (i.e.

500*500). however, each terrain tile is further subdevided into 8*8=64 terrain cell (each cell takes up about 64*64 meters). Alpha channels of a terrain texture is only created on a per cell basis. A single alpha image (128*128) will be created for each used texture in the cell.

Parameters

x	in world unit
y	in world unit
indices	this will be filled with texture indices which are used in the cell.

§ GetVertexElevation()

float CGlobalTerrain::GetVertexElevation	(	float	x,
		float	y
	)

Returns the height of the vertex closest to the specified point.

Parameters

x	The x location of the point on the Terrain's surface in world units.
y	The y location of the point on the Terrain's surface in world units.

Returns

§ GetVertexSpacing()

float CGlobalTerrain::GetVertexSpacing ( ) const

Returns the number of real units between vertices in the terrain's mesh.

§ InstallFields()

int CGlobalTerrain::InstallFields	(	CAttributeClass *	pClass,
		bool	bOverride
	)

virtual

this class should be implemented if one wants to add new attribute.

This function is always called internally.

Reimplemented from ParaEngine::IAttributeFields.

§ IntersectRay()

float CGlobalTerrain::IntersectRay	(	float	startX,
		float	startY,
		float	startZ,
		float	dirX,
		float	dirY,
		float	dirZ,
		float &	intersectX,
		float &	intersectY,
		float &	intersectZ,
		float	fMaxDistance = `999999999.0f`
	)

This method makes use of the terrain's quad tree to optimize the ray-tracing.

If it is latticed terrain, only the 9 tiles around the camera position are used for ray-tracing.

Returns: The distance from the starting point to the intersection. A negative value is returned if the ray misses the Terrain.

Parameters

startX	The starting point of the ray.
startY	The starting point of the ray.
startZ	The starting point of the ray.
dirX	The direction of the ray - this vector should be normalized.
dirY	The direction of the ray - this vector should be normalized.
dirZ	The direction of the ray - this vector should be normalized.
intersectX	Filled with the intersection point of this ray with the Terrain surface.
intersectY	Filled with the intersection point of this ray with the Terrain surface.
intersectZ	Filled with the intersection point of this ray with the Terrain surface.
fMaxDistance	if negative it means the ray length is infinity. otherwise it means ray length.

if terrain object is created, just return the intersection with the y=0 plane

§ IsHole()

bool CGlobalTerrain::IsHole	(	float	x,
		float	y
	)

Whether the terrain contains a hole at the specified location.

Currently, we allow user to load a low resolution hole maps at the beginning of terrain creation.

Parameters

x	The x location of the point on the Terrain's surface in world units.
y	The y location of the point on the Terrain's surface in world units.

Returns: : true if the position specified by (x,y) is inside a terrain hole

§ IsModified()

bool CGlobalTerrain::IsModified ( )

virtual

return true, if the terrain is modified and should be saved.

Reimplemented from ParaEngine::IAttributeFields.

§ IsTerrainEngineEnabled()

bool CGlobalTerrain::IsTerrainEngineEnabled ( ) const

enable/disable global real world terrain engine.

If disabled CreateTerrain does not take effect.

§ IsVerbose()

bool CGlobalTerrain::IsVerbose ( )

Specifies whether or not Demeter should output diagnostic information at runtime.

§ MergeHeightField()

void CGlobalTerrain::MergeHeightField	(	float	x,
		float	y,
		const char *	filename,
		int	mergeOperation = `0`,
		float	weight1 = `1.0`,
		float	weight2 = `1.0`,
		int	nSmoothPixels = `7`
	)

merge a rectangular height field from file to the current terrain.

Parameters

x	center of the rect in world unit
y	center of the rect in world unit
filename	: the raw elevation or gray scale image file that contains the height field.
MergeOperation	{ Addition=0, Subtract=1, Multiplication=2, Division=3, Minimum=4, Maximum=5, };
weight1	the destination merging weight
weight2	the source file merging weight
nSmoothPixels	the number of pixels to smooth from the edge of the height field. if this is 0, the original height field will be loaded unmodified. if it is greater than 0, the loaded height field will be smoothed for nSmoothPixels from the edge, where the edge is always 0.

§ Paint()

void CGlobalTerrain::Paint	(	ParaEngine::TextureEntity *	detailTexture,
		float	brushRadius,
		float	brushIntensity,
		float	maxIntensity,
		bool	erase,
		float	x,
		float	y
	)

paint on the specified location of the global terrain.

Parameters

detailTexture	the texture entity to paint on the terrain. The texture is usually tilable such as road and grass. if this is NULL, it means the base layer or layer 0. Since version 0.9.9, the base layer also has an editable alpha mask .
brushRadius	The width of the brush to paint with in DetailTexture layer pixels. There are typically 256 of these pixels across a TextureCell.
brushIntensity	The intensity with which to paint, ranging from 0.0 to 1.0. This determines how opaque the painted "splat" will be.
maxIntensity	The maximum intensity of the painted splat, ranging from 0.0 to 1.0, accounting for mixing with a splat that may already reside on the surface.
erase	Specifies whether to add the splat to the surface or remove existing splat texels already on the surface (pass false to paint and pass true to erase existing splats)
x	The x location of the point to paint on the Terrain's surface in world units.
y	The y location of the point to paint on the Terrain's surface in world units.

§ RadialScale()

void CGlobalTerrain::RadialScale	(	float	x,
		float	y,
		float	scale_factor,
		float	min_dist,
		float	max_dist,
		float	smooth_factor = `0.5f`,
		int	frequency = `1`
	)

Note: terrain data should be in normalized space with height in the range [0,1].

Picks a point and scales the surrounding terrain in a circular manner. Can be used to make all sorts of circular shapes. Still needs some work. radial_scale: pick a point (center_x, center_y) and scale the points where distance is mindist<=distance<=maxdist linearly. The formula we'll use for a nice sloping smoothing factor is (-cos(x*3)/2)+0.5.

Parameters

x	center of the circle in world unit
y	center of the circle in world unit
scale_factor	height of the scaled portion in world unit. This value can be negative.

§ Ramp()

void CGlobalTerrain::Ramp	(	float	x1,
		float	y1,
		float	x2,
		float	y2,
		float	radius,
		float	borderpercentage = `0.5f`,
		float	factor = `1.0f`
	)

create a ramp (inclined slope) from (x1,y1) to (x2,y2).

The ramp's half width is radius. this is usually used to created a slope path connecting a high land with a low land.

Parameters

radius	The ramp's half width
borderpercentage	borderpercentage*radius is how long the ramp boarder is to linearly interpolate with the original terrain. specify 0 for sharp ramp border.
factor	in range[0,1]. it is the smoothness to merge with other border heights.Specify 1.0 for a complete merge

§ RemoveTextureInCell()

bool CGlobalTerrain::RemoveTextureInCell	(	float	x,
		float	y,
		int	nIndex
	)

remove the given texture in the cell specified by the point(x,y).

Parameters

x	in world unit
y	in world unit
nIndex	Texture index in the current terrain tile. this should be smaller than the total number of textures in the texture set. see GetTextureCount().

§ Render()

void CGlobalTerrain::Render ( void )

Render last scene assuming that the camera has not moved.

§ ReplaceTexture()

bool CGlobalTerrain::ReplaceTexture	(	float	x,
		float	y,
		int	nIndex,
		TextureEntity *	TextureAsset
	)

replace the texture at the given index.

Parameters

nIndex this should be smaller than the total number of textures in the texture set. see GetTextureCount(). there are two reserved negative index for the common and main textures -1: common texture, which is repeated several times over each terrain tile surface. -2: main texture, which is chopped and mapped to the entire terrain surface.

§ Roughen_Smooth()

void CGlobalTerrain::Roughen_Smooth	(	float	x,
		float	y,
		float	radius,
		bool	roughen = `false`,
		bool	big_grid = `false`,
		float	factor = `0.5f`
	)

square filter for sharpening and smoothing.

Use neighbour-averaging to roughen or smooth the height field. The factor determines how much of the computed roughening is actually applied to the height field. In it's default invocation, the 4 directly neighboring squares are used to calculate the roughening. If you select big sampling grid, all 8 neighboring cells will be used.

Parameters

x	center of the circle in world unit
y	center of the circle in world unit
radius	radius of the inner circle in world unit
roughen	true for sharpening, false for smoothing.
big_grid	true for 8 neighboring cells, false for 4.
factor	value is between [0,1]. 1 means fully transformed; 0 means nothing is changed

§ SaveTerrain()

void CGlobalTerrain::SaveTerrain	(	bool	bHeightMap,
		bool	bTextures
	)

save modified terrain to disk.

Parameters

bHeightMap	true to save height map
bTextures	true to save textures: alpha maps, etc

§ SetAllLoadedModified()

void CGlobalTerrain::SetAllLoadedModified	(	bool	bIsModified = `true`,
		DWORD	dwModifiedBits = `16`
	)

set all loaded terrain tile content modified.

§ SetBlockDamageTexture()

void CGlobalTerrain::SetBlockDamageTexture ( const char * textureName )

used to render damaged texture.

It is layer on top of block texture

§ SetBlockSelectionTexture()

void CGlobalTerrain::SetBlockSelectionTexture ( const char * textureName )

used to render selection texture.

It is layer on top of block texture

§ SetCameraPosition()

void CGlobalTerrain::SetCameraPosition	(	float	x,
		float	y
	)

Set the camera position, so that terrain tiles around it are automatically loaded.

It is only useful for latticed terrain.

§ SetContentModified()

void CGlobalTerrain::SetContentModified	(	float	x,
		float	y,
		bool	bIsModified = `true`,
		DWORD	dwModifiedBits = `16`
	)

set the content of the terrain modified.

the terrain is specified by a 2D point. the on load script will be rebuilt once saving the terrain.

Parameters

x,y	save all loaded content modified.
bIsModified	true to set modified.
dwModifiedBits	this is any combination of TERRAIN_MODIFIED_BITS. Default value is MODIFIED_ON_LOAD_SCRIPT enum TERRAIN_MODIFIED_BITS { MODIFIED_NONE = 0, detailed terrain texture(with mask) has been modified. MODIFIED_TEXTURE = 0x1, height map has modified MODIFIED_HEIGHTMAP = 0x1<<1, configuration such as base texture, common file, holes, etc has been modified. MODIFIED_CONFIGURATION = 0x1<<2, holes have been changed. this should mean the same thing as MODIFIED_CONFIGURATION MODIFIED_HOLES = 0x1<<3, if static objects have been modified, so that we will need to update the on load script MODIFIED_ON_LOAD_SCRIPT = 0x1<<4, MODIFIED_ALL = 0xffff };

§ SetEditor()

void CGlobalTerrain::SetEditor ( bool isEditor )

This makes memory usage much higher but makes dynamically editing the terrain easier for applications such as terrain editors.

§ SetEnablePathEncoding()

void ParaTerrain::CGlobalTerrain::SetEnablePathEncoding ( bool bEnable )

inline

set whether we will encode terrain related files.

default to true. By enabling path encoding, terrain related files like "worlddir/worldfile.txt" will be saved as "%WORLD%/worldfile.txt", thus even the entire world directory changes, the world files can still be found using path variables. Path encoding needs to be disabled when you are creating a template world.

§ SetHeightmapOf()

bool CGlobalTerrain::SetHeightmapOf	(	float	fCenterX,
		float	fCenterY,
		float	fSize,
		TTerrain *	pIn
	)

set the height map of a given square region in the global terrain.

Note: : the center location will be aligned to the closest terrain vertex before the height map is applied. hence it is good practice to call SnapToTerrainVertex() and only use the exact vertex position as the center.

Parameters

fCenterX	global world position of the center of the square region.
fCenterY	global world position of the center of the square region.
fSize	width or height of the square region.
pIn	[in] the height map is to be filled with height map of the terrain in the specified region.

Returns: true if succeed.

§ SetHole()

void CGlobalTerrain::SetHole	(	float	x,
		float	y,
		bool	bIsHold
	)

set a new terrain hole at the specified location.

Currently, we will allow user to dynamically dig holes in terrain. After calling this function, the user must manually Call UpdateHoles() to inform that the holes in the terrain has been updated.

Parameters

x	The x location of the point on the Terrain's surface in world units.
y	The y location of the point on the Terrain's surface in world units.

See also: UpdateHoles();

§ SetMaxTileCacheSize()

void CGlobalTerrain::SetMaxTileCacheSize ( int nNum )

Get how many terrain tile(including height fields, etc) are cached in memory.

The actual cached tile number may be smaller or larger than this value, since we ensure that a tile that is very recently used is never removed from cache. the default value is 18. The smallest value is 18, the largest value is 4000

§ SetTessellateMethod()

void CGlobalTerrain::SetTessellateMethod ( int method )

This setting determines which algorithm Demeter uses to simplify terrain blocks.

Some settings are faster but less general and vice versa. The default setting is TM_NEW.

§ SetTextureMaskWidth()

void CGlobalTerrain::SetTextureMaskWidth ( int nWidth )

get the default texture mask file resolution.

Although the low level implementation allows us to special a different resolution per cell and per detail texture. this is the only exposed API to change the default mask resolution. Default to 128. the larger, the more details, yet also increases file size of *.mask file. 256, 126, 64 are all reasonable values.

§ SetUseNormals()

void CGlobalTerrain::SetUseNormals ( bool bUseNormals )

Turning this option on will make Demeter use more memory and will slow rendering slightly on most hardware.

You will definitely need to turn this setting on if you want to use lighting on your Terrain objects instead of "baking" lighting into the terrain textures.

§ SetVertexElevation()

void CGlobalTerrain::SetVertexElevation	(	float	x,
		float	y,
		float	fHeight
	)

Set elevation at the nearest vertex to the specified point.

Parameters

x	world x coordinate
y	world y coordinate
fHeight	absolute height

§ SnapPointToVertexGrid()

void CGlobalTerrain::SnapPointToVertexGrid	(	float	x,
		float	y,
		float *	vertex_x,
		float *	vertex_y
	)

snap any 2D point on the height map to a vertex position on the height map.

Parameters

x	arbitrary 2D point on the height map
y	arbitrary 2D point on the height map
vertex_x	[out] vertex position on the height map
vertex_y	[out] vertex position on the height map

§ Spherical()

void CGlobalTerrain::Spherical	(	float	x,
		float	y,
		float	radius,
		float	offset
	)

offset in a spherical region

Parameters

x	center of the circle in world unit
y	center of the circle in world unit
radius	radius of the inner circle in world unit

§ TerrainRenderingEnabled()

bool CGlobalTerrain::TerrainRenderingEnabled ( )

true if terrain is rendered.

Returns

§ Update()

void CGlobalTerrain::Update ( bool bForceUpdate = false )

should be called when the camera moves to re-tessellate the terrain and rebuild the terrain buffer.

However, if RenderAuto() is called. There is no need to call this function.

Parameters

bForceUpdate if true, the terrain will be re-tessellate even if the camera is not moved.

§ UpdateHoles()

void CGlobalTerrain::UpdateHoles	(	float	x,
		float	y
	)

Update all holes in the terrain tile that contains the input point.

Parameters

x	The x location of the point on the Terrain's surface in world units.
y	The y location of the point on the Terrain's surface in world units.

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

Client/trunk/ParaEngineClient/terrain/GlobalTerrain.h
Client/trunk/ParaEngineClient/terrain/GlobalTerrain.cpp

Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

§ AddHeightField()

§ CreateSingleTerrain()

§ CreateTerrain()

§ DigCircleFlat()

§ EnableLighting()

§ EnableTerrainRendering()

§ Flatten()

§ GetAttributeClassID()

§ GetAttributeObjectAt()

§ GetBoundingBox()

§ GetBoundingBoxes()

§ GetChildAttributeColumnCount()

§ GetChildAttributeObject()

§ GetChildAttributeObjectCount()

§ GetElevation()

§ GetEnablePathEncoding()

§ GetHeightmapOf()

§ GetLowestVisibleHeight()

§ GetMaxTileCacheSize()

§ GetNormal()

§ GetRegionValue()

§ GetSettings()

§ GetTerrainAtPoint()

§ GetTexture()

§ GetTexturesInCell()

§ GetVertexElevation()

§ GetVertexSpacing()

§ InstallFields()

§ IntersectRay()

§ IsHole()

§ IsModified()

§ IsTerrainEngineEnabled()

§ IsVerbose()

§ MergeHeightField()

§ Paint()

§ RadialScale()

§ Ramp()

§ RemoveTextureInCell()

§ Render()

§ ReplaceTexture()

§ Roughen_Smooth()

§ SaveTerrain()

§ SetAllLoadedModified()

§ SetBlockDamageTexture()

§ SetBlockSelectionTexture()

§ SetCameraPosition()

§ SetContentModified()

§ SetEditor()

§ SetEnablePathEncoding()

§ SetHeightmapOf()

§ SetHole()

§ SetMaxTileCacheSize()

§ SetTessellateMethod()

§ SetTextureMaskWidth()

§ SetUseNormals()

§ SetVertexElevation()

§ SnapPointToVertexGrid()

§ Spherical()

§ TerrainRenderingEnabled()

§ Update()

§ UpdateHoles()