Xors3d Engine
Terrains

Functions

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

Function Documentation

BBDECL Entity* BBCALL 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
BBDECL Entity* BBCALL 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
BBDECL void BBCALL 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
BBDECL float BBCALL 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
BBDECL int BBCALL xTerrainSize ( Terrain *  terrain)

Returns terrain size.

Parameters:
terrainTerrain handle
BBDECL float BBCALL 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
BBDECL float BBCALL 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
BBDECL float BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL xTerrainDetail ( Terrain *  terrain,
int  detail 
)

Sets the detail level for a terrain.

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

Enables or disables terrain splatting.

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

Loads the streaming texture for terrains.

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

Frees the streaming terrain texture.

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

Enables or disables lightmap used for the streaming texture.

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

Applies the streaming texture for the terrain.

Parameters:
terrainTerrain handle
textureStreaming texture handle
BBDECL void BBCALL 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)
BBDECL void BBCALL 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)