Unigine::ObjectTerrain Class

Interface for object terrain handling. See also the UnigineScript analog.

To use this class, include the UnigineObjectTerrain.h file.

Unigine::ObjectTerrain Class

Members

---

static Ptr< ObjectTerrain > create (const NodePtr & node)

ObjectTerrain constructor.

Arguments

• const NodePtr & node - Node smart pointer.

static Ptr< ObjectTerrain > create (const ObjectPtr & object)

ObjectTerrain constructor.

Arguments

• const ObjectPtr & object - Object smart pointer.

static Ptr< ObjectTerrain > create ()

ObjectTerrain constructor.

static Ptr< ObjectTerrain > create (const char * name)

ObjectTerrain constructor.

Arguments

• const char * name - Terrain file name (*.ter).

virtual int create (const ImagePtr & image, float step, float height) const =0

Creates a new terrain from a loaded height map.

Arguments

• const ImagePtr & image - Height map. Image size (height and width) must be power-of-two + 1 (maximum size is 32769 × 32769).
• float step - Step of terrain grid cell in units.
• float height - Maximum height. All height gradations will be written in range from 0 to 32768.

Return value

Returns 1 if the terrain is created successfully; otherwise, 0.

virtual int create (int size_x, int size_y, float step, float height) const =0

Creates an new terrain of a specified grid size.

Arguments

• int size_x - Terrain width in grid cells along X axis in range [257;32679].
• int size_y - Terrain length in grid cells along Y axis in range [257;32679].
• float step - Step of terrain grid cell in units.
• float height - Maximum height. All height gradations will be written in range from 0 to 32768.

Return value

Returns 1 if the terrain is created successfully; otherwise, 0.

virtual int load (const char * name) const =0

Loads a terrain from a file.

Arguments

• const char * name - Path to the terrain file (*.ter).

Return value

Returns 1 if the terrain is loaded successfully; otherwise, 0.

virtual int save (const char * name, int force) const =0

Saves the terrain.

Arguments

• const char * name - Path to the terrain file (*.ter).
• int force - Force flag. Use 1 to save the terrain file in any case or 0 to save the terrain file if changes were made.

Return value

Returns 1 if the terrain is saved successfully; otherwise, 0.

virtual int isLoaded () const =0

Returns a value indicating whether the terrain is loaded.

Return value

Returns 1 if the terrain is loaded; otherwise, 0.

virtual int getSizeX () const =0

Returns terrain width in grid cells.

Return value

Terrain width along X axis.

virtual int getSizeY () const =0

Returns terrain length in grid cells.

Return value

Terrain length along Y axis.

virtual float getStep () const =0

Returns the linear size of a grid cell in units.

Return value

Cell size in units.

virtual float getHeight () const =0

Returns the maximum height value of the terrain.

Return value

Maximum height value.

virtual void setHeight (int x, int y, float height) const =0

Changes height of a given terrain point.

Arguments

• int x - X coordinate of the point on the terrain grid in range from 0 to the maximum terrain width.
• int y - Y coordinate of the point on the terrain grid in range from 0 to the maximum terrain length.
• float height - Height in units to set.

virtual float getHeight (int x, int y) const =0

Returns height of a given terrain point.

Arguments

• int x - X coordinate of the point on the terrain grid in range from 0 to the maximum terrain width.
• int y - Y coordinate of the point on the terrain grid in range from 0 to the maximum terrain length.

Return value

Height of the point.

virtual float getHeight (float x, float y) const =0

Returns interpolated height of a given terrain point.

Arguments

• float x - X coordinate of the point.
• float y - Y coordinate of the point.

Return value

Interpolated height value of the point.

virtual int setHeights (int x, int y, const ImagePtr & image) const =0

Imports a height map for the terrain.

Arguments

• int x - X coordinate of the point on the terrain grid in range from 0 to the maximum terrain width.
• int y - Y coordinate of the point on the terrain grid in range from 0 to the maximum terrain length.
• const ImagePtr & image - Height map. The following formats are acceptable: R8, RG8, R16.

Return value

Returns 1 if the height map is imported successfully; otherwise, 0.

virtual int getHeights (int x, int y, int width, int height, const ImagePtr & image) const =0

Exports a height map into an R16 image. The sum of the X coordinate of the point on the terrain grid and width of the exported image must be less than or equal to the maximum terrain width. The sum of the Y coordinate of the point on the terrain grid and height of the exported image must be less than or equal to the maximum terrain length.

