Unigine::ObjectGrass Class

This class is used to create grass. The grass object is rendered in grid cells.

The following samples demonstrate the ObjectGrass class usage:

• grass_00
• grass_01
• grass_02
• grass_03

ObjectGrass Class

Members

---

static ObjectGrassPtr create()

Constructor. Creates a new grass object.

Ptr<ObjectGrass> cast(const Ptr<Object> & base)

Casts an ObjectGrass out of the Object instance.

Arguments

• const Ptr<Object> & base - Pointer to Object.

Return value

Pointer to ObjectGrass.

Ptr<ObjectGrass> cast(const Ptr<Node> & node)

Casts an ObjectGrass out of the Node instance.

Arguments

• const Ptr<Node> & node - Pointer to Node.

Return value

Pointer to ObjectGrass.

void setAngle(float angle)

Sets the angle cosine defining the slope steepness appropriate for grass growing.

Arguments

• float angle - Slope angle cosine in range from 0 to 1.

float getAngle()

Returns the current angle cosine defining the slope steepness appropriate for grass growing.

Return value

Slope angle cosine.

void setAspect(const Math::vec4 & mean, const Math::vec4 & spread)

Sets the aspect of the grass polygons (width to height ratio).

Arguments

• const Math::vec4 & mean - Mean value of grass aspect.
• const Math::vec4 & spread - Spread value of grass aspect.

Math::vec4 getAspectMean()

Returns the current mean value of the grass aspect (width to height ratio), defined for four diffuse texture columns.

Return value

Mean value of grass aspect.

Math::vec4 getAspectSpread()

Returns the current spread value of the grass aspect (width to height ratio), defined for four diffuse texture columns.

Return value

Spread value of grass aspect.

void setDensity(float density)

Sets the density factor for the grass per square unit.

Arguments

• float density - Density factor. If a negative value is provided, 0 will be used instead.

float getDensity()

Returns the current density factor for the grass per square unit.

Return value

Density factor.

void setFieldMask(int mask)

Sets a mask specifying the area of the Field node to be applied to the grass.

Arguments

• int mask - Integer, each bit of which is a mask.

int getFieldMask()

Returns a mask specifying the area of the Field node to be applied to the grass.

Return value

Integer, each bit of which is a mask.

void setIntersection(int intersection)

Sets a value indicating whether grass should grow upon the ground: either the terrain or a mesh set as a parent node.

Arguments

• int intersection - Positive number to enable intersection; 0 to disable.

int getIntersection()

Returns a value indicating whether grass grow upon the ground: either the terrain or a mesh set as a parent node.

Return value

Positive number if intersection is enabled; otherwise, 0.

void setMaskFlipX(int maskflipx)

Flip the mask by X axis.

Arguments

• int maskflipx - Positive value to flip the mask; otherwise, 0.

int getMaskFlipX()

Returns a flag indicating if a mask is flipped by X axis.

Return value

Positive value if the mask is flipped; otherwise, 0.

void setMaskFlipY(int maskflipy)

Flip the mask by Y axis.

Arguments

• int maskflipy - Positive value to flip the mask; otherwise, 0.

int getMaskFlipY()

Returns a flag indicating if a mask is flipped by Y axis.

Return value

Positive value if the mask is flipped; otherwise, 0.

int setMaskImage(const Ptr<Image> & image, int invalidate = 1)

Sets an image that defines the areas of growing grass. Possible mask formats are R8, RG8, RGB8 and RGBA8.

Arguments

• const Ptr<Image> & image - Pointer to the image.
• int invalidate - Invalidate flag. Set 1 to invalidate all grass cells; otherwise, set 0. All invalidated cells will be regenerated.

Return value

1 if the mask image is successfully set; otherwise, 0.

int getMaskImage(const Ptr<Image> & image)

Writes the image that is currently used to define the areas of grass growing into the given buffer. Possible mask formats are R8, RG8, RGB8 and RGBA8.

Arguments

• const Ptr<Image> & image - Image buffer to store a mask into.

Return value

1 if the mask image is successfully written into the buffer; otherwise, 0.

