Class TCODHeightMap¶

Defined in File heightmap.hpp

Class Documentation¶

class TCODHeightMap¶

This toolkit allows one to create a 2D grid of float values using various algorithms.

The code using the heightmap toolkit can be automatically generated with the heightmap tool (hmtool) included in the libtcod package.

Public Functions

TCODHeightMap(int width, int height)¶

As with other modules, you have to create a heightmap object first : Note that whereas most other modules use opaque structs, the TCOD_heightmap_t fields can be freely accessed.

Thus, the TCOD_heightmap_new function returns a TCOD_heightmap_t pointer, not a TCOD_heightmap_t. The w and h fields should not be modified after the heightmap creation. The newly created heightmap is filled with 0.0 values.

typedef struct { int w,h; float *values; } TCOD_heightmap_t; TCOD_heightmap_t *TCOD_heightmap_new(int w,int h)

map=libtcod.heightmap_new(50,50) print map.w, map.h

Parameters: w, h – The width and height of the heightmap.

virtual ~TCODHeightMap()¶

To release the resources used by a heightmap, destroy it with :

Parameters: hm – In the C version, the address of the heightmap struct returned by the creation function.

inline void setValue(int x, int y, float v)¶

Once the heightmap has been created, you can do some basic operations on the values inside it. You can set a single value :

Those are simple operations applied either on a single map cell or on every map cell.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
x, y – Coordinates of the cells to modify inside the map. 0 <= x < map width 0 <= y < map height
value – The new value of the map cell.

void add(float f)¶

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
value – Value to add to every cell.

void scale(float f)¶

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
value – Every cell’s value is multiplied by this value.

void clear()¶

Parameters: hm – In the C version, the address of the heightmap struct returned by the creation function.

void clamp(float min, float max)¶

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
min, max – Every cell value is clamped between min and max. min < max

void copy(const TCODHeightMap *source)¶

Parameters

source – Each cell value from the source heightmap is copied in the destination (this for C++) heightmap. The source and destination heightmap must have the same width and height.
dest – In the C and Python versions, the address of the destination heightmap.

void normalize(float newMin = 0.0f, float newMax = 1.0f)¶

void TCODHeightMap::normalize() void TCODHeightMap::normalize(float min) void TCODHeightMap::normalize(float min, float max)

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
min, max – The whole heightmap is translated and scaled so that the lowest cell value becomes min and the highest cell value becomes max min < max

void lerp(const TCODHeightMap *a, const TCODHeightMap *b, float coef)¶

Parameters

a – First heightmap in the lerp operation.
b – Second heightmap in the lerp operation.
coef – lerp coefficient. For each cell in the destination map (this for C++), value = a.value + (b.value - a.value) * coef
res – In the C and Python versions, the address of the destination heightmap.

void add(const TCODHeightMap *a, const TCODHeightMap *b)¶

Parameters

a – First heightmap.
b – Second heightmap. For each cell in the destination map (this for C++), value = a.value + b.value
res – In the C and Python versions, the address of the destination heightmap.

void multiply(const TCODHeightMap *a, const TCODHeightMap *b)¶

Parameters

a – First heightmap.
b – Second heightmap. For each cell in the destination map (this for C++), value = a.value * b.value
res – In the C and Python versions, the address of the destination heightmap.

void addHill(float x, float y, float radius, float height)¶

This function adds a hill (a half spheroid) at given position.

Those are advanced operations involving several or all map cells.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
x, y – Coordinates of the center of the hill. 0 <= x < map width 0 <= y < map height
radius – The hill radius.
height – The hill height. If height == radius or -radius, the hill is a half-sphere.

void digHill(float hx, float hy, float h_radius, float height)¶

This function takes the highest value (if height > 0) or the lowest (if height < 0) between the map and the hill.

It’s main goal is to carve things in maps (like rivers) by digging hills along a curve.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
x, y – Coordinates of the center of the hill. 0 <= x < map width 0 <= y < map height
radius – The hill radius.
height – The hill height. Can be < 0 or > 0

void rainErosion(int nbDrops, float erosionCoef, float sedimentationCoef, TCODRandom *rnd)¶

This function simulates the effect of rain drops on the terrain, resulting in erosion patterns.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
nbDrops – Number of rain drops to simulate. Should be at least width * height.
erosionCoef – Amount of ground eroded on the drop’s path.
sedimentationCoef – Amount of ground deposited when the drops stops to flow
rnd – RNG to use, NULL for default generator.

void kernelTransform(int kernelSize, const int *dx, const int *dy, const float *weight, float minLevel, float maxLevel)¶

This function allows you to apply a generic transformation on the map, so that each resulting cell value is the weighted sum of several neighbour cells.

This can be used to smooth/sharpen the map. See examples below for a simple horizontal smoothing kernel : replace value(x,y) with 0.33*value(x-1,y) + 0.33*value(x,y) + 0.33*value(x+1,y).To do this, you need a kernel of size 3 (the sum involves 3 surrounding cells). The dx,dy array will contain : dx=-1,dy = 0 for cell x-1,y dx=1,dy=0 for cell x+1,y dx=0,dy=0 for current cell (x,y) The weight array will contain 0.33 for each cell.

