GPR_$CLEAR                        GPR Calls                         GPR_$CLEAR


NAME
     gpr_$clear - sets all pixels in the current bitmap to the given color.

FORMAT
     gpr_$clear (color, status)

DESCRIPTION
     This routine sets all pixels in the current bitmap to the given color.

     The gpr_$clear routine sets every pixel in the current bitmap to the
     specified color.  Don't be fooled by the name; gpr_$clear does not neces-
     sarily "clear" the bits to black.  It actually sets all the bits to a
     particular color.  You could, for example, use gpr_$clear to set all the
     bits in the current bitmap to purple.

     If you specify the special number -2 for color, the system sets every bit
     in the current bitmap to the bitmap's background color.  If the current
     bitmap is a main memory bitmap, hidden display memory bitmap, or external
     file bitmap, the background color is zero.  If the current bitmap is a
     display memory bitmap in borrow mode, then the background color is zero
     (which is usually, but not always, black).  If the current bitmap is a
     display memory bitmap in frame or direct mode, the background color is
     the same as that used for the window background color.

   Input Parameters
     color
          The color that all pixels in the current bitmap should be set to, in
          gpr_$pixel_value_t format.  This is a 4-byte integer.  Valid values
          are:


             ⊕  0 - 1 For monochromatic displays

             ⊕  0 - 15 For color displays in 4-bit pixel format

             ⊕  0 - 255 For color displays in 8-bit pixel format

             ⊕  0 - 4096 For color displays in 12-bit pixel format

             ⊕  0 - 16,777,215 For color displays in 24-bit pixel format

             ⊕  -2 For all displays.

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

SEE ALSO
     gpr_$set_color_map, gpr_$set_color_map.

NOTES
     You can use gpr_$set_color_map to establish  the  correspondence  between
     color  map  indexes  and  color  values.   This  means  that  you can use
     gpr_$set_color_map to assign the pixel value 0 to bright  intensity,  and
     then use gpr_$clear either to make the screen bright by passing the pixel
     value 0, or make the screen dark by passing the value 1.

     This routine is subject to the restrictions of the current clipping  win-
     dow  sets all pixels in the current bitmap to the given color.  and plane
     mask.