GPR_$SET_COLOR_MAP                GPR Calls                 GPR_$SET_COLOR_MAP


NAME
     gpr_$set_color_map - establishes new values for the color map.

FORMAT
     gpr_$set_color_map (start_index, n_entries, values, status)

DESCRIPTION
     This routine establishes new values for the color map.  Use the
     gpr_$set_color_map routine to change one, some, or all of the available
     slots in the color chart.

   Input Parameters
     start_index
          Index of first color value entry, in gpr_$pixel_value_t format.
          This is a 4-byte integer.

     n_entries
          Number of entries.  This is a 2-byte integer.  Valid values are

             ⊕  2 For monochromatic displays.

             ⊕  1 - 16 For color displays in 4-plane format.

             ⊕  1 - 256 For color displays in 8-plane format.

     values
          The color table, stored as an array of 4-byte integers.  The
          gpr_$color_vector_t type is an example of such an array, though your
          array need not be this large.

   Output Parameters
     status
          Completion status, in status_$t format.

SEE ALSO
     gpr_$inq_color_map, Programming with Domain Graphics Primitives.

NOTES
     In general, you do not have to call gpr_$set_color_map when running in an
     RGB mode because the system automatically loads a linear ramp color map
     for you.  If you specify the Display Manager command CDM -p 1 and ini-
     tialize the display mode with gpr_$direct, then calling
     gpr_$set_color_map will have no effect.  In gpr_$borrow_rgb mode, you can
     call gpr_$set_color_map to alter the linear ramp color map (perhaps to
     perform a gamma correction).

     On monochromatic displays, the color map is either simulated or in
     hardware.  If the color map is simulated, then the pixel value 1 always
     corresponds to white and the pixel value 0 always corresponds to black.
     Calling gpr_$set_color_map on such a machine will not change these
     correspondences.  However, if the color map is in hardware, then the sys-
     tem does use the pixel value as an index into the color map.  In this
     instance, you can use gpr_$set_color_map to change 1 to black and 0 to
     white or vice-versa.  By default, the start_index is 0, n_entries is 2,
     and the values are gpr_$black in the first array element and gpr_$white
     in the second array element.  Dark has the value gpr_$black, and bright
     has the value gpr_$white.  If the program provides fewer than two values,
     or if the first two values are the same (both black or both white), the
     routine returns an error.  To determine whether the color map is simu-
     lated or in hardware, call the gpr_$inq_disp_characteristics routine.
     This routine will return the answer into the invert field of the "disp"
     record/structure in Pascal or C (or element 29 of the "disp" array in
     FORTRAN).

     In gpr_$direct mode, you must acquire the display before calling
     gpr_$set_color_map.