NAME

cxParamColorFloatGet - convert a string color parameter into floating point RGBA
#include <cx/DataAccess.h>

cxErrorCode cxParamColorFloatGet( cxParameter *src, float rgba[4] );
integer function cxParamColorFloatGet( src, rgba )
integer src
real rgba(4)
cxParamColorFloatGet converts src, a cxParameter in "color format" (described below), into a single precision red/green/blue/alpha representation stored in rgba. Color values are in the range [0..1]. An alpha (rgba[3]) value of 1.0 is completely opaque, a value of 0.0 is completely transparent.

A color format cxParameter must be of type string. Three basic formats are decoded in the following order:

(1) the X hexadecimal format, (2) an IRIS Explorer-specific format, (3) color names from the X database.

If the first character of the parameter string to be matched is '#', then the X hexadecimal format is assumed. This format specifies colors as hexadecimal strings, see Xlib Programming Manual, Volume 1. The format is #RGB, #RRGGBB, #RRRGGGBBB or #RRRRGGGGBBBB, giving 4, 8, 12 or 16 bits of color precision. Note that #3a7 and #3000a0007000 are equivalent. The number of hex characters following the '#' must be at least 3, no more than 12, and an even multiple of 3. For example, the strings #3f4 and #3f4.4 are legal, but #3f44 is not.

If the first three letters of the string are "RGB" or "HSV" (case is ignored), the IRIS Explorer format is assumed. This format specifies the color system and the values directly:


RGB red green blue [alpha] HSV hue saturation value [alpha]
Red, green, blue, hue, saturation, and value are all floating point values in the range [0..1]. The alpha value is optional, if not present it is set to 1.0. Any trailing input is ignored. The routines cxRGBtoHSV and cxHSVtoRGB can be used to convert between the color systems. cxRGBtoHSV(3E) gives a quick description of the Hue/Saturation/Value system.

If the above conversions fail, the input is assumed to be a color name. Color name matching is case insensitive. Leading and trailing white space is stripped off prior to matching, but embedded white space is not affected. The color name database is read from the output of showrgb(1). If showrgb fails or cannot be found, the file /usr/lib/X11/rgb.txt is read. If that file cannot be found, the eight primary and secondary colors are used. Note that this database may change over time, or be different on machines from different vendors. It is therefore intended only as a convenient starting point for selecting colors. If machine independence is required, use one of the first two explicit formats.

A value of cx_err_error is returned and rgba is unchanged if any conversion error occurs, otherwise cx_err_none is returned.

cxParamColorPackedGet(3E), cxParamColorFloatSet(3E), cxParamColorPackedSet(3E), cxRGBtoHSV(3E).
Last modified: Mon Nov 6 16:33:33 GMT 2000
[ Documentation Home ]
© The Numerical Algorithms Group Ltd, Oxford UK. 1999