libtcoddocumentation

1. Colors

The Doryen library uses 32bits colors. Thus, your OS desktop must use 32bits colors.
A color is defined by its red, green and blue component between 0 and 255.
You can use the following predefined colors (hover over a color to see its full name and R,G,B values):

STANDARD COLORS
desaturatedlightestlighterlightnormaldarkdarkerdarkest
red
flame
orange
amber
yellow
lime
chartreuse
green
sea
turquoise
cyan
sky
azure
blue
han
violet
purple
fuchsia
magenta
pink
crimson
METALLIC COLORS
brass
copper
gold
silver
MISCELLANEOUS COLORS
celadon
peach
GREYSCALE & SEPIA
 lightestlighterlightnormaldarkdarkerdarkest
grey 
sepia 
BLACK AND WHITE
black
white
Example:

TCODColor::desaturatedRed
TCODColor::lightestRed
TCODColor::lighterRed
TCODColor::lightRed
TCODColor::red
TCODColor::darkRed
TCODColor::darkerRed
TCODColor::darkestRed

TCOD_desaturated_red
TCOD_lightest_red
TCOD_lighter_red
TCOD_light_red
TCOD_red
TCOD_dark_red
TCOD_darker_red
TCOD_darkest_red

libtcod.desaturated_red
libtcod.lightest_red
libtcod.lighter_red
libtcod.light_red
libtcod.red
libtcod.dark_red
libtcod.darker_red
libtcod.darkest_red

TCODColor::desaturatedRed
TCODColor::lightestRed
TCODColor::lighterRed
TCODColor::lightRed
TCODColor::red
TCODColor::darkRed
TCODColor::darkerRed
TCODColor::darkestRed

tcod.color.desaturatedRed
tcod.color.lightestRed
tcod.color.lighterRed
tcod.color.lightRed
tcod.color.red
tcod.color.darkRed
tcod.color.darkerRed
tcod.color.darkestRed


Create your own colors

You can create your own colours using a set of constructors, both for RGB and HSV values.

Example:

TCODColor myColor(24,64,255); //RGB
TCODColor myOtherColor(321.0f,0.7f,1.0f);

TCOD_color_t my_color={24,64,255}; <span>/</span>* RGB *<span>/</span>
TCOD_color_t
my_other_color = TCOD_color_RGB(24,64,255); <span>/</span>* RGB too *<span>/</span>
TCOD_color_t
my_yet_another_color = TCOD_color_HSV(321.0f,0.7f,1.0f); <span>/</span>* HSV *<span>/</span>

my_color=libtcod.Color(24,64,255)

TCODColor myColor = new TCODColor(24,64,255); //RGB
         
TCODColor myColor = new TCODColor(321.0f,0.7f,1.0f);

myColor = tcod.Color(24,24,255)


Compare two colors

Example:

if (myColor == TCODColor::yellow) { ... }
if
(myColor != TCODColor::white) { ... }

if (TCOD_color_equals(my_color,TCOD_yellow)) { ... }
if
(!TCOD_color_equals(my_color,TCOD_white)) { ... }

if my_color == libtcod.yellow : ...
if
my_color != litbcod.white : ...

if (myColor.Equal(TCODColor.yellow)) { ... }
if (myColor.NotEqual(TCODColor.white)) { ... }

if myColor == tcod.color.yellow then ... end


Multiply two colors

c1 = c2 * c3 =>
c1.r = c2.r * c3.r / 255
c1.g = c2.g * c3.g / 255
c1.b = c2.b * c3.b / 255
darkishRed = darkGrey * red


Example:

TCODColor myDarkishRed = TCODColor::darkGrey * TCODColor::lightRed;

TCOD_color_t my_darkish_red = TCOD_color_multiply(TCOD_dark_grey, TCOD_light_red);

my_darkish_red = libtcod.dark_grey * libtcod.light_red

TCODColor myDarkishRed = TCODColor.darkGrey.Multiply(TCODColor.lightRed);

myDarkishRed = tcod.color.darkGrey * tcod.color.lightRed


Multiply a color by a float

c1 = c2 * v =>
c1.r = CLAMP(0, 255, c2.r * v)
c1.g = CLAMP(0, 255, c2.g * v)
c1.b = CLAMP(0, 255, c2.b * v)
darkishRed = red * 0.5



Example:

TCODColor myDarkishRed = TCODColor::lightRed * 0.5f;

TCOD_color_t my_darkish_red = TCOD_color_multiply_scalar(TCOD_light_red, 0.5f);

myDarkishRed = litbcod.light_red * 0.5

TCODColor myDarkishRed = TCODColor.lightRed.Multiply(0.5f);

myDarkishRed = tcod.color.lightRed * 0.5


Adding two colors

c1 = c1 + c2 => c1.r = MIN(255, c1.r + c2.r)
c1.g = MIN(255, c1.g + c2.g)
c1.b = MIN(255, c1.b + c2.b)
lightishRed = red + darkGrey


Example:

TCODColor myLightishRed = TCODColor::red + TCODColor::darkGrey

TCOD_color_t my_lightish_red = TCOD_color_add(TCOD_red, TCOD_dark_grey);

myLightishRed = libtcod.red + libtcod.dark_grey

TCODColor myLightishRed = TCODColor.red.Plus(TCODColor.darkGrey)

myLightishRed = tcod.color.red + tcod.color.darkGrey


Subtract two colors

c1 = c1 - c2 => c1.r = MAX(0, c1.r - c2.r)
c1.g = MAX(0, c1.g - c2.g)
c1.b = MAX(0, c1.b - c2.b)
redish = red - darkGrey


Example:

TCODColor myRedish = TCODColor::red - TCODColor::darkGrey

TCOD_color_t my_redish = TCOD_color_subtract(TCOD_red, TCOD_dark_grey);

myRedish = libtcod.red - libtcod.dark_grey

TCODColor myRedish = TCODColor.red.Minus(TCODColor.darkGrey)

myRedish = tcod.color.red - tcod.color.darkGrey


Interpolate between two colors

c1 = lerp (c2, c3, coef) => c1.r = c2.r + (c3.r - c2.r ) * coef
c1.g = c2.g + (c3.g - c2.g ) * coef
c1.b = c2.b + (c3.b - c2.b ) * coef
coef should be between 0.0 and 1.0 but you can as well use other values

coef == 0.0f
coef == 0.25f
coef == 0.5f
coef == 0.75f
coef == 1.0f

Example:

TCODColor myColor = TCODColor::lerp ( TCODColor::darkGrey, TCODColor::lightRed,coef );

TCOD_color_t my_color = TCOD_color_lerp ( TCOD_dark_grey, TCOD_light_red,coef);

my_color = libtcod.color_lerp ( libtcod.dark_grey, litbcod.light_red,coef)

TCODColor myColor = TCODColor.Interpolate( TCODColor.darkGrey, TCODColor.lightRed, coef );

myColor = tcod.color.Interpolate( tcod.color.darkGrey, tcod.color.lightRed, coef )


Define a color by its hue, saturation and value

After this function is called, the r,g,b fields of the color are calculated according to the h,s,v parameters.

void TCODColor::setHSV(float h, float s, float v)

void TCOD_color_set_HSV(TCOD_color_t *c,float h, float s, float v)

color_set_hsv(c,h,s,v)

void TCODColor::setHSV(float h, float s, float v)

Color:setHSV( h, s ,v )

ParameterDescription
cIn the C and python versions, the color to modify
h,s,vColor components in the HSV space
0.0 <= h < 360.0
0.0 <= s <= 1.0
0.0 <= v <= 1.0

Define a color's hue, saturation or lightness

These functions set only a single component in the HSV color space.

void TCODColor::setHue (float h)
void
TCODColor::setSaturation (float s)
void
TCODColor::setValue (float v)

void TCOD_color_set_hue (TCOD_color_t *c, float h)
void
TCOD_color_set_saturation (TCOD_color_t *c, float s)
void
TCOD_color_set_value (TCOD_color_t *c, float v)

Color:setHue(h)
Color:setSaturation(s)
Color:setValue(v)

