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

#include <TreeLoader2D.h>

Inheritance diagram for Forests::TreeLoader2D:

Public Member Functions
	TreeLoader2D (PagedGeometry *geom, const TBounds &bounds)
	Creates a new TreeLoader2D object. More...

void	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. More...

void	deleteTrees (const Ogre::Vector3 &position, Ogre::Real radius=0.001f, Ogre::Entity *type=NULL)
	Deletes trees within a certain radius of the given coordinates. More...

void	deleteTrees (TBounds area, Ogre::Entity *type=NULL)
	Deletes trees within a certain rectangular area. More...

void	setHeightFunction (Ogre::Real(heightFunction)(Ogre::Real x, Ogre::Real z, void userData), void *userData=NULL)
	Sets the height function used to calculate tree height coordinates. More...

TreeIterator2D	getTrees ()
	Gets an iterator which can be used to access all added trees. More...

void	setColorMap (const Ogre::String &mapFile, MapChannel channel=CHANNEL_COLOR)
	Sets the color map used to color trees. More...

void	setColorMap (Ogre::TexturePtr map, MapChannel channel=CHANNEL_COLOR)
	Sets the color map used to color trees. More...

ColorMap *	getColorMap ()
	Gets a pointer to the color map being used. More...

void	setColorMapFilter (MapFilter filter)
	Sets the filtering mode used for the color map. More...

void	setMaximumScale (Ogre::Real maxScale)
	Sets the maximum tree scale value. More...

Ogre::Real	getMaximumScale () const
	Gets the maximum tree scale value. More...

void	setMinimumScale (Ogre::Real minScale)
	Sets the minimum tree scale value. More...

Ogre::Real	getMinimumScale () const
	Gets the minimum tree scale value. More...

const TBounds &	getBounds () const
	Gets the tree boundary area. More...

void	loadPage (PageInfo &page)
	This should be overridden to load a specified region of entities. More...

Public Member Functions inherited from Forests::PageLoader
virtual void	unloadPage (PageInfo &page)
	This may be overridden (optional) to unload custom data associated with a page. More...

virtual void	frameUpdate ()
	Provides a method for you to perform per-frame tasks for your PageLoader if overridden (optional) More...

virtual	~PageLoader ()
	Destructor This is defined here so the destructors of derived classes are called properly. More...

Friends
class	TreeIterator2D

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)
	Call this from loadPage() to add an entity to the page being loaded. More...

Detailed 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.

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.

References Ogre::Math::Ceil(), Ogre::Math::Floor(), Forests::PagedGeometry::getBounds(), Forests::PagedGeometry::getPageSize(), Ogre::TRect< class >::left, and Ogre::TRect< class >::top.

Member Function Documentation

◆ 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.

References Ogre::Exception::ERR_INVALIDPARAMS, Ogre::Math::Floor(), OGRE_EXCEPT, and Ogre::Degree::valueDegrees().

◆ 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.

References Ogre::Math::Floor().

◆ 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.

References Ogre::TRect< class >::bottom, Ogre::Math::Floor(), Ogre::TRect< class >::left, Ogre::TRect< class >::right, and Ogre::TRect< class >::top.

◆ 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);

Real

float Real

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.

◆ getTrees()

TreeIterator2D Forests::TreeLoader2D::getTrees ( )

Gets an iterator which can be used to access all added trees.

The returned TreeIterator can be used to iterate through every tree that was added to this TreeLoader fairly efficiently.

See also: The TreeIterator class documentation for more info.

Warning: Be sure to test TreeIterator3D::hasMoreElements() before calling other members of the TreeIterator3D class.

◆ 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.

References load().

◆ 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.

References load().

◆ 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.

◆ 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.

References Forests::ColorMap::setFilter().

◆ 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.

◆ 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.

◆ 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.

◆ 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.

◆ getBounds()

const TBounds& Forests::TreeLoader2D::getBounds ( void ) 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.

◆ 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.

References Forests::PageInfo::bounds, Ogre::Math::Floor(), Ogre::TRect< class >::left, Ogre::TRect< class >::top, Ogre::ColourValue::White, Forests::PageInfo::xIndex, and Forests::PageInfo::zIndex.

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ TreeLoader2D()

Member Function Documentation

◆ addTree()

◆ deleteTrees() [1/2]

◆ deleteTrees() [2/2]

◆ setHeightFunction()

◆ getTrees()

◆ setColorMap() [1/2]

◆ setColorMap() [2/2]

◆ getColorMap()

◆ setColorMapFilter()

◆ setMaximumScale()

◆ getMaximumScale()

◆ setMinimumScale()

◆ getMinimumScale()

◆ getBounds()

◆ loadPage()