TCODHeightMap Class Reference

#include <heightmap.hpp>

Public Member 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.
	TCODHeightMap (const TCODHeightMap &rhs)
TCODHeightMap &	operator= (const TCODHeightMap &rhs)
	TCODHeightMap (TCODHeightMap &&rhs)
TCODHeightMap &	operator= (TCODHeightMap &&rhs)
void	swap (TCODHeightMap &rhs) noexcept
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 :
void	add (float f)
void	scale (float f)
void	clear ()
void	clamp (float min, float max)
void	copy (const TCODHeightMap *source)
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)
void	lerp (const TCODHeightMap *a, const TCODHeightMap *b, float coef)
void	add (const TCODHeightMap *a, const TCODHeightMap *b)
void	multiply (const TCODHeightMap *a, const TCODHeightMap *b)
void	addHill (float x, float y, float radius, float height)
	This function adds a hill (a half spheroid) at given position.
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.
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.
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.
void	addVoronoi (int nbPoints, int nbCoef, const float *coef, TCODRandom *rnd)
	This function adds values from a Voronoi diagram to the map.
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.
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.
float	getValue (int x, int y) const
	This function returns the height value of a map cell.
float	getInterpolatedValue (float x, float y) const
	This function returns the interpolated height at non integer coordinates.
float	getSlope (int x, int y) const
	This function returns the slope between 0 and PI/2 at given coordinates.
void	getNormal (float x, float y, float n[3], float waterLevel=0.0f) const
	This function returns the map normal at given coordinates.
int	countCells (float min, float max) const
	This function returns the number of map cells which value is between min and max.
bool	hasLandOnBorder (float waterLevel) const
	This function checks if the cells on the map border are below a certain height.
void	getMinMax (float *min, float *max) const
	This function calculates the min and max of all values inside the map.
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.
void	islandify (float seaLevel, TCODRandom *rnd)

Public Attributes
int	w {}
int	h {}
float *	values {}

Detailed Description

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.

Constructor & Destructor Documentation

TCODHeightMap()

TCODHeightMap::TCODHeightMap ( int width, int height )

inline

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)

Parameters

w,h	The width and height of the heightmap.

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

Member Function Documentation

add() [1/2]

void TCODHeightMap::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.

add() [2/2]

void TCODHeightMap::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.

addFbm()

void TCODHeightMap::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

addHill()

void TCODHeightMap::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.

addVoronoi()

void TCODHeightMap::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.

clamp()

void TCODHeightMap::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

clear()

void TCODHeightMap::clear

(

)

Parameters

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

copy()

void TCODHeightMap::copy ( const TCODHeightMap * source )

inline

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.

countCells()

int TCODHeightMap::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.

digBezier()

void TCODHeightMap::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.

digHill()

void TCODHeightMap::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

getInterpolatedValue()

float TCODHeightMap::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

getMinMax()

void TCODHeightMap::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.

getNormal()

void TCODHeightMap::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.

getSlope()

float TCODHeightMap::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

getValue()

float TCODHeightMap::getValue ( int x, int y ) const

inline

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

hasLandOnBorder()

bool TCODHeightMap::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.

kernelTransform()

void TCODHeightMap::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.

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.

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);

lerp()

void TCODHeightMap::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.

midPointDisplacement()

void TCODHeightMap::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.

multiply()

void TCODHeightMap::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.

normalize()

void TCODHeightMap::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

rainErosion()

void TCODHeightMap::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.

scale()

void TCODHeightMap::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.

setValue()

void TCODHeightMap::setValue ( int x, int y, float v )

inline

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.

---

The documentation for this class was generated from the following file:

• C:/Users/4b796/Projects/libtcod/src/libtcod/heightmap.hpp