COUPLEIDTOCOLOR(5ICD)

NAME
CoupleIdToColor - couple a user specified Id to a color from the CACD colormap

SYNOPSIS

CoupleIdToColor (Id, color)
int Id;
char *color;
CoupleIdsToColors (Ids, colors, n)
int Ids[];
char *colors[];
int n;

PARAMETERS

Id(s)
    a user specified Id of something he wishes to couple a color to.

color(s)
    a character string which specifies the color.

n   specifies the number of Ids and colors to couple.

DESCRIPTION
These functions create a mapping table from user supplied Id's to colors. A color specification is an ascii string (ISO Latin-1 encoding, upper and lower case does not matter) such as 'red'. Using a color database (normally /usr/lib/rgb) the color name is translated to an RGB specification which in turn is used to find the best matching color in the CACD colormap. The obtained pixel value is coupled to the specified Id in an internal table. When the same Id is specified several times the last color is stored. Colors can also be specified as a string of the following form:

#RGB
    (4 bits each)

#RRGGBB
    (8 bits each)

#RRRGGGBBB
    (12 bits each)

#RRRRGGGGBBBB
    (16 bits each)
where R, G and B represent single hexadecimal digits (upper or lower case). When fewer than 16 bits are specified, they represent the most significant bits of the value. For example, #3aF is the same as #3000a000f000.

DIAGNOSTICS
If the call to CoupleIdToColor() is successful 1 is returned. If CoupleIdToColor() fails 0 will be returned and cacdcmaperrno will be set to one of the following values:

NOINIT
    the CACD colormap library was not initialized.

NOCORE
    not enough core can be allocated.

BADID
    a specified Id was smaller than zero.

BADCOLOR
    a specified color cannot successfully be converted to an RGB value.

SEE ALSO
InitCacdCmap(5ICD) CoupleIdToRGB(5ICD) DecoupleId(5ICD) GetAffectedIds(5ICD)

NOTE
For optimal memory usage in the internal table, a set of Id's should be a consecutive set of integers starting at zero.