Color addon

These functions are declared in the following header file. Link with allegro_color.

 #include <allegro5/allegro_color.h>

When converting between certain color spaces, RGB colors are implicitly assumed to mean sRGB.

sRGB is a standard which maps RGB colors to absolute colors. sRGB is very close to RGB values on a monitor which has a gamma value of 2.2. For example when the red component of a color is 0.5, the monitor will use a brightness of pow(0.5, 2.2) or about 22% - and not 50%. The reason is that human eyes can distinguish better between dark colors than between bright colors, and so if a pixel of the monitor is lit up to 22% of its maximum power it already will appear at half brightness to a human eye.

sRGB improves upon simple gamma correction by taking differences between the three color channels into account as well. In general, most monitors nowadays try to be close to the sRGB specification. And so if in an Allegro game you display something with color

al_map_rgb_f(0.5, 0.5, 0,5)

then it will appear at about half brightness (even though the actual brightness output of the monitor will be less than half).

al_color_cmyk

ALLEGRO_COLOR al_color_cmyk(float c, float m, float y, float k)

Return an ALLEGRO_COLOR structure from CMYK values (cyan, magenta, yellow, black).

See also: al_color_cmyk_to_rgb, al_color_rgb_to_cmyk

Examples:

ex_color.cpp

al_color_cmyk_to_rgb

void al_color_cmyk_to_rgb(float cyan, float magenta, float yellow,
    float key, float *red, float *green, float *blue)

Convert CMYK values to RGB values.

See also: al_color_cmyk, al_color_rgb_to_cmyk

Examples:

ex_color.cpp

al_color_hsl

ALLEGRO_COLOR al_color_hsl(float h, float s, float l)

Return an ALLEGRO_COLOR structure from HSL (hue, saturation, lightness) values.

Parameters:

hue - Color hue angle in the range 0..360
saturation - Color saturation in the range 0..1
lightness - Color lightness in the range 0..1

See also: al_color_hsl_to_rgb, al_color_hsv

Examples:

al_color_hsl_to_rgb

void al_color_hsl_to_rgb(float hue, float saturation, float lightness,
   float *red, float *green, float *blue)

Convert values in HSL color model to RGB color model.

Parameters:

hue - Color hue angle in the range 0..360
saturation - Color saturation in the range 0..1
lightness - Color lightness in the range 0..1
red, green, blue - returned RGB values in the range 0..1

See also: al_color_rgb_to_hsl, al_color_hsl, al_color_hsv_to_rgb

Examples:

al_color_hsv

ALLEGRO_COLOR al_color_hsv(float h, float s, float v)

Return an ALLEGRO_COLOR structure from HSV (hue, saturation, value) values.

Parameters:

hue - Color hue angle in the range 0..360
saturation - Color saturation in the range 0..1
value - Color value in the range 0..1

See also: al_color_hsv_to_rgb, al_color_hsl

Examples:

al_color_hsv_to_rgb

void al_color_hsv_to_rgb(float hue, float saturation, float value,
   float *red, float *green, float *blue)

Convert values in HSV color model to RGB color model.

Parameters:

hue - Color hue angle in the range 0..360
saturation - Color saturation in the range 0..1
value - Color value in the range 0..1
red, green, blue - returned RGB values in the range 0..1

See also: al_color_rgb_to_hsv, al_color_hsv, al_color_hsl_to_rgb

Examples:

ex_color.cpp

al_color_html

ALLEGRO_COLOR al_color_html(char const *string)

