Forests::GrassLayer Class Reference

A data structure giving you full control over grass properties. More...

#include <GrassLoader.h>

Public Member Functions
void	setMaterialName (const Ogre::String &matName)
	Sets the material that is applied to all grass billboards/quads.
void	setMinimumSize (float width, float height)
	Sets the minimum size that grass quads/billboards will be.
void	setMaximumSize (float width, float height)
	Sets the maximum size that grass quads/billboards will be.
void	setDensity (float density)
	Sets the maximum density (measured in grass quads/billboards per square unit) of grass.
void	setHeightRange (float minHeight, float maxHeight=0)
	Sets a minimum / maximum height where grass may appear. More...
void	setMaxSlope (const float maxSlopeRatio)
	Set the maximum slope a grass of blade can be placed on. More...
void	setMaxSlope (Ogre::Radian maxSlopeAngle)
Ogre::Real	getMaxSlope () const
	Get the maximum slope a grass blade can be placed on (as set by setMaxSlope()). More...
void	setDensityMap (const Ogre::String &mapFile, MapChannel channel=CHANNEL_COLOR)
	Sets the density map used for this grass layer. More...
void	setDensityMap (Ogre::TexturePtr map, MapChannel channel=CHANNEL_COLOR)
	Sets the density map used for this grass layer. More...
void	setDensityMapFilter (MapFilter filter)
	Sets the filtering mode used for density maps. More...
void	setColorMap (const Ogre::String &mapFile, MapChannel channel=CHANNEL_COLOR)
	Sets the color map used for this grass layer. More...
void	setColorMap (Ogre::TexturePtr map, MapChannel channel=CHANNEL_COLOR)
	Sets the color map used for this grass layer. More...
void	setColorMapFilter (MapFilter filter)
	Sets the filtering mode used for color maps. More...
void	setMapBounds (const TBounds &bounds)
	Sets the boundaries of the density/color maps. More...
DensityMap *	getDensityMap () const
	Gets a pointer to the density map being used. More...
ColorMap *	getColorMap () const
	Gets a pointer to the color map being used. More...
bool	getBlendValue () const
	Gives back the value of blending.
GrassLoader *	getParentGrassLoader () const
	Gets the parent grassLoader of this layer.
bool	getLightingEnabled () const
	Gives back if lighting is enabled for grass.
const TBounds &	getMapBounds () const
	Gets the map bounds.
void	setRenderTechnique (GrassTechnique style, bool blendBase=false)
	Sets the technique used to render this grass layer. More...
void	setFadeTechnique (FadeTechnique style)
	Sets the technique used when fading out distant grass. More...
void	setAnimationEnabled (bool enabled)
	Enables/disables animation on this layer. More...
void	setLightingEnabled (bool enabled)
	Enables/disables lighting on this layer.
void	setSwayLength (Ogre::Real mag)
	Sets how far grass should sway back and forth. More...
void	setSwaySpeed (Ogre::Real speed)
	Sets the sway speed of the grass (measured in "sways-per-second")
void	setSwayDistribution (Ogre::Real freq)
	Sets the smooth distribution (positional phase shift) of the grass swaying animation. More...

Friends
class	GrassLoader

Detailed Description

A data structure giving you full control over grass properties.

Grass is added to the scene through GrassLoader::addLayer(). Through this class you can configure your grass layer any way you like - size, density, render technique, animation, etc. Simply call the appropriate "set" member function to set the desired property.

Remember that you cannot create or delete layers directly. Layers can only be created with GrassLoader::addLayer(), and may not be deleted manually (they will be deleted when the associated GrassLoader is deleted).

Member Function Documentation

setHeightRange()

void Forests::GrassLayer::setHeightRange ( float  minHeight, float  maxHeight = 0  )

inline

Sets a minimum / maximum height where grass may appear.

Parameters

minHeight	Sets the minimum height grass may have. 0 = no minimum
maxHeight	Sets the maximum height grass may have. 0 = no maximum

