Unigine::ObjectTerrain Class

ObjectTerrain Class

Members

---

static ObjectTerrainPtr create()

Constructor. Creates a new terrain object with default properties.

static ObjectTerrainPtr create(const char * name)

Constructor. Creates a new terrain object from a given file.

Arguments

• const char * name - Name of the terrain file.

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

Casts an ObjectTerrain out of the Node instance.

Arguments

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

Return value

Pointer to ObjectTerrain.

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

Casts an ObjectTerrain out of the Object instance.

Arguments

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

Return value

Pointer to ObjectTerrain.

Ptr<Texture> getAlbedoTexture()

Returns the terrain base albedo texture.

Return value

Terrain base albedo texture.

Ptr<Texture> getAlbedoTextureArray()

Returns the terrain base albedo texture array.

Return value

Terrain base albedo texture array.

void setAlbedoTextureArrayName(const char * name)

Sets the name of the terrain base albedo texture array.

Arguments

• const char * name - Albedo texture array name.

const char * getAlbedoTextureArrayName()

Returns the name of the terrain base albedo texture array.

Return value

Albedo texture array name.

int setAlbedoTextureImage(const Ptr<Image> & image)

Sets the image of the terrain base albedo texture.

Arguments

• const Ptr<Image> & image - Albedo texture image to be set.

Return value

1 if albedo texture image was successfully set; otherwise, 0.

int getAlbedoTextureImage(const Ptr<Image> & image)

Writes the current terrain base albedo texture into the given buffer.

Arguments

• const Ptr<Image> & image - Image buffer to write a texture into.

Return value

1 if the texture was successfully written to a buffer; otherwise, 0.

void setAlbedoTextureName(const char * name)

Sets the name of the terrain base albedo texture.

Arguments

• const char * name - Albedo texture name.

const char * getAlbedoTextureName()

Returns the name of the terrain base albedo texture.

Return value

Albedo texture name.

void setHeight(int x, int y, float height)

Changes the 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.

float getHeight(float x, float y)

Returns the height of a given terrain point.

Arguments

• float x - Interpolated height value between two points.
• float y - Interpolated height value between two points.

Return value

Height value.

float getHeight(int x, int y)

Returns the height of a given terrain point.

Arguments

• int x - X coordinate of the point (exact grid point).
• int y - Y coordinate of the point (exact grid point).

Return value

Height value.

int setHeights(int x, int y, const Ptr<Image> & image, float scale = 1.0f)

Imports a new 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 Ptr<Image> & image - Height map. The following formats are supported: R8, RG8, RGB8, R16, R16F, R32F.
• float scale - Height map scale.

Return value

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

int getHeights(int x, int y, int width, int height, const Ptr<Image> & image, int format, float scale = 1.0f)

Exports a height map into the R16 image. The sum of the X coordinate of the point on the terrain grid and the 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 the 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 Ptr<Image> & image - Image to export a height map into.
• int format - Image format. The following formats are supported: R8, RG8, RGB8, R16, R16F, R32F.
• float scale - Height map scale.

Return value

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

Ptr<Texture> getHeightTextureArray()

Returns the terrain base height texture array.

Return value

Terrain base height texture array.

void setHeightTextureArrayName(const char * name)

Sets the name of the terrain base height texture array.

Arguments

• const char * name - Height texture array name.

const char * getHeightTextureArrayName()

Returns the name of the terrain base height texture array.

Return value

Height texture array name.

void setHole(int x, int y, int hole)

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.

int getHole(float x, float y)

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

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

int getHole(int x, int y)

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

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

int setHoles(int x, int y, const Ptr<Image> & image)

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 - Y coordinate of the point on the terrain grid in range from 0 to the maximum terrain length.
• const Ptr<Image> & image - Holes texture. Only R8 format is acceptable.

Return value

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

int getHoles(int x, int y, int width, int height, const Ptr<Image> & image)

Exports a holes texture into the R8 image. The sum of the X coordinate of the point on the terrain grid and the 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 the 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 Ptr<Image> & image - Image to export a holes texture into.

Return value

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

void setLayerEnabled(int layer, int enable)

Enables or disables a given layer.

Arguments

• int layer - Target layer ID.
• int enable - 1 to enable a layer; 0 to disable it.

int getLayerEnabled(int layer)

Returns a value indicating if a given layer is enabled.

Arguments

• int layer - Target layer ID.

Return value

1 if a given layer is enabled; otherwise, 0.

void setLayerName(int layer, const char * name)

Sets the name for a given layer.