int dx [] = {-1,1,0}; int dy[] = {0,0,0}; float weight[] = {0.33f,0.33f,0.33f}; TCOD_heightMap_kernel_transform(heightmap,3,dx,dy,weight,0.0f,1.0f);

int dx [] = {-1,1,0}; int dy[] = {0,0,0}; float weight[] = {0.33f,0.33f,0.33f}; heightmap->kernelTransform(heightmap,3,dx,dy,weight,0.0f,1.0f);

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function. kernelSize Number of neighbour cells involved.
dx, dy – Array of kernelSize cells coordinates. The coordinates are relative to the current cell (0,0) is current cell, (-1,0) is west cell, (0,-1) is north cell, (1,0) is east cell, (0,1) is south cell, …
weight – Array of kernelSize cells weight. The value of each neighbour cell is scaled by its corresponding weight
minLevel – The transformation is only applied to cells which value is >= minLevel.
maxLevel – The transformation is only applied to cells which value is <= maxLevel.

void addVoronoi(int nbPoints, int nbCoef, const float *coef, TCODRandom *rnd)¶

This function adds values from a Voronoi diagram to the map.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
nbPoints – Number of Voronoi sites.
nbCoef – The diagram value is calculated from the nbCoef closest sites.
coef – The distance to each site is scaled by the corresponding coef. Closest site : coef[0], second closest site : coef[1], …
rnd – RNG to use, NULL for default generator.

void addFbm(TCODNoise *noise, float mul_x, float mul_y, float add_x, float add_y, float octaves, float delta, float scale)¶

This function adds values from a simplex fbm function to the map.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
noise – The 2D noise to use.
mul_x, mul_y – / add_x, add_y The noise coordinate for map cell (x,y) are (x + add_x)*mul_x / width , (y + add_y)*mul_y / height. Those values allow you to scale and translate the noise function over the heightmap.
octaves – Number of octaves in the fbm sum.
delta – / scale The value added to the heightmap is delta + noise * scale.
noise – is between -1.0 and 1.0

void scaleFbm(TCODNoise *noise, float mul_x, float mul_y, float add_x, float add_y, float octaves, float delta, float scale)¶: This function works exactly as the previous one, but it multiplies the resulting value instead of adding it to the heightmap.

void digBezier(int px[4], int py[4], float startRadius, float startDepth, float endRadius, float endDepth)¶

This function carve a path along a cubic Bezier curve using the digHill function.

Could be used for roads/rivers/… Both radius and depth can vary linearly along the path.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
px, py – The coordinates of the 4 Bezier control points.
startRadius – The path radius in map cells at point P0. Might be < 1.0
startDepth – The path depth at point P0.
endRadius – The path radius in map cells at point P3. Might be < 1.0
endDepth – The path depth at point P3.

inline float getValue(int x, int y) const¶

This function returns the height value of a map cell.

Those functions return raw or computed information about the heightmap.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
x, y – Coordinates of the map cell. 0 <= x < map width 0 <= y < map height

float getInterpolatedValue(float x, float y) const¶

This function returns the interpolated height at non integer coordinates.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
x, y – Coordinates of the map cell. 0 <= x < map width 0 <= y < map height

float getSlope(int x, int y) const¶

This function returns the slope between 0 and PI/2 at given coordinates.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
x, y – Coordinates of the map cell. 0 <= x < map width 0 <= y < map height

void getNormal(float x, float y, float n[3], float waterLevel = 0.0f) const¶

This function returns the map normal at given coordinates.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
x, y – Coordinates of the map cell. 0 <= x < map width 0 <= y < map height
n – The function stores the normalized normal vector in this array.
waterLevel – The map height is clamped at waterLevel so that the sea is flat.

int countCells(float min, float max) const¶

This function returns the number of map cells which value is between min and max.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
min, max – Only cells which value is >=min and <= max are counted.

bool hasLandOnBorder(float waterLevel) const¶

This function checks if the cells on the map border are below a certain height.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
waterLevel – Return true only if no border cell is > waterLevel.

void getMinMax(float *min, float *max) const¶

This function calculates the min and max of all values inside the map.

Parameters

hm – In the C version, the address of the heightmap struct returned by the creation function.
min, max – The min and max values are returned in these variables.

void midPointDisplacement(TCODRandom *rnd = NULL, float roughness = 0.45f)¶

This algorithm generates a realistic fractal heightmap using the diamond-square (or random midpoint displacement) algorithm.

The roughness range should be comprised between 0.4 and 0.6. The image below show the same map with roughness varying from 0.4 to 0.6.

It’s also a good habit to normalize the map after using this algorithm to avoid unexpected heights.

Parameters

hm – In the C and Python version, the address of the heightmap struct returned by the creation function.
rng – Random number generation to use, or NULL/0 to use the default one.
roughness – Map roughness.

void islandify(float seaLevel, TCODRandom *rnd)¶

Public Members

int w¶

int h¶

float *values¶