By default grass appears at all altitudes. You can use this function to restrict grass to a certain height range. For example, if sea level is at 100 units Y, you might restrict this layer to display only above 100 units (so your grass doesn't grow under water).

It's possible to use density maps (see setDensityMap()) to achieve similar results, but if your density map is extremely low resolution, this function may be the only practical option to prevent grass from growing under water (when used in combination with your density map).

Setting minHeight to 0 means grass has no minimum height - it can grow as low as necessary. Similarly, setting maxHeight to 0 means grass has no maximum height - it can grow as high as necessary.

setMaxSlope()

void Forests::GrassLayer::setMaxSlope ( const float  maxSlopeRatio )

inline

Set the maximum slope a grass of blade can be placed on.

Parameters

maxSlopeRatio

The maximum slope (h/w ratio) a grass blade is allowed to be placed on.

This function can be used to set the maximum slope you want your grass to be placed on (although it doesn't work for sprite grass). By default grass is allowed on any slope.

This version of setMaxSlope() accepts a slope ratio value, where ATan(maxSlopeRatio) = maxSlopeAngle. If you wish to provide a maximum slope as an angle, either use the other overload of this function, or convert your angle to a slope ratio first with Tan().

getMaxSlope()

Ogre::Real Forests::GrassLayer::getMaxSlope ( ) const

inline

Get the maximum slope a grass blade can be placed on (as set by setMaxSlope()).

Returns

The currently set maximum slope ratio value (not an angle).

This returns the currently set maximum slope which is used to determine what ground is too steep for grass to be placed on. Note that this returns the slope as a slope ratio, not an angle. If you need an angle value, convert with ATan() (maxSlopeAngle = ATan(maxSlopeRatio)).

setDensityMap() [1/2]

void Forests::GrassLayer::setDensityMap	(	const Ogre::String &	mapFile,
		MapChannel	channel = CHANNEL_COLOR
	)

Sets the density map used for this grass layer.

Parameters

mapFile	The density map image
channel	The color channel(s) to from the image to interpret as density

A density map is simply a greyscale image, similar to a heightmap, that specifies the grass density on your map. Full pixel intensity indicates that grass should be fully dense at that point (the maximum density is specified by GrassLayer::setDensity()), while no pixel intensity indicates that no grass should appear at that location.

The channel parameter allows you to extract the density information from the image's red, green, blue, alpha, or color values. For example, you may store density values in the alpha channel, in which case you would use CHANNEL_ALPHA. By default, CHANNEL_COLOR is used, which means the image color is converted to greyscale internally and used as a density map.

Note that GrassLayer by default has no idea of your terrain/world boundaries, so you must specify a rectangular/square area of your world that is affected by density/color maps. To do this, use the setMapBounds() function. Normally this is set to your terrain's bounds so the density/color map is aligned to your heightmap, but you could apply it anywhere you want.

References load().

setDensityMap() [2/2]

void Forests::GrassLayer::setDensityMap	(	Ogre::TexturePtr	map,
		MapChannel	channel = CHANNEL_COLOR
	)

Sets the density map used for this grass layer.

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

Note

The texture data you provide is copied into the GrassLayer's own memory space, so you can delete the texture after calling this function without risk of crashing.

References load().

setDensityMapFilter()

void Forests::GrassLayer::setDensityMapFilter

(

MapFilter

filter

)

Sets the filtering mode used for density maps.

This function can be used to set the filtering mode used for your density map when generating grass. By default, bilinear filtering is used (MAPFILTER_BILINEAR). If you disable filtering by using MAPFILTER_NONE, the resulting layout of your grass may look square and blocky, depending on the resolution of your density map.

MAPFILTER_NONE is slightly faster than MAPFILTER_BILINEAR, so use it if you don't notice any considerable blockiness.

setColorMap() [1/2]

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

Sets the color map used for this grass layer.

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 grass across your world for a more realistic look. For example, adding a dark spot to the center of your color map will make grass near the center of your terrain look darker, as long as you have the color map aligned to your terrain (see setMapBounds()).

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

Remember that GrassLayer by default has no idea of your terrain/world boundaries, so you must specify a rectangular/square area of your world that is affected by density/color maps. To do this, use the setMapBounds() function. Normally this is set to your terrain's bounds so the density/color map is aligned to your heightmap, but you could apply it anywhere you want.

References load().

setColorMap() [2/2]

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

Sets the color map used for this grass layer.

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().

setColorMapFilter()

void Forests::GrassLayer::setColorMapFilter

(

MapFilter

filter

)

Sets the filtering mode used for color maps.

This function can be used to set the filtering mode used for your color map when generating grass. By default, bilinear filtering is used (MAPFILTER_BILINEAR). If you disable filtering by using MAPFILTER_NONE, the resulting grass coloration may appear slightly pixelated, depending on the resolution of your color map.

MAPFILTER_NONE is slightly faster than MAPFILTER_BILINEAR, so use it if you don't notice any considerable pixelation.

setMapBounds()

void Forests::GrassLayer::setMapBounds ( const TBounds &  bounds )

inline

Sets the boundaries of the density/color maps.

Parameters

bounds

The map boundary

By default, the GrassLayer has no knowledge of your terrain/world boundaries, so you must use this function to specify a rectangular/square area of your world, otherwise density/color maps won't work properly. The boundary given to this function defines the area where density/color maps take effect. Normally this is set to your terrain's bounds so the density/color map is aligned to your heightmap, but you could apply it anywhere you want.

Note

The grass system is infinite, so there's no need to worry about using too expansive boundaries. This setting simply configures the behavior of density and color maps.

getDensityMap()

DensityMap* Forests::GrassLayer::getDensityMap ( ) const

inline

Gets a pointer to the density map being used.

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

Note that although you can edit the density 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 grass you see will remain unchanged.

getColorMap()

ColorMap* Forests::GrassLayer::getColorMap ( ) const

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 GrassLoader. 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 grass you see will remain unchanged.

setRenderTechnique()

void Forests::GrassLayer::setRenderTechnique	(	GrassTechnique	style,
		bool	blendBase = false
	)

Sets the technique used to render this grass layer.

Parameters

style	The GrassTechnique style used to display grass.
blendBase	Whether or not grass base blending is enabled.

The "style" setting allows you to choose from various construction methods, such as sprite-style grass quads, plain 3D quads, etc. See the GrassTechnique documentation for more information about this option. GRASSTECH_QUAD is used by default.

Setting "blendBase" to true will enable grass base blending, a technique which helps reduce the unnatural flat appearance of grass quads near the camera. Since the flatness is most obvious where the grass intersects the terrain, this technique attempts to smoothly blend the base of near-by grass into the terrain.

Note

Base blending does not work well with alpha-rejected textures.

setFadeTechnique()

void Forests::GrassLayer::setFadeTechnique

(

FadeTechnique

style

)

Sets the technique used when fading out distant grass.

Parameters

style

The FadeTechnique style used to fade grass.

This "style" setting allows you to choose from various fade techniques. Depending on your scene, certain techniques may look better than others. The most compatible method is FADETECH_ALPHA (used by default), although better results can usually be achieved with other methods. See the FadeTechnique documentation for more information.

setAnimationEnabled()

void Forests::GrassLayer::setAnimationEnabled

(

bool

enabled

)

Enables/disables animation on this layer.

Always use this function to disable animation, rather than setting SwayLength or SwaySpeed to 0. This function will use a different vertex shader which means improved performance when animation is disabled.

setSwayLength()

void Forests::GrassLayer::setSwayLength ( Ogre::Real  mag )

inline

Sets how far grass should sway back and forth.

Note

Since this is measured in world units, you may have to adjust this depending on the size of your grass as set by setMinimumSize() and setMaximumSize().

setSwayDistribution()

void Forests::GrassLayer::setSwayDistribution ( Ogre::Real  freq )

inline

Sets the smooth distribution (positional phase shift) of the grass swaying animation.

If you set this to 0, grass animation will look very unnatural, since all the grass sway motions will be in perfect synchronization (everything sways to the right, then everything sways to the left, etc.) This sets the "positional phase shift", which gives the grass a "wave" like phase distribution. The higher this value is, the more "chaotic" the wind will appear. Lower values give a smoother breeze appearance, but values too high can look unrealistic.