


RASTERLIB(3)                                         RASTERLIB(3)


NAME
       RASTER ORIENTED GRAPHICS LIBRARY

SYNOPSIS
       c [flags] files $(RASTERLIB) [ libraries]


AUTHORS
       James  Westervelt  -  Army  Corps Construction Engineering
       Research Laboratory
       Michael Shapiro  -  Army  Corps  Construction  Engineering
       Research Laboratory

DESCRIPTION
       GRASS  application  programs having graphic output connect
       themselves at run time to a user  chosen  graphics  driver
       which controls a graphics device:

       PROGRAM <--> DRIVER <--> DEVICE

       The  PROGRAM  to  DRIVER  interface  is  done through this
       RASTERLIB library of  commands.    Making  GRASS  
       programs
       generate  graphics  on  a new graphics device requires the
       development of a new DRIVER. This driver is then avail­
       able  to  all  existing GRASS programs without the need to
       recompile or reload the individual  graphics  applications
       programs.

       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.

       Two other reasons for the existence of this GRASS graphics
       standard  should also be mentioned.  1) Because the graph­
       ics 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 capa­
       bility while interfacing itself to commercially  available
       vector graphics.

       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  zoom­
       ing may be painfully slow to you.


USE
       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 graph­
       ics device.   To do so, this library can provide the  pro­
       gram  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.)

       To assist the  application  programs  in  identifying  the
       actual  device  pixle  that  needs  addressing, coordinate
       transformation calls in the GRASS  displaylib  are  avail­
       able.

       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  pad
       calls  are  used  primarily  by  the displaylib library to
       maintain information about the display device windows.

SEE ALSO
       displaylib(3)

GRAPHICS FUNCTIONS
      R_close_driver()
              This should be the last call in an application pro­
              gram.   It shuts down the connection (Usually sock­
              ets on Berkley 4.? machines or fifos on Bell Sys 5)
              to the graphics driver.

       R_color(index)
              int index ;
              Subsequent lines, text will be in color index.

       R_color_offset(n)
              int n ;
              Applicable     only     after     a     call     to
              R_color_table_float.  Increments all color sets and
              requests  by  offset  nn.  Ignored after requests to
              R_color_table_fixed.

       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.

       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.


       R_cont_abs(x,y)
              int x, y ;
              Draw  a line from the current screen location to an
              absolute screen position.

       R_cont_rel(x,y)
              int x, y ;
              Draw a line from the current screen location  to  a
              relative screen position.

       R_erase()
              Erase the entire screen.

       R_flush()
              Flush   pending  graphics  calls  to  the  graphics
              device.  Generally used for interactive graphics.

       R_get_location_with_box(cx, cy, wx, wy, button)
              int cx, cy ;
              int *wx, *wy ;
              int *button ;
              Get a location  off  the  screen  using  a  pointer
              device  (generally  a  mouse).  The cursor is a box
              with one corner fixed at ccxx,,ccyy.  The other  follows
              the  pointer.   Upon depression of a key (generally
              one of three buttons on a mouse) the current  loca­
              tion  of  the  pointer is returned in wwxx and wwyy.  A
              value from the set {1, 2,  3}  (representing  left,
              middle,  and  right  on  a  three  button mouse) is
              returned in bbuuttttoonn.

       R_get_location_with_line(cx, cy, wx, wy, button)
              int cx, cy ;
              int *wx, *wy ;
              int *button ;
              Same as R_get_location_with_box, except a line con­
              nects the two points instead of a box.

       R_get_location_with_pointer(wx, wy, button)
              int *wx, *wy ;
              int *button ;
              Same  as G_get_location_with_box except there is no
              fixed point.  Instead a cursor traces the  pointers
              position on the screen.

       R_move_abs(x,y)
              int x, y ;
              Move,  without  draw,  to  absolute screen location
              xx,,yy.

       R_move_rel(x,y)
              int x, y ;
              Move, without draw,  to  relative  screen  location
              xx,,yy.

       R_open_driver()
              This  call  must  pprreecceeeedd  all  other calls to this
              library.

       R_polydots_abs(xarray, yarray, number)
              int xarray[], yarray[], number ;
              Draws number single pixle dots on the screen at the
              absolute locations specified at xarray  and yarray.

       R_polydots_rel(xarray, yarray, number)
              int xarray[], yarray[], number ;
              Draws number single pixle dots on the screen at the
              relative locations specified at xarray  and yarray.
              Each x,y pair updates the current position.

       R_polygon_abs(xarray, yarray, number)
              int xarray[], yarray[], number ;
              Draws a filled polygon using the number of absolute
              screen locations specified by the xarray and yarray
              arrays.

       R_polygon_rel(xarray, yarray, number)
              int xarray[], yarray[], number ;
              Draws a filled polygon using the number of relative
              screen locations specified by the xarray and yarray
              arrays.

       R_polyline_abs(xarray, yarray, number)
              int xarray[], yarray[], number ;
              Draws a single line using the  number  of  absolute
              screen locations specified by the xarray and yarray
              arrays.

       R_polyline_rel(xarray, yarray, number)
              int xarray[], yarray[], number ;
              Draws a single line using the  number  of  relative
              screen locations specified by the xarray and yarray
              arrays.

       R_raster(num, nrows, ras)
              int num, nrows ;
              char * ras[] ;
              Draws a nnrroowwss of nnuumm  pixles  using  colors  repre­
              sented by the values in rraass.  Drawing begins at the
              current location.

       R_reraster()
              Draws one more row using the last raster passed  by
              R_raster (usually at an updated starting position).

       R_reset_color(red, grn, blu, number)
              float red, grn, blu ;
              int number ;
              If R_color_table_fixed() was  last  called,  resets



                            rasterlib                           4