Interprets an HTML-style hex number (e.g. #00faff) as a color. The accepted format is the same as al_color_html_to_rgb.

Returns the interpreted color, or al_map_rgba(0, 0, 0, 0) if the string could not be parsed.

Note: the behaviour on invalid strings is different from Allegro 5.0.x.

See also: al_color_html_to_rgb, al_color_rgb_to_html

al_color_html_to_rgb

bool al_color_html_to_rgb(char const *string,
   float *red, float *green, float *blue)

Interprets an HTML-style hex number (e.g. #00faff) as a color. The only accepted formats are “#RRGGBB” and “RRGGBB” where R, G, B are hexadecimal digits [0-9A-Fa-f].

Returns true on success, false on failure. On failure all components are set to zero.

Note: the behaviour on invalid strings is different from Allegro 5.0.x.

See also: al_color_html, al_color_rgb_to_html

al_color_rgb_to_html

void al_color_rgb_to_html(float red, float green, float blue,
    char *string)

Create an HTML-style string representation of an ALLEGRO_COLOR, e.g. #00faff.

Parameters:

red, green, blue - The color components in the range 0..1.
string - A pointer to a buffer of at least 8 bytes, into which the result will be written (including the NUL terminator).

Example:

char html[8];
al_color_rgb_to_html(1, 0, 0, html);

Now html will contain “#ff0000”.

See also: al_color_html, al_color_html_to_rgb

Examples:

ex_color.cpp

al_color_name

ALLEGRO_COLOR al_color_name(char const *name)

Return an ALLEGRO_COLOR with the given name. If the color is not found then black is returned.

See al_color_name_to_rgb for the list of names.

Examples:

al_color_name_to_rgb

bool al_color_name_to_rgb(char const *name, float *r, float *g, float *b)

Parameters:

name - The (lowercase) name of the color.
r, g, b - If one of the recognized color names below is passed, the corresponding RGB values in the range 0..1 are written.

The 148 recognized names are:

aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque, black, blanchedalmond, blue, blueviolet, brown, burlywood, cadetblue, chartreuse, chocolate, coral, cornflowerblue, cornsilk, crimson, cyan, darkblue, darkcyan, darkgoldenrod, darkgray, darkgreen, darkkhaki, darkmagenta, darkolivegreen, darkorange, darkorchid, darkred, darksalmon, darkseagreen, darkslateblue, darkslategray, darkturquoise, darkviolet, deeppink, deepskyblue, dimgray, dodgerblue, firebrick, floralwhite, forestgreen, fuchsia, gainsboro, ghostwhite, goldenrod, gold, gray, green, greenyellow, honeydew, hotpink, indianred, indigo, ivory, khaki, lavenderblush, lavender, lawngreen, lemonchiffon, lightblue, lightcoral, lightcyan, lightgoldenrodyellow, lightgreen, lightgrey, lightpink, lightsalmon, lightseagreen, lightskyblue, lightslategray, lightsteelblue, lightyellow, lime, limegreen, linen, magenta, maroon, mediumaquamarine, mediumblue, mediumorchid, mediumpurple, mediumseagreen, mediumslateblue, mediumspringgreen, mediumturquoise, mediumvioletred, midnightblue, mintcream, mistyrose, moccasin, avajowhite, navy, oldlace, olive, olivedrab, orange, orangered, orchid, palegoldenrod, palegreen, paleturquoise, palevioletred, papayawhip, peachpuff, peru, pink, plum, powderblue, purple, rebeccapurple, red, rosybrown, royalblue, saddlebrown, salmon, sandybrown, seagreen, seashell, sienna, silver, skyblue, slateblue, slategray, snow, springgreen, steelblue, tan, teal, thistle, tomato, turquoise, violet, wheat, white, whitesmoke, yellow, yellowgreen

They are taken from CSS: https://www.w3.org/TR/css-color-4/

Note that these 9 colors have two names and so there are only 139 distinct colors: aqua = cyan, darkgray = darkgrey, darkslategray = darkslategrey, dimgray = dimgrey, fuchsia = purple, gray = grey, lightgray = lightgrey, lightslategray = lightslategrey, slategray = slategrey

Returns: true if a name from the list above was passed, else false.

See also: al_color_name

al_color_rgb_to_cmyk

void al_color_rgb_to_cmyk(float red, float green, float blue,
   float *cyan, float *magenta, float *yellow, float *key)

Each RGB color can be represented in CMYK with a K component of 0 with the following formula:

C = 1 - R
M = 1 - G
Y = 1 - B
K = 0

This function will instead find the representation with the maximal value for K and minimal color components.

See also: al_color_cmyk, al_color_cmyk_to_rgb

Examples:

ex_color.cpp

al_color_rgb_to_hsl

void al_color_rgb_to_hsl(float red, float green, float blue,
   float *hue, float *saturation, float *lightness)

Given an RGB triplet with components in the range 0..1, return the hue in degrees from 0..360 and saturation and lightness in the range 0..1.

See also: al_color_hsl_to_rgb, al_color_hsl

Examples:

al_color_rgb_to_hsv

void al_color_rgb_to_hsv(float red, float green, float blue,
   float *hue, float *saturation, float *value)

Given an RGB triplet with components in the range 0..1, return the hue in degrees from 0..360 and saturation and value in the range 0..1.

See also: al_color_hsv_to_rgb, al_color_hsv

Examples:

al_color_rgb_to_name

char const *al_color_rgb_to_name(float r, float g, float b)

Given an RGB triplet with components in the range 0..1, find a color name describing it approximately.

See also: al_color_name_to_rgb, al_color_name

Examples:

ex_color.cpp

al_color_rgb_to_xyz

void al_color_rgb_to_xyz(float red, float green, float blue,
   float *x, float *y, float *z)

Convert RGB values to XYZ color space.

Since: 5.2.3

See also: al_color_xyz, al_color_xyz_to_rgb

al_color_xyz

ALLEGRO_COLOR al_color_xyz(float x, float y, float z)

Return an ALLEGRO_COLOR structure from XYZ values. The CIE 1931 XYZ color space consists of three components in the range 0..1. The Y component corresponds to luminance and the X and Z components define the color.

RGB components are always assumed to be in sRGB space.

Note:

The XYZ color space can represent more colors than are visible in sRGB and therefore conversion may result in RGB values outside of the 0..1 range. You can check for that case with al_is_color_valid.

Since: 5.2.3

See also: al_color_xyz_to_rgb, al_color_rgb_to_xyz

al_color_xyz_to_rgb

void al_color_xyz_to_rgb(float x, float y, float z,
    float *red, float *green, float *blue)

Convert XYZ color values to RGB color space.

Since: 5.2.3

See also: al_color_xyz, al_color_rgb_to_xyz

al_color_rgb_to_xyy

void al_color_rgb_to_xyy(float red, float green, float blue,
   float *x, float *y, float *y2)

Convert RGB values to xyY color space.

Since: 5.2.3

See also: al_color_xyy, al_color_xyy_to_rgb

al_color_xyy

ALLEGRO_COLOR al_color_xyy(float x, float y, float y2)

Return an ALLEGRO_COLOR structure from xyY values. The Y component in the xyY color space is the same as the Y in XYZ.

However the x and y values are computed from XYZ like this:

x = X / (X + Y + Z)
y = Y / (X + Y + Z)

Since: 5.2.3

See also: al_color_xyy_to_rgb, al_color_rgb_to_xyy

al_color_xyy_to_rgb

void al_color_xyy_to_rgb(float x, float y, float y2,
    float *red, float *green, float *blue)

Convert xyY color values to RGB color space.

Since: 5.2.3

See also: al_color_xyy, al_color_rgb_to_xyy

al_color_rgb_to_lab

void al_color_rgb_to_lab(float red, float green, float blue,
   float *l, float *a, float *b)

Convert RGB values to L*a*b* color space.

Since: 5.2.3

See also: al_color_lab, al_color_lab_to_rgb

Examples:

ex_color_gradient.c

al_color_lab

ALLEGRO_COLOR al_color_lab(float l, float a, float b)

Return an ALLEGRO_COLOR structure from CIE L*a*b* values. The L* component corresponds to luminance from 0..1. The a* and b* components are in the range -1..+1.

Note:

The L*a*b* color space can represent more colors than are visible in sRGB and therefore conversion may result in RGB values outside of the 0..1 range. You can check for that case with al_is_color_valid.

Note:

In some literature the range of L* is 0 to 100 and a* and b* are from -100 to +100. In that case divide all components by 100 before passing them to this function.

Since: 5.2.3

See also: al_color_lab_to_rgb, al_color_rgb_to_lab

Examples:

al_color_lab_to_rgb

void al_color_lab_to_rgb(float l, float a, float b,
    float *red, float *green, float *blue)

Convert CIE L*a*b* color values to RGB color space.

Since: 5.2.3

See also: al_color_lab, al_color_rgb_to_lab

Examples:

ex_color2.c

al_color_rgb_to_lch

void al_color_rgb_to_lch(float red, float green, float blue,
   float *l, float *c, float *h)

Convert RGB values to CIE LCH color space.

Since: 5.2.3

See also: al_color_lch, al_color_lch_to_rgb

Examples:

ex_color.cpp

al_color_lch

ALLEGRO_COLOR al_color_lch(float l, float c, float h)

Return an ALLEGRO_COLOR structure from CIE LCH values. LCH colors are very similar to HSL, with the same meaning of L and H and C corresponding to S. However LCH is more visually uniform. Furthermore, this function expects the angle for H in radians and not in degree.

The CIE LCH color space is a cylindrical representation of the L*a*b* color space. The L component is the same and C and H are computed like this:

C = sqrt(a * a + b * b)
H = atan2(b, a)

Since: 5.2.3

See also: al_color_lch_to_rgb, al_color_rgb_to_lch

Examples:

ex_color.cpp

al_color_lch_to_rgb

void al_color_lch_to_rgb(float l, float c, float h,
    float *red, float *green, float *blue)

Convert CIE LCH color values to RGB color space.

Since: 5.2.3

See also: al_color_lch, al_color_rgb_to_lch

Examples:

ex_color.cpp

al_color_distance_ciede2000

double al_color_distance_ciede2000(ALLEGRO_COLOR color1,
      ALLEGRO_COLOR color2) {

This function computes the CIEDE2000 color difference between two RGB colors. This is a visually uniform color difference, unlike for example the RGB distance.

When using the RGB distance (Euklidean distance between two RGB triplets) there can be color pairs with the same distance, where the colors of one pair appear to be almost the same color, while the colors of the other pair look quite different. This is improved by using the L*a*b* color space which was designed with perceptual uniformity in mind. However it still is not completely uniform. The CIEDE2000 formula contains some additional transformations to fix that.

The returned color distance is roughly in the range 0 (identical color) to 1 (completely different color) - but values greater than one are possible.

Note: This function uses al_color_lab internally which defines the L component to be in the range 0..1 (and not 0..100 as is sometimes seen).

Since: 5.2.3

Examples:

ex_color2.c

al_color_rgb_to_yuv

void al_color_rgb_to_yuv(float red, float green, float blue,
   float *y, float *u, float *v)

Convert RGB values to YUV color space.

See also: al_color_yuv, al_color_yuv_to_rgb

Examples:

ex_color.cpp

al_color_yuv

ALLEGRO_COLOR al_color_yuv(float y, float u, float v)

Return an ALLEGRO_COLOR structure from YUV values.

See also: al_color_yuv_to_rgb, al_color_rgb_to_yuv

Examples:

ex_color.cpp

al_color_yuv_to_rgb

void al_color_yuv_to_rgb(float y, float u, float v,
    float *red, float *green, float *blue)

Convert YUV color values to RGB color space.

See also: al_color_yuv, al_color_rgb_to_yuv

Examples:

ex_color.cpp

al_get_allegro_color_version

uint32_t al_get_allegro_color_version(void)

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

al_is_color_valid

Checks if all components of the color are between 0 and 1. Some of the color conversions in this addon support color spaces with more colors than can be represented in sRGB and when converted to RGB will result in invalid color components outside the 0..1 range.

Since: 5.2.3

al_color_rgb_to_oklab

void al_color_rgb_to_oklab(float red, float green, float blue,
   float *ol, float *oa, float *ob)

Convert RGB values to the Oklab color space.

Since: 5.2.8

See also: al_color_oklab, al_color_oklab_to_rgb

Examples:

ex_color_gradient.c

al_color_oklab

ALLEGRO_COLOR al_color_oklab(float l, float a, float b)

Return an ALLEGRO_COLOR structure from Oklab values. The L component corresponds to luminance from 0..1. The a and b components are in the range -1..+1.

Note:

The Oklab color space can represent more colors than are visible in sRGB and therefore conversion may result in RGB values outside of the 0..1 range. You can check for that case with al_is_color_valid.

Since: 5.2.8

See also: al_color_oklab_to_rgb, al_color_rgb_to_oklab

Examples:

ex_color_gradient.c

al_color_oklab_to_rgb

void al_color_oklab_to_rgb(float ol, float oa, float ob,
    float *red, float *green, float *blue)

Convert Oklab color values to RGB.

Since: 5.2.8

See also: al_color_oklab, al_color_rgb_to_oklab

al_color_rgb_to_linear

void al_color_rgb_to_linear(float red, float green, float blue,
   float *r, float *g, float *b)

Convert gamma corrected sRGB values (i.e. normal RGB) to linear sRGB space.

Since: 5.2.8

See also: al_color_linear, al_color_linear_to_rgb

Examples:

ex_color_gradient.c

al_color_linear

ALLEGRO_COLOR al_color_linear(float r, float g, float b)

Return an ALLEGRO_COLOR structure from linear sRGB values. Allegro RGB values are assumed to be sRGB. The sRGB standard is in wide use by various display devices. It accounts for a standard gamma correction applied to RGB colors before they get displayed.

Gamma correction means if for example we have a medium gray color specified with al_map_rgb_f(0.5,0.5,0.5) then we do not want the monitor to set the pixel to exactly half the physical maximum intensity, but instead to an intensity that appears to be half as bright as the maximum to the person looking at it. In this case that would be closer to 21% of maximum intensity rather than to 50% intensity.

For some applications it may be useful to specify a color in linear sRGB components, in which case you can use this function. For example:

ALLEGRO_COLOR gray = al_color_linear(0.216, 0.216, 0.216);
char html[8];
al_color_rgb_to_html(gray.r, gray.g, gray.b, html); // "#808080"

Since: 5.2.8

See also: al_color_linear_to_rgb, al_color_rgb_to_linear

Examples:

ex_color_gradient.c

al_color_linear_to_rgb

void al_color_linear_to_rgb(float r, float g, float b,
    float *red, float *green, float *blue)

Convert linear sRGB color values to gamma corrected (i.e. normal) RGB values.

Since: 5.2.8

See also: [al_color_linera], al_color_rgb_to_linear

Allegro version 5.2.10 (20231119) - Last updated: 2024-11-26 05:31:20 UTC