PROGRAMMING IN THE AUTON PROJECT AND SCHENLEY PARK RESEARCH
                                       
                                   CONTENTS
                                       
     [1]INTRODUCTION
     [2]PICTURES
     ----- [3]DRAWING FUNCTIONS:
     ----- [4]COLOR FUNCTIONS:
     ----- [5]NOW BACK TO APICTS
     [6]THE SIMPLEST FORM OF DRAWING DIRECTLY
     ----- [7]Saving graphics to Postscript
     ----- [8]Rescaling the drawing region.
     [9]2-d line and dot plotting (lingraphs)
     [10]3-d surface and dot plotting (surgraphs)
     
                                 INTRODUCTION
                                       
                                   PICTURES
                                       
      #include "apict.h"

   The only abstract data type involved is called an apict. It represents
   a picture. Elements of these pictures may be circles, lines, strings,
   rectangles, and discs (solid circles).
   
   To begin drawing a picture, call void apict_on(). Then you may use any
   of the following functions to draw into a global picture defined on a
   square area of width and height 512.0 units, in which coordinates are
   represented by (x,y) pairs. The origin (0,0) is the bottom left hand
   corner. x (a double) is the horizontal distance. y (also a double) is
   the vertical distance.
   
DRAWING FUNCTIONS:

      void ag_dot(double x, double y)
      void ag_line(double u, double v, double x, double y)
      void ag_circle(double x, double y, double r)
      void ag_box(double x_botleft, double y_botleft, double x_tr, double y_tr)
      double x_topright, double y_topright)
      void ag_disc(double x, double y, double r)
      void ag_print(double x, double y, char *s)

COLOR FUNCTIONS:

   There are 16 colors which may be used (though that number may later be
   reduced to 8). The colors are represented by amut_colors, which are
   #defined integer constants from amxw.h. They have imaginative names
   like AG_RED.
   
      void ag_set_pen_color(int amut_col)
      int ag_pen_color()
      int ag_spectrum_color(double fract)

   fract should be in the range [0, 1.0]; this will return the amut color
   at the specified fraction of the way along an approximate rainbow
   spectrum (0.0 = red end; 1.0 = violet).
   
NOW BACK TO APICTS

   To create an apict call
      apict_on()

   then do as much drawing as you like, then call
      apict *apict_off()

   which AM_MALLOCs an apict, representing the picture you just drew.
   This also clears the global picture.
   
   To display the picture on Unix under X-windows, call render_apict().
   On Windows NT under Visual C++, the top level user interface has its
   own methods of rendering apicts, and all you have to do is return
   those apicts to the top level user interface.
   
   Here are other functions on apicts:
   
      void free_apict(apict *g)
      apict *mk_copy_apict(apict *ap)

   There also exist apict_sets for people who wish to produce sequences
   of pictures. Andrew will document this (Andrew!)
   
                     THE SIMPLEST FORM OF DRAWING DIRECTLY
                                       
   Instead of creating an apict and then rendering it, you can simply
   call
   
      ag_on("")

   This (Under X) will pop up a square white window in the top left of
   the screen. Then commands like ag_line() ag_dot etc will draw within
   the window.
   
   When you have finished drawing, we recommend you call ag_off(). The
   window won't disappear, but it is important if you want to save stuff
   to Postscript. You may call ag_on("") at any time. If you have
   previously called it, then all that will happen is that the square
   window will be blanked out.
   
Saving graphics to Postscript

   Instead of calling ag_on(""), call ag_on("test.ps") (or a filename of
   your choice). Then when you next call ag_off() you'll find a file
   called test.ps has been created with the picture (and appropriate
   bounding boxes etc) defined. These pictures can be inserted directly
   into latex reports with \psfig.
   
Rescaling the drawing region.

   By default, when you call ag_on(""), the bottom left hand of the image
   will correspond to coordinates (0,0) and the top right will be
   coordinates (512,512). If instead you wish the bottom left to be
   (xlo,ylo) and the top right to be (xhi,yhi) just call
   
      void set_ag_frame(double xlo,double ylo,double xhi,double yhi);

                     2-d line and dot plotting (lingraphs)
                                       
   See lingraph.h in the draw library
   
                   3-d surface and dot plotting (surgraphs)
                                       
   See drac.h in the draw library. Seach for "surgraph" and you can
   ignore all the low-level contour plotting stuff.

References

   1. file://localhost/afs/cs.cmu.edu/project/learn/group/doc/draw.html#0
   2. file://localhost/afs/cs.cmu.edu/project/learn/group/doc/draw.html#1
   3. file://localhost/afs/cs.cmu.edu/project/learn/group/doc/draw.html#2
   4. file://localhost/afs/cs.cmu.edu/project/learn/group/doc/draw.html#3
   5. file://localhost/afs/cs.cmu.edu/project/learn/group/doc/draw.html#4
   6. file://localhost/afs/cs.cmu.edu/project/learn/group/doc/draw.html#5
   7. file://localhost/afs/cs.cmu.edu/project/learn/group/doc/draw.html#6
   8. file://localhost/afs/cs.cmu.edu/project/learn/group/doc/draw.html#7
   9. file://localhost/afs/cs.cmu.edu/project/learn/group/doc/draw.html#8
  10. file://localhost/afs/cs.cmu.edu/project/learn/group/doc/draw.html#9