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.