ctm_find_color()

CTM_$FIND_COLOR                   Domain/OS                    CTM_$FIND_COLOR


NAME
     ctm_$find_color - find a color in the color map

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/gpr.h>
     #include <apollo/ctm.h>

     void ctm_$find_color(
          gpr_$color_t &color,
          short &color_radius,
          void *pixel_value,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/gpr.ins.pas';
     %include '/sys/ins/ctm.ins.pas';

     procedure ctm_$find_color(
          in color: gpr_$color_t;
          in color_radius: integer;
          out pixel_value: univ gpr_$pixel_value_t;
          out status: status_$t);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/ctm.ins.ftn'

           integer*2 color_radius
           integer*4 status, pixel_value, color

           call ctm_$find_color(color, color_radius, pixel_value, status)

DESCRIPTION
     Ctm_$find_color 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.

     Ctm_$find_color 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.

     color
          The color desired by the calling process.

     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.

          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.

     pixel_value
          The pixel value of a color map entry that best satisfies the con-
          straints defined by color and color_radius.

     status
          The completion status.
Museum
