CTM_FIND_COLOR CTM Calls CTM_FIND_COLOR
NAME
ctm_$find_color - finds a color in the color map.
FORMAT
ctm_$find_color (color, color_radius, pixel_value, status)
DESCRIPTION
The ctm_$find_color routine searches in the color map for a color value
within the range defined by color and color_radius. If a color value
within the specified range is already in the color map, ctm_$find_color
increments its use count and supplies its pixel value in pixel_value. If
there are no existing colors within the specified range, ctm_$find_color
allocates a pixel value to the calling process for the color specified in
color, and supplies it in pixel_value.
The color and color_radius arguments effectively define a sphere in the
RGB (red, green, blue) color space, and any existing color values in the
color map that fall within the sphere are candidates for having their
corresponding pixel values supplied to the calling process by
ctm_$find_color.
The ctm_$find_color routine determines whether an existing color value is
within the specified range by summing the squares of the differences
between the red, green, and blue intensities specified in color and the
respective intensities in the existing color value. The existing color
value is within the desired color range if the resulting sum is less than
the square of color_radius. If more than one color value satisfies the
color and color_radius constraints, ctm_$find_color will supply the pixel
value of the existing color that minimizes the sum.
Input Parameters
color
The color desired by the calling process, in gpr_$color_t format.
This parameter is a 4-byte integer.
color_radius
A distance in the color space that together with color defines a
range of acceptable colors. If only an exact match for color will
do, set color_radius to 0. This parameter is a 2-byte integer.
Choosing a large value for color_radius will force the CTM to choose
only from colors already in the color map and prevent it from allo-
cating a pixel value to the calling process. To force a choice from
existing color values choose some very large and positive 2-byte
integer; ((short)0x3fff) will do the job in C, in Pascal
lastof(integer) serves handily.
Output Parameters
pixel_value
The pixel value of a color map entry that best satisfies the con-
straints defined by color and color_radius, in gpr_$pixel_value_t
format. This is a 4-byte integer.
status
The completion status, in status_$t format.