Arguments

• int layer - Target layer ID.
• const char * name - Layer name.

const char * getLayerName(int layer)

Sets the name for a given layer.

Arguments

• int layer - Target layer ID.

Return value

Layer name.

int isLoaded()

Returns a value indicating whether the terrain is loaded or not.

Return value

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

Math::vec3 getLocalPoint(const Math::Vec3 & position)

Returns the local coordinates of a given point.

Arguments

• const Math::Vec3 & position - World coordinates of the point.

Return value

Local coordinates of the point.

void setLodDistance(float distance)

Sets the distance to the first level of detail. The default value is 2.0.

Arguments

• float distance - Distance to the first LOD, in units.

float getLodDistance()

Returns the distance to the first level of detail. This distance is used to calculate distances to the rest of levels of details.

Return value

Distance to the first LOD, in units.

void setLodProgression(float progression)

Sets LOD Progression value. This distance is used to calculate distances to the rest of levels of details.

Arguments

• float progression - LOD Progression value.

float getLodProgression()

Returns LOD progression value. Default value is 2.0.

Return value

LOD Progression value.

void setLodTerrainBottom(const Ptr<ObjectTerrain> & bottom)

Sets the new bottom LOD for the current terrain.

Arguments

• const Ptr<ObjectTerrain> & bottom - Bottom terrain LOD.

Ptr<ObjectTerrain> getLodTerrainBottom()

Returns the bottom LOD of the current terrain.

Return value

Bottom terrain LOD.

void setLodTerrainLeft(const Ptr<ObjectTerrain> & left)

Sets the new left LOD for the current terrain.

Arguments

• const Ptr<ObjectTerrain> & left - Left terrain LOD.

Ptr<ObjectTerrain> getLodTerrainLeft()

Returns the left LOD of the current terrain.

Return value

Left terrain LOD.

void setLodTerrainRight(const Ptr<ObjectTerrain> & right)

Sets the new right LOD for the current terrain.

Arguments

• const Ptr<ObjectTerrain> & right - Right terrain LOD.

Ptr<ObjectTerrain> getLodTerrainRight()

Returns the right LOD of the current terrain.

Return value

Right terrain LOD.

void setLodTerrainTop(const Ptr<ObjectTerrain> & top)

Sets the new top LOD for the current terrain.

Arguments

• const Ptr<ObjectTerrain> & top - Top terrain LOD.

Ptr<ObjectTerrain> getLodTerrainTop()

Returns the top LOD of the current terrain.

Return value

Top terrain LOD.

void setLodThreshold(float threshold, int force = 0)

Sets the LOD height threshold.

Arguments

• float threshold - LOD height threshold.
• int force - Force flag. Terrain will load all height maps into the memory and will perform height map relaxation for the smooth LOD transition for the given threshold level.

float getLodThreshold()

Returns the LOD height threshold.

Return value

LOD height threshold.

Ptr<Texture> getMaskTexture()

Returns the terrain mask texture.

Return value

Mask texture.

int setMaskTextureImage(const Ptr<Image> & image)

Sets a new terrain mask texture from a given image.

Arguments

• const Ptr<Image> & image - Mask texture image to be set.

Return value

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

int getMaskTextureImage(const Ptr<Image> & image)

Writes the current terrain mask texture into the given buffer.

Arguments

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

Return value

1 if the texture mask has been successfully written into the buffer; otherwise, 0.

void setMaskTextureName(const char * name)

Sets the name of the terrain mask texture.

Arguments

• const char * name - Mask texture name.

const char * getMaskTextureName()

Returns the name of the current terrain mask texture.

Return value

Mask texture name.

void setMaterialAlbedoColor(int layer, int material, const Math::vec4 & color)

Sets the albedo color multiplier for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• const Math::vec4 & color - Material albedo color multiplier.

Math::vec4 getMaterialAlbedoColor(int layer, int material)

Returns the albedo color multiplier for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Material albedo color multiplier.

void setMaterialAlbedoScale(int layer, int material, float scale)

Sets the albedo scale for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• float scale - Material albedo scale.

float getMaterialAlbedoScale(int layer, int material)

Returns the albedo scale for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Material albedo scale.

void setMaterialAlbedoTextureName(int layer, int material, const char * name)

Sets the name of the albedo texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• const char * name - Material albedo texture name.

const char * getMaterialAlbedoTextureName(int layer, int material)

Returns the name of the albedo texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Material albedo texture name.

void setMaterialDetail(int layer, int material, int detail)