RASTERLIB(3)                                         RASTERLIB(3)


              the  software  color lookup table  for color number
              number to display  the  color  represented  by  the
              intensities  in rreedd, ggrreeeenn, and bblluuee.  These inten­
              sities  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 number is updated in hardware. In this
              situation, all locations on the screen  using  this
              color number already will be instantly changed.

       R_reset_colors(red, grn, blu, tot_colr)
              float red[], grn[], blu[] ;
              int tot_colr ;
              Same as RR__ccoolloorr__ttaabbllee__ffiixxeedd except that red, green,               and blue, are arrays hhoollddiinngg ttoott__ccoollrr colors.  Col­
              ors 0 through ttoott__ccoollrr - 1 are updated.

       R_screen_bot()
              Returns  the  row number of the bottom row.  Always
              larger than the top row.

       R_screen_left()
              Returns the  column  number  of  the  left  column.
              Always smaller than the right column.

       R_screen_rite()
              Returns  the  column  number  of  the right column.
              Always larger than the left column.

       R_screen_top()
              Returns the row number  of  the  top  row.   Always
              smaller than the bottom row.

       R_set_window(t, b, l, r)
              int t, b, l, r ;
              Sets  the  ttop,  bbottom, lleft, and rright edges of a
              window  on  the  graphics  device.   Text  will  be
              clipped at these limits.

       R_text(sometext)
              char *sometext ;
              The  text  in  ssoommeetteexxtt is printed beginning at the
              current location.  THe current  color,  text  size,
              and text rotation are used.

       R_text_rotation(rotation)
              float rotation ;
              Subesquent calls to RR__tteexxtt will print text at angle
              rroottaattiioonn.  This angle is in degrees  counter-clock­
              wise from the positive x axis.

       R_text_size(width, height)
              float width, height ;
              Subsequent  calls to RR__tteexxtt will print text at size
              hheeiigghhtt and wwiiddtthh.

PAD FUNCTIONS
       The monitor has a very simple database management capabil­
       ity  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 NOT to be
       used by the programmer.  They are used indirectly  through
       the displaylib library calls.
