AG_COLOR(3)

NAME
AG_Color - agar color structure

SYNOPSIS

    #include <agar/core.h>
    #include <agar/gui.h>

DESCRIPTION
The AG_Color structure describes a color in terms of Red, Green, Blue, and Alpha components. The AG_Color structure is declared as:

    typedef struct ag_color {
    #if AG_MODEL == AG_LARGE
    	Uint16 r,g,b,a;			/* LG (16-bit color) */
    #else
    	Uint8  r,g,b,a;			/* MD (8-bit color) */
    #endif
    } AG_Color;

The alpha component may or may not be used in a given context. A value of 0 (or AG_TRANSPARENT or AG_COLOR_FIRST) is fully transparent, while AG_OPAQUE (or AG_COLOR_LAST) is fully opaque.

INTERFACE
void AG_ColorRGB_8(AG_Color *c, Uint8 r, Uint8 g, Uint8 b)

void AG_ColorRGBA_8(AG_Color *c, Uint8 r, Uint8 g, Uint8 b, Uint8 a)

void AG_ColorRGB_16(AG_Color *c, Uint16 r, Uint16 g, Uint16 b)

void AG_ColorRGBA_16(AG_Color *c, Uint16 r, Uint16 g, Uint16 b, Uint16 a)

void AG_HSV2Color(float hue, float sat, float val, AG_Color *c)

void AG_Color2HSV(AG_Color *c, float *hue, float *sat, float *val)

void AG_ColorHex16(AG_Color *c, Uint16 hex)

void AG_ColorHex32(AG_Color *c, Uint32 hex)

void AG_ColorHex64(AG_Color *c, Uint64 hex)

void AG_ColorFromString(AG_Color *c, const char *spec, const AG_Color *parentColor)

void AG_ColorNone(AG_Color *c)

void AG_ColorBlack(AG_Color *c)

void AG_ColorWhite(AG_Color *c)

void AG_ColorLighten(AG_Color *c, int shade)

void AG_ColorDarken(AG_Color *c, int shade)

void AG_ColorInterpolate(AG_Color *cx, const AG_Color *c1, const AG_Color *c2)

int AG_ColorCompare(const AG_Color *a, const AG_Color *b)

AG_ColorRGB_8() and AG_ColorRGB_16() return an AG_Color from 8- or 16-bit red, green and blue components (with alpha set to fully opaque).

AG_ColorRGBA_8() and AG_ColorRGBA_16() return an AG_Color from 8- or 16-bit RGB and alpha components.

AG_HSV2Color() maps a color in HSV space to the closest approximation in RGB space, and copies the A component as-is. The inverse operation is performed by AG_Color2HSV(). Note: H and V become increasingly lossy as S->0.

The AG_ColorHex16(), AG_ColorHex32() and AG_ColorHex64() routines convert a color packed into 0xRGBA (4-bit components), 0xRRGGBBAA (8-bit components), or 0xRRRRGGGGBBBBAAAA (16-bit components) into an AG_Color.

AG_ColorFromString() converts a text-based color representation to an AG_Color. The following formats are allowed:

    "#RGB[A]"
    "#RRGGBB[AA]"
    "#RRRRGGGGBBBB[AAAA]"
    "r,g,b[,a]"
    "rgb(r,g,b[,a])"
    "rgb16(r,g,b[,a])"
    "hsv(h,s,v[,a])"
    "AliceBlue"

Color components may be separated by `/', ':' or ','.

A component terminating with a `%' character is interpreted as a ratio (in %) of the corresponding component of pColor (or White if pColor is NULL).

AG_ColorNone() initializes the color to fully transparent black (0,0,0,0). AG_ColorBlack() and AG_ColorWhite() initialize the respective fully opaque color.

AG_ColorLighten() and AG_ColorDarken increase and decrease the overall value of c by some small increment multiplied by shade. A shade argument of 0 leaves the color value unchanged.

AG_ColorInterpolate() traces an imaginary line in RGB color space between c1 and c2 and returns into cx the color closest to the point described by the fraction num over denom.

AG_ColorCompare() returns non-zero if the two colors differ.

SEE ALSO
AG_Intro(3), AG_MapColorRGB(3), AG_MapColorRGBA(3), AG_MapPixelRGB(3), AG_MapPixelRGBA(3), AG_Surface(3), AG_Widget(3)

HISTORY
Agar 1.0 through 1.3 described colors using packed pixels in a 32-bit reference format. The AG_Color structure first appeared in Agar 1.4.0. Agar 1.6.0 introduced the AG_LARGE memory model and 48-bit "Deep Color". AG_Color2HSV(), AG_HSV2Color(), AG_ColorNone(), AG_ColorDarken(), AG_ColorLighten() and the AG_ColorInterpolate() functions appeared in 1.6.0.