void setMaskImageName(const char * name, int invalidate = 1)

Sets the name of a mask image that defines the areas of growing grass. Possible mask formats are R8, RG8, RGB8 and RGBA8.

Arguments

• const char * name - Name (path) of the mask image.
• int invalidate - Invalidate flag. Set 1 to invalidate all grass cells; otherwise, set 0. All invalidated cells will be regenerated.

const char * getMaskImageName()

Returns a name of the current mask image that defines the areas of grass growing. Possible mask formats are R8, RG8, RGB8 and RGBA8.

Return value

Name (path) of the mask image.

void setMaskInverse(int inverse)

Specifies if the grass should be rendered inside or outside the mask mesh contour.

Arguments

• int inverse - 0 to render the grass inside the mesh contour; 1 to render it outside.

int getMaskInverse()

Returns a flag indicating if the grass is rendered inside or outside the mask mesh contour.

Return value

0 if the grass is rendered inside the mesh contour; 1 if outside.

void setMaskMaxValue(int value)

Sets the maximum value of the mask application range.

Arguments

• int value - Maximum mask value, [0;255].

int getMaskMaxValue()

Returns the maximum value of the mask application range.

Return value

Maximum mask value.

int setMaskMesh(const Ptr<Mesh> & mesh, int invalidate = 1)

Sets a mesh to be used as a mask on-the-fly. Limitations:

• Before the method is called, another mesh must be set via setMaskMeshName() first.
• If the world is reloaded, the mesh set via setMaskMeshName() will be loaded.
• If the memory limit is exceeded, the new mesh might be replaced with the mesh set via setMaskMeshName().

Arguments

• const Ptr<Mesh> & mesh - Pointer to the mesh.
• int invalidate - Invalidate flag. Set 1 to invalidate all grass cells; otherwise, set 0. All invalidated cells will be regenerated.

Return value

1 if the mesh is set successfully; otherwise - 0.

int getMaskMesh(const Ptr<Mesh> & mesh)

Copies the current mask mesh (if it exists) to the specified target mesh.

Arguments

• const Ptr<Mesh> & mesh - Pointer to the mesh to copy the current mask mesh to.

Return value

1 if mesh mask exists; otherwise - 0.

void setMaskMeshName(const char * name, int invalidate = 1)

Sets a mesh to be used as a mask for the grass. This mesh should be plane.

Arguments

• const char * name - Path to the *.mesh file.
• int invalidate - Invalidate flag. Set 1 to invalidate all grass cells; otherwise, set 0. All invalidated cells will be regenerated.

const char * getMaskMeshName()

Returns the name (path) of the current mesh used as a mask for the grass. This mesh should be plane.

Return value

Path to the *.mesh file.

void setMaskMinValue(int value)

Sets the minimum value of the mask application range.

Arguments

• int value - Minimum mask value, [0;255].

int getMaskMinValue()

Returns the minimum value of the mask application range.

Return value

Minimum mask value.

void setMaxBend(const Math::vec4 & mean, const Math::vec4 & spread)

Sets the maximum grass bending parameters (rendered in areas with the highest density according to the mask). Bend angles (mean and spread) are defined for four diffuse texture columns. The resulting value is determined as follows: Result = Mean + Random * Spread, where Random is a random value in range from -1 to 1.

Arguments

• const Math::vec4 & mean - Vector of mean values of grass bending angles to be set for four diffuse texture columns.
• const Math::vec4 & spread - Vector of spread values of grass bending angles to be set for four diffuse texture columns.

Math::vec4 getMaxBendMean()

Returns the mean value for the maximum grass bending (rendered in areas with the highest density according to the mask). Bend angles are defined for four diffuse texture columns.

Return value

Vector of mean values of grass bending angles for four diffuse texture columns.

Math::vec4 getMaxBendSpread()

Returns the spread value for the maximum grass bending (rendered in areas with the highest density according to the mask). Bend angles are defined for four diffuse texture columns.

Return value

Vector of spread values of grass bending angles for four diffuse texture columns.

void setMinBend(const Math::vec4 & mean, const Math::vec4 & spread)