Sets a value indicating if a given material of a given layer uses its parent's material mask (or generates own mask on its basis) or the layer's mask (or generates own mask on its basis).

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• int detail - 1 to use the parent material mask (or generate own mask on its basis); 0 to use the layer's mask (or generate own mask on its basis).

int getMaterialDetail(int layer, int material)

Returns a value indicating if a given material of a given layer uses its parent's material mask (or generates own mask on its basis) or the layer's mask (or generates own mask on its basis).

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

1 if the parent's material mask is used; otherwise, 0.

void setMaterialEnabled(int layer, int material, int enable)

Enables or disables a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• int enable - 1 to enable a given material of a given layer; 0 to disable it.

int getMaterialEnabled(int layer, int material)

Returns a value indicating if a given material of a given layer is enabled.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

1 if a given material of a given layer is enabled; otherwise, 0

void setMaterialHeightTextureName(int layer, int material, const char * name)

Sets the name of the height texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• const char * name - Material height texture name.

const char * getMaterialHeightTextureName(int layer, int material)

Returns the name of the height texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Material height texture name.

void setMaterialLayer(int layer, int material, int layer_target)

Sets a new layer for a given material of a given layer.

Arguments

• int layer - Current layer ID.
• int material - Target material ID.
• int layer_target - New layer ID.

void setMaterialMaskThreshold(int layer, int material, float threshold)

Sets the blending threshold for a given material of a given layer. This parameter controls smoothness of blending. Higher values provide smoother results. Blending is performed according to the layer's mask.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• float threshold - Blending threshold value within the [0.0f; 1.0f] range.

float getMaterialMaskThreshold(int layer, int material)

Returns the blending threshold for a given material of a given layer. This parameter controls smoothness of blending. Higher values provide smoother results. Blending is performed according to the layer's mask.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Blending threshold value within the [0.0f; 1.0f] range.

void setMaterialMaskValue(int layer, int material, float value)

Sets the blending value for a given material of a given layer. This parameter controls the spread intensity of the layer. Lower values provide bigger spread. Blending is performed according to the layer's mask.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• float value - Blending value within the [0.0f; 1.0f] range.

float getMaterialMaskValue(int layer, int material)

Returns the blending value for a given material of a given layer. This parameter controls the spread intensity of the layer. Lower values provide bigger spread. Blending is performed according to the layer's mask.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Blending value within the [0.0f; 1.0f] range.

void setMaterialMaskWidth(int layer, int material, float width)

Sets the blending width for a given material of a given layer. This parameter controls the width of blending with a layer. Higher values provide wider areas. Blending is performed according to the layer's mask.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• float width - Blending width value within the [0.0f; 1.0f] range.

float getMaterialMaskWidth(int layer, int material)

Returns the blending width for a given material of a given layer. This parameter controls the width of blending with a layer. Higher values provide wider areas. Blending is performed according to the layer's mask.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Blending width value within the [0.0f; 1.0f] range.

void setMaterialName(int layer, int material, const char * name)

Sets the name of a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• const char * name - Material name.

const char * getMaterialName(int layer, int material)

Returns the name of a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Material name.

void setMaterialNormalScale(int layer, int material, float scale)

Sets the intensity scale of the normal texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• float scale - Material normal texture scale value within the [0.0f; 1.0f] range.

float getMaterialNormalScale(int layer, int material)

Returns the intensity scale of the normal texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Material normal scale value within the [0.0f; 1.0f] range.

void setMaterialNormalTextureName(int layer, int material, const char * name)

Sets the name of the normal texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• const char * name - Material normal texture name.

const char * getMaterialNormalTextureName(int layer, int material)

Returns the name of the normal texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Material normal texture name.

void setMaterialOverlap(int layer, int material, int overlap)

Enables or disables overlap blending mode for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• int overlap - 1 to enable overlap blending mode; 0 to disable it and use overlay mode.

int getMaterialOverlap(int layer, int material)

Returns a value indicating if overlap blending mode is enabled for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

1 if overlap blending mode for a given material is enabled; otherwise, 0.

void setMaterialRoughness(int layer, int material, float roughness)

Sets the roughness value multiplier for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• float roughness - Material roughness value multiplier within the [0.0f; 1.0f] range.

float getMaterialRoughness(int layer, int material)

Returns the roughness value multiplier for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Material roughness value multiplier within the [0.0f; 1.0f] range.

void setMaterialRoughnessScale(int layer, int material, float scale)

Sets the intensity scale of the roughness texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• float scale - Material roughness scale value within the [0.0f; 1.0f] range.

