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

#include <TreeLoader3D.h>

Inheritance diagram for Forests::TreeLoader3D:

Public Member Functions
	TreeLoader3D (PagedGeometry *geom, const TBounds &bounds)
	Creates a new TreeLoader3D 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, 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...

TreeIterator3D	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	TreeIterator3D

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: TreeLoader3D 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 TreeLoader3D::addTree(), supplying the appropriate parameters. You may notice that TreeLoader3D restricts trees to uniform scale and yaw rotation. This is done to conserve memory; TreeLoader3D packs trees into memory as effeciently as possible, taking only 10 bytes per tree. This means 1 million trees takes 9.53 MB of RAM (additionally, adding 1 million trees takes less than a second in a release build).

Note: Using TreeLoader2D uses 40% less memory than TreeLoader3D.

Constructor & Destructor Documentation

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

Creates a new TreeLoader3D object.

Parameters

geom	The PagedGeometry object that this TreeLoader3D 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< T >::left, and Ogre::TRect< T >::top.

Member Function Documentation

void Forests::TreeLoader3D::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

While TreeLoader3D allows you to provide full 3-dimensional x/y/z coordinates, you are restricted to only yaw rotation, and only uniform scale.

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, Ogre::Degree::valueDegrees(), Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

void Forests::TreeLoader3D::deleteTrees	(	const Ogre::Vector3 &	position,
		Ogre::Real	radius,
		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(), Ogre::Vector3::x, and Ogre::Vector3::z.

void Forests::TreeLoader3D::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< T >::bottom, Ogre::Math::Floor(), Ogre::TRect< T >::left, Ogre::TRect< T >::right, Ogre::TRect< T >::top, type, Ogre::Vector3::x, and Ogre::Vector3::z.

TreeIterator3D Forests::TreeLoader3D::getTrees ( )

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

The returned TreeIterator3D can be used to iterate through every tree that was added to this TreeLoader3D 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.

void Forests::TreeLoader3D::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().

void Forests::TreeLoader3D::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 SharedPtr< Texture >::isNull(), and load().

ColorMap* Forests::TreeLoader3D::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 TreeLoader3D. 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.

void Forests::TreeLoader3D::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().

void Forests::TreeLoader3D::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.

Ogre::Real Forests::TreeLoader3D::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.

void Forests::TreeLoader3D::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.

Ogre::Real Forests::TreeLoader3D::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.

const TBounds& Forests::TreeLoader3D::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.

References Ogre::Exception::ERR_INVALIDPARAMS, loadPage(), and OGRE_EXCEPT.

void Forests::TreeLoader3D::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< T >::left, Ogre::TRect< T >::top, Ogre::Vector3::UNIT_Y, Ogre::ColourValue::White, Ogre::Vector3::x, Forests::PageInfo::xIndex, Ogre::Vector3::y, Ogre::Vector3::z, and Forests::PageInfo::zIndex.

Referenced by getBounds().

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation