Colors

libtcod uses 32-bit color, therefore your OS desktop must also use 32-bit color. 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):

INSERT COLOUR TABLE IN A PAINLESS MANNER

Create your own colors

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

/* RGB */
TCOD_color_t my_color= { 24, 64, 255 };
TCOD_color_t my_other_color = TCOD_color_RGB(24, 64, 255);
/* HSV */
TCOD_color_t my_yet_another_color = TCOD_color_HSV(321.0f, 0.7f, 1.0f);
// RGB
TCODColor myColor(24, 64, 255);
// HSV
TCODColor myOtherColor(321.0f, 0.7f, 1.0f);
my_color = libtcod.Color(24, 64, 255)

Compare two colors

bool TCOD_color_equals(TCOD_color_t c1, TCOD_color_t c2)

Return a true value if c1 and c2 are equal.

Add and subtract Colors

TCOD_color_t TCOD_color_add(TCOD_color_t c1, TCOD_color_t c2)

Add two colors together and return the result.

Return
A new TCOD_color_t struct with the result.
Parameters
  • c1: The first color.
  • c2: The second color.

TCOD_color_t TCOD_color_subtract(TCOD_color_t c1, TCOD_color_t c2)

Subtract c2 from c1 and return the result.

Return
A new TCOD_color_t struct with the result.
Parameters
  • c1: The first color.
  • c2: The second color.

Multiply Colors together

TCOD_color_t TCOD_color_multiply(TCOD_color_t c1, TCOD_color_t c2)

Multiply two colors together and return the result.

Return
A new TCOD_color_t struct with the result.
Parameters
  • c1: The first color.
  • c2: The second color.

TCOD_color_t TCOD_color_multiply_scalar(TCOD_color_t c1, float value)

Multiply a color with a scalar value and return the result.

Return
A new TCOD_color_t struct with the result.
Parameters
  • c1: The color to multiply.
  • value: The scalar float.

Interpolate between two colors

TCOD_color_t TCOD_color_lerp(TCOD_color_t c1, TCOD_color_t c2, float coef)

Interpolate two colors together and return the result.

Return
A new TCOD_color_t struct with the result.
Parameters
  • c1: The first color (where coef if 0)
  • c2: The second color (where coef if 1)
  • coef: The coefficient.

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 TCOD_color_set_HSV(TCOD_color_t *color, float hue, float saturation, float value)

Sets a colors values from HSV values.

Parameters
  • color: The color to be changed.
  • hue: The colors hue (in degrees.)
  • saturation: The colors saturation (from 0 to 1)
  • value: The colors value (from 0 to 1)

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

void TCOD_color_set_hue(TCOD_color_t *color, float hue)

Change a colors hue.

Parameters
  • color: Pointer to a color struct.
  • hue: The hue in degrees.

void TCOD_color_set_saturation(TCOD_color_t *color, float saturation)

Change a colors saturation.

Parameters
  • color: Pointer to a color struct.
  • saturation: The desired saturation value.

void TCOD_color_set_value(TCOD_color_t *color, float value)

Change a colors value.

Parameters
  • color: Pointer to a color struct.
  • value: The desired value.

Get a color hue, saturation and value components

void TCOD_color_get_HSV(TCOD_color_t color, float *hue, float *saturation, float *value)

Get a set of HSV values from a color.

The hue, saturation, and value parameters can not be NULL pointers,

Parameters
  • color: The color
  • hue: Pointer to a float, filled with the hue. (degrees)
  • saturation: Pointer to a float, filled with the saturation. (0 to 1)
  • value: Pointer to a float, filled with the value. (0 to 1)

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 TCOD_color_get_hue(TCOD_color_t color)

Return a colors hue.

Return
The colors hue. (degrees)
Parameters
  • color: A color struct.

float TCOD_color_get_saturation(TCOD_color_t color)

Return a colors saturation.

Return
The colors saturation. (0 to 1)
Parameters
  • color: A color struct.

float TCOD_color_get_value(TCOD_color_t color)

Get a colors value.

Return
The colors value. (0 to 1)
Parameters
  • color: A color struct.

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 TCOD_color_shift_hue(TCOD_color_t *color, float hshift)

Shift a colors hue by an amount.

Parameters
  • color: Pointer to a color struct.
  • hue_shift: The distance to shift the hue, in degrees.

Scale a color’s saturation and value

void TCOD_color_scale_HSV(TCOD_color_t *color, float saturation_coef, float value_coef)

Scale a colors saturation and value.

Parameters
  • color: Pointer to a color struct.
  • saturation_coef: Multiplier for this colors saturation.
  • value_coef: Multiplier for this colors value.

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:

INSERT TABLE.

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

Generate an interpolated gradient of colors.

TCOD_color_t[256] gradient;
TCOD_color_t[4] key_color = {TCOD_black, TCOD_dark_amber,
                             TCOD_cyan, TCOD_white};
int[4] key_index = {0, 64, 192, 255};
TCOD_color_gen_map(&gradient, 4, &key_color, &key_index);
Parameters
  • map: Array to fill with the new gradient.
  • nb_key: The array size of the key_color and key_index parameters.
  • key_color: An array of colors to use, in order.
  • key_index: An array mapping key_color items to the map array.