float getMaterialRoughnessScale(int layer, int material)

Returns the intensity scale of the roughness texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Material roughness scale value within the [0.0f; 1.0f] range.

void setMaterialRoughnessTextureName(int layer, int material, const char * name)

Sets the name of the roughness texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• const char * name - Material roughness texture name.

const char * getMaterialRoughnessTextureName(int layer, int material)

Returns the name of the roughness texture for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Material roughness texture name.

void setMaterialTransform(int layer, int material, const Math::vec4 & transform)

Sets the transformation parameters for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.
• const Math::vec4 & transform - Vec4 transformation vector with the following components:
  • X - Tiling X - tile of the textures along the X axis.
  • Y - Tiling Y - tile of the textures along the Y axis.
  • Z - Offset X - texture offset along the X axis.
  • W - Offset Y - texture offset along the Y axis.

Math::vec4 getMaterialTransform(int layer, int material)

Returns the transformation parameters for a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

Vec4 transformation vector with the following components:

• X - Tiling X - tile of the textures along the X axis.
• Y - Tiling Y - tile of the textures along the Y axis.
• Z - Offset X - texture offset along the X axis.
• W - Offset Y - texture offset along the Y axis.

Math::vec3 getNormal(float x, float y)

Returns the normal vector for 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.

Math::vec3 getNormal(int x, int y)

Returns the normal vector for 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.

int getNormals(int x, int y, int width, int height, const Ptr<Image> & image)

Exports a normal map into the RG8 image. The sum of the X coordinate of the point on the terrain grid and the 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 the 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 Ptr<Image> & image - Image to export a normal map into.

Return value

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

Ptr<Texture> getNormalTexture()

Returns the terrain normal texture.

Return value

Normal texture.

Ptr<Texture> getNormalTextureArray()

Returns the normal textures array.

Return value

Normal textures array.

void setNormalTextureArrayName(const char * name)

Sets the new name of the normal textures array.

Arguments

• const char * name - Name of the array.

const char * getNormalTextureArrayName()

Returns the name of the normal textures array.

Return value

Name of the array.

int setNormalTextureImage(const Ptr<Image> & image)

Sets a new terrain normal texture from a given image.

Arguments

• const Ptr<Image> & image - Texture image.

Return value

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

int getNormalTextureImage(const Ptr<Image> & image)

Writes the current terrain normal texture into the given buffer.

Arguments

• const Ptr<Image> & image - Image buffer to write a texture into.

Return value

1 if the texture has been successfully written into the buffer; otherwise, 0.

void setNormalTextureName(const char * name)

Sets the name of the terrain normal texture.

Arguments

• const char * name - Normal texture name.

const char * getNormalTextureName()

Returns the name of the current terrain normal texture.

Return value

Normal texture name.

int getNumAllMaterials()

Returns the total number of terrain materials.

Return value

Total number of terrain materials.

int getNumLayers()

Returns the total number of terrain layers.

Return value

Total number of terrain layers.

int getNumMaterials(int layer)

Returns the number of materials for a given layer.

Arguments

• int layer - Target layer ID.

Return value

Number of layer's materials.

void setShadowDistance(float distance)

Sets the Shadow distance parameter value (the distance up to which a terrain casts shadows).

Arguments

• float distance - Shadow distance, in units.

float getShadowDistance()

Returns the Shadow distance parameter value (the distance up to which a terrain casts shadows).

Return value

Shadow distance, in units.

int getSizeX()

Returns the terrain width along the X axis, in grid cells.

Return value

Terrain width along X axis.

int getSizeY()

Returns the terrain length along the Y axis, in grid cells.

Return value

Terrain length along Y axis.

float getStep()

Returns the linear size of a grid cell, in units.

Return value

Cell size.

Ptr<Texture> getSurfaceAlbedoTexture(int x, int y)

Returns the albedo texture for the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

Surface albedo texture.

int setSurfaceAlbedoTextureImage(int x, int y, const Ptr<Image> & image)

Sets the albedo texture image for the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• const Ptr<Image> & image - Albedo texture image.

int getSurfaceAlbedoTextureImage(int x, int y, const Ptr<Image> & image)

Writes the current surface albedo texture into the given buffer.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• const Ptr<Image> & image - Image buffer to write a texture into.

Return value

1 if the texture has been successfully written into the buffer; otherwise, 0.

void setSurfaceAlbedoTextureName(int x, int y, const char * name)

Sets the albedo texture name for the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• const char * name - Albedo texture name.

