Description

A PageLoader-derived object you can use with PagedGeometry to easily place trees on your terrain.

Note: TreeLoader2D is derived from PageLoader - this implementation provides you with an easy way to add trees to your scene. Remember that if the included PageLoader's aren't enough, you can easily create your own to load geometry any way you want. You could even modify existing an PageLoader to suit your needs.

Using a TreeLoader is simple - simply create an instance, attach it to your PagedGeometry object with PagedGeometry::setPageLoader(), and add your trees.

To add trees, just call TreeLoader2D::addTree(), supplying the appropriate parameters. You may notice that TreeLoader2D restricts trees to uniform scale, yaw rotation, and a position value with no vertical component. This is done to conserve memory; TreeLoader2D packs trees into memory as effeciently as possible, taking only 6 bytes per tree. This means 1 million trees only takes 5.72 MB of RAM (additionally, adding 1 million trees takes less than a second in a release build).

Note: By default, TreeLoader2D doesn't know what shape your terrain is, so all trees will be placed at 0 height. To inform TreeLoader2D of the shape of your terrain, you must specify a height function that returns the height (vertical coordinate) of your terrain at the given coordinates. See the TreeLoader2D::setHeightFunction() documentation for more information.

Warning: If you attempt to use Ogre's scene queries to get the terrain height, keep in mind that calculating the height of Ogre's built-in terrain this way can be VERY slow if not done properly, and may cause stuttering due to long paging delays.

If the inability to supply a vertical coordinate to addTree() is too limiting, or you are unable to implement a fast enough height function, please refer to TreeLoader3D. TreeLoader3D allows you to provide full 3D x/y/z coordinates, although 40% more memory is required per tree.

Definition at line 51 of file TreeLoader2D.h.

Inheritance diagram for Forests::TreeLoader2D:

Data Structures
struct	TreeDef

Public Member Functions
	TreeLoader2D (PagedGeometry *geom, const TBounds &bounds)

	~TreeLoader2D ()

void	addTree (Ogre::Entity entity, const Ogre::Vector3 &position, Ogre::Degree yaw=Ogre::Degree(0), Ogre::Real scale=1.0f, void userData=NULL)

void	deleteTrees (const Ogre::Vector3 &position, Ogre::Real radius=0.001f, Ogre::Entity *type=NULL)

void	deleteTrees (TBounds area, Ogre::Entity *type=NULL)

void	setHeightFunction (Ogre::Real(heightFunction)(Ogre::Real x, Ogre::Real z, void userData), void *userData=NULL)

void	setColorMap (const Ogre::String &mapFile, MapChannel channel=CHANNEL_COLOR)

void	setColorMap (Ogre::TexturePtr map, MapChannel channel=CHANNEL_COLOR)

ColorMap *	getColorMap ()

void	setColorMapFilter (MapFilter filter)

void	setMaximumScale (Ogre::Real maxScale)

Ogre::Real	getMaximumScale () const

void	setMinimumScale (Ogre::Real minScale)

Ogre::Real	getMinimumScale () const

const TBounds &	getBounds () const

void	loadPage (PageInfo &page)

Public Member Functions inherited from Forests::PageLoader
virtual void	unloadPage (PageInfo &page)

virtual void	frameUpdate ()

virtual	~PageLoader ()

Private Types
typedef std::map< Ogre::Entity , std::vector< TreeDef > >::iterator	PageGridListIterator

typedef std::pair< Ogre::Entity , std::vector< TreeDef > >	PageGridListValue

Private Member Functions
std::vector< TreeDef > &	_getGridPage (std::vector< TreeDef > *grid, int x, int z)

void	_setGridPage (std::vector< TreeDef > *grid, int x, int z, const std::vector< TreeDef > &page)

Private Attributes
int	pageGridX

int	pageGridZ

Ogre::Real	pageSize

TBounds	gridBounds

TBounds	actualBounds

Ogre::Real	maximumScale

Ogre::Real	minimumScale

ColorMap *	colorMap

MapFilter	colorMapFilter

Ogre::Real(*	heightFunction )(Ogre::Real x, Ogre::Real z, void *userData)

void *	heightFunctionUserData

PagedGeometry *	geom

std::map< Ogre::Entity , std::vector< TreeDef > >	pageGridList

Additional Inherited Members
Protected Member Functions inherited from Forests::PageLoader
void	addEntity (Ogre::Entity *ent, const Ogre::Vector3 &position, const Ogre::Quaternion &rotation, const Ogre::Vector3 &scale=Ogre::Vector3::UNIT_SCALE, const Ogre::ColourValue &color=Ogre::ColourValue::White)

Member Typedef Documentation

◆ PageGridListIterator