Sets the minimum grass bending parameters (rendered in areas with the lowest density according to the mask). Bend angles (mean and spread) are defined for four diffuse texture columns. The resulting value is determined as follows: Result = Mean + Random * Spread, where Random is a random value in range from -1 to 1.

Arguments

• const Math::vec4 & mean - Vector of mean values of grass bending angles to be set for four diffuse texture columns.
• const Math::vec4 & spread - Vector of spread values of grass bending angles to be set for four diffuse texture columns.

Math::vec4 getMinBendMean()

Returns the mean value for the minimum grass bending (rendered in areas with the lowest density according to the mask). Bend angles are defined for four diffuse texture columns.

Return value

Vector of mean values of grass bending angles for four diffuse texture columns.

Math::vec4 getMinBendSpread()

Returns the spread value for the minimum grass bending (rendered in areas with the lowest density according to the mask). Bend angles are defined for four diffuse texture columns.

Return value

Vector of spread values of grass bending angles for four diffuse texture columns.

void setMaxHeight(const Math::vec4 & mean, const Math::vec4 & spread)

Sets the maximum grass height (rendered in areas with the highest density according to the mask). The height is defined for four diffuse texture columns, as mean and spread values ( Result = Mean + Random * Spread, where Random is a random value in range from -1 to 1).

Arguments

• const Math::vec4 & mean - Mean value for the maximum grass height in units. If a negative value is provided, EPSILON will be used instead.
• const Math::vec4 & spread - Spread value for the maximum grass height in units.

Math::vec4 getMaxHeightMean()

Returns the mean value for the maximum grass height (rendered in areas with the highest density according to the mask). The height is defined for four diffuse texture columns.

Return value

Mean value for the maximum grass height in units.

Math::vec4 getMaxHeightSpread()

Returns the spread value for the maximum grass height (rendered in areas with the highest density according to the mask). The height is defined for four diffuse texture columns.

Return value

Spread value for the maximum grass height in units.

void setMinHeight(const Math::vec4 & mean, const Math::vec4 & spread)

Sets the minimum grass height (rendered in areas with the lowest density according to the mask). The height is defined for four diffuse texture columns, as mean and spread values ( Result = Mean + Random * Spread, where Random is a random value in range from -1 to 1).

Arguments

• const Math::vec4 & mean - Mean value for the minimum grass height in units. If a negative value is provided, EPSILON will be used instead.
• const Math::vec4 & spread - Spread value for the minimum grass height in units.

Math::vec4 getMinHeightMean()

Returns the mean value for the minimum grass height (rendered in areas with the lowest density according to the mask). The height is defined for four diffuse texture columns.

Return value

Mean value for the minimum grass height in units.

Math::vec4 getMinHeightSpread()

Returns the spread value for the minimum grass height (rendered in areas with the lowest density according to the mask). The height is defined for four diffuse texture columns.

Return value

Spread value for the minimum grass height in units.

void setNumTextures(int textures)

Sets the number of textures contained in the grass diffuse texture.

Arguments

• int textures - The number of contained textures.

int getNumTextures()

Returns the number of textures contained in the grass diffuse texture.

Return value

The number of contained textures.

void setOffset(const Math::vec4 & mean, const Math::vec4 & spread)

Sets the grass offset from the surface along the surface normal, defined for four diffuse texture columns. If a negative mean value is provided, vec4_eps will be used instead.

Arguments

• const Math::vec4 & mean - Mean value of grass polygons offset in units.
• const Math::vec4 & spread - Spread value of grass polygons offset in units.

Math::vec4 getOffsetMean()

Returns the current mean value of the grass offset from the surface along the surface normal, defined for four diffuse texture columns.

Return value

Mean value of grass polygons offset in units.

Math::vec4 getOffsetSpread()

Returns the current spread value for the grass offset from the surface along the surface normal, defined for four diffuse texture columns.

Return value

Spread value for grass polygons offset in units.

void setOrientation(int orientation)

Sets a flag to orient grass polygons along the normal of its parent (for example, a terrain).

Arguments

• int orientation - 1 to orient the grass along the normals of the ground; 0 to render it always pointing upwards.

