ObjectTerrain Class
This class is used to create terrains. The terrain is rendered using grid-based surfaces, each of which has has a unique diffuse texture, normal map and mask texture. They are automatically created when loading the full terrain size textures. Terrains also support holes.
ObjectTerrain Class
This class inherits from ObjectMembers
ObjectTerrain ()
Constructor. Creates a new terrain object with default properties.ObjectTerrain (string file_name)
Constructor. Creates a new terrain object from a given file.Arguments
- string file_name - Name of the terrain file.
int addMaterial (string name)
Adds a material to the terrain.Arguments
- string name - Name of the material.
Return value
Number of the added material.int addSurfaceMaterial (int x, int y, int num)
Adds a detail material to the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- int num - Material number.
Return value
Added material number in the list of ones assigned to the surface.void clearMaterials ()
Removes all detail materials.void clearSurfaceMaterials (int x, int y)
Removes all textures assigned to the current surface (i.e. patches of the diffuse texture, normal map and mask).Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
int create (Image image, float step, float height)
Creates a new terrain object basing on a height map.Arguments
- Image image - Height map.
- float step - Step of terrain grid cell in units.
- float height - Maximum height value. All height gradations will be written in range from 0 to 32768.
Return value
1 if the terrain was successfully created; otherwise, 0.int create (int size_x, int size_y, float step, float height)
Creates a new terrain object of the specified grid size.Arguments
- int size_x - Terrain width in grid cells along X axis.
- int size_y - Terrain length in grid cells along Y axis.
- float step - Step of terrain grid cell in units.
- float height - Maximum height value. All height gradations will be written in range from 0 to 32768.
Return value
1 if the terrain was successfully created; otherwise, 0.int getDiffuseTextureImage (Image image)
Writes the image that is currently used as a diffuse texture for a terrain into the given buffer.Arguments
- Image image - Image buffer to store a texture into.
Return value
1 if the texture image is successfully written into the buffer; otherwise, 0.string getDiffuseTextureName ()
Returns the name of the diffuse texture, which is used with the terrain.Return value
Name (path) of the diffuse texture.int getFlatnessThreshold ()
Returns the flatness threshold for subdividing plain or low height difference areas into less polygons (i.e. use higher LOD).Return value
Flatness threshold defining maximum height difference for LOD optimization.float getHeight ()
Returns the maximum height value of the terrain.Return value
Maximum height value.float getHeight (variable x, variable y)
Returns a height of a given terrain point.Arguments
- variable x - X coordinate of the point. Can be either int (exact grid point) or float (interpolated height value between two points).
- variable y - Y coordinate of the point. Must be of the same type as x.
Return value
Height.int getHeights (int x, int y, int width, int height, Image image)
Exports a height map into a R16 image.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.
- Image image - Image to export a height map into.
Return value
1 if the height map was successfully exported; otherwise, 0.int getHole (variable x, variable y)
Returns a value indicating if there is a hole at a given point.Arguments
- variable x - X-coordinate of the point. Can be either int or float.
- variable y - Y-coordinate of the point. Must be of the same type as x.
Return value
Positive number if there is a hole; otherwise, 0.int getHoles (int x, int y, int width, int height, Image image)
Exports a holes texture into a R8 image.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.
- Image image - Image to export a holes texture into.
Return value
1 if the holes texture was successfully exported; otherwise, 0.int getIntersection (vec3 point_0, vec3 point_1, int surface, int holes, int ret_id)
Traces a line from one point to another to find a terrain located on that line. Terrain local space coordinates are used for this function.Arguments
- vec3 point_0 - Start of the line (in the local coordinates).
- vec3 point_1 - End of the line (in the local coordinates).
- int surface - Surface number.
- int holes - Positive integer to take holes into account, 0 to intersect with terrain even if hole has occurred at that place.
- int ret_id - Return array, its components are:
- ret[0]: intersection point (vec3), in the local coordinates.
- ret[1]: normal of the intersection point (vec3).
- ret[2]: texture coordinates along X and Y axes (vec4, where Z and W values will always equal zero).
Return value
Return array ID.float getLodDistance ()
Returns a distance to the first level of details. This distance is used to calculate distances to the rest of levels of details.Return value
Base LOD distance in units.float getLodProgression ()
Returns LOD progression value. Default value is 2.0.Return value
LOD Progression value.int getMaskTextureImage (Image image)
Writes the image that is currently used as a mask for a terrain into the given buffer.Arguments
- Image image - Image buffer to store a mask into.
Return value
1 if the mask image is successfully written into the buffer; otherwise, 0.string getMaskTextureName ()
Returns a name of the the mask texture used for the whole terrain.Return value
Name (path) of the terrain mask texture.int getMaterialDetail (int num)
Returns a value indicating how a detail material is rendered (not rendered, rendered in an overlay or overlap mode). The default mode is overlayArguments
- int num - Material number.
Return value
Rendering flag for a detail material:float getMaterialDiffuseScale (int num)
Returns the visibility scale of a diffuse texture assigned to the specified detail material. The default is 0.5.Arguments
- int num - Material number.
Return value
Visibility scale of the diffuse texture.string getMaterialDiffuseTextureName (int num)
>Returns the diffuse texture name of the specified detail material.Arguments
- int num - Material number.
Return value
Diffuse texture name (path).string getMaterialName (int num)
Returns the name of the specified detail material.Arguments
- int num - Material number.
Return value
Material name.float getMaterialNormalScale (int num)
Returns the visibility scale of a normal map assigned to the specified detail material. The default is 0.5.Arguments
- int num - Material number.
Return value
Visibility scale of the normal map.string getMaterialNormalTextureName (int num)
>Returns the normal map name of the specified detail material.Arguments
- int num - Material number.
Return value
Normal map name (path).float getMaterialOverlapThreshold (int num)
Returns the blending threshold that controls the smoothness of blending for detail material edges. It is available only for materials on overlap mode. By 0 there is no blending; by 1, the blended area is at its maximum size. The default is 0.5.Arguments
- int num - Material number.
Return value
Blending threshold.float getMaterialOverlapValue (int num)
Returns the spread of a detail material according to the mask. It is available only for materials on overlap mode. By 0 the material is rendered everywhere; by 1, it is not rendered. The default is 0.5.Arguments
- int num - Material number.
Return value
Material spread value.vec4 getMaterialTransform (int num)
Returns the texture coordinate transformations of detail material textures (diffuse texture and normal map).Arguments
- int num - Material number.
Return value
Texture coordinates transformation of material textures (tile and offset).int getNormalTextureImage (Image image)
Writes the image that is currently used as a normal texture for a terrain into the given buffer.Arguments
- Image image - Image buffer to store a texture into.
Return value
1 if the texture image is successfully written into the buffer; otherwise, 0.string getNormalTextureName ()
Returns the name of the normal map texture, which is used with the terrain.Return value
Name (path) of the normal map texture.vec3 getNormal (int x, int y)
Returns a normal vector 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.
Return value
Normal vector if the operation was successful, otherwise - 0.vec3 getNormal (vec3 float v)
Returns a normal vector at a given terrain point.Arguments
- vec3 float v - Coordinates of the point on the terrain grid.
Return value
Normal vector if the operation was successful, otherwise - 0.int getNormals (int x, int y, int width, int height, Image image)
Exports a normal map into a RG8 image.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.
- Image image - Image to export a normal map into.
Return value
1 if the normal map was successfully exported; otherwise, 0.int getNumMaterials ()
Returns the total number of detail materials assigned to the terrain.Return value
The total number of terrain materials.int getNumSurfaceMaterials (int x, int y)
The total number of detail materials assigned to the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
The number of detail materials.vec3 getPoint (vec3 int i)
Returns the point on the terrain grid.Arguments
- vec3 int i - Point on the terrain grid.
Return value
Returns the point if it's found; otherwise, 0.float getShadowDistance ()
Returns the distance up to which the terrain relief will cast shadows.Return value
Shadow distance.float getShadowRadius ()
Returns the current distance to draw additional terrain polygons outside the view frustum. This option allows to eliminate popping of shadows at the edges of the screen when the camera is turning. The default is 0.Return value
Distance in units.int getSizeX ()
Returns terrain width in grid cells.Return value
Terrain width along X axis.int getSizeY ()
Returns terrain length in grid cells.Return value
Terrain length along Y axis.float getStep ()
Returns the linear size of a cell in units.Return value
Cell size in units.vec3 getSurfaceBoundCenter (int x, int y)
Returns the bounding sphere center coordinates for the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
Bounding sphere center.vec3 getSurfaceBoundMax (int x, int y)
Returns the bounding box maximum coordinates for the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
Bounding box maximum (by X, Y, and Z axes).vec3 getSurfaceBoundMin (int x, int y)
Returns the bounding box minimum for the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
Bounding box minimum (by X, Y, and Z axes).float getSurfaceBoundRadius (int x, int y)
Returns the bounding sphere radius for the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
Bounding sphere radius.int getSurfaceDiffuseTextureImage (int x, int y, Image image)
Exports a diffuse texture of the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- Image image - Image to export a surface diffuse texture into.
Return value
1 if the surface diffuse texture was successfully exported; otherwise, 0.string getSurfaceDiffuseTextureName (int x, int y)
Returns a diffuse texture name of the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
Name (path) of the surface diffuse texture.int getSurfaceFlatnessThreshold (int x, int y)
Returns the current flatness threshold for a given surface. It is used to subdivide plain or low height difference areas into less polygons (i.e. use higher LOD). By a surface threshold equal to -1 (by default), the common terrain's flatness threshold (set via setFlatnessThreshold()) is used.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
Flatness threshold that defines maximum height difference for LOD optimization.int getSurfaceMaskTextureImage (int x, int y, Image image)
Exports a mask texture of the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- Image image - Image to export a surface mask texture into.
Return value
1 if the surface mask texture was successfully exported; otherwise, 0.string getSurfaceMaskTextureName (int x, int y)
Returns a mask texture name of the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
Name (path) of the surface mask texture.int getSurfaceMaterial (int x, int y, int num)
Returns the number of detail material in the list of materials assigned to the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- int num - Material number.
Return value
Material number from the list of ones assigned to the surface.int getSurfaceNormalTextureImage (int x, int y, Image image)
Exports a normal map of the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- Image image - Image to export a surface normal map into.
Return value
1 if the surface normal map was successfully exported; otherwise, 0.string getSurfaceNormalTextureName (int x, int y)
Returns a normal map name of the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
Name (path) of the surface normal map.int getSurfacesX ()
Returns the number of terrain surfaces along the X axis.Return value
The number of surfaces along X axis.int getSurfacesY ()
Returns the number of terrain surfaces along the Y axis.Return value
The number of surfaces along Y axis.string getTerrainName ()
Returns a name of the terrain.Return value
Terrain name (path to the .TER file).float getVisibleDistance ()
Returns the distance up to which terrain is rendered visible. The terrain would disappear on per-surface basis.Return value
Visibility distance in units.int isLoaded ()
Returns a value indicating whether terrain is loaded.Return value
1 if the terrain is loaded; otherwise, 0.int isSurfaceCastShadow (int x, int y)
Returns a value indicating whether terrain geometry across the current surface casts shadows (from all types of light sources).Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
1 if the terrain is loaded; otherwise, 0.int isSurfaceEnabled (int x, int y)
Returns a value indicating whether a specified surface is enabled or disabled for rendering.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
1 if the surface is enabled; otherwise, 0.int isSurfaceTriplanar (int x, int y)
Returns a value indicating whether triplanar texturing (three planar projection for steep heights) is used on a specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
Return value
1 if triplanar texturing is used; otherwise, 0.int loadHeights (vec3 center, float radius, vec3 max, vec3 min, int force)
Allows to force the loading of the specified by the bounding box terrain region.Arguments
- vec3 center - Bounding box center.
- float radius - Bounding box radius.
- vec3 max - Maximum value of the bounding box points (along X, Y and Z axes respectively).
- vec3 min - Minimum value of the bounding box points (along X, Y and Z axes respectively).
- int force - 1 to force loading of the terrain region; otherwise - 0.
Return value
1 if the specified terrain region is loaded successfully; otherwise 0.int load (string name)
Loads a terrain from a file.Arguments
- string name - Path to the *.ter file.
Return value
1 if the terrain was successfully loaded; otherwise, 0.void removeMaterial (int num)
Removes the specified detail material.Arguments
- int num - Material number.
void removeSurfaceMaterial (int x, int y, int num)
Removes a detail material from the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- int num - Material number.
int save (string name, int force)
Force save of the terrain.Arguments
- string name - Name of the terrain.
- int force - 0 - save only if the changes have been made; 1 - save the the file in any case.
Return value
1 if the operation was successful; otherwise, 0.int setDiffuseTextureImage (Image Image)
Sets an image that will be used as a diffuse texture for a terrain.Arguments
- Image Image - Pointer to the image.
Return value
1 if the texture image is successfully set; otherwise, 0.void setDiffuseTextureName (string name)
Sets the name of a diffuse texture, which will be used with the terrain.Arguments
- string name - Name (path) of the diffuse texture.
void setFlatnessThreshold (int threshold)
Sets a flatness threshold for the whole terrain. It is used to subdivide plain or low height difference areas into less polygons (i.e. use higher LOD). The default is 0.Pre-surface threshold can also be set, if necessary.
Arguments
- int threshold - Flatness threshold defining maximum height difference for LOD optimization.
void setHeight (int grid_x, int grid_y, float height)
Changes height of a given terrain point.Arguments
- int grid_x - X coordinate of the point on the terrain grid.
- int grid_y - Y coordinate of the point on the terrain grid.
- float height - Height in units.
int setHeights (int x, int y, Image image)
Imports a height map for the terrain.Arguments
- int x - X coordinate of the point on the terrain grid.
- int y - Y coordinate of the point on the terrain grid.
- Image image - Height map.
Return value
1 if the height map was successfully set; otherwise, 0.void setHole (int grid_x, int grid_y, int hole)
Adds or removes holes to the terrain.Arguments
- int grid_x - X coordinate of the point on the terrain grid.
- int grid_y - Y coordinate of the point on the terrain grid.
- int hole - Positive number to add a hole, 0 to remove a hole.
int setHoles (int x, int y, Image image)
Imports a holes texture for the terrain.Arguments
- int x - X coordinate of the point on the terrain grid.
- int y - Y coordinate of the point on the terrain grid.
- Image image - Holes texture.
Return value
1 if the holes image was successfully set; otherwise, 0.void setLodDistance (float distance)
Sets a distance to the first level of details. This distance is used to calculate distances to the rest of levels of details.Arguments
- float distance - Base LOD distance in units.
void setLodProgression (float progression)
Sets LOD Progression value.Arguments
- float progression - LOD Progression value.
int setMaskTextureImage (Image Image)
Sets an image that will be used as a mask texture for a terrain.Arguments
- Image Image - Pointer to the image.
Return value
1 if the mask image is successfully set; otherwise, 0.void setMaskTextureName (string name)
Sets a mask texture name for the whole terrain.Arguments
- string name - Name (path) of the terrain mask texture.
void setMaterialDetail (int num, int detail)
Sets the rendering mode for a detail material (not rendered, overlay or overlap modes). The default mode is overlay.Arguments
- int num - Material number.
- int detail - Rendering flag for a detail material (one of OBJECT_TERRAIN_MATERIAL_* variables).
void setMaterialDiffuseScale (int num, float scale)
Sets the visibility scale of a diffuse texture assigned to the specified detail material. The default is 0.5.Arguments
- int num - Material number.
- float scale - Visibility scale of the diffuse texture. The provided value is saturated in range [0;1.0].
void setMaterialDiffuseTextureName (int num, string name)
Sets a diffuse texture name for the specified detail material.Arguments
- int num - Material number.
- string name - Diffuse texture name (path).
void setMaterialName (int num, string name)
Sets a new name for the detail material.Arguments
- int num - Material number.
- string name - Material name.
void setMaterialNormalScale (int num, float scale)
Sets the visibility scale of a normal map assigned to the specified detail material. The default is 0.5.Arguments
- int num - Material number.
- float scale - Visibility scale of the normal map. The provided value is saturated in range [0;1.0].
void setMaterialNormalTextureName (int num, string name)
Sets a normal map name for the specified detail material.Arguments
- int num - Material number.
- string name - Normal map name (path).
void setMaterialOverlapThreshold (int num, float threshold)
Sets the blending threshold that controls smoothness of blending for detail material edges. It is available only for materials on overlap mode. The default is 0.5.Arguments
- int num - Material number.
- float threshold - Blending threshold. It is clipped to the range [0;1]. By 0 there is no blending; by 1, the blended area is at its maximum size.
void setMaterialOverlapValue (int num, float value)
Sets the spread of detail material according to the mask. It is available only for materials on overlap mode. The default is 0.5.Arguments
- int num - Material number.
- float value - Material spread value. It is clipped to the range [0;1]. By 0 the material is rendered everywhere; by 1, it is not rendered.
void setMaterialTransform (int num, vec4 transform)
Sets the texture coordinate transformations for detail material textures (diffuse texture and normal map).Arguments
- int num - Material number.
- vec4 transform - Texture coordinates transformation of material textures (tile and offset).
int setNormalTextureImage (Image Image)
Sets an image that will be used as a normal texture for a terrain.Arguments
- Image Image - Pointer to the image.
Return value
1 if the texture image is successfully set; otherwise, 0.void setNormalTextureName (string name)
Sets the name of a normal map texture, which will be used with the terrain.Arguments
- string name - Name (path) of the normal map texture.
void setShadowDistance (float distance)
Sets the distance up to which the terrain relief will cast shadows.Arguments
- float distance - Shadow distance.
void setShadowRadius (float radius)
Sets the distance to draw additional terrain polygons outside the view frustum. This option allows to eliminate popping of shadows at the edges of the screen when the camera is turning. The default is 0.Arguments
- float radius - Distance in units. If a negative value is provided, 0 will be used instead.
void setSurfaceCastShadow (int x, int y, int cast_shadow)
Sets a value indicating whether terrain geometry across the current surface should cast shadows (from all types of light sources).Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- int cast_shadow - Positive value for terrain geometry to cast shadows; 0 not to cast.
int setSurfaceDiffuseTextureImage (int x, int y, Image image)
Imports a diffuse texture to the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- Image image - Surface diffuse texture image.
Return value
1 if the surface diffuse texture was successfully set; otherwise, 0.void setSurfaceDiffuseTextureName (int x, int y, string name)
Sets a diffuse texture name for the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- string name - Name (path) of the surface diffuse texture.
void setSurfaceEnabled (int x, int y, int enable)
Sets a value indicating whether a specified surface is enabled or disabled for rendering.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- int enable - Positive value to enable the surface; 0 to disable.
void setSurfaceFlatnessThreshold (int x, int y, int threshold)
Sets a flatness threshold for a given surface. It is used to subdivide plain or low height difference areas into less polygons (i.e. use higher LOD). By a surface threshold equal to -1 (by default), the common terrain's flatness threshold (set via setFlatnessThreshold()) is used.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- int threshold - Flatness threshold defining maximum height difference for LOD optimization. -1 means the common terrain threshold is used. If a lower value is provided, -1 will be used instead.
int setSurfaceMaskTextureImage (int x, int y, Image image)
Imports a mask texture to the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- Image image - Surface mask texture image.
Return value
1 if the surface mask texture was successfully set; otherwise, 0.void setSurfaceMaskTextureName (int x, int y, string name)
Sets a mask texture name for the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- string name - Name (path) of the surface mask texture.
int setSurfaceNormalTextureImage (int x, int y, Image image)
Imports a normal map to the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- Image image - Surface normal map image.
Return value
1 if the surface normal map was successfully set; otherwise, 0.void setSurfaceNormalTextureName (int x, int y, string name)
Sets a normal map name for the specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- string name - Name (path) of the surface normal map.
void setSurfaceTriplanar (int x, int y, int triplanar)
Sets a value indicating whether triplanar texturing (three planar projection for steep heights) is used on a specified surface.Arguments
- int x - Offset in surfaces along X axis.
- int y - Offset in surfaces along Y axis.
- int triplanar - Positive value to enable the triplanar texturing; 0 to disable.
void setTerrainName (string name)
Sets the name of the terrain.Arguments
- string name - Terrain name (path to the .TER file).
void setVisibleDistance (float distance)
Sets the distance up to which terrain is rendered visible. The terrain would disappear on per-surface basis.Arguments
- float distance - Visibility distance in units.
int OBJECT_TERRAIN_MATERIAL_NONE
Description
Skip rendering of a terrain detail material.int OBJECT_TERRAIN_MATERIAL_OVERLAP
Description
Overlap rendering mode for a terrain detail material.int OBJECT_TERRAIN_MATERIAL_OVERLAY
Description
Overlay rendering mode for a terrain detail material.Last update: 2017-07-03
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)