typedef std::map<Ogre::Entity*,std::vector<TreeDef>*>::iterator Forests::TreeLoader2D::PageGridListIterator

private

Definition at line 261 of file TreeLoader2D.h.

◆ PageGridListValue

typedef std::pair<Ogre::Entity*, std::vector<TreeDef>*> Forests::TreeLoader2D::PageGridListValue

private

Definition at line 262 of file TreeLoader2D.h.

Constructor & Destructor Documentation

◆ TreeLoader2D()

Forests::TreeLoader2D::TreeLoader2D	(	PagedGeometry *	geom,
		const TBounds &	bounds
	)

Creates a new TreeLoader2D object.

Parameters

geom	The PagedGeometry object that this TreeLoader2D will be assigned to.
bounds	The rectangular boundary in which all trees will be placed.

Definition at line 26 of file TreeLoader2D.cpp.

◆ ~TreeLoader2D()

Forests::TreeLoader2D::~TreeLoader2D ( )

Definition at line 57 of file TreeLoader2D.cpp.

Member Function Documentation

◆ _getGridPage()

std::vector< TreeDef > & Forests::TreeLoader2D::_getGridPage	(	std::vector< TreeDef > *	grid,
		int	x,
		int	z
	)

inlineprivate

Definition at line 264 of file TreeLoader2D.h.

◆ _setGridPage()

void Forests::TreeLoader2D::_setGridPage	(	std::vector< TreeDef > *	grid,
		int	x,
		int	z,
		const std::vector< TreeDef > &	page
	)

inlineprivate

Definition at line 276 of file TreeLoader2D.h.

◆ addTree()

void Forests::TreeLoader2D::addTree	(	Ogre::Entity *	entity,
		const Ogre::Vector3 &	position,
		Ogre::Degree	yaw = `Ogre::Degree(0)`,
		Ogre::Real	scale = `1.0f`,
		void *	userData = `NULL`
	)

Adds an entity to the scene with the specified location, rotation, and scale.

Parameters

entity	The entity to be added to the scene.
position	The desired position of the tree
yaw	The desired rotation around the vertical axis in degrees
scale	The desired scale of the entity

