.\" @(#)MAN	2.1 10/12/87
.TH RASTERLIB 3 rasterlib
.SH NAME
RASTER ORIENTED GRAPHICS LIBRARY
.SH SYNOPSIS
.B
cc [flags] files $(RASTERLIB) [ libraries ]

.SH AUTHORS
James Westervelt - Army Corps Construction Engineering Research Laboratory
.br
Michael Shapiro - Army Corps Construction Engineering Research Laboratory
.SH DESCRIPTION
.PP
GRASS application programs having graphic output connect themselves at run time
to a user chosen graphics driver which controls a graphics device:
.sp
PROGRAM <--> DRIVER <--> DEVICE
.sp
The PROGRAM to DRIVER interface is done through this \fBRASTERLIB\fR library of
commands.   Making GRASS programs generate graphics on a new graphics device
requires the development of a new \fBDRIVER\fR.  This driver is then available
to all existing GRASS programs without the need to recompile or reload the
individual graphics applications programs.
.PP
The GRASS application programmer is completely separated from the problems of
graphic devices; needing only to learn and use the graphics calls listed in
this manual entry.
.PP
Two other reasons for the existence of this GRASS graphics standard should also
be mentioned.  1) Because the graphics code comes as part of the package,
there is usually no need for a site to purchase special graphics libraries. 2)
All graphics standards in industry are aimed at CAD-CAM vector applications.
GRASS, being raster based in its primary data format, requires the ability to
work directly with a device's pixles.  This library provides that capability
while interfacing itself to commercially available vector graphics.
.PP
This raster capability in an easily ported format comes with some known, but
chosen, drawbacks.   Fancy graphics capabilities supported by one device or a
particular graphics library are not always available.  These include 3-D,
windowing, multi-buffer, panning/zooming, and display lists.  Such
capabilities must (and are) built into GRASS when necessary,  but if your
machine supports hardware panning and zooming, the GRASS software panning and
zooming may be painfully slow to you.
.SH USE
.PP
This graphics library is raster oriented.  To be efficient in the painting of
raster information on a raster device, the application programs must talk
directly to the graphics device.   To do so, this library can provide the
program with the left, right, top, and bottom edges of the screen.  To simplify
coding, the device's 0,0 location is always in the upper left.  (If necessary a
particular graphics driver can make the appropriate manipulations.)
.PP
To assist the application programs in identifying the actual device pixle that
needs addressing, coordinate transformation calls in the GRASS
\fBdisplaylib\fR are available.
.PP
This library contains two independent sets of routines.  The graphics calls
are responsible for the drawing of lines and text on a graphics device.  These
are used directly by the GRASS application programmer. The \fBpad\fR calls
are used primarily by the \fBdisplaylib\fR library to maintain information
about the display device windows.
.SH SEE ALSO
displaylib(3)
.SH GRAPHICS FUNCTIONS
.TP
R_close_driver()
This should be the last call in an application program.  It shuts down the
connection (Usually sockets on Berkley 4.? machines or fifos on Bell Sys 5) to
the graphics driver.
.TP
R_color(index)
int index ;
.br
Subsequent lines, text will be in color \fBindex\fR.
.TP
R_color_offset(n)
int n ;
.br
Applicable only after a call to R_color_table_float.  Increments all color sets
and requests by offset \fBn\fR.  Ignored after requests to
R_color_table_fixed.
.TP
R_color_table_fixed()
A fixed color table will be used.   Requests by R_reset_color and R_reset_color
will modify an internal index into the devices fixed color table.
.TP
R_color_table_float()
A floating, or adjustable color table will be used.  Requests by R_reset_color
will modify a graphics devices internal color lookup tables.  Colors already
displayed on a screen will be immediately affected.
.TP
R_cont_abs(x,y)
int x, y ;
.br
Draw a line from the current screen location to an absolute screen position.
.TP
R_cont_rel(x,y)
int x, y ;
.br
Draw a line from the current screen location to a relative screen position.
.TP
R_erase()
Erase the entire screen.
.TP
R_flush()
Flush pending graphics calls to the graphics device.  Generally used for
interactive graphics.
.TP
R_get_location_with_box(cx, cy, wx, wy, button)
int cx, cy ;
.br
int *wx, *wy ;
.br
int *button ;
.br
Get a location off the screen using a pointer device (generally a mouse).  The
cursor is a box with one corner fixed at \fBcx,cy\fR.
The other follows the pointer.
Upon depression of a key (generally one of three buttons on a mouse) the
current location of the pointer is returned in \fBwx\fR and \fBwy\fR.
A value from the set
{1, 2, 3} (representing left, middle, and right on a three button mouse) is
returned in \fBbutton\fR.
.TP
R_get_location_with_line(cx, cy, wx, wy, button)
int cx, cy ;
.br
int *wx, *wy ;
.br
int *button ;
.br
Same as R_get_location_with_box, except a line connects the two points instead
of a box.
.TP
R_get_location_with_pointer(wx, wy, button)
int *wx, *wy ;
.br
int *button ;
.br
Same as G_get_location_with_box except there is no fixed point.  Instead a
cursor traces the pointers position on the screen.
.TP
R_move_abs(x,y)
int x, y ;
.br
Move, without draw, to absolute screen location \fBx,y\fR.
.TP
R_move_rel(x,y)
int x, y ;
.br
Move, without draw, to relative screen location \fBx,y\fR.
.TP
R_open_driver() 
This call must \fBpreceed\fR all other calls to this library.
.TP
R_polydots_abs(xarray, yarray, number)
int xarray[], yarray[], number ;
.br
Draws \fBnumber\fR single pixle dots on the screen at the absolute
locations specified at \fBxarray\fR  and \fByarray\fR.
.TP
R_polydots_rel(xarray, yarray, number)
int xarray[], yarray[], number ;
.br
Draws \fBnumber\fR single pixle dots on the screen at the relative
locations specified at \fBxarray\fR  and \fByarray\fR.  Each x,y pair updates
the current position.
.TP
R_polygon_abs(xarray, yarray, number)
int xarray[], yarray[], number ;
.br
Draws a filled polygon using the \fBnumber\fR of absolute screen locations
specified by the \fBxarray\fR and \fByarray\fR arrays.
.TP
R_polygon_rel(xarray, yarray, number)
int xarray[], yarray[], number ;
.br
Draws a filled polygon using the \fBnumber\fR of relative screen locations
specified by the \fBxarray\fR and \fByarray\fR arrays.
.TP
R_polyline_abs(xarray, yarray, number)
int xarray[], yarray[], number ;
.br
Draws a single line using the \fBnumber\fR of absolute screen locations
specified by the \fBxarray\fR and \fByarray\fR arrays.
.TP
R_polyline_rel(xarray, yarray, number)
int xarray[], yarray[], number ;
.br
Draws a single line using the \fBnumber\fR of relative screen locations
specified by the \fBxarray\fR and \fByarray\fR arrays.
.TP
R_raster(num, nrows, ras)
int num, nrows ;
.br
char * ras[] ;
.br
Draws a \fBnrows\fR of \fBnum\fR pixles using colors represented
by the values in \fBras\fR.  Drawing begins at the current location.
.TP
R_reraster()
Draws one more row using the last raster passed by \fBR_raster\fR (usually at
an updated starting position).
.TP
R_reset_color(red, grn, blu, number)
float red, grn, blu ;
.br
int number ;
.br
If R_color_table_fixed() was last called, 
resets the software color lookup table  for color number \fBnumber\fR to
display the color represented by the intensities in \fBred\fR,
\fBgreen\fR, and \fBblue\fR.  These intensities are values between 0.0 and
1.0.  If R_color_table_float() was last called (and your device supports
hardware color lookup tables), color number \fBnumber\fR is updated in
hardware. In this situation, all locations on the screen using this color
number already will be instantly changed.
.TP
R_reset_colors(red, grn, blu, tot_colr)
float red[], grn[], blu[] ;
.br
int tot_colr ;
.br
Same as \fBR_color_table_fixed\fR except that \fBred\fB, \fBgreen\fB,
and \fBblue\fB, are arrays holding \fBtot_colr\fR colors.  Colors 0 through
\fBtot_colr\fR - 1 are updated.
.TP
R_screen_bot()
Returns the row number of the bottom row.  Always larger than the top row.
.TP
R_screen_left()
Returns the column number of the left column.  Always smaller than the right
column.
.TP
R_screen_rite()
Returns the column number of the right column.  Always larger than the left
column.
.TP
R_screen_top()
Returns the row number of the top row.  Always smaller than the bottom row.
.TP
R_set_window(t, b, l, r)
int t, b, l, r ;
.br
Sets the \fBt\fRop, \fBb\fRottom, \fBl\fReft, and \fBr\fRight
edges of a window on the graphics device.
Text will be clipped at these limits.
.TP
R_text(sometext)
char *sometext ;
.br
The text in \fBsometext\fR is printed beginning at the current location.  THe
current color, text size, and text rotation are used.
.TP
R_text_rotation(rotation)
float rotation ;
.br
Subesquent calls to \fBR_text\fR will print text at angle \fBrotation\fR.  This
angle is in degrees counter-clockwise from the positive x axis.
.TP
R_text_size(width, height)
float width, height ;
.br
Subesquent calls to \fBR_text\fR will print text at size \fBheight\fR and
\fBwidth\fR.
.SH PAD FUNCTIONS
.PP
The monitor has a very simple database management capability which
supports the windowing.
There are scratch pads to be written on. Each scratch pad can contain
items, and each item can have a list of values.  These are \fBNOT\fR to be used
by the programmer.  They are used indirectly through the \fBdisplaylib(3)\fR
library calls.