const char * getSurfaceAlbedoTextureName(int x, int y)

Returns the albedo texture name for the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

Albedo texture name.

BoundBox getSurfaceBoundBox(int x, int y)

Returns the bounding box of the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

Surface bounding box.

BoundSphere getSurfaceBoundSphere(int x, int y)

Returns the bounding sphere of the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

Surface bounding sphere.

void setSurfaceCastShadow(int x, int y, int cast_shadow)

Sets a value indicating whether terrain geometry across the specified surface should cast shadows (from all types of light sources).

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• int cast_shadow - 1 to cast shadows; 0 not to cast.

int isSurfaceCastShadow(int x, int y)

Returns a value indicating whether terrain geometry across the specified surface casts shadows (from all types of light sources).

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

1 if the surface casts shadows; otherwise, 0.

void setSurfaceEnabled(int x, int y, int enabled)

Sets a value indicating whether the specified surface is enabled or disabled for rendering.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• int enabled - Enabled flag. 1 to enable the surface; 0 to disable it.

int isSurfaceEnabled(int x, int y)

Returns a value indicating whether the specified surface is enabled or disabled for rendering.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

1 if the surface is enabled; otherwise, 0.

int getSurfaceIntersection(const Math::vec3 & p0, const Math::vec3 & p1, Math::vec3 * ret_point, Math::vec3 * ret_normal, Math::vec4 * ret_texcoord, int surface, int holes)

Performs the search for the intersection of the given terrain surface with the given traced line. Depending on the variable, passed as the third argument, the return value can be the intersection point, the intersection point normal or the intersection point texture coordinates.

Arguments

• const Math::vec3 & p0 - Start point coordinates.
• const Math::vec3 & p1 - End point coordinates.
• Math::vec3 * ret_point - Return array to write the intersection point coordinates into.
• Math::vec3 * ret_normal - Return array to write the intersection point normal into.
• Math::vec4 * ret_texcoord - Return array to write the intersection point texture coordinates into.
• int surface - Number of the surface.
• int holes - 0 is to return the intersection with a terrain even if it hits the hole; otherwise, 1.

Return value

1 if the intersection is found; otherwise - 0.

void setSurfaceLodThreshold(int x, int y, float threshold, int force = 0)

Sets the height threshold value for the LOD of the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• float threshold - Threshold of the surface LOD.
• int force - Force flag. The terrain will load all height maps into the memory and will perform a height map relaxation for the smooth LOD transition for the given threshold level.

float getSurfaceLodThreshold(int x, int y)

Returns the threshold value for the first LOD of the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

Threshold value.

Ptr<Texture> getSurfaceMaskTexture(int x, int y)

Returns the mask texture of the surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

Mask texture.

int setSurfaceMaskTextureImage(int x, int y, const Ptr<Image> & image)

Sets a mask texture image for the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• const Ptr<Image> & image - Surface mask texture image.

Return value

1 if the surface mask texture was successfully set; otherwise, 0.

int getSurfaceMaskTextureImage(int x, int y, const Ptr<Image> & image)

Writes the current mask texture of the specified surface into the given buffer.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• const Ptr<Image> & image - Image buffer to write a mask texture into.

Return value

1 if the mask texture has been successfully written into the buffer; otherwise, 0.

void setSurfaceMaskTextureName(int x, int y, const char * name)

Sets the mask texture name for the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• const char * name - Surface mask texture name.

const char * getSurfaceMaskTextureName(int x, int y)

Returns the mask texture name for the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

Surface mask texture name.

Ptr<Texture> getSurfaceNormalTexture(int x, int y)

Returns the normal texture of the surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

Normal texture.

int setSurfaceNormalTextureImage(int x, int y, const Ptr<Image> & image)

Sets a normal texture image for the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• const Ptr<Image> & image - Surface normal texture image to be set.

Return value

1 if the surface normal map was successfully set; otherwise, 0.

int getSurfaceNormalTextureImage(int x, int y, const Ptr<Image> & image)

Writes the current normal texture of the specified surface into the given buffer.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• const Ptr<Image> & image - Image buffer to write a texture into.

Return value

1 if the surface normal map was successfully written; otherwise, 0.

void setSurfaceNormalTextureName(int x, int y, const char * name)

Sets the normal texture name for the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.
• const char * name - Surface normal texture name.

const char * getSurfaceNormalTextureName(int x, int y)

Returns the normal texture name for the specified surface.

Arguments

• int x - Number of the surface along the X axis.
• int y - Number of the surface along the Y axis.

