Forests::GrassLoader Class Reference

A PageLoader-derived object you can use with PagedGeometry to produce realistic grass. More...

#include <GrassLoader.h>

Inheritance diagram for Forests::GrassLoader:

Public Member Functions
	GrassLoader (PagedGeometry *geom)
	Creates a new GrassLoader object. More...
GrassLayer *	addLayer (const Ogre::String &material)
	Adds a grass layer to the scene. More...
void	deleteLayer (GrassLayer *layer)
	Removes and deletes a grass layer from the scene. More...
std::list< GrassLayer * > &	getLayerList ()
	Returns a list of added grass layers. More...
void	setWindDirection (Ogre::Vector3 &dir)
	Sets the global wind direction for this GrassLoader. More...
void	setBuildEdgesEnabled (bool value)
bool	getBuildEdgesEnabled ()
Ogre::Vector3 &	getWindDirection ()
	Returns the global wind direction for this GrassLoader. More...
void	setDensityFactor (float density)
	Sets the global density factor for this GrassLoader. More...
float	getDensityFactor ()
	Returns the global density factor for this GrassLoader. More...
void	setRenderQueueGroup (Ogre::uint8 queueID)
	Sets the render queue group the grass will be rendered through. More...
void	setHeightFunction (Ogre::Real(*heightFunction)(Ogre::Real x, Ogre::Real z, void *userData), void *userData=NULL)
	Sets the height function used to calculate grass Y coordinates. More...
void	loadPage (PageInfo &page)
	INTERNAL FUNCTION - DO NOT USE.
void	unloadPage (PageInfo &page)
	INTERNAL FUNCTION - DO NOT USE.
void	frameUpdate ()
	INTERNAL FUNCTION - DO NOT USE.
Public Member Functions inherited from Forests::PageLoader
virtual	~PageLoader ()
	Destructor This is defined here so the destructors of derived classes are called properly. More...

Static Public Member Functions
static float	getRangeRandom (float start, float end)

Friends
class	GrassLayer

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 produce realistic grass.

Using a GrassLoader is simple - simply create an instance, attach it to your PagedGeometry object with PagedGeometry::setPageLoader(), and add your grass. Important: For best performance, it is recommended that you use GrassPage (included in GrassLoader.h) to display geometry loaded by GrassLoader. This page type is designed for best performance with this grass system. BatchPage will work, although performance will be reduced slightly, and ImpostorPage will run extremely slow.

To add grass, just call addLayer(). addLayer() returns a GrassLayer object pointer, which you should use to further configure your newly added grass. Properties like size, density, color, animation, etc. can be controlled through the GrassLayer class.

Note

By default, the GrassLoader doesn't know what shape your terrain so all grass will be placed at 0 height. To inform GrassLoader of the shape of your terrain, you must specify a height function that returns the height (y coordinate) of your terrain at the given x and z 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.

Constructor & Destructor Documentation

GrassLoader()

Forests::GrassLoader::GrassLoader

(

PagedGeometry *

geom

)

Creates a new GrassLoader object.

Parameters

geom	The PagedGeometry object that this GrassLoader will be assigned to.

References Forests::PagedGeometry::getRenderQueue().

Member Function Documentation

addLayer()

GrassLayer * Forests::GrassLoader::addLayer

(

const Ogre::String &

material

)

Adds a grass layer to the scene.

Parameters

material

The initial grass texture to use (this can be changed later).

Since all grass is potentially infinite, it is not added like normal entities which have a specific position. Instead you add a grass "layer" to the scene. A grass layer is a "carpet" of a single type of grass that gets applied everywhere in your world. If you want multiple types of grass with different appearances, you'll have to add a multiple grass layers for each style.

Of course, a grass layer is not completely uniform. The GrassLayer class contains functions to vary grass size and density levels as desired.

See also

GrassLayer class for more information.

References Forests::GrassLayer::setMaterialName().

deleteLayer()

void Forests::GrassLoader::deleteLayer

(

GrassLayer *

layer

)

Removes and deletes a grass layer from the scene.

This function simply deletes a GrassLayer previously created with addLayer().

getLayerList()

std::list<GrassLayer*>& Forests::GrassLoader::getLayerList ( )

inline

Returns a list of added grass layers.

This function returns a std::list<GrassLayer*> reference, which contains all grass layers which have been added to this GrassLoader.

setWindDirection()

void Forests::GrassLoader::setWindDirection ( Ogre::Vector3 &  dir )

inline

Sets the global wind direction for this GrassLoader.

GrassLayer animation properties are used to configure the most of the animation behavior (sway length, speed, etc.), but wind direction is not included in GrassLayer since this is really a global property. Using this function, you can set the "global" wind direction which affects all animated grass associated with this PageLoader.

Default value is Vector3::UNIT_X.

Note

This only affects grass layers which have breeze animations enabled.

getWindDirection()

Ogre::Vector3& Forests::GrassLoader::getWindDirection ( )

inline

Returns the global wind direction for this GrassLoader.

See also

setWindDirection() for more information about the wind direction.

setDensityFactor()

void Forests::GrassLoader::setDensityFactor ( float  density )

inline

Sets the global density factor for this GrassLoader.

This function can be used to up-scale or down-scale the density of all grass associated with this GrassLoader. This is typically used to provide the user the option to reduce grass density for better performance on slower machines.

Final density values are calculated by multiplying the layer density by this density factor. For example, a layer with .4 density and a density factor of .5 will result in a final density of .2 (.5 * .4)

By default, the density factor is set to 1.0 so the layer density is not modified.

getDensityFactor()

float Forests::GrassLoader::getDensityFactor ( )

inline

Returns the global density factor for this GrassLoader.

See also

setDensityFactor() for more information about the density factor.

setRenderQueueGroup()

void Forests::GrassLoader::setRenderQueueGroup ( Ogre::uint8  queueID )

inline

Sets the render queue group the grass will be rendered through.

Parameters

queueID

Enumerated value of the queue group to use

Like Ogre's MovableObject::setRenderQueueGroup(), this allows you to customize the rendering order of your scene. Since grass is transparent, it's likely that you may encounter alpha-sorting issues between grass and your particle effects, for example. In this case you can use this function to adjust the rendering order of the grass to fix the problem.

If you don't call this function, the RENDER_QUEUE_6 queue will be used.

Note

Once grass is loaded and being rendered, this won't have any effect on it. Be sure to call this function before the scene begins rendering, otherwise you will have to call PagedGeometry::reloadGeometry() to force a reload in order for the changes to take effect.

setHeightFunction()

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

inline

Sets the height function used to calculate grass Y coordinates.

Parameters

heightFunction

A pointer to a height function

Unless you want all your grass placed at 0 height, you need to specify a height function so GrassLoader will be able to calculate the Y 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);

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.