ParameterDescription
h,s,vColor components in the HSV space
cIn the C and python versions, the color to modify

Get a color hue, saturation and value components

void TCODColor::getHSV(float *h, float *s, float *v) const

void TCOD_color_get_HSV(TCOD_color_t c,float * h, float * s, float * v)

color_get_HSV(c)

void TCODColor::getHSV(out float h, out float s, out float v)

Color:getHSV()

ParameterDescription
cIn the C and python versions, the TCOD_color_t from which to read.
h,s,vColor components in the HSV space
0.0 <= h < 360.0
0.0 <= s <= 1.0
0.0 <= v <= 1.0

Get a color's hue, saturation or value

Should you need to extract only one of the HSV components, these functions are what you should call. Note that if you need all three values, it's way less burdensome for the CPU to call TCODColor::getHSV().

float TCODColor::getHue ()
float
TCODColor::getSaturation ()
float
TCODColor::getValue ()

float TCOD_color_get_hue (TCOD_color_t c)
float
TCOD_color_get_saturation (TCOD_color_t c)
float
TCOD_color_get_value (TCOD_color_t c)

float TCODColor::getHue()
float
TCODColor::getSaturation()
float
TCODColor::getValue()

Color:getHue()
Color:getSaturation()
Color:getValue()

ParameterDescription
cthe TCOD_color_t from which to read

Shift a color's hue up or down

The hue shift value is the number of grades the color's hue will be shifted. The value can be negative for shift left, or positive for shift right.
Resulting values H < 0 and H >= 360 are handled automatically.

void TCODColor::shiftHue (float hshift)

void TCOD_color_shift_hue (TCOD_color_t *c, float hshift)

TCODColor::shiftHue(float hshift)

Color:shiftHue(hshift)

ParameterDescription
cThe color to modify
hshiftThe hue shift value

Scale a color's saturation and value

void TCODColor::scaleHSV (float sscale, float vscale)

void TCOD_color_scale_HSV (TCOD_color_t *c, float scoef, float vcoef)

color_scale_HSV(c, scoef, vcoef)

TCODColor::scaleHSV (float sscale, float vscale)

Color:scaleHSV(sscale,vscale)

ParameterDescription
cThe color to modify
sscalesaturation multiplier (1.0f for no change)
vscalevalue multiplier (1.0f for no change)

Generate a smooth color map

You can define a color map from an array of color keys. Colors will be interpolated between the keys.
0 -> black
4 -> red
8 -> white
Result :

map[0]
 black
map[1]
 
map[2]
 
map[3]
 
map[4]
 red
map[5]
 
map[6]
 
map[7]
 
map[8]
 white

static void genMap(TCODColor *map, int nbKey, TCODColor const *keyColor, int const *keyIndex)

void TCOD_gen_map(TCOD_color_t *map, int nb_key, TCOD_color_t const *key_color, int const *key_index)

color_gen_map(keyColor,keyIndex)

ParameterDescription
mapAn array of colors to be filled by the function.
nbKeyNumber of color keys
keyColorArray of nbKey colors containing the color of each key
keyIndexArray of nbKey integers containing the index of each key.
If you want to fill the map array, keyIndex[0] must be 0 and keyIndex[nbKey-1] is the number of elements in map minus 1 but you can also use the function to fill only a part of the map array.
Example:

int idx[] = { 0, 4, 8 }; // indexes of the keys
TCODColor col[] = { TCODColor( 0,0,0 ), TCODColor(255,0,0), TCODColor(255,255,255) }; // colors : black, red, white
TCODColor map[9];
TCODColor::genMap(map,3,col,idx);

int idx[] = { 0, 4, 8 }; // indexes of the keys
TCOD_color_t col[] = { { 0,0,0 }, {255,0,0}, {255,255,255} }; // colors : black, red, white
TCOD_color_t map[9];
TCOD_color_gen_map(map,3,col,idx);

idx = [ 0, 4, 8 ] # indexes of the keys
col = [ libtcod.Color( 0,0,0 ), libtcod.Color( 255,0,0 ), libtcod.Color(255,255,255) ] # colors : black, red, white
map=libtcod.color_gen_map(col,idx)