Return value

Surface normal texture name.

int getSurfacesX()

Returns the number of the surfaces along the X axis.

Return value

Number of the surfaces along the X axis.

int getSurfacesY()

Returns the number of the surfaces along the Y axis.

Return value

Number of the surfaces along the Y axis.

void setTerrainName(const char * name)

Sets the name for the terrain.

Arguments

• const char * name - Terrain name (path to the .TER file).

const char * getTerrainName()

Returns the current terrain name.

Return value

Terrain name (path to the .TER file).

int getTopologyData(float x, float y, Math::vec3 & point, Math::vec3 & normal, Math::vec3 & up, int force = 0)

Returns topology data for 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.
• Math::vec3 & point - World coordinates of the point.
• Math::vec3 & normal - Normal coordinates.
• Math::vec3 & up - "Up" vector coordinates.
• int force - Force flag. Use 1 to load the terrain height file in any case or generate default height values (-1); otherwise, 0.

Return value

1 if the topology data is retrieved successfully; otherwise, 0.

void setVisibleDistance(float distance)

Sets the distance up to which terrain is rendered visible. The terrain would disappear on a per-surface basis.

Arguments

• float distance - Visibility distance, in units.

float getVisibleDistance()

Returns the distance up to which terrain is rendered visible. The terrain would disappear on a per-surface basis.

Return value

Visibility distance, in units.

float getWorldHeight(const Math::Vec3 & position)

Returns the height of a given terrain point in world coordinates.

Arguments

• const Math::Vec3 & position - World coordinates of the point.

Return value

Height (Z-coordinate) in world coordinates.

int addLayer(const char * name)

Adds a new terrain layer. New layer is enabled by default.

Arguments

• const char * name - New layer name.

Return value

New total number of terrain layers.

int addMaterial(int layer, const char * name)

Adds a new terrain material to a given layer.

Arguments

• int layer - Target layer ID.
• const char * name - New material name.

Return value

Number of layer's materials.

void allocateLayers(int num)

Allocates memory for the specified number of layers. All layers are empty by default.

Arguments

• int num - Number of layers.

void allocateMaterials(int layer, int num)

Allocates memory for the specified number of materials of a given layer. All materials are initialized with default parameters.

Arguments

• int layer - Target layer ID.
• int num - Number of materials.

int cloneLayer(int layer)

Clones a given layer.

Arguments

• int layer - Target layer ID.

Return value

New number of terrain layers.

int cloneMaterial(int layer, int material)

Clones a given material of a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

Return value

New number of materials of a given layer.

int create(int size_x, int size_y, float step)

Creates a new terrain with the specified step from a loaded height map.

Arguments

• int size_x - Terrain width in grid cells along the X axis in range [257;32679], in units.
• int size_y - Terrain length in grid cells along the Y axis in range [257;32679], in units.
• float step - Step of terrain grid cell in units.

Return value

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

int create(const Ptr<Image> & image, float step, float scale = 1.0f)

Creates a new terrain with the specified step from a loaded height map.

Arguments

• const Ptr<Image> & image - Pointer to a height map.
• float step - A step of the terrain grid cell, in units.
• float scale - The maximum height value, in units.

Return value

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

int loadHeights(const BoundSphere & bs, const BoundBox & bb, int force = 0)

Sets a diffuse texture name for the specified layer.

Arguments

• const BoundSphere & bs - Bounding sphere (terrain-relative coordinate system).
• const BoundBox & bb - Bounding box (terrain-relative coordinate system).
• int force - Force data loading with possible stall.

int loadTerrain(const char * name)

Loads a terrain from a file.

Arguments

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

Return value

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

void removeLayer(int layer)

Removes a given layer.

Arguments

• int layer - Target layer ID.

void removeMaterial(int layer, int material)

Removes a given material from a given layer.

Arguments

• int layer - Target layer ID.
• int material - Target material ID.

int saveTerrain(const char * name, int force = 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 only if any changes were made.

Return value

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

void swapLayer(int layer_0, int layer_1)

Swaps given terrain layers.

Arguments

• int layer_0 - First layer ID.
• int layer_1 - Second layer ID.

void swapMaterial(int layer_0, int material_0, int layer_1, int material_1)

Swaps given terrain materials.

Arguments

• int layer_0 - Layer ID for the first material.
• int material_0 - First material ID.
• int layer_1 - Layer ID for the second material.
• int material_1 - Second material ID.

int type()

Returns the type of the object.

Return value

Object Terrain type identifier