Arguments

• int x - X coordinate of the point on the terrain grid.
• int y - Y coordinate of the point on the terrain grid.
• int width - Width of the exported image in grid points.
• int height - Height of the exported image in grid points.
• const ImagePtr & image - Image to export a height map into.

Return value

Returns 1 if the height map is exported successfully; otherwise, 0.

virtual void setHole (int x, int y, int hole) const =0

Adds or removes a hole at a given terrain point.

Arguments

• int x - X coordinate of the point on the terrain grid.
• int y - Y coordinate of the point on the terrain grid.
• int hole - 1 to add a hole; 0 to remove a hole.

virtual int getHole (int x, int y) const =0

Returns a value indicating if there is a hole at a given point.

Arguments

• int x - X coordinate of the point on the terrain grid in range from 0 to the maximum terrain width.
• int y - Y coordinate of the point on the terrain grid in range from 0 to the maximum terrain length.

Return value

Returns 1 if there is a hole at a given point; otherwise, 0.

virtual int getHole (float x, float y) const =0

Returns a value indicating if there is a hole at a given point.

Arguments

• float x - X coordinate of the point on the terrain grid in range from 0 to the maximum terrain width.
• float y - Y coordinate of the point on the terrain grid in range from 0 to the maximum terrain length.

Return value

Returns 1 if there is a hole at a given point; otherwise, 0.

virtual int setHoles (int x, int y, const ImagePtr & image) const =0

Imports a holes texture for the terrain.

Arguments

• int x - X coordinate of the point on the terrain grid in range from 0 to the maximum terrain width.
• int y - X coordinate of the point on the terrain grid in range from 0 to the maximum terrain length.
• const ImagePtr & image - Holes texture. Only R8 format is acceptable.

Return value

Returns 1 if the holes texture is imported successfully; otherwise, 0.

virtual int getHoles (int x, int y, int width, int height, const ImagePtr & image) const =0

Exports a holes texture into an R8 image. The sum of the X coordinate of the point on the terrain grid and width of the exported image must be less than or equal to the maximum terrain width. The sum of the Y coordinate of the point on the terrain grid and height of the exported image must be less than or equal to the maximum terrain length.

Arguments

• int x - X coordinate of the point on the terrain grid.
• int y - Y coordinate of the point on the terrain grid.
• int width - Width of the exported image in grid points.
• int height - Height of the exported image in grid points.
• const ImagePtr & image - Image to export a holes texture into.

Return value

Returns 1 if the holes texture is exported successfully; otherwise, 0.

virtual vec3 getNormal (int x, int y) const =0

Returns a normal vector at a given terrain point.

Arguments

• int x - X coordinate of the point on the terrain grid in range from 0 to the maximum terrain width.
• int y - Y coordinate of the point on the terrain grid in range from 0 to the maximum terrain length.

Return value

Normal vector.

virtual vec3 getNormal (float x, float y) const =0

Returns a normal vector at a given terrain point.

Arguments

• float x - X coordinate of the point on the terrain grid in range from 0 to the maximum terrain width.
• float y - Y coordinate of the point on the terrain grid in range from 0 to the maximum terrain length.

Return value

Normal vector.

virtual int getNormals (int x, int y, int width, int height, const ImagePtr & image) const =0

Exports a normal map into an RG8 image. The sum of the X coordinate of the point on the terrain grid and width of the exported image must be less than or equal to the maximum terrain width. The sum of the Y coordinate of the point on the terrain grid and height of the exported image must be less than or equal to the maximum terrain length.

Arguments

• int x - X coordinate of the point on the terrain grid.
• int y - Y coordinate of the point on the terrain grid.
• int width - Width of the exported image in grid points.
• int height - Height of the exported image in grid points.
• const ImagePtr & image - Image to export a normal map into.

Return value

Returns 1 if the normal map is exported successfully; otherwise, 0.

virtual int getPoint (float x, float y, float & height, vec3 & normal) const =0

Searches for a given point on the terrain grid.

Arguments

• float x - X coordinate of the point on the terrain grid.
• float y - Y coordinate of the point on the terrain grid.
• float & height - Height of the point.
• vec3 & normal - Normal vector.

Return value

Returns 1 if the point is found; 0 if the given point is a hole or it is out of the terrain.