int getOrientation()

Returns a flag indicating if grass polygons are oriented along the normal of its parent (for example, a terrain).

Return value

1 if the grass is oriented along the normals of the ground; 0 if it always points upwards.

void setProbability(const Math::vec4 & probability)

Sets the grass rendering probability per column (in the diffuse texture). The higher the value for some column, the more frequently it will be rendered.

Arguments

• const Math::vec4 & probability - Per-column probability. Any values can be set, since they are normalized.

Math::vec4 getProbability()

Returns the current grass rendering probability per column (in the diffuse texture). The higher the value for some column, the more frequently it will be rendered.

Return value

Per-column probability.

void setSeed(int seed)

Sets the seed for pseudo-random positioning of grass.

Arguments

• int seed - Number used to initialize a pseudo-random sequence. If a negative value is provided, 0 will be used instead.

int getSeed()

Returns the seed used for pseudo-random positioning of grass.

Return value

Number used to initialize a pseudo-random sequence.

void setSizeX(float sizex)

Sets the width of the grass object along the X-coordinate.

Arguments

• float sizex - X-coordinate width in units. If a negative value is provided, 0 will be used instead.

float getSizeX()

Returns the current width of the grass object along the X-coordinate.

Return value

X-coordinate width in units.

void setSizeY(float sizey)

Sets the length of the grass object along the Y-coordinate.

Arguments

• float sizey - Y-coordinate length in units. If a negative value is provided, 0 will be used instead.

float getSizeY()

Returns the current length of the grass object along the Y-coordinate.

Return value

Y-coordinate length in units.

int getSpawnCount()

Returns the number of cells to be generated.

Return value

Number of cells to be generated if the scene generation is not completed; otherwise, 0.

void setStep(float step)

Sets the step for cells used to render grass.

Arguments

• float step - Step for grass cells.

float getStep()

Returns the current step for cells used to render grass.

Return value

Step for grass cells.

void setSubdivision(int subdivision)

Subdivide grass rendering cells into smaller sub-cells. It is used if a grass node is used as a distant LOD for WorldClutter or ObjectMeshClutter with smaller cells. This way, positions of randomly scattered objects will coincide with those of grass-based impostors.

Arguments

• int subdivision - Divisor for cells. The value is clamped to a range [1;32].

int getSubdivision()

Returns the current divisor used to subdivide grass rendering cells into smaller sub-cells. Subdividing is used if a grass node is used as a distant LOD for WorldClutter or ObjectMeshClutter with smaller cells. This way, positions of randomly scattered objects will coincide with those of grass-based impostors.

Return value

Divisor for cells.

void setThinning(int thinning)

Sets a flag to thin out grass with a distance (random grass polygons are not rendered across the grass Fade distance).

Arguments

• int thinning - 1 to thin out the grass; 0 to render all grass polygons at the distance.

int getThinning()

Returns a flag indicating if the grass is thinned out with a distance (random grass polygons are not rendered across the grass Fade distance).

Return value

1 if the grass is thinned out; 0 if all grass polygons are rendered at the distance.

void setThreshold(float threshold)

Sets the threshold for density, starting from which the grass will be rendered.

Arguments

• float threshold - Threshold value in range from 0 to 1.

float getThreshold()

Returns the current threshold for density, starting from which the grass is rendered.

Return value

Threshold value.

void setVariation(int variation)

Sets the random horizontal flip for grass polygons.

Arguments

• int variation - 1 to enable grass flipping, 0 to disable it.

int getVariation()

Returns a value indicating if the random horizontal flip for grass polygons is set.

Return value

1 if grass flipping is enabled; otherwise, 0.

int type()

Returns the type of the node.

Return value

Object type identifier.

void invalidate()

Invalidates all grass cells. All invalidated cells will be regenerated.

void invalidate(const UNIGINE_BOUND_BOX & bounds)

Invalidates all grass cells within the area specified by the given bounding box. All invalidated cells will be regenerated.

Arguments

• const UNIGINE_BOUND_BOX & bounds - Bounding box, defining the area, where grass cells will be regenerated.