Xors3d Engine
Terrains

Functions

Entity * xCreateTerrain (int size, Entity *parent=NULL)
 Creates a terrain entity and returns its handle.
void xFreeTerrainTexture (TerrainTexture *texture)
 Frees the streaming terrain texture.
Entity * xLoadTerrain (const char *path, Entity *parent=NULL)
 Loads a terrain from an image file and returns the terrain's handle.
TerrainTexture * xLoadTerrainTexture (const char *path)
 Loads the streaming texture for terrains.
void xModifyTerrain (Terrain *terrain, int x, int y, float height, bool realtime=false)
 Sets the height of a point on a terrain.
void xTerrainDetail (Terrain *terrain, int detail)
 Sets the detail level for a terrain.
float xTerrainHeight (Terrain *terrain, int x, int y)
 Returns the height of the terrain at terrain grid coordinates x, z.
void xTerrainLODs (int lodsCount)
 Sets the number of LOD levels for the terrains.
void xTerrainShading (Terrain *terrain, bool state=false)
 Enables or disables terrain shading.
int xTerrainSize (Terrain *terrain)
 Returns terrain size.
void xTerrainSplatting (Terrain *terrain, bool state)
 Enables or disables terrain splatting.
void xTerrainTexture (Terrain *terrain, TerrainTexture *texture)
 Applies the streaming texture for the terrain.
void xTerrainTextureLightmap (TerrainTexture *texture, bool state)
 Enables or disables lightmap used for the streaming texture.
void xTerrainViewZone (Terrain *terrain, int viewZone, int texturingZone=-1)
 Sets a view zone for the streaming terrain.
float xTerrainX (Terrain *terrain, float x, float y, float z)
 Returns the interpolated x coordinate on a terrain.
float xTerrainY (Terrain *terrain, float x, float y, float z)
 Returns the interpolated y coordinate on a terrain.
float xTerrainZ (Terrain *terrain, float x, float y, float z)
 Returns the interpolated z coordinate on a terrain.

Function Documentation

Entity* xLoadTerrain ( const char *  path,
Entity *  parent = NULL 
)

Loads a terrain from an image file and returns the terrain's handle.

The image's red channel is used to determine heights. Terrain is initially the same width and depth as the image, and 1.0 unit high.

Tips on generating nice terrain:

Smooth or blur the height map

Reduce the y scale of the terrain

Increase the x/z scale of the terrain

Reduce the camera range

When texturing an entity, a texture with a scale of 1, 1, 1 (default) will cover the whole terrain.
The parent parameter allows you to specify a parent entity for the terrain so that when the parent is moved the child terrain will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent. Specifying a parent entity will still result in the terrain being created at position 0, 0, 0 rather than at the parent entity's position. A heightmaps dimensions (width and height) must be the same and must be a power of 2 (e.g. 64, 128, 256, 512, 1024) or a power of 2 + 1 (e.g. 65, 129, 257, 513, 1025).

Parameters:
pathFilename of image file to be used as height map
parentParent entity handle
Entity* xCreateTerrain ( int  size,
Entity *  parent = NULL 
)

Creates a terrain entity and returns its handle.

The terrain extends from 0, 0, 0 to size, 1, size. The parent parameter allows you to specify a parent entity for the terrain so that when the parent is moved the child terrain will move with it. However, this relationship is one way; applying movement commands to the child will not affect the parent. Specifying a parent entity will still result in the terrain being created at position 0, 0, 0 rather than at the parent entity's position.

Parameters:
sizeNumber of grid squares along each side of terrain, and must be a power of 2 value, e.g. 32, 64, 128, 256, 512, 1024
parentParent entity handle
void xTerrainShading ( Terrain *  terrain,
bool  state = false 
)

Enables or disables terrain shading.

Shaded terrains are a little slower than non-shaded terrains, and in some instances can increase the visibility. However, the option is there to have shaded terrains if you wish to do so.

Parameters:
terrainTerrain handle
stateTrue to enable terrain shading, false to to disable it. The default mode is false
float xTerrainHeight ( Terrain *  terrain,
int  x,
int  y 
)

Returns the height of the terrain at terrain grid coordinates x, z.

The value returned is in the range [0.0; 1.0].

Parameters:
terrainTerrain handle
xGrid x coordinate of terrain
yGrid y coordinate of terrain
int xTerrainSize ( Terrain *  terrain)

Returns terrain size.

Parameters:
terrainTerrain handle
float xTerrainX ( Terrain *  terrain,
float  x,
float  y,
float  z 
)

Returns the interpolated x coordinate on a terrain.

Parameters:
terrainTerrain handle
xWorld x coordinate
yWorld y coordinate
zWorld z coordinate
float xTerrainY ( Terrain *  terrain,
float  x,
float  y,
float  z 
)

Returns the interpolated y coordinate on a terrain.

Parameters:
terrainTerrain handle
xWorld x coordinate
yWorld y coordinate
zWorld z coordinate
float xTerrainZ ( Terrain *  terrain,
float  x,
float  y,
float  z 
)

Returns the interpolated z coordinate on a terrain.

Parameters:
terrainTerrain handle
xWorld x coordinate
yWorld y coordinate
zWorld z coordinate
void xModifyTerrain ( Terrain *  terrain,
int  x,
int  y,
float  height,
bool  realtime = false 
)

Sets the height of a point on a terrain.

Parameters:
terrainTerrain handle
xGrid x coordinate of terrain
yGrid y coordinate of terrain
heightHeight of point on terrain. Should be in the range [0.0; 1.0]
realtimeTrue to modify terrain immediately. False to modify terrain when xRenderWorld() in next called
void xTerrainDetail ( Terrain *  terrain,
int  detail 
)

Sets the detail level for a terrain.

Parameters:
terrainTerrain handle
detailTerrains detail level (default - 2048)
void xTerrainSplatting ( Terrain *  terrain,
bool  state 
)

Enables or disables terrain splatting.

Parameters:
terrainTerrain handle
stateTErrain splatting state
TerrainTexture* xLoadTerrainTexture ( const char *  path)

Loads the streaming texture for terrains.

Parameters:
pathTexture description file name
void xFreeTerrainTexture ( TerrainTexture *  texture)

Frees the streaming terrain texture.

Parameters:
textureStreaming texture handle
void xTerrainTextureLightmap ( TerrainTexture *  texture,
bool  state 
)

Enables or disables lightmap used for the streaming texture.

Parameters:
textureStreaming texture handle
stateLightmap using state
void xTerrainTexture ( Terrain *  terrain,
TerrainTexture *  texture 
)

Applies the streaming texture for the terrain.

Parameters:
terrainTerrain handle
textureStreaming texture handle
void xTerrainViewZone ( Terrain *  terrain,
int  viewZone,
int  texturingZone = -1 
)

Sets a view zone for the streaming terrain.

By default value is 1, so engine uses 3x3 zone, if you specify 2 engine will use 5x5 zone and so one.

Parameters:
terrainTerrain handle
viewZoneView zone size (1 by default)
texturingZoneTexturing zone size (-1 by default, use same value as viewZone)
void xTerrainLODs ( int  lodsCount)

Sets the number of LOD levels for the terrains.

This command must be called before you create any terrain

Parameters:
lodsCountNumber of terrain's LODs (5 by default)