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:
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.
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.