Trees added with TreeLoader2D are restricted to yaw rotation only, and uniform scale values. This conserves memory by avoiding storage of useless data (for example, storing the height of each tree when this can be easily calculated from the terrain's shape).

Unlike TreeLoader3D, the vertical position of each tree is NOT stored (therefore TreeLoader2D takes less memory than TreeLoader3D), but this means you must provide a height function with setHeightFunction() in order for TreeLoader2D to be able to calculate the desired height values when the time comes. If you do not specify a height function, all trees will appear at 0 height.

Warning: By default, scale values may not exceed 2.0. If you need to use higher scale values than 2.0, use setMaximumScale() to reconfigure the maximum.

Definition at line 67 of file TreeLoader2D.cpp.

◆ deleteTrees() [1/2]

void Forests::TreeLoader2D::deleteTrees	(	const Ogre::Vector3 &	position,
		Ogre::Real	radius = `0.001f`,
		Ogre::Entity *	type = `NULL`
	)

Deletes trees within a certain radius of the given coordinates.

Parameters

position	The coordinate of the tree(s) to delete
radius	The radius from the given coordinate where trees will be deleted
type	The type of tree to delete (optional)

Note: If the "type" parameter is set to an entity, only trees created with that entity will be deleted.

◆ deleteTrees() [2/2]

void Forests::TreeLoader2D::deleteTrees	(	TBounds	area,
		Ogre::Entity *	type = `NULL`
	)

Deletes trees within a certain rectangular area.

Parameters

area	The area where trees are to be deleted
type	The type of tree to delete (optional)

Note: If the "type" parameter is set to an entity, only trees created with that entity will be deleted.

Definition at line 213 of file TreeLoader2D.cpp.

◆ getBounds()

const TBounds & Forests::TreeLoader2D::getBounds ( ) const

inline

Gets the tree boundary area.

Returns: A TBounds boundary value

This function returns the boundaries in which all trees are added. This value is set from the constructor.

Definition at line 227 of file TreeLoader2D.h.

◆ getColorMap()

ColorMap * Forests::TreeLoader2D::getColorMap ( )

inline

Gets a pointer to the color map being used.

You can use this function to access the internal color map object used by the TreeLoader2D. Through this object you can directly manipulate the pixels of the color map, among other things.

Note that although you can edit the color map in real-time through this class, the changes won't be uploaded to your video card until you call PagedGeometry::reloadGeometry(). If you don't, the colors of the trees you see will remain unchanged.

Definition at line 169 of file TreeLoader2D.h.

◆ getMaximumScale()

Ogre::Real Forests::TreeLoader2D::getMaximumScale ( ) const

inline

Gets the maximum tree scale value.

Returns: The maximum tree scale value

This function will return the maximum tree scale value as set by setMaximumScale(). By default this value will be 2.0.

Definition at line 203 of file TreeLoader2D.h.

◆ getMinimumScale()

Ogre::Real Forests::TreeLoader2D::getMinimumScale ( ) const

inline

Gets the minimum tree scale value.

Returns: The minimum tree scale value

This function will return the minimum tree scale value as set by setMinimumScale(). By default this value will be 0.

Definition at line 221 of file TreeLoader2D.h.

◆ loadPage()

void Forests::TreeLoader2D::loadPage ( PageInfo & page )

virtual

This should be overridden to load a specified region of entities.

Parameters

page	A PageInfo variable which includes boundary information and other useful values.

Override this function to load entities within the specified boundary. The boundary information is contained in the "page" parameter, along with other useful information as well (see the PageInfo documentation for more info about this).

Simply use the member function addEntity() to add all the entities you want. If you create your own objects inside this function, you are responsible for deleting it appropriately in unloadPage() or somewhere else. The PageInfo::userData member is useful here since you can point it to your data structures for later reference in unloadPage().

Warning: Do not ever add an entity outside of the given region, otherwise this may crash the program (depending on how the current page types handle this situation).

See also: PagedGeometry::addDetailLevel() for information about page types.

Implements Forests::PageLoader.

Definition at line 309 of file TreeLoader2D.cpp.

◆ setColorMap() [1/2]

void Forests::TreeLoader2D::setColorMap	(	const Ogre::String &	mapFile,
		MapChannel	channel = `CHANNEL_COLOR`
	)

Sets the color map used to color trees.

Parameters

mapFile	The color map image
channel	The color channel(s) to from the image to use

A color map is simply a texture that allows you to vary the color and shading of trees across your world for a more realistic look. For example, adding a dark spot to the center of your color map will make trees near the center of your world look darker.

The channel parameter allows you to extract the color information from the image's red, green, blue, alpha, or color values. For example, you may store the desired shade of your trees in the red channel of an image, in which case you would use CHANNEL_RED (when you choose a single channel, it is converted to a greyscale color). By default, CHANNEL_COLOR is used, which uses the full color information available in the image.

Definition at line 285 of file TreeLoader2D.cpp.

◆ setColorMap() [2/2]

void Forests::TreeLoader2D::setColorMap	(	Ogre::TexturePtr	map,
		MapChannel	channel = `CHANNEL_COLOR`
	)

Sets the color map used to color trees.

Overloaded to accept a Texture object. See the original setColorMap() documentation above for more detailed information on color maps.

Note: The texture data you provide is copied into RAM, so you can delete the texture after calling this function without risk of crashing.

Definition at line 297 of file TreeLoader2D.cpp.

◆ setColorMapFilter()

void Forests::TreeLoader2D::setColorMapFilter ( MapFilter filter )

inline

Sets the filtering mode used for the color map.

This function can be used to set the filtering mode used for your tree color map. By default, no filtering is used (MAPFILTER_NONE). If you enable bilinear filtering by using MAPFILTER_BILINEAR, the resulting tree coloration may appear more smooth (less pixelated), depending on the resolution of your color map.

MAPFILTER_BILINEAR is slightly slowe than MAPFILTER_NONE, so don't use it unless you notice considerable pixelation.

Definition at line 180 of file TreeLoader2D.h.

◆ setHeightFunction()

void Forests::TreeLoader2D::setHeightFunction	(	Ogre::Real()(Ogre::Real x, Ogre::Real z, void userData)	heightFunction,
		void *	userData = `NULL`
	)

inline

Sets the height function used to calculate tree height coordinates.

Parameters

heightFunction	A pointer to a height function
userData	Optional user data to be supplied to the height function

Unless you want all your trees placed at 0 height, you need to specify a height function so TreeLoader2D will be able to calculate the height coordinate. The height function given to setHeightFunction() should use the following prototype (although you can name the function anything you want):

Real getHeightAt(Real x, Real z, void *userData);

x

float x

Definition (ValueTypes) quaternion.h:3

z

float z

Definition (ValueTypes) quaternion.h:5

Note: If you're not using the default coordinate system (where x = right, z = back), the x/z parameters will actually be representing the appropriate equivalents.

The userData parameter allows you to include any additional data you want when your height function is called, and is completely optional (although you can't actually omit it from the declaration, you can ignore it). Any userData value you choose to supply to setHeightFunction() will be passed on to your height function every time it is called.

After you've defined a height function, using setHeightFunction is easy:

pageLoader2D->setHeightFunction(&getHeightAt);
//Or (if you want to pass additional data on to your height function)...
pageLoader2D->setHeightFunction(&getHeightAt, myUserData);

In most cases, you may not even need to use the extra "userData" parameter, but it's there in the event that your height function needs extra contextual data.

Definition at line 130 of file TreeLoader2D.h.

◆ setMaximumScale()

void Forests::TreeLoader2D::setMaximumScale ( Ogre::Real maxScale )

inline

Sets the maximum tree scale value.

When calling addTree() to add trees, the scale values you are allowed to use are restricted to 2.0 maximum by default. With this function, you can adjust the maximum scale you are allowed to use for trees. However, keep in mind that the higher the maximum scale is, the less precision there will be in storing the tree scales (since scale values are actually packed into a single byte).

Warning: Be sure to call this before adding any trees - otherwise adjusting this value will cause the size of the currently added trees to change.

Definition at line 196 of file TreeLoader2D.h.

◆ setMinimumScale()

void Forests::TreeLoader2D::setMinimumScale ( Ogre::Real minScale )

inline

Sets the minimum tree scale value.

When calling addTree() to add trees, the scale values you are allowed to use are restricted in the range of 0.0 - 2.0 by default. With this function, you can adjust the minimum scale you are allowed to use for trees. The closer this minimum value is to the maximum tree scale, the more precision there will be when storing trees with addTree().

Warning: Be sure to call this before adding any trees - otherwise adjusting this value will cause the size of the currently added trees to change.

Definition at line 214 of file TreeLoader2D.h.

Field Documentation

◆ actualBounds

TBounds Forests::TreeLoader2D::actualBounds

private

Definition at line 242 of file TreeLoader2D.h.

◆ colorMap

ColorMap* Forests::TreeLoader2D::colorMap

private

Definition at line 247 of file TreeLoader2D.h.

◆ colorMapFilter

MapFilter Forests::TreeLoader2D::colorMapFilter

private

Definition at line 248 of file TreeLoader2D.h.

◆ geom

PagedGeometry* Forests::TreeLoader2D::geom

private

Definition at line 255 of file TreeLoader2D.h.

◆ gridBounds

TBounds Forests::TreeLoader2D::gridBounds

private

Definition at line 242 of file TreeLoader2D.h.

◆ heightFunction

Ogre::Real(* Forests::TreeLoader2D::heightFunction) (Ogre::Real x, Ogre::Real z, void *userData)

private

Definition at line 251 of file TreeLoader2D.h.

◆ heightFunctionUserData

void* Forests::TreeLoader2D::heightFunctionUserData

private

Definition at line 252 of file TreeLoader2D.h.

◆ maximumScale

Ogre::Real Forests::TreeLoader2D::maximumScale

private

Definition at line 244 of file TreeLoader2D.h.

◆ minimumScale

Ogre::Real Forests::TreeLoader2D::minimumScale

private

Definition at line 244 of file TreeLoader2D.h.

◆ pageGridList

std::map<Ogre::Entity*, std::vector<TreeDef>*> Forests::TreeLoader2D::pageGridList

private

Definition at line 260 of file TreeLoader2D.h.

◆ pageGridX

int Forests::TreeLoader2D::pageGridX

private

Definition at line 240 of file TreeLoader2D.h.

◆ pageGridZ

int Forests::TreeLoader2D::pageGridZ

private

Definition at line 240 of file TreeLoader2D.h.

◆ pageSize

Ogre::Real Forests::TreeLoader2D::pageSize

private

Definition at line 241 of file TreeLoader2D.h.

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

source/main/terrain/paged/TreeLoader2D.h
source/main/terrain/paged/TreeLoader2D.cpp

Description

Data Structures

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Additional Inherited Members

Member Typedef Documentation

◆ PageGridListIterator

◆ PageGridListValue

Constructor & Destructor Documentation

◆ TreeLoader2D()

◆ ~TreeLoader2D()

Member Function Documentation

◆ _getGridPage()

◆ _setGridPage()

◆ addTree()

◆ deleteTrees() [1/2]

◆ deleteTrees() [2/2]

◆ getBounds()

◆ getColorMap()

◆ getMaximumScale()

◆ getMinimumScale()

◆ loadPage()

◆ setColorMap() [1/2]

◆ setColorMap() [2/2]

◆ setColorMapFilter()

◆ setHeightFunction()

◆ setMaximumScale()

◆ setMinimumScale()

Field Documentation

◆ actualBounds

◆ colorMap

◆ colorMapFilter

◆ geom

◆ gridBounds

◆ heightFunction

◆ heightFunctionUserData

◆ maximumScale

◆ minimumScale

◆ pageGridList

◆ pageGridX

◆ pageGridZ

◆ pageSize